@radix-ng/primitives 1.0.9 → 1.1.0

package/types/radix-ng-primitives-core.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { Type, Provider, InputSignal, WritableSignal, ModelSignal, Signal, InjectionToken, InputSignalWithTransform, OutputRef, OutputEmitterRef, Injector, ElementRef, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions } from '@angular/core';
+import { InputSignal, InputSignalWithTransform, ModelSignal, OutputRef, Signal, Type, Provider, WritableSignal, ProviderToken, InjectionToken, OutputEmitterRef, Injector, ElementRef, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions } from '@angular/core';
 import { ControlValueAccessor } from '@angular/forms';
 import { DateValue, Time, CalendarDateTime, ZonedDateTime } from '@internationalized/date';
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
@@ -101,6 +101,114 @@ declare class RdxControlValueAccessor<T> implements ControlValueAccessor {
  */
 declare function injectControlValueAccessor<T>(): RdxControlValueAccessor<T>;
 
+/**
+ * Local mirror of Angular Signal Forms' control contracts
+ * (`@angular/forms/signals`, stable in Angular 22).
+ *
+ * These interfaces intentionally do **not** import from `@angular/forms/signals`,
+ * so control entries do not pull that optional integration into their public
+ * dependency graph. Primitives can still declare `implements RdxFormValueControl<T>` /
+ * `implements RdxFormCheckboxControl`; the mirror locks the public surface (the
+ * required `value` / `checked` signal) and catches naming regressions on CI — e.g.
+ * a rewrite renaming `value` → `modelValue` (as the slider once had) would no
+ * longer type-check.
+ *
+ * Optional state types are widened only where Radix NG controls legitimately
+ * differ from Angular's exact types (e.g. `input<string>()` produces
+ * `string | undefined`, and boolean inputs carry a coercion transform).
+ *
+ * The real Angular types stay isolated in `@radix-ng/primitives/signal-forms`.
+ * See ADR 0018 and `.claude/skills/project-knowledge/references/signal-forms-readiness.md`.
+ */
+/** An optional control-state member exposed as an Angular input signal (with or without a coercion transform). */
+type RdxFormStateInput<T> = InputSignal<T> | InputSignalWithTransform<T, any>;
+/**
+ * Minimal stand-in for Angular's `ValidationError`. The real type is a tagged
+ * union (`RequiredValidationError`, `PatternValidationError`, …); this keeps a
+ * shared shape until the v22 type is available.
+ */
+interface RdxValidationError {
+    readonly kind: string;
+    readonly message?: string;
+}
+/** Optional state shared by value and checkbox controls (mirror of Angular's `FormUiControl`). */
+interface RdxFormUiControl {
+    readonly disabled?: RdxFormStateInput<boolean>;
+    readonly readonly?: RdxFormStateInput<boolean>;
+    readonly required?: RdxFormStateInput<boolean>;
+    readonly invalid?: RdxFormStateInput<boolean>;
+    readonly hidden?: RdxFormStateInput<boolean>;
+    readonly pending?: RdxFormStateInput<boolean>;
+    /**
+     * Touched status the form writes into the control.
+     *
+     * The two API generations disagree on the notification half: the 21.x
+     * experimental implementation listens to a `touched` **model**'s
+     * `touchedChange` output, while stable Angular 22 reverted to a plain
+     * `touched` input plus a separate {@link touch} output. A `model()` set on
+     * blur **plus** an emitted `touch` output satisfies both (`ModelSignal`
+     * extends `InputSignalWithTransform`, so it type-checks as the 22 input).
+     */
+    readonly touched?: ModelSignal<boolean> | RdxFormStateInput<boolean> | OutputRef<boolean>;
+    readonly dirty?: RdxFormStateInput<boolean>;
+    readonly name?: RdxFormStateInput<string | undefined>;
+    readonly errors?: RdxFormStateInput<readonly RdxValidationError[]>;
+    readonly minLength?: RdxFormStateInput<number | undefined>;
+    readonly maxLength?: RdxFormStateInput<number | undefined>;
+    readonly pattern?: RdxFormStateInput<readonly RegExp[]>;
+    /** Notifies the form the control was touched (stable Angular 22 contract; ignored by 21.x). */
+    readonly touch?: OutputRef<void>;
+    /** Resets the control's UI state (optional method added in stable Angular 22). */
+    reset?(): void;
+}
+/**
+ * Mirror of `FormValueControl<TValue>` — a control that edits a single value via
+ * `value = model<TValue>()`. It must **not** expose `checked`.
+ */
+interface RdxFormValueControl<TValue> extends RdxFormUiControl {
+    readonly value: ModelSignal<TValue>;
+    readonly checked?: undefined;
+    readonly min?: RdxFormStateInput<NonNullable<TValue> | undefined>;
+    readonly max?: RdxFormStateInput<NonNullable<TValue> | undefined>;
+}
+/**
+ * Mirror of `FormCheckboxControl` — a control that toggles via
+ * `checked = model<boolean>()`. It must **not** expose `value`.
+ */
+interface RdxFormCheckboxControl extends RdxFormUiControl {
+    readonly checked: ModelSignal<boolean>;
+    readonly value?: undefined;
+}
+
+/**
+ * Form state owned by an Angular Reactive Forms or template-driven `NgControl` on the same host
+ * element. `connected` stays false for standalone and Signal Forms controls.
+ *
+ * @ignore
+ */
+interface RdxNgControlState {
+    readonly connected: Signal<boolean>;
+    readonly name: Signal<string | undefined>;
+    readonly value: Signal<unknown>;
+    readonly valid: Signal<boolean>;
+    readonly invalid: Signal<boolean>;
+    readonly pending: Signal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly errors: Signal<readonly RdxValidationError[]>;
+    readonly dirty: Signal<boolean>;
+    readonly touched: Signal<boolean>;
+}
+/**
+ * Lazily connects to the same-host `NgControl` without creating a circular dependency while Angular
+ * is resolving its `ControlValueAccessor`. The unified `AbstractControl.events` stream mirrors
+ * programmatic value, status, validation, and interaction-state changes as well as user-driven ones.
+ *
+ * Must be called in an injection context.
+ *
+ * @ignore
+ */
+declare function injectNgControlState(): RdxNgControlState;
+
 /**
  * Include in the providers section of a component which utilizes ControlValueAccessor to redundant code.
  *
@@ -453,21 +561,21 @@ declare function getSegmentElements(parentElement: HTMLElement): Element[];
 type UseDateFieldProps = {
     hasLeftFocus: WritableSignal<boolean>;
     lastKeyZero: WritableSignal<boolean>;
-    placeholder: ModelSignal<DateValue> | WritableSignal<DateValue>;
-    hourCycle: HourCycle;
+    placeholder: Signal<DateValue>;
+    hourCycle: HourCycle | undefined;
     formatter: Formatter;
     segmentValues: WritableSignal<SegmentValueObj>;
     step: Signal<DateStep>;
-    disabled: InputSignal<boolean>;
-    readonly: InputSignal<boolean>;
+    disabled: Signal<boolean>;
+    readonly: Signal<boolean>;
     part: SegmentPart;
-    modelValue: ModelSignal<DateValue | undefined> | WritableSignal<DateValue | undefined>;
+    modelValue: ModelSignal<DateValue | null> | WritableSignal<DateValue | null>;
     focusNext: () => void;
 };
 type SegmentAttrProps = {
     disabled: boolean;
     segmentValues: SegmentValueObj;
-    hourCycle: HourCycle;
+    hourCycle: HourCycle | undefined;
     placeholder: DateValue;
     formatter: Formatter;
 };
@@ -763,104 +871,28 @@ declare function isEqual(a: any, b: any): boolean;
  * of the specified class. This is especially useful when you want multiple
  * tokens (or interfaces) to resolve to the same directive/component instance.
  *
- * @template T - The type associated with the injection token.
- * @param token - The InjectionToken or abstract type you want to provide.
- * @param type  - The class type whose existing instance will be used for this token.
+ * `Type<T>` ties the class to the token's contract, so a class that does not
+ * satisfy `T` is rejected at compile time instead of failing at runtime.
+ *
+ * @template T - The type associated with the provider token.
+ * @param token - The token (InjectionToken, class, or abstract class) to provide.
+ * @param type  - The class whose existing instance resolves this token; must satisfy `T`.
  * @returns A Provider configuration object for Angular's DI system.
  *
  * @example
  *
  * @Directive({
  *   providers: [
- *     provideToken(RdxFooToken, RdxFooDirective),
+ *     provideExistingToken(RdxFooToken, RdxFooDirective),
  *     provideValueAccessor(RdxFooDirective)
  *   ]
  * })
  * export class RdxFooDirective {}
  */
-declare function provideToken<T>(token: InjectionToken<T>, type: Type<unknown>): Provider;
+declare function provideExistingToken<T>(token: ProviderToken<T>, type: Type<T>): Provider;
 
 /**
- * Local mirror of Angular Signal Forms' control contracts
- * (`@angular/forms/signals`, stable in Angular 22).
- *
- * These interfaces intentionally do **not** import from `@angular/forms/signals`
- * so primitives can declare `implements RdxFormValueControl<T>` /
- * `implements RdxFormCheckboxControl` while the library baseline is still on
- * Angular 21, where the real API is experimental. They mirror Angular's contract
- * closely enough to lock the public surface (the required `value` / `checked`
- * signal) and catch naming regressions on CI — e.g. a rewrite renaming
- * `value` → `modelValue` (as the slider once had) would no longer type-check.
- *
- * Optional state types are widened only where Radix NG controls legitimately
- * differ from Angular's exact types (e.g. `input<string>()` produces
- * `string | undefined`, and boolean inputs carry a coercion transform).
- *
- * Replace with the real imports once the baseline moves to Angular 22.
- * See `.claude/skills/project-knowledge/references/signal-forms-readiness.md`.
- */
-/** An optional control-state member exposed as an Angular input signal (with or without a coercion transform). */
-type RdxFormStateInput<T> = InputSignal<T> | InputSignalWithTransform<T, any>;
-/**
- * Minimal stand-in for Angular's `ValidationError`. The real type is a tagged
- * union (`RequiredValidationError`, `PatternValidationError`, …); this keeps a
- * shared shape until the v22 type is available.
- */
-interface RdxValidationError {
-    readonly kind: string;
-    readonly message?: string;
-}
-/** Optional state shared by value and checkbox controls (mirror of Angular's `FormUiControl`). */
-interface RdxFormUiControl {
-    readonly disabled?: RdxFormStateInput<boolean>;
-    readonly readonly?: RdxFormStateInput<boolean>;
-    readonly required?: RdxFormStateInput<boolean>;
-    readonly invalid?: RdxFormStateInput<boolean>;
-    readonly hidden?: RdxFormStateInput<boolean>;
-    readonly pending?: RdxFormStateInput<boolean>;
-    /**
-     * Touched status the form writes into the control.
-     *
-     * The two API generations disagree on the notification half: the 21.x
-     * experimental implementation listens to a `touched` **model**'s
-     * `touchedChange` output, while stable Angular 22 reverted to a plain
-     * `touched` input plus a separate {@link touch} output. A `model()` set on
-     * blur **plus** an emitted `touch` output satisfies both (`ModelSignal`
-     * extends `InputSignalWithTransform`, so it type-checks as the 22 input).
-     */
-    readonly touched?: ModelSignal<boolean> | RdxFormStateInput<boolean> | OutputRef<boolean>;
-    readonly dirty?: RdxFormStateInput<boolean>;
-    readonly name?: RdxFormStateInput<string | undefined>;
-    readonly errors?: RdxFormStateInput<readonly RdxValidationError[]>;
-    readonly minLength?: RdxFormStateInput<number | undefined>;
-    readonly maxLength?: RdxFormStateInput<number | undefined>;
-    readonly pattern?: RdxFormStateInput<readonly RegExp[]>;
-    /** Notifies the form the control was touched (stable Angular 22 contract; ignored by 21.x). */
-    readonly touch?: OutputRef<void>;
-    /** Resets the control's UI state (optional method added in stable Angular 22). */
-    reset?(): void;
-}
-/**
- * Mirror of `FormValueControl<TValue>` — a control that edits a single value via
- * `value = model<TValue>()`. It must **not** expose `checked`.
- */
-interface RdxFormValueControl<TValue> extends RdxFormUiControl {
-    readonly value: ModelSignal<TValue>;
-    readonly checked?: undefined;
-    readonly min?: RdxFormStateInput<NonNullable<TValue> | undefined>;
-    readonly max?: RdxFormStateInput<NonNullable<TValue> | undefined>;
-}
-/**
- * Mirror of `FormCheckboxControl` — a control that toggles via
- * `checked = model<boolean>()`. It must **not** expose `value`.
- */
-interface RdxFormCheckboxControl extends RdxFormUiControl {
-    readonly checked: ModelSignal<boolean>;
-    readonly value?: undefined;
-}
-
-/**
- * Optional form-control UI state derived from a control's `invalid`/`errors`/`touched`/`dirty`
+ * Optional form-control UI state derived from a control's `invalid`/`pending`/`errors`/`touched`/`dirty`
  * inputs (the optional members of Signal Forms' `FormUiControl`), plus the two mutators every
  * control needs.
  *
@@ -869,6 +901,12 @@ interface RdxFormCheckboxControl extends RdxFormUiControl {
 interface RdxFormUiState {
     /** Invalid when the `invalid` input is set or the `errors` list is non-empty. */
     readonly invalidState: Signal<boolean>;
+    /** Whether asynchronous validation is still settling. Pending is neither valid nor invalid. */
+    readonly pendingState: Signal<boolean>;
+    /** Tri-state validity: valid / invalid / neutral while pending or disabled. */
+    readonly validState: Signal<boolean | null>;
+    /** Explicit control errors merged with same-host Angular Forms errors. */
+    readonly errorsState: Signal<readonly RdxValidationError[]>;
     /** Whether the control has been touched (reflects the `touched` model). */
     readonly touchedState: Signal<boolean>;
     /** Whether the value changed from its initial value — external `dirty` OR internal tracking. */
@@ -877,6 +915,10 @@ interface RdxFormUiState {
     markAsTouched(): void;
     /** Flag the control dirty after a value change (feeds {@link dirtyState}). */
     markDirty(): void;
+    /** Clear control-owned touched/dirty state when a form resets it. */
+    resetInteractionState?(): void;
+    /** Clear only control-owned dirty state when the form marks the field pristine. */
+    resetDirtyState?(): void;
 }
 /** Minimal `ControlValueAccessor` surface the form-UI state bridges for the dual (Reactive/template) path. */
 interface RdxFormUiTouchTarget {
@@ -885,20 +927,24 @@ interface RdxFormUiTouchTarget {
 /** Inputs a control passes to {@link createFormUiState} — its own `FormUiControl` signals. */
 interface RdxFormUiStateOptions {
     readonly invalid: Signal<boolean>;
+    /** Optional for backwards compatibility with custom controls authored before pending support. */
+    readonly pending?: Signal<boolean>;
     readonly errors: Signal<readonly RdxValidationError[]>;
     readonly touched: ModelSignal<boolean>;
     readonly touch: OutputEmitterRef<void>;
     readonly dirty: Signal<boolean>;
+    /** Same-host Reactive/template-driven form interaction state, when one is present. */
+    readonly ngControlState?: RdxNgControlState | null;
     /**
      * The control's `ControlValueAccessor`, if it has one (dual controls — switch, number-field, …).
-     * Omit or pass `null` for Signal-Forms-only controls without a CVA (e.g. select).
+     * Omit or pass `null` for Signal-Forms-only controls without a CVA (e.g. date-field).
      */
     readonly cva?: RdxFormUiTouchTarget | null;
 }
 /**
  * Builds the shared form-UI state and its mutators from a control's input signals, removing the
- * per-control copy-paste of the `invalidState`/`touchedState`/`dirtyState` computeds and the
- * `markAsTouched`/`markDirty` logic.
+ * per-control copy-paste of the validation/interaction computeds and the `markAsTouched`/`markDirty`
+ * logic.
  *
  * **Why the inputs stay on the control (not in here):** Angular's compiler only discovers
  * `input()`/`model()` declared as field initializers, and Signal Forms binds form-written state
@@ -916,6 +962,8 @@ declare function createFormUiState(options: RdxFormUiStateOptions): RdxFormUiSta
  */
 interface RdxFormUiStateContext {
     invalidState: Signal<boolean>;
+    pendingState: Signal<boolean>;
+    validState: Signal<boolean | null>;
     touchedState: Signal<boolean>;
     dirtyState: Signal<boolean>;
     markAsTouched: () => void;
@@ -936,14 +984,14 @@ declare const RDX_FIELD_VALIDITY: InjectionToken<Signal<boolean | null>>;
 /**
  * Tri-state display validity: when inside a `Field` the field's gated `validState` is the **single
  * source** (the control reflects it, including its `validationMode` neutral state); standalone, the
- * control's own binary invalidity.
+ * control's own tri-state validity (pending is neutral).
  *
  * **Contract:** inside a `Field` a control's own `invalid` / `errors` inputs are **not** displayed — the
  * Field owns displayed validity. Drive validity through the Field instead: bind `rdxSignalField`
  * (Signal Forms), or set `[invalid]` on `rdxFieldRoot`. The control's own `invalid`/`errors` are for
  * standalone use.
  */
-declare function resolveDisplayValid(fieldValidity: Signal<boolean | null> | null, ownInvalid: Signal<boolean>): boolean | null;
+declare function resolveDisplayValid(fieldValidity: Signal<boolean | null> | null, ownInvalid: Signal<boolean>, ownPending?: Signal<boolean>): boolean | null;
 /**
  * Provide a control's {@link RdxFormUiState} on its host element so {@link RdxFormUiStateHost} can
  * reflect it. Pair with `hostDirectives: [RdxFormUiStateHost]`:
@@ -982,7 +1030,7 @@ declare class RdxFormUiStateHost {
 }
 /**
  * Abstract base that declares the optional `FormUiControl` state inputs
- * (`invalid`/`errors`/`touched`/`dirty` + the `touch` output) once and builds the control's
+ * (`invalid`/`pending`/`errors`/`touched`/`dirty` + the `touch` output) once and builds the control's
  * {@link RdxFormUiState} from them, so a control directive can inherit the whole surface with a
  * single `extends` instead of re-declaring it.
  *
@@ -999,6 +1047,8 @@ declare class RdxFormUiStateHost {
 declare abstract class RdxFormUiControlBase {
     /** Whether the control is invalid. A non-empty {@link errors} list also marks it invalid. */
     readonly invalid: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether async validation is pending. Pending controls publish neither `data-valid` nor `data-invalid`. */
+    readonly pending: i0.InputSignalWithTransform<boolean, BooleanInput>;
     /** Whether the control has been touched. A `model()` so Signal Forms can write it; set on blur/focus-out. */
     readonly touched: ModelSignal<boolean>;
     /** Whether the value changed from its initial value. Merged with internal tracking. */
@@ -1007,8 +1057,12 @@ declare abstract class RdxFormUiControlBase {
     readonly errors: i0.InputSignal<readonly RdxValidationError[]>;
     /** Emits when the control is touched, notifying Signal Forms (stable Angular 22 contract). */
     readonly touch: OutputEmitterRef<void>;
+    private readonly ngControlState;
     /** The shared form-UI state derived from the inputs above. Call `formUi.markDirty()` on value change. */
     readonly formUi: RdxFormUiState;
+    /** Validation errors from the control inputs and a same-host Reactive/template-driven form control. */
+    readonly validationErrors: Signal<readonly RdxValidationError[]>;
+    constructor();
     /** The enclosing Field's tri-state display validity, if any. `protected` so a control whose own
      * invalidity is richer than `formUi.invalidState` (e.g. date/time-field add a parse check) can build
      * its own `displayValid` from it. */
@@ -1016,19 +1070,26 @@ declare abstract class RdxFormUiControlBase {
     /**
      * Tri-state *displayed* validity for controls that bind their own host attributes (radio, switch,
      * number-field): the enclosing Field's gated state when inside a `rdxFieldRoot`, else this control's
-     * own binary invalidity (`formUi.invalidState`). Bind `data-valid`/`data-invalid`/`aria-invalid` to
+     * own validity (`formUi.pendingState` is neutral; otherwise `formUi.invalidState` is binary). Bind
+     * `data-valid`/`data-invalid`/`aria-invalid` to
      * this so a neutral field shows neither. Controls whose `invalidState` is richer than
-     * `formUi.invalidState` override this with `resolveDisplayValid(this.fieldValidity, this.invalidState)`.
+     * `formUi.invalidState` override this with
+     * `resolveDisplayValid(this.fieldValidity, this.invalidState, this.formUi.pendingState)`.
      */
     readonly displayValid: Signal<boolean | null>;
     /**
      * Override to bridge the control's `ControlValueAccessor` into `markAsTouched` (dual controls —
      * return `injectControlValueAccessor()` or a `{ markAsTouched }` adapter). Default: no CVA
-     * (Signal-Forms-only controls such as select).
+     * (Signal-Forms-only controls such as date-field).
      */
     protected formUiTouchTarget(): RdxFormUiTouchTarget | null;
+    /**
+     * Reset control-owned interaction state. Angular Signal Forms calls this optional custom-control
+     * hook from `FieldState.reset()` after restoring the field value.
+     */
+    reset(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<RdxFormUiControlBase, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxFormUiControlBase, never, never, { "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "dirty": { "alias": "dirty"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; }, { "touched": "touchedChange"; "touch": "touch"; }, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxFormUiControlBase, never, never, { "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "pending": { "alias": "pending"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "dirty": { "alias": "dirty"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; }, { "touched": "touchedChange"; "touch": "touch"; }, never, never, true, never>;
 }
 
 /**
@@ -2053,5 +2114,5 @@ declare enum RdxPositionAlign {
     End = "end"
 }
 
-export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, DOCS_BASE_URL, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RDX_DEFAULT_VALIDATION_MODE, RDX_FIELD_VALIDITY, RDX_FLOATING_REGISTRATION, RDX_FLOATING_ROOT_CONTEXT, RDX_FLOATING_TREE, RDX_FORM_UI_STATE, RDX_INTERNAL_BACKDROP_ATTR, RDX_SCROLL_LOCKED_ATTR, RdxControlValueAccessor, RdxFloatingNode, RdxFloatingNodeRegistration, RdxFloatingRegistrationContext, RdxFloatingRootContext, RdxFloatingTree, RdxFormUiControlBase, RdxFormUiStateHost, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, RdxTriggerRegistry, SHIFT, SPACE, SPACE_CODE, TAB, TIME_GRANULARITIES, a, areAllDaysBetweenValid, clamp, createCancelableChangeEventDetails, createContent, createContext, createFloatingEvents, createFloatingRootContext, createFormUiState, createFormatter, createMonth, createMonths, docsUrl, elementSize, formUiStateContext, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectFloatingRootContext, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isItemEqualToValue, isNullish, isNumberString, isSegmentNavigationKey, isValidationRevealed, isZonedDateTime, itemToStringLabel, itemToStringValue, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideFloatingRegistration, provideFloatingRootContext, provideFloatingTree, provideFormUiState, provideToken, provideValueAccessor, rdxCheckLabelElement, rdxCheckTriggerElement, rdxDevError, rdxDevWarning, resetRdxDevWarnings, resizeEffect, resolveDisplayValid, resolveFloatingTree, roundToStepPrecision, segmentBuilders, setupInternalBackdrop, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useAnchoredScrollLock, useArrowNavigation, useDateField, useFilter, useGraceArea, useListHighlight, usePointerDrag, useScrollLock, useTransitionStatus, watch };
-export type { AcceptableValue, AnyExceptLiteral, AriaLivePoliteness, BooleanInput, CreateMonthProps, DataOrientation, DateAndTimeSegmentObj, DateFormatterOptions, DateMatcher, DateRange, DateSegmentObj, DateSegmentPart, DateStep, DayPeriod, Direction, EditableSegmentPart, FilterPredicates, Formatter, Granularity, HourCycle, InjectContext, ItemValueComparator, ListHighlight, Month, NonEditableSegmentPart, Nullable, NumberInput, PlaceholderMap, RdxAnchoredScrollLockOptions, RdxCancelableChangeEventDetails, RdxCancelableChangeEventTransaction, RdxFloatingEventMap, RdxFloatingEvents, RdxFloatingLifecycle, RdxFloatingNodeInit, RdxFloatingParentOverride, RdxFloatingRegistrationReader, RdxFloatingRegistrationStatus, RdxFloatingRootContextEventMap, RdxFloatingRootContextInit, RdxFormCheckboxControl, RdxFormStateInput, RdxFormUiControl, RdxFormUiState, RdxFormUiStateContext, RdxFormUiStateOptions, RdxFormUiTouchTarget, RdxFormValueControl, RdxInternalBackdropOptions, RdxPointerDragHandlers, RdxScrollLockOptions, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, RdxValidationInteraction, RdxValidationMode, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps, UseFilterOptions, UseListHighlightOptions };
+export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, DOCS_BASE_URL, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RDX_DEFAULT_VALIDATION_MODE, RDX_FIELD_VALIDITY, RDX_FLOATING_REGISTRATION, RDX_FLOATING_ROOT_CONTEXT, RDX_FLOATING_TREE, RDX_FORM_UI_STATE, RDX_INTERNAL_BACKDROP_ATTR, RDX_SCROLL_LOCKED_ATTR, RdxControlValueAccessor, RdxFloatingNode, RdxFloatingNodeRegistration, RdxFloatingRegistrationContext, RdxFloatingRootContext, RdxFloatingTree, RdxFormUiControlBase, RdxFormUiStateHost, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, RdxTriggerRegistry, SHIFT, SPACE, SPACE_CODE, TAB, TIME_GRANULARITIES, a, areAllDaysBetweenValid, clamp, createCancelableChangeEventDetails, createContent, createContext, createFloatingEvents, createFloatingRootContext, createFormUiState, createFormatter, createMonth, createMonths, docsUrl, elementSize, formUiStateContext, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectFloatingRootContext, injectId, injectNgControlState, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isItemEqualToValue, isNullish, isNumberString, isSegmentNavigationKey, isValidationRevealed, isZonedDateTime, itemToStringLabel, itemToStringValue, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideExistingToken, provideFloatingRegistration, provideFloatingRootContext, provideFloatingTree, provideFormUiState, provideValueAccessor, rdxCheckLabelElement, rdxCheckTriggerElement, rdxDevError, rdxDevWarning, resetRdxDevWarnings, resizeEffect, resolveDisplayValid, resolveFloatingTree, roundToStepPrecision, segmentBuilders, setupInternalBackdrop, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useAnchoredScrollLock, useArrowNavigation, useDateField, useFilter, useGraceArea, useListHighlight, usePointerDrag, useScrollLock, useTransitionStatus, watch };
+export type { AcceptableValue, AnyExceptLiteral, AriaLivePoliteness, BooleanInput, CreateMonthProps, DataOrientation, DateAndTimeSegmentObj, DateFormatterOptions, DateMatcher, DateRange, DateSegmentObj, DateSegmentPart, DateStep, DayPeriod, Direction, EditableSegmentPart, FilterPredicates, Formatter, Granularity, HourCycle, InjectContext, ItemValueComparator, ListHighlight, Month, NonEditableSegmentPart, Nullable, NumberInput, PlaceholderMap, RdxAnchoredScrollLockOptions, RdxCancelableChangeEventDetails, RdxCancelableChangeEventTransaction, RdxFloatingEventMap, RdxFloatingEvents, RdxFloatingLifecycle, RdxFloatingNodeInit, RdxFloatingParentOverride, RdxFloatingRegistrationReader, RdxFloatingRegistrationStatus, RdxFloatingRootContextEventMap, RdxFloatingRootContextInit, RdxFormCheckboxControl, RdxFormStateInput, RdxFormUiControl, RdxFormUiState, RdxFormUiStateContext, RdxFormUiStateOptions, RdxFormUiTouchTarget, RdxFormValueControl, RdxInternalBackdropOptions, RdxNgControlState, RdxPointerDragHandlers, RdxScrollLockOptions, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, RdxValidationInteraction, RdxValidationMode, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps, UseFilterOptions, UseListHighlightOptions };

package/types/radix-ng-primitives-date-field.d.ts

@@ -4,11 +4,12 @@ import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
 import { RdxFormUiControlBase, RdxFormValueControl, DateMatcher, HourCycle, Granularity, Direction, BooleanInput, DateStep, Formatter, SegmentValueObj, SegmentPart } from '@radix-ng/primitives/core';
 import { DateValue } from '@internationalized/date';
 
-declare class RdxDateFieldRootDirective extends RdxFormUiControlBase implements RdxFormValueControl<DateValue | undefined> {
+declare class RdxDateFieldRootDirective extends RdxFormUiControlBase implements RdxFormValueControl<DateValue | null> {
     /**
-     * The controlled value of the date field.
+     * The controlled value of the date field. `null` represents an empty field and keeps the value
+     * addressable as an Angular Signal Forms child field (`undefined` denotes an absent optional path).
      */
-    readonly value: _angular_core.ModelSignal<DateValue | undefined>;
+    readonly value: _angular_core.ModelSignal<DateValue | null>;
     /**
      * A matcher that marks specific dates as unavailable; a matched value makes the field invalid.
      */
@@ -64,6 +65,13 @@ declare class RdxDateFieldRootDirective extends RdxFormUiControlBase implements
      * The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar and can be used to programmatically control the calendar view
      */
     readonly placeholder: _angular_core.ModelSignal<DateValue | undefined>;
+    /**
+     * Always-defined placeholder used for segment math. A controlled `[placeholder]` can be reset to
+     * `undefined`; fall back to the default date so segment attributes and key handlers never
+     * dereference `undefined`.
+     * @ignore
+     */
+    readonly effectivePlaceholder: Signal<DateValue>;
     /**
      * Segment input parts, collected from the projected content in DOM order. This
      * stays in sync with `segmentContents()` (granularity / locale / value changes
@@ -115,6 +123,8 @@ declare class RdxDateFieldRootDirective extends RdxFormUiControlBase implements
     private readonly userInteracted;
     /** @ignore Mark the field touched (model + `touch` output) for Signal Forms. Called on segment blur. */
     markAsTouched(): void;
+    /** Reset segment interaction so the form-owned value write remains pristine. */
+    reset(): void;
     /**
      * @ignore
      */
@@ -228,16 +238,19 @@ declare class RdxDateFieldInputDirective {
 
 interface DateFieldContextToken {
     locale: InputSignal<string>;
-    value: ModelSignal<DateValue | undefined>;
-    disabled: InputSignal<boolean>;
-    readonly: InputSignal<boolean>;
+    value: ModelSignal<DateValue | null>;
+    disabled: Signal<boolean>;
+    readonly: Signal<boolean>;
     isInvalid: Signal<boolean>;
     /** Effective invalid: the built-in range/availability check OR the form-driven invalid state. */
     invalidState: Signal<boolean>;
     /** Tri-state displayed validity (`true`/`false`/`null`): the field's gated state inside a Field, else own. */
     displayValid: Signal<boolean | null>;
-    placeholder: ModelSignal<DateValue>;
-    hourCycle: InputSignal<HourCycle>;
+    /** The controlled placeholder; may be `undefined`. Use `effectivePlaceholder` for segment math. */
+    placeholder: Signal<DateValue | undefined>;
+    /** Always-defined placeholder (falls back to the default date) for segment attributes/key handlers. */
+    effectivePlaceholder: Signal<DateValue>;
+    hourCycle: Signal<HourCycle | undefined>;
     step$: Signal<DateStep>;
     formatter: Signal<Formatter>;
     segmentValues: WritableSignal<SegmentValueObj>;

package/types/radix-ng-primitives-field.d.ts

@@ -63,6 +63,15 @@ declare class RdxFieldError {
      * @group Props
      */
     readonly id: _angular_core.InputSignal<string>;
+    /**
+     * Shows this error only for a matching validation-error key. Bind `true` to keep it visible under
+     * external control; omit it for the field's default error behavior.
+     *
+     * @group Props
+     */
+    readonly match: _angular_core.InputSignal<string | boolean | undefined>;
+    /** Whether this error part is currently presented. */
+    readonly visible: _angular_core.Signal<boolean>;
     /**
      * The field's validation messages — client (provider / form name-routing, once `validationMode`
      * reveals them) then server (the Form's `errors` input, always); `[]` when none. Render them
@@ -73,12 +82,11 @@ declare class RdxFieldError {
     constructor();
     protected readonly dataAttr: (value: boolean) => "" | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldError, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldError, "[rdxFieldError]", ["rdxFieldError"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldError, "[rdxFieldError]", ["rdxFieldError"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "match": { "alias": "match"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * External owner of field state. An adapter (e.g. a future Signal Forms
- * `[rdxSignalField]` directive, or a Reactive Forms bridge) registers one via
+ * External owner of field state. An adapter (`rdxSignalField` or `rdxNgControlField`) registers one via
  * `setStateProvider` so Field reads authoritative form state instead of
  * self-computing it from the DOM. Each member is an optional signal-like
  * accessor; only the states the adapter owns need to be provided — the rest
@@ -86,15 +94,19 @@ declare class RdxFieldError {
  * `() => boolean` accessors keeps Field framework-agnostic (no dependency on
  * `@angular/forms/signals`).
  *
- * See ADR 0004 and `signal-forms-readiness.md` (prep #4).
+ * See ADR 0004, ADR 0021, and `signal-forms-readiness.md` (prep #4).
  */
 interface RdxFieldState {
+    /** Field name inferred by an adapter. An explicit `rdxFieldRoot[name]` always wins. */
+    name?: () => string | undefined;
     /**
      * The control's **actual** invalidity (ungated). The Field decides *when* to display it from its
      * `validationMode` (e.g. only after blur) — the adapter just reports the real state. A non-empty
      * `errors()` also counts as invalid.
      */
     invalid?: () => boolean;
+    /** Whether async validation is pending. Pending validity remains neutral, never falsely valid. */
+    pending?: () => boolean;
     disabled?: () => boolean;
     required?: () => boolean;
     dirty?: () => boolean;
@@ -108,7 +120,7 @@ interface RdxFieldState {
      * any enclosing Form's server messages. Uses `core`'s framework-free shim type so the seam stays free of
      * `@angular/forms/signals` (ADR 0004 amendment).
      */
-    errors?: () => RdxValidationError[];
+    errors?: () => readonly RdxValidationError[];
 }
 interface RdxFieldRootContext {
     controlId: Signal<string>;
@@ -116,6 +128,8 @@ interface RdxFieldRootContext {
     descriptionIds: Signal<string[]>;
     errorIds: Signal<string[]>;
     messages: Signal<string[]>;
+    /** Whether the currently displayed client errors contain this validation kind. */
+    matchesError: (kind: string) => boolean;
     notifyEdited: () => void;
     /** Tri-state *displayed* validity (`true` valid / `false` invalid / `null` neutral), gated by the
      * field's `validationMode`. The source for `data-valid` / `data-invalid` on the field and its controls. */
@@ -229,6 +243,8 @@ declare class RdxFieldRoot {
     private readonly stateProvider;
     /** Whether an external adapter currently owns field state. */
     readonly hasStateProvider: Signal<boolean>;
+    /** Explicit field name wins; an adapter may infer one from its form-control binding. */
+    readonly effectiveName: Signal<string | undefined>;
     /** Error content from a registered state provider (e.g. a Signal Forms adapter). */
     private readonly providerErrors;
     /** **Client** validation errors routed by a form-level provider (`rdxSignalForm`) — gated by `validationMode`. */
@@ -246,6 +262,8 @@ declare class RdxFieldRoot {
      * field state), so deduping renders it once while still surfacing distinct messages from each source.
      */
     readonly messages: Signal<string[]>;
+    /** Whether a client validation error of `kind` is currently revealed by the field. */
+    matchesError(kind: string): boolean;
     /** Effective validation-display mode: this field's override → the enclosing Form's → the default. */
     readonly effectiveValidationMode: Signal<RdxValidationMode>;
     /** Whether client-side validity is revealed yet, per {@link effectiveValidationMode} + interaction. */
@@ -276,6 +294,7 @@ declare class RdxFieldRoot {
      * the provider/input `invalid`.
      */
     readonly actualInvalidState: Signal<boolean>;
+    readonly pendingState: Signal<boolean>;
     readonly disabledState: Signal<boolean>;
     readonly requiredState: Signal<boolean>;
     readonly dirtyState: Signal<boolean>;
@@ -310,8 +329,8 @@ declare class RdxFieldRoot {
     clearStateProvider(provider: RdxFieldState | null, previous: RdxFieldState | null): void;
     /**
      * Prefer the registered provider's value for `key` when it exposes one,
-     * otherwise fall back to the root inputs / DOM-derived signals. `errors` (content) and `valid`
-     * (tri-state `boolean | null`) are resolved separately, so they're excluded from this boolean key.
+     * otherwise fall back to the root inputs / DOM-derived signals. `name` and `errors` are resolved
+     * separately, so they're excluded from this boolean key.
      */
     private resolve;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldRoot, never>;
@@ -369,5 +388,33 @@ declare class RdxFieldLabel {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldLabel, "[rdxFieldLabel]", ["rdxFieldLabel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { RdxFieldControl, RdxFieldDescription, RdxFieldError, RdxFieldItem, RdxFieldLabel, RdxFieldRoot, injectFieldRootContext, provideFieldRootContext };
+/**
+ * Bridges a same-host Reactive Forms or template-driven `NgControl` into an enclosing `rdxFieldRoot`.
+ * Place it next to `formControl`, `formControlName`, or `ngModel`; Angular remains the source of value,
+ * validation, and interaction state while Field owns when that state is displayed.
+ *
+ * ```html
+ * <div rdxFieldRoot>
+ *   <label rdxFieldLabel>Email</label>
+ *   <input formControlName="email" rdxFieldControl rdxNgControlField />
+ *   <p match="required" rdxFieldError>Email is required.</p>
+ * </div>
+ * ```
+ *
+ * The adapter also infers the Field name from `formControlName` / `ngModel` for Form-level server-error
+ * routing. An explicit `name` on `rdxFieldRoot` takes precedence (useful for nested or remapped keys).
+ *
+ * @group Components
+ */
+declare class RdxNgControlField {
+    private readonly ngControlState;
+    private readonly fieldContext;
+    /** Normalized Angular validation errors (`{ kind, message? }[]`). */
+    readonly validationErrors: _angular_core.Signal<readonly _radix_ng_primitives_core.RdxValidationError[]>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxNgControlField, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxNgControlField, "[formControl][rdxNgControlField], [formControlName][rdxNgControlField], [ngModel][rdxNgControlField]", ["rdxNgControlField"], {}, {}, never, never, true, never>;
+}
+
+export { RdxFieldControl, RdxFieldDescription, RdxFieldError, RdxFieldItem, RdxFieldLabel, RdxFieldRoot, RdxNgControlField, injectFieldRootContext, provideFieldRootContext };
 export type { RdxFieldRootContext, RdxFieldState };

package/types/radix-ng-primitives-floating-focus-manager.d.ts

@@ -162,6 +162,13 @@ declare class RdxFloatingFocusManager {
      * - an element (direct or from a callback) → that element (returned **explicitly**, bypassing the
      *   "focus moved elsewhere" guard).
      */
+    /**
+     * Public view of {@link resolveReturnFocusTarget} for a **keep-mounted** primitive to apply
+     * return-focus on *close* — the composed scope's unmount-driven return never runs while the popup
+     * stays in the DOM. Returns an explicit element, `false` (suppress), or `undefined` (default →
+     * caller restores the previously-focused element, e.g. the trigger).
+     */
+    resolveReturnTarget(): HTMLElement | false | undefined;
     private resolveReturnFocusTarget;
     /**
      * Base UI's `defaultInitialFocus`: on a **touch** open, focus the popup itself instead of its first