@skdx/web-components 0.27.0 → 0.29.0

package/dist/internal/family.js

@@ -0,0 +1 @@
+function r(e,{selector:n=`skdx-${e}`,init:o}={}){let i=`skdx-${e}-internal-update`;return{event:i,selector:n,root:t=>t.closest(n),notify(t){t.dispatchEvent(new CustomEvent(i,o))}}}export{r as defineFamily};

package/dist/internal/field-core.cjs

@@ -0,0 +1 @@
+"use strict";var f=Object.defineProperty;var P=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var H=Object.prototype.hasOwnProperty;var q=(i,e)=>{for(var t in e)f(i,t,{get:e[t],enumerable:!0})},U=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of N(e))!H.call(i,n)&&n!==t&&f(i,n,{get:()=>e[n],enumerable:!(r=P(e,n))||r.enumerable});return i};var $=i=>U(f({},"__esModule",{value:!0}),i);var se={};q(se,{CHARACTER_COUNT_ANNOUNCE_DELAY_MS:()=>Y,ERROR_SUMMARY_RESCAN_EVENTS:()=>j,FIELD_CHARACTER_COUNT_ATTRIBUTE:()=>G,FIELD_CONTROL_ATTRIBUTE:()=>w,FIELD_CONTROL_SELECTOR:()=>I,FIELD_DESCRIPTION_ATTRIBUTE:()=>F,FIELD_ERROR_ATTRIBUTE:()=>L,FIELD_ERROR_SUMMARY_ATTRIBUTE:()=>D,FIELD_MESSAGE_ATTRIBUTE:()=>c,FIELD_NAME_ATTRIBUTE:()=>u,FIELD_PENDING_ATTRIBUTE:()=>v,FIELD_REQUIRED_INDICATOR_ATTRIBUTE:()=>z,FIELD_RESUBMIT_ATTRIBUTE:()=>h,FIELD_ROOT_ATTRIBUTE:()=>o,FIELD_VALIDITY_CHANGE_EVENT:()=>C,FORM_FIELD_ATTRIBUTE:()=>p,FORM_MESSAGE_ATTRIBUTE:()=>_,FieldController:()=>A,NATIVE_INVALID_FALLBACK_MESSAGE:()=>O,characterCountMessage:()=>M,characterCountVisible:()=>V,collectFieldErrors:()=>Z,errorSummaryScope:()=>X,findFieldControl:()=>x,focusFieldTarget:()=>ie,isFilled:()=>d,normalizeMessages:()=>b,readControlValue:()=>B,resetFields:()=>te,validateFields:()=>ee});module.exports=$(se);var C="validity-change",o="data-skdx-field",u="data-skdx-field-name",c="data-skdx-field-message",F="data-skdx-field-description",L="data-skdx-field-error",G="data-skdx-field-character-count",v="data-skdx-field-pending",h="data-skdx-field-resubmit",p="data-skdx-form-field",_="data-skdx-form-message",j=["validity-change","invalid","change","blur"],D="data-skdx-error-summary",Y=1e3;function M(i){let e=Math.abs(i),t=e===1?"character":"characters";return i<0?`You have ${e} ${t} too many`:`You have ${e} ${t} remaining`}function V(i,e,t=0){return t<=0?!0:i>=e*t/100}var O="This field is invalid.",w="data-skdx-field-control",I=[`[${w}]`,'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(", "),z="data-skdx-field-required-indicator",K=new Set(["INPUT","SELECT","TEXTAREA"]),k=new Set(["radiogroup","group"]),Q=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function b(i){return i==null?[]:(Array.isArray(i)?i:[i]).filter(t=>typeof t=="string"&&t.trim()!=="")}function x(i){for(let e of Array.from(i.querySelectorAll(I)))if(e.getAttribute("aria-hidden")!=="true"&&e.closest(`[${o}]`)===i)return e;return null}function g(i,e){return E(i,o,e)}function E(i,e,t){for(let r of Array.from(i.querySelectorAll(t)))if(r.closest(`[${e}]`)===i)return r;return null}function B(i){if(!i)return;let e=i;return e.type==="checkbox"||e.type==="radio"?e.checked:"value"in i?e.value:i.querySelector('input[aria-hidden="true"]')?.value}function d(i){return i==null||i===!1||i===""?!1:!(Array.isArray(i)&&i.length===0)}function a(i,e,t){t?i.setAttribute(e,""):i.removeAttribute(e)}function R(i,...e){let t=i.split(/\s+/).filter(Boolean);for(let r of e)r&&!t.includes(r)&&t.push(r);return t.join(" ")}function X(i){return i.closest("form, skdx-form")??i.parentElement??i}function J(i){let e=x(i),r=g(i,`[${L}]`)?.textContent?.trim()||i.getAttribute(c)||i.getAttribute(u)||"";return!e?.id||!r?[]:[{id:e.id,message:r}]}function W(i){let e=E(i,p,I);if(!e?.id||e.getAttribute("aria-invalid")!=="true")return[];let r=E(i,p,`[${_}]:not([hidden])`)?.textContent?.trim()||i.getAttribute(u)||"";return r?[{id:e.id,message:r}]:[]}function Z(i){return Array.from(i.querySelectorAll(`[${o}][data-invalid], [${p}]`)).flatMap(t=>(t.hasAttribute(o)?J:W)(t))}var T="__skdxFieldCheckValidity",y="__skdxFieldReset";async function ee(i){let e=Array.from(i.querySelectorAll(`[${o}]`));return(await Promise.all(e.map(r=>r[T]?.()??Promise.resolve(!0)))).every(Boolean)}function te(i){for(let e of Array.from(i.querySelectorAll(`[${o}]`)))e[y]?.()}function ie(i,e=document){let t=e.getElementById(i);if(!t)return;let r=t.getAttribute("role"),s=(t.tagName==="FIELDSET"||r!==null&&k.has(r)?t.querySelector(Q):null)??t;s.focus(),s.scrollIntoView?.({block:"center"})}var A=class{constructor(e){this.options=e;this.props={};this.root=null;this.form=null;this.control=null;this.baseDescribedBy="";this.baseLabelledBy="";this.wroteLabelledBy=!1;this.wroteRequired=!1;this.wroteDisabled=!1;this.wroteGroupDisabled=!1;this.runToken=0;this.pending=!1;this.injected=[];this.custom=[];this.characterCount=null;this.awaitingSubmit=!1;this.handleInput=()=>{let e=this.isOverLimit(this.snapshot.count),t=this.readCount();this.update({dirty:!0,filled:d(this.resolveValue()),count:t,errors:this.composeErrors(t)}),this.scheduleCountAnnouncement(t,e),(this.props.mode==="change"||this.snapshot.errors.length>0)&&this.scheduleValidation()};this.handleFocusOut=()=>{let e=this.readCount();this.update({touched:!0,filled:d(this.resolveValue()),count:e,errors:this.composeErrors(e)});let t=this.validationTimer!==void 0;clearTimeout(this.validationTimer),this.validationTimer=void 0;let r=this.props.mode??"blur";(t||r==="blur"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleSubmit=e=>{if(!this.form)return;let t=e.target;if(t!==this.form&&t?.closest?.("form")!==this.form||this.isEngineResubmit(e))return;this.markTouched();let r=this.runValidation({silent:this.hasErrorSummary()});if(S(r)){e.preventDefault(),this.awaitingSubmit=!0,Promise.resolve(r).then(()=>{this.awaitingSubmit&&(this.awaitingSubmit=!1,this.resubmitIfSettled())});return}(r.length>0||this.pending)&&e.preventDefault()};this.snapshot={controlId:"",errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0,validity:null}}get state(){return this.snapshot}setProps(e){let t=this.props.value;this.props=e;let r=b(e.errors??null),n=!re(this.injected,r);n&&(this.injected=r);let s=e.value!==t;if(!n&&!s)return;let l=this.readCount();this.update({count:l,filled:d(this.resolveValue()),errors:this.composeErrors(l)})}setCharacterCount(e){if((this.characterCount?.maxLength??null)===(e?.maxLength??null)&&(this.characterCount?.threshold??0)===(e?.threshold??0))return;this.characterCount=e;let r=this.readCount();this.update({count:r,errors:this.composeErrors(r)})}readCount(){let e=this.resolveValue();return typeof e=="string"?e.length:0}countMessage(e){return(this.props.getCharacterCountMessage??M)(e)}isOverLimit(e){return this.characterCount!==null&&e>this.characterCount.maxLength}composeErrors(e=this.snapshot.count){let t=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(e)&&t.push(this.countMessage(this.characterCount.maxLength-e)),t}scheduleCountAnnouncement(e,t){let r=this.characterCount;if(!r)return;if(clearTimeout(this.announceTimer),this.isOverLimit(e)){t||this.options.announce(this.countMessage(r.maxLength-e),"assertive");return}if(!V(e,r.maxLength,r.threshold))return;let n=r.maxLength-e;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(n),"polite")},1e3)}connect(e){this.root=e,e.setAttribute(o,""),Object.defineProperty(e,T,{value:()=>this.validate(),configurable:!0,enumerable:!1,writable:!0}),Object.defineProperty(e,y,{value:()=>this.reset(),configurable:!0,enumerable:!1,writable:!0}),e.addEventListener("input",this.handleInput,!0),e.addEventListener("change",this.handleInput,!0),e.addEventListener("focusout",this.handleFocusOut,!0),this.form=e.closest("form"),this.form&&e.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();let t=this.readCount();this.update({filled:d(this.resolveValue()),count:t,errors:this.composeErrors(t)})}disconnect(){clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.awaitingSubmit=!1;let e=this.root;e&&(e.removeEventListener("input",this.handleInput,!0),e.removeEventListener("change",this.handleInput,!0),e.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&e.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),delete e[T],delete e[y],this.root=null,this.form=null,this.control=null)}sync(){let e=this.root;if(!e)return;let t=x(e);t!==this.control&&(this.control=t,this.baseDescribedBy=t?.getAttribute("aria-describedby")??"",this.baseLabelledBy=t?.getAttribute("aria-labelledby")??"",this.wroteLabelledBy=!1,this.wroteRequired=!1,this.wroteDisabled=!1,this.wroteGroupDisabled=!1);let{name:r}=this.props;r?e.setAttribute(u,r):e.removeAttribute(u);let n=this.snapshot.errors.join(" ");n?e.setAttribute(c,n):e.removeAttribute(c),this.applyStateAttributes(e),t&&(t.id||(t.id=this.options.controlId),t.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:t.id,validity:this.readValidity()},this.options.onSnapshotChange(this.snapshot)),this.applyDescribedBy(e,t),this.snapshot.errors.length>0?t.setAttribute("aria-invalid","true"):t.removeAttribute("aria-invalid"),this.applyLabelledBy(e,t),this.applyConstraintState(t),this.applyStateAttributes(t))}applyDescribedBy(e,t){let r=g(e,`[${F}]`)!==null,n=g(e,`[${L}]`)!==null,s=R(this.baseDescribedBy,r?this.options.descriptionId:void 0,n?this.options.errorId:void 0);s?t.setAttribute("aria-describedby",s):t.removeAttribute("aria-describedby")}applyLabelledBy(e,t){let r=e.ownerDocument.getElementById(this.options.labelId)!==null;this.options.grouped&&r?(t.setAttribute("aria-labelledby",R(this.baseLabelledBy,this.options.labelId)),this.wroteLabelledBy=!0):this.wroteLabelledBy&&(this.baseLabelledBy?t.setAttribute("aria-labelledby",this.baseLabelledBy):t.removeAttribute("aria-labelledby"),this.wroteLabelledBy=!1)}applyConstraintState(e){let t=K.has(e.tagName),r=this.props.required===!0,n=this.props.disabled===!0;r?(t?e.setAttribute("required",""):e.setAttribute("aria-required","true"),this.wroteRequired=!0):this.wroteRequired&&(e.removeAttribute(t?"required":"aria-required"),this.wroteRequired=!1),n?(t?e.setAttribute("disabled",""):e.setAttribute("aria-disabled","true"),this.wroteDisabled=!0):this.wroteDisabled&&(e.removeAttribute(t?"disabled":"aria-disabled"),this.wroteDisabled=!1),t||this.applyGroupDisabled(e,n)}applyGroupDisabled(e,t){let r=e.getAttribute("role");if(!(!(e.tagName==="FIELDSET"||r!==null&&k.has(r))||!t&&!this.wroteGroupDisabled)){for(let s of e.querySelectorAll("input, select, textarea, button"))t?s.setAttribute("disabled",""):s.removeAttribute("disabled");this.wroteGroupDisabled=t}}validate(){return Promise.resolve(this.runValidation()).then(e=>e.length===0)}reset(){this.injected=[],this.custom=[],this.pending=!1,this.awaitingSubmit=!1,this.runToken++,clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.markPending(!1);let e=this.readCount();this.update({touched:!1,dirty:!1,count:e,filled:d(this.resolveValue()),errors:this.composeErrors(e)}),this.sync()}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(e){let{errors:t,touched:r,dirty:n,filled:s,count:l}=this.snapshot;a(e,"data-invalid",t.length>0),a(e,"data-valid",t.length===0),a(e,"data-touched",r),a(e,"data-dirty",n),a(e,"data-filled",s),a(e,"data-over-limit",this.isOverLimit(l)),a(e,"data-disabled",this.props.disabled===!0)}resolveValue(){return this.props.value!==void 0?this.props.value:B(this.control)}readValidity(){return this.control?.validity??null}markPending(e){this.root&&a(this.root,v,e)}nativeMessage(){let e=this.control;return!e?.validity||e.validity.valid?null:e.validationMessage||this.props.invalidMessage||O}runValidation(e={}){let t=++this.runToken,r=this.props.validate?.(this.resolveValue());return S(r)?(this.pending=!0,this.markPending(!0),Promise.resolve(r).then(n=>t!==this.runToken?this.snapshot.errors:(this.pending=!1,this.markPending(!1),this.commit(n,e)))):this.commit(r,e)}commit(e,t){if(this.custom=b(e),this.custom.length===0){let m=this.nativeMessage();m&&!this.injected.includes(m)&&(this.custom=[m])}let r=this.readCount(),n=this.composeErrors(r),s=this.snapshot.errors.length===0;this.update({errors:n,count:r,filled:d(this.resolveValue())});let l=n[0];return l&&s&&!t.silent&&this.options.announce(l,"assertive"),n}update(e){let t={...this.snapshot,...e,valid:!0,validity:this.readValidity()};t.valid=t.errors.length===0,!ne(this.snapshot,t)&&(this.snapshot=t,this.sync(),this.options.onSnapshotChange(t),this.root?.dispatchEvent(new CustomEvent(C,{bubbles:!0,composed:!0,detail:{valid:t.valid,errors:t.errors,touched:t.touched,dirty:t.dirty,filled:t.filled,count:t.count,validity:t.validity}})))}scheduleValidation(){clearTimeout(this.validationTimer),this.validationTimer=void 0;let e=this.props.mode==="change"?this.props.validationDebounceTime??0:0;if(e<=0){this.runValidation();return}this.validationTimer=setTimeout(()=>{this.validationTimer=void 0,this.runValidation()},e)}hasErrorSummary(){return this.form?.querySelector(`[${D}]`)!=null}isEngineResubmit(e){return this.form?.hasAttribute(h)?(this.snapshot.errors.length>0&&e.preventDefault(),!0):!1}resubmitIfSettled(){let e=this.form;if(!(!e||typeof e.requestSubmit!="function")&&!e.querySelector(`[${v}]`)&&!e.querySelector(`[${o}][data-invalid]`)){e.setAttribute(h,"");try{e.requestSubmit()}finally{e.removeAttribute(h)}}}};function S(i){return typeof i?.then=="function"}function re(i,e){return i.length===e.length&&i.every((t,r)=>t===e[r])}function ne(i,e){return i.controlId===e.controlId&&i.valid===e.valid&&i.touched===e.touched&&i.dirty===e.dirty&&i.filled===e.filled&&i.count===e.count&&i.validity===e.validity&&i.errors.length===e.errors.length&&i.errors.every((t,r)=>t===e.errors[r])}0&&(module.exports={CHARACTER_COUNT_ANNOUNCE_DELAY_MS,ERROR_SUMMARY_RESCAN_EVENTS,FIELD_CHARACTER_COUNT_ATTRIBUTE,FIELD_CONTROL_ATTRIBUTE,FIELD_CONTROL_SELECTOR,FIELD_DESCRIPTION_ATTRIBUTE,FIELD_ERROR_ATTRIBUTE,FIELD_ERROR_SUMMARY_ATTRIBUTE,FIELD_MESSAGE_ATTRIBUTE,FIELD_NAME_ATTRIBUTE,FIELD_PENDING_ATTRIBUTE,FIELD_REQUIRED_INDICATOR_ATTRIBUTE,FIELD_RESUBMIT_ATTRIBUTE,FIELD_ROOT_ATTRIBUTE,FIELD_VALIDITY_CHANGE_EVENT,FORM_FIELD_ATTRIBUTE,FORM_MESSAGE_ATTRIBUTE,FieldController,NATIVE_INVALID_FALLBACK_MESSAGE,characterCountMessage,characterCountVisible,collectFieldErrors,errorSummaryScope,findFieldControl,focusFieldTarget,isFilled,normalizeMessages,readControlValue,resetFields,validateFields});

package/dist/internal/field-core.d.cts

@@ -0,0 +1,248 @@
+/** 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 to the root on validity changes. */
+export declare const FIELD_MESSAGE_ATTRIBUTE = "data-skdx-field-message";
+/** Marks a Field's description element, so its id can be added to the control's `aria-describedby`. */
+export declare const FIELD_DESCRIPTION_ATTRIBUTE = "data-skdx-field-description";
+/** 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";
+/** Marks a Field whose async validator is still running. */
+export declare const FIELD_PENDING_ATTRIBUTE = "data-skdx-field-pending";
+/** Marks the re-dispatched submit after async validators have settled. */
+export declare const FIELD_RESUBMIT_ATTRIBUTE = "data-skdx-field-resubmit";
+/** Marks a FormField root, allowing error summary to list both Field and FormField failures. */
+export declare const FORM_FIELD_ATTRIBUTE = "data-skdx-form-field";
+/** Marks a rendered FormMessage so the error summary shows the user's displayed message. */
+export declare const FORM_MESSAGE_ATTRIBUTE = "data-skdx-form-message";
+/** Events a Form ErrorSummary should re-scan on. */
+export declare const ERROR_SUMMARY_RESCAN_EVENTS: readonly ["validity-change", "invalid", "change", "blur"];
+/** Marks a Form's ErrorSummary so the engine knows whether to suppress the Field's own announcement. */
+export declare const FIELD_ERROR_SUMMARY_ATTRIBUTE = "data-skdx-error-summary";
+/** Delay in milliseconds before character count announces remaining count. */
+export declare const CHARACTER_COUNT_ANNOUNCE_DELAY_MS = 1000;
+/** What a Field's character count is configured with. */
+export interface FieldCharacterCountOptions {
+    /** The soft limit, not the native `maxlength` which truncates silently. */
+    maxLength: number;
+    /**
+     * Percentage of `maxLength` before the count appears; `0` shows it immediately.
+     * @default 0
+     */
+    threshold?: number | undefined;
+}
+/** Default count message; negative means over-limit. */
+export declare function characterCountMessage(remaining: number): string;
+/** Whether a count has passed its threshold and should be rendered/announced. */
+export declare function characterCountVisible(count: number, maxLength: number, threshold?: number): boolean;
+/** Fallback message when native constraint validation has no `validationMessage`. */
+export declare const NATIVE_INVALID_FALLBACK_MESSAGE = "This field is invalid.";
+/** Marks an element as this Field's control, an escape hatch for composites in shadow DOM. */
+export declare const FIELD_CONTROL_ATTRIBUTE = "data-skdx-field-control";
+/** Selector to find a Field's control, matching first in document order. */
+export declare const FIELD_CONTROL_SELECTOR: string;
+/** Marks a Field's required indicator for styling and assertion verification. */
+export declare const FIELD_REQUIRED_INDICATOR_ATTRIBUTE = "data-skdx-field-required-indicator";
+/** The public state of one Field, handed to the framework layer and to `validity-change` listeners. */
+export interface FieldSnapshot {
+    /** The id of the discovered control — the Label's `for`, and the error summary's link target. */
+    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 discovered control's live `ValidityState`, or `null` when none; compared by identity to detect swaps. */
+    validity: ValidityState | null;
+}
+/** The props the framework layer forwards into the controller on every render. */
+export interface FieldControllerProps {
+    /** See {@link FieldValidator}. */
+    validate?: FieldValidator | undefined;
+    /**
+     * When validation first runs; re-validates on input after any failure.
+     * @default 'blur'
+     */
+    mode?: FieldMode | undefined;
+    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    errors?: string | string[] | undefined;
+    /** 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 | undefined;
+    /**
+     * Whether an answer is mandatory, reflected as native `required` or `aria-required="true"`.
+     * @default undefined — not required.
+     */
+    required?: boolean | undefined;
+    /**
+     * Whether the field is unavailable, applied as native `disabled` or `aria-disabled="true"`.
+     * @default undefined — not disabled.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Formats the character-count message; negative `remaining` means over-limit.
+     * @default undefined — {@link characterCountMessage}'s English wording.
+     */
+    getCharacterCountMessage?: ((remaining: number) => string) | undefined;
+    /**
+     * Fallback message when native constraint validation fails without a message.
+     * @default undefined — 'This field is invalid.'
+     */
+    invalidMessage?: string | undefined;
+    /**
+     * Delay in milliseconds before `change` mode validates; `0` validates every keystroke.
+     * @default 0 — no debounce.
+     */
+    validationDebounceTime?: number | undefined;
+}
+/** 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 fieldsets where Label is legend and control uses aria-labelledby. */
+    grouped: boolean;
+    /** Called whenever the snapshot changes, so the framework layer can re-render. */
+    onSnapshotChange: (snapshot: FieldSnapshot) => void;
+    /** Announces messages to the live region with politeness picked per message. */
+    announce: (message: string, politeness: 'polite' | 'assertive') => void;
+}
+/** Coerces whatever a validator (or the `errors` prop) returned into a message list. */
+export declare function normalizeMessages(result: FieldValidationResult | string | string[]): string[];
+/** The first control inside `root` that belongs to *this* Field rather than to a nested one. */
+export declare function findFieldControl(root: Element): HTMLElement | null;
+/** Reads the current value from a control, checking checked state, value property, or hidden input. */
+export declare function readControlValue(control: HTMLElement | null): unknown;
+/** Whether a value counts as entered, for `data-filled`. */
+export declare function isFilled(value: unknown): boolean;
+/** 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;
+}
+/** Returns the form or skdx-form a summary should scan, falling back to its parent. */
+export declare function errorSummaryScope(root: Element): Element;
+/** Returns all currently-failing fields in scope, in document order. */
+export declare function collectFieldErrors(scope: ParentNode): FieldErrorEntry[];
+/** Runs all Fields in scope without short-circuiting, so all errors appear in ErrorSummary. */
+export declare function validateFields(scope: ParentNode): Promise<boolean>;
+/** Resets every Field's state when the form is reset, clearing messages and interaction flags. */
+export declare function resetFields(scope: ParentNode): void;
+/** Sends focus to a failing field, or to the first control inside a group. */
+export declare function focusFieldTarget(id: string, doc?: Document): void;
+/** Owns one Field's state machine, connected to its root element and re-synced on every render. */
+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;
+    /** The `aria-labelledby` the consumer put on the control themselves, preserved across rewrites. */
+    private baseLabelledBy;
+    /** Whether this controller wrote aria-labelledby; only we may withdraw it. */
+    private wroteLabelledBy;
+    /** Whether this controller wrote required/disabled; only we may withdraw them. */
+    private wroteRequired;
+    private wroteDisabled;
+    private wroteGroupDisabled;
+    /** 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;
+    /** Pending {@link FieldControllerProps.validationDebounceTime} run, cancelled by the next keystroke or a blur. */
+    private validationTimer;
+    /** Whether a submit is waiting on this Field's async validator to settle. */
+    private awaitingSubmit;
+    private snapshot;
+    constructor(options: FieldControllerOptions);
+    /** The current state. Read by the framework layer to render the parts. */
+    get state(): FieldSnapshot;
+    /** Replaces the forwarded props; safe to call on every render. */
+    setProps(props: FieldControllerProps): void;
+    /** Registers or clears the character count configuration. */
+    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;
+    /** Composes errors: server errors, validation results, then over-limit message. */
+    private composeErrors;
+    /** Announces the count politely one pause after the last keystroke, or assertively on over-limit. */
+    private scheduleCountAnnouncement;
+    /** Attaches the controller to its rendered root element. */
+    connect(root: HTMLElement): void;
+    /** Detaches every listener. */
+    disconnect(): void;
+    /** Re-discovers the control and re-applies injected attributes. */
+    sync(): void;
+    private applyDescribedBy;
+    private applyLabelledBy;
+    /** Sets required and disabled on control using native attributes or ARIA as appropriate. */
+    private applyConstraintState;
+    /** A group container needs its radios disabled individually; only undo what this controller set. */
+    private applyGroupDisabled;
+    /** Runs validation now, resolving to whether the field is valid. */
+    validate(): Promise<boolean>;
+    /** Resets the field to mount state and bumps the token to cancel any async validation run. */
+    reset(): void;
+    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    private markTouched;
+    private applyStateAttributes;
+    private resolveValue;
+    /** The discovered control's live `ValidityState`, when it has one. */
+    private readValidity;
+    /** Publishes (or withdraws) the "a validator is still running here" marker. */
+    private markPending;
+    private nativeMessage;
+    /** Runs validation, returning messages synchronously for sync validators. */
+    private runValidation;
+    private commit;
+    private update;
+    private readonly handleInput;
+    /** Runs validator with debounce in change mode, immediately in blur/submit mode. */
+    private scheduleValidation;
+    /** Whether this Field's form has an ErrorSummary; queried per submit since it renders conditionally. */
+    private hasErrorSummary;
+    private readonly handleFocusOut;
+    /** Whether this submit is the re-dispatch from {@link resubmitIfSettled}, which must not re-run validators. */
+    private isEngineResubmit;
+    private readonly handleSubmit;
+    /** Re-dispatches submit once all async validators have settled, avoiding loops via FIELD_RESUBMIT_ATTRIBUTE. */
+    private resubmitIfSettled;
+}

package/dist/internal/field-core.d.ts

@@ -0,0 +1,248 @@
+/** 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 to the root on validity changes. */
+export declare const FIELD_MESSAGE_ATTRIBUTE = "data-skdx-field-message";
+/** Marks a Field's description element, so its id can be added to the control's `aria-describedby`. */
+export declare const FIELD_DESCRIPTION_ATTRIBUTE = "data-skdx-field-description";
+/** 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";
+/** Marks a Field whose async validator is still running. */
+export declare const FIELD_PENDING_ATTRIBUTE = "data-skdx-field-pending";
+/** Marks the re-dispatched submit after async validators have settled. */
+export declare const FIELD_RESUBMIT_ATTRIBUTE = "data-skdx-field-resubmit";
+/** Marks a FormField root, allowing error summary to list both Field and FormField failures. */
+export declare const FORM_FIELD_ATTRIBUTE = "data-skdx-form-field";
+/** Marks a rendered FormMessage so the error summary shows the user's displayed message. */
+export declare const FORM_MESSAGE_ATTRIBUTE = "data-skdx-form-message";
+/** Events a Form ErrorSummary should re-scan on. */
+export declare const ERROR_SUMMARY_RESCAN_EVENTS: readonly ["validity-change", "invalid", "change", "blur"];
+/** Marks a Form's ErrorSummary so the engine knows whether to suppress the Field's own announcement. */
+export declare const FIELD_ERROR_SUMMARY_ATTRIBUTE = "data-skdx-error-summary";
+/** Delay in milliseconds before character count announces remaining count. */
+export declare const CHARACTER_COUNT_ANNOUNCE_DELAY_MS = 1000;
+/** What a Field's character count is configured with. */
+export interface FieldCharacterCountOptions {
+    /** The soft limit, not the native `maxlength` which truncates silently. */
+    maxLength: number;
+    /**
+     * Percentage of `maxLength` before the count appears; `0` shows it immediately.
+     * @default 0
+     */
+    threshold?: number | undefined;
+}
+/** Default count message; negative means over-limit. */
+export declare function characterCountMessage(remaining: number): string;
+/** Whether a count has passed its threshold and should be rendered/announced. */
+export declare function characterCountVisible(count: number, maxLength: number, threshold?: number): boolean;
+/** Fallback message when native constraint validation has no `validationMessage`. */
+export declare const NATIVE_INVALID_FALLBACK_MESSAGE = "This field is invalid.";
+/** Marks an element as this Field's control, an escape hatch for composites in shadow DOM. */
+export declare const FIELD_CONTROL_ATTRIBUTE = "data-skdx-field-control";
+/** Selector to find a Field's control, matching first in document order. */
+export declare const FIELD_CONTROL_SELECTOR: string;
+/** Marks a Field's required indicator for styling and assertion verification. */
+export declare const FIELD_REQUIRED_INDICATOR_ATTRIBUTE = "data-skdx-field-required-indicator";
+/** The public state of one Field, handed to the framework layer and to `validity-change` listeners. */
+export interface FieldSnapshot {
+    /** The id of the discovered control — the Label's `for`, and the error summary's link target. */
+    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 discovered control's live `ValidityState`, or `null` when none; compared by identity to detect swaps. */
+    validity: ValidityState | null;
+}
+/** The props the framework layer forwards into the controller on every render. */
+export interface FieldControllerProps {
+    /** See {@link FieldValidator}. */
+    validate?: FieldValidator | undefined;
+    /**
+     * When validation first runs; re-validates on input after any failure.
+     * @default 'blur'
+     */
+    mode?: FieldMode | undefined;
+    /** Server-injected errors, always shown, listed before anything `validate` produces. */
+    errors?: string | string[] | undefined;
+    /** 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 | undefined;
+    /**
+     * Whether an answer is mandatory, reflected as native `required` or `aria-required="true"`.
+     * @default undefined — not required.
+     */
+    required?: boolean | undefined;
+    /**
+     * Whether the field is unavailable, applied as native `disabled` or `aria-disabled="true"`.
+     * @default undefined — not disabled.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Formats the character-count message; negative `remaining` means over-limit.
+     * @default undefined — {@link characterCountMessage}'s English wording.
+     */
+    getCharacterCountMessage?: ((remaining: number) => string) | undefined;
+    /**
+     * Fallback message when native constraint validation fails without a message.
+     * @default undefined — 'This field is invalid.'
+     */
+    invalidMessage?: string | undefined;
+    /**
+     * Delay in milliseconds before `change` mode validates; `0` validates every keystroke.
+     * @default 0 — no debounce.
+     */
+    validationDebounceTime?: number | undefined;
+}
+/** 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 fieldsets where Label is legend and control uses aria-labelledby. */
+    grouped: boolean;
+    /** Called whenever the snapshot changes, so the framework layer can re-render. */
+    onSnapshotChange: (snapshot: FieldSnapshot) => void;
+    /** Announces messages to the live region with politeness picked per message. */
+    announce: (message: string, politeness: 'polite' | 'assertive') => void;
+}
+/** Coerces whatever a validator (or the `errors` prop) returned into a message list. */
+export declare function normalizeMessages(result: FieldValidationResult | string | string[]): string[];
+/** The first control inside `root` that belongs to *this* Field rather than to a nested one. */
+export declare function findFieldControl(root: Element): HTMLElement | null;
+/** Reads the current value from a control, checking checked state, value property, or hidden input. */
+export declare function readControlValue(control: HTMLElement | null): unknown;
+/** Whether a value counts as entered, for `data-filled`. */
+export declare function isFilled(value: unknown): boolean;
+/** 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;
+}
+/** Returns the form or skdx-form a summary should scan, falling back to its parent. */
+export declare function errorSummaryScope(root: Element): Element;
+/** Returns all currently-failing fields in scope, in document order. */
+export declare function collectFieldErrors(scope: ParentNode): FieldErrorEntry[];
+/** Runs all Fields in scope without short-circuiting, so all errors appear in ErrorSummary. */
+export declare function validateFields(scope: ParentNode): Promise<boolean>;
+/** Resets every Field's state when the form is reset, clearing messages and interaction flags. */
+export declare function resetFields(scope: ParentNode): void;
+/** Sends focus to a failing field, or to the first control inside a group. */
+export declare function focusFieldTarget(id: string, doc?: Document): void;
+/** Owns one Field's state machine, connected to its root element and re-synced on every render. */
+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;
+    /** The `aria-labelledby` the consumer put on the control themselves, preserved across rewrites. */
+    private baseLabelledBy;
+    /** Whether this controller wrote aria-labelledby; only we may withdraw it. */
+    private wroteLabelledBy;
+    /** Whether this controller wrote required/disabled; only we may withdraw them. */
+    private wroteRequired;
+    private wroteDisabled;
+    private wroteGroupDisabled;
+    /** 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;
+    /** Pending {@link FieldControllerProps.validationDebounceTime} run, cancelled by the next keystroke or a blur. */
+    private validationTimer;
+    /** Whether a submit is waiting on this Field's async validator to settle. */
+    private awaitingSubmit;
+    private snapshot;
+    constructor(options: FieldControllerOptions);
+    /** The current state. Read by the framework layer to render the parts. */
+    get state(): FieldSnapshot;
+    /** Replaces the forwarded props; safe to call on every render. */
+    setProps(props: FieldControllerProps): void;
+    /** Registers or clears the character count configuration. */
+    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;
+    /** Composes errors: server errors, validation results, then over-limit message. */
+    private composeErrors;
+    /** Announces the count politely one pause after the last keystroke, or assertively on over-limit. */
+    private scheduleCountAnnouncement;
+    /** Attaches the controller to its rendered root element. */
+    connect(root: HTMLElement): void;
+    /** Detaches every listener. */
+    disconnect(): void;
+    /** Re-discovers the control and re-applies injected attributes. */
+    sync(): void;
+    private applyDescribedBy;
+    private applyLabelledBy;
+    /** Sets required and disabled on control using native attributes or ARIA as appropriate. */
+    private applyConstraintState;
+    /** A group container needs its radios disabled individually; only undo what this controller set. */
+    private applyGroupDisabled;
+    /** Runs validation now, resolving to whether the field is valid. */
+    validate(): Promise<boolean>;
+    /** Resets the field to mount state and bumps the token to cancel any async validation run. */
+    reset(): void;
+    /** Marks the field touched without validating (used by a submit pass before it validates). */
+    private markTouched;
+    private applyStateAttributes;
+    private resolveValue;
+    /** The discovered control's live `ValidityState`, when it has one. */
+    private readValidity;
+    /** Publishes (or withdraws) the "a validator is still running here" marker. */
+    private markPending;
+    private nativeMessage;
+    /** Runs validation, returning messages synchronously for sync validators. */
+    private runValidation;
+    private commit;
+    private update;
+    private readonly handleInput;
+    /** Runs validator with debounce in change mode, immediately in blur/submit mode. */
+    private scheduleValidation;
+    /** Whether this Field's form has an ErrorSummary; queried per submit since it renders conditionally. */
+    private hasErrorSummary;
+    private readonly handleFocusOut;
+    /** Whether this submit is the re-dispatch from {@link resubmitIfSettled}, which must not re-run validators. */
+    private isEngineResubmit;
+    private readonly handleSubmit;
+    /** Re-dispatches submit once all async validators have settled, avoiding loops via FIELD_RESUBMIT_ATTRIBUTE. */
+    private resubmitIfSettled;
+}

package/dist/internal/field-core.js

@@ -0,0 +1 @@
+var C="validity-change",a="data-skdx-field",u="data-skdx-field-name",p="data-skdx-field-message",F="data-skdx-field-description",I="data-skdx-field-error",$="data-skdx-field-character-count",E="data-skdx-field-pending",c="data-skdx-field-resubmit",m="data-skdx-form-field",_="data-skdx-form-message",G=["validity-change","invalid","change","blur"],D="data-skdx-error-summary",j=1e3;function M(i){let e=Math.abs(i),t=e===1?"character":"characters";return i<0?`You have ${e} ${t} too many`:`You have ${e} ${t} remaining`}function V(i,e,t=0){return t<=0?!0:i>=e*t/100}var O="This field is invalid.",w="data-skdx-field-control",x=[`[${w}]`,'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(", "),Y="data-skdx-field-required-indicator",k=new Set(["INPUT","SELECT","TEXTAREA"]),R=new Set(["radiogroup","group"]),B=['input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])","button:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function T(i){return i==null?[]:(Array.isArray(i)?i:[i]).filter(t=>typeof t=="string"&&t.trim()!=="")}function S(i){for(let e of Array.from(i.querySelectorAll(x)))if(e.getAttribute("aria-hidden")!=="true"&&e.closest(`[${a}]`)===i)return e;return null}function f(i,e){return v(i,a,e)}function v(i,e,t){for(let r of Array.from(i.querySelectorAll(t)))if(r.closest(`[${e}]`)===i)return r;return null}function P(i){if(!i)return;let e=i;return e.type==="checkbox"||e.type==="radio"?e.checked:"value"in i?e.value:i.querySelector('input[aria-hidden="true"]')?.value}function d(i){return i==null||i===!1||i===""?!1:!(Array.isArray(i)&&i.length===0)}function o(i,e,t){t?i.setAttribute(e,""):i.removeAttribute(e)}function y(i,...e){let t=i.split(/\s+/).filter(Boolean);for(let r of e)r&&!t.includes(r)&&t.push(r);return t.join(" ")}function z(i){return i.closest("form, skdx-form")??i.parentElement??i}function N(i){let e=S(i),r=f(i,`[${I}]`)?.textContent?.trim()||i.getAttribute(p)||i.getAttribute(u)||"";return!e?.id||!r?[]:[{id:e.id,message:r}]}function H(i){let e=v(i,m,x);if(!e?.id||e.getAttribute("aria-invalid")!=="true")return[];let r=v(i,m,`[${_}]:not([hidden])`)?.textContent?.trim()||i.getAttribute(u)||"";return r?[{id:e.id,message:r}]:[]}function K(i){return Array.from(i.querySelectorAll(`[${a}][data-invalid], [${m}]`)).flatMap(t=>(t.hasAttribute(a)?N:H)(t))}var b="__skdxFieldCheckValidity",g="__skdxFieldReset";async function Q(i){let e=Array.from(i.querySelectorAll(`[${a}]`));return(await Promise.all(e.map(r=>r[b]?.()??Promise.resolve(!0)))).every(Boolean)}function X(i){for(let e of Array.from(i.querySelectorAll(`[${a}]`)))e[g]?.()}function J(i,e=document){let t=e.getElementById(i);if(!t)return;let r=t.getAttribute("role"),s=(t.tagName==="FIELDSET"||r!==null&&R.has(r)?t.querySelector(B):null)??t;s.focus(),s.scrollIntoView?.({block:"center"})}var A=class{constructor(e){this.options=e;this.props={};this.root=null;this.form=null;this.control=null;this.baseDescribedBy="";this.baseLabelledBy="";this.wroteLabelledBy=!1;this.wroteRequired=!1;this.wroteDisabled=!1;this.wroteGroupDisabled=!1;this.runToken=0;this.pending=!1;this.injected=[];this.custom=[];this.characterCount=null;this.awaitingSubmit=!1;this.handleInput=()=>{let e=this.isOverLimit(this.snapshot.count),t=this.readCount();this.update({dirty:!0,filled:d(this.resolveValue()),count:t,errors:this.composeErrors(t)}),this.scheduleCountAnnouncement(t,e),(this.props.mode==="change"||this.snapshot.errors.length>0)&&this.scheduleValidation()};this.handleFocusOut=()=>{let e=this.readCount();this.update({touched:!0,filled:d(this.resolveValue()),count:e,errors:this.composeErrors(e)});let t=this.validationTimer!==void 0;clearTimeout(this.validationTimer),this.validationTimer=void 0;let r=this.props.mode??"blur";(t||r==="blur"||this.snapshot.errors.length>0)&&this.runValidation()};this.handleSubmit=e=>{if(!this.form)return;let t=e.target;if(t!==this.form&&t?.closest?.("form")!==this.form||this.isEngineResubmit(e))return;this.markTouched();let r=this.runValidation({silent:this.hasErrorSummary()});if(L(r)){e.preventDefault(),this.awaitingSubmit=!0,Promise.resolve(r).then(()=>{this.awaitingSubmit&&(this.awaitingSubmit=!1,this.resubmitIfSettled())});return}(r.length>0||this.pending)&&e.preventDefault()};this.snapshot={controlId:"",errors:[],valid:!0,touched:!1,dirty:!1,filled:!1,count:0,validity:null}}get state(){return this.snapshot}setProps(e){let t=this.props.value;this.props=e;let r=T(e.errors??null),n=!q(this.injected,r);n&&(this.injected=r);let s=e.value!==t;if(!n&&!s)return;let l=this.readCount();this.update({count:l,filled:d(this.resolveValue()),errors:this.composeErrors(l)})}setCharacterCount(e){if((this.characterCount?.maxLength??null)===(e?.maxLength??null)&&(this.characterCount?.threshold??0)===(e?.threshold??0))return;this.characterCount=e;let r=this.readCount();this.update({count:r,errors:this.composeErrors(r)})}readCount(){let e=this.resolveValue();return typeof e=="string"?e.length:0}countMessage(e){return(this.props.getCharacterCountMessage??M)(e)}isOverLimit(e){return this.characterCount!==null&&e>this.characterCount.maxLength}composeErrors(e=this.snapshot.count){let t=[...this.injected,...this.custom];return this.characterCount&&this.isOverLimit(e)&&t.push(this.countMessage(this.characterCount.maxLength-e)),t}scheduleCountAnnouncement(e,t){let r=this.characterCount;if(!r)return;if(clearTimeout(this.announceTimer),this.isOverLimit(e)){t||this.options.announce(this.countMessage(r.maxLength-e),"assertive");return}if(!V(e,r.maxLength,r.threshold))return;let n=r.maxLength-e;this.announceTimer=setTimeout(()=>{this.options.announce(this.countMessage(n),"polite")},1e3)}connect(e){this.root=e,e.setAttribute(a,""),Object.defineProperty(e,b,{value:()=>this.validate(),configurable:!0,enumerable:!1,writable:!0}),Object.defineProperty(e,g,{value:()=>this.reset(),configurable:!0,enumerable:!1,writable:!0}),e.addEventListener("input",this.handleInput,!0),e.addEventListener("change",this.handleInput,!0),e.addEventListener("focusout",this.handleFocusOut,!0),this.form=e.closest("form"),this.form&&e.ownerDocument.addEventListener("submit",this.handleSubmit,!0),this.sync();let t=this.readCount();this.update({filled:d(this.resolveValue()),count:t,errors:this.composeErrors(t)})}disconnect(){clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.awaitingSubmit=!1;let e=this.root;e&&(e.removeEventListener("input",this.handleInput,!0),e.removeEventListener("change",this.handleInput,!0),e.removeEventListener("focusout",this.handleFocusOut,!0),this.form&&e.ownerDocument.removeEventListener("submit",this.handleSubmit,!0),delete e[b],delete e[g],this.root=null,this.form=null,this.control=null)}sync(){let e=this.root;if(!e)return;let t=S(e);t!==this.control&&(this.control=t,this.baseDescribedBy=t?.getAttribute("aria-describedby")??"",this.baseLabelledBy=t?.getAttribute("aria-labelledby")??"",this.wroteLabelledBy=!1,this.wroteRequired=!1,this.wroteDisabled=!1,this.wroteGroupDisabled=!1);let{name:r}=this.props;r?e.setAttribute(u,r):e.removeAttribute(u);let n=this.snapshot.errors.join(" ");n?e.setAttribute(p,n):e.removeAttribute(p),this.applyStateAttributes(e),t&&(t.id||(t.id=this.options.controlId),t.id!==this.snapshot.controlId&&(this.snapshot={...this.snapshot,controlId:t.id,validity:this.readValidity()},this.options.onSnapshotChange(this.snapshot)),this.applyDescribedBy(e,t),this.snapshot.errors.length>0?t.setAttribute("aria-invalid","true"):t.removeAttribute("aria-invalid"),this.applyLabelledBy(e,t),this.applyConstraintState(t),this.applyStateAttributes(t))}applyDescribedBy(e,t){let r=f(e,`[${F}]`)!==null,n=f(e,`[${I}]`)!==null,s=y(this.baseDescribedBy,r?this.options.descriptionId:void 0,n?this.options.errorId:void 0);s?t.setAttribute("aria-describedby",s):t.removeAttribute("aria-describedby")}applyLabelledBy(e,t){let r=e.ownerDocument.getElementById(this.options.labelId)!==null;this.options.grouped&&r?(t.setAttribute("aria-labelledby",y(this.baseLabelledBy,this.options.labelId)),this.wroteLabelledBy=!0):this.wroteLabelledBy&&(this.baseLabelledBy?t.setAttribute("aria-labelledby",this.baseLabelledBy):t.removeAttribute("aria-labelledby"),this.wroteLabelledBy=!1)}applyConstraintState(e){let t=k.has(e.tagName),r=this.props.required===!0,n=this.props.disabled===!0;r?(t?e.setAttribute("required",""):e.setAttribute("aria-required","true"),this.wroteRequired=!0):this.wroteRequired&&(e.removeAttribute(t?"required":"aria-required"),this.wroteRequired=!1),n?(t?e.setAttribute("disabled",""):e.setAttribute("aria-disabled","true"),this.wroteDisabled=!0):this.wroteDisabled&&(e.removeAttribute(t?"disabled":"aria-disabled"),this.wroteDisabled=!1),t||this.applyGroupDisabled(e,n)}applyGroupDisabled(e,t){let r=e.getAttribute("role");if(!(!(e.tagName==="FIELDSET"||r!==null&&R.has(r))||!t&&!this.wroteGroupDisabled)){for(let s of e.querySelectorAll("input, select, textarea, button"))t?s.setAttribute("disabled",""):s.removeAttribute("disabled");this.wroteGroupDisabled=t}}validate(){return Promise.resolve(this.runValidation()).then(e=>e.length===0)}reset(){this.injected=[],this.custom=[],this.pending=!1,this.awaitingSubmit=!1,this.runToken++,clearTimeout(this.announceTimer),clearTimeout(this.validationTimer),this.validationTimer=void 0,this.markPending(!1);let e=this.readCount();this.update({touched:!1,dirty:!1,count:e,filled:d(this.resolveValue()),errors:this.composeErrors(e)}),this.sync()}markTouched(){this.snapshot.touched||this.update({touched:!0})}applyStateAttributes(e){let{errors:t,touched:r,dirty:n,filled:s,count:l}=this.snapshot;o(e,"data-invalid",t.length>0),o(e,"data-valid",t.length===0),o(e,"data-touched",r),o(e,"data-dirty",n),o(e,"data-filled",s),o(e,"data-over-limit",this.isOverLimit(l)),o(e,"data-disabled",this.props.disabled===!0)}resolveValue(){return this.props.value!==void 0?this.props.value:P(this.control)}readValidity(){return this.control?.validity??null}markPending(e){this.root&&o(this.root,E,e)}nativeMessage(){let e=this.control;return!e?.validity||e.validity.valid?null:e.validationMessage||this.props.invalidMessage||O}runValidation(e={}){let t=++this.runToken,r=this.props.validate?.(this.resolveValue());return L(r)?(this.pending=!0,this.markPending(!0),Promise.resolve(r).then(n=>t!==this.runToken?this.snapshot.errors:(this.pending=!1,this.markPending(!1),this.commit(n,e)))):this.commit(r,e)}commit(e,t){if(this.custom=T(e),this.custom.length===0){let h=this.nativeMessage();h&&!this.injected.includes(h)&&(this.custom=[h])}let r=this.readCount(),n=this.composeErrors(r),s=this.snapshot.errors.length===0;this.update({errors:n,count:r,filled:d(this.resolveValue())});let l=n[0];return l&&s&&!t.silent&&this.options.announce(l,"assertive"),n}update(e){let t={...this.snapshot,...e,valid:!0,validity:this.readValidity()};t.valid=t.errors.length===0,!U(this.snapshot,t)&&(this.snapshot=t,this.sync(),this.options.onSnapshotChange(t),this.root?.dispatchEvent(new CustomEvent(C,{bubbles:!0,composed:!0,detail:{valid:t.valid,errors:t.errors,touched:t.touched,dirty:t.dirty,filled:t.filled,count:t.count,validity:t.validity}})))}scheduleValidation(){clearTimeout(this.validationTimer),this.validationTimer=void 0;let e=this.props.mode==="change"?this.props.validationDebounceTime??0:0;if(e<=0){this.runValidation();return}this.validationTimer=setTimeout(()=>{this.validationTimer=void 0,this.runValidation()},e)}hasErrorSummary(){return this.form?.querySelector(`[${D}]`)!=null}isEngineResubmit(e){return this.form?.hasAttribute(c)?(this.snapshot.errors.length>0&&e.preventDefault(),!0):!1}resubmitIfSettled(){let e=this.form;if(!(!e||typeof e.requestSubmit!="function")&&!e.querySelector(`[${E}]`)&&!e.querySelector(`[${a}][data-invalid]`)){e.setAttribute(c,"");try{e.requestSubmit()}finally{e.removeAttribute(c)}}}};function L(i){return typeof i?.then=="function"}function q(i,e){return i.length===e.length&&i.every((t,r)=>t===e[r])}function U(i,e){return i.controlId===e.controlId&&i.valid===e.valid&&i.touched===e.touched&&i.dirty===e.dirty&&i.filled===e.filled&&i.count===e.count&&i.validity===e.validity&&i.errors.length===e.errors.length&&i.errors.every((t,r)=>t===e.errors[r])}export{j as CHARACTER_COUNT_ANNOUNCE_DELAY_MS,G as ERROR_SUMMARY_RESCAN_EVENTS,$ as FIELD_CHARACTER_COUNT_ATTRIBUTE,w as FIELD_CONTROL_ATTRIBUTE,x as FIELD_CONTROL_SELECTOR,F as FIELD_DESCRIPTION_ATTRIBUTE,I as FIELD_ERROR_ATTRIBUTE,D as FIELD_ERROR_SUMMARY_ATTRIBUTE,p as FIELD_MESSAGE_ATTRIBUTE,u as FIELD_NAME_ATTRIBUTE,E as FIELD_PENDING_ATTRIBUTE,Y as FIELD_REQUIRED_INDICATOR_ATTRIBUTE,c as FIELD_RESUBMIT_ATTRIBUTE,a as FIELD_ROOT_ATTRIBUTE,C as FIELD_VALIDITY_CHANGE_EVENT,m as FORM_FIELD_ATTRIBUTE,_ as FORM_MESSAGE_ATTRIBUTE,A as FieldController,O as NATIVE_INVALID_FALLBACK_MESSAGE,M as characterCountMessage,V as characterCountVisible,K as collectFieldErrors,z as errorSummaryScope,S as findFieldControl,J as focusFieldTarget,d as isFilled,T as normalizeMessages,P as readControlValue,X as resetFields,Q as validateFields};

package/dist/internal/focus-targets.cjs

@@ -0,0 +1 @@
+"use strict";var u=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var n in t)u(e,n,{get:t[n],enumerable:!0})},T=(e,t,n,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of F(t))!g.call(e,r)&&r!==n&&u(e,r,{get:()=>t[r],enumerable:!(o=m(t,r))||o.enumerable});return e};var h=e=>T(u({},"__esModule",{value:!0}),e);var M={};p(M,{applyFinalFocus:()=>d,applyInitialFocus:()=>f,applyOpenAutoFocus:()=>y,initialFocusTarget:()=>L,resolveFocusSelector:()=>a,returnFocus:()=>H});module.exports=h(M);var i=require("./dismissal.cjs"),c=require("./tabbable.cjs"),E={Dialog:"the Cancel button when present, then the first tabbable element, then the panel itself",Drawer:"the first tabbable element, then the panel itself",Popover:"the first tabbable element, then the panel itself"},b={Dialog:"[data-skdx-dialog-cancel]"},v={Dialog:"the dialog panel",Drawer:"the drawer panel",Popover:"the popover panel"};function a(e,t,n,o){if(!t)return null;let r;try{r=e.querySelector(t)}catch{return console.warn(`[skdx] ${o}: ${n}="${t}" is not a valid CSS selector. Falling back to the default focus target.`),null}return r||console.warn(n==="initialFocus"?`[skdx] ${o}: initialFocus="${t}" matched no element inside ${v[o]}. Falling back to ${E[o]}.`:`[skdx] ${o}: finalFocus="${t}" matched no element in the document. Falling back to the element that was focused before it opened.`),r}function s(e,t){let n=b[t];return n?e.querySelector(n):null}function L(e,t,n){return a(e,t,"initialFocus",n)??s(e,n)??e.querySelector(c.TABBABLE_SELECTOR)??e}function f(e,t,n){let o=a(e,t,"initialFocus",n)??s(e,n);if(o){o.focus({preventScroll:!0});return}if(e.contains(document.activeElement))return;let l=e.querySelector(c.TABBABLE_SELECTOR)??e;l===e&&e.tabIndex<0&&(e.tabIndex=-1),l.focus?.({preventScroll:!0})}function d(e,t){let n=a(document,e,"finalFocus",t);return n?(n.focus({preventScroll:!0}),!0):!1}function y(e,t,n,o,r){let l=document.activeElement;return(0,i.autoFocusEvent)("open-auto-focus",o)?(f(e,t,n),!0):(document.activeElement===l&&r?.isConnected&&e.contains(l)&&r.focus({preventScroll:!0}),!1)}function H(e,t,n,o){return(0,i.autoFocusEvent)("close-auto-focus",o)?d(e,t)?!0:!n?.isConnected||n===document.body||n===document.documentElement?!1:(n.focus({preventScroll:!0}),!0):!1}0&&(module.exports={applyFinalFocus,applyInitialFocus,applyOpenAutoFocus,initialFocusTarget,resolveFocusSelector,returnFocus});