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

package/src/lib/core/registry/render-registry.spec.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  get,
+  isSupported,
+  register,
+  resolve,
+  unregister,
+  type RenderDescriptor,
+} from './render-registry';
+
+/** Los 21 tipos de campo que la UI sabe dibujar (R3.3). */
+const CAMPOS = [
+  'text',
+  'textarea',
+  'slug',
+  'number',
+  'currency',
+  'boolean',
+  'select',
+  'multiselect',
+  'url',
+  'email',
+  'phone',
+  'date',
+  'time',
+  'readonly-text',
+  'group',
+  'list',
+  'string-list',
+  'key-value',
+  'relation',
+  'image',
+  'file',
+] as const;
+
+/** Componente que sólo puede salir si el registro no resuelve. */
+class SinRenderizador {}
+
+describe('render-registry', () => {
+  it('registra y devuelve el descriptor por (kind, type)', () => {
+    const descriptor: RenderDescriptor = {
+      kind: 'view',
+      type: 'ficha-de-prueba',
+      since: '9.9',
+      load: async () => SinRenderizador,
+    };
+
+    register('view', descriptor);
+    try {
+      expect(get('view', 'ficha-de-prueba')).toBe(descriptor);
+      expect(get('field', 'ficha-de-prueba')).toBeUndefined();
+    } finally {
+      // El catálogo es GLOBAL: sin retirarla, la entrada de prueba contamina
+      // `renderKinds()` y el tripwire de contract.spec.ts flashea según el
+      // orden de ejecución (R7.6).
+      unregister('view', 'ficha-de-prueba');
+    }
+  });
+
+  it('isSupported sólo mira dentro de su kind', () => {
+    expect(isSupported('field', 'texto-que-no-existe')).toBe(false);
+    expect(isSupported('widget', 'text')).toBe(false);
+  });
+
+  it('los 21 tipos de campo están en el catálogo', () => {
+    for (const type of CAMPOS) {
+      expect(isSupported('field', type), `falta el descriptor de "${type}"`).toBe(true);
+    }
+  });
+
+  // Son 21 imports dinámicos de componentes reales: con el suite completo
+  // compitiendo por el hilo, el default de 10 s se queda corto y el gate se
+  // pone rojo por reloj, no por código.
+  it('los 21 tipos de campo resuelven su componente real', async () => {
+    for (const type of CAMPOS) {
+      const component = await resolve('field', type, SinRenderizador);
+      expect(component, `"${type}" resolvió el fallback`).not.toBe(SinRenderizador);
+    }
+  }, 30_000);
+
+  it('devuelve el fallback cuando el tipo no está registrado', async () => {
+    await expect(resolve('field', 'no-existe', SinRenderizador)).resolves.toBe(SinRenderizador);
+  });
+
+  it('el descriptor declara kind, since y carga perezosa', () => {
+    for (const type of CAMPOS) {
+      const descriptor = get('field', type)!;
+      expect(descriptor.kind, type).toBe('field');
+      expect(descriptor.type, type).toBe(type);
+      expect(descriptor.since, type).toBeTruthy();
+      expect(typeof descriptor.load, type).toBe('function');
+      expect(descriptor.surfaces, type).toContain('form');
+    }
+  });
+});

package/src/lib/core/registry/render-registry.ts

@@ -0,0 +1,312 @@
+import {
+  isDevMode,
+  makeEnvironmentProviders,
+  provideAppInitializer,
+  type EnvironmentProviders,
+  type TemplateRef,
+  type Type,
+} from '@angular/core';
+
+import type { RootTree } from '../../fields/field-node';
+import type { SeedKind } from '../../shared/utils/seed';
+import { columnFormatDescriptors } from '../../columns/descriptors';
+import { fieldDescriptors } from '../../fields/descriptors';
+import { layoutDescriptors } from '../../layouts/descriptors';
+import { widgetDescriptors } from '../../widgets/descriptors';
+import { viewDescriptors } from '../../views/descriptors';
+import type { FieldSchema, LayoutMode, ListColumn, WidgetSchema } from '../models/schema.model';
+
+/**
+ * Registro único de render (R3.1 · `doc/plan-refactor-motor.md` §3.1).
+ *
+ * Un solo sitio declara qué componentes sabe dibujar la UI: cada tipo de
+ * campo, widget, acción o vista aporta un `RenderDescriptor` y el registro
+ * lo resuelve por `(kind, type)`. Los hosts dejan de mantener `Set`s de tipos
+ * e imports a mano — **en runtime el registro es la única fuente de verdad**.
+ *
+ * Se carga a scope de módulo y no desde DI: `buildFormSchema()` es una
+ * función pura que consulta el registro sin inyectar nada, así que un
+ * registro llenado únicamente por un provider dejaría esa consulta correr
+ * contra un catálogo vacío. `provideRenderDescriptors()` existe igualmente
+ * como punto de entrada explícito para `app.config.ts` (R3.2).
+ *
+ * Autodescubrimiento (D9-1): se opta por **registro manual** — un manifiesto
+ * con una línea por descriptor — porque `import.meta.glob` no está
+ * implementada por el bundler de producción (`@angular/build:application`
+ * usa esbuild) y la llamada cruda sobreviviría en `dist/`, rompiendo el
+ * arranque. Con Vite sólo en el dev-server y en el runner de tests, además,
+ * el comportamiento habría diferido entre `npm test` y `npm run build`.
+ */
+
+/** Qué clase de cosa se está resolviendo. Identificador único dentro de su `kind`. */
+export type RenderKind = 'field' | 'column-format' | 'widget' | 'action' | 'view' | 'layout';
+export type ComponentRenderKind = Exclude<RenderKind, 'layout'>;
+
+/** Superficies en las que un descriptor puede aparecer. */
+export type RenderSurface = 'form' | 'display' | 'list' | 'filter';
+
+/**
+ * Qué puede describir un `RenderDescriptor`: un campo del formulario, un
+ * widget del dashboard o una columna de listado (R4.3).
+ *
+ * Es el tipo del input `config` del host. Los descriptores sólo comparten
+ * `key` y `label`; lo demás lo decide cada `kind`, y quien necesita el resto
+ * lo castea con su propia mirada (`cfgCampo()`, que es lo que el host ya
+ * hacía antes de que existieran las columnas).
+ */
+export type RenderConfig = FieldSchema | WidgetSchema | ListColumn;
+
+/**
+ * Contexto de render que el host expone por DI (R3.4 · `doc/plan-refactor-motor.md` §3.4).
+ *
+ * Los controles viven en un componente distinto por cada tipo, así que en vez
+ * de repetir cinco inputs en los 20 el host lo provee una sola vez y cada
+ * control lo inyecta si lo necesita — el mismo criterio que ya usaba
+ * `FIELD_ARIA`.
+ *
+ * `tree` viaja en el contexto y no como input suelto porque es **por
+ * instancia**: los hijos de un `group` o de un `list` navegan su subárbol, no
+ * el del padre.
+ *
+ * Vive acá y no en `render-host.ts` porque el contrato de los descriptores
+ * (`RenderExtras`) necesita nombrarlo: el descriptor de un campo compuesto
+ * decide qué se le pasa al componente y eso sólo es escribible conociendo el
+ * tipo. `render-host.ts` lo re-exporta para no mover a sus consumidores.
+ */
+export interface RenderContext {
+  /** Árbol del formulario del nivel de este campo. */
+  tree: RootTree;
+  /** Errores del backend por ruta (`address.street`, `faq[2].answer`). */
+  serverErrors: Record<string, string>;
+  /** Prefijo de ruta de este campo en el registro raíz (`address.`). */
+  pathPrefix: string;
+  /** Si el registro ya existe (lo consume `slug` con `lockAfterCreate`). */
+  exists: boolean;
+  /** Recurso dueño del formulario (lo consume `image` para la firma, §11.2). */
+  resource: string;
+}
+
+/**
+ * Contexto vacío con el que arranca `RenderHost.ctx`.
+ *
+ * Sólo lo alcanza quien renderiza sin contexto — los widgets, que no forman
+ * parte de un formulario. Un campo montado sin `ctx` es un error de
+ * programación y `childTree` lo dice con su propio mensaje, igual que lo
+ * decía el `input.required` anterior.
+ */
+export const RENDER_CONTEXT_VACIO: RenderContext = {
+  tree: undefined as unknown as RootTree,
+  serverErrors: {},
+  pathPrefix: '',
+  exists: false,
+  resource: '',
+};
+
+/**
+ * Segundo argumento de `RenderDescriptor.inputs`.
+ *
+ * Aporta lo que el host conoce y el descriptor no: el contexto de formulario
+ * (sólo para campos), el payload del dato (sólo para widgets) y los dos
+ * templates con los que se componen `group` y `list`.
+ */
+export interface RenderExtras {
+  /** Contexto del nivel; `RENDER_CONTEXT_VACIO` cuando no hay formulario. */
+  ctx: RenderContext;
+  /** Payload del widget (`<app-widget-host [data]>`); `null` en campos. */
+  data: unknown;
+  /** Template del contenido de un `group`. */
+  groupContent?: TemplateRef<unknown>;
+  /** Template de los hijos de un `list`. */
+  childTemplate?: TemplateRef<unknown>;
+}
+
+/**
+ * Declaración de un componente renderizable.
+ *
+ * No lleva `configSchema`: esa cláusula de `refactormotor.md` no existe en
+ * el código y el plan la descartó (D17).
+ */
+export interface RenderDescriptor<C = unknown> {
+  /** Clase de cosa. */
+  kind: ComponentRenderKind;
+  /** Identificador `kebab-case`, único dentro de `kind`. */
+  type: string;
+  /** Versión del contrato en que apareció (`doc/refactormotor.md`). */
+  since: string;
+  /**
+   * Carga perezosa del componente. El registro se resuelve sin arrastrar el
+   * bundle: los descriptores sólo guardan el cierre, no la clase.
+   */
+  load: () => Promise<Type<any>>;
+  /** Superficies en las que se usa. Sólo lo que se pueda evidenciar en el código. */
+  surfaces?: RenderSurface[];
+  /** Valores por defecto de la configuración del descriptor. */
+  defaults?: Partial<C>;
+  /**
+   * Forma del valor inicial que siembra este campo en el modelo del
+   * formulario (D32 · R3.8).
+   *
+   * **Dato, no función**: un nombre resuelto por `shared/utils/seed.ts`, no
+   * una clausura. Así el descriptor sigue siendo puro —`kind`, `type`,
+   * `load`, `surfaces`, `seed`— y `seed.ts` es el único dueño de recorrer
+   * un árbol de campos. La alternativa (`seed: (cfg) => …`) obligaría a que
+   * `group` importara `seedFields`, lo que cerraría un ciclo
+   * registro → manifiesto → descriptor → `seed` → registro.
+   *
+   * Sólo los campos lo declaran. **Obligatorio para `kind: 'field'`** — lo
+   * vigila `core/registry/contract.spec.ts`, porque la exhaustividad de una
+   * unión de strings no puede imponerse en tiempo de compilación.
+   */
+  seed?: SeedKind;
+  /**
+   * Cableado del componente: qué inputs recibe y con qué valor.
+   *
+   * Es **la** pieza que mantiene el host genérico: sin esto el motor tendría
+   * que saber que `metric-card` recibe `label/value/hint` y que `group`
+   * necesita además el template de sus hijos, y «añadir un tipo» volvería a
+   * tocar `render-host.ts` (R3.8). Cada descriptor declara el suyo y el host
+   * sólo hace `ngComponentOutletInputs = descriptor.inputs(config, extras)`.
+   *
+   * No es obligatorio: el 80 % de los tipos comparten la forma estándar de su
+   * `kind` — `{field, tree}` en campos, `{widget, data}` en widgets — y para
+   * ellos el host aplica esa forma por defecto. Se declara sólo cuando el
+   * componente se desvía de ella.
+   */
+  inputs?: (config: C, extras: RenderExtras) => Record<string, unknown>;
+}
+
+/** Declaración de un layout manejado por el host de formularios. */
+export interface LayoutDescriptor {
+  kind: 'layout';
+  type: LayoutMode;
+  since: string;
+}
+
+/** Catálogo en memoria: `kind:type` → descriptor. */
+const RENDERERS = new Map<string, RenderDescriptor>();
+const LAYOUTS = new Map<string, LayoutDescriptor>();
+
+function keyOf(kind: RenderKind, type: string): string {
+  return `${kind}:${type}`;
+}
+
+/**
+ * Registra un descriptor. Idempotente por clave: volver a registrar el mismo
+ * `(kind, type)` lo sobrescribe, lo que permite que un módulo se recargue en
+ * desarrollo sin duplicar entradas.
+ */
+export function register(kind: 'layout', descriptor: LayoutDescriptor): void;
+export function register(kind: ComponentRenderKind, descriptor: RenderDescriptor): void;
+export function register(kind: RenderKind, descriptor: RenderDescriptor | LayoutDescriptor): void {
+  if (kind === 'layout') {
+    if (!('kind' in descriptor) || descriptor.kind !== 'layout') {
+      throw new Error(`El descriptor de layout "${descriptor.type}" no declara kind: "layout".`);
+    }
+    LAYOUTS.set(descriptor.type, descriptor);
+    return;
+  }
+  if (descriptor.kind === 'layout') {
+    throw new Error(
+      `El descriptor de layout "${descriptor.type}" no puede registrarse como ${kind}.`,
+    );
+  }
+  RENDERERS.set(keyOf(kind, descriptor.type), descriptor);
+}
+
+/**
+ * Quita un descriptor (R7.6). Simétrico a `register`: los specs que
+ * registran entradas de prueba deben retirarlas, o el catálogo global queda
+ * contaminado para cualquier otro spec que lea `renderKinds()` (flaky por
+ * orden de ejecución).
+ */
+export function unregister(kind: RenderKind, type: string): void {
+  if (kind === 'layout') {
+    LAYOUTS.delete(type);
+  } else {
+    RENDERERS.delete(keyOf(kind, type));
+  }
+}
+
+/** Descriptor declarado para `(kind, type)`, o `undefined` si nadie lo registró. */
+export function get(kind: ComponentRenderKind, type: string): RenderDescriptor | undefined {
+  return RENDERERS.get(keyOf(kind, type));
+}
+
+/** ¿La UI sabe dibujar este `(kind, type)`? Reemplaza a los `Set`s de los hosts. */
+export function isSupported(kind: RenderKind, type: string): boolean {
+  return kind === 'layout' ? LAYOUTS.has(type) : RENDERERS.has(keyOf(kind, type));
+}
+
+/**
+ * Componente para `(kind, type)`, o `fallback` si el tipo no está en el
+ * catálogo.
+ *
+ * Es **asíncrona** porque `load()` importa el componente bajo demanda; el
+ * `fallback` es síncrono y sólo se usa cuando no hay descriptor. Un fallo de
+ * `load()` NO se traga: propagarlo es lo que hace visible un descriptor mal
+ * escrito, y la política «nunca pantalla rota» la resuelve el llamante con el
+ * `fallback` que ya recibe.
+ */
+export async function resolve<C = unknown>(
+  kind: ComponentRenderKind,
+  type: string,
+  fallback: Type<C>,
+): Promise<Type<C>> {
+  const descriptor = get(kind, type);
+  if (!descriptor) return fallback;
+  return (await descriptor.load()) as Type<C>;
+}
+
+// Catálogo a scope de módulo: se registra al importar, sin esperar a DI.
+for (const descriptor of [
+  ...fieldDescriptors,
+  ...widgetDescriptors,
+  ...columnFormatDescriptors,
+  ...viewDescriptors,
+  ...layoutDescriptors,
+]) {
+  if (descriptor.kind === 'layout') {
+    register('layout', descriptor);
+  } else {
+    register(descriptor.kind, descriptor);
+  }
+}
+
+/**
+ * Punto de entrada para `app.config.ts` (R3.2).
+ *
+ * El catálogo ya quedó cargado al importar este módulo; el provider sirve
+ * para que el arranque sea explícito y para avisar en desarrollo si el
+ * manifiesto vino vacío — que es exactamente lo que pasaría si alguien
+ * borra una línea del manifiesto sin reemplazarla.
+ */
+export function provideRenderDescriptors(): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    provideAppInitializer(() => {
+      if (isDevMode() && RENDERERS.size === 0 && LAYOUTS.size === 0) {
+        console.warn('[render-registry] el catálogo de descriptores vino vacío');
+      }
+    }),
+  ]);
+}
+
+/** Cuántos descriptores hay registrados. Sólo para comprobaciones y tests. */
+export function renderDescriptorCount(): number {
+  return RENDERERS.size + LAYOUTS.size;
+}
+
+/**
+ * `kind`s que hoy tienen al menos un descriptor.
+ *
+ * Existe para el test de exhaustividad (R3.7): él recorre los schemas de los
+ * `kind`s que tienen registro y **falla** si aparece un `kind` con descriptor
+ * que nadie recorre — de lo contrario «tener registro» y «estar cubierto»
+ * serían dos afirmaciones distintas que nadie reconcilia.
+ */
+export function renderKinds(): RenderKind[] {
+  const kinds = new Set<RenderKind>([...RENDERERS.values()].map((descriptor) => descriptor.kind));
+  if (LAYOUTS.size > 0) {
+    kinds.add('layout');
+  }
+  return [...kinds];
+}

package/src/lib/core/registry/schema-catalog.ts

@@ -0,0 +1,156 @@
+import {
+  EnvironmentProviders,
+  InjectionToken,
+  Provider,
+  inject,
+  provideAppInitializer,
+} from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+
+import { apiErrorInterceptor } from '../interceptors/api-error.interceptor';
+import { AuthService } from '../services/auth.service';
+import { ConfigService } from '../services/config.service';
+import type { AuthSchema, ResourceSchema, ResponseUnwrap } from '../models/schema.model';
+import type { FirebaseAuthAdapter } from '../adapters/firebase-auth.adapter';
+import { API_DRIVER, DEFAULT_RESPONSE_UNWRAP, FIREBASE_AUTH_ADAPTER, VALUE_SOURCES } from '../tokens';
+import type { ValueSources } from '../tokens';
+
+
+/**
+ * Catálogo de schemas del consumidor (F1 · G-F2).
+ *
+ * Antes de la extracción el motor importaba `getSchema` del
+ * `schemas/registry.ts` de la app. Ese acoplamiento se rompe con un
+ * catálogo a nivel módulo: el consumidor llama
+ * `provideGasAdmin({ schemas, auth })` en su `app.config.ts` y el motor
+ * resuelve en runtime con la MISMA semántica que antes (un solo catálogo
+ * por aplicación, seteado una vez en el bootstrap).
+ *
+ * `provideGasAdmin` se ejecuta al evaluarse el `app.config` (módulo), y
+ * todo uso del catálogo (guards, componentes, rutas dinámicas) ocurre en
+ * runtime posterior al bootstrap — el orden es determinístico.
+ */
+
+let catalog: readonly ResourceSchema[] = [];
+let authCatalog: AuthSchema | undefined;
+
+/** Fija el catálogo (uso interno de `provideGasAdmin`; testable directo). */
+export function setSchemaCatalog(
+  schemas: readonly ResourceSchema[],
+  auth?: AuthSchema,
+): void {
+  catalog = schemas;
+  authCatalog = auth;
+}
+
+/** Busca un schema por `id`; `undefined` si no existe. */
+export function getSchema(id: string): ResourceSchema | undefined {
+  return catalog.find((schema) => schema.id === id);
+}
+
+/** Catálogo completo en orden (menú lateral). */
+export function allSchemas(): readonly ResourceSchema[] {
+  return catalog;
+}
+
+/** Declaración de la pantalla de login; `undefined` sin `auth` en config. */
+export function getAuth(): AuthSchema | undefined {
+  return authCatalog;
+}
+
+/** Token DI del catálogo (para inyectarlo donde un `inject()` es posible). */
+export const GAS_SCHEMAS = new InjectionToken<readonly ResourceSchema[]>(
+  'gas.admin.schemas',
+);
+
+/** Configuración del motor. */
+export interface GasAdminConfig {
+  /** Catálogo ordenado de recursos (menú + rutas + resolución `getSchema`). */
+  schemas: readonly ResourceSchema[];
+  /** Declaración de la pantalla de login (opcional: sin ella, sin `/login`). */
+  auth?: AuthSchema;
+  /**
+   * Driver de transporte HTTP.
+   *
+   * - `'gas'` (default): tunnel `POST text/plain` con envelope Apps Script.
+   * - `'rest'`: verbos HTTP reales con `Authorization: Bearer` en cabeceras.
+   *
+   * Sin declaración el motor usa `'gas'` — cero impacto en consumidores existentes.
+   */
+  driver?: 'gas' | 'rest';
+  /**
+   * Fuentes de contexto que el consumidor aporta para marcadores en paths de
+   * endpoints: `{ <fuente> }` / `{ <fuente>.<ruta> }` se resuelven en el
+   * momento de la petición contra este registro más las fuentes construidas
+   * `auth` (sesión) y `config` (config global).
+   *
+   * Opcional: sin él, sólo existen `auth` y `config`. Declararlo no cambia
+   * ningún path que no lleve marcadores — cero impacto en schemas existentes.
+   */
+  valueSources?: ValueSources;
+  /**
+   * Unwrap de respuesta global por defecto. Se fusiona con la declaración
+   * `endpoint.responseUnwrap` de cada recurso (la del recurso tiene prioridad
+   * en claves declaradas). Opcional: sin él, sólo aplica lo declarado por
+   * recurso — cero impacto en schemas existentes (R2).
+   */
+  defaultResponseUnwrap?: ResponseUnwrap;
+}
+
+/**
+ * Wiring completo del motor: catálogo + HTTP con el interceptor de
+ * errores del envelope + loaders de config y sesión en el bootstrap
+ * (antes en el `app.config` del consumidor).
+ *
+ * El consumidor conserva `provideRouter` y `{ provide: API_URL, ... }`
+ * (su environment decide la URL del Web App).
+ */
+export function provideGasAdmin(
+  config: GasAdminConfig,
+): (Provider | EnvironmentProviders)[] {
+  setSchemaCatalog(config.schemas, config.auth);
+  // Singletons de configuración: los declara el catálogo, no el servicio.
+  // Un singleton nuevo con `endpoint.get` se carga solo.
+  const configEndpoints = () =>
+    config.schemas.flatMap((schema) =>
+      schema.kind === 'singleton' && schema.endpoint?.get
+        ? [{ get: schema.endpoint.get }]
+        : [],
+    );
+  return [
+    { provide: GAS_SCHEMAS, useValue: config.schemas },
+    // Driver de transporte: 'gas' por defecto para cero breaking changes.
+    { provide: API_DRIVER, useValue: config.driver ?? 'gas' },
+    // Fuentes de contexto del consumidor: vacío por defecto ⇒ sólo `auth` y
+    // `config`, que el motor arma por su cuenta en cada petición.
+    { provide: VALUE_SOURCES, useValue: config.valueSources ?? {} },
+    // Unwrap global por defecto: undefined si no se declara ⇒ sólo aplica lo
+    // declarado por recurso (R2, cero impacto en schemas existentes).
+    { provide: DEFAULT_RESPONSE_UNWRAP, useValue: config.defaultResponseUnwrap },
+    // Sin `authInterceptor` en modo GAS: el token viaja en el cuerpo del envelope
+    // (baseapi §2.3, criterio 11: ninguna cabecera custom).
+    // En modo REST el token viaja como cabecera `Authorization` dentro de ApiService.
+    provideHttpClient(withInterceptors([apiErrorInterceptor])),
+    // Carga de config en bootstrap (fuera del constructor del servicio):
+    // un singleton que falle no rompe el arranque.
+    provideAppInitializer(() => inject(ConfigService).load(configEndpoints())),
+    // Sesión (R2.12): revalida contra `/auth/me` el token que restauró el
+    // AuthService de `sessionStorage`. Corre ANTES del primer guard.
+    provideAppInitializer(() => inject(AuthService).restore()),
+  ];
+}
+
+/**
+ * Registra una implementación concreta de FirebaseAuthAdapter en el árbol de DI.
+ * Usar junto con provideGasAdmin() en app.config.ts al configurar proveedores federados
+ * (como 'google') o autenticación por Firebase.
+ *
+ * @example
+ * // app.config.ts
+ * provideGasAdmin({ schemas, auth }),
+ * provideFirebaseAdapter(new MyFirebaseAuthAdapter(getAuth(firebaseApp))),
+ */
+export function provideFirebaseAdapter(adapter: FirebaseAuthAdapter): Provider {
+  return { provide: FIREBASE_AUTH_ADAPTER, useValue: adapter };
+}
+