<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media_ui\Service;

use Drupal\media\MediaInterface;

/**
 * Builds render arrays for the media status detail page.
 *
 * @internal
 */
interface MediaStatusPageBuilderInterface {

  /**
   * Builds the video preview section with thumbnail and dialog player.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name override.
   *
   * @phpstan-return array<string, mixed>|null
   *   Render array for the video preview, or NULL if unavailable.
   */
  #[\NoDiscard]
  public function buildVideoPreview(MediaInterface $media, string $fieldName = ''): ?array;

  /**
   * Builds the conversion progress section.
   *
   * @param array<string, mixed> $status
   *   Status array from MediaOperationsService::getStatus().
   *
   * @phpstan-return array<string, mixed>
   *   Render array for the progress section.
   */
  #[\NoDiscard]
  public function buildProgressSection(array $status): array;

  /**
   * Builds the error details section for failed conversions.
   *
   * @param array<string, mixed> $status
   *   Status array with 'error' key.
   *
   * @phpstan-return array<string, mixed>|null
   *   Render array for error details, or NULL if not failed.
   */
  #[\NoDiscard]
  public function buildErrorDetails(array $status): ?array;

  /**
   * Builds the outputs listing section.
   *
   * @param array<string, array<string, mixed>> $outputs
   *   Output data keyed by output type.
   *
   * @phpstan-return array<string, mixed>|null
   *   Render array, or NULL if no outputs.
   */
  #[\NoDiscard]
  public function buildOutputsSection(array $outputs): ?array;

  /**
   * Builds the transcript info section.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name override.
   *
   * @phpstan-return array<string, mixed>|null
   *   Render array or NULL if no transcript available.
   */
  #[\NoDiscard]
  public function buildTranscriptSection(MediaInterface $media, string $fieldName = ''): ?array;

  /**
   * Builds the video information card for the sidebar.
   *
   * @param array<string, mixed> $videoInfo
   *   Video information from MediaOperationsService::getVideoInfo().
   *
   * @phpstan-return array<string, mixed>
   *   Render array for the video info card.
   */
  #[\NoDiscard]
  public function buildVideoInfoCard(array $videoInfo): array;

  /**
   * Builds the action buttons for the sidebar.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param array<string, mixed> $status
   *   Current status array.
   * @param string $fieldName
   *   Optional source field name override.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for action buttons.
   */
  #[\NoDiscard]
  public function buildActionButtons(MediaInterface $media, array $status, string $fieldName = ''): array;

  /**
   * Gets the source file URL for a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name override.
   *
   * @return string|null
   *   Public URL or NULL if not available.
   */
  #[\NoDiscard]
  public function getSourceFileUrl(MediaInterface $media, string $fieldName = ''): ?string;

  /**
   * Gets the poster/thumbnail URL for a media entity.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   Optional source field name override.
   *
   * @return string|null
   *   The poster URL, or NULL if unavailable.
   */
  #[\NoDiscard]
  public function getPosterUrl(MediaInterface $media, string $fieldName = ''): ?string;

}
