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

package/src/lib/core/utils/template-interpolator.ts

@@ -0,0 +1,56 @@
+/**
+ * Resuelve una plantilla de texto reemplazando marcadores `{key}` o `{nested.key}`
+ * con los valores presentes en el objeto `data` o en el contexto adicional `extraContext`.
+ *
+ * Si un valor es `null` o `undefined`, se reemplaza por una cadena vacía.
+ * No arroja excepciones ante claves no encontradas ni ante objetos nulos.
+ */
+export function interpolateTemplate(
+  template: string,
+  data: Record<string, unknown> = {},
+  extraContext: Record<string, unknown> = {},
+): string {
+  if (!template) return '';
+
+  return template.replace(/\{([a-zA-Z0-9_.]+)\}/g, (match, key: string) => {
+    const val = getDeepValue(data, key) ?? getDeepValue(extraContext, key);
+    if (val === null || val === undefined) {
+      return '';
+    }
+    return String(val);
+  });
+}
+
+function getDeepValue(obj: Record<string, unknown>, path: string): unknown {
+  if (!obj || typeof obj !== 'object') return undefined;
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export interface ParsedRoute {
+  path: string;
+  queryParams: Record<string, string>;
+}
+
+/**
+ * Descompone una ruta relativa o absoluta en path y queryParams para routerLink.
+ */
+export function parseNavigationUrl(url: string): ParsedRoute {
+  if (!url) return { path: '', queryParams: {} };
+  const [path, queryString] = url.split('?');
+  const queryParams: Record<string, string> = {};
+  if (queryString) {
+    const params = new URLSearchParams(queryString);
+    params.forEach((value, key) => {
+      queryParams[key] = value;
+    });
+  }
+  return { path: path || '', queryParams };
+}

package/src/lib/core/view-navigation/view-navigation.service.spec.ts

@@ -0,0 +1,207 @@
+import { setSchemaCatalog } from '../registry/schema-catalog';
+import { testCatalog } from '../testing/test-catalog';
+
+setSchemaCatalog(testCatalog);
+
+import { Component } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { provideRouter, Router } from '@angular/router';
+import { describe, expect, it, vi } from 'vitest';
+
+import { roleGuard } from '../guards/auth.guard';
+import type { NavigationTarget, SelectionBinding } from '../models/schema.model';
+import { AuthService } from '../services/auth.service';
+import {
+  buildSegments,
+  targetRoutePattern,
+  ViewNavigationService,
+} from './view-navigation.service';
+
+@Component({ standalone: true, template: 'lista' })
+class ListaStub {}
+
+@Component({ standalone: true, template: 'detalle' })
+class DetalleStub {}
+
+/** Target declarado sobre el schema real `orders` (registry front). */
+const target: NavigationTarget = { resource: 'orders', view: 'detail', params: ['key'] };
+
+function rutaBinding(mode: 'route'): SelectionBinding {
+  return { on: 'open', mode, target };
+}
+
+describe('buildSegments (key-only, sin concat de strings)', () => {
+  it('sustituye :key por la clave COMPLETA sin partirla (clave A/B)', () => {
+    expect(buildSegments(['orders', ':key'], 'A/B')).toEqual(['orders', 'A/B']);
+  });
+
+  it('sustituye params en posición media y mantiene literales', () => {
+    expect(buildSegments(['orders', ':key', 'edit'], '7')).toEqual(['orders', '7', 'edit']);
+  });
+
+  it('param distinto de :key ⇒ falla ruido (sin fuente declarada)', () => {
+    expect(() => buildSegments(['orders', ':otro'], 'x')).toThrow('sin fuente declarada');
+  });
+});
+
+describe('targetRoutePattern (misma fuente que el validador)', () => {
+  it('resuelve el patrón de la ruta destino desde la registry', () => {
+    expect(targetRoutePattern({ resource: 'orders', view: 'detail', params: ['key'] })).toEqual([
+      'orders',
+      ':key',
+    ]);
+  });
+
+  it('recurso o vista destino inexistente ⇒ undefined (nada navega)', () => {
+    expect(targetRoutePattern({ resource: 'nope', view: 'detail' })).toBeUndefined();
+    expect(targetRoutePattern({ resource: 'orders', view: 'nope' })).toBeUndefined();
+  });
+});
+
+describe('ViewNavigationService.dispatch', () => {
+  function servicio(auth = { isAuthenticated: () => true, canAccess: () => true }) {
+    TestBed.configureTestingModule({
+      providers: [
+        provideRouter([
+          {
+            path: 'orders',
+            component: ListaStub,
+            data: { resourceId: 'orders' },
+            canActivate: [roleGuard],
+          },
+          {
+            path: 'orders/:key',
+            component: DetalleStub,
+            data: { resourceId: 'orders' },
+            canActivate: [roleGuard],
+          },
+        ]),
+        { provide: AuthService, useValue: auth },
+      ],
+    });
+    return {
+      nav: TestBed.inject(ViewNavigationService),
+      router: TestBed.inject(Router),
+    };
+  }
+
+  it('target declarado ⇒ navega con la clave codificada y el guard corre', async () => {
+    const { nav, router } = servicio();
+    const ok = await nav.dispatch(rutaBinding('route'), {
+      resource: 'orders',
+      key: 'A/B',
+      action: 'open',
+    });
+    expect(ok).toBe(true);
+    // El router serializa :key ⇒ '/' de la clave queda codificado, sin partir
+    expect(router.url).toBe('/orders/A%2FB');
+  });
+
+  it('patrón sin params navega a los segmentos literales', async () => {
+    const { nav, router } = servicio();
+    const ok = await nav.dispatch(
+      { on: 'open', mode: 'route', target: { resource: 'orders', view: 'create' } },
+      { resource: 'orders', key: 'ignorada', action: 'open' },
+    );
+    expect(ok).toBe(true);
+    expect(router.url).toBe('/orders/new');
+  });
+
+  it('acción que no es la declarada ⇒ sin navegación (scope del target)', async () => {
+    const { nav, router } = servicio();
+    const espia = vi.spyOn(router, 'navigate');
+    await nav.dispatch(rutaBinding('route'), { resource: 'orders', key: '1', action: 'select' });
+    expect(espia).not.toHaveBeenCalled();
+    expect(router.url).toBe('/');
+  });
+
+  it('sin binding declarado ⇒ inerte aunque el evento pida mutar', async () => {
+    const { nav, router } = servicio();
+    const espia = vi.spyOn(router, 'navigate');
+    await nav.dispatch(undefined, { resource: 'orders', key: '1', action: 'move' });
+    expect(espia).not.toHaveBeenCalled();
+  });
+
+  it('mode inline/none ⇒ sin navegación (comportamiento local del leaf)', async () => {
+    const { nav, router } = servicio();
+    const espia = vi.spyOn(router, 'navigate');
+    await nav.dispatch(
+      { on: 'open', mode: 'inline' },
+      { resource: 'orders', key: '1', action: 'open' },
+    );
+    await nav.dispatch(
+      { on: 'open', mode: 'none' },
+      { resource: 'orders', key: '1', action: 'open' },
+    );
+    expect(espia).not.toHaveBeenCalled();
+  });
+
+  it('target sin recurso/vista declarado en el registry ⇒ falla ruido, no navega', async () => {
+    const { nav, router } = servicio();
+    const espia = vi.spyOn(router, 'navigate');
+    await expect(
+      nav.dispatch(
+        { on: 'open', mode: 'route', target: { resource: 'no-existe', view: 'x' } },
+        { resource: 'no-existe', key: '1', action: 'open' },
+      ),
+    ).rejects.toThrow('no existe');
+    expect(espia).not.toHaveBeenCalled();
+  });
+
+  it('guard bloquea (sin permiso) ⇒ URL intacta y sin payload del registro', async () => {
+    const { nav, router } = servicio({ isAuthenticated: () => true, canAccess: () => false });
+    const espia = vi.spyOn(router, 'navigate');
+    const ok = await nav.dispatch(rutaBinding('route'), {
+      resource: 'orders',
+      key: 'A/B',
+      action: 'open',
+    });
+    expect(ok).toBe(false);
+    expect(espia).toHaveBeenCalledWith(['/', 'orders', 'A/B']);
+    expect(router.url).toBe('/'); // ningún dato del registro llegó a la URL
+    // guard bloqueado ⇒ el origen NO queda registrado (nada que volver a ver)
+    await nav.back();
+    expect(router.url).toBe('/');
+  });
+});
+
+describe('ViewNavigationService.back (D4)', () => {
+  function servicio() {
+    TestBed.configureTestingModule({
+      providers: [
+        provideRouter([
+          { path: 'orders', component: ListaStub, data: { resourceId: 'orders' } },
+          { path: 'orders/:key', component: DetalleStub, data: { resourceId: 'orders' } },
+        ]),
+        { provide: AuthService, useValue: { isAuthenticated: () => true, canAccess: () => true } },
+      ],
+    });
+    return {
+      nav: TestBed.inject(ViewNavigationService),
+      router: TestBed.inject(Router),
+    };
+  }
+
+  it('con dispatch previo ⇒ vuelve al origen registrado', async () => {
+    const { nav, router } = servicio();
+    await nav.dispatch(rutaBinding('route'), { resource: 'orders', key: '9', action: 'open' });
+    expect(router.url).toBe('/orders/9');
+    await nav.back();
+    expect(router.url).toBe('/');
+  });
+
+  it('returnPath declarado ⇒ navega ahí (gana sobre el origen)', async () => {
+    const { nav, router } = servicio();
+    await nav.dispatch(rutaBinding('route'), { resource: 'orders', key: '9', action: 'open' });
+    await nav.back('orders');
+    expect(router.url).toBe('/orders');
+  });
+
+  it('deep link sin dispatch ⇒ cae a la raíz del recurso de la ruta', async () => {
+    const { nav, router } = servicio();
+    await router.navigate(['/orders/XYZ']); // entrada directa: no hay origen en memoria
+    expect(router.url).toBe('/orders/XYZ');
+    await nav.back();
+    expect(router.url).toBe('/orders'); // raíz declarada del resourceId de la ruta
+  });
+});

package/src/lib/core/view-navigation/view-navigation.service.ts

@@ -0,0 +1,132 @@
+import { Injectable, inject } from '@angular/core';
+import { Router, type ActivatedRouteSnapshot } from '@angular/router';
+
+import type { NavigationTarget, SelectionBinding } from '../models/schema.model';
+import { getSchema } from '../registry/schema-catalog';
+import type { SelectionEvent } from '../../views/composer/view-context';
+
+/**
+ * R9.9 · D4 — Servicio de navegación declarativa.
+ *
+ * Un leaf (hoja) sólo NAVEGA cuando hay `select` declarado; el motor vive
+ * aquí, no en cada hoja. El flujo completo es:
+ *
+ * `ctx.emit/leaf → dispatch → buildSegments(pattern, {key}) →
+ * router.navigate(matriz de comandos) → roleGuard`
+ *
+ * Invariantes:
+ *
+ * - **key-only**: la ÚNICA identidad que viaja es `event.key`. Los comandos
+ *   son una matriz de segmentos (nunca concat de strings) ⇒ el Router
+ *   codifica la clave (una clave `A/B` queda `A%2FB` en la URL) y ningún
+ *   dato del registro llega a la URL.
+ * - **Fail closed**: sin binding, con acción distinta a la declarada o con
+ *   `mode` distinto de `route`, NO hay navegación — simplemente no ocurre.
+ * - **Fail loud**: un target que el registry no declara lanza ruido antes de
+ *   navegar (el validador pre-render ya lo garantiza; esto es defensa en
+ *   profundidad).
+ * - **Guards reales**: `router.navigate` ⇒ `roleGuard` corre igual que en
+ *   cualquier navegación declarada. Si el guard bloquea, no se registra
+ *   origen (no hay «atrás» que una sesión sin permiso deba volver a ver).
+ */
+
+/**
+ * Patrón de segmentos de la ruta destino (`['orders', ':key']`). Usa la
+ * MISMA fuente que el validador (`getSchema`) para que lo validado en build
+ * sea exactamente lo navegado en runtime. Inexistente ⇒ `undefined` (la
+ * defensa en profundidad: el validador pre-render garantiza que esto no
+ * ocurre en schemas válidos).
+ */
+export function targetRoutePattern(target: NavigationTarget): string[] | undefined {
+  const destino = getSchema(target.resource);
+  const vista = destino?.uiViews?.[target.view];
+  if (!destino || !vista) return undefined;
+  const relativa = vista.path ?? '';
+  return [destino.id, ...(relativa === '' ? [] : relativa.split('/'))];
+}
+
+/**
+ * Segmentos de la ruta destino con la clave sustituida. La clave es SIEMPRE
+ * un segmento completo (no se parte en `/`); un param distinto de `:key` no
+ * tiene fuente declarada ⇒ falla ruido, no navega a medias.
+ */
+export function buildSegments(pattern: readonly string[], key: string): string[] {
+  const commands: string[] = [];
+  for (const segmento of pattern) {
+    if (segmento.startsWith(':')) {
+      const nombre = segmento.slice(1);
+      if (nombre !== 'key') {
+        throw new Error(`Destino ':${nombre}' sin fuente declarada en SelectionEvent`);
+      }
+      commands.push(key);
+    } else {
+      commands.push(segmento);
+    }
+  }
+  return commands;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ViewNavigationService {
+  private readonly router = inject(Router);
+
+  /** URL desde la que se navegó la última selección válida (origen del «atrás»). */
+  private origen: string | undefined;
+
+  /**
+   * Transición declarada de un leaf. Inerte si no hay binding, si la acción
+   * no es la declarada o si el modo no es `route`; falla ruido si el target
+   * no existe en el registry.
+   *
+   * @returns `true` si el Router completó la navegación (guards aceptados).
+   */
+  async dispatch(binding: SelectionBinding | undefined, event: SelectionEvent): Promise<boolean> {
+    if (binding === undefined) return false; // sin declaración ⇒ inerte
+    if (binding.on !== event.action) return false; // fuera del scope declarado
+    if (binding.mode !== 'route') return false; // comportamiento local del leaf
+
+    const pattern = targetRoutePattern(binding.target);
+    if (pattern === undefined) {
+      throw new Error(
+        `Destino '${binding.target.resource}/${binding.target.view}' no existe en el registry`,
+      );
+    }
+
+    const urlOrigen = this.router.url;
+    const ok = await this.router.navigate(['/', ...buildSegments(pattern, event.key)]);
+    if (ok) this.origen = urlOrigen;
+    return ok;
+  }
+
+  /**
+   * Forma de volver (D4). Orden: `returnPath` declarado por el leaf ⇒
+   * origen registrado por `dispatch` ⇒ raíz del recurso declarado en la ruta
+   * actual (entrada directa a la URL: no hay origen en memoria). Fallback
+   * final: la raíz de la aplicación.
+   */
+  async back(returnPath?: string): Promise<boolean> {
+    if (returnPath !== undefined) return this.router.navigate([returnPath]);
+
+    if (this.origen !== undefined) {
+      const destino = this.origen;
+      this.origen = undefined;
+      return this.router.navigateByUrl(destino);
+    }
+
+    const recurso = this.recursoActual();
+    return recurso === undefined
+      ? this.router.navigate(['/'])
+      : this.router.navigate(['/', recurso]);
+  }
+
+  /** Primer `resourceId` declarado en el árbol de rutas activo. */
+  private recursoActual(): string | undefined {
+    let nodo: ActivatedRouteSnapshot | null = this.router.routerState.snapshot.root;
+    while (nodo !== null) {
+      const id = nodo.data?.['resourceId'];
+      if (id !== undefined) return String(id);
+      nodo = nodo.firstChild;
+    }
+    return undefined;
+  }
+}

package/src/lib/fields/boolean/boolean.descriptor.ts

@@ -0,0 +1,11 @@
+import type { RenderDescriptor } from '../../core/registry/render-registry';
+
+/** Descriptor del campo `boolean` (R3.3). */
+export const descriptor: RenderDescriptor = {
+  kind: 'field',
+  type: 'boolean',
+  since: '1.0',
+  load: () => import('./boolean').then((module) => module.FieldBoolean),
+  seed: 'boolean',
+  surfaces: ['form', 'display'],
+};

package/src/lib/fields/boolean/boolean.ts

@@ -0,0 +1,40 @@
+import { Component, computed, input } from '@angular/core';
+import { FormField } from '@angular/forms/signals';
+
+import type { BooleanField } from '../../core/models/schema.model';
+import { FieldAria } from '../field-aria';
+import { childTree, type RootTree } from '../field-node';
+
+/**
+ * Interruptor booleano (base.md §5.1) con `trueLabel`/`falseLabel`.
+ * Checkbox nativo + `formField` (se estiliza como switch con `peer-checked`).
+ */
+@Component({
+  selector: 'app-field-boolean',
+  imports: [FieldAria, FormField],
+  template: `
+    <label class="inline-flex cursor-pointer items-center gap-2">
+      <input type="checkbox" class="peer sr-only" [id]="state().name()" [formField]="node()" />
+      <span
+        class="relative h-5 w-9 shrink-0 rounded-full bg-neutral/30 transition-colors peer-checked:bg-primary after:absolute after:top-0.5 after:left-0.5 after:h-4 after:w-4 after:rounded-full after:bg-white after:transition-transform after:content-[''] peer-checked:after:translate-x-4"
+      ></span>
+      <span class="text-sm">{{ currentLabel() }}</span>
+    </label>
+  `,
+})
+export class FieldBoolean {
+  readonly field = input.required<BooleanField>();
+  readonly tree = input.required<RootTree>();
+
+  protected readonly node = computed(() => childTree<boolean>(this.tree(), this.field().key));
+  protected readonly state = computed(() => this.node()());
+
+  protected readonly currentLabel = computed(() => {
+    const on = this.state().value() === true;
+    const field = this.field();
+    if (on) {
+      return field.trueLabel ?? 'Sí';
+    }
+    return field.falseLabel ?? 'No';
+  });
+}

package/src/lib/fields/color/color.descriptor.ts

@@ -0,0 +1,12 @@
+import type { RenderDescriptor } from '../../core/registry/render-registry';
+
+/** Descriptor del campo `color` (selector de color). */
+export const descriptor: RenderDescriptor = {
+  kind: 'field',
+  type: 'color',
+  since: '1.0',
+  load: () => import('./color').then((module) => module.FieldColor),
+  // Nace como cadena (hexadecimal #RRGGBB).
+  seed: 'string',
+  surfaces: ['form', 'display'],
+};

package/src/lib/fields/color/color.ts

@@ -0,0 +1,34 @@
+import { Component, computed, input } from '@angular/core';
+import { FormField } from '@angular/forms/signals';
+
+import type { ColorField } from '../../core/models/schema.model';
+import { FieldAria } from '../field-aria';
+import { childTree, type RootTree } from '../field-node';
+
+/**
+ * Selector de color (`<input type="color">`, base.md §5.1 `color`).
+ *
+ * Devuelve un string hexadecimal `#RRGGBB`. El navegador muestra su propia
+ * paleta de colores; no hay validación de formato extra porque el input
+ * `type="color"` ya garantiza el formato válido.
+ */
+@Component({
+  selector: 'app-field-color',
+  imports: [FieldAria, FormField],
+  template: `
+    <input
+      type="color"
+      class="field-input h-10 w-full p-0 border-0 bg-transparent focus-visible:outline-0 cursor-pointer"
+      [id]="state().name()"
+      [formField]="node()"
+      [title]="field().label"
+    />
+  `,
+})
+export class FieldColor {
+  readonly field = input.required<ColorField>();
+  readonly tree = input.required<RootTree>();
+
+  protected readonly node = computed(() => childTree<string>(this.tree(), this.field().key));
+  protected readonly state = computed(() => this.node()());
+}

package/src/lib/fields/currency/currency.descriptor.ts

@@ -0,0 +1,12 @@
+import type { RenderDescriptor } from '../../core/registry/render-registry';
+
+/** Descriptor del campo `currency` (R3.3). */
+export const descriptor: RenderDescriptor = {
+  kind: 'field',
+  type: 'currency',
+  since: '1.0',
+  load: () => import('./currency').then((module) => module.FieldCurrency),
+  // Nace como `null`: no puede ser `0`, que sería un valor ya cargado.
+  seed: 'number',
+  surfaces: ['form', 'display'],
+};

package/src/lib/fields/currency/currency.ts

@@ -0,0 +1,67 @@
+import { Component, computed, input } from '@angular/core';
+import { FormField } from '@angular/forms/signals';
+
+import type { CurrencyField } from '../../core/models/schema.model';
+import { FieldAria } from '../field-aria';
+import { childTree, type RootTree } from '../field-node';
+
+/**
+ * Número con prefijo de moneda (base.md §5.1). El valor sigue siendo número
+ * puro; el prefijo sale del campo `currencyFrom` (código ISO, ej. `PEN`)
+ * traducido a símbolo con Intl.
+ */
+@Component({
+  selector: 'app-field-currency',
+  imports: [FieldAria, FormField],
+  template: `
+    <div class="flex items-center gap-2">
+      @if (symbol(); as symbol) {
+        <span class="shrink-0 text-sm text-neutral" data-testid="currency-symbol">{{
+          symbol
+        }}</span>
+      }
+      <input
+        type="number"
+        step="any"
+        class="field-input"
+        [id]="state().name()"
+        [formField]="node()"
+        [placeholder]="field().placeholder ?? ''"
+      />
+    </div>
+  `,
+})
+export class FieldCurrency {
+  readonly field = input.required<CurrencyField>();
+  readonly tree = input.required<RootTree>();
+
+  protected readonly node = computed(() => childTree<number>(this.tree(), this.field().key));
+  protected readonly state = computed(() => this.node()());
+
+  /** Código ISO de la moneda desde el campo hermano (`currencyFrom`). */
+  private readonly currencyCode = computed(() => {
+    const from = this.field().currencyFrom;
+    if (!from) {
+      return null;
+    }
+    const value = childTree<unknown>(this.tree(), from)().value();
+    return typeof value === 'string' && value !== '' ? value : null;
+  });
+
+  /** Símbolo localizado (`S/` para PEN); el código crudo si Intl lo rechaza. */
+  protected readonly symbol = computed(() => {
+    const code = this.currencyCode();
+    if (code === null) {
+      return null;
+    }
+    try {
+      const parts = new Intl.NumberFormat('es-PE', {
+        style: 'currency',
+        currency: code,
+      }).formatToParts(0);
+      return parts.find((part) => part.type === 'currency')?.value ?? code;
+    } catch {
+      return code;
+    }
+  });
+}

package/src/lib/fields/date/date.descriptor.ts

@@ -0,0 +1,12 @@
+import type { RenderDescriptor } from '../../core/registry/render-registry';
+
+/** Descriptor del campo `date` (R3.3). */
+export const descriptor: RenderDescriptor = {
+  kind: 'field',
+  type: 'date',
+  since: '1.0',
+  load: () => import('./date').then((module) => module.FieldDate),
+  // Nace como cadena: los textos, fechas, urls, selects y relacionales.
+  seed: 'string',
+  surfaces: ['form', 'display'],
+};

package/src/lib/fields/date/date.ts

@@ -0,0 +1,36 @@
+import { Component, computed, input } from '@angular/core';
+import { FormField } from '@angular/forms/signals';
+
+import type { DateField } from '../../core/models/schema.model';
+import { FieldAria } from '../field-aria';
+import { childTree, type RootTree } from '../field-node';
+
+/**
+ * Selector de fecha ISO `YYYY-MM-DD` (base.md §5.1).
+ *
+ * `min`/`max` del schema se validan con reglas propias en
+ * `pages/form-view/form-schema.ts`: `minDate`/`maxDate` de Signal Forms
+ * exigen valores `Date` y este modelo guarda strings. `FormField` solo setea
+ * los atributos nativos `min`/`max` cuando existen las reglas `min()`/`max()`
+ * (que aplican a números).
+ */
+@Component({
+  selector: 'app-field-date',
+  imports: [FieldAria, FormField],
+  template: `
+    <input
+      type="date"
+      class="field-input"
+      [id]="state().name()"
+      [formField]="node()"
+      [placeholder]="field().placeholder ?? ''"
+    />
+  `,
+})
+export class FieldDate {
+  readonly field = input.required<DateField>();
+  readonly tree = input.required<RootTree>();
+
+  protected readonly node = computed(() => childTree<string>(this.tree(), this.field().key));
+  protected readonly state = computed(() => this.node()());
+}