@skdx/vue 0.26.0 → 0.28.0

package/dist/field/fieldCore.d.cts

@@ -1,15 +1,8 @@
 /**
- * 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 Field engine: discovers controls, wires ARIA, runs validation,
+ * and mirrors state as `data-*` so all five packages run the same algorithm.
+ * Framework layer creates controller, syncs after each render, re-renders on
+ * snapshot changes.
  */
 /** When a Field first runs its validator. See {@link FieldControllerProps.mode}. */
 export type FieldMode = 'change' | 'blur' | 'submit';
@@ -23,16 +16,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 synchronously when 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,245 +24,174 @@ 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 validator is still running. */
+export declare const FIELD_PENDING_ATTRIBUTE = "data-skdx-field-pending";
+/** Marks the submit the engine re-dispatches once every pending Field settles. */
+export declare const FIELD_RESUBMIT_ATTRIBUTE = "data-skdx-field-resubmit";
+/** Marks a FormField root: the native constraint validation half of the family. */
+export declare const FORM_FIELD_ATTRIBUTE = "data-skdx-form-field";
+/** Marks a rendered FormMessage for error summary link text extraction. */
+export declare const FORM_MESSAGE_ATTRIBUTE = "data-skdx-form-message";
+/** Events an ErrorSummary rescans on, unified across all five packages. */
+export declare const ERROR_SUMMARY_RESCAN_EVENTS: readonly ["validity-change", "invalid", "change", "blur"];
+/** Marks a Form's ErrorSummary for announcement suppression decisions. */
+export declare const FIELD_ERROR_SUMMARY_ATTRIBUTE = "data-skdx-error-summary";
+/** Milliseconds after last keystroke before character count announces. */
 export declare const CHARACTER_COUNT_ANNOUNCE_DELAY_MS = 1000;
-/** What a Field's character count is configured with. */
+/** Configuration for a Field's character count. */
 export interface FieldCharacterCountOptions {
-    /** The soft limit. Deliberately *not* the control's native `maxlength`, which truncates silently. */
+    /** Soft limit, not the control's native truncating maxlength. */
     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.
-     * @default 0
-     */
+    /** Percentage before the count is shown; `0` shows from first render. @default 0 */
     threshold?: number;
 }
 /** The default count copy, in GOV.UK's wording. Negative `remaining` means over the 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 for controls failing native validation without a message. */
 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.
- */
+/** Opt-in marker: "I am my Field's control", for discovery in shadow roots. */
 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 for Field controls; first match wins in document order. */
 export declare const FIELD_CONTROL_SELECTOR: string;
-/** The public state of one Field, handed to the framework layer and to `validity-change` listeners. */
+/** Marks a Field's required indicator for styling and testing. */
+export declare const FIELD_REQUIRED_INDICATOR_ATTRIBUTE = "data-skdx-field-required-indicator";
+/** The public state of one Field. */
 export interface FieldSnapshot {
-    /** The id of the discovered control — the Label's `for`, and the error summary's link target. */
+    /** The discovered control's id. */
     controlId: string;
-    /** Every current message, server-injected first. Empty means valid. */
+    /** Current messages, server-injected first. */
     errors: string[];
     /** `errors.length === 0`. */
     valid: boolean;
-    /** The control has been blurred at least once. */
+    /** Control blurred at least once. */
     touched: boolean;
-    /** The value has been edited at least once. */
+    /** Value edited at least once. */
     dirty: boolean;
-    /** The control currently holds a value. */
+    /** Control currently holds a value. */
     filled: boolean;
-    /** Length of the control's value, tracked only while a character count is configured. */
+    /** Control value length, tracked only with character count configured. */
     count: number;
+    /** The control's live ValidityState, or null if none exists. */
+    validity: ValidityState | null;
 }
-/** The props the framework layer forwards into the controller on every render. */
+/** Props the framework layer forwards to the controller each render. */
 export interface FieldControllerProps {
-    /** See {@link FieldValidator}. */
+    /** Validator function. */
     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.
-     * @default 'blur'
-     */
+    /** When validation first runs. @default 'blur' */
     mode?: FieldMode;
-    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    /** Server-injected errors, shown before custom validation. */
     errors?: string | string[];
-    /** Value handed to `validate`; `undefined` reads it off the control instead. */
+    /** Value for validate; undefined reads control value. */
     value?: unknown;
-    /** Field name, used as the error-summary link text when no error element is rendered. */
+    /** Field name for error-summary link text. */
     name?: string;
-    /**
-     * Words the character-count copy — the text `SkdxFieldCharacterCount` 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.
-     * @default undefined — {@link characterCountMessage}'s English wording.
-     */
+    /** Whether answer is mandatory, reflected as required/aria-required. @default undefined */
+    required?: boolean;
+    /** Whether field is unavailable, reflected as disabled/aria-disabled. @default undefined */
+    disabled?: boolean;
+    /** Words character-count message and announcements. @default characterCountMessage English */
     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.
-     * @default undefined — 'This field is invalid.'
-     */
+    /** Fallback when control fails native validation without message. @default 'This field is invalid.' */
     invalidMessage?: string;
+    /** Milliseconds `mode: 'change'` waits before validation; 0 for each keystroke. @default 0 */
+    validationDebounceTime?: number;
 }
-/** Everything the controller needs that the framework layer owns. */
+/** Framework layer dependencies the controller needs. */
 export interface FieldControllerOptions {
-    /** Id of the Label element, used for a group's `aria-labelledby`. */
+    /** Label element id, used for group aria-labelledby. */
     labelId: string;
-    /** Id of the Description element. */
+    /** Description element id. */
     descriptionId: string;
-    /** Id of the Error element. */
+    /** Error element id. */
     errorId: string;
-    /** Fallback id assigned to a control that has none of its own. */
+    /** Fallback id for controls with none. */
     controlId: string;
-    /** True for a `Fieldset`: the Label is a `<legend>` and the control is labelled by `aria-labelledby`. */
+    /** True for Fieldset: label is legend, control named by aria-labelledby. */
     grouped: boolean;
-    /** Called whenever the snapshot changes, so the framework layer can re-render. */
+    /** Called when snapshot changes so framework 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.
-     */
+    /** Live-region announce callback; engine picks politeness per message. */
     announce: (message: string, politeness: 'polite' | 'assertive') => void;
 }
-/** Coerces whatever a validator (or the `errors` prop) returned into a message list. */
+/** Coerces validator/errors result 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. */
+/** The first control inside root that belongs to this Field. */
 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.
- */
+/** Value validator sees when consumer passes none: checked for checkbox, value property otherwise. */
 export declare function readControlValue(control: HTMLElement | null): unknown;
-/** Whether a value counts as entered, for `data-filled`. */
+/** Whether a value counts as entered. */
 export declare function isFilled(value: unknown): boolean;
-/** One failing field, as listed by a Form's ErrorSummary. */
+/** One failing field in an ErrorSummary list. */
 export interface FieldErrorEntry {
-    /** The control's id — the link's `href` target. */
+    /** Control id, the link's href target. */
     id: string;
-    /** The message shown as the link text. */
+    /** Message shown as 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.
- */
+/** Form a summary scans and listens on, defaulting to its parent. */
 export declare function errorSummaryScope(root: Element): Element;
-/** Every currently-failing Field in `scope`, in document order — the summary's list. */
+/** Every currently-failing field 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 every Field in scope and resolves whether all passed. */
+export declare function validateFields(scope: ParentNode): Promise<boolean>;
+/** Resets every Field in scope: what Form does on native reset. */
+export declare function resetFields(scope: ParentNode): void;
+/** Sends focus to failing field: control for non-groups, first control inside groups. */
 export declare function focusFieldTarget(id: string, doc?: Document): void;
-/**
- * Owns one Field's state machine. Created by the framework layer, given the
- * Field's root element on `connect()`, and told about re-renders via `sync()`.
- */
+/** One Field's state machine, created and synced by the framework layer. */
 export declare class FieldController {
     private readonly options;
     private props;
     private root;
     private form;
     private control;
-    /** The `aria-describedby` the consumer put on the control themselves, preserved across rewrites. */
     private baseDescribedBy;
-    /** Bumped on every validation run; a resolution from a superseded run is discarded. */
+    private baseLabelledBy;
+    /** Only this controller can withdraw what it wrote. */
+    private wroteLabelledBy;
+    private wroteRequired;
+    private wroteDisabled;
     private runToken;
     private pending;
-    /** Messages from the `errors` prop. Always listed first. */
     private injected;
-    /** Messages from the last `validate` run, or the native constraint-validation fallback. */
     private custom;
-    /** Set by a mounted character-count part; `null` while the Field has none. */
     private characterCount;
     private announceTimer;
+    private validationTimer;
+    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.
-     */
     setCharacterCount(options: FieldCharacterCountOptions | null): void;
-    /** Length of the control's current value; `0` when it holds something that is not text. */
     private readCount;
-    /** The count copy, in the consumer's wording when they supplied one. */
     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.
-     */
     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.
-     */
     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.
-     */
     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.
-     */
+    private applyConstraintState;
     validate(): Promise<boolean>;
-    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    reset(): void;
     private markTouched;
     private applyStateAttributes;
     private resolveValue;
+    private readValidity;
+    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.
-     */
     private runValidation;
     private commit;
     private update;
     private readonly handleInput;
+    private scheduleValidation;
+    private hasErrorSummary;
     private readonly handleFocusOut;
+    private isEngineResubmit;
     private readonly handleSubmit;
+    private resubmitIfSettled;
 }