@radix-ng/primitives 1.0.0-beta.1 → 1.0.0-beta.2

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

@@ -166,11 +166,13 @@ interface InjectContext<T> {
  * Creates a context with injector and provider functions for a given type
  * @template T The type of the context value
  * @param description Descriptive string for the context (used in token creation)
+ * @param docs Documentation path for the owning primitive (e.g. `'components/accordion'`),
+ *   appended to the missing-context error as a link to the required anatomy
  * @returns A tuple containing:
  *   - injectContext: Function to retrieve the context value
  *   - provideContext: Function to create a provider for the context
  */
-declare function createContext<T>(description: string): readonly [injectContext: InjectContext<T>, provideContext: (useFactory: () => T) => Provider];
+declare function createContext<T>(description: string, docs?: string): readonly [injectContext: InjectContext<T>, provideContext: (useFactory: () => T) => Provider];
 
 declare const DATE_SEGMENT_PARTS: readonly ["day", "month", "year"];
 declare const TIME_SEGMENT_PARTS: readonly ["hour", "minute", "second", "dayPeriod"];
@@ -343,6 +345,12 @@ declare function areAllDaysBetweenValid(start: DateValue, end: DateValue, isUnav
 type TimeValue = Time | CalendarDateTime | ZonedDateTime;
 type Granularity = 'day' | 'hour' | 'minute' | 'second';
 type TimeGranularity = 'hour' | 'minute' | 'second';
+/**
+ * The granularities that require a time component (and therefore a `CalendarDateTime`
+ * rather than a `CalendarDate`). Single source of truth — used by both the default-date
+ * builder and the segment-value initializer.
+ */
+declare const TIME_GRANULARITIES: readonly Granularity[];
 type GetDefaultDateProps = {
     defaultValue?: DateValue | DateValue[] | undefined;
     defaultPlaceholder?: DateValue | undefined;
@@ -405,7 +413,7 @@ type SyncTimeSegmentValuesProps = {
     formatter: Formatter;
 };
 declare function syncTimeSegmentValues(props: SyncTimeSegmentValuesProps): SegmentValueObj;
-declare function initializeSegmentValues(granularity: Granularity): SegmentValueObj;
+declare function initializeSegmentValues(granularity: Granularity, isTimeValue?: boolean): SegmentValueObj;
 type SharedContentProps = {
     granularity: Granularity;
     dateRef: DateValue;
@@ -462,54 +470,9 @@ type SegmentAttrProps = {
     placeholder: DateValue;
     formatter: Formatter;
 };
-declare function daySegmentAttrs(props: SegmentAttrProps): {
-    'aria-label': string;
-    'aria-valuemin': number;
-    'aria-valuemax': number;
-    'aria-valuenow': number;
-    'aria-valuetext': string;
-    'data-placeholder': string | undefined;
-    role: string;
-    contenteditable: boolean;
-    tabindex: number | undefined;
-    spellcheck: boolean;
-    inputmode: string;
-    autocorrect: string;
-    enterkeyhint: string;
-    style: string;
-};
-declare function monthSegmentAttrs(props: SegmentAttrProps): {
-    'aria-label': string;
-    contenteditable: boolean;
-    'aria-valuemin': number;
-    'aria-valuemax': number;
-    'aria-valuenow': number;
-    'aria-valuetext': string;
-    'data-placeholder': string | undefined;
-    role: string;
-    tabindex: number | undefined;
-    spellcheck: boolean;
-    inputmode: string;
-    autocorrect: string;
-    enterkeyhint: string;
-    style: string;
-};
-declare function yearSegmentAttrs(props: SegmentAttrProps): {
-    'aria-label': string;
-    'aria-valuemin': number;
-    'aria-valuemax': number;
-    'aria-valuenow': number;
-    'aria-valuetext': string;
-    'data-placeholder': string | undefined;
-    role: string;
-    contenteditable: boolean;
-    tabindex: number | undefined;
-    spellcheck: boolean;
-    inputmode: string;
-    autocorrect: string;
-    enterkeyhint: string;
-    style: string;
-};
+declare function daySegmentAttrs(props: SegmentAttrProps): {};
+declare function monthSegmentAttrs(props: SegmentAttrProps): {};
+declare function yearSegmentAttrs(props: SegmentAttrProps): {};
 declare function hourSegmentAttrs(props: SegmentAttrProps): {};
 declare function minuteSegmentAttrs(props: SegmentAttrProps): {};
 declare function secondSegmentAttrs(props: SegmentAttrProps): {};
@@ -616,6 +579,36 @@ declare class RdxIdGenerator {
  */
 declare function injectId(prefix: string): string;
 
+/**
+ * A comparator for list-item values, aligned with Base UI's `isItemEqualToValue` naming.
+ *
+ * - a **function** `(a, b) => boolean` — full control over equality;
+ * - a **string** — an object key whose values are compared with {@link isEqual} (Reka-style `by`);
+ * - omitted — structural deep equality via {@link isEqual}.
+ */
+type ItemValueComparator<T = unknown> = ((a: T, b: T) => boolean) | string;
+/**
+ * Converts an item value to the string shown to the user.
+ *
+ * Strings pass through unchanged; `null`/`undefined` become an empty string; everything else is
+ * coerced with `String()`. Primitives that hold object values (e.g. combobox) typically pass their
+ * own `itemToStringLabel` to render a field off the object instead.
+ */
+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.
+ */
+declare function itemToStringValue(value: unknown): string;
+/**
+ * Compares two item values for equality using an optional {@link ItemValueComparator}.
+ *
+ * @example
+ * isItemEqualToValue({ id: 1 }, { id: 1 }, 'id'); // true — compares the `id` key
+ * isItemEqualToValue({ id: 1 }, { id: 1 });       // true — deep equality fallback
+ */
+declare function isItemEqualToValue<T>(a: T, b: T, comparator?: ItemValueComparator<T>): boolean;
+
 declare const ALT = "Alt";
 declare const ARROW_DOWN = "ArrowDown";
 declare const ARROW_LEFT = "ArrowLeft";
@@ -756,15 +749,27 @@ interface RdxFormUiControl {
     readonly invalid?: RdxFormStateInput<boolean>;
     readonly hidden?: RdxFormStateInput<boolean>;
     readonly pending?: RdxFormStateInput<boolean>;
-    readonly touched?: 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 that the control was touched (mirror of Angular's `touch` output). */
+    /** 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
@@ -813,8 +818,13 @@ declare function resizeEffect(options: {
 }): EffectRef;
 
 /**
- * Locks `document.body` scrolling while `active()` is `true`, and restores the original overflow
- * when it becomes `false` or the calling context is destroyed.
+ * Locks page scrolling while `active()` is `true`, and restores the original state when it becomes
+ * `false` or the calling context is destroyed.
+ *
+ * Locks **both** `<body>` and `<html>`: a `body { overflow: hidden }` lock alone does *not* stop the
+ * page when `<html>` is the scroller (e.g. a global `overflow-y: scroll`, as Storybook sets), because
+ * body-overflow only propagates to the viewport when `<html>`'s overflow is `visible`. The width of
+ * the removed scrollbar is added as `padding-right` on `<html>` so the page doesn't shift.
  *
  * Lock ownership is shared across all callers via a single module-level counter, so nested or
  * concurrent overlays compose correctly. Must be called in an injection context.
@@ -885,6 +895,39 @@ interface ArrowNavigationOptions {
  */
 declare function useArrowNavigation(e: KeyboardEvent, currentElement: HTMLElement, parentElement: HTMLElement | undefined, options?: ArrowNavigationOptions): HTMLElement | null;
 
+/**
+ * Locale-aware string matching backed by `Intl.Collator`, mirroring Base UI's `useFilter`.
+ *
+ * The collator defaults to `sensitivity: 'base'`, so matching is both case-insensitive and
+ * diacritic-insensitive (`"Äpfel"` matches `"ap"`, `"résumé"` matches `"resume"`). Pass `locale`
+ * and/or any `Intl.Collator` options to override.
+ */
+interface UseFilterOptions extends Intl.CollatorOptions {
+    /** Locale(s) for the collator. Defaults to the runtime's default locale. */
+    locale?: Intl.LocalesArgument;
+}
+/** Predicates returned by {@link useFilter}. An empty `query` always matches. */
+interface FilterPredicates {
+    /** Whether `text` contains `query`. */
+    contains: (text: string, query: string) => boolean;
+    /** Whether `text` starts with `query`. */
+    startsWith: (text: string, query: string) => boolean;
+    /** Whether `text` ends with `query`. */
+    endsWith: (text: string, query: string) => boolean;
+}
+/**
+ * Creates locale-aware `contains` / `startsWith` / `endsWith` predicates.
+ *
+ * Matching uses `Intl.Collator` with `sensitivity: 'base'` and `usage: 'search'` by default, so
+ * comparisons ignore case and diacritics. An empty (or whitespace-only) `query` matches everything,
+ * which is the natural "no filter applied" state for a combobox.
+ *
+ * @example
+ * const { contains } = useFilter();
+ * contains('Äpfel', 'ap'); // true
+ */
+declare function useFilter(options?: UseFilterOptions): FilterPredicates;
+
 /**
  * Keeps hover content open while the pointer crosses the gap between a trigger and a popup.
  */
@@ -893,6 +936,55 @@ declare function useGraceArea(triggerEl: Signal<HTMLElement | null | undefined>,
     onPointerExit: (callback: (value: void) => void) => () => void;
 };
 
+/** Options for {@link useListHighlight}. */
+interface UseListHighlightOptions<T> {
+    /** All items in DOM order (e.g. a collection provider's `items()`). */
+    items: Signal<readonly T[]>;
+    /**
+     * Whether an item can be highlighted — must return `false` for hidden (filtered-out) and
+     * disabled items. Navigation and self-healing both consult this.
+     */
+    isNavigable: (item: T) => boolean;
+    /** Resolves the item's element id, exposed as {@link ListHighlight.activeId} for `aria-activedescendant`. */
+    getId: (item: T) => string | undefined;
+    /** Whether navigation wraps at the boundaries. Defaults to `true`. */
+    loop?: Signal<boolean>;
+    /** Injector to bind the self-healing effect to when not called in an injection context. */
+    injector?: Injector;
+}
+/** Highlight-model navigation API returned by {@link useListHighlight}. */
+interface ListHighlight<T> {
+    /** The currently highlighted item, or `null`. DOM focus is never moved by this state. */
+    readonly highlightedItem: Signal<T | null>;
+    /** The highlighted item's element id, or `undefined`. Bind to `aria-activedescendant`. */
+    readonly activeId: Signal<string | undefined>;
+    /** Highlight the first navigable item. */
+    first(): void;
+    /** Highlight the last navigable item. */
+    last(): void;
+    /** Highlight the next navigable item (wraps when `loop`). */
+    next(): void;
+    /** Highlight the previous navigable item (wraps when `loop`). */
+    previous(): void;
+    /** Highlight a specific item (ignored if not navigable); pass `null` to clear. */
+    set(item: T | null): void;
+    /** Clear the highlight. */
+    clear(): void;
+}
+/**
+ * Highlight-model list navigation over a set of items, decoupled from DOM focus.
+ *
+ * Unlike roving `tabindex`, the highlight is pure state: callers move it with the keyboard while DOM
+ * focus stays on a single controlling element (e.g. a combobox `<input>`), which exposes
+ * {@link ListHighlight.activeId} as `aria-activedescendant`. Navigation only ever lands on items for
+ * which `isNavigable` returns `true`, so hidden (filtered-out) and disabled items are skipped. A
+ * self-healing effect clears the highlight if its item stops being navigable or leaves the list, so
+ * `activeId` never references a detached or hidden element.
+ *
+ * Must be called in an injection context, or given an `injector`.
+ */
+declare function useListHighlight<T>(options: UseListHighlightOptions<T>): ListHighlight<T>;
+
 interface RdxPointerDragHandlers {
     /** Whether a press may begin a drag (e.g. enabled, not on an opt-out element, at a scroll edge). */
     canStart: (event: PointerEvent) => boolean;
@@ -1008,5 +1100,5 @@ declare enum RdxPositionAlign {
     End = "end"
 }
 
-export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RdxControlValueAccessor, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isNullish, isNumberString, isSegmentNavigationKey, isZonedDateTime, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useArrowNavigation, useDateField, useGraceArea, usePointerDrag, useScrollLock, useTransitionStatus, watch };
-export type { AcceptableValue, AnyExceptLiteral, AriaLivePoliteness, BooleanInput, CreateMonthProps, DataOrientation, DateAndTimeSegmentObj, DateFormatterOptions, DateMatcher, DateRange, DateSegmentObj, DateSegmentPart, DateStep, DayPeriod, Direction, EditableSegmentPart, Formatter, Granularity, HourCycle, InjectContext, Month, NonEditableSegmentPart, Nullable, NumberInput, PlaceholderMap, RdxFormCheckboxControl, RdxFormStateInput, RdxFormUiControl, RdxFormValueControl, RdxPointerDragHandlers, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps };
+export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RdxControlValueAccessor, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, TIME_GRANULARITIES, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isItemEqualToValue, isNullish, isNumberString, isSegmentNavigationKey, isZonedDateTime, itemToStringLabel, itemToStringValue, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, 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, RdxFormCheckboxControl, RdxFormStateInput, RdxFormUiControl, RdxFormValueControl, RdxPointerDragHandlers, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps, UseFilterOptions, UseListHighlightOptions };

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

@@ -1,7 +1,7 @@
 import * as _radix_ng_primitives_field from '@radix-ng/primitives/field';
 import * as _angular_core from '@angular/core';
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
-import { BooleanInput } from '@radix-ng/primitives/core';
+import { BooleanInput, RdxValidationError } from '@radix-ng/primitives/core';
 
 /**
  * Connects a form control to the field label, description, error, and state.
@@ -11,8 +11,11 @@ import { BooleanInput } from '@radix-ng/primitives/core';
 declare class RdxFieldControl {
     protected readonly rootContext: {
         controlId: _angular_core.WritableSignal<string>;
+        name: _angular_core.InputSignal<string | undefined>;
         descriptionIds: _angular_core.WritableSignal<string[]>;
         errorIds: _angular_core.WritableSignal<string[]>;
+        messages: _angular_core.Signal<string[]>;
+        notifyEdited: () => void;
         invalidState: _angular_core.Signal<boolean>;
         disabledState: _angular_core.Signal<boolean>;
         requiredState: _angular_core.Signal<boolean>;
@@ -60,8 +63,11 @@ declare class RdxFieldControl {
 declare class RdxFieldDescription {
     protected readonly rootContext: {
         controlId: _angular_core.WritableSignal<string>;
+        name: _angular_core.InputSignal<string | undefined>;
         descriptionIds: _angular_core.WritableSignal<string[]>;
         errorIds: _angular_core.WritableSignal<string[]>;
+        messages: _angular_core.Signal<string[]>;
+        notifyEdited: () => void;
         invalidState: _angular_core.Signal<boolean>;
         disabledState: _angular_core.Signal<boolean>;
         requiredState: _angular_core.Signal<boolean>;
@@ -101,8 +107,11 @@ declare class RdxFieldDescription {
 declare class RdxFieldError {
     protected readonly rootContext: {
         controlId: _angular_core.WritableSignal<string>;
+        name: _angular_core.InputSignal<string | undefined>;
         descriptionIds: _angular_core.WritableSignal<string[]>;
         errorIds: _angular_core.WritableSignal<string[]>;
+        messages: _angular_core.Signal<string[]>;
+        notifyEdited: () => void;
         invalidState: _angular_core.Signal<boolean>;
         disabledState: _angular_core.Signal<boolean>;
         requiredState: _angular_core.Signal<boolean>;
@@ -128,6 +137,12 @@ declare class RdxFieldError {
      * @group Props
      */
     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:
+     * `<p rdxFieldError #err="rdxFieldError">{{ err.messages().join(' ') }}</p>`.
+     */
+    readonly messages: _angular_core.Signal<string[]>;
     constructor();
     protected readonly dataAttr: (value: boolean) => "" | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldError, never>;
@@ -142,8 +157,11 @@ declare class RdxFieldError {
 declare class RdxFieldLabel {
     protected readonly rootContext: {
         controlId: _angular_core.WritableSignal<string>;
+        name: _angular_core.InputSignal<string | undefined>;
         descriptionIds: _angular_core.WritableSignal<string[]>;
         errorIds: _angular_core.WritableSignal<string[]>;
+        messages: _angular_core.Signal<string[]>;
+        notifyEdited: () => void;
         invalidState: _angular_core.Signal<boolean>;
         disabledState: _angular_core.Signal<boolean>;
         requiredState: _angular_core.Signal<boolean>;
@@ -195,11 +213,23 @@ interface RdxFieldState {
     touched?: () => boolean;
     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).
+     */
+    errors?: () => RdxValidationError[];
 }
 declare const fieldRootContext: () => {
     controlId: _angular_core.WritableSignal<string>;
+    name: _angular_core.InputSignal<string | undefined>;
     descriptionIds: _angular_core.WritableSignal<string[]>;
     errorIds: _angular_core.WritableSignal<string[]>;
+    /** Combined external messages (state provider's, then enclosing Form's), for `RdxFieldError`. */
+    messages: _angular_core.Signal<string[]>;
+    /** Notify an enclosing Form that this field's control was edited (composite-control opt-in). */
+    notifyEdited: () => void;
     invalidState: _angular_core.Signal<boolean>;
     disabledState: _angular_core.Signal<boolean>;
     requiredState: _angular_core.Signal<boolean>;
@@ -228,8 +258,13 @@ declare const fieldRootContext: () => {
 type RdxFieldRootContext = ReturnType<typeof fieldRootContext>;
 declare const injectFieldRootContext: _radix_ng_primitives_core.InjectContext<{
     controlId: _angular_core.WritableSignal<string>;
+    name: _angular_core.InputSignal<string | undefined>;
     descriptionIds: _angular_core.WritableSignal<string[]>;
     errorIds: _angular_core.WritableSignal<string[]>;
+    /** Combined external messages (state provider's, then enclosing Form's), for `RdxFieldError`. */
+    messages: _angular_core.Signal<string[]>;
+    /** Notify an enclosing Form that this field's control was edited (composite-control opt-in). */
+    notifyEdited: () => void;
     invalidState: _angular_core.Signal<boolean>;
     disabledState: _angular_core.Signal<boolean>;
     requiredState: _angular_core.Signal<boolean>;
@@ -257,8 +292,13 @@ declare const injectFieldRootContext: _radix_ng_primitives_core.InjectContext<{
 }>;
 declare const provideFieldRootContext: (useFactory: () => {
     controlId: _angular_core.WritableSignal<string>;
+    name: _angular_core.InputSignal<string | undefined>;
     descriptionIds: _angular_core.WritableSignal<string[]>;
     errorIds: _angular_core.WritableSignal<string[]>;
+    /** Combined external messages (state provider's, then enclosing Form's), for `RdxFieldError`. */
+    messages: _angular_core.Signal<string[]>;
+    /** Notify an enclosing Form that this field's control was edited (composite-control opt-in). */
+    notifyEdited: () => void;
     invalidState: _angular_core.Signal<boolean>;
     disabledState: _angular_core.Signal<boolean>;
     requiredState: _angular_core.Signal<boolean>;
@@ -337,6 +377,15 @@ declare class RdxFieldRoot {
      * @group Props
      */
     readonly focused: _angular_core.InputSignal<boolean | undefined>;
+    /**
+     * Identifies the field to an enclosing Form for external (server) error matching. Fields without a
+     * `name` never match external errors.
+     *
+     * @group Props
+     */
+    readonly name: _angular_core.InputSignal<string | 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>;
     readonly descriptionIds: _angular_core.WritableSignal<string[]>;
     readonly errorIds: _angular_core.WritableSignal<string[]>;
@@ -348,6 +397,12 @@ declare class RdxFieldRoot {
     private readonly stateProvider;
     /** Whether an external adapter currently owns field state. */
     readonly hasStateProvider: _angular_core.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: _angular_core.Signal<string[]>;
+    /** Provider messages first (`message ?? kind`), then the Form's external messages. */
+    readonly messages: _angular_core.Signal<string[]>;
     readonly invalidState: _angular_core.Signal<boolean>;
     readonly disabledState: _angular_core.Signal<boolean>;
     readonly requiredState: _angular_core.Signal<boolean>;
@@ -356,6 +411,20 @@ declare class RdxFieldRoot {
     readonly filledState: _angular_core.Signal<boolean>;
     readonly focusedState: _angular_core.Signal<boolean>;
     protected readonly dataAttr: (value: boolean) => "" | undefined;
+    constructor();
+    /** Notify the enclosing Form (if any) that this field's control was edited (clear-on-edit). */
+    notifyEdited(): void;
+    /** Reset interaction state on native form reset: touched/dirty/focused → false, filled re-synced. */
+    resetState(): void;
+    /** Focus the field's control (used by the Form's first-invalid-focus on blocked submit). */
+    private focusControl;
+    private readonly host;
+    /**
+     * The field's control element, found by `controlId` but scoped to this field's own subtree — a
+     * duplicate or consumer-reused id elsewhere on the page can't steal focus/reset. The control
+     * registers its id through `setControlId`, so this matches the same element the labels point at.
+     */
+    private controlElement;
     /**
      * Register an external owner of field state, returning the previous one.
      * @ignore
@@ -367,7 +436,7 @@ declare class RdxFieldRoot {
      */
     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; }; }, {}, 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; }; }, {}, never, never, true, never>;
 }
 
 export { RdxFieldControl, RdxFieldDescription, RdxFieldError, RdxFieldLabel, RdxFieldRoot, injectFieldRootContext, provideFieldRootContext };

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

@@ -0,0 +1,124 @@
+import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
+import * as _angular_core from '@angular/core';
+
+/** A normalized external-error map: each field name maps to its message(s) in display order. */
+type RdxFormErrors = Record<string, string | string[]>;
+/** Payload of {@link RdxFormRoot.onFormSubmit}. */
+interface RdxFormSubmitEvent {
+    /** The form's values serialized from `FormData` (repeated names collapse into arrays). */
+    values: Record<string, FormDataEntryValue | FormDataEntryValue[]>;
+    /** The original native submit event (already `preventDefault`-ed). */
+    event: SubmitEvent;
+}
+/**
+ * What a {@link RdxFieldRoot} registers with an enclosing Form. Structural `() =>` accessors keep the
+ * Form entry free of any import from `field` (acyclic ng-packagr graph: `field` → `form`).
+ */
+interface RdxFormFieldRegistration {
+    /** The field's `name` (key external errors match against), or `undefined`. */
+    name: () => string | undefined;
+    /** The field's merged invalid state (includes external errors). */
+    invalid: () => boolean;
+    /** Whether the field is dirty. */
+    dirty: () => boolean;
+    /** Whether the field is touched. */
+    touched: () => boolean;
+    /** Focus the field's control (by its `controlId`). */
+    focus: () => void;
+    /** Reset the field's interaction state (touched/dirty/focused → false, filled re-sync). */
+    resetState: () => void;
+}
+/**
+ * External owner of form-level state (e.g. a future Signal Forms `[rdxSignalForm]` adapter). Mirrors
+ * Field's `RdxFieldState` seam one level up. Each member is optional: a provided accessor wins over the
+ * built-in registry/`errors`-input behavior; absent accessors leave the built-in behavior untouched.
+ * Kept as framework-free `() =>` accessors (no `@angular/forms/signals` dependency). See ADR 0004.
+ */
+interface RdxFormState {
+    invalid?: () => boolean;
+    dirty?: () => boolean;
+    touched?: () => boolean;
+    submitting?: () => boolean;
+    /** Per-name external error source; while provided, the `errors` input + clear-on-edit are inert. */
+    errorsFor?: (name: string) => string[];
+}
+declare const formRootContext: () => {
+    errorsFor: (name: string | undefined) => string[];
+    notifyEdited: (name: string | undefined) => void;
+    register: (field: RdxFormFieldRegistration) => () => void;
+    setStateProvider: (provider: RdxFormState | null) => RdxFormState | null;
+    hasStateProvider: _angular_core.Signal<boolean>;
+};
+type RdxFormRootContext = ReturnType<typeof formRootContext>;
+declare const injectFormRootContext: _radix_ng_primitives_core.InjectContext<{
+    errorsFor: (name: string | undefined) => string[];
+    notifyEdited: (name: string | undefined) => void;
+    register: (field: RdxFormFieldRegistration) => () => void;
+    setStateProvider: (provider: RdxFormState | null) => RdxFormState | null;
+    hasStateProvider: _angular_core.Signal<boolean>;
+}>;
+declare const provideFormRootContext: (useFactory: () => {
+    errorsFor: (name: string | undefined) => string[];
+    notifyEdited: (name: string | undefined) => void;
+    register: (field: RdxFormFieldRegistration) => () => void;
+    setStateProvider: (provider: RdxFormState | null) => RdxFormState | null;
+    hasStateProvider: _angular_core.Signal<boolean>;
+}) => _angular_core.Provider;
+/**
+ * The top of the forms layer cake: a single directive on the native `<form>` element that aggregates
+ * field state, maps external (server) errors onto fields by `name`, intercepts submit (values-as-object,
+ * focus the first invalid field), and resets field interaction state on native `reset`. It owns no
+ * values and runs no validation — Angular form systems (or Field inputs) remain the source of validity.
+ *
+ * @group Components
+ */
+declare class RdxFormRoot {
+    private readonly form;
+    /** External/server validation errors keyed by `Field.Root` `name`. */
+    readonly errors: _angular_core.InputSignal<RdxFormErrors | null | undefined>;
+    /** Emits the remaining error map after a field's external error is cleared by a user edit (or reset). */
+    readonly onClearErrors: _angular_core.OutputEmitterRef<RdxFormErrors>;
+    /** Emits the serialized form values when a valid form is submitted. */
+    readonly onFormSubmit: _angular_core.OutputEmitterRef<RdxFormSubmitEvent>;
+    private readonly fields;
+    private readonly stateProvider;
+    /** Whether an external adapter currently owns form-level state. */
+    readonly hasStateProvider: _angular_core.Signal<boolean>;
+    /**
+     * Names whose external error has been cleared by a user edit. Reset to empty whenever a new `errors`
+     * object reference is assigned — the server just spoke, so everything it said is live again.
+     */
+    private readonly clearedNames;
+    /** The `errors` input minus cleared names, normalized to `string[]`. */
+    private readonly effectiveErrors;
+    readonly anyInvalid: _angular_core.Signal<boolean>;
+    readonly anyDirty: _angular_core.Signal<boolean>;
+    readonly anyTouched: _angular_core.Signal<boolean>;
+    readonly submitting: _angular_core.Signal<boolean>;
+    /** Resolve a boolean aggregate: a registered provider's accessor wins, else OR over the registry. */
+    private aggregate;
+    /** Resolves the external messages for a field name (provider source wins over the `errors` input). */
+    errorsFor(name: string | undefined): string[];
+    /** Clears a field's external error after a user edit, emitting the remaining map. */
+    notifyEdited(name: string | undefined): void;
+    register(field: RdxFormFieldRegistration): () => void;
+    /** Register (or clear with `null`) an external owner of form-level state; returns the previous one. */
+    setStateProvider(provider: RdxFormState | null): RdxFormState | null;
+    onSubmit(event: SubmitEvent): void;
+    onReset(): void;
+    private readonly resetTimers;
+    constructor();
+    private remainingErrors;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFormRoot, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFormRoot, "form[rdxFormRoot]", ["rdxFormRoot"], { "errors": { "alias": "errors"; "required": false; "isSignal": true; }; }, { "onClearErrors": "onClearErrors"; "onFormSubmit": "onFormSubmit"; }, never, never, true, never>;
+}
+
+declare const _importsForm: (typeof RdxFormRoot)[];
+declare class RdxFormModule {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFormModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<RdxFormModule, never, [typeof RdxFormRoot], [typeof RdxFormRoot]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<RdxFormModule>;
+}
+
+export { RdxFormModule, RdxFormRoot, _importsForm, injectFormRootContext, provideFormRootContext };
+export type { RdxFormErrors, RdxFormFieldRegistration, RdxFormRootContext, RdxFormState, RdxFormSubmitEvent };