signaltree-ng-forms

Using @signaltree/ng-forms

Use when an Angular component needs both a SignalTree-backed state slice (reactive in templates/computed/effect) and a native Angular FormGroup/FormControl for ReactiveFormsModule, third-party UI libs, or ControlValueAccessor interop.

Install:

npm install @signaltree/core @signaltree/ng-forms

Peer: @angular/core ^20, @angular/forms ^20, rxjs ^7.

Two patterns — choose one:

1. Pattern B: form() marker + formBridge() — recommended for new code. Form is one slice of a larger tree.
2. Pattern A: createFormTree() — when entire component is a form and you want all helpers on one object. Emits dev-only deprecation note; fully functional.

Pattern A — createFormTree (full example with validators, async validation, conditionals, persistence):

import { createFormTree, ngFormValidators } from '@signaltree/ng-forms';

// v12: the bare validator exports were removed — use the ngFormValidators object.
const { required, email, minLength, pattern } = ngFormValidators;

interface ProfileForm extends Record<string, unknown> {
  name: string;
  email: string;
  role: string;
  company: { name: string; size: string };
}

class ProfileComponent {
  emailAvailabilityValidator: any = null;

  readonly profile = createFormTree<ProfileForm>(
    { name: '', email: '', role: 'individual', company: { name: '', size: '1-10' } },
    {
      persistKey: 'profile-form',
      storage: typeof window !== 'undefined' ? window.localStorage : undefined,
      validationBatchMs: 120, // coalesce validation results (80–150ms for many async validators)
      fieldConfigs: {
        name: { validators: [required(), minLength(3)] },
        email: {
          validators: [required(), email()],
          asyncValidators: [this.emailAvailabilityValidator],
          debounceMs: 180,
        },
        'company.name': { validators: [pattern(/^[A-Za-z0-9 .,'&-]{2,}$/)] },
      },
      conditionals: [{ when: (v) => v.role === 'manager', fields: ['company.name'] }],
    }
  );

  async save() {
    try {
      await this.profile.submit(async (values) => {
        /* typed ProfileForm */
      });
    } catch {
      /* FormValidationError thrown on validation failure */
    }
  }
}

Bind template: [formGroup]="profile.form". Read signal: profile.$.name(). Read error: profile.getFieldError('email')().

Pattern B — form() marker + formBridge():

import { form, FormSignal, signalTree, validators } from '@signaltree/core';
import { formBridge } from '@signaltree/ng-forms';

const store = signalTree({
  contact: form<ContactForm>({
    initial: { name: '', email: '', message: '' },
    validators: {
      name: validators.required('Name is required'),
      email: [validators.required(), validators.email()],
      message: [validators.required(), validators.minLength(10)],
    },
  }),
}).with(formBridge());

const bridge = store.getAngularForm('contact');
// bridge?.formGroup → FormGroup; bridge?.formControl('email') → FormControl

formBridge() auto-discovers all form() markers in the tree, including nested paths (tree.getAngularForm('user.profile')).

Pattern C — wizard via form() marker:

import { form, signalTree } from '@signaltree/core';

interface SignupForm extends Record<string, unknown> {
  email: string;
  password: string;
  firstName: string;
  lastName: string;
}

const tree = signalTree({
  signup: form<SignupForm>({
    initial: { email: '', password: '', firstName: '', lastName: '' },
    wizard: {
      steps: ['credentials', 'profile'],
      stepFields: { credentials: ['email', 'password'], profile: ['firstName', 'lastName'] },
    },
  }),
});
// tree.$.signup.wizard: next(), prev(), goTo(step), currentStep, isLastStep

See WizardConfig and FormWizard in @signaltree/core for full shape.

Pattern D — undo/redo, via core history() (v13+; recommended, works with both form() alone and a bound signalForm()):

import { signalTree, form, history } from '@signaltree/core';

interface ContactForm extends Record<string, unknown> {
  name: string;
  email: string;
  ssn: string;
}

const tree = signalTree({
  contact: form<ContactForm>({
    initial: { name: '', email: '', ssn: '' },
    history: history({ capacity: 20, exclude: ['ssn'] }), // exclude = never snapshotted
  }),
});

tree.$.contact.patch({ name: 'Ada' });
tree.$.contact.history?.undo();
tree.$.contact.history?.redo();
tree.$.contact.history?.canUndo(); // Signal<boolean>
tree.$.contact.history?.history(); // Signal<{ past: T[]; present: T; future: T[] }>