@ng-forge/dynamic-forms 0.8.0 → 0.9.0-next.10

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

@@ -1,9 +1,12 @@
-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, ElementRef, EnvironmentInjector, runInInjectionContext } from '@angular/core';
+import { FIELD_SIGNAL_CONTEXT, 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 } 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 { TestBed } from '@angular/core/testing';
+import { form, schema } from '@angular/forms/signals';
 
 /**
  * Creates a value field context from the injected FIELD_SIGNAL_CONTEXT.
@@ -44,10 +47,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 +59,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 +91,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());
     });
 }
 
@@ -114,11 +112,9 @@ function valueFieldMapper(fieldDef) {
 function checkboxFieldMapper(fieldDef) {
     const context = inject(FIELD_SIGNAL_CONTEXT);
     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 +122,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 +165,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 +192,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 +215,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;
@@ -730,6 +720,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,43 +811,575 @@ 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) {
-                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;
-            }
-            else {
-                // Apply to host element (for Shadow DOM components)
-                appliedAttributes = applyMetaToElement(hostElement, currentMeta, appliedAttributes);
-            }
-        },
+    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.8", ngImport: i0, type: NgForgeFieldShell, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", 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.8", 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.8", ngImport: i0, type: NgForgeField, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", 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.8", 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.8", ngImport: i0, type: NgForgeAction, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", 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.8", 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);
+}
+
+/**
+ * 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.8", ngImport: i0, type: NgForgeControl, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", 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.8", 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.8", ngImport: i0, type: NgForgeHostControl, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.8", type: NgForgeHostControl, isStandalone: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", 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.8", ngImport: i0, type: NgForgeFieldHost, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.8", 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.8", 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.8", ngImport: i0, type: NgForgeActionHost, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.8", 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.8", 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 +1399,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 { NG_FORGE_ACTION_INPUTS, NG_FORGE_FIELD_SHELL_INPUTS, NG_FORGE_VALUE_FIELD_INPUTS, NgForgeAction, NgForgeActionHost, NgForgeControl, NgForgeField, NgForgeFieldHost, NgForgeFieldShell, NgForgeHostControl, addArrayItemButtonMapper, buildArrayButtonEventContext, buildValueFieldInputs, buttonFieldMapper, checkboxFieldMapper, createAriaDescribedBySignal, createNgForgeActionFixture, createNgForgeFieldFixture, createResolvedErrorsSignal, datepickerFieldMapper, injectNgForgeAction, 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