angular/packages/forms/signals/test/node/field_context.spec.ts
Miles Malerba b8314bd340 feat(forms): add experimental signal-based forms (#63408)
This commit introduces an experimental version of a new signal-based forms API for Angular. This new API aims to explore how signals can be leveraged to create a more declarative, intuitive, and reactive way of handling forms.

The primary goals of this new signal-based approach are:

*   **Signal-centric Design:** Place signals at the core of the forms experience, enabling a truly reactive programming model for form state and logic.
*   **Declarative Logic:** Allow developers to define form behavior, such as validation and conditional fields, declaratively using TypeScript. This moves logic out of the template and into a typed, testable schema.
*   **Developer-Owned Data Model:** The library does not maintain a copy of data in a form model, but instead read and write it via a developer-provided `WritableSignal`, eliminating the need for applications to synchronize their data with the form system.
*   **Interoperability:** A key design goal is seamless interoperability with existing reactive forms, allowing for incremental adoption.
*   **Bridging Template and Reactive Forms:** This exploration hopes to close the gap between template and reactive forms, offering a unified and more powerful approach that combines the best aspects of both.

This initial version of the experimental API includes the core building blocks, such as the `form()` function, `Field` and `FieldState` objects, and a `[control]` directive for binding to UI elements. It also introduces a schema-based system for defining validation, conditional logic, and other form behaviors.

Note: This is an early, experimental API. It is not yet complete and is subject to change based on feedback and further exploration.

Co-authored-by: Kirill Cherkashin <kirts@google.com>
Co-authored-by: Alex Rickabaugh <alxhub@users.noreply.github.com>
Co-authored-by: Leon Senft <leonsenft@users.noreply.github.com>
Co-authored-by: Dylan Hunn <dylhunn@gmail.com>
Co-authored-by: Michael Small <michael-small@users.noreply.github.com>

PR Close #63408
2025-08-28 09:02:43 -07:00

148 lines
3.9 KiB
TypeScript

/**
* @license
* Copyright Google LLC All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.dev/license
*/
import {Injector, signal, WritableSignal} from '@angular/core';
import {TestBed} from '@angular/core/testing';
import {applyEach, FieldContext, FieldPath, form, PathKind, validate} from '../../public_api';
function testContext<T>(
s: WritableSignal<T>,
callback: (ctx: FieldContext<T>, p: FieldPath<T>) => void,
) {
const isCalled = jasmine.createSpy();
TestBed.runInInjectionContext(() => {
const f = form(s, (p) => {
validate(p, (ctx) => {
callback(ctx, p);
isCalled();
return undefined;
});
});
f().errors();
});
expect(isCalled).toHaveBeenCalled();
}
describe('Field Context', () => {
it('value', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx) => {
expect(ctx.value().name).toEqual('pirojok-the-cat');
});
});
it('state', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx) => {
expect(ctx.state.value().name).toEqual('pirojok-the-cat');
});
});
it('field', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx) => {
expect(ctx.field.name().value()).toEqual('pirojok-the-cat');
expect(ctx.field.age().value()).toEqual(5);
});
});
it('key', () => {
const keys: string[] = [];
const recordKey = ({key}: FieldContext<unknown, PathKind.Child>) => {
try {
keys.push(key());
} catch (e) {
keys.push((e as Error).message);
}
return undefined;
};
const cat = signal({name: 'pirojok-the-cat', age: 5});
const f = form(
cat,
(p) => {
// @ts-expect-error
validate(p, recordKey);
validate(p.name, recordKey);
validate(p.age, recordKey);
},
{injector: TestBed.inject(Injector)},
);
f().valid();
expect(keys).toEqual([
'RuntimeError: the top-level field in the form has no parent',
'name',
'age',
]);
});
it('index', () => {
const indices: (string | number)[] = [];
const recordIndex = ({index}: FieldContext<unknown, PathKind.Item>) => {
try {
indices.push(index());
} catch (e) {
indices.push((e as Error).message);
}
return undefined;
};
const pets = signal({
cats: [
{name: 'pirojok-the-cat', age: 5},
{name: 'mielo', age: 10},
],
owner: 'joe',
});
const f = form(
pets,
(p) => {
// @ts-expect-error
validate(p, recordIndex);
applyEach(p.cats, (cat) => {
validate(cat, recordIndex);
});
// @ts-expect-error
validate(p.owner, recordIndex);
},
{injector: TestBed.inject(Injector)},
);
f().valid();
expect(indices).toEqual([
'RuntimeError: the top-level field in the form has no parent',
0,
1,
'RuntimeError: cannot access index, parent field is not an array',
]);
});
it('valueOf', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx, p) => {
expect(ctx.valueOf(p.name)).toEqual('pirojok-the-cat');
expect(ctx.valueOf(p.age)).toEqual(5);
});
});
it('stateOf', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx, p) => {
expect(ctx.stateOf(p.name).value()).toEqual('pirojok-the-cat');
expect(ctx.stateOf(p.age).value()).toEqual(5);
});
});
it('fieldOf', () => {
const cat = signal({name: 'pirojok-the-cat', age: 5});
testContext(cat, (ctx, p) => {
expect(ctx.fieldOf(p.name)().value()).toEqual('pirojok-the-cat');
expect(ctx.fieldOf(p.age)().value()).toEqual(5);
});
});
});