@signaltree/ng-forms 7.1.3 → 7.3.0

package/README.md

@@ -1,81 +1,129 @@
 # @signaltree/ng-forms
 
-**Tree-structured signal forms for Angular 21+**. When Angular's native signal forms aren't enough—add persistence, wizards, history tracking, and nested state management.
+**Angular FormGroup bridge for SignalTree's `form()` marker**. Adds reactive forms integration, conditional fields, and undo/redo to tree-integrated forms.
 
 **Bundle size: 3.38KB gzipped**
 
-## Why ng-forms?
+## Architecture: form() + formBridge()
 
-Angular 21 introduced native signal forms with `FormField<T>`, which work great for simple, flat forms. **ng-forms is for complex forms** that need:
+SignalTree v7 introduces a layered forms architecture:
 
-### **🌲 Tree-Structured State**
-```typescript
-// Angular 21: Flat fields, no relationships
-const name = formField('');
-const email = formField('');
-
-// ng-forms: Hierarchical structure that mirrors your data model
-const form = createFormTree({
-  user: { name: '', email: '' },
-  address: { street: '', city: '', zip: '' }
-});
-// Access nested: form.$.user.name()
-// Validate paths: 'address.zip'
 ```
-
-### **💾 Auto-Persistence**
-```typescript
-// Angular 21: No persistence, build it yourself
-// ng-forms: Built-in with debouncing
-const form = createFormTree(initialState, {
-  persistKey: 'checkout-draft',
-  storage: localStorage,
-  persistDebounceMs: 500
-});
-// Auto-saves changes, restores on init
+@signaltree/core                    @signaltree/ng-forms
+┌─────────────────────────┐         ┌─────────────────────────┐
+│ form() marker           │         │ formBridge()      │
+│ ─────────────────────── │   ───►  │ enhancer that:          │
+│ • Signal-based fields   │         │ • Creates FormGroup     │
+│ • Sync/async validators │         │ • Bidirectional sync    │
+│ • Persistence           │         │ • Conditional fields    │
+│ • Wizard navigation     │         │ • Angular validators    │
+│ • dirty/valid/submitting│         │                         │
+└─────────────────────────┘         │ withFormHistory()       │
+     Works standalone!              │ • Undo/redo             │
+                                    └─────────────────────────┘
 ```
 
-### **🧙 Wizard & Multi-Step Forms**
+**Key insight**: `form()` is self-sufficient. `formBridge()` adds Angular-specific capabilities.
+
+## Quick Start (Recommended Pattern)
+
 ```typescript
-// Angular 21: Build from scratch
-// ng-forms: First-class wizard support
-const wizard = createWizardForm([
-  { fields: ['profile.name', 'profile.email'] },
-  { fields: ['address.street', 'address.city'] }
-], initialValues);
-wizard.nextStep(); // Automatic field visibility management
+import { signalTree, form } from '@signaltree/core';
+import { formBridge } from '@signaltree/ng-forms';
+
+// Define forms in your tree
+const tree = signalTree({
+  checkout: {
+    shipping: form({
+      initial: { name: '', address: '', zip: '' },
+      validators: {
+        zip: (v) => (/^\d{5}$/.test(String(v)) ? null : 'Invalid ZIP'),
+      },
+      persist: 'checkout-shipping',
+    }),
+    payment: form({
+      initial: { card: '', cvv: '' },
+      wizard: { steps: ['card', 'review'] },
+    }),
+  },
+}).with(
+  formBridge({
+    conditionals: [{ when: (v) => v.checkout.sameAsBilling, fields: ['checkout.shipping.*'] }],
+  })
+);
+
+// Use in components
+@Component({
+  template: `
+    <!-- Option 1: Use form() signals directly -->
+    <input [value]="tree.$.checkout.shipping.$.name()" (input)="tree.$.checkout.shipping.$.name.set($event.target.value)" />
+
+    <!-- Option 2: Use Angular FormGroup -->
+    <form [formGroup]="shippingForm">
+      <input formControlName="name" />
+    </form>
+  `,
+})
+class CheckoutComponent {
+  tree = inject(CHECKOUT_TREE);
+
+  // Get the FormGroup bridge
+  shippingForm = this.tree.getAngularForm('checkout.shipping')?.formGroup;
+}
 ```
 
-### **↩️ History / Undo-Redo**
+## When to Use Each Layer
+
+### form() alone (no ng-forms needed)
+
 ```typescript
-// Angular 21: Not available
-// ng-forms: Built-in
-const form = withFormHistory(createFormTree(initialState));
-form.undo();
-form.redo();
+// Pure signal forms - works without Angular forms module
+const tree = signalTree({
+  login: form({
+    initial: { email: '', password: '' },
+    validators: { email: validators.email() },
+  }),
+});
+
+// Full functionality without Angular FormGroup
+tree.$.login.$.email.set('user@test.com');
+tree.$.login.valid(); // Reactive validation
+tree.$.login.validate(); // Trigger validation
+tree.$.login.submit(fn); // Submit handling
+tree.$.login.wizard?.next(); // Wizard navigation (if configured)
 ```
 
-### **🔗 Reactive Forms Bridge**
+**Use when**: SSR, unit tests, simple forms, non-Angular environments
+
+### form() + formBridge()
+
 ```typescript
-// Angular 21: New API, migration required
-// ng-forms: Works with existing FormGroup/FormControl
-<form [formGroup]="profile.form" (ngSubmit)="save()">
-  <input formControlName="name" />
-</form>
-// Signals AND reactive forms, incremental migration
+// Add Angular FormGroup bridge
+const tree = signalTree({
+  profile: form({ initial: { name: '' } }),
+}).with(formBridge());
+
+// Now you get FormGroup access
+const formGroup = tree.getAngularForm('profile')?.formGroup;
+// Or attached directly: (tree.$.profile as any).formGroup
 ```
 
-### **⚙️ Declarative Configuration**
+**Use when**: Need `[formGroup]` directives, Angular validators, conditional field disabling
+
+### form() + formBridge() + withFormHistory()
+
 ```typescript
-// Angular 21: Per-field imperative setup
-// ng-forms: Centralized, glob-pattern configs
-fieldConfigs: {
-  'email': { validators: [validators.email()], debounceMs: 300 },
-  'payment.card.*': { validators: validators.required() }
-}
+const tree = signalTree({
+  editor: form({ initial: { content: '' } }),
+})
+  .with(formBridge())
+  .with(withFormHistory({ capacity: 50 }));
+
+tree.undo();
+tree.redo();
 ```
 
-**Use Angular 21 signal forms for simple forms. Use ng-forms for enterprise apps with complex state, persistence, and workflow requirements.**
+**Use when**: Complex editors, need undo/redo
 
 ## Installation
 
@@ -175,11 +223,13 @@ The returned `FormTree` exposes:
 **ng-forms complements Angular 21's native signal forms**—use both in the same app:
 
 ### Use Angular 21 `FormField<T>` for:
+
 - ✅ Simple, flat forms (login, search)
 - ✅ Single-field validation
 - ✅ Maximum type safety
 
 ### Use ng-forms `createFormTree()` for:
+
 - ✅ Nested object structures (user + address + payment)
 - ✅ Forms with persistence/auto-save
 - ✅ Wizard/multi-step flows
@@ -188,6 +238,7 @@ The returned `FormTree` exposes:
 - ✅ Migration from reactive forms
 
 ### Hybrid Example: Simple Fields + Complex Tree
+
 ```typescript
 import { formField } from '@angular/forms';
 import { createFormTree } from '@signaltree/ng-forms';
@@ -215,6 +266,7 @@ class CheckoutComponent {
 ```
 
 ### Connecting to Reactive Forms
+
 ```ts
 import { toWritableSignal } from '@signaltree/core';
 
@@ -325,21 +377,83 @@ Use `SignalValueDirective` to keep standalone signals and `ngModel` fields align
 
 ## When to use ng-forms vs Angular 21 signal forms
 
-| Scenario | Recommendation |
-|----------|---------------|
-| Login form (2-3 fields) | ✅ Angular 21 `FormField` |
-| Search bar with filters | ✅ Angular 21 `FormField` |
-| User profile with nested address | ✅ **ng-forms** (tree structure) |
-| Checkout flow (shipping + payment + items) | ✅ **ng-forms** (persistence + wizard) |
-| Multi-step onboarding (5+ steps) | ✅ **ng-forms** (wizard API) |
-| Form with auto-save drafts | ✅ **ng-forms** (built-in persistence) |
-| Complex editor with undo/redo | ✅ **ng-forms** (history tracking) |
-| Migrating from reactive forms | ✅ **ng-forms** (FormGroup bridge) |
-| Dynamic form with conditional fields | ✅ **ng-forms** (conditionals config) |
-| Form synced with global app state | ✅ **ng-forms** (SignalTree integration) |
+| Scenario                                   | Recommendation                           |
+| ------------------------------------------ | ---------------------------------------- |
+| Login form (2-3 fields)                    | ✅ Angular 21 `FormField`                |
+| Search bar with filters                    | ✅ Angular 21 `FormField`                |
+| User profile with nested address           | ✅ **ng-forms** (tree structure)         |
+| Checkout flow (shipping + payment + items) | ✅ **ng-forms** (persistence + wizard)   |
+| Multi-step onboarding (5+ steps)           | ✅ **ng-forms** (wizard API)             |
+| Form with auto-save drafts                 | ✅ **ng-forms** (built-in persistence)   |
+| Complex editor with undo/redo              | ✅ **ng-forms** (history tracking)       |
+| Migrating from reactive forms              | ✅ **ng-forms** (FormGroup bridge)       |
+| Dynamic form with conditional fields       | ✅ **ng-forms** (conditionals config)    |
+| Form synced with global app state          | ✅ **ng-forms** (SignalTree integration) |
 
 **Rule of thumb**: If your form data is a nested object or needs workflow features (persistence/wizards/history), use ng-forms. For simple flat forms, Angular 21's native signal forms are perfect.
 
+## Migration from createFormTree()
+
+`createFormTree()` is deprecated in favor of the composable `form()` + `formBridge()` pattern.
+
+### Before (deprecated)
+
+```typescript
+import { createFormTree } from '@signaltree/ng-forms';
+
+const form = createFormTree(
+  {
+    name: '',
+    email: '',
+  },
+  {
+    validators: { email: validators.email() },
+    persistKey: 'profile-form',
+  }
+);
+
+// Access
+form.$.name.set('John');
+form.form; // FormGroup
+```
+
+### After (recommended)
+
+```typescript
+import { signalTree, form } from '@signaltree/core';
+import { formBridge } from '@signaltree/ng-forms';
+
+const tree = signalTree({
+  profile: form({
+    initial: { name: '', email: '' },
+    validators: { email: validators.email() },
+    persist: 'profile-form',
+  }),
+}).with(formBridge());
+
+// Access
+tree.$.profile.$.name.set('John');
+tree.getAngularForm('profile')?.formGroup; // FormGroup
+// Or: (tree.$.profile as any).formGroup
+```
+
+### Key differences
+
+| Aspect               | createFormTree()        | form() + formBridge()  |
+| -------------------- | ----------------------- | ---------------------------- |
+| **Standalone**       | Always needs Angular    | form() works without Angular |
+| **Tree integration** | Separate from app state | Lives in your main tree      |
+| **DevTools**         | Separate                | Inherits tree DevTools       |
+| **Composability**    | Limited                 | Add enhancers freely         |
+| **Tree-shaking**     | All-or-nothing          | Only what you use            |
+
+### Migration steps
+
+1. Move form state into your SignalTree using `form()` marker
+2. Add `.with(formBridge())` to your tree
+3. Update access patterns: `form.$.field` → `tree.$.formName.$.field`
+4. Update FormGroup access: `form.form` → `tree.getAngularForm('path')?.formGroup`
+
 ## Links
 
 - [SignalTree Documentation](https://signaltree.io)

package/dist/enhancer/form-bridge.js

@@ -0,0 +1,194 @@
+import { inject, DestroyRef, computed } from '@angular/core';
+import { FormControl, FormArray, FormGroup } from '@angular/forms';
+
+function findFormSignals(node, path, results) {
+  if (node === null || node === undefined) return;
+  const hasForm = (typeof node === 'function' || typeof node === 'object') && node !== null && '$' in node && 'valid' in node && 'dirty' in node && 'validate' in node;
+  if (hasForm && typeof node.validate === 'function') {
+    results.push({
+      path,
+      formSignal: node
+    });
+    return;
+  }
+  if (typeof node === 'function' || typeof node === 'object') {
+    const entries = Object.entries(node);
+    for (const [key, value] of entries) {
+      if (key.startsWith('_') || key === 'set' || key === 'update') continue;
+      const childPath = path ? `${path}.${key}` : key;
+      findFormSignals(value, childPath, results);
+    }
+  }
+}
+function createFormGroupBridge(formSignal, config, cleanupCallbacks) {
+  const values = formSignal();
+  const formGroup = createFormGroupFromValues(values, config.fieldConfigs || {});
+  const angularErrors = computed(() => {
+    const result = {};
+    collectControlErrors(formGroup, '', result);
+    return result;
+  });
+  const asyncPending = computed(() => formGroup.pending);
+  const syncSignalToControl = () => {
+    const currentValues = formSignal();
+    patchFormGroupValues(formGroup, currentValues);
+  };
+  const syncControlToSignal = () => {
+    const formValues = formGroup.getRawValue();
+    formSignal.set(formValues);
+  };
+  const subscription = formGroup.valueChanges.subscribe(() => {
+    syncControlToSignal();
+  });
+  cleanupCallbacks.push(() => subscription.unsubscribe());
+  syncSignalToControl();
+  if (config.conditionals && config.conditionals.length > 0) {
+    const conditionalState = new Map();
+    const applyConditionals = () => {
+      const values = formGroup.getRawValue();
+      for (const {
+        when,
+        fields
+      } of config.conditionals) {
+        let visible = true;
+        try {
+          visible = when(values);
+        } catch {
+          visible = true;
+        }
+        for (const fieldPath of fields) {
+          const control = formGroup.get(fieldPath);
+          if (!control) continue;
+          const previous = conditionalState.get(fieldPath);
+          if (previous === visible) continue;
+          conditionalState.set(fieldPath, visible);
+          if (visible) {
+            control.enable({
+              emitEvent: true
+            });
+          } else {
+            control.disable({
+              emitEvent: false
+            });
+          }
+        }
+      }
+    };
+    applyConditionals();
+    const condSub = formGroup.valueChanges.subscribe(() => applyConditionals());
+    cleanupCallbacks.push(() => condSub.unsubscribe());
+  }
+  return {
+    formGroup,
+    formControl: path => {
+      const control = formGroup.get(path);
+      return control instanceof FormControl ? control : null;
+    },
+    angularErrors,
+    asyncPending
+  };
+}
+function createFormGroupFromValues(values, fieldConfigs, basePath = '') {
+  const controls = {};
+  for (const [key, value] of Object.entries(values)) {
+    const path = basePath ? `${basePath}.${key}` : key;
+    const fieldConfig = fieldConfigs[path] || {};
+    if (Array.isArray(value)) {
+      const arrayControls = value.map((item, index) => {
+        if (typeof item === 'object' && item !== null) {
+          return createFormGroupFromValues(item, fieldConfigs, `${path}.${index}`);
+        }
+        return new FormControl(item);
+      });
+      controls[key] = new FormArray(arrayControls);
+    } else if (typeof value === 'object' && value !== null) {
+      controls[key] = createFormGroupFromValues(value, fieldConfigs, path);
+    } else {
+      const validators = fieldConfig.validators ? Array.isArray(fieldConfig.validators) ? fieldConfig.validators : [fieldConfig.validators] : [];
+      const asyncValidators = fieldConfig.asyncValidators ? Array.isArray(fieldConfig.asyncValidators) ? fieldConfig.asyncValidators : [fieldConfig.asyncValidators] : [];
+      controls[key] = new FormControl(value, {
+        validators,
+        asyncValidators
+      });
+    }
+  }
+  return new FormGroup(controls);
+}
+function patchFormGroupValues(group, values, basePath) {
+  for (const [key, value] of Object.entries(values)) {
+    const control = group.get(key);
+    if (!control) continue;
+    if (control instanceof FormGroup && typeof value === 'object' && value !== null) {
+      patchFormGroupValues(control, value);
+    } else if (control instanceof FormArray && Array.isArray(value)) {
+      control.clear({
+        emitEvent: false
+      });
+      for (const item of value) {
+        if (typeof item === 'object' && item !== null) {
+          control.push(createFormGroupFromValues(item, {}));
+        } else {
+          control.push(new FormControl(item));
+        }
+      }
+    } else {
+      control.setValue(value, {
+        emitEvent: false
+      });
+    }
+  }
+}
+function collectControlErrors(control, path, result) {
+  if (control.errors) {
+    result[path || 'root'] = control.errors;
+  }
+  if (control instanceof FormGroup) {
+    for (const [key, child] of Object.entries(control.controls)) {
+      collectControlErrors(child, path ? `${path}.${key}` : key, result);
+    }
+  } else if (control instanceof FormArray) {
+    control.controls.forEach((child, index) => {
+      collectControlErrors(child, `${path}.${index}`, result);
+    });
+  }
+}
+function formBridge(config = {}) {
+  return tree => {
+    const cleanupCallbacks = [];
+    const formBridgeMap = new Map();
+    const formLocations = [];
+    findFormSignals(tree.$, '', formLocations);
+    for (const {
+      path,
+      formSignal
+    } of formLocations) {
+      const bridge = createFormGroupBridge(formSignal, config, cleanupCallbacks);
+      formBridgeMap.set(path, bridge);
+      formSignal['formGroup'] = bridge.formGroup;
+      formSignal['formControl'] = bridge.formControl;
+      formSignal['angularErrors'] = bridge.angularErrors;
+      formSignal['asyncPending'] = bridge.asyncPending;
+    }
+    const destroyRef = config.destroyRef ?? tryInjectDestroyRef();
+    if (destroyRef) {
+      destroyRef.onDestroy(() => {
+        cleanupCallbacks.forEach(fn => fn());
+      });
+    }
+    const enhanced = tree;
+    enhanced.formBridge = formBridgeMap;
+    enhanced.getAngularForm = function (path) {
+      return formBridgeMap.get(path) ?? null;
+    };
+    return enhanced;
+  };
+}
+function tryInjectDestroyRef() {
+  try {
+    return inject(DestroyRef);
+  } catch {
+    return undefined;
+  }
+}
+
+export { formBridge };

package/dist/enhancer/index.js

@@ -0,0 +1,2 @@
+export { formBridge } from './form-bridge.js';
+export { FORM_MARKER, isFormMarker } from '@signaltree/core';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './core/ng-forms.js';
 export * from './core/validators.js';
 export * from './core/async-validators.js';
 export * from './history/index.js';
+export * from './enhancer/index.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/ng-forms",
-  "version": "7.1.3",
-  "description": "Complete Angular forms integration for SignalTree. FormTree creation, custom directives, validators, form state tracking, and RxJS bridge.",
+  "version": "7.3.0",
+  "description": "Angular forms as reactive JSON. Seamless SignalTree integration with FormTree creation, validators, and form state tracking.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,

package/src/enhancer/form-bridge.d.ts

@@ -0,0 +1,30 @@
+import { DestroyRef, Signal } from '@angular/core';
+import { AsyncValidatorFn, FormControl, FormGroup, ValidationErrors, ValidatorFn } from '@angular/forms';
+import { ISignalTree } from '@signaltree/core';
+export interface AngularConditionalField<T = unknown> {
+    when: (values: T) => boolean;
+    fields: string[];
+}
+export interface AngularFieldConfig {
+    debounceMs?: number;
+    validators?: ValidatorFn | ValidatorFn[];
+    asyncValidators?: AsyncValidatorFn | AsyncValidatorFn[];
+}
+export interface AngularFormsConfig<T = unknown> {
+    conditionals?: AngularConditionalField<T>[];
+    fieldConfigs?: Record<string, AngularFieldConfig>;
+    destroyRef?: DestroyRef;
+    validationBatchMs?: number;
+}
+export interface AngularFormBridge<T extends Record<string, unknown>> {
+    formGroup: FormGroup;
+    formControl(path: string): FormControl | null;
+    angularErrors: Signal<Record<string, ValidationErrors | null>>;
+    asyncPending: Signal<boolean>;
+}
+export interface AngularFormsMethods {
+    getAngularForm<T extends Record<string, unknown>>(path: string): AngularFormBridge<T> | null;
+    formBridge: Map<string, AngularFormBridge<Record<string, unknown>>>;
+}
+export declare function formBridge<TConfig = unknown>(config?: AngularFormsConfig<TConfig>): <T>(tree: ISignalTree<T>) => ISignalTree<T> & AngularFormsMethods;
+export { FORM_MARKER, isFormMarker } from '@signaltree/core';

package/src/enhancer/index.d.ts

@@ -0,0 +1 @@
+export * from './form-bridge';

package/src/index.d.ts

@@ -2,3 +2,4 @@ export * from './core/ng-forms';
 export * from './core/validators';
 export * from './core/async-validators';
 export * from './history';
+export * from './enhancer';

package/dist/audit/audit.js

@@ -1,74 +0,0 @@
-import { getChanges } from '../get-changes.js';
-
-function createAuditTracker(tree, auditLog, config = {}) {
-  const {
-    getMetadata,
-    includePreviousValues = false,
-    filter,
-    maxEntries = 0
-  } = config;
-  let previousState = structuredClone(tree());
-  let isTracking = true;
-  const handleChange = () => {
-    if (!isTracking) return;
-    const currentState = tree();
-    const changes = getChanges(previousState, currentState);
-    if (Object.keys(changes).length > 0) {
-      if (filter && !filter(changes)) {
-        previousState = structuredClone(currentState);
-        return;
-      }
-      const entry = {
-        timestamp: Date.now(),
-        changes,
-        metadata: getMetadata?.()
-      };
-      if (includePreviousValues) {
-        const prevValues = {};
-        for (const key of Object.keys(changes)) {
-          prevValues[key] = previousState[key];
-        }
-        entry.previousValues = prevValues;
-      }
-      auditLog.push(entry);
-      if (maxEntries > 0 && auditLog.length > maxEntries) {
-        auditLog.splice(0, auditLog.length - maxEntries);
-      }
-    }
-    previousState = structuredClone(currentState);
-  };
-  let unsubscribe;
-  let pollingId;
-  if ('subscribe' in tree && typeof tree.subscribe === 'function') {
-    try {
-      unsubscribe = tree.subscribe(handleChange);
-    } catch {
-      pollingId = setInterval(handleChange, 100);
-    }
-  } else {
-    pollingId = setInterval(handleChange, 100);
-  }
-  return () => {
-    isTracking = false;
-    if (unsubscribe) {
-      unsubscribe();
-    }
-    if (pollingId) {
-      clearInterval(pollingId);
-    }
-  };
-}
-function createAuditCallback(auditLog, getMetadata) {
-  return (previousState, currentState) => {
-    const changes = getChanges(previousState, currentState);
-    if (Object.keys(changes).length > 0) {
-      auditLog.push({
-        timestamp: Date.now(),
-        changes,
-        metadata: getMetadata?.()
-      });
-    }
-  };
-}
-
-export { createAuditCallback, createAuditTracker };

package/dist/audit/index.js

@@ -1 +0,0 @@
-export { createAuditCallback, createAuditTracker } from './audit.js';

package/dist/get-changes.js

@@ -1,11 +0,0 @@
-function getChanges(oldState, newState) {
-  const changes = {};
-  for (const key in newState) {
-    if (oldState[key] !== newState[key]) {
-      changes[key] = newState[key];
-    }
-  }
-  return changes;
-}
-
-export { getChanges };