@ng-forge/dynamic-forms 0.9.0-next.8 → 0.9.0

package/fesm2022/ng-forge-dynamic-forms-integration.mjs

@@ -1,9 +1,13 @@
-import { inject, computed, signal, Injector, afterRenderEffect } from '@angular/core';
-import { FIELD_SIGNAL_CONTEXT, omit, buildBaseInputs, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, resolveNonFieldHidden, resolveNonFieldDisabled, RootFormRegistryService, ARRAY_CONTEXT, DynamicFormLogger, AppendArrayItemEvent, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, FORM_OPTIONS, resolveSubmitButtonDisabled, resolveNextButtonDisabled, NextPageEvent, PreviousPageEvent, dynamicTextToObservable, interpolateParams, isEqual, applyMetaToElement } from '@ng-forge/dynamic-forms';
-export { isEqual, resolveNonFieldDisabled, resolveNonFieldHidden } from '@ng-forge/dynamic-forms';
+import * as i0 from '@angular/core';
+import { inject, computed, signal, Injector, isDevMode, afterRenderEffect, input, Directive, untracked, InjectionToken, ElementRef, EnvironmentInjector, runInInjectionContext } from '@angular/core';
+import { injectFieldSignalContext, omit, buildBaseInputs, DEFAULT_PROPS, resolveNonFieldHidden, resolveNonFieldDisabled, RootFormRegistryService, ARRAY_CONTEXT, DynamicFormLogger, AppendArrayItemEvent, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, FORM_OPTIONS, resolveSubmitButtonDisabled, resolveNextButtonDisabled, NextPageEvent, PreviousPageEvent, dynamicTextToObservable, interpolateParams, isEqual, applyMetaToElement, DEFAULT_VALIDATION_MESSAGES, EventBus, resolveTokens, resolveDynamicValue, ADDON_ACTION_REGISTRY, writeToFieldValue } from '@ng-forge/dynamic-forms';
+export { createWrappers, isEqual, isWrappersBundle, resolveNonFieldDisabled, resolveNonFieldHidden, wrapperProps } from '@ng-forge/dynamic-forms';
 import { toObservable, toSignal } from '@angular/core/rxjs-interop';
 import { combineLatest, of } from 'rxjs';
 import { switchMap, map } from 'rxjs/operators';
+import { explicitEffect } from 'ngxtension/explicit-effect';
+import { TestBed } from '@angular/core/testing';
+import { form, schema } from '@angular/forms/signals';
 
 /**
  * Creates a value field context from the injected FIELD_SIGNAL_CONTEXT.
@@ -20,7 +24,7 @@ import { switchMap, map } from 'rxjs/operators';
  * @returns The value field context with reactive field tree accessor
  */
 function resolveValueFieldContext() {
-    const context = inject(FIELD_SIGNAL_CONTEXT);
+    const context = injectFieldSignalContext();
     return {
         getFieldTree: (fieldKey) => {
             // Access context.form here (inside a function that will be called from a computed)
@@ -44,10 +48,9 @@ function resolveValueFieldContext() {
  * @param fieldDef The value field definition
  * @param ctx The resolved value field context
  * @param defaultProps Default props from the form configuration (may be undefined if not configured)
- * @param defaultValidationMessages Default validation messages from the form configuration (may be undefined if not configured)
  * @returns Record of input names to values
  */
-function buildValueFieldInputs(fieldDef, ctx, defaultProps, defaultValidationMessages) {
+function buildValueFieldInputs(fieldDef, ctx, defaultProps) {
     const omittedFields = omit(fieldDef, ['value']);
     const baseInputs = buildBaseInputs(omittedFields, defaultProps);
     const inputs = {
@@ -57,9 +60,6 @@ function buildValueFieldInputs(fieldDef, ctx, defaultProps, defaultValidationMes
     if (fieldDef.placeholder !== undefined) {
         inputs['placeholder'] = fieldDef.placeholder;
     }
-    if (defaultValidationMessages !== undefined) {
-        inputs['defaultValidationMessages'] = defaultValidationMessages;
-    }
     // Resolve field tree reactively - this call is inside a computed,
     // so it establishes the reactive dependency correctly
     const fieldTree = ctx.getFieldTree(fieldDef.key);
@@ -92,13 +92,12 @@ function valueFieldMapper(fieldDef) {
     // Get the context once at injection time (captures the FIELD_SIGNAL_CONTEXT reference)
     const ctx = resolveValueFieldContext();
     const defaultProps = inject(DEFAULT_PROPS);
-    const defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES);
     // The computed calls ctx.getFieldTree(fieldDef.key) inside, which:
     // 1. Accesses context.form (triggering the getter for array items)
     // 2. Returns the field tree if available, or undefined if not yet
     // 3. Re-runs when the form structure updates (reactive dependency)
     return computed(() => {
-        return buildValueFieldInputs(fieldDef, ctx, defaultProps(), defaultValidationMessages());
+        return buildValueFieldInputs(fieldDef, ctx, defaultProps());
     });
 }
 
@@ -112,13 +111,11 @@ function valueFieldMapper(fieldDef) {
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
 function checkboxFieldMapper(fieldDef) {
-    const context = inject(FIELD_SIGNAL_CONTEXT);
+    const context = injectFieldSignalContext();
     const defaultProps = inject(DEFAULT_PROPS);
-    const defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES);
     return computed(() => {
         const omittedFields = omit(fieldDef, ['value']);
         const baseInputs = buildBaseInputs(omittedFields, defaultProps());
-        const validationMessages = defaultValidationMessages();
         const inputs = {
             ...baseInputs,
             validationMessages: fieldDef.validationMessages ?? {},
@@ -126,9 +123,6 @@ function checkboxFieldMapper(fieldDef) {
         if (fieldDef.placeholder !== undefined) {
             inputs['placeholder'] = fieldDef.placeholder;
         }
-        if (validationMessages !== undefined) {
-            inputs['defaultValidationMessages'] = validationMessages;
-        }
         // Access form inside computed for reactivity and to handle cases where
         // form may not be immediately available (e.g., during array item initialization)
         const formRoot = context.form;
@@ -172,9 +166,8 @@ function toDate(value) {
 function datepickerFieldMapper(fieldDef) {
     const ctx = resolveValueFieldContext();
     const defaultProps = inject(DEFAULT_PROPS);
-    const defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES);
     return computed(() => {
-        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps(), defaultValidationMessages());
+        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps());
         // Add datepicker-specific properties, converting strings to Date objects
         if (fieldDef.minDate !== undefined) {
             inputs['minDate'] = toDate(fieldDef.minDate);
@@ -200,10 +193,9 @@ function datepickerFieldMapper(fieldDef) {
 function optionsFieldMapper(fieldDef) {
     const ctx = resolveValueFieldContext();
     const defaultProps = inject(DEFAULT_PROPS);
-    const defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES);
     return computed(() => {
         // Cast to BaseValueField - safe because all FieldWithOptions types extend BaseValueField
-        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps(), defaultValidationMessages());
+        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps());
         // Add options property
         inputs['options'] = fieldDef.options;
         return inputs;
@@ -224,9 +216,8 @@ function optionsFieldMapper(fieldDef) {
 function sliderFieldMapper(fieldDef) {
     const ctx = resolveValueFieldContext();
     const defaultProps = inject(DEFAULT_PROPS);
-    const defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES);
     return computed(() => {
-        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps(), defaultValidationMessages());
+        const inputs = buildValueFieldInputs(fieldDef, ctx, defaultProps());
         // Add slider-specific properties (these are at field level, not in props)
         if (fieldDef.minValue !== undefined) {
             inputs['minValue'] = fieldDef.minValue;
@@ -570,7 +561,7 @@ function submitButtonFieldMapper(fieldDef) {
 // =============================================================================
 /** Mapper for next page button — preconfigures NextPageEvent. */
 function nextButtonFieldMapper(fieldDef) {
-    const fieldSignalContext = inject(FIELD_SIGNAL_CONTEXT);
+    const fieldSignalContext = injectFieldSignalContext();
     const rootFormRegistry = inject(RootFormRegistryService);
     const defaultProps = inject(DEFAULT_PROPS);
     const formOptions = inject(FORM_OPTIONS);
@@ -730,6 +721,59 @@ function shouldShowErrors(field) {
     });
 }
 
+/**
+ * Resolve target set, compute combined attrs, apply via applyMetaToElement.
+ * Target resolution is cached by selector identity — re-resolves only on
+ * selector change or `dependents` change. afterRenderEffect is signal-tracked,
+ * so the callback re-runs only when computeAttrs / dependents differ.
+ * @internal
+ */
+function applyTrackedAttrsToTargets(elementRef, computeAttrs, options = {}) {
+    const appliedByElement = new WeakMap();
+    let cachedSelector;
+    let cachedTargets = [];
+    let previousAttrs;
+    let previousDeps;
+    const warnedSelectors = isDevMode() ? new Set() : undefined;
+    afterRenderEffect({
+        write: () => {
+            // Read dependents first so afterRenderEffect tracks them.
+            const currentDeps = options.dependents?.map((d) => d());
+            const attrs = computeAttrs();
+            const selector = (typeof options.selector === 'function' ? options.selector() : options.selector)?.trim() || undefined;
+            const selectorChanged = selector !== cachedSelector;
+            const depsChanged = !!currentDeps &&
+                (!previousDeps || currentDeps.length !== previousDeps.length || currentDeps.some((d, i) => d !== previousDeps[i]));
+            if (selectorChanged || depsChanged || cachedTargets.length === 0) {
+                cachedSelector = selector;
+                cachedTargets = selector ? Array.from(elementRef.nativeElement.querySelectorAll(selector)) : [elementRef.nativeElement];
+            }
+            previousDeps = currentDeps;
+            // Dev-mode safety net: selector typo or wrong descendant query leaves
+            // meta + aria unapplied. Warn the first time we'd apply non-empty attrs
+            // to zero matches for a given selector. Re-warns only when the selector
+            // string changes (so authors fixing one typo see the next).
+            if (warnedSelectors && selector && cachedTargets.length === 0 && attrs && Object.keys(attrs).length > 0) {
+                if (!warnedSelectors.has(selector)) {
+                    warnedSelectors.add(selector);
+                    const tag = elementRef.nativeElement.tagName.toLowerCase();
+                    console.warn(`[Dynamic Forms] ngForgeControl selector "${selector}" matched no descendants of <${tag}> — meta + aria attributes will not be applied. ` +
+                        `Check the selector for typos, or supply 'dependents' if the target is rendered after a signal emits.`);
+                }
+            }
+            // Bail when attrs unchanged AND nothing structural moved — keeps repeated
+            // effect runs (driven by an unrelated tracked-signal flicker) cheap.
+            if (!selectorChanged && !depsChanged && isEqual(attrs, previousAttrs)) {
+                return;
+            }
+            previousAttrs = attrs;
+            for (const el of cachedTargets) {
+                const applied = appliedByElement.get(el) ?? new Set();
+                appliedByElement.set(el, applyMetaToElement(el, attrs, applied));
+            }
+        },
+    });
+}
 /**
  * Sets up automatic meta attribute tracking and application for wrapped components.
  *
@@ -768,42 +812,880 @@ function shouldShowErrors(field) {
  * ```
  */
 function setupMetaTracking(elementRef, meta, options) {
-    let appliedAttributes = new Set();
-    let previousMeta;
-    let previousDeps;
-    afterRenderEffect({
-        write: () => {
-            // Read dependents to establish signal tracking and collect their values
-            const currentDeps = options?.dependents?.map((dep) => dep());
-            const currentMeta = meta();
-            const hostElement = elementRef.nativeElement;
-            // Early exit if nothing changed (using deep equality for meta)
-            const metaChanged = !isEqual(currentMeta, previousMeta);
-            const depsChanged = !previousDeps || currentDeps?.length !== previousDeps.length || currentDeps?.some((d, i) => d !== previousDeps[i]);
-            if (!metaChanged && !depsChanged) {
+    applyTrackedAttrsToTargets(elementRef, () => meta(), { selector: options?.selector, dependents: options?.dependents });
+}
+/**
+ * Marker-directive variant: writes parent meta + aria to resolved targets.
+ * Parent aria wins on key collision. Internal to NgForgeControl/HostControl.
+ * @internal
+ */
+function setupMarkerAttrTracking(elementRef, parent, selector) {
+    applyTrackedAttrsToTargets(elementRef, () => {
+        const ariaRequired = parent.ariaRequired();
+        const ariaDescribedBy = parent.ariaDescribedBy();
+        // Skip null aria-required/describedby so applyMetaToElement removes the
+        // attr (rather than serializing "null") on transitions.
+        return {
+            ...(parent.meta() ?? {}),
+            'aria-invalid': parent.ariaInvalid(),
+            ...(ariaRequired === null ? {} : { 'aria-required': ariaRequired }),
+            ...(ariaDescribedBy === null ? {} : { 'aria-describedby': ariaDescribedBy }),
+        };
+    }, { selector });
+}
+
+/**
+ * Creates a signal that computes the aria-describedby value based on errors and hint state.
+ * Errors take precedence over hints - when errors are displayed, the hint is hidden.
+ * Only the first error is displayed (single error ID, not indexed).
+ *
+ * @param errorsToDisplay Signal containing the array of errors currently being displayed
+ * @param errorId Signal containing the ID for the error element (single error only)
+ * @param hintId Signal containing the ID for the hint element
+ * @param hasHint Function that returns true if a hint is configured
+ * @returns Signal containing the aria-describedby value or null
+ */
+function createAriaDescribedBySignal(errorsToDisplay, errorId, hintId, hasHint) {
+    return computed(() => {
+        if (errorsToDisplay().length > 0) {
+            return errorId();
+        }
+        if (hasHint()) {
+            return hintId();
+        }
+        return null;
+    });
+}
+
+// Error display utilities for field components
+
+/**
+ * Base directive composed into every ng-forge component via `hostDirectives`.
+ * Owns the universal identity inputs (`key`, `className`) and the host
+ * bindings that every field shape — value-bearing, action, future container —
+ * shares: `[id]`, `[attr.data-testid]`, `[class]`.
+ *
+ * Shape-specific add-ons (`NgForgeField` for value fields, `NgForgeAction`
+ * for actions) inject this directive and read `key()` / `className()` from
+ * it. Source-of-truth concerns like `hidden` / `disabled` live on the add-on
+ * because they vary by shape (value fields derive from `field()()`; actions
+ * receive direct inputs).
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_FIELD` / `NG_FORGE_ACTION` presets rather than composing Shell
+ * directly.
+ */
+class NgForgeFieldShell {
+    key = input.required(...(ngDevMode ? [{ debugName: "key" }] : /* istanbul ignore next */ []));
+    className = input('', ...(ngDevMode ? [{ debugName: "className" }] : /* istanbul ignore next */ []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldShell, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeFieldShell, isStandalone: true, inputs: { key: { classPropertyName: "key", publicName: "key", isSignal: true, isRequired: true, transformFunction: null }, className: { classPropertyName: "className", publicName: "className", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "id": "key()", "attr.data-testid": "key()", "class": "className()" } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldShell, decorators: [{
+            type: Directive,
+            args: [{
+                    host: {
+                        '[id]': 'key()',
+                        '[attr.data-testid]': 'key()',
+                        '[class]': 'className()',
+                    },
+                }]
+        }], propDecorators: { key: [{ type: i0.Input, args: [{ isSignal: true, alias: "key", required: true }] }], className: [{ type: i0.Input, args: [{ isSignal: true, alias: "className", required: false }] }] } });
+/** Input names forwarded onto `NgForgeFieldShell` via `hostDirectives`. */
+const NG_FORGE_FIELD_SHELL_INPUTS = ['key', 'className'];
+
+/**
+ * Value-bearing add-on directive — composed alongside `NgForgeFieldShell` via
+ * the `NG_FORGE_FIELD` preset. Owns the value/validation/aria plumbing every
+ * value-bearing field needs.
+ *
+ * The Shell owns universal identity (`key`, `className`, `[id]`,
+ * `[attr.data-testid]`, `[class]`); this directive injects Shell and adds
+ * field-driven bindings (`[attr.hidden]`, `[attr.aria-disabled]`), the
+ * standard value-field inputs (`field`, `label`, `placeholder`, `tabIndex`,
+ * `props`, `meta`, `validationMessages`), the derived error/aria signals,
+ * and the meta-tracking claim contract.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: NG_FORGE_FIELD,
+ *   imports: [NgForgeControl, FormField],
+ *   template: `
+ *     <label [for]="ngf.key() + '-input'">{{ ngf.label() | dynamicText | async }}</label>
+ *     <input ngForgeControl [id]="ngf.key() + '-input'" [formField]="ngf.field()" />
+ *     @if (ngf.errorsToDisplay()[0]; as e) {
+ *       <span [id]="ngf.errorId()">{{ e.message }}</span>
+ *     }
+ *   `,
+ * })
+ * export class MyInputField {
+ *   protected readonly ngf = injectNgForgeField<string>();
+ * }
+ * ```
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_FIELD` preset over composing this directive manually.
+ */
+class NgForgeField {
+    // ───────────────────────────────────────────────────────────────────────────
+    // Shell-owned identity — re-exported so component templates keep using
+    // `ngf.key()` / `ngf.className()` without reaching for the Shell directly.
+    // ───────────────────────────────────────────────────────────────────────────
+    shell = inject(NgForgeFieldShell);
+    /** Shell-owned key, re-exported as plain `Signal<string>` so it doesn't get flagged by the host-directive input-lockstep assertion. */
+    key = this.shell.key;
+    /** Shell-owned className, re-exported as plain `Signal<string>` for the same reason. */
+    className = this.shell.className;
+    // ───────────────────────────────────────────────────────────────────────────
+    // Forwarded inputs — the value-field-specific subset of mapper output.
+    // ───────────────────────────────────────────────────────────────────────────
+    field = input.required(...(ngDevMode ? [{ debugName: "field" }] : /* istanbul ignore next */ []));
+    label = input(...(ngDevMode ? [undefined, { debugName: "label" }] : /* istanbul ignore next */ []));
+    placeholder = input(...(ngDevMode ? [undefined, { debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    tabIndex = input(...(ngDevMode ? [undefined, { debugName: "tabIndex" }] : /* istanbul ignore next */ []));
+    props = input(...(ngDevMode ? [undefined, { debugName: "props" }] : /* istanbul ignore next */ []));
+    meta = input(...(ngDevMode ? [undefined, { debugName: "meta" }] : /* istanbul ignore next */ []));
+    validationMessages = input(...(ngDevMode ? [undefined, { debugName: "validationMessages" }] : /* istanbul ignore next */ []));
+    // ───────────────────────────────────────────────────────────────────────────
+    // Wiring
+    // ───────────────────────────────────────────────────────────────────────────
+    defaultValidationMessages = inject(DEFAULT_VALIDATION_MESSAGES, { optional: true }) ?? signal(undefined);
+    // ───────────────────────────────────────────────────────────────────────────
+    // Error display
+    // ───────────────────────────────────────────────────────────────────────────
+    errors = createResolvedErrorsSignal(this.field, this.validationMessages, this.defaultValidationMessages);
+    showErrors = shouldShowErrors(this.field);
+    errorsToDisplay = computed(() => (this.showErrors() ? this.errors() : []), ...(ngDevMode ? [{ debugName: "errorsToDisplay" }] : /* istanbul ignore next */ []));
+    // ───────────────────────────────────────────────────────────────────────────
+    // Accessibility helpers
+    // ───────────────────────────────────────────────────────────────────────────
+    errorId = computed(() => `${this.key()}-error`, ...(ngDevMode ? [{ debugName: "errorId" }] : /* istanbul ignore next */ []));
+    hintId = computed(() => `${this.key()}-hint`, ...(ngDevMode ? [{ debugName: "hintId" }] : /* istanbul ignore next */ []));
+    ariaInvalid = computed(() => {
+        const state = this.field()();
+        return state.invalid() && state.touched();
+    }, ...(ngDevMode ? [{ debugName: "ariaInvalid" }] : /* istanbul ignore next */ []));
+    ariaRequired = computed(() => {
+        return this.field()().required?.() === true ? true : null;
+    }, ...(ngDevMode ? [{ debugName: "ariaRequired" }] : /* istanbul ignore next */ []));
+    ariaDescribedBy = createAriaDescribedBySignal(this.errorsToDisplay, this.errorId, this.hintId, () => Boolean(this.props()?.hint));
+    // ───────────────────────────────────────────────────────────────────────────
+    // Claim tracking — markers and ambient sub-components flip this to true so
+    // dev-mode can warn when meta() is non-empty but nothing consumed it.
+    // ───────────────────────────────────────────────────────────────────────────
+    _claimed = signal(false, ...(ngDevMode ? [{ debugName: "_claimed" }] : /* istanbul ignore next */ []));
+    /** @internal Marker directives + ambient sub-components call this on construction. */
+    markClaimed() {
+        this._claimed.set(true);
+    }
+    logger = inject(DynamicFormLogger, { optional: true });
+    constructor() {
+        // Dev-mode safety net: a mapper or template-author binds meta() but no
+        // NgForgeControl / NgForgeHostControl / ambient sub-component is in
+        // place to consume it. Fires at most once per directive instance.
+        if (isDevMode()) {
+            let warned = false;
+            afterRenderEffect({
+                write: () => {
+                    if (warned)
+                        return;
+                    const meta = this.meta();
+                    if (!meta || Object.keys(meta).length === 0)
+                        return;
+                    if (untracked(this._claimed))
+                        return;
+                    warned = true;
+                    // `untracked` safe — afterRenderEffect.write runs after first CD, so Shell's required `key` is bound (no NG0950).
+                    const key = untracked(this.key);
+                    const message = `NgForgeField - meta() provided for field "${key}" but no NgForgeControl / NgForgeHostControl / ` +
+                        `ambient sub-component claimed it. Meta will not be applied. ` +
+                        `See https://ng-forge.dev/building-an-adapter#meta-forwarding`;
+                    if (this.logger) {
+                        this.logger.warn(message);
+                    }
+                    else {
+                        console.warn(message);
+                    }
+                },
+            });
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeField, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeField, isStandalone: true, inputs: { field: { classPropertyName: "field", publicName: "field", isSignal: true, isRequired: true, transformFunction: null }, label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, tabIndex: { classPropertyName: "tabIndex", publicName: "tabIndex", isSignal: true, isRequired: false, transformFunction: null }, props: { classPropertyName: "props", publicName: "props", isSignal: true, isRequired: false, transformFunction: null }, meta: { classPropertyName: "meta", publicName: "meta", isSignal: true, isRequired: false, transformFunction: null }, validationMessages: { classPropertyName: "validationMessages", publicName: "validationMessages", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.hidden": "field()().hidden() || null", "attr.aria-disabled": "field()().disabled() || null" } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeField, decorators: [{
+            type: Directive,
+            args: [{
+                    host: {
+                        '[attr.hidden]': 'field()().hidden() || null',
+                        '[attr.aria-disabled]': 'field()().disabled() || null',
+                    },
+                }]
+        }], ctorParameters: () => [], propDecorators: { field: [{ type: i0.Input, args: [{ isSignal: true, alias: "field", required: true }] }], label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], tabIndex: [{ type: i0.Input, args: [{ isSignal: true, alias: "tabIndex", required: false }] }], props: [{ type: i0.Input, args: [{ isSignal: true, alias: "props", required: false }] }], meta: [{ type: i0.Input, args: [{ isSignal: true, alias: "meta", required: false }] }], validationMessages: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationMessages", required: false }] }] } });
+/**
+ * Inputs forwarded onto `NgForgeField` via `hostDirectives`. Excludes
+ * `key` / `className` (forwarded to `NgForgeFieldShell` separately via
+ * `NG_FORGE_FIELD_SHELL_INPUTS`). Most consumers shouldn't reference this
+ * directly — use the `NG_FORGE_FIELD` preset.
+ */
+const NG_FORGE_VALUE_FIELD_INPUTS = ['field', 'label', 'placeholder', 'tabIndex', 'props', 'meta', 'validationMessages'];
+// Compile-time lockstep: NG_FORGE_VALUE_FIELD_INPUTS must equal the declared
+// `input()` properties on NgForgeField. Drift in either direction fails the build.
+const _NG_FORGE_VALUE_FIELD_INPUTS_LOCKSTEP = true;
+void _NG_FORGE_VALUE_FIELD_INPUTS_LOCKSTEP;
+/**
+ * Typed wrapper around `inject(NgForgeField)`. The generic narrows the
+ * `field` signal to `Signal<FieldTree<T>>` for the calling component's value
+ * type. The cast is unchecked — the runtime contract is that mappers only
+ * forward a `field` whose value type matches the field-type definition.
+ *
+ * @example
+ * ```ts
+ * protected readonly ngf = injectNgForgeField<string>();
+ * // ngf.field() is Signal<FieldTree<string>>; ngf.errors() etc. unchanged
+ * ```
+ */
+function injectNgForgeField() {
+    return inject(NgForgeField);
+}
+
+/**
+ * Action add-on directive — composed alongside `NgForgeFieldShell` via the
+ * `NG_FORGE_ACTION` preset. Owns the inputs + dispatch logic every button /
+ * action component needs (label, disabled, event, eventArgs, …) plus the
+ * `[attr.hidden]` / `[attr.aria-disabled]` host bindings driven by its own
+ * inputs (no field tree).
+ *
+ * Components call `action.dispatch()` from their click handler; this
+ * directive resolves any `eventArgs` tokens via the optional `ARRAY_CONTEXT`
+ * and dispatches the configured `event` through the `EventBus`.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: NG_FORGE_ACTION,
+ *   template: `<button (click)="action.dispatch()" [disabled]="action.disabled()">{{ action.label() }}</button>`,
+ * })
+ * export class MyButton {
+ *   protected readonly action = inject(NgForgeAction);
+ * }
+ * ```
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_ACTION` preset over composing this directive manually.
+ */
+class NgForgeAction {
+    // ───────────────────────────────────────────────────────────────────────────
+    // Shell-owned identity — re-exported as plain `Signal<T>` so they don't get
+    // flagged by the lockstep assertion below.
+    // ───────────────────────────────────────────────────────────────────────────
+    shell = inject(NgForgeFieldShell);
+    key = this.shell.key;
+    className = this.shell.className;
+    // ───────────────────────────────────────────────────────────────────────────
+    // Forwarded inputs — the action-specific subset of mapper output.
+    // ───────────────────────────────────────────────────────────────────────────
+    label = input.required(...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
+    disabled = input(false, ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    hidden = input(false, ...(ngDevMode ? [{ debugName: "hidden" }] : /* istanbul ignore next */ []));
+    tabIndex = input(...(ngDevMode ? [undefined, { debugName: "tabIndex" }] : /* istanbul ignore next */ []));
+    event = input(...(ngDevMode ? [undefined, { debugName: "event" }] : /* istanbul ignore next */ []));
+    eventArgs = input(...(ngDevMode ? [undefined, { debugName: "eventArgs" }] : /* istanbul ignore next */ []));
+    eventContext = input(...(ngDevMode ? [undefined, { debugName: "eventContext" }] : /* istanbul ignore next */ []));
+    props = input(...(ngDevMode ? [undefined, { debugName: "props" }] : /* istanbul ignore next */ []));
+    // ───────────────────────────────────────────────────────────────────────────
+    // Dispatch
+    // ───────────────────────────────────────────────────────────────────────────
+    eventBus = inject(EventBus);
+    arrayContext = inject(ARRAY_CONTEXT, { optional: true });
+    /**
+     * Dispatch the configured event through the EventBus. Resolves `eventArgs`
+     * tokens (`$key`, `$index`, `$arrayKey`, `formValue`, …) against the
+     * ambient array context if present, falling back to a static `eventContext`
+     * input or the field's own `key` otherwise. No-op when `event` is unset
+     * (e.g. submit buttons handled by the native form lifecycle).
+     */
+    dispatch() {
+        const event = this.event();
+        if (!event)
+            return;
+        const args = this.eventArgs();
+        if (!args || args.length === 0) {
+            this.eventBus.dispatch(event);
+            return;
+        }
+        const context = this.arrayContext
+            ? {
+                key: this.key(),
+                index: this.arrayContext.index(),
+                arrayKey: this.arrayContext.arrayKey,
+                formValue: this.arrayContext.formValue,
+            }
+            : (this.eventContext() ?? { key: this.key() });
+        this.eventBus.dispatch(event, ...resolveTokens(args, context));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAction, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeAction, isStandalone: true, inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: true, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, hidden: { classPropertyName: "hidden", publicName: "hidden", isSignal: true, isRequired: false, transformFunction: null }, tabIndex: { classPropertyName: "tabIndex", publicName: "tabIndex", isSignal: true, isRequired: false, transformFunction: null }, event: { classPropertyName: "event", publicName: "event", isSignal: true, isRequired: false, transformFunction: null }, eventArgs: { classPropertyName: "eventArgs", publicName: "eventArgs", isSignal: true, isRequired: false, transformFunction: null }, eventContext: { classPropertyName: "eventContext", publicName: "eventContext", isSignal: true, isRequired: false, transformFunction: null }, props: { classPropertyName: "props", publicName: "props", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.hidden": "hidden() || null", "attr.aria-disabled": "disabled() || null" } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAction, decorators: [{
+            type: Directive,
+            args: [{
+                    host: {
+                        '[attr.hidden]': 'hidden() || null',
+                        '[attr.aria-disabled]': 'disabled() || null',
+                    },
+                }]
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: true }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], hidden: [{ type: i0.Input, args: [{ isSignal: true, alias: "hidden", required: false }] }], tabIndex: [{ type: i0.Input, args: [{ isSignal: true, alias: "tabIndex", required: false }] }], event: [{ type: i0.Input, args: [{ isSignal: true, alias: "event", required: false }] }], eventArgs: [{ type: i0.Input, args: [{ isSignal: true, alias: "eventArgs", required: false }] }], eventContext: [{ type: i0.Input, args: [{ isSignal: true, alias: "eventContext", required: false }] }], props: [{ type: i0.Input, args: [{ isSignal: true, alias: "props", required: false }] }] } });
+/**
+ * Inputs forwarded onto `NgForgeAction` via `hostDirectives`. Excludes
+ * `key` / `className` (forwarded to `NgForgeFieldShell` separately via
+ * `NG_FORGE_FIELD_SHELL_INPUTS`). Most consumers shouldn't reference this
+ * directly — use the `NG_FORGE_ACTION` preset.
+ */
+const NG_FORGE_ACTION_INPUTS = ['label', 'disabled', 'hidden', 'tabIndex', 'event', 'eventArgs', 'eventContext', 'props'];
+// Compile-time lockstep: NG_FORGE_ACTION_INPUTS must equal the declared
+// `input()` properties on NgForgeAction. Drift fails the build.
+const _NG_FORGE_ACTION_INPUTS_LOCKSTEP = true;
+void _NG_FORGE_ACTION_INPUTS_LOCKSTEP;
+/**
+ * Typed wrapper around `inject(NgForgeAction)`. The generic narrows the
+ * `event` input to a specific FormEvent subclass.
+ *
+ * @example
+ * ```ts
+ * protected readonly action = injectNgForgeAction<SubmitEvent>();
+ * ```
+ */
+function injectNgForgeAction() {
+    return inject(NgForgeAction);
+}
+
+/**
+ * Universal addon-array plumbing: signal-cached `hidden` resolution and
+ * slot bucketing. Used internally by the `NgForgeAddons` host wrapper —
+ * consumers should compose `NgForgeAddons` directly and inject the
+ * directive instance via `injectNgForgeAddons<TAddon>()`.
+ */
+class NgForgeAddonsBase {
+    /** Capture the host's injector so `toSignal` (inside `resolveDynamicValue`) ties to the host's `DestroyRef`. */
+    hostInjector = inject(Injector);
+    /** Addon array mapped from `FieldDef.addons` by `buildBaseInputs`. */
+    addons = input(undefined, ...(ngDevMode ? [{ debugName: "addons" }] : /* istanbul ignore next */ []));
+    /**
+     * Per-addon `hidden` signal cache. Built via `explicitEffect` rather
+     * than `computed` because `toSignal` (inside `resolveDynamicValue` for
+     * Observable inputs) is disallowed in reactive contexts (NG0602).
+     */
+    _hiddenSignalCache = signal(new Map(), ...(ngDevMode ? [{ debugName: "_hiddenSignalCache" }] : /* istanbul ignore next */ []));
+    hiddenSignalCache = this._hiddenSignalCache.asReadonly();
+    visibleAddons = computed(() => {
+        const list = this.addons() ?? [];
+        const cache = this.hiddenSignalCache();
+        return list.filter((a) => !(cache.get(a)?.() ?? false));
+    }, ...(ngDevMode ? [{ debugName: "visibleAddons" }] : /* istanbul ignore next */ []));
+    hasAddons = computed(() => this.visibleAddons().length > 0, ...(ngDevMode ? [{ debugName: "hasAddons" }] : /* istanbul ignore next */ []));
+    prefixAddons = computed(() => this.visibleAddons().filter((a) => a.slot === 'prefix'), ...(ngDevMode ? [{ debugName: "prefixAddons" }] : /* istanbul ignore next */ []));
+    suffixAddons = computed(() => this.visibleAddons().filter((a) => a.slot === 'suffix'), ...(ngDevMode ? [{ debugName: "suffixAddons" }] : /* istanbul ignore next */ []));
+    /**
+     * Visible addons grouped by their `slot` string. Convenience view for
+     * adapters with non-universal slots (e.g., Ionic `start` / `end`).
+     */
+    addonsBySlot = computed(() => {
+        const map = new Map();
+        for (const a of this.visibleAddons()) {
+            const bucket = map.get(a.slot) ?? [];
+            bucket.push(a);
+            map.set(a.slot, bucket);
+        }
+        return map;
+    }, ...(ngDevMode ? [{ debugName: "addonsBySlot" }] : /* istanbul ignore next */ []));
+    /** Secondary index keyed by `hidden` value identity. Catches the common case
+     *  where a FormConfig re-emit produces structurally-different-but-content-
+     *  identical addon objects — without this, every re-emit would spawn a new
+     *  `toSignal` subscription for each addon's hidden axis. */
+    _hiddenByValue = new WeakMap();
+    constructor() {
+        explicitEffect([this.addons], ([list]) => {
+            const prev = this._hiddenSignalCache();
+            const next = new Map();
+            for (const a of list ?? []) {
+                // Tier 1: reference identity — the cheapest hit when the same addon
+                // object is reused across emissions.
+                let resolved = prev.get(a);
+                if (!resolved) {
+                    // Tier 2: hidden-value identity — when `hidden` is an object
+                    // (Signal / Observable / function), the same instance can be passed
+                    // through multiple new addon objects on FormConfig re-emit.
+                    const h = a.hidden;
+                    const valueKey = typeof h === 'object' && h !== null ? h : null;
+                    resolved = valueKey ? this._hiddenByValue.get(valueKey) : undefined;
+                    if (!resolved) {
+                        resolved = resolveDynamicValue(a.hidden, false, this.hostInjector);
+                        if (valueKey)
+                            this._hiddenByValue.set(valueKey, resolved);
+                    }
+                }
+                next.set(a, resolved);
+            }
+            this._hiddenSignalCache.set(next);
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonsBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeAddonsBase, isStandalone: true, inputs: { addons: { classPropertyName: "addons", publicName: "addons", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonsBase, decorators: [{
+            type: Directive,
+            args: [{}]
+        }], ctorParameters: () => [], propDecorators: { addons: [{ type: i0.Input, args: [{ isSignal: true, alias: "addons", required: false }] }] } });
+/** Forwarded onto `NgForgeAddonsBase` via the `NgForgeAddons` wrapper. */
+const NG_FORGE_ADDONS_INPUTS = ['addons'];
+// Compile-time lockstep — drift between the tuple and the declared inputs fails the build.
+const _NG_FORGE_ADDONS_INPUTS_LOCKSTEP = true;
+void _NG_FORGE_ADDONS_INPUTS_LOCKSTEP;
+/**
+ * Host wrapper for `NgForgeAddonsBase`. Consumers compose this directly:
+ *
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeFieldHost, NgForgeAddons],
+ *   template: `
+ *     @if (ngfa.hasAddons()) {
+ *       <p-inputgroup>
+ *         @for (a of ngfa.prefixAddons(); track $index) {
+ *           <df-addon-slot [addon]="a" [hidden]="ngfa.hiddenSignalCache().get(a)" />
+ *         }
+ *         <input ngForgeControl ... />
+ *       </p-inputgroup>
+ *     }
+ *   `,
+ * })
+ * export class MyInputField {
+ *   protected readonly ngfa = injectNgForgeAddons<MyInputAddon>();
+ * }
+ * ```
+ *
+ * The wrapper exists so `hostDirectives: [NgForgeAddons]` resolves
+ * cross-package — same constraint that drives `NgForgeFieldHost`.
+ */
+class NgForgeAddons {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddons, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.14", type: NgForgeAddons, isStandalone: true, hostDirectives: [{ directive: NgForgeAddonsBase, inputs: ["addons", "addons"] }], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddons, decorators: [{
+            type: Directive,
+            args: [{
+                    hostDirectives: [{ directive: NgForgeAddonsBase, inputs: [...NG_FORGE_ADDONS_INPUTS] }],
+                }]
+        }] });
+/**
+ * Typed inject helper. Always resolves to the underlying
+ * `NgForgeAddonsBase` instance — the wrapper class has no instance
+ * fields of its own.
+ */
+function injectNgForgeAddons() {
+    return inject(NgForgeAddonsBase);
+}
+
+const ADDON_PRESET_HANDLER = new InjectionToken('ADDON_PRESET_HANDLER');
+
+/**
+ * Universal click-dispatch plumbing for action-style addons (icon buttons,
+ * labelled buttons, etc.): `disabled` / `loading` resolution from
+ * `DynamicValue<boolean>`, action context construction, and the
+ * `preset / actionRef / action` precedence dispatcher.
+ *
+ * Adapter button kinds (e.g., `prime-button`) compose `NgForgeAddonAction`
+ * and read state via `injectNgForgeAddonAction<TAddon>()`. Preset semantics
+ * are adapter-specific — register an `ADDON_PRESET_HANDLER` at the host
+ * field scope to receive preset dispatches.
+ */
+class NgForgeAddonActionBase {
+    // The action registry is form-scoped. `optional: true` matches the
+    // preset handler so addons rendered outside a form that called
+    // `provideAddonActions(...)` degrade gracefully instead of throwing —
+    // `actionRef` dispatches then log an actionable warning and no-op.
+    actionRegistry = inject(ADDON_ACTION_REGISTRY, { optional: true });
+    presetHandler = inject(ADDON_PRESET_HANDLER, { optional: true });
+    logger = inject(DynamicFormLogger);
+    hostInjector = inject(Injector);
+    addon = input.required(...(ngDevMode ? [{ debugName: "addon" }] : /* istanbul ignore next */ []));
+    fieldInputs = input(undefined, ...(ngDevMode ? [{ debugName: "fieldInputs" }] : /* istanbul ignore next */ []));
+    /**
+     * Per-value caches for `disabled` / `loading` signal resolution. Keyed by
+     * the `DynamicValue` identity so a single `toSignal` subscription is
+     * shared across addon-reference swaps that pass the same Observable.
+     * Mirrors `NgForgeAddonsBase._hiddenByValue` — `resolveDynamicValue`
+     * cannot run inside `computed`/`linkedSignal.computation` because
+     * `toSignal` throws in reactive contexts (NG0602), and re-running it on
+     * every recomputation would leak subscriptions on each cycle.
+     */
+    _disabledByValue = new WeakMap();
+    _loadingByValue = new WeakMap();
+    _resolvedDisabled = signal(undefined, ...(ngDevMode ? [{ debugName: "_resolvedDisabled" }] : /* istanbul ignore next */ []));
+    _resolvedLoading = signal(undefined, ...(ngDevMode ? [{ debugName: "_resolvedLoading" }] : /* istanbul ignore next */ []));
+    disabled = computed(() => this._resolvedDisabled()?.() ?? false, ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    loading = computed(() => this._resolvedLoading()?.() ?? false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    constructor() {
+        explicitEffect([this.addon], ([addon]) => {
+            this._resolvedDisabled.set(this._resolveAxis(addon.disabled, this._disabledByValue));
+            this._resolvedLoading.set(this._resolveAxis(addon.loading, this._loadingByValue));
+        });
+    }
+    _resolveAxis(value, cache) {
+        const valueKey = typeof value === 'object' && value !== null ? value : null;
+        let resolved = valueKey ? cache.get(valueKey) : undefined;
+        if (!resolved) {
+            resolved = resolveDynamicValue(value, false, this.hostInjector);
+            if (valueKey)
+                cache.set(valueKey, resolved);
+        }
+        return resolved;
+    }
+    /**
+     * Resolve the click handler from the addon's three-axis click variant and
+     * invoke it. Precedence on multi-set: `preset > actionRef > action`. The
+     * validator drops multi-set configs at config-init time; this is
+     * defence-in-depth + a logged warning so the misconfiguration is loud.
+     */
+    dispatch() {
+        const addon = this.addon();
+        const ctx = this.buildActionContext();
+        const variantsSet = [addon.preset, addon.actionRef, addon.action].filter((v) => v !== undefined).length;
+        if (variantsSet > 1) {
+            this.logger.warn(`Addon button: more than one of preset/actionRef/action configured — dispatching by precedence (preset > actionRef > action). Ship at most one to silence this.`);
+        }
+        if (addon.preset !== undefined) {
+            if (!this.presetHandler) {
+                this.logger.warn(`Addon button: preset '${addon.preset}' is configured but no ADDON_PRESET_HANDLER is registered in this scope. Did the adapter forget to provide one at the host field?`);
                 return;
             }
-            previousMeta = currentMeta;
-            previousDeps = currentDeps;
-            if (options?.selector) {
-                // Apply to elements matching selector
-                const elements = hostElement.querySelectorAll(options.selector);
-                const allApplied = new Set();
-                elements.forEach((el) => {
-                    const applied = applyMetaToElement(el, currentMeta, appliedAttributes);
-                    applied.forEach((attr) => allApplied.add(attr));
-                });
-                appliedAttributes = allApplied;
+            void this.presetHandler.run(addon.preset, ctx);
+            return;
+        }
+        if (addon.actionRef !== undefined) {
+            const handler = this.actionRegistry?.get(addon.actionRef);
+            if (handler) {
+                handler(ctx);
             }
             else {
-                // Apply to host element (for Shadow DOM components)
-                appliedAttributes = applyMetaToElement(hostElement, currentMeta, appliedAttributes);
+                this.logger.warn(`Addon button: actionRef '${addon.actionRef}' is not registered. ` +
+                    (this.actionRegistry
+                        ? `Did you call provideAddonActions({ ${addon.actionRef}: ... })?`
+                        : `No provideAddonActions(...) registry is reachable in this scope — was the addon rendered outside a form?`));
             }
-        },
-    });
+            return;
+        }
+        if (addon.action !== undefined) {
+            addon.action(ctx);
+            return;
+        }
+        // Decorative — no handler configured.
+    }
+    /**
+     * Build an `AddonActionContext` for handlers from the wrapper-style
+     * `fieldInputs` bag. Returns the field-bound variant when a host field
+     * is reachable, or the orphan variant otherwise.
+     *
+     * Resolution order for `setValue`:
+     * 1. `inputs.setValue` from the forwarded bag (preferred — populated by
+     *    `buildFieldInputs` in `DfFieldOutlet`).
+     * 2. Fallback reconstructed from `inputs.field` itself: although
+     *    `ReadonlyFieldTree.value` is type-narrowed to `Signal<T>`, the
+     *    underlying runtime object is the same `WritableSignal<T>` created
+     *    by Signal Forms (the read-only wrapping is type-level only, see
+     *    `toReadonlyFieldTree`). Casting back at the writer boundary
+     *    produces a working setValue for ANY field depth — top-level OR
+     *    nested under groups. This avoids the previous FSC-key navigation
+     *    that broke for grouped fields, where `inputs.key` is DOM-mangled
+     *    (`'user_address_street'`) and `fsc.form[key]` returns undefined.
+     *
+     * The orphan variant fires only when the bag carries no field tree at
+     * all — genuine "rendered outside a field" scenario.
+     */
+    buildActionContext() {
+        const inputs = this.fieldInputs();
+        const key = inputs?.key ?? '';
+        const type = inputs?.type ?? '';
+        const tree = inputs?.field;
+        if (tree) {
+            // `writeToFieldValue` centralises the `Signal → WritableSignal` cast and
+            // warns at runtime if Signal Forms ever stops storing a writable signal
+            // here (the alternative — a silent no-op preset — is much worse).
+            const setValue = inputs?.setValue ?? ((next) => writeToFieldValue(tree.value, next, this.logger));
+            return {
+                field: { key, type },
+                form: tree,
+                value: tree.value() ?? undefined,
+                setValue,
+            };
+        }
+        return {
+            field: { key, type },
+            form: null,
+            value: undefined,
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonActionBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeAddonActionBase, isStandalone: true, inputs: { addon: { classPropertyName: "addon", publicName: "addon", isSignal: true, isRequired: true, transformFunction: null }, fieldInputs: { classPropertyName: "fieldInputs", publicName: "fieldInputs", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonActionBase, decorators: [{
+            type: Directive,
+            args: [{}]
+        }], ctorParameters: () => [], propDecorators: { addon: [{ type: i0.Input, args: [{ isSignal: true, alias: "addon", required: true }] }], fieldInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldInputs", required: false }] }] } });
+/** Forwarded onto `NgForgeAddonActionBase` via the `NgForgeAddonAction` wrapper. */
+const NG_FORGE_ADDON_ACTION_INPUTS = ['addon', 'fieldInputs'];
+const _NG_FORGE_ADDON_ACTION_INPUTS_LOCKSTEP = true;
+void _NG_FORGE_ADDON_ACTION_INPUTS_LOCKSTEP;
+/**
+ * Host wrapper for `NgForgeAddonActionBase`. Consumers compose this directly:
+ *
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeAddonAction],
+ *   template: `
+ *     <p-button [loading]="action.loading()" [disabled]="action.disabled()"
+ *               (onClick)="action.dispatch()" />
+ *   `,
+ * })
+ * export class MyButtonAddon {
+ *   protected readonly action = injectNgForgeAddonAction<MyButtonAddon>();
+ * }
+ * ```
+ */
+class NgForgeAddonAction {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonAction, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.14", type: NgForgeAddonAction, isStandalone: true, hostDirectives: [{ directive: NgForgeAddonActionBase, inputs: ["addon", "addon", "fieldInputs", "fieldInputs"] }], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAddonAction, decorators: [{
+            type: Directive,
+            args: [{
+                    hostDirectives: [{ directive: NgForgeAddonActionBase, inputs: [...NG_FORGE_ADDON_ACTION_INPUTS] }],
+                }]
+        }] });
+function injectNgForgeAddonAction() {
+    return inject(NgForgeAddonActionBase);
 }
 
-// Error display utilities for field components
+/**
+ * Marker directive applied to the canonical control element of an
+ * `NgForgeField`-using component. Forwards the field's `meta` AND
+ * parent-derived aria signals (`aria-invalid`, `aria-required`,
+ * `aria-describedby`) onto a target element.
+ *
+ * By default attributes land on the directive's own host. For wrapped
+ * controls (e.g. `<mat-checkbox>`, `<p-toggleSwitch>`) where the canonical
+ * native input is rendered as a descendant inside the wrapper, pass a CSS
+ * selector through the input alias — the directive caches the resolved
+ * descendant set and re-resolves only when the selector changes.
+ *
+ * @example Bare native control
+ * ```html
+ * <input ngForgeControl [formField]="ngf.field()" />
+ * ```
+ *
+ * @example Wrapped control with inner native input
+ * ```html
+ * <mat-checkbox ngForgeControl="input[type='checkbox']" [formField]="ngf.field()">
+ *   {{ ngf.label() }}
+ * </mat-checkbox>
+ * ```
+ *
+ * @example Dynamic option list (radios rendered in @for)
+ * ```html
+ * @for (option of options(); track option.value) {
+ *   <input type="radio" ngForgeControl [value]="option.value" />
+ * }
+ * ```
+ *
+ * Each `@for` iteration creates its own directive instance; Angular's
+ * structural lifecycle handles add/remove naturally.
+ */
+class NgForgeControl {
+    target = input(undefined, { ...(ngDevMode ? { debugName: "target" } : /* istanbul ignore next */ {}), alias: 'ngForgeControl' });
+    constructor() {
+        const parent = inject(NgForgeField);
+        setupMarkerAttrTracking(inject(ElementRef), parent, () => this.target());
+        parent.markClaimed();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeControl, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.14", type: NgForgeControl, isStandalone: true, selector: "[ngForgeControl]", inputs: { target: { classPropertyName: "target", publicName: "ngForgeControl", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeControl, decorators: [{
+            type: Directive,
+            args: [{ selector: '[ngForgeControl]' }]
+        }], ctorParameters: () => [], propDecorators: { target: [{ type: i0.Input, args: [{ isSignal: true, alias: "ngForgeControl", required: false }] }] } });
+/**
+ * Selectorless companion directive for shadow-DOM-encapsulated components
+ * (PrimeNG `p-select`, Ionic web components, etc.) where no light-DOM child
+ * is the canonical control. Added to the component's `hostDirectives` so the
+ * field's `meta` + parent aria land on the component's own host element.
+ *
+ * For split parent/control components (e.g. `df-prime-select` rendering
+ * `df-prime-select-control` internally), place `NgForgeHostControl` on the
+ * INNER control component's `hostDirectives` — the inner element is the
+ * canonical control, and the marker's `inject(NgForgeField)` walks up the
+ * element-injector tree to find the parent's directive instance.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [
+ *     { directive: NgForgeField, inputs: [...NG_FORGE_FIELD_INPUTS] },
+ *     NgForgeHostControl,
+ *   ],
+ *   template: `...`,
+ * })
+ * export class IonicInputField { ... }
+ * ```
+ */
+// Empty `@Directive({})` is intentional — selectorless; used only via `hostDirectives`.
+class NgForgeHostControl {
+    constructor() {
+        const parent = inject(NgForgeField);
+        setupMarkerAttrTracking(inject(ElementRef), parent, () => undefined);
+        parent.markClaimed();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeHostControl, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.14", type: NgForgeHostControl, isStandalone: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeHostControl, decorators: [{
+            type: Directive,
+            args: [{}]
+        }], ctorParameters: () => [] });
+
+/**
+ * Value-bearing field host wrapper. Composes `NgForgeFieldShell` (universal
+ * identity) with `NgForgeField` (value + validation + aria + meta-tracking)
+ * in a single host-directive entry, so consumer components compose just one
+ * directive instead of two.
+ *
+ * Why a directive instead of a `const` preset: cross-package partial
+ * compilation can't resolve a const reference inside `hostDirectives:`, so
+ * an exported const array doesn't work for library consumers. A wrapper
+ * directive's own `hostDirectives` IS a literal at compile time (in this
+ * file), so it works everywhere.
+ *
+ * Authoring shape for adapter components:
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeFieldHost],
+ *   ...
+ * })
+ * export class MyInputField {
+ *   protected readonly ngf = injectNgForgeField<string>();
+ * }
+ * ```
+ *
+ * Pattern reference: Taiga UI uses the same wrapper-directive technique
+ * for the same reason. See https://www.angularspace.com/host-directives-decomposition-unleashed/
+ */
+class NgForgeFieldHost {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldHost, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.14", type: NgForgeFieldHost, isStandalone: true, hostDirectives: [{ directive: NgForgeFieldShell, inputs: ["key", "key", "className", "className"] }, { directive: NgForgeField, inputs: ["field", "field", "label", "label", "placeholder", "placeholder", "tabIndex", "tabIndex", "props", "props", "meta", "meta", "validationMessages", "validationMessages"] }], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldHost, decorators: [{
+            type: Directive,
+            args: [{
+                    hostDirectives: [
+                        { directive: NgForgeFieldShell, inputs: [...NG_FORGE_FIELD_SHELL_INPUTS] },
+                        { directive: NgForgeField, inputs: [...NG_FORGE_VALUE_FIELD_INPUTS] },
+                    ],
+                }]
+        }] });
+/**
+ * Action / button host wrapper. Composes `NgForgeFieldShell` with
+ * `NgForgeAction` (event dispatch + aria-disabled) for button-shaped
+ * components.
+ *
+ * Authoring shape:
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeActionHost],
+ *   ...
+ * })
+ * export class MyButton {
+ *   protected readonly action = injectNgForgeAction();
+ * }
+ * ```
+ */
+class NgForgeActionHost {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeActionHost, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.14", type: NgForgeActionHost, isStandalone: true, hostDirectives: [{ directive: NgForgeFieldShell, inputs: ["key", "key", "className", "className"] }, { directive: NgForgeAction, inputs: ["label", "label", "disabled", "disabled", "hidden", "hidden", "tabIndex", "tabIndex", "event", "event", "eventArgs", "eventArgs", "eventContext", "eventContext", "props", "props"] }], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeActionHost, decorators: [{
+            type: Directive,
+            args: [{
+                    hostDirectives: [
+                        { directive: NgForgeFieldShell, inputs: [...NG_FORGE_FIELD_SHELL_INPUTS] },
+                        { directive: NgForgeAction, inputs: [...NG_FORGE_ACTION_INPUTS] },
+                    ],
+                }]
+        }] });
+
+/**
+ * Builds a `ComponentFixture` for an `NgForgeField`-composing component with
+ * `field` + `key` bound BEFORE `detectChanges()` — sidesteps the NG0950 that
+ * Shell's required `key` and Field's required `field` would otherwise throw.
+ *
+ * The caller drives `detectChanges()` themselves (so they can `setInput`
+ * additional component-specific props in between).
+ */
+function createNgForgeFieldFixture(component, options) {
+    TestBed.configureTestingModule({ imports: [component], providers: [...(options.providers ?? [])] });
+    const key = options.key;
+    const rootValue = signal({ [key]: options.value }, ...(ngDevMode ? [{ debugName: "rootValue" }] : /* istanbul ignore next */ []));
+    const injector = TestBed.inject(EnvironmentInjector);
+    const schemaCallback = options.schema;
+    const root = runInInjectionContext(injector, () => {
+        if (!schemaCallback)
+            return form(rootValue);
+        return form(rootValue, schema((path) => {
+            schemaCallback(path[key]);
+        }));
+    });
+    const field = root[key];
+    if (options.touched)
+        field().markAsTouched();
+    const fixture = TestBed.createComponent(component);
+    fixture.componentRef.setInput('field', field);
+    fixture.componentRef.setInput('key', key);
+    if (options.inputs) {
+        for (const [name, value] of Object.entries(options.inputs)) {
+            fixture.componentRef.setInput(name, value);
+        }
+    }
+    return { fixture, field, rootValue };
+}
+/**
+ * Builds a `ComponentFixture` for an `NgForgeAction`-composing component with
+ * `key` + `label` bound and `EventBus` provided. The caller calls
+ * `detectChanges()`; the harness handles the NG0950-avoidance bindings.
+ */
+function createNgForgeActionFixture(component, options) {
+    TestBed.configureTestingModule({ imports: [component], providers: [EventBus, ...(options.providers ?? [])] });
+    const fixture = TestBed.createComponent(component);
+    fixture.componentRef.setInput('key', options.key);
+    fixture.componentRef.setInput('label', options.label);
+    if (options.event)
+        fixture.componentRef.setInput('event', options.event);
+    if (options.eventArgs)
+        fixture.componentRef.setInput('eventArgs', options.eventArgs);
+    if (options.disabled !== undefined)
+        fixture.componentRef.setInput('disabled', options.disabled);
+    if (options.hidden !== undefined)
+        fixture.componentRef.setInput('hidden', options.hidden);
+    if (options.inputs) {
+        for (const [name, value] of Object.entries(options.inputs)) {
+            fixture.componentRef.setInput(name, value);
+        }
+    }
+    return { fixture, eventBus: TestBed.inject(EventBus) };
+}
+/** Provider for `DEFAULT_VALIDATION_MESSAGES` in field tests — supply the default-messages map and the directive resolves it from DI. */
+function provideTestValidationMessages(messages) {
+    return { provide: DEFAULT_VALIDATION_MESSAGES, useValue: signal(messages) };
+}
 
 /**
  * @ng-forge/dynamic-forms/integration
@@ -824,5 +1706,5 @@ function setupMetaTracking(elementRef, meta, options) {
  * Generated bundle index. Do not edit.
  */
 
-export { addArrayItemButtonMapper, buildArrayButtonEventContext, buildValueFieldInputs, buttonFieldMapper, checkboxFieldMapper, createResolvedErrorsSignal, datepickerFieldMapper, insertArrayItemButtonMapper, nextButtonFieldMapper, optionsFieldMapper, popArrayItemButtonMapper, prependArrayItemButtonMapper, previousButtonFieldMapper, removeArrayItemButtonMapper, resolveArrayButtonContext, resolveArrayButtonEventArgs, resolveValueFieldContext, setupMetaTracking, shiftArrayItemButtonMapper, shouldShowErrors, submitButtonFieldMapper, valueFieldMapper };
+export { ADDON_PRESET_HANDLER, NG_FORGE_ACTION_INPUTS, NG_FORGE_ADDONS_INPUTS, NG_FORGE_ADDON_ACTION_INPUTS, NG_FORGE_FIELD_SHELL_INPUTS, NG_FORGE_VALUE_FIELD_INPUTS, NgForgeAction, NgForgeActionHost, NgForgeAddonAction, NgForgeAddonActionBase, NgForgeAddons, NgForgeAddonsBase, NgForgeControl, NgForgeField, NgForgeFieldHost, NgForgeFieldShell, NgForgeHostControl, addArrayItemButtonMapper, buildArrayButtonEventContext, buildValueFieldInputs, buttonFieldMapper, checkboxFieldMapper, createAriaDescribedBySignal, createNgForgeActionFixture, createNgForgeFieldFixture, createResolvedErrorsSignal, datepickerFieldMapper, injectNgForgeAction, injectNgForgeAddonAction, injectNgForgeAddons, injectNgForgeField, insertArrayItemButtonMapper, nextButtonFieldMapper, optionsFieldMapper, popArrayItemButtonMapper, prependArrayItemButtonMapper, previousButtonFieldMapper, provideTestValidationMessages, removeArrayItemButtonMapper, resolveArrayButtonContext, resolveArrayButtonEventArgs, resolveValueFieldContext, setupMetaTracking, shiftArrayItemButtonMapper, shouldShowErrors, submitButtonFieldMapper, valueFieldMapper };
 //# sourceMappingURL=ng-forge-dynamic-forms-integration.mjs.map