<?php

declare(strict_types=1);

namespace CliqThemes\StoreLocator\Data\Definition;

defined('ABSPATH') || exit;

use CliqThemes\UI\Data\DataProviderRegistry;

/**
 * A single admin entity's data-provider definition: it knows how to build and
 * register its provider (columns / filters / persistence) on the registry, and
 * returns its admin form schema.
 *
 * One implementation per entity keeps each entity's configuration a focused,
 * independently-evolvable unit (SRP) and lets new entities be added without
 * editing the orchestrator (OCP).
 */
interface ProviderDefinition
{
    /**
     * Provider identifier used as the registry key and form map key
     * (e.g. 'stores', 'brands').
     */
    public function key(): string;

    /**
     * Build the provider, register it on the registry, and return its admin
     * form schema. Return an empty array for providers with no editable form
     * (e.g. REST-only providers).
     *
     * @return array<string, mixed>
     */
    public function register(DataProviderRegistry $registry, ProviderContext $context): array;
}
