theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/patrones-angular/references/signal-forms.md

@@ -0,0 +1,795 @@
+# Signal Forms
+
+Los Signal Forms son la opción recomendada para formularios nuevos cuando la versión objetivo de Angular los soporta. Ofrecen una forma reactiva, con seguridad de tipos y guiada por el modelo de gestionar el estado del formulario usando Angular Signals.
+
+Al usar Signal Forms, no uses `null` como valor ni como tipo de ningún campo.
+
+## Imports
+
+Puedes importar lo siguiente desde `@angular/forms/signals`:
+
+```ts
+import {
+  form,
+  FormField,
+  submit,
+  // Reglas de estado de campos
+  disabled,
+  hidden,
+  readonly,
+  debounce,
+  // Helpers de esquema
+  applyWhen,
+  applyEach,
+  schema,
+  // Validación personalizada
+  validate,
+  validateHttp,
+  validateStandardSchema,
+  // Metadatos
+  metadata,
+} from '@angular/forms/signals';
+```
+
+## Crear un formulario
+
+Usa la función `form()` con un modelo basado en signals. La estructura del formulario se deriva directamente del modelo.
+
+```ts
+import {Component, signal} from '@angular/core';
+import {form, FormField} from '@angular/forms/signals';
+
+@Component({
+  // ...
+  imports: [FormField],
+})
+export class Example {
+  // 1. Define tu modelo con valores iniciales (evita undefined)
+  userModel = signal({
+    name: '', // CRÍTICO: NUNCA uses null ni undefined como valores iniciales
+    email: '',
+    age: 0, // Usa 0 para números, NO null
+    address: {
+      street: '',
+      city: '',
+    },
+    hobbies: [] as string[], // Usa [] para arrays, NO null
+  });
+
+  // MAL - NO HAGAS ESTO:
+  // badModel = signal({
+  //   name: null,      // ERROR: usa '' en su lugar
+  //   age: null,       // ERROR: usa 0 en su lugar
+  //   items: null      // ERROR: usa [] en su lugar
+  // });
+
+  // 2. Crea el formulario
+  userForm = form(this.userModel);
+}
+```
+
+## Validación
+
+Importa los validadores desde `@angular/forms/signals`.
+
+```ts
+import {required, email, min, max, minLength, maxLength, pattern} from '@angular/forms/signals';
+```
+
+Úsalos en la función de esquema que se pasa a `form()`:
+
+```ts
+userForm = form(this.userModel, (schemaPath) => {
+  // Obligatorio
+  required(schemaPath.name, {message: 'El nombre es obligatorio'});
+
+  // Obligatorio condicional.
+  required(schemaPath.name, {
+    when({valueOf}) {
+      return valueOf(schemaPath.age) > 10;
+    },
+  });
+  // when solo está disponible para required
+  // NO hagas esto: pattern(p.name, /xxx/, {when /* ERROR */)
+
+  // Email
+  email(schemaPath.email, {message: 'Email inválido'});
+
+  // Min/Max para números
+  min(schemaPath.age, 18);
+  max(schemaPath.age, 100);
+
+  // MinLength/MaxLength para strings/arrays
+  minLength(schemaPath.password, 8);
+  maxLength(schemaPath.description, 500);
+
+  // Patrón (regex)
+  pattern(schemaPath.zipCode, /^\d{5}$/);
+});
+```
+
+## FieldState vs. FormField: el requisito estructural
+
+Es importante entender la diferencia entre **FormField** (la estructura) y **FieldState** (los datos/signals reales).
+
+**REGLA**: debes **INVOCAR** un campo como función para acceder a sus signals de estado (valid, touched, dirty, hidden, etc.).
+
+```ts
+// f es un FormField (estructural)
+const f = form(signal({cat: {name: 'pirojok-the-cat', age: 5}}));
+
+f.cat.name; // FormField: ¡desde aquí no puedes obtener flags!
+f.cat.name.touched(); // ERROR: touched() no existe en FormField
+
+f.cat.name(); // FieldState: invocarlo te da acceso a las signals
+f.cat.name().touched(); // VÁLIDO: acceso a la signal
+f.cat().name.touched(); // ERROR: f.cat() es estado, ¡no tiene hijos!
+```
+
+De forma similar en una plantilla:
+
+```html
+<!-- MAL: la propiedad 'hidden' no existe en el tipo 'FormField' -->
+@if (bookingForm.hotelDetails.hidden()) { ... }
+
+<!-- BIEN: invócalo primero -->
+@if (bookingForm.hotelDetails().hidden()) { ... }
+```
+
+## Disabled / Readonly / Hidden
+
+Controla el estado de los campos con reglas en el esquema.
+
+```ts
+import {disabled, readonly, hidden} from '@angular/forms/signals';
+
+userForm = form(this.userModel, (schemaPath) => {
+  // Deshabilitado condicional
+  disabled(schemaPath.password, ({valueOf}) => !valueOf(schemaPath.createAccount));
+
+  // Oculto condicional (NO lo elimina del modelo, solo lo marca como oculto)
+  hidden(schemaPath.shippingAddress, ({valueOf}) => valueOf(schemaPath.sameAsBilling));
+
+  // Solo lectura
+  readonly(schemaPath.username);
+});
+```
+
+## Enlace
+
+Importa `FormField` y usa la directiva `[formField]`.
+
+```ts
+import {FormField} from '@angular/forms/signals';
+```
+
+Todas las propiedades de estado, como `disabled`, `hidden`, `readonly` y `name`, se enlazan automáticamente.
+_NO_ enlaces el campo `name`.
+
+**CRÍTICO: ATRIBUTOS PROHIBIDOS**
+Al usar `[formField]`, NO debes definir los siguientes atributos en la plantilla (ni estáticos ni enlazados):
+
+- `min`, `max` (usa validadores en el esquema)
+- `value`, `[value]`, `[attr.value]` (ya lo gestiona `[formField]`)
+- `[attr.min]`, `[attr.max]`
+- `[disabled]`, `[readonly]` (ya lo gestiona `[formField]`)
+
+NO hagas esto: `<input min="1" [formField]>` ni `<input [value]="val" [formField]>`.
+
+```html
+<!-- Input -->
+<input [formField]="userForm.name" />
+
+<!-- Checkbox -->
+<input type="checkbox" [formField]="userForm.isAdmin" />
+
+<!-- Select -->
+<select [formField]="userForm.country">
+  <option value="us">US</option>
+</select>
+
+<!-- userForm.name NO puede ser anulable, porque input no acepta null -->
+<input [formField]="userForm.name" />
+```
+
+## Formularios reactivos
+
+**NO importes** `FormControl`, `FormGroup`, `FormArray` ni `FormBuilder` desde `@angular/forms`. Los Signal Forms reemplazan por completo esos conceptos.
+Los signal forms NO tienen builder.
+
+## Acceder al estado
+
+Cada campo del formulario es una función que devuelve su estado.
+
+```ts
+// Accede al campo invocándolo
+const emailState = this.userForm.email();
+
+// Valor (WritableSignal)
+const value = this.userForm().value();
+
+// Estado de validación (signals)
+const isValid = this.userForm().valid();
+const isInvalid = this.userForm().invalid();
+const errors = this.userForm().errors(); // Array de errores
+const isPending = this.userForm().pending(); // Validación asíncrona pendiente
+
+// Estado de interacción (signals)
+const isTouched = this.userForm().touched();
+const isDirty = this.userForm().dirty();
+
+// Estado de disponibilidad (signals)
+const isDisabled = this.userForm().disabled();
+const isHidden = this.userForm().hidden();
+const isReadonly = this.userForm().readonly();
+```
+
+¡IMPORTANTE!: asegúrate de invocar el campo para obtener su estado.
+
+```ts
+form().invalid()
+form.field().dirty()
+form.field.subfield().touched()
+form.a.b.c.d().value()
+form.address.ssn().pending()
+form().reset()
+
+// La única excepción es length:
+form.children.length
+form.length // OJO: ¡sin paréntesis!
+form.client.addresses.length  // Sin "()"
+
+@for (income of form.addresses; track $index) {/**/}
+```
+
+## Envío
+
+Usa la función `submit()`. Marca automáticamente todos los campos como touched antes de ejecutar la acción.
+
+**CRÍTICO**: el callback de `submit()` DEBE ser `async` y DEBE devolver una Promise.
+
+```ts
+import { submit } from '@angular/forms/signals';
+
+// CORRECTO - callback async
+onSubmit() {
+  submit(this.userForm, async () => {
+    // Esto solo se ejecuta si el formulario es válido
+    await this.apiService.save(this.userModel());
+    console.log('¡Guardado!');
+  });
+}
+
+// MAL - falta la palabra clave async
+onSubmit() {
+  submit(this.userForm, () => {  // ERROR: debe ser async
+    console.log('¡Guardado!');
+  });
+}
+```
+
+## Gestión de errores
+
+`field().errors()` devuelve el array de errores de tipo ValidationError:
+
+```ts
+interface ValidationError {
+  readonly kind: string;
+  readonly message?: string;
+}
+```
+
+_NO_ devuelvas null desde los validadores.
+Cuando no hay errores, devuelve undefined.
+
+### Contexto
+
+Las funciones que se pasan a reglas como `validate()`, `disabled()` o `applyWhen` reciben un objeto de contexto. Es **CRÍTICO** entender su estructura:
+
+```ts
+validate(
+  schemaPath.username,
+  ({
+    value, // Signal<T>: valor actual escribible del campo
+    fieldTree, // FieldTree<T>: subcampos (si es un grupo/array)
+    state, // FieldState<T>: acceso a flags como state.valid(), state.dirty()
+    valueOf, // (path) => T: leer valores de OTROS campos (rastreando dependencias), p. ej. valueOf(schemaPath.password)
+    stateOf, // (path) => FieldState: acceder al estado (valid/dirty) de OTROS campos, p. ej. stateOf(schemaPath.password).valid()
+    pathKeys, // Signal<string[]>: ruta desde la raíz hasta este campo
+  }) => {
+    // MAL: if (touched()) ... (touched no está en el contexto)
+    // BIEN: if (state.touched()) ...
+
+    if (value() === 'admin') {
+      return {kind: 'reserved', message: 'El nombre de usuario admin está reservado'};
+    }
+  },
+);
+```
+
+### IMPORTANTE: los paths NO son signals
+
+Dentro del callback de `form()`, `schemaPath` y sus hijos (p. ej., `schemaPath.user.name`) **NO** son signals y **NO** son invocables.
+
+```ts
+// MAL - Esto lanzará un error:
+applyWhen(p.ssn, () => p.ssn().touched(), (ssnField) => { ... });
+
+// BIEN - Usa stateOf() para obtener el estado de un path:
+applyWhen(p.ssn, ({ stateOf }) => stateOf(p.ssn).touched(), (ssnField) => { ... });
+
+// BIEN - Usa valueOf() para obtener el valor de un path:
+applyWhen(p.ssn, ({ valueOf }) => valueOf(p.ssn) !== '', (ssnField) => { ... });
+```
+
+### Múltiples elementos
+
+- Usa `applyEach` para aplicar reglas por elemento.
+- **CRÍTICO**: el callback de `applyEach` recibe SOLO UN argumento (el path del elemento), NO dos:
+
+```ts
+// CORRECTO - un solo argumento
+applyEach(s.items, (item) => {
+  required(item.name);
+});
+
+// MAL - NO pases el índice
+applyEach(s.items, (item, index) => {
+  // ERROR: el callback recibe 1 argumento
+  required(item.name);
+});
+```
+
+- En la plantilla usa `@for` para iterar sobre los elementos.
+- Para eliminar un elemento de un array, simplemente elimínalo del array en los datos.
+- **Enlace de `select`**: SÍ puedes enlazar `<select [formField]="form.country">`. Asegúrate de que las opciones tengan atributos `value`.
+
+### Bucles @for anidados
+
+**CRÍTICO**: Angular NO tiene `$parent`. En bucles anidados, guarda el índice externo en una variable:
+
+```html
+<!-- MAL - $parent no existe -->
+@for (item of form.items; track $index) { @for (option of item.options; track $index) {
+<button (click)="removeOption($parent.$index, $index)">Eliminar</button>
+<!-- ERROR -->
+} }
+
+<!-- CORRECTO - usa let para guardar el índice externo -->
+@for (item of form.items; track $index; let outerIndex = $index) { @for (option of item.options;
+track $index) {
+<button (click)="removeOption(outerIndex, $index)">Eliminar</button>
+} }
+```
+
+### Deshabilitar el botón del formulario
+
+```html
+<button [disabled]="form().invalid() || form().pending()" />
+<!-- O -->
+<button [disabled]="taxForm.invalid()" />
+```
+
+NO uses `[disabled]` en un input. `[formField]` lo hace por ti.
+NO uses `[readonly]` en un input. `[formField]` lo hace por ti.
+Si necesitas un campo deshabilitado o de solo lectura, usa las reglas `disabled()` o `readonly()` en el esquema.
+
+### Validación asíncrona
+
+No uses `validate()` para lo asíncrono; usa `validateAsync()`:
+
+**CRÍTICO**:
+
+1. La opción `params` DEBE ser una función que devuelva el valor a validar.
+2. El manejador `onError` es **OBLIGATORIO** — ¡NO es opcional!
+
+```ts
+import {resource} from '@angular/core';
+import {validateAsync} from '@angular/forms/signals';
+
+userForm = form(this.userModel, (s) => {
+  validateAsync(s.username, {
+    // 1. DEBE ser una función - params recibe el contexto y devuelve el valor
+    params: ({value}) => value(),
+
+    // 2. Crea el resource - la factory recibe una Signal
+    factory: (username) =>
+      resource({
+        params: username, // Usa 'params' en resource()
+        loader: async ({params: value}) => {
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          return value === 'taken';
+        },
+      }),
+
+    // 3. Mapea el éxito a errores
+    onSuccess: (isTaken) =>
+      isTaken ? {kind: 'taken', message: 'El nombre de usuario ya está en uso'} : undefined,
+
+    // 4. Gestiona los errores - ¡ESTO ES OBLIGATORIO!
+    onError: () => ({kind: 'error', message: 'La validación falló'}),
+  });
+});
+```
+
+**Ejemplos INCORRECTOS:**
+
+```ts
+// MAL - params debe ser una función
+validateAsync(s.username, {
+  params: s.username, // ERROR: debe ser ({ value }) => value()
+  // ...
+});
+
+// MAL - falta onError (¡es obligatorio!)
+validateAsync(s.username, {
+  params: ({value}) => value(),
+  factory: (username) =>
+    resource({
+      /* ... */
+    }),
+  onSuccess: (result) => (result ? {kind: 'error'} : undefined),
+  // ERROR: ¡falta 'onError' pero es obligatorio!
+});
+```
+
+### Uso de resource
+
+**CRÍTICO**: en el `resource()` de Angular, usa `params` para la signal de entrada.
+
+```ts
+// CORRECTO
+resource({
+  params: mySignal,
+  loader: async ({params: value}) => {
+    /* ... */
+  },
+});
+
+// MAL
+resource({
+  request: mySignal, // ERROR: debe ser 'params'
+  loader: async ({request}) => {
+    /* ... */
+  },
+});
+```
+
+Usa `debounce()` para retrasar la sincronización entre la UI y el modelo.
+
+```ts
+import {debounce} from '@angular/forms/signals';
+
+userForm = form(this.userModel, (s) => {
+  // Retrasa las actualizaciones del modelo 300 ms
+  debounce(s.username, 300);
+});
+```
+
+### Validación condicional
+
+```ts
+form(
+  data,
+  (path) => {
+    applyWhen(
+      name,
+      ({value}) => value() !== 'admin',
+      (namePath) => {
+        validate(namePath.last /* ... */);
+        disable(namePath.last /* ... */);
+      },
+    );
+  },
+  {injector: TestBed.inject(Injector)},
+);
+```
+
+`applyWhen` pasa el path mapeado al primer argumento.
+Si necesitas el campo padre, simplemente pásalo a `applyWhen`:
+
+```ts
+form(
+  data,
+  (path) => {
+    applyWhen(
+      cat,
+      ({value}) => value().name !== 'admin',
+      (catPath) => {
+        require(cat.catPath /* ... */);
+      },
+    );
+  },
+  {injector: TestBed.inject(Injector)},
+);
+```
+
+## Errores comunes (NO HAGAS ESTO)
+
+| Escenario de error       | MAL (error común)                             | BIEN (forma correcta)                                        |
+| :----------------------- | :-------------------------------------------- | :----------------------------------------------------------- |
+| **Acceder a flags**      | `form.field.valid()`                          | `form.field().valid()`                                       |
+| **Acceder al valor**     | `form.field.value()`                          | `form.field().value()`                                       |
+| **Fijar el valor**       | `form.field.set(x)`                           | Actualiza la signal del modelo: `this.model.update(...)`     |
+| **Flags de la raíz**     | `form.invalid()`                              | `form().invalid()`                                           |
+| **Doble invocación**     | `form.field()()`                              | `form.field().value()`                                       |
+| **Contexto de reglas**   | `({ touched }) => touched()`                  | `({ state }) => state.touched()`                             |
+| **Invocar paths**        | `applyWhen(p.foo, () => p.foo() === 'x')`     | `applyWhen(p.foo, ({ valueOf }) => valueOf(p.foo) === 'x')`  |
+| **Args de applyWhen**    | `applyWhen(condition, () => {...})`           | `applyWhen(path, condition, schemaFn)` — requiere 3 args     |
+| **Longitud de array**    | `form.items().length`                         | `form.items.length` (estructural)                            |
+| **Multi-select array**   | `<select [formField]="form.tags">` (string[]) | Usa checkboxes para campos de array                          |
+| **Atributo readonly**    | `<input readonly [formField]>`                | Usa la regla `readonly()` en el esquema                      |
+| **Atributos min/max**    | `<input min="1" max="10">`                    | Usa las reglas `min()` y `max()` en el esquema               |
+| **Enlace de value**      | `<input [value]="val">`                       | NO uses `[value]` con `[formField]`                          |
+| **Opción when**          | `pattern(p.x, /.../, {when: ...})`            | `when` solo funciona con `required()`                        |
+| **Callback de submit**   | `submit(form, () => { ... })`                 | `submit(form, async () => { ... })`                          |
+| **Params asíncronos**    | `params: s.field`                             | `params: ({ value }) => value()`                             |
+| **onError asíncrono**    | Omitir `onError`                              | `onError` es OBLIGATORIO en `validateAsync`                  |
+| **API de resource()**    | `request: signal`                             | `params: signal`                                             |
+| **Args de applyEach**    | `applyEach(s.items, (item, index) => ...)`    | `applyEach(s.items, (item) => ...)`                          |
+| **@for anidados**        | `$parent.$index`                              | Usa `let outerIndex = $index`                                |
+| **Import de FormState**  | `import { FormState }`                        | `FormState` no existe, usa `FieldState`                      |
+| **Null en el modelo**    | `signal({ name: null })`                      | `signal({ name: '' })` o `signal({ age: 0 })`                |
+| **Sintaxis de validate** | `validate(s.field, { value } => ...)`         | `validate(s.field, ({ value }) => ...)`                      |
+| **Checkbox y arrays**    | `[formField]="form.tags"` (string[])          | Los checkboxes SOLO se enlazan a `boolean`                   |
+
+## Ejemplo de formulario grande
+
+### `src/app/app.ts`
+
+```ts
+import {Component, signal, ChangeDetectionStrategy} from '@angular/core';
+import {
+  form,
+  FormField,
+  submit,
+  required,
+  email,
+  min,
+  hidden,
+  applyEach,
+  validate,
+} from '@angular/forms/signals';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [FormField],
+  templateUrl: './app.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class App {
+  model = signal({
+    personalInfo: {
+      firstName: '',
+      lastName: '',
+      email: '',
+      age: 0,
+    },
+    tripDetails: {
+      destination: 'Mars',
+      launchDate: '',
+    },
+    package: {
+      tier: 'economy',
+      extras: [] as string[],
+    },
+    companions: [] as Array<{name: string; relation: string}>,
+  });
+
+  bookingForm = form(this.model, (s) => {
+    required(s.personalInfo.firstName, {message: 'El nombre es obligatorio'});
+    required(s.personalInfo.lastName, {message: 'El apellido es obligatorio'});
+    required(s.personalInfo.email, {message: 'El email es obligatorio'});
+    email(s.personalInfo.email, {message: 'Dirección de email inválida'});
+    required(s.personalInfo.age, {message: 'La edad es obligatoria'});
+    min(s.personalInfo.age, 18, {message: 'Debes tener al menos 18 años'});
+
+    required(s.tripDetails.destination);
+    required(s.tripDetails.launchDate);
+    validate(s.tripDetails.launchDate, ({value}) => {
+      const date = new Date(value());
+      if (isNaN(date.getTime())) return undefined;
+      const today = new Date();
+      if (date < today) {
+        return {kind: 'pastData', message: 'La fecha de lanzamiento debe ser futura'};
+      }
+      return undefined;
+    });
+
+    // valueOf se usa para acceder a valores de otros campos en las reglas
+    hidden(s.package.extras, ({valueOf}) => valueOf(s.package.tier) === 'economy');
+
+    applyEach(s.companions, (companion) => {
+      required(companion.name, {message: 'El nombre del acompañante es obligatorio'});
+      required(companion.relation, {message: 'La relación es obligatoria'});
+    });
+  });
+
+  addCompanion() {
+    this.model.update((m) => ({
+      ...m,
+      companions: [...m.companions, {name: '', relation: ''}],
+    }));
+  }
+
+  removeCompanion(index: number) {
+    this.model.update((m) => ({
+      ...m,
+      companions: m.companions.filter((_, i) => i !== index),
+    }));
+  }
+
+  onSubmit() {
+    // CRÍTICO: el callback de submit DEBE ser async
+    submit(this.bookingForm, async () => {
+      console.log('Reserva confirmada:', this.model());
+      // Si necesitas trabajo asíncrono:
+      // await this.apiService.save(this.model());
+    });
+  }
+}
+```
+
+### `src/app/app.html`
+
+```html
+<form (submit)="onSubmit(); $event.preventDefault()">
+  <h1>Reserva interestelar</h1>
+
+  <section>
+    <h2>Datos personales</h2>
+
+    <label>
+      Nombre
+      <input [formField]="bookingForm.personalInfo.firstName" />
+      @if (bookingForm.personalInfo.firstName().touched() &&
+      bookingForm.personalInfo.firstName().errors().length) {
+      <span>{{ bookingForm.personalInfo.firstName().errors()[0].message }}</span>
+      }
+    </label>
+
+    <label>
+      Apellido
+      <input [formField]="bookingForm.personalInfo.lastName" />
+      @if (bookingForm.personalInfo.lastName().touched() &&
+      bookingForm.personalInfo.lastName().errors().length) {
+      <span>{{ bookingForm.personalInfo.lastName().errors()[0].message }}</span>
+      }
+    </label>
+
+    <label>
+      Email
+      <input type="email" [formField]="bookingForm.personalInfo.email" />
+      @if (bookingForm.personalInfo.email().touched() &&
+      bookingForm.personalInfo.email().errors().length) {
+      <span>{{ bookingForm.personalInfo.email().errors()[0].message }}</span>
+      }
+    </label>
+
+    <label>
+      Edad
+      <input type="number" [formField]="bookingForm.personalInfo.age" />
+      @if (bookingForm.personalInfo.age().touched() &&
+      bookingForm.personalInfo.age().errors().length) {
+      <span>{{ bookingForm.personalInfo.age().errors()[0].message }}</span>
+      }
+    </label>
+  </section>
+
+  <section>
+    <h2>Detalles del viaje</h2>
+
+    <label>
+      Destino
+      <select [formField]="bookingForm.tripDetails.destination">
+        <option value="Mars">Marte</option>
+        <option value="Moon">Luna</option>
+        <option value="Titan">Titán</option>
+      </select>
+    </label>
+
+    <label>
+      Fecha de lanzamiento
+      <input type="date" [formField]="bookingForm.tripDetails.launchDate" />
+      @if (bookingForm.tripDetails.launchDate().touched() &&
+      bookingForm.tripDetails.launchDate().errors().length) {
+      <span>{{ bookingForm.tripDetails.launchDate().errors()[0].message }}</span>
+      }
+    </label>
+  </section>
+
+  <section>
+    <h2>Paquete</h2>
+
+    <label>
+      <input type="radio" value="economy" [formField]="bookingForm.package.tier" />
+      Económico
+    </label>
+    <label>
+      <input type="radio" value="business" [formField]="bookingForm.package.tier" />
+      Business
+    </label>
+    <label>
+      <input type="radio" value="first" [formField]="bookingForm.package.tier" />
+      Primera clase
+    </label>
+
+    @if (!bookingForm.package.extras().hidden()) {
+    <div>
+      <h3>Extras</h3>
+      <!-- La selección múltiple para arrays debe usar select multiple -->
+      <select multiple [formField]="bookingForm.package.extras">
+        <option value="wifi">WiFi</option>
+        <option value="gym">Gimnasio</option>
+      </select>
+    </div>
+    }
+  </section>
+
+  <section>
+    <h2>Acompañantes</h2>
+    <button type="button" (click)="addCompanion()">Añadir acompañante</button>
+
+    @for (companion of bookingForm.companions; track $index) {
+    <div>
+      <input [formField]="companion.name" placeholder="Nombre" />
+      @if (companion.name().touched() && companion.name().errors().length) {
+      <span>{{ companion.name().errors()[0].message }}</span>
+      }
+
+      <input [formField]="companion.relation" placeholder="Relación" />
+      @if (companion.relation().touched() && companion.relation().errors().length) {
+      <span>{{ companion.relation().errors()[0].message }}</span>
+      }
+
+      <button type="button" (click)="removeCompanion($index)">Eliminar</button>
+    </div>
+    }
+  </section>
+
+  <button [disabled]="bookingForm().invalid()">Enviar</button>
+</form>
+```
+
+## Recuperarse de errores de build
+
+Si encuentras errores de build, estas son las correcciones más comunes:
+
+### `Property 'value' does not exist on type 'FieldTree'`
+
+**Problema**: acceder a `.value()` directamente sobre un campo sin invocarlo primero.
+
+```ts
+// MAL
+const val = this.form.field.value();
+// BIEN
+const val = this.form.field().value();
+```
+
+### `Property 'set' does not exist on type 'FieldTree'`
+
+**Problema**: intentar fijar valores sobre el árbol del formulario. Los Signal Forms están guiados por el modelo.
+
+```ts
+// MAL
+this.form.address.street.set('Calle Mayor');
+// BIEN - actualiza la signal del modelo
+this.model.update((m) => ({...m, address: {...m.address, street: 'Calle Mayor'}}));
+```
+
+### `Type 'string[]' is not assignable to type 'string'`
+
+**Problema**: enlazar `[formField]` a un campo de array con un `<select>` de valor único.
+
+```html
+<!-- MAL - assignees es string[], select espera string -->
+<select [formField]="form.assignees">
+  ...
+</select>
+
+<!-- BIEN - usa select multiple para campos de array -->
+<select multiple [formField]="form.assignees">
+  <option value="us">US</option>
+</select>
+```