<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Hook;

use Drupal\Core\Hook\Attribute\Hook;
use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\StringTranslation\StringTranslationTrait;
use Drupal\Core\Url;

/**
 * Help hook implementations for FFmpeg Media.
 */
final class HelpHooks {

  use StringTranslationTrait;

  /**
   * Implements hook_help().
   *
   * @phpstan-return array<string, mixed>|string
   */
  #[Hook('help')]
  public function help(string $routeName, RouteMatchInterface $routeMatch): array|string {
    if ($routeName !== 'help.page.ffmpeg_media') {
      return '';
    }

    $build = [];

    $build['overview'] = $this->buildOverview();
    $build['submodules'] = $this->buildSubmodules();
    $build['permissions'] = $this->buildPermissions();
    $build['settings'] = $this->buildSettingsLink();
    $build['quickstart'] = $this->buildQuickStart();

    return $build;
  }

  /**
   * Builds the module overview section.
   *
   * @phpstan-return array<string, mixed>
   */
  protected function buildOverview(): array {
    return [
      '#type' => 'container',
      'heading' => [
        '#type' => 'html_tag',
        '#tag' => 'h3',
        '#value' => $this->t('About'),
      ],
      'description' => [
        '#type' => 'html_tag',
        '#tag' => 'p',
        '#value' => $this->t('FFmpeg Media is a professional video processing suite for Drupal. It provides queue-based video conversion powered by FFmpeg, with support for hardware acceleration (NVENC, VAAPI, QSV, Vulkan), multiple output formats, and a plugin-based architecture for codecs, outputs, and processors.'),
      ],
    ];
  }

  /**
   * Builds the submodules section.
   *
   * @phpstan-return array<string, mixed>
   */
  protected function buildSubmodules(): array {
    $items = [
      $this->t('<strong>FFmpeg Media Streaming</strong> &mdash; HLS and DASH adaptive streaming output support.'),
      $this->t('<strong>FFmpeg Media Whisper</strong> &mdash; AI-powered subtitle generation using Whisper via FFmpeg 8.'),
      $this->t('<strong>FFmpeg Media Advanced</strong> &mdash; HDR, watermarking, subtitles, audio normalization, and two-pass encoding.'),
      $this->t('<strong>FFmpeg Media UI</strong> &mdash; Dashboard, poster selection, and progress tracking interface.'),
      $this->t('<strong>FFmpeg Media Player</strong> &mdash; Video playback with Vidstack player for HLS, DASH, and progressive formats.'),
      $this->t('<strong>FFmpeg Media Image</strong> &mdash; Thumbnails, animated GIFs, and segment preview generation.'),
    ];

    return [
      '#type' => 'container',
      'heading' => [
        '#type' => 'html_tag',
        '#tag' => 'h3',
        '#value' => $this->t('Submodules'),
      ],
      'list' => [
        '#theme' => 'item_list',
        '#items' => $items,
      ],
    ];
  }

  /**
   * Builds the permissions section.
   *
   * @phpstan-return array<string, mixed>
   */
  protected function buildPermissions(): array {
    $items = [
      $this->t('<strong>Administer FFmpeg Media</strong> &mdash; Configure module settings and manage all conversions.'),
      $this->t('<strong>Convert media files</strong> &mdash; Queue media files for video conversion.'),
      $this->t('<strong>Reconvert media files</strong> &mdash; Re-process already converted media files.'),
      $this->t('<strong>View conversion progress</strong> &mdash; View the progress of ongoing video conversions.'),
      $this->t('<strong>View FFmpeg Media metrics</strong> &mdash; Access Prometheus metrics endpoint for monitoring.'),
    ];

    return [
      '#type' => 'container',
      'heading' => [
        '#type' => 'html_tag',
        '#tag' => 'h3',
        '#value' => $this->t('Permissions'),
      ],
      'description' => [
        '#type' => 'html_tag',
        '#tag' => 'p',
        '#value' => $this->t('The following permissions control access to FFmpeg Media features:'),
      ],
      'list' => [
        '#theme' => 'item_list',
        '#items' => $items,
      ],
    ];
  }

  /**
   * Builds the settings link section.
   *
   * @phpstan-return array<string, mixed>
   */
  protected function buildSettingsLink(): array {
    return [
      '#type' => 'container',
      'heading' => [
        '#type' => 'html_tag',
        '#tag' => 'h3',
        '#value' => $this->t('Configuration'),
      ],
      'link' => [
        '#type' => 'html_tag',
        '#tag' => 'p',
        '#value' => $this->t('Configure FFmpeg Media at the <a href=":url">settings page</a>.', [
          ':url' => Url::fromRoute('ffmpeg_media.settings')->toString(),
        ]),
      ],
    ];
  }

  /**
   * Builds the quick-start guide section.
   *
   * @phpstan-return array<string, mixed>
   */
  protected function buildQuickStart(): array {
    $steps = [
      $this->t('Enable the FFmpeg Media module and any desired submodules.'),
      $this->t('Navigate to <a href=":url">Configuration &gt; Media &gt; FFmpeg Media</a> and configure the paths to your FFmpeg and ffprobe binaries.', [
        ':url' => Url::fromRoute('ffmpeg_media.settings')->toString(),
      ]),
      $this->t('Configure a video field formatter under <em>Manage Display</em> for your media type. Enable <em>Auto convert</em> and select a conversion profile in the formatter settings.'),
      $this->t('Create a conversion profile specifying the desired output format, codec, and quality settings.'),
      $this->t('Upload a video to your media type. It will be automatically queued for conversion if auto-convert is enabled in the formatter.'),
      $this->t('Process the queues by running <code>drush queue:run ffmpeg_media_conversion</code> and <code>drush queue:run ffmpeg_media_conversion_large</code>, or by configuring cron (which processes both automatically).'),
    ];

    return [
      '#type' => 'container',
      'heading' => [
        '#type' => 'html_tag',
        '#tag' => 'h3',
        '#value' => $this->t('Quick start'),
      ],
      'steps' => [
        '#theme' => 'item_list',
        '#items' => $steps,
        '#list_type' => 'ol',
      ],
    ];
  }

}
