<?php

declare(strict_types=1);

namespace App\Application\LiveComponents\Services;

use App\Application\LiveComponents\ValueObjects\Suggestion;
use App\Application\LiveComponents\ValueObjects\SuggestionContext;

/**
 * SuggestionProvider - Interface for loading autocomplete suggestions
 */
interface SuggestionProvider
{
    /**
     * Get filtered and sorted suggestions for a query
     *
     * @param string $query Search query (minimum 2 characters)
     * @param SuggestionContext $context Context for suggestions
     * @param int $limit Maximum number of suggestions to return
     * @return array<Suggestion>
     */
    public function getSuggestions(string $query, SuggestionContext $context, int $limit = 10): array;

    /**
     * Get all available contexts
     *
     * @return array<SuggestionContext>
     */
    public function getAvailableContexts(): array;
}
