@radix-ng/primitives 1.0.10 → 1.1.1

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

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { Type, Provider, InputSignal, WritableSignal, Signal, ModelSignal, ProviderToken, InputSignalWithTransform, OutputRef, InjectionToken, 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,116 @@ 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>;
+    /** Resets a connected Reactive/template-driven control; returns whether one was connected. */
+    reset(value: unknown): 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.
  *
@@ -461,7 +571,7 @@ type UseDateFieldProps = {
     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 = {
@@ -665,8 +775,9 @@ type ItemValueComparator<T = unknown> = ((a: T, b: T) => boolean) | string;
  */
 declare function itemToStringLabel(value: unknown): string;
 /**
- * Converts an item value to the string used for form serialization. Defaults to the same rules as
- * {@link itemToStringLabel}; kept as a separate export so a primitive can diverge label vs. value.
+ * Converts an item value to the string used for form serialization. A conventional `{ value, label }`
+ * item serializes its `value` member; other non-string values use Base UI-compatible JSON serialization
+ * with `String()` as a fallback. Kept separate so a primitive can diverge label vs. value.
  */
 declare function itemToStringValue(value: unknown): string;
 /**
@@ -784,86 +895,7 @@ declare function isEqual(a: any, b: any): boolean;
 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.
  *
@@ -872,6 +904,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. */
@@ -880,6 +918,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 {
@@ -888,20 +930,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
@@ -919,6 +965,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;
@@ -939,14 +987,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]`:
@@ -985,7 +1033,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.
  *
@@ -1002,6 +1050,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. */
@@ -1010,8 +1060,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. */
@@ -1019,19 +1073,32 @@ 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;
+    /**
+     * Resets a same-host Reactive/template-driven control without reporting the reset as a user edit.
+     * Returns `false` when no Angular `NgControl` is connected, so a control can fall back to its CVA
+     * change callback for an unusually early native reset.
+     */
+    protected resetNgControl(value: unknown): boolean;
+    /**
+     * 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>;
 }
 
 /**
@@ -1737,6 +1804,55 @@ declare function elementSize({ elementRef, injector }: {
  */
 declare function getActiveElement(root?: DocumentOrShadowRoot): Element | null;
 
+/** Configuration for a composite control that participates in a native HTML form. */
+interface RdxNativeFormControlOptions<T> {
+    /** Form-field name. No value is contributed while it is absent. */
+    readonly name: Signal<string | undefined>;
+    /** Optional id of an external owning form. */
+    readonly form: Signal<string | undefined>;
+    /** Disabled controls are excluded from successful form controls. */
+    readonly disabled: Signal<boolean>;
+    /** Current control value, used when the form constructs `FormData`. */
+    readonly value?: Signal<T>;
+    /** Converts a value to one or more form entries. Omit for controls with their own native inputs. */
+    readonly serialize?: (value: T) => readonly string[];
+    /** Whether a consumer-rendered native input currently owns serialization. */
+    readonly hasNativeControl?: Signal<boolean>;
+    /** Synchronizes a consumer-rendered native control immediately before an imperative submit. */
+    readonly syncNativeControl?: () => void;
+    /** Value restored by a native form reset. Captured once after inputs bind. */
+    readonly defaultValue?: () => T;
+    /** Applies the captured default value after a native form reset. */
+    readonly onReset?: (value: T) => void;
+}
+/** Imperative operations needed by controls that submit immediately after a value change. */
+interface RdxNativeFormControl {
+    /** The current owning form, including an external form selected by the `form` input. */
+    ownerForm(): HTMLFormElement | null;
+    /** Synchronizes generated/native controls with the current signals. */
+    sync(): void;
+    /** Synchronizes the value and requests submission from the owning form. */
+    requestSubmit(): void;
+}
+/**
+ * Converts a scalar or array model to HTML form values. `null` and `undefined` represent no
+ * successful control; arrays deliberately become repeated entries under the same field name.
+ */
+declare function serializeNativeFormValue(value: unknown, itemToStringValue?: (entry: unknown) => string): readonly string[];
+/**
+ * Adds native form semantics to a composite control, rendering hidden inputs only when the control
+ * has no native successful control of its own.
+ *
+ * A hidden input is necessary for a headless root to enter the platform's successful-controls tree
+ * (including older engines that do not dispatch `formdata` for `new FormData(form)`). One input is
+ * created per serialized value, preserving repeated-field semantics; controls with their own native
+ * input use this solely for reset and imperative-submit coordination.
+ *
+ * Generated inputs are browser-only. Rendering imperative sibling nodes on the server would put DOM
+ * outside Angular's hydration graph; the client creates them after its view has been claimed instead.
+ */
+declare function useNativeFormControl<T>(options: RdxNativeFormControlOptions<T>): RdxNativeFormControl;
+
 /**
  * Creates a resize observer effect for element
  *
@@ -2056,5 +2172,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, 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, 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, serializeNativeFormValue, setupInternalBackdrop, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useAnchoredScrollLock, useArrowNavigation, useDateField, useFilter, useGraceArea, useListHighlight, useNativeFormControl, 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, RdxNativeFormControl, RdxNativeFormControlOptions, 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.
      */
@@ -122,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
      */
@@ -235,7 +238,7 @@ declare class RdxDateFieldInputDirective {
 
 interface DateFieldContextToken {
     locale: InputSignal<string>;
-    value: ModelSignal<DateValue | undefined>;
+    value: ModelSignal<DateValue | null>;
     disabled: Signal<boolean>;
     readonly: Signal<boolean>;
     isInvalid: Signal<boolean>;

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-form.d.ts

@@ -49,6 +49,13 @@ interface RdxFormState {
     dirty?: () => boolean;
     touched?: () => boolean;
     submitting?: () => boolean;
+    /**
+     * Optional Angular-owned submission lifecycle. Returning `undefined` keeps the Form's Base UI-style
+     * synchronous submit path; returning a Promise delegates this submit to the adapter. Signal Forms
+     * uses this only when its opt-in `rdxSignalSubmit` input is present, and calls Angular's public
+     * `submit()` API so validation, touched state, concurrency, and submission errors stay Angular-owned.
+     */
+    submit?: () => Promise<boolean> | undefined;
     /**
      * Per-name **client** validation errors (e.g. `rdxSignalForm`'s Signal Forms name-routing). Surfaced
      * through the Form's `clientErrorsFor` channel and gated by `validationMode` like any client validity.
@@ -190,6 +197,8 @@ declare class RdxFormRoot {
      */
     clearStateProvider(provider: RdxFormState | null, previous: RdxFormState | null): void;
     onSubmit(event: SubmitEvent): void;
+    private finishDelegatedSubmit;
+    private focusFirstInvalidField;
     onReset(): void;
     private readonly resetTimers;
     constructor();