@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.
- package/README.md +1 -1
- package/bin/ng-forge-mcp.js +1782 -283
- package/package.json +7 -7
- package/src/index.js +1782 -283
- package/src/registry/api-reference.json +76 -25
- package/src/registry/docs.json +52 -16
- package/src/registry/field-types.json +18 -6
- package/src/registry/instructions.d.ts +1 -1
- package/src/registry/instructions.d.ts.map +1 -1
- package/src/registry/validators.json +56 -4
- package/src/tools/data/lookup-topics.d.ts.map +1 -1
- package/src/tools/examples.tool.d.ts.map +1 -1
- package/src/tools/lookup.tool.d.ts.map +1 -1
- package/src/tools/scaffold.tool.d.ts.map +1 -1
- package/src/tools/validate.tool.d.ts.map +1 -1
package/src/registry/docs.json
CHANGED
|
@@ -9,13 +9,13 @@
|
|
|
9
9
|
"id": "advanced-events",
|
|
10
10
|
"title": "Advanced Events",
|
|
11
11
|
"category": "advanced",
|
|
12
|
-
"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// ✓ Type-safe event subscription\nclass UserUpdatedEvent implements FormEvent {\n readonly type = 'user-updated' as const;\n constructor(public readonly userId: string) {}\n}\n\n// ✓ 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// ✗ 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```"
|
|
12
|
+
"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** → creates a **primitive item** (field value extracted directly)\n- **Array of FieldDefs** → 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// ✓ Type-safe event subscription\nclass UserUpdatedEvent implements FormEvent {\n readonly type = 'user-updated' as const;\n constructor(public readonly userId: string) {}\n}\n\n// ✓ 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// ✗ 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```"
|
|
13
13
|
},
|
|
14
14
|
{
|
|
15
15
|
"id": "advanced-expression-parser",
|
|
16
16
|
"title": "Advanced Expression Parser",
|
|
17
17
|
"category": "advanced",
|
|
18
|
-
"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// ✅ Works - safe string methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.includes(\"@company.com\")'\n }\n}\n\n// ✅ 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// ❌ 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// ✅ Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// ❌ 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// ✅ 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// ❌ Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// ✅ 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- ✅ **Code Injection**: Can't execute
|
|
18
|
+
"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// ✅ Works - safe string methods\n{\n type: 'hidden',\n condition: {\n type: 'javascript',\n expression: 'formValue.email.includes(\"@company.com\")'\n }\n}\n\n// ✅ 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// ❌ 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// ✅ Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// ❌ 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// ✅ 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// ❌ Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// ✅ 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- ✅ **Code Injection**: Can't execute arbitrary code or create new code\n- ✅ **Prototype Pollution**: Can't access `constructor` or `__proto__`\n- ✅ **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// ✅ 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// ❌ 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"
|
|
19
19
|
},
|
|
20
20
|
{
|
|
21
21
|
"id": "advanced-type-safety-basics",
|
|
@@ -23,17 +23,23 @@
|
|
|
23
23
|
"category": "advanced",
|
|
24
24
|
"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()); // ✓ Safe - always defined\n console.log(value.name?.toUpperCase()); // ✓ Must use optional chaining\n console.log(value.age + 1); // ✗ 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); // ✓ Type: string (required)\n console.log(value.age); // ✓ 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; // ✓ Autocomplete works\n value.lastName; // ✓ Autocomplete works\n value.email; // ✓ Autocomplete works\n value.invalid; // ✗ 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// ✓ Correct - enables inference + type checking\nconst config = { fields: [...] } as const satisfies FormConfig;\n\n// ✗ Wrong - no inference\nconst config = { fields: [...] };\n\n// ✗ 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// ✓ 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// ✗ 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// ✗ 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// ✓ 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// ✗ Wrong - type is widened, inference fails\nconst config: FormConfig = {\n fields: [{ key: 'name', type: 'input', value: '' }],\n} as const;\n\n// ✓ 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// ✗ 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┌─────────────────────────────────────────────────────────────┐\n│ NESTING RULES │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ PAGE ──────┬──► ROW ────────┬──► GROUP ──┬──► LEAF FIELD │\n│ │ │ │ │\n│ ├──► GROUP ──────┼──► ROW ────┴──► LEAF FIELD │\n│ │ │ │\n│ └──► LEAF FIELD └──► LEAF FIELD │\n│ │\n├─────────────────────────────────────────────────────────────┤\n│ ✗ PAGE cannot contain PAGE │\n│ ✗ ROW cannot contain ROW or PAGE │\n│ ✗ GROUP cannot contain GROUP or PAGE │\n└─────────────────────────────────────────────────────────────┘\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// ✗ 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// ✗ 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:' }, // ✗ Excluded\n { key: 'name', type: 'input', value: '' }, // ✓ Included\n { type: 'submit', label: 'Save' }, // ✗ Excluded\n {\n type: 'row', // ✗ Excluded (container)\n fields: [\n { key: 'city', type: 'input', value: '' }, // ✓ 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"
|
|
25
25
|
},
|
|
26
|
+
{
|
|
27
|
+
"id": "advanced-value-exclusion",
|
|
28
|
+
"title": "Advanced Value Exclusion",
|
|
29
|
+
"category": "advanced",
|
|
30
|
+
"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` → value is **included** when hidden\n- **Field B** uses field-level (`true`) → 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```"
|
|
31
|
+
},
|
|
26
32
|
{
|
|
27
33
|
"id": "ai-integration",
|
|
28
34
|
"title": "AI Integration",
|
|
29
35
|
"category": "ai-integration",
|
|
30
|
-
"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 | ✅ |\n| `ngforge_examples` | Get working code examples for common form patterns | ✅ |\n| `ngforge_validate` | Validate FormConfig and get detailed error feedback | ✅ |\n| `ngforge_scaffold` | Generate valid FormConfig skeletons | ✅ |\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
|
|
36
|
+
"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 | ✅ |\n| `ngforge_examples` | Get working code examples for common form patterns | ✅ |\n| `ngforge_validate` | Validate FormConfig and get detailed error feedback | ✅ |\n| `ngforge_scaffold` | Generate valid FormConfig skeletons | ✅ |\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)."
|
|
31
37
|
},
|
|
32
38
|
{
|
|
33
39
|
"id": "dynamic-behavior-conditional-logic-overview",
|
|
34
40
|
"title": "Dynamic Behavior Conditional Logic Overview",
|
|
35
41
|
"category": "dynamic-behavior",
|
|
36
|
-
"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┌─────────────────────────────────────────────────────────────┐\n│ LOGIC EVALUATION FLOW │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ Form Value Changes │\n│ │ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ Signal Updates │◄──── Angular's reactive system │\n│ └────────┬────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ Evaluate logic │ │\n│ │ conditions │ │\n│ └────────┬────────┘ │\n│ │ │\n│ ┌─────┴─────┐ │\n│ ▼ ▼ │\n│ ┌──────┐ ┌──────┐ │\n│ │ true │ │false │ │\n│ └──┬───┘ └──┬───┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ Apply Remove │\n│ effect effect │\n│ (hide, (show, │\n│ require, optional, │\n│ readonly) editable) │\n│ │\n└─────────────────────────────────────────────────────────────┘\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// ✅ Good - Easy to understand\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n\n// ❌ 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"
|
|
42
|
+
"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┌─────────────────────────────────────────────────────────────┐\n│ LOGIC EVALUATION FLOW │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ Form Value Changes │\n│ │ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ Signal Updates │◄──── Angular's reactive system │\n│ └────────┬────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────┐ │\n│ │ Evaluate logic │ │\n│ │ conditions │ │\n│ └────────┬────────┘ │\n│ │ │\n│ ┌─────┴─────┐ │\n│ ▼ ▼ │\n│ ┌──────┐ ┌──────┐ │\n│ │ true │ │false │ │\n│ └──┬───┘ └──┬───┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ Apply Remove │\n│ effect effect │\n│ (hide, (show, │\n│ require, optional, │\n│ readonly) editable) │\n│ │\n└─────────────────────────────────────────────────────────────┘\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 — 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`** — the current field's own state\n- **`formFieldState`** — 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 — 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 — 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 | — | Identifies this as an HTTP condition |\n| `http` | `HttpRequestConfig` | Yes | — | 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` — 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 — 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 | — | Identifies this as an async condition |\n| `asyncFunctionName` | `string` | Yes | — | 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 — 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// ✅ Good - Easy to understand\n{\n type: 'fieldValue',\n fieldPath: 'accountType',\n operator: 'equals',\n value: 'business',\n}\n\n// ❌ 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/)** — Computed field values\n- **[Async Derivation](../value-derivation/async/)** — HTTP and async function derivations, stopOnUserOverride\n- **[Validation](../../validation/basics/)** — Conditional validation\n- **[Custom Validators](../../validation/custom-validators/)** — Async and HTTP validators\n- **[Type Safety](../../advanced/type-safety/basics/)** — TypeScript integration\n- **[Examples](/examples)** — Real-world form patterns"
|
|
37
43
|
},
|
|
38
44
|
{
|
|
39
45
|
"id": "dynamic-behavior-i18n",
|
|
@@ -45,13 +51,25 @@
|
|
|
45
51
|
"id": "dynamic-behavior-submission",
|
|
46
52
|
"title": "Dynamic Behavior Submission",
|
|
47
53
|
"category": "dynamic-behavior",
|
|
48
|
-
"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```"
|
|
54
|
+
"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```"
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
"id": "dynamic-behavior-value-derivation-basics-async-derivation",
|
|
58
|
+
"title": "Dynamic Behavior Value Derivation Basics Async Derivation",
|
|
59
|
+
"category": "dynamic-behavior",
|
|
60
|
+
"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[]`** — Explicit field dependencies. The request only re-fires when these fields change.\n- **`responseExpression: string`** — 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 — 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`** — Name of the function registered in `customFnConfig.asyncDerivations`.\n- **`dependsOn: string[]`** — 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\" — 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 — 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 — identifies HTTP mode\n\n http: HttpRequestConfig; // Required — request configuration\n dependsOn: string[]; // Required — explicit field dependencies\n responseExpression: string; // Required — 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 — identifies async function mode\n\n asyncFunctionName: string; // Required — name in customFnConfig.asyncDerivations\n dependsOn: string[]; // Required — 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](./)** — Expression, static value, and function-based derivations\n- **[Properties](./property-derivation)** — Derive component properties from form values\n- **[HTTP Conditions](../../conditional-logic/overview/)** — HTTP-driven field visibility and state\n- **[Custom Validators](../../../validation/custom-validators/)** — Async and HTTP validation"
|
|
49
61
|
},
|
|
50
62
|
{
|
|
51
63
|
"id": "dynamic-behavior-value-derivation-basics",
|
|
52
64
|
"title": "Dynamic Behavior Value Derivation Basics",
|
|
53
65
|
"category": "dynamic-behavior",
|
|
54
|
-
"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 ─┐\n ├── subtotal ─┐\nunitPrice ─┘ ├── total\n │\n tax ─────────┘\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"
|
|
66
|
+
"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 ─┐\n ├── subtotal ─┐\nunitPrice ─┘ ├── total\n │\n tax ─────────┘\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) — Derive component properties (minDate, options, label) from form values\n- **Async Derivation** (see tab above) — HTTP and async function derivations, stopOnUserOverride\n- **[Conditional Logic](../conditional-logic/overview/)** — Control field visibility and state\n- **[Array Fields](../../prebuilt/form-arrays/simplified/)** — Working with array fields\n- **[Examples](/examples)** — Real-world form patterns"
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
"id": "dynamic-behavior-value-derivation-basics-property-derivation",
|
|
70
|
+
"title": "Dynamic Behavior Value Derivation Basics Property Derivation",
|
|
71
|
+
"category": "dynamic-behavior",
|
|
72
|
+
"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"
|
|
55
73
|
},
|
|
56
74
|
{
|
|
57
75
|
"id": "age-conditional-form",
|
|
@@ -59,6 +77,12 @@
|
|
|
59
77
|
"category": "examples",
|
|
60
78
|
"content": "[← 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"
|
|
61
79
|
},
|
|
80
|
+
{
|
|
81
|
+
"id": "array-form",
|
|
82
|
+
"title": "Array Form",
|
|
83
|
+
"category": "examples",
|
|
84
|
+
"content": "[← 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 — 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 — 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"
|
|
85
|
+
},
|
|
62
86
|
{
|
|
63
87
|
"id": "business-account-form",
|
|
64
88
|
"title": "Business Account Form",
|
|
@@ -101,6 +125,12 @@
|
|
|
101
125
|
"category": "examples",
|
|
102
126
|
"content": "[← 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"
|
|
103
127
|
},
|
|
128
|
+
{
|
|
129
|
+
"id": "simplified-array-form",
|
|
130
|
+
"title": "Simplified Array Form",
|
|
131
|
+
"category": "examples",
|
|
132
|
+
"content": "[← 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 — 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 — 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 — 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 — 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"
|
|
133
|
+
},
|
|
104
134
|
{
|
|
105
135
|
"id": "user-registration",
|
|
106
136
|
"title": "User Registration",
|
|
@@ -117,37 +147,43 @@
|
|
|
117
147
|
"id": "index",
|
|
118
148
|
"title": "Index",
|
|
119
149
|
"category": "installation",
|
|
120
|
-
"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- ✅ Real-time validation with error messages\n- ✅ TypeScript type inference\n- ✅ Material Design styling\n- ✅ Accessibility support\n- ✅ 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](../
|
|
150
|
+
"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- ✅ Real-time validation with error messages\n- ✅ TypeScript type inference\n- ✅ Material Design styling\n- ✅ Accessibility support\n- ✅ 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- 💬 **[GitHub Discussions](https://github.com/ng-forge/ng-forge/discussions)** - Ask questions and get help\n- 🐛 **[Issue Tracker](https://github.com/ng-forge/ng-forge/issues)** - Report bugs\n- 📖 **[Documentation](../)** - Browse full documentation"
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
"id": "form-arrays-complete",
|
|
154
|
+
"title": "Form Arrays Complete",
|
|
155
|
+
"category": "prebuilt",
|
|
156
|
+
"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) → **Primitive item** - extracts field value directly\n- **Array of FieldDefs** → **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."
|
|
121
157
|
},
|
|
122
158
|
{
|
|
123
|
-
"id": "form-arrays",
|
|
124
|
-
"title": "Form Arrays",
|
|
159
|
+
"id": "form-arrays-simplified",
|
|
160
|
+
"title": "Form Arrays Simplified",
|
|
125
161
|
"category": "prebuilt",
|
|
126
|
-
"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 → creates `[value1, value2]`\n- **Object arrays**: Template is a group field → 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.) → creates flat arrays\n- Group fields → creates object arrays\n- Row fields → for horizontal layouts within each array item\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how arrays affect type inference."
|
|
162
|
+
"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 → primitive array\n{ key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' } }\n\n// Discriminant: template is an array of fields → 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 — starts empty\n{\n key: 'tags',\n type: 'array',\n template: { key: 'value', type: 'input', label: 'Tag' },\n}\n\n// Explicit empty array — 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 — 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 — 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 — 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)."
|
|
127
163
|
},
|
|
128
164
|
{
|
|
129
165
|
"id": "form-groups",
|
|
130
166
|
"title": "Form Groups",
|
|
131
167
|
"category": "prebuilt",
|
|
132
|
-
"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
|
|
168
|
+
"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/)."
|
|
133
169
|
},
|
|
134
170
|
{
|
|
135
171
|
"id": "form-pages",
|
|
136
172
|
"title": "Form Pages",
|
|
137
173
|
"category": "prebuilt",
|
|
138
|
-
"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 (±1)**\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', ... }, // ✓ Rendered (adjacent)\n { key: 'step2', type: 'page', ... }, // ✓ Visible (current)\n { key: 'step3', type: 'page', ... }, // ✓ Rendered (adjacent)\n { key: 'step4', type: 'page', ... }, // ⏳ Deferred (distant)\n { key: 'step5', type: 'page', ... }, // ⏳ Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- ⚡ **Zero navigation flicker** - Adjacent pages already rendered\n- 🚀 **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- ⏱️ **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- 📱 **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"
|
|
174
|
+
"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 (±1)**\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', ... }, // ✓ Rendered (adjacent)\n { key: 'step2', type: 'page', ... }, // ✓ Visible (current)\n { key: 'step3', type: 'page', ... }, // ✓ Rendered (adjacent)\n { key: 'step4', type: 'page', ... }, // ⏳ Deferred (distant)\n { key: 'step5', type: 'page', ... }, // ⏳ Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- ⚡ **Zero navigation flicker** - Adjacent pages already rendered\n- 🚀 **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- ⏱️ **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- 📱 **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 — 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"
|
|
139
175
|
},
|
|
140
176
|
{
|
|
141
177
|
"id": "form-rows",
|
|
142
178
|
"title": "Form Rows",
|
|
143
179
|
"category": "prebuilt",
|
|
144
|
-
"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
|
|
180
|
+
"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/)."
|
|
145
181
|
},
|
|
146
182
|
{
|
|
147
183
|
"id": "hidden-fields",
|
|
148
184
|
"title": "Hidden Fields",
|
|
149
185
|
"category": "prebuilt",
|
|
150
|
-
"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)"
|
|
186
|
+
"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)"
|
|
151
187
|
},
|
|
152
188
|
{
|
|
153
189
|
"id": "text-components",
|
|
@@ -219,12 +255,12 @@
|
|
|
219
255
|
"id": "validation-custom-validators",
|
|
220
256
|
"title": "Validation Custom Validators",
|
|
221
257
|
"category": "validation",
|
|
222
|
-
"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// ✅ Works safely even when nested values are null/undefined\n{\n expression: 'fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// ❌ 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// ✅ 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// ✅ 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"
|
|
258
|
+
"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// ✅ Works safely even when nested values are null/undefined\n{\n expression: 'fieldValue !== formValue.user.profile.firstName',\n kind: 'invalidNested',\n}\n\n// ❌ 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// ✅ 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// ✅ 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 — 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 — 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 — 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"
|
|
223
259
|
},
|
|
224
260
|
{
|
|
225
261
|
"id": "validation-reference",
|
|
226
262
|
"title": "Validation Reference",
|
|
227
263
|
"category": "validation",
|
|
228
|
-
"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
|
|
264
|
+
"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 — 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 — all sub-conditions must be true\ninterface AndCondition {\n type: 'and';\n conditions: ConditionalExpression[];\n}\n\n// Logical OR — 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"
|
|
229
265
|
}
|
|
230
266
|
]
|