Reference Signal Forms Agent Skill

Signal Forms Architecture

The packages/forms/signals directory contains an experimental, signal-based forms API for Angular.

This system differs significantly from the existing Reactive and Template-driven forms.

Mental Model

• 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).

• 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.

• 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.

• 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, pristine.
• metadataState: Stores metadata like min, max, required.
• submitState: Tracks submission status and server errors.

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

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_directive.ts)

The bridge between the FieldNode and the DOM.

• Selector: [formField]
• It supports:
• Native Elements: <input>, <select>, <textarea>.
• Custom Controls: Components implementing FormUiControl or FormValueControl.
• 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

• Read: form.field.value() reads directly from the underlying signal (projected to the specific path).
• Write: Writing to the form (e.g., via UI) updates the underlying signal.
• 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_directive.ts: The [formField] directive.

Supplemental Information

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