@radix-ng/primitives 1.0.7 → 1.0.9

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, Injector, ElementRef, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions } from '@angular/core';
+import { Type, Provider, InputSignal, WritableSignal, ModelSignal, Signal, InjectionToken, InputSignalWithTransform, OutputRef, 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';
@@ -859,6 +859,209 @@ interface RdxFormCheckboxControl extends RdxFormUiControl {
     readonly value?: undefined;
 }
 
+/**
+ * Optional form-control UI state derived from a control's `invalid`/`errors`/`touched`/`dirty`
+ * inputs (the optional members of Signal Forms' `FormUiControl`), plus the two mutators every
+ * control needs.
+ *
+ * @see createFormUiState
+ */
+interface RdxFormUiState {
+    /** Invalid when the `invalid` input is set or the `errors` list is non-empty. */
+    readonly invalidState: Signal<boolean>;
+    /** 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. */
+    readonly dirtyState: Signal<boolean>;
+    /** Mark the control touched: bridges the CVA (if any) + sets the `touched` model + emits `touch`. */
+    markAsTouched(): void;
+    /** Flag the control dirty after a value change (feeds {@link dirtyState}). */
+    markDirty(): void;
+}
+/** Minimal `ControlValueAccessor` surface the form-UI state bridges for the dual (Reactive/template) path. */
+interface RdxFormUiTouchTarget {
+    markAsTouched(): void;
+}
+/** Inputs a control passes to {@link createFormUiState} — its own `FormUiControl` signals. */
+interface RdxFormUiStateOptions {
+    readonly invalid: Signal<boolean>;
+    readonly errors: Signal<readonly RdxValidationError[]>;
+    readonly touched: ModelSignal<boolean>;
+    readonly touch: OutputEmitterRef<void>;
+    readonly dirty: Signal<boolean>;
+    /**
+     * 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).
+     */
+    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.
+ *
+ * **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
+ * (`errors`/`disabled`/`touched`) onto the single directive that carries the `value`/`checked`
+ * model — so the inputs must co-locate with `value` on the control directive. This helper takes
+ * those signals and centralizes only the derivation.
+ *
+ * Safe to call from a field initializer: `signal()`/`computed()` need no injection context.
+ */
+declare function createFormUiState(options: RdxFormUiStateOptions): RdxFormUiState;
+/**
+ * The subset of a compound primitive's context that surfaces the shared form-UI state to its child
+ * parts (so a trigger/button/input can reflect `data-invalid`/`data-touched`/`data-dirty` and call
+ * `markAsTouched()`). Compound-control context interfaces should `extends` this.
+ */
+interface RdxFormUiStateContext {
+    invalidState: Signal<boolean>;
+    touchedState: Signal<boolean>;
+    dirtyState: Signal<boolean>;
+    markAsTouched: () => void;
+}
+/** Spread helper to wire {@link RdxFormUiStateContext} fields from an {@link RdxFormUiState} into a context factory. */
+declare function formUiStateContext(state: RdxFormUiState): RdxFormUiStateContext;
+/** DI token holding the control's {@link RdxFormUiState}, read by {@link RdxFormUiStateHost}. */
+declare const RDX_FORM_UI_STATE: InjectionToken<RdxFormUiState>;
+/**
+ * Tri-state *displayed* validity (`true` valid / `false` invalid / `null` neutral) an enclosing `Field`
+ * exposes so a control can reflect the field's single, gated display-state instead of its own eager
+ * invalid. A control inside a `rdxFieldRoot` reads this for its `data-valid` / `data-invalid` /
+ * `aria-invalid`; standalone (token absent) it falls back to its own binary invalidity. This keeps the
+ * field root, the control, and any trigger/group part on one display-state (Base UI's `valid: boolean |
+ * null`). `Field` provides it (`useFactory` over the root's `validState`).
+ */
+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.
+ *
+ * **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;
+/**
+ * Provide a control's {@link RdxFormUiState} on its host element so {@link RdxFormUiStateHost} can
+ * reflect it. Pair with `hostDirectives: [RdxFormUiStateHost]`:
+ *
+ * ```ts
+ * providers: [provideFormUiState(() => inject(MyControl).formUi)],
+ * hostDirectives: [RdxFormUiStateHost]
+ * ```
+ */
+declare function provideFormUiState(state: () => RdxFormUiState): Provider;
+/**
+ * Host directive that reflects a control's {@link RdxFormUiState} as the standard validation
+ * `data-*`/`aria-invalid` attributes and marks the control touched on focus-out — the binding block
+ * that was otherwise copy-pasted into every form control's `host`.
+ *
+ * Compose it via `hostDirectives` on a control (or group root) whose host element is the one that
+ * should carry the attributes, and provide the state with {@link provideFormUiState}. It reads the
+ * state from DI, so the control does not need to expose `invalidState`/`touchedState`/`dirtyState`
+ * or a `markAsTouched` method just for the host bindings.
+ *
+ * Note: the `focusout` listener marks touched for controls whose touched-trigger is blur/focus-out
+ * (text inputs, groups). Controls that latch touched on interaction instead (e.g. checkbox) still do
+ * so themselves; the extra focus-out call only ever sets `touched` to `true`, so it is harmless.
+ *
+ * Not for compound controls that surface state on a child part via context (e.g. select reflects on
+ * its trigger) — those keep their own child-part bindings.
+ */
+declare class RdxFormUiStateHost {
+    /** @ignore The injected state the host bindings read. */
+    protected readonly formUi: RdxFormUiState;
+    private readonly fieldValidity;
+    /** @ignore Tri-state display validity (enclosing Field's gated state, else own invalidity). */
+    protected readonly displayValid: Signal<boolean | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RdxFormUiStateHost, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxFormUiStateHost, never, never, {}, {}, never, never, true, never>;
+}
+/**
+ * Abstract base that declares the optional `FormUiControl` state inputs
+ * (`invalid`/`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.
+ *
+ * The declarations must live on a decorated **directive class** (Angular only discovers
+ * `input()`/`model()`/`output()` as field initializers, and Signal Forms binds form-written state
+ * onto the single directive carrying the `value`/`checked` model) — inheritance keeps them on that
+ * directive, which a host directive could not. The control still declares its own `value`/`checked`
+ * model (the type-parametric part) and, for `data-*` reflection, either composes
+ * {@link RdxFormUiStateHost} or binds the attributes itself.
+ *
+ * Dual controls override {@link formUiTouchTarget} to bridge their `ControlValueAccessor` into
+ * `markAsTouched`.
+ */
+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 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. */
+    readonly dirty: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Validation errors for the control. A non-empty list marks it invalid. */
+    readonly errors: i0.InputSignal<readonly RdxValidationError[]>;
+    /** Emits when the control is touched, notifying Signal Forms (stable Angular 22 contract). */
+    readonly touch: OutputEmitterRef<void>;
+    /** The shared form-UI state derived from the inputs above. Call `formUi.markDirty()` on value change. */
+    readonly formUi: RdxFormUiState;
+    /** 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. */
+    protected readonly fieldValidity: Signal<boolean | null> | null;
+    /**
+     * 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
+     * this so a neutral field shows neither. Controls whose `invalidState` is richer than
+     * `formUi.invalidState` override this with `resolveDisplayValid(this.fieldValidity, this.invalidState)`.
+     */
+    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).
+     */
+    protected formUiTouchTarget(): RdxFormUiTouchTarget | null;
+    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>;
+}
+
+/**
+ * When a `Field` reveals its validity (the `data-valid` / `data-invalid` styling and the error message)
+ * — the form-system-agnostic equivalent of Base UI's `validationMode` and Angular Material's
+ * `ErrorStateMatcher`. The control/adapter always reports the **actual** state (`invalid` / `errors` /
+ * `touched` / `dirty`); the Field decides **when** to surface it from this mode.
+ *
+ * - `'always'` — reflect validity immediately (an empty required field shows its error on first render).
+ * - `'onChange'` — reveal once the user has changed the value (dirty), or the form submitted. A blur
+ *   alone does not reveal — that is `'onBlur'`'s behavior.
+ * - `'onBlur'` — reveal once the field has been touched (blurred), or the form submitted (the default).
+ * - `'onSubmit'` — reveal only after a submit has been attempted.
+ *
+ * Server/external errors are **not** gated by this mode — they surface immediately (they were set
+ * explicitly, e.g. from a submit response).
+ */
+type RdxValidationMode = 'always' | 'onChange' | 'onBlur' | 'onSubmit';
+/** The default validation-display mode when neither `rdxFieldRoot` nor `rdxFormRoot` sets one. */
+declare const RDX_DEFAULT_VALIDATION_MODE: RdxValidationMode;
+/** The field interaction state {@link isValidationRevealed} reads to decide whether to reveal validity. */
+interface RdxValidationInteraction {
+    touched: boolean;
+    dirty: boolean;
+    submitAttempted: boolean;
+}
+/**
+ * Whether a Field should reveal its (client-side) validity given the {@link RdxValidationMode} and the
+ * field's interaction state. `false` means stay neutral (neither `data-valid` nor `data-invalid`, error
+ * hidden); `true` means reflect the actual validity.
+ */
+declare function isValidationRevealed(mode: RdxValidationMode, interaction: RdxValidationInteraction): boolean;
+
 interface RdxCancelableChangeEventDetails<Reason extends string = string> {
     reason: Reason;
     event: Event;
@@ -1850,5 +2053,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_FLOATING_REGISTRATION, RDX_FLOATING_ROOT_CONTEXT, RDX_FLOATING_TREE, RDX_INTERNAL_BACKDROP_ATTR, RDX_SCROLL_LOCKED_ATTR, RdxControlValueAccessor, RdxFloatingNode, RdxFloatingNodeRegistration, RdxFloatingRegistrationContext, RdxFloatingRootContext, RdxFloatingTree, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, RdxTriggerRegistry, SHIFT, SPACE, SPACE_CODE, TAB, TIME_GRANULARITIES, a, areAllDaysBetweenValid, clamp, createCancelableChangeEventDetails, createContent, createContext, createFloatingEvents, createFloatingRootContext, createFormatter, createMonth, createMonths, docsUrl, elementSize, 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, isZonedDateTime, itemToStringLabel, itemToStringValue, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideFloatingRegistration, provideFloatingRootContext, provideFloatingTree, provideToken, provideValueAccessor, rdxCheckLabelElement, rdxCheckTriggerElement, rdxDevError, rdxDevWarning, resetRdxDevWarnings, resizeEffect, 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, RdxFormValueControl, RdxInternalBackdropOptions, RdxPointerDragHandlers, RdxScrollLockOptions, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, 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, 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 };

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

@@ -1,10 +1,10 @@
 import * as _angular_core from '@angular/core';
 import { Signal, InjectionToken, InputSignal, ModelSignal, WritableSignal } from '@angular/core';
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
-import { DateMatcher, HourCycle, Granularity, Direction, BooleanInput, DateStep, Formatter, SegmentValueObj, SegmentPart } 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 {
+declare class RdxDateFieldRootDirective extends RdxFormUiControlBase implements RdxFormValueControl<DateValue | undefined> {
     /**
      * The controlled value of the date field.
      */
@@ -96,6 +96,25 @@ declare class RdxDateFieldRootDirective {
      * @ignore
      */
     readonly isInvalid: Signal<boolean>;
+    /**
+     * @ignore Effective invalid: the built-in range/availability check OR the form-driven
+     * `invalid` / `errors` (Signal Forms). Reflected on the root and segments.
+     */
+    readonly invalidState: Signal<boolean>;
+    /**
+     * @ignore Tri-state display validity: the enclosing Field's gated state when inside a `rdxFieldRoot`,
+     * else the date-field's own (parse + form) invalidity. Overrides the base (whose default uses only
+     * `formUi.invalidState`) so the standalone path keeps the built-in range/availability check.
+     */
+    readonly displayValid: Signal<boolean | null>;
+    /** @ignore */
+    readonly touchedState: Signal<boolean>;
+    /** @ignore */
+    readonly dirtyState: Signal<boolean>;
+    /** @ignore Whether the user has focused a segment — gates dirty tracking so a form/initial seed of `value` doesn't mark dirty. */
+    private readonly userInteracted;
+    /** @ignore Mark the field touched (model + `touch` output) for Signal Forms. Called on segment blur. */
+    markAsTouched(): void;
     /**
      * @ignore
      */
@@ -168,6 +187,8 @@ declare class RdxDateFieldInputDirective {
      * @ignore
      */
     readonly isInvalid: _angular_core.Signal<boolean>;
+    /** @ignore Tri-state display validity from the root (gated by an enclosing Field). */
+    readonly displayValid: _angular_core.Signal<boolean | null>;
     /**
      * @ignore
      */
@@ -211,6 +232,10 @@ interface DateFieldContextToken {
     disabled: InputSignal<boolean>;
     readonly: InputSignal<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>;
     step$: Signal<DateStep>;

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

@@ -1,7 +1,7 @@
 import * as _angular_core from '@angular/core';
 import { Signal, WritableSignal } from '@angular/core';
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
-import { BooleanInput, NumberInput, RdxCancelableChangeEventDetails } from '@radix-ng/primitives/core';
+import { RdxFormUiControlBase, RdxFormValueControl, BooleanInput, NumberInput, RdxCancelableChangeEventDetails } from '@radix-ng/primitives/core';
 import * as i1 from '@radix-ng/primitives/dismissable-layer';
 import * as _radix_ng_primitives_editable from '@radix-ng/primitives/editable';
 
@@ -15,6 +15,11 @@ interface RdxEditableValueChangeEvent {
 }
 type EditableRootContext = {
     disabled: Signal<boolean>;
+    invalidState: Signal<boolean>;
+    /** Tri-state displayed validity (`true`/`false`/`null`): the field's gated state inside a Field, else own. */
+    displayValid: Signal<boolean | null>;
+    touchedState: Signal<boolean>;
+    dirtyState: Signal<boolean>;
     value: Signal<string | undefined>;
     inputValue: WritableSignal<string | undefined>;
     placeholder: Signal<{
@@ -43,10 +48,16 @@ declare const provideEditableRootContext: (useFactory: () => EditableRootContext
 /**
  * @group Components
  */
-declare class RdxEditableRoot {
+declare class RdxEditableRoot extends RdxFormUiControlBase implements RdxFormValueControl<string | undefined> {
     private readonly focusOutside;
     private readonly pointerDownOutside;
     readonly value: _angular_core.ModelSignal<string | undefined>;
+    /** @ignore */
+    readonly invalidState: Signal<boolean>;
+    /** @ignore */
+    readonly touchedState: Signal<boolean>;
+    /** @ignore */
+    readonly dirtyState: Signal<boolean>;
     /** Uncontrolled initial value. */
     readonly defaultValue: _angular_core.InputSignal<string | undefined>;
     readonly placeholder: _angular_core.InputSignal<string>;
@@ -80,6 +91,8 @@ declare class RdxEditableRoot {
     private suppressFocusActivation;
     constructor();
     canActivateOnFocus(): boolean;
+    /** @ignore Mark the field touched (model + `touch` output) for Signal Forms. Called on leaving edit mode. */
+    markAsTouched(): void;
     handleDismiss(): void;
     submit(event?: Event): void;
     cancel(): void;

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

@@ -2,7 +2,7 @@ import * as _angular_core from '@angular/core';
 import { Signal } from '@angular/core';
 import * as _radix_ng_primitives_field from '@radix-ng/primitives/field';
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
-import { BooleanInput, RdxValidationError } from '@radix-ng/primitives/core';
+import { BooleanInput, RdxValidationMode, RdxValidationError } from '@radix-ng/primitives/core';
 
 /**
  * Connects a form control to the field label, description, error, and state.
@@ -64,8 +64,9 @@ declare class RdxFieldError {
      */
     readonly id: _angular_core.InputSignal<string>;
     /**
-     * The field's external messages (state provider's, then enclosing Form's), `[]` when none. Render
-     * them explicitly via the `exportAs` reference — the directive never injects text content itself:
+     * 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
+     * explicitly via the `exportAs` reference — the directive never injects text content itself:
      * `<p rdxFieldError #err="rdxFieldError">{{ err.messages().join(' ') }}</p>`.
      */
     readonly messages: _angular_core.Signal<string[]>;
@@ -75,26 +76,6 @@ declare class RdxFieldError {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldError, "[rdxFieldError]", ["rdxFieldError"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-/**
- * Labels the field control.
- *
- * @group Components
- */
-declare class RdxFieldLabel {
-    protected readonly rootContext: _radix_ng_primitives_field.RdxFieldRootContext;
-    /**
-     * Label id.
-     *
-     * @group Props
-     */
-    readonly id: _angular_core.InputSignal<string>;
-    readonly htmlFor: () => string;
-    constructor();
-    protected readonly dataAttr: (value: boolean) => "" | undefined;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldLabel, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldLabel, "[rdxFieldLabel]", ["rdxFieldLabel"], { "id": { "alias": "id"; "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
@@ -108,6 +89,11 @@ declare class RdxFieldLabel {
  * See ADR 0004 and `signal-forms-readiness.md` (prep #4).
  */
 interface RdxFieldState {
+    /**
+     * 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;
     disabled?: () => boolean;
     required?: () => boolean;
@@ -116,10 +102,11 @@ interface RdxFieldState {
     filled?: () => boolean;
     focused?: () => boolean;
     /**
-     * Optional source of error *content* (not just the invalid boolean). When provided and non-empty
-     * it forces `invalidState` true, and its messages (`message ?? kind` per error) surface through
-     * `RdxFieldError.messages()` ahead of any enclosing Form's external messages. Uses `core`'s
-     * framework-free shim type so the seam stays free of `@angular/forms/signals` (ADR 0004 amendment).
+     * Optional source of error *content* (not just the invalid boolean). A non-empty list marks the field
+     * **actually** invalid (client validation) and its messages (`message ?? kind` per error) surface
+     * through `RdxFieldError.messages()` once the field's `validationMode` reveals client validity, ahead of
+     * 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[];
 }
@@ -130,6 +117,11 @@ interface RdxFieldRootContext {
     errorIds: Signal<string[]>;
     messages: Signal<string[]>;
     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. */
+    validState: Signal<boolean | null>;
+    /** Whether the enclosing Form has had a submit attempted (always `false` with no Form). */
+    formSubmitAttempted: Signal<boolean>;
     invalidState: Signal<boolean>;
     disabledState: Signal<boolean>;
     requiredState: Signal<boolean>;
@@ -147,6 +139,12 @@ interface RdxFieldRootContext {
     setDirty: (value: boolean) => void;
     setTouched: (value: boolean) => void;
     setStateProvider: (provider: RdxFieldState | null) => RdxFieldState | null;
+    /**
+     * Identity-checked teardown: roll the slot back to `previous` only if `provider` is still the
+     * active one. A newer adapter that registered after `provider` (create-before-destroy during a
+     * view swap) owns the slot and must not be clobbered by the old adapter's destroy.
+     */
+    clearStateProvider: (provider: RdxFieldState | null, previous: RdxFieldState | null) => void;
     hasStateProvider: Signal<boolean>;
 }
 declare const injectFieldRootContext: _radix_ng_primitives_core.InjectContext<RdxFieldRootContext>;
@@ -211,6 +209,13 @@ declare class RdxFieldRoot {
      * @group Props
      */
     readonly name: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Overrides when this field reveals its validity (error styling + message). Falls back to the
+     * enclosing `rdxFormRoot`'s `validationMode`, then `'onBlur'`. Server errors always show regardless.
+     *
+     * @group Props
+     */
+    readonly validationMode: _angular_core.InputSignal<RdxValidationMode | undefined>;
     /** The enclosing Form, if any. All Form-related behavior is a no-op when this is `null`. */
     private readonly formContext;
     readonly controlId: _angular_core.WritableSignal<string>;
@@ -226,11 +231,51 @@ declare class RdxFieldRoot {
     readonly hasStateProvider: Signal<boolean>;
     /** Error content from a registered state provider (e.g. a Signal Forms adapter). */
     private readonly providerErrors;
-    /** External messages from the enclosing Form matched by this field's `name`. */
-    readonly externalErrors: Signal<string[]>;
-    /** Provider messages first (`message ?? kind`), then the Form's external messages. */
+    /** **Client** validation errors routed by a form-level provider (`rdxSignalForm`) — gated by `validationMode`. */
+    private readonly clientErrors;
+    /** **Server/external** errors from the Form's `errors` input — shown eagerly (never gated). */
+    private readonly serverErrors;
+    /** Whether the enclosing Form has had a submit attempted; `false` when standalone. A presentation
+     * seam an adapter can read to reveal errors after a submit attempt (Base UI's submit-attempt state). */
+    readonly formSubmitAttempted: Signal<boolean>;
+    /**
+     * Client messages first (per-field `rdxSignalField` provider, then form-level `rdxSignalForm`
+     * name-routing) — only once `validationMode` reveals client validity — then the Form's **server**
+     * messages (the `errors` input), which always show. **Deduped by text**: a field can receive the same
+     * Signal Forms error from both a per-field provider and the form-level routing (they read the same
+     * field state), so deduping renders it once while still surfacing distinct messages from each source.
+     */
     readonly messages: Signal<string[]>;
+    /** 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. */
+    private readonly validationRevealed;
+    /**
+     * Client-side invalidity (gated by `validationMode`): the per-field provider's error content / `invalid`
+     * (`rdxSignalField`), a form-level provider's name-routed errors (`rdxSignalForm`), or the `[invalid]`
+     * input. Excludes server errors (which are eager).
+     */
+    private readonly clientInvalidState;
+    /**
+     * Tri-state *displayed* validity (`boolean | null`) — the source for `data-valid` / `data-invalid`.
+     * Server errors show immediately; client-side validity (including `rdxSignalForm` name-routing) stays
+     * **neutral** (`null`) until the field's {@link effectiveValidationMode} reveals it, then `false`/`true`.
+     */
+    readonly validState: Signal<boolean | null>;
+    /**
+     * Boolean **displayed** invalidity (= `validState() === false`), used by `rdxFieldError` (hidden) and
+     * `rdxFieldControl`'s `aria-describedby` error linking. A neutral (`null`) `validState` reads as not
+     * invalid here, so the error region stays hidden until the field's mode reveals it.
+     */
     readonly invalidState: Signal<boolean>;
+    /**
+     * Boolean **actual** invalidity — ungated by the display mode. The enclosing Form aggregates this into
+     * `anyInvalid` (→ submit-block / focus-first-invalid), so a field that is really invalid but displayed
+     * neutral still blocks submit. The form's presentation `data-invalid` comes from the *displayed*
+     * aggregate (`anyDisplayedInvalid`) instead — not from this. Server errors + provider error content +
+     * the provider/input `invalid`.
+     */
+    readonly actualInvalidState: Signal<boolean>;
     readonly disabledState: Signal<boolean>;
     readonly requiredState: Signal<boolean>;
     readonly dirtyState: Signal<boolean>;
@@ -257,14 +302,72 @@ declare class RdxFieldRoot {
      * @ignore
      */
     setStateProvider(provider: RdxFieldState | null): RdxFieldState | null;
+    /**
+     * Identity-checked teardown — roll back to `previous` only if `provider` is still active. Prevents
+     * an old adapter's destroy from clobbering a newer adapter that registered after it (create-before-
+     * destroy during a structural view swap).
+     */
+    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.
+     * 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.
      */
     private resolve;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldRoot, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldRoot, "[rdxFieldRoot]", ["rdxFieldRoot"], { "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "dirty": { "alias": "dirty"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "filled": { "alias": "filled"; "required": false; "isSignal": true; }; "focused": { "alias": "focused"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldRoot, "[rdxFieldRoot]", ["rdxFieldRoot"], { "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "dirty": { "alias": "dirty"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "filled": { "alias": "filled"; "required": false; "isSignal": true; }; "focused": { "alias": "focused"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "validationMode": { "alias": "validationMode"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Groups an individual item in a checkbox group or radio group with its own label and description.
+ *
+ * Use inside a `rdxFieldRoot` (typically wrapping a group) when each control needs its own label /
+ * description: the item scopes those associations to its control while reflecting the field's validation
+ * state. Mirrors Base UI's `Field.Item`.
+ *
+ * @group Components
+ */
+declare class RdxFieldItem {
+    /** The enclosing field root (items are leaves under the root, so `skipSelf` reaches it). */
+    readonly root: RdxFieldRoot;
+    /**
+     * Whether the wrapped control should ignore user interaction. The `disabled` on `rdxFieldRoot` takes
+     * precedence (it is OR'd in).
+     *
+     * @group Props
+     * @defaultValue false
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** This item's control id — label / description / control inside the item associate with it. */
+    readonly controlId: _angular_core.WritableSignal<string>;
+    /** Description ids for this item's control `aria-describedby`. */
+    readonly descriptionIds: _angular_core.WritableSignal<string[]>;
+    /** The item's effective disabled state: the root's disabled OR the item's. */
+    readonly disabledState: _angular_core.Signal<boolean>;
+    protected readonly dataAttr: (value: boolean) => "" | undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldItem, "[rdxFieldItem]", ["rdxFieldItem"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Labels the field control.
+ *
+ * @group Components
+ */
+declare class RdxFieldLabel {
+    protected readonly rootContext: _radix_ng_primitives_field.RdxFieldRootContext;
+    /**
+     * Label id.
+     *
+     * @group Props
+     */
+    readonly id: _angular_core.InputSignal<string>;
+    readonly htmlFor: () => string;
+    constructor();
+    protected readonly dataAttr: (value: boolean) => "" | undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldLabel, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldLabel, "[rdxFieldLabel]", ["rdxFieldLabel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { RdxFieldControl, RdxFieldDescription, RdxFieldError, RdxFieldLabel, RdxFieldRoot, injectFieldRootContext, provideFieldRootContext };
+export { RdxFieldControl, RdxFieldDescription, RdxFieldError, RdxFieldItem, RdxFieldLabel, RdxFieldRoot, injectFieldRootContext, provideFieldRootContext };
 export type { RdxFieldRootContext, RdxFieldState };