<?php

declare(strict_types=1);

namespace App\Application\LiveComponents\Services;

/**
 * ImageGalleryDataProvider Interface
 *
 * Provides image data for ImageGalleryComponent.
 * Implementations can use different data sources (Database, API, Demo data, etc.)
 */
interface ImageGalleryDataProvider
{
    /**
     * Get images with filtering, sorting, and pagination
     *
     * @param string $sortBy Sort field (created_at, filename, file_size, width, height)
     * @param string $sortDirection Sort direction (asc, desc)
     * @param string|null $mimeType Filter by mime type
     * @param string $searchQuery Search in filename or alt text
     * @param int $page Current page (1-based)
     * @param int $limit Items per page
     * @return array{images: array, total: int, has_more: bool}
     */
    public function getImages(
        string $sortBy = 'created_at',
        string $sortDirection = 'desc',
        ?string $mimeType = null,
        string $searchQuery = '',
        int $page = 1,
        int $limit = 20
    ): array;

    /**
     * Delete an image
     *
     * @param string $imageUlid Image ULID
     * @return bool Success
     */
    public function deleteImage(string $imageUlid): bool;

    /**
     * Update image alt text
     *
     * @param string $imageUlid Image ULID
     * @param string $altText New alt text
     * @return bool Success
     */
    public function updateAltText(string $imageUlid, string $altText): bool;
}
