@ng-forge/dynamic-forms 0.10.0-next.2 → 0.10.0-next.4

package/types/ng-forge-dynamic-forms-integration.d.ts

@@ -1,5 +1,7 @@
-import { FormEvent, FieldDef, FormEventConstructor, StateLogicConfig, BaseCheckedField, FieldMeta, BaseValueField, FieldOption, ArrayAllowedChildren, NonFieldLogicConfig, NextPageEvent, PreviousPageEvent, FieldWithValidation, ValidationMessages, DynamicText, ArrayItemContext, AnyAddon, BaseAddon, AddonActionHandler, DynamicValue, WrapperFieldInputs, AddonActionContext, EventBus } from '@ng-forge/dynamic-forms';
-export { FieldWrapper, InferWrapperRegistry, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle, createWrappers, isEqual, isWrappersBundle, resolveNonFieldDisabled, resolveNonFieldHidden, wrapperProps } from '@ng-forge/dynamic-forms';
+import { FormEvent, FormEventConstructor, NextPageEvent, PreviousPageEvent, FieldWithValidation, ArrayItemContext, BaseAddon, AddonActionHandler, DynamicValue } from '@ng-forge/dynamic-forms';
+export { ADDON_ACTION_HANDLERS, ADDON_ACTION_REGISTRY, ADDON_KIND_COMPONENT_CACHE, ADDON_KIND_DEFINITIONS, ADDON_KIND_REGISTRY, AddonActionHandler, BUILT_IN_FIELDS, FieldAddonSupportEntry, FieldWrapper, InferWrapperRegistry, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PresetCollaborators, WrapperRegistration, WrapperTypeDefinition, WrappersBundle, createWrappers, injectAddonKindRegistry, injectFieldsSupportingAddons, isWrappersBundle, resolveNonFieldDisabled, resolveNonFieldHidden, runPresetAction, wrapperProps } from '@ng-forge/dynamic-forms';
+import { FieldDef, StateLogicConfig, BaseCheckedField, FieldMeta, BaseValueField, FieldOption, ArrayAllowedChildren, NonFieldLogicConfig, ValidationMessages, DynamicText, AnyAddon, WrapperFieldInputs, AddonActionContext, EventBus } from '@ng-forge/dynamic-forms/internal';
+export { ARRAY_CONTEXT, ArrayContext, ArrayFieldTree, CheckedFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FormFieldStateMap, GROUP_CONTEXT, HttpResourceRequest, INITIALIZATION_TIMEOUT_MS, MapperFn, ReadonlyFieldTree, RootFormRegistryService, ValueFieldComponent, ValueHandlingMode, WrapperFieldInputs, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, dynamicTextToObservable, getArrayLength, groupFieldMapper, injectFieldSignalContext, interpolateParams, isEqual, pageFieldMapper, resolveDynamicValue, resolveTokens, rowFieldMapper, textFieldMapper, toReadonlyFieldTree, withPreviousValue, writeToFieldValue } from '@ng-forge/dynamic-forms/internal';
 import * as i0 from '@angular/core';
 import { Signal, Injector, ElementRef, InjectionToken, Provider, WritableSignal, Type } from '@angular/core';
 import { FieldTree, SchemaPath } from '@angular/forms/signals';
@@ -8,17 +10,9 @@ import { ComponentFixture } from '@angular/core/testing';
 /**
  * Event arguments that can contain static values or tokens to be resolved at runtime.
  * Tokens supported: $key, $index, $arrayKey, $template, formValue
- *
- * Used by the generic button type when manually configuring events.
  */
 type EventArgs = readonly (string | number | boolean | null | undefined)[];
-/**
- * Base interface for button fields.
- *
- * This is used by the generic 'button' type which requires explicit event configuration.
- * For specific button types (submit, next, previous, array buttons), use the
- * pre-configured types from the UI library instead.
- */
+/** Base interface for button fields. */
 interface ButtonField<TProps, TEvent extends FormEvent> extends FieldDef<TProps> {
     type: 'button';
     event: FormEventConstructor<TEvent>;
@@ -30,10 +24,6 @@ interface ButtonField<TProps, TEvent extends FormEvent> extends FieldDef<TProps>
      * - $arrayKey: The parent array field key (if inside an array field)
      * - $template: The template for array item creation (for array add buttons)
      * - formValue: Access to the current form value for indexing
-     *
-     * @example
-     * eventArgs: ['$arrayKey', '$index']
-     * eventArgs: ['contacts', 0]
      */
     eventArgs?: EventArgs;
     /** Logic rules for dynamic disabled state (overrides form-level defaults) */
@@ -81,71 +71,31 @@ type EnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | '
  * @see https://html.spec.whatwg.org/multipage/interaction.html#attr-autocapitalize
  */
 type Autocapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
-/**
- * Meta attributes specific to HTML input elements.
- *
- * Extends FieldMeta with input-specific native attributes that can be passed through
- * to the underlying input element.
- *
- * @example
- * ```typescript
- * // Input field with meta attributes
- * {
- *   type: 'input',
- *   key: 'email',
- *   meta: {
- *     autocomplete: 'email',
- *     inputmode: 'email',
- *     enterkeyhint: 'next',
- *     spellcheck: false,
- *     'data-testid': 'email-input'
- *   }
- * }
- * ```
- *
- * @public
- */
+/** Meta attributes specific to HTML input elements. */
 interface InputMeta extends FieldMeta {
-    /**
-     * Hint for form autofill behavior.
-     */
+    /** Hint for form autofill behavior. */
     autocomplete?: AutocompleteValue;
-    /**
-     * Hint for virtual keyboard type on mobile devices.
-     */
+    /** Hint for virtual keyboard type on mobile devices. */
     inputmode?: InputMode;
-    /**
-     * Hint for the enter key label on virtual keyboards.
-     */
+    /** Hint for the enter key label on virtual keyboards. */
     enterkeyhint?: EnterKeyHint;
-    /**
-     * Whether to enable spellchecking for the input.
-     */
+    /** Whether to enable spellchecking for the input. */
     spellcheck?: boolean;
-    /**
-     * Hint for autocapitalization behavior on virtual keyboards.
-     */
+    /** Hint for autocapitalization behavior on virtual keyboards. */
     autocapitalize?: Autocapitalize;
-    /**
-     * Pattern for client-side validation (regex).
-     */
+    /** Pattern for client-side validation (regex). */
     pattern?: string;
-    /**
-     * Size hint for the input element (character count).
-     */
+    /** Size hint for the input element (character count). */
     size?: number;
-    /**
-     * Maximum number of characters allowed.
-     */
+    /** Maximum number of characters allowed. */
     maxlength?: number;
-    /**
-     * Minimum number of characters required.
-     */
+    /** Minimum number of characters required. */
     minlength?: number;
 }
 
 /**
  * All valid HTML input types per MDN specification.
+ *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types
  */
 type HtmlInputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'datetime-local' | 'month' | 'week' | 'time' | 'color' | 'range' | 'checkbox' | 'radio' | 'file' | 'hidden' | 'button' | 'submit' | 'reset' | 'image';
@@ -159,14 +109,7 @@ type HtmlInputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' |
  * - file, hidden, button, etc. → dedicated fields
  */
 type InputType = Extract<HtmlInputType, 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search'>;
-/**
- * Infers the TypeScript value type for a given input type.
- *
- * @example
- * type NumberValue = InferInputValue<'number'>; // number
- * type TextValue = InferInputValue<'text'>; // string
- * type DateValue = InferInputValue<'date'>; // string (extended types)
- */
+/** Infers the TypeScript value type for a given input type. */
 type InferInputValue<T extends HtmlInputType> = T extends 'number' ? number : string;
 /**
  * @deprecated Use `InferInputValue` instead. Will be removed in v1.0.0.
@@ -175,14 +118,6 @@ type InputTypeToValueType<T extends InputType> = InferInputValue<T>;
 /**
  * Props for input fields with optional type specification.
  * Generic parameter allows extending InputType with additional HtmlInputType values.
- *
- * @example
- * // Default usage
- * interface MyProps extends InputProps { ... }
- *
- * // Extended input types (e.g., supporting date inputs)
- * type ExtendedType = InputType | 'date' | 'time';
- * interface ExtendedProps extends InputProps<ExtendedType> { ... }
  */
 interface InputProps<T extends HtmlInputType = InputType> {
     /**
@@ -195,17 +130,9 @@ interface InputProps<T extends HtmlInputType = InputType> {
 /**
  * Input types that produce numeric values.
  * Currently only 'number' produces a numeric value in HTML inputs.
- *
- * @example
- * type Numeric = NumericInputType; // 'number'
  */
 type NumericInputType<T extends HtmlInputType = InputType> = Extract<T, 'number'>;
-/**
- * Input types that produce string values.
- *
- * @example
- * type Strings = StringInputType; // Exclude<InputType, 'number'>
- */
+/** Input types that produce string values. */
 type StringInputType<T extends HtmlInputType = InputType> = Exclude<T, 'number'>;
 /**
  * Number input field with strict number value type.
@@ -248,30 +175,6 @@ type BuildInputFieldUnion<TProps extends {
 /**
  * Input field with automatic type-safe value inference.
  * TypeScript automatically infers the correct value type based on props.type.
- *
- * @example
- * // Direct usage - automatic strict type safety
- * const numberField: InputField = {
- *   type: 'input',
- *   key: 'age',
- *   props: { type: 'number' },
- *   value: 25 // ✓ number only (string is type error!)
- * };
- *
- * const textField: InputField = {
- *   type: 'input',
- *   key: 'name',
- *   props: { type: 'text' },
- *   value: 'hello' // ✓ string only (number is type error!)
- * };
- *
- * @example
- * // Framework usage - extend with custom props
- * interface MatInputProps extends InputProps {
- *   appearance?: 'fill' | 'outline';
- *   hint?: string;
- * }
- * type MatInputField = InputField<MatInputProps>; // Automatically gets discriminated union
  */
 type InputField<TProps extends {
     type?: string;
@@ -280,18 +183,6 @@ type InputField<TProps extends {
 /**
  * Multi-checkbox field for selecting multiple values from a list of options.
  * The value is an array of selected option values.
- *
- * @example
- * const tagsField: MultiCheckboxField<string> = {
- *   type: 'multi-checkbox',
- *   key: 'tags',
- *   value: ['tag1', 'tag2'], // Array of selected values
- *   options: [
- *     { label: 'Tag 1', value: 'tag1' },
- *     { label: 'Tag 2', value: 'tag2' },
- *     { label: 'Tag 3', value: 'tag3' }
- *   ]
- * };
  */
 interface MultiCheckboxField<TValue, TProps = object, TNullable extends boolean = boolean> extends BaseValueField<TProps, TValue[], FieldMeta, TNullable> {
     type: 'multi-checkbox';
@@ -326,29 +217,7 @@ interface SliderField<TProps, TNullable extends boolean = boolean> extends BaseV
  * @see https://html.spec.whatwg.org/multipage/form-elements.html#attr-textarea-wrap
  */
 type TextareaWrap = 'hard' | 'soft' | 'off';
-/**
- * Meta attributes specific to HTML textarea elements.
- *
- * Extends FieldMeta with textarea-specific native attributes that can be passed through
- * to the underlying textarea element.
- *
- * @example
- * ```typescript
- * // Textarea field with meta attributes
- * {
- *   type: 'textarea',
- *   key: 'description',
- *   meta: {
- *     wrap: 'soft',
- *     spellcheck: true,
- *     autocomplete: 'off',
- *     'data-testid': 'description-textarea'
- *   }
- * }
- * ```
- *
- * @public
- */
+/** Meta attributes specific to HTML textarea elements. */
 interface TextareaMeta extends FieldMeta {
     /**
      * How text should wrap when submitted.
@@ -357,29 +226,17 @@ interface TextareaMeta extends FieldMeta {
      * - 'off': No wrapping, horizontal scrolling if needed
      */
     wrap?: TextareaWrap;
-    /**
-     * Whether to enable spellchecking for the textarea.
-     */
+    /** Whether to enable spellchecking for the textarea. */
     spellcheck?: boolean;
-    /**
-     * Hint for form autofill behavior.
-     */
+    /** Hint for form autofill behavior. */
     autocomplete?: AutocompleteValue;
-    /**
-     * Hint for autocapitalization behavior on virtual keyboards.
-     */
+    /** Hint for autocapitalization behavior on virtual keyboards. */
     autocapitalize?: Autocapitalize;
-    /**
-     * Hint for the enter key label on virtual keyboards.
-     */
+    /** Hint for the enter key label on virtual keyboards. */
     enterkeyhint?: EnterKeyHint;
-    /**
-     * Maximum number of characters allowed.
-     */
+    /** Maximum number of characters allowed. */
     maxlength?: number;
-    /**
-     * Minimum number of characters required.
-     */
+    /** Minimum number of characters required. */
     minlength?: number;
 }
 
@@ -399,10 +256,6 @@ interface ToggleField<TProps, TNullable extends boolean = boolean> extends BaseC
 /**
  * Context for value field mapping, containing the injected context reference.
  * Used by specialized mappers to avoid duplicate injection.
- *
- * Note: The field tree is resolved lazily via getFieldTree() to support
- * reactive form access (e.g., for array items where the form structure
- * may not exist at injection time but becomes available later).
  */
 interface ValueFieldContext {
     /**
@@ -416,14 +269,6 @@ interface ValueFieldContext {
  * Creates a value field context from the injected FIELD_SIGNAL_CONTEXT.
  * Must be called within an injection context.
  *
- * With direct root form binding for array items, the FIELD_SIGNAL_CONTEXT.form
- * uses a getter that evaluates reactively. This means:
- * - For regular fields: direct access to the form's FieldTree
- * - For array items: the getter resolves rootForm['arrayKey'][index] dynamically
- *
- * The returned context provides a getFieldTree function that should be called
- * inside a computed to establish proper reactive dependencies.
- *
  * @returns The value field context with reactive field tree accessor
  */
 declare function resolveValueFieldContext(): ValueFieldContext;
@@ -431,9 +276,6 @@ declare function resolveValueFieldContext(): ValueFieldContext;
  * Builds the base inputs for a value field.
  * This is a helper function used by valueFieldMapper and specialized mappers.
  *
- * Note: This function should be called inside a computed signal to ensure
- * proper reactive dependency tracking for the field tree resolution.
- *
  * @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)
@@ -443,20 +285,6 @@ declare function buildValueFieldInputs<TProps, TValue = unknown>(fieldDef: BaseV
 /**
  * Maps a value field definition to component inputs.
  *
- * Value fields are input fields that contribute to the form's value (text, number, etc.).
- * This mapper injects FIELD_SIGNAL_CONTEXT to access the form structure and retrieve the field proxy.
- *
- * For array items, the FIELD_SIGNAL_CONTEXT.form uses a reactive getter that resolves
- * rootForm['arrayKey'][index] dynamically. This means:
- * - Zod/StandardSchema validation errors are automatically available
- * - The field tree updates reactively when the root form structure changes
- * - Newly added array items will get their field tree once the form value updates
- *
- * For fields with specific properties, use the specialized mappers:
- * - optionsFieldMapper: for fields with options (select, radio, multi-checkbox)
- * - datepickerFieldMapper: for fields with minDate, maxDate, startAt
- * - checkboxFieldMapper: for boolean fields (checkbox, toggle)
- *
  * @param fieldDef The value field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -465,9 +293,6 @@ declare function valueFieldMapper<TProps = unknown, TValue = unknown>(fieldDef:
 /**
  * Maps a checkbox/toggle field definition to component inputs.
  *
- * Checkbox fields are checked fields that contribute to the form's value as boolean.
- * This mapper injects FIELD_SIGNAL_CONTEXT to access the form structure and retrieve the field tree.
- *
  * @param fieldDef The checkbox field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -476,28 +301,16 @@ declare function checkboxFieldMapper(fieldDef: BaseCheckedField<unknown, FieldMe
 /**
  * Maps a datepicker field to component inputs.
  *
- * Extends the base value field mapper by adding datepicker-specific properties:
- * - minDate: Minimum selectable date
- * - maxDate: Maximum selectable date
- * - startAt: Initial date to display when opening the picker
- *
- * Date values are automatically converted from strings to Date objects
- * since UI libraries (Material, PrimeNG, etc.) expect Date objects.
- *
  * @param fieldDef The datepicker field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
 declare function datepickerFieldMapper<TProps>(fieldDef: DatepickerField<TProps>): Signal<Record<string, unknown>>;
 
-/**
- * Field types that have an options property.
- */
+/** Field types that have an options property. */
 type FieldWithOptions<T = unknown, TProps = unknown> = SelectField<T, TProps> | RadioField<T, TProps> | MultiCheckboxField<T, TProps>;
 /**
  * Maps a field with options (select, radio, multi-checkbox) to component inputs.
  *
- * Extends the base value field mapper by adding the options property.
- *
  * @param fieldDef The field definition with options
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -506,17 +319,6 @@ declare function optionsFieldMapper<T, TProps>(fieldDef: FieldWithOptions<T, TPr
 /**
  * Maps a button field to component inputs.
  *
- * Unlike value field mappers, button fields do not participate in form values
- * and do not need field tree resolution or validation messages.
- *
- * Button-specific properties:
- * - event: The FormEvent constructor to emit when clicked
- * - eventArgs: Optional arguments to pass to the event constructor
- *
- * Hidden and disabled states are resolved using non-field logic resolvers which consider:
- * 1. Explicit `hidden: true` / `disabled: true` on the field definition
- * 2. Field-level `logic` array with `type: 'hidden'` or `type: 'disabled'` conditions
- *
  * @param fieldDef The button field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -536,9 +338,7 @@ interface ArrayButtonContext {
     /** Whether this button is inside an array context */
     isInsideArray: boolean;
 }
-/**
- * Event context passed to button components for array operations.
- */
+/** Event context passed to button components for array operations. */
 interface ArrayButtonEventContext {
     /** The button field key */
     key: string;
@@ -557,11 +357,6 @@ interface ArrayButtonEventContext {
 /**
  * Resolves array button context for button mappers.
  *
- * Handles both inside-array (context from ARRAY_CONTEXT) and
- * outside-array (explicit arrayKey) placements.
- *
- * Must be called in injection context.
- *
  * @param fieldKey The button field key (for logging)
  * @param buttonType The button type name (for logging)
  * @param explicitArrayKey Optional explicit arrayKey from field definition
@@ -571,8 +366,6 @@ declare function resolveArrayButtonContext(fieldKey: string, buttonType: string,
 /**
  * Builds the event context passed to the button component.
  *
- * Should be called inside a computed to track index signal changes.
- *
  * @param fieldKey The button field key
  * @param ctx The resolved array button context
  * @param template Optional template for add operations (single field or array of fields)
@@ -670,9 +463,7 @@ declare function popArrayItemButtonMapper<TProps>(fieldDef: BaseArrayRemoveButto
 /** Mapper for shift array item button — removes the first item from array. */
 declare function shiftArrayItemButtonMapper<TProps>(fieldDef: BaseArrayRemoveButtonField<TProps>): Signal<Record<string, unknown>>;
 
-/**
- * Base interface for navigation button fields (submit, next, previous).
- */
+/** Base interface for navigation button fields (submit, next, previous). */
 type BaseNavigationButtonField<TProps = unknown> = ButtonField<TProps, SubmitEvent | NextPageEvent | PreviousPageEvent> & {
     type: string;
     /** Logic rules for dynamic disabled state */
@@ -688,9 +479,7 @@ declare function nextButtonFieldMapper<TProps>(fieldDef: BaseNavigationButtonFie
 /** Mapper for previous page button — preconfigures PreviousPageEvent. */
 declare function previousButtonFieldMapper<TProps>(fieldDef: BaseNavigationButtonField<TProps>): Signal<Record<string, unknown>>;
 
-/**
- * Resolved validation error with interpolated message
- */
+/** Resolved validation error with interpolated message */
 interface ResolvedError {
     kind: string;
     message: string;
@@ -704,15 +493,6 @@ interface ResolvedError {
  * @param defaultValidationMessages - Signal containing default validation messages (fallback)
  * @param injector - Optional injector for DynamicText resolution
  * @returns Signal<ResolvedError[]> - Reactively resolved error messages
- *
- * @example
- * ```typescript
- * readonly resolvedErrors = createResolvedErrorsSignal(
- *   this.field,
- *   this.validationMessages,
- *   this.defaultValidationMessages
- * );
- * ```
  */
 declare function createResolvedErrorsSignal<T>(field: Signal<FieldTree<T>>, validationMessages: Signal<ValidationMessages | undefined>, defaultValidationMessages?: Signal<ValidationMessages | undefined>, injector?: Injector): Signal<ResolvedError[]>;
 
@@ -725,68 +505,25 @@ declare function createResolvedErrorsSignal<T>(field: Signal<FieldTree<T>>, vali
  */
 declare function shouldShowErrors<T>(field: Signal<FieldTree<T>>): Signal<boolean>;
 
-/**
- * Configuration options for setupMetaTracking.
- */
+/** Configuration options for setupMetaTracking. */
 interface MetaTrackingOptions {
     /**
      * CSS selector for target elements within the host.
      * If not provided, meta attributes are applied directly to the host element.
-     *
-     * @example
-     * // Apply to internal radio inputs
-     * selector: 'input[type="radio"]'
-     *
-     * // Apply to host element (for Shadow DOM components)
-     * selector: undefined
      */
     selector?: string;
     /**
      * Additional signals to track that should trigger re-application of meta.
      * Useful for components where DOM elements are dynamically created (e.g., radio options).
-     *
-     * @example
-     * // Re-apply when options change
-     * dependents: [this.options]
      */
     dependents?: Signal<unknown>[];
 }
 /**
  * Sets up automatic meta attribute tracking and application for wrapped components.
  *
- * This utility creates an `afterRenderEffect` that applies meta attributes to DOM elements
- * after Angular's render cycle. It efficiently tracks signal dependencies and only re-applies
- * when the meta signal or any dependent signals change.
- *
- * Use this instead of MutationObserver for better performance and integration with Angular's
- * change detection.
- *
  * @param elementRef - Reference to the host element
  * @param meta - Signal containing meta attributes to apply
  * @param options - Configuration options
- *
- * @example
- * ```typescript
- * // For a radio group with dynamic options
- * constructor() {
- *   setupMetaTracking(inject(ElementRef), this.meta, {
- *     selector: 'input[type="radio"]',
- *     dependents: [this.options]
- *   });
- * }
- *
- * // For a simple checkbox
- * constructor() {
- *   setupMetaTracking(inject(ElementRef), this.meta, {
- *     selector: 'input[type="checkbox"]'
- *   });
- * }
- *
- * // For Shadow DOM components (apply to host)
- * constructor() {
- *   setupMetaTracking(inject(ElementRef), this.meta);
- * }
- * ```
  */
 declare function setupMetaTracking(elementRef: ElementRef<HTMLElement>, meta: Signal<FieldMeta | undefined>, options?: MetaTrackingOptions): void;
 
@@ -808,16 +545,6 @@ declare function createAriaDescribedBySignal(errorsToDisplay: Signal<ResolvedErr
  * 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.
  */
 declare class NgForgeFieldShell {
     readonly key: i0.InputSignal<string>;
@@ -833,21 +560,6 @@ declare const NG_FORGE_FIELD_SHELL_INPUTS: readonly ["key", "className"];
  * 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>
  *     }
@@ -912,12 +624,6 @@ type TypedNgForgeField<T> = Omit<NgForgeField, 'field'> & {
  * `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
- * ```
  */
 declare function injectNgForgeField<T = unknown>(): TypedNgForgeField<T>;
 
@@ -927,24 +633,6 @@ declare function injectNgForgeField<T = unknown>(): TypedNgForgeField<T>;
  * 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.
  */
 declare class NgForgeAction<TEvent extends FormEvent = FormEvent> {
     private readonly shell;
@@ -981,11 +669,6 @@ declare const NG_FORGE_ACTION_INPUTS: readonly ["label", "disabled", "hidden", "
 /**
  * Typed wrapper around `inject(NgForgeAction)`. The generic narrows the
  * `event` input to a specific FormEvent subclass.
- *
- * @example
- * ```ts
- * protected readonly action = injectNgForgeAction<SubmitEvent>();
- * ```
  */
 declare function injectNgForgeAction<TEvent extends FormEvent = FormEvent>(): NgForgeAction<TEvent>;
 
@@ -1030,10 +713,6 @@ declare const NG_FORGE_ADDONS_INPUTS: readonly ["addons"];
 /**
  * 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) {
@@ -1087,11 +766,6 @@ interface ActionAddonShape extends BaseAddon {
  * 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.
  */
 declare class NgForgeAddonActionBase {
     private readonly actionRegistry;
@@ -1128,22 +802,6 @@ declare class NgForgeAddonActionBase {
      * 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(): AddonActionContext;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddonActionBase, never>;
@@ -1151,22 +809,7 @@ declare class NgForgeAddonActionBase {
 }
 /** Forwarded onto `NgForgeAddonActionBase` via the `NgForgeAddonAction` wrapper. */
 declare const NG_FORGE_ADDON_ACTION_INPUTS: readonly ["addon", "fieldInputs"];
-/**
- * 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>();
- * }
- * ```
- */
+/** Host wrapper for `NgForgeAddonActionBase`. Consumers compose this directly: */
 declare class NgForgeAddonAction {
     static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddonAction, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAddonAction, never, never, {}, {}, never, never, true, [{ directive: typeof NgForgeAddonActionBase; inputs: { "addon": "addon"; "fieldInputs": "fieldInputs"; }; outputs: {}; }]>;
@@ -1183,10 +826,6 @@ declare function injectNgForgeAddonAction<TAddon extends ActionAddonShape = Acti
  * (`NgForgeAddonAction`) delegates to this when an addon configures a
  * `preset`; the adapter wires concrete preset semantics in its own
  * provider scope.
- *
- * `NgForgeAddonAction` injects this with `{ optional: true }`. Addons that
- * configure a preset on an adapter that hasn't registered a handler get a
- * lenient warning at click time.
  */
 interface AddonPresetHandler {
     run(preset: string, ctx: AddonActionContext): void | Promise<void>;
@@ -1199,26 +838,6 @@ declare const ADDON_PRESET_HANDLER: InjectionToken<AddonPresetHandler>;
  * 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" />
  * }
@@ -1238,24 +857,6 @@ declare class NgForgeControl {
  * (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 { ... }
- * ```
  */
 declare class NgForgeHostControl {
     constructor();
@@ -1268,26 +869,6 @@ declare class NgForgeHostControl {
  * 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/
  */
 declare class NgForgeFieldHost {
     static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeFieldHost, never>;
@@ -1297,17 +878,6 @@ declare class NgForgeFieldHost {
  * 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();
- * }
- * ```
  */
 declare class NgForgeActionHost {
     static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeActionHost, never>;
@@ -1337,9 +907,6 @@ interface NgForgeFieldFixture<C, TValue = unknown> {
  * 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).
  */
 declare function createNgForgeFieldFixture<C, TValue = unknown>(component: Type<C>, options: CreateNgForgeFieldFixtureOptions<TValue>): NgForgeFieldFixture<C, TValue>;
 interface CreateNgForgeActionFixtureOptions<TEvent extends FormEvent = FormEvent> {