@skdx/web-components 0.26.0

package/dist/field/field-core.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 `<skdx-field-character-count>`
+     * 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/field-core.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 `<skdx-field-character-count>`
+     * 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/field-core.js

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

package/dist/field/index.cjs

@@ -0,0 +1 @@
+"use strict";var i=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var f=(t,e)=>{for(var d in e)i(t,d,{get:e[d],enumerable:!0})},m=(t,e,d,l)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of E(e))!c.call(t,o)&&o!==d&&i(t,o,{get:()=>e[o],enumerable:!(l=s(e,o))||l.enumerable});return t};var S=t=>m(i({},"__esModule",{value:!0}),t);var T={};f(T,{FIELD_CHARACTER_COUNT_ATTRIBUTE:()=>r.FIELD_CHARACTER_COUNT_ATTRIBUTE,FIELD_VALIDITY_CHANGE_EVENT:()=>r.FIELD_VALIDITY_CHANGE_EVENT,SkdxField:()=>a.SkdxField,SkdxFieldCharacterCount:()=>n.SkdxFieldCharacterCount,SkdxFieldDescription:()=>F.SkdxFieldDescription,SkdxFieldError:()=>C.SkdxFieldError,SkdxFieldLabel:()=>x.SkdxFieldLabel,SkdxFieldset:()=>p.SkdxFieldset,characterCountMessage:()=>r.characterCountMessage,characterCountVisible:()=>r.characterCountVisible});module.exports=S(T);var a=require("./Field.cjs"),p=require("./Fieldset.cjs"),x=require("./FieldLabel.cjs"),F=require("./FieldDescription.cjs"),C=require("./FieldError.cjs"),n=require("./FieldCharacterCount.cjs"),r=require("./field-core.cjs");0&&(module.exports={FIELD_CHARACTER_COUNT_ATTRIBUTE,FIELD_VALIDITY_CHANGE_EVENT,SkdxField,SkdxFieldCharacterCount,SkdxFieldDescription,SkdxFieldError,SkdxFieldLabel,SkdxFieldset,characterCountMessage,characterCountVisible});

package/dist/field/index.d.cts

@@ -0,0 +1,7 @@
+export { SkdxField } from './Field.cjs';
+export { SkdxFieldset } from './Fieldset.cjs';
+export { SkdxFieldLabel } from './FieldLabel.cjs';
+export { SkdxFieldDescription } from './FieldDescription.cjs';
+export { SkdxFieldError } from './FieldError.cjs';
+export { SkdxFieldCharacterCount } from './FieldCharacterCount.cjs';
+export { characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_VALIDITY_CHANGE_EVENT, type FieldCharacterCountOptions, type FieldMode, type FieldSnapshot, type FieldValidationResult, type FieldValidator, } from './field-core.cjs';

package/dist/field/index.d.ts

@@ -0,0 +1,7 @@
+export { SkdxField } from './Field.js';
+export { SkdxFieldset } from './Fieldset.js';
+export { SkdxFieldLabel } from './FieldLabel.js';
+export { SkdxFieldDescription } from './FieldDescription.js';
+export { SkdxFieldError } from './FieldError.js';
+export { SkdxFieldCharacterCount } from './FieldCharacterCount.js';
+export { characterCountMessage, characterCountVisible, FIELD_CHARACTER_COUNT_ATTRIBUTE, FIELD_VALIDITY_CHANGE_EVENT, type FieldCharacterCountOptions, type FieldMode, type FieldSnapshot, type FieldValidationResult, type FieldValidator, } from './field-core.js';

package/dist/field/index.js

@@ -0,0 +1 @@
+import{SkdxField as t}from"./Field.js";import{SkdxFieldset as d}from"./Fieldset.js";import{SkdxFieldLabel as l}from"./FieldLabel.js";import{SkdxFieldDescription as p}from"./FieldDescription.js";import{SkdxFieldError as F}from"./FieldError.js";import{SkdxFieldCharacterCount as n}from"./FieldCharacterCount.js";import{characterCountMessage as E,characterCountVisible as c,FIELD_CHARACTER_COUNT_ATTRIBUTE as f,FIELD_VALIDITY_CHANGE_EVENT as m}from"./field-core.js";export{f as FIELD_CHARACTER_COUNT_ATTRIBUTE,m as FIELD_VALIDITY_CHANGE_EVENT,t as SkdxField,n as SkdxFieldCharacterCount,p as SkdxFieldDescription,F as SkdxFieldError,l as SkdxFieldLabel,d as SkdxFieldset,E as characterCountMessage,c as characterCountVisible};

package/dist/file-upload/FileUpload.cjs

@@ -0,0 +1,5 @@
+"use strict";var f=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var F=(s,t)=>{for(var e in t)f(s,e,{get:t[e],enumerable:!0})},y=(s,t,e,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of b(t))!v.call(s,i)&&i!==e&&f(s,i,{get:()=>t[i],enumerable:!(a=d(t,i))||a.enumerable});return s};var g=s=>y(f({},"__esModule",{value:!0}),s),n=(s,t,e,a)=>{for(var i=a>1?void 0:a?d(t,e):t,l=s.length-1,o;l>=0;l--)(o=s[l])&&(i=(a?o(t,e,i):o(i))||i);return a&&i&&f(t,e,i),i};var C={};F(C,{SkdxFileUpload:()=>r});module.exports=g(C);var m=require("lit"),u=require("lit/decorators.js"),p=require("../internal/define.cjs"),c=require("../internal/form-associated.cjs");function E(s,t){if(!t)return!0;let e=t.split(",").map(l=>l.trim().toLowerCase()).filter(Boolean);if(e.length===0)return!0;let a=s.name.toLowerCase(),i=s.type.toLowerCase();return e.some(l=>l.startsWith(".")?a.endsWith(l):l.endsWith("/*")?i.startsWith(l.slice(0,-1)):i===l)}function z(s,t){let e=[];return E(s,t.accept)||e.push("file-invalid-type"),t.maxFileSize!==void 0&&s.size>t.maxFileSize&&e.push("file-too-large"),t.minFileSize!==void 0&&s.size<t.minFileSize&&e.push("file-too-small"),e.push(...t.validate?.(s)??[]),e}var r=class extends(0,c.FormAssociated)(m.LitElement){constructor(){super(...arguments);this.multiple=!1;this.disabled=!1;this.required=!1;this.internalFiles=[];this.inputEl=null}get files(){return this.value??this.internalFiles}updated(e){e.has("disabled")&&(this.disabled?this.setAttribute("data-disabled",""):this.removeAttribute("data-disabled"),this.broadcast()),e.has("value")&&this.broadcast(),(e.has("value")||e.has("required")||e.has("name"))&&this.syncFormState()}syncFormState(){this.setFormValue(this.multiFormValue(this.files)),this.setValueMissing(this.required&&this.files.length===0,"Please select a file.")}formResetCallback(){this.setFiles([])}addFiles(e){if(this.disabled)return;let a=this.multiple?this.files:[],i=(this.multiple?this.maxFiles??1/0:1)-a.length,l=[];for(let o of Array.from(e)){let h=z(o,this);if(l.length>=i&&h.push("too-many-files"),h.length>0){this.dispatchEvent(new CustomEvent("file-reject",{detail:{file:o,errors:h},bubbles:!0,composed:!0}));continue}l.push(o)}l.length!==0&&this.setFiles([...a,...l])}removeFile(e){this.setFiles(this.files.filter((a,i)=>i!==e))}setFiles(e){this.value===void 0&&(this.internalFiles=e),this.syncFormState(),this.dispatchEvent(new CustomEvent("value-change",{detail:e,bubbles:!0,composed:!0})),this.broadcast()}registerInput(e){this.inputEl=e}openPicker(){this.disabled||this.inputEl?.click()}broadcast(){this.dispatchEvent(new CustomEvent("skdx-file-upload-update",{bubbles:!0,composed:!0}))}render(){return m.html`<slot></slot>`}};r.styles=m.css`
+    :host {
+      display: block;
+    }
+  `,n([(0,u.property)({type:String})],r.prototype,"accept",2),n([(0,u.property)({type:Boolean,reflect:!0})],r.prototype,"multiple",2),n([(0,u.property)({type:Boolean,reflect:!0})],r.prototype,"disabled",2),n([(0,u.property)({attribute:!1})],r.prototype,"value",2),n([(0,u.property)({type:Boolean,reflect:!0})],r.prototype,"required",2),n([(0,u.property)({type:String,reflect:!0})],r.prototype,"name",2),n([(0,u.property)({attribute:"required-message"})],r.prototype,"requiredMessage",2),n([(0,u.property)({type:Number,attribute:"max-files"})],r.prototype,"maxFiles",2),n([(0,u.property)({type:Number,attribute:"max-file-size"})],r.prototype,"maxFileSize",2),n([(0,u.property)({type:Number,attribute:"min-file-size"})],r.prototype,"minFileSize",2),n([(0,u.property)({attribute:!1})],r.prototype,"validate",2),r=n([(0,p.customElement)("skdx-file-upload","file-upload","root")],r);0&&(module.exports={SkdxFileUpload});