@skdx/vue 0.26.0

package/dist/field/fieldCore.d.cts

@@ -0,0 +1,284 @@
+/**
+ * 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`.
+ */
+/** 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. */
+export type FieldValidationResult = string | string[] | null | undefined | void;
+/** A Field's validator, sync or async. */
+export type FieldValidator = (value: unknown) => FieldValidationResult | Promise<FieldValidationResult>;
+/** The bubbling DOM event a Field fires whenever its snapshot changes; a Form's ErrorSummary listens for it. */
+export declare const FIELD_VALIDITY_CHANGE_EVENT = "validity-change";
+/** Marks a Field root, so the error summary can find failing fields without a registry. */
+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.
+ */
+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";
+/** Marks a Field's error element, so its id can be added to `aria-describedby` and its text read by the summary. */
+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.
+ */
+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. */
+    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
+     */
+    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.
+ */
+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.
+ */
+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.
+ */
+export declare const FIELD_CONTROL_SELECTOR: string;
+/** 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. */
+    controlId: string;
+    /** Every current message, server-injected first. Empty means valid. */
+    errors: string[];
+    /** `errors.length === 0`. */
+    valid: boolean;
+    /** The control has been blurred at least once. */
+    touched: boolean;
+    /** The value has been edited at least once. */
+    dirty: boolean;
+    /** The control currently holds a value. */
+    filled: boolean;
+    /** Length of the control's value, tracked only while a character count is configured. */
+    count: number;
+}
+/** 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.
+     * @default 'blur'
+     */
+    mode?: FieldMode;
+    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    errors?: string | string[];
+    /** Value handed to `validate`; `undefined` reads it off the control instead. */
+    value?: unknown;
+    /** Field name, used as the error-summary link text when no error element is rendered. */
+    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.
+     */
+    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.'
+     */
+    invalidMessage?: string;
+}
+/** Everything the controller needs that the framework layer owns. */
+export interface FieldControllerOptions {
+    /** Id of the Label element, used for a group's `aria-labelledby`. */
+    labelId: string;
+    /** Id of the Description element. */
+    descriptionId: string;
+    /** Id of the Error element. */
+    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`. */
+    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.
+     */
+    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.
+ */
+export declare function readControlValue(control: HTMLElement | null): unknown;
+/** Whether a value counts as entered, for `data-filled`. */
+export declare function isFilled(value: unknown): boolean;
+/** One failing field, as listed by a Form's ErrorSummary. */
+export interface FieldErrorEntry {
+    /** The control's id — the link's `href` target. */
+    id: string;
+    /** 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.
+ */
+export declare function errorSummaryScope(root: Element): Element;
+/** Every currently-failing Field in `scope`, in document order — the summary's list. */
+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.
+ */
+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()`.
+ */
+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 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 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.
+     */
+    validate(): Promise<boolean>;
+    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    private markTouched;
+    private applyStateAttributes;
+    private resolveValue;
+    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 readonly handleFocusOut;
+    private readonly handleSubmit;
+}

package/dist/field/fieldCore.d.ts

@@ -0,0 +1,284 @@
+/**
+ * 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`.
+ */
+/** 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. */
+export type FieldValidationResult = string | string[] | null | undefined | void;
+/** A Field's validator, sync or async. */
+export type FieldValidator = (value: unknown) => FieldValidationResult | Promise<FieldValidationResult>;
+/** The bubbling DOM event a Field fires whenever its snapshot changes; a Form's ErrorSummary listens for it. */
+export declare const FIELD_VALIDITY_CHANGE_EVENT = "validity-change";
+/** Marks a Field root, so the error summary can find failing fields without a registry. */
+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.
+ */
+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";
+/** Marks a Field's error element, so its id can be added to `aria-describedby` and its text read by the summary. */
+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.
+ */
+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. */
+    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
+     */
+    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.
+ */
+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.
+ */
+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.
+ */
+export declare const FIELD_CONTROL_SELECTOR: string;
+/** 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. */
+    controlId: string;
+    /** Every current message, server-injected first. Empty means valid. */
+    errors: string[];
+    /** `errors.length === 0`. */
+    valid: boolean;
+    /** The control has been blurred at least once. */
+    touched: boolean;
+    /** The value has been edited at least once. */
+    dirty: boolean;
+    /** The control currently holds a value. */
+    filled: boolean;
+    /** Length of the control's value, tracked only while a character count is configured. */
+    count: number;
+}
+/** 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.
+     * @default 'blur'
+     */
+    mode?: FieldMode;
+    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    errors?: string | string[];
+    /** Value handed to `validate`; `undefined` reads it off the control instead. */
+    value?: unknown;
+    /** Field name, used as the error-summary link text when no error element is rendered. */
+    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.
+     */
+    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.'
+     */
+    invalidMessage?: string;
+}
+/** Everything the controller needs that the framework layer owns. */
+export interface FieldControllerOptions {
+    /** Id of the Label element, used for a group's `aria-labelledby`. */
+    labelId: string;
+    /** Id of the Description element. */
+    descriptionId: string;
+    /** Id of the Error element. */
+    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`. */
+    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.
+     */
+    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.
+ */
+export declare function readControlValue(control: HTMLElement | null): unknown;
+/** Whether a value counts as entered, for `data-filled`. */
+export declare function isFilled(value: unknown): boolean;
+/** One failing field, as listed by a Form's ErrorSummary. */
+export interface FieldErrorEntry {
+    /** The control's id — the link's `href` target. */
+    id: string;
+    /** 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.
+ */
+export declare function errorSummaryScope(root: Element): Element;
+/** Every currently-failing Field in `scope`, in document order — the summary's list. */
+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.
+ */
+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()`.
+ */
+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 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 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.
+     */
+    validate(): Promise<boolean>;
+    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    private markTouched;
+    private applyStateAttributes;
+    private resolveValue;
+    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 readonly handleFocusOut;
+    private readonly handleSubmit;
+}

package/dist/field/fieldCore.js

@@ -0,0 +1 @@
+var t="validity-change",e="data-skdx-field",s="data-skdx-field-name",r="data-skdx-field-message",i="data-skdx-field-description",o="data-skdx-field-error",n="data-skdx-field-character-count",a=1e3;function h(t){const e=Math.abs(t),s=1===e?"character":"characters";return t<0?`You have ${e} ${s} too many`:`You have ${e} ${s} remaining`}function l(t,e,s=0){return s<=0||t>=e*s/100}var u="This field is invalid.",d="data-skdx-field-control",c=[`[${d}]`,'input:not([type="hidden"])',"select","textarea",'[role="textbox"]','[role="searchbox"]','[role="combobox"]','[role="listbox"]','[role="radiogroup"]','[role="group"]','[role="slider"]','[role="spinbutton"]','[role="checkbox"]','[role="radio"]','[role="switch"]'].join(", "),p=/* @__PURE__ */new Set(["radiogroup","group"]),m=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function f(t){return null==t?[]:(Array.isArray(t)?t:[t]).filter(t=>"string"==typeof t&&""!==t.trim())}function v(t){for(const e of Array.from(t.querySelectorAll(c)))if("true"!==e.getAttribute("aria-hidden")&&e.closest("[data-skdx-field]")===t)return e;return null}function b(t,e){for(const s of Array.from(t.querySelectorAll(e)))if(s.closest("[data-skdx-field]")===t)return s;return null}function g(t){if(!t)return;const e=t;return"checkbox"===e.type||"radio"===e.type?e.checked:"value"in t?e.value:t.querySelector('input[aria-hidden="true"]')?.value}function A(t){return null!=t&&!1!==t&&""!==t&&!(Array.isArray(t)&&0===t.length)}function E(t,e,s){s?t.setAttribute(e,""):t.removeAttribute(e)}function y(t){return t.closest("form, skdx-form")??t.parentElement??t}function T(t){return Array.from(t.querySelectorAll(`[${e}][data-invalid]`)).flatMap(t=>{const e=v(t),s=b(t,"[data-skdx-field-error]")?.textContent?.trim()||t.getAttribute("data-skdx-field-message")||t.getAttribute("data-skdx-field-name")||"";return e?.id&&s?[{id:e.id,message:s}]:[]})}function I(t,e=document){const s=e.getElementById(t);if(!s)return;const r=s.getAttribute("role"),i=("FIELDSET"===s.tagName||null!==r&&p.has(r)?s.querySelector(m):null)??s;i.focus(),i.scrollIntoView?.({block:"center"})}var C=class{constructor(t){this.options=t,this.props={},this.root=null,this.form=null,this.control=null,this.baseDescribedBy="",this.runToken=0,this.pending=!1,this.injected=[],this.custom=[],this.characterCount=null,this.handleInput=()=>{const t=this.isOverLimit(this.snapshot.count),e=this.readCount();this.update({dirty:!0,filled:A(this.resolveValue()),count:e,errors:this.composeErrors(e)}),this.scheduleCountAnnouncement(e,t),("change"===this.props.mode||this.snapshot.errors.length>0)&&this.runValidation()},this.handleFocusOut=()=>{const t=this.readCount();this.update({touched:!0,filled:A(this.resolveValue()),count:t,errors:this.composeErrors(t)}),("blur"===(this.props.mode??"blur")||this.snapshot.errors.length>0)&&this.runValidation()},this.handleSubmit=t=>{if(t.target?.closest?.("form")!==this.form)return;this.markTouched();const e=this.runValidation({silent:!0});(L(e)||e.length>0||this.pending)&&t.preventDefault()},this.snapshot={controlId:t.controlId,errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0}}get state(){return this.snapshot}setProps(t){this.props=t;const e=f(t.errors??null);(function(t,e){return t.length===e.length&&t.every((t,s)=>t===e[s])})(this.injected,e)||(this.injected=e,this.update({errors:this.composeErrors()}))}setCharacterCount(t){if((this.characterCount?.maxLength??null)===(t?.maxLength??null)&&(this.characterCount?.threshold??0)===(t?.threshold??0))return;this.characterCount=t;const e=this.readCount();this.update({count:e,errors:this.composeErrors(e)})}readCount(){const t=this.resolveValue();return"string"==typeof t?t.length:0}countMessage(t){return(this.props.getCharacterCountMessage??h)(t)}isOverLimit(t){return null!==this.characterCount&&t>this.characterCount.maxLength}composeErrors(t=this.snapshot.count){const e=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(t)&&e.push(this.countMessage(this.characterCount.maxLength-t)),e}scheduleCountAnnouncement(t,e){const s=this.characterCount;if(!s)return;if(clearTimeout(this.announceTimer),this.isOverLimit(t))return void(e||this.options.announce(this.countMessage(s.maxLength-t),"assertive"));if(!l(t,s.maxLength,s.threshold))return;const r=s.maxLength-t;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(r),"polite")},1e3)}connect(t){this.root=t,t.setAttribute(e,""),t.addEventListener("input",this.handleInput,!0),t.addEventListener("change",this.handleInput,!0),t.addEventListener("focusout",this.handleFocusOut,!0),this.form=t.closest("form"),this.form&&t.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();const s=this.readCount();this.update({filled:A(this.resolveValue()),count:s,errors:this.composeErrors(s)})}disconnect(){clearTimeout(this.announceTimer);const t=this.root;t&&(t.removeEventListener("input",this.handleInput,!0),t.removeEventListener("change",this.handleInput,!0),t.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&t.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),this.root=null,this.form=null,this.control=null)}sync(){const t=this.root;if(!t)return;const e=v(t);e!==this.control&&(this.control=e,this.baseDescribedBy=e?.getAttribute("aria-describedby")??"");const{name:n}=this.props;n?t.setAttribute(s,n):t.removeAttribute(s);const a=this.snapshot.errors.join(" ");if(a?t.setAttribute(r,a):t.removeAttribute(r),this.applyStateAttributes(t),!e)return;e.id||(e.id=this.options.controlId),e.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:e.id},this.options.onSnapshotChange(this.snapshot));const h=null!==b(t,`[${i}]`),l=null!==b(t,`[${o}]`),u=function(t,...e){const s=t.split(/\s+/).filter(Boolean);for(const t of e)t&&!s.includes(t)&&s.push(t);return s.join(" ")}(this.baseDescribedBy,h?this.options.descriptionId:void 0,l?this.options.errorId:void 0);u?e.setAttribute("aria-describedby",u):e.removeAttribute("aria-describedby"),this.snapshot.errors.length>0?e.setAttribute("aria-invalid","true"):e.removeAttribute("aria-invalid");const d=null!==t.ownerDocument.getElementById(this.options.labelId);this.options.grouped&&d?e.setAttribute("aria-labelledby",this.options.labelId):e.getAttribute("aria-labelledby")===this.options.labelId&&e.removeAttribute("aria-labelledby"),this.applyStateAttributes(e)}validate(){return Promise.resolve(this.runValidation()).then(t=>0===t.length)}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(t){const{errors:e,touched:s,dirty:r,filled:i,count:o}=this.snapshot;E(t,"data-invalid",e.length>0),E(t,"data-valid",0===e.length),E(t,"data-touched",s),E(t,"data-dirty",r),E(t,"data-filled",i),E(t,"data-over-limit",this.isOverLimit(o))}resolveValue(){return void 0!==this.props.value?this.props.value:g(this.control)}nativeMessage(){const t=this.control;return!t?.validity||t.validity.valid?null:t.validationMessage||this.props.invalidMessage||"This field is invalid."}runValidation(t={}){const e=++this.runToken,s=this.props.validate?.(this.resolveValue());return L(s)?(this.pending=!0,Promise.resolve(s).then(s=>e!==this.runToken?this.snapshot.errors:(this.pending=!1,this.commit(s,t)))):this.commit(s,t)}commit(t,e){if(this.custom=f(t),0===this.custom.length&&0===this.injected.length){const t=this.nativeMessage();t&&(this.custom=[t])}const s=this.readCount(),r=this.composeErrors(s),i=0===this.snapshot.errors.length;this.update({errors:r,count:s,filled:A(this.resolveValue())});const o=r[0];return o&&i&&!e.silent&&this.options.announce(o,"assertive"),r}update(e){const s={...this.snapshot,...e,valid:!0};s.valid=0===s.errors.length,!function(t,e){return t.controlId===e.controlId&&t.valid===e.valid&&t.touched===e.touched&&t.dirty===e.dirty&&t.filled===e.filled&&t.count===e.count&&t.errors.length===e.errors.length&&t.errors.every((t,s)=>t===e.errors[s])}(this.snapshot,s)&&(this.snapshot=s,this.sync(),this.options.onSnapshotChange(s),this.root?.dispatchEvent(new CustomEvent(t,{bubbles:!0,composed:!0,detail:{valid:s.valid,errors:s.errors,touched:s.touched,dirty:s.dirty,filled:s.filled,count:s.count}})))}};function L(t){return"function"==typeof t?.then}export{a as CHARACTER_COUNT_ANNOUNCE_DELAY_MS,n as FIELD_CHARACTER_COUNT_ATTRIBUTE,d as FIELD_CONTROL_ATTRIBUTE,c as FIELD_CONTROL_SELECTOR,i as FIELD_DESCRIPTION_ATTRIBUTE,o as FIELD_ERROR_ATTRIBUTE,r as FIELD_MESSAGE_ATTRIBUTE,s as FIELD_NAME_ATTRIBUTE,e as FIELD_ROOT_ATTRIBUTE,t as FIELD_VALIDITY_CHANGE_EVENT,C as FieldController,u as NATIVE_INVALID_FALLBACK_MESSAGE,h as characterCountMessage,l as characterCountVisible,T as collectFieldErrors,y as errorSummaryScope,v as findFieldControl,I as focusFieldTarget,A as isFilled,f as normalizeMessages,g as readControlValue};

package/dist/field/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./fieldCore.cjs"),r=require("./Field.vue.cjs"),i=require("./Fieldset.vue.cjs"),_=require("./FieldLabel.vue.cjs"),t=require("./FieldDescription.vue.cjs"),E=require("./FieldError.vue.cjs"),C=require("./FieldCharacterCount.vue.cjs");exports.CHARACTER_COUNT_ANNOUNCE_DELAY_MS=e.CHARACTER_COUNT_ANNOUNCE_DELAY_MS;exports.FIELD_CHARACTER_COUNT_ATTRIBUTE=e.FIELD_CHARACTER_COUNT_ATTRIBUTE;exports.FIELD_CONTROL_SELECTOR=e.FIELD_CONTROL_SELECTOR;exports.FIELD_VALIDITY_CHANGE_EVENT=e.FIELD_VALIDITY_CHANGE_EVENT;exports.NATIVE_INVALID_FALLBACK_MESSAGE=e.NATIVE_INVALID_FALLBACK_MESSAGE;exports.SkdxField=r.default;exports.SkdxFieldCharacterCount=C.default;exports.SkdxFieldDescription=t.default;exports.SkdxFieldError=E.default;exports.SkdxFieldLabel=_.default;exports.SkdxFieldset=i.default;exports.characterCountMessage=e.characterCountMessage;exports.characterCountVisible=e.characterCountVisible;exports.findFieldControl=e.findFieldControl;

package/dist/field/index.d.cts

@@ -0,0 +1,8 @@
+export { default as SkdxField } from './Field.vue.cjs';
+export { default as SkdxFieldset } from './Fieldset.vue.cjs';
+export { default as SkdxFieldLabel } from './FieldLabel.vue.cjs';
+export { default as SkdxFieldDescription } from './FieldDescription.vue.cjs';
+export { default as SkdxFieldError } from './FieldError.vue.cjs';
+export { default as SkdxFieldCharacterCount } from './FieldCharacterCount.vue.cjs';
+export type { FieldValidityDetail } from './context.cjs';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, type FieldMode, type FieldValidator, type FieldValidationResult, type FieldCharacterCountOptions, } from './fieldCore.cjs';

package/dist/field/index.d.ts

@@ -0,0 +1,8 @@
+export { default as SkdxField } from './Field.vue.js';
+export { default as SkdxFieldset } from './Fieldset.vue.js';
+export { default as SkdxFieldLabel } from './FieldLabel.vue.js';
+export { default as SkdxFieldDescription } from './FieldDescription.vue.js';
+export { default as SkdxFieldError } from './FieldError.vue.js';
+export { default as SkdxFieldCharacterCount } from './FieldCharacterCount.vue.js';
+export type { FieldValidityDetail } from './context.js';
+export { CHARACTER_COUNT_ANNOUNCE_DELAY_MS, characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_CONTROL_SELECTOR, FIELD_VALIDITY_CHANGE_EVENT, NATIVE_INVALID_FALLBACK_MESSAGE, findFieldControl, type FieldSnapshot, type FieldMode, type FieldValidator, type FieldValidationResult, type FieldCharacterCountOptions, } from './fieldCore.js';

package/dist/field/index.js

@@ -0,0 +1 @@
+import{CHARACTER_COUNT_ANNOUNCE_DELAY_MS as e,FIELD_CHARACTER_COUNT_ATTRIBUTE as s,FIELD_CONTROL_SELECTOR as a,FIELD_VALIDITY_CHANGE_EVENT as r,NATIVE_INVALID_FALLBACK_MESSAGE as E,characterCountMessage as C,characterCountVisible as i,findFieldControl as o}from"./fieldCore.js";import _ from"./Field.vue.js";import A from"./Fieldset.vue.js";import t from"./FieldLabel.vue.js";import T from"./FieldDescription.vue.js";import d from"./FieldError.vue.js";import F from"./FieldCharacterCount.vue.js";export{e as CHARACTER_COUNT_ANNOUNCE_DELAY_MS,s as FIELD_CHARACTER_COUNT_ATTRIBUTE,a as FIELD_CONTROL_SELECTOR,r as FIELD_VALIDITY_CHANGE_EVENT,E as NATIVE_INVALID_FALLBACK_MESSAGE,_ as SkdxField,F as SkdxFieldCharacterCount,T as SkdxFieldDescription,d as SkdxFieldError,t as SkdxFieldLabel,A as SkdxFieldset,C as characterCountMessage,i as characterCountVisible,o as findFieldControl};

package/dist/field/useField.cjs

@@ -0,0 +1 @@
+const v=require("./fieldCore.cjs"),h=require("../utils/liveAnnouncer.cjs"),o=require("./context.cjs");let n=require("vue");function g(e,u,I){const c={labelId:o.nextFieldId("label"),descriptionId:o.nextFieldId("description"),errorId:o.nextFieldId("error"),controlId:o.nextFieldId("control")},a=(0,n.ref)(c.controlId),l=(0,n.ref)([]),d=(0,n.ref)(0),i=(0,n.ref)(null),r=new v.FieldController({...c,grouped:u,onSnapshotChange:t=>{a.value=t.controlId,l.value=t.errors,d.value=t.count;const{controlId:s,...f}=t;I(f)},announce:h.announce});(0,n.provide)(o.FIELD_CONTEXT,{...c,controlId:a,errors:l,grouped:u,count:d,setCharacterCount:t=>r.setCharacterCount(t),get getCharacterCountMessage(){return e.getCharacterCountMessage},requestSync:()=>r.sync()});let C=!1;return(0,n.watchEffect)(()=>{const t={validate:e.validate,mode:e.mode,errors:e.errors,value:e.value,name:e.name,getCharacterCountMessage:e.getCharacterCountMessage,invalidMessage:e.invalidMessage},s=i.value;s&&!C&&(C=!0,r.connect(s)),r.setProps(t),r.sync()},{flush:"post"}),(0,n.watch)([l,a],()=>r.sync(),{flush:"post"}),(0,n.onUnmounted)(()=>r.disconnect()),i}exports.useField=g;

package/dist/field/useField.d.cts

@@ -0,0 +1,13 @@
+import { type Ref } from 'vue';
+import { type FieldValidityDetail } from './context.cjs';
+import { type FieldControllerProps } from './fieldCore.cjs';
+/**
+ * Creates and drives the {@link FieldController} for one Field root, and
+ * provides the {@link FIELD_CONTEXT} its parts read. The controller does all
+ * the DOM work — discovery, ARIA wiring, the validation model — so this
+ * composable only feeds it props, tells it about renders, and mirrors its
+ * snapshot into refs so the parts re-render.
+ *
+ * Returns the template ref to bind to the root element.
+ */
+export declare function useField(props: FieldControllerProps, grouped: boolean, onValidityChange: (detail: FieldValidityDetail) => void): Ref<HTMLElement | null>;

package/dist/field/useField.d.ts

@@ -0,0 +1,13 @@
+import { type Ref } from 'vue';
+import { type FieldValidityDetail } from './context.js';
+import { type FieldControllerProps } from './fieldCore.js';
+/**
+ * Creates and drives the {@link FieldController} for one Field root, and
+ * provides the {@link FIELD_CONTEXT} its parts read. The controller does all
+ * the DOM work — discovery, ARIA wiring, the validation model — so this
+ * composable only feeds it props, tells it about renders, and mirrors its
+ * snapshot into refs so the parts re-render.
+ *
+ * Returns the template ref to bind to the root element.
+ */
+export declare function useField(props: FieldControllerProps, grouped: boolean, onValidityChange: (detail: FieldValidityDetail) => void): Ref<HTMLElement | null>;