@ng-forge/dynamic-form-mcp 0.9.0-next.8 → 0.9.0

package/bin/ng-forge-mcp.js

@@ -780,7 +780,7 @@ var VALIDATORS = [
   {
     type: "custom",
     category: "custom",
-    description: "Custom synchronous validator using registered function or expression. IMPORTANT: The validator returns { kind: 'errorKind' } on failure. The actual error MESSAGE is defined in 'validationMessages' at the FIELD level, NOT in the validator config.",
+    description: "Custom synchronous validator using registered function or expression. IMPORTANT: The validator returns { kind: 'errorKind' } on failure. The actual error MESSAGE is defined in 'validationMessages' at the FIELD level, NOT in the validator config. NOTE: TypeScript-authored configs may also use an inline `fn: CustomValidator` instead of `functionName` (XOR with `functionName`, code-only \u2014 not JSON-serializable); MCP-generated configs should use `functionName`.",
     parameters: {
       functionName: {
         name: "functionName",
@@ -832,7 +832,7 @@ var VALIDATORS = [
   {
     type: "async",
     category: "async",
-    description: "Async validator using registered async function (resource-based). Register the function via customFnConfig.asyncValidators.",
+    description: "Async validator using registered async function (resource-based). Register the function via customFnConfig.asyncValidators. NOTE: TypeScript-authored configs may also use an inline `fn: AsyncCustomValidator` instead of `functionName` (XOR with `functionName`, code-only \u2014 not JSON-serializable); MCP-generated configs should use `functionName`.",
     parameters: {
       functionName: {
         name: "functionName",
@@ -855,7 +855,7 @@ var VALIDATORS = [
   {
     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).",
+    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). NOTE: TypeScript-authored configs may also use an inline `fn: HttpCustomValidator` instead of `functionName` (XOR with `functionName`, code-only \u2014 not JSON-serializable); MCP-generated configs should use `functionName` or declarative mode.",
     parameters: {
       functionName: {
         name: "functionName",
@@ -1402,7 +1402,7 @@ var DOCUMENTATION = [
 // packages/dynamic-form-mcp/src/registry/wrappers.ts
 var WRAPPER_AUTHORING_CONTRACT = `All wrapper components MUST:
 
-1. Implement \`FieldWrapperContract\` from \`@ng-forge/dynamic-forms\`.
+1. Implement \`FieldWrapper\` from \`@ng-forge/dynamic-forms\`.
 2. Expose \`readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });\`
    \u2014 this is the slot where the inner wrapper (or the field) is rendered
    imperatively by the outlet.
@@ -1553,6 +1553,419 @@ const tagItemTemplate = { key: 'tag', type: 'input', label: 'Tag' } as const sat
   }
 ];
 
+// packages/dynamic-form-mcp/src/registry/addons.ts
+var UNIVERSAL_BASE_PROPS = {
+  slot: {
+    name: "slot",
+    type: "'prefix' | 'suffix' | string",
+    description: "Slot to render this addon in. `prefix` and `suffix` are universal; adapters may add more.",
+    required: true
+  },
+  className: {
+    name: "className",
+    type: "string",
+    description: "CSS class applied to the addon host element.",
+    required: false
+  },
+  hidden: {
+    name: "hidden",
+    type: "boolean | Signal<boolean> | Observable<boolean>",
+    description: "Reactive visibility \u2014 `true` removes the addon from layout. JSON-safe when boolean.",
+    required: false
+  },
+  disabled: {
+    name: "disabled",
+    type: "boolean | Signal<boolean> | Observable<boolean>",
+    description: "Reactive disabled state \u2014 primarily relevant for interactive kinds.",
+    required: false
+  }
+};
+var ADDON_KINDS = [
+  // ─── Core-shipped universal kinds ────────────────────────────────────────
+  {
+    kind: "text",
+    category: "core",
+    package: "@ng-forge/dynamic-forms",
+    adapter: null,
+    description: "Renders inline text content (currency symbol, unit label, character counter, etc.).",
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      text: {
+        name: "text",
+        type: "DynamicText",
+        description: "Text content. Supports plain strings, observables, signals, and i18n keys.",
+        required: true
+      }
+    },
+    example: `{ slot: 'prefix', kind: 'text', text: '$' }`,
+    minimalExample: `{ slot: 'prefix', kind: 'text', text: '$' }`
+  },
+  {
+    kind: "template",
+    category: "core",
+    package: "@ng-forge/dynamic-forms",
+    adapter: null,
+    description: "Renders a named `<ng-template>` projected into <df-dynamic-form>. JSON-safe \u2014 backend ships the key, FE supplies the template.",
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      templateKey: {
+        name: "templateKey",
+        type: "string",
+        description: 'Name of an `<ng-template dfTemplate="...">` projected into the host form.',
+        required: true
+      }
+    },
+    example: `{ slot: 'suffix', kind: 'template', templateKey: 'searchIcon' }`,
+    minimalExample: `{ slot: 'suffix', kind: 'template', templateKey: 'mySlot' }`
+  },
+  {
+    kind: "component",
+    category: "core",
+    package: "@ng-forge/dynamic-forms",
+    adapter: null,
+    description: "Renders an arbitrary Angular component. The `component` loader is a function; this kind is dropped from JSON-derived configs by the validator.",
+    jsonSafe: false,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      component: {
+        name: "component",
+        type: "() => Promise<Type<unknown> | { default: Type<unknown> }>",
+        description: "Lazy loader for the Angular component to render.",
+        required: true
+      },
+      inputs: {
+        name: "inputs",
+        type: "Record<string, unknown>",
+        description: "Inputs forwarded to the rendered component.",
+        required: false
+      }
+    },
+    example: `{
+  slot: 'prefix',
+  kind: 'component',
+  component: () => import('./my-component').then(m => m.MyComponent),
+  inputs: { foo: 'bar' },
+}`,
+    minimalExample: `{ slot: 'prefix', kind: 'component', component: () => import('./x') }`
+  },
+  // ─── PrimeNG-shipped kinds ───────────────────────────────────────────────
+  {
+    kind: "prime-icon",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-primeng",
+    adapter: "primeng",
+    description: 'Renders `<i class="pi pi-{icon}">` \u2014 bare PrimeIcons name.',
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: {
+        name: "icon",
+        type: "string",
+        description: 'PrimeIcons name without the `pi-` prefix (e.g., "search", "times").',
+        required: true
+      },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "Accessible label for icons that convey meaning. Decorative icons omit this.",
+        required: false
+      }
+    },
+    example: `{ slot: 'prefix', kind: 'prime-icon', icon: 'search', ariaLabel: 'Search' }`,
+    minimalExample: `{ slot: 'prefix', kind: 'prime-icon', icon: 'search' }`
+  },
+  {
+    kind: "prime-button",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-primeng",
+    adapter: "primeng",
+    description: "Renders `<p-button>` with optional icon, label, severity, reactive loading, and exactly one click handler (preset, actionRef, or action).",
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: { name: "icon", type: "string", description: "PrimeIcons name without the `pi-` prefix.", required: false },
+      label: { name: "label", type: "DynamicText", description: "Visible button label.", required: false },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "Required when icon-only (no `label`). Used as `aria-label`.",
+        required: false
+      },
+      severity: {
+        name: "severity",
+        type: "'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'help' | 'contrast'",
+        description: "PrimeNG button colour variant.",
+        required: false
+      },
+      loading: {
+        name: "loading",
+        type: "boolean | Signal<boolean> | Observable<boolean>",
+        description: "Reactive loading state \u2014 renders the native PrimeNG spinner.",
+        required: false
+      },
+      preset: {
+        name: "preset",
+        type: "'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility' | string",
+        description: "Built-in preset action. Mutually exclusive with `actionRef` and `action`. Adapters may extend the preset union.",
+        required: false
+      },
+      actionRef: {
+        name: "actionRef",
+        type: "string",
+        description: "Typed string handle to a handler registered via `provideAddonActions(...)`. Mutually exclusive with `preset` and `action`. JSON-safe.",
+        required: false
+      },
+      action: {
+        name: "action",
+        type: "(ctx: AddonActionContext) => void",
+        description: "Inline click handler (code-only \u2014 dropped from JSON-derived configs). Mutually exclusive with `preset` and `actionRef`.",
+        required: false
+      }
+    },
+    example: `{ slot: 'suffix', kind: 'prime-button', icon: 'times', ariaLabel: 'Clear', preset: 'clear' }`,
+    minimalExample: `{ slot: 'suffix', kind: 'prime-button', icon: 'times', ariaLabel: 'Clear', preset: 'clear' }`
+  },
+  // ─── Material-shipped kinds ──────────────────────────────────────────────
+  {
+    kind: "mat-icon",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-material",
+    adapter: "material",
+    description: "Renders `<mat-icon>{icon}</mat-icon>` \u2014 Material Icons ligature name.",
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: {
+        name: "icon",
+        type: "string",
+        description: 'Material Icons ligature (e.g., "search", "close", "visibility").',
+        required: true
+      },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "Accessible label for icons that convey meaning. Decorative icons omit this.",
+        required: false
+      }
+    },
+    example: `{ slot: 'prefix', kind: 'mat-icon', icon: 'search', ariaLabel: 'Search' }`,
+    minimalExample: `{ slot: 'prefix', kind: 'mat-icon', icon: 'search' }`
+  },
+  {
+    kind: "mat-button",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-material",
+    adapter: "material",
+    description: "Renders `<button mat-icon-button>` (icon-only) or `<button mat-button>` (labeled) with optional color, reactive loading, and exactly one click handler (preset, actionRef, or action).",
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: { name: "icon", type: "string", description: "Material Icons ligature.", required: false },
+      label: { name: "label", type: "DynamicText", description: "Visible button label.", required: false },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "REQUIRED when icon-only (no `label`). Used as `aria-label`.",
+        required: false
+      },
+      color: {
+        name: "color",
+        type: "'primary' | 'accent' | 'warn'",
+        description: "Material button color variant.",
+        required: false
+      },
+      loading: {
+        name: "loading",
+        type: "boolean | Signal<boolean> | Observable<boolean>",
+        description: "Reactive loading state \u2014 disables the button when truthy.",
+        required: false
+      },
+      preset: {
+        name: "preset",
+        type: "'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility' | string",
+        description: "Built-in preset action. Mutually exclusive with `actionRef` and `action`.",
+        required: false
+      },
+      actionRef: {
+        name: "actionRef",
+        type: "string",
+        description: "Typed handle to a handler registered via `provideAddonActions(...)`. JSON-safe.",
+        required: false
+      },
+      action: {
+        name: "action",
+        type: "(ctx: AddonActionContext) => void",
+        description: "Inline click handler (code-only \u2014 dropped from JSON-derived configs).",
+        required: false
+      }
+    },
+    example: `{ slot: 'suffix', kind: 'mat-button', icon: 'close', ariaLabel: 'Clear', preset: 'clear' }`,
+    minimalExample: `{ slot: 'suffix', kind: 'mat-button', icon: 'close', ariaLabel: 'Clear', preset: 'clear' }`
+  },
+  // ─── Bootstrap-shipped kinds ─────────────────────────────────────────────
+  {
+    kind: "bs-icon",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-bootstrap",
+    adapter: "bootstrap",
+    description: 'Renders `<i class="bi bi-{icon}">` \u2014 Bootstrap Icons name without the `bi-` prefix.',
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: {
+        name: "icon",
+        type: "string",
+        description: 'Bootstrap Icons name without the `bi-` prefix (e.g., "search", "x", "eye").',
+        required: true
+      },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "Accessible label for icons that convey meaning. Decorative icons omit this.",
+        required: false
+      }
+    },
+    example: `{ slot: 'prefix', kind: 'bs-icon', icon: 'search', ariaLabel: 'Search' }`,
+    minimalExample: `{ slot: 'prefix', kind: 'bs-icon', icon: 'search' }`
+  },
+  {
+    kind: "bs-button",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-bootstrap",
+    adapter: "bootstrap",
+    description: 'Renders `<button class="btn btn-outline-{severity}">` with optional icon, label, severity, and reactive loading (swaps to a spinner).',
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: { name: "icon", type: "string", description: "Bootstrap Icons name without the `bi-` prefix.", required: false },
+      label: { name: "label", type: "DynamicText", description: "Visible button label.", required: false },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "REQUIRED when icon-only (no `label`). Used as `aria-label`.",
+        required: false
+      },
+      severity: {
+        name: "severity",
+        type: "'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark'",
+        description: "Bootstrap button variant (mapped to `btn-outline-{severity}`).",
+        required: false
+      },
+      loading: {
+        name: "loading",
+        type: "boolean | Signal<boolean> | Observable<boolean>",
+        description: "Reactive loading state \u2014 swaps the button content for a spinner.",
+        required: false
+      },
+      preset: {
+        name: "preset",
+        type: "'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility' | string",
+        description: "Built-in preset action. Mutually exclusive with `actionRef` and `action`.",
+        required: false
+      },
+      actionRef: {
+        name: "actionRef",
+        type: "string",
+        description: "Typed handle to a handler registered via `provideAddonActions(...)`. JSON-safe.",
+        required: false
+      },
+      action: {
+        name: "action",
+        type: "(ctx: AddonActionContext) => void",
+        description: "Inline click handler (code-only \u2014 dropped from JSON-derived configs).",
+        required: false
+      }
+    },
+    example: `{ slot: 'suffix', kind: 'bs-button', icon: 'x', ariaLabel: 'Clear', preset: 'clear' }`,
+    minimalExample: `{ slot: 'suffix', kind: 'bs-button', icon: 'x', ariaLabel: 'Clear', preset: 'clear' }`
+  },
+  // ─── Ionic-shipped kinds ─────────────────────────────────────────────────
+  {
+    kind: "ion-icon",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-ionic",
+    adapter: "ionic",
+    description: 'Renders `<ion-icon name="{icon}">` \u2014 Ionicons name.',
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: {
+        name: "icon",
+        type: "string",
+        description: 'Ionicons name (e.g., "search-outline", "close-outline", "eye-outline").',
+        required: true
+      },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "Accessible label for icons that convey meaning. Decorative icons omit this.",
+        required: false
+      }
+    },
+    example: `{ slot: 'prefix', kind: 'ion-icon', icon: 'search-outline', ariaLabel: 'Search' }`,
+    minimalExample: `{ slot: 'prefix', kind: 'ion-icon', icon: 'search-outline' }`
+  },
+  {
+    kind: "ion-button",
+    category: "adapter",
+    package: "@ng-forge/dynamic-forms-ionic",
+    adapter: "ionic",
+    description: 'Renders `<ion-button>` with optional icon, label, color, fill, and reactive loading (renders an `<ion-spinner>`). `ion-button` addons render INSIDE `<ion-input>` as native `<ion-button slot="start|end">` via an attribute-selector component so Ionic\'s `::slotted(ion-button[slot=start|end])` shadow CSS sizes them natively.',
+    jsonSafe: true,
+    props: {
+      ...UNIVERSAL_BASE_PROPS,
+      icon: { name: "icon", type: "string", description: "Ionicons name.", required: false },
+      label: { name: "label", type: "DynamicText", description: "Visible button label.", required: false },
+      ariaLabel: {
+        name: "ariaLabel",
+        type: "DynamicText",
+        description: "REQUIRED when icon-only (no `label`). Used as `aria-label`.",
+        required: false
+      },
+      color: {
+        name: "color",
+        type: "'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark'",
+        description: "Ionic button color.",
+        required: false
+      },
+      fill: {
+        name: "fill",
+        type: "'clear' | 'outline' | 'solid' | 'default'",
+        description: "Ionic button fill style.",
+        required: false
+      },
+      loading: {
+        name: "loading",
+        type: "boolean | Signal<boolean> | Observable<boolean>",
+        description: "Reactive loading state \u2014 renders an `<ion-spinner>`.",
+        required: false
+      },
+      preset: {
+        name: "preset",
+        type: "'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility' | string",
+        description: "Built-in preset action. Mutually exclusive with `actionRef` and `action`.",
+        required: false
+      },
+      actionRef: {
+        name: "actionRef",
+        type: "string",
+        description: "Typed handle to a handler registered via `provideAddonActions(...)`. JSON-safe.",
+        required: false
+      },
+      action: {
+        name: "action",
+        type: "(ctx: AddonActionContext) => void",
+        description: "Inline click handler (code-only \u2014 dropped from JSON-derived configs).",
+        required: false
+      }
+    },
+    example: `{ slot: 'suffix', kind: 'ion-button', icon: 'close-outline', ariaLabel: 'Clear', preset: 'clear' }`,
+    minimalExample: `{ slot: 'suffix', kind: 'ion-button', icon: 'close-outline', ariaLabel: 'Clear', preset: 'clear' }`
+  }
+];
+
 // packages/dynamic-form-mcp/src/registry/index.ts
 function getFieldTypes() {
   return FIELD_TYPES;
@@ -1596,6 +2009,12 @@ function getDocPage(id) {
 function getDocPagesByCategory(category) {
   return DOCUMENTATION.filter((d) => d.category === category);
 }
+function getAddonKinds() {
+  return ADDON_KINDS;
+}
+function getAddonKind(kind) {
+  return ADDON_KINDS.find((k) => k.kind === kind);
+}
 
 // packages/dynamic-form-mcp/src/resources/field-types.resource.ts
 function registerFieldTypesResource(server) {
@@ -2142,7 +2561,9 @@ const config: FormConfig = {
 
 Every field MUST have:
 
-- \`key\`: Unique identifier (except for \`row\` type which is layout-only)
+- \`key\`: Identifier, unique within its group scope (the same leaf key may repeat inside different groups, e.g. \`createA.name\` and \`createB.name\`). Page/row/array containers do not introduce a scope. Buttons (which don't bind to form values) don't need unique keys.
+  - **DOM id / data-testid composition:** keys are joined with \`_\` through group ancestors to form the rendered DOM id. A leaf \`street\` inside group \`address\` renders as \`id="address_street"\`. Inside an array item, the item index is appended after: \`id="address_street_0"\`. Use this exact form for \`for=\`, \`aria-describedby\`, \`aria-labelledby\`, or CSS selectors that target group-nested fields.
+  - **Avoid \`_\` in keys when they could collide with a group-prefixed id.** A top-level key \`foo_bar\` and a leaf \`bar\` inside group \`foo\` would both render as \`id="foo_bar"\`. The validator catches this collision at boot, but it's easier to just not put \`_\` in keys that share a name with an existing group + leaf pair.
 - \`type\`: One of the registered field types
 - \`label\`: Human-readable label (for accessibility)
 
@@ -2299,12 +2720,13 @@ Available shorthands: \`required\`, \`email\`, \`min\`, \`max\`, \`minLength\`,
 
 ### Nullable Values
 
-Value fields accept a \`nullable?: boolean\` flag. When \`true\`:
+Value fields and checked fields (\`checkbox\`, \`toggle\`) accept a \`nullable?: boolean\` flag. When \`true\`:
 
 - \`value\` accepts \`null\` in addition to the field's normal value type.
-- An omitted \`value\` resolves to \`null\` (instead of the type-specific empty default like \`''\`, \`NaN\`, or \`[]\`).
+- An omitted \`value\` resolves to \`null\` (instead of the type-specific empty default like \`''\`, \`NaN\`, \`false\`, or \`[]\`).
 - Orthogonal to \`required\`. \`nullable\` declares that the **model** accepts \`null\`; \`required\` is a **validation** constraint. Angular's \`Validators.required\` treats \`null\` as invalid, so a field that is both \`nullable\` and \`required\` will fail required-validation when the value is \`null\` \u2014 the two flags describe different layers (data shape vs. validation), not conflicting semantics.
 - Map OpenAPI \`nullable: true\` (3.0) or \`type: [T, null]\` (3.1) to this flag.
+- Container fields (\`group\`, \`array\`, \`row\`, \`page\`) do NOT support \`nullable\` \u2014 their null semantics are ambiguous.
 
 \`\`\`typescript
 {
@@ -2314,6 +2736,14 @@ Value fields accept a \`nullable?: boolean\` flag. When \`true\`:
   nullable: true,
   value: null,  // valid; default-resolves to null
 }
+
+{
+  key: 'active',
+  type: 'checkbox',
+  label: 'Active',
+  nullable: true,
+  value: null,  // undecided checkbox state \u2014 model permits null, UI renders unchecked
+}
 \`\`\`
 
 Read-side caveat: a user clearing a text input reads back as \`""\`, not \`null\` \u2014 this is a DOM/Web IDL contract, identical to classic Reactive Forms. \`nullable\` is a contract for accepted values, not a guarantee of emitted ones.
@@ -2409,6 +2839,8 @@ Invokes a registered custom function by name:
 
 Register functions via \`customFnConfig.customFunctions\`.
 
+> **TypeScript-authored configs:** the same surface also accepts an inline \`fn: CustomFunction\` instead of \`functionName\` (XOR with \`functionName\`, code-only \u2014 not JSON-serializable). The MCP server emits \`functionName\` exclusively; consumers writing configs in TS may prefer \`fn\` when they don't need JSON round-tripping. Same caveat applies to async conditions (\`asyncFn\`), function derivations (\`fn\`), async function derivations (\`asyncFn\`), and validators (\`fn\`).
+
 #### Async Custom Condition
 
 Invokes a registered async function that returns \`Promise<boolean>\` or \`Observable<boolean>\`:
@@ -2482,6 +2914,53 @@ Available adapters:
 - \`@ng-forge/dynamic-forms-primeng\` - PrimeNG
 - \`@ng-forge/dynamic-forms-ionic\` - Ionic
 
+### Style Defaults (opt-in)
+
+Each adapter ships an opinionated Sass partial with host-framework colors/typography. Library SCSS uses \`var(--df-name, structural-fallback)\` so forms render usefully without any opt-in \u2014 only opt in if you want the adapter-themed look.
+
+\`\`\`scss
+@use '@ng-forge/dynamic-forms-material/styles/defaults' as df;
+
+:root {
+  @include df.apply-material-form-defaults;
+}
+\`\`\`
+
+Substitute \`material\` for \`bootstrap\`, \`primeng\`, or \`ionic\`. Material also ships \`form-material-defaults-dark\` for dark-mode hint/error colors. Ionic ships \`apply-ionic-legacy-error-styles\` that pairs with \`withLegacyStatusClasses()\` (see below).
+
+## Provider Features
+
+\`provideDynamicForm()\` accepts optional \`with*\` feature configurators alongside the adapter field bundle:
+
+### \`withLegacyStatusClasses()\` \u2014 opt into legacy ng-* CSS classes
+
+By default, Angular Signal Forms uses its modern class strategy. If your CSS targets \`.ng-touched\`, \`.ng-invalid\`, \`.ng-dirty\`, etc. on form-bound elements, add this feature to wire up the compat-class strategy:
+
+\`\`\`typescript
+import { provideDynamicForm, withLegacyStatusClasses } from '@ng-forge/dynamic-forms';
+import { withMaterialFields } from '@ng-forge/dynamic-forms-material';
+
+export const appConfig = {
+  providers: [
+    provideDynamicForm(
+      ...withMaterialFields(),
+      withLegacyStatusClasses(),
+    ),
+  ],
+};
+\`\`\`
+
+Recommended when consuming Ionic's \`apply-ionic-legacy-error-styles\` mixin, when using Bootstrap themes that style \`is-invalid.ng-touched\`, or any custom CSS that depends on the \`ng-*\` classes.
+
+### Other built-in features
+
+- \`withLoggerConfig(options?)\` \u2014 configure or disable the dynamic-form logger
+- \`withEventFormValue()\` \u2014 attach the current form value to every dispatched event
+- \`withValueExclusionDefaults(options)\` \u2014 set form-wide value exclusion defaults
+- \`withValidationExecutionDefaults(options)\` \u2014 set form-wide validation execution defaults (e.g. defer until touched)
+
+All features are exported from \`@ng-forge/dynamic-forms\`.
+
 ## Common Patterns
 
 ### Always End with Submit Button
@@ -2516,7 +2995,7 @@ Available adapters:
 
 1. **Missing labels** - Always include labels for accessibility
 2. **Missing validation messages** - Users need clear feedback
-3. **Duplicate keys** - Each key must be unique within its scope
+3. **Duplicate keys within a group scope** - Keys must be unique within the same group. Same key in different groups is fine (different scoped paths). Buttons are exempt.
 4. **Select without options** - Select/radio fields must have options
 5. **Array without fields** - Array fields need a fields template
 6. **Group without fields** - Group fields need child fields
@@ -9378,6 +9857,7 @@ function getTopicList() {
   const fieldTypes = ["input", "select", "slider", "radio", "checkbox", "textarea", "datepicker", "toggle", "text", "hidden"];
   const containers = ["group", "row", "array", "simplified-array", "page"];
   const wrappers = ["wrappers", ...getWrappers().map((w) => w.type)];
+  const addons = ["addons", ...getAddonKinds().map((k) => k.kind)];
   const concepts = [
     "validation",
     "validation-messages",
@@ -9416,6 +9896,9 @@ ${containers.map(formatTopicItem).join("\n")}
 ## Wrappers
 ${wrappers.map(formatTopicItem).join("\n")}
 
+## Addons
+${addons.map(formatTopicItem).join("\n")}
+
 ## Concepts
 ${concepts.map(formatTopicItem).join("\n")}
 
@@ -9584,7 +10067,120 @@ const config = {
   lines.push(wrappers[0]?.contract ?? "");
   return lines.join("\n");
 }
+function formatAddonInfo(addon, depth) {
+  if (depth === "brief") {
+    return [
+      `# ${addon.kind} addon`,
+      "",
+      `${addon.description.split(".")[0]}.`,
+      "",
+      "```typescript",
+      addon.minimalExample,
+      "```",
+      addon.jsonSafe ? "" : "**Code-only** \u2014 dropped by the lenient validator when the config came from JSON."
+    ].filter(Boolean).join("\n");
+  }
+  const lines = [];
+  lines.push(`# ${addon.kind} addon`);
+  lines.push("");
+  lines.push(`**Category:** ${addon.category}`);
+  lines.push(`**Package:** \`${addon.package}\``);
+  if (addon.adapter) lines.push(`**Adapter:** ${addon.adapter}`);
+  lines.push(`**JSON-safe:** ${addon.jsonSafe ? "Yes" : "No (code-only)"}`);
+  lines.push(`**Description:** ${addon.description}`);
+  if (Object.keys(addon.props).length > 0) {
+    lines.push("");
+    lines.push("## Config Props");
+    for (const prop of Object.values(addon.props)) {
+      const req = prop.required ? " **(required)**" : "";
+      lines.push(`- \`${prop.name}\`: ${prop.type}${req} \u2014 ${prop.description}`);
+    }
+  }
+  lines.push("");
+  lines.push("## Minimal Example");
+  lines.push("```typescript");
+  lines.push(addon.minimalExample);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Full Example");
+  lines.push("```typescript");
+  lines.push(addon.example);
+  lines.push("```");
+  return lines.join("\n");
+}
+function formatAddonsOverview() {
+  const kinds = getAddonKinds();
+  const lines = [];
+  lines.push("# Addons");
+  lines.push("");
+  lines.push(
+    "Addons render inside a field slot \u2014 icons, buttons, inline text, custom templates, or custom components. Multiple addons in the same slot render left-to-right (mirrored in RTL). `hidden` and `disabled` are reactive (signals, observables, or `FormStateCondition`)."
+  );
+  lines.push("");
+  lines.push("## Applying an addon");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push(`{
+  key: 'q',
+  type: 'input',
+  label: 'Search',
+  addons: [
+    { slot: 'prefix', kind: 'mat-icon', icon: 'search', ariaLabel: 'Search' },
+    { slot: 'suffix', kind: 'mat-button', icon: 'close', ariaLabel: 'Clear', preset: 'clear' },
+  ],
+}`);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Registered Kinds");
+  lines.push("");
+  const core = kinds.filter((k) => k.category === "core");
+  const adapter = kinds.filter((k) => k.category === "adapter");
+  if (core.length > 0) {
+    lines.push("### Core (universal \u2014 ship from `@ng-forge/dynamic-forms`)");
+    for (const k of core) {
+      const json = k.jsonSafe ? "" : " _(code-only)_";
+      lines.push(`- **${k.kind}**${json} \u2014 ${k.description.split(".")[0]}.`);
+    }
+    lines.push("");
+  }
+  if (adapter.length > 0) {
+    lines.push("### Adapter (provided by UI integration packages)");
+    for (const k of adapter) {
+      lines.push(`- **${k.kind}** (${k.adapter}, \`${k.package}\`) \u2014 ${k.description.split(".")[0]}.`);
+    }
+    lines.push("");
+  }
+  lines.push('Use `ngforge_lookup topic="<kind>"` (e.g., `mat-button`, `pi-icon`) for full details on any individual addon kind.');
+  lines.push("");
+  lines.push("## Click variants (mutually exclusive on button-like addons)");
+  lines.push("");
+  lines.push("- `preset`: built-in semantics \u2014 `clear` / `reset` / `paste` / `copy` / `toggle-password-visibility`.");
+  lines.push("- `actionRef`: named handler resolved via `provideAddonActions({ ... })`.");
+  lines.push("- `action`: inline function (code-only, dropped by JSON validator).");
+  lines.push("");
+  lines.push("Setting more than one logs a warning and applies the first (precedence: `preset` > `actionRef` > `action`).");
+  return lines.join("\n");
+}
 async function resolveTopicContent(resolvedTopic, depth, uiIntegration) {
+  if (resolvedTopic === "addons" || resolvedTopic === "addon" || resolvedTopic === "addon-kinds") {
+    if (depth === "brief") {
+      const kinds = getAddonKinds();
+      return [
+        "**Addons** render inside a field slot (prefix / suffix / adapter-specific): icons, buttons, inline text, templates, components.",
+        "",
+        "Registered kinds:",
+        ...kinds.map((k) => `- \`${k.kind}\` (${k.category}${k.adapter ? `, ${k.adapter}` : ""})${k.jsonSafe ? "" : " \u2014 code-only"}`),
+        "",
+        'Use `addons: [{ slot: "suffix", kind: "<kind>", ... }]` on an addon-supporting field. See `ngforge_lookup topic="addons"` for full docs.'
+      ].join("\n");
+    }
+    return formatAddonsOverview();
+  }
+  const addonInfo = getAddonKind(resolvedTopic);
+  const collidesWithFieldOrWrapper = resolvedTopic === "text" || !!getWrapper(resolvedTopic);
+  if (addonInfo && !collidesWithFieldOrWrapper) {
+    return formatAddonInfo(addonInfo, depth);
+  }
   if (resolvedTopic === "wrappers" || resolvedTopic === "wrapper") {
     if (depth === "brief") {
       const wrappers = getWrappers();
@@ -9735,6 +10331,8 @@ Containers: group, row, array, simplified-array, page
 
 Wrappers: wrappers (overview), css (shipping), section, arraySection (demo-only)
 
+Addons: addons (overview), text, template, component (core), mat-icon, mat-button, bs-icon, bs-button, pi-icon, pi-button, ion-icon, ion-button
+
 Concepts: validation, conditional, derivation, property-derivation, options-format, expression-variables, async-validators
 
 Patterns: field-placement, logic-matrix, context-api, containers, multi-page-gotchas
@@ -13192,6 +13790,18 @@ function buildIndex() {
       toolCall: `ngforge_lookup topic="${wrapper.type}"`
     });
   }
+  for (const addon of getAddonKinds()) {
+    const subcategory = addon.adapter ? `Addon (${addon.adapter})` : `Addon (${addon.category})`;
+    entries.push({
+      id: addon.kind,
+      category: "addon",
+      subcategory,
+      description: addon.description,
+      aliases: [],
+      content: `${addon.kind} addon ${addon.description} ${addon.package}`.toLowerCase(),
+      toolCall: `ngforge_lookup topic="${addon.kind}"`
+    });
+  }
   searchIndex = entries;
   return entries;
 }