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

package/src/lib/pages/drawer-form/drawer-form.ts

@@ -0,0 +1,228 @@
+import {
+  Component,
+  DestroyRef,
+  Injector,
+  OnInit,
+  computed,
+  inject,
+  input,
+  output,
+  signal,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { form, submit } from '@angular/forms/signals';
+import { firstValueFrom } from 'rxjs';
+
+import type { FieldSchema, ResourceSchema } from '../../core/models/schema.model';
+import { ApiService } from '../../core/services/api.service';
+import { ErrorMapperService } from '../../core/services/error-mapper.service';
+import { NotificationService } from '../../core/services/notification.service';
+import { FieldHost } from '../../fields/field-host/field-host';
+import { childTree, type RootTree } from '../../fields/field-node';
+import { Button } from '../../shared/components/button/button';
+import { Drawer, type DrawerSize } from '../../shared/components/drawer/drawer';
+import { Skeleton } from '../../shared/components/skeleton/skeleton';
+import { buildFormSchema } from '../form-view/form-schema';
+import { buildPayload, seedModel } from '../form-view/form-model';
+
+/**
+ * Formulario dentro de un drawer (plan 6.4/6.5, guía §5).
+ *
+ * Es deliberadamente más chico que `form-view`: sin pestañas, sin secciones,
+ * sin borrador y sin resumen de errores. Sirve para abrir 1–3 campos sin
+ * perder el contexto de la pantalla de la que vino el usuario, y para crear
+ * un registro desde el dropdown de una relación.
+ *
+ * Componente controlado: `open` entra por `input()`, y el padre cierra con
+ * `close`/`saved`. Nada navega por su cuenta.
+ */
+@Component({
+  selector: 'app-drawer-form',
+  imports: [Button, Drawer, FieldHost, Skeleton],
+  template: `
+    <app-drawer [open]="open()" [title]="drawerTitle()" [size]="size()" (close)="close.emit()">
+      @if (status() === 'loading') {
+        <app-skeleton [lines]="4" />
+      } @else if (status() === 'error') {
+        <p role="alert" class="rounded-lg bg-danger/10 px-3 py-2 text-sm text-danger">
+          {{ loadError() }}
+        </p>
+      } @else if (tree(); as formTree) {
+        @if (generalError()) {
+          <p
+            role="alert"
+            class="mb-4 rounded-lg bg-danger/10 px-3 py-2 text-sm text-danger"
+            data-drawer-error
+          >
+            {{ generalError() }}
+          </p>
+        }
+        @for (field of visibleFields(); track field.key) {
+          <div class="mb-4">
+            <app-field-host
+              [field]="field"
+              [tree]="formTree"
+              [exists]="mode() === 'edit'"
+              [serverErrors]="fieldErrors()"
+              [resource]="schema().id"
+            />
+          </div>
+        }
+      }
+
+      <div drawer-actions class="flex justify-end gap-2">
+        <button app-button variant="outline" type="button" (click)="close.emit()">Cancelar</button>
+        <button app-button type="button" [loading]="saving()" (click)="save()">Guardar</button>
+      </div>
+    </app-drawer>
+  `,
+})
+export class DrawerForm implements OnInit {
+  readonly open = input(false);
+  readonly schema = input.required<ResourceSchema>();
+  /** Subconjunto de campos a mostrar. Por defecto, todos los del schema. */
+  readonly fields = input<readonly FieldSchema[] | undefined>(undefined);
+  readonly mode = input<'create' | 'edit'>('create');
+  readonly recordKey = input<string | null>(null);
+  readonly title = input<string | null>(null);
+  readonly size = input<DrawerSize>('md');
+
+  /** Registro creado o actualizado, listo para que el padre refresque. */
+  readonly saved = output<Record<string, unknown>>();
+  readonly close = output<void>();
+
+  private readonly api = inject(ApiService);
+  private readonly notifications = inject(NotificationService);
+  private readonly errorMapper = inject(ErrorMapperService);
+  private readonly injector = inject(Injector);
+  private readonly destroyRef = inject(DestroyRef);
+
+  private readonly tree = signal<RootTree | null>(null);
+  private readonly status = signal<'idle' | 'loading' | 'ready' | 'error'>('idle');
+  private readonly saving = signal(false);
+  private readonly generalError = signal('');
+  private readonly fieldErrors = signal<Record<string, string>>({});
+  private readonly loadError = signal('');
+
+  readonly visibleFields = computed<readonly FieldSchema[]>(
+    () => this.fields() ?? this.schema().fields,
+  );
+
+  readonly drawerTitle = computed(() => {
+    if (this.title() !== null) {
+      return this.title() as string;
+    }
+    const label = this.schema().label;
+    return this.mode() === 'create' ? `Crear ${label}` : `Editar ${label}`;
+  });
+
+  ngOnInit(): void {
+    // Se construye al montar, NO en un `effect`: `form()` crea un effect
+    // interno y no puede correr dentro de otro (NG0602). Los padres montan
+    // este componente bajo un `@if` y fijan los inputs, así que no hace
+    // falta reaccionar a cambios posteriores.
+    this.build();
+  }
+
+  private build(): void {
+    const schema = this.schema();
+    const recordKey = this.recordKey();
+    const schemaFn = buildFormSchema(schema, this.api, recordKey ?? undefined);
+    const tree = form(signal(seedModel(schema)), schemaFn, { injector: this.injector });
+
+    if (this.mode() === 'create' || recordKey === null) {
+      this.tree.set(tree);
+      this.status.set('ready');
+      return;
+    }
+
+    // Edición: el valor se pisa con el registro, dejando los defaults de
+    // los campos que el backend no devuelve.
+    this.status.set('loading');
+    this.api
+      .get<Record<string, unknown>>(schema.endpoint, recordKey)
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe({
+        next: (record) => {
+          tree().value.set({ ...seedModel(schema), ...record });
+          this.tree.set(tree);
+          this.status.set('ready');
+        },
+        error: (error: unknown) => {
+          this.loadError.set(this.errorMapper.messageOf(error));
+          this.status.set('error');
+        },
+      });
+  }
+
+  async save(): Promise<void> {
+    const tree = this.tree();
+    const schema = this.schema();
+    if (tree === null || this.saving()) {
+      return;
+    }
+    this.saving.set(true);
+    this.generalError.set('');
+    this.fieldErrors.set({});
+    try {
+      const ok = await submit(tree, {
+        // `null` = sin errores propios: los del backend se pintan aparte.
+        action: async () => {
+          await this.persist(tree, schema);
+          return null;
+        },
+        onInvalid: () => this.markTouched(tree),
+      });
+      if (!ok || Object.keys(this.fieldErrors()).length > 0 || this.generalError() !== '') {
+        this.markTouched(tree);
+      }
+    } finally {
+      this.saving.set(false);
+    }
+  }
+
+  /**
+   * Marca como tocado lo que se está mostrando. Se recorre por campo y no
+   * desde la raíz: `FieldTree<Record<string, unknown>>` se indexa con una
+   * clave dinámica y `markAsTouched` no compila ahí (`childTree` centraliza
+   * ese cast). Baja a todos los descendientes, así un `group` queda cubierto.
+   */
+  private markTouched(tree: RootTree): void {
+    for (const field of this.visibleFields()) {
+      childTree<unknown>(tree, field.key)().markAsTouched();
+    }
+  }
+
+  /** create/update; nunca lanza (los errores quedan en las señales). */
+  private async persist(tree: RootTree, schema: ResourceSchema): Promise<void> {
+    const payload = buildPayload(schema, tree);
+    try {
+      if (this.mode() === 'create') {
+        const created = await firstValueFrom(
+          this.api.create<Record<string, unknown>>(schema.endpoint, payload),
+        );
+        this.notifications.success('Registro creado.');
+        this.saved.emit(created ?? {});
+        this.close.emit();
+        return;
+      }
+      const updated = await firstValueFrom(
+        this.api.update<Record<string, unknown>>(
+          schema.endpoint,
+          this.recordKey() ?? undefined,
+          payload,
+        ),
+      );
+      this.notifications.success('Registro guardado.');
+      this.saved.emit(updated ?? {});
+      this.close.emit();
+    } catch (error: unknown) {
+      const mapped = this.errorMapper.map(error);
+      this.fieldErrors.set(mapped.fields);
+      const withoutFields = Object.keys(mapped.fields).length === 0;
+      this.generalError.set(
+        mapped.general ?? (withoutFields ? this.errorMapper.messageOf(error) : ''),
+      );
+    }
+  }
+}

package/src/lib/pages/form-view/form-model.ts

@@ -0,0 +1,88 @@
+import type { FieldSchema, ResourceSchema } from '../../core/models/schema.model';
+import { childTree, itemTree, listTree, type RootTree } from '../../fields/field-node';
+import { seedFields } from '../../shared/utils/seed';
+
+/**
+ * Modelo y payload del formulario genérico (Fase 10, ampliado en Fase 11).
+ *
+ * - `seedModel` siembra un valor inicial para CADA campo declarado en el
+ *   schema antes de crear el formulario: el árbol de Signal Forms replica la
+ *   forma del modelo, así que un campo ausente no tendría estado (ni valor
+ *   que enviar). La siembra vive en `shared/utils/seed.ts`.
+ * - `buildPayload` decide qué viaja al backend (base.md §10): solo las claves
+ *   declaradas en el schema, sin los ocultos y sin `positionField` raíz.
+ */
+
+/** Valores por defecto del schema, en el mismo orden/shape que el JSON. */
+export function seedModel(schema: ResourceSchema): Record<string, unknown> {
+  return seedFields(schema.fields);
+}
+
+/**
+ * Payload del guardado: whitelist de `schema.fields`.
+ *
+ * - Los campos ocultos (`visibleWhen` falso) no se muestran ni se envían
+ *   (base.md §10): usar `hidden()` garantiza que no aparezcan acá aunque
+ *   tengan valor sembrado — también dentro de `group` y de los ítems de una
+ *   `list` (recursivo).
+ * - `positionField` del recurso se excluye aunque esté declarado: el orden
+ *   del listado lo gestiona el backend (api.md R3, nunca se expone). El
+ *   `positionField` de los ÍTEMS de una lista sí viaja: el orden local lo
+ *   calcula el front (base.md §8).
+ * - Los tipos que la UI todavía no edita SÍ viajan: sus valores llegan del
+ *   registro leído, así que reenviarlos evita pisarlos.
+ */
+export function buildPayload(schema: ResourceSchema, root: RootTree): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  collectPayload(root, schema.fields, payload, schema.positionField);
+  return payload;
+}
+
+function collectPayload(
+  tree: RootTree,
+  fields: readonly FieldSchema[],
+  payload: Record<string, unknown>,
+  excludedKey: string | undefined,
+): void {
+  for (const field of fields) {
+    if (excludedKey !== undefined && field.key === excludedKey) {
+      continue;
+    }
+    const state = childTree<unknown>(tree, field.key)();
+    if (state.hidden()) {
+      continue;
+    }
+    if (field.type === 'group') {
+      const nested: Record<string, unknown> = {};
+      collectPayload(
+        childTree<Record<string, unknown>>(tree, field.key),
+        field.fields,
+        nested,
+        undefined,
+      );
+      payload[field.key] = nested;
+      continue;
+    }
+    if (field.type === 'list') {
+      const items = listTree(tree, field.key);
+      const raw = (state.value() as Record<string, unknown>[] | null) ?? [];
+      const list: unknown[] = [];
+      for (let index = 0; index < raw.length; index++) {
+        const nested: Record<string, unknown> = {};
+        collectPayload(itemTree(items, index), field.itemFields, nested, undefined);
+        // El orden de los ítems viaja con el registro padre (base.md §8): el
+        // `positionField` no es un campo editable, por eso no está en
+        // `itemFields` y hay que leerlo del modelo crudo.
+        const positionKey = field.positionField;
+        const position = positionKey !== undefined ? raw[index]?.[positionKey] : undefined;
+        if (positionKey !== undefined && position !== undefined) {
+          nested[positionKey] = position;
+        }
+        list.push(nested);
+      }
+      payload[field.key] = list;
+      continue;
+    }
+    payload[field.key] = state.value();
+  }
+}

package/src/lib/pages/form-view/form-schema.ts

@@ -0,0 +1,255 @@
+import {
+  applyEach,
+  disabled,
+  hidden,
+  readonly as readonlyRule,
+  type SchemaFn,
+  type SchemaPathTree,
+} from '@angular/forms/signals';
+
+import type { FieldSchema, ResourceSchema } from '../../core/models/schema.model';
+import type { ApiService } from '../../core/services/api.service';
+import {
+  FIELD_VALIDATORS,
+  registerEmailRule,
+  registerUrlRule,
+  type FieldPath,
+  type ValidatorContext,
+} from '../../core/registry/field-validators';
+import { isSupported } from '../../core/registry/render-registry';
+import { evaluateCondition } from '../../shared/utils/condition-evaluator';
+
+/** Ruta de un hijo bajo un path (raíz, grupo o ítem). */
+type ChildPath<V> = FieldPath<V>;
+/** Ruta raíz del formulario. */
+type RootPath = SchemaPathTree<Record<string, unknown>>;
+/** Ruta de un campo lista (para `applyEach`). */
+type ListPath<V> = FieldPath<V>;
+
+/**
+ * Reglas del formulario desde el schema (base.md §4, §6, §9, §10).
+ *
+ * Hay DOS clases de reglas y viven en sitios distintos:
+ *
+ * 1. **Ciclo de vida** — `visibleWhen`, `readonlyOn`, `hiddenOn`, `dependsOn`:
+ *   decides si el campo se toca, se ve o se manda. Vive acá, con la
+ *   estructura del formulario.
+ * 2. **Validadores** — obligatoriedad, longitud, patrón, rangos, únicos…:
+ *   vive en `core/registry/field-validators.ts` (F7 + B11), con los MISMOS
+ *   nombres que el back. Este módulo sólo RECORRE ese registro por cada
+ *   campo: añadir un validador es una entrada allá, no un `case` acá.
+ *
+ * El schema de Signal Forms recibe el path RAÍZ; las reglas se atan a la ruta
+ * dinámica de cada campo. El barrido es **recursivo** — un `group` registra
+ * las reglas de sus hijos bajo su propia ruta y un `list` registra las de
+ * cada ítem con `applyEach`, de modo que las reglas corran también para los
+ * ítems que se agregan después.
+ *
+ * Solo se generan reglas para los tipos que la UI sabe editar (`isSupported('field', …)`):
+ * un campo invisible con `required` bloquearía el guardado para siempre.
+ *
+ * `api` y `excludeKey` alimentan la validación `unique`: se consulta el
+ * listado del recurso y se descarta el propio registro (la clave del registro
+ * en edición, tomada de la ruta).
+ */
+export function buildFormSchema(
+  schema: ResourceSchema,
+  api: ApiService,
+  excludeKey?: string,
+): SchemaFn<Record<string, unknown>> {
+  return (root) => {
+    applyRulesToFields(
+      { schema, api, excludeKey, root, container: root, siblings: schema.fields },
+      schema.fields,
+    );
+  };
+}
+
+/**
+ * Ámbito de registro de reglas.
+ *
+ * - `root` es siempre la raíz del formulario (referencia para condiciones que
+ *   nombran un campo de la raíz, base.md §4: «mismo nivel o registro raíz»).
+ * - `container` es el nodo del que cuelgan las rutas hijas: la raíz, un
+ *   `group` o un ítem de un `list`.
+ * - `siblings` son los campos declarados en `container`: si una condición
+ *   nombra a uno de ellos se evalúa contra el contenedor, si no, contra la
+ *   raíz.
+ */
+interface RuleScope {
+  schema: ResourceSchema;
+  api: ApiService;
+  excludeKey: string | undefined;
+  root: RootPath;
+  container: object;
+  siblings: readonly FieldSchema[];
+}
+
+function applyRulesToFields(scope: RuleScope, fields: readonly FieldSchema[]): void {
+  for (const field of fields) {
+    if (!isSupported('field', field.type)) {
+      continue;
+    }
+    applyRulesToField(scope, field, pathAt<unknown>(scope.container, field.key));
+  }
+}
+
+function applyRulesToField(scope: RuleScope, field: FieldSchema, path: ChildPath<unknown>): void {
+  applyLifecycleRules(scope, field, path);
+
+  // Validadores: el registro manda. Cada entrada decide si el campo la pide
+  // y ata su regla a ESTA ruta (F7: sin `if` por regla en este módulo).
+  const ctx: ValidatorContext = {
+    path,
+    field,
+    schema: scope.schema,
+    api: scope.api,
+    excludeKey: scope.excludeKey,
+  };
+  for (const entry of FIELD_VALIDATORS) {
+    if (entry.declares(ctx)) {
+      entry.register(ctx);
+    }
+  }
+
+  // Estructura (no es validador): los HIJOS se registran bajo su propia
+  // ruta, recursivamente, para que las reglas corran también en los ítems
+  // que el usuario agrega después.
+  switch (field.type) {
+    case 'group': {
+      applyRulesToFields({ ...scope, container: path, siblings: field.fields }, field.fields);
+      break;
+    }
+    case 'list': {
+      applyEach(path as unknown as ListPath<Record<string, unknown>[]>, (item) =>
+        applyRulesToFields(
+          { ...scope, container: item as object, siblings: field.itemFields },
+          field.itemFields,
+        ),
+      );
+      break;
+    }
+    case 'string-list': {
+      applyEach(path as unknown as ListPath<string[]>, (item) =>
+        applyStringItemRules(item as ChildPath<string>, field.itemType),
+      );
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+/**
+ * ¿Aplica `mode` en ESTE contexto de formulario?
+ *
+ * Lo comparten `readonlyOn` y `hiddenOn`: `always` vale en todos los modos,
+ * `create` sólo en alta y `update` sólo en edición. El modo se detecta por
+ * `scope.excludeKey !== undefined`, que es la señal que ya usaba `readonlyOn`
+ * (form-view define `mode` a partir de la misma condición).
+ */
+function modeAppliesTo(mode: 'create' | 'update' | 'always', isEdit: boolean): boolean {
+  return mode === 'always' || (mode === 'update' && isEdit) || (mode === 'create' && !isEdit);
+}
+
+/**
+ * Ciclo de vida del campo: visibilidad, edición y dependencias (base.md §4).
+ *
+ * Aquí NO hay validadores — la obligatoriedad vive en el registro.
+ * `hidden` además excluye el campo de `dirty`, `invalid` y del payload
+ * (base.md §10 «Campos ocultos»), y `disabled` lo deja fuera de la
+ * validación, así un `required` en el hijo no bloquea el guardado mientras
+ * no haya nada que elegir.
+ */
+function applyLifecycleRules(scope: RuleScope, field: FieldSchema, path: ChildPath<unknown>): void {
+  if (field.visibleWhen) {
+    const condition = field.visibleWhen;
+    hidden(path, {
+      when: (ctx) =>
+        !evaluateCondition(condition, ctx.valueOf(conditionPath(scope, condition.field))),
+    });
+  }
+  // Selección dependiente (guía §1, plan 6.6): el hijo no se puede tocar
+  // hasta que el padre tenga valor.
+  //
+  // Acá NO sirve `conditionPath`: eso devuelve el contenedor entero porque
+  // `evaluateCondition` recibe el objeto de hermanos. Acá se necesita el
+  // valor concreto del padre.
+  if (field.dependsOn) {
+    const parentKey = field.dependsOn;
+    const isSibling = scope.siblings.some((candidate) => candidate.key === parentKey);
+    const parent = isSibling ? scope.container : scope.root;
+    const parentPath = pathAt<unknown>(parent, parentKey);
+    disabled(path, ({ valueOf }) => isEmptyValue(valueOf(parentPath)));
+  }
+  if (field.readonly) {
+    readonlyRule(path, { when: () => true });
+  }
+  if (field.readonlyOn && modeAppliesTo(field.readonlyOn, scope.excludeKey !== undefined)) {
+    readonlyRule(path, { when: () => true });
+  }
+  // Ciclo de vida de la visibilidad — simétrico a `readonlyOn` de arriba.
+  // `hidden()` deja el campo fuera de la validación y del payload, así que en
+  // alta un campo que LLENA EL BACK no ocupa la sección ni exige nada: sin
+  // esto, `ref` y `pin` aparecían vacíos con un "se genera solo al guardar".
+  if (field.hiddenOn && modeAppliesTo(field.hiddenOn, scope.excludeKey !== undefined)) {
+    hidden(path, { when: () => true });
+  }
+  if (field.readonlyWhen) {
+    const condition = field.readonlyWhen;
+    readonlyRule(path, {
+      when: (ctx) =>
+        evaluateCondition(condition, ctx.valueOf(conditionPath(scope, condition.field))),
+    });
+  }
+}
+
+/** Vacío para el propósito de «el padre todavía no eligió nada». */
+function isEmptyValue(value: unknown): boolean {
+  if (value === undefined || value === null || value === '') {
+    return true;
+  }
+  return Array.isArray(value) && value.length === 0;
+}
+
+/**
+ * Path contra el que se evalúa una condición: el contenedor si nombra a un
+ * campo hermano, la raíz si no (base.md §4: «otro campo del mismo nivel o
+ * del registro raíz»).
+ */
+function conditionPath(scope: RuleScope, key: string): RootPath {
+  const isSibling = scope.siblings.some((field) => field.key === key);
+  const target = isSibling ? scope.container : scope.root;
+  return target as RootPath;
+}
+
+/** Ítems de `string-list`: validan según el tipo declarado (§9: text/url/email). */
+function applyStringItemRules(
+  path: ChildPath<string>,
+  itemType: 'text' | 'url' | 'email' | undefined,
+): void {
+  if (itemType === 'email') {
+    registerEmailRule(path);
+  }
+  if (itemType === 'url') {
+    registerUrlRule(path);
+  }
+}
+
+/**
+ * Navegación dinámica sobre el árbol de paths.
+ *
+ * Indexar `SchemaPathTree<Record<string, unknown>>` con una clave dinámica
+ * devuelve `SchemaPath<unknown, …> | undefined`: el `| undefined` es solo una
+ * consecuencia del index signature, y las reglas con valor concreto (`min`,
+ * `minLength`, `email`…) exigen afinar el tipo. Los casts de este módulo
+ * viven acá; los del registro, en `field-validators.ts` (solución reportada
+ * en plan.md, Fase 10).
+ */
+function pathAt<V>(parent: object, key: string): ChildPath<V> {
+  const path = (parent as unknown as Record<string, unknown>)[key];
+  if (path === undefined) {
+    throw new Error(`El formulario no contiene la ruta "${key}".`);
+  }
+  return path as ChildPath<V>;
+}