<?php

declare(strict_types=1);

namespace CliqThemes\UI\Contracts;

/**
 * A registry of reusable, host-overridable option datasets (Google font families,
 * CSS units, …) that the admin UI and PHP control schemas pull from instead of
 * hardcoding lists. The framework owns this generic web-platform data; host
 * plugins consume it via {@see \CliqThemes\UI\CliqUI::dataRepo()} and may register
 * or override datasets — they never redefine the data themselves.
 */
interface DataRepository
{
    /**
     * Register (or override) a dataset by key. The provider is a callable returning
     * the dataset array, resolved lazily on first {@see get()}.
     */
    public function register(string $key, callable $provider): void;

    /** True when a dataset is registered for the key. */
    public function has(string $key): bool;

    /**
     * Resolve a dataset (e.g. 'font_family') to its value — typically an option list
     * of [{ value, label }]. Returns [] for an unknown key.
     *
     * @return array<int|string, mixed>
     */
    public function get(string $key): array;
}
