@skdx/react 0.26.0 → 0.28.0

package/dist/field/fieldCore.d.ts

@@ -1,16 +1,4 @@
-/**
- * The framework-free engine behind `Field`. Everything here is plain DOM
- * work — discovering the control inside a Field, injecting the ARIA wiring
- * onto it, running the validation model, and mirroring the interaction state
- * as `data-*` — so all five framework packages run the *same* algorithm and
- * the shared `assertFieldContract` assertions mean the same thing everywhere.
- *
- * The framework layer above this only ever: creates a controller, hands it
- * props, calls `sync()` after each render, and re-renders when the controller
- * says its snapshot changed.
- *
- * See `reports/design-system-competitive-audit/14-rfc-field-fieldset-validation.md`.
- */
+/** Framework-free validation engine used by all five framework packages. */
 /** When a Field first runs its validator. See {@link FieldControllerProps.mode}. */
 export type FieldMode = 'change' | 'blur' | 'submit';
 /** What a validator may return: one message, several, or nothing when the value is acceptable. */
@@ -23,16 +11,7 @@ export declare const FIELD_VALIDITY_CHANGE_EVENT = "validity-change";
 export declare const FIELD_ROOT_ATTRIBUTE = "data-skdx-field";
 /** Marks a Field's name, used as the error-summary link text when nothing else supplies one. */
 export declare const FIELD_NAME_ATTRIBUTE = "data-skdx-field-name";
-/**
- * The Field's current messages, written straight onto the root the moment
- * validity changes.
- *
- * This exists so the error summary never depends on a framework's render
- * timing: a Field dispatches `validity-change` synchronously from its own DOM
- * listener, *before* React/Vue/Angular/Lit have rendered the Error element, so
- * a summary that could only read that element's text would scan a field that
- * is already `data-invalid` and find nothing to link to.
- */
+/** The Field's current messages, written to the root on validity changes. */
 export declare const FIELD_MESSAGE_ATTRIBUTE = "data-skdx-field-message";
 /** Marks a Field's description element, so its id can be added to the control's `aria-describedby`. */
 export declare const FIELD_DESCRIPTION_ATTRIBUTE = "data-skdx-field-description";
@@ -40,50 +19,42 @@ export declare const FIELD_DESCRIPTION_ATTRIBUTE = "data-skdx-field-description"
 export declare const FIELD_ERROR_ATTRIBUTE = "data-skdx-field-error";
 /** Marks a Field's character-count element, so it can be styled and found without a framework ref. */
 export declare const FIELD_CHARACTER_COUNT_ATTRIBUTE = "data-skdx-field-character-count";
-/**
- * How long the character count waits after the last keystroke before it
- * announces the remaining count.
- *
- * GOV.UK's number, and the reason it exists: a live region that fires on every
- * keystroke reads a running commentary over the character the user just typed.
- * One announcement per typing pause is the whole point of the pattern.
- */
+/** Marks a Field whose async validator is still running. */
+export declare const FIELD_PENDING_ATTRIBUTE = "data-skdx-field-pending";
+/** Marks the re-dispatched submit after async validators have settled. */
+export declare const FIELD_RESUBMIT_ATTRIBUTE = "data-skdx-field-resubmit";
+/** Marks a FormField root, allowing error summary to list both Field and FormField failures. */
+export declare const FORM_FIELD_ATTRIBUTE = "data-skdx-form-field";
+/** Marks a rendered FormMessage so the error summary shows the user's displayed message. */
+export declare const FORM_MESSAGE_ATTRIBUTE = "data-skdx-form-message";
+/** Events a Form ErrorSummary should re-scan on. */
+export declare const ERROR_SUMMARY_RESCAN_EVENTS: readonly ["validity-change", "invalid", "change", "blur"];
+/** Marks a Form's ErrorSummary so the engine knows whether to suppress the Field's own announcement. */
+export declare const FIELD_ERROR_SUMMARY_ATTRIBUTE = "data-skdx-error-summary";
+/** Delay in milliseconds before character count announces remaining count. */
 export declare const CHARACTER_COUNT_ANNOUNCE_DELAY_MS = 1000;
 /** What a Field's character count is configured with. */
 export interface FieldCharacterCountOptions {
-    /** The soft limit. Deliberately *not* the control's native `maxlength`, which truncates silently. */
+    /** The soft limit, not the native `maxlength` which truncates silently. */
     maxLength: number;
     /**
-     * Percentage of `maxLength` that must be typed before the count is shown and
-     * announced at all. `0` shows it from the first render.
+     * Percentage of `maxLength` before the count appears; `0` shows it immediately.
      * @default 0
      */
     threshold?: number;
 }
-/** The default count copy, in GOV.UK's wording. Negative `remaining` means over the limit. */
+/** Default count message; negative means over-limit. */
 export declare function characterCountMessage(remaining: number): string;
 /** Whether a count has passed its threshold and should be rendered/announced. */
 export declare function characterCountVisible(count: number, maxLength: number, threshold?: number): boolean;
-/**
- * Used when a control fails native constraint validation but the engine
- * reports no message of its own (jsdom and some browsers leave
- * `validationMessage` empty). A Field is never invalid without something to
- * say, because an error with no message is unannounceable.
- */
+/** Fallback message when native constraint validation has no `validationMessage`. */
 export declare const NATIVE_INVALID_FALLBACK_MESSAGE = "This field is invalid.";
-/**
- * Opt-in marker saying "I am my Field's control". Discovery's escape hatch for
- * a composite whose role element the Field cannot reach: `<skdx-date-field>`
- * keeps its `role="group"` in a shadow root, so only the host is findable from
- * the Field's light DOM.
- */
+/** Marks an element as this Field's control, an escape hatch for composites in shadow DOM. */
 export declare const FIELD_CONTROL_ATTRIBUTE = "data-skdx-field-control";
-/**
- * How a Field recognises the control it wraps. First match in document order
- * wins, which is why group roles work: a `[role="radiogroup"]` precedes the
- * radios inside it.
- */
+/** Selector to find a Field's control, matching first in document order. */
 export declare const FIELD_CONTROL_SELECTOR: string;
+/** Marks a Field's required indicator for styling and assertion verification. */
+export declare const FIELD_REQUIRED_INDICATOR_ATTRIBUTE = "data-skdx-field-required-indicator";
 /** The public state of one Field, handed to the framework layer and to `validity-change` listeners. */
 export interface FieldSnapshot {
     /** The id of the discovered control — the Label's `for`, and the error summary's link target. */
@@ -100,14 +71,18 @@ export interface FieldSnapshot {
     filled: boolean;
     /** Length of the control's value, tracked only while a character count is configured. */
     count: number;
+    /**
+     * The discovered control's live `ValidityState`, or `null` if none (role elements, no control).
+     * The control's own object, not a copy; compared by identity to detect control swaps.
+     */
+    validity: ValidityState | null;
 }
 /** The props the framework layer forwards into the controller on every render. */
 export interface FieldControllerProps {
     /** See {@link FieldValidator}. */
     validate?: FieldValidator;
     /**
-     * When validation first runs. After a failure the field re-validates on
-     * every input regardless, so an error clears as soon as it is fixed.
+     * When validation first runs; re-validates on input after any failure.
      * @default 'blur'
      */
     mode?: FieldMode;
@@ -118,20 +93,30 @@ export interface FieldControllerProps {
     /** Field name, used as the error-summary link text when no error element is rendered. */
     name?: string;
     /**
-     * Words the character-count copy — the text `FieldCharacterCount` renders,
-     * the message announced one typing pause later, and the error raised once
-     * the value goes over the soft limit. A negative `remaining` means over the
-     * limit.
+     * Whether an answer is mandatory, reflected as native `required` or `aria-required="true"`.
+     * @default undefined — not required.
+     */
+    required?: boolean;
+    /**
+     * Whether the field is unavailable, applied as native `disabled` or `aria-disabled="true"`.
+     * @default undefined — not disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Formats the character-count message; negative `remaining` means over-limit.
      * @default undefined — {@link characterCountMessage}'s English wording.
      */
     getCharacterCountMessage?: (remaining: number) => string;
     /**
-     * Replaces {@link NATIVE_INVALID_FALLBACK_MESSAGE}: what the Field says when
-     * the wrapped control fails native constraint validation but the engine
-     * reports no message of its own.
+     * Fallback message when native constraint validation fails without a message.
      * @default undefined — 'This field is invalid.'
      */
     invalidMessage?: string;
+    /**
+     * Delay in milliseconds before `change` mode validates; `0` validates every keystroke.
+     * @default 0 — no debounce.
+     */
+    validationDebounceTime?: number;
 }
 /** Everything the controller needs that the framework layer owns. */
 export interface FieldControllerOptions {
@@ -143,32 +128,18 @@ export interface FieldControllerOptions {
     errorId: string;
     /** Fallback id assigned to a control that has none of its own. */
     controlId: string;
-    /** True for a `Fieldset`: the Label is a `<legend>` and the control is labelled by `aria-labelledby`. */
+    /** True for fieldsets where Label is legend and control uses aria-labelledby. */
     grouped: boolean;
     /** Called whenever the snapshot changes, so the framework layer can re-render. */
     onSnapshotChange: (snapshot: FieldSnapshot) => void;
-    /**
-     * The live-region `announce`. The engine picks the politeness per message, because
-     * the two things it says want different ones: an error the user has already
-     * moved past interrupts, a running character count must not.
-     */
+    /** Announces messages to the live region with politeness picked per message. */
     announce: (message: string, politeness: 'polite' | 'assertive') => void;
 }
 /** Coerces whatever a validator (or the `errors` prop) returned into a message list. */
 export declare function normalizeMessages(result: FieldValidationResult | string | string[]): string[];
 /** The first control inside `root` that belongs to *this* Field rather than to a nested one. */
 export declare function findFieldControl(root: Element): HTMLElement | null;
-/**
- * The value a validator sees when the consumer passed none: a checkbox or
- * radio reports `checked`, everything else reports its `value` property, and a
- * composite root that has no `value` of its own (a `role="group"` segmented
- * field, a `role="radiogroup"`) reports whatever its form-participation input
- * would submit.
- *
- * ponytail: a composite control that keeps its value only in framework state
- * and mirrors it nowhere — no `value` property, and no `name` so no hidden
- * input either — needs the explicit `value` prop. Pass it if you build one.
- */
+/** Reads the current value from a control, checking checked state, value property, or hidden input. */
 export declare function readControlValue(control: HTMLElement | null): unknown;
 /** Whether a value counts as entered, for `data-filled`. */
 export declare function isFilled(value: unknown): boolean;
@@ -179,19 +150,15 @@ export interface FieldErrorEntry {
     /** The message shown as the link text. */
     message: string;
 }
-/**
- * The form (or `<skdx-form>`) a summary should scan and listen on, falling
- * back to the summary's own parent when it is used standalone.
- */
+/** Returns the form or skdx-form a summary should scan, falling back to its parent. */
 export declare function errorSummaryScope(root: Element): Element;
-/** Every currently-failing Field in `scope`, in document order — the summary's list. */
+/** Returns all currently-failing fields in scope, in document order. */
 export declare function collectFieldErrors(scope: ParentNode): FieldErrorEntry[];
-/**
- * Sends focus to a failing field the GOV.UK way: straight to the control,
- * unless the target is a group — then to the first control inside it, because
- * focusing a `<fieldset>`/`[role="radiogroup"]` announces the group but leaves
- * the user with nothing to operate.
- */
+/** Runs all Fields in scope without short-circuiting, so all errors appear in ErrorSummary. */
+export declare function validateFields(scope: ParentNode): Promise<boolean>;
+/** Resets every Field's state when the form is reset, clearing messages and interaction flags. */
+export declare function resetFields(scope: ParentNode): void;
+/** Sends focus to a failing field, or to the first control inside a group. */
 export declare function focusFieldTarget(id: string, doc?: Document): void;
 /**
  * Owns one Field's state machine. Created by the framework layer, given the
@@ -205,6 +172,13 @@ export declare class FieldController {
     private control;
     /** The `aria-describedby` the consumer put on the control themselves, preserved across rewrites. */
     private baseDescribedBy;
+    /** The `aria-labelledby` the consumer put on the control themselves, preserved across rewrites. */
+    private baseLabelledBy;
+    /** Whether this controller wrote aria-labelledby; only we may withdraw it. */
+    private wroteLabelledBy;
+    /** Whether this controller wrote required/disabled; only we may withdraw them. */
+    private wroteRequired;
+    private wroteDisabled;
     /** Bumped on every validation run; a resolution from a superseded run is discarded. */
     private runToken;
     private pending;
@@ -215,16 +189,17 @@ export declare class FieldController {
     /** Set by a mounted character-count part; `null` while the Field has none. */
     private characterCount;
     private announceTimer;
+    /** Pending {@link FieldControllerProps.validationDebounceTime} run, cancelled by the next keystroke or a blur. */
+    private validationTimer;
+    /** Whether a submit is waiting on this Field's async validator to settle. */
+    private awaitingSubmit;
     private snapshot;
     constructor(options: FieldControllerOptions);
     /** The current state. Read by the framework layer to render the parts. */
     get state(): FieldSnapshot;
     /** Replaces the forwarded props. Safe to call on every render. */
     setProps(props: FieldControllerProps): void;
-    /**
-     * Registers (or clears) the character count. Called by the count part on
-     * mount, on prop change, and on unmount.
-     */
+    /** Registers or clears the character count configuration. */
     setCharacterCount(options: FieldCharacterCountOptions | null): void;
     /** Length of the control's current value; `0` when it holds something that is not text. */
     private readCount;
@@ -232,53 +207,50 @@ export declare class FieldController {
     private countMessage;
     /** True once the value is longer than the configured soft limit. */
     private isOverLimit;
-    /**
-     * Server errors first, then whatever the last validation run produced, then
-     * the over-limit message — so going over the limit makes the Field invalid
-     * through exactly the same path as any other error, and blocks submit.
-     */
+    /** Composes errors: server errors, validation results, then over-limit message. */
     private composeErrors;
-    /**
-     * Says the count, sparingly. Under the limit it is queued politely, one
-     * typing pause after the last keystroke, so a burst of typing produces one
-     * number instead of a running commentary. Crossing the limit interrupts —
-     * once, on the transition, not on every keystroke past it.
-     *
-     * The over-limit message cannot ride on `commit()`'s error announcement: by
-     * the time validation runs, `update()` has already put the message into
-     * `errors`, so `commit()` no longer sees the field as newly-invalid.
-     */
+    /** Announces the count politely one pause after the last keystroke, or assertively on over-limit. */
     private scheduleCountAnnouncement;
     /** Attaches the controller to its rendered root element. */
     connect(root: HTMLElement): void;
     /** Detaches every listener. */
     disconnect(): void;
-    /**
-     * Re-discovers the control and re-applies every injected attribute. The
-     * framework layer calls this after each render, because a render may have
-     * swapped the control or mounted/unmounted the Description or Error.
-     */
+    /** Re-discovers the control and re-applies injected attributes. */
     sync(): void;
-    /**
-     * Runs validation now. Resolves to whether the field is valid — the
-     * imperative entry point `<skdx-field>.validate()` and Angular's
-     * `SkdxFieldComponent.validate()` expose directly.
-     */
+    /** Sets required and disabled on control using native attributes or ARIA as appropriate. */
+    private applyConstraintState;
+    /** Runs validation now, resolving to whether the field is valid. */
     validate(): Promise<boolean>;
+    /** Resets field to mount state: no messages, not touched/dirty/pending. Bumps token to cancel async runs. */
+    reset(): void;
     /** Marks the field touched without validating (used by a submit pass before it validates). */
     private markTouched;
     private applyStateAttributes;
     private resolveValue;
+    /** The discovered control's live `ValidityState`, when it has one. */
+    private readValidity;
+    /** Publishes (or withdraws) the "a validator is still running here" marker. */
+    private markPending;
     private nativeMessage;
-    /**
-     * Returns the new message list — synchronously for a sync validator, which
-     * is what lets the submit handler decide whether to `preventDefault()`
-     * before the browser submits.
-     */
+    /** Runs validation, returning messages synchronously for sync validators. */
     private runValidation;
     private commit;
     private update;
     private readonly handleInput;
+    /** Runs validator with debounce in change mode, immediately in blur/submit mode. */
+    private scheduleValidation;
+    /**
+     * Whether this Field's form has an ErrorSummary. Queried per submit (not cached)
+     * since the summary is conditionally rendered.
+     */
+    private hasErrorSummary;
     private readonly handleFocusOut;
+    /**
+     * Whether this is the re-dispatch from {@link resubmitIfSettled}. Re-running
+     * validators here would block the original submit.
+     */
+    private isEngineResubmit;
     private readonly handleSubmit;
+    /** Re-dispatches submit once all async validators have settled, avoiding loops via FIELD_RESUBMIT_ATTRIBUTE. */
+    private resubmitIfSettled;
 }

package/dist/field/index.d.cts

@@ -1,7 +1,3 @@
 export { Field, Fieldset } from './Field.cjs';
-export { FieldLabel } from './FieldLabel.cjs';
-export { FieldDescription } from './FieldDescription.cjs';
-export { FieldError } from './FieldError.cjs';
-export { FieldCharacterCount } from './FieldCharacterCount.cjs';
-export type { FieldProps, FieldsetProps, FieldLabelProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldOwnProps, FieldValidityDetail, FieldMode, FieldValidator, FieldValidationResult, FieldCharacterCountOptions, } from './types.cjs';
-export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, errorSummaryScope, focusFieldTarget, type FieldErrorEntry, } from './fieldCore.cjs';
+export type { FieldProps, FieldsetProps, FieldsetHandle, FieldOwnProps, FieldValidityDetail, FieldValidateHandle, FieldHandle, FieldMode, FieldValidator, FieldValidationResult, } from './types.cjs';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_REQUIRED_INDICATOR_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, ERROR_SUMMARY_RESCAN_EVENTS, errorSummaryScope, FORM_FIELD_ATTRIBUTE, FORM_MESSAGE_ATTRIBUTE, FIELD_NAME_ATTRIBUTE, focusFieldTarget, type FieldErrorEntry, resetFields, validateFields, } from './fieldCore.cjs';

package/dist/field/index.d.ts

@@ -1,7 +1,3 @@
 export { Field, Fieldset } from './Field.js';
-export { FieldLabel } from './FieldLabel.js';
-export { FieldDescription } from './FieldDescription.js';
-export { FieldError } from './FieldError.js';
-export { FieldCharacterCount } from './FieldCharacterCount.js';
-export type { FieldProps, FieldsetProps, FieldLabelProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldOwnProps, FieldValidityDetail, FieldMode, FieldValidator, FieldValidationResult, FieldCharacterCountOptions, } from './types.js';
-export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, errorSummaryScope, focusFieldTarget, type FieldErrorEntry, } from './fieldCore.js';
+export type { FieldProps, FieldsetProps, FieldsetHandle, FieldOwnProps, FieldValidityDetail, FieldValidateHandle, FieldHandle, FieldMode, FieldValidator, FieldValidationResult, } from './types.js';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_REQUIRED_INDICATOR_ATTRIBUTE, FIELD_CONTROL_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, collectFieldErrors, ERROR_SUMMARY_RESCAN_EVENTS, errorSummaryScope, FORM_FIELD_ATTRIBUTE, FORM_MESSAGE_ATTRIBUTE, FIELD_NAME_ATTRIBUTE, focusFieldTarget, type FieldErrorEntry, resetFields, validateFields, } from './fieldCore.js';

package/dist/field/primitives.d.cts

@@ -0,0 +1,26 @@
+/**
+ * Primitives for `Field` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { FieldRoot, FieldLabel, FieldRequiredIndicator, FieldDescription, FieldCharacterCount, FieldError } from '@skdx/react/primitives/field';
+ *
+ * <FieldRoot>
+ *   <FieldLabel>
+ *     Why are you applying?
+ *     <FieldRequiredIndicator>(required)</FieldRequiredIndicator>
+ *   </FieldLabel>
+ *   <Textarea />
+ *   <FieldDescription>Keep it under 200 characters.</FieldDescription>
+ *   <FieldCharacterCount maxLength={200} threshold={75} />
+ *   <FieldError />
+ * </FieldRoot>
+ * ```
+ */
+export { FieldRoot, Fieldset } from './Field.cjs';
+export { FieldLabel } from './FieldLabel.cjs';
+export { FieldRequiredIndicator } from './FieldRequiredIndicator.cjs';
+export { FieldDescription } from './FieldDescription.cjs';
+export { FieldError } from './FieldError.cjs';
+export { FieldCharacterCount } from './FieldCharacterCount.cjs';
+export type { FieldRootProps, FieldsetProps, FieldsetHandle, FieldLabelProps, FieldRequiredIndicatorProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldCharacterCountOptions, } from './types.cjs';

package/dist/field/primitives.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Primitives for `Field` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { FieldRoot, FieldLabel, FieldRequiredIndicator, FieldDescription, FieldCharacterCount, FieldError } from '@skdx/react/primitives/field';
+ *
+ * <FieldRoot>
+ *   <FieldLabel>
+ *     Why are you applying?
+ *     <FieldRequiredIndicator>(required)</FieldRequiredIndicator>
+ *   </FieldLabel>
+ *   <Textarea />
+ *   <FieldDescription>Keep it under 200 characters.</FieldDescription>
+ *   <FieldCharacterCount maxLength={200} threshold={75} />
+ *   <FieldError />
+ * </FieldRoot>
+ * ```
+ */
+export { FieldRoot, Fieldset } from './Field.js';
+export { FieldLabel } from './FieldLabel.js';
+export { FieldRequiredIndicator } from './FieldRequiredIndicator.js';
+export { FieldDescription } from './FieldDescription.js';
+export { FieldError } from './FieldError.js';
+export { FieldCharacterCount } from './FieldCharacterCount.js';
+export type { FieldRootProps, FieldsetProps, FieldsetHandle, FieldLabelProps, FieldRequiredIndicatorProps, FieldDescriptionProps, FieldErrorProps, FieldCharacterCountProps, FieldCharacterCountOptions, } from './types.js';

package/dist/field/types.d.cts

@@ -1,8 +1,38 @@
-import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type * as React from 'react';
+import type { PolymorphicTag, PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FieldCharacterCountOptions, FieldMode, FieldSnapshot, FieldValidator } from './fieldCore.cjs';
 export type { FieldCharacterCountOptions, FieldMode, FieldValidationResult, FieldValidator, } from './fieldCore.cjs';
 /** The state a `Field` reports through {@link FieldOwnProps.onValidityChange}. */
 export type FieldValidityDetail = Omit<FieldSnapshot, 'controlId'>;
+/**
+ * Imperative Field contract (shared across all five framework packages).
+ */
+export interface FieldValidateHandle {
+    /**
+     * Run validation now (server errors, custom, native constraint, character count).
+     * Named for the platform method; allows all five frameworks to use `validate` prop name.
+     */
+    checkValidity(): Promise<boolean>;
+    /**
+     * Clear messages and `touched`/`dirty` flags, re-derive `filled`/`count` from control.
+     * Clear `errors` prop too (it's declarative, re-applied next render).
+     */
+    reset(): void;
+}
+/**
+ * What {@link Field}'s forwarded ref carries: the root `<div>` plus
+ * `validate()`. Type your ref as this to call it —
+ * `React.useRef<FieldHandle>(null)`.
+ */
+export type FieldHandle = HTMLDivElement & FieldValidateHandle;
+/**
+ * What {@link Fieldset}'s forwarded ref carries: the `<fieldset>` plus
+ * `validate()`. `FieldValidateHandle` comes first because `<fieldset>` has a
+ * synchronous `checkValidity()` of its own: a call against the intersection
+ * resolves to whichever side is named first, and the async one is what the
+ * node actually carries at runtime.
+ */
+export type FieldsetHandle = FieldValidateHandle & HTMLFieldSetElement;
 /** The validation-model props shared by {@link FieldProps} and {@link FieldsetProps}. */
 export interface FieldOwnProps {
     /**
@@ -37,20 +67,36 @@ export interface FieldOwnProps {
      * @default undefined
      */
     name?: string;
+    /**
+     * Whether an answer is mandatory. Reflected onto the wrapped control as the
+     * native `required` attribute when it is an `<input>`/`<select>`/
+     * `<textarea>`, and as `aria-required="true"` when it is a group or a
+     * widget-role element, which has no native `required` to set.
+     *
+     * Render a `FieldRequiredIndicator` inside the `FieldLabel` to say so
+     * visibly; its text joins the control's accessible name, so the requirement
+     * is announced rather than only drawn.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Whether the field is unavailable. Applied to the wrapped control — the
+     * native `disabled` attribute where there is one, `aria-disabled="true"`
+     * otherwise, because a disabled *widget* stays focusable and stays
+     * announced — and mirrored as `data-disabled` on the Field root and the
+     * control for styling.
+     * @default false
+     */
+    disabled?: boolean;
     /**
      * Fires whenever the field's validity or interaction state changes.
      * @default undefined
      */
     onValidityChange?: (detail: FieldValidityDetail) => void;
     /**
-     * Words every piece of character-count copy this Field produces: the text
-     * `FieldCharacterCount` renders, the message announced a typing pause after
-     * the last keystroke, and the error raised once the value passes the soft
-     * limit. A negative `remaining` means over the limit.
-     *
-     * One prop for all three deliberately — the announced count and the rendered
-     * count saying different things is worse than either being in English.
-     * @default undefined — the built-in GOV.UK wording ("You have 12 characters remaining").
+     * Words all character-count copy: rendered text, announced message, and over-limit error.
+     * Negative `remaining` means over the limit. One callback for all three for consistency.
+     * @default undefined
      */
     getCharacterCountMessage?: (remaining: number) => string;
     /**
@@ -61,21 +107,75 @@ export interface FieldOwnProps {
      * @default undefined — 'This field is invalid.'
      */
     invalidMessage?: string;
+    /**
+     * How long, in milliseconds, `mode="change"` waits after the last keystroke
+     * before running `validate`. Only `change` mode is debounced, and a blur
+     * cancels the pending run and validates immediately — the delay exists to
+     * keep a validator quiet *while* the user types, and a blur means they have
+     * stopped.
+     * @default 0 — no debounce.
+     */
+    validationDebounceTime?: number;
 }
-/** Props for {@link Field}, which wires one control to its label, description, and error text. */
-export interface FieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'value'>, FieldOwnProps {
+/** Props for {@link FieldRoot}: {@link FieldProps} minus the derived-anatomy-only props. */
+export type FieldRootProps = Omit<FieldProps, 'label' | 'description'> & Pick<PrimitivePropsWithRef<'div'>, 'asChild'>;
+/**
+ * Props for {@link Field}, which wires one control to its label, description,
+ * and error text. No `asChild`: the recipe always wraps its children in the
+ * derived anatomy, so `Slot` would never receive the single element it needs.
+ * Reach for `primitives/field`'s headless `FieldRoot` for that.
+ */
+export interface FieldProps extends Omit<PrimitivePropsWithRef<'div'>, 'value' | 'asChild'>, FieldOwnProps {
+    /**
+     * The control's label, rendered into a derived `FieldLabel` whose `htmlFor`
+     * points at the control the Field found. The required marker is derived
+     * *inside* it, so the requirement joins the control's accessible name
+     * rather than sitting beside it.
+     * @default undefined — no label is rendered, and the control is unnamed.
+     */
+    label?: React.ReactNode;
+    /**
+     * Help text, rendered into a derived `FieldDescription` whose id joins the
+     * control's `aria-describedby`, so it is announced with the control.
+     * @default undefined — no description is rendered.
+     */
+    description?: React.ReactNode;
 }
-/** Props for {@link Fieldset}, a {@link Field} that groups several controls under a `<legend>`. */
+/** Props for {@link Fieldset}, a {@link FieldRoot} that groups several controls under a `<legend>`. */
 export interface FieldsetProps extends Omit<PrimitivePropsWithRef<'fieldset'>, 'value' | 'name'>, FieldOwnProps {
 }
 /** Props for {@link FieldLabel}, which renders a `<label>` — or a `<legend>` inside a {@link Fieldset}. */
 export interface FieldLabelProps extends PrimitivePropsWithRef<'label'> {
 }
+/** Props for {@link FieldRequiredIndicator}, the "this one is mandatory" marker inside a {@link FieldLabel}. */
+export interface FieldRequiredIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Overrides the default `*`. Prefer words — the indicator sits inside the
+     * `FieldLabel`, so whatever it renders is read out as part of the control's
+     * accessible name, and "Email (required)" says more than "Email star".
+     * @default undefined — renders `*`.
+     */
+    children?: React.ReactNode;
+}
 /** Props for {@link FieldDescription}, help text announced with the control. */
 export interface FieldDescriptionProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Element name to render instead of the default tag, from the library's
+     * allowlist of tags. Takes a tag name only, never a component — `asChild`
+     * is React's escape hatch for that, and wins when both are set.
+     * @default 'span'
+     */
+    as?: PolymorphicTag;
 }
 /** Props for {@link FieldError}, rendered only while the field is invalid. */
 export interface FieldErrorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Element name to render instead of the default tag, from the library's
+     * allowlist of tags. Takes a tag name only, never a component — `asChild`
+     * is React's escape hatch for that, and wins when both are set.
+     * @default 'span'
+     */
+    as?: PolymorphicTag;
 }
 /** Props for {@link FieldCharacterCount}, the running "N characters remaining" count. */
 export interface FieldCharacterCountProps extends PrimitivePropsWithRef<'span'> {
@@ -100,6 +200,8 @@ export interface FieldContextValue {
     controlId?: string;
     errors: string[];
     grouped: boolean;
+    /** Whether the Field is required, so `FieldRequiredIndicator` knows whether to render at all. */
+    required: boolean;
     count: number;
     setCharacterCount: (options: FieldCharacterCountOptions | null) => void;
     /** The root's `getCharacterCountMessage`, so the rendered count uses the same wording as the announced one. */