@skdx/react 0.26.0 → 0.28.0

package/dist/field/fieldCore.d.cts

@@ -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;
 }