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

package/bin/ng-forge-mcp.js

@@ -24,7 +24,7 @@ var require_docs = __commonJS({
         id: "advanced-expression-parser",
         title: "Advanced Expression Parser",
         category: "advanced",
-        content: "Dynamic forms use expressions for conditional logic and dynamic values. When you use JavaScript expressions with `type: 'javascript'`, the expression parser evaluates them safely, preventing code injection attacks while maintaining the flexibility you need.\n\n## How JavaScript Expressions Work\n\nWhen you configure JavaScript expressions in your form:\n\n```typescript\n{\n  key: 'driverLicense',\n  type: 'input',\n  value: '',\n  label: 'Driver License',\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.age >= 18 && formValue.needsTransport === true'\n      },\n    }\n  ]\n}\n```\n\nThe expression `'formValue.age >= 18 && formValue.needsTransport === true'` is evaluated by the parser, which has access to:\n\n```typescript\n{\n  fieldValue: currentFieldValue,\n  formValue: { age: 25, needsTransport: true, ... },\n  fieldPath: 'driverLicense'\n}\n```\n\n## Security Model\n\nThe parser uses different rules for methods and properties:\n\n### Methods: Whitelist Only\n\nOnly safe methods can be called in expressions:\n\n```typescript\n// \u2705 Works - safe string methods\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.email.includes(\"@company.com\")'\n  }\n}\n\n// \u2705 Works - safe array methods\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.roles.some((role) => role === \"admin\")'\n  }\n}\n\n// \u274C Blocked - not whitelisted\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.text.link(\"url\")' // Error: Method \"link\" is not allowed\n  }\n}\n```\n\n### Whitelisted Methods Reference\n\n| Category   | Methods                                                                                                                                                           |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **String** | `toUpperCase`, `toLowerCase`, `trim`, `includes`, `startsWith`, `endsWith`, `slice`, `substring`, `charAt`, `indexOf`, `lastIndexOf`, `split`, `replace`, `match` |\n| **Array**  | `map`, `filter`, `some`, `every`, `find`, `findIndex`, `includes`, `indexOf`, `join`, `slice`, `flat`, `flatMap`                                                  |\n| **Number** | `toFixed`, `toString`, `valueOf`                                                                                                                                  |\n| **Object** | `hasOwnProperty`, `toString`, `valueOf`                                                                                                                           |\n\n### Properties: Open Access (Except Dangerous Ones)\n\nAll properties in the form data are accessible, except prototype properties:\n\n```typescript\n// \u2705 Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// \u274C Blocked - prototype pollution risks\nexpression: 'formValue.constructor'; // Error: Property \"constructor\" is not accessible\nexpression: 'formValue.__proto__'; // Error: Property \"__proto__\" is not accessible\n```\n\n**Why?** Dynamic forms need to access any field name you define. The parser blocks only the dangerous properties that could break security.\n\n### Safe Member Access (Built-in)\n\n**Important**: Member access is safe by default - accessing properties on `null` or `undefined` returns `undefined` instead of throwing errors:\n\n```typescript\n// \u2705 All of these work safely, even when intermediate values are null/undefined\nexpression: 'formValue.user.profile.firstName';\nexpression: 'formValue.address.city.toLowerCase()';\nexpression: 'formValue.settings.notifications.email';\n\n// If formValue.user is null, the expression returns undefined (no error thrown)\n// If formValue.user.profile is null, the expression returns undefined (no error thrown)\n// No manual null checks needed!\n```\n\n**This means you don't need to write defensive null checks:**\n\n```typescript\n// \u274C Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// \u2705 Better - Safe by default\nexpression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n```\n\nThe parser automatically handles null/undefined at every level of property access, making expressions cleaner and more maintainable.\n\n## Available Context Variables\n\nWhen expressions are evaluated, they have access to:\n\n```typescript\n{\n  fieldValue: 'current field value',\n  formValue: { /* entire form state */ },\n  fieldPath: 'fieldName',\n  externalData: { /* external application state, if configured */ }\n}\n```\n\n### External Data\n\nWhen you configure `externalData` in your FormConfig, it becomes available in expressions:\n\n```typescript\nconst config = {\n  externalData: {\n    userRole: computed(() => authService.role()),\n    permissions: computed(() => authService.permissions()),\n  },\n  fields: [\n    {\n      key: 'adminField',\n      type: 'input',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: \"externalData.userRole !== 'admin'\",\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n## Common Form Use Cases\n\n### Dynamic Visibility\n\n```typescript\n{\n  key: 'companyName',\n  type: 'input',\n  value: '',\n  label: 'Company Name',\n  // Show only if user selects \"Employed\"\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.employmentStatus !== \"employed\"'\n      }\n    }\n  ]\n}\n```\n\n### Conditional Required\n\n```typescript\n{\n  key: 'taxId',\n  type: 'input',\n  value: '',\n  label: 'Tax ID',\n  // Required only for business accounts\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.accountType === \"business\"'\n      },\n    }\n  ]\n}\n```\n\n### Complex Conditions\n\n```typescript\n{\n  key: 'personalConcierge',\n  type: 'checkbox',\n  value: false,\n  label: 'Request Personal Concierge Service',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.membershipLevel !== \"vip\" || formValue.annualIncome < 100000'\n      }\n    }\n  ]\n}\n```\n\n### String Methods in Expressions\n\n```typescript\n{\n  key: 'discountCode',\n  type: 'input',\n  value: '',\n  label: 'Discount Code',\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.email.endsWith(\"@company.com\")'\n      },\n    }\n  ]\n}\n```\n\n## What the Parser Prevents\n\nFor dynamic forms, the parser prevents:\n\n- \u2705 **Code Injection**: Can't execute `Function()`, `eval()`, or create new code\n- \u2705 **Prototype Pollution**: Can't access `constructor` or `__proto__`\n- \u2705 **Unsafe Operations**: Can't call methods that modify state or access globals\n\n## Custom Functions\n\nWhen providing custom functions for use in expressions, register them with the FunctionRegistryService:\n\n```typescript\n// \u2705 GOOD - Pure functions\nimport { FunctionRegistryService } from '@ng-forge/dynamic-forms';\n\nconst functionRegistry = inject(FunctionRegistryService);\n\nfunctionRegistry.registerCustomFunction('isValidEmail', (ctx) => {\n  return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(ctx.fieldValue);\n});\n\nfunctionRegistry.registerCustomFunction('isAdult', (ctx) => {\n  return ctx.formValue.age >= 18;\n});\n```\n\nThen use them with `type: 'custom'`:\n\n```typescript\n{\n  key: 'adultContent',\n  type: 'checkbox',\n  value: false,\n  label: 'Access Adult Content',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'custom',\n        expression: 'isAdult'\n      }\n    }\n  ]\n}\n```\n\n**Important**: Only provide pure functions without side effects:\n\n```typescript\n// \u274C BAD - Side effects\nfunctionRegistry.registerCustomFunction('logValue', (ctx) => {\n  console.log(ctx.fieldValue); // Side effect!\n  trackAnalytics(ctx); // Side effect!\n  return true;\n});\n```\n\n## Supported Expression Features\n\nIn JavaScript expressions (`type: 'javascript'`), you can use:\n\n| Feature               | Examples                                                        |\n| --------------------- | --------------------------------------------------------------- |\n| **Property access**   | `formValue.name`, `formValue.user.profile.email`                |\n| **Comparisons**       | `===`, `!==`, `>`, `<`, `>=`, `<=`                              |\n| **Logical operators** | `&&`, `\\|\\|`, `!`                                               |\n| **Arithmetic**        | `+`, `-`, `*`, `/`, `%`                                         |\n| **String methods**    | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n| **Array methods**     | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n\n**Example**:\n\n```typescript\nexpression: 'formValue.age >= 18 && formValue.email.includes(\"@example.com\")';\n```\n\n**Not Supported**: Object literals `{}`, ternary `a ? b : c`, assignment `x = 5`, `new` keyword, function declarations\n\n## Summary\n\nThe expression parser lets you write flexible conditional logic while preventing code injection attacks:\n\n1. **Form state is accessible** - Any field in `formValue` can be read\n2. **Methods are restricted** - Only safe, non-mutating methods allowed\n3. **Prototype is protected** - Can't access dangerous properties\n4. **Custom functions supported** - Register pure functions for reusable logic"
+        content: "Dynamic forms use expressions for conditional logic and dynamic values. When you use JavaScript expressions with `type: 'javascript'`, the expression parser evaluates them safely, preventing code injection attacks while maintaining the flexibility you need.\n\n## How JavaScript Expressions Work\n\nWhen you configure JavaScript expressions in your form:\n\n```typescript\n{\n  key: 'driverLicense',\n  type: 'input',\n  value: '',\n  label: 'Driver License',\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.age >= 18 && formValue.needsTransport === true'\n      },\n    }\n  ]\n}\n```\n\nThe expression `'formValue.age >= 18 && formValue.needsTransport === true'` is evaluated by the parser, which has access to:\n\n```typescript\n{\n  fieldValue: currentFieldValue,\n  formValue: { age: 25, needsTransport: true, ... },\n  fieldPath: 'driverLicense'\n}\n```\n\n## Security Model\n\nThe parser uses different rules for methods and properties:\n\n### Methods: Whitelist Only\n\nOnly safe methods can be called in expressions:\n\n```typescript\n// \u2705 Works - safe string methods\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.email.includes(\"@company.com\")'\n  }\n}\n\n// \u2705 Works - safe array methods\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.roles.some((role) => role === \"admin\")'\n  }\n}\n\n// \u274C Blocked - not whitelisted\n{\n  type: 'hidden',\n  condition: {\n    type: 'javascript',\n    expression: 'formValue.text.link(\"url\")' // Error: Method \"link\" is not allowed\n  }\n}\n```\n\n### Whitelisted Methods Reference\n\n| Category   | Methods                                                                                                                                                           |\n| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **String** | `toUpperCase`, `toLowerCase`, `trim`, `includes`, `startsWith`, `endsWith`, `slice`, `substring`, `charAt`, `indexOf`, `lastIndexOf`, `split`, `replace`, `match` |\n| **Array**  | `map`, `filter`, `some`, `every`, `find`, `findIndex`, `includes`, `indexOf`, `join`, `slice`, `flat`, `flatMap`                                                  |\n| **Number** | `toFixed`, `toString`, `valueOf`                                                                                                                                  |\n| **Object** | `hasOwnProperty`, `toString`, `valueOf`                                                                                                                           |\n\n### Properties: Open Access (Except Dangerous Ones)\n\nAll properties in the form data are accessible, except prototype properties:\n\n```typescript\n// \u2705 Works - access any form field\nexpression: 'formValue.firstName';\nexpression: 'formValue._internalFlag';\nexpression: 'formValue.nested.deeply.property';\n\n// \u274C Blocked - prototype pollution risks\nexpression: 'formValue.constructor'; // Error: Property \"constructor\" is not accessible\nexpression: 'formValue.__proto__'; // Error: Property \"__proto__\" is not accessible\n```\n\n**Why?** Dynamic forms need to access any field name you define. The parser blocks only the dangerous properties that could break security.\n\n### Safe Member Access (Built-in)\n\n**Important**: Member access is safe by default - accessing properties on `null` or `undefined` returns `undefined` instead of throwing errors:\n\n```typescript\n// \u2705 All of these work safely, even when intermediate values are null/undefined\nexpression: 'formValue.user.profile.firstName';\nexpression: 'formValue.address.city.toLowerCase()';\nexpression: 'formValue.settings.notifications.email';\n\n// If formValue.user is null, the expression returns undefined (no error thrown)\n// If formValue.user.profile is null, the expression returns undefined (no error thrown)\n// No manual null checks needed!\n```\n\n**This means you don't need to write defensive null checks:**\n\n```typescript\n// \u274C Unnecessary - Don't do this\nexpression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n\n// \u2705 Better - Safe by default\nexpression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName';\n```\n\nThe parser automatically handles null/undefined at every level of property access, making expressions cleaner and more maintainable.\n\n## Available Context Variables\n\nWhen expressions are evaluated, they have access to:\n\n```typescript\n{\n  fieldValue: 'current field value',\n  formValue: { /* entire form state */ },\n  fieldPath: 'fieldName',\n  externalData: { /* external application state, if configured */ }\n}\n```\n\n### External Data\n\nWhen you configure `externalData` in your FormConfig, it becomes available in expressions:\n\n```typescript\nconst config = {\n  externalData: {\n    userRole: computed(() => authService.role()),\n    permissions: computed(() => authService.permissions()),\n  },\n  fields: [\n    {\n      key: 'adminField',\n      type: 'input',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: \"externalData.userRole !== 'admin'\",\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n## Common Form Use Cases\n\n### Dynamic Visibility\n\n```typescript\n{\n  key: 'companyName',\n  type: 'input',\n  value: '',\n  label: 'Company Name',\n  // Show only if user selects \"Employed\"\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.employmentStatus !== \"employed\"'\n      }\n    }\n  ]\n}\n```\n\n### Conditional Required\n\n```typescript\n{\n  key: 'taxId',\n  type: 'input',\n  value: '',\n  label: 'Tax ID',\n  // Required only for business accounts\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.accountType === \"business\"'\n      },\n    }\n  ]\n}\n```\n\n### Complex Conditions\n\n```typescript\n{\n  key: 'personalConcierge',\n  type: 'checkbox',\n  value: false,\n  label: 'Request Personal Concierge Service',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.membershipLevel !== \"vip\" || formValue.annualIncome < 100000'\n      }\n    }\n  ]\n}\n```\n\n### String Methods in Expressions\n\n```typescript\n{\n  key: 'discountCode',\n  type: 'input',\n  value: '',\n  label: 'Discount Code',\n  logic: [\n    {\n      type: 'required',\n      condition: {\n        type: 'javascript',\n        expression: 'formValue.email.endsWith(\"@company.com\")'\n      },\n    }\n  ]\n}\n```\n\n## What the Parser Prevents\n\nFor dynamic forms, the parser prevents:\n\n- \u2705 **Code Injection**: Can't execute arbitrary code or create new code\n- \u2705 **Prototype Pollution**: Can't access `constructor` or `__proto__`\n- \u2705 **Unsafe Operations**: Can't call methods that modify state or access globals\n\n## Custom Functions\n\nWhen providing custom functions for use in expressions, register them with the FunctionRegistryService:\n\n```typescript\n// \u2705 GOOD - Pure functions\nimport { FunctionRegistryService } from '@ng-forge/dynamic-forms';\n\nconst functionRegistry = inject(FunctionRegistryService);\n\nfunctionRegistry.registerCustomFunction('isValidEmail', (ctx) => {\n  return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(ctx.fieldValue);\n});\n\nfunctionRegistry.registerCustomFunction('isAdult', (ctx) => {\n  return ctx.formValue.age >= 18;\n});\n```\n\nThen use them with `type: 'custom'`:\n\n```typescript\n{\n  key: 'adultContent',\n  type: 'checkbox',\n  value: false,\n  label: 'Access Adult Content',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'custom',\n        expression: 'isAdult'\n      }\n    }\n  ]\n}\n```\n\n**Important**: Only provide pure functions without side effects:\n\n```typescript\n// \u274C BAD - Side effects\nfunctionRegistry.registerCustomFunction('logValue', (ctx) => {\n  console.log(ctx.fieldValue); // Side effect!\n  trackAnalytics(ctx); // Side effect!\n  return true;\n});\n```\n\n## Supported Expression Features\n\nIn JavaScript expressions (`type: 'javascript'`), you can use:\n\n| Feature               | Examples                                                        |\n| --------------------- | --------------------------------------------------------------- |\n| **Property access**   | `formValue.name`, `formValue.user.profile.email`                |\n| **Comparisons**       | `===`, `!==`, `>`, `<`, `>=`, `<=`                              |\n| **Logical operators** | `&&`, `\\|\\|`, `!`                                               |\n| **Arithmetic**        | `+`, `-`, `*`, `/`, `%`                                         |\n| **String methods**    | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n| **Array methods**     | See [Whitelisted Methods](#whitelisted-methods-reference) above |\n\n**Example**:\n\n```typescript\nexpression: 'formValue.age >= 18 && formValue.email.includes(\"@example.com\")';\n```\n\n**Not Supported**: Object literals `{}`, ternary `a ? b : c`, assignment `x = 5`, `new` keyword, function declarations\n\n## Summary\n\nThe expression parser lets you write flexible conditional logic while preventing code injection attacks:\n\n1. **Form state is accessible** - Any field in `formValue` can be read\n2. **Methods are restricted** - Only safe, non-mutating methods allowed\n3. **Prototype is protected** - Can't access dangerous properties\n4. **Custom functions supported** - Register pure functions for reusable logic"
       },
       {
         id: "advanced-type-safety-basics",
@@ -32,6 +32,12 @@ var require_docs = __commonJS({
         category: "advanced",
         content: "Complete type inference for form configurations using TypeScript's type system and Angular signal forms.\n\n## Overview\n\nDynamic Forms provides compile-time type inference for form configurations, eliminating manual type definitions and catching errors before runtime. All form values are automatically inferred from your configuration using TypeScript's advanced type features.\n\n## Basic Type Inference\n\nUse `as const satisfies FormConfig` to enable type inference:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig = {\n  fields: [\n    { key: 'firstName', type: 'input', value: '' },\n    { key: 'email', type: 'input', value: '' },\n    { key: 'age', type: 'input', value: 0, props: { type: 'number' } },\n    { key: 'newsletter', type: 'checkbox', value: false },\n  ],\n} as const satisfies FormConfig;\n\n// Type is automatically inferred based on value property:\n// { firstName?: string; email?: string; age?: number; newsletter?: boolean }\n```\n\n**How it works:**\n\n1. `as const` makes the configuration deeply readonly, preserving literal types\n2. `satisfies FormConfig` validates the config structure without widening types\n3. TypeScript infers the form value type from the `value` properties\n\n## The `value` Property\n\nThe `value` property is critical for type inference - its type determines the inferred field type:\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'name', type: 'input', value: '' }, // string\n    { key: 'age', type: 'input', value: 0 }, // number\n    { key: 'active', type: 'checkbox', value: false }, // boolean\n    { key: 'tags', type: 'multi-checkbox', value: [] }, // string[]\n  ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n//   name?: string;\n//   age?: number;\n//   active?: boolean;\n//   tags?: string[];\n// }\n```\n\n## Field Registry System\n\nUI integrations register their field types via `provideDynamicForm`. For example, with Material Design:\n\n```typescript\n// app.config.ts\nimport { provideDynamicForm } from '@ng-forge/dynamic-forms';\nimport { withMaterialFields } from '@ng-forge/dynamic-forms-material';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideDynamicForm(...withMaterialFields()),\n    // other providers\n  ],\n};\n```\n\nMaterial fields augment the `FieldRegistryLeaves` interface for type safety:\n\n```typescript\n// From @ng-forge/dynamic-forms-material (already included)\ndeclare module '@ng-forge/dynamic-forms' {\n  interface FieldRegistryLeaves {\n    input: MatInputField;\n    select: MatSelectField<unknown>;\n    checkbox: MatCheckboxField;\n    // ... other Material fields\n  }\n}\n```\n\nThis determines:\n\n- What field `type` values are valid (e.g., `'input'`, `'select'`)\n- How each field type is structured\n- What props are available for each field\n\n**Example - Wrong field type:**\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'name', type: 'invalid', value: '' }, // TypeScript error!\n  ],\n} as const satisfies FormConfig;\n```\n\n## Required vs Optional Fields\n\nThe `required` flag affects whether fields include `undefined` in their type:\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'email', type: 'input', value: '', required: true }, // string (required)\n    { key: 'name', type: 'input', value: '' }, // string | undefined\n    { key: 'age', type: 'input', value: 0, required: false }, // number | undefined\n  ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n//   email: string;           // Required - no undefined\n//   name?: string;           // Optional - includes undefined\n//   age?: number;            // Optional - includes undefined\n// }\n```\n\n**In practice:**\n\n```typescript\nfunction handleSubmit(value: InferFormValue<typeof config.fields>) {\n  console.log(value.email.toUpperCase()); // \u2713 Safe - always defined\n  console.log(value.name?.toUpperCase()); // \u2713 Must use optional chaining\n  console.log(value.age + 1); // \u2717 Error - might be undefined\n}\n```\n\n## Using InferFormValue\n\nExtract the inferred type for use in your component:\n\n```typescript\nimport { signal } from '@angular/core';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\n@Component({...})\nexport class UserFormComponent {\n  config = {\n    fields: [\n      { key: 'username', type: 'input', value: '', required: true },\n      { key: 'age', type: 'input', value: 0 },\n    ]\n  } as const satisfies FormConfig;\n\n  // Extract type for signal\n  formValue = signal<InferFormValue<typeof this.config.fields>>({\n    username: '',\n  });\n\n  onSubmit() {\n    const value = this.formValue();\n    console.log(value.username);  // \u2713 Type: string (required)\n    console.log(value.age);       // \u2713 Type: number | undefined (optional)\n  }\n}\n```\n\n## IntelliSense Support\n\nTypeScript provides autocomplete for form values throughout your code:\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'firstName', type: 'input', value: '' },\n    { key: 'lastName', type: 'input', value: '' },\n    { key: 'email', type: 'input', value: '', required: true },\n  ],\n} as const satisfies FormConfig;\n\ntype FormValue = InferFormValue<typeof config.fields>;\n\nfunction processForm(value: FormValue) {\n  // IntelliSense suggests: firstName, lastName, email\n  value.firstName; // \u2713 Autocomplete works\n  value.lastName; // \u2713 Autocomplete works\n  value.email; // \u2713 Autocomplete works\n  value.invalid; // \u2717 TypeScript error - property doesn't exist\n}\n```\n\n## Best Practices\n\n### Always Use `as const satisfies FormConfig`\n\nThis enables type inference and validates your configuration:\n\n```typescript\n// \u2713 Correct - enables inference + type checking\nconst config = { fields: [...] } as const satisfies FormConfig;\n\n// \u2717 Wrong - no inference\nconst config = { fields: [...] };\n\n// \u2717 Wrong - too wide, loses precision\nconst config: FormConfig = { fields: [...] };\n```\n\n### Define Configs as Constants\n\nExport form configs as constants for reuse and consistent typing:\n\n```typescript\n// form-configs.ts\nexport const USER_FORM = {\n  fields: [\n    { key: 'name', type: 'input', value: '', required: true },\n    { key: 'email', type: 'input', value: '', required: true },\n  ],\n} as const satisfies FormConfig;\n\n// user-form.component.ts\nimport { USER_FORM } from './form-configs';\n\n@Component({...})\nexport class UserFormComponent {\n  config = USER_FORM;\n}\n```\n\n### Always Include `value` Property\n\nType inference requires the `value` property to determine field types:\n\n```typescript\n// \u2713 Good - type inferred from value\nconst config = {\n  fields: [\n    { key: 'age', type: 'input', value: 0 }, // number\n    { key: 'name', type: 'input', value: '' }, // string\n    { key: 'active', type: 'checkbox', value: false }, // boolean\n  ],\n} as const satisfies FormConfig;\n\n// \u2717 Bad - without value, type inference may not work correctly\nconst config = {\n  fields: [\n    { key: 'age', type: 'input' }, // Type unclear\n  ],\n} as const satisfies FormConfig;\n```\n\n### Extract Types When Needed\n\nCreate type aliases for complex form values:\n\n```typescript\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst REGISTRATION_FORM = {\n  fields: [\n    { key: 'username', type: 'input', value: '', required: true },\n    { key: 'email', type: 'input', value: '', required: true },\n    { key: 'password', type: 'input', value: '', required: true },\n  ],\n} as const satisfies FormConfig;\n\n// Export type for reuse\nexport type RegistrationFormValue = InferFormValue<(typeof REGISTRATION_FORM)['fields']>;\n\n// Use in functions\nfunction registerUser(data: RegistrationFormValue) {\n  console.log(data.username, data.email, data.password);\n}\n```\n\n## Troubleshooting\n\n### Type inference not working\n\nType inference requires `as const` - without it, TypeScript treats your config as mutable:\n\n```typescript\n// \u2717 No inference - types are too wide\nconst config = {\n  fields: [{ key: 'name', type: 'input', value: '' }],\n};\n// Type: { fields: { key: string; type: string; value: string }[] }\n\n// \u2713 With as const - precise inference\nconst config = {\n  fields: [{ key: 'name', type: 'input', value: '' }],\n} as const satisfies FormConfig;\n// Type inferred: { name?: string }\n```\n\n### `satisfies` vs type annotation\n\nDon't use type annotation (`const config: FormConfig = ...`) as it widens types:\n\n```typescript\n// \u2717 Wrong - type is widened, inference fails\nconst config: FormConfig = {\n  fields: [{ key: 'name', type: 'input', value: '' }],\n} as const;\n\n// \u2713 Correct - satisfies validates without widening\nconst config = {\n  fields: [{ key: 'name', type: 'input', value: '' }],\n} as const satisfies FormConfig;\n```\n\n### Dynamic form configs\n\nType inference only works for **static**, **compile-time constant** configurations:\n\n```typescript\n// \u2717 Dynamic - no inference possible\nconst fields = getFieldsFromAPI(); // Returns field array at runtime\nconst config = { fields } as const satisfies FormConfig;\n// Can't infer - TypeScript doesn't know what getFieldsFromAPI() returns\n\n// For dynamic forms, manually type your form values:\ninterface MyFormValue {\n  name: string;\n  email: string;\n}\n\nconst formValue = signal<MyFormValue>({ name: '', email: '' });\n```\n\nIf your form configuration is built dynamically (from API data, conditional logic, or runtime calculations), you'll need to manually define the form value type.\n\n## Container Fields\n\nUnderstanding how container fields affect type inference and form value structure.\n\n### Container Fields Overview\n\nContainer fields organize form layout and structure without directly contributing values. There are three types:\n\n- **Group Fields** - Nest children under a single key\n- **Row Fields** - Organize fields horizontally, flatten children to parent level\n- **Page Fields** - Multi-step forms, flatten children to parent level\n\nEach container type has different behavior for type inference and form values.\n\n### Group Fields\n\nGroups nest children under a single key, creating nested objects in the form value:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      type: 'group',\n      key: 'address',\n      label: 'Address Information',\n      fields: [\n        { key: 'street', type: 'input', value: '' },\n        { key: 'city', type: 'input', value: '' },\n        { key: 'zip', type: 'input', value: '' },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Inferred type:\n// {\n//   address: {\n//     street?: string;\n//     city?: string;\n//     zip?: string;\n//   }\n// }\n```\n\n**Use groups when:**\n\n- You want nested form values (e.g., `address.street`)\n- Grouping related fields logically\n- Creating reusable field sections\n\n**Example - Nested address:**\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'name', type: 'input', value: '', required: true },\n    {\n      type: 'group',\n      key: 'address',\n      fields: [\n        { key: 'street', type: 'input', value: '', required: true },\n        { key: 'city', type: 'input', value: '', required: true },\n        { key: 'state', type: 'select', value: '', required: true, options: [] },\n        { key: 'zip', type: 'input', value: '' },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Form value structure:\n// {\n//   name: string;\n//   address: {\n//     street: string;\n//     city: string;\n//     state: string;\n//     zip?: string;\n//   }\n// }\n\nfunction onSubmit(value: InferFormValue<typeof config.fields>) {\n  console.log(value.name); // string\n  console.log(value.address.street); // string\n  console.log(value.address.city); // string\n  console.log(value.address.zip); // string | undefined\n}\n```\n\n### Row Fields\n\nRows organize fields horizontally for layout purposes, but flatten children to the parent level in form values:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      type: 'row',\n      fields: [\n        { key: 'firstName', type: 'input', value: '' },\n        { key: 'lastName', type: 'input', value: '' },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Inferred type (flattened):\n// {\n//   firstName?: string;\n//   lastName?: string;\n// }\n```\n\n**Use rows when:**\n\n- You want horizontal layout (grid columns)\n- Fields should be at the parent level (not nested)\n- Creating responsive multi-column forms\n\n**Row vs Group:**\n\n```typescript\n// Row - fields are flattened\n{\n  type: 'row',\n  fields: [\n    { key: 'firstName', type: 'input', value: '' },\n    { key: 'lastName', type: 'input', value: '' },\n  ],\n}\n// Result: { firstName?: string, lastName?: string }\n\n// Group - fields are nested\n{\n  type: 'group',\n  key: 'name',\n  fields: [\n    { key: 'firstName', type: 'input', value: '' },\n    { key: 'lastName', type: 'input', value: '' },\n  ],\n}\n// Result: { name: { firstName?: string, lastName?: string } }\n```\n\n### Page Fields\n\nPages organize multi-step forms, flattening all children to the root level:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      key: 'page1',\n      type: 'page',\n      fields: [\n        { key: 'page1Title', type: 'text', label: 'Personal Information', props: { elementType: 'h3' } },\n        { key: 'email', type: 'input', value: '' },\n        { key: 'password', type: 'input', value: '' },\n      ],\n    },\n    {\n      key: 'page2',\n      type: 'page',\n      fields: [\n        { key: 'page2Title', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n        { key: 'firstName', type: 'input', value: '' },\n        { key: 'lastName', type: 'input', value: '' },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Inferred type (all pages flattened):\n// {\n//   email?: string;\n//   password?: string;\n//   firstName?: string;\n//   lastName?: string;\n// }\n```\n\n**Use pages when:**\n\n- Creating multi-step forms (wizard-style)\n- Fields from all steps should be at root level\n- You want step-by-step validation\n\n### Nesting Rules\n\nContainer fields enforce nesting constraints at compile-time to prevent invalid structures.\n\n**Visual Reference:**\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                      NESTING RULES                          \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502                                                             \u2502\n\u2502  PAGE \u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u25BA ROW \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u25BA GROUP \u2500\u2500\u252C\u2500\u2500\u25BA LEAF FIELD  \u2502\n\u2502             \u2502                \u2502            \u2502                 \u2502\n\u2502             \u251C\u2500\u2500\u25BA GROUP \u2500\u2500\u2500\u2500\u2500\u2500\u253C\u2500\u2500\u25BA ROW \u2500\u2500\u2500\u2500\u2534\u2500\u2500\u25BA LEAF FIELD  \u2502\n\u2502             \u2502                \u2502                              \u2502\n\u2502             \u2514\u2500\u2500\u25BA LEAF FIELD  \u2514\u2500\u2500\u25BA LEAF FIELD               \u2502\n\u2502                                                             \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502  \u2717 PAGE cannot contain PAGE                                 \u2502\n\u2502  \u2717 ROW cannot contain ROW or PAGE                          \u2502\n\u2502  \u2717 GROUP cannot contain GROUP or PAGE                      \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n**Valid Nesting:**\n\n- **Pages** can contain: rows, groups, leaf fields (not other pages)\n- **Rows** can contain: groups, leaf fields (not pages or rows)\n- **Groups** can contain: rows, leaf fields (not pages or other groups)\n\n**Invalid Nesting:**\n\nTypeScript will prevent these invalid structures:\n\n```typescript\n// \u2717 Invalid: page inside page\nconst config1 = {\n  fields: [\n    {\n      type: 'page',\n      fields: [\n        { type: 'page', fields: [] }, // TypeScript error!\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// \u2717 Invalid: row inside row\nconst config2 = {\n  fields: [\n    {\n      type: 'row',\n      fields: [\n        { type: 'row', fields: [] }, // TypeScript error!\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n### Value-Bearing vs Display Fields\n\nFields are categorized by whether they contribute to form values:\n\n**Value-Bearing Fields:**\n\nFields with a `value` property contribute to the form output:\n\n- `input`, `select`, `checkbox`, `textarea`, `datepicker`, `slider`, `toggle`, etc.\n\n**Display-Only Fields:**\n\nFields without values are excluded from form values:\n\n- `text` - displays content\n- `page`, `row`, `group` - container fields (children may have values)\n- Buttons - `submit`, `reset`, navigation buttons\n- Custom display components\n\n```typescript\nconst config = {\n  fields: [\n    { type: 'text', label: 'Enter your details:' }, // \u2717 Excluded\n    { key: 'name', type: 'input', value: '' }, // \u2713 Included\n    { type: 'submit', label: 'Save' }, // \u2717 Excluded\n    {\n      type: 'row', // \u2717 Excluded (container)\n      fields: [\n        { key: 'city', type: 'input', value: '' }, // \u2713 Included\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Only value-bearing fields:\n// {\n//   name?: string;\n//   city?: string;\n// }\n```\n\n### Array Fields\n\nMulti-select fields and multi-checkbox fields return arrays:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      key: 'skills',\n      type: 'select',\n      value: [],\n      props: { multiple: true },\n      options: [\n        { value: 'js', label: 'JavaScript' },\n        { value: 'ts', label: 'TypeScript' },\n        { value: 'go', label: 'Go' },\n      ],\n    },\n    {\n      key: 'interests',\n      type: 'multi-checkbox',\n      value: [],\n      options: [\n        { value: 'sports', label: 'Sports' },\n        { value: 'music', label: 'Music' },\n        { value: 'reading', label: 'Reading' },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Type: { skills?: string[]; interests?: string[] }\n```\n\n## Advanced Patterns\n\n### Runtime Validation\n\nForm values are typed at compile-time via `InferFormValue`, but runtime validation may be needed:\n\n#### Type Assertion (Trust Form Structure)\n\nIf you trust the form structure, cast the value:\n\n```typescript\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst USER_FORM = {\n  fields: [\n    { key: 'username', type: 'input', value: '', required: true },\n    { key: 'email', type: 'input', value: '', required: true },\n    { key: 'age', type: 'input', value: 0 },\n  ],\n} as const satisfies FormConfig;\n\ntype UserFormValue = InferFormValue<(typeof USER_FORM)['fields']>;\n\nfunction onSubmit(value: unknown) {\n  // Cast to inferred type\n  const data = value as UserFormValue;\n\n  console.log(data.username); // string\n  console.log(data.email); // string\n  console.log(data.age); // number | undefined\n}\n```\n\n#### Runtime Validation with Zod\n\nFor runtime guarantees, use a validation library like Zod:\n\n```typescript\nimport { z } from 'zod';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst USER_FORM = {\n  fields: [\n    { key: 'username', type: 'input', value: '', required: true },\n    { key: 'email', type: 'input', value: '', required: true },\n    { key: 'age', type: 'input', value: 0 },\n  ],\n} as const satisfies FormConfig;\n\n// Define Zod schema matching form structure\nconst userSchema = z.object({\n  username: z.string().min(1),\n  email: z.string().email(),\n  age: z.number().optional(),\n});\n\nfunction onSubmit(value: unknown) {\n  // Runtime validation\n  const result = userSchema.safeParse(value);\n\n  if (!result.success) {\n    console.error('Validation failed:', result.error);\n    return;\n  }\n\n  // Type-safe access\n  const data = result.data;\n  console.log(data.username); // string\n  console.log(data.email); // string\n  console.log(data.age); // number | undefined\n}\n```\n\n#### Combining Compile-Time and Runtime\n\nUse both for maximum safety:\n\n```typescript\nimport { z } from 'zod';\nimport { InferFormValue } from '@ng-forge/dynamic-forms';\n\nconst REGISTRATION_FORM = {\n  fields: [\n    { key: 'username', type: 'input', value: '', required: true },\n    { key: 'email', type: 'input', value: '', required: true },\n    { key: 'password', type: 'input', value: '', required: true },\n    { key: 'confirmPassword', type: 'input', value: '', required: true },\n  ],\n} as const satisfies FormConfig;\n\n// Compile-time type\ntype RegistrationValue = InferFormValue<typeof REGISTRATION_FORM['fields']>;\n\n// Runtime schema (with additional validation)\nconst registrationSchema = z.object({\n  username: z.string().min(3).max(20),\n  email: z.string().email(),\n  password: z.string().min(8),\n  confirmPassword: z.string(),\n}).refine((data) => data.password === data.confirmPassword, {\n  message: \"Passwords don't match\",\n  path: ['confirmPassword'],\n});\n\n@Component({...})\nexport class RegistrationComponent {\n  config = REGISTRATION_FORM;\n\n  // Compile-time type for signal\n  formValue = signal<RegistrationValue>({\n    username: '',\n    email: '',\n    password: '',\n    confirmPassword: '',\n  });\n\n  onSubmit() {\n    const value = this.formValue();\n\n    // Runtime validation with cross-field check\n    const result = registrationSchema.safeParse(value);\n\n    if (!result.success) {\n      console.error('Validation failed:', result.error);\n      return;\n    }\n\n    // Safe to use\n    this.register(result.data);\n  }\n}\n```\n\n### Type-Safe Validation\n\nng-forge integrates validation with the type system. Validators affect the inferred type:\n\n#### Shorthand Validators\n\nShorthand validators are simple and affect type inference:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      key: 'email',\n      type: 'input',\n      value: '',\n      required: true, // Removes undefined from type\n      email: true, // Email validation\n      minLength: 5, // Min length validation\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Type inferred: { email: string } (required, so no undefined)\n```\n\n#### Validator Array\n\nFor complex validation, use the `validators` array:\n\n```typescript\nconst config = {\n  fields: [\n    {\n      key: 'discount',\n      type: 'input',\n      value: 0,\n      validators: [\n        {\n          type: 'min',\n          value: 0,\n        },\n        {\n          type: 'max',\n          value: 100,\n          when: {\n            type: 'fieldValue',\n            fieldPath: 'discountType',\n            operator: 'equals',\n            value: 'percentage',\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n#### Conditional Required\n\nUse the `logic` array for conditional required fields:\n\n```typescript\nconst config = {\n  fields: [\n    { key: 'accountType', type: 'select', value: '', options: [] },\n    {\n      key: 'taxId',\n      type: 'input',\n      value: '',\n      logic: [\n        {\n          type: 'required',\n          condition: {\n            type: 'fieldValue',\n            fieldPath: 'accountType',\n            operator: 'equals',\n            value: 'business',\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Type: { accountType?: string; taxId?: string }\n// Note: Conditional required doesn't affect type inference\n```\n\n## Related\n\n- **[Validation](../../validation/basics/)** - How validators affect inferred types\n- **[Field Types](../../schema-fields/field-types/)** - Understanding available field types\n- **[Form Layout](../../prebuilt/form-groups/)** - Visual guide to container fields"
       },
+      {
+        id: "advanced-value-exclusion",
+        title: "Advanced Value Exclusion",
+        category: "advanced",
+        content: "Value exclusion controls which field values are included in the form submission output based on the field's reactive state (hidden, disabled, readonly).\n\n## Overview\n\nBy default, field values are **excluded** from the `(submitted)` output when the field is hidden, disabled, or readonly. This prevents stale or irrelevant data from being sent to the server.\n\n**Key point:** Value exclusion only affects the submission output. Internal form controls retain their values so they can be restored when a field becomes visible, enabled, or editable again. Two-way binding via `[value]` / `[(value)]` is **not affected**.\n\n## Default Behavior\n\nWhen no configuration is specified, the defaults are:\n\n| Rule                     | Default | Effect                                              |\n| ------------------------ | ------- | --------------------------------------------------- |\n| `excludeValueIfHidden`   | `true`  | Hidden field values are excluded from submission    |\n| `excludeValueIfDisabled` | `true`  | Disabled field values are excluded from submission  |\n| `excludeValueIfReadonly` | `true`  | Read-only field values are excluded from submission |\n\n> **Breaking change from pre-1.0:** Previously, all field values were always included. To restore the old behavior, see [Migration from Previous Versions](#migration-from-previous-versions).\n\n## 3-Tier Configuration\n\nValue exclusion supports a 3-tier configuration hierarchy. The most specific level wins for each property:\n\n| Priority | Level  | Where to set                                    |\n| -------- | ------ | ----------------------------------------------- |\n| 1 (wins) | Field  | `excludeValueIf*` on individual `FieldDef`      |\n| 2        | Form   | `excludeValueIf*` on `FormOptions`              |\n| 3        | Global | `withValueExclusionDefaults()` feature function |\n\nIf a property is `undefined` at a given level, the next level down is checked.\n\n## Global Configuration\n\nUse `withValueExclusionDefaults()` in your provider setup to configure global defaults:\n\n```typescript\nimport { provideDynamicForm, withValueExclusionDefaults } from '@ng-forge/dynamic-forms';\n\n// All exclusions enabled (same as default)\nprovideDynamicForm(...withMaterialFields(), withValueExclusionDefaults());\n\n// Disable readonly exclusion globally\nprovideDynamicForm(...withMaterialFields(), withValueExclusionDefaults({ excludeValueIfReadonly: false }));\n\n// Disable all exclusions globally (pre-1.0 behavior)\nprovideDynamicForm(\n  ...withMaterialFields(),\n  withValueExclusionDefaults({\n    excludeValueIfHidden: false,\n    excludeValueIfDisabled: false,\n    excludeValueIfReadonly: false,\n  }),\n);\n```\n\n## Form-Level Configuration\n\nOverride the global setting for a specific form using `FormOptions`:\n\n```typescript\nconst config: FormConfig = {\n  fields: [...],\n  options: {\n    // Include hidden field values for this form only\n    excludeValueIfHidden: false,\n    // Use global default for disabled and readonly\n  }\n};\n```\n\n## Field-Level Configuration\n\nOverride both global and form settings for a specific field:\n\n```typescript\nconst config: FormConfig = {\n  fields: [\n    {\n      type: 'input',\n      key: 'internalId',\n      label: 'Internal ID',\n      readonly: true,\n      // Always include this field's value, even when readonly\n      excludeValueIfReadonly: false,\n    },\n    {\n      type: 'input',\n      key: 'notes',\n      label: 'Notes',\n      // This field uses the form/global defaults\n    },\n  ],\n};\n```\n\n## Resolution Example\n\nGiven these settings:\n\n- **Global:** `excludeValueIfHidden: true`\n- **Form:** `excludeValueIfHidden: false`\n- **Field A:** `excludeValueIfHidden: undefined` (not set)\n- **Field B:** `excludeValueIfHidden: true`\n\nResolution:\n\n- **Field A** uses form-level (`false`) because field-level is `undefined` &rarr; value is **included** when hidden\n- **Field B** uses field-level (`true`) &rarr; value is **excluded** when hidden\n\n## HiddenField Type\n\nThe `HiddenField` type (`type: 'hidden'`) is **not affected** by value exclusion. These fields:\n\n- Store values without rendering any UI\n- Have a `hidden()` reactive state of `false` (they are part of the form, just not rendered)\n- Are always included in submission output\n\nValue exclusion applies to the `hidden` **property** on regular fields (e.g., `{ type: 'input', hidden: true }` or fields hidden via conditional logic), not to the `HiddenField` type.\n\n## What's Excluded vs Retained\n\n| Aspect                     | Affected by exclusion? | Details                                  |\n| -------------------------- | ---------------------- | ---------------------------------------- |\n| `(submitted)` output       | Yes                    | Excluded fields are omitted              |\n| `filteredFormValue` signal | Yes                    | Same filtering as submission             |\n| `formValue` signal         | No                     | Always contains all values               |\n| `[(value)]` binding        | No                     | Two-way binding retains all values       |\n| Internal form controls     | No                     | Fields keep their values for restoration |\n\n## Migration from Previous Versions\n\nIf you relied on all field values being present in `(submitted)` output, disable exclusion globally:\n\n```typescript\nprovideDynamicForm(\n  ...withMaterialFields(),\n  withValueExclusionDefaults({\n    excludeValueIfHidden: false,\n    excludeValueIfDisabled: false,\n    excludeValueIfReadonly: false,\n  }),\n);\n```\n\nOr disable per-form via `FormOptions`:\n\n```typescript\nconst config: FormConfig = {\n  fields: [...],\n  options: {\n    excludeValueIfHidden: false,\n    excludeValueIfDisabled: false,\n    excludeValueIfReadonly: false,\n  }\n};\n```"
+      },
       {
         id: "ai-integration",
         title: "AI Integration",
@@ -42,7 +48,7 @@ var require_docs = __commonJS({
         id: "dynamic-behavior-conditional-logic-overview",
         title: "Dynamic Behavior Conditional Logic Overview",
         category: "dynamic-behavior",
-        content: "Control field behavior dynamically based on form state. Dynamic forms provides a declarative API for conditional visibility, required state, and readonly state that maps directly to Angular's signal forms.\n\n## Signal Forms Integration\n\nThe library integrates with Angular's signal forms logic functions:\n\n```typescript\nimport { hidden, readonly, required } from '@angular/forms/signals';\n```\n\nAll conditional logic configuration is applied using these functions, providing:\n\n- **Reactive updates** when form state changes\n- **Type-safe** conditional expressions\n- **Automatic re-evaluation** on dependencies\n- **Integration** with form validation state\n\n## Static Properties\n\nUse simple boolean properties for fields with fixed states.\n\n### hidden\n\nHide a field from view (field still participates in form state):\n\n```typescript\n{\n  key: 'internalId',\n  type: 'input',\n  value: '',\n  label: 'Internal ID',\n  hidden: true,\n}\n```\n\nThe field is hidden from the UI but still included in the form value.\n\n### disabled\n\nDisable user interaction:\n\n```typescript\n{\n  key: 'systemField',\n  type: 'input',\n  value: 'auto-generated',\n  label: 'System Field',\n  disabled: true,\n}\n```\n\n**Note:** The `disabled` property is handled at the component level and does not use signal forms logic functions. It's a static UI property that prevents user interaction.\n\n### readonly\n\nMake a field read-only (displays value but prevents modification):\n\n```typescript\n{\n  key: 'createdAt',\n  type: 'input',\n  value: '2024-01-15',\n  label: 'Created Date',\n  readonly: true,\n}\n```\n\n## Dynamic Conditional Logic\n\nFor conditional behavior based on form state, use the `logic` array with `LogicConfig` objects.\n\n```typescript\ninterface LogicConfig {\n  /** Logic type */\n  type: 'hidden' | 'readonly' | 'disabled' | 'required';\n\n  /** Boolean expression, static value, or form state condition */\n  condition: ConditionalExpression | boolean | FormStateCondition;\n}\n```\n\n`FormStateCondition` values (`'formInvalid'`, `'formSubmitting'`, `'pageInvalid'`) are primarily used for button disabled logic.\n\n### Conditional Visibility (hidden)\n\nShow or hide fields based on other field values.\n\n#### Show Email When Contact Method is Email\n\n```typescript\n{\n  key: 'contactMethod',\n  type: 'select',\n  value: '',\n  options: [\n    { value: 'email', label: 'Email' },\n    { value: 'phone', label: 'Phone' },\n  ],\n}\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  label: 'Email Address',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'contactMethod',\n      operator: 'notEquals',\n      value: 'email',\n    },\n  }],\n}\n```\n\nWhen `contactMethod !== 'email'`, the email field is hidden.\n\n### Conditional Required\n\nMake fields required based on conditions.\n\n#### Tax ID Required for Business Accounts\n\n```typescript\n{\n  key: 'accountType',\n  type: 'radio',\n  value: 'personal',\n  options: [\n    { value: 'personal', label: 'Personal' },\n    { value: 'business', label: 'Business' },\n  ],\n}\n{\n  key: 'taxId',\n  type: 'input',\n  value: '',\n  label: 'Tax ID',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n### Conditional Readonly\n\nMake fields read-only based on conditions.\n\n#### Lock Field After Submission\n\n```typescript\n{\n  key: 'status',\n  type: 'select',\n  value: 'draft',\n  options: [\n    { value: 'draft', label: 'Draft' },\n    { value: 'submitted', label: 'Submitted' },\n  ],\n}\n{\n  key: 'documentNumber',\n  type: 'input',\n  value: '',\n  label: 'Document Number',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'status',\n      operator: 'equals',\n      value: 'submitted',\n    },\n  }],\n}\n```\n\nOnce status is \"submitted\", the document number becomes read-only.\n\n## Basic Conditional Expression\n\nThe most common conditional expression checks a specific field's value:\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'fieldKey',\n  operator: 'equals',\n  value: 'expectedValue',\n}\n```\n\n**Components:**\n\n- `type: 'fieldValue'` - Check a specific field\n- `fieldPath` - The field key to check\n- `operator` - Comparison operator (see [All Operators](#all-operators))\n- `value` - Value to compare against\n\n## Quick Example\n\nShow a field only when another field has a specific value:\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  label: 'Email Address',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'contactMethod',\n        operator: 'notEquals',\n        value: 'email',\n      },\n    },\n    {\n      type: 'required',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'contactMethod',\n        operator: 'equals',\n        value: 'email',\n      },\n    },\n  ],\n}\n```\n\nThis field is hidden unless `contactMethod === 'email'`, and required when visible. See the [Examples](/docs/examples) page for complete form implementations.\n\n## When Logic Runs\n\nConditional logic is evaluated:\n\n- **On form value change** - Any time a dependent field changes\n- **On initialization** - When the form is created\n- **Reactively** - Uses Angular's signal forms for automatic updates\n\n### Evaluation Flow\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                    LOGIC EVALUATION FLOW                    \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502                                                             \u2502\n\u2502  Form Value Changes                                         \u2502\n\u2502         \u2502                                                   \u2502\n\u2502         \u25BC                                                   \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 Signal Updates  \u2502\u25C4\u2500\u2500\u2500\u2500 Angular's reactive system        \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                                       \u2502\n\u2502           \u2502                                                 \u2502\n\u2502           \u25BC                                                 \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 Evaluate logic  \u2502                                       \u2502\n\u2502  \u2502    conditions   \u2502                                       \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                                       \u2502\n\u2502           \u2502                                                 \u2502\n\u2502     \u250C\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2510                                          \u2502\n\u2502     \u25BC           \u25BC                                          \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 true \u2502   \u2502false \u2502                                       \u2502\n\u2502  \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518                                       \u2502\n\u2502     \u2502          \u2502                                            \u2502\n\u2502     \u25BC          \u25BC                                            \u2502\n\u2502  Apply      Remove                                          \u2502\n\u2502  effect     effect                                          \u2502\n\u2502  (hide,     (show,                                          \u2502\n\u2502  require,   optional,                                       \u2502\n\u2502  readonly)  editable)                                       \u2502\n\u2502                                                             \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Expression Types\n\n### fieldValue\n\nCheck a specific field's value - the most common expression type.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'accountType',\n  operator: 'equals',\n  value: 'business',\n}\n```\n\n**Use when:** Checking a single field's value\n\n**Example:**\n\n```typescript\n{\n  key: 'companyName',\n  type: 'input',\n  value: '',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n### formValue\n\nCompare the entire form value object against a specific value using operators.\n\n```typescript\n{\n  type: 'formValue',\n  operator: 'equals',\n  value: { status: 'active', role: 'admin' },\n}\n```\n\n**Use when:** Checking if the entire form matches a specific state\n\n**Note:** For complex logic involving multiple fields with JavaScript expressions, use `javascript` or `custom` type instead.\n\n### javascript\n\nJavaScript expressions with access to `fieldValue` (current field) and `formValue` (entire form).\n\n```typescript\n{\n  type: 'javascript',\n  expression: 'new Date(fieldValue) > new Date()',\n}\n```\n\n**Use when:** Custom logic on field value or complex multi-field conditions\n\n**Examples:**\n\n```typescript\n// Check current field value\n{\n  key: 'eventDate',\n  type: 'datepicker',\n  value: null,\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'javascript',\n      expression: 'new Date(fieldValue) < new Date()',\n    },\n  }],\n}\n\n// Check multiple form fields (replaces old formValue expression pattern)\n{\n  key: 'stateProvince',\n  type: 'select',\n  value: '',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'javascript',\n      expression: 'formValue.country !== \"US\" && formValue.country !== \"CA\"',\n    },\n  }],\n}\n```\n\n**Safe member access:** Accessing nested properties on `null` or `undefined` returns `undefined` (no errors thrown):\n\n```typescript\n{\n  type: 'javascript',\n  // Safe even when user, profile, or preferences is null/undefined\n  expression: 'formValue.user.profile.preferences.notifications === true',\n}\n```\n\n### custom\n\nAdvanced custom expressions with access to both field and form values.\n\n```typescript\n{\n  type: 'custom',\n  expression: 'fieldValue > formValue.minAge && fieldValue < formValue.maxAge',\n}\n```\n\n**Safe member access:** Like `formValue` expressions, nested property access is safe:\n\n```typescript\n{\n  type: 'custom',\n  // Safe even when nested values are null/undefined\n  expression: 'fieldValue !== formValue.user.profile.firstName',\n}\n```\n\n## All Operators\n\n### Equality Operators\n\n#### equals\n\nExact match comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'status',\n  operator: 'equals',\n  value: 'active',\n}\n```\n\n#### notEquals\n\nNot equal to comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'status',\n  operator: 'notEquals',\n  value: 'archived',\n}\n```\n\n### Comparison Operators\n\n#### greater\n\nGreater than comparison (numbers/dates).\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'age',\n  operator: 'greater',\n  value: 18,\n}\n```\n\n#### less\n\nLess than comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'quantity',\n  operator: 'less',\n  value: 100,\n}\n```\n\n#### greaterOrEqual\n\nGreater than or equal to.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'age',\n  operator: 'greaterOrEqual',\n  value: 21,\n}\n```\n\n#### lessOrEqual\n\nLess than or equal to.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'discount',\n  operator: 'lessOrEqual',\n  value: 100,\n}\n```\n\n### String Operators\n\n#### contains\n\nCheck if string/array contains value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'email',\n  operator: 'contains',\n  value: '@company.com',\n}\n```\n\n#### startsWith\n\nCheck if string starts with value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'url',\n  operator: 'startsWith',\n  value: 'https://',\n}\n```\n\n#### endsWith\n\nCheck if string ends with value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'email',\n  operator: 'endsWith',\n  value: '.gov',\n}\n```\n\n#### matches\n\nRegular expression match.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'zipCode',\n  operator: 'matches',\n  value: '^[0-9]{5}$',\n}\n```\n\n## Combining Conditions\n\n### AND Logic\n\nAll conditions must be true.\n\n```typescript\n{\n  type: 'and',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'hasTeam',\n      operator: 'equals',\n      value: true,\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'teamSize',\n      operator: 'greater',\n      value: 5,\n    },\n  ],\n}\n```\n\n**Use case:** Field required when all conditions are met.\n\n```typescript\n{\n  key: 'enterpriseFeatures',\n  type: 'checkbox',\n  label: 'Enable Enterprise Features',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'and',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'business',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'plan',\n          operator: 'equals',\n          value: 'enterprise',\n        },\n      ],\n    },\n  }],\n}\n```\n\n### OR Logic\n\nAt least one condition must be true.\n\n```typescript\n{\n  type: 'or',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'role',\n      operator: 'equals',\n      value: 'admin',\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'role',\n      operator: 'equals',\n      value: 'owner',\n    },\n  ],\n}\n```\n\n**Use case:** Show field for multiple roles.\n\n```typescript\n{\n  key: 'adminPanel',\n  type: 'group',\n  label: 'Administration',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'role',\n          operator: 'notEquals',\n          value: 'admin',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'role',\n          operator: 'notEquals',\n          value: 'owner',\n        },\n      ],\n    },\n  }],\n}\n```\n\n### Nested Logic\n\nCombine AND/OR logic for complex conditions.\n\n```typescript\n{\n  type: 'and',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'country',\n      operator: 'equals',\n      value: 'US',\n    },\n    {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'age',\n          operator: 'greaterOrEqual',\n          value: 21,\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'hasParentalConsent',\n          operator: 'equals',\n          value: true,\n        },\n      ],\n    },\n  ],\n}\n```\n\nThis means: \"Country must be US AND (age >= 21 OR has parental consent)\"\n\n## Practical Examples\n\n### Show Field Based on Multiple Conditions\n\n```typescript\n{\n  key: 'internationalShipping',\n  type: 'checkbox',\n  label: 'Enable International Shipping',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'free',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'verified',\n          operator: 'equals',\n          value: false,\n        },\n      ],\n    },\n  }],\n}\n```\n\nHidden for free accounts OR unverified accounts.\n\n### Required Field with Complex Logic\n\n```typescript\n{\n  key: 'taxExemptionNumber',\n  type: 'input',\n  value: '',\n  label: 'Tax Exemption Number',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'and',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'business',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'claimsTaxExemption',\n          operator: 'equals',\n          value: true,\n        },\n        {\n          type: 'or',\n          conditions: [\n            {\n              type: 'fieldValue',\n              fieldPath: 'country',\n              operator: 'equals',\n              value: 'US',\n            },\n            {\n              type: 'fieldValue',\n              fieldPath: 'country',\n              operator: 'equals',\n              value: 'CA',\n            },\n          ],\n        },\n      ],\n    },\n  }],\n}\n```\n\n### Dynamic Read-Only Based on Status\n\n```typescript\n{\n  key: 'orderItems',\n  type: 'group',\n  label: 'Order Items',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'shipped',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'delivered',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'cancelled',\n        },\n      ],\n    },\n  }],\n}\n```\n\nOrder items become read-only once order is shipped, delivered, or cancelled.\n\n## Best Practices\n\n**Keep conditions readable:**\n\n```typescript\n// \u2705 Good - Easy to understand\n{\n  type: 'fieldValue',\n  fieldPath: 'accountType',\n  operator: 'equals',\n  value: 'business',\n}\n\n// \u274C Avoid - Hard to maintain\n{\n  type: 'formValue',\n  expression: 'formValue.accountType === \"business\" && formValue.country !== null && formValue.hasTeam',\n}\n```\n\n## ConditionalExpression Interface\n\n```typescript\ninterface ConditionalExpression {\n  /** Expression type - includes 'and' and 'or' for combining conditions */\n  type: 'fieldValue' | 'formValue' | 'javascript' | 'custom' | 'and' | 'or';\n\n  /** Field path for fieldValue type */\n  fieldPath?: string;\n\n  /**\n   * Comparison operator\n   * - For 'fieldValue': compares field at fieldPath against value\n   * - For 'formValue': compares entire form object against value\n   */\n  operator?:\n    | 'equals'\n    | 'notEquals'\n    | 'greater'\n    | 'less'\n    | 'greaterOrEqual'\n    | 'lessOrEqual'\n    | 'contains'\n    | 'startsWith'\n    | 'endsWith'\n    | 'matches';\n\n  /** Value to compare against (for fieldValue/formValue with operator) */\n  value?: unknown;\n\n  /**\n   * JavaScript expression string\n   * - For 'javascript': Has access to fieldValue and formValue\n   * - For 'custom': Name of registered custom function\n   */\n  expression?: string;\n\n  /** Array of sub-conditions for 'and' and 'or' types */\n  conditions?: ConditionalExpression[];\n}\n```\n\n**Expression types summary:**\n\n| Type         | Uses                             | Purpose                                        |\n| ------------ | -------------------------------- | ---------------------------------------------- |\n| `fieldValue` | `fieldPath`, `operator`, `value` | Compare a specific field's value               |\n| `formValue`  | `operator`, `value`              | Compare entire form object                     |\n| `javascript` | `expression`                     | Custom JS with `fieldValue`/`formValue` access |\n| `custom`     | `expression`                     | Call registered custom function                |\n| `and`/`or`   | `conditions`                     | Combine multiple conditions                    |\n\n## Common Patterns\n\n### Show/Hide Field Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      /* when to hide */\n    },\n  },\n];\n```\n\n### Conditional Required Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      /* when to hide */\n    },\n  },\n  {\n    type: 'required',\n    condition: {\n      /* when to require */\n    },\n  },\n];\n```\n\n### Multiple Conditions Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      type: 'and', // or 'or'\n      conditions: [\n        {\n          /* condition 1 */\n        },\n        {\n          /* condition 2 */\n        },\n      ],\n    },\n  },\n];\n```\n\n## External Data in Conditions\n\nAccess external application state (user roles, permissions, feature flags) in conditions using `externalData`:\n\n```typescript\nconst config = {\n  externalData: {\n    userRole: computed(() => authService.role()),\n    featureFlags: computed(() => ({\n      advancedMode: featureService.isAdvanced(),\n    })),\n  },\n  fields: [\n    {\n      key: 'adminNotes',\n      type: 'textarea',\n      label: 'Admin Notes',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: \"externalData.userRole !== 'admin'\",\n          },\n        },\n      ],\n    },\n    {\n      key: 'advancedSettings',\n      type: 'input',\n      label: 'Advanced Settings',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: 'externalData.featureFlags.advancedMode !== true',\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n**Key points:**\n\n- Each property in `externalData` must be a Signal (`signal()` or `computed()`)\n- Changes to external signals automatically re-evaluate conditions\n- Access values via `externalData.propertyName` in JavaScript expressions\n\n## Related\n\n- **[Value Derivation](../value-derivation/basics/)** - Computed field values\n- **[Validation](../../validation/basics/)** - Conditional validation\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration\n- **[Examples](/docs/examples)** - Real-world form patterns"
+        content: "Control field behavior dynamically based on form state. Dynamic forms provides a declarative API for conditional visibility, required state, and readonly state that maps directly to Angular's signal forms.\n\n## Signal Forms Integration\n\nThe library integrates with Angular's signal forms logic functions:\n\n```typescript\nimport { hidden, readonly, required } from '@angular/forms/signals';\n```\n\nAll conditional logic configuration is applied using these functions, providing:\n\n- **Reactive updates** when form state changes\n- **Type-safe** conditional expressions\n- **Automatic re-evaluation** on dependencies\n- **Integration** with form validation state\n\n## Static Properties\n\nUse simple boolean properties for fields with fixed states.\n\n### hidden\n\nHide a field from view (field still participates in form state):\n\n```typescript\n{\n  key: 'internalId',\n  type: 'input',\n  value: '',\n  label: 'Internal ID',\n  hidden: true,\n}\n```\n\nThe field is hidden from the UI but still included in the form value.\n\n### disabled\n\nDisable user interaction:\n\n```typescript\n{\n  key: 'systemField',\n  type: 'input',\n  value: 'auto-generated',\n  label: 'System Field',\n  disabled: true,\n}\n```\n\n**Note:** The `disabled` property is handled at the component level and does not use signal forms logic functions. It's a static UI property that prevents user interaction.\n\n### readonly\n\nMake a field read-only (displays value but prevents modification):\n\n```typescript\n{\n  key: 'createdAt',\n  type: 'input',\n  value: '2024-01-15',\n  label: 'Created Date',\n  readonly: true,\n}\n```\n\n## Dynamic Conditional Logic\n\nFor conditional behavior based on form state, use the `logic` array with `LogicConfig` objects.\n\n```typescript\ninterface LogicConfig {\n  /** Logic type */\n  type: 'hidden' | 'readonly' | 'disabled' | 'required';\n\n  /** Boolean expression, static value, or form state condition */\n  condition: ConditionalExpression | boolean | FormStateCondition;\n}\n```\n\n`FormStateCondition` values (`'formInvalid'`, `'formSubmitting'`, `'pageInvalid'`) are primarily used for button disabled logic.\n\n### Conditional Visibility (hidden)\n\nShow or hide fields based on other field values.\n\n#### Show Email When Contact Method is Email\n\n```typescript\n{\n  key: 'contactMethod',\n  type: 'select',\n  value: '',\n  options: [\n    { value: 'email', label: 'Email' },\n    { value: 'phone', label: 'Phone' },\n  ],\n}\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  label: 'Email Address',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'contactMethod',\n      operator: 'notEquals',\n      value: 'email',\n    },\n  }],\n}\n```\n\nWhen `contactMethod !== 'email'`, the email field is hidden.\n\n### Conditional Required\n\nMake fields required based on conditions.\n\n#### Tax ID Required for Business Accounts\n\n```typescript\n{\n  key: 'accountType',\n  type: 'radio',\n  value: 'personal',\n  options: [\n    { value: 'personal', label: 'Personal' },\n    { value: 'business', label: 'Business' },\n  ],\n}\n{\n  key: 'taxId',\n  type: 'input',\n  value: '',\n  label: 'Tax ID',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n### Conditional Readonly\n\nMake fields read-only based on conditions.\n\n#### Lock Field After Submission\n\n```typescript\n{\n  key: 'status',\n  type: 'select',\n  value: 'draft',\n  options: [\n    { value: 'draft', label: 'Draft' },\n    { value: 'submitted', label: 'Submitted' },\n  ],\n}\n{\n  key: 'documentNumber',\n  type: 'input',\n  value: '',\n  label: 'Document Number',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'status',\n      operator: 'equals',\n      value: 'submitted',\n    },\n  }],\n}\n```\n\nOnce status is \"submitted\", the document number becomes read-only.\n\n## Basic Conditional Expression\n\nThe most common conditional expression checks a specific field's value:\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'fieldKey',\n  operator: 'equals',\n  value: 'expectedValue',\n}\n```\n\n**Components:**\n\n- `type: 'fieldValue'` - Check a specific field\n- `fieldPath` - The field key to check\n- `operator` - Comparison operator (see [All Operators](#all-operators))\n- `value` - Value to compare against\n\n## Quick Example\n\nShow a field only when another field has a specific value:\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  label: 'Email Address',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'contactMethod',\n        operator: 'notEquals',\n        value: 'email',\n      },\n    },\n    {\n      type: 'required',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'contactMethod',\n        operator: 'equals',\n        value: 'email',\n      },\n    },\n  ],\n}\n```\n\nThis field is hidden unless `contactMethod === 'email'`, and required when visible. See the [Examples](/examples) page for complete form implementations.\n\n## When Logic Runs\n\nConditional logic is evaluated:\n\n- **On form value change** - Any time a dependent field changes\n- **On initialization** - When the form is created\n- **Reactively** - Uses Angular's signal forms for automatic updates\n\n### Evaluation Flow\n\n```\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                    LOGIC EVALUATION FLOW                    \u2502\n\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502                                                             \u2502\n\u2502  Form Value Changes                                         \u2502\n\u2502         \u2502                                                   \u2502\n\u2502         \u25BC                                                   \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 Signal Updates  \u2502\u25C4\u2500\u2500\u2500\u2500 Angular's reactive system        \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                                       \u2502\n\u2502           \u2502                                                 \u2502\n\u2502           \u25BC                                                 \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 Evaluate logic  \u2502                                       \u2502\n\u2502  \u2502    conditions   \u2502                                       \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518                                       \u2502\n\u2502           \u2502                                                 \u2502\n\u2502     \u250C\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2510                                          \u2502\n\u2502     \u25BC           \u25BC                                          \u2502\n\u2502  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510                                       \u2502\n\u2502  \u2502 true \u2502   \u2502false \u2502                                       \u2502\n\u2502  \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u252C\u2500\u2500\u2500\u2518                                       \u2502\n\u2502     \u2502          \u2502                                            \u2502\n\u2502     \u25BC          \u25BC                                            \u2502\n\u2502  Apply      Remove                                          \u2502\n\u2502  effect     effect                                          \u2502\n\u2502  (hide,     (show,                                          \u2502\n\u2502  require,   optional,                                       \u2502\n\u2502  readonly)  editable)                                       \u2502\n\u2502                                                             \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Expression Types\n\n### fieldValue\n\nCheck a specific field's value - the most common expression type.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'accountType',\n  operator: 'equals',\n  value: 'business',\n}\n```\n\n**Use when:** Checking a single field's value\n\n**Example:**\n\n```typescript\n{\n  key: 'companyName',\n  type: 'input',\n  value: '',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n### formValue\n\nCompare the entire form value object against a specific value using operators.\n\n```typescript\n{\n  type: 'formValue',\n  operator: 'equals',\n  value: { status: 'active', role: 'admin' },\n}\n```\n\n**Use when:** Checking if the entire form matches a specific state\n\n**Note:** This type is rarely useful in practice \u2014 deep equality on an entire form object is an unusual requirement. For conditions that involve multiple specific fields, use `javascript` or `custom` expressions instead (e.g. `formValue.status === 'active' && formValue.role === 'admin'`).\n\n### javascript\n\nJavaScript expressions with access to `fieldValue` (current field) and `formValue` (entire form).\n\n```typescript\n{\n  type: 'javascript',\n  expression: 'new Date(fieldValue) > new Date()',\n}\n```\n\n**Use when:** Custom logic on field value or complex multi-field conditions\n\n**Examples:**\n\n```typescript\n// Check current field value\n{\n  key: 'eventDate',\n  type: 'datepicker',\n  value: null,\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'javascript',\n      expression: 'new Date(fieldValue) < new Date()',\n    },\n  }],\n}\n\n// Check multiple form fields (replaces old formValue expression pattern)\n{\n  key: 'stateProvince',\n  type: 'select',\n  value: '',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'javascript',\n      expression: 'formValue.country !== \"US\" && formValue.country !== \"CA\"',\n    },\n  }],\n}\n```\n\n**Safe member access:** Accessing nested properties on `null` or `undefined` returns `undefined` (no errors thrown):\n\n```typescript\n{\n  type: 'javascript',\n  // Safe even when user, profile, or preferences is null/undefined\n  expression: 'formValue.user.profile.preferences.notifications === true',\n}\n```\n\n### custom\n\nAdvanced custom expressions with access to both field and form values.\n\n```typescript\n{\n  type: 'custom',\n  expression: 'fieldValue > formValue.minAge && fieldValue < formValue.maxAge',\n}\n```\n\n**Safe member access:** Like `formValue` expressions, nested property access is safe:\n\n```typescript\n{\n  type: 'custom',\n  // Safe even when nested values are null/undefined\n  expression: 'fieldValue !== formValue.user.profile.firstName',\n}\n```\n\n### Field State in Expressions\n\n`javascript` and `custom` expressions have access to two additional variables for querying field interaction state:\n\n- **`fieldState`** \u2014 the current field's own state\n- **`formFieldState`** \u2014 state of any field in the form, by key\n\n#### fieldState\n\nUse `fieldState` to react to the current field's own interaction state:\n\n```typescript\n// Lock the field as soon as the user edits it\n{\n  key: 'accountNumber',\n  type: 'input',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'javascript',\n      expression: 'fieldState.dirty',\n    },\n  }],\n}\n```\n\n**Available properties:**\n\n| Property   | Type      | Description                         |\n| ---------- | --------- | ----------------------------------- |\n| `touched`  | `boolean` | User has focused and left the field |\n| `dirty`    | `boolean` | User has changed the field value    |\n| `pristine` | `boolean` | Equivalent to `!dirty`              |\n| `valid`    | `boolean` | Field has no validation errors      |\n| `invalid`  | `boolean` | Field has validation errors         |\n| `pending`  | `boolean` | Async validation is in progress     |\n| `hidden`   | `boolean` | Field is currently hidden           |\n| `readonly` | `boolean` | Field is currently readonly         |\n| `disabled` | `boolean` | Field is currently disabled         |\n\n#### formFieldState\n\nUse `formFieldState` to react to another field's state. Access by field key:\n\n```typescript\n// Make a field readonly once a related field has been touched\n{\n  key: 'billingAddress',\n  type: 'input',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'javascript',\n      expression: 'formFieldState.shippingAddress.dirty',\n    },\n  }],\n}\n```\n\n`formFieldState` has the same properties as `fieldState`, keyed by field name.\n\n**Example \u2014 show a confirmation field only after the primary field is dirty:**\n\n```typescript\n{\n  key: 'confirmEmail',\n  type: 'input',\n  label: 'Confirm Email',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'javascript',\n      expression: '!formFieldState.email.dirty',\n    },\n  }],\n}\n```\n\n### http\n\nEvaluate a condition by sending an HTTP request and inspecting the response. The request fires automatically when declared query params change, with built-in debouncing.\n\n```typescript\n{\n  type: 'http',\n  http: {\n    url: '/api/permissions',\n    queryParams: {\n      role: 'formValue.userRole',\n    },\n  },\n  responseExpression: 'response.canEdit',\n  pendingValue: false,\n}\n```\n\n**Use when:** Field visibility or state must be determined server-side (permissions, feature flags, country-specific rules).\n\n**Full example \u2014 hide an admin panel based on server permissions:**\n\n```typescript\n{\n  key: 'adminPanel',\n  type: 'input',\n  label: 'Admin Panel Access Code',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'http',\n      http: {\n        url: '/api/permissions',\n        queryParams: {\n          role: 'formValue.userRole',\n        },\n      },\n      responseExpression: 'response.hideAdminPanel',\n      pendingValue: true, // Hide while checking\n    },\n  }],\n}\n```\n\n**HTTP condition properties:**\n\n| Property             | Type                | Required | Default      | Description                                                              |\n| -------------------- | ------------------- | -------- | ------------ | ------------------------------------------------------------------------ |\n| `type`               | `'http'`            | Yes      | \u2014            | Identifies this as an HTTP condition                                     |\n| `http`               | `HttpRequestConfig` | Yes      | \u2014            | Request configuration (see below)                                        |\n| `responseExpression` | `string`            | No       | `!!response` | Expression evaluated with `{ response }` in scope. Must return a boolean |\n| `pendingValue`       | `boolean`           | No       | `false`      | Value returned while the request is in-flight                            |\n| `cacheDurationMs`    | `number`            | No       | `30000`      | How long to cache responses (ms)                                         |\n| `debounceMs`         | `number`            | No       | `300`        | Debounce delay before re-sending (ms)                                    |\n\n**`HttpRequestConfig` quick reference:**\n\n| Property                  | Description                                                                         |\n| ------------------------- | ----------------------------------------------------------------------------------- |\n| `url`                     | Request URL. Use `:key` placeholders for path parameters                            |\n| `method`                  | HTTP method. Defaults to `'GET'`                                                    |\n| `params`                  | Path parameters. `:key` placeholders in the URL replaced with evaluated expressions |\n| `queryParams`             | Key/value map. Values are expressions evaluated against form context                |\n| `body`                    | Request body for POST/PUT/PATCH                                                     |\n| `evaluateBodyExpressions` | When `true`, top-level `body` string values are evaluated as expressions            |\n| `headers`                 | Request headers                                                                     |\n\n**HTTP condition on `required` \u2014 server-driven required fields:**\n\n```typescript\n{\n  key: 'taxId',\n  type: 'input',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'http',\n      http: {\n        url: '/api/tax-rules',\n        queryParams: { country: 'formValue.country' },\n      },\n      responseExpression: 'response.taxIdRequired',\n      pendingValue: false, // Optional while checking\n    },\n  }],\n}\n```\n\n### async\n\nEvaluate a condition using a custom async function registered in `customFnConfig.asyncConditions`. Functions receive the full form context and must return a `Promise<boolean>` or `Observable<boolean>`.\n\n```typescript\n{\n  type: 'async',\n  asyncFunctionName: 'checkPermission',\n  pendingValue: false,\n}\n```\n\n**Use when:** Condition logic involves Angular service injection, complex async operations, or anything that `http` conditions cannot express directly.\n\n> **Why `inject()` works here:** `customFnConfig` functions are called within an Angular injection context, so Angular's `inject()` API is available \u2014 the same way it works in a constructor or field initializer. Import `inject` from `@angular/core` as usual.\n\n**Registration and usage:**\n\n```typescript\nimport { inject } from '@angular/core';\n\nconst formConfig = {\n  customFnConfig: {\n    asyncConditions: {\n      checkReadonly: (context) => {\n        return inject(PermissionsService).canEdit(context.formValue.resourceId as string);\n      },\n    },\n  },\n\n  fields: [\n    {\n      key: 'salary',\n      type: 'input',\n      label: 'Salary',\n      logic: [\n        {\n          type: 'readonly',\n          condition: {\n            type: 'async',\n            asyncFunctionName: 'checkReadonly',\n            pendingValue: false, // Editable while checking\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n**Async condition properties:**\n\n| Property            | Type      | Required | Default | Description                                         |\n| ------------------- | --------- | -------- | ------- | --------------------------------------------------- |\n| `type`              | `'async'` | Yes      | \u2014       | Identifies this as an async condition               |\n| `asyncFunctionName` | `string`  | Yes      | \u2014       | Name registered in `customFnConfig.asyncConditions` |\n| `pendingValue`      | `boolean` | No       | `false` | Value returned while the function is resolving      |\n| `debounceMs`        | `number`  | No       | `300`   | Debounce delay before re-evaluating (ms)            |\n\n**Choosing `pendingValue`:**\n\nThe right `pendingValue` depends on the logic type and desired UX:\n\n| Logic type | `pendingValue: false`   | `pendingValue: true`    |\n| ---------- | ----------------------- | ----------------------- |\n| `hidden`   | Visible while checking  | Hidden while checking   |\n| `required` | Optional while checking | Required while checking |\n| `readonly` | Editable while checking | Readonly while checking |\n| `disabled` | Enabled while checking  | Disabled while checking |\n\n## All Operators\n\n### Equality Operators\n\n#### equals\n\nExact match comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'status',\n  operator: 'equals',\n  value: 'active',\n}\n```\n\n#### notEquals\n\nNot equal to comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'status',\n  operator: 'notEquals',\n  value: 'archived',\n}\n```\n\n### Comparison Operators\n\n#### greater\n\nGreater than comparison (numbers/dates).\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'age',\n  operator: 'greater',\n  value: 18,\n}\n```\n\n#### less\n\nLess than comparison.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'quantity',\n  operator: 'less',\n  value: 100,\n}\n```\n\n#### greaterOrEqual\n\nGreater than or equal to.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'age',\n  operator: 'greaterOrEqual',\n  value: 21,\n}\n```\n\n#### lessOrEqual\n\nLess than or equal to.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'discount',\n  operator: 'lessOrEqual',\n  value: 100,\n}\n```\n\n### String Operators\n\n#### contains\n\nCheck if string/array contains value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'email',\n  operator: 'contains',\n  value: '@company.com',\n}\n```\n\n#### startsWith\n\nCheck if string starts with value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'url',\n  operator: 'startsWith',\n  value: 'https://',\n}\n```\n\n#### endsWith\n\nCheck if string ends with value.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'email',\n  operator: 'endsWith',\n  value: '.gov',\n}\n```\n\n#### matches\n\nRegular expression match.\n\n```typescript\n{\n  type: 'fieldValue',\n  fieldPath: 'zipCode',\n  operator: 'matches',\n  value: '^[0-9]{5}$',\n}\n```\n\n## Combining Conditions\n\n### AND Logic\n\nAll conditions must be true.\n\n```typescript\n{\n  type: 'and',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'hasTeam',\n      operator: 'equals',\n      value: true,\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'teamSize',\n      operator: 'greater',\n      value: 5,\n    },\n  ],\n}\n```\n\n**Use case:** Field required when all conditions are met.\n\n```typescript\n{\n  key: 'enterpriseFeatures',\n  type: 'checkbox',\n  label: 'Enable Enterprise Features',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'and',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'business',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'plan',\n          operator: 'equals',\n          value: 'enterprise',\n        },\n      ],\n    },\n  }],\n}\n```\n\n### OR Logic\n\nAt least one condition must be true.\n\n```typescript\n{\n  type: 'or',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'role',\n      operator: 'equals',\n      value: 'admin',\n    },\n    {\n      type: 'fieldValue',\n      fieldPath: 'role',\n      operator: 'equals',\n      value: 'owner',\n    },\n  ],\n}\n```\n\n**Use case:** Show field for multiple roles \u2014 hide unless role is `admin` or `owner`.\n\n```typescript\n// Hide the panel when role is neither 'admin' nor 'owner'\n// (i.e. hidden when notEquals 'admin' AND notEquals 'owner')\n{\n  key: 'adminPanel',\n  type: 'group',\n  label: 'Administration',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'and',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'role',\n          operator: 'notEquals',\n          value: 'admin',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'role',\n          operator: 'notEquals',\n          value: 'owner',\n        },\n      ],\n    },\n  }],\n}\n```\n\n### Nested Logic\n\nCombine AND/OR logic for complex conditions.\n\n```typescript\n{\n  type: 'and',\n  conditions: [\n    {\n      type: 'fieldValue',\n      fieldPath: 'country',\n      operator: 'equals',\n      value: 'US',\n    },\n    {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'age',\n          operator: 'greaterOrEqual',\n          value: 21,\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'hasParentalConsent',\n          operator: 'equals',\n          value: true,\n        },\n      ],\n    },\n  ],\n}\n```\n\nThis means: \"Country must be US AND (age >= 21 OR has parental consent)\"\n\n## Practical Examples\n\n### Show Field Based on Multiple Conditions\n\n```typescript\n{\n  key: 'internationalShipping',\n  type: 'checkbox',\n  label: 'Enable International Shipping',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'free',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'verified',\n          operator: 'equals',\n          value: false,\n        },\n      ],\n    },\n  }],\n}\n```\n\nHidden for free accounts OR unverified accounts.\n\n### Required Field with Complex Logic\n\n```typescript\n{\n  key: 'taxExemptionNumber',\n  type: 'input',\n  value: '',\n  label: 'Tax Exemption Number',\n  logic: [{\n    type: 'required',\n    condition: {\n      type: 'and',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'accountType',\n          operator: 'equals',\n          value: 'business',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'claimsTaxExemption',\n          operator: 'equals',\n          value: true,\n        },\n        {\n          type: 'or',\n          conditions: [\n            {\n              type: 'fieldValue',\n              fieldPath: 'country',\n              operator: 'equals',\n              value: 'US',\n            },\n            {\n              type: 'fieldValue',\n              fieldPath: 'country',\n              operator: 'equals',\n              value: 'CA',\n            },\n          ],\n        },\n      ],\n    },\n  }],\n}\n```\n\n### Dynamic Read-Only Based on Status\n\n```typescript\n{\n  key: 'orderItems',\n  type: 'group',\n  label: 'Order Items',\n  logic: [{\n    type: 'readonly',\n    condition: {\n      type: 'or',\n      conditions: [\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'shipped',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'delivered',\n        },\n        {\n          type: 'fieldValue',\n          fieldPath: 'orderStatus',\n          operator: 'equals',\n          value: 'cancelled',\n        },\n      ],\n    },\n  }],\n}\n```\n\nOrder items become read-only once order is shipped, delivered, or cancelled.\n\n## Best Practices\n\n**Keep conditions readable:**\n\n```typescript\n// \u2705 Good - Easy to understand\n{\n  type: 'fieldValue',\n  fieldPath: 'accountType',\n  operator: 'equals',\n  value: 'business',\n}\n\n// \u274C Avoid - Hard to maintain\n{\n  type: 'formValue',\n  expression: 'formValue.accountType === \"business\" && formValue.country !== null && formValue.hasTeam',\n}\n```\n\n## ConditionalExpression Interface\n\n`ConditionalExpression` is a discriminated union of all expression types:\n\n```typescript\n// Sync expressions\ntype ConditionalExpression =\n  | { type: 'fieldValue'; fieldPath: string; operator: Operator; value: unknown }\n  | { type: 'formValue'; operator: Operator; value: unknown }\n  | { type: 'javascript'; expression: string }\n  | { type: 'custom'; expression: string }\n  | { type: 'and'; conditions: ConditionalExpression[] }\n  | { type: 'or'; conditions: ConditionalExpression[] }\n  // Async expressions\n  | HttpCondition\n  | AsyncCondition;\n\ntype Operator =\n  | 'equals'\n  | 'notEquals'\n  | 'greater'\n  | 'less'\n  | 'greaterOrEqual'\n  | 'lessOrEqual'\n  | 'contains'\n  | 'startsWith'\n  | 'endsWith'\n  | 'matches';\n\ninterface HttpCondition {\n  type: 'http';\n  http: HttpRequestConfig;\n  responseExpression?: string; // Evaluated with { response }. Defaults to !!response\n  pendingValue?: boolean; // Default: false\n  cacheDurationMs?: number; // Default: 30000\n  debounceMs?: number; // Default: 300\n}\n\ninterface AsyncCondition {\n  type: 'async';\n  asyncFunctionName: string;\n  pendingValue?: boolean; // Default: false\n  debounceMs?: number; // Default: 300\n}\n```\n\n**Expression types summary:**\n\n| Type         | Sync/Async | Key properties                   | Purpose                                                               |\n| ------------ | ---------- | -------------------------------- | --------------------------------------------------------------------- |\n| `fieldValue` | Sync       | `fieldPath`, `operator`, `value` | Compare a specific field's value                                      |\n| `formValue`  | Sync       | `operator`, `value`              | Compare entire form object                                            |\n| `javascript` | Sync       | `expression`                     | Custom JS with `fieldValue`/`formValue`/`fieldState`/`formFieldState` |\n| `custom`     | Sync       | `expression`                     | Inline expression with `fieldValue`/`formValue` (safe member access)  |\n| `and`/`or`   | Sync       | `conditions`                     | Combine multiple conditions                                           |\n| `http`       | Async      | `http`, `responseExpression`     | Server-driven condition via HTTP request                              |\n| `async`      | Async      | `asyncFunctionName`              | Custom async function registered in config                            |\n\n## Common Patterns\n\n### Show/Hide Field Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      /* when to hide */\n    },\n  },\n];\n```\n\n### Conditional Required Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      /* when to hide */\n    },\n  },\n  {\n    type: 'required',\n    condition: {\n      /* when to require */\n    },\n  },\n];\n```\n\n### Multiple Conditions Pattern\n\n```typescript\nlogic: [\n  {\n    type: 'hidden',\n    condition: {\n      type: 'and', // or 'or'\n      conditions: [\n        {\n          /* condition 1 */\n        },\n        {\n          /* condition 2 */\n        },\n      ],\n    },\n  },\n];\n```\n\n## External Data in Conditions\n\nAccess external application state (user roles, permissions, feature flags) in conditions using `externalData`:\n\n```typescript\nconst config = {\n  externalData: {\n    userRole: computed(() => authService.role()),\n    featureFlags: computed(() => ({\n      advancedMode: featureService.isAdvanced(),\n    })),\n  },\n  fields: [\n    {\n      key: 'adminNotes',\n      type: 'textarea',\n      label: 'Admin Notes',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: \"externalData.userRole !== 'admin'\",\n          },\n        },\n      ],\n    },\n    {\n      key: 'advancedSettings',\n      type: 'input',\n      label: 'Advanced Settings',\n      logic: [\n        {\n          type: 'hidden',\n          condition: {\n            type: 'javascript',\n            expression: 'externalData.featureFlags.advancedMode !== true',\n          },\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n**Key points:**\n\n- Each property in `externalData` must be a Signal (`signal()` or `computed()`)\n- Changes to external signals automatically re-evaluate conditions\n- Access values via `externalData.propertyName` in JavaScript expressions\n\n## Related\n\n- **[Value Derivation](../value-derivation/basics/)** \u2014 Computed field values\n- **[Async Derivation](../value-derivation/async/)** \u2014 HTTP and async function derivations, stopOnUserOverride\n- **[Validation](../../validation/basics/)** \u2014 Conditional validation\n- **[Custom Validators](../../validation/custom-validators/)** \u2014 Async and HTTP validators\n- **[Type Safety](../../advanced/type-safety/basics/)** \u2014 TypeScript integration\n- **[Examples](/examples)** \u2014 Real-world form patterns"
       },
       {
         id: "dynamic-behavior-i18n",
@@ -54,19 +60,25 @@ var require_docs = __commonJS({
         id: "dynamic-behavior-submission",
         title: "Dynamic Behavior Submission",
         category: "dynamic-behavior",
-        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```"
+        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```"
+      },
+      {
+        id: "dynamic-behavior-value-derivation-basics-async-derivation",
+        title: "Dynamic Behavior Value Derivation Basics Async Derivation",
+        category: "dynamic-behavior",
+        content: "Derive field values from HTTP responses or custom async functions. Async derivations are ideal for server-driven computed values, address/zip lookups, exchange rates, and any value that requires a network call.\n\n## HTTP Derivations\n\nUse `source: 'http'` to derive a field value from an HTTP response. The request fires when declared dependencies change, with automatic debouncing and in-flight request cancellation.\n\n### Basic Example\n\n```typescript\n{\n  key: 'exchangeRate',\n  type: 'input',\n  label: 'Exchange Rate',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    source: 'http',\n    http: {\n      url: '/api/exchange-rate',\n      method: 'GET',\n      queryParams: {\n        currency: 'formValue.currency',\n      },\n    },\n    responseExpression: 'response.rate',\n    dependsOn: ['currency'],\n  }],\n}\n```\n\nWhen `currency` changes, a GET request is sent and `response.rate` becomes the new field value.\n\n### HttpRequestConfig\n\n| Property                  | Type                      | Required | Description                                                                 |\n| ------------------------- | ------------------------- | -------- | --------------------------------------------------------------------------- |\n| `url`                     | `string`                  | Yes      | Request URL. Use `:key` placeholders for path parameters                    |\n| `method`                  | `string`                  | No       | HTTP method. Defaults to `'GET'`                                            |\n| `params`                  | `Record<string, string>`  | No       | Path parameters. Values are expressions evaluated against the form context  |\n| `queryParams`             | `Record<string, string>`  | No       | Query parameters. Values are expressions evaluated against the form context |\n| `body`                    | `Record<string, unknown>` | No       | Request body (for POST/PUT/PATCH)                                           |\n| `evaluateBodyExpressions` | `boolean`                 | No       | When `true`, top-level string values in `body` are treated as expressions   |\n| `headers`                 | `Record<string, string>`  | No       | Request headers                                                             |\n\n### Path Parameters\n\nUse `:key` placeholders in the URL and provide values via `params`. Values are expressions evaluated against the form context, then `encodeURIComponent`-encoded:\n\n```typescript\nhttp: {\n  url: '/api/users/:userId/orders/:orderId',\n  params: {\n    userId: 'formValue.userId',\n    orderId: 'formValue.orderId',\n  },\n}\n```\n\n### Query Params as Expressions\n\nValues in `queryParams` are evaluated as expressions, giving you dynamic request parameters built from form values:\n\n```typescript\nhttp: {\n  url: '/api/shipping-estimate',\n  queryParams: {\n    fromZip: 'formValue.originZip',\n    toZip: 'formValue.destinationZip',\n    weight: 'formValue.packageWeight',\n  },\n}\n```\n\n### POST with Dynamic Body\n\nFor `POST` requests, use `evaluateBodyExpressions: true` to build the body from form values:\n\n```typescript\nhttp: {\n  url: '/api/calculate-tax',\n  method: 'POST',\n  body: {\n    subtotal: 'formValue.subtotal',\n    state: 'formValue.state',\n    items: 'formValue.lineItems',\n  },\n  evaluateBodyExpressions: true,\n},\n```\n\nTop-level string values in `body` are evaluated as expressions. Nested objects are passed through as-is.\n\n### Extracting the Response Value\n\n`responseExpression` is evaluated with `{ response }` in scope and extracts the derived value:\n\n```typescript\nresponseExpression: 'response.rate'; // Simple property\nresponseExpression: 'response.data.price'; // Nested property\nresponseExpression: 'response.items[0].value'; // Array access\n```\n\n### Required Fields\n\n`source: 'http'` enforces two fields at the TypeScript level:\n\n- **`dependsOn: string[]`** \u2014 Explicit field dependencies. The request only re-fires when these fields change.\n- **`responseExpression: string`** \u2014 Expression to extract the derived value from the response body.\n\n### Controlling Request Timing\n\nUse `trigger` and `debounceMs` to control when requests fire:\n\n```typescript\n{\n  type: 'derivation',\n  source: 'http',\n  http: {\n    url: '/api/username-suggest',\n    queryParams: { q: 'formValue.companyName' },\n  },\n  responseExpression: 'response.suggestion',\n  dependsOn: ['companyName'],\n  trigger: 'debounced',\n  debounceMs: 400,\n}\n```\n\nThe request waits 400ms after the user stops typing before firing.\n\n### Conditional HTTP Derivation\n\nAdd a `condition` to only send the request when certain criteria are met:\n\n```typescript\n{\n  key: 'suggestedPrice',\n  type: 'input',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    source: 'http',\n    http: {\n      url: '/api/price-suggest',\n      queryParams: { productId: 'formValue.productId' },\n    },\n    responseExpression: 'response.suggestedPrice',\n    dependsOn: ['productId'],\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'productId',\n      operator: 'notEquals',\n      value: '',\n    },\n  }],\n}\n```\n\n## Async Function Derivations\n\nUse `source: 'asyncFunction'` when you need custom logic \u2014 Angular service injection, complex transformations, or any async computation not expressible as a plain HTTP config. Functions receive the full evaluation context and can return a `Promise` or `Observable`.\n\n### Basic Example\n\n```typescript\n// 1. Define and register the function in customFnConfig\nconst formConfig = {\n  customFnConfig: {\n    asyncDerivations: {\n      lookupCity: async (context) => {\n        const response = await fetch(`/api/geocode?zip=${context.formValue.zipCode}`);\n        const data = await response.json();\n        return data.city;\n      },\n    },\n  },\n\n  // 2. Reference it on the target field\n  fields: [\n    {\n      key: 'city',\n      type: 'input',\n      label: 'City',\n      readonly: true,\n      logic: [\n        {\n          type: 'derivation',\n          source: 'asyncFunction',\n          asyncFunctionName: 'lookupCity',\n          dependsOn: ['zipCode'],\n        },\n      ],\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n### Using RxJS Observables\n\nFunctions can return an `Observable` instead of a `Promise`, which is useful when using Angular services:\n\n```typescript\ncustomFnConfig: {\n  asyncDerivations: {\n    fetchAddress: (context) => {\n      return inject(AddressService)\n        .lookup(context.formValue.zipCode as string)\n        .pipe(map(result => result.formattedAddress));\n    },\n  },\n},\n```\n\n### Available Context\n\nAsync derivation functions receive the full `EvaluationContext`:\n\n| Variable                | Description                                      |\n| ----------------------- | ------------------------------------------------ |\n| `context.formValue`     | All current form field values                    |\n| `context.fieldValue`    | The current value of the target field            |\n| `context.externalData`  | External data passed to the form (if configured) |\n| `context.rootFormValue` | Entire form value when inside array fields       |\n\n### Conditional Async Derivation\n\nCombine with `condition` to only run the function when needed:\n\n```typescript\n{\n  key: 'city',\n  type: 'input',\n  label: 'City',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    source: 'asyncFunction',\n    asyncFunctionName: 'lookupCity',\n    dependsOn: ['zipCode'],\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'enableLookup',\n      operator: 'equals',\n      value: true,\n    },\n  }],\n}\n```\n\nThe async function is only called when `enableLookup === true`.\n\n### Required Fields\n\n`source: 'asyncFunction'` requires:\n\n- **`asyncFunctionName: string`** \u2014 Name of the function registered in `customFnConfig.asyncDerivations`.\n- **`dependsOn: string[]`** \u2014 Explicit field dependencies. Without this, the function would re-run on every form change.\n\n## Stop On User Override\n\n`stopOnUserOverride` turns a derivation into a \"smart default\" \u2014 the field is auto-filled initially, but derivation stops once the user manually edits it.\n\n### Basic Example\n\n```typescript\n{\n  key: 'displayName',\n  type: 'input',\n  label: 'Display Name',\n  logic: [{\n    type: 'derivation',\n    expression: 'formValue.firstName + \" \" + formValue.lastName',\n    stopOnUserOverride: true,\n  }],\n}\n```\n\nThe display name is auto-filled from first and last name. Once the user changes it directly, auto-fill stops.\n\n### Re-Engaging on Dependency Change\n\nUse `reEngageOnDependencyChange: true` to clear the user override when a dependency changes. The derivation respects user edits, but re-engages if the underlying data changes:\n\n```typescript\n{\n  key: 'phonePrefix',\n  type: 'input',\n  label: 'Phone Prefix',\n  logic: [\n    {\n      type: 'derivation',\n      value: '+1',\n      condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'US' },\n      stopOnUserOverride: true,\n      reEngageOnDependencyChange: true,\n      dependsOn: ['country'],\n    },\n    {\n      type: 'derivation',\n      value: '+44',\n      condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'UK' },\n      stopOnUserOverride: true,\n      reEngageOnDependencyChange: true,\n      dependsOn: ['country'],\n    },\n  ],\n}\n```\n\nWhen the user changes the country, the phone prefix is auto-filled again \u2014 overriding any previous manual edit.\n\n**Without** `reEngageOnDependencyChange`: once the user edits the field, the derivation never runs again for that field instance.\n\n**With** `reEngageOnDependencyChange`: the user override is cleared when a declared dependency changes, and the derivation re-fires.\n\n### Works with All Sources\n\n`stopOnUserOverride` and `reEngageOnDependencyChange` work across all derivation sources:\n\n```typescript\n// HTTP derivation with user override\n{\n  type: 'derivation',\n  source: 'http',\n  http: {\n    url: '/api/suggest-price',\n    queryParams: { category: 'formValue.category' },\n  },\n  responseExpression: 'response.suggestedPrice',\n  dependsOn: ['category'],\n  stopOnUserOverride: true,\n  reEngageOnDependencyChange: true,\n}\n\n// Async function derivation with user override\n{\n  type: 'derivation',\n  source: 'asyncFunction',\n  asyncFunctionName: 'fetchDefaultTitle',\n  dependsOn: ['template'],\n  stopOnUserOverride: true,\n}\n```\n\n## DerivationLogicConfig Reference (Async)\n\n### HTTP Derivation Fields\n\n```typescript\n{\n  type: 'derivation';\n  source: 'http';         // Required \u2014 identifies HTTP mode\n\n  http: HttpRequestConfig; // Required \u2014 request configuration\n  dependsOn: string[];     // Required \u2014 explicit field dependencies\n  responseExpression: string; // Required \u2014 expression to extract value from response\n\n  // Shared optional fields\n  trigger?: 'onChange' | 'debounced'; // Default: 'onChange'\n  debounceMs?: number;                // Default: 500 (when trigger: 'debounced')\n  condition?: ConditionalExpression | boolean;\n  stopOnUserOverride?: boolean;\n  reEngageOnDependencyChange?: boolean;\n  debugName?: string;\n}\n```\n\n### Async Function Derivation Fields\n\n```typescript\n{\n  type: 'derivation';\n  source: 'asyncFunction'; // Required \u2014 identifies async function mode\n\n  asyncFunctionName: string; // Required \u2014 name in customFnConfig.asyncDerivations\n  dependsOn: string[];       // Required \u2014 explicit field dependencies\n\n  // Shared optional fields\n  trigger?: 'onChange' | 'debounced';\n  debounceMs?: number;\n  condition?: ConditionalExpression | boolean;\n  stopOnUserOverride?: boolean;\n  reEngageOnDependencyChange?: boolean;\n  debugName?: string;\n}\n```\n\n## Related\n\n- **[Values](./)** \u2014 Expression, static value, and function-based derivations\n- **[Properties](./property-derivation)** \u2014 Derive component properties from form values\n- **[HTTP Conditions](../../conditional-logic/overview/)** \u2014 HTTP-driven field visibility and state\n- **[Custom Validators](../../../validation/custom-validators/)** \u2014 Async and HTTP validation"
       },
       {
         id: "dynamic-behavior-value-derivation-basics",
         title: "Dynamic Behavior Value Derivation Basics",
         category: "dynamic-behavior",
-        content: "Automatically compute and set field values based on other form values. Derivations enable calculated fields, auto-fill patterns, and value transformations.\n\n## Quick Start\n\nDerivations are defined ON the field that receives the computed value (self-targeting).\n\n### Shorthand Syntax (Preferred)\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  derivation: 'formValue.quantity * formValue.unitPrice',\n}\n```\n\n### Logic Block Syntax\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    expression: 'formValue.quantity * formValue.unitPrice',\n  }],\n}\n```\n\nWhen `quantity` or `unitPrice` changes, `total` is automatically recalculated.\n\n## Derivation Types\n\n### Expression-Based\n\nUse JavaScript expressions with access to `formValue`:\n\n```typescript\n{\n  key: 'fullName',\n  type: 'input',\n  label: 'Full Name',\n  readonly: true,\n  derivation: '(formValue.firstName || \"\") + \" \" + (formValue.lastName || \"\")',\n}\n```\n\n**Available variables:**\n\n- `formValue` - Object containing all form field values\n- `externalData` - External application state (when configured in FormConfig)\n\n### Static Value\n\nSet a constant value when a condition is met:\n\n```typescript\n{\n  key: 'phonePrefix',\n  type: 'input',\n  label: 'Phone Prefix',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    value: '+1',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'country',\n      operator: 'equals',\n      value: 'USA',\n    },\n  }],\n}\n```\n\n### Custom Function\n\nUse a registered function for complex logic:\n\n```typescript\n// In form config\ncustomFnConfig: {\n  derivations: {\n    calculateTax: (ctx) => ctx.formValue.subtotal * getTaxRate(ctx.formValue.state),\n  },\n},\nfields: [\n  {\n    key: 'tax',\n    type: 'input',\n    readonly: true,\n    logic: [{\n      type: 'derivation',\n      functionName: 'calculateTax',\n      dependsOn: ['subtotal', 'state'],\n    }],\n  },\n],\n```\n\n## Trigger Timing\n\nControl when derivations evaluate:\n\n| Trigger     | Description                           | Use Case                              |\n| ----------- | ------------------------------------- | ------------------------------------- |\n| `onChange`  | Immediately on value change (default) | Computed totals, conditional prefixes |\n| `debounced` | After value stabilizes                | Self-transforms, format masking       |\n\n### Debounced Derivations\n\nUse `trigger: 'debounced'` for self-transforming fields to avoid interrupting the user while typing:\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  label: 'Email',\n  logic: [{\n    type: 'derivation',\n    expression: 'formValue.email.toLowerCase()',\n    trigger: 'debounced',\n    debounceMs: 500, // optional, defaults to 500\n  }],\n}\n```\n\nThe transformation applies after the user stops typing for 500ms.\n\n## Conditional Derivations\n\nOnly apply derivations when conditions are met:\n\n```typescript\n{\n  key: 'currency',\n  type: 'input',\n  label: 'Currency',\n  readonly: true,\n  logic: [\n    {\n      type: 'derivation',\n      value: 'USD',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'country',\n        operator: 'equals',\n        value: 'USA',\n      },\n    },\n    {\n      type: 'derivation',\n      value: 'EUR',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'country',\n        operator: 'equals',\n        value: 'Germany',\n      },\n    },\n  ],\n}\n```\n\nMultiple derivations on the same field are evaluated in order.\n\n## Dependencies\n\n### Automatic Detection\n\nFor expressions, dependencies are automatically extracted:\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  derivation: 'formValue.quantity * formValue.unitPrice',\n  // Automatically depends on: quantity, unitPrice\n}\n```\n\n### Explicit Dependencies\n\nFor custom functions, specify dependencies explicitly:\n\n```typescript\n{\n  key: 'discount',\n  type: 'input',\n  label: 'Discount',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    functionName: 'calculateDiscount',\n    dependsOn: ['total', 'memberLevel'],\n  }],\n}\n```\n\nWithout `dependsOn`, custom functions re-evaluate on any form change.\n\n## Complete Example\n\n```typescript\nconst orderForm = {\n  fields: [\n    {\n      key: 'quantity',\n      type: 'input',\n      value: 1,\n      label: 'Quantity',\n      props: { type: 'number' },\n    },\n    {\n      key: 'unitPrice',\n      type: 'input',\n      value: 10,\n      label: 'Unit Price',\n      props: { type: 'number' },\n    },\n    {\n      key: 'subtotal',\n      type: 'input',\n      value: 0,\n      label: 'Subtotal',\n      readonly: true,\n      derivation: 'formValue.quantity * formValue.unitPrice',\n    },\n    {\n      key: 'tax',\n      type: 'input',\n      value: 0,\n      label: 'Tax (10%)',\n      readonly: true,\n      derivation: 'formValue.subtotal * 0.1',\n    },\n    {\n      key: 'total',\n      type: 'input',\n      value: 0,\n      label: 'Total',\n      readonly: true,\n      derivation: 'formValue.subtotal + formValue.tax',\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n## Array Field Derivations\n\nInside arrays, `formValue` is scoped to the current array item:\n\n```typescript\n{\n  key: 'lineItems',\n  type: 'array',\n  fields: [\n    {\n      key: 'itemRow',\n      type: 'row',\n      fields: [\n        { key: 'quantity', type: 'input', label: 'Qty', value: 1 },\n        { key: 'unitPrice', type: 'input', label: 'Price', value: 0 },\n        {\n          key: 'lineTotal',\n          type: 'input',\n          label: 'Total',\n          value: 0,\n          readonly: true,\n          // formValue is scoped to the current array item\n          derivation: 'formValue.quantity * formValue.unitPrice',\n        },\n      ],\n    },\n  ],\n}\n```\n\n### Accessing Root Form Value\n\nInside array items, `formValue` refers to the current array item. Use `rootFormValue` to access the entire form:\n\n```typescript\n{\n  key: 'lineTotal',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  // formValue = current array item { quantity, unitPrice }\n  // rootFormValue = entire form { lineItems, discount, ... }\n  derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.discount / 100)',\n}\n```\n\n## Debugging Derivations\n\nEnable derivation logging to troubleshoot issues:\n\n### Configuration\n\nConfigure derivation logging via `withLoggerConfig`:\n\n```typescript\n// In your providers\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'verbose' }));\n\n// Or just summary level\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'summary' }));\n```\n\n### Log Levels\n\n| Level     | Output                            |\n| --------- | --------------------------------- |\n| `none`    | No logging (default)              |\n| `summary` | Cycle completion with counts      |\n| `verbose` | Individual derivation evaluations |\n\n### Using debugName\n\nAdd names to derivations for easier identification in logs:\n\n```typescript\n{\n  key: 'lineTotal',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    debugName: 'Calculate line total',\n    expression: 'formValue.quantity * formValue.unitPrice',\n  }],\n}\n```\n\n**Console output (verbose mode):**\n\n```\nDerivation - Starting cycle (onChange) with 5 derivation(s)\nDerivation - Iteration 1\nDerivation - Applied \"Calculate line total\" { field: 'lineTotal', newValue: 150 }\nDerivation - Skipped: phonePrefix (condition not met)\nDerivation - Cycle complete (onChange) { applied: 1, skipped: 4, errors: 0, iterations: 1 }\n```\n\n## Bidirectional Derivations\n\nCreate two-way bindings between fields:\n\n```typescript\n// Celsius to Fahrenheit\n{\n  key: 'fahrenheit',\n  type: 'input',\n  value: 32,\n  derivation: 'formValue.celsius * 9 / 5 + 32',\n}\n\n// Fahrenheit to Celsius\n{\n  key: 'celsius',\n  type: 'input',\n  value: 0,\n  derivation: '(formValue.fahrenheit - 32) * 5 / 9',\n}\n```\n\n### Cycle Detection\n\nThe system automatically detects derivation cycles and warns during development:\n\n```\nBidirectional derivation detected: celsius <-> fahrenheit\nBidirectional derivations stabilize via equality check.\n```\n\n### Floating-Point Precision\n\nBidirectional derivations stabilize when the computed value equals the current value. For floating-point operations, consider:\n\n1. **Rounding in expressions:**\n\n   ```typescript\n   derivation: 'Math.round(formValue.usd * exchangeRate * 100) / 100';\n   ```\n\n2. **Using integers:** Store cents instead of dollars\n3. **One-way derivation:** If bidirectional isn't required\n\n## Derivation Processing\n\n### Evaluation Order\n\nDerivations are topologically sorted based on dependencies:\n\n```\nquantity  \u2500\u2510\n            \u251C\u2500\u2500 subtotal \u2500\u2510\nunitPrice \u2500\u2518              \u251C\u2500\u2500 total\n                          \u2502\n             tax \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nThis ensures `subtotal` is computed before `total`.\n\n### Iteration Limits\n\nTo prevent infinite loops, derivations are limited to 10 iterations per cycle. If exceeded:\n\n```\nDerivation - Max iterations reached (onChange).\nThis may indicate a loop in derivation logic.\n```\n\n## DerivationLogicConfig Interface\n\n```typescript\ninterface DerivationLogicConfig {\n  /** Logic type identifier */\n  type: 'derivation';\n\n  /** Optional name for debugging */\n  debugName?: string;\n\n  /** When to evaluate: 'onChange' (default) or 'debounced' */\n  trigger?: 'onChange' | 'debounced';\n\n  /** Debounce duration in ms (default: 500) */\n  debounceMs?: number;\n\n  /** Static value to set */\n  value?: unknown;\n\n  /** JavaScript expression (has access to formValue) */\n  expression?: string;\n\n  /** Name of registered custom function */\n  functionName?: string;\n\n  /** Explicit field dependencies */\n  dependsOn?: string[];\n\n  /** Condition for when derivation applies */\n  condition?: ConditionalExpression | boolean;\n}\n```\n\n## External Data in Derivations\n\nUse external application state in derivation expressions:\n\n```typescript\nconst config = {\n  externalData: {\n    discountRate: computed(() => pricingService.currentDiscount()),\n  },\n  fields: [\n    {\n      key: 'discountedPrice',\n      type: 'input',\n      label: 'Discounted Price',\n      readonly: true,\n      derivation: 'formValue.price * (1 - externalData.discountRate)',\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\nExternal data values are reactively tracked - when signals change, derivations are re-evaluated.\n\n## Related\n\n- **Property Derivation** (see tab above) - Derive component properties (minDate, options, label) from form values\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"
+        content: "Automatically compute and set field values based on other form values. Derivations enable calculated fields, auto-fill patterns, and value transformations.\n\n## Quick Start\n\nDerivations are defined ON the field that receives the computed value (self-targeting).\n\n### Shorthand Syntax (Preferred)\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  derivation: 'formValue.quantity * formValue.unitPrice',\n}\n```\n\n### Logic Block Syntax\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    expression: 'formValue.quantity * formValue.unitPrice',\n  }],\n}\n```\n\nWhen `quantity` or `unitPrice` changes, `total` is automatically recalculated.\n\n## Derivation Types\n\n### Expression-Based\n\nUse JavaScript expressions with access to `formValue`:\n\n```typescript\n{\n  key: 'fullName',\n  type: 'input',\n  label: 'Full Name',\n  readonly: true,\n  derivation: '(formValue.firstName || \"\") + \" \" + (formValue.lastName || \"\")',\n}\n```\n\n**Available variables:**\n\n- `formValue` - Object containing all form field values\n- `externalData` - External application state (when configured in FormConfig)\n\n### Static Value\n\nSet a constant value when a condition is met:\n\n```typescript\n{\n  key: 'phonePrefix',\n  type: 'input',\n  label: 'Phone Prefix',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    value: '+1',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'country',\n      operator: 'equals',\n      value: 'USA',\n    },\n  }],\n}\n```\n\n### Custom Function\n\nUse a registered function for complex logic:\n\n```typescript\n// In form config\ncustomFnConfig: {\n  derivations: {\n    calculateTax: (ctx) => ctx.formValue.subtotal * getTaxRate(ctx.formValue.state),\n  },\n},\nfields: [\n  {\n    key: 'tax',\n    type: 'input',\n    readonly: true,\n    logic: [{\n      type: 'derivation',\n      functionName: 'calculateTax',\n      dependsOn: ['subtotal', 'state'],\n    }],\n  },\n],\n```\n\n## Trigger Timing\n\nControl when derivations evaluate:\n\n| Trigger     | Description                           | Use Case                              |\n| ----------- | ------------------------------------- | ------------------------------------- |\n| `onChange`  | Immediately on value change (default) | Computed totals, conditional prefixes |\n| `debounced` | After value stabilizes                | Self-transforms, format masking       |\n\n### Debounced Derivations\n\nUse `trigger: 'debounced'` for self-transforming fields to avoid interrupting the user while typing:\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  label: 'Email',\n  logic: [{\n    type: 'derivation',\n    expression: 'formValue.email.toLowerCase()',\n    trigger: 'debounced',\n    debounceMs: 500, // optional, defaults to 500\n  }],\n}\n```\n\nThe transformation applies after the user stops typing for 500ms.\n\n## Conditional Derivations\n\nOnly apply derivations when conditions are met:\n\n```typescript\n{\n  key: 'currency',\n  type: 'input',\n  label: 'Currency',\n  readonly: true,\n  logic: [\n    {\n      type: 'derivation',\n      value: 'USD',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'country',\n        operator: 'equals',\n        value: 'USA',\n      },\n    },\n    {\n      type: 'derivation',\n      value: 'EUR',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'country',\n        operator: 'equals',\n        value: 'Germany',\n      },\n    },\n  ],\n}\n```\n\nMultiple derivations on the same field are evaluated in order.\n\n## Dependencies\n\n### Automatic Detection\n\nFor expressions, dependencies are automatically extracted:\n\n```typescript\n{\n  key: 'total',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  derivation: 'formValue.quantity * formValue.unitPrice',\n  // Automatically depends on: quantity, unitPrice\n}\n```\n\n### Explicit Dependencies\n\nFor custom functions, specify dependencies explicitly:\n\n```typescript\n{\n  key: 'discount',\n  type: 'input',\n  label: 'Discount',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    functionName: 'calculateDiscount',\n    dependsOn: ['total', 'memberLevel'],\n  }],\n}\n```\n\nWithout `dependsOn`, custom functions re-evaluate on any form change.\n\n## Complete Example\n\n```typescript\nconst orderForm = {\n  fields: [\n    {\n      key: 'quantity',\n      type: 'input',\n      value: 1,\n      label: 'Quantity',\n      props: { type: 'number' },\n    },\n    {\n      key: 'unitPrice',\n      type: 'input',\n      value: 10,\n      label: 'Unit Price',\n      props: { type: 'number' },\n    },\n    {\n      key: 'subtotal',\n      type: 'input',\n      value: 0,\n      label: 'Subtotal',\n      readonly: true,\n      derivation: 'formValue.quantity * formValue.unitPrice',\n    },\n    {\n      key: 'tax',\n      type: 'input',\n      value: 0,\n      label: 'Tax (10%)',\n      readonly: true,\n      derivation: 'formValue.subtotal * 0.1',\n    },\n    {\n      key: 'total',\n      type: 'input',\n      value: 0,\n      label: 'Total',\n      readonly: true,\n      derivation: 'formValue.subtotal + formValue.tax',\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\n## Array Field Derivations\n\nInside arrays, `formValue` is scoped to the current array item:\n\n```typescript\n{\n  key: 'lineItems',\n  type: 'array',\n  fields: [\n    {\n      key: 'itemRow',\n      type: 'row',\n      fields: [\n        { key: 'quantity', type: 'input', label: 'Qty', value: 1 },\n        { key: 'unitPrice', type: 'input', label: 'Price', value: 0 },\n        {\n          key: 'lineTotal',\n          type: 'input',\n          label: 'Total',\n          value: 0,\n          readonly: true,\n          // formValue is scoped to the current array item\n          derivation: 'formValue.quantity * formValue.unitPrice',\n        },\n      ],\n    },\n  ],\n}\n```\n\n### Accessing Root Form Value\n\nInside array items, `formValue` refers to the current array item. Use `rootFormValue` to access the entire form:\n\n```typescript\n{\n  key: 'lineTotal',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  // formValue = current array item { quantity, unitPrice }\n  // rootFormValue = entire form { lineItems, discount, ... }\n  derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.discount / 100)',\n}\n```\n\n## Debugging Derivations\n\nEnable derivation logging to troubleshoot issues:\n\n### Configuration\n\nConfigure derivation logging via `withLoggerConfig`:\n\n```typescript\n// In your providers\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'verbose' }));\n\n// Or just summary level\nprovideDynamicForm(...withMaterialFields(), withLoggerConfig({ derivations: 'summary' }));\n```\n\n### Log Levels\n\n| Level     | Output                            |\n| --------- | --------------------------------- |\n| `none`    | No logging (default)              |\n| `summary` | Cycle completion with counts      |\n| `verbose` | Individual derivation evaluations |\n\n### Using debugName\n\nAdd names to derivations for easier identification in logs:\n\n```typescript\n{\n  key: 'lineTotal',\n  type: 'input',\n  label: 'Total',\n  readonly: true,\n  logic: [{\n    type: 'derivation',\n    debugName: 'Calculate line total',\n    expression: 'formValue.quantity * formValue.unitPrice',\n  }],\n}\n```\n\n**Console output (verbose mode):**\n\n```\nDerivation - Starting cycle (onChange) with 5 derivation(s)\nDerivation - Iteration 1\nDerivation - Applied \"Calculate line total\" { field: 'lineTotal', newValue: 150 }\nDerivation - Skipped: phonePrefix (condition not met)\nDerivation - Cycle complete (onChange) { applied: 1, skipped: 4, errors: 0, iterations: 1 }\n```\n\n## Bidirectional Derivations\n\nCreate two-way bindings between fields:\n\n```typescript\n// Celsius to Fahrenheit\n{\n  key: 'fahrenheit',\n  type: 'input',\n  value: 32,\n  derivation: 'formValue.celsius * 9 / 5 + 32',\n}\n\n// Fahrenheit to Celsius\n{\n  key: 'celsius',\n  type: 'input',\n  value: 0,\n  derivation: '(formValue.fahrenheit - 32) * 5 / 9',\n}\n```\n\n### Cycle Detection\n\nThe system automatically detects derivation cycles and warns during development:\n\n```\nBidirectional derivation detected: celsius <-> fahrenheit\nBidirectional derivations stabilize via equality check.\n```\n\n### Floating-Point Precision\n\nBidirectional derivations stabilize when the computed value equals the current value. For floating-point operations, consider:\n\n1. **Rounding in expressions:**\n\n   ```typescript\n   derivation: 'Math.round(formValue.usd * exchangeRate * 100) / 100';\n   ```\n\n2. **Using integers:** Store cents instead of dollars\n3. **One-way derivation:** If bidirectional isn't required\n\n## Derivation Processing\n\n### Evaluation Order\n\nDerivations are topologically sorted based on dependencies:\n\n```\nquantity  \u2500\u2510\n            \u251C\u2500\u2500 subtotal \u2500\u2510\nunitPrice \u2500\u2518              \u251C\u2500\u2500 total\n                          \u2502\n             tax \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nThis ensures `subtotal` is computed before `total`.\n\n### Iteration Limits\n\nTo prevent infinite loops, derivations are limited to 10 iterations per cycle. If exceeded:\n\n```\nDerivation - Max iterations reached (onChange).\nThis may indicate a loop in derivation logic.\n```\n\n## DerivationLogicConfig Interface\n\n```typescript\ninterface DerivationLogicConfig {\n  /** Logic type identifier */\n  type: 'derivation';\n\n  /** Optional name for debugging */\n  debugName?: string;\n\n  /** When to evaluate: 'onChange' (default) or 'debounced' */\n  trigger?: 'onChange' | 'debounced';\n\n  /** Debounce duration in ms (default: 500) */\n  debounceMs?: number;\n\n  /** Static value to set */\n  value?: unknown;\n\n  /** JavaScript expression (has access to formValue) */\n  expression?: string;\n\n  /** Name of registered custom function */\n  functionName?: string;\n\n  /** Explicit field dependencies */\n  dependsOn?: string[];\n\n  /** Condition for when derivation applies */\n  condition?: ConditionalExpression | boolean;\n}\n```\n\n## External Data in Derivations\n\nUse external application state in derivation expressions:\n\n```typescript\nconst config = {\n  externalData: {\n    discountRate: computed(() => pricingService.currentDiscount()),\n  },\n  fields: [\n    {\n      key: 'discountedPrice',\n      type: 'input',\n      label: 'Discounted Price',\n      readonly: true,\n      derivation: 'formValue.price * (1 - externalData.discountRate)',\n    },\n  ],\n} as const satisfies FormConfig;\n```\n\nExternal data values are reactively tracked - when signals change, derivations are re-evaluated.\n\n## Related\n\n- **Property Derivation** (see tab above) \u2014 Derive component properties (minDate, options, label) from form values\n- **Async Derivation** (see tab above) \u2014 HTTP and async function derivations, stopOnUserOverride\n- **[Conditional Logic](../conditional-logic/overview/)** \u2014 Control field visibility and state\n- **[Array Fields](../../prebuilt/form-arrays/simplified/)** \u2014 Working with array fields\n- **[Examples](/examples)** \u2014 Real-world form patterns"
       },
       {
         id: "dynamic-behavior-value-derivation-basics-property-derivation",
         title: "Dynamic Behavior Value Derivation Basics Property Derivation",
         category: "dynamic-behavior",
-        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: 'propertyDerivation'` 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: 'propertyDerivation',\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## 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: 'propertyDerivation',\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: 'propertyDerivation',\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  propertyDerivations: {\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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    propertyDerivations: {\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation',\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: 'propertyDerivation'`         |\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.propertyDerivations` |\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: 'propertyDerivation',\n    debugName: 'endDate minDate constraint',\n    targetProperty: 'minDate',\n    expression: 'formValue.startDate',\n  },\n];\n```\n\n## PropertyDerivationLogicConfig Interface\n\n```typescript\ninterface PropertyDerivationLogicConfig {\n  /** Logic type identifier */\n  type: 'propertyDerivation';\n\n  /** Property to set on the field component */\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    propertyDerivations: {\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: 'propertyDerivation',\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/)** - Working with array fields"
+        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"
       },
       {
         id: "age-conditional-form",
@@ -74,6 +86,12 @@ var require_docs = __commonJS({
         category: "examples",
         content: "[\u2190 Back to Quick Start](/examples)\n\nRegistration form demonstrating numeric comparison operators for age-based conditional logic.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/age-conditional-form\" class=\"example-frame\" title=\"Age Conditional Form Demo\"></iframe>\n\n## Overview\n\nThis example shows how to use numeric comparison operators to display different fields based on age ranges. Minors see parental consent fields, while seniors see discount options.\n\n**Key patterns demonstrated:**\n\n- Age-appropriate field display\n- Numeric comparisons (greater than, less than)\n- Multiple conditional sections based on same field\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, type FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n  selector: 'app-age-conditional-form',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class AgeConditionalFormComponent {\n  formValue = signal({});\n\n  config = {\n    fields: [\n      {\n        key: 'name',\n        type: 'input',\n        value: '',\n        label: 'Full Name',\n        required: true,\n      },\n      {\n        key: 'email',\n        type: 'input',\n        value: '',\n        label: 'Email Address',\n        required: true,\n        email: true,\n      },\n      {\n        key: 'age',\n        type: 'input',\n        value: null,\n        label: 'Age',\n        required: true,\n        min: 0,\n        max: 120,\n        props: {\n          type: 'number',\n          hint: 'Enter your age to see relevant options',\n        },\n      },\n      {\n        key: 'parentalConsent',\n        type: 'checkbox',\n        value: false,\n        label: 'I have parental/guardian consent to register',\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'greaterOrEqual',\n              value: 18,\n            },\n          },\n          {\n            type: 'required',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'less',\n              value: 18,\n            },\n          },\n        ],\n      },\n      {\n        key: 'parentEmail',\n        type: 'input',\n        value: '',\n        label: 'Parent/Guardian Email',\n        email: true,\n        props: {\n          hint: 'We will send a verification email to your parent/guardian',\n        },\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'greaterOrEqual',\n              value: 18,\n            },\n          },\n          {\n            type: 'required',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'less',\n              value: 18,\n            },\n          },\n        ],\n      },\n      {\n        key: 'seniorDiscount',\n        type: 'checkbox',\n        value: false,\n        label: 'Apply senior discount (65+)',\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'less',\n              value: 65,\n            },\n          },\n        ],\n      },\n      {\n        key: 'aarpMember',\n        type: 'checkbox',\n        value: false,\n        label: 'I am an AARP member (additional 5% discount)',\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'age',\n              operator: 'less',\n              value: 65,\n            },\n          },\n        ],\n      },\n      {\n        type: 'submit',\n        key: 'submit',\n        label: 'Register',\n      },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\n## How It Works\n\n### Age-Based Visibility\n\nFields for minors are hidden when age >= 18:\n\n```typescript\n{\n  key: 'parentalConsent',\n  type: 'checkbox',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'age',\n      operator: 'greaterOrEqual',\n      value: 18,\n    },\n  }],\n}\n```\n\nFields for seniors are hidden when age < 65:\n\n```typescript\n{\n  key: 'seniorDiscount',\n  type: 'checkbox',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'age',\n      operator: 'less',\n      value: 65,\n    },\n  }],\n}\n```\n\n### Conditional Required for Minors\n\nParent email is required only for minors:\n\n```typescript\n{\n  key: 'parentEmail',\n  type: 'input',\n  logic: [\n    {\n      type: 'hidden',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'age',\n        operator: 'greaterOrEqual',\n        value: 18,\n      },\n    },\n    {\n      type: 'required',\n      condition: {\n        type: 'fieldValue',\n        fieldPath: 'age',\n        operator: 'less',\n        value: 18,\n      },\n    },\n  ],\n}\n```\n\n## Comparison Operators\n\nThis example uses numeric comparison operators:\n\n| Operator         | Description                |\n| ---------------- | -------------------------- |\n| `greater`        | Greater than (>)           |\n| `less`           | Less than (<)              |\n| `greaterOrEqual` | Greater than or equal (>=) |\n| `lessOrEqual`    | Less than or equal (<=)    |\n\n## Use Cases\n\n- Age-gated registration\n- Tiered pricing forms\n- Compliance forms with age requirements\n- Membership applications\n\n## Related Documentation\n\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Full conditional logic guide\n- **[Validation](../../validation/basics/)** - Min/max validation\n- **[User Registration](../user-registration/)** - Basic registration example"
       },
+      {
+        id: "array-form",
+        title: "Array Form",
+        category: "examples",
+        content: "[\u2190 Back to Quick Start](/examples)\n\nDynamic form arrays using the complete API with declarative add/remove buttons, custom button placement, and full control over item structure.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Overview\n\nThis example demonstrates the complete array API with:\n\n- **Flat arrays** with row-based items (input + remove button)\n- **Object arrays** with multiple fields per item\n- **Declarative buttons** for add, prepend, and remove operations\n- **Custom button placement** outside the array container\n- **Template-based item creation**\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new tags \u2014 a row with an input and remove button\nconst tagTemplate = {\n  key: 'tag',\n  type: 'row',\n  fields: [\n    {\n      key: 'value',\n      type: 'input',\n      label: 'Tag',\n      required: true,\n      minLength: 2,\n      props: { placeholder: 'Enter a tag', hint: 'Tags must be at least 2 characters' },\n    },\n    {\n      key: 'removeTag',\n      type: 'removeArrayItem',\n      label: 'Remove',\n      className: 'remove-tag-button',\n      props: { color: 'warn' },\n    },\n  ],\n} as const;\n\n// Template for new contacts \u2014 includes remove button inside each item\nconst contactTemplate = [\n  {\n    key: 'name',\n    type: 'input',\n    label: 'Contact Name',\n    required: true,\n    minLength: 2,\n    props: { placeholder: 'Enter contact name', hint: 'Full name of the emergency contact' },\n  },\n  {\n    key: 'phone',\n    type: 'input',\n    label: 'Phone Number',\n    required: true,\n    pattern: /^\\d{10}$/,\n    validationMessages: { pattern: 'Please enter a valid 10-digit phone number' },\n    props: { type: 'tel', placeholder: '5551234567' },\n  },\n  {\n    key: 'relationship',\n    type: 'select',\n    label: 'Relationship',\n    required: true,\n    options: [\n      { label: 'Family', value: 'family' },\n      { label: 'Friend', value: 'friend' },\n      { label: 'Colleague', value: 'colleague' },\n      { label: 'Other', value: 'other' },\n    ],\n  },\n  {\n    key: 'removeContact',\n    type: 'removeArrayItem',\n    label: 'Remove Contact',\n    className: 'remove-contact-button',\n    props: { color: 'warn' },\n  },\n] as const;\n\n@Component({\n  selector: 'app-array-form',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class ArrayFormComponent {\n  formValue = signal({});\n\n  config = {\n    fields: [\n      // Flat array with row-based items\n      {\n        key: 'tags',\n        type: 'array',\n        fields: [\n          [\n            {\n              key: 'tag',\n              type: 'row',\n              fields: [\n                { key: 'value', type: 'input', label: 'Tag', value: 'angular', required: true, minLength: 2 },\n                { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n              ],\n            },\n          ],\n          [\n            {\n              key: 'tag',\n              type: 'row',\n              fields: [\n                { key: 'value', type: 'input', label: 'Tag', value: 'typescript', required: true, minLength: 2 },\n                { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n              ],\n            },\n          ],\n        ],\n      },\n      // Add button placed outside the array\n      {\n        key: 'addTagButton',\n        type: 'addArrayItem',\n        label: 'Add Tag',\n        arrayKey: 'tags',\n        template: [tagTemplate],\n        props: { color: 'primary' },\n      },\n\n      // Object array with multiple fields per item\n      {\n        key: 'contacts',\n        type: 'array',\n        fields: [\n          [\n            { key: 'name', type: 'input', label: 'Contact Name', value: 'Jane Smith', required: true, minLength: 2 },\n            { key: 'phone', type: 'input', label: 'Phone Number', value: '5551234567', required: true },\n            {\n              key: 'relationship',\n              type: 'select',\n              label: 'Relationship',\n              value: 'family',\n              required: true,\n              options: [\n                { label: 'Family', value: 'family' },\n                { label: 'Friend', value: 'friend' },\n                { label: 'Colleague', value: 'colleague' },\n                { label: 'Other', value: 'other' },\n              ],\n            },\n            { key: 'removeContact', type: 'removeArrayItem', label: 'Remove Contact', props: { color: 'warn' } },\n          ],\n        ],\n      },\n      // Multiple add buttons with different behaviors\n      {\n        key: 'contactButtons',\n        type: 'row',\n        fields: [\n          {\n            key: 'prependContactButton',\n            type: 'prependArrayItem',\n            label: 'Add First',\n            arrayKey: 'contacts',\n            template: contactTemplate,\n            props: { color: 'accent' },\n          },\n          {\n            key: 'addContactButton',\n            type: 'addArrayItem',\n            label: 'Add Contact',\n            arrayKey: 'contacts',\n            template: contactTemplate,\n            props: { color: 'primary' },\n          },\n        ],\n      },\n\n      { key: 'submit', type: 'submit', label: 'Save All', props: { color: 'primary' } },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\n## Key Features\n\n### Declarative Add/Remove Buttons\n\nUse `addArrayItem`, `prependArrayItem`, and `removeArrayItem` button types directly in your config:\n\n```typescript\n// Add button outside the array\n{\n  key: 'addTag',\n  type: 'addArrayItem',\n  label: 'Add Tag',\n  arrayKey: 'tags',        // Points to the array field\n  template: tagTemplate,   // Defines the new item structure\n}\n\n// Remove button inside each array item\n{\n  key: 'removeTag',\n  type: 'removeArrayItem',\n  label: 'Remove',\n}\n```\n\n### Custom Button Placement\n\nPlace add/prepend buttons anywhere in the form layout:\n\n```typescript\n{\n  key: 'contactButtons',\n  type: 'row',\n  fields: [\n    { key: 'prepend', type: 'prependArrayItem', label: 'Add First', arrayKey: 'contacts', template: contactTemplate },\n    { key: 'append', type: 'addArrayItem', label: 'Add Last', arrayKey: 'contacts', template: contactTemplate },\n  ],\n}\n```\n\n### Templates for New Items\n\nEach add button defines its own template for what to insert:\n\n```typescript\nconst contactTemplate = [\n  { key: 'name', type: 'input', label: 'Name' },\n  { key: 'phone', type: 'input', label: 'Phone' },\n  { key: 'remove', type: 'removeArrayItem', label: 'Remove' },\n];\n```\n\n## Use Cases\n\n- Forms requiring custom button placement\n- Arrays with multiple add operations (append, prepend, insert)\n- Heterogeneous arrays with different item structures\n- Complex layouts with row-based array items\n\n## Related Examples\n\n- **[Simplified Array Form](../simplified-array-form/)** - Simpler API with auto-generated buttons\n- **[Paginated Form](../paginated-form/)** - Multi-step wizard form\n- **[Contact Form](../contact-form/)** - Basic contact form\n\n## Related Documentation\n\n- **[Complete Array API](../../prebuilt/form-arrays/complete/)** - Full API reference\n- **[Simplified Array API](../../prebuilt/form-arrays/simplified/)** - Simpler alternative\n- **[Validation](../../validation/basics/)** - Form validation guide"
+      },
       {
         id: "business-account-form",
         title: "Business Account Form",
@@ -116,6 +134,12 @@ var require_docs = __commonJS({
         category: "examples",
         content: "[\u2190 Back to Quick Start](/examples)\n\nCheckout form demonstrating the common \"same as billing\" pattern for shipping addresses.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/shipping-billing-address\" class=\"example-frame\" title=\"Shipping Billing Address Demo\"></iframe>\n\n## Overview\n\nThis example shows how to toggle an entire group of fields based on a checkbox. When \"Shipping same as billing\" is checked, the shipping address fields are hidden.\n\n**Key patterns demonstrated:**\n\n- Entire group hidden/shown with single condition\n- Checkbox controls form complexity\n- Reduces user effort when addresses are the same\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, type FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n  selector: 'app-shipping-billing-form',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class ShippingBillingFormComponent {\n  formValue = signal({});\n\n  config = {\n    fields: [\n      {\n        key: 'billingTitle',\n        type: 'text',\n        label: 'Billing Address',\n        props: { elementType: 'h4' },\n      },\n      {\n        key: 'billingAddress',\n        type: 'group',\n        fields: [\n          {\n            key: 'street',\n            type: 'input',\n            value: '',\n            label: 'Street Address',\n            required: true,\n          },\n          {\n            key: 'city',\n            type: 'input',\n            value: '',\n            label: 'City',\n            required: true,\n          },\n          {\n            key: 'state',\n            type: 'input',\n            value: '',\n            label: 'State/Province',\n            required: true,\n          },\n          {\n            key: 'zipCode',\n            type: 'input',\n            value: '',\n            label: 'ZIP/Postal Code',\n            required: true,\n          },\n        ],\n      },\n      {\n        key: 'sameAsBilling',\n        type: 'checkbox',\n        value: false,\n        label: 'Shipping address is same as billing address',\n      },\n      {\n        key: 'shippingTitle',\n        type: 'text',\n        label: 'Shipping Address',\n        props: { elementType: 'h4' },\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'sameAsBilling',\n              operator: 'equals',\n              value: true,\n            },\n          },\n        ],\n      },\n      {\n        key: 'shippingAddress',\n        type: 'group',\n        logic: [\n          {\n            type: 'hidden',\n            condition: {\n              type: 'fieldValue',\n              fieldPath: 'sameAsBilling',\n              operator: 'equals',\n              value: true,\n            },\n          },\n        ],\n        fields: [\n          {\n            key: 'street',\n            type: 'input',\n            value: '',\n            label: 'Street Address',\n            required: true,\n          },\n          {\n            key: 'city',\n            type: 'input',\n            value: '',\n            label: 'City',\n            required: true,\n          },\n          {\n            key: 'state',\n            type: 'input',\n            value: '',\n            label: 'State/Province',\n            required: true,\n          },\n          {\n            key: 'zipCode',\n            type: 'input',\n            value: '',\n            label: 'ZIP/Postal Code',\n            required: true,\n          },\n        ],\n      },\n      {\n        type: 'submit',\n        key: 'submit',\n        label: 'Continue to Payment',\n      },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\n## How It Works\n\n### Checkbox Toggle\n\nA simple checkbox controls whether shipping fields are visible:\n\n```typescript\n{\n  key: 'sameAsBilling',\n  type: 'checkbox',\n  value: false,\n  label: 'Shipping address is same as billing address',\n}\n```\n\n### Group Visibility\n\nThe entire shipping address group is hidden when the checkbox is checked:\n\n```typescript\n{\n  key: 'shippingAddress',\n  type: 'group',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'sameAsBilling',\n      operator: 'equals',\n      value: true,\n    },\n  }],\n  fields: [\n    // All shipping fields...\n  ],\n}\n```\n\n### Section Titles\n\nThe section title is also hidden along with the group:\n\n```typescript\n{\n  key: 'shippingTitle',\n  type: 'text',\n  label: 'Shipping Address',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'sameAsBilling',\n      operator: 'equals',\n      value: true,\n    },\n  }],\n}\n```\n\n## Use Cases\n\n- E-commerce checkout flows\n- Order forms\n- Account billing setup\n- Subscription management\n\n## Related Documentation\n\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Full conditional logic guide\n- **[Form Groups](../../prebuilt/form-groups/)** - Working with groups\n- **[Checkbox Fields](../../schema-fields/field-types/)** - Field types reference"
       },
+      {
+        id: "simplified-array-form",
+        title: "Simplified Array Form",
+        category: "examples",
+        content: "[\u2190 Back to Quick Start](/examples)\n\nDynamic arrays using the simplified API with auto-generated add/remove buttons, template-based item definitions, and both primitive and object arrays.\n\n## Live Demo\n\n<iframe src=\"http://localhost:4201/#/examples/simplified-array\" class=\"example-frame\" title=\"Simplified Array Demo\"></iframe>\n\n## Overview\n\nThis example showcases the simplified array API with:\n\n- **Primitive arrays** (tags) with flat scalar values\n- **Object arrays** (contacts) with multiple fields per item\n- **Empty arrays** that start with no items\n- **Button customization** including opt-out\n- **Auto-generated add/remove buttons**\n\n## Implementation\n\n```typescript\nimport { Component, signal } from '@angular/core';\nimport { DynamicForm, FormConfig } from '@ng-forge/dynamic-forms';\n\n@Component({\n  selector: 'app-simplified-array-form',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]=\"config\" [(value)]=\"formValue\"></form>`,\n})\nexport class SimplifiedArrayFormComponent {\n  formValue = signal({});\n\n  config = {\n    fields: [\n      // Primitive array \u2014 tags\n      {\n        key: 'tags',\n        type: 'array',\n        template: {\n          key: 'value',\n          type: 'input',\n          label: 'Tag',\n          required: true,\n          minLength: 2,\n          props: { placeholder: 'Enter a tag' },\n        },\n        value: ['angular', 'typescript'],\n        addButton: { label: 'Add Tag', props: { color: 'primary' } },\n        removeButton: { label: 'Remove', props: { color: 'warn' } },\n      },\n\n      // Object array \u2014 contacts\n      {\n        key: 'contacts',\n        type: 'array',\n        template: [\n          {\n            key: 'name',\n            type: 'input',\n            label: 'Contact Name',\n            required: true,\n            minLength: 2,\n            props: { placeholder: 'Enter contact name' },\n          },\n          {\n            key: 'phone',\n            type: 'input',\n            label: 'Phone Number',\n            props: { type: 'tel', placeholder: '5551234567' },\n          },\n        ],\n        value: [\n          { name: 'Jane Smith', phone: '5551234567' },\n          { name: 'John Doe', phone: '5559876543' },\n        ],\n        addButton: { label: 'Add Contact', props: { color: 'primary' } },\n      },\n\n      // Empty array \u2014 notes\n      {\n        key: 'notes',\n        type: 'array',\n        template: {\n          key: 'text',\n          type: 'input',\n          label: 'Note',\n          props: { placeholder: 'Enter a note' },\n        },\n        addButton: { label: 'Add Note' },\n      },\n\n      // No remove button \u2014 categories\n      {\n        key: 'categories',\n        type: 'array',\n        template: { key: 'name', type: 'input', label: 'Category' },\n        value: ['Frontend', 'Backend'],\n        removeButton: false,\n        addButton: { label: 'Add Category' },\n      },\n\n      { key: 'submit', type: 'submit', label: 'Save All', props: { color: 'primary' } },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\n## Key Features\n\n### Template-Based Items\n\nDefine the item structure once via `template`, and provide initial data via `value`:\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag', required: true },\n  value: ['angular', 'typescript'],\n}\n```\n\n### Auto-Generated Buttons\n\nAdd and remove buttons are generated automatically. Customize labels and props:\n\n```typescript\naddButton: { label: 'Add Tag', props: { color: 'primary' } },\nremoveButton: { label: 'Remove', props: { color: 'warn' } },\n```\n\n### Button Opt-Out\n\nDisable buttons entirely with `false`:\n\n```typescript\nremoveButton: false,  // No remove buttons on items\naddButton: false,     // No add button\n```\n\n## Use Cases\n\n- Tag lists and keyword management\n- Contact lists with multiple fields\n- Dynamic note-taking\n- Category management\n- Any repeating data entry\n\n## Related Examples\n\n- **[Array Form (Complete)](../array-form/)** - Full control with declarative buttons and EventBus\n- **[Paginated Form](../paginated-form/)** - Multi-step wizard form\n- **[Contact Form](../contact-form/)** - Basic contact form\n\n## Related Documentation\n\n- **[Simplified Array API](../../prebuilt/form-arrays/simplified/)** - Full API reference\n- **[Complete Array API](../../prebuilt/form-arrays/complete/)** - Advanced array features\n- **[Validation](../../validation/basics/)** - Form validation guide"
+      },
       {
         id: "user-registration",
         title: "User Registration",
@@ -132,37 +156,43 @@ var require_docs = __commonJS({
         id: "index",
         title: "Index",
         category: "installation",
-        content: 'Get ng-forge dynamic forms up and running in your Angular project.\n\n## Requirements\n\n- **Angular 21+** - ng-forge dynamic forms requires Angular 21 or higher for signal forms support\n- **TypeScript 5.6+** - For best type inference results\n\n## Installation\n\nInstall the core library and your preferred UI integration:\n\n```bash group="install" name="npm"\nnpm install @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="yarn"\nyarn add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="pnpm"\npnpm add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n> This installs the core `@ng-forge/dynamic-forms` package and the Material Design integration. See [UI Framework Options](#ui-framework-options) below for other choices.\n\n## Configure Your App\n\nAdd the dynamic form provider to your app configuration:\n\n```typescript name="app.config.ts"\nimport { ApplicationConfig } from \'@angular/core\';\nimport { provideDynamicForm } from \'@ng-forge/dynamic-forms\';\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideDynamicForm(...withMaterialFields()),\n    // ... other providers\n  ],\n};\n```\n\nThe `provideDynamicForm()` function registers field types and validators. The `withMaterialFields()` function provides all Material Design field components.\n\n## Create Your First Form\n\nCreate a simple login form to verify everything works:\n\n```typescript name="login.component.ts"\nimport { Component } from \'@angular/core\';\nimport { DynamicForm, type FormConfig } from \'@ng-forge/dynamic-forms\';\n\n@Component({\n  selector: \'app-login\',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]="config"></form>`,\n})\nexport class LoginComponent {\n  config = {\n    fields: [\n      {\n        key: \'email\',\n        type: \'input\',\n        value: \'\',\n        label: \'Email\',\n        required: true,\n        email: true,\n      },\n      {\n        key: \'password\',\n        type: \'input\',\n        value: \'\',\n        label: \'Password\',\n        required: true,\n        minLength: 8,\n        props: { type: \'password\' },\n      },\n      {\n        type: \'submit\',\n        key: \'submit\',\n        label: \'Sign In\',\n        props: { color: \'primary\' },\n      },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\nYou now have a working form with:\n\n- \u2705 Real-time validation with error messages\n- \u2705 TypeScript type inference\n- \u2705 Material Design styling\n- \u2705 Accessibility support\n- \u2705 Submit button auto-disables when invalid\n\n## UI Framework Options\n\nng-forge dynamic forms supports multiple UI frameworks. Install the integration package for your preferred framework:\n\n### Material Design (Preview)\n\n```bash group="install-material" name="npm"\nnpm install @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="yarn"\nyarn add @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="pnpm"\npnpm add @ng-forge/dynamic-forms-material\n```\n\n```typescript\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withMaterialFields())],\n};\n```\n\nSee [Material Integration](../ui-libs-integrations/material) for full documentation.\n\n### PrimeNG (Preview)\n\n```bash group="install-primeng" name="npm"\nnpm install @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="yarn"\nyarn add @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="pnpm"\npnpm add @ng-forge/dynamic-forms-primeng\n```\n\n```typescript\nimport { withPrimeNGFields } from \'@ng-forge/dynamic-forms-primeng\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withPrimeNGFields())],\n};\n```\n\nSee [PrimeNG Integration](../ui-libs-integrations/primeng) for full documentation.\n\n### Bootstrap (Preview)\n\n```bash group="install-bootstrap" name="npm"\nnpm install @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="yarn"\nyarn add @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="pnpm"\npnpm add @ng-forge/dynamic-forms-bootstrap\n```\n\n```typescript\nimport { withBootstrapFields } from \'@ng-forge/dynamic-forms-bootstrap\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withBootstrapFields())],\n};\n```\n\nSee [Bootstrap Integration](../ui-libs-integrations/bootstrap) for full documentation.\n\n### Ionic (Preview)\n\n```bash group="install-ionic" name="npm"\nnpm install @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="yarn"\nyarn add @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="pnpm"\npnpm add @ng-forge/dynamic-forms-ionic\n```\n\n```typescript\nimport { withIonicFields } from \'@ng-forge/dynamic-forms-ionic\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withIonicFields())],\n};\n```\n\nSee [Ionic Integration](../ui-libs-integrations/ionic) for full documentation.\n\n### Custom UI Components\n\nYou can also build your own field components using any UI library or custom styling:\n\n```typescript\nimport { MyCustomInputComponent } from \'./my-custom-input.component\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideDynamicForm([\n      { name: \'input\', loadComponent: () => MyCustomInputComponent },\n      // ... more custom field types\n    ]),\n  ],\n};\n```\n\nSee [Custom Integration Guide](../advanced/custom-integrations) for building custom field components.\n\n## Next Steps\n\nNow that you have ng-forge dynamic forms installed, explore the core features:\n\n### Learn Core Concepts\n\n- **[Field Types](../schema-fields/field-types)** - Understand all available field types (input, select, checkbox, group, etc.)\n- **[Validation](../validation/basics)** - Add validation rules with shorthand syntax or conditional validators\n- **[Conditional Logic](../dynamic-behavior/conditional-logic/overview)** - Show/hide fields based on other field values\n- **[Type Safety](../advanced/type-safety/basics)** - TypeScript type inference for forms\n\n### Build Advanced Forms\n\n- **[Multi-Step Forms](../layout-components/form-pages)** - Create wizard-style forms with page navigation\n- **[Repeatable Sections](../layout-components/form-arrays)** - Dynamic form arrays for adding/removing fields\n- **[Conditional Validation](../validation/advanced#conditional-validators)** - Validators that activate based on conditions\n\n### Customize and Extend\n\n- **[i18n Setup](../dynamic-behavior/i18n)** - Add multi-language support to your forms\n- **[Events](../advanced/events)** - Handle custom form events\n- **[Custom Fields](../advanced/custom-integrations)** - Create your own field types\n\n## Get Help\n\n- \u{1F4AC} **[GitHub Discussions](https://github.com/ng-forge/ng-forge/discussions)** - Ask questions and get help\n- \u{1F41B} **[Issue Tracker](https://github.com/ng-forge/ng-forge/issues)** - Report bugs\n- \u{1F4D6} **[Documentation](../)** - Browse full documentation'
+        content: 'Get ng-forge dynamic forms up and running in your Angular project.\n\n## Requirements\n\n- **Angular 21+** - ng-forge dynamic forms requires Angular 21 or higher for signal forms support\n- **TypeScript 5.6+** - For best type inference results\n\n## Installation\n\nInstall the core library and your preferred UI integration:\n\n```bash group="install" name="npm"\nnpm install @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="yarn"\nyarn add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n```bash group="install" name="pnpm"\npnpm add @ng-forge/dynamic-forms @ng-forge/dynamic-forms-material\n```\n\n> This installs the core `@ng-forge/dynamic-forms` package and the Material Design integration. See [UI Framework Options](#ui-framework-options) below for other choices.\n\n## Configure Your App\n\nAdd the dynamic form provider to your app configuration:\n\n```typescript name="app.config.ts"\nimport { ApplicationConfig } from \'@angular/core\';\nimport { provideDynamicForm } from \'@ng-forge/dynamic-forms\';\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideDynamicForm(...withMaterialFields()),\n    // ... other providers\n  ],\n};\n```\n\nThe `provideDynamicForm()` function registers field types and validators. The `withMaterialFields()` function provides all Material Design field components.\n\n## Create Your First Form\n\nCreate a simple login form to verify everything works:\n\n```typescript name="login.component.ts"\nimport { Component } from \'@angular/core\';\nimport { DynamicForm, type FormConfig } from \'@ng-forge/dynamic-forms\';\n\n@Component({\n  selector: \'app-login\',\n  imports: [DynamicForm],\n  template: `<form [dynamic-form]="config"></form>`,\n})\nexport class LoginComponent {\n  config = {\n    fields: [\n      {\n        key: \'email\',\n        type: \'input\',\n        value: \'\',\n        label: \'Email\',\n        required: true,\n        email: true,\n      },\n      {\n        key: \'password\',\n        type: \'input\',\n        value: \'\',\n        label: \'Password\',\n        required: true,\n        minLength: 8,\n        props: { type: \'password\' },\n      },\n      {\n        type: \'submit\',\n        key: \'submit\',\n        label: \'Sign In\',\n        props: { color: \'primary\' },\n      },\n    ],\n  } as const satisfies FormConfig;\n}\n```\n\nYou now have a working form with:\n\n- \u2705 Real-time validation with error messages\n- \u2705 TypeScript type inference\n- \u2705 Material Design styling\n- \u2705 Accessibility support\n- \u2705 Submit button auto-disables when invalid\n\n## UI Framework Options\n\nng-forge dynamic forms supports multiple UI frameworks. Install the integration package for your preferred framework:\n\n### Material Design (Preview)\n\n```bash group="install-material" name="npm"\nnpm install @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="yarn"\nyarn add @ng-forge/dynamic-forms-material\n```\n\n```bash group="install-material" name="pnpm"\npnpm add @ng-forge/dynamic-forms-material\n```\n\n```typescript\nimport { withMaterialFields } from \'@ng-forge/dynamic-forms-material\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withMaterialFields())],\n};\n```\n\nSee [Material Integration](../ui-libs-integrations/material) for full documentation.\n\n### PrimeNG (Preview)\n\n```bash group="install-primeng" name="npm"\nnpm install @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="yarn"\nyarn add @ng-forge/dynamic-forms-primeng\n```\n\n```bash group="install-primeng" name="pnpm"\npnpm add @ng-forge/dynamic-forms-primeng\n```\n\n```typescript\nimport { withPrimeNGFields } from \'@ng-forge/dynamic-forms-primeng\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withPrimeNGFields())],\n};\n```\n\nSee [PrimeNG Integration](../ui-libs-integrations/primeng) for full documentation.\n\n### Bootstrap (Preview)\n\n```bash group="install-bootstrap" name="npm"\nnpm install @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="yarn"\nyarn add @ng-forge/dynamic-forms-bootstrap\n```\n\n```bash group="install-bootstrap" name="pnpm"\npnpm add @ng-forge/dynamic-forms-bootstrap\n```\n\n```typescript\nimport { withBootstrapFields } from \'@ng-forge/dynamic-forms-bootstrap\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withBootstrapFields())],\n};\n```\n\nSee [Bootstrap Integration](../ui-libs-integrations/bootstrap) for full documentation.\n\n### Ionic (Preview)\n\n```bash group="install-ionic" name="npm"\nnpm install @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="yarn"\nyarn add @ng-forge/dynamic-forms-ionic\n```\n\n```bash group="install-ionic" name="pnpm"\npnpm add @ng-forge/dynamic-forms-ionic\n```\n\n```typescript\nimport { withIonicFields } from \'@ng-forge/dynamic-forms-ionic\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [provideDynamicForm(...withIonicFields())],\n};\n```\n\nSee [Ionic Integration](../ui-libs-integrations/ionic) for full documentation.\n\n### Custom UI Components\n\nYou can also build your own field components using any UI library or custom styling:\n\n```typescript\nimport { MyCustomInputComponent } from \'./my-custom-input.component\';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideDynamicForm([\n      { name: \'input\', loadComponent: () => MyCustomInputComponent },\n      // ... more custom field types\n    ]),\n  ],\n};\n```\n\nSee [Custom Integration Guide](../advanced/custom-integrations) for building custom field components.\n\n## Next Steps\n\nNow that you have ng-forge dynamic forms installed, explore the core features:\n\n### Learn Core Concepts\n\n- **[Field Types](../schema-fields/field-types)** - Understand all available field types (input, select, checkbox, group, etc.)\n- **[Validation](../validation/basics)** - Add validation rules with shorthand syntax or conditional validators\n- **[Conditional Logic](../dynamic-behavior/conditional-logic/overview)** - Show/hide fields based on other field values\n- **[Type Safety](../advanced/type-safety/basics)** - TypeScript type inference for forms\n\n### Build Advanced Forms\n\n- **[Multi-Step Forms](../prebuilt/form-pages)** - Create wizard-style forms with page navigation\n- **[Repeatable Sections](../prebuilt/form-arrays/simplified)** - Dynamic form arrays for adding/removing fields\n- **[Conditional Validation](../validation/advanced#conditional-validators)** - Validators that activate based on conditions\n\n### Customize and Extend\n\n- **[i18n Setup](../dynamic-behavior/i18n)** - Add multi-language support to your forms\n- **[Events](../advanced/events)** - Handle custom form events\n- **[Custom Fields](../advanced/custom-integrations)** - Create your own field types\n\n## Get Help\n\n- \u{1F4AC} **[GitHub Discussions](https://github.com/ng-forge/ng-forge/discussions)** - Ask questions and get help\n- \u{1F41B} **[Issue Tracker](https://github.com/ng-forge/ng-forge/issues)** - Report bugs\n- \u{1F4D6} **[Documentation](../)** - Browse full documentation'
       },
       {
-        id: "form-arrays",
-        title: "Form Arrays",
+        id: "form-arrays-complete",
+        title: "Form Arrays Complete",
         category: "prebuilt",
-        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## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Structure Overview\n\nThe `fields` property supports two item formats:\n\n- **Single FieldDef** (not wrapped in array) \u2192 **Primitive item** - extracts field value directly\n- **Array of FieldDefs** \u2192 **Object item** - merges fields into an object\n\n```typescript\n// Primitive array: ['angular', 'typescript']\n{\n  key: 'tags',\n  type: 'array',\n  fields: [\n    { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive\n    { key: 'tag', type: 'input', value: 'typescript' },\n  ]\n}\n\n// Object array: [{ name: 'Alice', email: '...' }]\n{\n  key: 'contacts',\n  type: 'array',\n  fields: [\n    [                                                      // Array of fields = object\n      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },\n      { key: 'email', type: 'input', label: 'Email', value: 'alice@example.com' }\n    ],\n  ]\n}\n```\n\n## Empty Arrays (No Initial Items)\n\nFor arrays that start empty and are populated via buttons:\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  fields: []  // No initial items - user adds via button\n}\n```\n\n## 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 dynamic add/remove:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { DynamicForm, EventBus, arrayEvent } 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  // Template for new tags - single field (primitive item)\n  private tagTemplate = {\n    key: 'tag',\n    type: 'input',\n    label: 'Tag',\n    value: '',\n    required: true,\n    minLength: 2,\n  };\n\n  formConfig = {\n    fields: [\n      {\n        key: 'tags',\n        type: 'array',\n        // Start with two initial tags (primitive items - not wrapped in arrays)\n        fields: [\n          { key: 'tag', type: 'input', label: 'Tag', value: 'featured', required: true, minLength: 2 },\n          { key: 'tag', type: 'input', label: 'Tag', value: 'popular', required: true, minLength: 2 },\n        ],\n      },\n    ],\n  };\n\n  // Form value: { tags: ['featured', 'popular'] }\n\n  addTag() {\n    this.eventBus.dispatch(arrayEvent('tags').append(this.tagTemplate));\n  }\n\n  removeTag(index: number) {\n    this.eventBus.dispatch(arrayEvent('tags').removeAt(index));\n  }\n}\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 and validation:\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { DynamicForm, EventBus, arrayEvent } 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  // Template for new contacts\n  private contactTemplate = [\n    { key: 'name', type: 'input', label: 'Contact Name', value: '', required: true, minLength: 2 },\n    { key: 'phone', type: 'input', label: 'Phone Number', value: '', required: true, pattern: /^\\d{10}$/ },\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  formConfig = {\n    fields: [\n      {\n        key: 'contacts',\n        type: 'array',\n        // Start with one pre-filled contact\n        fields: [\n          [\n            { key: 'name', type: 'input', label: 'Contact Name', value: 'John Doe', required: true, minLength: 2 },\n            { key: 'phone', type: 'input', label: 'Phone Number', value: '5551234567', required: true, pattern: /^\\d{10}$/ },\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        ],\n      },\n    ],\n  };\n\n  // Form value: { contacts: [{ name: 'John Doe', phone: '5551234567', relationship: 'family' }] }\n\n  addContact() {\n    this.eventBus.dispatch(arrayEvent('contacts').append(this.contactTemplate));\n  }\n\n  removeContact(index: number) {\n    this.eventBus.dispatch(arrayEvent('contacts').removeAt(index));\n  }\n}\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."
+        content: "Arrays create dynamic collections of field values. Each item in the `fields` array defines **one array item** with its structure and initial values.\n\n> For most use cases, the **simplified array API** is recommended. See [Form Arrays (Simplified)](/prebuilt/form-arrays/simplified) for details. This page documents the complete API for advanced use cases.\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/array\" class=\"example-frame\" title=\"Array Field Demo\"></iframe>\n\n## Structure Overview\n\nThe `fields` property supports two item formats:\n\n- **Single FieldDef** (not wrapped in array) \u2192 **Primitive item** - extracts field value directly\n- **Array of FieldDefs** \u2192 **Object item** - merges fields into an object\n\n```typescript\n// Primitive array: ['angular', 'typescript']\n{\n  key: 'tags',\n  type: 'array',\n  fields: [\n    { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive\n    { key: 'tag', type: 'input', value: 'typescript' },\n  ]\n}\n\n// Object array: [{ name: 'Alice', email: '...' }]\n{\n  key: 'contacts',\n  type: 'array',\n  fields: [\n    [                                                      // Array of fields = object\n      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },\n      { key: 'email', type: 'input', label: 'Email', value: 'alice@example.com' }\n    ],\n  ]\n}\n```\n\n## Empty Arrays (No Initial Items)\n\nFor arrays that start empty and are populated via buttons:\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  fields: []  // No initial items - user adds via button\n}\n```\n\n## Array Size Validation\n\nUse `minLength` and `maxLength` on the array field to constrain the number of items. When violated, the form becomes invalid (e.g. submit button is disabled), but no field-level error message is shown.\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  minLength: 1,  // At least 1 item required\n  maxLength: 5,  // No more than 5 items\n  fields: [\n    [{ key: 'tag', type: 'input', label: 'Tag', value: 'default' }]\n  ]\n}\n```\n\n| Property    | Type     | Description                   |\n| ----------- | -------- | ----------------------------- |\n| `minLength` | `number` | Minimum number of array items |\n| `maxLength` | `number` | Maximum number of array items |\n\nBoth properties are optional and can be used independently or together.\n\n## Initial Values\n\nInitial values are defined directly on each field via the `value` property - no separate `initialValue` is needed:\n\n```typescript\n{\n  key: 'emails',\n  type: 'array',\n  fields: [\n    // One initial item with pre-filled value (object item)\n    [\n      { key: 'email', type: 'input', label: 'Email', value: 'primary@example.com' }\n    ]\n  ]\n}\n```\n\n## Primitive Arrays (Simple Value Lists)\n\nFor simple arrays of primitive values like `['tag1', 'tag2']`, use a **single FieldDef per item** (not wrapped in an array):\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  fields: [\n    { key: 'tag', type: 'input', label: 'Tag', value: 'featured' },\n    { key: 'tag', type: 'input', label: 'Tag', value: 'popular' }\n  ]\n}\n```\n\nThis creates a true primitive array in the form value:\n\n```typescript\n{\n  tags: ['featured', 'popular'];\n}\n```\n\nThe `key` property on each field is used for internal tracking but doesn't affect the output value.\n\n## Object Arrays (Multiple Fields per Item)\n\nFor arrays of objects with multiple fields, wrap the fields in an **inner array**:\n\n```typescript\n{\n  key: 'contacts',\n  type: 'array',\n  fields: [\n    [\n      { key: 'name', type: 'input', label: 'Name', value: '' },\n      { key: 'phone', type: 'input', label: 'Phone', value: '' }\n    ]\n  ]\n}\n```\n\nThis creates an array of objects:\n\n```typescript\n{\n  contacts: [{ name: '', phone: '' }];\n}\n```\n\n## Nested Object Arrays (Using Groups)\n\nFor arrays with nested object structure, use a group field:\n\n```typescript\n{\n  key: 'contacts',\n  type: 'array',\n  fields: [\n    [\n      {\n        key: 'contact',\n        type: 'group',\n        fields: [\n          { key: 'name', type: 'input', label: 'Name', value: '' },\n          { key: 'phone', type: 'input', label: 'Phone', value: '' }\n        ]\n      }\n    ]\n  ]\n}\n```\n\nThis creates an array of nested objects (note the group key creates the nesting):\n\n```typescript\n{\n  contacts: [{ contact: { name: '', phone: '' } }];\n}\n```\n\n## Heterogeneous Arrays (Mixed Primitives and Objects)\n\nArrays can contain both primitive and object items in the same array:\n\n```typescript\n{\n  key: 'items',\n  type: 'array',\n  fields: [\n    [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item (wrapped in array)\n    { key: 'value', type: 'input', value: 'Simple' },        // Primitive item (single field)\n  ]\n}\n```\n\nThis creates a heterogeneous array:\n\n```typescript\n{\n  items: [{ label: 'Structured' }, 'Simple'];\n}\n```\n\n## Array vs Group\n\n- **Groups** create nested objects with keys: `{ address: { street: '', city: '' } }`\n- **Primitive Arrays** create lists of values: `{ tags: ['value1', 'value2'] }`\n- **Object Arrays** create lists of objects: `{ items: [{name: ''}, {name: ''}] }`\n\n## Dynamic Add/Remove\n\n### Declarative Approach (Recommended)\n\nUse button field types directly in your form configuration for declarative array manipulation:\n\n| Button Type        | Placement        | Description                                      |\n| ------------------ | ---------------- | ------------------------------------------------ |\n| `addArrayItem`     | Outside array    | Appends a new item to the end of the array       |\n| `prependArrayItem` | Outside array    | Inserts a new item at the beginning of the array |\n| `insertArrayItem`  | Outside array    | Inserts a new item at a specific index           |\n| `removeArrayItem`  | Inside each item | Removes the current item from the array          |\n| `popArrayItem`     | Outside array    | Removes the last item from the array             |\n| `shiftArrayItem`   | Outside array    | Removes the first item from the array            |\n\n**Important:** Add/prepend/insert buttons **require** a `template` property defining the new item structure. There is no fallback to the array's `fields[0]` - each button must explicitly define what structure to add.\n\nThe `template` can be:\n\n- **Single FieldDef** - creates a primitive item (field value is extracted directly)\n- **Array of FieldDefs** - creates an object item (fields merged into object)\n\n```typescript\n// Template for PRIMITIVE items (single field, not wrapped)\nconst tagTemplate = { key: 'tag', type: 'input', label: 'Tag' };\n\n// Template for OBJECT items (array of fields)\nconst contactTemplate = [\n  { key: 'name', type: 'input', label: 'Name' },\n  { key: 'phone', type: 'input', label: 'Phone' },\n  // Remove button inside each item (no template needed)\n  { key: 'remove', type: 'removeArrayItem', label: 'Remove' },\n];\n\n// Form configuration\n{\n  fields: [\n    {\n      key: 'tags',\n      type: 'array',\n      fields: [], // Start empty - primitive array\n    },\n    // Add button for primitive items\n    {\n      key: 'addTag',\n      type: 'addArrayItem',\n      label: 'Add Tag',\n      arrayKey: 'tags',\n      template: tagTemplate, // Single field = primitive item\n    },\n    {\n      key: 'contacts',\n      type: 'array',\n      fields: [], // Start empty - object array\n    },\n    // Add button for object items\n    {\n      key: 'addContact',\n      type: 'addArrayItem',\n      label: 'Add Contact',\n      arrayKey: 'contacts',\n      template: contactTemplate, // Array of fields = object item\n    },\n  ];\n}\n```\n\n### Programmatic Approach\n\nFor more control, use the event bus with the `arrayEvent` builder. **Note:** When using the programmatic approach, you must provide a template:\n\n```typescript\nimport { EventBus, arrayEvent } from '@ng-forge/dynamic-forms';\n\n// Inject the event bus\neventBus = inject(EventBus);\n\n// Template for PRIMITIVE items (single field, not wrapped)\ntagTemplate = { key: 'tag', type: 'input', label: 'Tag', value: '' };\n\n// Template for OBJECT items (array of fields)\ncontactTemplate = [\n  { key: 'name', type: 'input', label: 'Name', value: '' },\n  { key: 'phone', type: 'input', label: 'Phone', value: '' }\n];\n\n// Add PRIMITIVE item to end of array\naddTag() {\n  this.eventBus.dispatch(arrayEvent('tags').append(this.tagTemplate));\n}\n\n// Add OBJECT item to end of array\naddContact() {\n  this.eventBus.dispatch(arrayEvent('contacts').append(this.contactTemplate));\n}\n\n// Add item to beginning of array\nprependItem() {\n  this.eventBus.dispatch(arrayEvent('contacts').prepend(this.contactTemplate));\n}\n\n// Add item at specific index\naddItemAt(index: number) {\n  this.eventBus.dispatch(arrayEvent('contacts').insertAt(index, this.contactTemplate));\n}\n\n// Remove last item (no template needed)\nremoveLastItem() {\n  this.eventBus.dispatch(arrayEvent('contacts').pop());\n}\n\n// Remove first item (no template needed)\nremoveFirstItem() {\n  this.eventBus.dispatch(arrayEvent('contacts').shift());\n}\n\n// Remove item at specific index (no template needed)\nremoveItemAt(index: number) {\n  this.eventBus.dispatch(arrayEvent('contacts').removeAt(index));\n}\n```\n\n## Use Cases\n\nArrays are ideal for:\n\n- Lists of simple values (tags, categories, keywords)\n- Repeating form sections (multiple addresses, phone numbers)\n- Dynamic collections where items can be added/removed\n- Collection-based data structures where order matters\n\n## Complete Example: Primitive Array with Initial Values\n\nHere's a complete working example of a primitive array field (simple value list) with initial values and declarative add/remove buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new tags - a row with an input and a remove button\nconst tagTemplate = {\n  key: 'tag',\n  type: 'row',\n  fields: [\n    {\n      key: 'value',\n      type: 'input',\n      label: 'Tag',\n      required: true,\n      minLength: 2,\n    },\n    {\n      key: 'removeTag',\n      type: 'removeArrayItem',\n      label: 'Remove',\n      props: { color: 'warn' },\n    },\n  ],\n} as const;\n\nconst formConfig = {\n  fields: [\n    {\n      key: 'tags',\n      type: 'array',\n      // Start with two initial tags using the same row structure\n      fields: [\n        [\n          {\n            key: 'tag',\n            type: 'row',\n            fields: [\n              { key: 'value', type: 'input', label: 'Tag', value: 'featured', required: true, minLength: 2 },\n              { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n            ],\n          },\n        ],\n        [\n          {\n            key: 'tag',\n            type: 'row',\n            fields: [\n              { key: 'value', type: 'input', label: 'Tag', value: 'popular', required: true, minLength: 2 },\n              { key: 'removeTag', type: 'removeArrayItem', label: 'Remove', props: { color: 'warn' } },\n            ],\n          },\n        ],\n      ],\n    },\n    // Declarative add button - no EventBus needed\n    {\n      key: 'addTag',\n      type: 'addArrayItem',\n      label: 'Add Tag',\n      arrayKey: 'tags',\n      template: [tagTemplate],\n      props: { color: 'primary' },\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Form value: { tags: [{ tag: { value: 'featured' } }, { tag: { value: 'popular' } }] }\n```\n\n## Complete Example: Object Array with Initial Values\n\nHere's a complete working example of an object array field with initial values, validation, and declarative buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\n// Template for new contacts - includes a remove button inside each item\nconst contactTemplate = [\n  { key: 'name', type: 'input', label: 'Contact Name', required: true, minLength: 2 },\n  { key: 'phone', type: 'input', label: 'Phone Number', required: true, pattern: /^\\d{10}$/ },\n  {\n    key: 'relationship',\n    type: 'select',\n    label: 'Relationship',\n    options: [\n      { label: 'Family', value: 'family' },\n      { label: 'Friend', value: 'friend' },\n      { label: 'Colleague', value: 'colleague' },\n    ],\n  },\n  {\n    key: 'removeContact',\n    type: 'removeArrayItem',\n    label: 'Remove Contact',\n    props: { color: 'warn' },\n  },\n] as const;\n\nconst formConfig = {\n  fields: [\n    {\n      key: 'contacts',\n      type: 'array',\n      // Start with one pre-filled contact (includes remove button)\n      fields: [\n        [\n          { key: 'name', type: 'input', label: 'Contact Name', value: 'John Doe', required: true, minLength: 2 },\n          {\n            key: 'phone',\n            type: 'input',\n            label: 'Phone Number',\n            value: '5551234567',\n            required: true,\n            pattern: /^\\d{10}$/,\n          },\n          {\n            key: 'relationship',\n            type: 'select',\n            label: 'Relationship',\n            value: 'family',\n            options: [\n              { label: 'Family', value: 'family' },\n              { label: 'Friend', value: 'friend' },\n              { label: 'Colleague', value: 'colleague' },\n            ],\n          },\n          {\n            key: 'removeContact',\n            type: 'removeArrayItem',\n            label: 'Remove Contact',\n            props: { color: 'warn' },\n          },\n        ],\n      ],\n    },\n    // Declarative add button - no EventBus needed\n    {\n      key: 'addContact',\n      type: 'addArrayItem',\n      label: 'Add Contact',\n      arrayKey: 'contacts',\n      template: contactTemplate,\n      props: { color: 'primary' },\n    },\n  ],\n} as const satisfies FormConfig;\n\n// Form value: { contacts: [{ name: 'John Doe', phone: '5551234567', relationship: 'family' }] }\n```\n\n## Template Requirement\n\n**Important:** When adding items dynamically (via buttons or event bus), you must always provide an explicit `template`. There is no automatic fallback to use the first item's structure.\n\nThis design ensures:\n\n- Clear intent - each add operation explicitly defines what to add\n- Flexibility - different buttons can add different item structures\n- No ambiguity - the array's `fields` only defines initial items, not a \"default template\"\n\n## Heterogeneous Items\n\nArrays can have items with different field structures:\n\n```typescript\n{\n  key: 'entries',\n  type: 'array',\n  fields: [\n    // Item 0: Simple tag\n    [{ key: 'tag', type: 'input', label: 'Tag', value: 'simple' }],\n    // Item 1: Contact with more fields\n    [\n      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },\n      { key: 'email', type: 'input', label: 'Email', value: 'alice@example.com' }\n    ]\n  ]\n}\n```\n\nThis flexibility allows each item to have its own structure, though typically all items share the same structure for consistency.\n\n## Nesting Constraints\n\nArray fields can be used within:\n\n- Pages (top-level container)\n- Rows (for horizontal layouts)\n- Groups (for nested arrays within objects)\n\nArrays **cannot** contain:\n\n- Other array fields (no nested arrays)\n- Page fields\n\n## Allowed Children\n\nArrays can contain these field types:\n\n- Leaf fields (input, select, checkbox, etc.) -> creates flat or object arrays\n- Group fields with key -> creates nested object arrays `[{groupKey: {...}}, ...]`\n- Row fields -> creates flat object arrays `[{...}, {...}]` (rows don't add nesting)\n- Button fields (for remove operations inside each item)\n\nSee [Type Safety & Inference](../advanced/type-safety/basics) for details on how arrays affect type inference.\n\n## Conditional Visibility\n\nArray containers support the `logic` property to conditionally show or hide the entire array section based on form state.\n\n```typescript\n{\n  key: 'dependents',\n  type: 'array',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'hasDependents',\n      operator: 'equals',\n      value: false,\n    },\n  }],\n  fields: [/* ... */],\n}\n```\n\nWhen the array is hidden, all items and add/remove buttons are hidden with it. Only `'hidden'` is supported as a logic type on containers.\n\nFor all available condition types and operators, see [Conditional Logic](../../../dynamic-behavior/conditional-logic/overview/).\n\n## When to Use the Complete API\n\nThe complete API documented on this page is the right choice when you need capabilities beyond what the simplified API offers:\n\n- **Heterogeneous items** -- Different field structures per item (e.g. some items have 2 fields, others have 5)\n- **Custom button placement** -- Positioning add/remove/prepend/insert buttons in specific locations relative to the array\n- **Programmatic control via EventBus** -- Dispatching `arrayEvent` commands for append, prepend, insertAt, pop, shift, and removeAt operations from component code\n- **Custom templates per button action** -- Different add buttons that each insert a different item structure (e.g. an \"Add Simple\" and an \"Add Detailed\" button)\n- **Mixed primitive and object items** -- Arrays containing both primitive values and object values in the same collection\n\nFor all other scenarios, the [simplified array API](/prebuilt/form-arrays/simplified) provides a more concise configuration with auto-generated buttons."
+      },
+      {
+        id: "form-arrays-simplified",
+        title: "Form Arrays Simplified",
+        category: "prebuilt",
+        content: "The simplified array API provides a concise way to define dynamic arrays. Instead of manually specifying each item in `fields`, you provide a `template` for the item structure and a `value` array with initial data. Add and remove buttons are generated automatically.\n\n> **When should I use this?** For most array use cases -- primitive lists, object lists, and standard add/remove workflows -- the simplified API is the right choice. For advanced scenarios like heterogeneous items or custom button placement, see [Form Arrays (Complete)](/prebuilt/form-arrays/complete).\n\n## Interactive Demo\n\n<iframe src=\"http://localhost:4201/#/examples/simplified-array\" class=\"example-frame\" title=\"Simplified Array Demo\"></iframe>\n\n## Overview\n\nThe simplified API uses two key properties:\n\n| Property    | Description                                                                |\n| ----------- | -------------------------------------------------------------------------- |\n| `template`  | Defines the structure of a single array item (single field or field array) |\n| `value`     | Initial data array -- each element creates one pre-filled item             |\n| `minLength` | Minimum number of array items (form invalid if fewer)                      |\n| `maxLength` | Maximum number of array items (form invalid if more)                       |\n\nThe `template` shape determines the array variant:\n\n- **Single field** (`template: { ... }`) -- primitive array (e.g. `['tag1', 'tag2']`)\n- **Array of fields** (`template: [{ ... }, { ... }]`) -- object array (e.g. `[{ name: 'Jane', phone: '555' }]`)\n\n```typescript\n// Discriminant: template is a single field \u2192 primitive array\n{ key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' } }\n\n// Discriminant: template is an array of fields \u2192 object array\n{ key: 'contacts', type: 'array', template: [\n  { key: 'name', type: 'input', label: 'Name' },\n  { key: 'phone', type: 'input', label: 'Phone' },\n] }\n```\n\n## Primitive Arrays\n\nFor simple arrays of scalar values like `['angular', 'typescript']`, provide a single field as the `template` and a flat array as the `value`:\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag', required: true },\n  value: ['angular', 'typescript'],\n}\n```\n\nThis renders two input fields pre-filled with `'angular'` and `'typescript'`, each with an auto-generated **Remove** button. An **Add** button is placed after the array.\n\nForm value output:\n\n```typescript\n{\n  tags: ['angular', 'typescript'];\n}\n```\n\n## Object Arrays\n\nFor arrays of objects like `[{ name: 'Jane', phone: '555' }]`, provide an array of fields as the `template` and an array of objects as the `value`:\n\n```typescript\n{\n  key: 'contacts',\n  type: 'array',\n  template: [\n    { key: 'name', type: 'input', label: 'Contact Name', required: true },\n    { key: 'phone', type: 'input', label: 'Phone Number' },\n  ],\n  value: [\n    { name: 'Jane', phone: '555-1234' },\n    { name: 'Bob', phone: '555-5678' },\n  ],\n}\n```\n\nEach value object is matched to the template by key. If a value object omits a key, the corresponding field renders without an initial value.\n\nForm value output:\n\n```typescript\n{\n  contacts: [\n    { name: 'Jane', phone: '555-1234' },\n    { name: 'Bob', phone: '555-5678' },\n  ];\n}\n```\n\n## Empty Arrays\n\nOmit `value` or set `value: []` to start with an empty array. Users populate it via the auto-generated **Add** button:\n\n```typescript\n// No value property \u2014 starts empty\n{\n  key: 'tags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag' },\n}\n\n// Explicit empty array \u2014 same behavior\n{\n  key: 'emails',\n  type: 'array',\n  template: [\n    { key: 'address', type: 'input', label: 'Email Address', required: true },\n    { key: 'label', type: 'select', label: 'Type', options: [\n      { label: 'Work', value: 'work' },\n      { label: 'Personal', value: 'personal' },\n    ] },\n  ],\n  value: [],\n}\n```\n\n## Button Customization\n\nBy default, the library generates an **Add** button (label: `\"Add\"`) after the array and a **Remove** button (label: `\"Remove\"`) inside each item. You can customize both via `addButton` and `removeButton`:\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag' },\n  value: ['angular'],\n  addButton: { label: 'Add Tag', props: { color: 'primary' } },\n  removeButton: { label: 'Delete', props: { color: 'warn' } },\n}\n```\n\n### Button Config Properties\n\n| Property | Type                      | Description                                          |\n| -------- | ------------------------- | ---------------------------------------------------- |\n| `label`  | `string`                  | Custom label text for the button                     |\n| `props`  | `Record<string, unknown>` | Additional properties passed to the button component |\n\n## Button Opt-Out\n\nSet `addButton: false` or `removeButton: false` to suppress the corresponding auto-generated button entirely:\n\n```typescript\n// No add button \u2014 items are only removable, not addable\n{\n  key: 'defaultTags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag' },\n  value: ['featured', 'popular'],\n  addButton: false,\n}\n\n// No remove button \u2014 items are only addable, not removable\n{\n  key: 'skills',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Skill' },\n  value: ['TypeScript'],\n  removeButton: false,\n}\n\n// No buttons at all \u2014 static list rendered from initial values\n{\n  key: 'readonlyItems',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Item' },\n  value: ['A', 'B', 'C'],\n  addButton: false,\n  removeButton: false,\n}\n```\n\nWhen `removeButton: false` is set for a primitive array, each item renders as a plain field without being wrapped in a row. When set for an object array, the remove button is simply omitted from the item's field list.\n\n## Complete Example: Primitive Array\n\nA full working configuration for a tag list with custom buttons:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig: FormConfig = {\n  fields: [\n    {\n      key: 'projectName',\n      type: 'input',\n      label: 'Project Name',\n      required: true,\n    },\n    {\n      key: 'tags',\n      type: 'array',\n      template: { key: 'value', type: 'input', label: 'Tag', required: true, minLength: 2 },\n      value: ['angular', 'open-source'],\n      addButton: { label: 'Add Tag' },\n      removeButton: { label: 'Remove Tag' },\n    },\n  ],\n};\n\n// Form value:\n// {\n//   projectName: 'My Project',\n//   tags: ['angular', 'open-source']\n// }\n```\n\n## Complete Example: Object Array\n\nA full working configuration for a contact list:\n\n```typescript\nimport { FormConfig } from '@ng-forge/dynamic-forms';\n\nconst formConfig: FormConfig = {\n  fields: [\n    {\n      key: 'teamName',\n      type: 'input',\n      label: 'Team Name',\n      required: true,\n    },\n    {\n      key: 'members',\n      type: 'array',\n      template: [\n        { key: 'name', type: 'input', label: 'Full Name', required: true },\n        { key: 'email', type: 'input', label: 'Email', required: true },\n        {\n          key: 'role',\n          type: 'select',\n          label: 'Role',\n          options: [\n            { label: 'Developer', value: 'dev' },\n            { label: 'Designer', value: 'design' },\n            { label: 'Manager', value: 'manager' },\n          ],\n        },\n      ],\n      value: [\n        { name: 'Alice', email: 'alice@example.com', role: 'dev' },\n        { name: 'Bob', email: 'bob@example.com', role: 'design' },\n      ],\n      addButton: { label: 'Add Member' },\n      removeButton: { label: 'Remove' },\n    },\n  ],\n};\n\n// Form value:\n// {\n//   teamName: 'Frontend Team',\n//   members: [\n//     { name: 'Alice', email: 'alice@example.com', role: 'dev' },\n//     { name: 'Bob', email: 'bob@example.com', role: 'design' },\n//   ]\n// }\n```\n\n## Form Value Output\n\nThe simplified API produces the same form values as the complete API:\n\n| Template Shape  | Value Shape           | Output                                           |\n| --------------- | --------------------- | ------------------------------------------------ |\n| Single field    | Flat array of scalars | `{ tags: ['angular', 'typescript'] }`            |\n| Array of fields | Array of objects      | `{ contacts: [{ name: 'Jane', phone: '555' }] }` |\n| Any template    | `[]` or omitted       | `{ items: [] }`                                  |\n\n## Array Size Validation\n\nUse `minLength` and `maxLength` to constrain the number of items. When violated, the form becomes invalid (e.g. submit button is disabled).\n\n```typescript\n{\n  key: 'tags',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Tag' },\n  value: ['angular'],\n  minLength: 1,\n  maxLength: 5,\n}\n```\n\nBoth properties are optional and can be used independently or together.\n\n## Conditional Visibility\n\nSimplified arrays support `logic` for conditional visibility, just like the complete API:\n\n```typescript\n{\n  key: 'extras',\n  type: 'array',\n  template: { key: 'value', type: 'input', label: 'Extra' },\n  value: [],\n  logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showExtras', operator: 'equals', value: false } }],\n}\n```\n\n## Decision Guide: Simplified vs Complete API\n\n| Scenario                                        | Recommended API |\n| ----------------------------------------------- | --------------- |\n| Uniform items with standard add/remove          | **Simplified**  |\n| Pre-filled values from a data source            | **Simplified**  |\n| Custom button labels or styling                 | **Simplified**  |\n| Empty array populated by users                  | **Simplified**  |\n| Static list (no add/remove buttons)             | **Simplified**  |\n| Heterogeneous items (different fields per item) | Complete        |\n| Custom button placement (buttons outside array) | Complete        |\n| Programmatic control via EventBus               | Complete        |\n| Multiple add buttons (append, prepend, insert)  | Complete        |\n| Nested arrays inside item templates             | Complete        |\n\nAs a rule of thumb: **start with the simplified API**. If you hit a limitation, switch to the [complete API](/prebuilt/form-arrays/complete)."
       },
       {
         id: "form-groups",
         title: "Form Groups",
         category: "prebuilt",
-        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."
+        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/)."
       },
       {
         id: "form-pages",
         title: "Form Pages",
         category: "prebuilt",
-        content: "Create multi-step forms by using page fields. When your form contains page fields, it automatically enters \"paged mode\" and renders with navigation controls.\n\n## Basic Multi-Step Form\n\nCreate a multi-step form by adding multiple page fields to your form configuration:\n\n```typescript\n{\n  fields: [\n    {\n      key: 'account',\n      type: 'page',\n      fields: [\n        { key: 'accountTitle', type: 'text', label: 'Account Information', props: { elementType: 'h3' } },\n        { key: 'username', type: 'input', label: 'Username', value: '', required: true },\n        { key: 'password', type: 'input', label: 'Password', value: '', props: { type: 'password' }, required: true },\n      ],\n    },\n    {\n      key: 'profile',\n      type: 'page',\n      fields: [\n        { key: 'profileTitle', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n        { key: 'firstName', type: 'input', label: 'First Name', value: '' },\n        { key: 'lastName', type: 'input', label: 'Last Name', value: '' },\n      ],\n    },\n  ],\n}\n```\n\n## Page Properties\n\nEach page field supports:\n\n- `key` (required) - Unique identifier for the page\n- `type: 'page'` (required) - Field type identifier\n- `fields` (required) - Array of child fields to render on this page\n\n## Page with Description\n\n```typescript\n{\n  key: 'preferences',\n  type: 'page',\n  fields: [\n    { key: 'newsletter', type: 'checkbox', label: 'Subscribe to newsletter', value: false },\n    { key: 'notifications', type: 'checkbox', label: 'Enable notifications', value: false },\n  ],\n}\n```\n\n## Paged Mode Behavior\n\nWhen your form contains page fields:\n\n- **Automatic Detection**: Form automatically enters \"paged mode\"\n- **Navigation Controls**: Previous/Next buttons are rendered automatically\n- **Validation**: Users must complete required fields before advancing to the next page\n- **Single Page View**: Only one page is visible at a time\n\n## Performance & Lazy Loading\n\nng-forge uses Angular's `@defer` blocks with smart prefetching to optimize page rendering while maintaining flicker-free navigation.\n\n### How It Works\n\nThe page orchestrator uses a **2-tier loading strategy**:\n\n**Tier 1: Current + Adjacent Pages (\xB11)**\n\n- Render immediately using `@defer (on immediate)`\n- Initially, only 3 pages load (current + 2 adjacent)\n- Adjacent pages are fully rendered but hidden with `display: none`\n- Ensures zero flicker when navigating forward/backward\n\n**Tier 2: Distant Pages (2+ steps away)**\n\n- Defer loading until browser is idle using `@defer (on idle)`\n- Lazy loading optimizes initial page load\n- Load automatically during browser idle time\n- Once loaded, pages remain in DOM (hidden with CSS)\n\n### Benefits\n\n```typescript\n// Example: User is on step 2 of 5\nfields: [\n  { key: 'step1', type: 'page', ... }, // \u2713 Rendered (adjacent)\n  { key: 'step2', type: 'page', ... }, // \u2713 Visible (current)\n  { key: 'step3', type: 'page', ... }, // \u2713 Rendered (adjacent)\n  { key: 'step4', type: 'page', ... }, // \u23F3 Deferred (distant)\n  { key: 'step5', type: 'page', ... }, // \u23F3 Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- \u26A1 **Zero navigation flicker** - Adjacent pages already rendered\n- \u{1F680} **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- \u23F1\uFE0F **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- \u{1F4F1} **Mobile-friendly** - Lower startup cost on slower devices\n\n**Note:** Once loaded, pages remain in the DOM (hidden with CSS). The primary benefit is optimizing **initial load performance**, not ongoing memory usage.\n\nThis optimization happens automatically - no configuration needed.\n\n## Value Structure\n\nPages are container fields - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with pages\n{\n  fields: [\n    {\n      key: 'page1',\n      type: 'page',\n      fields: [\n        { key: 'firstName', type: 'input', value: '' },\n      ],\n    },\n    {\n      key: 'page2',\n      type: 'page',\n      fields: [\n        { key: 'lastName', type: 'input', value: '' },\n      ],\n    },\n  ],\n}\n\n// Resulting form value (flat structure)\n{\n  firstName: 'John',\n  lastName: 'Doe',\n  // Note: page keys are NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nPage fields can only be used at the top level of your form configuration. They **cannot** be nested inside:\n\n- Other page fields\n- Row fields\n- Group fields\n\nAttempting to nest pages will result in a validation error.\n\n## Allowed Children\n\nPages can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts)\n- Group fields (for nested data structures)\n\n## CSS Classes\n\nPage fields use these classes for styling:\n\n- `.df-page` - Applied to the page container\n- `.df-page-visible` - Applied to the currently visible page\n- `.df-page-hidden` - Applied to hidden pages\n- `.df-page-field` - Applied to the page field component"
+        content: "Create multi-step forms by using page fields. When your form contains page fields, it automatically enters \"paged mode\" and renders with navigation controls.\n\n## Basic Multi-Step Form\n\nCreate a multi-step form by adding multiple page fields to your form configuration:\n\n```typescript\n{\n  fields: [\n    {\n      key: 'account',\n      type: 'page',\n      fields: [\n        { key: 'accountTitle', type: 'text', label: 'Account Information', props: { elementType: 'h3' } },\n        { key: 'username', type: 'input', label: 'Username', value: '', required: true },\n        { key: 'password', type: 'input', label: 'Password', value: '', props: { type: 'password' }, required: true },\n      ],\n    },\n    {\n      key: 'profile',\n      type: 'page',\n      fields: [\n        { key: 'profileTitle', type: 'text', label: 'Profile Details', props: { elementType: 'h3' } },\n        { key: 'firstName', type: 'input', label: 'First Name', value: '' },\n        { key: 'lastName', type: 'input', label: 'Last Name', value: '' },\n      ],\n    },\n  ],\n}\n```\n\n## Page Properties\n\nEach page field supports:\n\n- `key` (required) - Unique identifier for the page\n- `type: 'page'` (required) - Field type identifier\n- `fields` (required) - Array of child fields to render on this page\n\n## Page with Description\n\n```typescript\n{\n  key: 'preferences',\n  type: 'page',\n  fields: [\n    { key: 'newsletter', type: 'checkbox', label: 'Subscribe to newsletter', value: false },\n    { key: 'notifications', type: 'checkbox', label: 'Enable notifications', value: false },\n  ],\n}\n```\n\n## Paged Mode Behavior\n\nWhen your form contains page fields:\n\n- **Automatic Detection**: Form automatically enters \"paged mode\"\n- **Navigation Controls**: Previous/Next buttons are rendered automatically\n- **Validation**: Users must complete required fields before advancing to the next page\n- **Single Page View**: Only one page is visible at a time\n\n## Performance & Lazy Loading\n\nng-forge uses Angular's `@defer` blocks with smart prefetching to optimize page rendering while maintaining flicker-free navigation.\n\n### How It Works\n\nThe page orchestrator uses a **2-tier loading strategy**:\n\n**Tier 1: Current + Adjacent Pages (\xB11)**\n\n- Render immediately using `@defer (on immediate)`\n- Initially, only 3 pages load (current + 2 adjacent)\n- Adjacent pages are fully rendered but hidden with `display: none`\n- Ensures zero flicker when navigating forward/backward\n\n**Tier 2: Distant Pages (2+ steps away)**\n\n- Defer loading until browser is idle using `@defer (on idle)`\n- Lazy loading optimizes initial page load\n- Load automatically during browser idle time\n- Once loaded, pages remain in DOM (hidden with CSS)\n\n### Benefits\n\n```typescript\n// Example: User is on step 2 of 5\nfields: [\n  { key: 'step1', type: 'page', ... }, // \u2713 Rendered (adjacent)\n  { key: 'step2', type: 'page', ... }, // \u2713 Visible (current)\n  { key: 'step3', type: 'page', ... }, // \u2713 Rendered (adjacent)\n  { key: 'step4', type: 'page', ... }, // \u23F3 Deferred (distant)\n  { key: 'step5', type: 'page', ... }, // \u23F3 Deferred (distant)\n]\n```\n\n**Performance advantages:**\n\n- \u26A1 **Zero navigation flicker** - Adjacent pages already rendered\n- \u{1F680} **Faster initial load** - Only 3 pages render immediately, distant pages defer until idle\n- \u23F1\uFE0F **Better Time to Interactive (TTI)** - Reduced initial JavaScript parsing/compilation\n- \u{1F4F1} **Mobile-friendly** - Lower startup cost on slower devices\n\n**Note:** Once loaded, pages remain in the DOM (hidden with CSS). The primary benefit is optimizing **initial load performance**, not ongoing memory usage.\n\nThis optimization happens automatically - no configuration needed.\n\n## Value Structure\n\nPages are container fields - they don't add nesting to your form values. Fields flatten to the root level:\n\n```typescript\n// Form config with pages\n{\n  fields: [\n    {\n      key: 'page1',\n      type: 'page',\n      fields: [\n        { key: 'firstName', type: 'input', value: '' },\n      ],\n    },\n    {\n      key: 'page2',\n      type: 'page',\n      fields: [\n        { key: 'lastName', type: 'input', value: '' },\n      ],\n    },\n  ],\n}\n\n// Resulting form value (flat structure)\n{\n  firstName: 'John',\n  lastName: 'Doe',\n  // Note: page keys are NOT in the value\n}\n```\n\n## Nesting Restrictions\n\nPage fields can only be used at the top level of your form configuration. They **cannot** be nested inside:\n\n- Other page fields\n- Row fields\n- Group fields\n\nAttempting to nest pages will result in a validation error.\n\n## Allowed Children\n\nPages can contain:\n\n- Leaf fields (input, select, checkbox, etc.)\n- Row fields (for horizontal layouts)\n- Group fields (for nested data structures)\n\n## Conditional Visibility\n\nPages support the `logic` property to conditionally skip a page (hide it from the page navigation and progression) based on form state.\n\n```typescript\n{\n  key: 'businessDetails',\n  type: 'page',\n  label: 'Business Details',\n  logic: [{\n    type: 'hidden',\n    condition: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'notEquals',\n      value: 'business',\n    },\n  }],\n  fields: [\n    { key: 'companyName', type: 'input', label: 'Company Name', value: '' },\n    { key: 'taxId', type: 'input', label: 'Tax ID', value: '' },\n  ],\n}\n```\n\nWhen a page is hidden, it is excluded from the multi-step navigation \u2014 users skip directly past it. Only `'hidden'` is supported as a logic type on containers.\n\nFor all available condition types and operators, see [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/).\n\n## CSS Classes\n\nPage fields use these classes for styling:\n\n- `.df-page` - Applied to the page container\n- `.df-page-visible` - Applied to the currently visible page\n- `.df-page-hidden` - Applied to hidden pages\n- `.df-page-field` - Applied to the page field component"
       },
       {
         id: "form-rows",
         title: "Form Rows",
         category: "prebuilt",
-        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)"
+        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/)."
       },
       {
         id: "hidden-fields",
         title: "Hidden Fields",
         category: "prebuilt",
-        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)"
+        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)"
       },
       {
         id: "text-components",
@@ -234,13 +264,13 @@ var require_docs = __commonJS({
         id: "validation-custom-validators",
         title: "Validation Custom Validators",
         category: "validation",
-        content: "Custom validation functions for complex validation logic that goes beyond built-in validators.\n\n## Overview\n\nng-forge supports three types of custom validators using Angular's Signal Forms API:\n\n1. **CustomValidator** - Synchronous validators with access to FieldContext\n2. **AsyncCustomValidator** - Async validators using Angular's resource API\n3. **HttpCustomValidator** - HTTP-specific validators with automatic request cancellation\n\n**Key Principle:** Validators should focus on validation logic, NOT presentation. Return only the error `kind` and configure messages at field level for proper i18n support.\n\n## Live Demo\n\nTry the interactive example below to see both expression-based and function-based validators in action:\n\n<iframe src=\"http://localhost:4201/#/examples/expression-validators\" class=\"example-frame\" title=\"Expression Validators Demo\"></iframe>\n\n## Message Resolution (STRICT)\n\nAll error messages MUST be explicitly configured. The framework enforces this strictly:\n\n1. **Field-level `validationMessages[kind]`** (highest priority - per-field customization)\n2. **Form-level `defaultValidationMessages[kind]`** (fallback for common messages)\n3. **No message configured = Console warning + error NOT displayed**\n\n**Important:** Validator-returned messages are NOT used as fallbacks. This enforces proper separation of concerns and i18n patterns.\n\nYou can define messages at the form level for common validation errors:\n\n```typescript\n{\n  defaultValidationMessages: {\n    noSpaces: 'Spaces are not allowed',\n    passwordMismatch: 'Passwords must match'\n  },\n  fields: [/* ... */]\n}\n```\n\n## Two Validator Patterns\n\nng-forge supports two patterns for custom validators:\n\n1. **Function-based** - Register reusable validator functions (best for complex logic, reusability)\n2. **Expression-based** - Inline JavaScript expressions (best for simple, one-off validations)\n\n## Expression-Based Validators\n\nFor simple validation logic, use inline JavaScript expressions without registering functions.\n\n### Basic Example\n\n```typescript\n{\n  key: 'confirmPassword',\n  type: 'input',\n  value: '',\n  validators: [{\n    type: 'custom',\n    expression: 'fieldValue === formValue.password',\n    kind: 'passwordMismatch',\n  }],\n  validationMessages: {\n    passwordMismatch: 'Passwords must match',\n  },\n}\n```\n\n**How it works:**\n\n- `fieldValue` - Current field's value\n- `formValue` - Entire form value object\n- Expression returns `true` = validation passes\n- Expression returns `false` = validation fails with the specified `kind`\n\n### Available Context\n\nExpression-based validators have access to:\n\n- **`fieldValue`** - Current field value\n- **`formValue`** - Complete form value object (e.g., `formValue.password`, `formValue.email`)\n- **`fieldPath`** - Current field path\n- Custom functions registered in `customFnConfig.customFunctions`\n\n### Safe Member Access\n\n**Built-in null/undefined handling**: Member access is safe by default - no manual null checks needed!\n\n```typescript\n// \u2705 Works safely even when nested values are null/undefined\n{\n  expression: 'fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n\n// \u274C Unnecessary - Don't do this\n{\n  expression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n\n// \u2705 Better - Safe by default\n{\n  expression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n```\n\nAccessing properties on `null` or `undefined` returns `undefined` instead of throwing errors, making expressions cleaner and more maintainable.\n\n### Common Expression Patterns\n\n**Password confirmation:**\n\n```typescript\n{\n  expression: 'fieldValue === formValue.password',\n  kind: 'passwordMismatch',\n}\n```\n\n**Date range validation:**\n\n```typescript\n{\n  expression: 'new Date(fieldValue) > new Date(formValue.startDate)',\n  kind: 'endDateBeforeStart',\n}\n```\n\n**Conditional required:**\n\n```typescript\n{\n  expression: 'formValue.requiresApproval ? fieldValue?.length > 0 : true',\n  kind: 'approvalRequired',\n}\n```\n\n**Numeric comparison:**\n\n```typescript\n{\n  expression: 'fieldValue >= formValue.minAge && fieldValue <= formValue.maxAge',\n  kind: 'ageOutOfRange',\n}\n```\n\n**Deeply nested field validation:**\n\n```typescript\n{\n  // Safe to access deeply nested properties\n  expression: 'fieldValue.toLowerCase() !== formValue.user.address.city.toLowerCase()',\n  kind: 'invalidAddress',\n}\n```\n\n### Security\n\nExpressions use **secure AST-based parsing** - no `eval()` or `new Function()`. Only safe JavaScript operations are allowed.\n\n## Function-Based Validators\n\nBest for validation that needs field value and access to other fields via FieldContext.\n\n### Basic Example\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\n// \u2705 RECOMMENDED: Return only kind\nconst noSpaces: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  if (typeof value === 'string' && value.includes(' ')) {\n    return { kind: 'noSpaces' }; // No hardcoded message\n  }\n  return null;\n};\n\n// Register and configure message\nconst config = {\n  fields: [\n    {\n      key: 'username',\n      type: 'input',\n      validators: [{ type: 'custom', functionName: 'noSpaces' }],\n      validationMessages: {\n        noSpaces: 'Spaces are not allowed', // Or Observable/Signal for i18n\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: {\n      noSpaces,\n    },\n  },\n};\n```\n\n### FieldContext API\n\nThe `FieldContext` API provides access to:\n\n- **`ctx.value()`** - Current field value (signal)\n- **`ctx.state`** - Field state (errors, touched, dirty, etc.)\n- **`ctx.valueOf(path)`** - Access other field values (PUBLIC API for cross-field validation)\n- **`ctx.stateOf(path)`** - Access other field states\n- **`ctx.field`** - Current field tree\n\n### Cross-Field Validation\n\nUse `ctx.valueOf()` to access other field values for comparison validators:\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\nconst greaterThanMin: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const minValue = ctx.valueOf('minAge');\n\n  if (minValue !== undefined && value <= minValue) {\n    return { kind: 'notGreaterThanMin' };\n  }\n  return null;\n};\n\n// Note: Custom validators return only 'kind'. Built-in validators (min, max, etc.)\n// automatically include params for interpolation (e.g., {{min}}, {{max}}, etc.)\nconst config = {\n  fields: [\n    { key: 'minAge', type: 'input', value: 0 },\n    {\n      key: 'maxAge',\n      type: 'input',\n      value: 0,\n      validators: [\n        {\n          type: 'custom',\n          functionName: 'greaterThanMin',\n        },\n      ],\n      validationMessages: {\n        notGreaterThanMin: 'Maximum age must be greater than minimum age',\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: { greaterThanMin },\n  },\n};\n```\n\n**Common Cross-Field Patterns:**\n\n- Password confirmation matching\n- Date range validation (start < end)\n- Numeric range validation (min < max)\n- Conditional required fields\n\n### Password Confirmation Example\n\n```typescript\nconst passwordMatch: CustomValidator = (ctx) => {\n  const confirmPassword = ctx.value();\n  const password = ctx.valueOf('password');\n\n  if (!confirmPassword || !password) {\n    return null; // Let required validator handle empty case\n  }\n\n  if (password !== confirmPassword) {\n    return { kind: 'passwordMismatch' };\n  }\n  return null;\n};\n\n// In field config:\n{\n  key: 'confirmPassword',\n  type: 'input',\n  validators: [{ type: 'custom', functionName: 'passwordMatch' }],\n  validationMessages: {\n    passwordMismatch: 'Passwords do not match'\n  }\n}\n```\n\n## Async Validators (Resource-based)\n\nAsync validators use Angular's resource API for database lookups or complex async operations.\n\n### Basic Example\n\n```typescript\nimport { AsyncCustomValidator } from '@ng-forge/dynamic-forms';\nimport { inject } from '@angular/core';\nimport { rxResource } from '@angular/core/rxjs-interop';\nimport { of } from 'rxjs';\nimport { UserService } from './user.service';\n\nconst checkUsernameAvailable: AsyncCustomValidator = {\n  // Extract params from field context\n  params: (ctx) => ({ username: ctx.value() }),\n\n  // Create resource with params signal\n  factory: (params) => {\n    const userService = inject(UserService);\n    return rxResource({\n      request: params,\n      loader: ({ request }) => {\n        if (!request?.username) return of(null);\n        return userService.checkAvailability(request.username);\n      },\n    });\n  },\n\n  // Map result to validation error\n  onSuccess: (result, ctx) => {\n    if (!result) return null;\n    return result.available ? null : { kind: 'usernameTaken' };\n  },\n\n  // Handle errors gracefully\n  onError: (error, ctx) => {\n    console.error('Availability check failed:', error);\n    return null; // Don't block form on network errors\n  },\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'username',\n      type: 'input',\n      validators: [{ type: 'customAsync', functionName: 'checkUsernameAvailable' }],\n      validationMessages: {\n        usernameTaken: 'This username is already taken',\n      },\n    },\n  ],\n  customFnConfig: {\n    asyncValidators: {\n      checkUsernameAvailable,\n    },\n  },\n};\n```\n\n**Key Benefits:**\n\n- Automatic loading states via resource API\n- Angular manages resource lifecycle\n- Reactive - refetches when params change\n- Integrates with Signal Forms validation state\n\n### Structure\n\n```typescript\ninterface AsyncCustomValidator<TValue, TParams, TResult> {\n  // Function that receives field context and returns resource params\n  readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;\n\n  // Function that creates a ResourceRef from the params signal\n  readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;\n\n  // Map successful resource result to validation errors\n  readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n  // Handle resource errors\n  readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n```\n\n## HTTP Validators\n\nHTTP validators provide optimized HTTP validation with automatic request cancellation.\n\n### Basic Example\n\n```typescript\nimport { HttpCustomValidator } from '@ng-forge/dynamic-forms';\n\nconst checkEmailDomain: HttpCustomValidator = {\n  // Build HTTP request from context\n  request: (ctx) => {\n    const email = ctx.value();\n    if (!email?.includes('@')) return undefined; // Skip if invalid\n\n    const domain = email.split('@')[1];\n    return {\n      url: `/api/validate-domain`,\n      method: 'POST',\n      body: { domain },\n      headers: { 'Content-Type': 'application/json' },\n    };\n  },\n\n  // NOTE: Inverted logic - onSuccess checks if response indicates INVALID\n  // We're validating, not fetching data!\n  onSuccess: (response, ctx) => {\n    // Assuming API returns { valid: boolean }\n    return response.valid ? null : { kind: 'invalidDomain' };\n  },\n\n  onError: (error, ctx) => {\n    console.error('Domain validation failed:', error);\n    return null; // Don't block form on network errors\n  },\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'email',\n      type: 'input',\n      validators: [{ type: 'customHttp', functionName: 'checkEmailDomain' }],\n      validationMessages: {\n        invalidDomain: 'This email domain is not allowed',\n      },\n    },\n  ],\n  customFnConfig: {\n    httpValidators: {\n      checkEmailDomain,\n    },\n  },\n};\n```\n\n**Key Benefits:**\n\n- Automatic request cancellation when field changes\n- Built-in debouncing via resource API\n- Prevents race conditions\n- Optimized for HTTP-specific validation\n\n**Important:** HTTP validators use \"inverted logic\" - `onSuccess` should return an error if validation fails, not if the HTTP request succeeds. You're checking validation status, not fetching data.\n\n### Structure\n\n```typescript\ninterface HttpCustomValidator<TValue, TResult> {\n  // Build HTTP request from field context\n  readonly request: (ctx: FieldContext<TValue>) => HttpResourceRequest | string | undefined;\n\n  // Map successful response to validation error\n  readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n  // Handle HTTP errors\n  readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n\ninterface HttpResourceRequest {\n  url: string;\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n  body?: any;\n  headers?: Record<string, string | string[]>;\n}\n```\n\n## Conditional Custom Validators\n\nApply validators conditionally using the `when` property with a `ConditionalExpression`:\n\n```typescript\nconst businessEmailValidator: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const domain = value?.split('@')[1];\n\n  const freeEmailDomains = ['gmail.com', 'yahoo.com', 'hotmail.com'];\n\n  if (domain && freeEmailDomains.includes(domain.toLowerCase())) {\n    return { kind: 'requireBusinessEmail' };\n  }\n  return null;\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'accountType',\n      type: 'select',\n      value: 'personal',\n      options: [\n        { value: 'personal', label: 'Personal' },\n        { value: 'business', label: 'Business' },\n      ],\n    },\n    {\n      key: 'email',\n      type: 'input',\n      validators: [\n        {\n          type: 'custom',\n          functionName: 'businessEmailValidator',\n          // Only apply when account type is \"business\"\n          when: {\n            type: 'fieldValue',\n            fieldPath: 'accountType',\n            operator: 'equals',\n            value: 'business',\n          },\n        },\n      ],\n      validationMessages: {\n        requireBusinessEmail: 'Please use a business email address',\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: { businessEmailValidator },\n  },\n};\n```\n\nThe validator is only active when the `when` condition evaluates to `true`, allowing dynamic validation based on form state. See [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/) for all expression types and operators.\n\n## Common Validation Patterns\n\n### Email Domain Validation\n\n```typescript\nconst emailDomainValidator: CustomValidator = (ctx) => {\n  const blockedDomains = ['tempmail.com', 'throwaway.email'];\n  const email = ctx.value();\n  const domain = email?.split('@')[1];\n\n  if (domain && blockedDomains.includes(domain)) {\n    return { kind: 'blockedDomain' };\n  }\n  return null;\n};\n```\n\n### Age Validation\n\n```typescript\nconst ageValidator: CustomValidator = (ctx) => {\n  const birthDate = ctx.value();\n  const age = calculateAge(birthDate);\n\n  if (age < 18) {\n    return { kind: 'tooYoung' };\n  }\n  return null;\n};\n```\n\n### Conditional Required\n\n```typescript\nconst conditionalRequiredValidator: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const employmentStatus = ctx.valueOf('employmentStatus');\n\n  // Company name required if employed\n  if (employmentStatus === 'employed' && !value) {\n    return { kind: 'required' };\n  }\n  return null;\n};\n```\n\n### Date Range Validation\n\n```typescript\nconst dateRangeValidator: CustomValidator = (ctx) => {\n  const endDate = ctx.value();\n  const startDate = ctx.valueOf('startDate');\n\n  if (startDate && endDate && startDate > endDate) {\n    return { kind: 'invalidDateRange' };\n  }\n  return null;\n};\n```\n\n## Multiple Errors\n\nValidators can return multiple errors for cross-field validation:\n\n```typescript\nconst validateDateRange: CustomValidator = (ctx) => {\n  const errors: ValidationError[] = [];\n\n  const startDate = ctx.valueOf('startDate');\n  const endDate = ctx.valueOf('endDate');\n\n  if (!startDate) errors.push({ kind: 'startDateRequired' });\n  if (!endDate) errors.push({ kind: 'endDateRequired' });\n  if (startDate && endDate && startDate > endDate) {\n    errors.push({ kind: 'invalidDateRange' });\n  }\n\n  return errors.length > 0 ? errors : null;\n};\n```\n\n## Validation Messages\n\n### Field-Level Messages\n\n```typescript\n{\n  key: 'username',\n  validators: [{ type: 'custom', functionName: 'noSpaces' }],\n  validationMessages: {\n    noSpaces: 'Spaces are not allowed'\n  }\n}\n```\n\n### Form-Level Default Messages\n\n```typescript\n{\n  defaultValidationMessages: {\n    noSpaces: 'Spaces are not allowed',\n    passwordMismatch: 'Passwords must match',\n    usernameTaken: 'This username is already taken'\n  },\n  fields: [/* ... */]\n}\n```\n\n### Dynamic Messages with i18n\n\n```typescript\nimport { inject } from '@angular/core';\nimport { TranslateService } from '@ngx-translate/core';\n\n{\n  key: 'username',\n  validators: [{ type: 'custom', functionName: 'noSpaces' }],\n  validationMessages: {\n    noSpaces: inject(TranslateService).get('VALIDATION.NO_SPACES')\n  }\n}\n```\n\n### Parameterized Messages\n\nMessages can interpolate params from ValidatorConfig using Angular template syntax (double curly braces around the param name).\n\n**Syntax:** To interpolate a param, wrap its name in double curly braces (same syntax as Angular templates).\n\n**Example:** To access `params.label`, write the param name `label` wrapped in double curly braces in your message string.\n\n```typescript\n{\n  validators: [\n    {\n      type: 'custom',\n      functionName: 'lessThanField',\n      params: { field: 'minAge', label: 'Minimum Age' }\n    }\n  ],\n  validationMessages: {\n    // Interpolate params.label using double curly braces\n    notLessThan: 'Must be less than {{label}}'\n  }\n}\n```\n\nThe validation message will render as **\"Must be less than Minimum Age\"** by interpolating the `label` param value.\n\n## Type Safety\n\nAll validator types are fully typed. While validators can optionally use generic type parameters for stricter typing, the simple form without generics works well for most cases:\n\n```typescript\n// Simple form - works for most cases\nconst noSpaces: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  if (typeof value === 'string' && value.includes(' ')) {\n    return { kind: 'noSpaces' };\n  }\n  return null;\n};\n\n// With type parameter - for stricter typing (advanced)\nconst strictNoSpaces: CustomValidator<string> = (ctx) => {\n  const value = ctx.value(); // Type: string\n  // TypeScript knows value is always string\n  return value.includes(' ') ? { kind: 'noSpaces' } : null;\n};\n\n// Async validators with type parameters (advanced)\nconst checkUsername: AsyncCustomValidator<string, { username: string }, { available: boolean }> = {\n  params: (ctx) => ({ username: ctx.value() }),\n  factory: (params) => {\n    /* ... */\n  },\n  onSuccess: (result, ctx) => {\n    result.available; // Type: boolean\n    return result.available ? null : { kind: 'usernameTaken' };\n  },\n};\n\n// HTTP validators with type parameters (advanced)\nconst checkDomain: HttpCustomValidator<string, { valid: boolean }> = {\n  request: (ctx) => ({\n    /* ... */\n  }),\n  onSuccess: (response, ctx) => {\n    response.valid; // Type: boolean\n    return response.valid ? null : { kind: 'invalidDomain' };\n  },\n};\n```\n\n**Note:** When registering validators in `customFnConfig.validators`, use the simple form without type parameters to avoid TypeScript compatibility issues.\n\n## Best Practices\n\n1. **Separation of Concerns**: Return only error `kind`, configure messages separately\n2. **i18n Support**: Use Observable/Signal for validation messages\n3. **Graceful Degradation**: Handle async/HTTP errors without blocking the form\n4. **Cross-Field Validation**: Use `ctx.valueOf()` for accessing related fields\n5. **Type Safety**: Leverage TypeScript generics for type-safe validation\n6. **Message Priority**: Use field-level messages for customization, form-level for common errors\n7. **Conditional Validation**: Use `when` property with `ConditionalExpression` for dynamic validators\n8. **Inverted Logic**: HTTP validators check validity, not data fetching success\n\n## Related Documentation\n\n- [Validation Basics](../basics/) - Core validation concepts\n- [Validation Reference](../reference/) - Standard validation rules\n- [Type Safety](../../advanced/type-safety/basics/) - TypeScript integration"
+        content: "Custom validation functions for complex validation logic that goes beyond built-in validators.\n\n## Overview\n\nng-forge supports four types of custom validators:\n\n1. **Declarative HTTP** (`type: 'http'`) - Validate against an HTTP endpoint with no function registration\n2. **CustomValidator** - Synchronous validators with access to FieldContext\n3. **AsyncCustomValidator** - Async validators using Angular's resource API\n4. **HttpCustomValidator** (function-based) - HTTP validators with full programmatic control\n\n**Key Principle:** Validators should focus on validation logic, NOT presentation. Return only the error `kind` and configure messages at field level for proper i18n support.\n\n## Live Demo\n\nTry the interactive example below to see both expression-based and function-based validators in action:\n\n<iframe src=\"http://localhost:4201/#/examples/expression-validators-demo\" class=\"example-frame\" title=\"Expression Validators Demo\"></iframe>\n\n## Message Resolution (STRICT)\n\nAll error messages MUST be explicitly configured. The framework enforces this strictly:\n\n1. **Field-level `validationMessages[kind]`** (highest priority - per-field customization)\n2. **Form-level `defaultValidationMessages[kind]`** (fallback for common messages)\n3. **No message configured = Console warning + error NOT displayed**\n\n**Important:** Validator-returned messages are NOT used as fallbacks. This enforces proper separation of concerns and i18n patterns.\n\nYou can define messages at the form level for common validation errors:\n\n```typescript\n{\n  defaultValidationMessages: {\n    noSpaces: 'Spaces are not allowed',\n    passwordMismatch: 'Passwords must match'\n  },\n  fields: [/* ... */]\n}\n```\n\n## Two Validator Patterns\n\nng-forge supports two patterns for custom validators:\n\n1. **Function-based** - Register reusable validator functions (best for complex logic, reusability)\n2. **Expression-based** - Inline JavaScript expressions (best for simple, one-off validations)\n\n## Expression-Based Validators\n\nFor simple validation logic, use inline JavaScript expressions without registering functions.\n\n### Basic Example\n\n```typescript\n{\n  key: 'confirmPassword',\n  type: 'input',\n  value: '',\n  validators: [{\n    type: 'custom',\n    expression: 'fieldValue === formValue.password',\n    kind: 'passwordMismatch',\n  }],\n  validationMessages: {\n    passwordMismatch: 'Passwords must match',\n  },\n}\n```\n\n**How it works:**\n\n- `fieldValue` - Current field's value\n- `formValue` - Entire form value object\n- Expression returns `true` = validation passes\n- Expression returns `false` = validation fails with the specified `kind`\n\n### Available Context\n\nExpression-based validators have access to:\n\n- **`fieldValue`** - Current field value\n- **`formValue`** - Complete form value object (e.g., `formValue.password`, `formValue.email`)\n- **`fieldPath`** - Current field path\n- Custom functions registered in `customFnConfig.customFunctions`\n\n### Safe Member Access\n\n**Built-in null/undefined handling**: Member access is safe by default - no manual null checks needed!\n\n```typescript\n// \u2705 Works safely even when nested values are null/undefined\n{\n  expression: 'fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n\n// \u274C Unnecessary - Don't do this\n{\n  expression: '!formValue.user || !formValue.user.profile || !formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n\n// \u2705 Better - Safe by default\n{\n  expression: '!formValue.user.profile.firstName || fieldValue !== formValue.user.profile.firstName',\n  kind: 'invalidNested',\n}\n```\n\nAccessing properties on `null` or `undefined` returns `undefined` instead of throwing errors, making expressions cleaner and more maintainable.\n\n### Common Expression Patterns\n\n**Password confirmation:**\n\n```typescript\n{\n  expression: 'fieldValue === formValue.password',\n  kind: 'passwordMismatch',\n}\n```\n\n**Date range validation:**\n\n```typescript\n{\n  expression: 'new Date(fieldValue) > new Date(formValue.startDate)',\n  kind: 'endDateBeforeStart',\n}\n```\n\n**Conditional required:**\n\n```typescript\n{\n  expression: 'formValue.requiresApproval ? fieldValue?.length > 0 : true',\n  kind: 'approvalRequired',\n}\n```\n\n**Numeric comparison:**\n\n```typescript\n{\n  expression: 'fieldValue >= formValue.minAge && fieldValue <= formValue.maxAge',\n  kind: 'ageOutOfRange',\n}\n```\n\n**Deeply nested field validation:**\n\n```typescript\n{\n  // Safe to access deeply nested properties\n  expression: 'fieldValue.toLowerCase() !== formValue.user.address.city.toLowerCase()',\n  kind: 'invalidAddress',\n}\n```\n\n### Security\n\nExpressions use **secure AST-based parsing**. Only safe JavaScript operations are allowed.\n\n## Function-Based Validators\n\nBest for validation that needs field value and access to other fields via FieldContext.\n\n### Basic Example\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\n// \u2705 RECOMMENDED: Return only kind\nconst noSpaces: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  if (typeof value === 'string' && value.includes(' ')) {\n    return { kind: 'noSpaces' }; // No hardcoded message\n  }\n  return null;\n};\n\n// Register and configure message\nconst config = {\n  fields: [\n    {\n      key: 'username',\n      type: 'input',\n      validators: [{ type: 'custom', functionName: 'noSpaces' }],\n      validationMessages: {\n        noSpaces: 'Spaces are not allowed', // Or Observable/Signal for i18n\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: {\n      noSpaces,\n    },\n  },\n};\n```\n\n### FieldContext API\n\nThe `FieldContext` API provides access to:\n\n- **`ctx.value()`** - Current field value (signal)\n- **`ctx.state`** - Field state (errors, touched, dirty, etc.)\n- **`ctx.valueOf(path)`** - Access other field values (PUBLIC API for cross-field validation)\n- **`ctx.stateOf(path)`** - Access other field states\n- **`ctx.field`** - Current field tree\n\n### Cross-Field Validation\n\nUse `ctx.valueOf()` to access other field values for comparison validators:\n\n```typescript\nimport { CustomValidator } from '@ng-forge/dynamic-forms';\n\nconst greaterThanMin: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const minValue = ctx.valueOf('minAge');\n\n  if (minValue !== undefined && value <= minValue) {\n    return { kind: 'notGreaterThanMin' };\n  }\n  return null;\n};\n\n// Note: Custom validators return only 'kind'. Built-in validators (min, max, etc.)\n// automatically include params for interpolation (e.g., {{min}}, {{max}}, etc.)\nconst config = {\n  fields: [\n    { key: 'minAge', type: 'input', value: 0 },\n    {\n      key: 'maxAge',\n      type: 'input',\n      value: 0,\n      validators: [\n        {\n          type: 'custom',\n          functionName: 'greaterThanMin',\n        },\n      ],\n      validationMessages: {\n        notGreaterThanMin: 'Maximum age must be greater than minimum age',\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: { greaterThanMin },\n  },\n};\n```\n\n**Common Cross-Field Patterns:**\n\n- Password confirmation matching\n- Date range validation (start < end)\n- Numeric range validation (min < max)\n- Conditional required fields\n\n### Password Confirmation Example\n\n```typescript\nconst passwordMatch: CustomValidator = (ctx) => {\n  const confirmPassword = ctx.value();\n  const password = ctx.valueOf('password');\n\n  if (!confirmPassword || !password) {\n    return null; // Let required validator handle empty case\n  }\n\n  if (password !== confirmPassword) {\n    return { kind: 'passwordMismatch' };\n  }\n  return null;\n};\n\n// In field config:\n{\n  key: 'confirmPassword',\n  type: 'input',\n  validators: [{ type: 'custom', functionName: 'passwordMatch' }],\n  validationMessages: {\n    passwordMismatch: 'Passwords do not match'\n  }\n}\n```\n\n## Async Validators (Resource-based)\n\n> **Deprecation notice:** The old `type: 'customAsync'` still works but is deprecated. Use `type: 'async'` instead.\n\nAsync validators use Angular's resource API for database lookups or complex async operations.\n\n### Basic Example\n\n```typescript\nimport { AsyncCustomValidator } from '@ng-forge/dynamic-forms';\nimport { inject } from '@angular/core';\nimport { rxResource } from '@angular/core/rxjs-interop';\nimport { of } from 'rxjs';\nimport { UserService } from './user.service';\n\nconst checkUsernameAvailable: AsyncCustomValidator = {\n  // Extract params from field context\n  params: (ctx) => ({ username: ctx.value() }),\n\n  // Create resource with params signal\n  factory: (params) => {\n    const userService = inject(UserService);\n    return rxResource({\n      request: params,\n      loader: ({ request }) => {\n        if (!request?.username) return of(null);\n        return userService.checkAvailability(request.username);\n      },\n    });\n  },\n\n  // Map result to validation error\n  onSuccess: (result, ctx) => {\n    if (!result) return null;\n    return result.available ? null : { kind: 'usernameTaken' };\n  },\n\n  // Handle errors gracefully\n  onError: (error, ctx) => {\n    console.error('Availability check failed:', error);\n    return null; // Don't block form on network errors\n  },\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'username',\n      type: 'input',\n      validators: [{ type: 'async', functionName: 'checkUsernameAvailable' }],\n      validationMessages: {\n        usernameTaken: 'This username is already taken',\n      },\n    },\n  ],\n  customFnConfig: {\n    asyncValidators: {\n      checkUsernameAvailable,\n    },\n  },\n};\n```\n\n**Key Benefits:**\n\n- Automatic loading states via resource API\n- Angular manages resource lifecycle\n- Reactive - refetches when params change\n- Integrates with Signal Forms validation state\n\n### Structure\n\n```typescript\ninterface AsyncCustomValidator<TValue, TParams, TResult> {\n  // Function that receives field context and returns resource params\n  readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;\n\n  // Function that creates a ResourceRef from the params signal\n  readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;\n\n  // Map successful resource result to validation errors\n  readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n  // Handle resource errors\n  readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n```\n\n## Declarative HTTP Validators\n\nThe simplest way to validate against an HTTP endpoint. No function registration required \u2014 configure the request and response mapping inline.\n\n### Basic Example\n\n```typescript\n{\n  key: 'username',\n  type: 'input',\n  validators: [\n    {\n      type: 'http',\n      http: {\n        url: '/api/users/check-availability',\n        method: 'GET',\n        queryParams: {\n          username: 'fieldValue', // fieldValue refers to the current field\n        },\n      },\n      responseMapping: {\n        validWhen: 'response.available', // Truthy = valid\n        errorKind: 'usernameTaken',\n      },\n    },\n  ],\n  validationMessages: {\n    usernameTaken: 'This username is already taken',\n  },\n}\n```\n\n**Key points:**\n\n- `fieldValue` is available as an expression in `params`, `queryParams`, and `body` (refers to the current field's value)\n- Use `params` with `:key` URL placeholders for path parameters (e.g. `url: '/api/users/:id'` + `params: { id: 'fieldValue' }`)\n- `validWhen` is evaluated with `{ response }` in scope \u2014 truthy means validation passed\n- **Fail-closed:** if the HTTP request errors, the validator returns `{ kind: errorKind }` by default (prevents submission on network failure)\n\n### POST with Body Expressions\n\n```typescript\n{\n  type: 'http',\n  http: {\n    url: '/api/validate-email',\n    method: 'POST',\n    body: {\n      email: 'fieldValue',\n    },\n    evaluateBodyExpressions: true,\n  },\n  responseMapping: {\n    validWhen: 'response.valid',\n    errorKind: 'emailInvalid',\n  },\n}\n```\n\n### Error Message Interpolation\n\nUse `errorParams` to include response data in validation messages:\n\n```typescript\n{\n  type: 'http',\n  http: {\n    url: '/api/users/check-availability',\n    queryParams: { username: 'fieldValue' },\n  },\n  responseMapping: {\n    validWhen: 'response.available',\n    errorKind: 'usernameTaken',\n    errorParams: {\n      suggestion: 'response.suggestion', // Maps to {{suggestion}} in the message\n    },\n  },\n}\n// Message: 'Username is taken. Try {{suggestion}}'\n```\n\n### HttpValidationResponseMapping Interface\n\n```typescript\ninterface HttpValidationResponseMapping {\n  /** Expression evaluated with { response }. Truthy = valid (no error). */\n  validWhen: string;\n\n  /** Error kind returned when validWhen is falsy \u2014 maps to validationMessages. */\n  errorKind: string;\n\n  /**\n   * Optional parameters for message interpolation.\n   * Keys become {{paramName}} placeholders. Values are expressions evaluated with { response }.\n   */\n  errorParams?: Record<string, string>;\n}\n```\n\n**When to use declarative vs function-based:**\n\n| Scenario                                        | Use                                              |\n| ----------------------------------------------- | ------------------------------------------------ |\n| Standard availability check                     | Declarative (`type: 'http'` + `responseMapping`) |\n| Need `inject()` for Angular services            | Function-based (`HttpCustomValidator`)           |\n| Conditional request (skip based on field state) | Function-based (`HttpCustomValidator`)           |\n| Custom error handling (fail-open on error)      | Function-based (`HttpCustomValidator`)           |\n\n## HTTP Validators (Function-Based)\n\n> **Deprecation notice:** The old `type: 'customHttp'` still works but is deprecated. Use `type: 'http'` with `functionName` instead.\n\nFunction-based HTTP validators give you full programmatic control over request construction and response handling.\n\n### Basic Example\n\n```typescript\nimport { HttpCustomValidator } from '@ng-forge/dynamic-forms';\n\nconst checkEmailDomain: HttpCustomValidator = {\n  // Build HTTP request from context\n  request: (ctx) => {\n    const email = ctx.value();\n    if (!email?.includes('@')) return undefined; // Skip if invalid\n\n    const domain = email.split('@')[1];\n    return {\n      url: `/api/validate-domain`,\n      method: 'POST',\n      body: { domain },\n      headers: { 'Content-Type': 'application/json' },\n    };\n  },\n\n  // NOTE: Inverted logic - onSuccess checks if response indicates INVALID\n  // We're validating, not fetching data!\n  onSuccess: (response, ctx) => {\n    // Assuming API returns { valid: boolean }\n    return response.valid ? null : { kind: 'invalidDomain' };\n  },\n\n  onError: (error, ctx) => {\n    console.error('Domain validation failed:', error);\n    return null; // Don't block form on network errors\n  },\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'email',\n      type: 'input',\n      validators: [{ type: 'http', functionName: 'checkEmailDomain' }],\n      validationMessages: {\n        invalidDomain: 'This email domain is not allowed',\n      },\n    },\n  ],\n  customFnConfig: {\n    httpValidators: {\n      checkEmailDomain,\n    },\n  },\n};\n```\n\n**Key Benefits:**\n\n- Automatic request cancellation when field changes\n- Built-in debouncing via resource API\n- Prevents race conditions\n- Optimized for HTTP-specific validation\n\n**Important:** HTTP validators use \"inverted logic\" - `onSuccess` should return an error if validation fails, not if the HTTP request succeeds. You're checking validation status, not fetching data.\n\n### Structure\n\n```typescript\ninterface HttpCustomValidator<TValue, TResult> {\n  // Build HTTP request from field context\n  readonly request: (ctx: FieldContext<TValue>) => HttpResourceRequest | string | undefined;\n\n  // Map successful response to validation error\n  readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n\n  // Handle HTTP errors\n  readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError | ValidationError[] | null;\n}\n\ninterface HttpResourceRequest {\n  url: string;\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n  body?: any;\n  headers?: Record<string, string | string[]>;\n}\n```\n\n## Conditional Custom Validators\n\nApply validators conditionally using the `when` property with a `ConditionalExpression`:\n\n```typescript\nconst businessEmailValidator: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const domain = value?.split('@')[1];\n\n  const freeEmailDomains = ['gmail.com', 'yahoo.com', 'hotmail.com'];\n\n  if (domain && freeEmailDomains.includes(domain.toLowerCase())) {\n    return { kind: 'requireBusinessEmail' };\n  }\n  return null;\n};\n\nconst config = {\n  fields: [\n    {\n      key: 'accountType',\n      type: 'select',\n      value: 'personal',\n      options: [\n        { value: 'personal', label: 'Personal' },\n        { value: 'business', label: 'Business' },\n      ],\n    },\n    {\n      key: 'email',\n      type: 'input',\n      validators: [\n        {\n          type: 'custom',\n          functionName: 'businessEmailValidator',\n          // Only apply when account type is \"business\"\n          when: {\n            type: 'fieldValue',\n            fieldPath: 'accountType',\n            operator: 'equals',\n            value: 'business',\n          },\n        },\n      ],\n      validationMessages: {\n        requireBusinessEmail: 'Please use a business email address',\n      },\n    },\n  ],\n  customFnConfig: {\n    validators: { businessEmailValidator },\n  },\n};\n```\n\nThe validator is only active when the `when` condition evaluates to `true`, allowing dynamic validation based on form state. See [Conditional Logic](../../dynamic-behavior/conditional-logic/overview/) for all expression types and operators.\n\n## Common Validation Patterns\n\n### Email Domain Validation\n\n```typescript\nconst emailDomainValidator: CustomValidator = (ctx) => {\n  const blockedDomains = ['tempmail.com', 'throwaway.email'];\n  const email = ctx.value();\n  const domain = email?.split('@')[1];\n\n  if (domain && blockedDomains.includes(domain)) {\n    return { kind: 'blockedDomain' };\n  }\n  return null;\n};\n```\n\n### Age Validation\n\n```typescript\nconst ageValidator: CustomValidator = (ctx) => {\n  const birthDate = ctx.value();\n  const age = calculateAge(birthDate);\n\n  if (age < 18) {\n    return { kind: 'tooYoung' };\n  }\n  return null;\n};\n```\n\n### Conditional Required\n\n```typescript\nconst conditionalRequiredValidator: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  const employmentStatus = ctx.valueOf('employmentStatus');\n\n  // Company name required if employed\n  if (employmentStatus === 'employed' && !value) {\n    return { kind: 'required' };\n  }\n  return null;\n};\n```\n\n### Date Range Validation\n\n```typescript\nconst dateRangeValidator: CustomValidator = (ctx) => {\n  const endDate = ctx.value();\n  const startDate = ctx.valueOf('startDate');\n\n  if (startDate && endDate && startDate > endDate) {\n    return { kind: 'invalidDateRange' };\n  }\n  return null;\n};\n```\n\n## Multiple Errors\n\nValidators can return multiple errors for cross-field validation:\n\n```typescript\nconst validateDateRange: CustomValidator = (ctx) => {\n  const errors: ValidationError[] = [];\n\n  const startDate = ctx.valueOf('startDate');\n  const endDate = ctx.valueOf('endDate');\n\n  if (!startDate) errors.push({ kind: 'startDateRequired' });\n  if (!endDate) errors.push({ kind: 'endDateRequired' });\n  if (startDate && endDate && startDate > endDate) {\n    errors.push({ kind: 'invalidDateRange' });\n  }\n\n  return errors.length > 0 ? errors : null;\n};\n```\n\n## Validation Messages\n\n### Field-Level Messages\n\n```typescript\n{\n  key: 'username',\n  validators: [{ type: 'custom', functionName: 'noSpaces' }],\n  validationMessages: {\n    noSpaces: 'Spaces are not allowed'\n  }\n}\n```\n\n### Form-Level Default Messages\n\n```typescript\n{\n  defaultValidationMessages: {\n    noSpaces: 'Spaces are not allowed',\n    passwordMismatch: 'Passwords must match',\n    usernameTaken: 'This username is already taken'\n  },\n  fields: [/* ... */]\n}\n```\n\n### Dynamic Messages with i18n\n\n```typescript\nimport { inject } from '@angular/core';\nimport { TranslateService } from '@ngx-translate/core';\n\n{\n  key: 'username',\n  validators: [{ type: 'custom', functionName: 'noSpaces' }],\n  validationMessages: {\n    noSpaces: inject(TranslateService).get('VALIDATION.NO_SPACES')\n  }\n}\n```\n\n### Parameterized Messages\n\nMessages can interpolate params from ValidatorConfig using Angular template syntax (double curly braces around the param name).\n\n**Syntax:** To interpolate a param, wrap its name in double curly braces (same syntax as Angular templates).\n\n**Example:** To access `params.label`, write the param name `label` wrapped in double curly braces in your message string.\n\n```typescript\n{\n  validators: [\n    {\n      type: 'custom',\n      functionName: 'lessThanField',\n      params: { field: 'minAge', label: 'Minimum Age' }\n    }\n  ],\n  validationMessages: {\n    // Interpolate params.label using double curly braces\n    notLessThan: 'Must be less than {{label}}'\n  }\n}\n```\n\nThe validation message will render as **\"Must be less than Minimum Age\"** by interpolating the `label` param value.\n\n## Type Safety\n\nAll validator types are fully typed. While validators can optionally use generic type parameters for stricter typing, the simple form without generics works well for most cases:\n\n```typescript\n// Simple form - works for most cases\nconst noSpaces: CustomValidator = (ctx) => {\n  const value = ctx.value();\n  if (typeof value === 'string' && value.includes(' ')) {\n    return { kind: 'noSpaces' };\n  }\n  return null;\n};\n\n// With type parameter - for stricter typing (advanced)\nconst strictNoSpaces: CustomValidator<string> = (ctx) => {\n  const value = ctx.value(); // Type: string\n  // TypeScript knows value is always string\n  return value.includes(' ') ? { kind: 'noSpaces' } : null;\n};\n\n// Async validators with type parameters (advanced)\nconst checkUsername: AsyncCustomValidator<string, { username: string }, { available: boolean }> = {\n  params: (ctx) => ({ username: ctx.value() }),\n  factory: (params) => {\n    /* ... */\n  },\n  onSuccess: (result, ctx) => {\n    result.available; // Type: boolean\n    return result.available ? null : { kind: 'usernameTaken' };\n  },\n};\n\n// HTTP validators with type parameters (advanced)\nconst checkDomain: HttpCustomValidator<string, { valid: boolean }> = {\n  request: (ctx) => ({\n    /* ... */\n  }),\n  onSuccess: (response, ctx) => {\n    response.valid; // Type: boolean\n    return response.valid ? null : { kind: 'invalidDomain' };\n  },\n};\n```\n\n**Note:** When registering validators in `customFnConfig.validators`, use the simple form without type parameters to avoid TypeScript compatibility issues.\n\n## Best Practices\n\n1. **Separation of Concerns**: Return only error `kind`, configure messages separately\n2. **i18n Support**: Use Observable/Signal for validation messages\n3. **Graceful Degradation**: Handle async/HTTP errors without blocking the form\n4. **Cross-Field Validation**: Use `ctx.valueOf()` for accessing related fields\n5. **Type Safety**: Leverage TypeScript generics for type-safe validation\n6. **Message Priority**: Use field-level messages for customization, form-level for common errors\n7. **Conditional Validation**: Use `when` property with `ConditionalExpression` for dynamic validators\n8. **Inverted Logic**: HTTP validators check validity, not data fetching success\n\n## Related Documentation\n\n- [Validation Basics](../basics/) - Core validation concepts\n- [Validation Reference](../reference/) - Standard validation rules\n- [Type Safety](../../advanced/type-safety/basics/) - TypeScript integration"
       },
       {
         id: "validation-reference",
         title: "Validation Reference",
         category: "validation",
-        content: "Complete reference for all validators, conditional expressions, and validation configuration options.\n\n## All Validator Types\n\n### required\n\nField must have a value.\n\n```typescript\n// Shorthand\n{ required: true }\n\n// Explicit\n{\n  validators: [{\n    type: 'required',\n  }],\n}\n```\n\n### email\n\nMust be a valid email format.\n\n```typescript\n// Shorthand\n{ email: true }\n\n// Explicit\n{\n  validators: [{\n    type: 'email',\n  }],\n}\n```\n\n### minLength\n\nMinimum string length.\n\n```typescript\n// Shorthand\n{ minLength: 8 }\n\n// Explicit\n{\n  validators: [{\n    type: 'minLength',\n    value: 8,\n  }],\n}\n```\n\n### maxLength\n\nMaximum string length.\n\n```typescript\n// Shorthand\n{ maxLength: 20 }\n\n// Explicit\n{\n  validators: [{\n    type: 'maxLength',\n    value: 20,\n  }],\n}\n```\n\n### min\n\nMinimum numeric value.\n\n```typescript\n// Shorthand\n{ min: 0 }\n\n// Explicit\n{\n  validators: [{\n    type: 'min',\n    value: 0,\n  }],\n}\n```\n\n### max\n\nMaximum numeric value.\n\n```typescript\n// Shorthand\n{ max: 100 }\n\n// Explicit\n{\n  validators: [{\n    type: 'max',\n    value: 100,\n  }],\n}\n```\n\n### pattern\n\nRegular expression validation.\n\n```typescript\n// Shorthand\n{ pattern: '^[0-9]{5}$' }\n\n// Explicit\n{\n  validators: [{\n    type: 'pattern',\n    value: '^[0-9]{5}$',\n  }],\n}\n```\n\n## Conditional Expressions\n\nValidators support a `when` property for conditional validation. See **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** for the complete reference on:\n\n- All operators (`equals`, `notEquals`, `greater`, `less`, `contains`, `matches`, etc.)\n- Expression types (`fieldValue`, `formValue`, `javascript`, `custom`)\n- Combining conditions with `and`/`or` logic\n\n**Quick example:**\n\n```typescript\n{\n  validators: [{\n    type: 'required',\n    when: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n## ValidatorConfig Types\n\nValidatorConfig is a discriminated union type with four variants:\n\n```typescript\n// Built-in validators (required, email, min, max, etc.)\ninterface BuiltInValidatorConfig {\n  type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';\n  value?: number | string | RegExp;\n  expression?: string;\n  when?: ConditionalExpression;\n}\n\n// Custom synchronous validators\ninterface CustomValidatorConfig {\n  type: 'custom';\n  functionName?: string;\n  params?: Record<string, unknown>;\n  expression?: string;\n  kind?: string;\n  errorParams?: Record<string, string>;\n  when?: ConditionalExpression;\n}\n\n// Async validators (for debounced validation, database lookups)\ninterface AsyncValidatorConfig {\n  type: 'customAsync';\n  functionName: string;\n  params?: Record<string, unknown>;\n  when?: ConditionalExpression;\n}\n\n// HTTP validators (optimized HTTP validation with auto-cancellation)\ninterface HttpValidatorConfig {\n  type: 'customHttp';\n  functionName: string;\n  params?: Record<string, unknown>;\n  when?: ConditionalExpression;\n}\n\ntype ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | HttpValidatorConfig;\n```\n\n## ConditionalExpression Interface\n\n```typescript\ninterface ConditionalExpression {\n  // Expression type - includes 'and' and 'or' for combining conditions\n  type: 'fieldValue' | 'formValue' | 'custom' | 'javascript' | 'and' | 'or';\n\n  // Field path for fieldValue type\n  fieldPath?: string;\n\n  // Comparison operator\n  operator?:\n    | 'equals'\n    | 'notEquals'\n    | 'greater'\n    | 'less'\n    | 'greaterOrEqual'\n    | 'lessOrEqual'\n    | 'contains'\n    | 'startsWith'\n    | 'endsWith'\n    | 'matches';\n\n  // Value to compare against\n  value?: unknown;\n\n  // JavaScript expression for custom logic\n  expression?: string;\n\n  // Array of sub-conditions for 'and' and 'or' types\n  conditions?: ConditionalExpression[];\n}\n```\n\n## Validation Messages\n\n### Per-Field Messages\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  email: true,\n  validationMessages: {\n    required: 'Email is required',\n    email: 'Invalid email format',\n  },\n}\n```\n\n### Dynamic Messages (i18n)\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  validationMessages: {\n    required: this.transloco.selectTranslate('validation.required'),\n    email: this.transloco.selectTranslate('validation.email'),\n  },\n}\n```\n\n## Common Patterns\n\n### Email Validation\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  email: true,\n  validationMessages: {\n    required: 'Email is required',\n    email: 'Please enter a valid email address',\n  },\n}\n```\n\n### Password Requirements\n\n```typescript\n{\n  key: 'password',\n  type: 'input',\n  value: '',\n  required: true,\n  minLength: 8,\n  maxLength: 128,\n  pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&])',\n  validationMessages: {\n    required: 'Password is required',\n    minLength: 'Password must be at least 8 characters',\n    pattern: 'Password must include uppercase, lowercase, number, and special character',\n  },\n  props: { type: 'password' },\n}\n```\n\n### Numeric Range\n\n```typescript\n{\n  key: 'age',\n  type: 'input',\n  value: null,\n  required: true,\n  min: 18,\n  max: 120,\n  validationMessages: {\n    required: 'Age is required',\n    min: 'Must be at least 18 years old',\n    max: 'Please enter a valid age',\n  },\n  props: { type: 'number' },\n}\n```\n\n### ZIP Code\n\n```typescript\n{\n  key: 'zipCode',\n  type: 'input',\n  value: '',\n  required: true,\n  pattern: '^[0-9]{5}(-[0-9]{4})?$',\n  validationMessages: {\n    required: 'ZIP code is required',\n    pattern: 'Must be 5 digits or 5+4 format (e.g., 12345 or 12345-6789)',\n  },\n}\n```\n\n### Phone Number\n\n```typescript\n{\n  key: 'phone',\n  type: 'input',\n  value: '',\n  pattern: '^\\\\+?[1-9]\\\\d{1,14}$',\n  validationMessages: {\n    pattern: 'Please enter a valid phone number (E.164 format preferred)',\n  },\n  props: { type: 'tel' },\n}\n```\n\n### URL\n\n```typescript\n{\n  key: 'website',\n  type: 'input',\n  value: '',\n  pattern: '^https?:\\\\/\\\\/.+',\n  validationMessages: {\n    pattern: 'Please enter a valid URL starting with http:// or https://',\n  },\n  props: { type: 'url' },\n}\n```\n\n## Related\n\n- **[Validation Basics](../basics/)** - Getting started with validation\n- **[Validation Advanced](../advanced/)** - Conditional validators\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Field behavior changes\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration"
+        content: "Complete reference for all validators, conditional expressions, and validation configuration options.\n\n## All Validator Types\n\n### required\n\nField must have a value.\n\n```typescript\n// Shorthand\n{ required: true }\n\n// Explicit\n{\n  validators: [{\n    type: 'required',\n  }],\n}\n```\n\n### email\n\nMust be a valid email format.\n\n```typescript\n// Shorthand\n{ email: true }\n\n// Explicit\n{\n  validators: [{\n    type: 'email',\n  }],\n}\n```\n\n### minLength\n\nMinimum string length.\n\n```typescript\n// Shorthand\n{ minLength: 8 }\n\n// Explicit\n{\n  validators: [{\n    type: 'minLength',\n    value: 8,\n  }],\n}\n```\n\n### maxLength\n\nMaximum string length.\n\n```typescript\n// Shorthand\n{ maxLength: 20 }\n\n// Explicit\n{\n  validators: [{\n    type: 'maxLength',\n    value: 20,\n  }],\n}\n```\n\n### min\n\nMinimum numeric value.\n\n```typescript\n// Shorthand\n{ min: 0 }\n\n// Explicit\n{\n  validators: [{\n    type: 'min',\n    value: 0,\n  }],\n}\n```\n\n### max\n\nMaximum numeric value.\n\n```typescript\n// Shorthand\n{ max: 100 }\n\n// Explicit\n{\n  validators: [{\n    type: 'max',\n    value: 100,\n  }],\n}\n```\n\n### pattern\n\nRegular expression validation.\n\n```typescript\n// Shorthand\n{ pattern: '^[0-9]{5}$' }\n\n// Explicit\n{\n  validators: [{\n    type: 'pattern',\n    value: '^[0-9]{5}$',\n  }],\n}\n```\n\n## Conditional Expressions\n\nValidators support a `when` property for conditional validation. See **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** for the complete reference on:\n\n- All operators (`equals`, `notEquals`, `greater`, `less`, `contains`, `matches`, etc.)\n- Expression types (`fieldValue`, `formValue` (deprecated), `javascript`, `custom`)\n- Combining conditions with `and`/`or` logic\n\n**Quick example:**\n\n```typescript\n{\n  validators: [{\n    type: 'required',\n    when: {\n      type: 'fieldValue',\n      fieldPath: 'accountType',\n      operator: 'equals',\n      value: 'business',\n    },\n  }],\n}\n```\n\n## ValidatorConfig Types\n\nValidatorConfig is a discriminated union type with five variants:\n\n```typescript\n// Built-in validators (required, email, min, max, etc.)\ninterface BuiltInValidatorConfig {\n  type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';\n  value?: number | string | RegExp;\n  expression?: string;\n  when?: ConditionalExpression;\n}\n\n// Custom synchronous validators\ninterface CustomValidatorConfig {\n  type: 'custom';\n  functionName?: string;\n  params?: Record<string, unknown>;\n  expression?: string;\n  kind?: string;\n  errorParams?: Record<string, string>;\n  when?: ConditionalExpression;\n}\n\n// Async validators (for debounced validation, database lookups)\ninterface AsyncValidatorConfig {\n  // 'async' is preferred; 'customAsync' is deprecated and emits a warning in dev mode\n  type: 'async' | 'customAsync';\n  functionName: string;\n  params?: Record<string, unknown>;\n  when?: ConditionalExpression;\n}\n\n// Function-based HTTP validators (requires a registered function)\ninterface FunctionHttpValidatorConfig {\n  // 'http' is preferred; 'customHttp' is deprecated and emits a warning in dev mode\n  type: 'http' | 'customHttp';\n  functionName: string;\n  params?: Record<string, unknown>;\n  when?: ConditionalExpression;\n}\n\n// Declarative HTTP validators (fully JSON-serializable, no function registration)\ninterface DeclarativeHttpValidatorConfig {\n  type: 'http';\n  http: HttpRequestConfig;\n  responseMapping: HttpValidationResponseMapping;\n  when?: ConditionalExpression;\n}\n\ntype ValidatorConfig =\n  | BuiltInValidatorConfig\n  | CustomValidatorConfig\n  | AsyncValidatorConfig\n  | FunctionHttpValidatorConfig\n  | DeclarativeHttpValidatorConfig;\n```\n\n> **Deprecation notes:**\n>\n> - `type: 'customAsync'` is deprecated. Use `type: 'async'` instead.\n> - `type: 'customHttp'` is deprecated. Use `type: 'http'` instead.\n> - `FunctionHttpValidatorConfig` and `DeclarativeHttpValidatorConfig` both use `type: 'http'`. They are discriminated by property presence: `functionName` indicates function-based, `http` + `responseMapping` indicates declarative.\n\n### HttpRequestConfig\n\nUsed by `DeclarativeHttpValidatorConfig` to define the HTTP request:\n\n```typescript\ninterface HttpRequestConfig {\n  url: string;\n  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; // defaults to 'GET'\n  queryParams?: Record<string, string>; // values are expressions\n  body?: Record<string, unknown>;\n  evaluateBodyExpressions?: boolean; // when true, top-level string values in body are evaluated as expressions\n  headers?: Record<string, string>;\n}\n```\n\n### HttpValidationResponseMapping\n\nUsed by `DeclarativeHttpValidatorConfig` to interpret the HTTP response:\n\n```typescript\ninterface HttpValidationResponseMapping {\n  validWhen: string; // expression evaluated with { response } scope; truthy = valid\n  errorKind: string; // error kind for validationMessages lookup\n  errorParams?: Record<string, string>; // parameter expressions evaluated against { response }\n}\n```\n\n## ConditionalExpression Types\n\n`ConditionalExpression` is a discriminated union of six condition types. Each variant only allows the properties relevant to its type, providing compile-time safety against invalid property combinations.\n\n```typescript\n// Compare a specific field's value\ninterface FieldValueCondition {\n  type: 'fieldValue';\n  fieldPath: string;\n  operator: ComparisonOperator;\n  value?: unknown;\n}\n\n// Compare the entire form value (deprecated \u2014 use FieldValueCondition or JavascriptCondition instead)\ninterface FormValueCondition {\n  type: 'formValue';\n  operator: ComparisonOperator;\n  value?: unknown;\n}\n\n// Invoke a registered custom function by name\ninterface CustomCondition {\n  type: 'custom';\n  expression: string; // registered function name\n}\n\n// Evaluate a JavaScript expression via the secure AST-based parser\ninterface JavascriptCondition {\n  type: 'javascript';\n  expression: string; // has access to formValue, fieldValue, externalData, etc.\n}\n\n// Logical AND \u2014 all sub-conditions must be true\ninterface AndCondition {\n  type: 'and';\n  conditions: ConditionalExpression[];\n}\n\n// Logical OR \u2014 at least one sub-condition must be true\ninterface OrCondition {\n  type: 'or';\n  conditions: ConditionalExpression[];\n}\n\ntype ComparisonOperator =\n  | 'equals'\n  | 'notEquals'\n  | 'greater'\n  | 'less'\n  | 'greaterOrEqual'\n  | 'lessOrEqual'\n  | 'contains'\n  | 'startsWith'\n  | 'endsWith'\n  | 'matches';\n\ntype ConditionalExpression = FieldValueCondition | FormValueCondition | CustomCondition | JavascriptCondition | AndCondition | OrCondition;\n```\n\n> **Deprecation note:** `FormValueCondition` (`type: 'formValue'`) is deprecated. Use `FieldValueCondition` for specific field checks, or `JavascriptCondition` with an expression for complex form-level comparisons.\n\n## Validation Messages\n\n### Per-Field Messages\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  email: true,\n  validationMessages: {\n    required: 'Email is required',\n    email: 'Invalid email format',\n  },\n}\n```\n\n### Dynamic Messages (i18n)\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  validationMessages: {\n    required: this.transloco.selectTranslate('validation.required'),\n    email: this.transloco.selectTranslate('validation.email'),\n  },\n}\n```\n\n## Common Patterns\n\n### Email Validation\n\n```typescript\n{\n  key: 'email',\n  type: 'input',\n  value: '',\n  required: true,\n  email: true,\n  validationMessages: {\n    required: 'Email is required',\n    email: 'Please enter a valid email address',\n  },\n}\n```\n\n### Password Requirements\n\n```typescript\n{\n  key: 'password',\n  type: 'input',\n  value: '',\n  required: true,\n  minLength: 8,\n  maxLength: 128,\n  pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&])',\n  validationMessages: {\n    required: 'Password is required',\n    minLength: 'Password must be at least 8 characters',\n    pattern: 'Password must include uppercase, lowercase, number, and special character',\n  },\n  props: { type: 'password' },\n}\n```\n\n### Numeric Range\n\n```typescript\n{\n  key: 'age',\n  type: 'input',\n  value: null,\n  required: true,\n  min: 18,\n  max: 120,\n  validationMessages: {\n    required: 'Age is required',\n    min: 'Must be at least 18 years old',\n    max: 'Please enter a valid age',\n  },\n  props: { type: 'number' },\n}\n```\n\n### ZIP Code\n\n```typescript\n{\n  key: 'zipCode',\n  type: 'input',\n  value: '',\n  required: true,\n  pattern: '^[0-9]{5}(-[0-9]{4})?$',\n  validationMessages: {\n    required: 'ZIP code is required',\n    pattern: 'Must be 5 digits or 5+4 format (e.g., 12345 or 12345-6789)',\n  },\n}\n```\n\n### Phone Number\n\n```typescript\n{\n  key: 'phone',\n  type: 'input',\n  value: '',\n  pattern: '^\\\\+?[1-9]\\\\d{1,14}$',\n  validationMessages: {\n    pattern: 'Please enter a valid phone number (E.164 format preferred)',\n  },\n  props: { type: 'tel' },\n}\n```\n\n### URL\n\n```typescript\n{\n  key: 'website',\n  type: 'input',\n  value: '',\n  pattern: '^https?:\\\\/\\\\/.+',\n  validationMessages: {\n    pattern: 'Please enter a valid URL starting with http:// or https://',\n  },\n  props: { type: 'url' },\n}\n```\n\n## Related\n\n- **[Validation Basics](../basics/)** - Getting started with validation\n- **[Validation Advanced](../advanced/)** - Conditional validators\n- **[Conditional Logic](../../dynamic-behavior/conditional-logic/overview/)** - Field behavior changes\n- **[Type Safety](../../advanced/type-safety/basics/)** - TypeScript integration"
       }
     ];
   }
@@ -504,7 +534,7 @@ var field_types_default = [
   {
     type: "row",
     category: "container",
-    description: "Horizontal layout container for grouping fields in columns. Rows do NOT have a label property and do NOT support logic blocks.",
+    description: "Horizontal layout container for grouping fields in columns. Rows do NOT have a label property. Supports only 'hidden' logic type for conditional visibility.",
     baseInterface: "FieldDef",
     props: {
       fields: {
@@ -537,13 +567,13 @@ var field_types_default = [
       "previous"
     ],
     cannotContain: ["page", "row", "hidden"],
-    example: "{\n  key: 'nameRow',\n  type: 'row',\n  // NOTE: Rows do NOT have label or logic properties\n  fields: [\n    { key: 'firstName', type: 'input', label: 'First Name', col: 6 },\n    { key: 'lastName', type: 'input', label: 'Last Name', col: 6 }\n  ]\n}\n// NOT ALLOWED in rows:\n// - type: 'hidden' (hidden fields cannot be inside rows)\n// - type: 'page' (pages are top-level only)\n// - type: 'row' (no nested rows)",
+    example: "{\n  key: 'nameRow',\n  type: 'row',\n  // NOTE: Rows do NOT have a label property\n  // Rows support only 'hidden' logic type for conditional visibility\n  fields: [\n    { key: 'firstName', type: 'input', label: 'First Name', col: 6 },\n    { key: 'lastName', type: 'input', label: 'Last Name', col: 6 }\n  ]\n}\n// NOT ALLOWED in rows:\n// - type: 'hidden' (hidden fields cannot be inside rows)\n// - type: 'page' (pages are top-level only)\n// - type: 'row' (no nested rows)",
     minimalExample: "{ key: 'row1', type: 'row', fields: [...] }"
   },
   {
     type: "group",
     category: "container",
-    description: "Nested form group container creating a sub-object in form values. Groups are logical containers only and do NOT have a label property.",
+    description: "Nested form group container creating a sub-object in form values. Groups are logical containers only and do NOT have a label property. Supports only 'hidden' logic type for conditional visibility.",
     valueType: "object",
     baseInterface: "FieldDef",
     props: {
@@ -583,7 +613,7 @@ var field_types_default = [
   {
     type: "array",
     category: "container",
-    description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have label, minItems, or maxItems properties. Use "fields" (not "template") to define the item template.',
+    description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have a label property. Use "fields" (not "template") to define the item template. Supports only \'hidden\' logic type for conditional visibility. Supports minLength/maxLength for array size validation. Each array item is rendered inside a `<div class="df-array-item">` wrapper with `role="group"`, `aria-label="Item N"` (1-based), `data-array-item-id`, and `data-array-item-index` attributes for styling, accessibility, and testing.',
     valueType: "T[]",
     baseInterface: "FieldDef",
     props: {
@@ -592,9 +622,21 @@ var field_types_default = [
         type: "ArrayAllowedChildren[]",
         description: "Template field(s) for each array item. Allowed: rows, groups, leaf fields (NOT pages or other arrays)",
         required: true
+      },
+      minLength: {
+        name: "minLength",
+        type: "number",
+        description: "Minimum number of items required in the array. Validation fails if fewer items.",
+        required: false
+      },
+      maxLength: {
+        name: "maxLength",
+        type: "number",
+        description: "Maximum number of items allowed in the array. Validation fails if more items.",
+        required: false
       }
     },
-    validationSupported: false,
+    validationSupported: true,
     source: "core",
     allowedIn: ["top-level", "page", "row", "group"],
     notAllowedIn: ["array"],
@@ -618,7 +660,7 @@ var field_types_default = [
       "previous"
     ],
     cannotContain: ["page", "array"],
-    example: "// Flat array (primitive values)\n{\n  key: 'tags',\n  type: 'array',\n  // NOTE: Arrays do NOT have label, minItems, or maxItems\n  fields: [\n    { key: 'tag', type: 'input', label: 'Tag' }\n  ]\n}\n// Result: { tags: ['value1', 'value2'] }\n\n// Object array (nested groups)\n{\n  key: 'contacts',\n  type: 'array',\n  fields: [{\n    type: 'group',\n    fields: [\n      { key: 'name', type: 'input', label: 'Name' },\n      { key: 'email', type: 'input', label: 'Email' }\n    ]\n  }]\n}\n// Result: { contacts: [{name: '', email: ''}, ...] }",
+    example: "// Flat array with length validation\n{\n  key: 'tags',\n  type: 'array',\n  minLength: 1,  // At least one tag required\n  maxLength: 5,  // No more than 5 tags\n  fields: [\n    { key: 'tag', type: 'input', label: 'Tag' }\n  ]\n}\n// Result: { tags: ['value1', 'value2'] }\n\n// Object array (nested groups)\n{\n  key: 'contacts',\n  type: 'array',\n  minLength: 1,\n  fields: [{\n    type: 'group',\n    fields: [\n      { key: 'name', type: 'input', label: 'Name' },\n      { key: 'email', type: 'input', label: 'Email' }\n    ]\n  }]\n}\n// Result: { contacts: [{name: '', email: ''}, ...] }",
     minimalExample: "{ key: 'items', type: 'array', fields: [...] }"
   },
   {
@@ -861,10 +903,30 @@ var validators_default = [
     },
     example: "// Expression-based custom validator with error message\n// The validator:\n{\n  type: 'custom',\n  expression: 'fieldValue === formValue.password',\n  kind: 'passwordMismatch'  // Just the error KIND, not the message\n}\n\n// COMPLETE FIELD with validationMessages at FIELD level:\n{\n  key: 'confirmPassword',\n  type: 'input',\n  label: 'Confirm Password',\n  props: { type: 'password' },\n  validators: [\n    { type: 'custom', expression: 'fieldValue === formValue.password', kind: 'passwordMismatch' }\n  ],\n  validationMessages: {\n    passwordMismatch: 'Passwords do not match'  // Message goes HERE at field level\n  }\n}"
   },
+  {
+    type: "async",
+    category: "async",
+    description: "Async validator using registered async function (resource-based). Register the function via customFnConfig.asyncValidators.",
+    parameters: {
+      functionName: {
+        name: "functionName",
+        type: "string",
+        description: "Name of registered async validator function",
+        required: true
+      },
+      params: {
+        name: "params",
+        type: "Record<string, unknown>",
+        description: "Parameters to pass to validator function",
+        required: false
+      }
+    },
+    example: "{\n  type: 'async',\n  functionName: 'checkUsernameAvailability'\n}"
+  },
   {
     type: "customAsync",
     category: "async",
-    description: "Async validator using registered async function",
+    description: "DEPRECATED \u2014 use type: 'async' instead. Async validator using registered async function.",
     parameters: {
       functionName: {
         name: "functionName",
@@ -879,12 +941,12 @@ var validators_default = [
         required: false
       }
     },
-    example: "{\n  type: 'customAsync',\n  functionName: 'checkUsernameAvailability'\n}"
+    example: "// DEPRECATED \u2014 use type: 'async' instead\n{\n  type: 'customAsync',\n  functionName: 'checkUsernameAvailability'\n}"
   },
   {
     type: "customHttp",
     category: "http",
-    description: "HTTP-based validator with automatic request cancellation",
+    description: "DEPRECATED \u2014 use type: 'http' with functionName instead. HTTP-based validator with automatic request cancellation.",
     parameters: {
       functionName: {
         name: "functionName",
@@ -899,7 +961,39 @@ var validators_default = [
         required: false
       }
     },
-    example: "{\n  type: 'customHttp',\n  functionName: 'validateEmailExists'\n}"
+    example: "// DEPRECATED \u2014 use type: 'http' with functionName instead\n{\n  type: 'customHttp',\n  functionName: 'validateEmailExists'\n}"
+  },
+  {
+    type: "http",
+    category: "http",
+    description: "HTTP validator \u2014 supports two modes: (1) Declarative (fully JSON-serializable, no function registration) using http + responseMapping properties, or (2) Function-based using functionName to reference a registered HTTP validator function. Query param values and (optionally) body values are expressions evaluated against the form context. Response mapping uses validWhen (truthy = valid) and errorKind (maps to field-level validationMessages).",
+    parameters: {
+      functionName: {
+        name: "functionName",
+        type: "string",
+        description: "Name of registered HTTP validator function (function-based mode). Mutually exclusive with http + responseMapping.",
+        required: false
+      },
+      http: {
+        name: "http",
+        type: "HttpRequestConfig",
+        description: "HTTP request configuration: { url, method?, queryParams?, body?, evaluateBodyExpressions?, headers?, debounceMs? }. queryParams values are expressions. When evaluateBodyExpressions is true, top-level string values in body are evaluated as expressions (shallow only). Required for declarative mode.",
+        required: false
+      },
+      responseMapping: {
+        name: "responseMapping",
+        type: "HttpValidationResponseMapping",
+        description: "Response mapping: { validWhen, errorKind, errorParams? }. validWhen is an expression evaluated with { response } scope \u2014 truthy means valid. errorKind maps to field-level validationMessages. Required for declarative mode.",
+        required: false
+      },
+      params: {
+        name: "params",
+        type: "Record<string, unknown>",
+        description: "Parameters to pass to HTTP validator function (function-based mode only).",
+        required: false
+      }
+    },
+    example: "// HTTP validator (fully JSON-serializable)\n{\n  type: 'http',\n  http: {\n    url: '/api/validate-username',\n    method: 'GET',\n    queryParams: {\n      username: 'fieldValue'\n    }\n  },\n  responseMapping: {\n    validWhen: 'response.available',\n    errorKind: 'usernameTaken',\n    errorParams: {\n      suggestion: 'response.suggestion'\n    }\n  }\n}\n\n// COMPLETE FIELD with validationMessages at FIELD level:\n{\n  key: 'username',\n  type: 'input',\n  label: 'Username',\n  validators: [\n    {\n      type: 'http',\n      http: {\n        url: '/api/validate-username',\n        method: 'GET',\n        queryParams: { username: 'fieldValue' }\n      },\n      responseMapping: {\n        validWhen: 'response.available',\n        errorKind: 'usernameTaken',\n        errorParams: { suggestion: 'response.suggestion' }\n      }\n    }\n  ],\n  validationMessages: {\n    usernameTaken: 'Username is taken. Try {{suggestion}}'\n  }\n}"
   }
 ];
 
@@ -1703,13 +1797,13 @@ Use when you need nested object structure in form values:
 
 #### Array (Repeatable Items)
 
-Use for dynamic lists:
+Use for dynamic lists. Each item is wrapped in a \`<div class="df-array-item">\` with \`role="group"\` and \`aria-label="Item N"\` for accessibility. Use \`--df-array-item-gap\` CSS variable to control spacing between items.
 
 \`\`\`typescript
 {
   key: 'contacts',
   type: 'array',
-  label: 'Emergency Contacts',
+  // \u26A0\uFE0F NO label property on arrays!
   fields: [
     {
       key: 'contact',
@@ -3089,7 +3183,22 @@ var BaseFieldDefSchema = z14.object({
   /**
    * Grid column width (1-12) in a 12-column layout system.
    */
-  col: z14.number().min(1).max(12).optional()
+  col: z14.number().min(1).max(12).optional(),
+  /**
+   * Whether to exclude this field's value from submission output when hidden.
+   * Overrides both the global and form-level settings.
+   */
+  excludeValueIfHidden: z14.boolean().optional(),
+  /**
+   * Whether to exclude this field's value from submission output when disabled.
+   * Overrides both the global and form-level settings.
+   */
+  excludeValueIfDisabled: z14.boolean().optional(),
+  /**
+   * Whether to exclude this field's value from submission output when readonly.
+   * Overrides both the global and form-level settings.
+   */
+  excludeValueIfReadonly: z14.boolean().optional()
 });
 
 // internal/dynamic-forms-zod/src/lib/schemas/field/field-with-validation.schema.ts
@@ -3832,7 +3941,10 @@ var HiddenFieldSchema = BaseFieldDefSchema.omit({
   readonly: true,
   hidden: true,
   tabIndex: true,
-  col: true
+  col: true,
+  excludeValueIfHidden: true,
+  excludeValueIfDisabled: true,
+  excludeValueIfReadonly: true
 }).extend({
   /**
    * Field type discriminant.
@@ -3870,7 +3982,7 @@ var MatLeafFieldSchema = z35.discriminatedUnion("type", [
 
 // internal/dynamic-forms-zod/src/lib/schemas/containers/factories.ts
 import { z as z36 } from "zod";
-var PageLogicSchema = z36.object({
+var ContainerLogicSchema = z36.object({
   type: z36.literal("hidden"),
   condition: z36.union([ConditionalExpressionSchema, z36.boolean()])
 });
@@ -3897,31 +4009,61 @@ function createContainerSchemas(options) {
   const PageFieldSchema = ContainerBaseSchema.extend({
     type: z36.literal("page"),
     fields: z36.array(AnyFieldSchema),
-    logic: z36.array(PageLogicSchema).optional(),
+    logic: z36.array(ContainerLogicSchema).optional(),
     // Also forbid title (common mistake)
     title: z36.never().optional()
   });
   const RowFieldSchema = ContainerBaseSchema.extend({
     type: z36.literal("row"),
     fields: z36.array(AnyFieldSchema),
-    // Explicitly forbid logic on rows
-    logic: z36.never().optional()
+    // Container logic - only 'hidden' type allowed (same as pages)
+    logic: z36.array(ContainerLogicSchema).optional()
   });
   const GroupFieldSchema = ContainerBaseSchema.extend({
     type: z36.literal("group"),
     fields: z36.array(AnyFieldSchema),
-    // Explicitly forbid logic on groups
-    logic: z36.never().optional()
+    // Container logic - only 'hidden' type allowed (same as pages)
+    logic: z36.array(ContainerLogicSchema).optional()
+  });
+  const ArrayButtonConfigSchema = z36.object({
+    label: z36.string().optional(),
+    props: z36.record(z36.unknown()).optional()
   });
-  const ArrayFieldSchema = ContainerBaseSchema.extend({
+  const FullArrayFieldSchema = ContainerBaseSchema.extend({
     type: z36.literal("array"),
     fields: z36.array(AnyFieldSchema),
-    // Explicitly forbid logic on arrays
-    logic: z36.never().optional(),
+    logic: z36.array(ContainerLogicSchema).optional(),
+    // Full API does not use template
     template: z36.never().optional(),
+    // Array length validation
+    minLength: z36.number().int().min(0).optional(),
+    maxLength: z36.number().int().min(0).optional()
+  });
+  const ArrayAllowedChildSchema = z36.lazy(
+    () => AnyFieldSchema.refine((field) => field.type !== "page" && field.type !== "array", {
+      message: "Array templates cannot contain page or array fields. Only leaf fields, rows, and groups are allowed."
+    })
+  );
+  const SimplifiedArrayFieldSchema = ContainerBaseSchema.extend({
+    type: z36.literal("array"),
+    // Template: single field (primitive array) or array of fields (object array)
+    // Only ArrayAllowedChildren (leaf fields, rows, groups) are valid — no pages or nested arrays.
+    template: z36.union([ArrayAllowedChildSchema, z36.array(ArrayAllowedChildSchema)]),
+    // Initial values for the array
+    value: z36.array(z36.unknown()).optional(),
+    // Button customization or opt-out (false to disable)
+    addButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
+    removeButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
+    logic: z36.array(ContainerLogicSchema).optional(),
+    // Array length validation
+    minLength: z36.number().int().min(0).optional(),
+    maxLength: z36.number().int().min(0).optional(),
+    // Simplified API does not use fields
+    fields: z36.never().optional(),
     minItems: z36.never().optional(),
     maxItems: z36.never().optional()
   });
+  const ArrayFieldSchema = z36.union([FullArrayFieldSchema, SimplifiedArrayFieldSchema]);
   const AllFieldsSchema = AnyFieldSchema;
   return {
     PageFieldSchema,
@@ -3992,7 +4134,22 @@ var FormOptionsSchema = z37.object({
   /**
    * Options for the next button behavior (multi-page forms).
    */
-  nextButton: NextButtonOptionsSchema.optional()
+  nextButton: NextButtonOptionsSchema.optional(),
+  /**
+   * Whether to exclude values of hidden fields from submission output.
+   * Overrides the global withValueExclusionDefaults() setting for this form.
+   */
+  excludeValueIfHidden: z37.boolean().optional(),
+  /**
+   * Whether to exclude values of disabled fields from submission output.
+   * Overrides the global withValueExclusionDefaults() setting for this form.
+   */
+  excludeValueIfDisabled: z37.boolean().optional(),
+  /**
+   * Whether to exclude values of readonly fields from submission output.
+   * Overrides the global withValueExclusionDefaults() setting for this form.
+   */
+  excludeValueIfReadonly: z37.boolean().optional()
 });
 
 // internal/dynamic-forms-zod/src/lib/schemas/form/schema-definition.schema.ts
@@ -4889,13 +5046,11 @@ var PROPERTY_GUIDANCE = {
   maxValue: "maxValue should be at FIELD level, not inside props",
   step: "step should be at FIELD level, not inside props (for slider)",
   fields: "fields should be at FIELD level, contains child fields for containers",
-  template: 'Use "fields" instead of "template" for array items',
+  template: "Arrays support two APIs: (1) Full API with `fields` for explicit item definitions, or (2) Simplified API with `template` + `value` for common cases. `fields` and `template` are mutually exclusive.",
   label: "Container types (row, group, array, page) do NOT have a label property",
   title: "Page fields do NOT have a title property",
-  minItems: "Array fields do NOT have minItems/maxItems properties",
-  maxItems: "Array fields do NOT have minItems/maxItems properties",
   expressions: 'Use "derivation" or "logic" instead of "expressions"',
-  logic: "Only PAGE and LEAF fields support logic blocks. Row, group, and array containers do NOT support logic - apply logic to their child fields instead"
+  logic: 'Container fields (page, group, row, array) only support the "hidden" logic type. For other logic types (disabled, required, readonly, derivation), apply them to child fields instead'
 };
 var DID_YOU_MEAN = {
   hideWhen: 'Did you mean `logic: [{ type: "hidden", condition: {...} }]`? There is no hideWhen shorthand.',
@@ -4914,7 +5069,7 @@ var DID_YOU_MEAN = {
   min: "Did you mean `minValue` at field level (for slider) or `min` shorthand validator (for numbers)?",
   max: "Did you mean `maxValue` at field level (for slider) or `max` shorthand validator (for numbers)?",
   items: "Did you mean `options` for select/radio/multi-checkbox, or `fields` for array containers?",
-  template: "Did you mean `fields`? Arrays use `fields` to define the template for each item.",
+  template: "Arrays support `template` (simplified API) or `fields` (full API). If using `template`, also provide `value` for initial data. They are mutually exclusive - do not use both.",
   element: 'Did you mean `props: { elementType: "..." }`? For text fields, use elementType inside props.',
   content: "Did you mean `label`? For text fields, the content goes in the label property.",
   title: 'Did you mean to use a `text` field with `label: "..." and props: { elementType: "h1" }`? Pages don\'t have titles.',
@@ -4963,11 +5118,24 @@ function formatZodError(error, config) {
                 mistakes.push("Use minValue/maxValue/step at field level, not min/max/step in props");
               }
             }
-            if (["array", "group", "row", "page"].includes(fieldType) && "template" in field) {
+            if (["group", "row", "page"].includes(fieldType) && "template" in field) {
               mistakes.push('Use "fields" instead of "template"');
             }
+            if (fieldType === "array" && "template" in field && "fields" in field) {
+              mistakes.push('"fields" and "template" are mutually exclusive on arrays. Use one or the other.');
+            }
             if (["row", "group", "array"].includes(fieldType) && "logic" in field) {
-              mistakes.push(`"${fieldType}" containers do NOT support logic blocks - apply logic to individual child fields instead`);
+              const logicArr = field["logic"];
+              if (Array.isArray(logicArr)) {
+                const nonHidden = logicArr.filter(
+                  (l) => l && typeof l === "object" && l["type"] !== "hidden"
+                );
+                if (nonHidden.length > 0) {
+                  mistakes.push(
+                    `"${fieldType}" containers only support 'hidden' logic type - for other logic types, apply to child fields instead`
+                  );
+                }
+              }
             }
             if (fieldType === "hidden") {
               if (!("value" in field)) {
@@ -4981,6 +5149,7 @@ function formatZodError(error, config) {
             }
             for (const [wrongProp, suggestion] of Object.entries(DID_YOU_MEAN)) {
               if (wrongProp in field) {
+                if (wrongProp === "template" && fieldType === "array") continue;
                 mistakes.push(suggestion);
               }
             }
@@ -5159,7 +5328,7 @@ var EXPECTED_STRUCTURE = {
   slider: `{ key: 'fieldKey', type: 'slider', label: 'Label', minValue: 0, maxValue: 100, step: 1 }`,
   row: `{ key: 'rowKey', type: 'row', fields: [...childFields] }`,
   group: `{ key: 'groupKey', type: 'group', fields: [...childFields] }`,
-  array: `{ key: 'arrayKey', type: 'array', fields: [...templateFields] }`,
+  array: `Full API: { key: 'arrayKey', type: 'array', fields: [...itemDefs] } OR Simplified API: { key: 'arrayKey', type: 'array', template: { type: 'input', label: 'Item' }, value: [] }`,
   page: `{ key: 'pageKey', type: 'page', fields: [...childFields, { key: 'next', type: 'next', label: 'Next' }] }`
 };
 function preValidateConfig(config) {
@@ -5216,6 +5385,9 @@ function preValidateConfig(config) {
       }
       for (const prop of CONTAINER_FORBIDDEN_PROPS) {
         if (prop in f) {
+          if (prop === "value" && fieldType === "array" && "template" in f) {
+            continue;
+          }
           const expected = EXPECTED_STRUCTURE[fieldType || ""] || "";
           errors.push({
             path: `${path}.${prop}`,
@@ -5223,11 +5395,17 @@ function preValidateConfig(config) {
           });
         }
       }
-      if ("logic" in f) {
-        errors.push({
-          path: `${path}.logic`,
-          message: `"${fieldType}" containers do NOT support logic blocks. Only PAGE and LEAF fields (input, select, etc.) support logic. Apply logic to individual child fields instead.`
-        });
+      if ("logic" in f && Array.isArray(f["logic"])) {
+        const nonHiddenLogic = f["logic"].filter(
+          (l) => l && typeof l === "object" && l["type"] !== "hidden"
+        );
+        if (nonHiddenLogic.length > 0) {
+          const invalidTypes = nonHiddenLogic.map((l) => `"${l["type"]}"`).join(", ");
+          errors.push({
+            path: `${path}.logic`,
+            message: `"${fieldType}" containers only support 'hidden' logic type. Found unsupported logic types: ${invalidTypes}. For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.`
+          });
+        }
       }
     }
     if (fieldType === "page") {
@@ -5327,7 +5505,7 @@ function preValidateConfig(config) {
         });
       }
     }
-    if (["row", "group", "array", "page"].includes(fieldType || "")) {
+    if (["row", "group", "page"].includes(fieldType || "")) {
       if (!("fields" in f)) {
         errors.push({
           path: `${path}.fields`,
@@ -5340,12 +5518,42 @@ function preValidateConfig(config) {
         });
       }
     }
+    if (fieldType === "array") {
+      const hasFields = "fields" in f;
+      const hasTemplate = "template" in f;
+      if (hasFields && hasTemplate) {
+        errors.push({
+          path,
+          message: `Array "${fieldKey || "unknown"}" has BOTH "fields" and "template". These are mutually exclusive. Use "fields" for the full API or "template" + "value" for the simplified API. ${EXPECTED_STRUCTURE["array"]}`
+        });
+      } else if (!hasFields && !hasTemplate) {
+        errors.push({
+          path,
+          message: `Array "${fieldKey || "unknown"}" is MISSING both "fields" and "template". Use "fields" (full API) or "template" + "value" (simplified API). ${EXPECTED_STRUCTURE["array"]}`
+        });
+      } else if (hasFields && !Array.isArray(f["fields"])) {
+        errors.push({
+          path: `${path}.fields`,
+          message: `Array "${fieldKey || "unknown"}" has invalid "fields" - must be an array of field objects, not ${typeof f["fields"]}.`
+        });
+      }
+    }
     const childFields = f["fields"];
     if (Array.isArray(childFields)) {
       childFields.forEach((child, idx) => {
         checkField(child, `${path}.fields[${idx}]`, fieldType);
       });
     }
+    if (fieldType === "array" && "template" in f) {
+      const template = f["template"];
+      if (Array.isArray(template)) {
+        template.forEach((child, idx) => {
+          checkField(child, `${path}.template[${idx}]`, fieldType);
+        });
+      } else if (template && typeof template === "object") {
+        checkField(template, `${path}.template`, fieldType);
+      }
+    }
   }
   fields.forEach((field, idx) => {
     checkField(field, `fields[${idx}]`, void 0);
@@ -5720,14 +5928,15 @@ Included in form value but not rendered.
     brief: `\`\`\`typescript
 { key: 'address', type: 'group', fields: [{ key: 'city', type: 'input', label: 'City' }] }
 \`\`\`
-\u26A0\uFE0F **NO label, NO logic** - creates nested object { address: { city: '...' } }`,
+\u26A0\uFE0F **NO label** - supports only \`hidden\` logic - creates nested object { address: { city: '...' } }`,
     full: `# Group Container (Nested Object)
 
 \`\`\`typescript
 {
   key: 'address',
   type: 'group',
-  // \u26A0\uFE0F NO LABEL! NO LOGIC!
+  // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
+  logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showAddress', operator: 'equals', value: false } }],
   fields: [
     { key: 'street', type: 'input', label: 'Street' },
     { key: 'city', type: 'input', label: 'City' }
@@ -5738,7 +5947,7 @@ Included in form value but not rendered.
 
 **\u26A0\uFE0F Common mistakes:**
 - Adding \`label\` to group (not allowed)
-- Adding \`logic\` to group (apply to child fields instead)
+- Using non-hidden logic types on group (only \`hidden\` is supported, apply other logic types to child fields instead)
 
 **Can contain:** rows, leaf fields (NOT pages, NOT nested groups)`
   },
@@ -5746,14 +5955,15 @@ Included in form value but not rendered.
     brief: `\`\`\`typescript
 { key: 'nameRow', type: 'row', fields: [{ key: 'first', type: 'input', label: 'First', col: 6 }, { key: 'last', type: 'input', label: 'Last', col: 6 }] }
 \`\`\`
-\u26A0\uFE0F **NO label, NO logic, NO hidden fields inside**`,
+\u26A0\uFE0F **NO label, NO hidden fields inside** - supports only \`hidden\` logic type`,
     full: `# Row Container (Horizontal Layout)
 
 \`\`\`typescript
 {
   key: 'nameRow',
   type: 'row',
-  // \u26A0\uFE0F NO LABEL! NO LOGIC!
+  // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
+  logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showNameRow', operator: 'equals', value: false } }],
   fields: [
     { key: 'firstName', type: 'input', label: 'First', col: 6 },
     { key: 'lastName', type: 'input', label: 'Last', col: 6 }
@@ -5761,7 +5971,7 @@ Included in form value but not rendered.
 }
 \`\`\`
 
-Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
+Use \`col\` (1-12) on child fields for grid width. Row is purely for layout. Supports only \`hidden\` logic type for conditional visibility.
 
 **Allowed children:** groups, arrays, value fields (input, select, checkbox, etc.)
 **NOT allowed:** \`hidden\` fields, \`page\` containers, nested \`row\` containers
@@ -5769,36 +5979,250 @@ Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
 \u26A0\uFE0F **Common mistake:** Putting hidden fields inside rows - hidden fields should be at page or form level, not in rows.`
   },
   array: {
-    brief: `\`\`\`typescript
-{ key: 'contacts', type: 'array', fields: [{ key: 'item', type: 'group', fields: [{ key: 'name', type: 'input', label: 'Name' }] }] }
-\`\`\`
-\u26A0\uFE0F Uses **fields** NOT template, **NO label, NO logic**`,
+    brief: `**Two APIs available:**
+**Simplified (recommended):** \`{ key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }\`
+**Full:** \`{ key: 'contacts', type: 'array', fields: [[{ key: 'name', type: 'input', value: 'Alice' }]] }\`
+\u26A0\uFE0F **NO label** - supports only \`hidden\` logic type. See topic \`simplified-array\` for the simplified API.`,
     full: `# Array Container (Dynamic List)
 
+Arrays support two APIs: **Simplified** (recommended for common cases) and **Full** (for advanced use cases).
+
+## Simplified API (Recommended)
+
+Use \`template\` + \`value\` for common array patterns. Add/remove buttons are auto-generated.
+
+\`\`\`typescript
+// Primitive array: ['angular', 'typescript']
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag' },
+  value: ['angular', 'typescript']
+}
+
+// Object array: [{ name: 'Jane', phone: '555' }]
+{
+  key: 'contacts',
+  type: 'array',
+  template: [
+    { key: 'name', type: 'input', label: 'Name', required: true },
+    { key: 'phone', type: 'input', label: 'Phone' }
+  ],
+  value: [{ name: 'Jane', phone: '555' }]
+}
+
+// Custom button config
+{
+  key: 'items',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Item' },
+  addButton: { label: 'Add Item', props: { color: 'primary' } },
+  removeButton: false  // Disable remove buttons
+}
+\`\`\`
+
+See topic \`simplified-array\` for full documentation on the simplified API.
+
+## Full API (Advanced)
+
+Use \`fields\` for explicit item definitions with full control.
+
 \`\`\`typescript
 {
   key: 'contacts',
   type: 'array',
-  // \u26A0\uFE0F NO LABEL! NO LOGIC! Uses 'fields', NOT 'template'!
+  // \u26A0\uFE0F NO LABEL! Supports only 'hidden' logic type.
+  logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'hasContacts', operator: 'equals', value: false } }],
   fields: [
-    {
-      key: 'contactItem',
-      type: 'group',
-      fields: [
-        { key: 'name', type: 'input', label: 'Name' },
-        { key: 'phone', type: 'input', label: 'Phone' }
-      ]
-    }
+    [
+      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
+      { key: 'phone', type: 'input', label: 'Phone', value: '555' }
+    ]
   ]
 }
-// Output: { contacts: [{ name: '...', phone: '...' }, ...] }
+// Output: { contacts: [{ name: 'Alice', phone: '555' }] }
 \`\`\`
 
-**\u26A0\uFE0F Common mistakes:**
-- Using \`template\` (doesn't exist) - use \`fields\`
-- Adding \`label\` or \`logic\` to array container
+**DOM Structure:**
+Each array item is wrapped in a \`<div class="df-array-item">\` with:
+- \`role="group"\` + \`aria-label="Item N"\` (1-based) for accessibility
+- \`data-array-item-id\` (stable ID) and \`data-array-item-index\` (current position) for testing/CSS
+- Use \`--df-array-item-gap\` CSS variable to control spacing between items
+
+**Key rules:**
+- \`fields\` and \`template\` are **mutually exclusive** - use one or the other
+- NO \`label\` property on arrays
+- Only \`hidden\` logic type is supported
+- Arrays cannot contain pages or other arrays
 
 **Can contain:** rows, groups, leaf fields (NOT pages, NOT nested arrays)`
+  },
+  "simplified-array": {
+    brief: `\`\`\`typescript
+// Primitive: { key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }
+// Object: { key: 'contacts', type: 'array', template: [{ key: 'name', type: 'input' }, { key: 'phone', type: 'input' }], value: [{ name: 'Jane', phone: '555' }] }
+// Buttons: { addButton: { label: 'Add Tag', props: { color: 'primary' } }, removeButton: false }
+\`\`\`
+Discriminant: \`template\` presence = simplified API; \`Array.isArray(template)\` = object vs primitive.`,
+    full: `# Simplified Array API
+
+The simplified array API provides a concise way to define dynamic arrays using \`template\` + \`value\` instead of verbose \`fields\` definitions. Add/remove buttons are auto-generated.
+
+## When to Use
+
+Use the simplified API when:
+- You have a common primitive or object array pattern
+- You want auto-generated add/remove buttons
+- Initial values are known and simple
+
+Use the full API (\`fields\`) when:
+- You need heterogeneous items (different field configs per item)
+- You need custom button placement
+- You need explicit control over each item's structure
+
+## Primitive Array
+
+Each item is a single value (string, number, etc.):
+
+\`\`\`typescript
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag', required: true },
+  value: ['angular', 'typescript']
+}
+// Output: { tags: ['angular', 'typescript'] }
+\`\`\`
+
+**Discriminant:** \`template\` is a single field definition (not an array).
+
+## Object Array
+
+Each item is an object with multiple fields:
+
+\`\`\`typescript
+{
+  key: 'contacts',
+  type: 'array',
+  template: [
+    { key: 'name', type: 'input', label: 'Contact Name', required: true },
+    { key: 'phone', type: 'input', label: 'Phone Number' }
+  ],
+  value: [
+    { name: 'Jane Doe', phone: '555-1234' },
+    { name: 'John Smith', phone: '555-5678' }
+  ]
+}
+// Output: { contacts: [{ name: 'Jane Doe', phone: '555-1234' }, ...] }
+\`\`\`
+
+**Discriminant:** \`template\` is an array of field definitions.
+
+## Button Configuration
+
+### Custom Add Button
+\`\`\`typescript
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag' },
+  addButton: {
+    label: 'Add New Tag',
+    props: { color: 'primary' }
+  }
+}
+\`\`\`
+
+### Custom Remove Button
+\`\`\`typescript
+{
+  key: 'items',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Item' },
+  removeButton: {
+    label: 'Delete',
+    props: { color: 'warn' }
+  }
+}
+\`\`\`
+
+### Disable Buttons
+\`\`\`typescript
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag' },
+  addButton: false,     // No add button
+  removeButton: false   // No remove button per item
+}
+\`\`\`
+
+## ArrayButtonConfig Interface
+
+\`\`\`typescript
+interface ArrayButtonConfig {
+  label?: string;                    // Custom button label
+  props?: Record<string, unknown>;   // Additional button component properties
+}
+\`\`\`
+
+## SimplifiedArrayField Interface
+
+\`\`\`typescript
+interface SimplifiedArrayField {
+  type: 'array';
+  key: string;
+  template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];  // Item structure
+  value?: readonly unknown[];         // Initial values
+  addButton?: ArrayButtonConfig | false;    // Add button config (default: { label: 'Add' })
+  removeButton?: ArrayButtonConfig | false; // Remove button config (default: { label: 'Remove' })
+  logic?: ContainerLogicConfig[];     // Only 'hidden' type supported
+  // label is NOT supported
+  // fields is NOT supported (mutually exclusive with template)
+}
+\`\`\`
+
+## How It Works Internally
+
+The simplified API is normalized into the full API at runtime:
+1. Each \`value\` element creates an item using the \`template\` structure
+2. An \`addArrayItem\` button is auto-generated after the array (unless \`addButton: false\`)
+3. A \`removeArrayItem\` button is added to each item (unless \`removeButton: false\`)
+
+## Conditional Visibility
+
+\`\`\`typescript
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag' },
+  logic: [{
+    type: 'hidden',
+    condition: { type: 'fieldValue', fieldPath: 'hasTags', operator: 'equals', value: false }
+  }]
+}
+\`\`\`
+
+## Common Mistakes
+
+\u274C Mixing \`fields\` and \`template\`:
+\`\`\`typescript
+// WRONG - mutually exclusive
+{ type: 'array', fields: [...], template: {...} }
+
+// CORRECT - use one or the other
+{ type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a'] }
+{ type: 'array', fields: [{ key: 'tag', type: 'input', value: 'a' }] }
+\`\`\`
+
+\u274C Wrong value shape for object templates:
+\`\`\`typescript
+// WRONG - value should match template keys
+{ template: [{ key: 'name', type: 'input' }], value: ['Jane'] }
+
+// CORRECT - value elements are objects matching template keys
+{ template: [{ key: 'name', type: 'input' }], value: [{ name: 'Jane' }] }
+\`\`\``
   },
   page: {
     brief: `\`\`\`typescript
@@ -5875,7 +6299,7 @@ Use \`col\` (1-12) on child fields for grid width. Row is purely for layout.
 
 **Async validators:**
 \`\`\`typescript
-validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
+validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
 \`\`\`
 
 **Custom error messages (validationMessages at FIELD level):**
@@ -5962,10 +6386,16 @@ See topic \`external-data\` for full documentation.`
 
 // Logic block (for conditions, debounce, etc.)
 logic: [{ type: 'derivation', expression: 'formValue.firstName + " " + formValue.lastName' }]
+
+// Stop on user edit (with optional re-engagement)
+logic: [{ type: 'derivation', expression: '...', stopOnUserOverride: true, reEngageOnDependencyChange: true }]
+
+// HTTP derivation (server-driven values)
+logic: [{ type: 'derivation', source: 'http', http: { url: '/api/rate', queryParams: { from: 'formValue.currency' } }, responseExpression: 'response.rate', dependsOn: ['currency'] }]
 \`\`\`
 Derivation is always defined ON the field that receives the computed value (self-targeting).
-**Variables:** \`formValue\`, \`fieldValue\`, \`externalData\` (see topic: external-data)
-**For deriving component properties** (minDate, options, label): see topic \`property-derivation\``,
+**Variables:** \`formValue\`, \`fieldValue\`, \`fieldState\`, \`formFieldState\`, \`externalData\` (see topic: expression-variables)
+**For deriving component properties** (minDate, options, label): use \`targetProperty\` (see topic \`property-derivation\`)`,
     full: `# Value Derivation (Computed Fields)
 
 Derivations are always defined ON the field that receives the computed value (self-targeting).
@@ -6027,44 +6457,175 @@ Derivations are always defined ON the field that receives the computed value (se
 }
 \`\`\`
 
-**Variables in expressions:**
-- \`formValue\`: Complete form value object
-- \`fieldValue\`: This field's current value
-- \`externalData\`: External application state (user roles, feature flags, etc.)
+## HTTP Derivation (Server-Driven Values)
 
-**Nested access:**
-\`\`\`typescript
-derivation: 'formValue.address?.city'                    // Optional chaining
-derivation: 'formValue.items?.[0]?.name'                // Array access
-derivation: 'formValue.discount ?? 0'                   // Nullish coalescing
-derivation: 'formValue.price * (1 - externalData.discountRate)'  // External data
-\`\`\`
+Fetch derived values from an HTTP endpoint. Requires \`dependsOn\` (explicit) and \`responseExpression\`.
 
-**Complex logic (IIFE):**
 \`\`\`typescript
-derivation: \`(() => {
-  const qty = formValue.quantity || 0;
-  const price = formValue.unitPrice || 0;
-  return qty * price;
-})()\`
+{
+  key: 'exchangeRate',
+  type: 'input',
+  label: 'Exchange Rate',
+  readonly: true,
+  logic: [{
+    type: 'derivation',
+    source: 'http',
+    http: {
+      url: '/api/exchange-rate',
+      method: 'GET',
+      queryParams: {
+        from: 'formValue.sourceCurrency',
+        to: 'formValue.targetCurrency'
+      }
+    },
+    responseExpression: 'response.rate',  // Extract value from response
+    dependsOn: ['sourceCurrency', 'targetCurrency'],  // Required for HTTP
+    trigger: 'debounced',
+    debounceMs: 500  // Optional, defaults to 300
+  }]
+}
 \`\`\`
 
-**See also:** \`property-derivation\` topic for deriving component properties (minDate, options, label, etc.)`
-  },
-  "options-format": {
-    brief: `\`\`\`typescript
-options: [{ label: 'Display Text', value: 'actual-value' }]  // AT FIELD LEVEL!
-\`\`\`
-\u26A0\uFE0F **NOT in props**, NOT just strings, MUST have label+value`,
-    full: `# Options Format (select, radio, multi-checkbox)
+**Key rules:**
+- \`source: 'http'\` is **required** to select HTTP derivation mode
+- \`dependsOn\` is **required** (prevents wildcard triggering on every keystroke)
+- \`responseExpression\` is **required** (extracts value from HTTP response body)
+- \`queryParams\` values are expressions evaluated by ExpressionParser
+- Requests are automatically debounced and cancelled (switchMap)
+- HTTP errors are caught and logged (stream continues)
+- Array fields (\`items.$.rate\`) are NOT supported for HTTP derivations
+- Works with \`stopOnUserOverride\` and \`condition\`
 
-**Required Format:**
-Options MUST be an array of objects with \`label\` and \`value\` at **FIELD level**:
+## Async Derivation (Custom Async Functions)
+
+Call a registered async function (Promise or Observable) to derive values. Requires \`dependsOn\` (explicit).
 
 \`\`\`typescript
 {
-  key: 'country',
-  type: 'select',
+  key: 'suggestedPrice',
+  type: 'input',
+  label: 'Suggested Price',
+  readonly: true,
+  logic: [{
+    type: 'derivation',
+    source: 'asyncFunction',
+    asyncFunctionName: 'fetchSuggestedPrice',
+    dependsOn: ['productId', 'quantity']  // Required for async
+  }]
+}
+\`\`\`
+
+Register the function in \`customFnConfig.asyncDerivations\`:
+
+\`\`\`typescript
+customFnConfig: {
+  asyncDerivations: {
+    fetchSuggestedPrice: async (context) => {
+      const response = await fetch(\`/api/price?product=\${context.formValue.productId}\`);
+      const data = await response.json();
+      return data.suggestedPrice;
+    },
+    // Observable-based alternative
+    lookupAddress: (context) => {
+      return addressService.lookup(context.formValue.zipCode).pipe(
+        map(result => result.formattedAddress)
+      );
+    },
+  }
+}
+\`\`\`
+
+**Key rules:**
+- \`asyncFunctionName\` is mutually exclusive with \`expression\`, \`value\`, \`functionName\`, and \`http\`
+- \`dependsOn\` is **required** (prevents triggering on every form change)
+- Wildcards (\`'*'\`) are **not allowed** in \`dependsOn\`
+- The function returns the value directly (no \`responseExpression\` needed)
+- Functions handle their own I/O (no HttpClient provided)
+- Requests are automatically debounced and cancelled (switchMap)
+- Errors are caught and logged (previous value retained)
+- Array fields (\`items.$.rate\`) are NOT supported
+- Works with \`stopOnUserOverride\` and \`condition\`
+
+## Stop on User Override
+
+When \`stopOnUserOverride: true\`, the derivation stops running after the user manually edits the target field:
+
+\`\`\`typescript
+{
+  key: 'fullName',
+  type: 'input',
+  label: 'Full Name',
+  logic: [{
+    type: 'derivation',
+    expression: 'formValue.firstName + " " + formValue.lastName',
+    stopOnUserOverride: true  // Derivation stops after user manually edits fullName
+  }]
+}
+\`\`\`
+
+### Re-engagement on Dependency Change
+
+Combine \`reEngageOnDependencyChange: true\` with \`stopOnUserOverride\` to clear user overrides when dependencies change:
+
+\`\`\`typescript
+{
+  key: 'fullName',
+  type: 'input',
+  label: 'Full Name',
+  logic: [{
+    type: 'derivation',
+    expression: 'formValue.firstName + " " + formValue.lastName',
+    stopOnUserOverride: true,
+    reEngageOnDependencyChange: true  // Clears user override when firstName/lastName changes
+  }]
+}
+\`\`\`
+
+**Use cases:**
+- Allow users to customize computed values
+- Reset customizations when source data changes
+- Smart defaults that defer to user input
+
+**Variables in expressions:**
+- \`formValue\`: Complete form value object
+- \`fieldValue\`: This field's current value
+- \`fieldState\`: Current field's state (touched, dirty, valid, etc.)
+- \`formFieldState\`: All fields' states keyed by field key
+- \`externalData\`: External application state (user roles, feature flags, etc.)
+
+**Nested access:**
+\`\`\`typescript
+derivation: 'formValue.address?.city'                    // Optional chaining
+derivation: 'formValue.items?.[0]?.name'                // Array access
+derivation: 'formValue.discount ?? 0'                   // Nullish coalescing
+derivation: 'formValue.price * (1 - externalData.discountRate)'  // External data
+\`\`\`
+
+**Complex logic (IIFE):**
+\`\`\`typescript
+derivation: \`(() => {
+  const qty = formValue.quantity || 0;
+  const price = formValue.unitPrice || 0;
+  return qty * price;
+})()\`
+\`\`\`
+
+**See also:** \`property-derivation\` topic for deriving component properties (minDate, options, label, etc.)`
+  },
+  "options-format": {
+    brief: `\`\`\`typescript
+options: [{ label: 'Display Text', value: 'actual-value' }]  // AT FIELD LEVEL!
+\`\`\`
+\u26A0\uFE0F **NOT in props**, NOT just strings, MUST have label+value`,
+    full: `# Options Format (select, radio, multi-checkbox)
+
+**Required Format:**
+Options MUST be an array of objects with \`label\` and \`value\` at **FIELD level**:
+
+\`\`\`typescript
+{
+  key: 'country',
+  type: 'select',
   label: 'Country',
   options: [                              // \u2705 AT FIELD LEVEL!
     { label: 'United States', value: 'us' },
@@ -6093,6 +6654,8 @@ Wrong: Wrong property names
   "expression-variables": {
     brief: `**formValue** - complete form object: \`formValue.fieldName\`, \`formValue.address?.city\`
 **fieldValue** - current field's value (in custom validators)
+**fieldState** - current field state: \`fieldState.touched\`, \`fieldState.valid\`, \`fieldState.dirty\`
+**formFieldState** - all field states: \`formFieldState.email.valid\`, \`formFieldState.password.pristine\`
 **externalData** - external signals: \`externalData.userRole\`, \`externalData.featureFlags.enabled\``,
     full: `# Variables in Expressions
 
@@ -6102,6 +6665,8 @@ Wrong: Wrong property names
 |----------|------|--------------|-------------|
 | \`formValue\` | object | Derivations, conditions, custom validators | Complete form values as nested object |
 | \`fieldValue\` | any | Custom validator expressions only | Current field's value |
+| \`fieldState\` | object | Derivations, conditions | Current field's state (touched, dirty, valid, etc.) |
+| \`formFieldState\` | object | Derivations, conditions | All fields' states keyed by field key |
 | \`externalData\` | object | Derivations, conditions | External application state (from \`externalData\` in FormConfig) |
 
 ## Accessing Values
@@ -6124,6 +6689,56 @@ expression: 'formValue.contacts?.[0]?.name'
 expression: '(formValue.items?.length || 0) + " items"'
 \`\`\`
 
+### Field State Access
+
+\`fieldState\` provides access to the current field's state properties:
+
+\`\`\`typescript
+// Check if current field has been touched
+expression: 'fieldState.touched ? "Modified" : "Untouched"'
+
+// Check if current field is valid
+expression: 'fieldState.valid && formValue.email'
+
+// Check if current field is dirty
+expression: 'fieldState.dirty ? "Changed from initial" : "Unchanged"'
+\`\`\`
+
+**Available \`fieldState\` properties:**
+- \`touched\`: boolean - Field has been focused and blurred
+- \`dirty\`: boolean - Value differs from initial value
+- \`pristine\`: boolean - Value matches initial value
+- \`valid\`: boolean - No validation errors
+- \`invalid\`: boolean - Has validation errors
+- \`pending\`: boolean - Async validation in progress
+- \`hidden\`: boolean - Field is currently hidden
+- \`readonly\`: boolean - Field is currently readonly
+- \`disabled\`: boolean - Field is currently disabled
+
+### Form Field State Access
+
+\`formFieldState\` provides access to any field's state by key:
+
+\`\`\`typescript
+// Check if email field is valid
+expression: 'formFieldState.email?.valid'
+
+// Conditional logic based on multiple field states
+expression: 'formFieldState.password?.valid && formFieldState.confirmPassword?.touched'
+
+// Check if any field is invalid
+expression: '!formFieldState.email?.valid || !formFieldState.password?.valid'
+\`\`\`
+
+**Nested field paths:**
+\`\`\`typescript
+// Access nested group field state
+expression: 'formFieldState["address.city"]?.dirty'
+
+// Access array item field state
+expression: 'formFieldState["contacts.0.name"]?.valid'
+\`\`\`
+
 ### External Data Access
 \`\`\`typescript
 expression: "externalData.userRole === 'admin'"
@@ -6131,19 +6746,37 @@ expression: 'externalData.featureFlags.advancedMode === true'
 expression: 'externalData.permissions.includes("edit")'
 \`\`\`
 
+## Common Patterns
+
+### Conditional derivation based on field state
+\`\`\`typescript
+// Only compute if other field is valid
+expression: 'formFieldState.email?.valid ? formValue.email.toLowerCase() : ""'
+
+// Show warning if field is touched but invalid
+expression: 'fieldState.touched && fieldState.invalid ? "Please fix errors" : ""'
+\`\`\`
+
+### Validation-aware derivations
+\`\`\`typescript
+// Only use value if source field is valid
+expression: 'formFieldState.price?.valid ? formValue.price * 1.2 : null'
+\`\`\`
+
 ## Safety Tips
 
-1. **Always use optional chaining** (\`?.\`) for nested paths
+1. **Always use optional chaining** (\`?.\`) for nested paths and field state access
 2. **Provide defaults** for potentially undefined values: \`formValue.count || 0\`
-3. **Use nullish coalescing** (\`??\`) when 0 or empty string are valid: \`formValue.score ?? 'N/A'\``
+3. **Use nullish coalescing** (\`??\`) when 0 or empty string are valid: \`formValue.score ?? 'N/A'\`
+4. **Check field existence** when using \`formFieldState\`: \`formFieldState.fieldKey?.valid\``
   },
   "property-derivation": {
     brief: `\`\`\`typescript
 // Derive endDate's minDate from startDate value
-logic: [{ type: 'propertyDerivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
+logic: [{ type: 'derivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
 
 // Derive select options from another field
-logic: [{ type: 'propertyDerivation', targetProperty: 'options', functionName: 'getCitiesForCountry', dependsOn: ['country'] }]
+logic: [{ type: 'derivation', targetProperty: 'options', functionName: 'getCitiesForCountry', dependsOn: ['country'] }]
 \`\`\`
 Unlike value derivation (which sets the field's **value**), property derivation sets **component input properties** like minDate, options, label, placeholder, props.appearance.`,
     full: `# Property Derivation (Dynamic Field Properties)
@@ -6160,7 +6793,7 @@ Property derivations are self-targeting: the logic is placed on the field whose
   type: 'datepicker',
   label: 'End Date',
   logic: [{
-    type: 'propertyDerivation',
+    type: 'derivation',
     targetProperty: 'minDate',
     expression: 'formValue.startDate',
   }]
@@ -6174,7 +6807,7 @@ When \`startDate\` changes, the \`minDate\` property on the \`endDate\` datepick
 ### Expression-Based
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'minDate',
   expression: 'formValue.startDate',
 }]
@@ -6183,7 +6816,7 @@ logic: [{
 ### Static Value
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'label',
   value: 'Mobile Phone',
   condition: { type: 'fieldValue', fieldPath: 'contactType', operator: 'equals', value: 'mobile' },
@@ -6194,7 +6827,7 @@ logic: [{
 \`\`\`typescript
 // Register in customFnConfig
 customFnConfig: {
-  propertyDerivations: {
+  derivations: {
     getCitiesForCountry: (ctx) => {
       const cities = { 'US': [{ label: 'NYC', value: 'nyc' }], 'DE': [{ label: 'Berlin', value: 'berlin' }] };
       return cities[ctx.formValue.country as string] ?? [];
@@ -6208,7 +6841,7 @@ customFnConfig: {
   type: 'select',
   label: 'City',
   logic: [{
-    type: 'propertyDerivation',
+    type: 'derivation',
     targetProperty: 'options',
     functionName: 'getCitiesForCountry',
     dependsOn: ['country'],
@@ -6235,7 +6868,7 @@ customFnConfig: {
 
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'options',
   functionName: 'searchProducts',
   trigger: 'debounced',
@@ -6248,7 +6881,7 @@ logic: [{
 
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'label',
   value: 'Company Email',
   condition: { type: 'fieldValue', fieldPath: 'accountType', operator: 'equals', value: 'business' },
@@ -6272,7 +6905,7 @@ Inside arrays, \`formValue\` is scoped to the current array item:
         type: 'datepicker',
         label: 'End',
         logic: [{
-          type: 'propertyDerivation',
+          type: 'derivation',
           targetProperty: 'minDate',
           expression: 'formValue.startDate',  // Scoped to current array item
         }]
@@ -6287,17 +6920,17 @@ Inside arrays, \`formValue\` is scoped to the current array item:
 | Aspect | Value Derivation | Property Derivation |
 |--------|-----------------|---------------------|
 | Sets | Field's form value | Component input property |
-| Type | \`type: 'derivation'\` | \`type: 'propertyDerivation'\` |
+| Type | \`type: 'derivation'\` | \`type: 'derivation'\` |
 | Target | Implicit (self) | \`targetProperty: 'minDate'\` |
 | Shorthand | \`derivation: 'expr'\` | None (must use logic block) |
 | Chaining | Topologically sorted | No chaining (single pass) |
-| Functions | \`customFnConfig.derivations\` | \`customFnConfig.propertyDerivations\` |
+| Functions | \`customFnConfig.derivations\` | \`customFnConfig.derivations\` |
 
-## PropertyDerivationLogicConfig Interface
+## DerivationLogicConfig Interface (with targetProperty)
 
 \`\`\`typescript
-interface PropertyDerivationLogicConfig {
-  type: 'propertyDerivation';
+interface DerivationLogicConfig {
+  type: 'derivation';
   targetProperty: string;               // Property to set (e.g., 'minDate', 'options')
   debugName?: string;                   // For logging/debugging
   condition?: ConditionalExpression | boolean;  // When to apply (default: true)
@@ -6409,7 +7042,7 @@ logic: [{
   },
   "async-validators": {
     brief: `\`\`\`typescript
-validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
+validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
 \`\`\`
 Define function, register in provideDynamicForm, use in config.`,
     full: `# Async Validators (Complete Example)
@@ -6449,7 +7082,7 @@ provideDynamicForm({
   type: 'input',
   label: 'Email',
   validators: [
-    { type: 'customAsync', functionName: 'checkEmailAvailable' }
+    { type: 'async', functionName: 'checkEmailAvailable' }
   ],
   validationMessages: { emailTaken: 'This email is already registered' }
 }
@@ -6543,16 +7176,16 @@ validators: [{
   },
   // ========== PATTERNS & RULES ==========
   "logic-matrix": {
-    brief: `**Containers:** group/row/array have NO logic (apply to children)
-**Page:** hidden only | **Value fields:** all logic types incl. propertyDerivation | **Buttons:** hidden, disabled`,
+    brief: `**Containers:** group/row/array support only \`hidden\` logic (same as pages). For other logic types, apply to children.
+**Page:** hidden only | **Value fields:** all logic types incl. derivation + targetProperty | **Buttons:** hidden, disabled`,
     full: `# Logic Support Matrix
 
-| Field Type     | hidden | disabled | required | readonly | derivation | propertyDerivation |
+| Field Type     | hidden | disabled | required | readonly | derivation | derivation+targetProperty |
 |----------------|--------|----------|----------|----------|------------|--------------------|
 | page           |   Y    |    N     |    N     |    N     |     N      |         N          |
-| group          |   N    |    N     |    N     |    N     |     N      |         N          |
-| row            |   N    |    N     |    N     |    N     |     N      |         N          |
-| array          |   N    |    N     |    N     |    N     |     N      |         N          |
+| group          |   Y    |    N     |    N     |    N     |     N      |         N          |
+| row            |   Y    |    N     |    N     |    N     |     N      |         N          |
+| array          |   Y    |    N     |    N     |    N     |     N      |         N          |
 | input          |   Y    |    Y     |    Y     |    Y     |     Y      |         Y          |
 | select         |   Y    |    Y     |    Y     |    Y     |     Y      |         Y          |
 | checkbox       |   Y    |    Y     |    Y     |    Y     |     Y      |         Y          |
@@ -6568,12 +7201,12 @@ validators: [{
 | next/previous  |   Y    |    Y     |    N     |    N     |     N      |         N          |
 
 **Key takeaways:**
-- Containers (group, row, array) do NOT support logic - apply to children instead
+- Containers (group, row, array) support only \`hidden\` logic type (same as pages) for conditional visibility. For other logic types, apply to child fields instead.
 - Page only supports \`hidden\` logic (for conditional pages)
 - Hidden fields have NO logic support at all
-- Value fields (input, select, etc.) support ALL logic types including \`propertyDerivation\`
-- \`propertyDerivation\` sets component input properties (e.g., \`minDate\`, \`options\`), NOT the field's form value
-- Text (display) fields support \`propertyDerivation\` for dynamic labels`
+- Value fields (input, select, etc.) support ALL logic types including \`derivation\` with \`targetProperty\`
+- \`derivation\` with \`targetProperty\` sets component input properties (e.g., \`minDate\`, \`options\`), NOT the field's form value
+- Text (display) fields support \`derivation\` with \`targetProperty\` for dynamic labels`
   },
   "context-api": {
     brief: `**Expressions:** \`formValue.field\`, \`fieldValue\`
@@ -6626,20 +7259,21 @@ provideDynamicForm({
     brief: `| Container | Label? | Logic? | Notes |
 |-----------|--------|--------|-------|
 | page | NO | hidden only | Nav buttons INSIDE |
-| group | NO | NO | Creates nested object |
-| array | NO | NO | Uses \`fields\` not \`template\` |
-| row | NO | NO | Layout only, no hidden fields |`,
+| group | NO | hidden only | Creates nested object |
+| array | NO | hidden only | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
+| row | NO | hidden only | Layout only, no hidden fields |`,
     full: `# Container Rules
 
 | Container | Label? | Logic? | Allowed Children | Notes |
 |-----------|--------|--------|------------------|-------|
 | page | NO | YES (hidden only) | rows, groups, arrays, leaf fields, buttons | Nav buttons go INSIDE |
-| group | NO | NO | rows, leaf fields (NOT pages, groups) | Creates nested object |
-| array | NO | NO | rows, groups, leaf fields (NOT pages, arrays) | Uses \`fields\`, not \`template\` |
-| row | NO | NO | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
+| group | NO | YES (hidden only) | rows, leaf fields (NOT pages, groups) | Creates nested object |
+| array | NO | YES (hidden only) | rows, groups, leaf fields (NOT pages, arrays) | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
+| row | NO | YES (hidden only) | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
 
 **CRITICAL:**
-- If you need conditional visibility for a container, apply logic to each CHILD field instead.
+- All containers (page, group, row, array) support only the \`hidden\` logic type for conditional visibility.
+- For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.
 - Hidden fields cannot be inside rows - place them at page/form level.
 - Pages cannot be nested - ALL top-level fields must be pages if using multi-page mode.`
   },
@@ -6838,9 +7472,10 @@ const formConfig = {
   pitfalls: {
     brief: `1. Hidden field missing \`value\` - REQUIRED!
 2. Hidden field with label/logic/validators - FORBIDDEN!
-3. Container (group/row/array) with logic - apply to children!
+3. Container (group/row/array) only supports 'hidden' logic - other types go on children!
 4. options/minValue/maxValue in props - must be at FIELD level!
-5. Generic button without \`event\` - use submit/next/previous!`,
+5. Generic button without \`event\` - use submit/next/previous!
+6. Array: \`fields\` and \`template\` are mutually exclusive - use one or the other!`,
     full: `# Common Pitfalls & Solutions
 
 ## 1. Hidden field missing value property
@@ -6868,16 +7503,17 @@ const formConfig = {
 { key: 'userId', type: 'hidden', value: '123' }  // \u2705
 \`\`\`
 
-## 3. Container fields don't support logic
+## 3. Containers only support 'hidden' logic
 \`\`\`typescript
-// WRONG - logic on group/row/array
-{ type: 'group', logic: [...] }  // \u274C TypeScript error!
+// WRONG - non-hidden logic on group/row/array
+{ type: 'group', logic: [{ type: 'disabled', condition: {...} }] }  // \u274C
 
-// CORRECT - apply logic to child fields
+// CORRECT - containers support 'hidden' logic for conditional visibility
 {
   type: 'group',
+  logic: [{ type: 'hidden', condition: { type: 'fieldValue', fieldPath: 'showGroup', operator: 'equals', value: false } }],  // \u2705
   fields: [
-    { key: 'city', type: 'input', label: 'City', logic: [...] }  // \u2705
+    { key: 'city', type: 'input', label: 'City', logic: [...] }  // \u2705 Other logic types on children
   ]
 }
 \`\`\`
@@ -6903,13 +7539,16 @@ const formConfig = {
 { type: 'button', label: 'Click', event: MyEvent }  // \u2705
 \`\`\`
 
-## 6. Array using 'template' instead of 'fields'
+## 6. Array: 'fields' vs 'template' (two APIs)
 \`\`\`typescript
-// WRONG
-{ type: 'array', template: [...] }  // \u274C 'template' doesn't exist
+// WRONG - mixing both APIs
+{ type: 'array', fields: [...], template: {...} }  // \u274C mutually exclusive
 
-// CORRECT
-{ type: 'array', fields: [...] }    // \u2705
+// CORRECT - Simplified API (recommended for common cases)
+{ type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }  // \u2705
+
+// CORRECT - Full API (for advanced use cases)
+{ type: 'array', fields: [{ key: 'tag', type: 'input', value: 'a' }] }  // \u2705
 \`\`\`
 
 ## 7. Type annotation loses inference
@@ -6924,7 +7563,8 @@ const config = { fields: [...] } as const satisfies FormConfig;
   conditions: {
     brief: `**Operators:** equals, notEquals, greater, less, greaterOrEqual, lessOrEqual, contains, startsWith, endsWith, matches
 **Combine:** \`{ type: 'and', conditions: [...] }\` or \`{ type: 'or', conditions: [...] }\`
-**JavaScript:** \`{ type: 'javascript', expression: 'formValue.age >= 18' }\``,
+**JavaScript:** \`{ type: 'javascript', expression: 'formValue.age >= 18' }\`
+**HTTP:** \`{ type: 'http', http: { url: '/api/check', queryParams: { field: 'formValue.x' } }, responseExpression: 'response.allowed' }\``,
     full: `# Condition Operators & Patterns
 
 ## Available Operators
@@ -6980,6 +7620,85 @@ condition: {
 }
 \`\`\`
 
+## HTTP Conditions (Server-Driven)
+
+Use \`type: 'http'\` to determine field state based on HTTP responses:
+
+\`\`\`typescript
+// Check if user has permission (GET)
+condition: {
+  type: 'http',
+  http: {
+    url: '/api/permissions/check',
+    queryParams: { role: 'formValue.role' }
+  },
+  responseExpression: 'response.allowed',
+  pendingValue: false,  // visible while loading
+  cacheDurationMs: 60000,
+  debounceMs: 500  // Optional, defaults to 300
+}
+
+// Check feature flag (POST)
+condition: {
+  type: 'http',
+  http: {
+    url: '/api/feature-flags',
+    method: 'POST',
+    body: { feature: 'advancedMode' },
+    evaluateBodyExpressions: false
+  },
+  responseExpression: 'response.enabled'
+}
+\`\`\`
+
+**Properties:**
+- \`http\` (required): \`HttpRequestConfig\` \u2014 URL, method, queryParams, body, headers
+- \`responseExpression\` (optional): Expression to extract boolean from response (scope: \`{ response }\`). When omitted, \`!!response\` is used
+- \`pendingValue\` (optional, default \`false\`): Value returned while HTTP request is in-flight
+- \`cacheDurationMs\` (optional, default \`30000\`): TTL for cached responses
+- \`debounceMs\` (optional, default \`300\`): Debounce for re-evaluation when dependent form values change
+
+**Important:** HTTP conditions are resolved asynchronously via signals. They cannot be used inside \`and\`/\`or\` composites (will return \`false\` with a warning). Use them as standalone conditions.
+
+## Async Conditions (Custom Async Functions)
+
+Use \`type: 'async'\` to determine field state based on a registered async function:
+
+\`\`\`typescript
+// Check permission via custom service
+condition: {
+  type: 'async',
+  asyncFunctionName: 'checkPermission',
+  pendingValue: false,  // visible while loading
+  debounceMs: 500
+}
+\`\`\`
+
+Register the function in \`customFnConfig.asyncConditions\`:
+
+\`\`\`typescript
+customFnConfig: {
+  asyncConditions: {
+    checkPermission: async (context) => {
+      const response = await fetch(\`/api/permissions?role=\${context.formValue.role}\`);
+      const data = await response.json();
+      return data.canEdit;
+    },
+    // Observable-based alternative
+    hasFeatureFlag: (context) => {
+      return featureService.isEnabled('advancedMode').pipe(map(r => r.enabled));
+    },
+  }
+}
+\`\`\`
+
+**Properties:**
+- \`asyncFunctionName\` (required): Name of the registered async condition function
+- \`pendingValue\` (optional, default \`false\`): Value returned while async resolution is pending
+- \`debounceMs\` (optional, default \`300\`): Debounce for re-evaluation
+
+**Important:** Async conditions are resolved asynchronously via signals. They cannot be used inside \`and\`/\`or\` composites (will return \`false\` with a warning). Use them as standalone conditions.
+
 ## Button-Only Conditions
 
 Buttons support special form state conditions:
@@ -7315,6 +8034,12 @@ var TOPIC_ALIASES = {
   list: "array",
   dynamic: "array",
   repeater: "array",
+  // Simplified array aliases
+  "simplified-arrays": "simplified-array",
+  "simple-array": "simplified-array",
+  "array-template": "simplified-array",
+  "template-array": "simplified-array",
+  "array-simplified": "simplified-array",
   layout: "row",
   columns: "row",
   grid: "row",
@@ -7868,7 +8593,7 @@ Show/hide pages based on conditions:
 \`\`\``
   },
   "minimal-array": {
-    description: "Dynamic array with add/remove (~30 lines)",
+    description: "Dynamic array with simplified API (~15 lines)",
     minimal: `import { FormConfig } from '@ng-forge/dynamic-forms';
 
 const formConfig = {
@@ -7876,22 +8601,16 @@ const formConfig = {
     {
       key: 'contacts',
       type: 'array',
-      fields: [
-        {
-          key: 'item',
-          type: 'group',
-          fields: [
-            { key: 'name', type: 'input', label: 'Name', required: true },
-            { key: 'phone', type: 'input', label: 'Phone' }
-          ]
-        }
-      ]
+      template: [
+        { key: 'name', type: 'input', label: 'Name', required: true },
+        { key: 'phone', type: 'input', label: 'Phone' }
+      ],
+      value: [{ name: 'Jane', phone: '555-1234' }]
     },
-    { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
     { key: 'submit', type: 'submit', label: 'Submit' }
   ]
 } as const satisfies FormConfig;`,
-    brief: `// Dynamic array form
+    brief: `// Dynamic array form using simplified API
 import { FormConfig } from '@ng-forge/dynamic-forms';
 
 const formConfig = {
@@ -7899,67 +8618,78 @@ const formConfig = {
     {
       key: 'contacts',
       type: 'array',
-      // \u26A0\uFE0F NO LABEL! Uses 'fields', NOT 'template'
-      fields: [
-        {
-          key: 'item',
-          type: 'group',
-          fields: [
-            { key: 'name', type: 'input', label: 'Name', required: true },
-            { key: 'phone', type: 'input', label: 'Phone' }
-          ]
-        }
-      ]
+      // Simplified API: template + value
+      // Add/remove buttons are auto-generated!
+      template: [
+        { key: 'name', type: 'input', label: 'Name', required: true },
+        { key: 'phone', type: 'input', label: 'Phone' }
+      ],
+      value: [{ name: 'Jane', phone: '555-1234' }]
     },
-    // \u26A0\uFE0F arrayKey at FIELD level, NOT in props!
-    { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
     { key: 'submit', type: 'submit', label: 'Submit' }
   ]
 } as const satisfies FormConfig;
 
-// Output: { contacts: [{ name: '...', phone: '...' }, ...] }`,
+// Output: { contacts: [{ name: 'Jane', phone: '555-1234' }, ...] }
+
+// For primitive arrays:
+// { key: 'tags', type: 'array', template: { key: 'value', type: 'input', label: 'Tag' }, value: ['a', 'b'] }
+// Output: { tags: ['a', 'b'] }`,
     full: `# Minimal Array Form
 
-A dynamic list with add/remove functionality.
+Dynamic lists with the simplified array API. Add/remove buttons are auto-generated.
+
+## Simplified API (Recommended)
 
 \`\`\`typescript
 import { FormConfig } from '@ng-forge/dynamic-forms';
 
 const formConfig = {
   fields: [
-    // ========== ARRAY CONTAINER ==========
+    // ========== OBJECT ARRAY ==========
     {
       key: 'contacts',
       type: 'array',
-      // \u26A0\uFE0F Arrays have NO LABEL, NO LOGIC!
-      // \u26A0\uFE0F Use 'fields' property, NOT 'template'!
-      fields: [
-        {
-          key: 'item',
-          type: 'group',  // Wrapping group creates objects in the array
-          fields: [
-            { key: 'name', type: 'input', label: 'Name', required: true },
-            { key: 'phone', type: 'input', label: 'Phone' },
-            // Optional: remove button inside each item
-            // { key: 'remove', type: 'removeArrayItem', label: 'Remove' }
-          ]
-        }
-      ]
+      // template: array of fields = object items
+      template: [
+        { key: 'name', type: 'input', label: 'Name', required: true },
+        { key: 'phone', type: 'input', label: 'Phone' }
+      ],
+      // Initial values (each element creates one item)
+      value: [{ name: 'Jane', phone: '555-1234' }],
+      // Optional: customize buttons
+      addButton: { label: 'Add Contact' },
+      // removeButton: false  // disable remove buttons
     },
-    // ========== ADD BUTTON (outside array) ==========
-    // \u26A0\uFE0F arrayKey goes at FIELD level, NOT in props!
-    { key: 'addContact', type: 'addArrayItem', label: 'Add Contact', arrayKey: 'contacts' },
     { key: 'submit', type: 'submit', label: 'Submit' }
   ]
 } as const satisfies FormConfig;
 \`\`\`
 
+## Primitive Array
+
+\`\`\`typescript
+const tagForm = {
+  fields: [
+    {
+      key: 'tags',
+      type: 'array',
+      // template: single field = primitive items
+      template: { key: 'value', type: 'input', label: 'Tag' },
+      value: ['angular', 'typescript']
+    },
+    { key: 'submit', type: 'submit', label: 'Submit' }
+  ]
+} as const satisfies FormConfig;
+// Output: { tags: ['angular', 'typescript'] }
+\`\`\`
+
 ## Output Shape
 
 \`\`\`typescript
 {
   contacts: [
-    { name: 'Alice', phone: '555-1234' },
+    { name: 'Jane', phone: '555-1234' },
     { name: 'Bob', phone: '555-5678' }
   ]
 }
@@ -7967,39 +8697,96 @@ const formConfig = {
 
 ## Key Rules
 
-- Arrays use \`fields\` property (NOT \`template\`)
-- \`arrayKey\` goes at field level (NOT in props)
-- Arrays have NO label or logic support`,
+- **Simplified API:** Use \`template\` + \`value\` (add/remove buttons are auto-generated)
+- **Full API:** Use \`fields\` (you manage add/remove buttons manually)
+- \`fields\` and \`template\` are **mutually exclusive**
+- Arrays have NO label property
+- Only \`hidden\` logic type is supported
+
+## Full API (Advanced)
+
+For full control, use the \`fields\`-based API with explicit add/remove buttons:
+
+\`\`\`typescript
+{
+  key: 'contacts',
+  type: 'array',
+  minLength: 1,  // Optional: minimum number of items
+  maxLength: 5,  // Optional: maximum number of items
+  fields: [
+    [
+      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
+      { key: 'phone', type: 'input', label: 'Phone', value: '555' }
+    ]
+  ]
+}
+// + separate addArrayItem button with arrayKey
+\`\`\``,
     explained: `# Array Fields - Complete Explanation
 
-Arrays create dynamic, repeatable lists of items.
+Arrays create dynamic, repeatable lists of items. Two APIs are available.
 
-## Structure
+## Simplified API (Recommended)
+
+The simplified API uses \`template\` + \`value\` and auto-generates add/remove buttons.
+
+### Primitive Array
+\`\`\`typescript
+{
+  key: 'tags',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Tag' },  // Single field = primitive
+  value: ['angular', 'typescript']
+}
+// Output: { tags: ['angular', 'typescript'] }
+\`\`\`
+
+### Object Array
+\`\`\`typescript
+{
+  key: 'contacts',
+  type: 'array',
+  template: [                                   // Array = object items
+    { key: 'name', type: 'input', label: 'Name' },
+    { key: 'phone', type: 'input', label: 'Phone' }
+  ],
+  value: [{ name: 'Jane', phone: '555' }]
+}
+// Output: { contacts: [{ name: 'Jane', phone: '555' }] }
+\`\`\`
+
+### Button Customization
+\`\`\`typescript
+{
+  key: 'items',
+  type: 'array',
+  template: { key: 'value', type: 'input', label: 'Item' },
+  addButton: { label: 'Add Item', props: { color: 'primary' } },
+  removeButton: false  // Disable remove buttons
+}
+\`\`\`
+
+## Full API (Advanced)
+
+For full control, use \`fields\` with explicit item definitions and manual add/remove buttons.
 
 \`\`\`typescript
 {
   key: 'contacts',
   type: 'array',
-  // \u26A0\uFE0F Arrays DO NOT support:
-  // - label (no visual label)
-  // - logic (apply logic to children instead)
-  // - minItems/maxItems (not implemented)
-  // - template (use 'fields' instead)
   fields: [
-    // Template for each array item
-    {
-      key: 'item',
-      type: 'group',  // Creates objects in the array
-      fields: [
-        { key: 'name', type: 'input', label: 'Name' },
-        { key: 'phone', type: 'input', label: 'Phone' }
-      ]
-    }
+    // Each element is one array item:
+    // - Single FieldDef = primitive item
+    // - Array of FieldDefs = object item
+    [
+      { key: 'name', type: 'input', label: 'Name', value: 'Alice' },
+      { key: 'phone', type: 'input', label: 'Phone', value: '555' }
+    ]
   ]
 }
 \`\`\`
 
-## Add/Remove Buttons
+### Manual Add/Remove Buttons (Full API)
 
 \`\`\`typescript
 // ADD button - place OUTSIDE the array
@@ -8014,14 +8801,12 @@ Arrays create dynamic, repeatable lists of items.
 {
   key: 'contacts',
   type: 'array',
-  fields: [{
-    key: 'item',
-    type: 'group',
-    fields: [
+  fields: [
+    [
       { key: 'name', type: 'input', label: 'Name' },
-      { key: 'remove', type: 'removeArrayItem', label: 'Remove' }  // No arrayKey needed
+      { key: 'remove', type: 'removeArrayItem', label: 'Remove' }
     ]
-  }]
+  ]
 }
 \`\`\`
 
@@ -8040,17 +8825,124 @@ expression: '(formValue.items || []).reduce((sum, item) => sum + (item.price ||
 
 ## Common Mistakes
 
-\u274C Using \`template\` instead of \`fields\`:
+\u274C Mixing \`fields\` and \`template\`:
+\`\`\`typescript
+{ type: 'array', fields: [...], template: {...} }  // WRONG - mutually exclusive
+\`\`\`
+
+\u274C Wrong value shape for object templates:
 \`\`\`typescript
-{ type: 'array', template: [...] }  // WRONG - template doesn't exist
-{ type: 'array', fields: [...] }    // CORRECT
+{ template: [{ key: 'name', type: 'input' }], value: ['Jane'] }  // WRONG
+{ template: [{ key: 'name', type: 'input' }], value: [{ name: 'Jane' }] }  // CORRECT
 \`\`\`
 
-\u274C Putting \`arrayKey\` in props:
+\u274C Putting \`arrayKey\` in props (full API):
 \`\`\`typescript
 { type: 'addArrayItem', props: { arrayKey: 'x' } }  // WRONG
 { type: 'addArrayItem', arrayKey: 'x' }             // CORRECT
 \`\`\``
+  },
+  "minimal-simplified-array": {
+    description: "Simplified array API with template + value (~15 lines)",
+    minimal: `import { FormConfig } from '@ng-forge/dynamic-forms';
+
+const formConfig = {
+  fields: [
+    {
+      key: 'tags',
+      type: 'array',
+      template: { key: 'value', type: 'input', label: 'Tag' },
+      value: ['angular', 'typescript']
+    },
+    { key: 'submit', type: 'submit', label: 'Submit' }
+  ]
+} as const satisfies FormConfig;`,
+    brief: `// Simplified array - primitive values
+import { FormConfig } from '@ng-forge/dynamic-forms';
+
+const formConfig = {
+  fields: [
+    // Primitive array with auto add/remove buttons
+    {
+      key: 'tags',
+      type: 'array',
+      template: { key: 'value', type: 'input', label: 'Tag' },  // Single field = primitive
+      value: ['angular', 'typescript']
+    },
+    // Object array
+    {
+      key: 'contacts',
+      type: 'array',
+      template: [  // Array of fields = object items
+        { key: 'name', type: 'input', label: 'Name', required: true },
+        { key: 'phone', type: 'input', label: 'Phone' }
+      ],
+      value: [{ name: 'Jane', phone: '555' }],
+      addButton: { label: 'Add Contact' },
+      removeButton: { label: 'Delete', props: { color: 'warn' } }
+    },
+    { key: 'submit', type: 'submit', label: 'Submit' }
+  ]
+} as const satisfies FormConfig;`,
+    full: `# Simplified Array API
+
+The concise way to define dynamic arrays. Auto-generates add/remove buttons.
+
+## Primitive Array
+
+\`\`\`typescript
+import { FormConfig } from '@ng-forge/dynamic-forms';
+
+const formConfig = {
+  fields: [
+    {
+      key: 'tags',
+      type: 'array',
+      template: { key: 'value', type: 'input', label: 'Tag' },  // Single field = primitive items
+      value: ['angular', 'typescript']               // Initial values
+      // Add/remove buttons are auto-generated!
+    },
+    { key: 'submit', type: 'submit', label: 'Submit' }
+  ]
+} as const satisfies FormConfig;
+// Output: { tags: ['angular', 'typescript'] }
+\`\`\`
+
+## Object Array
+
+\`\`\`typescript
+const contactForm = {
+  fields: [
+    {
+      key: 'contacts',
+      type: 'array',
+      template: [                                   // Array = object items
+        { key: 'name', type: 'input', label: 'Name', required: true },
+        { key: 'phone', type: 'input', label: 'Phone' }
+      ],
+      value: [
+        { name: 'Jane', phone: '555-1234' },
+        { name: 'John', phone: '555-5678' }
+      ],
+      addButton: { label: 'Add Contact', props: { color: 'primary' } },
+      removeButton: { label: 'Delete' }
+    },
+    { key: 'submit', type: 'submit', label: 'Submit' }
+  ]
+} as const satisfies FormConfig;
+// Output: { contacts: [{ name: 'Jane', phone: '555-1234' }, ...] }
+\`\`\`
+
+## Key Points
+
+- **Single field template** = primitive array (each item is a value)
+- **Array of fields template** = object array (each item is an object)
+- **Add/remove buttons** are auto-generated by default
+- Use \`addButton: false\` or \`removeButton: false\` to disable
+- \`template\` and \`fields\` are **mutually exclusive**`,
+    explained: `# Simplified Array API - Complete Explanation
+
+See the \`simplified-array\` lookup topic for full documentation.`
   },
   "minimal-conditional": {
     description: "Show/hide field based on condition (~25 lines)",
@@ -8438,7 +9330,7 @@ provideDynamicForm({
 })
 
 // 3. Use
-validators: [{ type: 'customAsync', functionName: 'checkEmailAvailable' }]
+validators: [{ type: 'async', functionName: 'checkEmailAvailable' }]
 \`\`\`
 
 ## Error Messages
@@ -8607,7 +9499,7 @@ const formConfig = {
       type: 'datepicker',
       label: 'End Date',
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'minDate',
         expression: 'formValue.startDate',
       }]
@@ -8625,10 +9517,10 @@ const formConfig = {
       key: 'endDate',
       type: 'datepicker',
       label: 'End Date',
-      // \u26A0\uFE0F type: 'propertyDerivation' (NOT 'derivation')
-      // \u26A0\uFE0F targetProperty specifies WHICH property to set
+      // type: 'derivation' + targetProperty = PROPERTY derivation
+      // Without targetProperty, it would be a VALUE derivation
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'minDate',
         expression: 'formValue.startDate',
       }]
@@ -8646,7 +9538,7 @@ const formConfig = {
       options: [],
       // Dynamic options from custom function
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'options',
         functionName: 'getCitiesForCountry',
         dependsOn: ['country'],
@@ -8657,10 +9549,10 @@ const formConfig = {
 } as const satisfies FormConfig;
 
 // Key points:
-// - type: 'propertyDerivation' sets component PROPERTIES (not form value)
+// - type: 'derivation' sets component PROPERTIES (not form value)
 // - targetProperty: which input property to set (e.g., 'minDate', 'options')
 // - Supports: expression, value, functionName (mutually exclusive)
-// - Register functions in customFnConfig.propertyDerivations`,
+// - Register functions in customFnConfig.derivations`,
     full: `# Property Derivation (Dynamic Field Properties)
 
 Derive field component properties reactively based on form values.
@@ -8677,7 +9569,7 @@ const formConfig = {
       type: 'datepicker',
       label: 'End Date',
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'minDate',        // Set minDate property
         expression: 'formValue.startDate', // From startDate's value
       }]
@@ -8699,7 +9591,7 @@ const formConfig = {
       label: 'City',
       options: [],  // Initial empty, filled by property derivation
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'options',
         functionName: 'getCitiesForCountry',
         dependsOn: ['country'],
@@ -8712,7 +9604,7 @@ const formConfig = {
       type: 'input',
       label: 'Phone',
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'label',
         value: 'Mobile Phone',
         condition: {
@@ -8730,7 +9622,7 @@ const formConfig = {
       type: 'textarea',
       label: 'Notes',
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'props.appearance',  // Dot-notation for nested
         expression: 'formValue.isPremium ? "fill" : "outline"',
       }]
@@ -8747,7 +9639,7 @@ const formConfig = {
 // customFnConfig is a property of FormConfig, not a provider option
 const formConfig = {
   customFnConfig: {
-    propertyDerivations: {
+    derivations: {
       getCitiesForCountry: (ctx) => {
         const cities: Record<string, { label: string; value: string }[]> = {
           'US': [{ label: 'New York', value: 'nyc' }, { label: 'LA', value: 'la' }],
@@ -8758,24 +9650,27 @@ const formConfig = {
     },
   },
   fields: [
-    // ... fields with propertyDerivation logic referencing 'getCitiesForCountry'
+    // ... fields with derivation + targetProperty logic referencing 'getCitiesForCountry'
   ],
 } as const satisfies FormConfig;
 \`\`\`
 
 ## Key Differences from Value Derivation
 
-| Feature | \`type: 'derivation'\` | \`type: 'propertyDerivation'\` |
+| Feature | Value Derivation | Property Derivation |
 |---------|----------------------|-------------------------------|
+| Type | \`type: 'derivation'\` | \`type: 'derivation'\` + \`targetProperty\` |
 | Sets | Field's form value | Component property |
 | Target | Implicit (self) | \`targetProperty: 'minDate'\` |
 | Shorthand | \`derivation: 'expr'\` | None |
-| Functions | \`customFnConfig.derivations\` | \`customFnConfig.propertyDerivations\` |`,
+| Functions | \`customFnConfig.derivations\` | \`customFnConfig.derivations\` |
+
+The presence of \`targetProperty\` distinguishes a property derivation from a value derivation.`,
     explained: `# Property Derivation - Complete Explanation
 
 ## What is Property Derivation?
 
-Property derivation allows you to **reactively update component input properties** based on form state. While value derivations (\`type: 'derivation'\`) compute a field's form value, property derivations (\`type: 'propertyDerivation'\`) compute the field's component properties like \`minDate\`, \`options\`, \`label\`, \`placeholder\`, \`props.appearance\`, etc.
+Property derivation allows you to **reactively update component input properties** based on form state. Both value and property derivations use \`type: 'derivation'\`. The distinction is the \`targetProperty\` field: when present, the derivation targets a component property; when absent, it targets the field's form value.
 
 ## When to Use Property Derivation
 
@@ -8794,8 +9689,8 @@ Use property derivation when:
   type: 'datepicker',
   label: 'End Date',
   logic: [{
-    type: 'propertyDerivation',    // \u26A0\uFE0F NOT 'derivation'!
-    targetProperty: 'minDate',      // Which property to set
+    type: 'derivation',              // Same type as value derivation
+    targetProperty: 'minDate',      // targetProperty makes it a PROPERTY derivation
     expression: 'formValue.startDate', // How to compute it
   }]
 }
@@ -8806,7 +9701,7 @@ Use property derivation when:
 ### 1. Expression (inline JavaScript)
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'minDate',
   expression: 'formValue.startDate',  // Access form values
 }]
@@ -8815,7 +9710,7 @@ logic: [{
 ### 2. Static Value (with condition)
 \`\`\`typescript
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'label',
   value: 'Business Email',           // Fixed value
   condition: { type: 'fieldValue', fieldPath: 'type', operator: 'equals', value: 'business' },
@@ -8826,7 +9721,7 @@ logic: [{
 \`\`\`typescript
 // In form config
 customFnConfig: {
-  propertyDerivations: {
+  derivations: {
     getCitiesForCountry: (ctx) => {
       // ctx.formValue contains all form values
       // ctx.externalData contains external signals (unwrapped)
@@ -8837,7 +9732,7 @@ customFnConfig: {
 
 // In field
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'options',
   functionName: 'getCitiesForCountry',
   dependsOn: ['country'],  // \u26A0\uFE0F Recommended for custom functions!
@@ -8872,7 +9767,7 @@ targetProperty: 'props.nested.deep'  // \u274C Too deep!
 \`\`\`typescript
 // Default: evaluate immediately on form value change
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'options',
   expression: '...',
   trigger: 'onChange',  // default
@@ -8880,7 +9775,7 @@ logic: [{
 
 // Debounced: wait for typing to stop
 logic: [{
-  type: 'propertyDerivation',
+  type: 'derivation',
   targetProperty: 'options',
   functionName: 'searchProducts',
   trigger: 'debounced',
@@ -8904,7 +9799,7 @@ Inside arrays, \`formValue\` is scoped to the current array item:
       {
         key: 'endDate', type: 'datepicker', label: 'End',
         logic: [{
-          type: 'propertyDerivation',
+          type: 'derivation',
           targetProperty: 'minDate',
           expression: 'formValue.startDate',  // Refers to THIS item's startDate
         }]
@@ -8938,7 +9833,7 @@ import { FormConfig } from '@ng-forge/dynamic-forms';
 
 const travelForm = {
   customFnConfig: {
-    propertyDerivations: {
+    derivations: {
       getCitiesForCountry: (ctx) => {
         const cities: Record<string, { label: string; value: string }[]> = {
           'US': [{ label: 'New York', value: 'nyc' }, { label: 'LA', value: 'la' }],
@@ -8964,7 +9859,7 @@ const travelForm = {
       label: 'City',
       options: [],
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'options',
         functionName: 'getCitiesForCountry',
         dependsOn: ['country'],
@@ -8976,7 +9871,7 @@ const travelForm = {
       type: 'datepicker',
       label: 'Travel End',
       logic: [{
-        type: 'propertyDerivation',
+        type: 'derivation',
         targetProperty: 'minDate',
         expression: 'formValue.startDate',
       }],
@@ -8993,26 +9888,26 @@ const travelForm = {
 // WRONG - 'derivation' changes the form value, not a property
 logic: [{ type: 'derivation', expression: 'formValue.startDate' }]
 
-// CORRECT - 'propertyDerivation' changes a component property
-logic: [{ type: 'propertyDerivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
+// CORRECT - targetProperty makes it a PROPERTY derivation
+logic: [{ type: 'derivation', targetProperty: 'minDate', expression: 'formValue.startDate' }]
 \`\`\`
 
 \u274C Missing targetProperty:
 \`\`\`typescript
 // WRONG - must specify which property to set
-logic: [{ type: 'propertyDerivation', expression: '...' }]
+logic: [{ type: 'derivation', expression: '...' }]
 
 // CORRECT
-logic: [{ type: 'propertyDerivation', targetProperty: 'options', expression: '...' }]
+logic: [{ type: 'derivation', targetProperty: 'options', expression: '...' }]
 \`\`\`
 
-\u274C Using wrong customFnConfig key:
+\u274C Forgetting targetProperty entirely:
 \`\`\`typescript
-// WRONG - derivations is for value derivation functions
-customFnConfig: { derivations: { getCities: ... } }
+// WRONG - this is a VALUE derivation (overwrites the field value)
+logic: [{ type: 'derivation', functionName: 'getCities' }]
 
-// CORRECT - propertyDerivations is for property derivation functions
-customFnConfig: { propertyDerivations: { getCities: ... } }
+// CORRECT - targetProperty makes it set the 'options' PROPERTY
+logic: [{ type: 'derivation', targetProperty: 'options', functionName: 'getCities' }]
 \`\`\``
   },
   // ========== STANDARD PATTERNS ==========
@@ -9607,23 +10502,20 @@ const megaFormConfig = {
           ]
         },
 
-        // ARRAY
+        // ARRAY (Simplified API - recommended)
         {
           key: 'itemsHeader', type: 'text', label: 'Dynamic Array:', props: { elementType: 'h3' }
         },
         {
           key: 'demoArray',
           type: 'array',
-          fields: [{
-            key: 'arrayItem',
-            type: 'group',
-            fields: [
-              { key: 'itemName', type: 'input', label: 'Item Name' },
-              { key: 'itemQty', type: 'input', label: 'Qty', props: { type: 'number' } }
-            ]
-          }]
+          template: [
+            { key: 'itemName', type: 'input', label: 'Item Name' },
+            { key: 'itemQty', type: 'input', label: 'Qty', props: { type: 'number' } }
+          ],
+          value: [{ itemName: 'Widget', itemQty: '5' }],
+          addButton: { label: 'Add Item' }
         },
-        { key: 'addItem', type: 'addArrayItem', label: 'Add Item', arrayKey: 'demoArray' },
 
         {
           key: 'containersNav',
@@ -9643,7 +10535,7 @@ const megaFormConfig = {
 
 - **All field types:** input, select, radio, checkbox, multi-checkbox, textarea, toggle, slider, datepicker, text, hidden
 - **All container types:** page, row, group, array
-- **All button types:** submit, next, previous, addArrayItem
+- **All button types:** submit, next, previous, auto-generated add/remove (simplified array)
 - **Logic types:** hidden, required, derivation
 - **Condition types:** fieldValue with operators
 - **Layout:** col property for grid widths`;
@@ -9655,6 +10547,7 @@ function getPatternList() {
     "Minimal Patterns (~20-50 lines)": [
       "minimal-multipage",
       "minimal-array",
+      "minimal-simplified-array",
       "minimal-conditional",
       "minimal-validation",
       "minimal-hidden"
@@ -9685,7 +10578,8 @@ Recommended starting points:
 
 Minimal patterns (~20-50 lines):
 - minimal-multipage: 2-page wizard
-- minimal-array: Dynamic list with add/remove
+- minimal-array: Dynamic list with add/remove (simplified API)
+- minimal-simplified-array: Simplified array with template + value
 - minimal-conditional: Show/hide field
 - minimal-validation: Password confirmation
 - minimal-hidden: Hidden fields in multi-page
@@ -9696,7 +10590,7 @@ Use pattern="list" to see all available patterns.
 Use depth="minimal" for code-only output (no markdown).`,
     {
       pattern: z55.string().optional().describe(
-        'Pattern to get: minimal-multipage, minimal-array, minimal-conditional, minimal-validation, minimal-hidden, derivation, property-derivation, multi-page, conditional, validation, complete, mega. Use "list" to see all.'
+        'Pattern to get: minimal-multipage, minimal-array, minimal-simplified-array, minimal-conditional, minimal-validation, minimal-hidden, derivation, property-derivation, multi-page, conditional, validation, complete, mega. Use "list" to see all.'
       ),
       depth: z55.enum(["minimal", "brief", "full", "explained"]).default("full").describe(
         "minimal=code only (~20-50 lines), brief=code+summary, full=code+comments (default), explained=code+detailed explanation"
@@ -10185,11 +11079,11 @@ var UI_INTEGRATIONS3 = ["material", "bootstrap", "primeng", "ionic"];
 var FIX_SUGGESTIONS = {
   options: "Move `options` from `props: { options: [...] }` to field level: `{ key, type, options: [...] }`",
   label: "Remove `label` from this container field (page/group/row/array). Use a `text` field inside for headings.",
-  logic: "Move `logic` to individual child fields. Containers (row/group/array) don't support logic - only their children do.",
+  logic: "Containers (group, row, array) only support 'hidden' logic type (same as pages). For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.",
   minValue: "Use `minValue` at field level for sliders, not `min` in props.",
   maxValue: "Use `maxValue` at field level for sliders, not `max` in props.",
   step: "Use `step` at field level for sliders, not in props.",
-  template: "Use `fields` instead of `template` for array item definition.",
+  template: "Arrays support two APIs: (1) Full API with `fields` for explicit item definitions, or (2) Simplified API with `template` + `value` for common cases. If using `template`, provide a single field for primitive arrays or an array of fields for object arrays.",
   content: "Use `label` for text content and `props: { elementType }` for HTML element.",
   element: "Use `props: { elementType }` not `element` for text field HTML element.",
   hideWhen: "Use `logic: [{ type: 'hidden', condition: {...} }]` - no `hideWhen` shorthand exists.",
@@ -10360,7 +11254,7 @@ Returns SPECIFIC error messages with:
 Example errors you'll see:
 - "Hidden field missing REQUIRED value property"
 - "options MUST be at FIELD level, NOT inside props"
-- "row containers do NOT support logic blocks"`,
+- "containers only support 'hidden' logic type"`,
     {
       config: z56.union([z56.string(), z56.object({}).passthrough()]).describe(
         "File path (.ts/.js) OR JSON string OR JSON object. Auto-detects: paths ending in .ts/.js or starting with / are treated as files."
@@ -10551,22 +11445,16 @@ ${indent}  ]
 ${indent}}`;
 }
 function generateArray(name, indent) {
-  const array = `${indent}{
+  return `${indent}{
 ${indent}  key: '${name}',
 ${indent}  type: 'array',
-${indent}  fields: [
-${indent}    {
-${indent}      key: '${name}Item',
-${indent}      type: 'group',
-${indent}      fields: [
-${indent}        { key: 'itemName', type: 'input', label: 'Name' },
-${indent}        { key: 'itemValue', type: 'input', label: 'Value' }
-${indent}      ]
-${indent}    }
-${indent}  ]
+${indent}  template: [
+${indent}    { key: 'itemName', type: 'input', label: 'Name' },
+${indent}    { key: 'itemValue', type: 'input', label: 'Value' }
+${indent}  ],
+${indent}  value: [],
+${indent}  addButton: { label: 'Add ${capitalize(name)}' }
 ${indent}}`;
-  const addButton = `${indent}{ key: 'add${capitalize(name)}', type: 'addArrayItem', label: 'Add ${capitalize(name)}', arrayKey: '${name}' }`;
-  return [array, addButton];
 }
 function capitalize(s) {
   return s.charAt(0).toUpperCase() + s.slice(1).replace(/([A-Z])/g, " $1").trim();
@@ -10598,15 +11486,13 @@ function generateScaffold(options) {
       const arraysForThisPage = pages > 2 && p > 1 && p < pages ? arrays : p === Math.ceil(pages / 2) ? arrays : [];
       if (pages <= 2 && isFirst) {
         for (const a of arrays) {
-          const [arrayDef, addBtn] = generateArray(a, "        ");
+          const arrayDef = generateArray(a, "        ");
           lines.push(arrayDef + ",");
-          lines.push(addBtn + ",");
         }
       } else {
         for (const a of arraysForThisPage) {
-          const [arrayDef, addBtn] = generateArray(a, "        ");
+          const arrayDef = generateArray(a, "        ");
           lines.push(arrayDef + ",");
-          lines.push(addBtn + ",");
         }
       }
       const fieldsPerPage = Math.ceil(fields.length / pages);
@@ -10650,9 +11536,8 @@ function generateScaffold(options) {
       lines.push(generateGroup(g, "    ") + ",");
     }
     for (const a of arrays) {
-      const [arrayDef, addBtn] = generateArray(a, "    ");
+      const arrayDef = generateArray(a, "    ");
       lines.push(arrayDef + ",");
-      lines.push(addBtn + ",");
     }
     for (const f of fields) {
       lines.push(generateField(f, "    ") + ",");