<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media_ui\Service;

/**
 * Interface for building dashboard render arrays from data.
 *
 * @internal
 */
interface DashboardBuilderServiceInterface {

  /**
   * Builds the full stats cards render array.
   *
   * @phpstan-param array<string, mixed> $conversionStats
   *   Conversion stats from DashboardStatsService::getConversionStats().
   *
   * @phpstan-return array<string, mixed>
   *   Render array containing stats card grid.
   */
  #[\NoDiscard]
  public function buildStatsCards(array $conversionStats): array;

  /**
   * Builds the 24-hour statistics render array.
   *
   * @phpstan-param array<string, mixed> $dailyStats
   *   Daily stats from DashboardStatsService::get24HourStats().
   *
   * @phpstan-return array<string, mixed>
   *   Render array containing 24h stat items.
   */
  #[\NoDiscard]
  public function buildStats24h(array $dailyStats): array;

  /**
   * Builds the system status section render array.
   *
   * @phpstan-param array<string, mixed> $ffmpegStatus
   *   FFmpeg status data with keys: available, version, path, hardware.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for system status section.
   */
  #[\NoDiscard]
  public function buildSystemStatus(array $ffmpegStatus): array;

  /**
   * Builds the active conversions section render array.
   *
   * @phpstan-param array<int, array<string, mixed>> $activeConversions
   *   Active conversion data with media_id, status, percent, etc.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for active conversions section.
   */
  #[\NoDiscard]
  public function buildActiveConversions(array $activeConversions): array;

  /**
   * Builds the recent conversions section render array.
   *
   * @phpstan-param array<int, array<string, mixed>> $recentConversions
   *   Recent conversion data from stats service.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for recent conversions section.
   */
  #[\NoDiscard]
  public function buildRecentConversions(array $recentConversions): array;

  /**
   * Builds the recent failures section render array.
   *
   * @phpstan-param array<int, array<string, mixed>> $recentFailures
   *   Recent failure data from stats service.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for recent failures section.
   */
  #[\NoDiscard]
  public function buildRecentFailures(array $recentFailures): array;

  /**
   * Builds the media listing table render array.
   *
   * @phpstan-param array<int, array<string, mixed>> $items
   *   Media items with status data. Each item has keys:
   *   - label: string
   *   - media_id: int|string
   *   - bundle_label: string
   *   - status: string
   *   - updated: int|null (timestamp)
   *   - output_badges: array<string, mixed> (render array)
   *   - operations: array<string, array{
   *       title: \Drupal\Core\StringTranslation\TranslatableMarkup,
   *       url: \Drupal\Core\Url
   *     }>
   *
   * @phpstan-return array<string, mixed>
   *   Render array for media table.
   */
  #[\NoDiscard]
  public function buildMediaTable(array $items): array;

  /**
   * Builds the enhanced queue status render array.
   *
   * @phpstan-param array<string, mixed> $queueStatus
   *   Queue status with normal_count, large_count, total_count, and optional
   *   queued_media authoritative dedup count.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for queue status grid.
   */
  #[\NoDiscard]
  public function buildEnhancedQueueStatus(array $queueStatus): array;

  /**
   * Builds the status filter pills render array.
   *
   * @param string $currentFilter
   *   Currently active filter value.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for status filter navigation.
   */
  #[\NoDiscard]
  public function buildStatusFilter(string $currentFilter): array;

  /**
   * Builds the setup incomplete alert render array.
   *
   * @param bool $hasMappings
   *   Whether any auto-convert formatter is configured.
   * @param string $configUrl
   *   URL to the settings configuration form.
   *
   * @phpstan-return array<string, mixed>
   *   Render array for setup alert, empty if configured.
   */
  #[\NoDiscard]
  public function buildSetupAlert(bool $hasMappings, string $configUrl): array;

  /**
   * Builds a status badge render array.
   *
   * @param string $status
   *   Status string (pending, processing, completed, failed, none).
   *
   * @phpstan-return array<string, mixed>
   *   Render array for status badge.
   */
  #[\NoDiscard]
  public function buildStatusBadge(string $status): array;

}
