@signaltree/ng-forms 4.1.2 → 4.1.4

package/README.md

@@ -1,16 +1,89 @@
 # @signaltree/ng-forms
 
-Angular 20 signal forms meet SignalTree. `@signaltree/ng-forms` keeps your form state, validation, persistence, and wizard flows in sync with the rest of your application signals—no manual plumbing.
+**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.
 
 **Bundle size: 3.38KB gzipped**
 
+## Why ng-forms?
+
+Angular 21 introduced native signal forms with `FormField<T>`, which work great for simple, flat forms. **ng-forms is for complex forms** that need:
+
+### **🌲 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
+```
+
+### **🧙 Wizard & Multi-Step Forms**
+```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
+```
+
+### **↩️ History / Undo-Redo**
+```typescript
+// Angular 21: Not available
+// ng-forms: Built-in
+const form = withFormHistory(createFormTree(initialState));
+form.undo();
+form.redo();
+```
+
+### **🔗 Reactive Forms Bridge**
+```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
+```
+
+### **⚙️ Declarative Configuration**
+```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() }
+}
+```
+
+**Use Angular 21 signal forms for simple forms. Use ng-forms for enterprise apps with complex state, persistence, and workflow requirements.**
+
 ## Installation
 
 ```bash
 pnpm add @signaltree/core @signaltree/ng-forms
 ```
 
-> This package supports Angular 17+ with TypeScript 5.5+. Angular 17-19 support uses a legacy bridge that will be deprecated when Angular 21 is released. For the best experience, upgrade to Angular 20.3+ to use native Signal Forms.
+> **Compatibility**: Angular 17+ with TypeScript 5.5+. Angular 21+ recommended for best experience. Works alongside Angular's native signal forms—use both where appropriate.
 
 ## Quick start
 
@@ -97,30 +170,58 @@ The returned `FormTree` exposes:
 - **Signal ↔ Observable bridge**: Convert signals to RxJS streams for interoperability
 - **Template-driven adapter**: `SignalValueDirective` bridges standalone signals with `ngModel`
 
-## Signal Forms (Angular 20+)
+## Angular 21 Interoperability
 
-`@signaltree/ng-forms` now prefers Angular's experimental Signal Forms `connect()` API when available.
+**ng-forms complements Angular 21's native signal forms**—use both in the same app:
 
-- Leaves in a SignalTree are native `WritableSignal<T>` and can be connected directly
-- For object slices, convert to a `WritableSignal<T>` via `toWritableSignal()` from `@signaltree/core`
+### Use Angular 21 `FormField<T>` for:
+- ✅ Simple, flat forms (login, search)
+- ✅ Single-field validation
+- ✅ Maximum type safety
 
-```ts
-import { toWritableSignal } from '@signaltree/core';
+### Use ng-forms `createFormTree()` for:
+- ✅ Nested object structures (user + address + payment)
+- ✅ Forms with persistence/auto-save
+- ✅ Wizard/multi-step flows
+- ✅ History/undo requirements
+- ✅ Complex conditional logic
+- ✅ Migration from reactive forms
 
-const values = createFormTree({
-  user: { name: '', email: '' },
-});
-
-// Connect leaves directly
-nameControl.connect(values.$.user.name);
-emailControl.connect(values.$.user.email);
+### Hybrid Example: Simple Fields + Complex Tree
+```typescript
+import { formField } from '@angular/forms';
+import { createFormTree } from '@signaltree/ng-forms';
+
+@Component({...})
+class CheckoutComponent {
+  // Simple field: Use Angular 21 native
+  promoCode = formField('');
+
+  // Complex nested state: Use ng-forms
+  checkout = createFormTree({
+    shipping: { name: '', address: '', city: '', zip: '' },
+    payment: { card: '', cvv: '', expiry: '' },
+    items: [] as CartItem[]
+  }, {
+    persistKey: 'checkout-draft',
+    fieldConfigs: {
+      'shipping.zip': { validators: validators.zipCode() },
+      'payment.card': { validators: validators.creditCard(), debounceMs: 300 }
+    }
+  });
 
-// Or connect a whole slice
-const userSignal = toWritableSignal(values.values.$.user);
-userGroupControl.connect(userSignal);
+  // Both work together seamlessly
+}
 ```
 
-Angular 20.3+ is preferred for native Signal Forms `connect()`. Angular 17-19 is supported via a legacy bridge that will be deprecated when Angular 21 is released.
+### Connecting to Reactive Forms
+```ts
+import { toWritableSignal } from '@signaltree/core';
+
+// Convert ng-forms signals to work with Angular's .connect()
+const nameSignal = toWritableSignal(formTree.$.user.name);
+reactiveControl.connect(nameSignal);
+```
 
 ## Form tree configuration
 
@@ -222,16 +323,27 @@ History tracking works at the FormGroup level so it plays nicely with external u
 
 Use `SignalValueDirective` to keep standalone signals and `ngModel` fields aligned in legacy sections while new pages migrate to forms-first APIs.
 
-## When to reach for ng-forms
+## 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) |
 
-- Complex Angular forms that need to remain in sync with SignalTree application state
-- Workflows that require persistence, auto-save, or offline drafts
-- Multi-step wizards or surveys with dynamic branching
-- Applications that benefit from first-class signal APIs around Angular forms
+**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.
 
 ## Links
 
 - [SignalTree Documentation](https://signaltree.io)
+- [Angular 21 Migration Guide](./ANGULAR21-MIGRATION.md)
 - [Core Package](https://www.npmjs.com/package/@signaltree/core)
 - [GitHub Repository](https://github.com/JBorgia/signaltree)
 - [Demo Application](https://signaltree.io/examples)

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@signaltree/ng-forms",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "Complete Angular forms integration for SignalTree. FormTree creation, custom directives, validators, form state tracking, and RxJS bridge.",
   "peerDependencies": {
     "@angular/core": "^20.3.0",
     "@angular/forms": "^20.3.0",
-    "@signaltree/core": "4.1.2",
+    "@signaltree/core": "4.1.4",
     "rxjs": "^7.0.0"
   },
   "sideEffects": false,
@@ -43,4 +43,4 @@
   "dependencies": {
     "tslib": "^2.3.0"
   }
-}
+}

package/LICENSE

@@ -1,54 +0,0 @@
-BUSINESS SOURCE LICENSE 1.1
-
-Copyright (c) 2025 Jonathan D Borgia
-
-This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
-
-1. Definitions
-
-"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
-
-"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
-
-"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
-
-"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
-
-2. License Grant
-
-Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
-
-3. Commercial Use
-
-You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
-
-4. Limitations and Conditions
-
-a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
-
-b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
-
-c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
-
-5. Disclaimer and Limitation of Liability
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
-
-6. Change License
-
-On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
-
-7. Governing Law
-
-This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
-
-8. Accepting this License
-
-You accept this License by copying, modifying, or distributing the Software or any portion thereof.
-
----
-
-LICENSE NOTE
-
-- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
-  or standard modifications for your own applications.