<?php
declare(strict_types=1);

namespace ROITheme\Admin\Shared\Domain\Contracts;

/**
 * Contrato para mapeo de campos de formulario a atributos de BD
 *
 * RESPONSABILIDAD:
 * - Definir el mapeo de field IDs a grupos/atributos
 * - Cada modulo implementa su propio mapper
 *
 * PRINCIPIOS:
 * - ISP: Interfaz pequena (2 metodos)
 * - DIP: Capas superiores dependen de esta abstraccion
 */
interface FieldMapperInterface
{
    /**
     * Retorna el nombre del componente que mapea
     *
     * @return string Nombre en kebab-case (ej: 'cta-box-sidebar')
     */
    public function getComponentName(): string;

    /**
     * Retorna el mapeo de field IDs a grupo/atributo
     *
     * @return array<string, array{group: string, attribute: string}>
     *
     * Ejemplo:
     * [
     *     'ctaTitle' => ['group' => 'content', 'attribute' => 'title'],
     *     'ctaEnabled' => ['group' => 'visibility', 'attribute' => 'is_enabled'],
     * ]
     */
    public function getFieldMapping(): array;
}