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

package/src/lib/core/adapters/firebase-auth.adapter.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-exporta `FirebaseAuthAdapter` desde `tokens.ts` (única fuente de verdad).
+ * Mantiene este archivo como punto de importación estable para consumidores
+ * que ya referencian esta ruta, sin duplicar la definición de la interfaz.
+ */
+export type { FirebaseAuthAdapter } from '../tokens';

package/src/lib/core/guards/auth.guard.spec.ts

@@ -0,0 +1,88 @@
+import { provideHttpClient } from '@angular/common/http';
+import { TestBed } from '@angular/core/testing';
+import { ActivatedRouteSnapshot, Router, UrlTree, provideRouter } from '@angular/router';
+
+import { API_URL } from '../tokens';
+import { SESSION_TOKEN_KEY, SESSION_USER_KEY } from '../services/auth.service';
+import { authGuard, roleGuard } from './auth.guard';
+
+/**
+ * R2.10 — guards de sesión (auth.md §5.3).
+ *
+ * No son una barrera (el back re-verifica desde R2.6): son el filtro de
+ * pantalla. Por eso aquí sólo se comprueba HACIA DÓNDE mandan, no qué
+ * protegen.
+ */
+describe('authGuard / roleGuard — filtro de pantalla (R2.10)', () => {
+  afterEach(() => sessionStorage.clear());
+
+  /** `role === null` ⇒ sin sesión: no se siembra nada en el storage. */
+  function setup(role: string | null = 'admin') {
+    sessionStorage.clear();
+    if (role !== null) {
+      sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok');
+      sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role }));
+    }
+
+    TestBed.configureTestingModule({
+      providers: [provideHttpClient(), provideRouter([]), { provide: API_URL, useValue: '/api' }],
+    });
+    return { authGuard, roleGuard, router: TestBed.inject(Router) };
+  }
+
+  /** `route` mínimo con un solo parámetro de ruta. */
+  function routeWithId(id: string | null): ActivatedRouteSnapshot {
+    return {
+      paramMap: {
+        get: (key: string) => (key === 'id' ? id : null),
+      },
+    } as unknown as ActivatedRouteSnapshot;
+  }
+
+  const isUrlTree = (r: unknown): r is UrlTree => r instanceof UrlTree;
+
+  /**
+   * El router invoca un guard DENTRO de un contexto de inyección; una llamada
+   * directa desde el spec no lo tiene, y `inject(AuthService)` revienta.
+   * `runInInjectionContext` reproducía el contexto real del router.
+   */
+  function run(guard: typeof authGuard, route: ActivatedRouteSnapshot): boolean | UrlTree {
+    const result = TestBed.runInInjectionContext(() => guard(route, {} as never));
+    // Los dos guards son síncronos: `MaybeAsync` sólo es ruido de tipos acá.
+    return result as boolean | UrlTree;
+  }
+
+  it('con sesión deja pasar', () => {
+    const { authGuard: guard } = setup();
+    expect(run(guard, {} as ActivatedRouteSnapshot)).toBe(true);
+  });
+
+  it('sin sesión manda a /login', () => {
+    const { authGuard: guard, router } = setup(null);
+    const result = run(guard, {} as ActivatedRouteSnapshot);
+    expect(isUrlTree(result)).toBe(true);
+    expect(router.serializeUrl(result as UrlTree)).toBe('/login');
+  });
+
+  it('sin sesión, un `:id` también manda a /login (redundancia barata)', () => {
+    const { roleGuard: guard, router } = setup(null);
+    const result = run(guard, routeWithId('orders'));
+    expect(isUrlTree(result)).toBe(true);
+    expect(router.serializeUrl(result as UrlTree)).toBe('/login');
+  });
+
+  it('un `:id` desconocido deja que responda el back (no inventamos política)', () => {
+    const { roleGuard: guard } = setup();
+    expect(run(guard, routeWithId('no-existe'))).toBe(true);
+  });
+
+  it('una ruta sin `:id` no decide nada', () => {
+    const { roleGuard: guard } = setup();
+    expect(run(guard, routeWithId(null))).toBe(true);
+  });
+
+  it('un recurso sin `access` declarado se ve con sesión', () => {
+    const { roleGuard: guard } = setup('staff');
+    expect(run(guard, routeWithId('dashboard'))).toBe(true);
+  });
+});

package/src/lib/core/guards/auth.guard.ts

@@ -0,0 +1,48 @@
+import { inject } from '@angular/core';
+import type { CanActivateFn } from '@angular/router';
+import { Router } from '@angular/router';
+
+import { getSchema } from '../registry/schema-catalog';
+import { AuthService, LOGIN_PATH } from '../services/auth.service';
+
+/**
+ * Guards de sesión (auth.md §5.3).
+ *
+ * Dos puertas y ninguna es una barrera de seguridad: el back re-verifica
+ * `accessLevel` en **cada** petición desde R2.6. Éstas sólo evitan pintar
+ * una pantalla que no le toca al usuario — enseñarle un formulario que va
+ * a recibir 403 es mala UX, no un agujero.
+ *
+ * `authGuard` va en la ruta madre (todo el shell); `roleGuard` en cada
+ * `:id`, que es donde aparece el recurso que puede tener `access`.
+ */
+
+/** Sin sesión → login. Corre ANTES que cualquier ruta del shell. */
+export const authGuard: CanActivateFn = () => {
+  const auth = inject(AuthService);
+  if (auth.isAuthenticated()) return true;
+  return inject(Router).createUrlTree([LOGIN_PATH]);
+};
+
+/**
+ * El recurso declara `access` y esta sesión no lo cumple → se cancela la
+ * navegación. No hay pantalla de 403 (tampoco la pide §5.3) y el menú ya
+ * oculta la entrada, así que queda sólo el caso de alguien tecleando la URL.
+ */
+export const roleGuard: CanActivateFn = (route) => {
+  const auth = inject(AuthService);
+  const router = inject(Router);
+
+  // Redundante con `authGuard` (la madre ya filtra) pero barato: un hijo
+  // nunca debe dejar una sesión muerta navegando sola.
+  if (!auth.isAuthenticated()) return router.createUrlTree([LOGIN_PATH]);
+
+  const id = route.data?.['resourceId'] ?? route.paramMap.get('id');
+  // Ruta sin recurso declarado, o id que no existe en el registry → que
+  // responda el back (404). No inventar una política sobre datos ajenos.
+  if (id === null) return true;
+  const schema = getSchema(String(id));
+  if (schema === undefined) return true;
+
+  return auth.canAccess(schema.access);
+};

package/src/lib/core/guards/unsaved-changes.guard.ts

@@ -0,0 +1,16 @@
+import { CanDeactivateFn } from '@angular/router';
+
+/** Componente que expone si se puede salir (base.md §13.9: cambios sin guardar). */
+export interface CanLeaveWhenDirty {
+  canDeactivate(): boolean | Promise<boolean>;
+}
+
+/**
+ * Avisa antes de salir con cambios sin guardar. El componente decide:
+ * `canDeactivate()` devuelve `true` para salir limpio o una `Promise` que
+ * resuelve según la respuesta del usuario (vía `NotificationService.confirm`).
+ */
+export const unsavedChangesGuard: CanDeactivateFn<unknown> = (component) => {
+  const candidate = component as Partial<CanLeaveWhenDirty> | null | undefined;
+  return candidate?.canDeactivate?.() ?? true;
+};

package/src/lib/core/interceptors/api-error.interceptor.spec.ts

@@ -0,0 +1,182 @@
+import { HttpClient, provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { provideRouter } from '@angular/router';
+
+import { ApiError } from '../models/api.model';
+import { API_URL } from '../tokens';
+import { AuthService, SESSION_TOKEN_KEY, SESSION_USER_KEY } from '../services/auth.service';
+import { apiErrorInterceptor } from './api-error.interceptor';
+
+/**
+ * Emite `body` en el canal de éxito (el backend responde 200 con el error
+ * dentro) y devuelve el `ApiError` que el interceptor lanzó.
+ * A nivel de módulo: lo usan el describe de mensajes y el de R2.9.
+ */
+function errorFromBody(body: object): ApiError {
+  const http = TestBed.inject(HttpClient);
+  const mock = TestBed.inject(HttpTestingController);
+  let lanzado: unknown;
+  http.get('/recursos').subscribe({
+    error: (e: unknown) => {
+      lanzado = e;
+    },
+  });
+  mock.expectOne('/recursos').flush(body);
+  mock.verify();
+  return lanzado as ApiError;
+}
+
+/**
+ * Plan 7.3 — mensajes en lenguaje humano (guía §2).
+ *
+ * Dos canales distintos: el body del backend (que ya escribe en español) y
+ * el transporte (red caída, proxy, 5xx), que sin normalizar deja en pantalla
+ * el texto crudo de Angular: «Http failure response for http://…».
+ *
+ * **R2.9** — desde que el interceptor entrega los `AUTH_*` a
+ * `AuthService.applyAuthCode`, necesita poder inyectarlo: por eso acá hay
+ * router y `API_URL`, que son las dependencias de ese servicio.
+ */
+describe('apiErrorInterceptor — mensajes humanos', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([apiErrorInterceptor])),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+      ],
+    });
+  });
+
+  afterEach(() => sessionStorage.clear());
+
+  function failWith(status: number, body?: unknown): string {
+    const http = TestBed.inject(HttpClient);
+    const mock = TestBed.inject(HttpTestingController);
+    let message = '';
+    http.get('/recursos').subscribe({
+      error: (error: unknown) => {
+        message = error instanceof ApiError ? error.message : String(error);
+      },
+    });
+    const request = mock.expectOne('/recursos');
+    if (status === 0) {
+      // Red caída: el backend no llegó a responder.
+      request.error(new ErrorEvent('error'));
+    } else {
+      // `flush` con status fuera de 2xx materializa un `HttpErrorResponse`.
+      request.flush(body ?? '', { status, statusText: 'ERR' });
+    }
+    mock.verify();
+    return message;
+  }
+
+  it('un 5xx se explica en español, no con el texto crudo de Angular', () => {
+    expect(failWith(500)).toBe(
+      'El servidor tuvo un problema. Vuelve a intentarlo en unos segundos.',
+    );
+  });
+
+  it('la red caída (status 0) dice que no hubo conexión', () => {
+    expect(failWith(0)).toBe('No se pudo conectar con el servidor. Revisa tu conexión.');
+  });
+
+  it('un 403 habla de permisos', () => {
+    expect(failWith(403)).toBe('No tienes permisos para realizar esta acción.');
+  });
+
+  it('conserva el mensaje del backend cuando viene en el body (canal de éxito)', () => {
+    expect(
+      failWith(200, {
+        error: { status: 422, message: 'Ya existe un registro con este valor', path: 'name' },
+      }),
+    ).toBe('Ya existe un registro con este valor');
+  });
+
+  /**
+   * D42 — el422 manda sus rutas en `error.errors[]`, NO en `path`: sin
+   * modelar esa lista el form veía «Errores de validación» y no pintaba
+   * ningún campo (base.md §5, guía §10).
+   */
+  it('conserva errors[] completo (path, message, code) en el ApiError', () => {
+    const error = errorFromBody({
+      error: {
+        status: 422,
+        message: 'Errores de validación',
+        errors: [
+          {
+            path: 'sku',
+            message: 'Debe tener al menos 5 caracteres.',
+            code: 'VALIDATION_MIN_LENGTH',
+          },
+          { path: 'faq[2].answer', message: 'Campo obligatorio.', code: 'VALIDATION_REQUIRED' },
+        ],
+      },
+    });
+    expect(error.status).toBe(422);
+    expect(error.message).toBe('Errores de validación');
+    expect(error.issues).toEqual([
+      { path: 'sku', message: 'Debe tener al menos 5 caracteres.', code: 'VALIDATION_MIN_LENGTH' },
+      { path: 'faq[2].answer', message: 'Campo obligatorio.', code: 'VALIDATION_REQUIRED' },
+    ]);
+    // Sin `path` en el sobre no hay fieldPath: las rutas vienen en los issues.
+    expect(error.fieldPath).toBeUndefined();
+  });
+});
+
+/**
+ * R2.9 — éste es el ÚNICO puente entre el sobre de error y la tabla de
+ * §4.5. Si el interceptor dejara de llamar a `applyAuthCode`, el front se
+ * quedaría en una pantalla caducada sin reloguear: por eso el puente se
+ * prueba acá y las cinco filas de la tabla, en `auth.service.spec.ts`.
+ */
+describe('apiErrorInterceptor — entrega de los códigos de sesión (R2.9)', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    sessionStorage.setItem(SESSION_TOKEN_KEY, 'tok-vigente');
+    sessionStorage.setItem(SESSION_USER_KEY, JSON.stringify({ id: 'u_1', role: 'admin' }));
+    TestBed.configureTestingModule({
+      providers: [
+        provideHttpClient(withInterceptors([apiErrorInterceptor])),
+        provideHttpClientTesting(),
+        provideRouter([]),
+        { provide: API_URL, useValue: '/api' },
+      ],
+    });
+  });
+
+  afterEach(() => sessionStorage.clear());
+
+  it('conserva el `code` en el ApiError que recibe el llamador', () => {
+    const error = errorFromBody({
+      error: { status: 401, message: 'No autorizado', code: 'AUTH_EXPIRED' },
+    });
+    expect(error.code).toBe('AUTH_EXPIRED');
+    expect(error.status).toBe(401);
+  });
+
+  it('un error SIN código de sesión no toca la sesión', () => {
+    errorFromBody({ error: { status: 422, message: 'Datos no válidos', path: 'name' } });
+    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBe('tok-vigente');
+    expect(TestBed.inject(AuthService).isAuthenticated()).toBe(true);
+  });
+
+  it('FORBIDDEN deja al usuario DENTRO de la sesión (§4.5)', () => {
+    errorFromBody({ error: { status: 403, message: 'Prohibido', code: 'FORBIDDEN' } });
+    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBe('tok-vigente');
+    expect(TestBed.inject(AuthService).isAuthenticated()).toBe(true);
+  });
+
+  it('AUTH_INVALID borra token y usuario ANTES de nada más (§5.4)', () => {
+    errorFromBody({ error: { status: 401, message: 'No autorizado', code: 'AUTH_INVALID' } });
+    expect(sessionStorage.getItem(SESSION_TOKEN_KEY)).toBeNull();
+    expect(sessionStorage.getItem(SESSION_USER_KEY)).toBeNull();
+    const auth = TestBed.inject(AuthService);
+    expect(auth.token()).toBeNull();
+    expect(auth.user()).toBeNull();
+    expect(auth.isAuthenticated()).toBe(false);
+  });
+});

package/src/lib/core/interceptors/api-error.interceptor.ts

@@ -0,0 +1,87 @@
+import { HttpErrorResponse, HttpInterceptorFn, HttpResponse } from '@angular/common/http';
+import { inject } from '@angular/core';
+import { catchError, map, throwError } from 'rxjs';
+
+import { ApiError } from '../models/api.model';
+import type { ApiErrorBody } from '../models/api.model';
+import { AuthService } from '../services/auth.service';
+
+/**
+ * Mensaje humano para un error HTTP real (§2).
+ *
+ * El backend siempre responde 200 con el error dentro del body —eso ya
+ * viene en español—, así que esto sólo cubre lo que el transporte falla:
+ * red caída, proxy y 5xx. Sin esto el usuario ve el texto crudo de Angular
+ * («Http failure response for http://…»), que es inglés técnico.
+ */
+function httpMessage(status: number): string {
+  switch (status) {
+    case 0:
+      return 'No se pudo conectar con el servidor. Revisa tu conexión.';
+    case 401:
+      return 'Tu sesión ha expirado. Vuelve a iniciar sesión.';
+    case 403:
+      return 'No tienes permisos para realizar esta acción.';
+    case 404:
+      return 'No se encontró el recurso solicitado.';
+    case 409:
+      return 'El registro cambió o ya existe. Recarga la página y vuelve a intentarlo.';
+    case 413:
+      return 'El archivo es demasiado grande.';
+    case 422:
+      return 'Los datos enviados no son válidos.';
+    default:
+      if (status >= 500) {
+        return 'El servidor tuvo un problema. Vuelve a intentarlo en unos segundos.';
+      }
+      return status >= 400 ? 'No se pudo completar la operación.' : 'Error inesperado.';
+  }
+}
+
+function isErrorBody(body: unknown): body is ApiErrorBody {
+  if (typeof body !== 'object' || body === null) {
+    return false;
+  }
+  const error = (body as ApiErrorBody).error;
+  return typeof error === 'object' && error !== null && typeof error.message === 'string';
+}
+
+/**
+ * El backend responde SIEMPRE HTTP 200 y pone los errores en el body
+ * (api.md §7), así que se detectan en el canal de **éxito** y se relanzan
+ * como `ApiError` (con `fieldPath` cuando el backend envía `path`).
+ * Los errores HTTP reales (red caída, proxy) también se normalizan.
+ *
+ * **R2.9 — paso dos de dos.** Éste archivo es el ÚNICO punto donde el
+ * sobre de error se abre; lo que decide qué ocurre con un `AUTH_*` es
+ * `AuthService.applyAuthCode` (la tabla de §4.5). Aquí sólo se le entrega
+ * el código y se propaga el `ApiError` con él — un segundo sitio que
+ * «interprete» el código sería una regla duplicada y, a la larga, una que
+ * se contradiga con la primera.
+ */
+export const apiErrorInterceptor: HttpInterceptorFn = (req, next) => {
+  const auth = inject(AuthService);
+
+  return next(req).pipe(
+    map((event) => {
+      if (event instanceof HttpResponse && isErrorBody(event.body)) {
+        const { status, message, path, code, errors } = event.body.error;
+        // R2.9: ésta es la ÚNICA llamada a la tabla de §4.5.
+        auth.applyAuthCode(code);
+        // `errors[]` es el422 con rutas (D42): va entero al ApiError para que
+        // `ErrorMapperService` lo convierta en `serverErrors[prefix + key]`.
+        throw new ApiError(status, message, path, code, errors ?? []);
+      }
+      return event;
+    }),
+    catchError((err: unknown) => {
+      if (err instanceof ApiError) {
+        return throwError(() => err);
+      }
+      if (err instanceof HttpErrorResponse) {
+        return throwError(() => new ApiError(err.status, httpMessage(err.status)));
+      }
+      return throwError(() => err);
+    }),
+  );
+};

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

@@ -0,0 +1,104 @@
+/**
+ * Contrato HTTP con el backend (doc/baseapi.md §8 «Errores»).
+ *
+ * El backend responde SIEMPRE HTTP 200; los errores viajan en el body
+ * con `{ error: { status, message, errors?: [{ path, message }] } }`.
+ * El interceptor (Fase 3) los convierte en `ApiError`.
+ */
+
+/**
+ * Un error con ruta del422 (auth.md §6): `path` para pintarlo en el campo y
+ * `code` MAYUS_SNAKE (`VALIDATION_MIN_LENGTH`) para mapearlo sin leer texto.
+ */
+export interface ApiIssue {
+  /** Ruta del campo afectado (`faq[2].answer`, `sku`). */
+  path: string;
+  /** Mensaje en español, listo para pintar. */
+  message: string;
+  /** Código estable del validador (B11); el mensaje puede cambiar, el código no. */
+  code?: string;
+}
+
+/** Shape del body de error (doc/baseapi.md §8 «Errores»). */
+export interface ApiErrorBody {
+  error: {
+    status: number;
+    message: string;
+    /** Ruta del campo afectado cuando el backend la envía (base.md §10). */
+    path?: string;
+    /**
+     * Código de sesión de §4.5 (R2.9): `AUTH_REQUIRED` · `AUTH_INVALID` ·
+     * `AUTH_EXPIRED` · `FORBIDDEN` · `RATE_LIMITED`. Aparece SÓLO en esas
+     * cinco respuestas — el sobre de error es aditivo (O7 / D10-5).
+     */
+    code?: string;
+    /**
+     * Errores de validación con ruta (base.md §5, guía §10): el 422 los manda
+     * ACÁ (`error.errors[]`), no en `path`. Sin modelarlos el form veía
+     * «Errores de validación» genérico y ningún campo se pintaba (D42).
+     */
+    errors?: ApiIssue[];
+  };
+}
+
+/** Error de API estandarizado que lanza el interceptor de errores. */
+export class ApiError extends Error {
+  readonly status: number;
+  /** Ruta del campo que provocó el error (ej. `faq[2].answer`), si existe. */
+  readonly fieldPath?: string;
+  /** Código de sesión de §4.5 si el backend lo envió; `undefined` en el resto. */
+  readonly code?: string;
+  /** Issues con ruta (422); vacío cuando el error no trae `errors[]`. */
+  readonly issues: readonly ApiIssue[];
+
+  constructor(
+    status: number,
+    message: string,
+    fieldPath?: string,
+    code?: string,
+    issues: readonly ApiIssue[] = [],
+  ) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.fieldPath = fieldPath;
+    this.code = code;
+    this.issues = issues;
+  }
+}
+
+/**
+ * `meta.renewedToken` (auth.md §3.2/§3.4): el back lo adjunta a la respuesta
+ * cuando la vida del token bajó del umbral de renovación. Es el ÚNICO modo
+ * de que el front se entere — el token nuevo no viaja en cabeceras ni en la
+ * URL. Devuelve `null` cuando no hay renovación (que es lo normal).
+ *
+ * Vive acá y no en el `ApiService` porque lo consumen DOS servicios
+ * (`ApiService` y `AuthService`) y éste modelo no importa a ninguno de los
+ * dos: sin este archivo no hay ciclo de imports.
+ */
+export function renewedTokenOf(body: unknown): string | null {
+  if (body === null || typeof body !== 'object') return null;
+  const meta = (body as { meta?: unknown }).meta;
+  if (meta === null || typeof meta !== 'object') return null;
+  const token = (meta as { renewedToken?: unknown }).renewedToken;
+  return typeof token === 'string' && token !== '' ? token : null;
+}
+
+/**
+ * Resultado de una página para `ApiService.listPage()`.
+ *
+ * El backend envía la metadata de paginación dentro del sobre (típicamente
+ * en `meta`); el motor la extrae según la declaración `responseUnwrap.pagination`
+ * y la entrega en este shape. `list()` NO usa este tipo: sigue devolviendo `T[]`.
+ */
+export interface PageResult<T> {
+  /** Registros de la página actual. */
+  items: T[];
+  /** Cursor para pedir la página siguiente; `null` cuando no hay más. */
+  nextCursor: string | null;
+  /** Total de registros del conjunto, si el backend lo informa; `0` si no. */
+  total: number;
+  /** `true` si hay al menos una página más. `false` sin cursor informativo. */
+  hasMore: boolean;
+}

package/src/lib/core/models/schema-descriptions.ts

@@ -0,0 +1,118 @@
+/**
+ * Descripciones centralizadas del catálogo de campos del motor `@tinya-code/gas-admin-ui`.
+ *
+ * Este archivo es el único lugar donde se editan los textos descriptivos de
+ * cada propiedad del schema. Los JSDoc de `schema.model.ts` usan estos mismos
+ * textos para que el editor (VSCode) muestre tooltips al pasar el cursor
+ * sobre una propiedad del schema del consumidor.
+ *
+ * Estructura: clave de propiedad → descripción en español.
+ *
+ * Uso en el consumidor (loyalty-admin, etc.):
+ *   import { schemaDescriptions } from '@tinya-code/gas-admin-ui';
+ *   schemaDescriptions['docLink']; // 'URL de documentación externa para este campo.'
+ *
+ * Nota: este objeto no se renderiza en la UI; solo existe para documentación
+ * y tooltips del editor. Para renderizar tooltips en el formulario usa
+ * `description` en cada campo del schema del consumidor.
+ */
+
+export const schemaDescriptions = {
+  // ── Propiedades comunes a todo campo (FieldBase) ───────────────────────
+  key: 'Nombre de la propiedad en el JSON que envía/recibe el back.',
+  label: 'Rótulo visible para el usuario en el formulario y la ficha.',
+  help: 'Texto corto de ayuda que se muestra debajo del campo.',
+  placeholder: 'Texto sugerente que se muestra dentro del input cuando está vacío.',
+  required: 'Si es obligatorio. El back también lo valida (R7.4).',
+  default: 'Valor por defecto si el registro no trae este campo (ej. `default: "none"` en un `select`/`dropdown`).',
+  readonly: 'Si el campo es solo lectura (no editable en el formulario).',
+  readonlyOn: 'Bloquea el campo solo en creación, solo en edición o siempre.',
+  readonlyWhen: 'Condición bajo la cual el campo es solo lectura (expresión sobre otros campos).',
+  visibleWhen: 'Condición bajo la cual el campo se muestra u oculta.',
+  hiddenOn: 'Oculta el campo en creación, en edición o siempre.',
+  dependsOn: 'Selección dependiente (guía §1: país → ciudad). Clave del campo padre del mismo nivel.',
+  validators: 'Reglas de validación (mínimo, máximo, patrón, unicidad, etc.).',
+  width: 'Ancho en la grilla del formulario (1–12), igual que un widget del dashboard.',
+  section: 'Id de la sección/pestaña del layout a la que pertenece (base.md §4).',
+  read: 'Código de nivel de acceso requerido para leer el campo.',
+  write: 'Código de nivel de acceso requerido para escribir el campo.',
+  description: 'Descripción corta de para qué sirve este campo. Se muestra como tooltip al pasar el cursor sobre el rótulo.',
+  docLink: 'URL de documentación externa para este campo (se abre al hacer clic en el tooltip).',
+
+  // ── Opciones de select/dropdown ───────────────────────────────────────
+  value: 'Valor que se envía al back cuando se elige esta opción.',
+  labelOption: 'Texto visible de la opción.',
+  disabled: 'Si la opción está deshabilitada (no se puede elegir).',
+
+  // ── Campos específicos ─────────────────────────────────────────────────
+  type: 'Tipo de campo: `text`, `color`, `number`, `currency`, `boolean`, `select`, `dropdown`, `rich-select`, `multiselect`, `url`, `email`, `phone`, `date`, `time`, `readonly-text`, `slug`, `textarea`, `relation`, `image`, `file`, `group`, `list`, `string-list`, `key-value`.',
+  maxLength: 'Longitud máxima de caracteres permitida.',
+  pattern: 'Expresión regular que debe cumplir el valor.',
+  rows: 'Número de filas visibles del textarea.',
+  minWords: 'Cantidad mínima de palabras.',
+  maxWords: 'Cantidad máxima de palabras.',
+  tokens: 'Marcadores insertables como chips bajo el área (plantillas de mensaje).',
+  from: 'Campo del registro del que se autogenera el slug.',
+  lockAfterCreate: 'Bloquea el campo una vez creado el registro (por defecto: sí).',
+  min: 'Valor mínimo permitido.',
+  max: 'Valor máximo permitido.',
+  step: 'Incremento entre valores permitidos.',
+  decimals: 'Número de decimales mostrados.',
+  currencyFrom: 'Campo del registro del que se toma la moneda (ej. `currency`).',
+  trueLabel: 'Texto que se muestra cuando el valor es verdadero.',
+  falseLabel: 'Texto que se muestra cuando el valor es falso.',
+  source: 'De dónde salen las opciones: `{ resource, view?, params?, … }` (F8 · R6.5).',
+  resource: 'Recurso declarado (`resource.id`): su listado es el de las opciones.',
+  view: 'Vista declarada en `resource.views` (opcional): filtra en el back.',
+  params: 'Valores interpolados para la vista (`{campo}` ← contexto).',
+  labelField: 'Etiqueta por defecto de las filas (si no, `titleField` del recurso).',
+  valueField: 'Valor por defecto de las filas (si no, `keyField` del recurso).',
+  secondaryField: 'Segundo dato a mostrar junto a la etiqueta (ej. "Juan Pérez · DNI 123").',
+  onlyActive: 'Cargar solo registros activos (lo exige además la FK en el back).',
+  accept: 'Tipos aceptados (ej. `image/*`, `image/png,image/jpeg` o `pdf,docx`).',
+  maxSizeMB: 'Tamaño máximo del archivo en megabytes.',
+  aspectRatio: 'Relación de aspecto de la vista previa (ej. `16/9`).',
+  previewSize: 'Tamaño de la vista previa.',
+  formatCurrency: 'Campo del registro del que se toma la moneda (ej. `currency`).',
+  display: 'Presentación del grupo: `card`, `collapsible` o `inline`.',
+  fields: 'Campos de cada item (cualquier tipo, incluso `group` o `list`).',
+  minItems: 'Cantidad mínima de items.',
+  maxItems: 'Cantidad máxima de items.',
+  sortable: 'Si se puede reordenar (por defecto: sí).',
+  positionField: 'Campo donde se guarda el orden dentro de cada item (`position`).',
+  addLabel: 'Etiqueta del botón para agregar un item nuevo.',
+  emptyText: 'Texto que se muestra cuando no hay items.',
+  itemDisplay: 'Cómo se muestra cada item: `card`, `row` o `accordion`.',
+  itemFields: 'Campos de cada item (cualquier tipo, incluso `group` o `list`).',
+  itemTitle: 'Campo del item usado como título cuando está colapsado.',
+  primaryFirst: 'El primer item tiene significado especial (ej. imagen principal).',
+  itemType: 'Tipo permitido de cada item (base.md §9: solo `text`, `url` o `email`).',
+  sort: 'Si la lista se ordena alfabéticamente o por posición.',
+  filter: 'Si el listado permite filtrado por texto.',
+  search: 'Campos buscables en el listado.',
+  filters: 'Filtros declarados para el listado.',
+  listColumns: 'Columnas que se muestran en el listado.',
+  searchable: 'Si el campo es buscable.',
+  filterable: 'Si el campo es filtrable.',
+  sortableItems: 'Si los items de la lista se pueden reordenar.',
+  groupBy: 'Campo por el que agrupar los items.',
+  cardWidth: 'Ancho de cada tarjeta de opción en la grilla (1–12). Por defecto `4` (3 tarjetas por fila en escritorio).',
+  cardCols: 'Cuántas tarjetas mostrar por fila en el punto de ruptura `lg`. Sobrescribe el cálculo automático basado en `cardWidth`.',
+  hintMetric: 'Texto secundario bajo la cifra (estático, va en el schema).',
+  unitChart: 'Sufijo de las cifras del eje («unidades», «S/»).',
+  segments: 'Segmentos de la barra de distribución porcentual.',
+  actions: 'Acciones de navegación por fila.',
+  labelAction: 'Etiqueta de la acción.',
+  icon: 'Icono de la acción.',
+  navigateTo: 'Ruta de destino de la acción.',
+  variant: 'Variante visual: `primary`, `secondary` u `outline`.',
+
+  // ── Widgets de dashboard ──────────────────────────────────────────────
+  widgets: 'Widgets del panel. Se declara en `ResourceSchema.widgets` — no en `fields`, porque un KPI no es un campo.',
+  mobileWidth: 'Ancho en la grilla en mobile (1–12). Por defecto `12` (ancho completo, apilado).',
+  sourceWidget: 'De dónde saca sus datos: `DataSource` o `{ kind: "payload" }`.',
+  hintWidget: 'Texto secundario bajo la cifra (estático, va en el schema).',
+  unitWidget: 'Sufijo de las cifras del eje.',
+} as const;
+
+export type SchemaDescriptionKey = keyof typeof schemaDescriptions;