@ng-forge/dynamic-form-mcp 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +1 -1
  2. package/bin/ng-forge-mcp.js +1782 -283
  3. package/package.json +7 -7
  4. package/src/index.js +1782 -283
  5. package/src/registry/api-reference.json +76 -25
  6. package/src/registry/docs.json +52 -16
  7. package/src/registry/field-types.json +18 -6
  8. package/src/registry/instructions.d.ts +1 -1
  9. package/src/registry/instructions.d.ts.map +1 -1
  10. package/src/registry/validators.json +56 -4
  11. package/src/tools/data/lookup-topics.d.ts.map +1 -1
  12. package/src/tools/examples.tool.d.ts.map +1 -1
  13. package/src/tools/lookup.tool.d.ts.map +1 -1
  14. package/src/tools/scaffold.tool.d.ts.map +1 -1
  15. package/src/tools/validate.tool.d.ts.map +1 -1
package/src/index.js CHANGED
@@ -17,13 +17,13 @@ var require_docs = __commonJS({
17
17
  id: "advanced-events",
18
18
  title: "Advanced Events",
19
19
  category: "advanced",
20
- content: "The event bus enables communication between the `dynamic-form` component and custom field components within it. Each form instance has its own isolated event bus.\n\n## Overview\n\nThe event bus provides:\n\n- Communication between field components within a single form\n- Type-safe event subscriptions\n- Reactive event handling with RxJS\n- Wizard page navigation coordination\n- Custom field component workflows\n\n**Note**: The event bus is scoped to each `dynamic-form` instance - events don't cross form boundaries.\n\n## Usage in Custom Field Components\n\nWhen building custom field types, inject the event bus to communicate with the parent form or other fields:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { EventBus } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-custom-submit-button',\n template: `<button (click)=\"submit()\">Submit Form</button>`,\n})\nexport class CustomSubmitButton {\n eventBus = inject(EventBus);\n\n submit() {\n // Dispatch submit event to the parent dynamic-forms\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```\n\n## Built-in Events\n\n### SubmitEvent\n\nFired when form is submitted.\n\n```typescript\neventBus.on<SubmitEvent>('submit').subscribe(() => {\n // Handle form submission\n console.log('Form submitted');\n});\n```\n\n### PageChangeEvent\n\nFired when navigating between wizard pages.\n\n```typescript\neventBus.on<PageChangeEvent>('page-change').subscribe((event) => {\n console.log(`Page ${event.currentPageIndex + 1} of ${event.totalPages}`);\n console.log(`Previous page: ${event.previousPageIndex}`);\n});\n```\n\n**Properties:**\n\n- `currentPageIndex: number` - Current page (0-based)\n- `totalPages: number` - Total number of pages\n- `previousPageIndex?: number` - Previous page index\n\n### NextPageEvent\n\nNavigate to next page in wizard.\n\n```typescript\neventBus.dispatch(NextPageEvent);\n```\n\n### PreviousPageEvent\n\nNavigate to previous page in wizard.\n\n```typescript\neventBus.dispatch(PreviousPageEvent);\n```\n\n### FormResetEvent\n\nReset form to default values.\n\n```typescript\n// Dispatch reset event\neventBus.dispatch(FormResetEvent);\n\n// Listen for reset\neventBus.on<FormResetEvent>('form-reset').subscribe(() => {\n console.log('Form was reset to defaults');\n});\n```\n\n### FormClearEvent\n\nClear all form values (empty state, not defaults).\n\n```typescript\n// Dispatch clear event\neventBus.dispatch(FormClearEvent);\n\n// Listen for clear\neventBus.on<FormClearEvent>('form-clear').subscribe(() => {\n console.log('Form was cleared');\n});\n```\n\n### AddArrayItemEvent\n\nAdd an item to an array field.\n\n```typescript\n// Add item using array's template\neventBus.dispatch(AddArrayItemEvent, 'contacts');\n\n// Add item with custom field template\nconst fieldTemplate = { key: 'email', type: 'input', value: '' };\neventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate);\n\n// Add item at specific index\neventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate, 2);\n```\n\n**Constructor parameters:**\n\n- `arrayKey: string` - Key of the array field\n- `field?: ArrayAllowedChildren` - Optional field template (uses array's template if omitted)\n- `index?: number` - Optional index to insert at (defaults to end)\n\n### RemoveArrayItemEvent\n\nRemove an item from an array field.\n\n```typescript\n// Remove item at index 1\neventBus.dispatch(RemoveArrayItemEvent, 'contacts', 1);\n\n// Remove last item\neventBus.dispatch(RemoveArrayItemEvent, 'contacts');\n```\n\n**Constructor parameters:**\n\n- `arrayKey: string` - Key of the array field\n- `index?: number` - Index to remove (defaults to last item)\n\n## Multiple Event Subscriptions\n\nSubscribe to multiple event types by passing an array of type strings:\n\n```typescript\neventBus.on<SubmitEvent | PageChangeEvent | NextPageEvent>(['submit', 'page-change', 'next-page']).subscribe((event) => {\n switch (event.type) {\n case 'submit':\n handleSubmit();\n break;\n case 'page-change':\n handlePageChange(event);\n break;\n case 'next-page':\n handleNextPage();\n break;\n }\n});\n```\n\n## Custom Events\n\nCreate custom events for your forms:\n\n```typescript\nimport { FormEvent } from '@ng-forge/dynamic-forms';\n\n// Simple event\nexport class SaveDraftEvent implements FormEvent {\n readonly type = 'save-draft' as const;\n}\n\n// Event with payload\nexport class ValidationErrorEvent implements FormEvent {\n readonly type = 'validation-error' as const;\n\n constructor(\n public readonly fieldKey: string,\n public readonly errorMessage: string,\n ) {}\n}\n```\n\nUsage:\n\n```typescript\n// Dispatch simple event\neventBus.dispatch(SaveDraftEvent);\n\n// Dispatch event with payload\neventBus.dispatch(ValidationErrorEvent, 'email', 'Invalid email format');\n\n// Subscribe to custom event\neventBus.on<SaveDraftEvent>('save-draft').subscribe(() => {\n saveDraft();\n});\n\neventBus.on<ValidationErrorEvent>('validation-error').subscribe((event) => {\n showError(event.fieldKey, event.errorMessage);\n});\n```\n\n## Practical Examples\n\n### Form Auto-save\n\n```typescript\n@Component({...})\nexport class AutoSaveFormComponent {\n eventBus = inject(EventBus);\n\n ngOnInit() {\n // Auto-save on page change\n this.eventBus.on<PageChangeEvent>('page-change').subscribe(() => {\n this.saveDraft();\n });\n }\n\n saveDraft() {\n // Save form data\n }\n}\n```\n\n### Multi-step Form Navigation\n\n```typescript\n@Component({\n template: `\n <button (click)=\"previous()\">Previous</button>\n <button (click)=\"next()\">Next</button>\n <button (click)=\"submit()\">Submit</button>\n `,\n})\nexport class WizardNavigationComponent {\n eventBus = inject(EventBus);\n\n previous() {\n this.eventBus.dispatch(PreviousPageEvent);\n }\n\n next() {\n this.eventBus.dispatch(NextPageEvent);\n }\n\n submit() {\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```\n\n### Progress Tracking\n\n```typescript\n@Component({...})\nexport class ProgressTrackerComponent {\n eventBus = inject(EventBus);\n progress = signal(0);\n\n ngOnInit() {\n this.eventBus.on<PageChangeEvent>('page-change').subscribe((event) => {\n const percentage = ((event.currentPageIndex + 1) / event.totalPages) * 100;\n this.progress.set(percentage);\n });\n }\n}\n```\n\n### Form Reset and Clear\n\n```typescript\n@Component({...})\nexport class FormActionsComponent {\n eventBus = inject(EventBus);\n\n resetForm() {\n // Reset form to default values\n this.eventBus.dispatch(FormResetEvent);\n }\n\n clearForm() {\n // Clear all form values\n this.eventBus.dispatch(FormClearEvent);\n }\n}\n```\n\n## Best Practices\n\n**Use built-in events:**\n\n- Leverage existing events for common scenarios\n- Consistent behavior across forms\n\n**Create custom events for domain logic:**\n\n- Keep event names descriptive\n- Include necessary payload data\n- Use readonly properties\n\n**Type safety:**\n\n```typescript\n// \u2713 Type-safe event subscription\nclass UserUpdatedEvent implements FormEvent {\n readonly type = 'user-updated' as const;\n constructor(public readonly userId: string) {}\n}\n\n// \u2713 Use generic parameter for type inference\neventBus.on<UserUpdatedEvent>('user-updated').subscribe((event) => {\n console.log(event.userId); // TypeScript knows event has userId\n});\n\n// \u2717 Avoid subscriptions without generic type parameter\neventBus.on('some-random-event'); // No type checking on event properties\n```\n\n## Attaching Form Values to Events\n\nBy default, events don't include the form's current value. You can opt-in to automatically attach the form value to all dispatched events using `withEventFormValue()`.\n\n### Global Opt-in\n\nEnable for all forms in your application:\n\n```typescript\nimport { provideDynamicForm, withEventFormValue } from '@ng-forge/dynamic-forms';\n\nprovideDynamicForm(...withMaterialFields(), withEventFormValue());\n```\n\n### Per-Form Control\n\nOverride the global setting for specific forms:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n // Enable for this form (even if globally disabled)\n emitFormValueOnEvents: true,\n // Or disable for this form (even if globally enabled)\n // emitFormValueOnEvents: false,\n }\n};\n```\n\n### Accessing the Form Value\n\nUse the `hasFormValue()` type guard to safely access the attached value:\n\n```typescript\nimport { hasFormValue } from '@ng-forge/dynamic-forms';\n\neventBus.on<SubmitEvent>('submit').subscribe((event) => {\n if (hasFormValue(event)) {\n // TypeScript knows event.formValue exists\n console.log('Form value at submission:', event.formValue);\n sendToApi(event.formValue);\n }\n});\n```\n\nThis is useful when you need the complete form state at the time an event occurred, such as:\n\n- Logging form values on submission\n- Auto-saving on page changes\n- Analytics tracking\n\n## Event Flow\n\n1. Component dispatches event via `eventBus.dispatch()`\n2. Event bus broadcasts to all subscribers\n3. Subscribers receive event and execute handlers\n4. Type filtering ensures only relevant handlers execute\n\n## Integration with Forms\n\nThe event bus is automatically provided by the `DynamicForm` component to all child field components. You don't need to manually provide it:\n\n```typescript\n// The DynamicForm component internally provides EventBus\n// All child field components can inject and use it\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-my-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\"></form>`,\n})\nexport class MyFormComponent {\n // EventBus is available to all field components rendered by DynamicForm\n}\n```\n\nField components can inject and use the event bus:\n\n```typescript\nexport class CustomFieldComponent extends BaseFieldComponent {\n eventBus = inject(EventBus);\n\n onSubmit() {\n // Trigger form submission from custom component\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```"
20
+ content: "The event bus enables communication between the `dynamic-form` component and custom field components within it. Each form instance has its own isolated event bus.\n\n## Overview\n\nThe event bus provides:\n\n- Communication between field components within a single form\n- Type-safe event subscriptions\n- Reactive event handling with RxJS\n- Wizard page navigation coordination\n- Custom field component workflows\n\n**Note**: The event bus is scoped to each `dynamic-form` instance - events don't cross form boundaries.\n\n## Usage in Custom Field Components\n\nWhen building custom field types, inject the event bus to communicate with the parent form or other fields:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { EventBus } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-custom-submit-button',\n template: `<button (click)=\"submit()\">Submit Form</button>`,\n})\nexport class CustomSubmitButton {\n eventBus = inject(EventBus);\n\n submit() {\n // Dispatch submit event to the parent dynamic-forms\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```\n\n## Built-in Events\n\n### SubmitEvent\n\nFired when form is submitted.\n\n```typescript\neventBus.on<SubmitEvent>('submit').subscribe(() => {\n // Handle form submission\n console.log('Form submitted');\n});\n```\n\n### PageChangeEvent\n\nFired when navigating between wizard pages.\n\n```typescript\neventBus.on<PageChangeEvent>('page-change').subscribe((event) => {\n console.log(`Page ${event.currentPageIndex + 1} of ${event.totalPages}`);\n console.log(`Previous page: ${event.previousPageIndex}`);\n});\n```\n\n**Properties:**\n\n- `currentPageIndex: number` - Current page (0-based)\n- `totalPages: number` - Total number of pages\n- `previousPageIndex?: number` - Previous page index\n\n### NextPageEvent\n\nNavigate to next page in wizard.\n\n```typescript\neventBus.dispatch(NextPageEvent);\n```\n\n### PreviousPageEvent\n\nNavigate to previous page in wizard.\n\n```typescript\neventBus.dispatch(PreviousPageEvent);\n```\n\n### FormResetEvent\n\nReset form to default values.\n\n```typescript\n// Dispatch reset event\neventBus.dispatch(FormResetEvent);\n\n// Listen for reset\neventBus.on<FormResetEvent>('form-reset').subscribe(() => {\n console.log('Form was reset to defaults');\n});\n```\n\n### FormClearEvent\n\nClear all form values (empty state, not defaults).\n\n```typescript\n// Dispatch clear event\neventBus.dispatch(FormClearEvent);\n\n// Listen for clear\neventBus.on<FormClearEvent>('form-clear').subscribe(() => {\n console.log('Form was cleared');\n});\n```\n\n### Array Events\n\nThe `arrayEvent()` builder provides a fluent API for array field manipulation. Import it from the main package:\n\n```typescript\nimport { arrayEvent } from '@ng-forge/dynamic-forms';\n```\n\n#### Adding Items\n\n**Important:** A template is required for all add operations. The template defines the structure of the new item:\n\n- **Single FieldDef** \u2192 creates a **primitive item** (field value extracted directly)\n- **Array of FieldDefs** \u2192 creates an **object item** (fields merged into object)\n\n```typescript\n// Define templates\nconst tagTemplate = { key: 'tag', type: 'input', label: 'Tag' }; // Primitive item\nconst contactTemplate = [\n // Object item\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'email', type: 'input', label: 'Email' },\n];\n\n// Append item at end (most common)\neventBus.dispatch(arrayEvent('tags').append(tagTemplate)); // Primitive: adds a string value\neventBus.dispatch(arrayEvent('contacts').append(contactTemplate)); // Object: adds { name, email }\n\n// Prepend item at beginning\neventBus.dispatch(arrayEvent('contacts').prepend(contactTemplate));\n\n// Insert at specific index\neventBus.dispatch(arrayEvent('contacts').insertAt(2, contactTemplate));\n```\n\n#### Removing Items\n\n```typescript\n// Remove last item (stack pop)\neventBus.dispatch(arrayEvent('contacts').pop());\n\n// Remove first item (queue shift)\neventBus.dispatch(arrayEvent('contacts').shift());\n\n// Remove item at specific index\neventBus.dispatch(arrayEvent('contacts').removeAt(2));\n```\n\n#### Internal Event Classes\n\nFor advanced use cases (extending events or type-checking), you can import the underlying event classes:\n\n```typescript\nimport {\n AppendArrayItemEvent,\n PrependArrayItemEvent,\n InsertArrayItemEvent,\n PopArrayItemEvent,\n ShiftArrayItemEvent,\n RemoveAtIndexEvent,\n} from '@ng-forge/dynamic-forms';\n\n// Example: extend for custom template\nexport class AddContactEvent extends AppendArrayItemEvent {\n constructor() {\n super('contacts', [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'phone', type: 'input', label: 'Phone' },\n ]);\n }\n}\n\n// Usage\neventBus.dispatch(new AddContactEvent());\n```\n\n**Event types:**\n\n| Event | Description |\n| ----------------------- | ------------------------------ |\n| `AppendArrayItemEvent` | Add item at end of array |\n| `PrependArrayItemEvent` | Add item at beginning of array |\n| `InsertArrayItemEvent` | Add item at specific index |\n| `PopArrayItemEvent` | Remove last item |\n| `ShiftArrayItemEvent` | Remove first item |\n| `RemoveAtIndexEvent` | Remove item at specific index |\n\n## Multiple Event Subscriptions\n\nSubscribe to multiple event types by passing an array of type strings:\n\n```typescript\neventBus.on<SubmitEvent | PageChangeEvent | NextPageEvent>(['submit', 'page-change', 'next-page']).subscribe((event) => {\n switch (event.type) {\n case 'submit':\n handleSubmit();\n break;\n case 'page-change':\n handlePageChange(event);\n break;\n case 'next-page':\n handleNextPage();\n break;\n }\n});\n```\n\n## Custom Events\n\nCreate custom events for your forms:\n\n```typescript\nimport { FormEvent } from '@ng-forge/dynamic-forms';\n\n// Simple event\nexport class SaveDraftEvent implements FormEvent {\n readonly type = 'save-draft' as const;\n}\n\n// Event with payload\nexport class ValidationErrorEvent implements FormEvent {\n readonly type = 'validation-error' as const;\n\n constructor(\n public readonly fieldKey: string,\n public readonly errorMessage: string,\n ) {}\n}\n```\n\nUsage:\n\n```typescript\n// Dispatch simple event\neventBus.dispatch(SaveDraftEvent);\n\n// Dispatch event with payload\neventBus.dispatch(ValidationErrorEvent, 'email', 'Invalid email format');\n\n// Subscribe to custom event\neventBus.on<SaveDraftEvent>('save-draft').subscribe(() => {\n saveDraft();\n});\n\neventBus.on<ValidationErrorEvent>('validation-error').subscribe((event) => {\n showError(event.fieldKey, event.errorMessage);\n});\n```\n\n## Practical Examples\n\n### Form Auto-save\n\n```typescript\n@Component({...})\nexport class AutoSaveFormComponent {\n eventBus = inject(EventBus);\n\n ngOnInit() {\n // Auto-save on page change\n this.eventBus.on<PageChangeEvent>('page-change').subscribe(() => {\n this.saveDraft();\n });\n }\n\n saveDraft() {\n // Save form data\n }\n}\n```\n\n### Multi-step Form Navigation\n\n```typescript\n@Component({\n template: `\n <button (click)=\"previous()\">Previous</button>\n <button (click)=\"next()\">Next</button>\n <button (click)=\"submit()\">Submit</button>\n `,\n})\nexport class WizardNavigationComponent {\n eventBus = inject(EventBus);\n\n previous() {\n this.eventBus.dispatch(PreviousPageEvent);\n }\n\n next() {\n this.eventBus.dispatch(NextPageEvent);\n }\n\n submit() {\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```\n\n### Progress Tracking\n\n```typescript\n@Component({...})\nexport class ProgressTrackerComponent {\n eventBus = inject(EventBus);\n progress = signal(0);\n\n ngOnInit() {\n this.eventBus.on<PageChangeEvent>('page-change').subscribe((event) => {\n const percentage = ((event.currentPageIndex + 1) / event.totalPages) * 100;\n this.progress.set(percentage);\n });\n }\n}\n```\n\n### Form Reset and Clear\n\n```typescript\n@Component({...})\nexport class FormActionsComponent {\n eventBus = inject(EventBus);\n\n resetForm() {\n // Reset form to default values\n this.eventBus.dispatch(FormResetEvent);\n }\n\n clearForm() {\n // Clear all form values\n this.eventBus.dispatch(FormClearEvent);\n }\n}\n```\n\n## Best Practices\n\n**Use built-in events:**\n\n- Leverage existing events for common scenarios\n- Consistent behavior across forms\n\n**Create custom events for domain logic:**\n\n- Keep event names descriptive\n- Include necessary payload data\n- Use readonly properties\n\n**Type safety:**\n\n```typescript\n// \u2713 Type-safe event subscription\nclass UserUpdatedEvent implements FormEvent {\n readonly type = 'user-updated' as const;\n constructor(public readonly userId: string) {}\n}\n\n// \u2713 Use generic parameter for type inference\neventBus.on<UserUpdatedEvent>('user-updated').subscribe((event) => {\n console.log(event.userId); // TypeScript knows event has userId\n});\n\n// \u2717 Avoid subscriptions without generic type parameter\neventBus.on('some-random-event'); // No type checking on event properties\n```\n\n## Attaching Form Values to Events\n\nBy default, events don't include the form's current value. You can opt-in to automatically attach the form value to all dispatched events using `withEventFormValue()`.\n\n### Global Opt-in\n\nEnable for all forms in your application:\n\n```typescript\nimport { provideDynamicForm, withEventFormValue } from '@ng-forge/dynamic-forms';\n\nprovideDynamicForm(...withMaterialFields(), withEventFormValue());\n```\n\n### Per-Form Control\n\nOverride the global setting for specific forms:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n // Enable for this form (even if globally disabled)\n emitFormValueOnEvents: true,\n // Or disable for this form (even if globally enabled)\n // emitFormValueOnEvents: false,\n }\n};\n```\n\n### Accessing the Form Value\n\nUse the `hasFormValue()` type guard to safely access the attached value:\n\n```typescript\nimport { hasFormValue } from '@ng-forge/dynamic-forms';\n\neventBus.on<SubmitEvent>('submit').subscribe((event) => {\n if (hasFormValue(event)) {\n // TypeScript knows event.formValue exists\n console.log('Form value at submission:', event.formValue);\n sendToApi(event.formValue);\n }\n});\n```\n\nThis is useful when you need the complete form state at the time an event occurred, such as:\n\n- Logging form values on submission\n- Auto-saving on page changes\n- Analytics tracking\n\n## Event Flow\n\n1. Component dispatches event via `eventBus.dispatch()`\n2. Event bus broadcasts to all subscribers\n3. Subscribers receive event and execute handlers\n4. Type filtering ensures only relevant handlers execute\n\n## Integration with Forms\n\nThe event bus is automatically provided by the `DynamicForm` component to all child field components. You don't need to manually provide it:\n\n```typescript\n// The DynamicForm component internally provides EventBus\n// All child field components can inject and use it\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-my-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\"></form>`,\n})\nexport class MyFormComponent {\n // EventBus is available to all field components rendered by DynamicForm\n}\n```\n\nField components can inject and use the event bus:\n\n```typescript\nexport class CustomFieldComponent extends BaseFieldComponent {\n eventBus = inject(EventBus);\n\n onSubmit() {\n // Trigger form submission from custom component\n this.eventBus.dispatch(SubmitEvent);\n }\n}\n```"
21
21
  },
22
22
  {
23
23
  id: "advanced-expression-parser",
24
24
  title: "Advanced Expression Parser",
25
25
  category: "advanced",
26
- content: "Dynamic forms use expressions for conditional logic and dynamic values. When you use JavaScript expressions with `type: 'javascript'`, the expression parser evaluates them safely, preventing code injection attacks while maintaining the flexibility you need.\n\n## How JavaScript Expressions Work\n\nWhen you configure JavaScript expressions in your form:\n\n```typescript\n{\n key: 'driverLicense',\n type: 'input',\n value: '',\n label: 'Driver License',\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.age >= 18 && formValue.needsTransport === true'\n },\n }\n ]\n}\n```\n\nThe expression `'formValue.age >= 18 && formValue.needsTransport === true'` is evaluated by the parser, which has access to:\n\n```typescript\n{\n fieldValue: currentFieldValue,\n formValue: { age: 25, needsTransport: true, ... },\n fieldPath: 'driverLicense'\n}\n```\n\n## Security Model\n\nThe parser uses different rules for methods and properties:\n\n### Methods: Whitelist Only\n\nOnly safe methods can be called in expressions:\n\n```typescript\n// \u2705 Works - safe string methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.includes(\"@company.com\")'\n }\n}\n\n// \u2705 Works - safe array methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.roles.some((role) => role === \"admin\")'\n }\n}\n\n// \u274C Blocked - not whitelisted\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.text.link(\"url\")' // Error: Method \"link\" is not allowed\n }\n}\n```\n\n### Whitelisted Methods Reference\n\n| Category | Methods |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **String** | `toUpperCase`, `toLowerCase`, `trim`, `includes`, `startsWith`, `endsWith`, `slice`, `substring`, `charAt`, `indexOf`, `lastIndexOf`, `split`, `replace`, `match` |\n| **Array** | `map`, `filter`, `some`, `every`, `find`, `findIndex`, `includes`, `indexOf`, `join`, `slice`, `flat`, `flatMap` |\n| **Number** | `toFixed`, `toString`, `valueOf` |\n| **Object** | `hasOwnProperty`, `toString`, `valueOf` |\n\n### Properties: Open Access (Except Dangerous Ones)\n\nAll properties in the form data are accessible, except prototype properties:\n\n```typescript\n// \u2705 Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// \u274C Blocked - prototype pollution risks\nexpression: 'formValue.constructor'; // Error: Property \"constructor\" is not accessible\nexpression: 'formValue.__proto__'; // Error: Property \"__proto__\" is not accessible\n```\n\n**Why?** Dynamic forms need to access any field name you define. The parser blocks only the dangerous properties that could break security.\n\n### Safe Member Access (Built-in)\n\n**Important**: Member access is safe by default - accessing properties on `null` or `undefined` returns `undefined` instead of throwing errors:\n\n```typescript\n// \u2705 All of these work safely, even when intermediate values are null/undefined\nexpression: 'formValue.user.profile.firstName';\nexpression: 'formValue.address.city.toLowerCase()';\nexpression: 'formValue.settings.notifications.email';\n\n// If formValue.user is null, the expression returns undefined (no error thrown)\n// If formValue.user.profile is null, the expression returns undefined (no error thrown)\n// No manual null checks needed!\n```\n\n**This means you don't need to write defensive null checks:**\n\n```typescript\n// \u274C Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// \u2705 Better - Safe by default\nexpression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n```\n\nThe parser automatically handles null/undefined at every level of property access, making expressions cleaner and more maintainable.\n\n## Available Context Variables\n\nWhen expressions are evaluated, they have access to:\n\n```typescript\n{\n fieldValue: 'current field value',\n formValue: { /* entire form state */ },\n fieldPath: 'fieldName',\n externalData: { /* external application state, if configured */ }\n}\n```\n\n### External Data\n\nWhen you configure `externalData` in your FormConfig, it becomes available in expressions:\n\n```typescript\nconst config = {\n externalData: {\n userRole: computed(() => authService.role()),\n permissions: computed(() => authService.permissions()),\n },\n fields: [\n {\n key: 'adminField',\n type: 'input',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: \"externalData.userRole !== 'admin'\",\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n## Common Form Use Cases\n\n### Dynamic Visibility\n\n```typescript\n{\n key: 'companyName',\n type: 'input',\n value: '',\n label: 'Company Name',\n // Show only if user selects \"Employed\"\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.employmentStatus !== \"employed\"'\n }\n }\n ]\n}\n```\n\n### Conditional Required\n\n```typescript\n{\n key: 'taxId',\n type: 'input',\n value: '',\n label: 'Tax ID',\n // Required only for business accounts\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.accountType === \"business\"'\n },\n }\n ]\n}\n```\n\n### Complex Conditions\n\n```typescript\n{\n key: 'personalConcierge',\n type: 'checkbox',\n value: false,\n label: 'Request Personal Concierge Service',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.membershipLevel !== \"vip\" || formValue.annualIncome < 100000'\n }\n }\n ]\n}\n```\n\n### String Methods in Expressions\n\n```typescript\n{\n key: 'discountCode',\n type: 'input',\n value: '',\n label: 'Discount Code',\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.endsWith(\"@company.com\")'\n },\n }\n ]\n}\n```\n\n## What the Parser Prevents\n\nFor dynamic forms, the parser prevents:\n\n- \u2705 **Code Injection**: Can't execute `Function()`, `eval()`, or create new code\n- \u2705 **Prototype Pollution**: Can't access `constructor` or `__proto__`\n- \u2705 **Unsafe Operations**: Can't call methods that modify state or access globals\n\n## Custom Functions\n\nWhen providing custom functions for use in expressions, register them with the FunctionRegistryService:\n\n```typescript\n// \u2705 GOOD - Pure functions\nimport { FunctionRegistryService } from '@ng-forge/dynamic-forms';\n\nconst functionRegistry = inject(FunctionRegistryService);\n\nfunctionRegistry.registerCustomFunction('isValidEmail', (ctx) => {\n return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(ctx.fieldValue);\n});\n\nfunctionRegistry.registerCustomFunction('isAdult', (ctx) => {\n return ctx.formValue.age >= 18;\n});\n```\n\nThen use them with `type: 'custom'`:\n\n```typescript\n{\n key: 'adultContent',\n type: 'checkbox',\n value: false,\n label: 'Access Adult Content',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'custom',\n expression: 'isAdult'\n }\n }\n ]\n}\n```\n\n**Important**: Only provide pure functions without side effects:\n\n```typescript\n// \u274C BAD - Side effects\nfunctionRegistry.registerCustomFunction('logValue', (ctx) => {\n console.log(ctx.fieldValue); // Side effect!\n trackAnalytics(ctx); // Side effect!\n return true;\n});\n```\n\n## Supported Expression Features\n\nIn JavaScript expressions (`type: 'javascript'`), you can use:\n\n| Feature | Examples |\n| --------------------- | --------------------------------------------------------------- |\n| **Property access** | `formValue.name`, `formValue.user.profile.email` |\n| **Comparisons** | `===`, `!==`, `>`, `<`, `>=`, `<=` |\n| **Logical operators** | `&&`, `\\|\\|`, `!` |\n| **Arithmetic** | `+`, `-`, `*`, `/`, `%` |\n| **String methods** | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n| **Array methods** | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n\n**Example**:\n\n```typescript\nexpression: 'formValue.age >= 18 && formValue.email.includes(\"@example.com\")';\n```\n\n**Not Supported**: Object literals `{}`, ternary `a ? b : c`, assignment `x = 5`, `new` keyword, function declarations\n\n## Summary\n\nThe expression parser lets you write flexible conditional logic while preventing code injection attacks:\n\n1. **Form state is accessible** - Any field in `formValue` can be read\n2. **Methods are restricted** - Only safe, non-mutating methods allowed\n3. **Prototype is protected** - Can't access dangerous properties\n4. **Custom functions supported** - Register pure functions for reusable logic"
26
+ content: "Dynamic forms use expressions for conditional logic and dynamic values. When you use JavaScript expressions with `type: 'javascript'`, the expression parser evaluates them safely, preventing code injection attacks while maintaining the flexibility you need.\n\n## How JavaScript Expressions Work\n\nWhen you configure JavaScript expressions in your form:\n\n```typescript\n{\n key: 'driverLicense',\n type: 'input',\n value: '',\n label: 'Driver License',\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.age >= 18 && formValue.needsTransport === true'\n },\n }\n ]\n}\n```\n\nThe expression `'formValue.age >= 18 && formValue.needsTransport === true'` is evaluated by the parser, which has access to:\n\n```typescript\n{\n fieldValue: currentFieldValue,\n formValue: { age: 25, needsTransport: true, ... },\n fieldPath: 'driverLicense'\n}\n```\n\n## Security Model\n\nThe parser uses different rules for methods and properties:\n\n### Methods: Whitelist Only\n\nOnly safe methods can be called in expressions:\n\n```typescript\n// \u2705 Works - safe string methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.includes(\"@company.com\")'\n }\n}\n\n// \u2705 Works - safe array methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.roles.some((role) => role === \"admin\")'\n }\n}\n\n// \u274C Blocked - not whitelisted\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.text.link(\"url\")' // Error: Method \"link\" is not allowed\n }\n}\n```\n\n### Whitelisted Methods Reference\n\n| Category | Methods |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **String** | `toUpperCase`, `toLowerCase`, `trim`, `includes`, `startsWith`, `endsWith`, `slice`, `substring`, `charAt`, `indexOf`, `lastIndexOf`, `split`, `replace`, `match` |\n| **Array** | `map`, `filter`, `some`, `every`, `find`, `findIndex`, `includes`, `indexOf`, `join`, `slice`, `flat`, `flatMap` |\n| **Number** | `toFixed`, `toString`, `valueOf` |\n| **Object** | `hasOwnProperty`, `toString`, `valueOf` |\n\n### Properties: Open Access (Except Dangerous Ones)\n\nAll properties in the form data are accessible, except prototype properties:\n\n```typescript\n// \u2705 Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// \u274C Blocked - prototype pollution risks\nexpression: 'formValue.constructor'; // Error: Property \"constructor\" is not accessible\nexpression: 'formValue.__proto__'; // Error: Property \"__proto__\" is not accessible\n```\n\n**Why?** Dynamic forms need to access any field name you define. The parser blocks only the dangerous properties that could break security.\n\n### Safe Member Access (Built-in)\n\n**Important**: Member access is safe by default - accessing properties on `null` or `undefined` returns `undefined` instead of throwing errors:\n\n```typescript\n// \u2705 All of these work safely, even when intermediate values are null/undefined\nexpression: 'formValue.user.profile.firstName';\nexpression: 'formValue.address.city.toLowerCase()';\nexpression: 'formValue.settings.notifications.email';\n\n// If formValue.user is null, the expression returns undefined (no error thrown)\n// If formValue.user.profile is null, the expression returns undefined (no error thrown)\n// No manual null checks needed!\n```\n\n**This means you don't need to write defensive null checks:**\n\n```typescript\n// \u274C Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// \u2705 Better - Safe by default\nexpression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n```\n\nThe parser automatically handles null/undefined at every level of property access, making expressions cleaner and more maintainable.\n\n## Available Context Variables\n\nWhen expressions are evaluated, they have access to:\n\n```typescript\n{\n fieldValue: 'current field value',\n formValue: { /* entire form state */ },\n fieldPath: 'fieldName',\n externalData: { /* external application state, if configured */ }\n}\n```\n\n### External Data\n\nWhen you configure `externalData` in your FormConfig, it becomes available in expressions:\n\n```typescript\nconst config = {\n externalData: {\n userRole: computed(() => authService.role()),\n permissions: computed(() => authService.permissions()),\n },\n fields: [\n {\n key: 'adminField',\n type: 'input',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: \"externalData.userRole !== 'admin'\",\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n## Common Form Use Cases\n\n### Dynamic Visibility\n\n```typescript\n{\n key: 'companyName',\n type: 'input',\n value: '',\n label: 'Company Name',\n // Show only if user selects \"Employed\"\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.employmentStatus !== \"employed\"'\n }\n }\n ]\n}\n```\n\n### Conditional Required\n\n```typescript\n{\n key: 'taxId',\n type: 'input',\n value: '',\n label: 'Tax ID',\n // Required only for business accounts\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.accountType === \"business\"'\n },\n }\n ]\n}\n```\n\n### Complex Conditions\n\n```typescript\n{\n key: 'personalConcierge',\n type: 'checkbox',\n value: false,\n label: 'Request Personal Concierge Service',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.membershipLevel !== \"vip\" || formValue.annualIncome < 100000'\n }\n }\n ]\n}\n```\n\n### String Methods in Expressions\n\n```typescript\n{\n key: 'discountCode',\n type: 'input',\n value: '',\n label: 'Discount Code',\n logic: [\n {\n type: 'required',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.endsWith(\"@company.com\")'\n },\n }\n ]\n}\n```\n\n## What the Parser Prevents\n\nFor dynamic forms, the parser prevents:\n\n- \u2705 **Code Injection**: Can't execute arbitrary code or create new code\n- \u2705 **Prototype Pollution**: Can't access `constructor` or `__proto__`\n- \u2705 **Unsafe Operations**: Can't call methods that modify state or access globals\n\n## Custom Functions\n\nWhen providing custom functions for use in expressions, register them with the FunctionRegistryService:\n\n```typescript\n// \u2705 GOOD - Pure functions\nimport { FunctionRegistryService } from '@ng-forge/dynamic-forms';\n\nconst functionRegistry = inject(FunctionRegistryService);\n\nfunctionRegistry.registerCustomFunction('isValidEmail', (ctx) => {\n return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(ctx.fieldValue);\n});\n\nfunctionRegistry.registerCustomFunction('isAdult', (ctx) => {\n return ctx.formValue.age >= 18;\n});\n```\n\nThen use them with `type: 'custom'`:\n\n```typescript\n{\n key: 'adultContent',\n type: 'checkbox',\n value: false,\n label: 'Access Adult Content',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'custom',\n expression: 'isAdult'\n }\n }\n ]\n}\n```\n\n**Important**: Only provide pure functions without side effects:\n\n```typescript\n// \u274C BAD - Side effects\nfunctionRegistry.registerCustomFunction('logValue', (ctx) => {\n console.log(ctx.fieldValue); // Side effect!\n trackAnalytics(ctx); // Side effect!\n return true;\n});\n```\n\n## Supported Expression Features\n\nIn JavaScript expressions (`type: 'javascript'`), you can use:\n\n| Feature | Examples |\n| --------------------- | --------------------------------------------------------------- |\n| **Property access** | `formValue.name`, `formValue.user.profile.email` |\n| **Comparisons** | `===`, `!==`, `>`, `<`, `>=`, `<=` |\n| **Logical operators** | `&&`, `\\|\\|`, `!` |\n| **Arithmetic** | `+`, `-`, `*`, `/`, `%` |\n| **String methods** | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n| **Array methods** | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n\n**Example**:\n\n```typescript\nexpression: 'formValue.age >= 18 && formValue.email.includes(\"@example.com\")';\n```\n\n**Not Supported**: Object literals `{}`, ternary `a ? b : c`, assignment `x = 5`, `new` keyword, function declarations\n\n## Summary\n\nThe expression parser lets you write flexible conditional logic while preventing code injection attacks:\n\n1. **Form state is accessible** - Any field in `formValue` can be read\n2. **Methods are restricted** - Only safe, non-mutating methods allowed\n3. **Prototype is protected** - Can't access dangerous properties\n4. **Custom functions supported** - Register pure functions for reusable logic"
27
27
  },
28
28
  {
29
29
  id: "advanced-type-safety-basics",
@@ -31,17 +31,23 @@ var require_docs = __commonJS({
31
31
  category: "advanced",
32
32
  content: "Complete type inference for form configurations using TypeScript's type system and Angular signal forms.\n\n## Overview\n\nDynamic Forms provides compile-time type inference for form configurations, eliminating manual type definitions and catching errors before runtime. All form values are automatically inferred from your configuration using TypeScript's advanced type features.\n\n## Basic Type Inference\n\nUse `as const satisfies FormConfig` to enable type inference:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig = {\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n { key: 'email', type: 'input', value: '' },\n { key: 'age', type: 'input', value: 0, props: { type: 'number' } },\n { key: 'newsletter', type: 'checkbox', value: false },\n ],\n} as const satisfies FormConfig;\n\n// Type is automatically inferred based on value property:\n// { firstName?: string; email?: string; age?: number; newsletter?: boolean }\n```\n\n**How it works:**\n\n1. `as const` makes the configuration deeply readonly, preserving literal types\n2. `satisfies FormConfig` validates the config structure without widening types\n3. TypeScript infers the form value type from the `value` properties\n\n## The `value` Property\n\nThe `value` property is critical for type inference - its type determines the inferred field type:\n\n```typescript\nconst config = {\n fields: [\n { key: 'name', type: 'input', value: '' }, // string\n { key: 'age', type: 'input', value: 0 }, // number\n { key: 'active', type: 'checkbox', value: false }, // boolean\n { key: 'tags', type: 'multi-checkbox', value: [] }, // string[]\n ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n// name?: string;\n// age?: number;\n// active?: boolean;\n// tags?: string[];\n// }\n```\n\n## Field Registry System\n\nUI integrations register their field types via `provideDynamicForm`. For example, with Material Design:\n\n```typescript\n// app.config.ts\nimport { provideDynamicForm } from '@ng-forge/dynamic-forms';\nimport { withMaterialFields } from '@ng-forge/dynamic-forms-material';\n\nexport const appConfig: ApplicationConfig = {\n providers: [\n provideDynamicForm(...withMaterialFields()),\n // other providers\n ],\n};\n```\n\nMaterial fields augment the `FieldRegistryLeaves` interface for type safety:\n\n```typescript\n// From @ng-forge/dynamic-forms-material (already included)\ndeclare module '@ng-forge/dynamic-forms' {\n interface FieldRegistryLeaves {\n input: MatInputField;\n select: MatSelectField<unknown>;\n checkbox: MatCheckboxField;\n // ... other Material fields\n }\n}\n```\n\nThis determines:\n\n- What field `type` values are valid (e.g., `'input'`, `'select'`)\n- How each field type is structured\n- What props are available for each field\n\n**Example - Wrong field type:**\n\n```typescript\nconst config = {\n fields: [\n { key: 'name', type: 'invalid', value: '' }, // TypeScript error!\n ],\n} as const satisfies FormConfig;\n```\n\n## Required vs Optional Fields\n\nThe `required` flag affects whether fields include `undefined` in their type:\n\n```typescript\nconst config = {\n fields: [\n { key: 'email', type: 'input', value: '', required: true }, // string (required)\n { key: 'name', type: 'input', value: '' }, // string | undefined\n { key: 'age', type: 'input', value: 0, required: false }, // number | undefined\n ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n// email: string; // Required - no undefined\n// name?: string; // Optional - includes undefined\n// age?: number; // Optional - includes undefined\n// }\n```\n\n**In practice:**\n\n```typescript\nfunction handleSubmit(value: InferFormValue<typeof config.fields>) {\n console.log(value.email.toUpperCase()); // \u2713 Safe - always defined\n console.log(value.name?.toUpperCase()); // \u2713 Must use optional chaining\n console.log(value.age + 1); // \u2717 Error - might be undefined\n}\n```\n\n## Using InferFormValue\n\nExtract the inferred type for use in your component:\n\n```typescript\nimport { signal } from '@angular/core';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\n@Component({...})\nexport class UserFormComponent {\n config = {\n fields: [\n { key: 'username', type: 'input', value: '', required: true },\n { key: 'age', type: 'input', value: 0 },\n ]\n } as const satisfies FormConfig;\n\n // Extract type for signal\n formValue = signal<InferFormValue<typeof this.config.fields>>({\n username: '',\n });\n\n onSubmit() {\n const value = this.formValue();\n console.log(value.username); // \u2713 Type: string (required)\n console.log(value.age); // \u2713 Type: number | undefined (optional)\n }\n}\n```\n\n## IntelliSense Support\n\nTypeScript provides autocomplete for form values throughout your code:\n\n```typescript\nconst config = {\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n { key: 'lastName', type: 'input', value: '' },\n { key: 'email', type: 'input', value: '', required: true },\n ],\n} as const satisfies FormConfig;\n\ntype FormValue = InferFormValue<typeof config.fields>;\n\nfunction processForm(value: FormValue) {\n // IntelliSense suggests: firstName, lastName, email\n value.firstName; // \u2713 Autocomplete works\n value.lastName; // \u2713 Autocomplete works\n value.email; // \u2713 Autocomplete works\n value.invalid; // \u2717 TypeScript error - property doesn't exist\n}\n```\n\n## Best Practices\n\n### Always Use `as const satisfies FormConfig`\n\nThis enables type inference and validates your configuration:\n\n```typescript\n// \u2713 Correct - enables inference + type checking\nconst config = { fields: [...] } as const satisfies FormConfig;\n\n// \u2717 Wrong - no inference\nconst config = { fields: [...] };\n\n// \u2717 Wrong - too wide, loses precision\nconst config: FormConfig = { fields: [...] };\n```\n\n### Define Configs as Constants\n\nExport form configs as constants for reuse and consistent typing:\n\n```typescript\n// form-configs.ts\nexport const USER_FORM = {\n fields: [\n { key: 'name', type: 'input', value: '', required: true },\n { key: 'email', type: 'input', value: '', required: true },\n ],\n} as const satisfies FormConfig;\n\n// user-form.component.ts\nimport { USER_FORM } from './form-configs';\n\n@Component({...})\nexport class UserFormComponent {\n config = USER_FORM;\n}\n```\n\n### Always Include `value` Property\n\nType inference requires the `value` property to determine field types:\n\n```typescript\n// \u2713 Good - type inferred from value\nconst config = {\n fields: [\n { key: 'age', type: 'input', value: 0 }, // number\n { key: 'name', type: 'input', value: '' }, // string\n { key: 'active', type: 'checkbox', value: false }, // boolean\n ],\n} as const satisfies FormConfig;\n\n// \u2717 Bad - without value, type inference may not work correctly\nconst config = {\n fields: [\n { key: 'age', type: 'input' }, // Type unclear\n ],\n} as const satisfies FormConfig;\n```\n\n### Extract Types When Needed\n\nCreate type aliases for complex form values:\n\n```typescript\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst REGISTRATION_FORM = {\n fields: [\n { key: 'username', type: 'input', value: '', required: true },\n { key: 'email', type: 'input', value: '', required: true },\n { key: 'password', type: 'input', value: '', required: true },\n ],\n} as const satisfies FormConfig;\n\n// Export type for reuse\nexport type RegistrationFormValue = InferFormValue<(typeof REGISTRATION_FORM)['fields']>;\n\n// Use in functions\nfunction registerUser(data: RegistrationFormValue) {\n console.log(data.username, data.email, data.password);\n}\n```\n\n## Troubleshooting\n\n### Type inference not working\n\nType inference requires `as const` - without it, TypeScript treats your config as mutable:\n\n```typescript\n// \u2717 No inference - types are too wide\nconst config = {\n fields: [{ key: 'name', type: 'input', value: '' }],\n};\n// Type: { fields: { key: string; type: string; value: string }[] }\n\n// \u2713 With as const - precise inference\nconst config = {\n fields: [{ key: 'name', type: 'input', value: '' }],\n} as const satisfies FormConfig;\n// Type inferred: { name?: string }\n```\n\n### `satisfies` vs type annotation\n\nDon't use type annotation (`const config: FormConfig = ...`) as it widens types:\n\n```typescript\n// \u2717 Wrong - type is widened, inference fails\nconst config: FormConfig = {\n fields: [{ key: 'name', type: 'input', value: '' }],\n} as const;\n\n// \u2713 Correct - satisfies validates without widening\nconst config = {\n fields: [{ key: 'name', type: 'input', value: '' }],\n} as const satisfies FormConfig;\n```\n\n### Dynamic form configs\n\nType inference only works for **static**, **compile-time constant** configurations:\n\n```typescript\n// \u2717 Dynamic - no inference possible\nconst fields = getFieldsFromAPI(); // Returns field array at runtime\nconst config = { fields } as const satisfies FormConfig;\n// Can't infer - TypeScript doesn't know what getFieldsFromAPI() returns\n\n// For dynamic forms, manually type your form values:\ninterface MyFormValue {\n name: string;\n email: string;\n}\n\nconst formValue = signal<MyFormValue>({ name: '', email: '' });\n```\n\nIf your form configuration is built dynamically (from API data, conditional logic, or runtime calculations), you'll need to manually define the form value type.\n\n## Container Fields\n\nUnderstanding how container fields affect type inference and form value structure.\n\n### Container Fields Overview\n\nContainer fields organize form layout and structure without directly contributing values. There are three types:\n\n- **Group Fields** - Nest children under a single key\n- **Row Fields** - Organize fields horizontally, flatten children to parent level\n- **Page Fields** - Multi-step forms, flatten children to parent level\n\nEach container type has different behavior for type inference and form values.\n\n### Group Fields\n\nGroups nest children under a single key, creating nested objects in the form value:\n\n```typescript\nconst config = {\n fields: [\n {\n type: 'group',\n key: 'address',\n label: 'Address Information',\n fields: [\n { key: 'street', type: 'input', value: '' },\n { key: 'city', type: 'input', value: '' },\n { key: 'zip', type: 'input', value: '' },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n// address: {\n// street?: string;\n// city?: string;\n// zip?: string;\n// }\n// }\n```\n\n**Use groups when:**\n\n- You want nested form values (e.g., `address.street`)\n- Grouping related fields logically\n- Creating reusable field sections\n\n**Example - Nested address:**\n\n```typescript\nconst config = {\n fields: [\n { key: 'name', type: 'input', value: '', required: true },\n {\n type: 'group',\n key: 'address',\n fields: [\n { key: 'street', type: 'input', value: '', required: true },\n { key: 'city', type: 'input', value: '', required: true },\n { key: 'state', type: 'select', value: '', required: true, options: [] },\n { key: 'zip', type: 'input', value: '' },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Form value structure:\n// {\n// name: string;\n// address: {\n// street: string;\n// city: string;\n// state: string;\n// zip?: string;\n// }\n// }\n\nfunction onSubmit(value: InferFormValue<typeof config.fields>) {\n console.log(value.name); // string\n console.log(value.address.street); // string\n console.log(value.address.city); // string\n console.log(value.address.zip); // string | undefined\n}\n```\n\n### Row Fields\n\nRows organize fields horizontally for layout purposes, but flatten children to the parent level in form values:\n\n```typescript\nconst config = {\n fields: [\n {\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n { key: 'lastName', type: 'input', value: '' },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Inferred type (flattened):\n// {\n// firstName?: string;\n// lastName?: string;\n// }\n```\n\n**Use rows when:**\n\n- You want horizontal layout (grid columns)\n- Fields should be at the parent level (not nested)\n- Creating responsive multi-column forms\n\n**Row vs Group:**\n\n```typescript\n// Row - fields are flattened\n{\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n { key: 'lastName', type: 'input', value: '' },\n ],\n}\n// Result: { firstName?: string, lastName?: string }\n\n// Group - fields are nested\n{\n type: 'group',\n key: 'name',\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n { key: 'lastName', type: 'input', value: '' },\n ],\n}\n// Result: { name: { firstName?: string, lastName?: string } }\n```\n\n### Page Fields\n\nPages organize multi-step forms, flattening all children to the root level:\n\n```typescript\nconst config = {\n fields: [\n {\n key: 'page1',\n type: 'page',\n fields: [\n { key: 'page1Title', type: 'text', label: 'Personal Information', props: { elementType: 'h3' } },\n { key: 'email', type: 'input', value: '' },\n { key: 'password', type: 'input', value: '' },\n ],\n },\n {\n key: 'page2',\n type: 'page',\n fields: [\n { key: 'page2Title', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n { key: 'firstName', type: 'input', value: '' },\n { key: 'lastName', type: 'input', value: '' },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Inferred type (all pages flattened):\n// {\n// email?: string;\n// password?: string;\n// firstName?: string;\n// lastName?: string;\n// }\n```\n\n**Use pages when:**\n\n- Creating multi-step forms (wizard-style)\n- Fields from all steps should be at root level\n- You want step-by-step validation\n\n### Nesting Rules\n\nContainer fields enforce nesting constraints at compile-time to prevent invalid structures.\n\n**Visual Reference:**\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 NESTING RULES \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2502\n\u2502 PAGE \u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u25BA ROW \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u25BA GROUP \u2500\u2500\u252C\u2500\u2500\u25BA LEAF FIELD \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \u251C\u2500\u2500\u25BA GROUP \u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u25BA ROW \u2500\u2500\u2500\u2500\u2534\u2500\u2500\u25BA LEAF FIELD \u2502\n\u2502 \u2502 \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u25BA LEAF FIELD \u2514\u2500\u2500\u25BA LEAF FIELD \u2502\n\u2502 \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2717 PAGE cannot contain PAGE \u2502\n\u2502 \u2717 ROW cannot contain ROW or PAGE \u2502\n\u2502 \u2717 GROUP cannot contain GROUP or PAGE \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Valid Nesting:**\n\n- **Pages** can contain: rows, groups, leaf fields (not other pages)\n- **Rows** can contain: groups, leaf fields (not pages or rows)\n- **Groups** can contain: rows, leaf fields (not pages or other groups)\n\n**Invalid Nesting:**\n\nTypeScript will prevent these invalid structures:\n\n```typescript\n// \u2717 Invalid: page inside page\nconst config1 = {\n fields: [\n {\n type: 'page',\n fields: [\n { type: 'page', fields: [] }, // TypeScript error!\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// \u2717 Invalid: row inside row\nconst config2 = {\n fields: [\n {\n type: 'row',\n fields: [\n { type: 'row', fields: [] }, // TypeScript error!\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n### Value-Bearing vs Display Fields\n\nFields are categorized by whether they contribute to form values:\n\n**Value-Bearing Fields:**\n\nFields with a `value` property contribute to the form output:\n\n- `input`, `select`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`, etc.\n\n**Display-Only Fields:**\n\nFields without values are excluded from form values:\n\n- `text` - displays content\n- `page`, `row`, `group` - container fields (children may have values)\n- Buttons - `submit`, `reset`, navigation buttons\n- Custom display components\n\n```typescript\nconst config = {\n fields: [\n { type: 'text', label: 'Enter your details:' }, // \u2717 Excluded\n { key: 'name', type: 'input', value: '' }, // \u2713 Included\n { type: 'submit', label: 'Save' }, // \u2717 Excluded\n {\n type: 'row', // \u2717 Excluded (container)\n fields: [\n { key: 'city', type: 'input', value: '' }, // \u2713 Included\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Only value-bearing fields:\n// {\n// name?: string;\n// city?: string;\n// }\n```\n\n### Array Fields\n\nMulti-select fields and multi-checkbox fields return arrays:\n\n```typescript\nconst config = {\n fields: [\n {\n key: 'skills',\n type: 'select',\n value: [],\n props: { multiple: true },\n options: [\n { value: 'js', label: 'JavaScript' },\n { value: 'ts', label: 'TypeScript' },\n { value: 'go', label: 'Go' },\n ],\n },\n {\n key: 'interests',\n type: 'multi-checkbox',\n value: [],\n options: [\n { value: 'sports', label: 'Sports' },\n { value: 'music', label: 'Music' },\n { value: 'reading', label: 'Reading' },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Type: { skills?: string[]; interests?: string[] }\n```\n\n## Advanced Patterns\n\n### Runtime Validation\n\nForm values are typed at compile-time via `InferFormValue`, but runtime validation may be needed:\n\n#### Type Assertion (Trust Form Structure)\n\nIf you trust the form structure, cast the value:\n\n```typescript\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst USER_FORM = {\n fields: [\n { key: 'username', type: 'input', value: '', required: true },\n { key: 'email', type: 'input', value: '', required: true },\n { key: 'age', type: 'input', value: 0 },\n ],\n} as const satisfies FormConfig;\n\ntype UserFormValue = InferFormValue<(typeof USER_FORM)['fields']>;\n\nfunction onSubmit(value: unknown) {\n // Cast to inferred type\n const data = value as UserFormValue;\n\n console.log(data.username); // string\n console.log(data.email); // string\n console.log(data.age); // number | undefined\n}\n```\n\n#### Runtime Validation with Zod\n\nFor runtime guarantees, use a validation library like Zod:\n\n```typescript\nimport { z } from 'zod';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst USER_FORM = {\n fields: [\n { key: 'username', type: 'input', value: '', required: true },\n { key: 'email', type: 'input', value: '', required: true },\n { key: 'age', type: 'input', value: 0 },\n ],\n} as const satisfies FormConfig;\n\n// Define Zod schema matching form structure\nconst userSchema = z.object({\n username: z.string().min(1),\n email: z.string().email(),\n age: z.number().optional(),\n});\n\nfunction onSubmit(value: unknown) {\n // Runtime validation\n const result = userSchema.safeParse(value);\n\n if (!result.success) {\n console.error('Validation failed:', result.error);\n return;\n }\n\n // Type-safe access\n const data = result.data;\n console.log(data.username); // string\n console.log(data.email); // string\n console.log(data.age); // number | undefined\n}\n```\n\n#### Combining Compile-Time and Runtime\n\nUse both for maximum safety:\n\n```typescript\nimport { z } from 'zod';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst REGISTRATION_FORM = {\n fields: [\n { key: 'username', type: 'input', value: '', required: true },\n { key: 'email', type: 'input', value: '', required: true },\n { key: 'password', type: 'input', value: '', required: true },\n { key: 'confirmPassword', type: 'input', value: '', required: true },\n ],\n} as const satisfies FormConfig;\n\n// Compile-time type\ntype RegistrationValue = InferFormValue<typeof REGISTRATION_FORM['fields']>;\n\n// Runtime schema (with additional validation)\nconst registrationSchema = z.object({\n username: z.string().min(3).max(20),\n email: z.string().email(),\n password: z.string().min(8),\n confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n message: \"Passwords don't match\",\n path: ['confirmPassword'],\n});\n\n@Component({...})\nexport class RegistrationComponent {\n config = REGISTRATION_FORM;\n\n // Compile-time type for signal\n formValue = signal<RegistrationValue>({\n username: '',\n email: '',\n password: '',\n confirmPassword: '',\n });\n\n onSubmit() {\n const value = this.formValue();\n\n // Runtime validation with cross-field check\n const result = registrationSchema.safeParse(value);\n\n if (!result.success) {\n console.error('Validation failed:', result.error);\n return;\n }\n\n // Safe to use\n this.register(result.data);\n }\n}\n```\n\n### Type-Safe Validation\n\nng-forge integrates validation with the type system. Validators affect the inferred type:\n\n#### Shorthand Validators\n\nShorthand validators are simple and affect type inference:\n\n```typescript\nconst config = {\n fields: [\n {\n key: 'email',\n type: 'input',\n value: '',\n required: true, // Removes undefined from type\n email: true, // Email validation\n minLength: 5, // Min length validation\n },\n ],\n} as const satisfies FormConfig;\n\n// Type inferred: { email: string } (required, so no undefined)\n```\n\n#### Validator Array\n\nFor complex validation, use the `validators` array:\n\n```typescript\nconst config = {\n fields: [\n {\n key: 'discount',\n type: 'input',\n value: 0,\n validators: [\n {\n type: 'min',\n value: 0,\n },\n {\n type: 'max',\n value: 100,\n when: {\n type: 'fieldValue',\n fieldPath: 'discountType',\n operator: 'equals',\n value: 'percentage',\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n#### Conditional Required\n\nUse the `logic` array for conditional required fields:\n\n```typescript\nconst config = {\n fields: [\n { key: 'accountType', type: 'select', value: '', options: [] },\n {\n key: 'taxId',\n type: 'input',\n value: '',\n logic: [\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n\n// Type: { accountType?: string; taxId?: string }\n// Note: Conditional required doesn't affect type inference\n```\n\n## Related\n\n- **[Validation](../../validation/basics/)** - How validators affect inferred types\n- **[Field Types](../../schema-fields/field-types/)** - Understanding available field types\n- **[Form Layout](../../prebuilt/form-groups/)** - Visual guide to container fields"
33
33
  },
34
+ {
35
+ id: "advanced-value-exclusion",
36
+ title: "Advanced Value Exclusion",
37
+ category: "advanced",
38
+ content: "Value exclusion controls which field values are included in the form submission output based on the field's reactive state (hidden, disabled, readonly).\n\n## Overview\n\nBy default, field values are **excluded** from the `(submitted)` output when the field is hidden, disabled, or readonly. This prevents stale or irrelevant data from being sent to the server.\n\n**Key point:** Value exclusion only affects the submission output. Internal form controls retain their values so they can be restored when a field becomes visible, enabled, or editable again. Two-way binding via `[value]` / `[(value)]` is **not affected**.\n\n## Default Behavior\n\nWhen no configuration is specified, the defaults are:\n\n| Rule | Default | Effect |\n| ------------------------ | ------- | --------------------------------------------------- |\n| `excludeValueIfHidden` | `true` | Hidden field values are excluded from submission |\n| `excludeValueIfDisabled` | `true` | Disabled field values are excluded from submission |\n| `excludeValueIfReadonly` | `true` | Read-only field values are excluded from submission |\n\n> **Breaking change from pre-1.0:** Previously, all field values were always included. To restore the old behavior, see [Migration from Previous Versions](#migration-from-previous-versions).\n\n## 3-Tier Configuration\n\nValue exclusion supports a 3-tier configuration hierarchy. The most specific level wins for each property:\n\n| Priority | Level | Where to set |\n| -------- | ------ | ----------------------------------------------- |\n| 1 (wins) | Field | `excludeValueIf*` on individual `FieldDef` |\n| 2 | Form | `excludeValueIf*` on `FormOptions` |\n| 3 | Global | `withValueExclusionDefaults()` feature function |\n\nIf a property is `undefined` at a given level, the next level down is checked.\n\n## Global Configuration\n\nUse `withValueExclusionDefaults()` in your provider setup to configure global defaults:\n\n```typescript\nimport { provideDynamicForm, withValueExclusionDefaults } from '@ng-forge/dynamic-forms';\n\n// All exclusions enabled (same as default)\nprovideDynamicForm(...withMaterialFields(), withValueExclusionDefaults());\n\n// Disable readonly exclusion globally\nprovideDynamicForm(...withMaterialFields(), withValueExclusionDefaults({ excludeValueIfReadonly: false }));\n\n// Disable all exclusions globally (pre-1.0 behavior)\nprovideDynamicForm(\n ...withMaterialFields(),\n withValueExclusionDefaults({\n excludeValueIfHidden: false,\n excludeValueIfDisabled: false,\n excludeValueIfReadonly: false,\n }),\n);\n```\n\n## Form-Level Configuration\n\nOverride the global setting for a specific form using `FormOptions`:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n // Include hidden field values for this form only\n excludeValueIfHidden: false,\n // Use global default for disabled and readonly\n }\n};\n```\n\n## Field-Level Configuration\n\nOverride both global and form settings for a specific field:\n\n```typescript\nconst config: FormConfig = {\n fields: [\n {\n type: 'input',\n key: 'internalId',\n label: 'Internal ID',\n readonly: true,\n // Always include this field's value, even when readonly\n excludeValueIfReadonly: false,\n },\n {\n type: 'input',\n key: 'notes',\n label: 'Notes',\n // This field uses the form/global defaults\n },\n ],\n};\n```\n\n## Resolution Example\n\nGiven these settings:\n\n- **Global:** `excludeValueIfHidden: true`\n- **Form:** `excludeValueIfHidden: false`\n- **Field A:** `excludeValueIfHidden: undefined` (not set)\n- **Field B:** `excludeValueIfHidden: true`\n\nResolution:\n\n- **Field A** uses form-level (`false`) because field-level is `undefined` &rarr; value is **included** when hidden\n- **Field B** uses field-level (`true`) &rarr; value is **excluded** when hidden\n\n## HiddenField Type\n\nThe `HiddenField` type (`type: 'hidden'`) is **not affected** by value exclusion. These fields:\n\n- Store values without rendering any UI\n- Have a `hidden()` reactive state of `false` (they are part of the form, just not rendered)\n- Are always included in submission output\n\nValue exclusion applies to the `hidden` **property** on regular fields (e.g., `{ type: 'input', hidden: true }` or fields hidden via conditional logic), not to the `HiddenField` type.\n\n## What's Excluded vs Retained\n\n| Aspect | Affected by exclusion? | Details |\n| -------------------------- | ---------------------- | ---------------------------------------- |\n| `(submitted)` output | Yes | Excluded fields are omitted |\n| `filteredFormValue` signal | Yes | Same filtering as submission |\n| `formValue` signal | No | Always contains all values |\n| `[(value)]` binding | No | Two-way binding retains all values |\n| Internal form controls | No | Fields keep their values for restoration |\n\n## Migration from Previous Versions\n\nIf you relied on all field values being present in `(submitted)` output, disable exclusion globally:\n\n```typescript\nprovideDynamicForm(\n ...withMaterialFields(),\n withValueExclusionDefaults({\n excludeValueIfHidden: false,\n excludeValueIfDisabled: false,\n excludeValueIfReadonly: false,\n }),\n);\n```\n\nOr disable per-form via `FormOptions`:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n excludeValueIfHidden: false,\n excludeValueIfDisabled: false,\n excludeValueIfReadonly: false,\n }\n};\n```"
39
+ },
34
40
  {
35
41
  id: "ai-integration",
36
42
  title: "AI Integration",
37
43
  category: "ai-integration",
38
- content: '# AI Integration\n\nThe `@ng-forge/dynamic-form-mcp` package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to generate, validate, and work with ng-forge dynamic form configurations.\n\n## Available Tools\n\nThe MCP server provides 4 focused tools:\n\n| Tool | Description | Read-only |\n| ------------------ | ----------------------------------------------------------- | --------- |\n| `ngforge_lookup` | Get documentation about field types, concepts, and patterns | \u2705 |\n| `ngforge_examples` | Get working code examples for common form patterns | \u2705 |\n| `ngforge_validate` | Validate FormConfig and get detailed error feedback | \u2705 |\n| `ngforge_scaffold` | Generate valid FormConfig skeletons | \u2705 |\n\n## Get Started\n\n### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n}\n```\n\n### VS Code with Copilot\n\nCreate `.vscode/mcp.json` in your project:\n\n```json\n{\n "servers": {\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n "mcpServers": {\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n }\n}\n```\n\n### JetBrains IDEs\n\nGo to **Settings > Tools > AI Assistant > Model Context Protocol (MCP)** and add:\n\n| Field | Value |\n| --------- | ----------------------------- |\n| Name | ng-forge |\n| Command | npx |\n| Arguments | -y @ng-forge/dynamic-form-mcp |\n\n------------ | --------------------------------------------------------- | ---------- | ----------------------- |\n| `topic` | string | (required) | Topic to look up |\n| `depth` | `"brief"` \\| `"full"` \\| `"schema"` | `"full"` | Level of detail |\n| `uiIntegration` | `"material"` \\| `"bootstrap"` \\| `"primeng"` \\| `"ionic"` | - | Filter UI-specific info |\n\n**Available Topics:**\n\n| Category | Topics |\n| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Field Types | `input`, `select`, `radio`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`, `hidden`, `text`, `button`, `submit`, `next`, `previous`, `addArrayItem`, `removeArrayItem` |\n| Containers | `group`, `row`, `array`, `page` |\n| Concepts | `validation`, `conditional`, `derivation`, `options-format`, `expression-variables`, `async-validators`, `validation-messages` |\n| Patterns | `golden-path`, `multi-page-gotchas`, `pitfalls`, `workflow` |\n\n**Examples:**\n\n```\nngforge_lookup topic="hidden" depth="brief"\nngforge_lookup topic="conditional" depth="full"\nngforge_lookup topic="input" depth="schema" uiIntegration="material"\n```\n\n---\n\n### ngforge_examples\n\nGet working code examples for common patterns.\n\n| Parameter | Type | Default | Description |\n| --------- | ----------------------------------------------------- | ---------- | --------------- |\n| `pattern` | string | (required) | Pattern name |\n| `depth` | `"minimal"` \\| `"brief"` \\| `"full"` \\| `"explained"` | `"full"` | Level of detail |\n\n**Available Patterns:**\n\n| Pattern | Description | Lines |\n| --------------------- | ---------------------------------------- | ----- |\n| `minimal-multipage` | Simplest 2-page wizard form | ~50 |\n| `minimal-array` | Array with add/remove buttons | ~30 |\n| `minimal-conditional` | Show/hide field based on condition | ~25 |\n| `minimal-validation` | Password confirmation validation | ~20 |\n| `minimal-hidden` | Hidden fields in multi-page form | ~15 |\n| `derivation` | Value derivation (computed fields) | - |\n| `conditional` | Conditional visibility patterns | - |\n| `multi-page` | Multi-step wizard forms | - |\n| `validation` | Form validation patterns | - |\n| `complete` | Full form with all major features | - |\n| `mega` | Kitchen sink demonstrating every feature | - |\n\n**Examples:**\n\n```\nngforge_examples pattern="minimal-multipage" depth="minimal"\nngforge_examples pattern="conditional" depth="explained"\n```\n\n---\n\n### ngforge_validate\n\nValidate FormConfig and get detailed error feedback.\n\n| Parameter | Type | Default | Description |\n| --------------- | --------------------------------------------------------- | ------------ | ------------------------------ |\n| `config` | string \\| object | (required) | File path or JSON config |\n| `uiIntegration` | `"material"` \\| `"bootstrap"` \\| `"primeng"` \\| `"ionic"` | `"material"` | UI library to validate against |\n\n**Input Detection:**\n\n| Input | Treated As |\n| ------------------------ | ------------------ |\n| Ends with `.ts` or `.js` | File path |\n| Starts with `{` or `[` | JSON string |\n| Object | Validated directly |\n\n**Example Errors:**\n\n- "Hidden field missing REQUIRED value property"\n- "options MUST be at FIELD level, NOT inside props"\n- "row containers do NOT support logic blocks"\n\n**Examples:**\n\n```\nngforge_validate config="/path/to/form.config.ts"\nngforge_validate config=\'{"fields":[...]}\' uiIntegration="bootstrap"\n```\n\n---\n\n### ngforge_scaffold\n\nGenerate valid FormConfig skeletons.\n\n| Parameter | Type | Default | Description |\n| --------------- | -------- | ------------ | ------------------------------------- |\n| `pages` | number | `0` | Number of pages (0 = single-page) |\n| `arrays` | string[] | `[]` | Array field names |\n| `groups` | string[] | `[]` | Group field names |\n| `hidden` | string[] | `[]` | Hidden fields as `"name:value"` pairs |\n| `fields` | string[] | `[]` | Fields as `"name:type"` pairs |\n| `uiIntegration` | enum | `"material"` | UI library |\n\n**Supported Types for `fields`:**\n\n`input`, `select`, `radio`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`\n\n**Examples:**\n\n```\nngforge_scaffold pages=0 fields=["name:input","email:input"]\nngforge_scaffold pages=3 arrays=["contacts"] groups=["address"]\nngforge_scaffold hidden=["userId:abc123","source:web"]\n```\n\n---\n\n## MCP Resources\n\nIn addition to tools, the server exposes resources that AI can read:\n\n| Resource URI | Description |\n| -------------------------- | ---------------------------------------------- |\n| `ng-forge://instructions` | Best practices guide for generating FormConfig |\n| `ng-forge://examples` | Curated FormConfig examples |\n| `ng-forge://examples/{id}` | Specific example by ID |\n| `ng-forge://field-types` | Field type reference |\n| `ng-forge://validators` | Validator reference |\n| `ng-forge://ui-adapters` | UI library configurations |\n| `ng-forge://docs` | Full documentation index |\n\n---\n\n## Feedback\n\nFound an issue or have a suggestion? [Open an issue on GitHub](https://github.com/ng-forge/ng-forge/issues).'
44
+ content: '# AI Integration\n\nThe `@ng-forge/dynamic-form-mcp` package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants to generate, validate, and work with ng-forge dynamic form configurations.\n\n## Available Tools\n\nThe MCP server provides 4 focused tools:\n\n| Tool | Description | Read-only |\n| ------------------ | ----------------------------------------------------------- | --------- |\n| `ngforge_lookup` | Get documentation about field types, concepts, and patterns | \u2705 |\n| `ngforge_examples` | Get working code examples for common form patterns | \u2705 |\n| `ngforge_validate` | Validate FormConfig and get detailed error feedback | \u2705 |\n| `ngforge_scaffold` | Generate valid FormConfig skeletons | \u2705 |\n\n## Get Started\n\n### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n}\n```\n\n### VS Code with Copilot\n\nCreate `.vscode/mcp.json` in your project:\n\n```json\n{\n "servers": {\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n "mcpServers": {\n "ng-forge": {\n "command": "npx",\n "args": ["-y", "@ng-forge/dynamic-form-mcp"]\n }\n }\n}\n```\n\n### JetBrains IDEs\n\nGo to **Settings > Tools > AI Assistant > Model Context Protocol (MCP)** and add:\n\n| Field | Value |\n| --------- | ----------------------------- |\n| Name | ng-forge |\n| Command | npx |\n| Arguments | -y @ng-forge/dynamic-form-mcp |\n\n------------ | --------------------------------------------------------- | ---------- | ----------------------- |\n| `topic` | string | (required) | Topic to look up |\n| `depth` | `"brief"` \\| `"full"` \\| `"schema"` | `"full"` | Level of detail |\n| `uiIntegration` | `"material"` \\| `"bootstrap"` \\| `"primeng"` \\| `"ionic"` | - | Filter UI-specific info |\n\n**Available Topics:**\n\n| Category | Topics |\n| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Field Types | `input`, `select`, `radio`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`, `hidden`, `text`, `button`, `submit`, `next`, `previous`, `addArrayItem`, `prependArrayItem`, `insertArrayItem`, `removeArrayItem`, `popArrayItem`, `shiftArrayItem` |\n| Containers | `group`, `row`, `array`, `page` |\n| Concepts | `validation`, `conditional`, `derivation`, `options-format`, `expression-variables`, `async-validators`, `validation-messages` |\n| Patterns | `golden-path`, `multi-page-gotchas`, `pitfalls`, `workflow` |\n\n**Examples:**\n\n```\nngforge_lookup topic="hidden" depth="brief"\nngforge_lookup topic="conditional" depth="full"\nngforge_lookup topic="input" depth="schema" uiIntegration="material"\n```\n\n---\n\n### ngforge_examples\n\nGet working code examples for common patterns.\n\n| Parameter | Type | Default | Description |\n| --------- | ----------------------------------------------------- | ---------- | --------------- |\n| `pattern` | string | (required) | Pattern name |\n| `depth` | `"minimal"` \\| `"brief"` \\| `"full"` \\| `"explained"` | `"full"` | Level of detail |\n\n**Available Patterns:**\n\n| Pattern | Description | Lines |\n| --------------------- | ---------------------------------------- | ----- |\n| `minimal-multipage` | Simplest 2-page wizard form | ~50 |\n| `minimal-array` | Array with add/remove buttons | ~30 |\n| `minimal-conditional` | Show/hide field based on condition | ~25 |\n| `minimal-validation` | Password confirmation validation | ~20 |\n| `minimal-hidden` | Hidden fields in multi-page form | ~15 |\n| `derivation` | Value derivation (computed fields) | - |\n| `conditional` | Conditional visibility patterns | - |\n| `multi-page` | Multi-step wizard forms | - |\n| `validation` | Form validation patterns | - |\n| `complete` | Full form with all major features | - |\n| `mega` | Kitchen sink demonstrating every feature | - |\n\n**Examples:**\n\n```\nngforge_examples pattern="minimal-multipage" depth="minimal"\nngforge_examples pattern="conditional" depth="explained"\n```\n\n---\n\n### ngforge_validate\n\nValidate FormConfig and get detailed error feedback.\n\n| Parameter | Type | Default | Description |\n| --------------- | --------------------------------------------------------- | ------------ | ------------------------------ |\n| `config` | string \\| object | (required) | File path or JSON config |\n| `uiIntegration` | `"material"` \\| `"bootstrap"` \\| `"primeng"` \\| `"ionic"` | `"material"` | UI library to validate against |\n\n**Input Detection:**\n\n| Input | Treated As |\n| ------------------------ | ------------------ |\n| Ends with `.ts` or `.js` | File path |\n| Starts with `{` or `[` | JSON string |\n| Object | Validated directly |\n\n**Example Errors:**\n\n- "Hidden field missing REQUIRED value property"\n- "options MUST be at FIELD level, NOT inside props"\n- "row containers do NOT support logic blocks"\n\n**Examples:**\n\n```\nngforge_validate config="/path/to/form.config.ts"\nngforge_validate config=\'{"fields":[...]}\' uiIntegration="bootstrap"\n```\n\n---\n\n### ngforge_scaffold\n\nGenerate valid FormConfig skeletons.\n\n| Parameter | Type | Default | Description |\n| --------------- | -------- | ------------ | ------------------------------------- |\n| `pages` | number | `0` | Number of pages (0 = single-page) |\n| `arrays` | string[] | `[]` | Array field names |\n| `groups` | string[] | `[]` | Group field names |\n| `hidden` | string[] | `[]` | Hidden fields as `"name:value"` pairs |\n| `fields` | string[] | `[]` | Fields as `"name:type"` pairs |\n| `uiIntegration` | enum | `"material"` | UI library |\n\n**Supported Types for `fields`:**\n\n`input`, `select`, `radio`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`\n\n**Examples:**\n\n```\nngforge_scaffold pages=0 fields=["name:input","email:input"]\nngforge_scaffold pages=3 arrays=["contacts"] groups=["address"]\nngforge_scaffold hidden=["userId:abc123","source:web"]\n```\n\n---\n\n## MCP Resources\n\nIn addition to tools, the server exposes resources that AI can read:\n\n| Resource URI | Description |\n| -------------------------- | ---------------------------------------------- |\n| `ng-forge://instructions` | Best practices guide for generating FormConfig |\n| `ng-forge://examples` | Curated FormConfig examples |\n| `ng-forge://examples/{id}` | Specific example by ID |\n| `ng-forge://field-types` | Field type reference |\n| `ng-forge://validators` | Validator reference |\n| `ng-forge://ui-adapters` | UI library configurations |\n| `ng-forge://docs` | Full documentation index |\n\n---\n\n## Feedback\n\nFound an issue or have a suggestion? [Open an issue on GitHub](https://github.com/ng-forge/ng-forge/issues).'
39
45
  },
40
46
  {
41
47
  id: "dynamic-behavior-conditional-logic-overview",
42
48
  title: "Dynamic Behavior Conditional Logic Overview",
43
49
  category: "dynamic-behavior",
44
- content: "Control field behavior dynamically based on form state. Dynamic forms provides a declarative API for conditional visibility, required state, and readonly state that maps directly to Angular's signal forms.\n\n## Signal Forms Integration\n\nThe library integrates with Angular's signal forms logic functions:\n\n```typescript\nimport { hidden, readonly, required } from '@angular/forms/signals';\n```\n\nAll conditional logic configuration is applied using these functions, providing:\n\n- **Reactive updates** when form state changes\n- **Type-safe** conditional expressions\n- **Automatic re-evaluation** on dependencies\n- **Integration** with form validation state\n\n## Static Properties\n\nUse simple boolean properties for fields with fixed states.\n\n### hidden\n\nHide a field from view (field still participates in form state):\n\n```typescript\n{\n key: 'internalId',\n type: 'input',\n value: '',\n label: 'Internal ID',\n hidden: true,\n}\n```\n\nThe field is hidden from the UI but still included in the form value.\n\n### disabled\n\nDisable user interaction:\n\n```typescript\n{\n key: 'systemField',\n type: 'input',\n value: 'auto-generated',\n label: 'System Field',\n disabled: true,\n}\n```\n\n**Note:** The `disabled` property is handled at the component level and does not use signal forms logic functions. It's a static UI property that prevents user interaction.\n\n### readonly\n\nMake a field read-only (displays value but prevents modification):\n\n```typescript\n{\n key: 'createdAt',\n type: 'input',\n value: '2024-01-15',\n label: 'Created Date',\n readonly: true,\n}\n```\n\n## Dynamic Conditional Logic\n\nFor conditional behavior based on form state, use the `logic` array with `LogicConfig` objects.\n\n```typescript\ninterface LogicConfig {\n /** Logic type */\n type: 'hidden' | 'readonly' | 'disabled' | 'required';\n\n /** Boolean expression, static value, or form state condition */\n condition: ConditionalExpression | boolean | FormStateCondition;\n}\n```\n\n`FormStateCondition` values (`'formInvalid'`, `'formSubmitting'`, `'pageInvalid'`) are primarily used for button disabled logic.\n\n### Conditional Visibility (hidden)\n\nShow or hide fields based on other field values.\n\n#### Show Email When Contact Method is Email\n\n```typescript\n{\n key: 'contactMethod',\n type: 'select',\n value: '',\n options: [\n { value: 'email', label: 'Email' },\n { value: 'phone', label: 'Phone' },\n ],\n}\n{\n key: 'email',\n type: 'input',\n value: '',\n label: 'Email Address',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'notEquals',\n value: 'email',\n },\n }],\n}\n```\n\nWhen `contactMethod !== 'email'`, the email field is hidden.\n\n### Conditional Required\n\nMake fields required based on conditions.\n\n#### Tax ID Required for Business Accounts\n\n```typescript\n{\n key: 'accountType',\n type: 'radio',\n value: 'personal',\n options: [\n { value: 'personal', label: 'Personal' },\n { value: 'business', label: 'Business' },\n ],\n}\n{\n key: 'taxId',\n type: 'input',\n value: '',\n label: 'Tax ID',\n logic: [{\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n### Conditional Readonly\n\nMake fields read-only based on conditions.\n\n#### Lock Field After Submission\n\n```typescript\n{\n key: 'status',\n type: 'select',\n value: 'draft',\n options: [\n { value: 'draft', label: 'Draft' },\n { value: 'submitted', label: 'Submitted' },\n ],\n}\n{\n key: 'documentNumber',\n type: 'input',\n value: '',\n label: 'Document Number',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'equals',\n value: 'submitted',\n },\n }],\n}\n```\n\nOnce status is \"submitted\", the document number becomes read-only.\n\n## Basic Conditional Expression\n\nThe most common conditional expression checks a specific field's value:\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'fieldKey',\n operator: 'equals',\n value: 'expectedValue',\n}\n```\n\n**Components:**\n\n- `type: 'fieldValue'` - Check a specific field\n- `fieldPath` - The field key to check\n- `operator` - Comparison operator (see [All Operators](#all-operators))\n- `value` - Value to compare against\n\n## Quick Example\n\nShow a field only when another field has a specific value:\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n label: 'Email Address',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'notEquals',\n value: 'email',\n },\n },\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'equals',\n value: 'email',\n },\n },\n ],\n}\n```\n\nThis field is hidden unless `contactMethod === 'email'`, and required when visible. See the [Examples](/docs/examples) page for complete form implementations.\n\n## When Logic Runs\n\nConditional logic is evaluated:\n\n- **On form value change** - Any time a dependent field changes\n- **On initialization** - When the form is created\n- **Reactively** - Uses Angular's signal forms for automatic updates\n\n### Evaluation Flow\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 LOGIC EVALUATION FLOW \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2502\n\u2502 Form Value Changes \u2502\n\u2502 \u2502 \u2502\n\u2502 \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Signal Updates \u2502\u25C4\u2500\u2500\u2500\u2500 Angular's reactive system \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502\n\u2502 \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Evaluate logic \u2502 \u2502\n\u2502 \u2502 conditions \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u25BC \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 true \u2502 \u2502false \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502 \u2502\n\u2502 \u25BC \u25BC \u2502\n\u2502 Apply Remove \u2502\n\u2502 effect effect \u2502\n\u2502 (hide, (show, \u2502\n\u2502 require, optional, \u2502\n\u2502 readonly) editable) \u2502\n\u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Expression Types\n\n### fieldValue\n\nCheck a specific field's value - the most common expression type.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n```\n\n**Use when:** Checking a single field's value\n\n**Example:**\n\n```typescript\n{\n key: 'companyName',\n type: 'input',\n value: '',\n logic: [{\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n### formValue\n\nCompare the entire form value object against a specific value using operators.\n\n```typescript\n{\n type: 'formValue',\n operator: 'equals',\n value: { status: 'active', role: 'admin' },\n}\n```\n\n**Use when:** Checking if the entire form matches a specific state\n\n**Note:** For complex logic involving multiple fields with JavaScript expressions, use `javascript` or `custom` type instead.\n\n### javascript\n\nJavaScript expressions with access to `fieldValue` (current field) and `formValue` (entire form).\n\n```typescript\n{\n type: 'javascript',\n expression: 'new Date(fieldValue) > new Date()',\n}\n```\n\n**Use when:** Custom logic on field value or complex multi-field conditions\n\n**Examples:**\n\n```typescript\n// Check current field value\n{\n key: 'eventDate',\n type: 'datepicker',\n value: null,\n logic: [{\n type: 'readonly',\n condition: {\n type: 'javascript',\n expression: 'new Date(fieldValue) < new Date()',\n },\n }],\n}\n\n// Check multiple form fields (replaces old formValue expression pattern)\n{\n key: 'stateProvince',\n type: 'select',\n value: '',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.country !== \"US\" && formValue.country !== \"CA\"',\n },\n }],\n}\n```\n\n**Safe member access:** Accessing nested properties on `null` or `undefined` returns `undefined` (no errors thrown):\n\n```typescript\n{\n type: 'javascript',\n // Safe even when user, profile, or preferences is null/undefined\n expression: 'formValue.user.profile.preferences.notifications === true',\n}\n```\n\n### custom\n\nAdvanced custom expressions with access to both field and form values.\n\n```typescript\n{\n type: 'custom',\n expression: 'fieldValue > formValue.minAge && fieldValue < formValue.maxAge',\n}\n```\n\n**Safe member access:** Like `formValue` expressions, nested property access is safe:\n\n```typescript\n{\n type: 'custom',\n // Safe even when nested values are null/undefined\n expression: 'fieldValue !== formValue.user.profile.firstName',\n}\n```\n\n## All Operators\n\n### Equality Operators\n\n#### equals\n\nExact match comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'equals',\n value: 'active',\n}\n```\n\n#### notEquals\n\nNot equal to comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'notEquals',\n value: 'archived',\n}\n```\n\n### Comparison Operators\n\n#### greater\n\nGreater than comparison (numbers/dates).\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greater',\n value: 18,\n}\n```\n\n#### less\n\nLess than comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'quantity',\n operator: 'less',\n value: 100,\n}\n```\n\n#### greaterOrEqual\n\nGreater than or equal to.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 21,\n}\n```\n\n#### lessOrEqual\n\nLess than or equal to.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'discount',\n operator: 'lessOrEqual',\n value: 100,\n}\n```\n\n### String Operators\n\n#### contains\n\nCheck if string/array contains value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'email',\n operator: 'contains',\n value: '@company.com',\n}\n```\n\n#### startsWith\n\nCheck if string starts with value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'url',\n operator: 'startsWith',\n value: 'https://',\n}\n```\n\n#### endsWith\n\nCheck if string ends with value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'email',\n operator: 'endsWith',\n value: '.gov',\n}\n```\n\n#### matches\n\nRegular expression match.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'zipCode',\n operator: 'matches',\n value: '^[0-9]{5}$',\n}\n```\n\n## Combining Conditions\n\n### AND Logic\n\nAll conditions must be true.\n\n```typescript\n{\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'hasTeam',\n operator: 'equals',\n value: true,\n },\n {\n type: 'fieldValue',\n fieldPath: 'teamSize',\n operator: 'greater',\n value: 5,\n },\n ],\n}\n```\n\n**Use case:** Field required when all conditions are met.\n\n```typescript\n{\n key: 'enterpriseFeatures',\n type: 'checkbox',\n label: 'Enable Enterprise Features',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'plan',\n operator: 'equals',\n value: 'enterprise',\n },\n ],\n },\n }],\n}\n```\n\n### OR Logic\n\nAt least one condition must be true.\n\n```typescript\n{\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'equals',\n value: 'admin',\n },\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'equals',\n value: 'owner',\n },\n ],\n}\n```\n\n**Use case:** Show field for multiple roles.\n\n```typescript\n{\n key: 'adminPanel',\n type: 'group',\n label: 'Administration',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'notEquals',\n value: 'admin',\n },\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'notEquals',\n value: 'owner',\n },\n ],\n },\n }],\n}\n```\n\n### Nested Logic\n\nCombine AND/OR logic for complex conditions.\n\n```typescript\n{\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'US',\n },\n {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 21,\n },\n {\n type: 'fieldValue',\n fieldPath: 'hasParentalConsent',\n operator: 'equals',\n value: true,\n },\n ],\n },\n ],\n}\n```\n\nThis means: \"Country must be US AND (age >= 21 OR has parental consent)\"\n\n## Practical Examples\n\n### Show Field Based on Multiple Conditions\n\n```typescript\n{\n key: 'internationalShipping',\n type: 'checkbox',\n label: 'Enable International Shipping',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'free',\n },\n {\n type: 'fieldValue',\n fieldPath: 'verified',\n operator: 'equals',\n value: false,\n },\n ],\n },\n }],\n}\n```\n\nHidden for free accounts OR unverified accounts.\n\n### Required Field with Complex Logic\n\n```typescript\n{\n key: 'taxExemptionNumber',\n type: 'input',\n value: '',\n label: 'Tax Exemption Number',\n logic: [{\n type: 'required',\n condition: {\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'claimsTaxExemption',\n operator: 'equals',\n value: true,\n },\n {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'US',\n },\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'CA',\n },\n ],\n },\n ],\n },\n }],\n}\n```\n\n### Dynamic Read-Only Based on Status\n\n```typescript\n{\n key: 'orderItems',\n type: 'group',\n label: 'Order Items',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'shipped',\n },\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'delivered',\n },\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'cancelled',\n },\n ],\n },\n }],\n}\n```\n\nOrder items become read-only once order is shipped, delivered, or cancelled.\n\n## Best Practices\n\n**Keep conditions readable:**\n\n```typescript\n// \u2705 Good - Easy to understand\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n\n// \u274C Avoid - Hard to maintain\n{\n type: 'formValue',\n expression: 'formValue.accountType === \"business\" && formValue.country !== null && formValue.hasTeam',\n}\n```\n\n## ConditionalExpression Interface\n\n```typescript\ninterface ConditionalExpression {\n /** Expression type - includes 'and' and 'or' for combining conditions */\n type: 'fieldValue' | 'formValue' | 'javascript' | 'custom' | 'and' | 'or';\n\n /** Field path for fieldValue type */\n fieldPath?: string;\n\n /**\n * Comparison operator\n * - For 'fieldValue': compares field at fieldPath against value\n * - For 'formValue': compares entire form object against value\n */\n operator?:\n | 'equals'\n | 'notEquals'\n | 'greater'\n | 'less'\n | 'greaterOrEqual'\n | 'lessOrEqual'\n | 'contains'\n | 'startsWith'\n | 'endsWith'\n | 'matches';\n\n /** Value to compare against (for fieldValue/formValue with operator) */\n value?: unknown;\n\n /**\n * JavaScript expression string\n * - For 'javascript': Has access to fieldValue and formValue\n * - For 'custom': Name of registered custom function\n */\n expression?: string;\n\n /** Array of sub-conditions for 'and' and 'or' types */\n conditions?: ConditionalExpression[];\n}\n```\n\n**Expression types summary:**\n\n| Type | Uses | Purpose |\n| ------------ | -------------------------------- | ---------------------------------------------- |\n| `fieldValue` | `fieldPath`, `operator`, `value` | Compare a specific field's value |\n| `formValue` | `operator`, `value` | Compare entire form object |\n| `javascript` | `expression` | Custom JS with `fieldValue`/`formValue` access |\n| `custom` | `expression` | Call registered custom function |\n| `and`/`or` | `conditions` | Combine multiple conditions |\n\n## Common Patterns\n\n### Show/Hide Field Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n /* when to hide */\n },\n },\n];\n```\n\n### Conditional Required Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n /* when to hide */\n },\n },\n {\n type: 'required',\n condition: {\n /* when to require */\n },\n },\n];\n```\n\n### Multiple Conditions Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n type: 'and', // or 'or'\n conditions: [\n {\n /* condition 1 */\n },\n {\n /* condition 2 */\n },\n ],\n },\n },\n];\n```\n\n## External Data in Conditions\n\nAccess external application state (user roles, permissions, feature flags) in conditions using `externalData`:\n\n```typescript\nconst config = {\n externalData: {\n userRole: computed(() => authService.role()),\n featureFlags: computed(() => ({\n advancedMode: featureService.isAdvanced(),\n })),\n },\n fields: [\n {\n key: 'adminNotes',\n type: 'textarea',\n label: 'Admin Notes',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: \"externalData.userRole !== 'admin'\",\n },\n },\n ],\n },\n {\n key: 'advancedSettings',\n type: 'input',\n label: 'Advanced Settings',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'externalData.featureFlags.advancedMode !== true',\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n**Key points:**\n\n- Each property in `externalData` must be a Signal (`signal()` or `computed()`)\n- Changes to external signals automatically re-evaluate conditions\n- Access values via `externalData.propertyName` in JavaScript expressions\n\n## Related\n\n- **[Value Derivation](../value-derivation/basics/)** - Computed field values\n- **[Validation](../../validation/basics/)** - Conditional validation\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration\n- **[Examples](/docs/examples)** - Real-world form patterns"
50
+ content: "Control field behavior dynamically based on form state. Dynamic forms provides a declarative API for conditional visibility, required state, and readonly state that maps directly to Angular's signal forms.\n\n## Signal Forms Integration\n\nThe library integrates with Angular's signal forms logic functions:\n\n```typescript\nimport { hidden, readonly, required } from '@angular/forms/signals';\n```\n\nAll conditional logic configuration is applied using these functions, providing:\n\n- **Reactive updates** when form state changes\n- **Type-safe** conditional expressions\n- **Automatic re-evaluation** on dependencies\n- **Integration** with form validation state\n\n## Static Properties\n\nUse simple boolean properties for fields with fixed states.\n\n### hidden\n\nHide a field from view (field still participates in form state):\n\n```typescript\n{\n key: 'internalId',\n type: 'input',\n value: '',\n label: 'Internal ID',\n hidden: true,\n}\n```\n\nThe field is hidden from the UI but still included in the form value.\n\n### disabled\n\nDisable user interaction:\n\n```typescript\n{\n key: 'systemField',\n type: 'input',\n value: 'auto-generated',\n label: 'System Field',\n disabled: true,\n}\n```\n\n**Note:** The `disabled` property is handled at the component level and does not use signal forms logic functions. It's a static UI property that prevents user interaction.\n\n### readonly\n\nMake a field read-only (displays value but prevents modification):\n\n```typescript\n{\n key: 'createdAt',\n type: 'input',\n value: '2024-01-15',\n label: 'Created Date',\n readonly: true,\n}\n```\n\n## Dynamic Conditional Logic\n\nFor conditional behavior based on form state, use the `logic` array with `LogicConfig` objects.\n\n```typescript\ninterface LogicConfig {\n /** Logic type */\n type: 'hidden' | 'readonly' | 'disabled' | 'required';\n\n /** Boolean expression, static value, or form state condition */\n condition: ConditionalExpression | boolean | FormStateCondition;\n}\n```\n\n`FormStateCondition` values (`'formInvalid'`, `'formSubmitting'`, `'pageInvalid'`) are primarily used for button disabled logic.\n\n### Conditional Visibility (hidden)\n\nShow or hide fields based on other field values.\n\n#### Show Email When Contact Method is Email\n\n```typescript\n{\n key: 'contactMethod',\n type: 'select',\n value: '',\n options: [\n { value: 'email', label: 'Email' },\n { value: 'phone', label: 'Phone' },\n ],\n}\n{\n key: 'email',\n type: 'input',\n value: '',\n label: 'Email Address',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'notEquals',\n value: 'email',\n },\n }],\n}\n```\n\nWhen `contactMethod !== 'email'`, the email field is hidden.\n\n### Conditional Required\n\nMake fields required based on conditions.\n\n#### Tax ID Required for Business Accounts\n\n```typescript\n{\n key: 'accountType',\n type: 'radio',\n value: 'personal',\n options: [\n { value: 'personal', label: 'Personal' },\n { value: 'business', label: 'Business' },\n ],\n}\n{\n key: 'taxId',\n type: 'input',\n value: '',\n label: 'Tax ID',\n logic: [{\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n### Conditional Readonly\n\nMake fields read-only based on conditions.\n\n#### Lock Field After Submission\n\n```typescript\n{\n key: 'status',\n type: 'select',\n value: 'draft',\n options: [\n { value: 'draft', label: 'Draft' },\n { value: 'submitted', label: 'Submitted' },\n ],\n}\n{\n key: 'documentNumber',\n type: 'input',\n value: '',\n label: 'Document Number',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'equals',\n value: 'submitted',\n },\n }],\n}\n```\n\nOnce status is \"submitted\", the document number becomes read-only.\n\n## Basic Conditional Expression\n\nThe most common conditional expression checks a specific field's value:\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'fieldKey',\n operator: 'equals',\n value: 'expectedValue',\n}\n```\n\n**Components:**\n\n- `type: 'fieldValue'` - Check a specific field\n- `fieldPath` - The field key to check\n- `operator` - Comparison operator (see [All Operators](#all-operators))\n- `value` - Value to compare against\n\n## Quick Example\n\nShow a field only when another field has a specific value:\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n label: 'Email Address',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'notEquals',\n value: 'email',\n },\n },\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactMethod',\n operator: 'equals',\n value: 'email',\n },\n },\n ],\n}\n```\n\nThis field is hidden unless `contactMethod === 'email'`, and required when visible. See the [Examples](/examples) page for complete form implementations.\n\n## When Logic Runs\n\nConditional logic is evaluated:\n\n- **On form value change** - Any time a dependent field changes\n- **On initialization** - When the form is created\n- **Reactively** - Uses Angular's signal forms for automatic updates\n\n### Evaluation Flow\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 LOGIC EVALUATION FLOW \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2502\n\u2502 Form Value Changes \u2502\n\u2502 \u2502 \u2502\n\u2502 \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Signal Updates \u2502\u25C4\u2500\u2500\u2500\u2500 Angular's reactive system \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502\n\u2502 \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Evaluate logic \u2502 \u2502\n\u2502 \u2502 conditions \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u25BC \u25BC \u2502\n\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 true \u2502 \u2502false \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u2502 \u2502 \u2502\n\u2502 \u25BC \u25BC \u2502\n\u2502 Apply Remove \u2502\n\u2502 effect effect \u2502\n\u2502 (hide, (show, \u2502\n\u2502 require, optional, \u2502\n\u2502 readonly) editable) \u2502\n\u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Expression Types\n\n### fieldValue\n\nCheck a specific field's value - the most common expression type.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n```\n\n**Use when:** Checking a single field's value\n\n**Example:**\n\n```typescript\n{\n key: 'companyName',\n type: 'input',\n value: '',\n logic: [{\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n### formValue\n\nCompare the entire form value object against a specific value using operators.\n\n```typescript\n{\n type: 'formValue',\n operator: 'equals',\n value: { status: 'active', role: 'admin' },\n}\n```\n\n**Use when:** Checking if the entire form matches a specific state\n\n**Note:** This type is rarely useful in practice \u2014 deep equality on an entire form object is an unusual requirement. For conditions that involve multiple specific fields, use `javascript` or `custom` expressions instead (e.g. `formValue.status === 'active' && formValue.role === 'admin'`).\n\n### javascript\n\nJavaScript expressions with access to `fieldValue` (current field) and `formValue` (entire form).\n\n```typescript\n{\n type: 'javascript',\n expression: 'new Date(fieldValue) > new Date()',\n}\n```\n\n**Use when:** Custom logic on field value or complex multi-field conditions\n\n**Examples:**\n\n```typescript\n// Check current field value\n{\n key: 'eventDate',\n type: 'datepicker',\n value: null,\n logic: [{\n type: 'readonly',\n condition: {\n type: 'javascript',\n expression: 'new Date(fieldValue) < new Date()',\n },\n }],\n}\n\n// Check multiple form fields (replaces old formValue expression pattern)\n{\n key: 'stateProvince',\n type: 'select',\n value: '',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.country !== \"US\" && formValue.country !== \"CA\"',\n },\n }],\n}\n```\n\n**Safe member access:** Accessing nested properties on `null` or `undefined` returns `undefined` (no errors thrown):\n\n```typescript\n{\n type: 'javascript',\n // Safe even when user, profile, or preferences is null/undefined\n expression: 'formValue.user.profile.preferences.notifications === true',\n}\n```\n\n### custom\n\nAdvanced custom expressions with access to both field and form values.\n\n```typescript\n{\n type: 'custom',\n expression: 'fieldValue > formValue.minAge && fieldValue < formValue.maxAge',\n}\n```\n\n**Safe member access:** Like `formValue` expressions, nested property access is safe:\n\n```typescript\n{\n type: 'custom',\n // Safe even when nested values are null/undefined\n expression: 'fieldValue !== formValue.user.profile.firstName',\n}\n```\n\n### Field State in Expressions\n\n`javascript` and `custom` expressions have access to two additional variables for querying field interaction state:\n\n- **`fieldState`** \u2014 the current field's own state\n- **`formFieldState`** \u2014 state of any field in the form, by key\n\n#### fieldState\n\nUse `fieldState` to react to the current field's own interaction state:\n\n```typescript\n// Lock the field as soon as the user edits it\n{\n key: 'accountNumber',\n type: 'input',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'javascript',\n expression: 'fieldState.dirty',\n },\n }],\n}\n```\n\n**Available properties:**\n\n| Property | Type | Description |\n| ---------- | --------- | ----------------------------------- |\n| `touched` | `boolean` | User has focused and left the field |\n| `dirty` | `boolean` | User has changed the field value |\n| `pristine` | `boolean` | Equivalent to `!dirty` |\n| `valid` | `boolean` | Field has no validation errors |\n| `invalid` | `boolean` | Field has validation errors |\n| `pending` | `boolean` | Async validation is in progress |\n| `hidden` | `boolean` | Field is currently hidden |\n| `readonly` | `boolean` | Field is currently readonly |\n| `disabled` | `boolean` | Field is currently disabled |\n\n#### formFieldState\n\nUse `formFieldState` to react to another field's state. Access by field key:\n\n```typescript\n// Make a field readonly once a related field has been touched\n{\n key: 'billingAddress',\n type: 'input',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'javascript',\n expression: 'formFieldState.shippingAddress.dirty',\n },\n }],\n}\n```\n\n`formFieldState` has the same properties as `fieldState`, keyed by field name.\n\n**Example \u2014 show a confirmation field only after the primary field is dirty:**\n\n```typescript\n{\n key: 'confirmEmail',\n type: 'input',\n label: 'Confirm Email',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: '!formFieldState.email.dirty',\n },\n }],\n}\n```\n\n### http\n\nEvaluate a condition by sending an HTTP request and inspecting the response. The request fires automatically when declared query params change, with built-in debouncing.\n\n```typescript\n{\n type: 'http',\n http: {\n url: '/api/permissions',\n queryParams: {\n role: 'formValue.userRole',\n },\n },\n responseExpression: 'response.canEdit',\n pendingValue: false,\n}\n```\n\n**Use when:** Field visibility or state must be determined server-side (permissions, feature flags, country-specific rules).\n\n**Full example \u2014 hide an admin panel based on server permissions:**\n\n```typescript\n{\n key: 'adminPanel',\n type: 'input',\n label: 'Admin Panel Access Code',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'http',\n http: {\n url: '/api/permissions',\n queryParams: {\n role: 'formValue.userRole',\n },\n },\n responseExpression: 'response.hideAdminPanel',\n pendingValue: true, // Hide while checking\n },\n }],\n}\n```\n\n**HTTP condition properties:**\n\n| Property | Type | Required | Default | Description |\n| -------------------- | ------------------- | -------- | ------------ | ------------------------------------------------------------------------ |\n| `type` | `'http'` | Yes | \u2014 | Identifies this as an HTTP condition |\n| `http` | `HttpRequestConfig` | Yes | \u2014 | Request configuration (see below) |\n| `responseExpression` | `string` | No | `!!response` | Expression evaluated with `{ response }` in scope. Must return a boolean |\n| `pendingValue` | `boolean` | No | `false` | Value returned while the request is in-flight |\n| `cacheDurationMs` | `number` | No | `30000` | How long to cache responses (ms) |\n| `debounceMs` | `number` | No | `300` | Debounce delay before re-sending (ms) |\n\n**`HttpRequestConfig` quick reference:**\n\n| Property | Description |\n| ------------------------- | ----------------------------------------------------------------------------------- |\n| `url` | Request URL. Use `:key` placeholders for path parameters |\n| `method` | HTTP method. Defaults to `'GET'` |\n| `params` | Path parameters. `:key` placeholders in the URL replaced with evaluated expressions |\n| `queryParams` | Key/value map. Values are expressions evaluated against form context |\n| `body` | Request body for POST/PUT/PATCH |\n| `evaluateBodyExpressions` | When `true`, top-level `body` string values are evaluated as expressions |\n| `headers` | Request headers |\n\n**HTTP condition on `required` \u2014 server-driven required fields:**\n\n```typescript\n{\n key: 'taxId',\n type: 'input',\n logic: [{\n type: 'required',\n condition: {\n type: 'http',\n http: {\n url: '/api/tax-rules',\n queryParams: { country: 'formValue.country' },\n },\n responseExpression: 'response.taxIdRequired',\n pendingValue: false, // Optional while checking\n },\n }],\n}\n```\n\n### async\n\nEvaluate a condition using a custom async function registered in `customFnConfig.asyncConditions`. Functions receive the full form context and must return a `Promise<boolean>` or `Observable<boolean>`.\n\n```typescript\n{\n type: 'async',\n asyncFunctionName: 'checkPermission',\n pendingValue: false,\n}\n```\n\n**Use when:** Condition logic involves Angular service injection, complex async operations, or anything that `http` conditions cannot express directly.\n\n> **Why `inject()` works here:** `customFnConfig` functions are called within an Angular injection context, so Angular's `inject()` API is available \u2014 the same way it works in a constructor or field initializer. Import `inject` from `@angular/core` as usual.\n\n**Registration and usage:**\n\n```typescript\nimport { inject } from '@angular/core';\n\nconst formConfig = {\n customFnConfig: {\n asyncConditions: {\n checkReadonly: (context) => {\n return inject(PermissionsService).canEdit(context.formValue.resourceId as string);\n },\n },\n },\n\n fields: [\n {\n key: 'salary',\n type: 'input',\n label: 'Salary',\n logic: [\n {\n type: 'readonly',\n condition: {\n type: 'async',\n asyncFunctionName: 'checkReadonly',\n pendingValue: false, // Editable while checking\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n**Async condition properties:**\n\n| Property | Type | Required | Default | Description |\n| ------------------- | --------- | -------- | ------- | --------------------------------------------------- |\n| `type` | `'async'` | Yes | \u2014 | Identifies this as an async condition |\n| `asyncFunctionName` | `string` | Yes | \u2014 | Name registered in `customFnConfig.asyncConditions` |\n| `pendingValue` | `boolean` | No | `false` | Value returned while the function is resolving |\n| `debounceMs` | `number` | No | `300` | Debounce delay before re-evaluating (ms) |\n\n**Choosing `pendingValue`:**\n\nThe right `pendingValue` depends on the logic type and desired UX:\n\n| Logic type | `pendingValue: false` | `pendingValue: true` |\n| ---------- | ----------------------- | ----------------------- |\n| `hidden` | Visible while checking | Hidden while checking |\n| `required` | Optional while checking | Required while checking |\n| `readonly` | Editable while checking | Readonly while checking |\n| `disabled` | Enabled while checking | Disabled while checking |\n\n## All Operators\n\n### Equality Operators\n\n#### equals\n\nExact match comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'equals',\n value: 'active',\n}\n```\n\n#### notEquals\n\nNot equal to comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'status',\n operator: 'notEquals',\n value: 'archived',\n}\n```\n\n### Comparison Operators\n\n#### greater\n\nGreater than comparison (numbers/dates).\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greater',\n value: 18,\n}\n```\n\n#### less\n\nLess than comparison.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'quantity',\n operator: 'less',\n value: 100,\n}\n```\n\n#### greaterOrEqual\n\nGreater than or equal to.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 21,\n}\n```\n\n#### lessOrEqual\n\nLess than or equal to.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'discount',\n operator: 'lessOrEqual',\n value: 100,\n}\n```\n\n### String Operators\n\n#### contains\n\nCheck if string/array contains value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'email',\n operator: 'contains',\n value: '@company.com',\n}\n```\n\n#### startsWith\n\nCheck if string starts with value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'url',\n operator: 'startsWith',\n value: 'https://',\n}\n```\n\n#### endsWith\n\nCheck if string ends with value.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'email',\n operator: 'endsWith',\n value: '.gov',\n}\n```\n\n#### matches\n\nRegular expression match.\n\n```typescript\n{\n type: 'fieldValue',\n fieldPath: 'zipCode',\n operator: 'matches',\n value: '^[0-9]{5}$',\n}\n```\n\n## Combining Conditions\n\n### AND Logic\n\nAll conditions must be true.\n\n```typescript\n{\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'hasTeam',\n operator: 'equals',\n value: true,\n },\n {\n type: 'fieldValue',\n fieldPath: 'teamSize',\n operator: 'greater',\n value: 5,\n },\n ],\n}\n```\n\n**Use case:** Field required when all conditions are met.\n\n```typescript\n{\n key: 'enterpriseFeatures',\n type: 'checkbox',\n label: 'Enable Enterprise Features',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'plan',\n operator: 'equals',\n value: 'enterprise',\n },\n ],\n },\n }],\n}\n```\n\n### OR Logic\n\nAt least one condition must be true.\n\n```typescript\n{\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'equals',\n value: 'admin',\n },\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'equals',\n value: 'owner',\n },\n ],\n}\n```\n\n**Use case:** Show field for multiple roles \u2014 hide unless role is `admin` or `owner`.\n\n```typescript\n// Hide the panel when role is neither 'admin' nor 'owner'\n// (i.e. hidden when notEquals 'admin' AND notEquals 'owner')\n{\n key: 'adminPanel',\n type: 'group',\n label: 'Administration',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'notEquals',\n value: 'admin',\n },\n {\n type: 'fieldValue',\n fieldPath: 'role',\n operator: 'notEquals',\n value: 'owner',\n },\n ],\n },\n }],\n}\n```\n\n### Nested Logic\n\nCombine AND/OR logic for complex conditions.\n\n```typescript\n{\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'US',\n },\n {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 21,\n },\n {\n type: 'fieldValue',\n fieldPath: 'hasParentalConsent',\n operator: 'equals',\n value: true,\n },\n ],\n },\n ],\n}\n```\n\nThis means: \"Country must be US AND (age >= 21 OR has parental consent)\"\n\n## Practical Examples\n\n### Show Field Based on Multiple Conditions\n\n```typescript\n{\n key: 'internationalShipping',\n type: 'checkbox',\n label: 'Enable International Shipping',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'free',\n },\n {\n type: 'fieldValue',\n fieldPath: 'verified',\n operator: 'equals',\n value: false,\n },\n ],\n },\n }],\n}\n```\n\nHidden for free accounts OR unverified accounts.\n\n### Required Field with Complex Logic\n\n```typescript\n{\n key: 'taxExemptionNumber',\n type: 'input',\n value: '',\n label: 'Tax Exemption Number',\n logic: [{\n type: 'required',\n condition: {\n type: 'and',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n {\n type: 'fieldValue',\n fieldPath: 'claimsTaxExemption',\n operator: 'equals',\n value: true,\n },\n {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'US',\n },\n {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'CA',\n },\n ],\n },\n ],\n },\n }],\n}\n```\n\n### Dynamic Read-Only Based on Status\n\n```typescript\n{\n key: 'orderItems',\n type: 'group',\n label: 'Order Items',\n logic: [{\n type: 'readonly',\n condition: {\n type: 'or',\n conditions: [\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'shipped',\n },\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'delivered',\n },\n {\n type: 'fieldValue',\n fieldPath: 'orderStatus',\n operator: 'equals',\n value: 'cancelled',\n },\n ],\n },\n }],\n}\n```\n\nOrder items become read-only once order is shipped, delivered, or cancelled.\n\n## Best Practices\n\n**Keep conditions readable:**\n\n```typescript\n// \u2705 Good - Easy to understand\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n\n// \u274C Avoid - Hard to maintain\n{\n type: 'formValue',\n expression: 'formValue.accountType === \"business\" && formValue.country !== null && formValue.hasTeam',\n}\n```\n\n## ConditionalExpression Interface\n\n`ConditionalExpression` is a discriminated union of all expression types:\n\n```typescript\n// Sync expressions\ntype ConditionalExpression =\n | { type: 'fieldValue'; fieldPath: string; operator: Operator; value: unknown }\n | { type: 'formValue'; operator: Operator; value: unknown }\n | { type: 'javascript'; expression: string }\n | { type: 'custom'; expression: string }\n | { type: 'and'; conditions: ConditionalExpression[] }\n | { type: 'or'; conditions: ConditionalExpression[] }\n // Async expressions\n | HttpCondition\n | AsyncCondition;\n\ntype Operator =\n | 'equals'\n | 'notEquals'\n | 'greater'\n | 'less'\n | 'greaterOrEqual'\n | 'lessOrEqual'\n | 'contains'\n | 'startsWith'\n | 'endsWith'\n | 'matches';\n\ninterface HttpCondition {\n type: 'http';\n http: HttpRequestConfig;\n responseExpression?: string; // Evaluated with { response }. Defaults to !!response\n pendingValue?: boolean; // Default: false\n cacheDurationMs?: number; // Default: 30000\n debounceMs?: number; // Default: 300\n}\n\ninterface AsyncCondition {\n type: 'async';\n asyncFunctionName: string;\n pendingValue?: boolean; // Default: false\n debounceMs?: number; // Default: 300\n}\n```\n\n**Expression types summary:**\n\n| Type | Sync/Async | Key properties | Purpose |\n| ------------ | ---------- | -------------------------------- | --------------------------------------------------------------------- |\n| `fieldValue` | Sync | `fieldPath`, `operator`, `value` | Compare a specific field's value |\n| `formValue` | Sync | `operator`, `value` | Compare entire form object |\n| `javascript` | Sync | `expression` | Custom JS with `fieldValue`/`formValue`/`fieldState`/`formFieldState` |\n| `custom` | Sync | `expression` | Inline expression with `fieldValue`/`formValue` (safe member access) |\n| `and`/`or` | Sync | `conditions` | Combine multiple conditions |\n| `http` | Async | `http`, `responseExpression` | Server-driven condition via HTTP request |\n| `async` | Async | `asyncFunctionName` | Custom async function registered in config |\n\n## Common Patterns\n\n### Show/Hide Field Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n /* when to hide */\n },\n },\n];\n```\n\n### Conditional Required Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n /* when to hide */\n },\n },\n {\n type: 'required',\n condition: {\n /* when to require */\n },\n },\n];\n```\n\n### Multiple Conditions Pattern\n\n```typescript\nlogic: [\n {\n type: 'hidden',\n condition: {\n type: 'and', // or 'or'\n conditions: [\n {\n /* condition 1 */\n },\n {\n /* condition 2 */\n },\n ],\n },\n },\n];\n```\n\n## External Data in Conditions\n\nAccess external application state (user roles, permissions, feature flags) in conditions using `externalData`:\n\n```typescript\nconst config = {\n externalData: {\n userRole: computed(() => authService.role()),\n featureFlags: computed(() => ({\n advancedMode: featureService.isAdvanced(),\n })),\n },\n fields: [\n {\n key: 'adminNotes',\n type: 'textarea',\n label: 'Admin Notes',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: \"externalData.userRole !== 'admin'\",\n },\n },\n ],\n },\n {\n key: 'advancedSettings',\n type: 'input',\n label: 'Advanced Settings',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'externalData.featureFlags.advancedMode !== true',\n },\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n**Key points:**\n\n- Each property in `externalData` must be a Signal (`signal()` or `computed()`)\n- Changes to external signals automatically re-evaluate conditions\n- Access values via `externalData.propertyName` in JavaScript expressions\n\n## Related\n\n- **[Value Derivation](../value-derivation/basics/)** \u2014 Computed field values\n- **[Async Derivation](../value-derivation/async/)** \u2014 HTTP and async function derivations, stopOnUserOverride\n- **[Validation](../../validation/basics/)** \u2014 Conditional validation\n- **[Custom Validators](../../validation/custom-validators/)** \u2014 Async and HTTP validators\n- **[Type Safety](../../advanced/type-safety/basics/)** \u2014 TypeScript integration\n- **[Examples](/examples)** \u2014 Real-world form patterns"
45
51
  },
46
52
  {
47
53
  id: "dynamic-behavior-i18n",
@@ -53,13 +59,25 @@ var require_docs = __commonJS({
53
59
  id: "dynamic-behavior-submission",
54
60
  title: "Dynamic Behavior Submission",
55
61
  category: "dynamic-behavior",
56
- content: "Form submission in dynamic forms integrates with Angular Signal Forms' native `submit()` function, providing automatic button disabling, loading states, and server error handling.\n\n## Overview\n\nThe submission system provides:\n\n- Async form submission with automatic loading state\n- Server-side validation error handling\n- Automatic submit button disabling during submission\n- Configurable button disabled behavior\n- Custom disabled logic via `FormStateCondition`\n\n**Note**: The submission mechanism is **optional** - you can still handle submission manually via the `(submitted)` output if you prefer.\n\n## Basic Usage\n\nConfigure form submission with the `submission` property:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { HttpClient } from '@angular/common/http';\nimport { FormConfig, InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst formFields = {\n fields: [\n { type: 'input', key: 'email', label: 'Email', value: '', required: true, email: true },\n { type: 'input', key: 'password', label: 'Password', value: '', required: true, props: { type: 'password' } },\n { type: 'submit', key: 'submit', label: 'Sign In' },\n ],\n} as const satisfies FormConfig;\n\ntype LoginForm = InferFormValue<typeof formFields.fields>;\n\n@Component({...})\nexport class LoginFormComponent {\n private http = inject(HttpClient);\n\n config = {\n ...formFields,\n submission: {\n action: (form: LoginForm) => this.http.post('/api/login', form),\n },\n };\n}\n```\n\n## SubmissionConfig\n\nThe `submission.action` function receives the typed form value and can return an Observable or Promise:\n\n| Return Value | Meaning |\n| ---------------------- | ------------------------------------------ |\n| Completes successfully | Successful submission |\n| `TreeValidationResult` | Server validation errors (single or array) |\n\n**Note:** `TreeValidationResult` from Angular Signal Forms supports both single errors and arrays. You can return a single error object or an array of errors.\n\nWhile the action is executing, the form is in a submitting state, enabling automatic button disabling and loading states.\n\n### Server Error Handling\n\nReturn validation errors to apply them to specific fields using `catchError`:\n\n```typescript\nimport { catchError, of } from 'rxjs';\n\nsubmission: {\n action: (form: FormValue) => this.http.post('/api/register', form).pipe(\n catchError((error) => {\n if (error.error?.code === 'EMAIL_EXISTS') {\n return of([{\n field: 'email',\n error: { kind: 'server', message: 'Email already exists' },\n }]);\n }\n throw error; // Re-throw unexpected errors\n }),\n ),\n}\n```\n\n## Button Disabled Behavior\n\nSubmit and next page buttons are automatically disabled based on form state. Configure defaults via `options`:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n submitButton: {\n disableWhenInvalid: true, // Disable when form is invalid (default: true)\n disableWhileSubmitting: true, // Disable during submission (default: true)\n },\n nextButton: {\n disableWhenPageInvalid: true, // Disable when current page is invalid (default: true)\n disableWhileSubmitting: true, // Disable during submission (default: true)\n }\n }\n};\n```\n\n### SubmitButtonOptions\n\n| Option | Type | Default | Description |\n| ------------------------ | --------- | ------- | ------------------------------ |\n| `disableWhenInvalid` | `boolean` | `true` | Disable when form is invalid |\n| `disableWhileSubmitting` | `boolean` | `true` | Disable during form submission |\n\n### NextButtonOptions\n\n| Option | Type | Default | Description |\n| ------------------------ | --------- | ------- | -------------------------------------------- |\n| `disableWhenPageInvalid` | `boolean` | `true` | Disable when current page has invalid fields |\n| `disableWhileSubmitting` | `boolean` | `true` | Disable during form submission |\n\n## Custom Button Logic\n\nOverride form-level defaults on individual buttons using the `logic` array:\n\n```typescript\n{\n type: 'submit',\n key: 'submit',\n label: 'Submit',\n logic: [\n { type: 'disabled', condition: 'formInvalid' },\n { type: 'disabled', condition: 'formSubmitting' }\n ]\n}\n```\n\n**Note:** `type: 'submit'` is a UI-integration convenience type that pre-configures the button with `SubmitEvent`. Use `type: 'button'` with `event: SubmitEvent` for the core API.\n\n### FormStateCondition\n\nSpecial condition strings for button logic:\n\n| Condition | Description |\n| ------------------ | ------------------------------------------------------------ |\n| `'formInvalid'` | Evaluates to `true` when the form is invalid |\n| `'formSubmitting'` | Evaluates to `true` when form submission is in progress |\n| `'pageInvalid'` | Evaluates to `true` when the current page has invalid fields |\n\n### Logic Precedence\n\nButton disabled state is determined in this order:\n\n1. **Explicit `disabled: true`** - Always wins\n2. **Field-level `logic` array** - If present, overrides form-level defaults\n3. **Form-level options** - Default behavior from `options.submitButton` or `options.nextButton`\n\n### Advanced Logic Example\n\nCombine form state conditions with custom expressions:\n\n```typescript\n{\n type: 'submit',\n key: 'submit',\n label: 'Submit',\n logic: [\n // Disable when form is invalid\n { type: 'disabled', condition: 'formInvalid' },\n // Disable when submitting\n { type: 'disabled', condition: 'formSubmitting' },\n // Also disable if terms not accepted\n {\n type: 'disabled',\n condition: {\n type: 'fieldValue',\n fieldPath: 'acceptTerms',\n operator: 'equals',\n value: false,\n }\n }\n ]\n}\n```\n\n## Manual Submission\n\nIf you prefer manual control, use the `(submitted)` output instead:\n\n```typescript\n@Component({\n template: `<form [dynamic-form]=\"config\" (submitted)=\"onSubmit($event)\"></form>`,\n})\nexport class MyFormComponent {\n onSubmit(value: FormValue) {\n this.http.post('/api/submit', value).subscribe();\n }\n}\n```"
62
+ content: "Form submission in dynamic forms integrates with Angular Signal Forms' native `submit()` function, providing automatic button disabling, loading states, and server error handling.\n\n## Overview\n\nThe submission system provides:\n\n- Async form submission with automatic loading state\n- Server-side validation error handling\n- Automatic submit button disabling during submission\n- Configurable button disabled behavior\n- Custom disabled logic via `FormStateCondition`\n\n**Note**: The submission mechanism is **optional** - you can still handle submission manually via the `(submitted)` output if you prefer.\n\n## Basic Usage\n\nConfigure form submission with the `submission` property:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { HttpClient } from '@angular/common/http';\nimport { FormConfig, InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst formFields = {\n fields: [\n { type: 'input', key: 'email', label: 'Email', value: '', required: true, email: true },\n { type: 'input', key: 'password', label: 'Password', value: '', required: true, props: { type: 'password' } },\n { type: 'submit', key: 'submit', label: 'Sign In' },\n ],\n} as const satisfies FormConfig;\n\ntype LoginForm = InferFormValue<typeof formFields.fields>;\n\n@Component({...})\nexport class LoginFormComponent {\n private http = inject(HttpClient);\n\n config = {\n ...formFields,\n submission: {\n action: (form: LoginForm) => this.http.post('/api/login', form),\n },\n };\n}\n```\n\n## SubmissionConfig\n\nThe `submission.action` function receives the typed form value and can return an Observable or Promise:\n\n| Return Value | Meaning |\n| ---------------------- | ------------------------------------------ |\n| Completes successfully | Successful submission |\n| `TreeValidationResult` | Server validation errors (single or array) |\n\n**Note:** `TreeValidationResult` from Angular Signal Forms supports both single errors and arrays. You can return a single error object or an array of errors.\n\nWhile the action is executing, the form is in a submitting state, enabling automatic button disabling and loading states.\n\n### Server Error Handling\n\nReturn validation errors to apply them to specific fields using `catchError`:\n\n```typescript\nimport { catchError, of } from 'rxjs';\n\nsubmission: {\n action: (form: FormValue) => this.http.post('/api/register', form).pipe(\n catchError((error) => {\n if (error.error?.code === 'EMAIL_EXISTS') {\n return of([{\n field: 'email',\n error: { kind: 'server', message: 'Email already exists' },\n }]);\n }\n throw error; // Re-throw unexpected errors\n }),\n ),\n}\n```\n\n## Button Disabled Behavior\n\nSubmit and next page buttons are automatically disabled based on form state. Configure defaults via `options`:\n\n```typescript\nconst config: FormConfig = {\n fields: [...],\n options: {\n submitButton: {\n disableWhenInvalid: true, // Disable when form is invalid (default: true)\n disableWhileSubmitting: true, // Disable during submission (default: true)\n },\n nextButton: {\n disableWhenPageInvalid: true, // Disable when current page is invalid (default: true)\n disableWhileSubmitting: true, // Disable during submission (default: true)\n }\n }\n};\n```\n\n### SubmitButtonOptions\n\n| Option | Type | Default | Description |\n| ------------------------ | --------- | ------- | ------------------------------ |\n| `disableWhenInvalid` | `boolean` | `true` | Disable when form is invalid |\n| `disableWhileSubmitting` | `boolean` | `true` | Disable during form submission |\n\n### NextButtonOptions\n\n| Option | Type | Default | Description |\n| ------------------------ | --------- | ------- | -------------------------------------------- |\n| `disableWhenPageInvalid` | `boolean` | `true` | Disable when current page has invalid fields |\n| `disableWhileSubmitting` | `boolean` | `true` | Disable during form submission |\n\n## Custom Button Logic\n\nOverride form-level defaults on individual buttons using the `logic` array:\n\n```typescript\n{\n type: 'submit',\n key: 'submit',\n label: 'Submit',\n logic: [\n { type: 'disabled', condition: 'formInvalid' },\n { type: 'disabled', condition: 'formSubmitting' }\n ]\n}\n```\n\n**Note:** `type: 'submit'` is a UI-integration convenience type that pre-configures the button with `SubmitEvent`. Use `type: 'button'` with `event: SubmitEvent` for the core API.\n\n### FormStateCondition\n\nSpecial condition strings for button logic:\n\n| Condition | Description |\n| ------------------ | ------------------------------------------------------------ |\n| `'formInvalid'` | Evaluates to `true` when the form is invalid |\n| `'formSubmitting'` | Evaluates to `true` when form submission is in progress |\n| `'pageInvalid'` | Evaluates to `true` when the current page has invalid fields |\n\n### Logic Precedence\n\nButton disabled state is determined in this order:\n\n1. **Explicit `disabled: true`** - Always wins\n2. **Field-level `logic` array** - If present, overrides form-level defaults\n3. **Form-level options** - Default behavior from `options.submitButton` or `options.nextButton`\n\n### Advanced Logic Example\n\nCombine form state conditions with custom expressions:\n\n```typescript\n{\n type: 'submit',\n key: 'submit',\n label: 'Submit',\n logic: [\n // Disable when form is invalid\n { type: 'disabled', condition: 'formInvalid' },\n // Disable when submitting\n { type: 'disabled', condition: 'formSubmitting' },\n // Also disable if terms not accepted\n {\n type: 'disabled',\n condition: {\n type: 'fieldValue',\n fieldPath: 'acceptTerms',\n operator: 'equals',\n value: false,\n }\n }\n ]\n}\n```\n\n## Value Exclusion\n\nBy default, field values are excluded from the `(submitted)` output when the field is hidden, disabled, or readonly. This prevents stale or irrelevant data from being submitted.\n\nValue exclusion supports a 3-tier configuration hierarchy: **Global > Form > Field**, where the most specific level wins. Internal form state and two-way binding are unaffected.\n\n```typescript\n// Disable hidden value exclusion for this form\nconst config: FormConfig = {\n fields: [...],\n options: {\n excludeValueIfHidden: false,\n }\n};\n```\n\nSee the **Value Exclusion** page under Recipes for full documentation on configuration tiers, per-field overrides, and migration instructions.\n\n## Manual Submission\n\nIf you prefer manual control, use the `(submitted)` output instead:\n\n```typescript\n@Component({\n template: `<form [dynamic-form]=\"config\" (submitted)=\"onSubmit($event)\"></form>`,\n})\nexport class MyFormComponent {\n onSubmit(value: FormValue) {\n this.http.post('/api/submit', value).subscribe();\n }\n}\n```"
63
+ },
64
+ {
65
+ id: "dynamic-behavior-value-derivation-basics-async-derivation",
66
+ title: "Dynamic Behavior Value Derivation Basics Async Derivation",
67
+ category: "dynamic-behavior",
68
+ content: "Derive field values from HTTP responses or custom async functions. Async derivations are ideal for server-driven computed values, address/zip lookups, exchange rates, and any value that requires a network call.\n\n## HTTP Derivations\n\nUse `source: 'http'` to derive a field value from an HTTP response. The request fires when declared dependencies change, with automatic debouncing and in-flight request cancellation.\n\n### Basic Example\n\n```typescript\n{\n key: 'exchangeRate',\n type: 'input',\n label: 'Exchange Rate',\n readonly: true,\n logic: [{\n type: 'derivation',\n source: 'http',\n http: {\n url: '/api/exchange-rate',\n method: 'GET',\n queryParams: {\n currency: 'formValue.currency',\n },\n },\n responseExpression: 'response.rate',\n dependsOn: ['currency'],\n }],\n}\n```\n\nWhen `currency` changes, a GET request is sent and `response.rate` becomes the new field value.\n\n### HttpRequestConfig\n\n| Property | Type | Required | Description |\n| ------------------------- | ------------------------- | -------- | --------------------------------------------------------------------------- |\n| `url` | `string` | Yes | Request URL. Use `:key` placeholders for path parameters |\n| `method` | `string` | No | HTTP method. Defaults to `'GET'` |\n| `params` | `Record<string, string>` | No | Path parameters. Values are expressions evaluated against the form context |\n| `queryParams` | `Record<string, string>` | No | Query parameters. Values are expressions evaluated against the form context |\n| `body` | `Record<string, unknown>` | No | Request body (for POST/PUT/PATCH) |\n| `evaluateBodyExpressions` | `boolean` | No | When `true`, top-level string values in `body` are treated as expressions |\n| `headers` | `Record<string, string>` | No | Request headers |\n\n### Path Parameters\n\nUse `:key` placeholders in the URL and provide values via `params`. Values are expressions evaluated against the form context, then `encodeURIComponent`-encoded:\n\n```typescript\nhttp: {\n url: '/api/users/:userId/orders/:orderId',\n params: {\n userId: 'formValue.userId',\n orderId: 'formValue.orderId',\n },\n}\n```\n\n### Query Params as Expressions\n\nValues in `queryParams` are evaluated as expressions, giving you dynamic request parameters built from form values:\n\n```typescript\nhttp: {\n url: '/api/shipping-estimate',\n queryParams: {\n fromZip: 'formValue.originZip',\n toZip: 'formValue.destinationZip',\n weight: 'formValue.packageWeight',\n },\n}\n```\n\n### POST with Dynamic Body\n\nFor `POST` requests, use `evaluateBodyExpressions: true` to build the body from form values:\n\n```typescript\nhttp: {\n url: '/api/calculate-tax',\n method: 'POST',\n body: {\n subtotal: 'formValue.subtotal',\n state: 'formValue.state',\n items: 'formValue.lineItems',\n },\n evaluateBodyExpressions: true,\n},\n```\n\nTop-level string values in `body` are evaluated as expressions. Nested objects are passed through as-is.\n\n### Extracting the Response Value\n\n`responseExpression` is evaluated with `{ response }` in scope and extracts the derived value:\n\n```typescript\nresponseExpression: 'response.rate'; // Simple property\nresponseExpression: 'response.data.price'; // Nested property\nresponseExpression: 'response.items[0].value'; // Array access\n```\n\n### Required Fields\n\n`source: 'http'` enforces two fields at the TypeScript level:\n\n- **`dependsOn: string[]`** \u2014 Explicit field dependencies. The request only re-fires when these fields change.\n- **`responseExpression: string`** \u2014 Expression to extract the derived value from the response body.\n\n### Controlling Request Timing\n\nUse `trigger` and `debounceMs` to control when requests fire:\n\n```typescript\n{\n type: 'derivation',\n source: 'http',\n http: {\n url: '/api/username-suggest',\n queryParams: { q: 'formValue.companyName' },\n },\n responseExpression: 'response.suggestion',\n dependsOn: ['companyName'],\n trigger: 'debounced',\n debounceMs: 400,\n}\n```\n\nThe request waits 400ms after the user stops typing before firing.\n\n### Conditional HTTP Derivation\n\nAdd a `condition` to only send the request when certain criteria are met:\n\n```typescript\n{\n key: 'suggestedPrice',\n type: 'input',\n readonly: true,\n logic: [{\n type: 'derivation',\n source: 'http',\n http: {\n url: '/api/price-suggest',\n queryParams: { productId: 'formValue.productId' },\n },\n responseExpression: 'response.suggestedPrice',\n dependsOn: ['productId'],\n condition: {\n type: 'fieldValue',\n fieldPath: 'productId',\n operator: 'notEquals',\n value: '',\n },\n }],\n}\n```\n\n## Async Function Derivations\n\nUse `source: 'asyncFunction'` when you need custom logic \u2014 Angular service injection, complex transformations, or any async computation not expressible as a plain HTTP config. Functions receive the full evaluation context and can return a `Promise` or `Observable`.\n\n### Basic Example\n\n```typescript\n// 1. Define and register the function in customFnConfig\nconst formConfig = {\n customFnConfig: {\n asyncDerivations: {\n lookupCity: async (context) => {\n const response = await fetch(`/api/geocode?zip=${context.formValue.zipCode}`);\n const data = await response.json();\n return data.city;\n },\n },\n },\n\n // 2. Reference it on the target field\n fields: [\n {\n key: 'city',\n type: 'input',\n label: 'City',\n readonly: true,\n logic: [\n {\n type: 'derivation',\n source: 'asyncFunction',\n asyncFunctionName: 'lookupCity',\n dependsOn: ['zipCode'],\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\n### Using RxJS Observables\n\nFunctions can return an `Observable` instead of a `Promise`, which is useful when using Angular services:\n\n```typescript\ncustomFnConfig: {\n asyncDerivations: {\n fetchAddress: (context) => {\n return inject(AddressService)\n .lookup(context.formValue.zipCode as string)\n .pipe(map(result => result.formattedAddress));\n },\n },\n},\n```\n\n### Available Context\n\nAsync derivation functions receive the full `EvaluationContext`:\n\n| Variable | Description |\n| ----------------------- | ------------------------------------------------ |\n| `context.formValue` | All current form field values |\n| `context.fieldValue` | The current value of the target field |\n| `context.externalData` | External data passed to the form (if configured) |\n| `context.rootFormValue` | Entire form value when inside array fields |\n\n### Conditional Async Derivation\n\nCombine with `condition` to only run the function when needed:\n\n```typescript\n{\n key: 'city',\n type: 'input',\n label: 'City',\n readonly: true,\n logic: [{\n type: 'derivation',\n source: 'asyncFunction',\n asyncFunctionName: 'lookupCity',\n dependsOn: ['zipCode'],\n condition: {\n type: 'fieldValue',\n fieldPath: 'enableLookup',\n operator: 'equals',\n value: true,\n },\n }],\n}\n```\n\nThe async function is only called when `enableLookup === true`.\n\n### Required Fields\n\n`source: 'asyncFunction'` requires:\n\n- **`asyncFunctionName: string`** \u2014 Name of the function registered in `customFnConfig.asyncDerivations`.\n- **`dependsOn: string[]`** \u2014 Explicit field dependencies. Without this, the function would re-run on every form change.\n\n## Stop On User Override\n\n`stopOnUserOverride` turns a derivation into a \"smart default\" \u2014 the field is auto-filled initially, but derivation stops once the user manually edits it.\n\n### Basic Example\n\n```typescript\n{\n key: 'displayName',\n type: 'input',\n label: 'Display Name',\n logic: [{\n type: 'derivation',\n expression: 'formValue.firstName + \" \" + formValue.lastName',\n stopOnUserOverride: true,\n }],\n}\n```\n\nThe display name is auto-filled from first and last name. Once the user changes it directly, auto-fill stops.\n\n### Re-Engaging on Dependency Change\n\nUse `reEngageOnDependencyChange: true` to clear the user override when a dependency changes. The derivation respects user edits, but re-engages if the underlying data changes:\n\n```typescript\n{\n key: 'phonePrefix',\n type: 'input',\n label: 'Phone Prefix',\n logic: [\n {\n type: 'derivation',\n value: '+1',\n condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'US' },\n stopOnUserOverride: true,\n reEngageOnDependencyChange: true,\n dependsOn: ['country'],\n },\n {\n type: 'derivation',\n value: '+44',\n condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'UK' },\n stopOnUserOverride: true,\n reEngageOnDependencyChange: true,\n dependsOn: ['country'],\n },\n ],\n}\n```\n\nWhen the user changes the country, the phone prefix is auto-filled again \u2014 overriding any previous manual edit.\n\n**Without** `reEngageOnDependencyChange`: once the user edits the field, the derivation never runs again for that field instance.\n\n**With** `reEngageOnDependencyChange`: the user override is cleared when a declared dependency changes, and the derivation re-fires.\n\n### Works with All Sources\n\n`stopOnUserOverride` and `reEngageOnDependencyChange` work across all derivation sources:\n\n```typescript\n// HTTP derivation with user override\n{\n type: 'derivation',\n source: 'http',\n http: {\n url: '/api/suggest-price',\n queryParams: { category: 'formValue.category' },\n },\n responseExpression: 'response.suggestedPrice',\n dependsOn: ['category'],\n stopOnUserOverride: true,\n reEngageOnDependencyChange: true,\n}\n\n// Async function derivation with user override\n{\n type: 'derivation',\n source: 'asyncFunction',\n asyncFunctionName: 'fetchDefaultTitle',\n dependsOn: ['template'],\n stopOnUserOverride: true,\n}\n```\n\n## DerivationLogicConfig Reference (Async)\n\n### HTTP Derivation Fields\n\n```typescript\n{\n type: 'derivation';\n source: 'http'; // Required \u2014 identifies HTTP mode\n\n http: HttpRequestConfig; // Required \u2014 request configuration\n dependsOn: string[]; // Required \u2014 explicit field dependencies\n responseExpression: string; // Required \u2014 expression to extract value from response\n\n // Shared optional fields\n trigger?: 'onChange' | 'debounced'; // Default: 'onChange'\n debounceMs?: number; // Default: 500 (when trigger: 'debounced')\n condition?: ConditionalExpression | boolean;\n stopOnUserOverride?: boolean;\n reEngageOnDependencyChange?: boolean;\n debugName?: string;\n}\n```\n\n### Async Function Derivation Fields\n\n```typescript\n{\n type: 'derivation';\n source: 'asyncFunction'; // Required \u2014 identifies async function mode\n\n asyncFunctionName: string; // Required \u2014 name in customFnConfig.asyncDerivations\n dependsOn: string[]; // Required \u2014 explicit field dependencies\n\n // Shared optional fields\n trigger?: 'onChange' | 'debounced';\n debounceMs?: number;\n condition?: ConditionalExpression | boolean;\n stopOnUserOverride?: boolean;\n reEngageOnDependencyChange?: boolean;\n debugName?: string;\n}\n```\n\n## Related\n\n- **[Values](./)** \u2014 Expression, static value, and function-based derivations\n- **[Properties](./property-derivation)** \u2014 Derive component properties from form values\n- **[HTTP Conditions](../../conditional-logic/overview/)** \u2014 HTTP-driven field visibility and state\n- **[Custom Validators](../../../validation/custom-validators/)** \u2014 Async and HTTP validation"
57
69
  },
58
70
  {
59
71
  id: "dynamic-behavior-value-derivation-basics",
60
72
  title: "Dynamic Behavior Value Derivation Basics",
61
73
  category: "dynamic-behavior",
62
- content: "Automatically compute and set field values based on other form values. Derivations enable calculated fields, auto-fill patterns, and value transformations.\n\n## Quick Start\n\nDerivations are defined ON the field that receives the computed value (self-targeting).\n\n### Shorthand Syntax (Preferred)\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n}\n```\n\n### Logic Block Syntax\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n logic: [{\n type: 'derivation',\n expression: 'formValue.quantity * formValue.unitPrice',\n }],\n}\n```\n\nWhen `quantity` or `unitPrice` changes, `total` is automatically recalculated.\n\n## Derivation Types\n\n### Expression-Based\n\nUse JavaScript expressions with access to `formValue`:\n\n```typescript\n{\n key: 'fullName',\n type: 'input',\n label: 'Full Name',\n readonly: true,\n derivation: '(formValue.firstName || \"\") + \" \" + (formValue.lastName || \"\")',\n}\n```\n\n**Available variables:**\n\n- `formValue` - Object containing all form field values\n- `externalData` - External application state (when configured in FormConfig)\n\n### Static Value\n\nSet a constant value when a condition is met:\n\n```typescript\n{\n key: 'phonePrefix',\n type: 'input',\n label: 'Phone Prefix',\n readonly: true,\n logic: [{\n type: 'derivation',\n value: '+1',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'USA',\n },\n }],\n}\n```\n\n### Custom Function\n\nUse a registered function for complex logic:\n\n```typescript\n// In form config\ncustomFnConfig: {\n derivations: {\n calculateTax: (ctx) => ctx.formValue.subtotal * getTaxRate(ctx.formValue.state),\n },\n},\nfields: [\n {\n key: 'tax',\n type: 'input',\n readonly: true,\n logic: [{\n type: 'derivation',\n functionName: 'calculateTax',\n dependsOn: ['subtotal', 'state'],\n }],\n },\n],\n```\n\n## Trigger Timing\n\nControl when derivations evaluate:\n\n| Trigger | Description | Use Case |\n| ----------- | ------------------------------------- | ------------------------------------- |\n| `onChange` | Immediately on value change (default) | Computed totals, conditional prefixes |\n| `debounced` | After value stabilizes | Self-transforms, format masking |\n\n### Debounced Derivations\n\nUse `trigger: 'debounced'` for self-transforming fields to avoid interrupting the user while typing:\n\n```typescript\n{\n key: 'email',\n type: 'input',\n label: 'Email',\n logic: [{\n type: 'derivation',\n expression: 'formValue.email.toLowerCase()',\n trigger: 'debounced',\n debounceMs: 500, // optional, defaults to 500\n }],\n}\n```\n\nThe transformation applies after the user stops typing for 500ms.\n\n## Conditional Derivations\n\nOnly apply derivations when conditions are met:\n\n```typescript\n{\n key: 'currency',\n type: 'input',\n label: 'Currency',\n readonly: true,\n logic: [\n {\n type: 'derivation',\n value: 'USD',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'USA',\n },\n },\n {\n type: 'derivation',\n value: 'EUR',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'Germany',\n },\n },\n ],\n}\n```\n\nMultiple derivations on the same field are evaluated in order.\n\n## Dependencies\n\n### Automatic Detection\n\nFor expressions, dependencies are automatically extracted:\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n // Automatically depends on: quantity, unitPrice\n}\n```\n\n### Explicit Dependencies\n\nFor custom functions, specify dependencies explicitly:\n\n```typescript\n{\n key: 'discount',\n type: 'input',\n label: 'Discount',\n readonly: true,\n logic: [{\n type: 'derivation',\n functionName: 'calculateDiscount',\n dependsOn: ['total', 'memberLevel'],\n }],\n}\n```\n\nWithout `dependsOn`, custom functions re-evaluate on any form change.\n\n## Complete Example\n\n```typescript\nconst orderForm = {\n fields: [\n {\n key: 'quantity',\n type: 'input',\n value: 1,\n label: 'Quantity',\n props: { type: 'number' },\n },\n {\n key: 'unitPrice',\n type: 'input',\n value: 10,\n label: 'Unit Price',\n props: { type: 'number' },\n },\n {\n key: 'subtotal',\n type: 'input',\n value: 0,\n label: 'Subtotal',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n },\n {\n key: 'tax',\n type: 'input',\n value: 0,\n label: 'Tax (10%)',\n readonly: true,\n derivation: 'formValue.subtotal * 0.1',\n },\n {\n key: 'total',\n type: 'input',\n value: 0,\n label: 'Total',\n readonly: true,\n derivation: 'formValue.subtotal + formValue.tax',\n },\n ],\n} as const satisfies FormConfig;\n```\n\n## Array Field Derivations\n\nInside arrays, `formValue` is scoped to the current array item:\n\n```typescript\n{\n key: 'lineItems',\n type: 'array',\n fields: [\n {\n key: 'itemRow',\n type: 'row',\n fields: [\n { key: 'quantity', type: 'input', label: 'Qty', value: 1 },\n { key: 'unitPrice', type: 'input', label: 'Price', value: 0 },\n {\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n value: 0,\n readonly: true,\n // formValue is scoped to the current array item\n derivation: 'formValue.quantity * formValue.unitPrice',\n },\n ],\n },\n ],\n}\n```\n\n### Accessing Root Form Value\n\nInside array items, `formValue` refers to the current array item. Use `rootFormValue` to access the entire form:\n\n```typescript\n{\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n readonly: true,\n // formValue = current array item { quantity, unitPrice }\n // rootFormValue = entire form { lineItems, discount, ... }\n derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.discount / 100)',\n}\n```\n\n## Debugging Derivations\n\nEnable derivation logging to troubleshoot issues:\n\n### Configuration\n\nConfigure derivation logging via `withLoggerConfig`:\n\n```typescript\n// In your providers\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'verbose' }));\n\n// Or just summary level\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'summary' }));\n```\n\n### Log Levels\n\n| Level | Output |\n| --------- | --------------------------------- |\n| `none` | No logging (default) |\n| `summary` | Cycle completion with counts |\n| `verbose` | Individual derivation evaluations |\n\n### Using debugName\n\nAdd names to derivations for easier identification in logs:\n\n```typescript\n{\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n readonly: true,\n logic: [{\n type: 'derivation',\n debugName: 'Calculate line total',\n expression: 'formValue.quantity * formValue.unitPrice',\n }],\n}\n```\n\n**Console output (verbose mode):**\n\n```\nDerivation - Starting cycle (onChange) with 5 derivation(s)\nDerivation - Iteration 1\nDerivation - Applied \"Calculate line total\" { field: 'lineTotal', newValue: 150 }\nDerivation - Skipped: phonePrefix (condition not met)\nDerivation - Cycle complete (onChange) { applied: 1, skipped: 4, errors: 0, iterations: 1 }\n```\n\n## Bidirectional Derivations\n\nCreate two-way bindings between fields:\n\n```typescript\n// Celsius to Fahrenheit\n{\n key: 'fahrenheit',\n type: 'input',\n value: 32,\n derivation: 'formValue.celsius * 9 / 5 + 32',\n}\n\n// Fahrenheit to Celsius\n{\n key: 'celsius',\n type: 'input',\n value: 0,\n derivation: '(formValue.fahrenheit - 32) * 5 / 9',\n}\n```\n\n### Cycle Detection\n\nThe system automatically detects derivation cycles and warns during development:\n\n```\nBidirectional derivation detected: celsius <-> fahrenheit\nBidirectional derivations stabilize via equality check.\n```\n\n### Floating-Point Precision\n\nBidirectional derivations stabilize when the computed value equals the current value. For floating-point operations, consider:\n\n1. **Rounding in expressions:**\n\n ```typescript\n derivation: 'Math.round(formValue.usd * exchangeRate * 100) / 100';\n ```\n\n2. **Using integers:** Store cents instead of dollars\n3. **One-way derivation:** If bidirectional isn't required\n\n## Derivation Processing\n\n### Evaluation Order\n\nDerivations are topologically sorted based on dependencies:\n\n```\nquantity \u2500\u2510\n \u251C\u2500\u2500 subtotal \u2500\u2510\nunitPrice \u2500\u2518 \u251C\u2500\u2500 total\n \u2502\n tax \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nThis ensures `subtotal` is computed before `total`.\n\n### Iteration Limits\n\nTo prevent infinite loops, derivations are limited to 10 iterations per cycle. If exceeded:\n\n```\nDerivation - Max iterations reached (onChange).\nThis may indicate a loop in derivation logic.\n```\n\n## DerivationLogicConfig Interface\n\n```typescript\ninterface DerivationLogicConfig {\n /** Logic type identifier */\n type: 'derivation';\n\n /** Optional name for debugging */\n debugName?: string;\n\n /** When to evaluate: 'onChange' (default) or 'debounced' */\n trigger?: 'onChange' | 'debounced';\n\n /** Debounce duration in ms (default: 500) */\n debounceMs?: number;\n\n /** Static value to set */\n value?: unknown;\n\n /** JavaScript expression (has access to formValue) */\n expression?: string;\n\n /** Name of registered custom function */\n functionName?: string;\n\n /** Explicit field dependencies */\n dependsOn?: string[];\n\n /** Condition for when derivation applies */\n condition?: ConditionalExpression | boolean;\n}\n```\n\n## External Data in Derivations\n\nUse external application state in derivation expressions:\n\n```typescript\nconst config = {\n externalData: {\n discountRate: computed(() => pricingService.currentDiscount()),\n },\n fields: [\n {\n key: 'discountedPrice',\n type: 'input',\n label: 'Discounted Price',\n readonly: true,\n derivation: 'formValue.price * (1 - externalData.discountRate)',\n },\n ],\n} as const satisfies FormConfig;\n```\n\nExternal data values are reactively tracked - when signals change, derivations are re-evaluated.\n\n## Related\n\n- **[Conditional Logic](../conditional-logic/overview/)** - Control field visibility and state\n- **[Array Fields](../../prebuilt/form-arrays/)** - Working with array fields\n- **[Examples](/docs/examples)** - Real-world form patterns"
74
+ content: "Automatically compute and set field values based on other form values. Derivations enable calculated fields, auto-fill patterns, and value transformations.\n\n## Quick Start\n\nDerivations are defined ON the field that receives the computed value (self-targeting).\n\n### Shorthand Syntax (Preferred)\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n}\n```\n\n### Logic Block Syntax\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n logic: [{\n type: 'derivation',\n expression: 'formValue.quantity * formValue.unitPrice',\n }],\n}\n```\n\nWhen `quantity` or `unitPrice` changes, `total` is automatically recalculated.\n\n## Derivation Types\n\n### Expression-Based\n\nUse JavaScript expressions with access to `formValue`:\n\n```typescript\n{\n key: 'fullName',\n type: 'input',\n label: 'Full Name',\n readonly: true,\n derivation: '(formValue.firstName || \"\") + \" \" + (formValue.lastName || \"\")',\n}\n```\n\n**Available variables:**\n\n- `formValue` - Object containing all form field values\n- `externalData` - External application state (when configured in FormConfig)\n\n### Static Value\n\nSet a constant value when a condition is met:\n\n```typescript\n{\n key: 'phonePrefix',\n type: 'input',\n label: 'Phone Prefix',\n readonly: true,\n logic: [{\n type: 'derivation',\n value: '+1',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'USA',\n },\n }],\n}\n```\n\n### Custom Function\n\nUse a registered function for complex logic:\n\n```typescript\n// In form config\ncustomFnConfig: {\n derivations: {\n calculateTax: (ctx) => ctx.formValue.subtotal * getTaxRate(ctx.formValue.state),\n },\n},\nfields: [\n {\n key: 'tax',\n type: 'input',\n readonly: true,\n logic: [{\n type: 'derivation',\n functionName: 'calculateTax',\n dependsOn: ['subtotal', 'state'],\n }],\n },\n],\n```\n\n## Trigger Timing\n\nControl when derivations evaluate:\n\n| Trigger | Description | Use Case |\n| ----------- | ------------------------------------- | ------------------------------------- |\n| `onChange` | Immediately on value change (default) | Computed totals, conditional prefixes |\n| `debounced` | After value stabilizes | Self-transforms, format masking |\n\n### Debounced Derivations\n\nUse `trigger: 'debounced'` for self-transforming fields to avoid interrupting the user while typing:\n\n```typescript\n{\n key: 'email',\n type: 'input',\n label: 'Email',\n logic: [{\n type: 'derivation',\n expression: 'formValue.email.toLowerCase()',\n trigger: 'debounced',\n debounceMs: 500, // optional, defaults to 500\n }],\n}\n```\n\nThe transformation applies after the user stops typing for 500ms.\n\n## Conditional Derivations\n\nOnly apply derivations when conditions are met:\n\n```typescript\n{\n key: 'currency',\n type: 'input',\n label: 'Currency',\n readonly: true,\n logic: [\n {\n type: 'derivation',\n value: 'USD',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'USA',\n },\n },\n {\n type: 'derivation',\n value: 'EUR',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'Germany',\n },\n },\n ],\n}\n```\n\nMultiple derivations on the same field are evaluated in order.\n\n## Dependencies\n\n### Automatic Detection\n\nFor expressions, dependencies are automatically extracted:\n\n```typescript\n{\n key: 'total',\n type: 'input',\n label: 'Total',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n // Automatically depends on: quantity, unitPrice\n}\n```\n\n### Explicit Dependencies\n\nFor custom functions, specify dependencies explicitly:\n\n```typescript\n{\n key: 'discount',\n type: 'input',\n label: 'Discount',\n readonly: true,\n logic: [{\n type: 'derivation',\n functionName: 'calculateDiscount',\n dependsOn: ['total', 'memberLevel'],\n }],\n}\n```\n\nWithout `dependsOn`, custom functions re-evaluate on any form change.\n\n## Complete Example\n\n```typescript\nconst orderForm = {\n fields: [\n {\n key: 'quantity',\n type: 'input',\n value: 1,\n label: 'Quantity',\n props: { type: 'number' },\n },\n {\n key: 'unitPrice',\n type: 'input',\n value: 10,\n label: 'Unit Price',\n props: { type: 'number' },\n },\n {\n key: 'subtotal',\n type: 'input',\n value: 0,\n label: 'Subtotal',\n readonly: true,\n derivation: 'formValue.quantity * formValue.unitPrice',\n },\n {\n key: 'tax',\n type: 'input',\n value: 0,\n label: 'Tax (10%)',\n readonly: true,\n derivation: 'formValue.subtotal * 0.1',\n },\n {\n key: 'total',\n type: 'input',\n value: 0,\n label: 'Total',\n readonly: true,\n derivation: 'formValue.subtotal + formValue.tax',\n },\n ],\n} as const satisfies FormConfig;\n```\n\n## Array Field Derivations\n\nInside arrays, `formValue` is scoped to the current array item:\n\n```typescript\n{\n key: 'lineItems',\n type: 'array',\n fields: [\n {\n key: 'itemRow',\n type: 'row',\n fields: [\n { key: 'quantity', type: 'input', label: 'Qty', value: 1 },\n { key: 'unitPrice', type: 'input', label: 'Price', value: 0 },\n {\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n value: 0,\n readonly: true,\n // formValue is scoped to the current array item\n derivation: 'formValue.quantity * formValue.unitPrice',\n },\n ],\n },\n ],\n}\n```\n\n### Accessing Root Form Value\n\nInside array items, `formValue` refers to the current array item. Use `rootFormValue` to access the entire form:\n\n```typescript\n{\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n readonly: true,\n // formValue = current array item { quantity, unitPrice }\n // rootFormValue = entire form { lineItems, discount, ... }\n derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.discount / 100)',\n}\n```\n\n## Debugging Derivations\n\nEnable derivation logging to troubleshoot issues:\n\n### Configuration\n\nConfigure derivation logging via `withLoggerConfig`:\n\n```typescript\n// In your providers\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'verbose' }));\n\n// Or just summary level\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'summary' }));\n```\n\n### Log Levels\n\n| Level | Output |\n| --------- | --------------------------------- |\n| `none` | No logging (default) |\n| `summary` | Cycle completion with counts |\n| `verbose` | Individual derivation evaluations |\n\n### Using debugName\n\nAdd names to derivations for easier identification in logs:\n\n```typescript\n{\n key: 'lineTotal',\n type: 'input',\n label: 'Total',\n readonly: true,\n logic: [{\n type: 'derivation',\n debugName: 'Calculate line total',\n expression: 'formValue.quantity * formValue.unitPrice',\n }],\n}\n```\n\n**Console output (verbose mode):**\n\n```\nDerivation - Starting cycle (onChange) with 5 derivation(s)\nDerivation - Iteration 1\nDerivation - Applied \"Calculate line total\" { field: 'lineTotal', newValue: 150 }\nDerivation - Skipped: phonePrefix (condition not met)\nDerivation - Cycle complete (onChange) { applied: 1, skipped: 4, errors: 0, iterations: 1 }\n```\n\n## Bidirectional Derivations\n\nCreate two-way bindings between fields:\n\n```typescript\n// Celsius to Fahrenheit\n{\n key: 'fahrenheit',\n type: 'input',\n value: 32,\n derivation: 'formValue.celsius * 9 / 5 + 32',\n}\n\n// Fahrenheit to Celsius\n{\n key: 'celsius',\n type: 'input',\n value: 0,\n derivation: '(formValue.fahrenheit - 32) * 5 / 9',\n}\n```\n\n### Cycle Detection\n\nThe system automatically detects derivation cycles and warns during development:\n\n```\nBidirectional derivation detected: celsius <-> fahrenheit\nBidirectional derivations stabilize via equality check.\n```\n\n### Floating-Point Precision\n\nBidirectional derivations stabilize when the computed value equals the current value. For floating-point operations, consider:\n\n1. **Rounding in expressions:**\n\n ```typescript\n derivation: 'Math.round(formValue.usd * exchangeRate * 100) / 100';\n ```\n\n2. **Using integers:** Store cents instead of dollars\n3. **One-way derivation:** If bidirectional isn't required\n\n## Derivation Processing\n\n### Evaluation Order\n\nDerivations are topologically sorted based on dependencies:\n\n```\nquantity \u2500\u2510\n \u251C\u2500\u2500 subtotal \u2500\u2510\nunitPrice \u2500\u2518 \u251C\u2500\u2500 total\n \u2502\n tax \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nThis ensures `subtotal` is computed before `total`.\n\n### Iteration Limits\n\nTo prevent infinite loops, derivations are limited to 10 iterations per cycle. If exceeded:\n\n```\nDerivation - Max iterations reached (onChange).\nThis may indicate a loop in derivation logic.\n```\n\n## DerivationLogicConfig Interface\n\n```typescript\ninterface DerivationLogicConfig {\n /** Logic type identifier */\n type: 'derivation';\n\n /** Optional name for debugging */\n debugName?: string;\n\n /** When to evaluate: 'onChange' (default) or 'debounced' */\n trigger?: 'onChange' | 'debounced';\n\n /** Debounce duration in ms (default: 500) */\n debounceMs?: number;\n\n /** Static value to set */\n value?: unknown;\n\n /** JavaScript expression (has access to formValue) */\n expression?: string;\n\n /** Name of registered custom function */\n functionName?: string;\n\n /** Explicit field dependencies */\n dependsOn?: string[];\n\n /** Condition for when derivation applies */\n condition?: ConditionalExpression | boolean;\n}\n```\n\n## External Data in Derivations\n\nUse external application state in derivation expressions:\n\n```typescript\nconst config = {\n externalData: {\n discountRate: computed(() => pricingService.currentDiscount()),\n },\n fields: [\n {\n key: 'discountedPrice',\n type: 'input',\n label: 'Discounted Price',\n readonly: true,\n derivation: 'formValue.price * (1 - externalData.discountRate)',\n },\n ],\n} as const satisfies FormConfig;\n```\n\nExternal data values are reactively tracked - when signals change, derivations are re-evaluated.\n\n## Related\n\n- **Property Derivation** (see tab above) \u2014 Derive component properties (minDate, options, label) from form values\n- **Async Derivation** (see tab above) \u2014 HTTP and async function derivations, stopOnUserOverride\n- **[Conditional Logic](../conditional-logic/overview/)** \u2014 Control field visibility and state\n- **[Array Fields](../../prebuilt/form-arrays/simplified/)** \u2014 Working with array fields\n- **[Examples](/examples)** \u2014 Real-world form patterns"
75
+ },
76
+ {
77
+ id: "dynamic-behavior-value-derivation-basics-property-derivation",
78
+ title: "Dynamic Behavior Value Derivation Basics Property Derivation",
79
+ category: "dynamic-behavior",
80
+ content: "Reactively derive field component properties (like `minDate`, `options`, `label`, `placeholder`) based on form values. While value derivations set a field's form value, property derivations set **component input properties**.\n\n## Quick Start\n\nProperty derivations use `type: 'derivation'` with `targetProperty` in the `logic` array and are self-targeting: the logic is placed on the field whose property should be derived.\n\n```typescript\n{\n key: 'endDate',\n type: 'datepicker',\n label: 'End Date',\n logic: [{\n type: 'derivation',\n targetProperty: 'minDate',\n expression: 'formValue.startDate',\n }]\n}\n```\n\nWhen `startDate` changes, the `minDate` property on `endDate`'s datepicker component is automatically updated.\n\n> **Migration note:** The previous `type: 'propertyDerivation'` syntax is deprecated but still works.\n> Use `type: 'derivation'` with `targetProperty` instead. Similarly, register functions via\n> `customFnConfig.derivations` instead of `customFnConfig.propertyDerivations`.\n\n## Derivation Sources\n\nProperty derivations support three mutually exclusive ways to compute a value.\n\n### Expression-Based\n\nUse JavaScript expressions with access to `formValue`:\n\n```typescript\n{\n key: 'endDate',\n type: 'datepicker',\n label: 'End Date',\n logic: [{\n type: 'derivation',\n targetProperty: 'minDate',\n expression: 'formValue.startDate',\n }]\n}\n```\n\n**Available variables:**\n\n- `formValue` - Object containing all form field values\n- `externalData` - External application state (when configured in FormConfig)\n\n### Static Value\n\nSet a constant property value when a condition is met:\n\n```typescript\n{\n key: 'phone',\n type: 'input',\n label: 'Phone',\n logic: [{\n type: 'derivation',\n targetProperty: 'label',\n value: 'Mobile Phone',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactType',\n operator: 'equals',\n value: 'mobile',\n },\n }]\n}\n```\n\n### Custom Function\n\nUse a registered function for complex logic:\n\n```typescript\n// In form config\ncustomFnConfig: {\n derivations: {\n getCitiesForCountry: (ctx) => {\n const cities: Record<string, { label: string; value: string }[]> = {\n 'US': [{ label: 'New York', value: 'nyc' }, { label: 'LA', value: 'la' }],\n 'DE': [{ label: 'Berlin', value: 'berlin' }],\n };\n return cities[ctx.formValue.country as string] ?? [];\n },\n },\n},\nfields: [\n {\n key: 'city',\n type: 'select',\n label: 'City',\n options: [],\n logic: [{\n type: 'derivation',\n targetProperty: 'options',\n functionName: 'getCitiesForCountry',\n dependsOn: ['country'],\n }],\n },\n],\n```\n\n## Target Properties\n\n### Simple Properties\n\nSet any direct component input property:\n\n```typescript\ntargetProperty: 'minDate'; // Date constraint\ntargetProperty: 'maxDate'; // Date constraint\ntargetProperty: 'options'; // Select/radio options\ntargetProperty: 'label'; // Field label\ntargetProperty: 'placeholder'; // Input placeholder\ntargetProperty: 'hint'; // Hint text\ntargetProperty: 'rows'; // Textarea rows\n```\n\n### Nested Properties (Dot Notation)\n\nSet properties nested one level deep using dot notation:\n\n```typescript\ntargetProperty: 'props.appearance'; // Material appearance\ntargetProperty: 'props.color'; // Material color\ntargetProperty: 'meta.autocomplete'; // Custom metadata\n```\n\n> **Note:** Maximum nesting depth is 2 levels (one dot). Deeper paths like `props.nested.deep` are not supported.\n\n## Trigger Timing\n\nControl when property derivations evaluate:\n\n| Trigger | Description | Use Case |\n| ----------- | ------------------------------------- | --------------------------------- |\n| `onChange` | Immediately on value change (default) | Date constraints, dynamic options |\n| `debounced` | After value stabilizes | Expensive lookups, search queries |\n\n### Debounced Property Derivations\n\nUse `trigger: 'debounced'` for expensive operations:\n\n```typescript\n{\n key: 'productSearch',\n type: 'select',\n label: 'Product',\n options: [],\n logic: [{\n type: 'derivation',\n targetProperty: 'options',\n functionName: 'searchProducts',\n trigger: 'debounced',\n debounceMs: 300,\n dependsOn: ['searchQuery'],\n }]\n}\n```\n\n## Conditional Property Derivations\n\nOnly apply property derivations when conditions are met:\n\n```typescript\n{\n key: 'email',\n type: 'input',\n label: 'Email',\n logic: [\n {\n type: 'derivation',\n targetProperty: 'label',\n value: 'Work Email',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n },\n {\n type: 'derivation',\n targetProperty: 'label',\n value: 'Personal Email',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'personal',\n },\n },\n ],\n}\n```\n\n## Dependencies\n\n### Automatic Detection\n\nFor expressions, dependencies are automatically extracted:\n\n```typescript\n{\n key: 'endDate',\n type: 'datepicker',\n label: 'End Date',\n logic: [{\n type: 'derivation',\n targetProperty: 'minDate',\n expression: 'formValue.startDate',\n // Automatically depends on: startDate\n }]\n}\n```\n\n### Explicit Dependencies\n\nFor custom functions, specify dependencies explicitly:\n\n```typescript\n{\n key: 'city',\n type: 'select',\n label: 'City',\n options: [],\n logic: [{\n type: 'derivation',\n targetProperty: 'options',\n functionName: 'getCitiesForCountry',\n dependsOn: ['country'],\n }]\n}\n```\n\nWithout `dependsOn`, custom functions re-evaluate on **any** form value change.\n\n## Array Field Property Derivations\n\nInside arrays, `formValue` is scoped to the current array item:\n\n```typescript\n{\n key: 'lineItems',\n type: 'array',\n fields: [\n {\n key: 'item',\n type: 'group',\n fields: [\n { key: 'startDate', type: 'datepicker', label: 'Start' },\n {\n key: 'endDate',\n type: 'datepicker',\n label: 'End',\n logic: [{\n type: 'derivation',\n targetProperty: 'minDate',\n // formValue is scoped to the current array item\n expression: 'formValue.startDate',\n }]\n },\n ],\n },\n ],\n}\n```\n\nEach array item independently derives its own `endDate.minDate` from its own `startDate`.\n\n## Complete Example\n\n```typescript\nconst travelForm = {\n customFnConfig: {\n derivations: {\n getCitiesForCountry: (ctx) => {\n const cities: Record<string, { label: string; value: string }[]> = {\n US: [\n { label: 'New York', value: 'nyc' },\n { label: 'Los Angeles', value: 'la' },\n { label: 'Chicago', value: 'chi' },\n ],\n DE: [\n { label: 'Berlin', value: 'berlin' },\n { label: 'Munich', value: 'munich' },\n ],\n };\n return cities[ctx.formValue.country as string] ?? [];\n },\n },\n },\n fields: [\n {\n key: 'country',\n type: 'select',\n label: 'Country',\n required: true,\n options: [\n { label: 'USA', value: 'US' },\n { label: 'Germany', value: 'DE' },\n ],\n },\n {\n key: 'city',\n type: 'select',\n label: 'City',\n required: true,\n options: [],\n logic: [\n {\n type: 'derivation',\n targetProperty: 'options',\n functionName: 'getCitiesForCountry',\n dependsOn: ['country'],\n },\n ],\n },\n { key: 'startDate', type: 'datepicker', label: 'Travel Start', required: true },\n {\n key: 'endDate',\n type: 'datepicker',\n label: 'Travel End',\n required: true,\n logic: [\n {\n type: 'derivation',\n targetProperty: 'minDate',\n expression: 'formValue.startDate',\n },\n ],\n },\n {\n key: 'notes',\n type: 'textarea',\n label: 'Notes',\n logic: [\n {\n type: 'derivation',\n targetProperty: 'props.appearance',\n value: 'fill',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'equals',\n value: 'DE',\n },\n },\n {\n type: 'derivation',\n targetProperty: 'props.appearance',\n value: 'outline',\n condition: {\n type: 'fieldValue',\n fieldPath: 'country',\n operator: 'notEquals',\n value: 'DE',\n },\n },\n ],\n },\n { key: 'submit', type: 'submit', label: 'Book Trip' },\n ],\n} as const satisfies FormConfig;\n```\n\n## Comparison with Value Derivation\n\n| Aspect | Value Derivation | Property Derivation |\n| ---------------- | ---------------------------- | --------------------------------------- |\n| Logic type | `type: 'derivation'` | `type: 'derivation'` + `targetProperty` |\n| Sets | Field's form value | Component input property |\n| Target | Implicit (self) | `targetProperty: 'minDate'` |\n| Shorthand | `derivation: 'expr'` | None (must use logic block) |\n| Chaining | Topologically sorted | No chaining (single pass) |\n| Custom functions | `customFnConfig.derivations` | `customFnConfig.derivations` |\n| Max iterations | Configurable (default 10) | Single pass |\n\n## Debugging\n\nAdd `debugName` to property derivations for easier identification in logs:\n\n```typescript\nlogic: [\n {\n type: 'derivation',\n debugName: 'endDate minDate constraint',\n targetProperty: 'minDate',\n expression: 'formValue.startDate',\n },\n];\n```\n\n## DerivationLogicConfig Interface\n\nBoth value derivations and property derivations use the unified `DerivationLogicConfig`. The presence of `targetProperty` is what distinguishes a property derivation from a value derivation.\n\n```typescript\ninterface DerivationLogicConfig {\n /** Logic type identifier (unified for both value and property derivations) */\n type: 'derivation';\n\n /** Property to set on the field component. When present, this is a property derivation. When absent, this is a value derivation. */\n targetProperty?: string;\n\n /** Optional name for debugging */\n debugName?: string;\n\n /** When to evaluate: 'onChange' (default) or 'debounced' */\n trigger?: 'onChange' | 'debounced';\n\n /** Debounce duration in ms (default: 500) */\n debounceMs?: number;\n\n /** Static value to set (mutually exclusive) */\n value?: unknown;\n\n /** JavaScript expression (mutually exclusive) */\n expression?: string;\n\n /** Name of registered custom function (mutually exclusive) */\n functionName?: string;\n\n /** Explicit field dependencies */\n dependsOn?: string[];\n\n /** Condition for when derivation applies (default: true) */\n condition?: ConditionalExpression | boolean;\n}\n```\n\n## External Data in Property Derivations\n\nUse external application state in property derivation custom functions:\n\n```typescript\nconst config = {\n externalData: {\n userRegion: computed(() => this.regionService.current()),\n },\n customFnConfig: {\n derivations: {\n getCurrencyOptions: (ctx) => {\n const optionsByRegion: Record<string, { label: string; value: string }[]> = {\n EU: [\n { label: 'EUR', value: 'eur' },\n { label: 'GBP', value: 'gbp' },\n ],\n US: [\n { label: 'USD', value: 'usd' },\n { label: 'CAD', value: 'cad' },\n ],\n };\n return optionsByRegion[ctx.externalData.userRegion as string] ?? [];\n },\n },\n },\n fields: [\n {\n key: 'currency',\n type: 'select',\n label: 'Currency',\n options: [],\n logic: [\n {\n type: 'derivation',\n targetProperty: 'options',\n functionName: 'getCurrencyOptions',\n },\n ],\n },\n ],\n} as const satisfies FormConfig;\n```\n\nExternal data values are reactively tracked - when signals change, property derivations are re-evaluated.\n\n## Related\n\n- **Value Derivation** (see tab above) - Compute field form values\n- **[Conditional Logic](../conditional-logic/overview/)** - Control field visibility and state\n- **[Array Fields](../../prebuilt/form-arrays/simplified/)** - Working with array fields"
63
81
  },
64
82
  {
65
83
  id: "age-conditional-form",
@@ -67,6 +85,12 @@ var require_docs = __commonJS({
67
85
  category: "examples",
68
86
  content: "[\u2190 Back to Quick Start](/examples)\n\nRegistration form demonstrating numeric comparison operators for age-based conditional logic.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/age-conditional-form\" class=\"example-frame\" title=\"Age Conditional Form Demo\"></iframe>\n\n## Overview\n\nThis example shows how to use numeric comparison operators to display different fields based on age ranges. Minors see parental consent fields, while seniors see discount options.\n\n**Key patterns demonstrated:**\n\n- Age-appropriate field display\n- Numeric comparisons (greater than, less than)\n- Multiple conditional sections based on same field\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, type FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-age-conditional-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class AgeConditionalFormComponent {\n formValue = signal({});\n\n config = {\n fields: [\n {\n key: 'name',\n type: 'input',\n value: '',\n label: 'Full Name',\n required: true,\n },\n {\n key: 'email',\n type: 'input',\n value: '',\n label: 'Email Address',\n required: true,\n email: true,\n },\n {\n key: 'age',\n type: 'input',\n value: null,\n label: 'Age',\n required: true,\n min: 0,\n max: 120,\n props: {\n type: 'number',\n hint: 'Enter your age to see relevant options',\n },\n },\n {\n key: 'parentalConsent',\n type: 'checkbox',\n value: false,\n label: 'I have parental/guardian consent to register',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 18,\n },\n },\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 18,\n },\n },\n ],\n },\n {\n key: 'parentEmail',\n type: 'input',\n value: '',\n label: 'Parent/Guardian Email',\n email: true,\n props: {\n hint: 'We will send a verification email to your parent/guardian',\n },\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 18,\n },\n },\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 18,\n },\n },\n ],\n },\n {\n key: 'seniorDiscount',\n type: 'checkbox',\n value: false,\n label: 'Apply senior discount (65+)',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 65,\n },\n },\n ],\n },\n {\n key: 'aarpMember',\n type: 'checkbox',\n value: false,\n label: 'I am an AARP member (additional 5% discount)',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 65,\n },\n },\n ],\n },\n {\n type: 'submit',\n key: 'submit',\n label: 'Register',\n },\n ],\n } as const satisfies FormConfig;\n}\n```\n\n## How It Works\n\n### Age-Based Visibility\n\nFields for minors are hidden when age >= 18:\n\n```typescript\n{\n key: 'parentalConsent',\n type: 'checkbox',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 18,\n },\n }],\n}\n```\n\nFields for seniors are hidden when age < 65:\n\n```typescript\n{\n key: 'seniorDiscount',\n type: 'checkbox',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 65,\n },\n }],\n}\n```\n\n### Conditional Required for Minors\n\nParent email is required only for minors:\n\n```typescript\n{\n key: 'parentEmail',\n type: 'input',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'greaterOrEqual',\n value: 18,\n },\n },\n {\n type: 'required',\n condition: {\n type: 'fieldValue',\n fieldPath: 'age',\n operator: 'less',\n value: 18,\n },\n },\n ],\n}\n```\n\n## Comparison Operators\n\nThis example uses numeric comparison operators:\n\n| Operator | Description |\n| ---------------- | -------------------------- |\n| `greater` | Greater than (>) |\n| `less` | Less than (<) |\n| `greaterOrEqual` | Greater than or equal (>=) |\n| `lessOrEqual` | Less than or equal (<=) |\n\n## Use Cases\n\n- Age-gated registration\n- Tiered pricing forms\n- Compliance forms with age requirements\n- Membership applications\n\n## Related Documentation\n\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Full conditional logic guide\n- **[Validation](../../validation/basics/)** - Min/max validation\n- **[User Registration](../user-registration/)** - Basic registration example"
69
87
  },
88
+ {
89
+ id: "array-form",
90
+ title: "Array Form",
91
+ category: "examples",
92
+ content: "[\u2190 Back to Quick Start](/examples)\n\nDynamic form arrays using the complete API with declarative add/remove buttons, custom button placement, and full control over item structure.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Overview\n\nThis example demonstrates the complete array API with:\n\n- **Flat arrays** with row-based items (input + remove button)\n- **Object arrays** with multiple fields per item\n- **Declarative buttons** for add, prepend, and remove operations\n- **Custom button placement** outside the array container\n- **Template-based item creation**\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new tags \u2014 a row with an input and remove button\nconst tagTemplate = {\n key: 'tag',\n type: 'row',\n fields: [\n {\n key: 'value',\n type: 'input',\n label: 'Tag',\n required: true,\n minLength: 2,\n props: { placeholder: 'Enter a tag', hint: 'Tags must be at least 2 characters' },\n },\n {\n key: 'removeTag',\n type: 'removeArrayItem',\n label: 'Remove',\n className: 'remove-tag-button',\n props: { color: 'warn' },\n },\n ],\n} as const;\n\n// Template for new contacts \u2014 includes remove button inside each item\nconst contactTemplate = [\n {\n key: 'name',\n type: 'input',\n label: 'Contact Name',\n required: true,\n minLength: 2,\n props: { placeholder: 'Enter contact name', hint: 'Full name of the emergency contact' },\n },\n {\n key: 'phone',\n type: 'input',\n label: 'Phone Number',\n required: true,\n pattern: /^\\d{10}$/,\n validationMessages: { pattern: 'Please enter a valid 10-digit phone number' },\n props: { type: 'tel', placeholder: '5551234567' },\n },\n {\n key: 'relationship',\n type: 'select',\n label: 'Relationship',\n required: true,\n options: [\n { label: 'Family', value: 'family' },\n { label: 'Friend', value: 'friend' },\n { label: 'Colleague', value: 'colleague' },\n { label: 'Other', value: 'other' },\n ],\n },\n {\n key: 'removeContact',\n type: 'removeArrayItem',\n label: 'Remove Contact',\n className: 'remove-contact-button',\n props: { color: 'warn' },\n },\n] as const;\n\n@Component({\n selector: 'app-array-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class ArrayFormComponent {\n formValue = signal({});\n\n config = {\n fields: [\n // Flat array with row-based items\n {\n key: 'tags',\n type: 'array',\n fields: [\n [\n {\n key: 'tag',\n type: 'row',\n fields: [\n { key: 'value', type: 'input', label: 'Tag', value: 'angular', required: true, minLength: 2 },\n { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n ],\n },\n ],\n [\n {\n key: 'tag',\n type: 'row',\n fields: [\n { key: 'value', type: 'input', label: 'Tag', value: 'typescript', required: true, minLength: 2 },\n { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n ],\n },\n ],\n ],\n },\n // Add button placed outside the array\n {\n key: 'addTagButton',\n type: 'addArrayItem',\n label: 'Add Tag',\n arrayKey: 'tags',\n template: [tagTemplate],\n props: { color: 'primary' },\n },\n\n // Object array with multiple fields per item\n {\n key: 'contacts',\n type: 'array',\n fields: [\n [\n { key: 'name', type: 'input', label: 'Contact Name', value: 'Jane Smith', required: true, minLength: 2 },\n { key: 'phone', type: 'input', label: 'Phone Number', value: '5551234567', required: true },\n {\n key: 'relationship',\n type: 'select',\n label: 'Relationship',\n value: 'family',\n required: true,\n options: [\n { label: 'Family', value: 'family' },\n { label: 'Friend', value: 'friend' },\n { label: 'Colleague', value: 'colleague' },\n { label: 'Other', value: 'other' },\n ],\n },\n { key: 'removeContact', type: 'removeArrayItem', label: 'Remove Contact', props: { color: 'warn' } },\n ],\n ],\n },\n // Multiple add buttons with different behaviors\n {\n key: 'contactButtons',\n type: 'row',\n fields: [\n {\n key: 'prependContactButton',\n type: 'prependArrayItem',\n label: 'Add First',\n arrayKey: 'contacts',\n template: contactTemplate,\n props: { color: 'accent' },\n },\n {\n key: 'addContactButton',\n type: 'addArrayItem',\n label: 'Add Contact',\n arrayKey: 'contacts',\n template: contactTemplate,\n props: { color: 'primary' },\n },\n ],\n },\n\n { key: 'submit', type: 'submit', label: 'Save All', props: { color: 'primary' } },\n ],\n } as const satisfies FormConfig;\n}\n```\n\n## Key Features\n\n### Declarative Add/Remove Buttons\n\nUse `addArrayItem`, `prependArrayItem`, and `removeArrayItem` button types directly in your config:\n\n```typescript\n// Add button outside the array\n{\n key: 'addTag',\n type: 'addArrayItem',\n label: 'Add Tag',\n arrayKey: 'tags', // Points to the array field\n template: tagTemplate, // Defines the new item structure\n}\n\n// Remove button inside each array item\n{\n key: 'removeTag',\n type: 'removeArrayItem',\n label: 'Remove',\n}\n```\n\n### Custom Button Placement\n\nPlace add/prepend buttons anywhere in the form layout:\n\n```typescript\n{\n key: 'contactButtons',\n type: 'row',\n fields: [\n { key: 'prepend', type: 'prependArrayItem', label: 'Add First', arrayKey: 'contacts', template: contactTemplate },\n { key: 'append', type: 'addArrayItem', label: 'Add Last', arrayKey: 'contacts', template: contactTemplate },\n ],\n}\n```\n\n### Templates for New Items\n\nEach add button defines its own template for what to insert:\n\n```typescript\nconst contactTemplate = [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'phone', type: 'input', label: 'Phone' },\n { key: 'remove', type: 'removeArrayItem', label: 'Remove' },\n];\n```\n\n## Use Cases\n\n- Forms requiring custom button placement\n- Arrays with multiple add operations (append, prepend, insert)\n- Heterogeneous arrays with different item structures\n- Complex layouts with row-based array items\n\n## Related Examples\n\n- **[Simplified Array Form](../simplified-array-form/)** - Simpler API with auto-generated buttons\n- **[Paginated Form](../paginated-form/)** - Multi-step wizard form\n- **[Contact Form](../contact-form/)** - Basic contact form\n\n## Related Documentation\n\n- **[Complete Array API](../../prebuilt/form-arrays/complete/)** - Full API reference\n- **[Simplified Array API](../../prebuilt/form-arrays/simplified/)** - Simpler alternative\n- **[Validation](../../validation/basics/)** - Form validation guide"
93
+ },
70
94
  {
71
95
  id: "business-account-form",
72
96
  title: "Business Account Form",
@@ -109,6 +133,12 @@ var require_docs = __commonJS({
109
133
  category: "examples",
110
134
  content: "[\u2190 Back to Quick Start](/examples)\n\nCheckout form demonstrating the common \"same as billing\" pattern for shipping addresses.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/shipping-billing-address\" class=\"example-frame\" title=\"Shipping Billing Address Demo\"></iframe>\n\n## Overview\n\nThis example shows how to toggle an entire group of fields based on a checkbox. When \"Shipping same as billing\" is checked, the shipping address fields are hidden.\n\n**Key patterns demonstrated:**\n\n- Entire group hidden/shown with single condition\n- Checkbox controls form complexity\n- Reduces user effort when addresses are the same\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, type FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-shipping-billing-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class ShippingBillingFormComponent {\n formValue = signal({});\n\n config = {\n fields: [\n {\n key: 'billingTitle',\n type: 'text',\n label: 'Billing Address',\n props: { elementType: 'h4' },\n },\n {\n key: 'billingAddress',\n type: 'group',\n fields: [\n {\n key: 'street',\n type: 'input',\n value: '',\n label: 'Street Address',\n required: true,\n },\n {\n key: 'city',\n type: 'input',\n value: '',\n label: 'City',\n required: true,\n },\n {\n key: 'state',\n type: 'input',\n value: '',\n label: 'State/Province',\n required: true,\n },\n {\n key: 'zipCode',\n type: 'input',\n value: '',\n label: 'ZIP/Postal Code',\n required: true,\n },\n ],\n },\n {\n key: 'sameAsBilling',\n type: 'checkbox',\n value: false,\n label: 'Shipping address is same as billing address',\n },\n {\n key: 'shippingTitle',\n type: 'text',\n label: 'Shipping Address',\n props: { elementType: 'h4' },\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'sameAsBilling',\n operator: 'equals',\n value: true,\n },\n },\n ],\n },\n {\n key: 'shippingAddress',\n type: 'group',\n logic: [\n {\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'sameAsBilling',\n operator: 'equals',\n value: true,\n },\n },\n ],\n fields: [\n {\n key: 'street',\n type: 'input',\n value: '',\n label: 'Street Address',\n required: true,\n },\n {\n key: 'city',\n type: 'input',\n value: '',\n label: 'City',\n required: true,\n },\n {\n key: 'state',\n type: 'input',\n value: '',\n label: 'State/Province',\n required: true,\n },\n {\n key: 'zipCode',\n type: 'input',\n value: '',\n label: 'ZIP/Postal Code',\n required: true,\n },\n ],\n },\n {\n type: 'submit',\n key: 'submit',\n label: 'Continue to Payment',\n },\n ],\n } as const satisfies FormConfig;\n}\n```\n\n## How It Works\n\n### Checkbox Toggle\n\nA simple checkbox controls whether shipping fields are visible:\n\n```typescript\n{\n key: 'sameAsBilling',\n type: 'checkbox',\n value: false,\n label: 'Shipping address is same as billing address',\n}\n```\n\n### Group Visibility\n\nThe entire shipping address group is hidden when the checkbox is checked:\n\n```typescript\n{\n key: 'shippingAddress',\n type: 'group',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'sameAsBilling',\n operator: 'equals',\n value: true,\n },\n }],\n fields: [\n // All shipping fields...\n ],\n}\n```\n\n### Section Titles\n\nThe section title is also hidden along with the group:\n\n```typescript\n{\n key: 'shippingTitle',\n type: 'text',\n label: 'Shipping Address',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'sameAsBilling',\n operator: 'equals',\n value: true,\n },\n }],\n}\n```\n\n## Use Cases\n\n- E-commerce checkout flows\n- Order forms\n- Account billing setup\n- Subscription management\n\n## Related Documentation\n\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Full conditional logic guide\n- **[Form Groups](../../prebuilt/form-groups/)** - Working with groups\n- **[Checkbox Fields](../../schema-fields/field-types/)** - Field types reference"
111
135
  },
136
+ {
137
+ id: "simplified-array-form",
138
+ title: "Simplified Array Form",
139
+ category: "examples",
140
+ content: "[\u2190 Back to Quick Start](/examples)\n\nDynamic arrays using the simplified API with auto-generated add/remove buttons, template-based item definitions, and both primitive and object arrays.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/simplified-array\" class=\"example-frame\" title=\"Simplified Array Demo\"></iframe>\n\n## Overview\n\nThis example showcases the simplified array API with:\n\n- **Primitive arrays** (tags) with flat scalar values\n- **Object arrays** (contacts) with multiple fields per item\n- **Empty arrays** that start with no items\n- **Button customization** including opt-out\n- **Auto-generated add/remove buttons**\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-simplified-array-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class SimplifiedArrayFormComponent {\n formValue = signal({});\n\n config = {\n fields: [\n // Primitive array \u2014 tags\n {\n key: 'tags',\n type: 'array',\n template: {\n key: 'value',\n type: 'input',\n label: 'Tag',\n required: true,\n minLength: 2,\n props: { placeholder: 'Enter a tag' },\n },\n value: ['angular', 'typescript'],\n addButton: { label: 'Add Tag', props: { color: 'primary' } },\n removeButton: { label: 'Remove', props: { color: 'warn' } },\n },\n\n // Object array \u2014 contacts\n {\n key: 'contacts',\n type: 'array',\n template: [\n {\n key: 'name',\n type: 'input',\n label: 'Contact Name',\n required: true,\n minLength: 2,\n props: { placeholder: 'Enter contact name' },\n },\n {\n key: 'phone',\n type: 'input',\n label: 'Phone Number',\n props: { type: 'tel', placeholder: '5551234567' },\n },\n ],\n value: [\n { name: 'Jane Smith', phone: '5551234567' },\n { name: 'John Doe', phone: '5559876543' },\n ],\n addButton: { label: 'Add Contact', props: { color: 'primary' } },\n },\n\n // Empty array \u2014 notes\n {\n key: 'notes',\n type: 'array',\n template: {\n key: 'text',\n type: 'input',\n label: 'Note',\n props: { placeholder: 'Enter a note' },\n },\n addButton: { label: 'Add Note' },\n },\n\n // No remove button \u2014 categories\n {\n key: 'categories',\n type: 'array',\n template: { key: 'name', type: 'input', label: 'Category' },\n value: ['Frontend', 'Backend'],\n removeButton: false,\n addButton: { label: 'Add Category' },\n },\n\n { key: 'submit', type: 'submit', label: 'Save All', props: { color: 'primary' } },\n ],\n } as const satisfies FormConfig;\n}\n```\n\n## Key Features\n\n### Template-Based Items\n\nDefine the item structure once via `template`, and provide initial data via `value`:\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag', required: true },\n value: ['angular', 'typescript'],\n}\n```\n\n### Auto-Generated Buttons\n\nAdd and remove buttons are generated automatically. Customize labels and props:\n\n```typescript\naddButton: { label: 'Add Tag', props: { color: 'primary' } },\nremoveButton: { label: 'Remove', props: { color: 'warn' } },\n```\n\n### Button Opt-Out\n\nDisable buttons entirely with `false`:\n\n```typescript\nremoveButton: false, // No remove buttons on items\naddButton: false, // No add button\n```\n\n## Use Cases\n\n- Tag lists and keyword management\n- Contact lists with multiple fields\n- Dynamic note-taking\n- Category management\n- Any repeating data entry\n\n## Related Examples\n\n- **[Array Form (Complete)](../array-form/)** - Full control with declarative buttons and EventBus\n- **[Paginated Form](../paginated-form/)** - Multi-step wizard form\n- **[Contact Form](../contact-form/)** - Basic contact form\n\n## Related Documentation\n\n- **[Simplified Array API](../../prebuilt/form-arrays/simplified/)** - Full API reference\n- **[Complete Array API](../../prebuilt/form-arrays/complete/)** - Advanced array features\n- **[Validation](../../validation/basics/)** - Form validation guide"
141
+ },
112
142
  {
113
143
  id: "user-registration",
114
144
  title: "User Registration",
@@ -125,37 +155,43 @@ var require_docs = __commonJS({
125
155
  id: "index",
126
156
  title: "Index",
127
157
  category: "installation",
128
- content: 'Get ng-forge dynamic forms up and running in your Angular project.\n\n## Requirements\n\n- **Angular 21+** - ng-forge dynamic forms requires Angular 21 or higher for signal forms support\n- **TypeScript 5.6+** - For best type inference results\n\n## Installation\n\nInstall the core library and your preferred UI integration:\n\n```bash group="install" name="npm"\nnpm install @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="yarn"\nyarn add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="pnpm"\npnpm add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n> This installs the core `@ng-forge/dynamic-forms` package and the Material Design integration. See [UI Framework Options](#ui-framework-options) below for other choices.\n\n## Configure Your App\n\nAdd the dynamic form provider to your app configuration:\n\n```typescript name="app.config.ts"\nimport { ApplicationConfig } from \'@angular/core\';\nimport { provideDynamicForm } from \'@ng-forge/dynamic-forms\';\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [\n provideDynamicForm(...withMaterialFields()),\n // ... other providers\n ],\n};\n```\n\nThe `provideDynamicForm()` function registers field types and validators. The `withMaterialFields()` function provides all Material Design field components.\n\n## Create Your First Form\n\nCreate a simple login form to verify everything works:\n\n```typescript name="login.component.ts"\nimport { Component } from \'@angular/core\';\nimport { DynamicForm, type FormConfig } from \'@ng-forge/dynamic-forms\';\n\n@Component({\n selector: \'app-login\',\n imports: [DynamicForm],\n template: `<form [dynamic-form]="config"></form>`,\n})\nexport class LoginComponent {\n config = {\n fields: [\n {\n key: \'email\',\n type: \'input\',\n value: \'\',\n label: \'Email\',\n required: true,\n email: true,\n },\n {\n key: \'password\',\n type: \'input\',\n value: \'\',\n label: \'Password\',\n required: true,\n minLength: 8,\n props: { type: \'password\' },\n },\n {\n type: \'submit\',\n key: \'submit\',\n label: \'Sign In\',\n props: { color: \'primary\' },\n },\n ],\n } as const satisfies FormConfig;\n}\n```\n\nYou now have a working form with:\n\n- \u2705 Real-time validation with error messages\n- \u2705 TypeScript type inference\n- \u2705 Material Design styling\n- \u2705 Accessibility support\n- \u2705 Submit button auto-disables when invalid\n\n## UI Framework Options\n\nng-forge dynamic forms supports multiple UI frameworks. Install the integration package for your preferred framework:\n\n### Material Design (Preview)\n\n```bash group="install-material" name="npm"\nnpm install @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="yarn"\nyarn add @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="pnpm"\npnpm add @ng-forge/dynamic-forms-material\n```\n\n```typescript\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withMaterialFields())],\n};\n```\n\nSee [Material Integration](../ui-libs-integrations/material) for full documentation.\n\n### PrimeNG (Preview)\n\n```bash group="install-primeng" name="npm"\nnpm install @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="yarn"\nyarn add @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="pnpm"\npnpm add @ng-forge/dynamic-forms-primeng\n```\n\n```typescript\nimport { withPrimeNGFields } from \'@ng-forge/dynamic-forms-primeng\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withPrimeNGFields())],\n};\n```\n\nSee [PrimeNG Integration](../ui-libs-integrations/primeng) for full documentation.\n\n### Bootstrap (Preview)\n\n```bash group="install-bootstrap" name="npm"\nnpm install @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="yarn"\nyarn add @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="pnpm"\npnpm add @ng-forge/dynamic-forms-bootstrap\n```\n\n```typescript\nimport { withBootstrapFields } from \'@ng-forge/dynamic-forms-bootstrap\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withBootstrapFields())],\n};\n```\n\nSee [Bootstrap Integration](../ui-libs-integrations/bootstrap) for full documentation.\n\n### Ionic (Preview)\n\n```bash group="install-ionic" name="npm"\nnpm install @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="yarn"\nyarn add @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="pnpm"\npnpm add @ng-forge/dynamic-forms-ionic\n```\n\n```typescript\nimport { withIonicFields } from \'@ng-forge/dynamic-forms-ionic\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withIonicFields())],\n};\n```\n\nSee [Ionic Integration](../ui-libs-integrations/ionic) for full documentation.\n\n### Custom UI Components\n\nYou can also build your own field components using any UI library or custom styling:\n\n```typescript\nimport { MyCustomInputComponent } from \'./my-custom-input.component\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [\n provideDynamicForm([\n { name: \'input\', loadComponent: () => MyCustomInputComponent },\n // ... more custom field types\n ]),\n ],\n};\n```\n\nSee [Custom Integration Guide](../advanced/custom-integrations) for building custom field components.\n\n## Next Steps\n\nNow that you have ng-forge dynamic forms installed, explore the core features:\n\n### Learn Core Concepts\n\n- **[Field Types](../schema-fields/field-types)** - Understand all available field types (input, select, checkbox, group, etc.)\n- **[Validation](../validation/basics)** - Add validation rules with shorthand syntax or conditional validators\n- **[Conditional Logic](../dynamic-behavior/conditional-logic/overview)** - Show/hide fields based on other field values\n- **[Type Safety](../advanced/type-safety/basics)** - TypeScript type inference for forms\n\n### Build Advanced Forms\n\n- **[Multi-Step Forms](../layout-components/form-pages)** - Create wizard-style forms with page navigation\n- **[Repeatable Sections](../layout-components/form-arrays)** - Dynamic form arrays for adding/removing fields\n- **[Conditional Validation](../validation/advanced#conditional-validators)** - Validators that activate based on conditions\n\n### Customize and Extend\n\n- **[i18n Setup](../dynamic-behavior/i18n)** - Add multi-language support to your forms\n- **[Events](../advanced/events)** - Handle custom form events\n- **[Custom Fields](../advanced/custom-integrations)** - Create your own field types\n\n## Get Help\n\n- \u{1F4AC} **[GitHub Discussions](https://github.com/ng-forge/ng-forge/discussions)** - Ask questions and get help\n- \u{1F41B} **[Issue Tracker](https://github.com/ng-forge/ng-forge/issues)** - Report bugs\n- \u{1F4D6} **[Documentation](../)** - Browse full documentation'
158
+ content: 'Get ng-forge dynamic forms up and running in your Angular project.\n\n## Requirements\n\n- **Angular 21+** - ng-forge dynamic forms requires Angular 21 or higher for signal forms support\n- **TypeScript 5.6+** - For best type inference results\n\n## Installation\n\nInstall the core library and your preferred UI integration:\n\n```bash group="install" name="npm"\nnpm install @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="yarn"\nyarn add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="pnpm"\npnpm add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n> This installs the core `@ng-forge/dynamic-forms` package and the Material Design integration. See [UI Framework Options](#ui-framework-options) below for other choices.\n\n## Configure Your App\n\nAdd the dynamic form provider to your app configuration:\n\n```typescript name="app.config.ts"\nimport { ApplicationConfig } from \'@angular/core\';\nimport { provideDynamicForm } from \'@ng-forge/dynamic-forms\';\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [\n provideDynamicForm(...withMaterialFields()),\n // ... other providers\n ],\n};\n```\n\nThe `provideDynamicForm()` function registers field types and validators. The `withMaterialFields()` function provides all Material Design field components.\n\n## Create Your First Form\n\nCreate a simple login form to verify everything works:\n\n```typescript name="login.component.ts"\nimport { Component } from \'@angular/core\';\nimport { DynamicForm, type FormConfig } from \'@ng-forge/dynamic-forms\';\n\n@Component({\n selector: \'app-login\',\n imports: [DynamicForm],\n template: `<form [dynamic-form]="config"></form>`,\n})\nexport class LoginComponent {\n config = {\n fields: [\n {\n key: \'email\',\n type: \'input\',\n value: \'\',\n label: \'Email\',\n required: true,\n email: true,\n },\n {\n key: \'password\',\n type: \'input\',\n value: \'\',\n label: \'Password\',\n required: true,\n minLength: 8,\n props: { type: \'password\' },\n },\n {\n type: \'submit\',\n key: \'submit\',\n label: \'Sign In\',\n props: { color: \'primary\' },\n },\n ],\n } as const satisfies FormConfig;\n}\n```\n\nYou now have a working form with:\n\n- \u2705 Real-time validation with error messages\n- \u2705 TypeScript type inference\n- \u2705 Material Design styling\n- \u2705 Accessibility support\n- \u2705 Submit button auto-disables when invalid\n\n## UI Framework Options\n\nng-forge dynamic forms supports multiple UI frameworks. Install the integration package for your preferred framework:\n\n### Material Design (Preview)\n\n```bash group="install-material" name="npm"\nnpm install @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="yarn"\nyarn add @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="pnpm"\npnpm add @ng-forge/dynamic-forms-material\n```\n\n```typescript\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withMaterialFields())],\n};\n```\n\nSee [Material Integration](../ui-libs-integrations/material) for full documentation.\n\n### PrimeNG (Preview)\n\n```bash group="install-primeng" name="npm"\nnpm install @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="yarn"\nyarn add @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="pnpm"\npnpm add @ng-forge/dynamic-forms-primeng\n```\n\n```typescript\nimport { withPrimeNGFields } from \'@ng-forge/dynamic-forms-primeng\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withPrimeNGFields())],\n};\n```\n\nSee [PrimeNG Integration](../ui-libs-integrations/primeng) for full documentation.\n\n### Bootstrap (Preview)\n\n```bash group="install-bootstrap" name="npm"\nnpm install @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="yarn"\nyarn add @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="pnpm"\npnpm add @ng-forge/dynamic-forms-bootstrap\n```\n\n```typescript\nimport { withBootstrapFields } from \'@ng-forge/dynamic-forms-bootstrap\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withBootstrapFields())],\n};\n```\n\nSee [Bootstrap Integration](../ui-libs-integrations/bootstrap) for full documentation.\n\n### Ionic (Preview)\n\n```bash group="install-ionic" name="npm"\nnpm install @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="yarn"\nyarn add @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="pnpm"\npnpm add @ng-forge/dynamic-forms-ionic\n```\n\n```typescript\nimport { withIonicFields } from \'@ng-forge/dynamic-forms-ionic\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [provideDynamicForm(...withIonicFields())],\n};\n```\n\nSee [Ionic Integration](../ui-libs-integrations/ionic) for full documentation.\n\n### Custom UI Components\n\nYou can also build your own field components using any UI library or custom styling:\n\n```typescript\nimport { MyCustomInputComponent } from \'./my-custom-input.component\';\n\nexport const appConfig: ApplicationConfig = {\n providers: [\n provideDynamicForm([\n { name: \'input\', loadComponent: () => MyCustomInputComponent },\n // ... more custom field types\n ]),\n ],\n};\n```\n\nSee [Custom Integration Guide](../advanced/custom-integrations) for building custom field components.\n\n## Next Steps\n\nNow that you have ng-forge dynamic forms installed, explore the core features:\n\n### Learn Core Concepts\n\n- **[Field Types](../schema-fields/field-types)** - Understand all available field types (input, select, checkbox, group, etc.)\n- **[Validation](../validation/basics)** - Add validation rules with shorthand syntax or conditional validators\n- **[Conditional Logic](../dynamic-behavior/conditional-logic/overview)** - Show/hide fields based on other field values\n- **[Type Safety](../advanced/type-safety/basics)** - TypeScript type inference for forms\n\n### Build Advanced Forms\n\n- **[Multi-Step Forms](../prebuilt/form-pages)** - Create wizard-style forms with page navigation\n- **[Repeatable Sections](../prebuilt/form-arrays/simplified)** - Dynamic form arrays for adding/removing fields\n- **[Conditional Validation](../validation/advanced#conditional-validators)** - Validators that activate based on conditions\n\n### Customize and Extend\n\n- **[i18n Setup](../dynamic-behavior/i18n)** - Add multi-language support to your forms\n- **[Events](../advanced/events)** - Handle custom form events\n- **[Custom Fields](../advanced/custom-integrations)** - Create your own field types\n\n## Get Help\n\n- \u{1F4AC} **[GitHub Discussions](https://github.com/ng-forge/ng-forge/discussions)** - Ask questions and get help\n- \u{1F41B} **[Issue Tracker](https://github.com/ng-forge/ng-forge/issues)** - Report bugs\n- \u{1F4D6} **[Documentation](../)** - Browse full documentation'
159
+ },
160
+ {
161
+ id: "form-arrays-complete",
162
+ title: "Form Arrays Complete",
163
+ category: "prebuilt",
164
+ content: "Arrays create dynamic collections of field values. Each item in the `fields` array defines **one array item** with its structure and initial values.\n\n> For most use cases, the **simplified array API** is recommended. See [Form Arrays (Simplified)](/prebuilt/form-arrays/simplified) for details. This page documents the complete API for advanced use cases.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Structure Overview\n\nThe `fields` property supports two item formats:\n\n- **Single FieldDef** (not wrapped in array) \u2192 **Primitive item** - extracts field value directly\n- **Array of FieldDefs** \u2192 **Object item** - merges fields into an object\n\n```typescript\n// Primitive array: ['angular', 'typescript']\n{\n key: 'tags',\n type: 'array',\n fields: [\n { key: 'tag', type: 'input', value: 'angular' }, // Single field = primitive\n { key: 'tag', type: 'input', value: 'typescript' },\n ]\n}\n\n// Object array: [{ name: 'Alice', email: '...' }]\n{\n key: 'contacts',\n type: 'array',\n fields: [\n [ // Array of fields = object\n { key: 'name', type: 'input', label: 'Name', value: 'Alice' },\n { key: 'email', type: 'input', label: 'Email', value: 'alice@example.com' }\n ],\n ]\n}\n```\n\n## Empty Arrays (No Initial Items)\n\nFor arrays that start empty and are populated via buttons:\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n fields: [] // No initial items - user adds via button\n}\n```\n\n## Array Size Validation\n\nUse `minLength` and `maxLength` on the array field to constrain the number of items. When violated, the form becomes invalid (e.g. submit button is disabled), but no field-level error message is shown.\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n minLength: 1, // At least 1 item required\n maxLength: 5, // No more than 5 items\n fields: [\n [{ key: 'tag', type: 'input', label: 'Tag', value: 'default' }]\n ]\n}\n```\n\n| Property | Type | Description |\n| ----------- | -------- | ----------------------------- |\n| `minLength` | `number` | Minimum number of array items |\n| `maxLength` | `number` | Maximum number of array items |\n\nBoth properties are optional and can be used independently or together.\n\n## Initial Values\n\nInitial values are defined directly on each field via the `value` property - no separate `initialValue` is needed:\n\n```typescript\n{\n key: 'emails',\n type: 'array',\n fields: [\n // One initial item with pre-filled value (object item)\n [\n { key: 'email', type: 'input', label: 'Email', value: 'primary@example.com' }\n ]\n ]\n}\n```\n\n## Primitive Arrays (Simple Value Lists)\n\nFor simple arrays of primitive values like `['tag1', 'tag2']`, use a **single FieldDef per item** (not wrapped in an array):\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n fields: [\n { key: 'tag', type: 'input', label: 'Tag', value: 'featured' },\n { key: 'tag', type: 'input', label: 'Tag', value: 'popular' }\n ]\n}\n```\n\nThis creates a true primitive array in the form value:\n\n```typescript\n{\n tags: ['featured', 'popular'];\n}\n```\n\nThe `key` property on each field is used for internal tracking but doesn't affect the output value.\n\n## Object Arrays (Multiple Fields per Item)\n\nFor arrays of objects with multiple fields, wrap the fields in an **inner array**:\n\n```typescript\n{\n key: 'contacts',\n type: 'array',\n fields: [\n [\n { key: 'name', type: 'input', label: 'Name', value: '' },\n { key: 'phone', type: 'input', label: 'Phone', value: '' }\n ]\n ]\n}\n```\n\nThis creates an array of objects:\n\n```typescript\n{\n contacts: [{ name: '', phone: '' }];\n}\n```\n\n## Nested Object Arrays (Using Groups)\n\nFor arrays with nested object structure, use a group field:\n\n```typescript\n{\n key: 'contacts',\n type: 'array',\n fields: [\n [\n {\n key: 'contact',\n type: 'group',\n fields: [\n { key: 'name', type: 'input', label: 'Name', value: '' },\n { key: 'phone', type: 'input', label: 'Phone', value: '' }\n ]\n }\n ]\n ]\n}\n```\n\nThis creates an array of nested objects (note the group key creates the nesting):\n\n```typescript\n{\n contacts: [{ contact: { name: '', phone: '' } }];\n}\n```\n\n## Heterogeneous Arrays (Mixed Primitives and Objects)\n\nArrays can contain both primitive and object items in the same array:\n\n```typescript\n{\n key: 'items',\n type: 'array',\n fields: [\n [{ key: 'label', type: 'input', value: 'Structured' }], // Object item (wrapped in array)\n { key: 'value', type: 'input', value: 'Simple' }, // Primitive item (single field)\n ]\n}\n```\n\nThis creates a heterogeneous array:\n\n```typescript\n{\n items: [{ label: 'Structured' }, 'Simple'];\n}\n```\n\n## Array vs Group\n\n- **Groups** create nested objects with keys: `{ address: { street: '', city: '' } }`\n- **Primitive Arrays** create lists of values: `{ tags: ['value1', 'value2'] }`\n- **Object Arrays** create lists of objects: `{ items: [{name: ''}, {name: ''}] }`\n\n## Dynamic Add/Remove\n\n### Declarative Approach (Recommended)\n\nUse button field types directly in your form configuration for declarative array manipulation:\n\n| Button Type | Placement | Description |\n| ------------------ | ---------------- | ------------------------------------------------ |\n| `addArrayItem` | Outside array | Appends a new item to the end of the array |\n| `prependArrayItem` | Outside array | Inserts a new item at the beginning of the array |\n| `insertArrayItem` | Outside array | Inserts a new item at a specific index |\n| `removeArrayItem` | Inside each item | Removes the current item from the array |\n| `popArrayItem` | Outside array | Removes the last item from the array |\n| `shiftArrayItem` | Outside array | Removes the first item from the array |\n\n**Important:** Add/prepend/insert buttons **require** a `template` property defining the new item structure. There is no fallback to the array's `fields[0]` - each button must explicitly define what structure to add.\n\nThe `template` can be:\n\n- **Single FieldDef** - creates a primitive item (field value is extracted directly)\n- **Array of FieldDefs** - creates an object item (fields merged into object)\n\n```typescript\n// Template for PRIMITIVE items (single field, not wrapped)\nconst tagTemplate = { key: 'tag', type: 'input', label: 'Tag' };\n\n// Template for OBJECT items (array of fields)\nconst contactTemplate = [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'phone', type: 'input', label: 'Phone' },\n // Remove button inside each item (no template needed)\n { key: 'remove', type: 'removeArrayItem', label: 'Remove' },\n];\n\n// Form configuration\n{\n fields: [\n {\n key: 'tags',\n type: 'array',\n fields: [], // Start empty - primitive array\n },\n // Add button for primitive items\n {\n key: 'addTag',\n type: 'addArrayItem',\n label: 'Add Tag',\n arrayKey: 'tags',\n template: tagTemplate, // Single field = primitive item\n },\n {\n key: 'contacts',\n type: 'array',\n fields: [], // Start empty - object array\n },\n // Add button for object items\n {\n key: 'addContact',\n type: 'addArrayItem',\n label: 'Add Contact',\n arrayKey: 'contacts',\n template: contactTemplate, // Array of fields = object item\n },\n ];\n}\n```\n\n### Programmatic Approach\n\nFor more control, use the event bus with the `arrayEvent` builder. **Note:** When using the programmatic approach, you must provide a template:\n\n```typescript\nimport { EventBus, arrayEvent } from '@ng-forge/dynamic-forms';\n\n// Inject the event bus\neventBus = inject(EventBus);\n\n// Template for PRIMITIVE items (single field, not wrapped)\ntagTemplate = { key: 'tag', type: 'input', label: 'Tag', value: '' };\n\n// Template for OBJECT items (array of fields)\ncontactTemplate = [\n { key: 'name', type: 'input', label: 'Name', value: '' },\n { key: 'phone', type: 'input', label: 'Phone', value: '' }\n];\n\n// Add PRIMITIVE item to end of array\naddTag() {\n this.eventBus.dispatch(arrayEvent('tags').append(this.tagTemplate));\n}\n\n// Add OBJECT item to end of array\naddContact() {\n this.eventBus.dispatch(arrayEvent('contacts').append(this.contactTemplate));\n}\n\n// Add item to beginning of array\nprependItem() {\n this.eventBus.dispatch(arrayEvent('contacts').prepend(this.contactTemplate));\n}\n\n// Add item at specific index\naddItemAt(index: number) {\n this.eventBus.dispatch(arrayEvent('contacts').insertAt(index, this.contactTemplate));\n}\n\n// Remove last item (no template needed)\nremoveLastItem() {\n this.eventBus.dispatch(arrayEvent('contacts').pop());\n}\n\n// Remove first item (no template needed)\nremoveFirstItem() {\n this.eventBus.dispatch(arrayEvent('contacts').shift());\n}\n\n// Remove item at specific index (no template needed)\nremoveItemAt(index: number) {\n this.eventBus.dispatch(arrayEvent('contacts').removeAt(index));\n}\n```\n\n## Use Cases\n\nArrays are ideal for:\n\n- Lists of simple values (tags, categories, keywords)\n- Repeating form sections (multiple addresses, phone numbers)\n- Dynamic collections where items can be added/removed\n- Collection-based data structures where order matters\n\n## Complete Example: Primitive Array with Initial Values\n\nHere's a complete working example of a primitive array field (simple value list) with initial values and declarative add/remove buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new tags - a row with an input and a remove button\nconst tagTemplate = {\n key: 'tag',\n type: 'row',\n fields: [\n {\n key: 'value',\n type: 'input',\n label: 'Tag',\n required: true,\n minLength: 2,\n },\n {\n key: 'removeTag',\n type: 'removeArrayItem',\n label: 'Remove',\n props: { color: 'warn' },\n },\n ],\n} as const;\n\nconst formConfig = {\n fields: [\n {\n key: 'tags',\n type: 'array',\n // Start with two initial tags using the same row structure\n fields: [\n [\n {\n key: 'tag',\n type: 'row',\n fields: [\n { key: 'value', type: 'input', label: 'Tag', value: 'featured', required: true, minLength: 2 },\n { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n ],\n },\n ],\n [\n {\n key: 'tag',\n type: 'row',\n fields: [\n { key: 'value', type: 'input', label: 'Tag', value: 'popular', required: true, minLength: 2 },\n { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n ],\n },\n ],\n ],\n },\n // Declarative add button - no EventBus needed\n {\n key: 'addTag',\n type: 'addArrayItem',\n label: 'Add Tag',\n arrayKey: 'tags',\n template: [tagTemplate],\n props: { color: 'primary' },\n },\n ],\n} as const satisfies FormConfig;\n\n// Form value: { tags: [{ tag: { value: 'featured' } }, { tag: { value: 'popular' } }] }\n```\n\n## Complete Example: Object Array with Initial Values\n\nHere's a complete working example of an object array field with initial values, validation, and declarative buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new contacts - includes a remove button inside each item\nconst contactTemplate = [\n { key: 'name', type: 'input', label: 'Contact Name', required: true, minLength: 2 },\n { key: 'phone', type: 'input', label: 'Phone Number', required: true, pattern: /^\\d{10}$/ },\n {\n key: 'relationship',\n type: 'select',\n label: 'Relationship',\n options: [\n { label: 'Family', value: 'family' },\n { label: 'Friend', value: 'friend' },\n { label: 'Colleague', value: 'colleague' },\n ],\n },\n {\n key: 'removeContact',\n type: 'removeArrayItem',\n label: 'Remove Contact',\n props: { color: 'warn' },\n },\n] as const;\n\nconst formConfig = {\n fields: [\n {\n key: 'contacts',\n type: 'array',\n // Start with one pre-filled contact (includes remove button)\n fields: [\n [\n { key: 'name', type: 'input', label: 'Contact Name', value: 'John Doe', required: true, minLength: 2 },\n {\n key: 'phone',\n type: 'input',\n label: 'Phone Number',\n value: '5551234567',\n required: true,\n pattern: /^\\d{10}$/,\n },\n {\n key: 'relationship',\n type: 'select',\n label: 'Relationship',\n value: 'family',\n options: [\n { label: 'Family', value: 'family' },\n { label: 'Friend', value: 'friend' },\n { label: 'Colleague', value: 'colleague' },\n ],\n },\n {\n key: 'removeContact',\n type: 'removeArrayItem',\n label: 'Remove Contact',\n props: { color: 'warn' },\n },\n ],\n ],\n },\n // Declarative add button - no EventBus needed\n {\n key: 'addContact',\n type: 'addArrayItem',\n label: 'Add Contact',\n arrayKey: 'contacts',\n template: contactTemplate,\n props: { color: 'primary' },\n },\n ],\n} as const satisfies FormConfig;\n\n// Form value: { contacts: [{ name: 'John Doe', phone: '5551234567', relationship: 'family' }] }\n```\n\n## Template Requirement\n\n**Important:** When adding items dynamically (via buttons or event bus), you must always provide an explicit `template`. There is no automatic fallback to use the first item's structure.\n\nThis design ensures:\n\n- Clear intent - each add operation explicitly defines what to add\n- Flexibility - different buttons can add different item structures\n- No ambiguity - the array's `fields` only defines initial items, not a \"default template\"\n\n## Heterogeneous Items\n\nArrays can have items with different field structures:\n\n```typescript\n{\n key: 'entries',\n type: 'array',\n fields: [\n // Item 0: Simple tag\n [{ key: 'tag', type: 'input', label: 'Tag', value: 'simple' }],\n // Item 1: Contact with more fields\n [\n { key: 'name', type: 'input', label: 'Name', value: 'Alice' },\n { key: 'email', type: 'input', label: 'Email', value: 'alice@example.com' }\n ]\n ]\n}\n```\n\nThis flexibility allows each item to have its own structure, though typically all items share the same structure for consistency.\n\n## Nesting Constraints\n\nArray fields can be used within:\n\n- Pages (top-level container)\n- Rows (for horizontal layouts)\n- Groups (for nested arrays within objects)\n\nArrays **cannot** contain:\n\n- Other array fields (no nested arrays)\n- Page fields\n\n## Allowed Children\n\nArrays can contain these field types:\n\n- Leaf fields (input, select, checkbox, etc.) -> creates flat or object arrays\n- Group fields with key -> creates nested object arrays `[{groupKey: {...}}, ...]`\n- Row fields -> creates flat object arrays `[{...}, {...}]` (rows don't add nesting)\n- Button fields (for remove operations inside each item)\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how arrays affect type inference.\n\n## Conditional Visibility\n\nArray containers support the `logic` property to conditionally show or hide the entire array section based on form state.\n\n```typescript\n{\n key: 'dependents',\n type: 'array',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'hasDependents',\n operator: 'equals',\n value: false,\n },\n }],\n fields: [/* ... */],\n}\n```\n\nWhen the array is hidden, all items and add/remove buttons are hidden with it. Only `'hidden'` is supported as a logic type on containers.\n\nFor all available condition types and operators, see [Conditional Logic](../../../dynamic-behavior/conditional-logic/overview/).\n\n## When to Use the Complete API\n\nThe complete API documented on this page is the right choice when you need capabilities beyond what the simplified API offers:\n\n- **Heterogeneous items** -- Different field structures per item (e.g. some items have 2 fields, others have 5)\n- **Custom button placement** -- Positioning add/remove/prepend/insert buttons in specific locations relative to the array\n- **Programmatic control via EventBus** -- Dispatching `arrayEvent` commands for append, prepend, insertAt, pop, shift, and removeAt operations from component code\n- **Custom templates per button action** -- Different add buttons that each insert a different item structure (e.g. an \"Add Simple\" and an \"Add Detailed\" button)\n- **Mixed primitive and object items** -- Arrays containing both primitive values and object values in the same collection\n\nFor all other scenarios, the [simplified array API](/prebuilt/form-arrays/simplified) provides a more concise configuration with auto-generated buttons."
129
165
  },
130
166
  {
131
- id: "form-arrays",
132
- title: "Form Arrays",
167
+ id: "form-arrays-simplified",
168
+ title: "Form Arrays Simplified",
133
169
  category: "prebuilt",
134
- content: "Arrays create dynamic collections of field values. The fields array defines a **template** that is cloned for each array item.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array-field\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Flat Arrays (Primitive Values)\n\nFor simple arrays of primitive values, use a leaf field as the template:\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n fields: [\n { key: 'tag', type: 'input', label: 'Tag', value: '' }\n ],\n}\n```\n\nThis creates a flat array in the form value:\n\n```typescript\n{\n tags: ['tag1', 'tag2', 'tag3'];\n}\n```\n\n## Object Arrays (Nested Groups)\n\nFor arrays of objects, use a group field as the template:\n\n```typescript\n{\n key: 'contacts',\n type: 'array',\n fields: [{\n type: 'group',\n fields: [\n { key: 'name', type: 'input', label: 'Name', value: '' },\n { key: 'phone', type: 'input', label: 'Phone', value: '' }\n ]\n }],\n}\n```\n\nThis creates an array of objects:\n\n```typescript\n{\n contacts: [\n { name: 'John Doe', phone: '5551234567' },\n { name: 'Jane Smith', phone: '5559876543' },\n ];\n}\n```\n\n## Array vs Group\n\n- **Groups** create nested objects with keys: `{ address: { street: '', city: '' } }`\n- **Flat Arrays** create lists of values: `{ tags: ['value1', 'value2'] }`\n- **Object Arrays** create lists of objects: `{ items: [{name: ''}, {name: ''}] }`\n\n## Dynamic Add/Remove\n\nArray items can be added or removed dynamically at runtime using the event bus:\n\n```typescript\nimport { EventBus, AddArrayItemEvent, RemoveArrayItemEvent } from '@ng-forge/dynamic-forms';\n\n// Inject the event bus\neventBus = inject(EventBus);\n\n// Add item to array\naddItem() {\n this.eventBus.dispatch(AddArrayItemEvent, 'tags');\n}\n\n// Add item at specific index\naddItemAt(index: number) {\n this.eventBus.dispatch(AddArrayItemEvent, 'tags', index);\n}\n\n// Remove last item\nremoveItem() {\n this.eventBus.dispatch(RemoveArrayItemEvent, 'tags');\n}\n\n// Remove item at specific index\nremoveItemAt(index: number) {\n this.eventBus.dispatch(RemoveArrayItemEvent, 'tags', index);\n}\n```\n\n## Use Cases\n\nArrays are ideal for:\n\n- Lists of simple values (tags, categories, keywords)\n- Repeating form sections (multiple addresses, phone numbers)\n- Dynamic collections where items can be added/removed\n- Collection-based data structures where order matters\n\n## Complete Example: Flat Array\n\nHere's a complete working example of a flat array field with dynamic add/remove:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { DynamicForm, EventBus, AddArrayItemEvent, RemoveArrayItemEvent } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-tags-form',\n imports: [DynamicForm],\n template: `\n <form [dynamic-form]=\"formConfig\"></form>\n <button (click)=\"addTag()\">Add Tag</button>\n `,\n})\nexport class TagsFormComponent {\n private eventBus = inject(EventBus);\n\n formConfig = {\n fields: [\n // Note: Array fields don't support the 'label' property.\n // Use a text field above if you need a section header.\n {\n key: 'tags',\n type: 'array',\n fields: [\n {\n key: 'tag',\n type: 'input',\n label: 'Tag',\n value: '',\n required: true,\n minLength: 2,\n },\n ],\n },\n ],\n };\n\n addTag() {\n this.eventBus.dispatch(AddArrayItemEvent, 'tags');\n }\n\n removeTag(index: number) {\n this.eventBus.dispatch(RemoveArrayItemEvent, 'tags', index);\n }\n}\n```\n\n## Complete Example: Object Array\n\nHere's a complete working example of an object array field with validation:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { DynamicForm, EventBus, AddArrayItemEvent, RemoveArrayItemEvent } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-contacts-form',\n imports: [DynamicForm],\n template: `\n <form [dynamic-form]=\"formConfig\"></form>\n <button (click)=\"addContact()\">Add Contact</button>\n `,\n})\nexport class ContactsFormComponent {\n private eventBus = inject(EventBus);\n\n formConfig = {\n fields: [\n // Note: Array fields don't support the 'label' property.\n // Use a text field above if you need a section header.\n {\n key: 'contacts',\n type: 'array',\n fields: [\n {\n type: 'group',\n fields: [\n {\n key: 'name',\n type: 'input',\n label: 'Contact Name',\n value: '',\n required: true,\n minLength: 2,\n },\n {\n key: 'phone',\n type: 'input',\n label: 'Phone Number',\n value: '',\n required: true,\n pattern: /^\\d{10}$/,\n },\n {\n key: 'relationship',\n type: 'select',\n label: 'Relationship',\n value: 'friend',\n options: [\n { label: 'Family', value: 'family' },\n { label: 'Friend', value: 'friend' },\n { label: 'Colleague', value: 'colleague' },\n ],\n },\n ],\n },\n ],\n },\n ],\n };\n\n addContact() {\n this.eventBus.dispatch(AddArrayItemEvent, 'contacts');\n }\n\n removeContact(index: number) {\n this.eventBus.dispatch(RemoveArrayItemEvent, 'contacts', index);\n }\n}\n```\n\n## Template Field Concept\n\nThe key concept is that the `fields` array contains a **template** (typically one field definition):\n\n- **Flat arrays**: Template is a leaf field \u2192 creates `[value1, value2]`\n- **Object arrays**: Template is a group field \u2192 creates `[{...}, {...}]`\n\nWhen you add an array item via the event bus, the template is cloned and a new instance is created with the appropriate default value.\n\n## Nesting Constraints\n\nArray fields can be used within:\n\n- Pages (top-level container)\n- Rows (for horizontal layouts)\n- Groups (for nested arrays within objects)\n\nArrays **cannot** contain:\n\n- Other array fields (no nested arrays)\n- Page fields\n\n## Allowed Children (as template)\n\nArrays can use these field types as templates:\n\n- Leaf fields (input, select, checkbox, etc.) \u2192 creates flat arrays\n- Group fields \u2192 creates object arrays\n- Row fields \u2192 for horizontal layouts within each array item\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how arrays affect type inference."
170
+ content: "The simplified array API provides a concise way to define dynamic arrays. Instead of manually specifying each item in `fields`, you provide a `template` for the item structure and a `value` array with initial data. Add and remove buttons are generated automatically.\n\n> **When should I use this?** For most array use cases -- primitive lists, object lists, and standard add/remove workflows -- the simplified API is the right choice. For advanced scenarios like heterogeneous items or custom button placement, see [Form Arrays (Complete)](/prebuilt/form-arrays/complete).\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/simplified-array\" class=\"example-frame\" title=\"Simplified Array Demo\"></iframe>\n\n## Overview\n\nThe simplified API uses two key properties:\n\n| Property | Description |\n| ----------- | -------------------------------------------------------------------------- |\n| `template` | Defines the structure of a single array item (single field or field array) |\n| `value` | Initial data array -- each element creates one pre-filled item |\n| `minLength` | Minimum number of array items (form invalid if fewer) |\n| `maxLength` | Maximum number of array items (form invalid if more) |\n\nThe `template` shape determines the array variant:\n\n- **Single field** (`template: { ... }`) -- primitive array (e.g. `['tag1', 'tag2']`)\n- **Array of fields** (`template: [{ ... }, { ... }]`) -- object array (e.g. `[{ name: 'Jane', phone: '555' }]`)\n\n```typescript\n// Discriminant: template is a single field \u2192 primitive array\n{ key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' } }\n\n// Discriminant: template is an array of fields \u2192 object array\n{ key: 'contacts', type: 'array', template: [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'phone', type: 'input', label: 'Phone' },\n] }\n```\n\n## Primitive Arrays\n\nFor simple arrays of scalar values like `['angular', 'typescript']`, provide a single field as the `template` and a flat array as the `value`:\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag', required: true },\n value: ['angular', 'typescript'],\n}\n```\n\nThis renders two input fields pre-filled with `'angular'` and `'typescript'`, each with an auto-generated **Remove** button. An **Add** button is placed after the array.\n\nForm value output:\n\n```typescript\n{\n tags: ['angular', 'typescript'];\n}\n```\n\n## Object Arrays\n\nFor arrays of objects like `[{ name: 'Jane', phone: '555' }]`, provide an array of fields as the `template` and an array of objects as the `value`:\n\n```typescript\n{\n key: 'contacts',\n type: 'array',\n template: [\n { key: 'name', type: 'input', label: 'Contact Name', required: true },\n { key: 'phone', type: 'input', label: 'Phone Number' },\n ],\n value: [\n { name: 'Jane', phone: '555-1234' },\n { name: 'Bob', phone: '555-5678' },\n ],\n}\n```\n\nEach value object is matched to the template by key. If a value object omits a key, the corresponding field renders without an initial value.\n\nForm value output:\n\n```typescript\n{\n contacts: [\n { name: 'Jane', phone: '555-1234' },\n { name: 'Bob', phone: '555-5678' },\n ];\n}\n```\n\n## Empty Arrays\n\nOmit `value` or set `value: []` to start with an empty array. Users populate it via the auto-generated **Add** button:\n\n```typescript\n// No value property \u2014 starts empty\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag' },\n}\n\n// Explicit empty array \u2014 same behavior\n{\n key: 'emails',\n type: 'array',\n template: [\n { key: 'address', type: 'input', label: 'Email Address', required: true },\n { key: 'label', type: 'select', label: 'Type', options: [\n { label: 'Work', value: 'work' },\n { label: 'Personal', value: 'personal' },\n ] },\n ],\n value: [],\n}\n```\n\n## Button Customization\n\nBy default, the library generates an **Add** button (label: `\"Add\"`) after the array and a **Remove** button (label: `\"Remove\"`) inside each item. You can customize both via `addButton` and `removeButton`:\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag' },\n value: ['angular'],\n addButton: { label: 'Add Tag', props: { color: 'primary' } },\n removeButton: { label: 'Delete', props: { color: 'warn' } },\n}\n```\n\n### Button Config Properties\n\n| Property | Type | Description |\n| -------- | ------------------------- | ---------------------------------------------------- |\n| `label` | `string` | Custom label text for the button |\n| `props` | `Record<string, unknown>` | Additional properties passed to the button component |\n\n## Button Opt-Out\n\nSet `addButton: false` or `removeButton: false` to suppress the corresponding auto-generated button entirely:\n\n```typescript\n// No add button \u2014 items are only removable, not addable\n{\n key: 'defaultTags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag' },\n value: ['featured', 'popular'],\n addButton: false,\n}\n\n// No remove button \u2014 items are only addable, not removable\n{\n key: 'skills',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Skill' },\n value: ['TypeScript'],\n removeButton: false,\n}\n\n// No buttons at all \u2014 static list rendered from initial values\n{\n key: 'readonlyItems',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Item' },\n value: ['A', 'B', 'C'],\n addButton: false,\n removeButton: false,\n}\n```\n\nWhen `removeButton: false` is set for a primitive array, each item renders as a plain field without being wrapped in a row. When set for an object array, the remove button is simply omitted from the item's field list.\n\n## Complete Example: Primitive Array\n\nA full working configuration for a tag list with custom buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig: FormConfig = {\n fields: [\n {\n key: 'projectName',\n type: 'input',\n label: 'Project Name',\n required: true,\n },\n {\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag', required: true, minLength: 2 },\n value: ['angular', 'open-source'],\n addButton: { label: 'Add Tag' },\n removeButton: { label: 'Remove Tag' },\n },\n ],\n};\n\n// Form value:\n// {\n// projectName: 'My Project',\n// tags: ['angular', 'open-source']\n// }\n```\n\n## Complete Example: Object Array\n\nA full working configuration for a contact list:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig: FormConfig = {\n fields: [\n {\n key: 'teamName',\n type: 'input',\n label: 'Team Name',\n required: true,\n },\n {\n key: 'members',\n type: 'array',\n template: [\n { key: 'name', type: 'input', label: 'Full Name', required: true },\n { key: 'email', type: 'input', label: 'Email', required: true },\n {\n key: 'role',\n type: 'select',\n label: 'Role',\n options: [\n { label: 'Developer', value: 'dev' },\n { label: 'Designer', value: 'design' },\n { label: 'Manager', value: 'manager' },\n ],\n },\n ],\n value: [\n { name: 'Alice', email: 'alice@example.com', role: 'dev' },\n { name: 'Bob', email: 'bob@example.com', role: 'design' },\n ],\n addButton: { label: 'Add Member' },\n removeButton: { label: 'Remove' },\n },\n ],\n};\n\n// Form value:\n// {\n// teamName: 'Frontend Team',\n// members: [\n// { name: 'Alice', email: 'alice@example.com', role: 'dev' },\n// { name: 'Bob', email: 'bob@example.com', role: 'design' },\n// ]\n// }\n```\n\n## Form Value Output\n\nThe simplified API produces the same form values as the complete API:\n\n| Template Shape | Value Shape | Output |\n| --------------- | --------------------- | ------------------------------------------------ |\n| Single field | Flat array of scalars | `{ tags: ['angular', 'typescript'] }` |\n| Array of fields | Array of objects | `{ contacts: [{ name: 'Jane', phone: '555' }] }` |\n| Any template | `[]` or omitted | `{ items: [] }` |\n\n## Array Size Validation\n\nUse `minLength` and `maxLength` to constrain the number of items. When violated, the form becomes invalid (e.g. submit button is disabled).\n\n```typescript\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag' },\n value: ['angular'],\n minLength: 1,\n maxLength: 5,\n}\n```\n\nBoth properties are optional and can be used independently or together.\n\n## Conditional Visibility\n\nSimplified arrays support `logic` for conditional visibility, just like the complete API:\n\n```typescript\n{\n key: 'extras',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Extra' },\n value: [],\n logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showExtras', operator: 'equals', value: false } }],\n}\n```\n\n## Decision Guide: Simplified vs Complete API\n\n| Scenario | Recommended API |\n| ----------------------------------------------- | --------------- |\n| Uniform items with standard add/remove | **Simplified** |\n| Pre-filled values from a data source | **Simplified** |\n| Custom button labels or styling | **Simplified** |\n| Empty array populated by users | **Simplified** |\n| Static list (no add/remove buttons) | **Simplified** |\n| Heterogeneous items (different fields per item) | Complete |\n| Custom button placement (buttons outside array) | Complete |\n| Programmatic control via EventBus | Complete |\n| Multiple add buttons (append, prepend, insert) | Complete |\n| Nested arrays inside item templates | Complete |\n\nAs a rule of thumb: **start with the simplified API**. If you hit a limitation, switch to the [complete API](/prebuilt/form-arrays/complete)."
135
171
  },
136
172
  {
137
173
  id: "form-groups",
138
174
  title: "Form Groups",
139
175
  category: "prebuilt",
140
- content: "Groups nest form fields under a single key in the form value. This creates logical grouping for form data, not visual grouping.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/group-field\" class=\"example-frame\" title=\"Group Field Demo\"></iframe>\n\n## Basic Group\n\n```typescript\n{\n type: 'group',\n key: 'address',\n fields: [\n { key: 'street', type: 'input', label: 'Street', value: '' },\n { key: 'city', type: 'input', label: 'City', value: '' },\n { key: 'zip', type: 'input', label: 'ZIP', value: '' },\n ],\n}\n```\n\nThis creates a nested structure in the form value:\n\n```typescript\n{\n address: {\n street: '',\n city: '',\n zip: ''\n }\n}\n```\n\nGroups are for organizing form **data**, not UI. The visual presentation depends on your UI integration (Material, Bootstrap, etc.).\n\n## Complete Example\n\nHere's a complete working example of a group field with validation:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-user-profile-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>`,\n})\nexport class UserProfileFormComponent {\n formConfig = {\n fields: [\n {\n key: 'name',\n type: 'input',\n label: 'Full Name',\n value: '',\n required: true,\n },\n {\n key: 'address',\n type: 'group',\n fields: [\n {\n key: 'street',\n type: 'input',\n label: 'Street Address',\n value: '',\n required: true,\n },\n {\n key: 'city',\n type: 'input',\n label: 'City',\n value: '',\n required: true,\n },\n {\n key: 'state',\n type: 'input',\n label: 'State',\n value: '',\n required: true,\n maxLength: 2,\n },\n {\n key: 'zip',\n type: 'input',\n label: 'ZIP Code',\n value: '',\n required: true,\n pattern: /^\\d{5}$/,\n },\n ],\n },\n ],\n };\n}\n```\n\nThis produces a form value with nested structure:\n\n```typescript\n{\n name: 'John Doe',\n address: {\n street: '123 Main St',\n city: 'Springfield',\n state: 'IL',\n zip: '62701'\n }\n}\n```\n\n## Nesting Restrictions\n\nGroup fields can be used within:\n\n- Pages (top-level container)\n- Rows (for horizontal layouts)\n- Array fields (for creating object arrays where each array item is an object)\n\nGroups **cannot** be nested inside:\n\n- Other group fields (no nested groups)\n\n## Allowed Children\n\nGroups can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts within the group)\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how groups affect type inference."
176
+ content: "Groups nest form fields under a single key in the form value. This creates logical grouping for form data, not visual grouping.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/group\" class=\"example-frame\" title=\"Group Field Demo\"></iframe>\n\n## Basic Group\n\n```typescript\n{\n type: 'group',\n key: 'address',\n fields: [\n { key: 'street', type: 'input', label: 'Street', value: '' },\n { key: 'city', type: 'input', label: 'City', value: '' },\n { key: 'zip', type: 'input', label: 'ZIP', value: '' },\n ],\n}\n```\n\nThis creates a nested structure in the form value:\n\n```typescript\n{\n address: {\n street: '',\n city: '',\n zip: ''\n }\n}\n```\n\nGroups are for organizing form **data**, not UI. The visual presentation depends on your UI integration (Material, Bootstrap, etc.).\n\n## Complete Example\n\nHere's a complete working example of a group field with validation:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-user-profile-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>`,\n})\nexport class UserProfileFormComponent {\n formConfig = {\n fields: [\n {\n key: 'name',\n type: 'input',\n label: 'Full Name',\n value: '',\n required: true,\n },\n {\n key: 'address',\n type: 'group',\n fields: [\n {\n key: 'street',\n type: 'input',\n label: 'Street Address',\n value: '',\n required: true,\n },\n {\n key: 'city',\n type: 'input',\n label: 'City',\n value: '',\n required: true,\n },\n {\n key: 'state',\n type: 'input',\n label: 'State',\n value: '',\n required: true,\n maxLength: 2,\n },\n {\n key: 'zip',\n type: 'input',\n label: 'ZIP Code',\n value: '',\n required: true,\n pattern: /^\\d{5}$/,\n },\n ],\n },\n ],\n };\n}\n```\n\nThis produces a form value with nested structure:\n\n```typescript\n{\n name: 'John Doe',\n address: {\n street: '123 Main St',\n city: 'Springfield',\n state: 'IL',\n zip: '62701'\n }\n}\n```\n\n## Nesting Restrictions\n\nGroup fields can be used within:\n\n- Pages (top-level container)\n- Rows (for horizontal layouts)\n- Array fields (for creating object arrays where each array item is an object)\n\nGroups **cannot** be nested inside:\n\n- Other group fields (no nested groups)\n\n## Allowed Children\n\nGroups can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts within the group)\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how groups affect type inference.\n\n## Conditional Visibility\n\nGroup containers support the `logic` property to conditionally show or hide the entire group (and all its nested fields) based on form state.\n\n```typescript\n{\n key: 'addressGroup',\n type: 'group',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'sameAsBilling',\n operator: 'equals',\n value: true,\n },\n }],\n fields: [\n { key: 'street', type: 'input', label: 'Street', value: '' },\n { key: 'city', type: 'input', label: 'City', value: '' },\n { key: 'zip', type: 'input', label: 'ZIP', value: '' },\n ],\n}\n```\n\nWhen the group is hidden, all its nested fields are hidden with it. Only `'hidden'` is supported as a logic type on containers (not `required`, `readonly`, or `disabled`).\n\nFor all available condition types and operators, see [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)."
141
177
  },
142
178
  {
143
179
  id: "form-pages",
144
180
  title: "Form Pages",
145
181
  category: "prebuilt",
146
- content: "Create multi-step forms by using page fields. When your form contains page fields, it automatically enters \"paged mode\" and renders with navigation controls.\n\n## Basic Multi-Step Form\n\nCreate a multi-step form by adding multiple page fields to your form configuration:\n\n```typescript\n{\n fields: [\n {\n key: 'account',\n type: 'page',\n fields: [\n { key: 'accountTitle', type: 'text', label: 'Account Information', props: { elementType: 'h3' } },\n { key: 'username', type: 'input', label: 'Username', value: '', required: true },\n { key: 'password', type: 'input', label: 'Password', value: '', props: { type: 'password' }, required: true },\n ],\n },\n {\n key: 'profile',\n type: 'page',\n fields: [\n { key: 'profileTitle', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n { key: 'firstName', type: 'input', label: 'First Name', value: '' },\n { key: 'lastName', type: 'input', label: 'Last Name', value: '' },\n ],\n },\n ],\n}\n```\n\n## Page Properties\n\nEach page field supports:\n\n- `key` (required) - Unique identifier for the page\n- `type: 'page'` (required) - Field type identifier\n- `fields` (required) - Array of child fields to render on this page\n\n## Page with Description\n\n```typescript\n{\n key: 'preferences',\n type: 'page',\n fields: [\n { key: 'newsletter', type: 'checkbox', label: 'Subscribe to newsletter', value: false },\n { key: 'notifications', type: 'checkbox', label: 'Enable notifications', value: false },\n ],\n}\n```\n\n## Paged Mode Behavior\n\nWhen your form contains page fields:\n\n- **Automatic Detection**: Form automatically enters \"paged mode\"\n- **Navigation Controls**: Previous/Next buttons are rendered automatically\n- **Validation**: Users must complete required fields before advancing to the next page\n- **Single Page View**: Only one page is visible at a time\n\n## Performance & Lazy Loading\n\nng-forge uses Angular's `@defer` blocks with smart prefetching to optimize page rendering while maintaining flicker-free navigation.\n\n### How It Works\n\nThe page orchestrator uses a **2-tier loading strategy**:\n\n**Tier 1: Current + Adjacent Pages (\xB11)**\n\n- Render immediately using `@defer (on immediate)`\n- Initially, only 3 pages load (current + 2 adjacent)\n- Adjacent pages are fully rendered but hidden with `display: none`\n- Ensures zero flicker when navigating forward/backward\n\n**Tier 2: Distant Pages (2+ steps away)**\n\n- Defer loading until browser is idle using `@defer (on idle)`\n- Lazy loading optimizes initial page load\n- Load automatically during browser idle time\n- Once loaded, pages remain in DOM (hidden with CSS)\n\n### Benefits\n\n```typescript\n// Example: User is on step 2 of 5\nfields: [\n { key: 'step1', type: 'page', ... }, // \u2713 Rendered (adjacent)\n { key: 'step2', type: 'page', ... }, // \u2713 Visible (current)\n { key: 'step3', type: 'page', ... }, // \u2713 Rendered (adjacent)\n { key: 'step4', type: 'page', ... }, // \u23F3 Deferred (distant)\n { key: 'step5', type: 'page', ... }, // \u23F3 Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- \u26A1 **Zero navigation flicker** - Adjacent pages already rendered\n- \u{1F680} **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- \u23F1\uFE0F **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- \u{1F4F1} **Mobile-friendly** - Lower startup cost on slower devices\n\n**Note:** Once loaded, pages remain in the DOM (hidden with CSS). The primary benefit is optimizing **initial load performance**, not ongoing memory usage.\n\nThis optimization happens automatically - no configuration needed.\n\n## Value Structure\n\nPages are container fields - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with pages\n{\n fields: [\n {\n key: 'page1',\n type: 'page',\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n ],\n },\n {\n key: 'page2',\n type: 'page',\n fields: [\n { key: 'lastName', type: 'input', value: '' },\n ],\n },\n ],\n}\n\n// Resulting form value (flat structure)\n{\n firstName: 'John',\n lastName: 'Doe',\n // Note: page keys are NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nPage fields can only be used at the top level of your form configuration. They **cannot** be nested inside:\n\n- Other page fields\n- Row fields\n- Group fields\n\nAttempting to nest pages will result in a validation error.\n\n## Allowed Children\n\nPages can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts)\n- Group fields (for nested data structures)\n\n## CSS Classes\n\nPage fields use these classes for styling:\n\n- `.df-page` - Applied to the page container\n- `.df-page-visible` - Applied to the currently visible page\n- `.df-page-hidden` - Applied to hidden pages\n- `.df-page-field` - Applied to the page field component"
182
+ content: "Create multi-step forms by using page fields. When your form contains page fields, it automatically enters \"paged mode\" and renders with navigation controls.\n\n## Basic Multi-Step Form\n\nCreate a multi-step form by adding multiple page fields to your form configuration:\n\n```typescript\n{\n fields: [\n {\n key: 'account',\n type: 'page',\n fields: [\n { key: 'accountTitle', type: 'text', label: 'Account Information', props: { elementType: 'h3' } },\n { key: 'username', type: 'input', label: 'Username', value: '', required: true },\n { key: 'password', type: 'input', label: 'Password', value: '', props: { type: 'password' }, required: true },\n ],\n },\n {\n key: 'profile',\n type: 'page',\n fields: [\n { key: 'profileTitle', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n { key: 'firstName', type: 'input', label: 'First Name', value: '' },\n { key: 'lastName', type: 'input', label: 'Last Name', value: '' },\n ],\n },\n ],\n}\n```\n\n## Page Properties\n\nEach page field supports:\n\n- `key` (required) - Unique identifier for the page\n- `type: 'page'` (required) - Field type identifier\n- `fields` (required) - Array of child fields to render on this page\n\n## Page with Description\n\n```typescript\n{\n key: 'preferences',\n type: 'page',\n fields: [\n { key: 'newsletter', type: 'checkbox', label: 'Subscribe to newsletter', value: false },\n { key: 'notifications', type: 'checkbox', label: 'Enable notifications', value: false },\n ],\n}\n```\n\n## Paged Mode Behavior\n\nWhen your form contains page fields:\n\n- **Automatic Detection**: Form automatically enters \"paged mode\"\n- **Navigation Controls**: Previous/Next buttons are rendered automatically\n- **Validation**: Users must complete required fields before advancing to the next page\n- **Single Page View**: Only one page is visible at a time\n\n## Performance & Lazy Loading\n\nng-forge uses Angular's `@defer` blocks with smart prefetching to optimize page rendering while maintaining flicker-free navigation.\n\n### How It Works\n\nThe page orchestrator uses a **2-tier loading strategy**:\n\n**Tier 1: Current + Adjacent Pages (\xB11)**\n\n- Render immediately using `@defer (on immediate)`\n- Initially, only 3 pages load (current + 2 adjacent)\n- Adjacent pages are fully rendered but hidden with `display: none`\n- Ensures zero flicker when navigating forward/backward\n\n**Tier 2: Distant Pages (2+ steps away)**\n\n- Defer loading until browser is idle using `@defer (on idle)`\n- Lazy loading optimizes initial page load\n- Load automatically during browser idle time\n- Once loaded, pages remain in DOM (hidden with CSS)\n\n### Benefits\n\n```typescript\n// Example: User is on step 2 of 5\nfields: [\n { key: 'step1', type: 'page', ... }, // \u2713 Rendered (adjacent)\n { key: 'step2', type: 'page', ... }, // \u2713 Visible (current)\n { key: 'step3', type: 'page', ... }, // \u2713 Rendered (adjacent)\n { key: 'step4', type: 'page', ... }, // \u23F3 Deferred (distant)\n { key: 'step5', type: 'page', ... }, // \u23F3 Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- \u26A1 **Zero navigation flicker** - Adjacent pages already rendered\n- \u{1F680} **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- \u23F1\uFE0F **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- \u{1F4F1} **Mobile-friendly** - Lower startup cost on slower devices\n\n**Note:** Once loaded, pages remain in the DOM (hidden with CSS). The primary benefit is optimizing **initial load performance**, not ongoing memory usage.\n\nThis optimization happens automatically - no configuration needed.\n\n## Value Structure\n\nPages are container fields - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with pages\n{\n fields: [\n {\n key: 'page1',\n type: 'page',\n fields: [\n { key: 'firstName', type: 'input', value: '' },\n ],\n },\n {\n key: 'page2',\n type: 'page',\n fields: [\n { key: 'lastName', type: 'input', value: '' },\n ],\n },\n ],\n}\n\n// Resulting form value (flat structure)\n{\n firstName: 'John',\n lastName: 'Doe',\n // Note: page keys are NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nPage fields can only be used at the top level of your form configuration. They **cannot** be nested inside:\n\n- Other page fields\n- Row fields\n- Group fields\n\nAttempting to nest pages will result in a validation error.\n\n## Allowed Children\n\nPages can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts)\n- Group fields (for nested data structures)\n\n## Conditional Visibility\n\nPages support the `logic` property to conditionally skip a page (hide it from the page navigation and progression) based on form state.\n\n```typescript\n{\n key: 'businessDetails',\n type: 'page',\n label: 'Business Details',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'notEquals',\n value: 'business',\n },\n }],\n fields: [\n { key: 'companyName', type: 'input', label: 'Company Name', value: '' },\n { key: 'taxId', type: 'input', label: 'Tax ID', value: '' },\n ],\n}\n```\n\nWhen a page is hidden, it is excluded from the multi-step navigation \u2014 users skip directly past it. Only `'hidden'` is supported as a logic type on containers.\n\nFor all available condition types and operators, see [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/).\n\n## CSS Classes\n\nPage fields use these classes for styling:\n\n- `.df-page` - Applied to the page container\n- `.df-page-visible` - Applied to the currently visible page\n- `.df-page-hidden` - Applied to hidden pages\n- `.df-page-field` - Applied to the page field component"
147
183
  },
148
184
  {
149
185
  id: "form-rows",
150
186
  title: "Form Rows",
151
187
  category: "prebuilt",
152
- content: "Organize fields into horizontal rows for compact layouts. Rows display fields side-by-side.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/row-field\" class=\"example-frame\" title=\"Row Field Demo\"></iframe>\n\n## Basic Row\n\n```typescript\n{\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', label: 'First Name', value: '', col: 6 },\n { key: 'lastName', type: 'input', label: 'Last Name', value: '', col: 6 },\n ],\n}\n```\n\nRows flatten their children - they don't add nesting to form values. Use the `col` property to control field widths (see Column Sizing below).\n\n## Column Sizing\n\nControl field widths within rows using the `col` property:\n\n```typescript\n{\n type: 'row',\n fields: [\n { key: 'city', type: 'input', label: 'City', value: '', col: 6 },\n { key: 'state', type: 'select', label: 'State', value: '', col: 3 },\n { key: 'zip', type: 'input', label: 'ZIP', value: '', col: 3 },\n ],\n}\n```\n\nThe `col` property uses a 12-column grid system (like Bootstrap). In this example:\n\n- `city` takes 6/12 (50%) width\n- `state` takes 3/12 (25%) width\n- `zip` takes 3/12 (25%) width\n\n## Responsive Behavior\n\nRows automatically stack on small screens, making forms mobile-friendly without additional configuration.\n\n## Complete Example\n\nHere's a complete working example of a row field with multiple fields:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-address-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>\n >`,\n})\nexport class AddressFormComponent {\n formConfig = {\n fields: [\n {\n type: 'row',\n fields: [\n {\n key: 'firstName',\n type: 'input',\n label: 'First Name',\n value: '',\n required: true,\n col: 6,\n },\n {\n key: 'lastName',\n type: 'input',\n label: 'Last Name',\n value: '',\n required: true,\n col: 6,\n },\n ],\n },\n {\n key: 'email',\n type: 'input',\n label: 'Email Address',\n value: '',\n required: true,\n email: true,\n },\n {\n type: 'row',\n fields: [\n {\n key: 'city',\n type: 'input',\n label: 'City',\n value: '',\n required: true,\n col: 6,\n },\n {\n key: 'state',\n type: 'input',\n label: 'State',\n value: '',\n required: true,\n maxLength: 2,\n col: 3,\n },\n {\n key: 'zip',\n type: 'input',\n label: 'ZIP',\n value: '',\n required: true,\n pattern: /^\\d{5}$/,\n col: 3,\n },\n ],\n },\n ],\n };\n}\n```\n\nThis produces a flat form value (rows don't create nesting):\n\n```typescript\n{\n firstName: 'John',\n lastName: 'Doe',\n email: 'john.doe@example.com',\n city: 'Springfield',\n state: 'IL',\n zip: '62701'\n}\n```\n\n## Value Structure\n\nRows are layout containers - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with rows\n{\n fields: [\n {\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', value: '', col: 6 },\n { key: 'lastName', type: 'input', value: '', col: 6 },\n ],\n },\n ];\n}\n\n// Resulting form value (flat structure)\n{\n firstName: 'John',\n lastName: 'Doe',\n // Note: row itself is NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nRow fields can be used within:\n\n- Pages (top-level container)\n- Groups (for layouts within grouped data)\n- Arrays (for layouts within array items)\n\nRows **cannot** be nested inside:\n\n- Other row fields\n\n## Allowed Children\n\nRows can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Group fields (for nested data structures within the row)\n- Array fields (for repeating sections within the row)"
188
+ content: "Organize fields into horizontal rows for compact layouts. Rows display fields side-by-side.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/row\" class=\"example-frame\" title=\"Row Field Demo\"></iframe>\n\n## Basic Row\n\n```typescript\n{\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', label: 'First Name', value: '', col: 6 },\n { key: 'lastName', type: 'input', label: 'Last Name', value: '', col: 6 },\n ],\n}\n```\n\nRows flatten their children - they don't add nesting to form values. Use the `col` property to control field widths (see Column Sizing below).\n\n## Column Sizing\n\nControl field widths within rows using the `col` property:\n\n```typescript\n{\n type: 'row',\n fields: [\n { key: 'city', type: 'input', label: 'City', value: '', col: 6 },\n { key: 'state', type: 'select', label: 'State', value: '', col: 3 },\n { key: 'zip', type: 'input', label: 'ZIP', value: '', col: 3 },\n ],\n}\n```\n\nThe `col` property uses a 12-column grid system (like Bootstrap). In this example:\n\n- `city` takes 6/12 (50%) width\n- `state` takes 3/12 (25%) width\n- `zip` takes 3/12 (25%) width\n\n## Responsive Behavior\n\nRows automatically stack on small screens, making forms mobile-friendly without additional configuration.\n\n## Complete Example\n\nHere's a complete working example of a row field with multiple fields:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-address-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>\n >`,\n})\nexport class AddressFormComponent {\n formConfig = {\n fields: [\n {\n type: 'row',\n fields: [\n {\n key: 'firstName',\n type: 'input',\n label: 'First Name',\n value: '',\n required: true,\n col: 6,\n },\n {\n key: 'lastName',\n type: 'input',\n label: 'Last Name',\n value: '',\n required: true,\n col: 6,\n },\n ],\n },\n {\n key: 'email',\n type: 'input',\n label: 'Email Address',\n value: '',\n required: true,\n email: true,\n },\n {\n type: 'row',\n fields: [\n {\n key: 'city',\n type: 'input',\n label: 'City',\n value: '',\n required: true,\n col: 6,\n },\n {\n key: 'state',\n type: 'input',\n label: 'State',\n value: '',\n required: true,\n maxLength: 2,\n col: 3,\n },\n {\n key: 'zip',\n type: 'input',\n label: 'ZIP',\n value: '',\n required: true,\n pattern: /^\\d{5}$/,\n col: 3,\n },\n ],\n },\n ],\n };\n}\n```\n\nThis produces a flat form value (rows don't create nesting):\n\n```typescript\n{\n firstName: 'John',\n lastName: 'Doe',\n email: 'john.doe@example.com',\n city: 'Springfield',\n state: 'IL',\n zip: '62701'\n}\n```\n\n## Value Structure\n\nRows are layout containers - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with rows\n{\n fields: [\n {\n type: 'row',\n fields: [\n { key: 'firstName', type: 'input', value: '', col: 6 },\n { key: 'lastName', type: 'input', value: '', col: 6 },\n ],\n },\n ];\n}\n\n// Resulting form value (flat structure)\n{\n firstName: 'John',\n lastName: 'Doe',\n // Note: row itself is NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nRow fields can be used within:\n\n- Pages (top-level container)\n- Groups (for layouts within grouped data)\n- Arrays (for layouts within array items)\n\nRows **cannot** be nested inside:\n\n- Other row fields\n\n## Allowed Children\n\nRows can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Group fields (for nested data structures within the row)\n- Array fields (for repeating sections within the row)\n\n## Conditional Visibility\n\nRow containers support the `logic` property to conditionally show or hide the entire row (and all its fields) based on form state.\n\n```typescript\n{\n key: 'contactRow',\n type: 'row',\n logic: [{\n type: 'hidden',\n condition: {\n type: 'fieldValue',\n fieldPath: 'contactPreference',\n operator: 'equals',\n value: 'none',\n },\n }],\n fields: [\n { key: 'phone', type: 'input', label: 'Phone', col: 6 },\n { key: 'email', type: 'input', label: 'Email', col: 6 },\n ],\n}\n```\n\nOnly `'hidden'` is supported as a logic type on containers. For all available condition types and operators, see [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)."
153
189
  },
154
190
  {
155
191
  id: "hidden-fields",
156
192
  title: "Hidden Fields",
157
193
  category: "prebuilt",
158
- content: "Hidden fields store values in the form model without rendering any visible UI. They're useful for persisting IDs, metadata, or other non-user-facing data.\n\n## Basic Usage\n\n```typescript\n{\n type: 'hidden',\n key: 'id',\n value: 'uuid-550e8400-e29b-41d4-a716-446655440000',\n}\n```\n\nThis adds `id` to the form value without rendering anything:\n\n```typescript\n{\n id: 'uuid-550e8400-e29b-41d4-a716-446655440000',\n // ... other fields\n}\n```\n\n## Supported Value Types\n\nHidden fields support scalar values and arrays of scalars:\n\n```typescript\n// String\n{ type: 'hidden', key: 'sessionId', value: 'abc123' }\n\n// Number\n{ type: 'hidden', key: 'version', value: 42 }\n\n// Boolean\n{ type: 'hidden', key: 'isActive', value: true }\n\n// String array\n{ type: 'hidden', key: 'tags', value: ['draft', 'review'] }\n\n// Number array\n{ type: 'hidden', key: 'tagIds', value: [1, 2, 3] }\n\n// Boolean array\n{ type: 'hidden', key: 'flags', value: [true, false, true] }\n```\n\n## Complete Example\n\nHere's a form that uses hidden fields to persist metadata during an update operation:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-edit-user-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>`,\n})\nexport class EditUserFormComponent {\n formConfig = {\n fields: [\n // Hidden fields for metadata\n {\n type: 'hidden',\n key: 'id',\n value: 'user-123',\n },\n {\n type: 'hidden',\n key: 'version',\n value: 3,\n },\n {\n type: 'hidden',\n key: 'roles',\n value: ['admin', 'editor'],\n },\n // Visible fields\n {\n key: 'name',\n type: 'input',\n label: 'Full Name',\n value: 'John Doe',\n required: true,\n },\n {\n key: 'email',\n type: 'input',\n label: 'Email',\n value: 'john@example.com',\n required: true,\n props: { type: 'email' },\n },\n {\n key: 'submit',\n type: 'submit',\n label: 'Save Changes',\n },\n ],\n };\n}\n```\n\nForm value on submission:\n\n```typescript\n{\n id: 'user-123',\n version: 3,\n roles: ['admin', 'editor'],\n name: 'John Doe',\n email: 'john@example.com'\n}\n```\n\n## Use Cases\n\n- Persisting record IDs for update operations\n- Tracking version numbers for optimistic concurrency\n- Passing context data (parent IDs, source references)\n- Storing computed values that shouldn't be user-editable\n- Including metadata in form submissions\n\n## Placement\n\nHidden fields can be placed:\n\n- At the top level of a form\n- Inside page fields\n- Inside group fields\n\n**Note:** Placing hidden fields inside row fields will generate a validation warning. Rows are meant for horizontal layouts, and since hidden fields don't render anything, placing them in rows serves no purpose. Place hidden fields outside of rows instead.\n\n## Type Safety\n\nHidden fields are fully type-safe:\n\n```typescript\nimport { HiddenField } from '@ng-forge/dynamic-forms';\n\n// Typed hidden field\nconst idField: HiddenField<string> = {\n type: 'hidden',\n key: 'id',\n value: 'abc123',\n};\n\n// Array type\nconst tagsField: HiddenField<number[]> = {\n type: 'hidden',\n key: 'tagIds',\n value: [1, 2, 3],\n};\n```\n\nUse the `isHiddenField` type guard to check field types at runtime:\n\n```typescript\nimport { isHiddenField } from '@ng-forge/dynamic-forms';\n\nif (isHiddenField(field)) {\n console.log(field.value); // Type-safe access to value\n}\n```\n\n## Technical Details\n\n- **Componentless**: Hidden fields have no Angular component and render zero DOM elements\n- **Value handling**: Uses `valueHandling: 'include'`, so values are always included in form submissions\n- **Required value**: The `value` property is required (unlike most field types where it's optional)"
194
+ content: "Hidden fields store values in the form model without rendering any visible UI. They're useful for persisting IDs, metadata, or other non-user-facing data.\n\n## Basic Usage\n\n```typescript\n{\n type: 'hidden',\n key: 'id',\n value: 'uuid-550e8400-e29b-41d4-a716-446655440000',\n}\n```\n\nThis adds `id` to the form value without rendering anything:\n\n```typescript\n{\n id: 'uuid-550e8400-e29b-41d4-a716-446655440000',\n // ... other fields\n}\n```\n\n## Supported Value Types\n\nHidden fields support scalar values and arrays of scalars:\n\n```typescript\n// String\n{ type: 'hidden', key: 'sessionId', value: 'abc123' }\n\n// Number\n{ type: 'hidden', key: 'version', value: 42 }\n\n// Boolean\n{ type: 'hidden', key: 'isActive', value: true }\n\n// String array\n{ type: 'hidden', key: 'tags', value: ['draft', 'review'] }\n\n// Number array\n{ type: 'hidden', key: 'tagIds', value: [1, 2, 3] }\n\n// Boolean array\n{ type: 'hidden', key: 'flags', value: [true, false, true] }\n```\n\n## Complete Example\n\nHere's a form that uses hidden fields to persist metadata during an update operation:\n\n```typescript\nimport { Component } from '@angular/core';\nimport { DynamicForm } from '@ng-forge/dynamic-forms';\n\n@Component({\n selector: 'app-edit-user-form',\n imports: [DynamicForm],\n template: `<form [dynamic-form]=\"formConfig\"></form>`,\n})\nexport class EditUserFormComponent {\n formConfig = {\n fields: [\n // Hidden fields for metadata\n {\n type: 'hidden',\n key: 'id',\n value: 'user-123',\n },\n {\n type: 'hidden',\n key: 'version',\n value: 3,\n },\n {\n type: 'hidden',\n key: 'roles',\n value: ['admin', 'editor'],\n },\n // Visible fields\n {\n key: 'name',\n type: 'input',\n label: 'Full Name',\n value: 'John Doe',\n required: true,\n },\n {\n key: 'email',\n type: 'input',\n label: 'Email',\n value: 'john@example.com',\n required: true,\n props: { type: 'email' },\n },\n {\n key: 'submit',\n type: 'submit',\n label: 'Save Changes',\n },\n ],\n };\n}\n```\n\nForm value on submission:\n\n```typescript\n{\n id: 'user-123',\n version: 3,\n roles: ['admin', 'editor'],\n name: 'John Doe',\n email: 'john@example.com'\n}\n```\n\n## Use Cases\n\n- Persisting record IDs for update operations\n- Tracking version numbers for optimistic concurrency\n- Passing context data (parent IDs, source references)\n- Storing computed values that shouldn't be user-editable\n- Including metadata in form submissions\n\n## Placement\n\nHidden fields can be placed:\n\n- At the top level of a form\n- Inside page fields\n- Inside group fields\n\n**Note:** Placing hidden fields inside row fields will generate a validation warning. Rows are meant for horizontal layouts, and since hidden fields don't render anything, placing them in rows serves no purpose. Place hidden fields outside of rows instead.\n\n## Type Safety\n\nHidden fields are fully type-safe:\n\n```typescript\nimport { HiddenField } from '@ng-forge/dynamic-forms';\n\n// Typed hidden field\nconst idField: HiddenField<string> = {\n type: 'hidden',\n key: 'id',\n value: 'abc123',\n};\n\n// Array type\nconst tagsField: HiddenField<number[]> = {\n type: 'hidden',\n key: 'tagIds',\n value: [1, 2, 3],\n};\n```\n\nUse the `isHiddenField` type guard to check field types at runtime:\n\n```typescript\nimport { isHiddenField } from '@ng-forge/dynamic-forms';\n\nif (isHiddenField(field)) {\n console.log(field.value); // Type-safe access to value\n}\n```\n\n## Value Exclusion\n\nThe `HiddenField` type (`type: 'hidden'`) is **not affected** by value exclusion. Hidden fields:\n\n- Have no reactive `hidden()` state (they don't render a component)\n- Are always included in submission output, regardless of `excludeValueIfHidden` settings\n\nThis is different from regular fields with `hidden: true` or fields hidden via conditional logic. Those fields have a reactive `hidden()` state that value exclusion checks.\n\nSee the **Value Exclusion** page under Recipes for full details.\n\n## Technical Details\n\n- **Componentless**: Hidden fields have no Angular component and render zero DOM elements\n- **Value handling**: Uses `valueHandling: 'include'`, so values are always included in form submissions\n- **Required value**: The `value` property is required (unlike most field types where it's optional)"
159
195
  },
160
196
  {
161
197
  id: "text-components",
@@ -227,13 +263,13 @@ var require_docs = __commonJS({
227
263
  id: "validation-custom-validators",
228
264
  title: "Validation Custom Validators",
229
265
  category: "validation",
230
- content: "Custom validation functions for complex validation logic that goes beyond built-in validators.\n\n## Overview\n\nng-forge supports three types of custom validators using Angular's Signal Forms API:\n\n1. **CustomValidator** - Synchronous validators with access to FieldContext\n2. **AsyncCustomValidator** - Async validators using Angular's resource API\n3. **HttpCustomValidator** - HTTP-specific validators with automatic request cancellation\n\n**Key Principle:** Validators should focus on validation logic, NOT presentation. Return only the error `kind` and configure messages at field level for proper i18n support.\n\n## Live Demo\n\nTry the interactive example below to see both expression-based and function-based validators in action:\n\n<iframe src=\"http://localhost:4201/#/examples/expression-validators\" class=\"example-frame\" title=\"Expression Validators Demo\"></iframe>\n\n## Message Resolution (STRICT)\n\nAll error messages MUST be explicitly configured. The framework enforces this strictly:\n\n1. **Field-level `validationMessages[kind]`** (highest priority - per-field customization)\n2. **Form-level `defaultValidationMessages[kind]`** (fallback for common messages)\n3. **No message configured = Console warning + error NOT displayed**\n\n**Important:** Validator-returned messages are NOT used as fallbacks. This enforces proper separation of concerns and i18n patterns.\n\nYou can define messages at the form level for common validation errors:\n\n```typescript\n{\n defaultValidationMessages: {\n noSpaces: 'Spaces are not allowed',\n passwordMismatch: 'Passwords must match'\n },\n fields: [/* ... */]\n}\n```\n\n## Two Validator Patterns\n\nng-forge supports two patterns for custom validators:\n\n1. **Function-based** - Register reusable validator functions (best for complex logic, reusability)\n2. **Expression-based** - Inline JavaScript expressions (best for simple, one-off validations)\n\n## Expression-Based Validators\n\nFor simple validation logic, use inline JavaScript expressions without registering functions.\n\n### Basic Example\n\n```typescript\n{\n key: 'confirmPassword',\n type: 'input',\n value: '',\n validators: [{\n type: 'custom',\n expression: 'fieldValue === formValue.password',\n kind: 'passwordMismatch',\n }],\n validationMessages: {\n passwordMismatch: 'Passwords must match',\n },\n}\n```\n\n**How it works:**\n\n- `fieldValue` - Current field's value\n- `formValue` - Entire form value object\n- Expression returns `true` = validation passes\n- Expression returns `false` = validation fails with the specified `kind`\n\n### Available Context\n\nExpression-based validators have access to:\n\n- **`fieldValue`** - Current field value\n- **`formValue`** - Complete form value object (e.g., `formValue.password`, `formValue.email`)\n- **`fieldPath`** - Current field path\n- Custom functions registered in `customFnConfig.customFunctions`\n\n### Safe Member Access\n\n**Built-in null/undefined handling**: Member access is safe by default - no manual null checks needed!\n\n```typescript\n// \u2705 Works safely even when nested values are null/undefined\n{\n expression: 'fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// \u274C Unnecessary - Don't do this\n{\n expression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// \u2705 Better - Safe by default\n{\n expression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n```\n\nAccessing properties on `null` or `undefined` returns `undefined` instead of throwing errors, making expressions cleaner and more maintainable.\n\n### Common Expression Patterns\n\n**Password confirmation:**\n\n```typescript\n{\n expression: 'fieldValue === formValue.password',\n kind: 'passwordMismatch',\n}\n```\n\n**Date range validation:**\n\n```typescript\n{\n expression: 'new Date(fieldValue) > new Date(formValue.startDate)',\n kind: 'endDateBeforeStart',\n}\n```\n\n**Conditional required:**\n\n```typescript\n{\n expression: 'formValue.requiresApproval ? fieldValue?.length > 0 : true',\n kind: 'approvalRequired',\n}\n```\n\n**Numeric comparison:**\n\n```typescript\n{\n expression: 'fieldValue >= formValue.minAge && fieldValue <= formValue.maxAge',\n kind: 'ageOutOfRange',\n}\n```\n\n**Deeply nested field validation:**\n\n```typescript\n{\n // Safe to access deeply nested properties\n expression: 'fieldValue.toLowerCase() !== formValue.user.address.city.toLowerCase()',\n kind: 'invalidAddress',\n}\n```\n\n### Security\n\nExpressions use **secure AST-based parsing** - no `eval()` or `new Function()`. Only safe JavaScript operations are allowed.\n\n## Function-Based Validators\n\nBest for validation that needs field value and access to other fields via FieldContext.\n\n### Basic Example\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\n// \u2705 RECOMMENDED: Return only kind\nconst noSpaces: CustomValidator = (ctx) => {\n const value = ctx.value();\n if (typeof value === 'string' && value.includes(' ')) {\n return { kind: 'noSpaces' }; // No hardcoded message\n }\n return null;\n};\n\n// Register and configure message\nconst config = {\n fields: [\n {\n key: 'username',\n type: 'input',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: 'Spaces are not allowed', // Or Observable/Signal for i18n\n },\n },\n ],\n customFnConfig: {\n validators: {\n noSpaces,\n },\n },\n};\n```\n\n### FieldContext API\n\nThe `FieldContext` API provides access to:\n\n- **`ctx.value()`** - Current field value (signal)\n- **`ctx.state`** - Field state (errors, touched, dirty, etc.)\n- **`ctx.valueOf(path)`** - Access other field values (PUBLIC API for cross-field validation)\n- **`ctx.stateOf(path)`** - Access other field states\n- **`ctx.field`** - Current field tree\n\n### Cross-Field Validation\n\nUse `ctx.valueOf()` to access other field values for comparison validators:\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\nconst greaterThanMin: CustomValidator = (ctx) => {\n const value = ctx.value();\n const minValue = ctx.valueOf('minAge');\n\n if (minValue !== undefined && value <= minValue) {\n return { kind: 'notGreaterThanMin' };\n }\n return null;\n};\n\n// Note: Custom validators return only 'kind'. Built-in validators (min, max, etc.)\n// automatically include params for interpolation (e.g., {{min}}, {{max}}, etc.)\nconst config = {\n fields: [\n { key: 'minAge', type: 'input', value: 0 },\n {\n key: 'maxAge',\n type: 'input',\n value: 0,\n validators: [\n {\n type: 'custom',\n functionName: 'greaterThanMin',\n },\n ],\n validationMessages: {\n notGreaterThanMin: 'Maximum age must be greater than minimum age',\n },\n },\n ],\n customFnConfig: {\n validators: { greaterThanMin },\n },\n};\n```\n\n**Common Cross-Field Patterns:**\n\n- Password confirmation matching\n- Date range validation (start < end)\n- Numeric range validation (min < max)\n- Conditional required fields\n\n### Password Confirmation Example\n\n```typescript\nconst passwordMatch: CustomValidator = (ctx) => {\n const confirmPassword = ctx.value();\n const password = ctx.valueOf('password');\n\n if (!confirmPassword || !password) {\n return null; // Let required validator handle empty case\n }\n\n if (password !== confirmPassword) {\n return { kind: 'passwordMismatch' };\n }\n return null;\n};\n\n// In field config:\n{\n key: 'confirmPassword',\n type: 'input',\n validators: [{ type: 'custom', functionName: 'passwordMatch' }],\n validationMessages: {\n passwordMismatch: 'Passwords do not match'\n }\n}\n```\n\n## Async Validators (Resource-based)\n\nAsync validators use Angular's resource API for database lookups or complex async operations.\n\n### Basic Example\n\n```typescript\nimport { AsyncCustomValidator } from '@ng-forge/dynamic-forms';\nimport { inject } from '@angular/core';\nimport { rxResource } from '@angular/core/rxjs-interop';\nimport { of } from 'rxjs';\nimport { UserService } from './user.service';\n\nconst checkUsernameAvailable: AsyncCustomValidator = {\n // Extract params from field context\n params: (ctx) => ({ username: ctx.value() }),\n\n // Create resource with params signal\n factory: (params) => {\n const userService = inject(UserService);\n return rxResource({\n request: params,\n loader: ({ request }) => {\n if (!request?.username) return of(null);\n return userService.checkAvailability(request.username);\n },\n });\n },\n\n // Map result to validation error\n onSuccess: (result, ctx) => {\n if (!result) return null;\n return result.available ? null : { kind: 'usernameTaken' };\n },\n\n // Handle errors gracefully\n onError: (error, ctx) => {\n console.error('Availability check failed:', error);\n return null; // Don't block form on network errors\n },\n};\n\nconst config = {\n fields: [\n {\n key: 'username',\n type: 'input',\n validators: [{ type: 'customAsync', functionName: 'checkUsernameAvailable' }],\n validationMessages: {\n usernameTaken: 'This username is already taken',\n },\n },\n ],\n customFnConfig: {\n asyncValidators: {\n checkUsernameAvailable,\n },\n },\n};\n```\n\n**Key Benefits:**\n\n- Automatic loading states via resource API\n- Angular manages resource lifecycle\n- Reactive - refetches when params change\n- Integrates with Signal Forms validation state\n\n### Structure\n\n```typescript\ninterface AsyncCustomValidator<TValue, TParams, TResult> {\n // Function that receives field context and returns resource params\n readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;\n\n // Function that creates a ResourceRef from the params signal\n readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;\n\n // Map successful resource result to validation errors\n readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n // Handle resource errors\n readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n```\n\n## HTTP Validators\n\nHTTP validators provide optimized HTTP validation with automatic request cancellation.\n\n### Basic Example\n\n```typescript\nimport { HttpCustomValidator } from '@ng-forge/dynamic-forms';\n\nconst checkEmailDomain: HttpCustomValidator = {\n // Build HTTP request from context\n request: (ctx) => {\n const email = ctx.value();\n if (!email?.includes('@')) return undefined; // Skip if invalid\n\n const domain = email.split('@')[1];\n return {\n url: `/api/validate-domain`,\n method: 'POST',\n body: { domain },\n headers: { 'Content-Type': 'application/json' },\n };\n },\n\n // NOTE: Inverted logic - onSuccess checks if response indicates INVALID\n // We're validating, not fetching data!\n onSuccess: (response, ctx) => {\n // Assuming API returns { valid: boolean }\n return response.valid ? null : { kind: 'invalidDomain' };\n },\n\n onError: (error, ctx) => {\n console.error('Domain validation failed:', error);\n return null; // Don't block form on network errors\n },\n};\n\nconst config = {\n fields: [\n {\n key: 'email',\n type: 'input',\n validators: [{ type: 'customHttp', functionName: 'checkEmailDomain' }],\n validationMessages: {\n invalidDomain: 'This email domain is not allowed',\n },\n },\n ],\n customFnConfig: {\n httpValidators: {\n checkEmailDomain,\n },\n },\n};\n```\n\n**Key Benefits:**\n\n- Automatic request cancellation when field changes\n- Built-in debouncing via resource API\n- Prevents race conditions\n- Optimized for HTTP-specific validation\n\n**Important:** HTTP validators use \"inverted logic\" - `onSuccess` should return an error if validation fails, not if the HTTP request succeeds. You're checking validation status, not fetching data.\n\n### Structure\n\n```typescript\ninterface HttpCustomValidator<TValue, TResult> {\n // Build HTTP request from field context\n readonly request: (ctx: FieldContext<TValue>) => HttpResourceRequest | string | undefined;\n\n // Map successful response to validation error\n readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n // Handle HTTP errors\n readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n\ninterface HttpResourceRequest {\n url: string;\n method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n body?: any;\n headers?: Record<string, string | string[]>;\n}\n```\n\n## Conditional Custom Validators\n\nApply validators conditionally using the `when` property with a `ConditionalExpression`:\n\n```typescript\nconst businessEmailValidator: CustomValidator = (ctx) => {\n const value = ctx.value();\n const domain = value?.split('@')[1];\n\n const freeEmailDomains = ['gmail.com', 'yahoo.com', 'hotmail.com'];\n\n if (domain && freeEmailDomains.includes(domain.toLowerCase())) {\n return { kind: 'requireBusinessEmail' };\n }\n return null;\n};\n\nconst config = {\n fields: [\n {\n key: 'accountType',\n type: 'select',\n value: 'personal',\n options: [\n { value: 'personal', label: 'Personal' },\n { value: 'business', label: 'Business' },\n ],\n },\n {\n key: 'email',\n type: 'input',\n validators: [\n {\n type: 'custom',\n functionName: 'businessEmailValidator',\n // Only apply when account type is \"business\"\n when: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n },\n ],\n validationMessages: {\n requireBusinessEmail: 'Please use a business email address',\n },\n },\n ],\n customFnConfig: {\n validators: { businessEmailValidator },\n },\n};\n```\n\nThe validator is only active when the `when` condition evaluates to `true`, allowing dynamic validation based on form state. See [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/) for all expression types and operators.\n\n## Common Validation Patterns\n\n### Email Domain Validation\n\n```typescript\nconst emailDomainValidator: CustomValidator = (ctx) => {\n const blockedDomains = ['tempmail.com', 'throwaway.email'];\n const email = ctx.value();\n const domain = email?.split('@')[1];\n\n if (domain && blockedDomains.includes(domain)) {\n return { kind: 'blockedDomain' };\n }\n return null;\n};\n```\n\n### Age Validation\n\n```typescript\nconst ageValidator: CustomValidator = (ctx) => {\n const birthDate = ctx.value();\n const age = calculateAge(birthDate);\n\n if (age < 18) {\n return { kind: 'tooYoung' };\n }\n return null;\n};\n```\n\n### Conditional Required\n\n```typescript\nconst conditionalRequiredValidator: CustomValidator = (ctx) => {\n const value = ctx.value();\n const employmentStatus = ctx.valueOf('employmentStatus');\n\n // Company name required if employed\n if (employmentStatus === 'employed' && !value) {\n return { kind: 'required' };\n }\n return null;\n};\n```\n\n### Date Range Validation\n\n```typescript\nconst dateRangeValidator: CustomValidator = (ctx) => {\n const endDate = ctx.value();\n const startDate = ctx.valueOf('startDate');\n\n if (startDate && endDate && startDate > endDate) {\n return { kind: 'invalidDateRange' };\n }\n return null;\n};\n```\n\n## Multiple Errors\n\nValidators can return multiple errors for cross-field validation:\n\n```typescript\nconst validateDateRange: CustomValidator = (ctx) => {\n const errors: ValidationError[] = [];\n\n const startDate = ctx.valueOf('startDate');\n const endDate = ctx.valueOf('endDate');\n\n if (!startDate) errors.push({ kind: 'startDateRequired' });\n if (!endDate) errors.push({ kind: 'endDateRequired' });\n if (startDate && endDate && startDate > endDate) {\n errors.push({ kind: 'invalidDateRange' });\n }\n\n return errors.length > 0 ? errors : null;\n};\n```\n\n## Validation Messages\n\n### Field-Level Messages\n\n```typescript\n{\n key: 'username',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: 'Spaces are not allowed'\n }\n}\n```\n\n### Form-Level Default Messages\n\n```typescript\n{\n defaultValidationMessages: {\n noSpaces: 'Spaces are not allowed',\n passwordMismatch: 'Passwords must match',\n usernameTaken: 'This username is already taken'\n },\n fields: [/* ... */]\n}\n```\n\n### Dynamic Messages with i18n\n\n```typescript\nimport { inject } from '@angular/core';\nimport { TranslateService } from '@ngx-translate/core';\n\n{\n key: 'username',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: inject(TranslateService).get('VALIDATION.NO_SPACES')\n }\n}\n```\n\n### Parameterized Messages\n\nMessages can interpolate params from ValidatorConfig using Angular template syntax (double curly braces around the param name).\n\n**Syntax:** To interpolate a param, wrap its name in double curly braces (same syntax as Angular templates).\n\n**Example:** To access `params.label`, write the param name `label` wrapped in double curly braces in your message string.\n\n```typescript\n{\n validators: [\n {\n type: 'custom',\n functionName: 'lessThanField',\n params: { field: 'minAge', label: 'Minimum Age' }\n }\n ],\n validationMessages: {\n // Interpolate params.label using double curly braces\n notLessThan: 'Must be less than {{label}}'\n }\n}\n```\n\nThe validation message will render as **\"Must be less than Minimum Age\"** by interpolating the `label` param value.\n\n## Type Safety\n\nAll validator types are fully typed. While validators can optionally use generic type parameters for stricter typing, the simple form without generics works well for most cases:\n\n```typescript\n// Simple form - works for most cases\nconst noSpaces: CustomValidator = (ctx) => {\n const value = ctx.value();\n if (typeof value === 'string' && value.includes(' ')) {\n return { kind: 'noSpaces' };\n }\n return null;\n};\n\n// With type parameter - for stricter typing (advanced)\nconst strictNoSpaces: CustomValidator<string> = (ctx) => {\n const value = ctx.value(); // Type: string\n // TypeScript knows value is always string\n return value.includes(' ') ? { kind: 'noSpaces' } : null;\n};\n\n// Async validators with type parameters (advanced)\nconst checkUsername: AsyncCustomValidator<string, { username: string }, { available: boolean }> = {\n params: (ctx) => ({ username: ctx.value() }),\n factory: (params) => {\n /* ... */\n },\n onSuccess: (result, ctx) => {\n result.available; // Type: boolean\n return result.available ? null : { kind: 'usernameTaken' };\n },\n};\n\n// HTTP validators with type parameters (advanced)\nconst checkDomain: HttpCustomValidator<string, { valid: boolean }> = {\n request: (ctx) => ({\n /* ... */\n }),\n onSuccess: (response, ctx) => {\n response.valid; // Type: boolean\n return response.valid ? null : { kind: 'invalidDomain' };\n },\n};\n```\n\n**Note:** When registering validators in `customFnConfig.validators`, use the simple form without type parameters to avoid TypeScript compatibility issues.\n\n## Best Practices\n\n1. **Separation of Concerns**: Return only error `kind`, configure messages separately\n2. **i18n Support**: Use Observable/Signal for validation messages\n3. **Graceful Degradation**: Handle async/HTTP errors without blocking the form\n4. **Cross-Field Validation**: Use `ctx.valueOf()` for accessing related fields\n5. **Type Safety**: Leverage TypeScript generics for type-safe validation\n6. **Message Priority**: Use field-level messages for customization, form-level for common errors\n7. **Conditional Validation**: Use `when` property with `ConditionalExpression` for dynamic validators\n8. **Inverted Logic**: HTTP validators check validity, not data fetching success\n\n## Related Documentation\n\n- [Validation Basics](../basics/) - Core validation concepts\n- [Validation Reference](../reference/) - Standard validation rules\n- [Type Safety](../../advanced/type-safety/basics/) - TypeScript integration"
266
+ content: "Custom validation functions for complex validation logic that goes beyond built-in validators.\n\n## Overview\n\nng-forge supports four types of custom validators:\n\n1. **Declarative HTTP** (`type: 'http'`) - Validate against an HTTP endpoint with no function registration\n2. **CustomValidator** - Synchronous validators with access to FieldContext\n3. **AsyncCustomValidator** - Async validators using Angular's resource API\n4. **HttpCustomValidator** (function-based) - HTTP validators with full programmatic control\n\n**Key Principle:** Validators should focus on validation logic, NOT presentation. Return only the error `kind` and configure messages at field level for proper i18n support.\n\n## Live Demo\n\nTry the interactive example below to see both expression-based and function-based validators in action:\n\n<iframe src=\"http://localhost:4201/#/examples/expression-validators-demo\" class=\"example-frame\" title=\"Expression Validators Demo\"></iframe>\n\n## Message Resolution (STRICT)\n\nAll error messages MUST be explicitly configured. The framework enforces this strictly:\n\n1. **Field-level `validationMessages[kind]`** (highest priority - per-field customization)\n2. **Form-level `defaultValidationMessages[kind]`** (fallback for common messages)\n3. **No message configured = Console warning + error NOT displayed**\n\n**Important:** Validator-returned messages are NOT used as fallbacks. This enforces proper separation of concerns and i18n patterns.\n\nYou can define messages at the form level for common validation errors:\n\n```typescript\n{\n defaultValidationMessages: {\n noSpaces: 'Spaces are not allowed',\n passwordMismatch: 'Passwords must match'\n },\n fields: [/* ... */]\n}\n```\n\n## Two Validator Patterns\n\nng-forge supports two patterns for custom validators:\n\n1. **Function-based** - Register reusable validator functions (best for complex logic, reusability)\n2. **Expression-based** - Inline JavaScript expressions (best for simple, one-off validations)\n\n## Expression-Based Validators\n\nFor simple validation logic, use inline JavaScript expressions without registering functions.\n\n### Basic Example\n\n```typescript\n{\n key: 'confirmPassword',\n type: 'input',\n value: '',\n validators: [{\n type: 'custom',\n expression: 'fieldValue === formValue.password',\n kind: 'passwordMismatch',\n }],\n validationMessages: {\n passwordMismatch: 'Passwords must match',\n },\n}\n```\n\n**How it works:**\n\n- `fieldValue` - Current field's value\n- `formValue` - Entire form value object\n- Expression returns `true` = validation passes\n- Expression returns `false` = validation fails with the specified `kind`\n\n### Available Context\n\nExpression-based validators have access to:\n\n- **`fieldValue`** - Current field value\n- **`formValue`** - Complete form value object (e.g., `formValue.password`, `formValue.email`)\n- **`fieldPath`** - Current field path\n- Custom functions registered in `customFnConfig.customFunctions`\n\n### Safe Member Access\n\n**Built-in null/undefined handling**: Member access is safe by default - no manual null checks needed!\n\n```typescript\n// \u2705 Works safely even when nested values are null/undefined\n{\n expression: 'fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// \u274C Unnecessary - Don't do this\n{\n expression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// \u2705 Better - Safe by default\n{\n expression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n```\n\nAccessing properties on `null` or `undefined` returns `undefined` instead of throwing errors, making expressions cleaner and more maintainable.\n\n### Common Expression Patterns\n\n**Password confirmation:**\n\n```typescript\n{\n expression: 'fieldValue === formValue.password',\n kind: 'passwordMismatch',\n}\n```\n\n**Date range validation:**\n\n```typescript\n{\n expression: 'new Date(fieldValue) > new Date(formValue.startDate)',\n kind: 'endDateBeforeStart',\n}\n```\n\n**Conditional required:**\n\n```typescript\n{\n expression: 'formValue.requiresApproval ? fieldValue?.length > 0 : true',\n kind: 'approvalRequired',\n}\n```\n\n**Numeric comparison:**\n\n```typescript\n{\n expression: 'fieldValue >= formValue.minAge && fieldValue <= formValue.maxAge',\n kind: 'ageOutOfRange',\n}\n```\n\n**Deeply nested field validation:**\n\n```typescript\n{\n // Safe to access deeply nested properties\n expression: 'fieldValue.toLowerCase() !== formValue.user.address.city.toLowerCase()',\n kind: 'invalidAddress',\n}\n```\n\n### Security\n\nExpressions use **secure AST-based parsing**. Only safe JavaScript operations are allowed.\n\n## Function-Based Validators\n\nBest for validation that needs field value and access to other fields via FieldContext.\n\n### Basic Example\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\n// \u2705 RECOMMENDED: Return only kind\nconst noSpaces: CustomValidator = (ctx) => {\n const value = ctx.value();\n if (typeof value === 'string' && value.includes(' ')) {\n return { kind: 'noSpaces' }; // No hardcoded message\n }\n return null;\n};\n\n// Register and configure message\nconst config = {\n fields: [\n {\n key: 'username',\n type: 'input',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: 'Spaces are not allowed', // Or Observable/Signal for i18n\n },\n },\n ],\n customFnConfig: {\n validators: {\n noSpaces,\n },\n },\n};\n```\n\n### FieldContext API\n\nThe `FieldContext` API provides access to:\n\n- **`ctx.value()`** - Current field value (signal)\n- **`ctx.state`** - Field state (errors, touched, dirty, etc.)\n- **`ctx.valueOf(path)`** - Access other field values (PUBLIC API for cross-field validation)\n- **`ctx.stateOf(path)`** - Access other field states\n- **`ctx.field`** - Current field tree\n\n### Cross-Field Validation\n\nUse `ctx.valueOf()` to access other field values for comparison validators:\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\nconst greaterThanMin: CustomValidator = (ctx) => {\n const value = ctx.value();\n const minValue = ctx.valueOf('minAge');\n\n if (minValue !== undefined && value <= minValue) {\n return { kind: 'notGreaterThanMin' };\n }\n return null;\n};\n\n// Note: Custom validators return only 'kind'. Built-in validators (min, max, etc.)\n// automatically include params for interpolation (e.g., {{min}}, {{max}}, etc.)\nconst config = {\n fields: [\n { key: 'minAge', type: 'input', value: 0 },\n {\n key: 'maxAge',\n type: 'input',\n value: 0,\n validators: [\n {\n type: 'custom',\n functionName: 'greaterThanMin',\n },\n ],\n validationMessages: {\n notGreaterThanMin: 'Maximum age must be greater than minimum age',\n },\n },\n ],\n customFnConfig: {\n validators: { greaterThanMin },\n },\n};\n```\n\n**Common Cross-Field Patterns:**\n\n- Password confirmation matching\n- Date range validation (start < end)\n- Numeric range validation (min < max)\n- Conditional required fields\n\n### Password Confirmation Example\n\n```typescript\nconst passwordMatch: CustomValidator = (ctx) => {\n const confirmPassword = ctx.value();\n const password = ctx.valueOf('password');\n\n if (!confirmPassword || !password) {\n return null; // Let required validator handle empty case\n }\n\n if (password !== confirmPassword) {\n return { kind: 'passwordMismatch' };\n }\n return null;\n};\n\n// In field config:\n{\n key: 'confirmPassword',\n type: 'input',\n validators: [{ type: 'custom', functionName: 'passwordMatch' }],\n validationMessages: {\n passwordMismatch: 'Passwords do not match'\n }\n}\n```\n\n## Async Validators (Resource-based)\n\n> **Deprecation notice:** The old `type: 'customAsync'` still works but is deprecated. Use `type: 'async'` instead.\n\nAsync validators use Angular's resource API for database lookups or complex async operations.\n\n### Basic Example\n\n```typescript\nimport { AsyncCustomValidator } from '@ng-forge/dynamic-forms';\nimport { inject } from '@angular/core';\nimport { rxResource } from '@angular/core/rxjs-interop';\nimport { of } from 'rxjs';\nimport { UserService } from './user.service';\n\nconst checkUsernameAvailable: AsyncCustomValidator = {\n // Extract params from field context\n params: (ctx) => ({ username: ctx.value() }),\n\n // Create resource with params signal\n factory: (params) => {\n const userService = inject(UserService);\n return rxResource({\n request: params,\n loader: ({ request }) => {\n if (!request?.username) return of(null);\n return userService.checkAvailability(request.username);\n },\n });\n },\n\n // Map result to validation error\n onSuccess: (result, ctx) => {\n if (!result) return null;\n return result.available ? null : { kind: 'usernameTaken' };\n },\n\n // Handle errors gracefully\n onError: (error, ctx) => {\n console.error('Availability check failed:', error);\n return null; // Don't block form on network errors\n },\n};\n\nconst config = {\n fields: [\n {\n key: 'username',\n type: 'input',\n validators: [{ type: 'async', functionName: 'checkUsernameAvailable' }],\n validationMessages: {\n usernameTaken: 'This username is already taken',\n },\n },\n ],\n customFnConfig: {\n asyncValidators: {\n checkUsernameAvailable,\n },\n },\n};\n```\n\n**Key Benefits:**\n\n- Automatic loading states via resource API\n- Angular manages resource lifecycle\n- Reactive - refetches when params change\n- Integrates with Signal Forms validation state\n\n### Structure\n\n```typescript\ninterface AsyncCustomValidator<TValue, TParams, TResult> {\n // Function that receives field context and returns resource params\n readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;\n\n // Function that creates a ResourceRef from the params signal\n readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;\n\n // Map successful resource result to validation errors\n readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n // Handle resource errors\n readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n```\n\n## Declarative HTTP Validators\n\nThe simplest way to validate against an HTTP endpoint. No function registration required \u2014 configure the request and response mapping inline.\n\n### Basic Example\n\n```typescript\n{\n key: 'username',\n type: 'input',\n validators: [\n {\n type: 'http',\n http: {\n url: '/api/users/check-availability',\n method: 'GET',\n queryParams: {\n username: 'fieldValue', // fieldValue refers to the current field\n },\n },\n responseMapping: {\n validWhen: 'response.available', // Truthy = valid\n errorKind: 'usernameTaken',\n },\n },\n ],\n validationMessages: {\n usernameTaken: 'This username is already taken',\n },\n}\n```\n\n**Key points:**\n\n- `fieldValue` is available as an expression in `params`, `queryParams`, and `body` (refers to the current field's value)\n- Use `params` with `:key` URL placeholders for path parameters (e.g. `url: '/api/users/:id'` + `params: { id: 'fieldValue' }`)\n- `validWhen` is evaluated with `{ response }` in scope \u2014 truthy means validation passed\n- **Fail-closed:** if the HTTP request errors, the validator returns `{ kind: errorKind }` by default (prevents submission on network failure)\n\n### POST with Body Expressions\n\n```typescript\n{\n type: 'http',\n http: {\n url: '/api/validate-email',\n method: 'POST',\n body: {\n email: 'fieldValue',\n },\n evaluateBodyExpressions: true,\n },\n responseMapping: {\n validWhen: 'response.valid',\n errorKind: 'emailInvalid',\n },\n}\n```\n\n### Error Message Interpolation\n\nUse `errorParams` to include response data in validation messages:\n\n```typescript\n{\n type: 'http',\n http: {\n url: '/api/users/check-availability',\n queryParams: { username: 'fieldValue' },\n },\n responseMapping: {\n validWhen: 'response.available',\n errorKind: 'usernameTaken',\n errorParams: {\n suggestion: 'response.suggestion', // Maps to {{suggestion}} in the message\n },\n },\n}\n// Message: 'Username is taken. Try {{suggestion}}'\n```\n\n### HttpValidationResponseMapping Interface\n\n```typescript\ninterface HttpValidationResponseMapping {\n /** Expression evaluated with { response }. Truthy = valid (no error). */\n validWhen: string;\n\n /** Error kind returned when validWhen is falsy \u2014 maps to validationMessages. */\n errorKind: string;\n\n /**\n * Optional parameters for message interpolation.\n * Keys become {{paramName}} placeholders. Values are expressions evaluated with { response }.\n */\n errorParams?: Record<string, string>;\n}\n```\n\n**When to use declarative vs function-based:**\n\n| Scenario | Use |\n| ----------------------------------------------- | ------------------------------------------------ |\n| Standard availability check | Declarative (`type: 'http'` + `responseMapping`) |\n| Need `inject()` for Angular services | Function-based (`HttpCustomValidator`) |\n| Conditional request (skip based on field state) | Function-based (`HttpCustomValidator`) |\n| Custom error handling (fail-open on error) | Function-based (`HttpCustomValidator`) |\n\n## HTTP Validators (Function-Based)\n\n> **Deprecation notice:** The old `type: 'customHttp'` still works but is deprecated. Use `type: 'http'` with `functionName` instead.\n\nFunction-based HTTP validators give you full programmatic control over request construction and response handling.\n\n### Basic Example\n\n```typescript\nimport { HttpCustomValidator } from '@ng-forge/dynamic-forms';\n\nconst checkEmailDomain: HttpCustomValidator = {\n // Build HTTP request from context\n request: (ctx) => {\n const email = ctx.value();\n if (!email?.includes('@')) return undefined; // Skip if invalid\n\n const domain = email.split('@')[1];\n return {\n url: `/api/validate-domain`,\n method: 'POST',\n body: { domain },\n headers: { 'Content-Type': 'application/json' },\n };\n },\n\n // NOTE: Inverted logic - onSuccess checks if response indicates INVALID\n // We're validating, not fetching data!\n onSuccess: (response, ctx) => {\n // Assuming API returns { valid: boolean }\n return response.valid ? null : { kind: 'invalidDomain' };\n },\n\n onError: (error, ctx) => {\n console.error('Domain validation failed:', error);\n return null; // Don't block form on network errors\n },\n};\n\nconst config = {\n fields: [\n {\n key: 'email',\n type: 'input',\n validators: [{ type: 'http', functionName: 'checkEmailDomain' }],\n validationMessages: {\n invalidDomain: 'This email domain is not allowed',\n },\n },\n ],\n customFnConfig: {\n httpValidators: {\n checkEmailDomain,\n },\n },\n};\n```\n\n**Key Benefits:**\n\n- Automatic request cancellation when field changes\n- Built-in debouncing via resource API\n- Prevents race conditions\n- Optimized for HTTP-specific validation\n\n**Important:** HTTP validators use \"inverted logic\" - `onSuccess` should return an error if validation fails, not if the HTTP request succeeds. You're checking validation status, not fetching data.\n\n### Structure\n\n```typescript\ninterface HttpCustomValidator<TValue, TResult> {\n // Build HTTP request from field context\n readonly request: (ctx: FieldContext<TValue>) => HttpResourceRequest | string | undefined;\n\n // Map successful response to validation error\n readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n // Handle HTTP errors\n readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n\ninterface HttpResourceRequest {\n url: string;\n method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n body?: any;\n headers?: Record<string, string | string[]>;\n}\n```\n\n## Conditional Custom Validators\n\nApply validators conditionally using the `when` property with a `ConditionalExpression`:\n\n```typescript\nconst businessEmailValidator: CustomValidator = (ctx) => {\n const value = ctx.value();\n const domain = value?.split('@')[1];\n\n const freeEmailDomains = ['gmail.com', 'yahoo.com', 'hotmail.com'];\n\n if (domain && freeEmailDomains.includes(domain.toLowerCase())) {\n return { kind: 'requireBusinessEmail' };\n }\n return null;\n};\n\nconst config = {\n fields: [\n {\n key: 'accountType',\n type: 'select',\n value: 'personal',\n options: [\n { value: 'personal', label: 'Personal' },\n { value: 'business', label: 'Business' },\n ],\n },\n {\n key: 'email',\n type: 'input',\n validators: [\n {\n type: 'custom',\n functionName: 'businessEmailValidator',\n // Only apply when account type is \"business\"\n when: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n },\n ],\n validationMessages: {\n requireBusinessEmail: 'Please use a business email address',\n },\n },\n ],\n customFnConfig: {\n validators: { businessEmailValidator },\n },\n};\n```\n\nThe validator is only active when the `when` condition evaluates to `true`, allowing dynamic validation based on form state. See [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/) for all expression types and operators.\n\n## Common Validation Patterns\n\n### Email Domain Validation\n\n```typescript\nconst emailDomainValidator: CustomValidator = (ctx) => {\n const blockedDomains = ['tempmail.com', 'throwaway.email'];\n const email = ctx.value();\n const domain = email?.split('@')[1];\n\n if (domain && blockedDomains.includes(domain)) {\n return { kind: 'blockedDomain' };\n }\n return null;\n};\n```\n\n### Age Validation\n\n```typescript\nconst ageValidator: CustomValidator = (ctx) => {\n const birthDate = ctx.value();\n const age = calculateAge(birthDate);\n\n if (age < 18) {\n return { kind: 'tooYoung' };\n }\n return null;\n};\n```\n\n### Conditional Required\n\n```typescript\nconst conditionalRequiredValidator: CustomValidator = (ctx) => {\n const value = ctx.value();\n const employmentStatus = ctx.valueOf('employmentStatus');\n\n // Company name required if employed\n if (employmentStatus === 'employed' && !value) {\n return { kind: 'required' };\n }\n return null;\n};\n```\n\n### Date Range Validation\n\n```typescript\nconst dateRangeValidator: CustomValidator = (ctx) => {\n const endDate = ctx.value();\n const startDate = ctx.valueOf('startDate');\n\n if (startDate && endDate && startDate > endDate) {\n return { kind: 'invalidDateRange' };\n }\n return null;\n};\n```\n\n## Multiple Errors\n\nValidators can return multiple errors for cross-field validation:\n\n```typescript\nconst validateDateRange: CustomValidator = (ctx) => {\n const errors: ValidationError[] = [];\n\n const startDate = ctx.valueOf('startDate');\n const endDate = ctx.valueOf('endDate');\n\n if (!startDate) errors.push({ kind: 'startDateRequired' });\n if (!endDate) errors.push({ kind: 'endDateRequired' });\n if (startDate && endDate && startDate > endDate) {\n errors.push({ kind: 'invalidDateRange' });\n }\n\n return errors.length > 0 ? errors : null;\n};\n```\n\n## Validation Messages\n\n### Field-Level Messages\n\n```typescript\n{\n key: 'username',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: 'Spaces are not allowed'\n }\n}\n```\n\n### Form-Level Default Messages\n\n```typescript\n{\n defaultValidationMessages: {\n noSpaces: 'Spaces are not allowed',\n passwordMismatch: 'Passwords must match',\n usernameTaken: 'This username is already taken'\n },\n fields: [/* ... */]\n}\n```\n\n### Dynamic Messages with i18n\n\n```typescript\nimport { inject } from '@angular/core';\nimport { TranslateService } from '@ngx-translate/core';\n\n{\n key: 'username',\n validators: [{ type: 'custom', functionName: 'noSpaces' }],\n validationMessages: {\n noSpaces: inject(TranslateService).get('VALIDATION.NO_SPACES')\n }\n}\n```\n\n### Parameterized Messages\n\nMessages can interpolate params from ValidatorConfig using Angular template syntax (double curly braces around the param name).\n\n**Syntax:** To interpolate a param, wrap its name in double curly braces (same syntax as Angular templates).\n\n**Example:** To access `params.label`, write the param name `label` wrapped in double curly braces in your message string.\n\n```typescript\n{\n validators: [\n {\n type: 'custom',\n functionName: 'lessThanField',\n params: { field: 'minAge', label: 'Minimum Age' }\n }\n ],\n validationMessages: {\n // Interpolate params.label using double curly braces\n notLessThan: 'Must be less than {{label}}'\n }\n}\n```\n\nThe validation message will render as **\"Must be less than Minimum Age\"** by interpolating the `label` param value.\n\n## Type Safety\n\nAll validator types are fully typed. While validators can optionally use generic type parameters for stricter typing, the simple form without generics works well for most cases:\n\n```typescript\n// Simple form - works for most cases\nconst noSpaces: CustomValidator = (ctx) => {\n const value = ctx.value();\n if (typeof value === 'string' && value.includes(' ')) {\n return { kind: 'noSpaces' };\n }\n return null;\n};\n\n// With type parameter - for stricter typing (advanced)\nconst strictNoSpaces: CustomValidator<string> = (ctx) => {\n const value = ctx.value(); // Type: string\n // TypeScript knows value is always string\n return value.includes(' ') ? { kind: 'noSpaces' } : null;\n};\n\n// Async validators with type parameters (advanced)\nconst checkUsername: AsyncCustomValidator<string, { username: string }, { available: boolean }> = {\n params: (ctx) => ({ username: ctx.value() }),\n factory: (params) => {\n /* ... */\n },\n onSuccess: (result, ctx) => {\n result.available; // Type: boolean\n return result.available ? null : { kind: 'usernameTaken' };\n },\n};\n\n// HTTP validators with type parameters (advanced)\nconst checkDomain: HttpCustomValidator<string, { valid: boolean }> = {\n request: (ctx) => ({\n /* ... */\n }),\n onSuccess: (response, ctx) => {\n response.valid; // Type: boolean\n return response.valid ? null : { kind: 'invalidDomain' };\n },\n};\n```\n\n**Note:** When registering validators in `customFnConfig.validators`, use the simple form without type parameters to avoid TypeScript compatibility issues.\n\n## Best Practices\n\n1. **Separation of Concerns**: Return only error `kind`, configure messages separately\n2. **i18n Support**: Use Observable/Signal for validation messages\n3. **Graceful Degradation**: Handle async/HTTP errors without blocking the form\n4. **Cross-Field Validation**: Use `ctx.valueOf()` for accessing related fields\n5. **Type Safety**: Leverage TypeScript generics for type-safe validation\n6. **Message Priority**: Use field-level messages for customization, form-level for common errors\n7. **Conditional Validation**: Use `when` property with `ConditionalExpression` for dynamic validators\n8. **Inverted Logic**: HTTP validators check validity, not data fetching success\n\n## Related Documentation\n\n- [Validation Basics](../basics/) - Core validation concepts\n- [Validation Reference](../reference/) - Standard validation rules\n- [Type Safety](../../advanced/type-safety/basics/) - TypeScript integration"
231
267
  },
232
268
  {
233
269
  id: "validation-reference",
234
270
  title: "Validation Reference",
235
271
  category: "validation",
236
- content: "Complete reference for all validators, conditional expressions, and validation configuration options.\n\n## All Validator Types\n\n### required\n\nField must have a value.\n\n```typescript\n// Shorthand\n{ required: true }\n\n// Explicit\n{\n validators: [{\n type: 'required',\n }],\n}\n```\n\n### email\n\nMust be a valid email format.\n\n```typescript\n// Shorthand\n{ email: true }\n\n// Explicit\n{\n validators: [{\n type: 'email',\n }],\n}\n```\n\n### minLength\n\nMinimum string length.\n\n```typescript\n// Shorthand\n{ minLength: 8 }\n\n// Explicit\n{\n validators: [{\n type: 'minLength',\n value: 8,\n }],\n}\n```\n\n### maxLength\n\nMaximum string length.\n\n```typescript\n// Shorthand\n{ maxLength: 20 }\n\n// Explicit\n{\n validators: [{\n type: 'maxLength',\n value: 20,\n }],\n}\n```\n\n### min\n\nMinimum numeric value.\n\n```typescript\n// Shorthand\n{ min: 0 }\n\n// Explicit\n{\n validators: [{\n type: 'min',\n value: 0,\n }],\n}\n```\n\n### max\n\nMaximum numeric value.\n\n```typescript\n// Shorthand\n{ max: 100 }\n\n// Explicit\n{\n validators: [{\n type: 'max',\n value: 100,\n }],\n}\n```\n\n### pattern\n\nRegular expression validation.\n\n```typescript\n// Shorthand\n{ pattern: '^[0-9]{5}$' }\n\n// Explicit\n{\n validators: [{\n type: 'pattern',\n value: '^[0-9]{5}$',\n }],\n}\n```\n\n## Conditional Expressions\n\nValidators support a `when` property for conditional validation. See **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** for the complete reference on:\n\n- All operators (`equals`, `notEquals`, `greater`, `less`, `contains`, `matches`, etc.)\n- Expression types (`fieldValue`, `formValue`, `javascript`, `custom`)\n- Combining conditions with `and`/`or` logic\n\n**Quick example:**\n\n```typescript\n{\n validators: [{\n type: 'required',\n when: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n## ValidatorConfig Types\n\nValidatorConfig is a discriminated union type with four variants:\n\n```typescript\n// Built-in validators (required, email, min, max, etc.)\ninterface BuiltInValidatorConfig {\n type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';\n value?: number | string | RegExp;\n expression?: string;\n when?: ConditionalExpression;\n}\n\n// Custom synchronous validators\ninterface CustomValidatorConfig {\n type: 'custom';\n functionName?: string;\n params?: Record<string, unknown>;\n expression?: string;\n kind?: string;\n errorParams?: Record<string, string>;\n when?: ConditionalExpression;\n}\n\n// Async validators (for debounced validation, database lookups)\ninterface AsyncValidatorConfig {\n type: 'customAsync';\n functionName: string;\n params?: Record<string, unknown>;\n when?: ConditionalExpression;\n}\n\n// HTTP validators (optimized HTTP validation with auto-cancellation)\ninterface HttpValidatorConfig {\n type: 'customHttp';\n functionName: string;\n params?: Record<string, unknown>;\n when?: ConditionalExpression;\n}\n\ntype ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | HttpValidatorConfig;\n```\n\n## ConditionalExpression Interface\n\n```typescript\ninterface ConditionalExpression {\n // Expression type - includes 'and' and 'or' for combining conditions\n type: 'fieldValue' | 'formValue' | 'custom' | 'javascript' | 'and' | 'or';\n\n // Field path for fieldValue type\n fieldPath?: string;\n\n // Comparison operator\n operator?:\n | 'equals'\n | 'notEquals'\n | 'greater'\n | 'less'\n | 'greaterOrEqual'\n | 'lessOrEqual'\n | 'contains'\n | 'startsWith'\n | 'endsWith'\n | 'matches';\n\n // Value to compare against\n value?: unknown;\n\n // JavaScript expression for custom logic\n expression?: string;\n\n // Array of sub-conditions for 'and' and 'or' types\n conditions?: ConditionalExpression[];\n}\n```\n\n## Validation Messages\n\n### Per-Field Messages\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n email: true,\n validationMessages: {\n required: 'Email is required',\n email: 'Invalid email format',\n },\n}\n```\n\n### Dynamic Messages (i18n)\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n validationMessages: {\n required: this.transloco.selectTranslate('validation.required'),\n email: this.transloco.selectTranslate('validation.email'),\n },\n}\n```\n\n## Common Patterns\n\n### Email Validation\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n email: true,\n validationMessages: {\n required: 'Email is required',\n email: 'Please enter a valid email address',\n },\n}\n```\n\n### Password Requirements\n\n```typescript\n{\n key: 'password',\n type: 'input',\n value: '',\n required: true,\n minLength: 8,\n maxLength: 128,\n pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&])',\n validationMessages: {\n required: 'Password is required',\n minLength: 'Password must be at least 8 characters',\n pattern: 'Password must include uppercase, lowercase, number, and special character',\n },\n props: { type: 'password' },\n}\n```\n\n### Numeric Range\n\n```typescript\n{\n key: 'age',\n type: 'input',\n value: null,\n required: true,\n min: 18,\n max: 120,\n validationMessages: {\n required: 'Age is required',\n min: 'Must be at least 18 years old',\n max: 'Please enter a valid age',\n },\n props: { type: 'number' },\n}\n```\n\n### ZIP Code\n\n```typescript\n{\n key: 'zipCode',\n type: 'input',\n value: '',\n required: true,\n pattern: '^[0-9]{5}(-[0-9]{4})?$',\n validationMessages: {\n required: 'ZIP code is required',\n pattern: 'Must be 5 digits or 5+4 format (e.g., 12345 or 12345-6789)',\n },\n}\n```\n\n### Phone Number\n\n```typescript\n{\n key: 'phone',\n type: 'input',\n value: '',\n pattern: '^\\\\+?[1-9]\\\\d{1,14}$',\n validationMessages: {\n pattern: 'Please enter a valid phone number (E.164 format preferred)',\n },\n props: { type: 'tel' },\n}\n```\n\n### URL\n\n```typescript\n{\n key: 'website',\n type: 'input',\n value: '',\n pattern: '^https?:\\\\/\\\\/.+',\n validationMessages: {\n pattern: 'Please enter a valid URL starting with http:// or https://',\n },\n props: { type: 'url' },\n}\n```\n\n## Related\n\n- **[Validation Basics](../basics/)** - Getting started with validation\n- **[Validation Advanced](../advanced/)** - Conditional validators\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Field behavior changes\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration"
272
+ content: "Complete reference for all validators, conditional expressions, and validation configuration options.\n\n## All Validator Types\n\n### required\n\nField must have a value.\n\n```typescript\n// Shorthand\n{ required: true }\n\n// Explicit\n{\n validators: [{\n type: 'required',\n }],\n}\n```\n\n### email\n\nMust be a valid email format.\n\n```typescript\n// Shorthand\n{ email: true }\n\n// Explicit\n{\n validators: [{\n type: 'email',\n }],\n}\n```\n\n### minLength\n\nMinimum string length.\n\n```typescript\n// Shorthand\n{ minLength: 8 }\n\n// Explicit\n{\n validators: [{\n type: 'minLength',\n value: 8,\n }],\n}\n```\n\n### maxLength\n\nMaximum string length.\n\n```typescript\n// Shorthand\n{ maxLength: 20 }\n\n// Explicit\n{\n validators: [{\n type: 'maxLength',\n value: 20,\n }],\n}\n```\n\n### min\n\nMinimum numeric value.\n\n```typescript\n// Shorthand\n{ min: 0 }\n\n// Explicit\n{\n validators: [{\n type: 'min',\n value: 0,\n }],\n}\n```\n\n### max\n\nMaximum numeric value.\n\n```typescript\n// Shorthand\n{ max: 100 }\n\n// Explicit\n{\n validators: [{\n type: 'max',\n value: 100,\n }],\n}\n```\n\n### pattern\n\nRegular expression validation.\n\n```typescript\n// Shorthand\n{ pattern: '^[0-9]{5}$' }\n\n// Explicit\n{\n validators: [{\n type: 'pattern',\n value: '^[0-9]{5}$',\n }],\n}\n```\n\n## Conditional Expressions\n\nValidators support a `when` property for conditional validation. See **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** for the complete reference on:\n\n- All operators (`equals`, `notEquals`, `greater`, `less`, `contains`, `matches`, etc.)\n- Expression types (`fieldValue`, `formValue` (deprecated), `javascript`, `custom`)\n- Combining conditions with `and`/`or` logic\n\n**Quick example:**\n\n```typescript\n{\n validators: [{\n type: 'required',\n when: {\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n },\n }],\n}\n```\n\n## ValidatorConfig Types\n\nValidatorConfig is a discriminated union type with five variants:\n\n```typescript\n// Built-in validators (required, email, min, max, etc.)\ninterface BuiltInValidatorConfig {\n type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';\n value?: number | string | RegExp;\n expression?: string;\n when?: ConditionalExpression;\n}\n\n// Custom synchronous validators\ninterface CustomValidatorConfig {\n type: 'custom';\n functionName?: string;\n params?: Record<string, unknown>;\n expression?: string;\n kind?: string;\n errorParams?: Record<string, string>;\n when?: ConditionalExpression;\n}\n\n// Async validators (for debounced validation, database lookups)\ninterface AsyncValidatorConfig {\n // 'async' is preferred; 'customAsync' is deprecated and emits a warning in dev mode\n type: 'async' | 'customAsync';\n functionName: string;\n params?: Record<string, unknown>;\n when?: ConditionalExpression;\n}\n\n// Function-based HTTP validators (requires a registered function)\ninterface FunctionHttpValidatorConfig {\n // 'http' is preferred; 'customHttp' is deprecated and emits a warning in dev mode\n type: 'http' | 'customHttp';\n functionName: string;\n params?: Record<string, unknown>;\n when?: ConditionalExpression;\n}\n\n// Declarative HTTP validators (fully JSON-serializable, no function registration)\ninterface DeclarativeHttpValidatorConfig {\n type: 'http';\n http: HttpRequestConfig;\n responseMapping: HttpValidationResponseMapping;\n when?: ConditionalExpression;\n}\n\ntype ValidatorConfig =\n | BuiltInValidatorConfig\n | CustomValidatorConfig\n | AsyncValidatorConfig\n | FunctionHttpValidatorConfig\n | DeclarativeHttpValidatorConfig;\n```\n\n> **Deprecation notes:**\n>\n> - `type: 'customAsync'` is deprecated. Use `type: 'async'` instead.\n> - `type: 'customHttp'` is deprecated. Use `type: 'http'` instead.\n> - `FunctionHttpValidatorConfig` and `DeclarativeHttpValidatorConfig` both use `type: 'http'`. They are discriminated by property presence: `functionName` indicates function-based, `http` + `responseMapping` indicates declarative.\n\n### HttpRequestConfig\n\nUsed by `DeclarativeHttpValidatorConfig` to define the HTTP request:\n\n```typescript\ninterface HttpRequestConfig {\n url: string;\n method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; // defaults to 'GET'\n queryParams?: Record<string, string>; // values are expressions\n body?: Record<string, unknown>;\n evaluateBodyExpressions?: boolean; // when true, top-level string values in body are evaluated as expressions\n headers?: Record<string, string>;\n}\n```\n\n### HttpValidationResponseMapping\n\nUsed by `DeclarativeHttpValidatorConfig` to interpret the HTTP response:\n\n```typescript\ninterface HttpValidationResponseMapping {\n validWhen: string; // expression evaluated with { response } scope; truthy = valid\n errorKind: string; // error kind for validationMessages lookup\n errorParams?: Record<string, string>; // parameter expressions evaluated against { response }\n}\n```\n\n## ConditionalExpression Types\n\n`ConditionalExpression` is a discriminated union of six condition types. Each variant only allows the properties relevant to its type, providing compile-time safety against invalid property combinations.\n\n```typescript\n// Compare a specific field's value\ninterface FieldValueCondition {\n type: 'fieldValue';\n fieldPath: string;\n operator: ComparisonOperator;\n value?: unknown;\n}\n\n// Compare the entire form value (deprecated \u2014 use FieldValueCondition or JavascriptCondition instead)\ninterface FormValueCondition {\n type: 'formValue';\n operator: ComparisonOperator;\n value?: unknown;\n}\n\n// Invoke a registered custom function by name\ninterface CustomCondition {\n type: 'custom';\n expression: string; // registered function name\n}\n\n// Evaluate a JavaScript expression via the secure AST-based parser\ninterface JavascriptCondition {\n type: 'javascript';\n expression: string; // has access to formValue, fieldValue, externalData, etc.\n}\n\n// Logical AND \u2014 all sub-conditions must be true\ninterface AndCondition {\n type: 'and';\n conditions: ConditionalExpression[];\n}\n\n// Logical OR \u2014 at least one sub-condition must be true\ninterface OrCondition {\n type: 'or';\n conditions: ConditionalExpression[];\n}\n\ntype ComparisonOperator =\n | 'equals'\n | 'notEquals'\n | 'greater'\n | 'less'\n | 'greaterOrEqual'\n | 'lessOrEqual'\n | 'contains'\n | 'startsWith'\n | 'endsWith'\n | 'matches';\n\ntype ConditionalExpression = FieldValueCondition | FormValueCondition | CustomCondition | JavascriptCondition | AndCondition | OrCondition;\n```\n\n> **Deprecation note:** `FormValueCondition` (`type: 'formValue'`) is deprecated. Use `FieldValueCondition` for specific field checks, or `JavascriptCondition` with an expression for complex form-level comparisons.\n\n## Validation Messages\n\n### Per-Field Messages\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n email: true,\n validationMessages: {\n required: 'Email is required',\n email: 'Invalid email format',\n },\n}\n```\n\n### Dynamic Messages (i18n)\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n validationMessages: {\n required: this.transloco.selectTranslate('validation.required'),\n email: this.transloco.selectTranslate('validation.email'),\n },\n}\n```\n\n## Common Patterns\n\n### Email Validation\n\n```typescript\n{\n key: 'email',\n type: 'input',\n value: '',\n required: true,\n email: true,\n validationMessages: {\n required: 'Email is required',\n email: 'Please enter a valid email address',\n },\n}\n```\n\n### Password Requirements\n\n```typescript\n{\n key: 'password',\n type: 'input',\n value: '',\n required: true,\n minLength: 8,\n maxLength: 128,\n pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&])',\n validationMessages: {\n required: 'Password is required',\n minLength: 'Password must be at least 8 characters',\n pattern: 'Password must include uppercase, lowercase, number, and special character',\n },\n props: { type: 'password' },\n}\n```\n\n### Numeric Range\n\n```typescript\n{\n key: 'age',\n type: 'input',\n value: null,\n required: true,\n min: 18,\n max: 120,\n validationMessages: {\n required: 'Age is required',\n min: 'Must be at least 18 years old',\n max: 'Please enter a valid age',\n },\n props: { type: 'number' },\n}\n```\n\n### ZIP Code\n\n```typescript\n{\n key: 'zipCode',\n type: 'input',\n value: '',\n required: true,\n pattern: '^[0-9]{5}(-[0-9]{4})?$',\n validationMessages: {\n required: 'ZIP code is required',\n pattern: 'Must be 5 digits or 5+4 format (e.g., 12345 or 12345-6789)',\n },\n}\n```\n\n### Phone Number\n\n```typescript\n{\n key: 'phone',\n type: 'input',\n value: '',\n pattern: '^\\\\+?[1-9]\\\\d{1,14}$',\n validationMessages: {\n pattern: 'Please enter a valid phone number (E.164 format preferred)',\n },\n props: { type: 'tel' },\n}\n```\n\n### URL\n\n```typescript\n{\n key: 'website',\n type: 'input',\n value: '',\n pattern: '^https?:\\\\/\\\\/.+',\n validationMessages: {\n pattern: 'Please enter a valid URL starting with http:// or https://',\n },\n props: { type: 'url' },\n}\n```\n\n## Related\n\n- **[Validation Basics](../basics/)** - Getting started with validation\n- **[Validation Advanced](../advanced/)** - Conditional validators\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Field behavior changes\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration"
237
273
  }
238
274
  ];
239
275
  }
@@ -497,7 +533,7 @@ var field_types_default = [
497
533
  {
498
534
  type: "row",
499
535
  category: "container",
500
- description: "Horizontal layout container for grouping fields in columns. Rows do NOT have a label property and do NOT support logic blocks.",
536
+ description: "Horizontal layout container for grouping fields in columns. Rows do NOT have a label property. Supports only 'hidden' logic type for conditional visibility.",
501
537
  baseInterface: "FieldDef",
502
538
  props: {
503
539
  fields: {
@@ -530,13 +566,13 @@ var field_types_default = [
530
566
  "previous"
531
567
  ],
532
568
  cannotContain: ["page", "row", "hidden"],
533
- example: "{\n key: 'nameRow',\n type: 'row',\n // NOTE: Rows do NOT have label or logic properties\n fields: [\n { key: 'firstName', type: 'input', label: 'First Name', col: 6 },\n { key: 'lastName', type: 'input', label: 'Last Name', col: 6 }\n ]\n}\n// NOT ALLOWED in rows:\n// - type: 'hidden' (hidden fields cannot be inside rows)\n// - type: 'page' (pages are top-level only)\n// - type: 'row' (no nested rows)",
569
+ example: "{\n key: 'nameRow',\n type: 'row',\n // NOTE: Rows do NOT have a label property\n // Rows support only 'hidden' logic type for conditional visibility\n fields: [\n { key: 'firstName', type: 'input', label: 'First Name', col: 6 },\n { key: 'lastName', type: 'input', label: 'Last Name', col: 6 }\n ]\n}\n// NOT ALLOWED in rows:\n// - type: 'hidden' (hidden fields cannot be inside rows)\n// - type: 'page' (pages are top-level only)\n// - type: 'row' (no nested rows)",
534
570
  minimalExample: "{ key: 'row1', type: 'row', fields: [...] }"
535
571
  },
536
572
  {
537
573
  type: "group",
538
574
  category: "container",
539
- description: "Nested form group container creating a sub-object in form values. Groups are logical containers only and do NOT have a label property.",
575
+ description: "Nested form group container creating a sub-object in form values. Groups are logical containers only and do NOT have a label property. Supports only 'hidden' logic type for conditional visibility.",
540
576
  valueType: "object",
541
577
  baseInterface: "FieldDef",
542
578
  props: {
@@ -576,7 +612,7 @@ var field_types_default = [
576
612
  {
577
613
  type: "array",
578
614
  category: "container",
579
- description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have label, minItems, or maxItems properties. Use "fields" (not "template") to define the item template.',
615
+ description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have a label property. Use "fields" (not "template") to define the item template. Supports only \'hidden\' logic type for conditional visibility. Supports minLength/maxLength for array size validation. Each array item is rendered inside a `<div class="df-array-item">` wrapper with `role="group"`, `aria-label="Item N"` (1-based), `data-array-item-id`, and `data-array-item-index` attributes for styling, accessibility, and testing.',
580
616
  valueType: "T[]",
581
617
  baseInterface: "FieldDef",
582
618
  props: {
@@ -585,9 +621,21 @@ var field_types_default = [
585
621
  type: "ArrayAllowedChildren[]",
586
622
  description: "Template field(s) for each array item. Allowed: rows, groups, leaf fields (NOT pages or other arrays)",
587
623
  required: true
624
+ },
625
+ minLength: {
626
+ name: "minLength",
627
+ type: "number",
628
+ description: "Minimum number of items required in the array. Validation fails if fewer items.",
629
+ required: false
630
+ },
631
+ maxLength: {
632
+ name: "maxLength",
633
+ type: "number",
634
+ description: "Maximum number of items allowed in the array. Validation fails if more items.",
635
+ required: false
588
636
  }
589
637
  },
590
- validationSupported: false,
638
+ validationSupported: true,
591
639
  source: "core",
592
640
  allowedIn: ["top-level", "page", "row", "group"],
593
641
  notAllowedIn: ["array"],
@@ -611,7 +659,7 @@ var field_types_default = [
611
659
  "previous"
612
660
  ],
613
661
  cannotContain: ["page", "array"],
614
- example: "// Flat array (primitive values)\n{\n key: 'tags',\n type: 'array',\n // NOTE: Arrays do NOT have label, minItems, or maxItems\n fields: [\n { key: 'tag', type: 'input', label: 'Tag' }\n ]\n}\n// Result: { tags: ['value1', 'value2'] }\n\n// Object array (nested groups)\n{\n key: 'contacts',\n type: 'array',\n fields: [{\n type: 'group',\n fields: [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'email', type: 'input', label: 'Email' }\n ]\n }]\n}\n// Result: { contacts: [{name: '', email: ''}, ...] }",
662
+ example: "// Flat array with length validation\n{\n key: 'tags',\n type: 'array',\n minLength: 1, // At least one tag required\n maxLength: 5, // No more than 5 tags\n fields: [\n { key: 'tag', type: 'input', label: 'Tag' }\n ]\n}\n// Result: { tags: ['value1', 'value2'] }\n\n// Object array (nested groups)\n{\n key: 'contacts',\n type: 'array',\n minLength: 1,\n fields: [{\n type: 'group',\n fields: [\n { key: 'name', type: 'input', label: 'Name' },\n { key: 'email', type: 'input', label: 'Email' }\n ]\n }]\n}\n// Result: { contacts: [{name: '', email: ''}, ...] }",
615
663
  minimalExample: "{ key: 'items', type: 'array', fields: [...] }"
616
664
  },
617
665
  {
@@ -854,10 +902,30 @@ var validators_default = [
854
902
  },
855
903
  example: "// Expression-based custom validator with error message\n// The validator:\n{\n type: 'custom',\n expression: 'fieldValue === formValue.password',\n kind: 'passwordMismatch' // Just the error KIND, not the message\n}\n\n// COMPLETE FIELD with validationMessages at FIELD level:\n{\n key: 'confirmPassword',\n type: 'input',\n label: 'Confirm Password',\n props: { type: 'password' },\n validators: [\n { type: 'custom', expression: 'fieldValue === formValue.password', kind: 'passwordMismatch' }\n ],\n validationMessages: {\n passwordMismatch: 'Passwords do not match' // Message goes HERE at field level\n }\n}"
856
904
  },
905
+ {
906
+ type: "async",
907
+ category: "async",
908
+ description: "Async validator using registered async function (resource-based). Register the function via customFnConfig.asyncValidators.",
909
+ parameters: {
910
+ functionName: {
911
+ name: "functionName",
912
+ type: "string",
913
+ description: "Name of registered async validator function",
914
+ required: true
915
+ },
916
+ params: {
917
+ name: "params",
918
+ type: "Record<string, unknown>",
919
+ description: "Parameters to pass to validator function",
920
+ required: false
921
+ }
922
+ },
923
+ example: "{\n type: 'async',\n functionName: 'checkUsernameAvailability'\n}"
924
+ },
857
925
  {
858
926
  type: "customAsync",
859
927
  category: "async",
860
- description: "Async validator using registered async function",
928
+ description: "DEPRECATED \u2014 use type: 'async' instead. Async validator using registered async function.",
861
929
  parameters: {
862
930
  functionName: {
863
931
  name: "functionName",
@@ -872,12 +940,12 @@ var validators_default = [
872
940
  required: false
873
941
  }
874
942
  },
875
- example: "{\n type: 'customAsync',\n functionName: 'checkUsernameAvailability'\n}"
943
+ example: "// DEPRECATED \u2014 use type: 'async' instead\n{\n type: 'customAsync',\n functionName: 'checkUsernameAvailability'\n}"
876
944
  },
877
945
  {
878
946
  type: "customHttp",
879
947
  category: "http",
880
- description: "HTTP-based validator with automatic request cancellation",
948
+ description: "DEPRECATED \u2014 use type: 'http' with functionName instead. HTTP-based validator with automatic request cancellation.",
881
949
  parameters: {
882
950
  functionName: {
883
951
  name: "functionName",
@@ -892,7 +960,39 @@ var validators_default = [
892
960
  required: false
893
961
  }
894
962
  },
895
- example: "{\n type: 'customHttp',\n functionName: 'validateEmailExists'\n}"
963
+ example: "// DEPRECATED \u2014 use type: 'http' with functionName instead\n{\n type: 'customHttp',\n functionName: 'validateEmailExists'\n}"
964
+ },
965
+ {
966
+ type: "http",
967
+ category: "http",
968
+ description: "HTTP validator \u2014 supports two modes: (1) Declarative (fully JSON-serializable, no function registration) using http + responseMapping properties, or (2) Function-based using functionName to reference a registered HTTP validator function. Query param values and (optionally) body values are expressions evaluated against the form context. Response mapping uses validWhen (truthy = valid) and errorKind (maps to field-level validationMessages).",
969
+ parameters: {
970
+ functionName: {
971
+ name: "functionName",
972
+ type: "string",
973
+ description: "Name of registered HTTP validator function (function-based mode). Mutually exclusive with http + responseMapping.",
974
+ required: false
975
+ },
976
+ http: {
977
+ name: "http",
978
+ type: "HttpRequestConfig",
979
+ description: "HTTP request configuration: { url, method?, queryParams?, body?, evaluateBodyExpressions?, headers?, debounceMs? }. queryParams values are expressions. When evaluateBodyExpressions is true, top-level string values in body are evaluated as expressions (shallow only). Required for declarative mode.",
980
+ required: false
981
+ },
982
+ responseMapping: {
983
+ name: "responseMapping",
984
+ type: "HttpValidationResponseMapping",
985
+ description: "Response mapping: { validWhen, errorKind, errorParams? }. validWhen is an expression evaluated with { response } scope \u2014 truthy means valid. errorKind maps to field-level validationMessages. Required for declarative mode.",
986
+ required: false
987
+ },
988
+ params: {
989
+ name: "params",
990
+ type: "Record<string, unknown>",
991
+ description: "Parameters to pass to HTTP validator function (function-based mode only).",
992
+ required: false
993
+ }
994
+ },
995
+ example: "// HTTP validator (fully JSON-serializable)\n{\n type: 'http',\n http: {\n url: '/api/validate-username',\n method: 'GET',\n queryParams: {\n username: 'fieldValue'\n }\n },\n responseMapping: {\n validWhen: 'response.available',\n errorKind: 'usernameTaken',\n errorParams: {\n suggestion: 'response.suggestion'\n }\n }\n}\n\n// COMPLETE FIELD with validationMessages at FIELD level:\n{\n key: 'username',\n type: 'input',\n label: 'Username',\n validators: [\n {\n type: 'http',\n http: {\n url: '/api/validate-username',\n method: 'GET',\n queryParams: { username: 'fieldValue' }\n },\n responseMapping: {\n validWhen: 'response.available',\n errorKind: 'usernameTaken',\n errorParams: { suggestion: 'response.suggestion' }\n }\n }\n ],\n validationMessages: {\n usernameTaken: 'Username is taken. Try {{suggestion}}'\n }\n}"
896
996
  }
897
997
  ];
898
998
 
@@ -1700,13 +1800,13 @@ Use when you need nested object structure in form values:
1700
1800
 
1701
1801
  #### Array (Repeatable Items)
1702
1802
 
1703
- Use for dynamic lists:
1803
+ Use for dynamic lists. Each item is wrapped in a \`<div class="df-array-item">\` with \`role="group"\` and \`aria-label="Item N"\` for accessibility. Use \`--df-array-item-gap\` CSS variable to control spacing between items.
1704
1804
 
1705
1805
  \`\`\`typescript
1706
1806
  {
1707
1807
  key: 'contacts',
1708
1808
  type: 'array',
1709
- label: 'Emergency Contacts',
1809
+ // \u26A0\uFE0F NO label property on arrays!
1710
1810
  fields: [
1711
1811
  {
1712
1812
  key: 'contact',
@@ -3089,7 +3189,22 @@ var BaseFieldDefSchema = z14.object({
3089
3189
  /**
3090
3190
  * Grid column width (1-12) in a 12-column layout system.
3091
3191
  */
3092
- col: z14.number().min(1).max(12).optional()
3192
+ col: z14.number().min(1).max(12).optional(),
3193
+ /**
3194
+ * Whether to exclude this field's value from submission output when hidden.
3195
+ * Overrides both the global and form-level settings.
3196
+ */
3197
+ excludeValueIfHidden: z14.boolean().optional(),
3198
+ /**
3199
+ * Whether to exclude this field's value from submission output when disabled.
3200
+ * Overrides both the global and form-level settings.
3201
+ */
3202
+ excludeValueIfDisabled: z14.boolean().optional(),
3203
+ /**
3204
+ * Whether to exclude this field's value from submission output when readonly.
3205
+ * Overrides both the global and form-level settings.
3206
+ */
3207
+ excludeValueIfReadonly: z14.boolean().optional()
3093
3208
  });
3094
3209
 
3095
3210
  // internal/dynamic-forms-zod/src/lib/schemas/field/field-with-validation.schema.ts
@@ -3832,7 +3947,10 @@ var HiddenFieldSchema = BaseFieldDefSchema.omit({
3832
3947
  readonly: true,
3833
3948
  hidden: true,
3834
3949
  tabIndex: true,
3835
- col: true
3950
+ col: true,
3951
+ excludeValueIfHidden: true,
3952
+ excludeValueIfDisabled: true,
3953
+ excludeValueIfReadonly: true
3836
3954
  }).extend({
3837
3955
  /**
3838
3956
  * Field type discriminant.
@@ -3870,7 +3988,7 @@ var MatLeafFieldSchema = z35.discriminatedUnion("type", [
3870
3988
 
3871
3989
  // internal/dynamic-forms-zod/src/lib/schemas/containers/factories.ts
3872
3990
  import { z as z36 } from "zod";
3873
- var PageLogicSchema = z36.object({
3991
+ var ContainerLogicSchema = z36.object({
3874
3992
  type: z36.literal("hidden"),
3875
3993
  condition: z36.union([ConditionalExpressionSchema, z36.boolean()])
3876
3994
  });
@@ -3897,31 +4015,61 @@ function createContainerSchemas(options) {
3897
4015
  const PageFieldSchema = ContainerBaseSchema.extend({
3898
4016
  type: z36.literal("page"),
3899
4017
  fields: z36.array(AnyFieldSchema),
3900
- logic: z36.array(PageLogicSchema).optional(),
4018
+ logic: z36.array(ContainerLogicSchema).optional(),
3901
4019
  // Also forbid title (common mistake)
3902
4020
  title: z36.never().optional()
3903
4021
  });
3904
4022
  const RowFieldSchema = ContainerBaseSchema.extend({
3905
4023
  type: z36.literal("row"),
3906
4024
  fields: z36.array(AnyFieldSchema),
3907
- // Explicitly forbid logic on rows
3908
- logic: z36.never().optional()
4025
+ // Container logic - only 'hidden' type allowed (same as pages)
4026
+ logic: z36.array(ContainerLogicSchema).optional()
3909
4027
  });
3910
4028
  const GroupFieldSchema = ContainerBaseSchema.extend({
3911
4029
  type: z36.literal("group"),
3912
4030
  fields: z36.array(AnyFieldSchema),
3913
- // Explicitly forbid logic on groups
3914
- logic: z36.never().optional()
4031
+ // Container logic - only 'hidden' type allowed (same as pages)
4032
+ logic: z36.array(ContainerLogicSchema).optional()
3915
4033
  });
3916
- const ArrayFieldSchema = ContainerBaseSchema.extend({
4034
+ const ArrayButtonConfigSchema = z36.object({
4035
+ label: z36.string().optional(),
4036
+ props: z36.record(z36.unknown()).optional()
4037
+ });
4038
+ const FullArrayFieldSchema = ContainerBaseSchema.extend({
3917
4039
  type: z36.literal("array"),
3918
4040
  fields: z36.array(AnyFieldSchema),
3919
- // Explicitly forbid logic on arrays
3920
- logic: z36.never().optional(),
4041
+ logic: z36.array(ContainerLogicSchema).optional(),
4042
+ // Full API does not use template
3921
4043
  template: z36.never().optional(),
4044
+ // Array length validation
4045
+ minLength: z36.number().int().min(0).optional(),
4046
+ maxLength: z36.number().int().min(0).optional()
4047
+ });
4048
+ const ArrayAllowedChildSchema = z36.lazy(
4049
+ () => AnyFieldSchema.refine((field) => field.type !== "page" && field.type !== "array", {
4050
+ message: "Array templates cannot contain page or array fields. Only leaf fields, rows, and groups are allowed."
4051
+ })
4052
+ );
4053
+ const SimplifiedArrayFieldSchema = ContainerBaseSchema.extend({
4054
+ type: z36.literal("array"),
4055
+ // Template: single field (primitive array) or array of fields (object array)
4056
+ // Only ArrayAllowedChildren (leaf fields, rows, groups) are valid — no pages or nested arrays.
4057
+ template: z36.union([ArrayAllowedChildSchema, z36.array(ArrayAllowedChildSchema)]),
4058
+ // Initial values for the array
4059
+ value: z36.array(z36.unknown()).optional(),
4060
+ // Button customization or opt-out (false to disable)
4061
+ addButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
4062
+ removeButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
4063
+ logic: z36.array(ContainerLogicSchema).optional(),
4064
+ // Array length validation
4065
+ minLength: z36.number().int().min(0).optional(),
4066
+ maxLength: z36.number().int().min(0).optional(),
4067
+ // Simplified API does not use fields
4068
+ fields: z36.never().optional(),
3922
4069
  minItems: z36.never().optional(),
3923
4070
  maxItems: z36.never().optional()
3924
4071
  });
4072
+ const ArrayFieldSchema = z36.union([FullArrayFieldSchema, SimplifiedArrayFieldSchema]);
3925
4073
  const AllFieldsSchema = AnyFieldSchema;
3926
4074
  return {
3927
4075
  PageFieldSchema,
@@ -3992,7 +4140,22 @@ var FormOptionsSchema = z37.object({
3992
4140
  /**
3993
4141
  * Options for the next button behavior (multi-page forms).
3994
4142
  */
3995
- nextButton: NextButtonOptionsSchema.optional()
4143
+ nextButton: NextButtonOptionsSchema.optional(),
4144
+ /**
4145
+ * Whether to exclude values of hidden fields from submission output.
4146
+ * Overrides the global withValueExclusionDefaults() setting for this form.
4147
+ */
4148
+ excludeValueIfHidden: z37.boolean().optional(),
4149
+ /**
4150
+ * Whether to exclude values of disabled fields from submission output.
4151
+ * Overrides the global withValueExclusionDefaults() setting for this form.
4152
+ */
4153
+ excludeValueIfDisabled: z37.boolean().optional(),
4154
+ /**
4155
+ * Whether to exclude values of readonly fields from submission output.
4156
+ * Overrides the global withValueExclusionDefaults() setting for this form.
4157
+ */
4158
+ excludeValueIfReadonly: z37.boolean().optional()
3996
4159
  });
3997
4160
 
3998
4161
  // internal/dynamic-forms-zod/src/lib/schemas/form/schema-definition.schema.ts
@@ -4930,13 +5093,11 @@ var PROPERTY_GUIDANCE = {
4930
5093
  maxValue: "maxValue should be at FIELD level, not inside props",
4931
5094
  step: "step should be at FIELD level, not inside props (for slider)",
4932
5095
  fields: "fields should be at FIELD level, contains child fields for containers",
4933
- template: 'Use "fields" instead of "template" for array items',
5096
+ template: "Arrays support two APIs: (1) Full API with `fields` for explicit item definitions, or (2) Simplified API with `template` + `value` for common cases. `fields` and `template` are mutually exclusive.",
4934
5097
  label: "Container types (row, group, array, page) do NOT have a label property",
4935
5098
  title: "Page fields do NOT have a title property",
4936
- minItems: "Array fields do NOT have minItems/maxItems properties",
4937
- maxItems: "Array fields do NOT have minItems/maxItems properties",
4938
5099
  expressions: 'Use "derivation" or "logic" instead of "expressions"',
4939
- logic: "Only PAGE and LEAF fields support logic blocks. Row, group, and array containers do NOT support logic - apply logic to their child fields instead"
5100
+ logic: 'Container fields (page, group, row, array) only support the "hidden" logic type. For other logic types (disabled, required, readonly, derivation), apply them to child fields instead'
4940
5101
  };
4941
5102
  var DID_YOU_MEAN = {
4942
5103
  hideWhen: 'Did you mean `logic: [{ type: "hidden", condition: {...} }]`? There is no hideWhen shorthand.',
@@ -4955,7 +5116,7 @@ var DID_YOU_MEAN = {
4955
5116
  min: "Did you mean `minValue` at field level (for slider) or `min` shorthand validator (for numbers)?",
4956
5117
  max: "Did you mean `maxValue` at field level (for slider) or `max` shorthand validator (for numbers)?",
4957
5118
  items: "Did you mean `options` for select/radio/multi-checkbox, or `fields` for array containers?",
4958
- template: "Did you mean `fields`? Arrays use `fields` to define the template for each item.",
5119
+ template: "Arrays support `template` (simplified API) or `fields` (full API). If using `template`, also provide `value` for initial data. They are mutually exclusive - do not use both.",
4959
5120
  element: 'Did you mean `props: { elementType: "..." }`? For text fields, use elementType inside props.',
4960
5121
  content: "Did you mean `label`? For text fields, the content goes in the label property.",
4961
5122
  title: 'Did you mean to use a `text` field with `label: "..." and props: { elementType: "h1" }`? Pages don\'t have titles.',
@@ -5004,11 +5165,24 @@ function formatZodError(error, config) {
5004
5165
  mistakes.push("Use minValue/maxValue/step at field level, not min/max/step in props");
5005
5166
  }
5006
5167
  }
5007
- if (["array", "group", "row", "page"].includes(fieldType) && "template" in field) {
5168
+ if (["group", "row", "page"].includes(fieldType) && "template" in field) {
5008
5169
  mistakes.push('Use "fields" instead of "template"');
5009
5170
  }
5171
+ if (fieldType === "array" && "template" in field && "fields" in field) {
5172
+ mistakes.push('"fields" and "template" are mutually exclusive on arrays. Use one or the other.');
5173
+ }
5010
5174
  if (["row", "group", "array"].includes(fieldType) && "logic" in field) {
5011
- mistakes.push(`"${fieldType}" containers do NOT support logic blocks - apply logic to individual child fields instead`);
5175
+ const logicArr = field["logic"];
5176
+ if (Array.isArray(logicArr)) {
5177
+ const nonHidden = logicArr.filter(
5178
+ (l) => l && typeof l === "object" && l["type"] !== "hidden"
5179
+ );
5180
+ if (nonHidden.length > 0) {
5181
+ mistakes.push(
5182
+ `"${fieldType}" containers only support 'hidden' logic type - for other logic types, apply to child fields instead`
5183
+ );
5184
+ }
5185
+ }
5012
5186
  }
5013
5187
  if (fieldType === "hidden") {
5014
5188
  if (!("value" in field)) {
@@ -5022,6 +5196,7 @@ function formatZodError(error, config) {
5022
5196
  }
5023
5197
  for (const [wrongProp, suggestion] of Object.entries(DID_YOU_MEAN)) {
5024
5198
  if (wrongProp in field) {
5199
+ if (wrongProp === "template" && fieldType === "array") continue;
5025
5200
  mistakes.push(suggestion);
5026
5201
  }
5027
5202
  }
@@ -5200,7 +5375,7 @@ var EXPECTED_STRUCTURE = {
5200
5375
  slider: `{ key: 'fieldKey', type: 'slider', label: 'Label', minValue: 0, maxValue: 100, step: 1 }`,
5201
5376
  row: `{ key: 'rowKey', type: 'row', fields: [...childFields] }`,
5202
5377
  group: `{ key: 'groupKey', type: 'group', fields: [...childFields] }`,
5203
- array: `{ key: 'arrayKey', type: 'array', fields: [...templateFields] }`,
5378
+ array: `Full API: { key: 'arrayKey', type: 'array', fields: [...itemDefs] } OR Simplified API: { key: 'arrayKey', type: 'array', template: { type: 'input', label: 'Item' }, value: [] }`,
5204
5379
  page: `{ key: 'pageKey', type: 'page', fields: [...childFields, { key: 'next', type: 'next', label: 'Next' }] }`
5205
5380
  };
5206
5381
  function preValidateConfig(config) {
@@ -5257,6 +5432,9 @@ function preValidateConfig(config) {
5257
5432
  }
5258
5433
  for (const prop of CONTAINER_FORBIDDEN_PROPS) {
5259
5434
  if (prop in f) {
5435
+ if (prop === "value" && fieldType === "array" && "template" in f) {
5436
+ continue;
5437
+ }
5260
5438
  const expected = EXPECTED_STRUCTURE[fieldType || ""] || "";
5261
5439
  errors.push({
5262
5440
  path: `${path}.${prop}`,
@@ -5264,11 +5442,17 @@ function preValidateConfig(config) {
5264
5442
  });
5265
5443
  }
5266
5444
  }
5267
- if ("logic" in f) {
5268
- errors.push({
5269
- path: `${path}.logic`,
5270
- message: `"${fieldType}" containers do NOT support logic blocks. Only PAGE and LEAF fields (input, select, etc.) support logic. Apply logic to individual child fields instead.`
5271
- });
5445
+ if ("logic" in f && Array.isArray(f["logic"])) {
5446
+ const nonHiddenLogic = f["logic"].filter(
5447
+ (l) => l && typeof l === "object" && l["type"] !== "hidden"
5448
+ );
5449
+ if (nonHiddenLogic.length > 0) {
5450
+ const invalidTypes = nonHiddenLogic.map((l) => `"${l["type"]}"`).join(", ");
5451
+ errors.push({
5452
+ path: `${path}.logic`,
5453
+ message: `"${fieldType}" containers only support 'hidden' logic type. Found unsupported logic types: ${invalidTypes}. For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.`
5454
+ });
5455
+ }
5272
5456
  }
5273
5457
  }
5274
5458
  if (fieldType === "page") {
@@ -5368,7 +5552,7 @@ function preValidateConfig(config) {
5368
5552
  });
5369
5553
  }
5370
5554
  }
5371
- if (["row", "group", "array", "page"].includes(fieldType || "")) {
5555
+ if (["row", "group", "page"].includes(fieldType || "")) {
5372
5556
  if (!("fields" in f)) {
5373
5557
  errors.push({
5374
5558
  path: `${path}.fields`,
@@ -5381,12 +5565,42 @@ function preValidateConfig(config) {
5381
5565
  });
5382
5566
  }
5383
5567
  }
5568
+ if (fieldType === "array") {
5569
+ const hasFields = "fields" in f;
5570
+ const hasTemplate = "template" in f;
5571
+ if (hasFields && hasTemplate) {
5572
+ errors.push({
5573
+ path,
5574
+ message: `Array "${fieldKey || "unknown"}" has BOTH "fields" and "template". These are mutually exclusive. Use "fields" for the full API or "template" + "value" for the simplified API. ${EXPECTED_STRUCTURE["array"]}`
5575
+ });
5576
+ } else if (!hasFields && !hasTemplate) {
5577
+ errors.push({
5578
+ path,
5579
+ message: `Array "${fieldKey || "unknown"}" is MISSING both "fields" and "template". Use "fields" (full API) or "template" + "value" (simplified API). ${EXPECTED_STRUCTURE["array"]}`
5580
+ });
5581
+ } else if (hasFields && !Array.isArray(f["fields"])) {
5582
+ errors.push({
5583
+ path: `${path}.fields`,
5584
+ message: `Array "${fieldKey || "unknown"}" has invalid "fields" - must be an array of field objects, not ${typeof f["fields"]}.`
5585
+ });
5586
+ }
5587
+ }
5384
5588
  const childFields = f["fields"];
5385
5589
  if (Array.isArray(childFields)) {
5386
5590
  childFields.forEach((child, idx) => {
5387
5591
  checkField(child, `${path}.fields[${idx}]`, fieldType);
5388
5592
  });
5389
5593
  }
5594
+ if (fieldType === "array" && "template" in f) {
5595
+ const template = f["template"];
5596
+ if (Array.isArray(template)) {
5597
+ template.forEach((child, idx) => {
5598
+ checkField(child, `${path}.template[${idx}]`, fieldType);
5599
+ });
5600
+ } else if (template && typeof template === "object") {
5601
+ checkField(template, `${path}.template`, fieldType);
5602
+ }
5603
+ }
5390
5604
  }
5391
5605
  fields.forEach((field, idx) => {
5392
5606
  checkField(field, `fields[${idx}]`, void 0);
@@ -5764,14 +5978,15 @@ Included in form value but not rendered.
5764
5978
  brief: `\`\`\`typescript
5765
5979
  { key: 'address', type: 'group', fields: [{ key: 'city', type: 'input', label: 'City' }] }
5766
5980
  \`\`\`
5767
- \u26A0\uFE0F **NO label, NO logic** - creates nested object { address: { city: '...' } }`,
5981
+ \u26A0\uFE0F **NO label** - supports only \`hidden\` logic - creates nested object { address: { city: '...' } }`,
5768
5982
  full: `# Group Container (Nested Object)
5769
5983
 
5770
5984
  \`\`\`typescript
5771
5985
  {
5772
5986
  key: 'address',
5773
5987
  type: 'group',
5774
- // \u26A0\uFE0F NO LABEL! NO LOGIC!
5988
+ // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
5989
+ logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showAddress', operator: 'equals', value: false } }],
5775
5990
  fields: [
5776
5991
  { key: 'street', type: 'input', label: 'Street' },
5777
5992
  { key: 'city', type: 'input', label: 'City' }
@@ -5782,7 +5997,7 @@ Included in form value but not rendered.
5782
5997
 
5783
5998
  **\u26A0\uFE0F Common mistakes:**
5784
5999
  - Adding \`label\` to group (not allowed)
5785
- - Adding \`logic\` to group (apply to child fields instead)
6000
+ - Using non-hidden logic types on group (only \`hidden\` is supported, apply other logic types to child fields instead)
5786
6001
 
5787
6002
  **Can contain:** rows, leaf fields (NOT pages, NOT nested groups)`
5788
6003
  },
@@ -5790,14 +6005,15 @@ Included in form value but not rendered.
5790
6005
  brief: `\`\`\`typescript
5791
6006
  { key: 'nameRow', type: 'row', fields: [{ key: 'first', type: 'input', label: 'First', col: 6 }, { key: 'last', type: 'input', label: 'Last', col: 6 }] }
5792
6007
  \`\`\`
5793
- \u26A0\uFE0F **NO label, NO logic, NO hidden fields inside**`,
6008
+ \u26A0\uFE0F **NO label, NO hidden fields inside** - supports only \`hidden\` logic type`,
5794
6009
  full: `# Row Container (Horizontal Layout)
5795
6010
 
5796
6011
  \`\`\`typescript
5797
6012
  {
5798
6013
  key: 'nameRow',
5799
6014
  type: 'row',
5800
- // \u26A0\uFE0F NO LABEL! NO LOGIC!
6015
+ // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
6016
+ logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showNameRow', operator: 'equals', value: false } }],
5801
6017
  fields: [
5802
6018
  { key: 'firstName', type: 'input', label: 'First', col: 6 },
5803
6019
  { key: 'lastName', type: 'input', label: 'Last', col: 6 }
@@ -5805,7 +6021,7 @@ Included in form value but not rendered.
5805
6021
  }
5806
6022
  \`\`\`
5807
6023
 
5808
- Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
6024
+ Use \`col\` (1-12) on child fields for grid width. Row is purely for layout. Supports only \`hidden\` logic type for conditional visibility.
5809
6025
 
5810
6026
  **Allowed children:** groups, arrays, value fields (input, select, checkbox, etc.)
5811
6027
  **NOT allowed:** \`hidden\` fields, \`page\` containers, nested \`row\` containers
@@ -5813,36 +6029,250 @@ Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
5813
6029
  \u26A0\uFE0F **Common mistake:** Putting hidden fields inside rows - hidden fields should be at page or form level, not in rows.`
5814
6030
  },
5815
6031
  array: {
5816
- brief: `\`\`\`typescript
5817
- { key: 'contacts', type: 'array', fields: [{ key: 'item', type: 'group', fields: [{ key: 'name', type: 'input', label: 'Name' }] }] }
5818
- \`\`\`
5819
- \u26A0\uFE0F Uses **fields** NOT template, **NO label, NO logic**`,
6032
+ brief: `**Two APIs available:**
6033
+ **Simplified (recommended):** \`{ key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }\`
6034
+ **Full:** \`{ key: 'contacts', type: 'array', fields: [[{ key: 'name', type: 'input', value: 'Alice' }]] }\`
6035
+ \u26A0\uFE0F **NO label** - supports only \`hidden\` logic type. See topic \`simplified-array\` for the simplified API.`,
5820
6036
  full: `# Array Container (Dynamic List)
5821
6037
 
6038
+ Arrays support two APIs: **Simplified** (recommended for common cases) and **Full** (for advanced use cases).
6039
+
6040
+ ## Simplified API (Recommended)
6041
+
6042
+ Use \`template\` + \`value\` for common array patterns. Add/remove buttons are auto-generated.
6043
+
6044
+ \`\`\`typescript
6045
+ // Primitive array: ['angular', 'typescript']
6046
+ {
6047
+ key: 'tags',
6048
+ type: 'array',
6049
+ template: { key: 'value', type: 'input', label: 'Tag' },
6050
+ value: ['angular', 'typescript']
6051
+ }
6052
+
6053
+ // Object array: [{ name: 'Jane', phone: '555' }]
6054
+ {
6055
+ key: 'contacts',
6056
+ type: 'array',
6057
+ template: [
6058
+ { key: 'name', type: 'input', label: 'Name', required: true },
6059
+ { key: 'phone', type: 'input', label: 'Phone' }
6060
+ ],
6061
+ value: [{ name: 'Jane', phone: '555' }]
6062
+ }
6063
+
6064
+ // Custom button config
6065
+ {
6066
+ key: 'items',
6067
+ type: 'array',
6068
+ template: { key: 'value', type: 'input', label: 'Item' },
6069
+ addButton: { label: 'Add Item', props: { color: 'primary' } },
6070
+ removeButton: false // Disable remove buttons
6071
+ }
6072
+ \`\`\`
6073
+
6074
+ See topic \`simplified-array\` for full documentation on the simplified API.
6075
+
6076
+ ## Full API (Advanced)
6077
+
6078
+ Use \`fields\` for explicit item definitions with full control.
6079
+
5822
6080
  \`\`\`typescript
5823
6081
  {
5824
6082
  key: 'contacts',
5825
6083
  type: 'array',
5826
- // \u26A0\uFE0F NO LABEL! NO LOGIC! Uses 'fields', NOT 'template'!
6084
+ // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
6085
+ logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'hasContacts', operator: 'equals', value: false } }],
5827
6086
  fields: [
5828
- {
5829
- key: 'contactItem',
5830
- type: 'group',
5831
- fields: [
5832
- { key: 'name', type: 'input', label: 'Name' },
5833
- { key: 'phone', type: 'input', label: 'Phone' }
5834
- ]
5835
- }
6087
+ [
6088
+ { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
6089
+ { key: 'phone', type: 'input', label: 'Phone', value: '555' }
6090
+ ]
5836
6091
  ]
5837
6092
  }
5838
- // Output: { contacts: [{ name: '...', phone: '...' }, ...] }
6093
+ // Output: { contacts: [{ name: 'Alice', phone: '555' }] }
5839
6094
  \`\`\`
5840
6095
 
5841
- **\u26A0\uFE0F Common mistakes:**
5842
- - Using \`template\` (doesn't exist) - use \`fields\`
5843
- - Adding \`label\` or \`logic\` to array container
6096
+ **DOM Structure:**
6097
+ Each array item is wrapped in a \`<div class="df-array-item">\` with:
6098
+ - \`role="group"\` + \`aria-label="Item N"\` (1-based) for accessibility
6099
+ - \`data-array-item-id\` (stable ID) and \`data-array-item-index\` (current position) for testing/CSS
6100
+ - Use \`--df-array-item-gap\` CSS variable to control spacing between items
6101
+
6102
+ **Key rules:**
6103
+ - \`fields\` and \`template\` are **mutually exclusive** - use one or the other
6104
+ - NO \`label\` property on arrays
6105
+ - Only \`hidden\` logic type is supported
6106
+ - Arrays cannot contain pages or other arrays
5844
6107
 
5845
6108
  **Can contain:** rows, groups, leaf fields (NOT pages, NOT nested arrays)`
6109
+ },
6110
+ "simplified-array": {
6111
+ brief: `\`\`\`typescript
6112
+ // Primitive: { key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }
6113
+ // Object: { key: 'contacts', type: 'array', template: [{ key: 'name', type: 'input' }, { key: 'phone', type: 'input' }], value: [{ name: 'Jane', phone: '555' }] }
6114
+ // Buttons: { addButton: { label: 'Add Tag', props: { color: 'primary' } }, removeButton: false }
6115
+ \`\`\`
6116
+ Discriminant: \`template\` presence = simplified API; \`Array.isArray(template)\` = object vs primitive.`,
6117
+ full: `# Simplified Array API
6118
+
6119
+ The simplified array API provides a concise way to define dynamic arrays using \`template\` + \`value\` instead of verbose \`fields\` definitions. Add/remove buttons are auto-generated.
6120
+
6121
+ ## When to Use
6122
+
6123
+ Use the simplified API when:
6124
+ - You have a common primitive or object array pattern
6125
+ - You want auto-generated add/remove buttons
6126
+ - Initial values are known and simple
6127
+
6128
+ Use the full API (\`fields\`) when:
6129
+ - You need heterogeneous items (different field configs per item)
6130
+ - You need custom button placement
6131
+ - You need explicit control over each item's structure
6132
+
6133
+ ## Primitive Array
6134
+
6135
+ Each item is a single value (string, number, etc.):
6136
+
6137
+ \`\`\`typescript
6138
+ {
6139
+ key: 'tags',
6140
+ type: 'array',
6141
+ template: { key: 'value', type: 'input', label: 'Tag', required: true },
6142
+ value: ['angular', 'typescript']
6143
+ }
6144
+ // Output: { tags: ['angular', 'typescript'] }
6145
+ \`\`\`
6146
+
6147
+ **Discriminant:** \`template\` is a single field definition (not an array).
6148
+
6149
+ ## Object Array
6150
+
6151
+ Each item is an object with multiple fields:
6152
+
6153
+ \`\`\`typescript
6154
+ {
6155
+ key: 'contacts',
6156
+ type: 'array',
6157
+ template: [
6158
+ { key: 'name', type: 'input', label: 'Contact Name', required: true },
6159
+ { key: 'phone', type: 'input', label: 'Phone Number' }
6160
+ ],
6161
+ value: [
6162
+ { name: 'Jane Doe', phone: '555-1234' },
6163
+ { name: 'John Smith', phone: '555-5678' }
6164
+ ]
6165
+ }
6166
+ // Output: { contacts: [{ name: 'Jane Doe', phone: '555-1234' }, ...] }
6167
+ \`\`\`
6168
+
6169
+ **Discriminant:** \`template\` is an array of field definitions.
6170
+
6171
+ ## Button Configuration
6172
+
6173
+ ### Custom Add Button
6174
+ \`\`\`typescript
6175
+ {
6176
+ key: 'tags',
6177
+ type: 'array',
6178
+ template: { key: 'value', type: 'input', label: 'Tag' },
6179
+ addButton: {
6180
+ label: 'Add New Tag',
6181
+ props: { color: 'primary' }
6182
+ }
6183
+ }
6184
+ \`\`\`
6185
+
6186
+ ### Custom Remove Button
6187
+ \`\`\`typescript
6188
+ {
6189
+ key: 'items',
6190
+ type: 'array',
6191
+ template: { key: 'value', type: 'input', label: 'Item' },
6192
+ removeButton: {
6193
+ label: 'Delete',
6194
+ props: { color: 'warn' }
6195
+ }
6196
+ }
6197
+ \`\`\`
6198
+
6199
+ ### Disable Buttons
6200
+ \`\`\`typescript
6201
+ {
6202
+ key: 'tags',
6203
+ type: 'array',
6204
+ template: { key: 'value', type: 'input', label: 'Tag' },
6205
+ addButton: false, // No add button
6206
+ removeButton: false // No remove button per item
6207
+ }
6208
+ \`\`\`
6209
+
6210
+ ## ArrayButtonConfig Interface
6211
+
6212
+ \`\`\`typescript
6213
+ interface ArrayButtonConfig {
6214
+ label?: string; // Custom button label
6215
+ props?: Record<string, unknown>; // Additional button component properties
6216
+ }
6217
+ \`\`\`
6218
+
6219
+ ## SimplifiedArrayField Interface
6220
+
6221
+ \`\`\`typescript
6222
+ interface SimplifiedArrayField {
6223
+ type: 'array';
6224
+ key: string;
6225
+ template: ArrayAllowedChildren | readonly ArrayAllowedChildren[]; // Item structure
6226
+ value?: readonly unknown[]; // Initial values
6227
+ addButton?: ArrayButtonConfig | false; // Add button config (default: { label: 'Add' })
6228
+ removeButton?: ArrayButtonConfig | false; // Remove button config (default: { label: 'Remove' })
6229
+ logic?: ContainerLogicConfig[]; // Only 'hidden' type supported
6230
+ // label is NOT supported
6231
+ // fields is NOT supported (mutually exclusive with template)
6232
+ }
6233
+ \`\`\`
6234
+
6235
+ ## How It Works Internally
6236
+
6237
+ The simplified API is normalized into the full API at runtime:
6238
+ 1. Each \`value\` element creates an item using the \`template\` structure
6239
+ 2. An \`addArrayItem\` button is auto-generated after the array (unless \`addButton: false\`)
6240
+ 3. A \`removeArrayItem\` button is added to each item (unless \`removeButton: false\`)
6241
+
6242
+ ## Conditional Visibility
6243
+
6244
+ \`\`\`typescript
6245
+ {
6246
+ key: 'tags',
6247
+ type: 'array',
6248
+ template: { key: 'value', type: 'input', label: 'Tag' },
6249
+ logic: [{
6250
+ type: 'hidden',
6251
+ condition: { type: 'fieldValue', fieldPath: 'hasTags', operator: 'equals', value: false }
6252
+ }]
6253
+ }
6254
+ \`\`\`
6255
+
6256
+ ## Common Mistakes
6257
+
6258
+ \u274C Mixing \`fields\` and \`template\`:
6259
+ \`\`\`typescript
6260
+ // WRONG - mutually exclusive
6261
+ { type: 'array', fields: [...], template: {...} }
6262
+
6263
+ // CORRECT - use one or the other
6264
+ { type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a'] }
6265
+ { type: 'array', fields: [{ key: 'tag', type: 'input', value: 'a' }] }
6266
+ \`\`\`
6267
+
6268
+ \u274C Wrong value shape for object templates:
6269
+ \`\`\`typescript
6270
+ // WRONG - value should match template keys
6271
+ { template: [{ key: 'name', type: 'input' }], value: ['Jane'] }
6272
+
6273
+ // CORRECT - value elements are objects matching template keys
6274
+ { template: [{ key: 'name', type: 'input' }], value: [{ name: 'Jane' }] }
6275
+ \`\`\``
5846
6276
  },
5847
6277
  page: {
5848
6278
  brief: `\`\`\`typescript
@@ -5919,7 +6349,7 @@ Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
5919
6349
 
5920
6350
  **Async validators:**
5921
6351
  \`\`\`typescript
5922
- validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
6352
+ validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
5923
6353
  \`\`\`
5924
6354
 
5925
6355
  **Custom error messages (validationMessages at FIELD level):**
@@ -6006,9 +6436,16 @@ See topic \`external-data\` for full documentation.`
6006
6436
 
6007
6437
  // Logic block (for conditions, debounce, etc.)
6008
6438
  logic: [{ type: 'derivation', expression: 'formValue.firstName + " " + formValue.lastName' }]
6439
+
6440
+ // Stop on user edit (with optional re-engagement)
6441
+ logic: [{ type: 'derivation', expression: '...', stopOnUserOverride: true, reEngageOnDependencyChange: true }]
6442
+
6443
+ // HTTP derivation (server-driven values)
6444
+ logic: [{ type: 'derivation', source: 'http', http: { url: '/api/rate', queryParams: { from: 'formValue.currency' } }, responseExpression: 'response.rate', dependsOn: ['currency'] }]
6009
6445
  \`\`\`
6010
6446
  Derivation is always defined ON the field that receives the computed value (self-targeting).
6011
- **Variables:** \`formValue\`, \`fieldValue\`, \`externalData\` (see topic: external-data)`,
6447
+ **Variables:** \`formValue\`, \`fieldValue\`, \`fieldState\`, \`formFieldState\`, \`externalData\` (see topic: expression-variables)
6448
+ **For deriving component properties** (minDate, options, label): use \`targetProperty\` (see topic \`property-derivation\`)`,
6012
6449
  full: `# Value Derivation (Computed Fields)
6013
6450
 
6014
6451
  Derivations are always defined ON the field that receives the computed value (self-targeting).
@@ -6070,39 +6507,172 @@ Derivations are always defined ON the field that receives the computed value (se
6070
6507
  }
6071
6508
  \`\`\`
6072
6509
 
6073
- **Variables in expressions:**
6074
- - \`formValue\`: Complete form value object
6075
- - \`fieldValue\`: This field's current value
6076
- - \`externalData\`: External application state (user roles, feature flags, etc.)
6510
+ ## HTTP Derivation (Server-Driven Values)
6077
6511
 
6078
- **Nested access:**
6079
- \`\`\`typescript
6080
- derivation: 'formValue.address?.city' // Optional chaining
6081
- derivation: 'formValue.items?.[0]?.name' // Array access
6082
- derivation: 'formValue.discount ?? 0' // Nullish coalescing
6083
- derivation: 'formValue.price * (1 - externalData.discountRate)' // External data
6084
- \`\`\`
6512
+ Fetch derived values from an HTTP endpoint. Requires \`dependsOn\` (explicit) and \`responseExpression\`.
6085
6513
 
6086
- **Complex logic (IIFE):**
6087
6514
  \`\`\`typescript
6088
- derivation: \`(() => {
6089
- const qty = formValue.quantity || 0;
6090
- const price = formValue.unitPrice || 0;
6091
- return qty * price;
6092
- })()\`
6093
- \`\`\``
6094
- },
6095
- "options-format": {
6096
- brief: `\`\`\`typescript
6097
- options: [{ label: 'Display Text', value: 'actual-value' }] // AT FIELD LEVEL!
6515
+ {
6516
+ key: 'exchangeRate',
6517
+ type: 'input',
6518
+ label: 'Exchange Rate',
6519
+ readonly: true,
6520
+ logic: [{
6521
+ type: 'derivation',
6522
+ source: 'http',
6523
+ http: {
6524
+ url: '/api/exchange-rate',
6525
+ method: 'GET',
6526
+ queryParams: {
6527
+ from: 'formValue.sourceCurrency',
6528
+ to: 'formValue.targetCurrency'
6529
+ }
6530
+ },
6531
+ responseExpression: 'response.rate', // Extract value from response
6532
+ dependsOn: ['sourceCurrency', 'targetCurrency'], // Required for HTTP
6533
+ trigger: 'debounced',
6534
+ debounceMs: 500 // Optional, defaults to 300
6535
+ }]
6536
+ }
6098
6537
  \`\`\`
6099
- \u26A0\uFE0F **NOT in props**, NOT just strings, MUST have label+value`,
6100
- full: `# Options Format (select, radio, multi-checkbox)
6101
6538
 
6102
- **Required Format:**
6103
- Options MUST be an array of objects with \`label\` and \`value\` at **FIELD level**:
6539
+ **Key rules:**
6540
+ - \`source: 'http'\` is **required** to select HTTP derivation mode
6541
+ - \`dependsOn\` is **required** (prevents wildcard triggering on every keystroke)
6542
+ - \`responseExpression\` is **required** (extracts value from HTTP response body)
6543
+ - \`queryParams\` values are expressions evaluated by ExpressionParser
6544
+ - Requests are automatically debounced and cancelled (switchMap)
6545
+ - HTTP errors are caught and logged (stream continues)
6546
+ - Array fields (\`items.$.rate\`) are NOT supported for HTTP derivations
6547
+ - Works with \`stopOnUserOverride\` and \`condition\`
6104
6548
 
6105
- \`\`\`typescript
6549
+ ## Async Derivation (Custom Async Functions)
6550
+
6551
+ Call a registered async function (Promise or Observable) to derive values. Requires \`dependsOn\` (explicit).
6552
+
6553
+ \`\`\`typescript
6554
+ {
6555
+ key: 'suggestedPrice',
6556
+ type: 'input',
6557
+ label: 'Suggested Price',
6558
+ readonly: true,
6559
+ logic: [{
6560
+ type: 'derivation',
6561
+ source: 'asyncFunction',
6562
+ asyncFunctionName: 'fetchSuggestedPrice',
6563
+ dependsOn: ['productId', 'quantity'] // Required for async
6564
+ }]
6565
+ }
6566
+ \`\`\`
6567
+
6568
+ Register the function in \`customFnConfig.asyncDerivations\`:
6569
+
6570
+ \`\`\`typescript
6571
+ customFnConfig: {
6572
+ asyncDerivations: {
6573
+ fetchSuggestedPrice: async (context) => {
6574
+ const response = await fetch(\`/api/price?product=\${context.formValue.productId}\`);
6575
+ const data = await response.json();
6576
+ return data.suggestedPrice;
6577
+ },
6578
+ // Observable-based alternative
6579
+ lookupAddress: (context) => {
6580
+ return addressService.lookup(context.formValue.zipCode).pipe(
6581
+ map(result => result.formattedAddress)
6582
+ );
6583
+ },
6584
+ }
6585
+ }
6586
+ \`\`\`
6587
+
6588
+ **Key rules:**
6589
+ - \`asyncFunctionName\` is mutually exclusive with \`expression\`, \`value\`, \`functionName\`, and \`http\`
6590
+ - \`dependsOn\` is **required** (prevents triggering on every form change)
6591
+ - Wildcards (\`'*'\`) are **not allowed** in \`dependsOn\`
6592
+ - The function returns the value directly (no \`responseExpression\` needed)
6593
+ - Functions handle their own I/O (no HttpClient provided)
6594
+ - Requests are automatically debounced and cancelled (switchMap)
6595
+ - Errors are caught and logged (previous value retained)
6596
+ - Array fields (\`items.$.rate\`) are NOT supported
6597
+ - Works with \`stopOnUserOverride\` and \`condition\`
6598
+
6599
+ ## Stop on User Override
6600
+
6601
+ When \`stopOnUserOverride: true\`, the derivation stops running after the user manually edits the target field:
6602
+
6603
+ \`\`\`typescript
6604
+ {
6605
+ key: 'fullName',
6606
+ type: 'input',
6607
+ label: 'Full Name',
6608
+ logic: [{
6609
+ type: 'derivation',
6610
+ expression: 'formValue.firstName + " " + formValue.lastName',
6611
+ stopOnUserOverride: true // Derivation stops after user manually edits fullName
6612
+ }]
6613
+ }
6614
+ \`\`\`
6615
+
6616
+ ### Re-engagement on Dependency Change
6617
+
6618
+ Combine \`reEngageOnDependencyChange: true\` with \`stopOnUserOverride\` to clear user overrides when dependencies change:
6619
+
6620
+ \`\`\`typescript
6621
+ {
6622
+ key: 'fullName',
6623
+ type: 'input',
6624
+ label: 'Full Name',
6625
+ logic: [{
6626
+ type: 'derivation',
6627
+ expression: 'formValue.firstName + " " + formValue.lastName',
6628
+ stopOnUserOverride: true,
6629
+ reEngageOnDependencyChange: true // Clears user override when firstName/lastName changes
6630
+ }]
6631
+ }
6632
+ \`\`\`
6633
+
6634
+ **Use cases:**
6635
+ - Allow users to customize computed values
6636
+ - Reset customizations when source data changes
6637
+ - Smart defaults that defer to user input
6638
+
6639
+ **Variables in expressions:**
6640
+ - \`formValue\`: Complete form value object
6641
+ - \`fieldValue\`: This field's current value
6642
+ - \`fieldState\`: Current field's state (touched, dirty, valid, etc.)
6643
+ - \`formFieldState\`: All fields' states keyed by field key
6644
+ - \`externalData\`: External application state (user roles, feature flags, etc.)
6645
+
6646
+ **Nested access:**
6647
+ \`\`\`typescript
6648
+ derivation: 'formValue.address?.city' // Optional chaining
6649
+ derivation: 'formValue.items?.[0]?.name' // Array access
6650
+ derivation: 'formValue.discount ?? 0' // Nullish coalescing
6651
+ derivation: 'formValue.price * (1 - externalData.discountRate)' // External data
6652
+ \`\`\`
6653
+
6654
+ **Complex logic (IIFE):**
6655
+ \`\`\`typescript
6656
+ derivation: \`(() => {
6657
+ const qty = formValue.quantity || 0;
6658
+ const price = formValue.unitPrice || 0;
6659
+ return qty * price;
6660
+ })()\`
6661
+ \`\`\`
6662
+
6663
+ **See also:** \`property-derivation\` topic for deriving component properties (minDate, options, label, etc.)`
6664
+ },
6665
+ "options-format": {
6666
+ brief: `\`\`\`typescript
6667
+ options: [{ label: 'Display Text', value: 'actual-value' }] // AT FIELD LEVEL!
6668
+ \`\`\`
6669
+ \u26A0\uFE0F **NOT in props**, NOT just strings, MUST have label+value`,
6670
+ full: `# Options Format (select, radio, multi-checkbox)
6671
+
6672
+ **Required Format:**
6673
+ Options MUST be an array of objects with \`label\` and \`value\` at **FIELD level**:
6674
+
6675
+ \`\`\`typescript
6106
6676
  {
6107
6677
  key: 'country',
6108
6678
  type: 'select',
@@ -6134,6 +6704,8 @@ Wrong: Wrong property names
6134
6704
  "expression-variables": {
6135
6705
  brief: `**formValue** - complete form object: \`formValue.fieldName\`, \`formValue.address?.city\`
6136
6706
  **fieldValue** - current field's value (in custom validators)
6707
+ **fieldState** - current field state: \`fieldState.touched\`, \`fieldState.valid\`, \`fieldState.dirty\`
6708
+ **formFieldState** - all field states: \`formFieldState.email.valid\`, \`formFieldState.password.pristine\`
6137
6709
  **externalData** - external signals: \`externalData.userRole\`, \`externalData.featureFlags.enabled\``,
6138
6710
  full: `# Variables in Expressions
6139
6711
 
@@ -6143,6 +6715,8 @@ Wrong: Wrong property names
6143
6715
  |----------|------|--------------|-------------|
6144
6716
  | \`formValue\` | object | Derivations, conditions, custom validators | Complete form values as nested object |
6145
6717
  | \`fieldValue\` | any | Custom validator expressions only | Current field's value |
6718
+ | \`fieldState\` | object | Derivations, conditions | Current field's state (touched, dirty, valid, etc.) |
6719
+ | \`formFieldState\` | object | Derivations, conditions | All fields' states keyed by field key |
6146
6720
  | \`externalData\` | object | Derivations, conditions | External application state (from \`externalData\` in FormConfig) |
6147
6721
 
6148
6722
  ## Accessing Values
@@ -6165,6 +6739,56 @@ expression: 'formValue.contacts?.[0]?.name'
6165
6739
  expression: '(formValue.items?.length || 0) + " items"'
6166
6740
  \`\`\`
6167
6741
 
6742
+ ### Field State Access
6743
+
6744
+ \`fieldState\` provides access to the current field's state properties:
6745
+
6746
+ \`\`\`typescript
6747
+ // Check if current field has been touched
6748
+ expression: 'fieldState.touched ? "Modified" : "Untouched"'
6749
+
6750
+ // Check if current field is valid
6751
+ expression: 'fieldState.valid && formValue.email'
6752
+
6753
+ // Check if current field is dirty
6754
+ expression: 'fieldState.dirty ? "Changed from initial" : "Unchanged"'
6755
+ \`\`\`
6756
+
6757
+ **Available \`fieldState\` properties:**
6758
+ - \`touched\`: boolean - Field has been focused and blurred
6759
+ - \`dirty\`: boolean - Value differs from initial value
6760
+ - \`pristine\`: boolean - Value matches initial value
6761
+ - \`valid\`: boolean - No validation errors
6762
+ - \`invalid\`: boolean - Has validation errors
6763
+ - \`pending\`: boolean - Async validation in progress
6764
+ - \`hidden\`: boolean - Field is currently hidden
6765
+ - \`readonly\`: boolean - Field is currently readonly
6766
+ - \`disabled\`: boolean - Field is currently disabled
6767
+
6768
+ ### Form Field State Access
6769
+
6770
+ \`formFieldState\` provides access to any field's state by key:
6771
+
6772
+ \`\`\`typescript
6773
+ // Check if email field is valid
6774
+ expression: 'formFieldState.email?.valid'
6775
+
6776
+ // Conditional logic based on multiple field states
6777
+ expression: 'formFieldState.password?.valid && formFieldState.confirmPassword?.touched'
6778
+
6779
+ // Check if any field is invalid
6780
+ expression: '!formFieldState.email?.valid || !formFieldState.password?.valid'
6781
+ \`\`\`
6782
+
6783
+ **Nested field paths:**
6784
+ \`\`\`typescript
6785
+ // Access nested group field state
6786
+ expression: 'formFieldState["address.city"]?.dirty'
6787
+
6788
+ // Access array item field state
6789
+ expression: 'formFieldState["contacts.0.name"]?.valid'
6790
+ \`\`\`
6791
+
6168
6792
  ### External Data Access
6169
6793
  \`\`\`typescript
6170
6794
  expression: "externalData.userRole === 'admin'"
@@ -6172,11 +6796,202 @@ expression: 'externalData.featureFlags.advancedMode === true'
6172
6796
  expression: 'externalData.permissions.includes("edit")'
6173
6797
  \`\`\`
6174
6798
 
6799
+ ## Common Patterns
6800
+
6801
+ ### Conditional derivation based on field state
6802
+ \`\`\`typescript
6803
+ // Only compute if other field is valid
6804
+ expression: 'formFieldState.email?.valid ? formValue.email.toLowerCase() : ""'
6805
+
6806
+ // Show warning if field is touched but invalid
6807
+ expression: 'fieldState.touched && fieldState.invalid ? "Please fix errors" : ""'
6808
+ \`\`\`
6809
+
6810
+ ### Validation-aware derivations
6811
+ \`\`\`typescript
6812
+ // Only use value if source field is valid
6813
+ expression: 'formFieldState.price?.valid ? formValue.price * 1.2 : null'
6814
+ \`\`\`
6815
+
6175
6816
  ## Safety Tips
6176
6817
 
6177
- 1. **Always use optional chaining** (\`?.\`) for nested paths
6818
+ 1. **Always use optional chaining** (\`?.\`) for nested paths and field state access
6178
6819
  2. **Provide defaults** for potentially undefined values: \`formValue.count || 0\`
6179
- 3. **Use nullish coalescing** (\`??\`) when 0 or empty string are valid: \`formValue.score ?? 'N/A'\``
6820
+ 3. **Use nullish coalescing** (\`??\`) when 0 or empty string are valid: \`formValue.score ?? 'N/A'\`
6821
+ 4. **Check field existence** when using \`formFieldState\`: \`formFieldState.fieldKey?.valid\``
6822
+ },
6823
+ "property-derivation": {
6824
+ brief: `\`\`\`typescript
6825
+ // Derive endDate's minDate from startDate value
6826
+ logic: [{ type: 'derivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
6827
+
6828
+ // Derive select options from another field
6829
+ logic: [{ type: 'derivation', targetProperty: 'options', functionName: 'getCitiesForCountry', dependsOn: ['country'] }]
6830
+ \`\`\`
6831
+ Unlike value derivation (which sets the field's **value**), property derivation sets **component input properties** like minDate, options, label, placeholder, props.appearance.`,
6832
+ full: `# Property Derivation (Dynamic Field Properties)
6833
+
6834
+ Reactively derive field component properties based on form values. Unlike value derivations (which compute the field's value), property derivations compute **component input properties** like \`minDate\`, \`options\`, \`label\`, \`placeholder\`, \`props.appearance\`, etc.
6835
+
6836
+ Property derivations are self-targeting: the logic is placed on the field whose property should be derived.
6837
+
6838
+ ## Basic Syntax
6839
+
6840
+ \`\`\`typescript
6841
+ {
6842
+ key: 'endDate',
6843
+ type: 'datepicker',
6844
+ label: 'End Date',
6845
+ logic: [{
6846
+ type: 'derivation',
6847
+ targetProperty: 'minDate',
6848
+ expression: 'formValue.startDate',
6849
+ }]
6850
+ }
6851
+ \`\`\`
6852
+
6853
+ When \`startDate\` changes, the \`minDate\` property on the \`endDate\` datepicker is automatically updated.
6854
+
6855
+ ## Derivation Sources
6856
+
6857
+ ### Expression-Based
6858
+ \`\`\`typescript
6859
+ logic: [{
6860
+ type: 'derivation',
6861
+ targetProperty: 'minDate',
6862
+ expression: 'formValue.startDate',
6863
+ }]
6864
+ \`\`\`
6865
+
6866
+ ### Static Value
6867
+ \`\`\`typescript
6868
+ logic: [{
6869
+ type: 'derivation',
6870
+ targetProperty: 'label',
6871
+ value: 'Mobile Phone',
6872
+ condition: { type: 'fieldValue', fieldPath: 'contactType', operator: 'equals', value: 'mobile' },
6873
+ }]
6874
+ \`\`\`
6875
+
6876
+ ### Custom Function
6877
+ \`\`\`typescript
6878
+ // Register in customFnConfig
6879
+ customFnConfig: {
6880
+ derivations: {
6881
+ getCitiesForCountry: (ctx) => {
6882
+ const cities = { 'US': [{ label: 'NYC', value: 'nyc' }], 'DE': [{ label: 'Berlin', value: 'berlin' }] };
6883
+ return cities[ctx.formValue.country as string] ?? [];
6884
+ },
6885
+ },
6886
+ }
6887
+
6888
+ // Use in field config
6889
+ {
6890
+ key: 'city',
6891
+ type: 'select',
6892
+ label: 'City',
6893
+ logic: [{
6894
+ type: 'derivation',
6895
+ targetProperty: 'options',
6896
+ functionName: 'getCitiesForCountry',
6897
+ dependsOn: ['country'],
6898
+ }]
6899
+ }
6900
+ \`\`\`
6901
+
6902
+ ## Supported Target Properties
6903
+
6904
+ ### Simple Properties (1 level)
6905
+ \`minDate\`, \`maxDate\`, \`options\`, \`label\`, \`placeholder\`, \`hint\`, \`disabled\`, \`readonly\`, \`required\`, \`rows\`, \`cols\`, etc.
6906
+
6907
+ ### Nested Properties (max 2 levels)
6908
+ \`props.appearance\`, \`props.color\`, \`props.variant\`, \`meta.autocomplete\`, etc.
6909
+
6910
+ \u26A0\uFE0F Deeper nesting (3+ levels) is **not supported**.
6911
+
6912
+ ## Trigger Timing
6913
+
6914
+ | Trigger | Description | Use Case |
6915
+ |-------------|---------------------------------------|-----------------------------------|
6916
+ | \`onChange\` | Immediately on change (default) | Date constraints, dynamic options |
6917
+ | \`debounced\` | After value stabilizes | Expensive lookups, API calls |
6918
+
6919
+ \`\`\`typescript
6920
+ logic: [{
6921
+ type: 'derivation',
6922
+ targetProperty: 'options',
6923
+ functionName: 'searchProducts',
6924
+ trigger: 'debounced',
6925
+ debounceMs: 300,
6926
+ dependsOn: ['searchQuery'],
6927
+ }]
6928
+ \`\`\`
6929
+
6930
+ ## Conditional Property Derivation
6931
+
6932
+ \`\`\`typescript
6933
+ logic: [{
6934
+ type: 'derivation',
6935
+ targetProperty: 'label',
6936
+ value: 'Company Email',
6937
+ condition: { type: 'fieldValue', fieldPath: 'accountType', operator: 'equals', value: 'business' },
6938
+ }]
6939
+ \`\`\`
6940
+
6941
+ ## Array Fields
6942
+
6943
+ Inside arrays, \`formValue\` is scoped to the current array item:
6944
+ \`\`\`typescript
6945
+ {
6946
+ key: 'lineItems',
6947
+ type: 'array',
6948
+ fields: [{
6949
+ key: 'item',
6950
+ type: 'group',
6951
+ fields: [
6952
+ { key: 'startDate', type: 'datepicker', label: 'Start' },
6953
+ {
6954
+ key: 'endDate',
6955
+ type: 'datepicker',
6956
+ label: 'End',
6957
+ logic: [{
6958
+ type: 'derivation',
6959
+ targetProperty: 'minDate',
6960
+ expression: 'formValue.startDate', // Scoped to current array item
6961
+ }]
6962
+ }
6963
+ ]
6964
+ }]
6965
+ }
6966
+ \`\`\`
6967
+
6968
+ ## Key Differences from Value Derivation
6969
+
6970
+ | Aspect | Value Derivation | Property Derivation |
6971
+ |--------|-----------------|---------------------|
6972
+ | Sets | Field's form value | Component input property |
6973
+ | Type | \`type: 'derivation'\` | \`type: 'derivation'\` |
6974
+ | Target | Implicit (self) | \`targetProperty: 'minDate'\` |
6975
+ | Shorthand | \`derivation: 'expr'\` | None (must use logic block) |
6976
+ | Chaining | Topologically sorted | No chaining (single pass) |
6977
+ | Functions | \`customFnConfig.derivations\` | \`customFnConfig.derivations\` |
6978
+
6979
+ ## DerivationLogicConfig Interface (with targetProperty)
6980
+
6981
+ \`\`\`typescript
6982
+ interface DerivationLogicConfig {
6983
+ type: 'derivation';
6984
+ targetProperty: string; // Property to set (e.g., 'minDate', 'options')
6985
+ debugName?: string; // For logging/debugging
6986
+ condition?: ConditionalExpression | boolean; // When to apply (default: true)
6987
+ value?: unknown; // Static value (mutually exclusive)
6988
+ expression?: string; // JavaScript expression (mutually exclusive)
6989
+ functionName?: string; // Custom function name (mutually exclusive)
6990
+ dependsOn?: string[]; // Explicit field dependencies
6991
+ trigger?: 'onChange' | 'debounced'; // Evaluation timing (default: 'onChange')
6992
+ debounceMs?: number; // Debounce duration (default: 500)
6993
+ }
6994
+ \`\`\``
6180
6995
  },
6181
6996
  "external-data": {
6182
6997
  brief: `\`\`\`typescript
@@ -6277,7 +7092,7 @@ logic: [{
6277
7092
  },
6278
7093
  "async-validators": {
6279
7094
  brief: `\`\`\`typescript
6280
- validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
7095
+ validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
6281
7096
  \`\`\`
6282
7097
  Define function, register in provideDynamicForm, use in config.`,
6283
7098
  full: `# Async Validators (Complete Example)
@@ -6317,7 +7132,7 @@ provideDynamicForm({
6317
7132
  type: 'input',
6318
7133
  label: 'Email',
6319
7134
  validators: [
6320
- { type: 'customAsync', functionName: 'checkEmailAvailable' }
7135
+ { type: 'async', functionName: 'checkEmailAvailable' }
6321
7136
  ],
6322
7137
  validationMessages: { emailTaken: 'This email is already registered' }
6323
7138
  }
@@ -6411,35 +7226,37 @@ validators: [{
6411
7226
  },
6412
7227
  // ========== PATTERNS & RULES ==========
6413
7228
  "logic-matrix": {
6414
- brief: `**Containers:** group/row/array have NO logic (apply to children)
6415
- **Page:** hidden only | **Value fields:** all logic types | **Buttons:** hidden, disabled`,
7229
+ brief: `**Containers:** group/row/array support only \`hidden\` logic (same as pages). For other logic types, apply to children.
7230
+ **Page:** hidden only | **Value fields:** all logic types incl. derivation + targetProperty | **Buttons:** hidden, disabled`,
6416
7231
  full: `# Logic Support Matrix
6417
7232
 
6418
- | Field Type | hidden | disabled | required | readonly | derivation |
6419
- |----------------|--------|----------|----------|----------|------------|
6420
- | page | Y | N | N | N | N |
6421
- | group | N | N | N | N | N |
6422
- | row | N | N | N | N | N |
6423
- | array | N | N | N | N | N |
6424
- | input | Y | Y | Y | Y | Y |
6425
- | select | Y | Y | Y | Y | Y |
6426
- | checkbox | Y | Y | Y | Y | Y |
6427
- | radio | Y | Y | Y | Y | Y |
6428
- | multi-checkbox | Y | Y | Y | Y | Y |
6429
- | textarea | Y | Y | Y | Y | Y |
6430
- | datepicker | Y | Y | Y | Y | Y |
6431
- | toggle | Y | Y | Y | Y | Y |
6432
- | slider | Y | Y | Y | Y | Y |
6433
- | hidden | N | N | N | N | N |
6434
- | text | Y | N | N | N | N |
6435
- | button/submit | Y | Y | N | N | N |
6436
- | next/previous | Y | Y | N | N | N |
7233
+ | Field Type | hidden | disabled | required | readonly | derivation | derivation+targetProperty |
7234
+ |----------------|--------|----------|----------|----------|------------|--------------------|
7235
+ | page | Y | N | N | N | N | N |
7236
+ | group | Y | N | N | N | N | N |
7237
+ | row | Y | N | N | N | N | N |
7238
+ | array | Y | N | N | N | N | N |
7239
+ | input | Y | Y | Y | Y | Y | Y |
7240
+ | select | Y | Y | Y | Y | Y | Y |
7241
+ | checkbox | Y | Y | Y | Y | Y | Y |
7242
+ | radio | Y | Y | Y | Y | Y | Y |
7243
+ | multi-checkbox | Y | Y | Y | Y | Y | Y |
7244
+ | textarea | Y | Y | Y | Y | Y | Y |
7245
+ | datepicker | Y | Y | Y | Y | Y | Y |
7246
+ | toggle | Y | Y | Y | Y | Y | Y |
7247
+ | slider | Y | Y | Y | Y | Y | Y |
7248
+ | hidden | N | N | N | N | N | N |
7249
+ | text | Y | N | N | N | N | Y |
7250
+ | button/submit | Y | Y | N | N | N | N |
7251
+ | next/previous | Y | Y | N | N | N | N |
6437
7252
 
6438
7253
  **Key takeaways:**
6439
- - Containers (group, row, array) do NOT support logic - apply to children instead
7254
+ - Containers (group, row, array) support only \`hidden\` logic type (same as pages) for conditional visibility. For other logic types, apply to child fields instead.
6440
7255
  - Page only supports \`hidden\` logic (for conditional pages)
6441
7256
  - Hidden fields have NO logic support at all
6442
- - Value fields (input, select, etc.) support ALL logic types`
7257
+ - Value fields (input, select, etc.) support ALL logic types including \`derivation\` with \`targetProperty\`
7258
+ - \`derivation\` with \`targetProperty\` sets component input properties (e.g., \`minDate\`, \`options\`), NOT the field's form value
7259
+ - Text (display) fields support \`derivation\` with \`targetProperty\` for dynamic labels`
6443
7260
  },
6444
7261
  "context-api": {
6445
7262
  brief: `**Expressions:** \`formValue.field\`, \`fieldValue\`
@@ -6492,20 +7309,21 @@ provideDynamicForm({
6492
7309
  brief: `| Container | Label? | Logic? | Notes |
6493
7310
  |-----------|--------|--------|-------|
6494
7311
  | page | NO | hidden only | Nav buttons INSIDE |
6495
- | group | NO | NO | Creates nested object |
6496
- | array | NO | NO | Uses \`fields\` not \`template\` |
6497
- | row | NO | NO | Layout only, no hidden fields |`,
7312
+ | group | NO | hidden only | Creates nested object |
7313
+ | array | NO | hidden only | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
7314
+ | row | NO | hidden only | Layout only, no hidden fields |`,
6498
7315
  full: `# Container Rules
6499
7316
 
6500
7317
  | Container | Label? | Logic? | Allowed Children | Notes |
6501
7318
  |-----------|--------|--------|------------------|-------|
6502
7319
  | page | NO | YES (hidden only) | rows, groups, arrays, leaf fields, buttons | Nav buttons go INSIDE |
6503
- | group | NO | NO | rows, leaf fields (NOT pages, groups) | Creates nested object |
6504
- | array | NO | NO | rows, groups, leaf fields (NOT pages, arrays) | Uses \`fields\`, not \`template\` |
6505
- | row | NO | NO | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
7320
+ | group | NO | YES (hidden only) | rows, leaf fields (NOT pages, groups) | Creates nested object |
7321
+ | array | NO | YES (hidden only) | rows, groups, leaf fields (NOT pages, arrays) | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
7322
+ | row | NO | YES (hidden only) | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
6506
7323
 
6507
7324
  **CRITICAL:**
6508
- - If you need conditional visibility for a container, apply logic to each CHILD field instead.
7325
+ - All containers (page, group, row, array) support only the \`hidden\` logic type for conditional visibility.
7326
+ - For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.
6509
7327
  - Hidden fields cannot be inside rows - place them at page/form level.
6510
7328
  - Pages cannot be nested - ALL top-level fields must be pages if using multi-page mode.`
6511
7329
  },
@@ -6704,9 +7522,10 @@ const formConfig = {
6704
7522
  pitfalls: {
6705
7523
  brief: `1. Hidden field missing \`value\` - REQUIRED!
6706
7524
  2. Hidden field with label/logic/validators - FORBIDDEN!
6707
- 3. Container (group/row/array) with logic - apply to children!
7525
+ 3. Container (group/row/array) only supports 'hidden' logic - other types go on children!
6708
7526
  4. options/minValue/maxValue in props - must be at FIELD level!
6709
- 5. Generic button without \`event\` - use submit/next/previous!`,
7527
+ 5. Generic button without \`event\` - use submit/next/previous!
7528
+ 6. Array: \`fields\` and \`template\` are mutually exclusive - use one or the other!`,
6710
7529
  full: `# Common Pitfalls & Solutions
6711
7530
 
6712
7531
  ## 1. Hidden field missing value property
@@ -6734,16 +7553,17 @@ const formConfig = {
6734
7553
  { key: 'userId', type: 'hidden', value: '123' } // \u2705
6735
7554
  \`\`\`
6736
7555
 
6737
- ## 3. Container fields don't support logic
7556
+ ## 3. Containers only support 'hidden' logic
6738
7557
  \`\`\`typescript
6739
- // WRONG - logic on group/row/array
6740
- { type: 'group', logic: [...] } // \u274C TypeScript error!
7558
+ // WRONG - non-hidden logic on group/row/array
7559
+ { type: 'group', logic: [{ type: 'disabled', condition: {...} }] } // \u274C
6741
7560
 
6742
- // CORRECT - apply logic to child fields
7561
+ // CORRECT - containers support 'hidden' logic for conditional visibility
6743
7562
  {
6744
7563
  type: 'group',
7564
+ logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showGroup', operator: 'equals', value: false } }], // \u2705
6745
7565
  fields: [
6746
- { key: 'city', type: 'input', label: 'City', logic: [...] } // \u2705
7566
+ { key: 'city', type: 'input', label: 'City', logic: [...] } // \u2705 Other logic types on children
6747
7567
  ]
6748
7568
  }
6749
7569
  \`\`\`
@@ -6769,13 +7589,16 @@ const formConfig = {
6769
7589
  { type: 'button', label: 'Click', event: MyEvent } // \u2705
6770
7590
  \`\`\`
6771
7591
 
6772
- ## 6. Array using 'template' instead of 'fields'
7592
+ ## 6. Array: 'fields' vs 'template' (two APIs)
6773
7593
  \`\`\`typescript
6774
- // WRONG
6775
- { type: 'array', template: [...] } // \u274C 'template' doesn't exist
7594
+ // WRONG - mixing both APIs
7595
+ { type: 'array', fields: [...], template: {...} } // \u274C mutually exclusive
6776
7596
 
6777
- // CORRECT
6778
- { type: 'array', fields: [...] } // \u2705
7597
+ // CORRECT - Simplified API (recommended for common cases)
7598
+ { type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] } // \u2705
7599
+
7600
+ // CORRECT - Full API (for advanced use cases)
7601
+ { type: 'array', fields: [{ key: 'tag', type: 'input', value: 'a' }] } // \u2705
6779
7602
  \`\`\`
6780
7603
 
6781
7604
  ## 7. Type annotation loses inference
@@ -6790,7 +7613,8 @@ const config = { fields: [...] } as const satisfies FormConfig;
6790
7613
  conditions: {
6791
7614
  brief: `**Operators:** equals, notEquals, greater, less, greaterOrEqual, lessOrEqual, contains, startsWith, endsWith, matches
6792
7615
  **Combine:** \`{ type: 'and', conditions: [...] }\` or \`{ type: 'or', conditions: [...] }\`
6793
- **JavaScript:** \`{ type: 'javascript', expression: 'formValue.age >= 18' }\``,
7616
+ **JavaScript:** \`{ type: 'javascript', expression: 'formValue.age >= 18' }\`
7617
+ **HTTP:** \`{ type: 'http', http: { url: '/api/check', queryParams: { field: 'formValue.x' } }, responseExpression: 'response.allowed' }\``,
6794
7618
  full: `# Condition Operators & Patterns
6795
7619
 
6796
7620
  ## Available Operators
@@ -6846,6 +7670,85 @@ condition: {
6846
7670
  }
6847
7671
  \`\`\`
6848
7672
 
7673
+ ## HTTP Conditions (Server-Driven)
7674
+
7675
+ Use \`type: 'http'\` to determine field state based on HTTP responses:
7676
+
7677
+ \`\`\`typescript
7678
+ // Check if user has permission (GET)
7679
+ condition: {
7680
+ type: 'http',
7681
+ http: {
7682
+ url: '/api/permissions/check',
7683
+ queryParams: { role: 'formValue.role' }
7684
+ },
7685
+ responseExpression: 'response.allowed',
7686
+ pendingValue: false, // visible while loading
7687
+ cacheDurationMs: 60000,
7688
+ debounceMs: 500 // Optional, defaults to 300
7689
+ }
7690
+
7691
+ // Check feature flag (POST)
7692
+ condition: {
7693
+ type: 'http',
7694
+ http: {
7695
+ url: '/api/feature-flags',
7696
+ method: 'POST',
7697
+ body: { feature: 'advancedMode' },
7698
+ evaluateBodyExpressions: false
7699
+ },
7700
+ responseExpression: 'response.enabled'
7701
+ }
7702
+ \`\`\`
7703
+
7704
+ **Properties:**
7705
+ - \`http\` (required): \`HttpRequestConfig\` \u2014 URL, method, queryParams, body, headers
7706
+ - \`responseExpression\` (optional): Expression to extract boolean from response (scope: \`{ response }\`). When omitted, \`!!response\` is used
7707
+ - \`pendingValue\` (optional, default \`false\`): Value returned while HTTP request is in-flight
7708
+ - \`cacheDurationMs\` (optional, default \`30000\`): TTL for cached responses
7709
+ - \`debounceMs\` (optional, default \`300\`): Debounce for re-evaluation when dependent form values change
7710
+
7711
+ **Important:** HTTP conditions are resolved asynchronously via signals. They cannot be used inside \`and\`/\`or\` composites (will return \`false\` with a warning). Use them as standalone conditions.
7712
+
7713
+ ## Async Conditions (Custom Async Functions)
7714
+
7715
+ Use \`type: 'async'\` to determine field state based on a registered async function:
7716
+
7717
+ \`\`\`typescript
7718
+ // Check permission via custom service
7719
+ condition: {
7720
+ type: 'async',
7721
+ asyncFunctionName: 'checkPermission',
7722
+ pendingValue: false, // visible while loading
7723
+ debounceMs: 500
7724
+ }
7725
+ \`\`\`
7726
+
7727
+ Register the function in \`customFnConfig.asyncConditions\`:
7728
+
7729
+ \`\`\`typescript
7730
+ customFnConfig: {
7731
+ asyncConditions: {
7732
+ checkPermission: async (context) => {
7733
+ const response = await fetch(\`/api/permissions?role=\${context.formValue.role}\`);
7734
+ const data = await response.json();
7735
+ return data.canEdit;
7736
+ },
7737
+ // Observable-based alternative
7738
+ hasFeatureFlag: (context) => {
7739
+ return featureService.isEnabled('advancedMode').pipe(map(r => r.enabled));
7740
+ },
7741
+ }
7742
+ }
7743
+ \`\`\`
7744
+
7745
+ **Properties:**
7746
+ - \`asyncFunctionName\` (required): Name of the registered async condition function
7747
+ - \`pendingValue\` (optional, default \`false\`): Value returned while async resolution is pending
7748
+ - \`debounceMs\` (optional, default \`300\`): Debounce for re-evaluation
7749
+
7750
+ **Important:** Async conditions are resolved asynchronously via signals. They cannot be used inside \`and\`/\`or\` composites (will return \`false\` with a warning). Use them as standalone conditions.
7751
+
6849
7752
  ## Button-Only Conditions
6850
7753
 
6851
7754
  Buttons support special form state conditions:
@@ -7181,6 +8084,12 @@ var TOPIC_ALIASES = {
7181
8084
  list: "array",
7182
8085
  dynamic: "array",
7183
8086
  repeater: "array",
8087
+ // Simplified array aliases
8088
+ "simplified-arrays": "simplified-array",
8089
+ "simple-array": "simplified-array",
8090
+ "array-template": "simplified-array",
8091
+ "template-array": "simplified-array",
8092
+ "array-simplified": "simplified-array",
7184
8093
  layout: "row",
7185
8094
  columns: "row",
7186
8095
  grid: "row",
@@ -7198,6 +8107,15 @@ var TOPIC_ALIASES = {
7198
8107
  computed: "derivation",
7199
8108
  calculate: "derivation",
7200
8109
  expression: "derivation",
8110
+ // Property derivation aliases
8111
+ "property-derive": "property-derivation",
8112
+ propertyderivation: "property-derivation",
8113
+ "dynamic-properties": "property-derivation",
8114
+ "derived-properties": "property-derivation",
8115
+ "dynamic-options": "property-derivation",
8116
+ "dynamic-label": "property-derivation",
8117
+ mindate: "property-derivation",
8118
+ maxdate: "property-derivation",
7201
8119
  // Validation aliases
7202
8120
  validators: "validation",
7203
8121
  required: "validation",
@@ -7301,6 +8219,7 @@ function getTopicList() {
7301
8219
  "validation-messages",
7302
8220
  "conditional",
7303
8221
  "derivation",
8222
+ "property-derivation",
7304
8223
  "options-format",
7305
8224
  "expression-variables",
7306
8225
  "async-validators",
@@ -7407,14 +8326,14 @@ Field types: input, select, slider, radio, checkbox, textarea, datepicker, toggl
7407
8326
 
7408
8327
  Containers: group, row, array, page
7409
8328
 
7410
- Concepts: validation, conditional, derivation, options-format, expression-variables, async-validators
8329
+ Concepts: validation, conditional, derivation, property-derivation, options-format, expression-variables, async-validators
7411
8330
 
7412
8331
  Patterns: field-placement, logic-matrix, context-api, containers, multi-page-gotchas
7413
8332
 
7414
8333
  Use topic="list" to see all available topics.`,
7415
8334
  {
7416
8335
  topic: z54.string().describe(
7417
- 'Topic to look up: field types (input, select, hidden, group, row, array, page), concepts (validation, conditional, derivation, options-format), patterns (golden-path, pitfalls, multi-page-gotchas), or "list" to see all topics'
8336
+ 'Topic to look up: field types (input, select, hidden, group, row, array, page), concepts (validation, conditional, derivation, property-derivation, options-format), patterns (golden-path, pitfalls, multi-page-gotchas), or "list" to see all topics'
7418
8337
  ),
7419
8338
  depth: z54.enum(["brief", "full", "schema"]).default("full").describe("brief=quick syntax (~20 lines), full=complete docs with examples, schema=include JSON schema"),
7420
8339
  uiIntegration: z54.enum(UI_INTEGRATIONS2).optional().describe("Filter UI-specific info (only with depth=schema). material, bootstrap, primeng, ionic")
@@ -7724,7 +8643,7 @@ Show/hide pages based on conditions:
7724
8643
  \`\`\``
7725
8644
  },
7726
8645
  "minimal-array": {
7727
- description: "Dynamic array with add/remove (~30 lines)",
8646
+ description: "Dynamic array with simplified API (~15 lines)",
7728
8647
  minimal: `import { FormConfig } from '@ng-forge/dynamic-forms';
7729
8648
 
7730
8649
  const formConfig = {
@@ -7732,22 +8651,16 @@ const formConfig = {
7732
8651
  {
7733
8652
  key: 'contacts',
7734
8653
  type: 'array',
7735
- fields: [
7736
- {
7737
- key: 'item',
7738
- type: 'group',
7739
- fields: [
7740
- { key: 'name', type: 'input', label: 'Name', required: true },
7741
- { key: 'phone', type: 'input', label: 'Phone' }
7742
- ]
7743
- }
7744
- ]
8654
+ template: [
8655
+ { key: 'name', type: 'input', label: 'Name', required: true },
8656
+ { key: 'phone', type: 'input', label: 'Phone' }
8657
+ ],
8658
+ value: [{ name: 'Jane', phone: '555-1234' }]
7745
8659
  },
7746
- { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
7747
8660
  { key: 'submit', type: 'submit', label: 'Submit' }
7748
8661
  ]
7749
8662
  } as const satisfies FormConfig;`,
7750
- brief: `// Dynamic array form
8663
+ brief: `// Dynamic array form using simplified API
7751
8664
  import { FormConfig } from '@ng-forge/dynamic-forms';
7752
8665
 
7753
8666
  const formConfig = {
@@ -7755,67 +8668,78 @@ const formConfig = {
7755
8668
  {
7756
8669
  key: 'contacts',
7757
8670
  type: 'array',
7758
- // \u26A0\uFE0F NO LABEL! Uses 'fields', NOT 'template'
7759
- fields: [
7760
- {
7761
- key: 'item',
7762
- type: 'group',
7763
- fields: [
7764
- { key: 'name', type: 'input', label: 'Name', required: true },
7765
- { key: 'phone', type: 'input', label: 'Phone' }
7766
- ]
7767
- }
7768
- ]
8671
+ // Simplified API: template + value
8672
+ // Add/remove buttons are auto-generated!
8673
+ template: [
8674
+ { key: 'name', type: 'input', label: 'Name', required: true },
8675
+ { key: 'phone', type: 'input', label: 'Phone' }
8676
+ ],
8677
+ value: [{ name: 'Jane', phone: '555-1234' }]
7769
8678
  },
7770
- // \u26A0\uFE0F arrayKey at FIELD level, NOT in props!
7771
- { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
7772
8679
  { key: 'submit', type: 'submit', label: 'Submit' }
7773
8680
  ]
7774
8681
  } as const satisfies FormConfig;
7775
8682
 
7776
- // Output: { contacts: [{ name: '...', phone: '...' }, ...] }`,
8683
+ // Output: { contacts: [{ name: 'Jane', phone: '555-1234' }, ...] }
8684
+
8685
+ // For primitive arrays:
8686
+ // { key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }
8687
+ // Output: { tags: ['a', 'b'] }`,
7777
8688
  full: `# Minimal Array Form
7778
8689
 
7779
- A dynamic list with add/remove functionality.
8690
+ Dynamic lists with the simplified array API. Add/remove buttons are auto-generated.
8691
+
8692
+ ## Simplified API (Recommended)
7780
8693
 
7781
8694
  \`\`\`typescript
7782
8695
  import { FormConfig } from '@ng-forge/dynamic-forms';
7783
8696
 
7784
8697
  const formConfig = {
7785
8698
  fields: [
7786
- // ========== ARRAY CONTAINER ==========
8699
+ // ========== OBJECT ARRAY ==========
7787
8700
  {
7788
8701
  key: 'contacts',
7789
8702
  type: 'array',
7790
- // \u26A0\uFE0F Arrays have NO LABEL, NO LOGIC!
7791
- // \u26A0\uFE0F Use 'fields' property, NOT 'template'!
7792
- fields: [
7793
- {
7794
- key: 'item',
7795
- type: 'group', // Wrapping group creates objects in the array
7796
- fields: [
7797
- { key: 'name', type: 'input', label: 'Name', required: true },
7798
- { key: 'phone', type: 'input', label: 'Phone' },
7799
- // Optional: remove button inside each item
7800
- // { key: 'remove', type: 'removeArrayItem', label: 'Remove' }
7801
- ]
7802
- }
7803
- ]
8703
+ // template: array of fields = object items
8704
+ template: [
8705
+ { key: 'name', type: 'input', label: 'Name', required: true },
8706
+ { key: 'phone', type: 'input', label: 'Phone' }
8707
+ ],
8708
+ // Initial values (each element creates one item)
8709
+ value: [{ name: 'Jane', phone: '555-1234' }],
8710
+ // Optional: customize buttons
8711
+ addButton: { label: 'Add Contact' },
8712
+ // removeButton: false // disable remove buttons
7804
8713
  },
7805
- // ========== ADD BUTTON (outside array) ==========
7806
- // \u26A0\uFE0F arrayKey goes at FIELD level, NOT in props!
7807
- { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
7808
8714
  { key: 'submit', type: 'submit', label: 'Submit' }
7809
8715
  ]
7810
8716
  } as const satisfies FormConfig;
7811
8717
  \`\`\`
7812
8718
 
8719
+ ## Primitive Array
8720
+
8721
+ \`\`\`typescript
8722
+ const tagForm = {
8723
+ fields: [
8724
+ {
8725
+ key: 'tags',
8726
+ type: 'array',
8727
+ // template: single field = primitive items
8728
+ template: { key: 'value', type: 'input', label: 'Tag' },
8729
+ value: ['angular', 'typescript']
8730
+ },
8731
+ { key: 'submit', type: 'submit', label: 'Submit' }
8732
+ ]
8733
+ } as const satisfies FormConfig;
8734
+ // Output: { tags: ['angular', 'typescript'] }
8735
+ \`\`\`
8736
+
7813
8737
  ## Output Shape
7814
8738
 
7815
8739
  \`\`\`typescript
7816
8740
  {
7817
8741
  contacts: [
7818
- { name: 'Alice', phone: '555-1234' },
8742
+ { name: 'Jane', phone: '555-1234' },
7819
8743
  { name: 'Bob', phone: '555-5678' }
7820
8744
  ]
7821
8745
  }
@@ -7823,39 +8747,96 @@ const formConfig = {
7823
8747
 
7824
8748
  ## Key Rules
7825
8749
 
7826
- - Arrays use \`fields\` property (NOT \`template\`)
7827
- - \`arrayKey\` goes at field level (NOT in props)
7828
- - Arrays have NO label or logic support`,
8750
+ - **Simplified API:** Use \`template\` + \`value\` (add/remove buttons are auto-generated)
8751
+ - **Full API:** Use \`fields\` (you manage add/remove buttons manually)
8752
+ - \`fields\` and \`template\` are **mutually exclusive**
8753
+ - Arrays have NO label property
8754
+ - Only \`hidden\` logic type is supported
8755
+
8756
+ ## Full API (Advanced)
8757
+
8758
+ For full control, use the \`fields\`-based API with explicit add/remove buttons:
8759
+
8760
+ \`\`\`typescript
8761
+ {
8762
+ key: 'contacts',
8763
+ type: 'array',
8764
+ minLength: 1, // Optional: minimum number of items
8765
+ maxLength: 5, // Optional: maximum number of items
8766
+ fields: [
8767
+ [
8768
+ { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
8769
+ { key: 'phone', type: 'input', label: 'Phone', value: '555' }
8770
+ ]
8771
+ ]
8772
+ }
8773
+ // + separate addArrayItem button with arrayKey
8774
+ \`\`\``,
7829
8775
  explained: `# Array Fields - Complete Explanation
7830
8776
 
7831
- Arrays create dynamic, repeatable lists of items.
8777
+ Arrays create dynamic, repeatable lists of items. Two APIs are available.
7832
8778
 
7833
- ## Structure
8779
+ ## Simplified API (Recommended)
8780
+
8781
+ The simplified API uses \`template\` + \`value\` and auto-generates add/remove buttons.
8782
+
8783
+ ### Primitive Array
8784
+ \`\`\`typescript
8785
+ {
8786
+ key: 'tags',
8787
+ type: 'array',
8788
+ template: { key: 'value', type: 'input', label: 'Tag' }, // Single field = primitive
8789
+ value: ['angular', 'typescript']
8790
+ }
8791
+ // Output: { tags: ['angular', 'typescript'] }
8792
+ \`\`\`
8793
+
8794
+ ### Object Array
8795
+ \`\`\`typescript
8796
+ {
8797
+ key: 'contacts',
8798
+ type: 'array',
8799
+ template: [ // Array = object items
8800
+ { key: 'name', type: 'input', label: 'Name' },
8801
+ { key: 'phone', type: 'input', label: 'Phone' }
8802
+ ],
8803
+ value: [{ name: 'Jane', phone: '555' }]
8804
+ }
8805
+ // Output: { contacts: [{ name: 'Jane', phone: '555' }] }
8806
+ \`\`\`
8807
+
8808
+ ### Button Customization
8809
+ \`\`\`typescript
8810
+ {
8811
+ key: 'items',
8812
+ type: 'array',
8813
+ template: { key: 'value', type: 'input', label: 'Item' },
8814
+ addButton: { label: 'Add Item', props: { color: 'primary' } },
8815
+ removeButton: false // Disable remove buttons
8816
+ }
8817
+ \`\`\`
8818
+
8819
+ ## Full API (Advanced)
8820
+
8821
+ For full control, use \`fields\` with explicit item definitions and manual add/remove buttons.
7834
8822
 
7835
8823
  \`\`\`typescript
7836
8824
  {
7837
8825
  key: 'contacts',
7838
8826
  type: 'array',
7839
- // \u26A0\uFE0F Arrays DO NOT support:
7840
- // - label (no visual label)
7841
- // - logic (apply logic to children instead)
7842
- // - minItems/maxItems (not implemented)
7843
- // - template (use 'fields' instead)
7844
8827
  fields: [
7845
- // Template for each array item
7846
- {
7847
- key: 'item',
7848
- type: 'group', // Creates objects in the array
7849
- fields: [
7850
- { key: 'name', type: 'input', label: 'Name' },
7851
- { key: 'phone', type: 'input', label: 'Phone' }
7852
- ]
7853
- }
8828
+ // Each element is one array item:
8829
+ // - Single FieldDef = primitive item
8830
+ // - Array of FieldDefs = object item
8831
+ [
8832
+ { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
8833
+ { key: 'phone', type: 'input', label: 'Phone', value: '555' }
8834
+ ]
7854
8835
  ]
7855
8836
  }
7856
8837
  \`\`\`
7857
8838
 
7858
- ## Add/Remove Buttons
8839
+ ### Manual Add/Remove Buttons (Full API)
7859
8840
 
7860
8841
  \`\`\`typescript
7861
8842
  // ADD button - place OUTSIDE the array
@@ -7870,43 +8851,148 @@ Arrays create dynamic, repeatable lists of items.
7870
8851
  {
7871
8852
  key: 'contacts',
7872
8853
  type: 'array',
7873
- fields: [{
7874
- key: 'item',
7875
- type: 'group',
7876
- fields: [
8854
+ fields: [
8855
+ [
7877
8856
  { key: 'name', type: 'input', label: 'Name' },
7878
- { key: 'remove', type: 'removeArrayItem', label: 'Remove' } // No arrayKey needed
8857
+ { key: 'remove', type: 'removeArrayItem', label: 'Remove' }
7879
8858
  ]
7880
- }]
8859
+ ]
7881
8860
  }
7882
8861
  \`\`\`
7883
8862
 
7884
- ## Accessing Array Values in Expressions
8863
+ ## Accessing Array Values in Expressions
8864
+
8865
+ \`\`\`typescript
8866
+ // Count items
8867
+ expression: '(formValue.contacts?.length || 0)'
8868
+
8869
+ // Access specific index
8870
+ expression: 'formValue.contacts?.[0]?.name'
8871
+
8872
+ // Sum values
8873
+ expression: '(formValue.items || []).reduce((sum, item) => sum + (item.price || 0), 0)'
8874
+ \`\`\`
8875
+
8876
+ ## Common Mistakes
8877
+
8878
+ \u274C Mixing \`fields\` and \`template\`:
8879
+ \`\`\`typescript
8880
+ { type: 'array', fields: [...], template: {...} } // WRONG - mutually exclusive
8881
+ \`\`\`
8882
+
8883
+ \u274C Wrong value shape for object templates:
8884
+ \`\`\`typescript
8885
+ { template: [{ key: 'name', type: 'input' }], value: ['Jane'] } // WRONG
8886
+ { template: [{ key: 'name', type: 'input' }], value: [{ name: 'Jane' }] } // CORRECT
8887
+ \`\`\`
8888
+
8889
+ \u274C Putting \`arrayKey\` in props (full API):
8890
+ \`\`\`typescript
8891
+ { type: 'addArrayItem', props: { arrayKey: 'x' } } // WRONG
8892
+ { type: 'addArrayItem', arrayKey: 'x' } // CORRECT
8893
+ \`\`\``
8894
+ },
8895
+ "minimal-simplified-array": {
8896
+ description: "Simplified array API with template + value (~15 lines)",
8897
+ minimal: `import { FormConfig } from '@ng-forge/dynamic-forms';
8898
+
8899
+ const formConfig = {
8900
+ fields: [
8901
+ {
8902
+ key: 'tags',
8903
+ type: 'array',
8904
+ template: { key: 'value', type: 'input', label: 'Tag' },
8905
+ value: ['angular', 'typescript']
8906
+ },
8907
+ { key: 'submit', type: 'submit', label: 'Submit' }
8908
+ ]
8909
+ } as const satisfies FormConfig;`,
8910
+ brief: `// Simplified array - primitive values
8911
+ import { FormConfig } from '@ng-forge/dynamic-forms';
8912
+
8913
+ const formConfig = {
8914
+ fields: [
8915
+ // Primitive array with auto add/remove buttons
8916
+ {
8917
+ key: 'tags',
8918
+ type: 'array',
8919
+ template: { key: 'value', type: 'input', label: 'Tag' }, // Single field = primitive
8920
+ value: ['angular', 'typescript']
8921
+ },
8922
+ // Object array
8923
+ {
8924
+ key: 'contacts',
8925
+ type: 'array',
8926
+ template: [ // Array of fields = object items
8927
+ { key: 'name', type: 'input', label: 'Name', required: true },
8928
+ { key: 'phone', type: 'input', label: 'Phone' }
8929
+ ],
8930
+ value: [{ name: 'Jane', phone: '555' }],
8931
+ addButton: { label: 'Add Contact' },
8932
+ removeButton: { label: 'Delete', props: { color: 'warn' } }
8933
+ },
8934
+ { key: 'submit', type: 'submit', label: 'Submit' }
8935
+ ]
8936
+ } as const satisfies FormConfig;`,
8937
+ full: `# Simplified Array API
8938
+
8939
+ The concise way to define dynamic arrays. Auto-generates add/remove buttons.
7885
8940
 
7886
- \`\`\`typescript
7887
- // Count items
7888
- expression: '(formValue.contacts?.length || 0)'
8941
+ ## Primitive Array
7889
8942
 
7890
- // Access specific index
7891
- expression: 'formValue.contacts?.[0]?.name'
8943
+ \`\`\`typescript
8944
+ import { FormConfig } from '@ng-forge/dynamic-forms';
7892
8945
 
7893
- // Sum values
7894
- expression: '(formValue.items || []).reduce((sum, item) => sum + (item.price || 0), 0)'
8946
+ const formConfig = {
8947
+ fields: [
8948
+ {
8949
+ key: 'tags',
8950
+ type: 'array',
8951
+ template: { key: 'value', type: 'input', label: 'Tag' }, // Single field = primitive items
8952
+ value: ['angular', 'typescript'] // Initial values
8953
+ // Add/remove buttons are auto-generated!
8954
+ },
8955
+ { key: 'submit', type: 'submit', label: 'Submit' }
8956
+ ]
8957
+ } as const satisfies FormConfig;
8958
+ // Output: { tags: ['angular', 'typescript'] }
7895
8959
  \`\`\`
7896
8960
 
7897
- ## Common Mistakes
8961
+ ## Object Array
7898
8962
 
7899
- \u274C Using \`template\` instead of \`fields\`:
7900
8963
  \`\`\`typescript
7901
- { type: 'array', template: [...] } // WRONG - template doesn't exist
7902
- { type: 'array', fields: [...] } // CORRECT
8964
+ const contactForm = {
8965
+ fields: [
8966
+ {
8967
+ key: 'contacts',
8968
+ type: 'array',
8969
+ template: [ // Array = object items
8970
+ { key: 'name', type: 'input', label: 'Name', required: true },
8971
+ { key: 'phone', type: 'input', label: 'Phone' }
8972
+ ],
8973
+ value: [
8974
+ { name: 'Jane', phone: '555-1234' },
8975
+ { name: 'John', phone: '555-5678' }
8976
+ ],
8977
+ addButton: { label: 'Add Contact', props: { color: 'primary' } },
8978
+ removeButton: { label: 'Delete' }
8979
+ },
8980
+ { key: 'submit', type: 'submit', label: 'Submit' }
8981
+ ]
8982
+ } as const satisfies FormConfig;
8983
+ // Output: { contacts: [{ name: 'Jane', phone: '555-1234' }, ...] }
7903
8984
  \`\`\`
7904
8985
 
7905
- \u274C Putting \`arrayKey\` in props:
7906
- \`\`\`typescript
7907
- { type: 'addArrayItem', props: { arrayKey: 'x' } } // WRONG
7908
- { type: 'addArrayItem', arrayKey: 'x' } // CORRECT
7909
- \`\`\``
8986
+ ## Key Points
8987
+
8988
+ - **Single field template** = primitive array (each item is a value)
8989
+ - **Array of fields template** = object array (each item is an object)
8990
+ - **Add/remove buttons** are auto-generated by default
8991
+ - Use \`addButton: false\` or \`removeButton: false\` to disable
8992
+ - \`template\` and \`fields\` are **mutually exclusive**`,
8993
+ explained: `# Simplified Array API - Complete Explanation
8994
+
8995
+ See the \`simplified-array\` lookup topic for full documentation.`
7910
8996
  },
7911
8997
  "minimal-conditional": {
7912
8998
  description: "Show/hide field based on condition (~25 lines)",
@@ -8294,7 +9380,7 @@ provideDynamicForm({
8294
9380
  })
8295
9381
 
8296
9382
  // 3. Use
8297
- validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
9383
+ validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
8298
9384
  \`\`\`
8299
9385
 
8300
9386
  ## Error Messages
@@ -8449,6 +9535,429 @@ These will cause validation errors:
8449
9535
  { key: 'roleId', type: 'hidden', value: 42 } // number
8450
9536
  { key: 'isActive', type: 'hidden', value: true } // boolean
8451
9537
  { key: 'tagIds', type: 'hidden', value: [1, 2, 3] } // array
9538
+ \`\`\``
9539
+ },
9540
+ "property-derivation": {
9541
+ description: "Derive field properties (minDate, options, label) from form values",
9542
+ minimal: `import { FormConfig } from '@ng-forge/dynamic-forms';
9543
+
9544
+ const formConfig = {
9545
+ fields: [
9546
+ { key: 'startDate', type: 'datepicker', label: 'Start Date' },
9547
+ {
9548
+ key: 'endDate',
9549
+ type: 'datepicker',
9550
+ label: 'End Date',
9551
+ logic: [{
9552
+ type: 'derivation',
9553
+ targetProperty: 'minDate',
9554
+ expression: 'formValue.startDate',
9555
+ }]
9556
+ },
9557
+ { key: 'submit', type: 'submit', label: 'Submit' }
9558
+ ]
9559
+ } as const satisfies FormConfig;`,
9560
+ brief: `// Derive component properties from form values
9561
+ import { FormConfig } from '@ng-forge/dynamic-forms';
9562
+
9563
+ const formConfig = {
9564
+ fields: [
9565
+ { key: 'startDate', type: 'datepicker', label: 'Start Date' },
9566
+ {
9567
+ key: 'endDate',
9568
+ type: 'datepicker',
9569
+ label: 'End Date',
9570
+ // type: 'derivation' + targetProperty = PROPERTY derivation
9571
+ // Without targetProperty, it would be a VALUE derivation
9572
+ logic: [{
9573
+ type: 'derivation',
9574
+ targetProperty: 'minDate',
9575
+ expression: 'formValue.startDate',
9576
+ }]
9577
+ },
9578
+ {
9579
+ key: 'country',
9580
+ type: 'select',
9581
+ label: 'Country',
9582
+ options: [{ label: 'USA', value: 'US' }, { label: 'Germany', value: 'DE' }]
9583
+ },
9584
+ {
9585
+ key: 'city',
9586
+ type: 'select',
9587
+ label: 'City',
9588
+ options: [],
9589
+ // Dynamic options from custom function
9590
+ logic: [{
9591
+ type: 'derivation',
9592
+ targetProperty: 'options',
9593
+ functionName: 'getCitiesForCountry',
9594
+ dependsOn: ['country'],
9595
+ }]
9596
+ },
9597
+ { key: 'submit', type: 'submit', label: 'Submit' }
9598
+ ]
9599
+ } as const satisfies FormConfig;
9600
+
9601
+ // Key points:
9602
+ // - type: 'derivation' sets component PROPERTIES (not form value)
9603
+ // - targetProperty: which input property to set (e.g., 'minDate', 'options')
9604
+ // - Supports: expression, value, functionName (mutually exclusive)
9605
+ // - Register functions in customFnConfig.derivations`,
9606
+ full: `# Property Derivation (Dynamic Field Properties)
9607
+
9608
+ Derive field component properties reactively based on form values.
9609
+
9610
+ \`\`\`typescript
9611
+ import { FormConfig } from '@ng-forge/dynamic-forms';
9612
+
9613
+ const formConfig = {
9614
+ fields: [
9615
+ // ========== DATE RANGE: minDate from startDate ==========
9616
+ { key: 'startDate', type: 'datepicker', label: 'Start Date' },
9617
+ {
9618
+ key: 'endDate',
9619
+ type: 'datepicker',
9620
+ label: 'End Date',
9621
+ logic: [{
9622
+ type: 'derivation',
9623
+ targetProperty: 'minDate', // Set minDate property
9624
+ expression: 'formValue.startDate', // From startDate's value
9625
+ }]
9626
+ },
9627
+
9628
+ // ========== DYNAMIC OPTIONS: cities from country ==========
9629
+ {
9630
+ key: 'country',
9631
+ type: 'select',
9632
+ label: 'Country',
9633
+ options: [
9634
+ { label: 'USA', value: 'US' },
9635
+ { label: 'Germany', value: 'DE' }
9636
+ ]
9637
+ },
9638
+ {
9639
+ key: 'city',
9640
+ type: 'select',
9641
+ label: 'City',
9642
+ options: [], // Initial empty, filled by property derivation
9643
+ logic: [{
9644
+ type: 'derivation',
9645
+ targetProperty: 'options',
9646
+ functionName: 'getCitiesForCountry',
9647
+ dependsOn: ['country'],
9648
+ }]
9649
+ },
9650
+
9651
+ // ========== CONDITIONAL LABEL ==========
9652
+ {
9653
+ key: 'phone',
9654
+ type: 'input',
9655
+ label: 'Phone',
9656
+ logic: [{
9657
+ type: 'derivation',
9658
+ targetProperty: 'label',
9659
+ value: 'Mobile Phone',
9660
+ condition: {
9661
+ type: 'fieldValue',
9662
+ fieldPath: 'contactType',
9663
+ operator: 'equals',
9664
+ value: 'mobile'
9665
+ },
9666
+ }]
9667
+ },
9668
+
9669
+ // ========== NESTED PROPERTY ==========
9670
+ {
9671
+ key: 'notes',
9672
+ type: 'textarea',
9673
+ label: 'Notes',
9674
+ logic: [{
9675
+ type: 'derivation',
9676
+ targetProperty: 'props.appearance', // Dot-notation for nested
9677
+ expression: 'formValue.isPremium ? "fill" : "outline"',
9678
+ }]
9679
+ },
9680
+
9681
+ { key: 'submit', type: 'submit', label: 'Submit' }
9682
+ ]
9683
+ } as const satisfies FormConfig;
9684
+ \`\`\`
9685
+
9686
+ ## Custom Function Registration
9687
+
9688
+ \`\`\`typescript
9689
+ // customFnConfig is a property of FormConfig, not a provider option
9690
+ const formConfig = {
9691
+ customFnConfig: {
9692
+ derivations: {
9693
+ getCitiesForCountry: (ctx) => {
9694
+ const cities: Record<string, { label: string; value: string }[]> = {
9695
+ 'US': [{ label: 'New York', value: 'nyc' }, { label: 'LA', value: 'la' }],
9696
+ 'DE': [{ label: 'Berlin', value: 'berlin' }, { label: 'Munich', value: 'munich' }],
9697
+ };
9698
+ return cities[ctx.formValue.country as string] ?? [];
9699
+ },
9700
+ },
9701
+ },
9702
+ fields: [
9703
+ // ... fields with derivation + targetProperty logic referencing 'getCitiesForCountry'
9704
+ ],
9705
+ } as const satisfies FormConfig;
9706
+ \`\`\`
9707
+
9708
+ ## Key Differences from Value Derivation
9709
+
9710
+ | Feature | Value Derivation | Property Derivation |
9711
+ |---------|----------------------|-------------------------------|
9712
+ | Type | \`type: 'derivation'\` | \`type: 'derivation'\` + \`targetProperty\` |
9713
+ | Sets | Field's form value | Component property |
9714
+ | Target | Implicit (self) | \`targetProperty: 'minDate'\` |
9715
+ | Shorthand | \`derivation: 'expr'\` | None |
9716
+ | Functions | \`customFnConfig.derivations\` | \`customFnConfig.derivations\` |
9717
+
9718
+ The presence of \`targetProperty\` distinguishes a property derivation from a value derivation.`,
9719
+ explained: `# Property Derivation - Complete Explanation
9720
+
9721
+ ## What is Property Derivation?
9722
+
9723
+ Property derivation allows you to **reactively update component input properties** based on form state. Both value and property derivations use \`type: 'derivation'\`. The distinction is the \`targetProperty\` field: when present, the derivation targets a component property; when absent, it targets the field's form value.
9724
+
9725
+ ## When to Use Property Derivation
9726
+
9727
+ Use property derivation when:
9728
+ - **Date constraints**: endDate's minDate should follow startDate
9729
+ - **Dynamic options**: City options depend on selected country
9730
+ - **Dynamic labels**: Field label changes based on another field
9731
+ - **Dynamic appearance**: Input style changes based on form state
9732
+ - **Conditional placeholders**: Placeholder text depends on context
9733
+
9734
+ ## Syntax
9735
+
9736
+ \`\`\`typescript
9737
+ {
9738
+ key: 'endDate',
9739
+ type: 'datepicker',
9740
+ label: 'End Date',
9741
+ logic: [{
9742
+ type: 'derivation', // Same type as value derivation
9743
+ targetProperty: 'minDate', // targetProperty makes it a PROPERTY derivation
9744
+ expression: 'formValue.startDate', // How to compute it
9745
+ }]
9746
+ }
9747
+ \`\`\`
9748
+
9749
+ ## Three Ways to Compute Values
9750
+
9751
+ ### 1. Expression (inline JavaScript)
9752
+ \`\`\`typescript
9753
+ logic: [{
9754
+ type: 'derivation',
9755
+ targetProperty: 'minDate',
9756
+ expression: 'formValue.startDate', // Access form values
9757
+ }]
9758
+ \`\`\`
9759
+
9760
+ ### 2. Static Value (with condition)
9761
+ \`\`\`typescript
9762
+ logic: [{
9763
+ type: 'derivation',
9764
+ targetProperty: 'label',
9765
+ value: 'Business Email', // Fixed value
9766
+ condition: { type: 'fieldValue', fieldPath: 'type', operator: 'equals', value: 'business' },
9767
+ }]
9768
+ \`\`\`
9769
+
9770
+ ### 3. Custom Function (for complex logic)
9771
+ \`\`\`typescript
9772
+ // In form config
9773
+ customFnConfig: {
9774
+ derivations: {
9775
+ getCitiesForCountry: (ctx) => {
9776
+ // ctx.formValue contains all form values
9777
+ // ctx.externalData contains external signals (unwrapped)
9778
+ return lookupCities(ctx.formValue.country);
9779
+ },
9780
+ },
9781
+ }
9782
+
9783
+ // In field
9784
+ logic: [{
9785
+ type: 'derivation',
9786
+ targetProperty: 'options',
9787
+ functionName: 'getCitiesForCountry',
9788
+ dependsOn: ['country'], // \u26A0\uFE0F Recommended for custom functions!
9789
+ }]
9790
+ \`\`\`
9791
+
9792
+ ## Target Property Formats
9793
+
9794
+ ### Simple properties (1 level)
9795
+ \`\`\`typescript
9796
+ targetProperty: 'minDate' // Direct property
9797
+ targetProperty: 'options' // Array of options
9798
+ targetProperty: 'label' // Field label
9799
+ targetProperty: 'placeholder' // Field placeholder
9800
+ targetProperty: 'hint' // Hint text
9801
+ \`\`\`
9802
+
9803
+ ### Nested properties (2 levels max)
9804
+ \`\`\`typescript
9805
+ targetProperty: 'props.appearance' // Nested in props
9806
+ targetProperty: 'props.color' // Material color
9807
+ targetProperty: 'meta.autocomplete' // Custom metadata
9808
+ \`\`\`
9809
+
9810
+ ### \u274C Not supported (3+ levels)
9811
+ \`\`\`typescript
9812
+ targetProperty: 'props.nested.deep' // \u274C Too deep!
9813
+ \`\`\`
9814
+
9815
+ ## Trigger Timing
9816
+
9817
+ \`\`\`typescript
9818
+ // Default: evaluate immediately on form value change
9819
+ logic: [{
9820
+ type: 'derivation',
9821
+ targetProperty: 'options',
9822
+ expression: '...',
9823
+ trigger: 'onChange', // default
9824
+ }]
9825
+
9826
+ // Debounced: wait for typing to stop
9827
+ logic: [{
9828
+ type: 'derivation',
9829
+ targetProperty: 'options',
9830
+ functionName: 'searchProducts',
9831
+ trigger: 'debounced',
9832
+ debounceMs: 300,
9833
+ dependsOn: ['searchQuery'],
9834
+ }]
9835
+ \`\`\`
9836
+
9837
+ ## Array Field Support
9838
+
9839
+ Inside arrays, \`formValue\` is scoped to the current array item:
9840
+
9841
+ \`\`\`typescript
9842
+ {
9843
+ key: 'lineItems',
9844
+ type: 'array',
9845
+ fields: [{
9846
+ key: 'item', type: 'group',
9847
+ fields: [
9848
+ { key: 'startDate', type: 'datepicker', label: 'Start' },
9849
+ {
9850
+ key: 'endDate', type: 'datepicker', label: 'End',
9851
+ logic: [{
9852
+ type: 'derivation',
9853
+ targetProperty: 'minDate',
9854
+ expression: 'formValue.startDate', // Refers to THIS item's startDate
9855
+ }]
9856
+ }
9857
+ ]
9858
+ }]
9859
+ }
9860
+ \`\`\`
9861
+
9862
+ ## Dependencies
9863
+
9864
+ ### Automatic (for expressions)
9865
+ Dependencies are auto-extracted from expressions:
9866
+ \`\`\`typescript
9867
+ expression: 'formValue.startDate' // Automatically depends on 'startDate'
9868
+ \`\`\`
9869
+
9870
+ ### Explicit (for custom functions)
9871
+ \`\`\`typescript
9872
+ functionName: 'getCities',
9873
+ dependsOn: ['country'], // Only re-evaluate when 'country' changes
9874
+ \`\`\`
9875
+
9876
+ ### Wildcard (default for functions without dependsOn)
9877
+ Functions without \`dependsOn\` re-evaluate on ANY form change. Add \`dependsOn\` for performance.
9878
+
9879
+ ## Complete Example
9880
+
9881
+ \`\`\`typescript
9882
+ import { FormConfig } from '@ng-forge/dynamic-forms';
9883
+
9884
+ const travelForm = {
9885
+ customFnConfig: {
9886
+ derivations: {
9887
+ getCitiesForCountry: (ctx) => {
9888
+ const cities: Record<string, { label: string; value: string }[]> = {
9889
+ 'US': [{ label: 'New York', value: 'nyc' }, { label: 'LA', value: 'la' }],
9890
+ 'DE': [{ label: 'Berlin', value: 'berlin' }],
9891
+ };
9892
+ return cities[ctx.formValue.country as string] ?? [];
9893
+ },
9894
+ },
9895
+ },
9896
+ fields: [
9897
+ {
9898
+ key: 'country',
9899
+ type: 'select',
9900
+ label: 'Country',
9901
+ options: [
9902
+ { label: 'USA', value: 'US' },
9903
+ { label: 'Germany', value: 'DE' },
9904
+ ],
9905
+ },
9906
+ {
9907
+ key: 'city',
9908
+ type: 'select',
9909
+ label: 'City',
9910
+ options: [],
9911
+ logic: [{
9912
+ type: 'derivation',
9913
+ targetProperty: 'options',
9914
+ functionName: 'getCitiesForCountry',
9915
+ dependsOn: ['country'],
9916
+ }],
9917
+ },
9918
+ { key: 'startDate', type: 'datepicker', label: 'Travel Start' },
9919
+ {
9920
+ key: 'endDate',
9921
+ type: 'datepicker',
9922
+ label: 'Travel End',
9923
+ logic: [{
9924
+ type: 'derivation',
9925
+ targetProperty: 'minDate',
9926
+ expression: 'formValue.startDate',
9927
+ }],
9928
+ },
9929
+ { key: 'submit', type: 'submit', label: 'Book Trip' },
9930
+ ],
9931
+ } as const satisfies FormConfig;
9932
+ \`\`\`
9933
+
9934
+ ## Common Mistakes
9935
+
9936
+ \u274C Confusing with value derivation:
9937
+ \`\`\`typescript
9938
+ // WRONG - 'derivation' changes the form value, not a property
9939
+ logic: [{ type: 'derivation', expression: 'formValue.startDate' }]
9940
+
9941
+ // CORRECT - targetProperty makes it a PROPERTY derivation
9942
+ logic: [{ type: 'derivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
9943
+ \`\`\`
9944
+
9945
+ \u274C Missing targetProperty:
9946
+ \`\`\`typescript
9947
+ // WRONG - must specify which property to set
9948
+ logic: [{ type: 'derivation', expression: '...' }]
9949
+
9950
+ // CORRECT
9951
+ logic: [{ type: 'derivation', targetProperty: 'options', expression: '...' }]
9952
+ \`\`\`
9953
+
9954
+ \u274C Forgetting targetProperty entirely:
9955
+ \`\`\`typescript
9956
+ // WRONG - this is a VALUE derivation (overwrites the field value)
9957
+ logic: [{ type: 'derivation', functionName: 'getCities' }]
9958
+
9959
+ // CORRECT - targetProperty makes it set the 'options' PROPERTY
9960
+ logic: [{ type: 'derivation', targetProperty: 'options', functionName: 'getCities' }]
8452
9961
  \`\`\``
8453
9962
  },
8454
9963
  // ========== STANDARD PATTERNS ==========
@@ -9043,23 +10552,20 @@ const megaFormConfig = {
9043
10552
  ]
9044
10553
  },
9045
10554
 
9046
- // ARRAY
10555
+ // ARRAY (Simplified API - recommended)
9047
10556
  {
9048
10557
  key: 'itemsHeader', type: 'text', label: 'Dynamic Array:', props: { elementType: 'h3' }
9049
10558
  },
9050
10559
  {
9051
10560
  key: 'demoArray',
9052
10561
  type: 'array',
9053
- fields: [{
9054
- key: 'arrayItem',
9055
- type: 'group',
9056
- fields: [
9057
- { key: 'itemName', type: 'input', label: 'Item Name' },
9058
- { key: 'itemQty', type: 'input', label: 'Qty', props: { type: 'number' } }
9059
- ]
9060
- }]
10562
+ template: [
10563
+ { key: 'itemName', type: 'input', label: 'Item Name' },
10564
+ { key: 'itemQty', type: 'input', label: 'Qty', props: { type: 'number' } }
10565
+ ],
10566
+ value: [{ itemName: 'Widget', itemQty: '5' }],
10567
+ addButton: { label: 'Add Item' }
9061
10568
  },
9062
- { key: 'addItem', type: 'addArrayItem', label: 'Add Item', arrayKey: 'demoArray' },
9063
10569
 
9064
10570
  {
9065
10571
  key: 'containersNav',
@@ -9079,7 +10585,7 @@ const megaFormConfig = {
9079
10585
 
9080
10586
  - **All field types:** input, select, radio, checkbox, multi-checkbox, textarea, toggle, slider, datepicker, text, hidden
9081
10587
  - **All container types:** page, row, group, array
9082
- - **All button types:** submit, next, previous, addArrayItem
10588
+ - **All button types:** submit, next, previous, auto-generated add/remove (simplified array)
9083
10589
  - **Logic types:** hidden, required, derivation
9084
10590
  - **Condition types:** fieldValue with operators
9085
10591
  - **Layout:** col property for grid widths`;
@@ -9091,11 +10597,12 @@ function getPatternList() {
9091
10597
  "Minimal Patterns (~20-50 lines)": [
9092
10598
  "minimal-multipage",
9093
10599
  "minimal-array",
10600
+ "minimal-simplified-array",
9094
10601
  "minimal-conditional",
9095
10602
  "minimal-validation",
9096
10603
  "minimal-hidden"
9097
10604
  ],
9098
- "Standard Patterns": ["derivation", "multi-page", "conditional", "validation"]
10605
+ "Standard Patterns": ["derivation", "property-derivation", "multi-page", "conditional", "validation"]
9099
10606
  };
9100
10607
  for (const [category, patterns] of Object.entries(categories)) {
9101
10608
  lines.push(`## ${category}`);
@@ -9121,18 +10628,19 @@ Recommended starting points:
9121
10628
 
9122
10629
  Minimal patterns (~20-50 lines):
9123
10630
  - minimal-multipage: 2-page wizard
9124
- - minimal-array: Dynamic list with add/remove
10631
+ - minimal-array: Dynamic list with add/remove (simplified API)
10632
+ - minimal-simplified-array: Simplified array with template + value
9125
10633
  - minimal-conditional: Show/hide field
9126
10634
  - minimal-validation: Password confirmation
9127
10635
  - minimal-hidden: Hidden fields in multi-page
9128
10636
 
9129
- Standard patterns: derivation, multi-page, conditional, validation
10637
+ Standard patterns: derivation, property-derivation, multi-page, conditional, validation
9130
10638
 
9131
10639
  Use pattern="list" to see all available patterns.
9132
10640
  Use depth="minimal" for code-only output (no markdown).`,
9133
10641
  {
9134
10642
  pattern: z55.string().optional().describe(
9135
- 'Pattern to get: minimal-multipage, minimal-array, minimal-conditional, minimal-validation, minimal-hidden, derivation, multi-page, conditional, validation, complete, mega. Use "list" to see all.'
10643
+ 'Pattern to get: minimal-multipage, minimal-array, minimal-simplified-array, minimal-conditional, minimal-validation, minimal-hidden, derivation, property-derivation, multi-page, conditional, validation, complete, mega. Use "list" to see all.'
9136
10644
  ),
9137
10645
  depth: z55.enum(["minimal", "brief", "full", "explained"]).default("full").describe(
9138
10646
  "minimal=code only (~20-50 lines), brief=code+summary, full=code+comments (default), explained=code+detailed explanation"
@@ -9621,11 +11129,11 @@ var UI_INTEGRATIONS3 = ["material", "bootstrap", "primeng", "ionic"];
9621
11129
  var FIX_SUGGESTIONS = {
9622
11130
  options: "Move `options` from `props: { options: [...] }` to field level: `{ key, type, options: [...] }`",
9623
11131
  label: "Remove `label` from this container field (page/group/row/array). Use a `text` field inside for headings.",
9624
- logic: "Move `logic` to individual child fields. Containers (row/group/array) don't support logic - only their children do.",
11132
+ logic: "Containers (group, row, array) only support 'hidden' logic type (same as pages). For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.",
9625
11133
  minValue: "Use `minValue` at field level for sliders, not `min` in props.",
9626
11134
  maxValue: "Use `maxValue` at field level for sliders, not `max` in props.",
9627
11135
  step: "Use `step` at field level for sliders, not in props.",
9628
- template: "Use `fields` instead of `template` for array item definition.",
11136
+ template: "Arrays support two APIs: (1) Full API with `fields` for explicit item definitions, or (2) Simplified API with `template` + `value` for common cases. If using `template`, provide a single field for primitive arrays or an array of fields for object arrays.",
9629
11137
  content: "Use `label` for text content and `props: { elementType }` for HTML element.",
9630
11138
  element: "Use `props: { elementType }` not `element` for text field HTML element.",
9631
11139
  hideWhen: "Use `logic: [{ type: 'hidden', condition: {...} }]` - no `hideWhen` shorthand exists.",
@@ -9796,7 +11304,7 @@ Returns SPECIFIC error messages with:
9796
11304
  Example errors you'll see:
9797
11305
  - "Hidden field missing REQUIRED value property"
9798
11306
  - "options MUST be at FIELD level, NOT inside props"
9799
- - "row containers do NOT support logic blocks"`,
11307
+ - "containers only support 'hidden' logic type"`,
9800
11308
  {
9801
11309
  config: z56.union([z56.string(), z56.object({}).passthrough()]).describe(
9802
11310
  "File path (.ts/.js) OR JSON string OR JSON object. Auto-detects: paths ending in .ts/.js or starting with / are treated as files."
@@ -9987,22 +11495,16 @@ ${indent} ]
9987
11495
  ${indent}}`;
9988
11496
  }
9989
11497
  function generateArray(name, indent) {
9990
- const array = `${indent}{
11498
+ return `${indent}{
9991
11499
  ${indent} key: '${name}',
9992
11500
  ${indent} type: 'array',
9993
- ${indent} fields: [
9994
- ${indent} {
9995
- ${indent} key: '${name}Item',
9996
- ${indent} type: 'group',
9997
- ${indent} fields: [
9998
- ${indent} { key: 'itemName', type: 'input', label: 'Name' },
9999
- ${indent} { key: 'itemValue', type: 'input', label: 'Value' }
10000
- ${indent} ]
10001
- ${indent} }
10002
- ${indent} ]
11501
+ ${indent} template: [
11502
+ ${indent} { key: 'itemName', type: 'input', label: 'Name' },
11503
+ ${indent} { key: 'itemValue', type: 'input', label: 'Value' }
11504
+ ${indent} ],
11505
+ ${indent} value: [],
11506
+ ${indent} addButton: { label: 'Add ${capitalize(name)}' }
10003
11507
  ${indent}}`;
10004
- const addButton = `${indent}{ key: 'add${capitalize(name)}', type: 'addArrayItem', label: 'Add ${capitalize(name)}', arrayKey: '${name}' }`;
10005
- return [array, addButton];
10006
11508
  }
10007
11509
  function capitalize(s) {
10008
11510
  return s.charAt(0).toUpperCase() + s.slice(1).replace(/([A-Z])/g, " $1").trim();
@@ -10034,15 +11536,13 @@ function generateScaffold(options) {
10034
11536
  const arraysForThisPage = pages > 2 && p > 1 && p < pages ? arrays : p === Math.ceil(pages / 2) ? arrays : [];
10035
11537
  if (pages <= 2 && isFirst) {
10036
11538
  for (const a of arrays) {
10037
- const [arrayDef, addBtn] = generateArray(a, " ");
11539
+ const arrayDef = generateArray(a, " ");
10038
11540
  lines.push(arrayDef + ",");
10039
- lines.push(addBtn + ",");
10040
11541
  }
10041
11542
  } else {
10042
11543
  for (const a of arraysForThisPage) {
10043
- const [arrayDef, addBtn] = generateArray(a, " ");
11544
+ const arrayDef = generateArray(a, " ");
10044
11545
  lines.push(arrayDef + ",");
10045
- lines.push(addBtn + ",");
10046
11546
  }
10047
11547
  }
10048
11548
  const fieldsPerPage = Math.ceil(fields.length / pages);
@@ -10086,9 +11586,8 @@ function generateScaffold(options) {
10086
11586
  lines.push(generateGroup(g, " ") + ",");
10087
11587
  }
10088
11588
  for (const a of arrays) {
10089
- const [arrayDef, addBtn] = generateArray(a, " ");
11589
+ const arrayDef = generateArray(a, " ");
10090
11590
  lines.push(arrayDef + ",");
10091
- lines.push(addBtn + ",");
10092
11591
  }
10093
11592
  for (const f of fields) {
10094
11593
  lines.push(generateField(f, " ") + ",");