@ng-forge/dynamic-forms 0.9.0-next.12 → 0.9.0-next.14

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

@@ -1,10 +1,11 @@
 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';
+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';
 
@@ -23,7 +24,7 @@ import { form, schema } from '@angular/forms/signals';
  * @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)
@@ -110,7 +111,7 @@ 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);
     return computed(() => {
         const omittedFields = omit(fieldDef, ['value']);
@@ -560,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);
@@ -877,10 +878,10 @@ function createAriaDescribedBySignal(errorsToDisplay, errorId, hintId, hasHint)
 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 });
+    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.8", ngImport: i0, type: NgForgeFieldShell, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldShell, decorators: [{
             type: Directive,
             args: [{
                     host: {
@@ -1010,10 +1011,10 @@ class NgForgeField {
             });
         }
     }
-    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 });
+    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.8", ngImport: i0, type: NgForgeField, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeField, decorators: [{
             type: Directive,
             args: [{
                     host: {
@@ -1124,10 +1125,10 @@ class NgForgeAction {
             : (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 });
+    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.8", ngImport: i0, type: NgForgeAction, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeAction, decorators: [{
             type: Directive,
             args: [{
                     host: {
@@ -1160,6 +1161,312 @@ 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;
+            }
+            void this.presetHandler.run(addon.preset, ctx);
+            return;
+        }
+        if (addon.actionRef !== undefined) {
+            const handler = this.actionRegistry?.get(addon.actionRef);
+            if (handler) {
+                handler(ctx);
+            }
+            else {
+                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);
+}
+
 /**
  * Marker directive applied to the canonical control element of an
  * `NgForgeField`-using component. Forwards the field's `meta` AND
@@ -1201,10 +1508,10 @@ class NgForgeControl {
         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 });
+    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.8", ngImport: i0, type: NgForgeControl, decorators: [{
+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 }] }] } });
@@ -1239,10 +1546,10 @@ class NgForgeHostControl {
         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 });
+    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.8", ngImport: i0, type: NgForgeHostControl, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeHostControl, decorators: [{
             type: Directive,
             args: [{}]
         }], ctorParameters: () => [] });
@@ -1274,10 +1581,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * 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 });
+    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.8", ngImport: i0, type: NgForgeFieldHost, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeFieldHost, decorators: [{
             type: Directive,
             args: [{
                     hostDirectives: [
@@ -1303,10 +1610,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * ```
  */
 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 });
+    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.8", ngImport: i0, type: NgForgeActionHost, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: NgForgeActionHost, decorators: [{
             type: Directive,
             args: [{
                     hostDirectives: [
@@ -1399,5 +1706,5 @@ function provideTestValidationMessages(messages) {
  * Generated bundle index. Do not edit.
  */
 
-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 };
+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