@tinya-code/gas-admin-ui 0.2.0-alpha.15 → 0.2.0-alpha.18

package/src/lib/core/models/schema.model.ts

@@ -1,1097 +0,0 @@
-/**
- * Modelos del schema de recursos — única fuente de verdad de la UI.
- * Especificación: doc/base.md §3–§7 y §9.
- *
- * Contrato de imágenes (decisión api.md §1): `image_url` en todo el JSON.
- */
-
-/** Anchos de columna dentro de una fila del layout (base.md §4: 1–12). */
-export type GridWidth = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-
-/** Operadores de `visibleWhen` / `readonlyWhen` (base.md §4). */
-export type ConditionOperator = 'eq' | 'ne' | 'empty' | 'contains';
-
-/**
- * Condición simple sobre otro campo del mismo nivel o del registro raíz.
- * Ej.: `{ field: 'availability', operator: 'eq', value: 'PreOrder' }`.
- */
-export interface FieldCondition {
-  field: string;
-  operator: ConditionOperator;
-  /** Valor de comparación; no aplica para `empty`. */
-  value?: string | number | boolean;
-}
-
-/**
- * Reglas de validación comunes (base.md §4).
- * Nota: algunas se solapan con opciones propias del tipo (§5); el motor de
- * validación (Fase 10) los fusiona y `validators` tiene prioridad.
- */
-export interface FieldValidators {
-  minLength?: number;
-  maxLength?: number;
-  pattern?: string;
-  min?: number;
-  max?: number;
-  minWords?: number;
-  maxWords?: number;
-  /** El valor debe ser único en el recurso (validación asíncrona). */
-  unique?: boolean;
-}
-
-/** Propiedades comunes a todo campo (base.md §4). */
-export interface FieldBase<T> {
-  /** Nombre de la propiedad en el JSON que envía/recibe el back. */
-  key: string;
-  /** Rótulo visible para el usuario en el formulario y la ficha. */
-  label: string;
-  /** Texto corto de ayuda que se muestra debajo del campo. */
-  help?: string;
-  /** Texto sugerente que se muestra dentro del input cuando está vacío. */
-  placeholder?: string;
-  /** Si es obligatorio. El back también lo valida (R7.4). */
-  required?: boolean;
-  /** Valor por defecto si el registro no trae este campo (ej. `default: 'none'` en un `select`/`dropdown`). */
-  default?: T;
-  /** Si el campo es solo lectura (no editable en el formulario). */
-  readonly?: boolean;
-  /** Bloquea el campo solo en creación, solo en edición o siempre. */
-  readonlyOn?: 'create' | 'update' | 'always';
-  /** Condición bajo la cual el campo es solo lectura (expresión sobre otros campos). */
-  readonlyWhen?: FieldCondition;
-  /** Condición bajo la cual el campo se muestra u oculta. */
-  visibleWhen?: FieldCondition;
-  /**
-   * Ciclo de vida de la VISIBILIDAD: oculta el campo en creación, en edición
-   * o siempre. Símétrico a `readonlyOn`, pero NO lo mismo que `visibleWhen`,
-   * que expresa una condición sobre el valor de otro campo.
-   *
-   * Vale para los campos que LLENA EL BACK (`ref`, `pin`): en alta no existen
-   * aún, así que mostrarlos vacíos y solo-lectura con un `help` que dice "se
-   * genera solo al guardar" es ruido ocupando la sección. `hidden()` de Signal
-   * Forms además los deja FUERA de la validación y del payload
-   * (field-host:311 no los dibuja, form-model:52 los salta).
-   */
-  hiddenOn?: 'create' | 'update' | 'always';
-  /**
-   * Selección dependiente (guía §1: país → ciudad). Clave del campo padre
-   * del MISMO nivel: mientras el padre esté vacío este campo queda
-   * `disabled`, y si el padre cambia el hijo se reinicia a su valor por
-   * defecto (plan 6.6).
-   */
-  dependsOn?: string;
-  /** Reglas de validación (mínimo, máximo, patrón, unicidad, etc.). */
-  validators?: FieldValidators;
-  /** Ancho en la grilla del formulario (1–12), igual que un widget del dashboard. */
-  width?: GridWidth;
-  /** Id de la sección/pestaña del layout a la que pertenece (base.md §4). */
-  section?: string;
-  /**
-   * R7.5: acceso por campo (B8 · R7.4b) — sólo UX; el back vuelve a
-   * verificar en cada petición.
-   */
-  access?: {
-    /** Código de nivel de acceso requerido para leer el campo. */
-    read?: string;
-    /** Código de nivel de acceso requerido para escribir el campo. */
-    write?: string;
-  };
-  /**
-   * Descripción corta de para qué sirve este campo. Se muestra como tooltip
-   * al pasar el cursor sobre el rótulo en el formulario y la ficha.
-   */
-  description?: string;
-  /** URL de documentación externa para este campo (se abre al hacer clic en el tooltip). */
-  docLink?: string;
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.1 Campos simples (valor escalar)
-// ─────────────────────────────────────────────────────────────
-
-export interface SelectOption {
-  value: string;
-  label: string;
-  disabled?: boolean;
-}
-
-export interface TextField extends FieldBase<string> {
-  type: 'text';
-  maxLength?: number;
-  pattern?: string;
-}
-
-export interface ColorField extends FieldBase<string> {
-  type: 'color';
-}
-
-export interface TextareaField extends FieldBase<string> {
-  type: 'textarea';
-  rows?: number;
-  minWords?: number;
-  maxWords?: number;
-  /**
-   * Marcadores insertables como chips bajo el área (plantillas de mensaje).
-   * Cada chip escribe `{key}` en la posición del cursor, no al final: el
-   * operador escribe, apreta, sigue escribiendo. El motor back no se entera —
-   * recibe el string final y lo interpola (`interpolateTemplate`).
-   *
-   * `label` es el rótulo humano del botón ("PIN"); `key` es la clave que se
-   * inserta y que el back resuelve contra `config + registro`.
-   */
-  tokens?: readonly TemplateToken[];
-}
-
-/** Chip insertable en un `textarea` de plantilla. */
-export interface TemplateToken {
-  /** Clave insertada como `{key}` y resuelta por el motor. */
-  key: string;
-  /** Rótulo visible en el chip (el token va como tooltip). */
-  label: string;
-}
-
-export interface SlugField extends FieldBase<string> {
-  type: 'slug';
-  /** Campo del que se autogenera el slug (ej. `name`). */
-  from: string;
-  /** Bloquea el campo una vez creado el registro (por defecto: sí). */
-  lockAfterCreate?: boolean;
-}
-
-export interface NumberField extends FieldBase<number> {
-  type: 'number';
-  min?: number;
-  max?: number;
-  step?: number;
-  decimals?: number;
-}
-
-export interface CurrencyField extends FieldBase<number> {
-  type: 'currency';
-  /** Campo del registro del que se toma la moneda (ej. `currency`). */
-  currencyFrom?: string;
-}
-
-export interface BooleanField extends FieldBase<boolean> {
-  type: 'boolean';
-  trueLabel?: string;
-  falseLabel?: string;
-}
-
-/**
- * De dónde salen las opciones de un desplegable: **exactamente una** de las
- * dos formas (XOR en el tipo, D62).
- *
- * - `options` — estáticas en el schema (el caso de las enums: `status`).
- * - `source` — pedidas al fetcher declarado (F8 · R6.5) para listados que
- *   viven en otro recurso.
- *
- * Ninguna ⇒ un desplegable mudo; las dos ⇒ dos verdades para el mismo campo.
- * Ambas reglas viven en este tipo, no en un chequeo en runtime.
- */
-type SelectData =
-  { options: SelectOption[]; source?: never } | { options?: never; source: DataSource };
-
-export type SelectField = FieldBase<string> & { type: 'select' } & SelectData;
-
-export type MultiselectField = FieldBase<string[]> & { type: 'multiselect' } & SelectData;
-
-/**
- * Desplegable nativo (`<select>`) que SIEMPRE se renderiza como lista
- * desplegable, independientemente de cuántas opciones tenga.
- *
- * A diferencia de `select` (que usa radio buttons para 2–4 opciones
- * estáticas por la guía de control §1), este tipo nunca muta a radios.
- * Úsalo cuando necesites un dropdown verdadero aunque tenga pocas opciones.
- */
-export interface DropdownField extends FieldBase<string> {
-  type: 'dropdown';
-  options: SelectOption[];
-}
-
-/**
- * Opción de un selector visual enriquecido (`rich-select`).
- *
- * Además de `value`/`label`, cada opción puede declarar una `preview` con
- * HTML seguro que el motor renderiza como tarjeta visual (badge, chip con
- * icono, color swatch, etc.). El HTML viaja en el schema y el motor lo
- * pinta tal cual tras pasar por el sanitizador de Angular.
- */
-export interface RichSelectOption {
-  value: string;
-  label: string;
-  disabled?: boolean;
-  /** HTML seguro para pintar como preview de la opción (ej. `<span class="chip">…</span>`). */
-  preview?: string;
-}
-
-/**
- * Selector visual enriquecido: cada opción se renderiza como tarjeta con su
- * `preview` HTML en vez de un `<select>` nativo o radio buttons planos.
- * Sólo opciones estáticas (sin `source`).
- */
-export interface RichSelectField extends FieldBase<string> {
-  type: 'rich-select';
-  options: RichSelectOption[];
-  /**
-   * Ancho de cada tarjeta de opción en la grilla (1–12), igual que `width`
-   * de un campo. Por defecto `4` (3 tarjetas por fila en escritorio).
-   * Úsalo para opciones con preview larga (menos tarjetas por fila) o
-   * preview corta (más tarjetas).
-   */
-  cardWidth?: GridWidth;
-  /**
-   * Cuántas tarjetas mostrar por fila en el punto de ruptura `lg`.
-   * Sobrescribe el cálculo automático basado en `cardWidth`.
-   * Ejemplo: `2` obliga a 2 columnas grandes sin importar el ancho.
-   */
-  cardCols?: 1 | 2 | 3 | 4 | 5 | 6;
-}
-
-export interface UrlField extends FieldBase<string> {
-  type: 'url';
-}
-
-export interface EmailField extends FieldBase<string> {
-  type: 'email';
-}
-
-export interface PhoneField extends FieldBase<string> {
-  type: 'phone';
-  /** Normalización del valor guardado. */
-  format?: 'e164' | 'digits';
-}
-
-export interface DateField extends FieldBase<string> {
-  type: 'date';
-  /** Fecha ISO `YYYY-MM-DD` permitida. */
-  min?: string;
-  max?: string;
-}
-
-export interface TimeField extends FieldBase<string> {
-  type: 'time';
-}
-
-export interface ReadonlyTextField extends FieldBase<string> {
-  type: 'readonly-text';
-  /** Formato de presentación (texto, fecha, moneda…). */
-  format?: string;
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.2 Referencias
-// ─────────────────────────────────────────────────────────────
-
-/**
- * Fuente de datos declarada (F8 · R6.5): UN vocabulario para relations,
- * selects y widgets en lugar de tres. El fetcher es único
- * (`DataSourceService`) y la clave de su caché es `resource+view+params`.
- *
- * `params` son valores interpolados `{campo}` que el front resuelve contra su
- * contexto (el registro del formulario o la fila del widget) y manda como
- * `payload.params`; el back los inyecta en el ctx de las vistas, donde una
- * condición los lee con el operando `param: '<nombre>'`. Una vista que no
- * referencia ese parámetro no se ve afectada por él — sólo cambia la clave
- * de caché.
- *
- * Los parámetros llegan del navegador, así que son ENTRADA: sólo filtran
- * dentro del recurso que la ruta ya autoriza a leer (nunca ensanchan el
- * acceso) y una vista que pide un parámetro ausente queda fail-closed.
- */
-export interface DataSource {
-  /** Recurso declarado (`resource.id`): su listado es el de las opciones. */
-  resource: string;
-  /** Vista declarada en `resource.views` (opcional): filtra en el back. */
-  view?: string;
-  /** Valores interpolados para la vista (`{campo}` ← contexto). */
-  params?: Record<string, string>;
-  /** Etiqueta por defecto de las filas (si no, `titleField` del recurso). */
-  labelField?: string;
-  /** Valor por defecto de las filas (si no, `keyField` del recurso). */
-  valueField?: string;
-}
-
-export interface RelationField extends FieldBase<string> {
-  type: 'relation';
-  /**
-   * De dónde salen las opciones (F8 · R6.5): `{ resource, view?, params?, … }`.
-   * Antes eran tres claves planas (`resource`/`labelField`/`valueField`);
-   * D62 las unifica con el resto de consumidores.
-   */
-  source: DataSource;
-  /**
-   * Segundo dato a mostrar junto a la etiqueta (guía §1: «Juan Pérez ·
-   * DNI 123»). Se concatena con « · » y forma parte de la opción, así que
-   * también se busca sobre él.
-   */
-  secondaryField?: string;
-  /** Cargar solo registros activos (lo exige además la FK en el back). */
-  onlyActive?: boolean;
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.3 Imagen — el valor es SOLO la URL pública (`image_url`)
-// ─────────────────────────────────────────────────────────────
-
-export interface ImageField extends FieldBase<string> {
-  type: 'image';
-  /** Tipos aceptados (ej. `image/*`, `image/png,image/jpeg`). */
-  accept?: string;
-  maxSizeMB?: number;
-  /** Relación de aspecto de la vista previa (ej. `16/9`). */
-  aspectRatio?: string;
-  previewSize?: string;
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.3b Archivo — el valor es SOLO la URL pública (mismo contrato que `image`)
-// ─────────────────────────────────────────────────────────────
-// R9.5.3: como `image`, pero para CUALQUIER archivo (pdf, xlsx, zip…). La
-// única diferencia semántica es que NO fuerza el prefijo `image/` en el
-// cliente: el catálogo de formatos lo acota el backend por campo (`formats`
-// declarado) o la lista global, y el motor guarda igualmente la URL.
-export interface FileField extends FieldBase<string> {
-  type: 'file';
-  /** Formatos aceptados (ej. `image/*`, `pdf,docx`). Si falta, usa los del backend. */
-  accept?: string;
-  maxSizeMB?: number;
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.4 Campos compuestos (contienen otros campos)
-// ─────────────────────────────────────────────────────────────
-
-export interface GroupField extends FieldBase<Record<string, unknown>> {
-  type: 'group';
-  fields: FieldSchema[];
-  /** Presentación del grupo (base.md §5.4). */
-  display?: 'card' | 'collapsible' | 'inline';
-}
-
-/** Propiedades comunes a las listas (base.md §6). */
-export interface ListOptions {
-  min?: number;
-  max?: number;
-  /** Si se puede reordenar (por defecto: sí). */
-  sortable?: boolean;
-  /** Campo donde se guarda el orden dentro de cada item (`position`). */
-  positionField?: string;
-  addLabel?: string;
-  emptyText?: string;
-  itemDisplay?: 'card' | 'row' | 'accordion';
-}
-
-export interface ListField extends FieldBase<Record<string, unknown>[]>, ListOptions {
-  type: 'list';
-  /** Campos de cada item (cualquier tipo, incluso `group` o `list`). */
-  itemFields: FieldSchema[];
-  /** Campo del item usado como título cuando está colapsado. */
-  itemTitle?: string;
-  /** El primer item tiene significado especial (ej. imagen principal). */
-  primaryFirst?: boolean;
-}
-
-export interface StringListField extends FieldBase<string[]>, ListOptions {
-  type: 'string-list';
-  /** Tipo permitido de cada item (base.md §9: solo text, url o email). */
-  itemType?: 'text' | 'url' | 'email';
-}
-
-export interface KeyValueItem {
-  key: string;
-  value: string;
-}
-
-export interface KeyValueField extends FieldBase<KeyValueItem[]>, ListOptions {
-  type: 'key-value';
-}
-
-// ─────────────────────────────────────────────────────────────
-// §5.6 Widgets de panel (sólo `kind: 'dashboard'` — refactormotor.md F4)
-// ─────────────────────────────────────────────────────────────
-
-/**
- * Base de un widget de panel. Se declara en `ResourceSchema.widgets` — no
- * en `fields`, porque un KPI no es un campo: no se valida, no se envía y
- * `field-host` no lo renderiza. Sólo un recurso `kind: 'dashboard'` los
- * dibuja, y agregar un widget es tocar el schema, no el template.
- *
- * Su `key` es además la clave del dato en la respuesta del endpoint del
- * dashboard (`{ key: 'pendientes' }` ↔ `{ pendientes: 3 }`), salvo que el
- * widget declare otra fuente (F8 · R6.5).
- */
-
-/**
- * Fuente de datos de un widget: el mismo vocabulario declarado de F8 que usan
- * relations y selects (D62), más el caso «payload del panel».
- *
- * - `DataSource` (`{ resource, view?, params? }`): el widget pide sus filas o
- *   su agregado al recurso declarado vía `DataSourceService`; deja de depender
- *   de que un handler haya armado `data[widget.key]`.
- * - `{ kind: 'payload' }`: lee la respuesta COMPLETA del endpoint del
- *   dashboard (varias claves a la vez).
- */
-export type WidgetSource = DataSource | { kind: 'payload' };
-
-export interface WidgetBase {
-  key: string;
-  label: string;
-  help?: string;
-  /** Ancho en la grilla del panel (1–12), igual que un campo. */
-  width?: GridWidth;
-  /**
-   * Ancho en la grilla en mobile (1–12). Por defecto `12` (ancho completo,
-   * apilado). Declararlo permite controlar el layout responsive en pantallas
-   * chicas sin tocar el ancho de escritorio (`width`).
-   */
-  mobileWidth?: GridWidth;
-  /**
-   * De dónde saca sus datos (F8 · R6.5).
-   *
-   * - **ausente** (por defecto): `data[widget.key]`. Es el contrato normal y
-   *   el que usan los KPI (`{ key: 'pendientes' }` ↔ `{ pendientes: 3 }`).
-   * - **`{ kind: 'payload' }`**: la respuesta COMPLETA, para widgets que se
-   *   componen de varias claves (`status-progress` leyendo `pendientes` +
-   *   `entregados` + `cancelados`) sin que el orquestador tenga que saber
-   *   qué tipo de widget es.
-   * - **`DataSource`**: las filas salen del recurso declarado (vista
-   *   incluida), pedidas al fetcher común.
-   */
-  source?: WidgetSource;
-}
-
-/** KPI de una cifra suelta («3 pendientes»). */
-export interface MetricCardWidget extends WidgetBase {
-  type: 'metric-card';
-  /** Texto secundario bajo la cifra (estático, va en el schema). */
-  hint?: string;
-}
-
-/** Barras por categoría con CSS/SVG — sin librería. */
-export interface BarChartWidget extends WidgetBase {
-  type: 'bar-chart';
-  /** Sufijo de las cifras del eje («unidades», «S/»). */
-  unit?: string;
-}
-
-/**
- * Serie temporal con Chart.js.
- *
- * La librería (61,4 K gz medidos) vive en el chunk que abre el descriptor
- * (`import('./chart-line')`), así que **no entra en el bundle inicial**; el
- * `@defer (on viewport)` que el propio componente dibuja tarda además la
- * creación del lienzo hasta que el gráfico se ve. Ver
- * `widgets/chart-line/chart-line.ts`.
- */
-export interface ChartLineWidget extends WidgetBase {
-  type: 'chart-line';
-  /** Sufijo de las cifras del eje («unidades», «S/»). */
-  unit?: string;
-}
-
-/** Tabla embebida de registros operativos (ej. pedidos que requieren atención). */
-export interface RecordListWidget extends WidgetBase {
-  type: 'record-list';
-  /**
-   * Claves de columnas a mostrar en la tabla compacta.
-   *
-   * No lleva `resource`: si las filas vienen declaradas, ese recurso ya está
-   * en `source.resource` (D63 retira la clave duplicada — estaba declarada y
-   * nadie la leía).
-   */
-  columns: string[];
-  /** Acción de navegación por fila. */
-  action?: {
-    label: string;
-    routeTemplate: string;
-  };
-}
-
-/** Grid de botones de accesos directos operativos. */
-export interface QuickActionsWidget extends WidgetBase {
-  type: 'quick-actions';
-  actions: {
-    label: string;
-    icon?: string;
-    navigateTo: string;
-    variant?: 'primary' | 'secondary' | 'outline';
-  }[];
-}
-
-/** Barra de distribución porcentual de estados o categorías. */
-export interface StatusProgressWidget extends WidgetBase {
-  type: 'status-progress';
-  segments: {
-    key: string;
-    label: string;
-    color: 'success' | 'warning' | 'danger' | 'neutral';
-  }[];
-}
-
-export type WidgetSchema =
-  | MetricCardWidget
-  | BarChartWidget
-  | ChartLineWidget
-  | RecordListWidget
-  | QuickActionsWidget
-  | StatusProgressWidget;
-
-export type WidgetType = WidgetSchema['type'];
-
-// ─────────────────────────────────────────────────────────────
-// Unión discriminada por `type` (21 tipos, base.md §5)
-// ─────────────────────────────────────────────────────────────
-
-export type FieldSchema =
-  | TextField
-  | TextareaField
-  | SlugField
-  | NumberField
-  | CurrencyField
-  | BooleanField
-  | SelectField
-  | MultiselectField
-  | RichSelectField
-  | DropdownField
-  | UrlField
-  | EmailField
-  | PhoneField
-  | DateField
-  | TimeField
-  | ReadonlyTextField
-  | RelationField
-  | ImageField
-  | FileField
-  | GroupField
-  | ListField
-  | StringListField
-  | KeyValueField
-  | ColorField;
-
-export type FieldType = FieldSchema['type'];
-
-// ─────────────────────────────────────────────────────────────
-// Listado, layout y metadatos del recurso (base.md §3)
-// ─────────────────────────────────────────────────────────────
-
-export type ListColumnFormat =
-  'text' | 'badge' | 'thumbnail' | 'boolean' | 'number' | 'currency' | 'date';
-
-export interface ListColumn {
-  key: string;
-  label: string;
-  /**
-   * Sólo para sobreescribir: sin él manda la tabla de
-   * `columns/column-defaults` (`FORMATO_POR_DEFECTO`) según el `type` del
-   * campo con esta `key` (R4.4).
-   */
-  format?: ListColumnFormat;
-}
-
-export interface ListFilter {
-  key: string;
-  label: string;
-  type?: 'text' | 'select' | 'boolean';
-  options?: SelectOption[];
-}
-
-export interface LayoutSection {
-  /** Coincide con `field.section`. */
-  id: string;
-  label: string;
-}
-
-export type LayoutMode = 'grid' | 'tabs' | 'sections' | 'steps' | 'columns';
-
-export interface ResourceLayout {
-  /** Presentación del formulario. */
-  mode?: LayoutMode;
-  sections?: LayoutSection[];
-  /** Número de columnas para `mode: 'columns'` (por defecto 2). */
-  columns?: 2 | 3;
-}
-
-export interface ResourceActionBase {
-  id: string;
-  label: string;
-  icon?: string;
-  variant?: 'primary' | 'secondary' | 'outline' | 'danger';
-  visibleWhen?: { field: string; op: 'eq' | 'neq' | 'in'; value: unknown }[];
-}
-
-export interface CopyShareAction extends ResourceActionBase {
-  type: 'copy-share';
-  urlTemplate: string;
-  shareTextTemplate?: string;
-}
-
-export interface NavigateAction extends ResourceActionBase {
-  type?: 'navigate';
-  /** Plantilla con marcadores, ej. `/products/{slug}` o `/admin/orders?id={ref}`. */
-  urlTemplate: string;
-}
-
-export interface TriggerAction extends ResourceActionBase {
-  /**
-   * Acción de dominio **declarada en el back** (B3 `actions.<name>`,
-   * publicada como `POST /admin/<recurso>/:id/actions/<name>` — R5.4).
-   * El destino no se declara acá: la ruta lógica se deriva en R3.12.
-   */
-  type: 'trigger';
-  /** Nombre de la acción en el back si difiere del `id` de esta declaración. */
-  name?: string;
-  confirmMessage?: string;
-}
-
-/** Acciones extra de registro o listado (duplicar, compartir, navegar…). */
-export type ResourceAction = CopyShareAction | NavigateAction | TriggerAction;
-
-/** Configuración de diálogo/modal o acción tras crear un registro con éxito. */
-export interface PostCreateSchema {
-  mode: 'modal' | 'toast' | 'redirect_detail' | 'stay';
-  title?: string;
-  description?: string;
-  summaryFields?: string[];
-  actions?: ResourceAction[];
-}
-
-/** Configuración de Ficha de Detalle (modo lectura estructurado). */
-export interface DetailViewSchema {
-  enabled: boolean;
-  headerFields?: string[];
-  sections?: {
-    id: string;
-    label: string;
-    fields: string[];
-  }[];
-  actions?: ResourceAction[];
-  allowEdit?: boolean;
-  allowDelete?: boolean;
-}
-
-/** Operaciones permitidas (base.md §3). `undefined` = permitido. */
-export interface ResourcePermissions {
-  create?: boolean;
-  update?: boolean;
-  remove?: boolean;
-  reorder?: boolean;
-}
-
-/**
- * Rutas de la API relativas a `API_URL` (base.md §3, api.md §6 Opción A).
- *
- * Marcadores que un path acepta — se resuelven ANTES de despachar la petición
- * (y para ambos drivers):
- *
- * - `{key}` — clave del registro actual; sólo aplica a las operaciones con
- *   clave (`get`, `update`, `remove`). Si llega sin resolver, es error.
- * - `{<fuente>}` / `{<fuente>.<ruta.anidada>}` — valor de una fuente de
- *   contexto: las construidas `auth` (sesión) y `config` (config global), o
- *   cualquier fuente registrada en `provideGasAdmin({ valueSources })`.
- *
- * El valor se codifica como segmento de URL. Un marcador sin valor, o con una
- * fuente no registrada, lanza un error que nombra el path y el marcador: nunca
- * se envía un segmento vacío. Los singleton solo usan `get` / `update`.
- */
-export interface ResourceEndpoints {
-  list?: string;
-  get?: string;
-  create?: string;
-  update?: string;
-  remove?: string;
-  /**
-   * Declaración opcional de cómo unwrappear la respuesta de esta operación.
-   * Cuando se declara, el motor extrae el contenido de `dataKey` antes de
-   * devolverlo al consumidor (ej.: `{ data: [...] }` → `[...]`).
-   * Si no se declara, el motor mantiene el comportamiento actual:
-   * respuesta pasada tal cual (array plano, `{ items }`, o objeto crudo).
-   * Esta declaración es por operación; si se desea un valor global, usarlo
-   * en cada operación o considerar un default a nivel de config en futuro.
-   */
-  responseUnwrap?: ResponseUnwrap;
-}
-
-/**
- * Cómo el motor debe desempaquetar la respuesta HTTP antes de entregarla.
- * Opcional y opt-in: schemas sin este campo siguen el contrato actual.
- *
- * - `dataKey`: clave en el body que contiene el payload real (ej. `data`,
- *   `items`, `result`). Si el body no tiene esta clave, se devuelve `undefined`
- *   para lista / objeto vacío según corresponda, y se lanza error en modo
- *   estricto si se configura.
- * - `metaKey`: clave con metadatos (paginación, total, etc.). Se ignora en
- *   el valor devuelto al consumidor pero puede leerse si el motor la expone
- *   en futuro.
- * - `apply`: `'list' | 'get' | 'create' | 'update' | 'remove' | 'all'`.
- *   Qué operaciones aplican el unwrap. Por defecto `'all'` cuando se declara.
- */
-export interface ResponseUnwrap {
-  dataKey: string;
-  metaKey?: string;
-  apply?: 'list' | 'get' | 'create' | 'update' | 'remove' | 'all';
-  /**
-   * Claves de metadata de paginación dentro del sobre. Usadas por
-   * `ApiService.listPage()` para armar `PageResult<T>`. Opcional: sin
-   * declaración, el motor intenta auto-detectar claves comunes
-   * (`nextCursor`, `total`, `hasMore`) y, si no hay, `hasMore = false`.
-   */
-  pagination?: {
-    /** Clave del cursor siguiente dentro de `meta` (o del body si no hay `metaKey`). */
-    cursorKey?: string;
-    /** Clave del total de registros. */
-    totalKey?: string;
-    /** Clave del flag booleano "hay más páginas". */
-    hasMoreKey?: string;
-  };
-}
-
-/**
- * Método HTTP soportado por endpoints personalizados.
- * Declarado aquí (y no en api.service.ts) para evitar ciclos de importación
- * entre modelos y servicios.
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-
-/**
- * Definición de un endpoint personalizado más allá de los cinco estándar
- * (list/get/create/update/remove). Permite al consumidor declarar rutas con
- * verbos arbitrarios, segmentos extra, payloads JSON o multipart, y unwrap de
- * respuesta propio.
- *
- * Ejemplo:
- *   name: 'recalculate-ranks'
- *   method: 'POST'
- *   path: '/admin/businesses/{businessId}/ranks/recalculate'
- *   payloadMode: 'json'
- */
-export interface CustomEndpointDefinition {
-  /** Nombre único del endpoint dentro del recurso. Se usa para invocarlo. */
-  name: string;
-  /** Método HTTP de la petición. */
-  method: HttpMethod;
-  /** Ruta relativa a `API_URL`. Puede incluir marcadores {key}, {auth.user.id}, etc. */
-  path: string;
-  /** Modo de payload: 'json' (default) o 'multipart' para FormData. */
-  payloadMode?: 'json' | 'multipart';
-  /** Unwrap de respuesta override para este endpoint. Si no se declara, se usa el del recurso. */
-  responseUnwrap?: ResponseUnwrap;
-}
-
-export interface ResourceSchema {
-  /** Identificador interno (`categories`). */
-  id: string;
-  label: string;
-  labelPlural: string;
-  /**
-   * `collection` → listado, `singleton` → formulario directo,
-   * `dashboard` → panel de sólo lectura (refactormotor.md F4; sus datos llegan
-   * un endpoint declarativo, no de CRUD).
-   */
-  kind: 'collection' | 'singleton' | 'dashboard';
-  endpoint: ResourceEndpoints;
-  /** Campo que identifica el registro (`slug`). */
-  keyField: string;
-  /** Campo que se muestra como nombre del registro. */
-  titleField: string;
-  /** Endpoints personalizados más allá de list/get/create/update/remove. */
-  customEndpoints?: Record<string, CustomEndpointDefinition>;
-  /** Si el listado se reordena (requiere `positionField`). */
-  sortable?: boolean;
-  positionField?: string;
-  listColumns: ListColumn[];
-  filters?: ListFilter[];
-  /** Campos buscables en el listado. */
-  search?: string[];
-  /** Árbol de campos del formulario (base.md §4–§6). */
-  fields: FieldSchema[];
-  /**
-   * Widgets del panel — sólo `kind: 'dashboard'` (refactormotor.md F4).
-   *
-   * Van aparte de `fields`: un KPI no es un campo y no comparte `FieldBase`
-   * (`required`/`visibleWhen`/`validators`…). Decisión tomada tras medir el
-   * ripple de unirlos a `FieldSchema`: 18+ errores de tipos en 4 ficheros.
-   * `contract-check` sólo recorre `fields`, así que esta propiedad no se
-   * compara back↔front — el widget es config de UI, no dato almacenado.
-   */
-  widgets?: WidgetSchema[];
-  layout?: ResourceLayout;
-  actions?: ResourceAction[];
-  /** Configuración de Ficha de Detalle estructurada para el recurso. */
-  detail?: DetailViewSchema;
-  /** Configuración de diálogo/modal post-creación. */
-  postCreate?: PostCreateSchema;
-  permissions?: ResourcePermissions;
-  /**
-   * Acceso declarado por recurso (auth.md §5.3) — **sólo UX**: oculta
-   * ruta, entrada de menú y botones. Aunque el front se manipule, el back
-   * vuelve a verificar en cada petición: esto nunca es una barrera.
-   *
-   * No lo declara ningún schema mientras sólo exista el rol `admin`
-   * (§9.4): sin declaración el efecto es «sesión», que es lo correcto hoy.
-   * Aparece el día que haya un segundo rol.
-   */
-  access?: ResourceAccess;
-  /**
-   * Claves de `fields` que el listado edita en un drawer sin navegar
-   * (plan 6.5, guía §5: «edición rápida de pocos campos, panel lateral en
-   * lugar de pantalla nueva»). 1–3 campos; si no se declara, no hay atajo.
-   */
-  quickEdit?: string[];
-
-  // ── Metadatos públicos de `/admin/schema` (F7-1, PLAN-MEJORAS) ──
-  // Ausentes ⇒ sólo manda el schema local (merge local-driven preservado).
-  /** Rutas efectivas por operación, con la forma pública si la declara. */
-  operations?: ResourceOperations;
-  /** Vistas declaradas como metadatos (sin operandos internos). */
-  views?: Record<string, ViewDescriptor>;
-  /** Páginas y rutas del frontend; separado de `views` del backend. */
-  uiViews?: Record<string, UiViewDescriptor>;
-  /** Lo mínimo del backend para menú/acciones: `access` normalizado. */
-  policies?: ResourcePolicies;
-}
-
-// ─────────────────────────────────────────────────────────────
-// Metadatos públicos de `/admin/schema` (F7-1)
-// ─────────────────────────────────────────────────────────────
-
-/** Forma pública de la respuesta de una operación (declaración `shape`). */
-export interface OperationShape {
-  pick?: 'full' | 'list' | string[];
-  include?: string[];
-  rename?: Record<string, string>;
-  nest?: Record<string, string[]>;
-  envelope?: 'plain' | 'list';
-}
-
-/** Ruta efectiva de una operación: método + path (con `{key}` si aplica). */
-export interface OperationDescriptor {
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  path: string;
-  shape?: OperationShape;
-}
-
-/** Operaciones CRUD efectivas (derivadas de la misma ruta que el router). */
-export interface ResourceOperations {
-  list?: OperationDescriptor;
-  get?: OperationDescriptor;
-  create?: OperationDescriptor;
-  update?: OperationDescriptor;
-  remove?: OperationDescriptor;
-}
-
-/**
- * Condición de vista como metadato público: el literal `value` y el `ref`
- * (metadato de relación) viajan; el operando interno `from: '$item.x'` no.
- */
-export interface ViewCondition {
-  field: string;
-  op: string;
-  not?: boolean;
-  value?: unknown;
-  ref?: string;
-}
-
-/** Vista declarada publicada como metadato (F7-1). */
-export interface ViewDescriptor {
-  where?: ViewCondition[];
-  sort?: { field: string; dir?: 'asc' | 'desc' }[];
-  limit?: number;
-  extends?: string;
-  /** Vista con handler propio (escape hatch): su existencia, nada más. */
-  custom?: boolean;
-}
-
-/** Config para una `uiView` de tipo `calendar`. */
-export interface CalendarViewConfig {
-  /** Campo `date` (o `datetime` futuro): inicio del evento. Obligatorio. */
-  startField: string;
-  /** Campo `date`/`time`: fin. Ausente ⇒ evento de 1 día sobre `startField`. */
-  endField?: string;
-  /** Campo `text`/`relation`: rótulo del evento. Obligatorio. */
-  titleField: string;
-  /** Campo `select`/`text`: color/estado (token de paleta o valor crudo). */
-  colorField?: string;
-  /** Vista por defecto al abrir. Por defecto `month`. */
-  defaultView?: 'month' | 'week' | 'day' | 'agenda';
-  /** Origen de filas; ausente ⇒ la propia instancia del recurso (su listado). */
-  source?: DataSource;
-}
-
-/** Config para una `uiView` de tipo `kanban`. */
-export interface KanbanViewConfig {
-  /** Campo `select`/`relation`: columna por valor. Obligatorio. */
-  groupField: string;
-  /** Orden estable de columnas. Valores no declarados ⇒ columna extra al final. */
-  columns: KanbanColumn[];
-  /** Rótulo de la tarjeta; ausente ⇒ `keyField` del recurso. */
-  titleField?: string;
-  /** Segundo renglón de la tarjeta (opcional). */
-  subtitleField?: string;
-  /** Origen de filas; ausente ⇒ la propia instancia del recurso. */
-  source?: DataSource;
-}
-
-/** Una columna del tablero Kanban. */
-export interface KanbanColumn {
-  /** Valor del `groupField` que agrupa esta columna. */
-  value: string;
-  /** Etiqueta visible de la columna. */
-  label: string;
-}
-
-/**
- * Evento que dispara un `select` declarado (R9.9.4): `open`, `select` o una
- * acción con nombre (`open-detail`). El string libre cubre las acciones con
- * nombre sin perder autocompletado para los dos literales fijos.
- */
-export type SelectionTrigger = 'open' | 'select' | (string & {});
-
-/**
- * Destino de navegación declarado (R9.9.4 · spec view-navigation): recurso +
- * `uiView` declarada + params de ruta permitidos. Las URLs crudas o
- * externas NO son destinos válidos — el validador las rechaza pre-render.
- */
-export interface NavigationTarget {
-  /** Recurso declarado (`schema.id` del front). */
-  resource: string;
-  /** Clave de `uiViews` en ese recurso. */
-  view: string;
-  /** Nombres de params de la ruta del destino (`:key` ⇒ `['key']`). */
-  params?: string[];
-}
-
-/**
- * Vinculación selección ⇒ transición declarada en una `uiView` o en un hijo
- * de composición (R9.9.4). `route` exige un `NavigationTarget` declarado;
- * `inline` selecciona en local y `none` es un no-op explícito.
- */
-export type SelectionBinding =
-  | { on: SelectionTrigger; mode: 'none' | 'inline' }
-  | { on: SelectionTrigger; mode: 'route'; target: NavigationTarget };
-
-/** Base común de todo hijo de una composición embebida (R9.9.2). */
-export interface ViewChildBase {
-  /** Identificador estable y único entre hermanos del mismo contenedor. */
-  id: string;
-  /** Etiqueta visible (rótulo de la pestaña). */
-  label: string;
-  /** Conserva el estado al cambiar de pestaña; ausente ⇒ destruir (R9.9.5). */
-  retain?: boolean;
-  /** Visibilidad declarativa (condiciones sobre campos del formulario). */
-  visibleWhen?: FieldCondition[];
-}
-
-/**
- * Hijo declarado inline (`type` + `config`) o por referencia a una `uiView`
- * del mismo schema (`ref`). Los `ref` hacen posible que un contenedor
- * contenga —directa o transitivamente— a sí mismo: por eso el
- * `composition-validator` es obligatorio antes del render (D2).
- */
-export type ViewChildNode = (ViewChildBase & UiViewDescriptor) | (ViewChildBase & { ref: string });
-
-/** Config de una `uiView` contenedora `tabs` (R9.9.2). */
-export interface TabsConfig {
-  /** Lista ordenada de hijos; el orden declarado es el orden de render. */
-  children: ViewChildNode[];
-  /** `id` del hijo seleccionado al montar; ausente ⇒ el primero. */
-  initial?: string;
-}
-
-/** Vista `tabs` declarada en el schema local del frontend. */
-export interface UiViewTabs extends UiViewBase {
-  type: 'tabs';
-  config: TabsConfig;
-}
-
-/** Base común de toda `uiView`: tipo + ruta relativa al recurso. */
-export interface UiViewBase {
-  /** Tipo resuelto por `kind: 'view'` en el registro de render. */
-  type: string;
-  /** Ruta relativa al recurso; ausente o vacía significa la ruta raíz. */
-  path?: string;
-  /**
-   * Binding de selección declarado (R9.9.4). Ausente ⇒ la hoja conserva su
-   * comportamiento local y NO navega; una URL cruda nunca es un destino
-   * válido (el `composition-validator` la rechaza antes del render, D2).
-   */
-  select?: SelectionBinding;
-}
-
-/** Vista `calendar` declarada en el schema local del frontend. */
-export interface UiViewCalendar extends UiViewBase {
-  type: 'calendar';
-  config: CalendarViewConfig;
-}
-
-/** Vista `kanban` declarada en el schema local del frontend. */
-export interface UiViewKanban extends UiViewBase {
-  type: 'kanban';
-  config: KanbanViewConfig;
-}
-
-/**
- * Una página/ruta declarada en el schema local del frontend, discriminada
- * por `type`. Los tipos base (`list`/`detail`/`form`/`dashboard`) conservan
- * la forma plana sin `config`; `calendar` y `kanban` llevan su config tipada.
- */
-export type UiViewDescriptor = UiViewBase | UiViewCalendar | UiViewKanban | UiViewTabs;
-
-/** Políticas públicas: sólo `access`, lo mínimo para menú/acciones. */
-export interface ResourcePolicies {
-  access: {
-    read: string;
-    write: string;
-    /** R7.5: override por operación (B8 · R7.4a) */
-    operations?: Record<string, string>;
-  };
-}
-
-/** §5.3 — `access` de un recurso. `requires` usa el vocabulario de §4.4. */
-export interface ResourceAccess {
-  requires?: string;
-  roles?: string[];
-}
-
-/** Un campo de la pantalla de login (auth.md §5.1). */
-export interface AuthFieldDeclaration {
-  key: string;
-  /** `email` | `password` — tipos primitivos; el registro de render los
-   *  absorberá en Fase 3 (R3.3), cuando exista el descriptor `password`. */
-  type: string;
-  required?: boolean;
-}
-
-/** Supported auth providers. Extensible without breaking existing schemas. */
-export type AuthProvider = 'password' | 'google' | (string & {});
-
-/** Firebase config block — present only when at least one Firebase provider is listed. */
-export interface FirebaseAuthConfig {
-  /**
-   * The backend endpoint that exchanges a Firebase ID token for the app token.
-   * Defaults to '/auth/firebase' when omitted.
-   */
-  exchangeEndpoint?: string;
-}
-
-/**
- * Pantalla de login declarada (auth.md §5.1): **vive sólo en el schema del
- * front** — el back no conoce estas etiquetas ni este layout, sólo declara
- * el `input` de `/auth/login`. El `contract-check` (R2.11) verifica que las
- * claves de `loginFields` existan en ese `input`.
- */
-export interface AuthSchema {
-  /** Proveedores disponibles: 'password' | 'google' u otros federados. */
-  providers: AuthProvider[];
-  loginFields: AuthFieldDeclaration[];
-  redirectAfterLogin: string;
-  /**
-   * D10-3 → **`false` siempre.** La opción «recordarme» con `localStorage`
-   * quedó denegada (§9.3): el token vive en `sessionStorage` y muere con la
-   * pestaña. Declarar `true` prometería un storage que nadie usa.
-   */
-  rememberMe: boolean;
-  /** Configuración de Firebase cuando se usan proveedores federados o Firebase Auth. */
-  firebase?: FirebaseAuthConfig;
-}
-