<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media_ui\Service;

/**
 * Provides data retrieval for the dashboard media listing.
 *
 * @internal
 */
interface MediaListDataServiceInterface {

  /**
   * Gets all video media entities with status info for the dashboard.
   *
   * @param string $statusFilter
   *   Status filter value (empty for all, or 'none', 'pending', etc.).
   *
   * @phpstan-return array{items: array<int, array<string, mixed>>, total: int}
   *   Array with 'items' and 'total' keys.
   */
  #[\NoDiscard]
  public function getAllVideoMedia(string $statusFilter): array;

  /**
   * Prepares media items for the builder by extracting plain data.
   *
   * Transforms entity-based items into plain data arrays suitable
   * for the DashboardBuilderService, which does not handle entities.
   *
   * @phpstan-param array<int, array<string, mixed>> $items
   *   Media items from getAllVideoMedia() with entity references.
   *
   * @phpstan-return array<int, array<string, mixed>>
   *   Plain data arrays for the builder.
   */
  #[\NoDiscard]
  public function prepareMediaTableItems(array $items): array;

  /**
   * Builds quick action links for enabled modules the current user can access.
   *
   * @phpstan-return array<int, array{label: \Drupal\Core\StringTranslation\TranslatableMarkup, url: string}>
   *   Quick action link data.
   */
  #[\NoDiscard]
  public function buildQuickActions(): array;

}
