reference-signal-forms

name	reference-signal-forms
description	Explains the mental model and architecture of the code under `packages/forms/signals`. You MUST use this skill any time you plan to work with code in `packages/forms/signals`

Signal Forms Architecture

The packages/forms/signals directory contains the signal-based forms API for Angular. This system differs significantly from the existing Reactive and Template-driven forms.

Mental Model

1. Model-Driven: The system is built around a WritableSignal<T> which serves as the single source of truth. Unlike Reactive Forms where the FormControl holds the value, here the Signal holds the value. The form is merely a view or projection of that signal, adding form-specific state (validity, dirty, touched).

2. Proxy-Based Traversal: The form API (form(signal)) returns a FieldTree. This object is a Proxy. It allows accessing nested fields (e.g., myForm.user.name) without manually creating control groups. Accessing a property on the proxy lazily resolves or creates the corresponding FieldNode.

3. Schema-Based Logic: Validation, disabled state, and other metadata are defined separately via Schemas. Schemas are applied to the form structure using functions like apply, applyEach (for arrays), and applyWhen. This separates the structure of the data from the rules governing it.

4. Directives as Glue: The [formField] directive binds a DOM element (native input or custom control) to a FieldNode. It handles:

   • Syncing the value between the DOM and the Signal.
   • Reflecting state (valid, touched, etc.) to the UI.
   • Handling user interaction events (blur, input).

Key Components

1. FieldNode (src/field/node.ts)

The central internal class representing a single field in the form graph. It aggregates several state managers:

• structure: Manages parent/child relationships and signal slicing.
• validationState: Computes valid, invalid, errors signals.
• nodeState: Tracks touched, dirty, and derived logical state.
• metadataState: Stores metadata like min, max, required.
• submitState: Tracks submission status and server errors.

2. FieldValidationState (src/field/validation.ts)

Implements ValidationState and manages the complexity of validation:

• Synchronous Errors: Derived from schema rules.
• Asynchronous Errors: Handled via signals, including 'pending' states.
• Tree Errors: Errors that bubble up or are targeted at specific fields.
• Submission Errors: Server-side errors injected imperatively via submit().

3. FormField Directive (src/directive/form_field.ts)

The bridge between the FieldNode and the DOM.

• Selector: [formField]
• It supports:
  • Native Elements: <input>, <select>, <textarea>.
  • Custom Controls: Components implementing FormValueControl or FormCheckboxControl.
  • Legacy Interop: Components implementing ControlValueAccessor (via InteropNgControl).

4. Schema (src/api/structure.ts & src/api/rules)

Defines the behavior.

• Created via schema(fn).
• Applied via apply(path, schema).
• Rules include validators (required, pattern, min, max) and state modifiers (disabled, hidden).

Data Flow

1. Read: form.field().value() reads directly from the underlying signal (projected to the specific path).
2. Write: Writing to the form (e.g., via UI) updates the underlying signal.
3. Validation: A computed effect observes the value signal and runs validators defined in the schema.

Usage Example (Conceptual)

// 1. Define Model
const user = signal({name: '', age: 0});

// 2. Define Schema
const userRules = schema((u) => {
  required(u.name);
  min(u.age, 18);
});

// 3. Create Form
const userForm = form(user, userRules); // OR apply(userForm, userRules)

// 4. Bind in Template
// <input [formField]="userForm.name">

Important Files

• packages/forms/signals/src/api/structure.ts: Public API entry points (form, apply).
• packages/forms/signals/src/api/control.ts: Interfaces for custom controls (FormUiControl).
• packages/forms/signals/src/field/node.ts: The FieldNode implementation.
• packages/forms/signals/src/directive/form_field.ts: The [formField] directive.

Supplemental Information

• Compiler & Core Integration: Details how [formField] hooks into type-checking and the runtime.