<?php

declare(strict_types=1);

namespace App\Framework\LiveComponents\Contracts;

use App\Application\LiveComponents\LiveComponentState;
use App\Framework\Http\UploadedFile;
use App\Framework\LiveComponents\ComponentEventDispatcher;

/**
 * Interface for LiveComponents that support file uploads
 *
 * Components implementing this interface can handle file uploads
 * through the LiveComponent upload endpoint.
 *
 * Following the same pattern as regular LiveComponent actions,
 * handleUpload() returns the component's State object with updated state.
 * The Handler will create the ComponentUpdate from the returned state.
 */
interface SupportsFileUpload
{
    /**
     * Handle file upload
     *
     * @param UploadedFile $file The uploaded file
     * @param ComponentEventDispatcher|null $events Optional event dispatcher
     * @return LiveComponentState Updated component state
     */
    public function handleUpload(UploadedFile $file, ?ComponentEventDispatcher $events = null): LiveComponentState;

    /**
     * Validate uploaded file
     *
     * @param UploadedFile $file The file to validate
     * @return array Array of validation errors (empty if valid)
     */
    public function validateUpload(UploadedFile $file): array;

    /**
     * Get allowed MIME types for upload
     *
     * @return array<string> List of allowed MIME types (empty = allow all)
     */
    public function getAllowedMimeTypes(): array;

    /**
     * Get maximum file size in bytes
     *
     * @return int Maximum file size (0 = no limit)
     */
    public function getMaxFileSize(): int;
}
