@skdx/react 0.28.0 → 0.30.0

package/dist/{field/fieldCore.d.ts → utils/field-core.d.ts}

@@ -1,4 +1,3 @@
-/** Framework-free validation engine used by all five framework packages. */
 /** When a Field first runs its validator. See {@link FieldControllerProps.mode}. */
 export type FieldMode = 'change' | 'blur' | 'submit';
 /** What a validator may return: one message, several, or nothing when the value is acceptable. */
@@ -41,7 +40,7 @@ export interface FieldCharacterCountOptions {
      * Percentage of `maxLength` before the count appears; `0` shows it immediately.
      * @default 0
      */
-    threshold?: number;
+    threshold?: number | undefined;
 }
 /** Default count message; negative means over-limit. */
 export declare function characterCountMessage(remaining: number): string;
@@ -71,52 +70,49 @@ export interface FieldSnapshot {
     filled: boolean;
     /** Length of the control's value, tracked only while a character count is configured. */
     count: number;
-    /**
-     * The discovered control's live `ValidityState`, or `null` if none (role elements, no control).
-     * The control's own object, not a copy; compared by identity to detect control swaps.
-     */
+    /** 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;
+    validate?: FieldValidator | undefined;
     /**
      * When validation first runs; re-validates on input after any failure.
      * @default 'blur'
      */
-    mode?: FieldMode;
+    mode?: FieldMode | undefined;
     /** Server-injected errors, always shown, listed before anything `validate` produces. */
-    errors?: string | string[];
+    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;
+    name?: string | undefined;
     /**
      * Whether an answer is mandatory, reflected as native `required` or `aria-required="true"`.
      * @default undefined — not required.
      */
-    required?: boolean;
+    required?: boolean | undefined;
     /**
      * Whether the field is unavailable, applied as native `disabled` or `aria-disabled="true"`.
      * @default undefined — not disabled.
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Formats the character-count message; negative `remaining` means over-limit.
      * @default undefined — {@link characterCountMessage}'s English wording.
      */
-    getCharacterCountMessage?: (remaining: number) => string;
+    getCharacterCountMessage?: ((remaining: number) => string) | undefined;
     /**
      * Fallback message when native constraint validation fails without a message.
      * @default undefined — 'This field is invalid.'
      */
-    invalidMessage?: string;
+    invalidMessage?: string | undefined;
     /**
      * Delay in milliseconds before `change` mode validates; `0` validates every keystroke.
      * @default 0 — no debounce.
      */
-    validationDebounceTime?: number;
+    validationDebounceTime?: number | undefined;
 }
 /** Everything the controller needs that the framework layer owns. */
 export interface FieldControllerOptions {
@@ -160,10 +156,7 @@ export declare function validateFields(scope: ParentNode): Promise<boolean>;
 export declare function resetFields(scope: ParentNode): void;
 /** Sends focus to a failing field, or to the first control inside a group. */
 export declare function focusFieldTarget(id: string, doc?: Document): void;
-/**
- * Owns one Field's state machine. Created by the framework layer, given the
- * Field's root element on `connect()`, and told about re-renders via `sync()`.
- */
+/** 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;
@@ -179,10 +172,11 @@ export declare class FieldController {
     /** 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. */
+    /** Messages from the `errors` prop, always listed first. */
     private injected;
     /** Messages from the last `validate` run, or the native constraint-validation fallback. */
     private custom;
@@ -197,7 +191,7 @@ export declare class FieldController {
     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. */
+    /** 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;
@@ -217,11 +211,15 @@ export declare class FieldController {
     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 field to mount state: no messages, not touched/dirty/pending. Bumps token to cancel async runs. */
+    /** 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;
@@ -239,16 +237,10 @@ export declare class FieldController {
     private readonly handleInput;
     /** Runs validator with debounce in change mode, immediately in blur/submit mode. */
     private scheduleValidation;
-    /**
-     * Whether this Field's form has an ErrorSummary. Queried per submit (not cached)
-     * since the summary is conditionally rendered.
-     */
+    /** Whether this Field's form has an ErrorSummary; queried per submit since it renders conditionally. */
     private hasErrorSummary;
     private readonly handleFocusOut;
-    /**
-     * Whether this is the re-dispatch from {@link resubmitIfSettled}. Re-running
-     * validators here would block the original submit.
-     */
+    /** 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. */

package/dist/utils/field-core.js

@@ -0,0 +1,2 @@
+'use client';
+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/utils/focus-targets.cjs

@@ -0,0 +1,2 @@
+'use client';
+"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});

package/dist/utils/focus-targets.d.cts

@@ -0,0 +1,77 @@
+import { type AutoFocusEvent } from './dismissal.cjs';
+/**
+ * Resolution of initialFocus/finalFocus selectors for overlay families
+ * (Dialog, Drawer, Popover). Uses CSS selector strings (not
+ * element handles) so members survive as attributes on `<skdx-*-content>` —
+ * a DOM node cannot cross HTML attribute boundaries.
+ *
+ * A miss falls back to the overlay's automatic target (the whole point).
+ * Wrong selectors warn on console even in production (a selector pointing at
+ * nothing is a defect regardless).
+ * @internal
+ */
+export type FocusTargetFamily = 'Dialog' | 'Drawer' | 'Popover';
+/**
+ * Resolves one focus-target selector against `root`, or returns `null` and
+ * warns when it names nothing.
+ *
+ * @param root Content for `initialFocus` (the target is part of the panel by
+ * definition, and a loose selector must not reach into the page behind it), the
+ * document for `finalFocus` (whose target is outside Content by definition).
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus', family: FocusTargetFamily): HTMLElement | null;
+/**
+ * Element initial focus should land on inside content: the selector's match or
+ * the default (a Cancel part when present, then first tabbable, then panel).
+ * @internal
+ */
+export declare function initialFocusTarget(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): HTMLElement;
+/**
+ * Places initial focus for a native `<dialog>` after `showModal()`: the selector's match, then the family's own
+ * default target, else — unless the platform already focused inside the panel — the first tabbable, then the panel itself.
+ * @internal
+ */
+export declare function applyInitialFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): void;
+/**
+ * Sends focus where finalFocus names, resolved at document level (panel is
+ * closing and the opening element may be gone). Returns whether focus was placed.
+ * @internal
+ */
+export declare function applyFinalFocus(selector: string | undefined, family: FocusTargetFamily): boolean;
+/**
+ * The open-time focus move under its veto: `open-auto-focus` fires *before*
+ * anything moves, so a consumer preventing it keeps focus where the user left
+ * it. A native `<dialog>` is the exception — `showModal()` has already moved
+ * focus into the panel by the time any handler can run, so a veto has to put it
+ * back rather than merely decline to move it. A veto that places focus itself is the
+ * documented way to take initial focus over, so that undo only runs when the handler
+ * left focus where the platform put it.
+ *
+ * @param content the overlay panel
+ * @param selector the `initialFocus` selector, or `undefined` for the default chain
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param handler the consumer's `open-auto-focus` handler
+ * @param previouslyFocused what had focus before the platform moved it, for the undo
+ * @returns whether focus was placed inside the panel
+ * @internal
+ */
+export declare function applyOpenAutoFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily, handler?: (event: AutoFocusEvent) => void, previouslyFocused?: HTMLElement | null): boolean;
+/**
+ * The close-time focus return, run on every close route (Escape, outside press,
+ * the close button, a controlled `open` flipping) so focus never strands on a
+ * panel that is going away. `close-auto-focus` fires *before* the move, and a
+ * veto leaves focus alone; otherwise `finalFocus` wins, and the element that
+ * opened the overlay is the fallback — skipped when it has left the document,
+ * since focusing a detached node silently drops focus onto `<body>`, and skipped
+ * when it *is* `<body>` or `<html>`, which means nothing was focused when the
+ * overlay opened rather than that the page root should take focus.
+ *
+ * @param selector the `finalFocus` selector, or `undefined` to go straight to the opener
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param opener the element focused before the overlay opened
+ * @param handler the consumer's `close-auto-focus` handler
+ * @returns whether focus was placed
+ * @internal
+ */
+export declare function returnFocus(selector: string | undefined, family: FocusTargetFamily, opener: HTMLElement | null | undefined, handler?: (event: AutoFocusEvent) => void): boolean;

package/dist/utils/focus-targets.d.ts

@@ -0,0 +1,77 @@
+import { type AutoFocusEvent } from './dismissal.js';
+/**
+ * Resolution of initialFocus/finalFocus selectors for overlay families
+ * (Dialog, Drawer, Popover). Uses CSS selector strings (not
+ * element handles) so members survive as attributes on `<skdx-*-content>` —
+ * a DOM node cannot cross HTML attribute boundaries.
+ *
+ * A miss falls back to the overlay's automatic target (the whole point).
+ * Wrong selectors warn on console even in production (a selector pointing at
+ * nothing is a defect regardless).
+ * @internal
+ */
+export type FocusTargetFamily = 'Dialog' | 'Drawer' | 'Popover';
+/**
+ * Resolves one focus-target selector against `root`, or returns `null` and
+ * warns when it names nothing.
+ *
+ * @param root Content for `initialFocus` (the target is part of the panel by
+ * definition, and a loose selector must not reach into the page behind it), the
+ * document for `finalFocus` (whose target is outside Content by definition).
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus', family: FocusTargetFamily): HTMLElement | null;
+/**
+ * Element initial focus should land on inside content: the selector's match or
+ * the default (a Cancel part when present, then first tabbable, then panel).
+ * @internal
+ */
+export declare function initialFocusTarget(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): HTMLElement;
+/**
+ * Places initial focus for a native `<dialog>` after `showModal()`: the selector's match, then the family's own
+ * default target, else — unless the platform already focused inside the panel — the first tabbable, then the panel itself.
+ * @internal
+ */
+export declare function applyInitialFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): void;
+/**
+ * Sends focus where finalFocus names, resolved at document level (panel is
+ * closing and the opening element may be gone). Returns whether focus was placed.
+ * @internal
+ */
+export declare function applyFinalFocus(selector: string | undefined, family: FocusTargetFamily): boolean;
+/**
+ * The open-time focus move under its veto: `open-auto-focus` fires *before*
+ * anything moves, so a consumer preventing it keeps focus where the user left
+ * it. A native `<dialog>` is the exception — `showModal()` has already moved
+ * focus into the panel by the time any handler can run, so a veto has to put it
+ * back rather than merely decline to move it. A veto that places focus itself is the
+ * documented way to take initial focus over, so that undo only runs when the handler
+ * left focus where the platform put it.
+ *
+ * @param content the overlay panel
+ * @param selector the `initialFocus` selector, or `undefined` for the default chain
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param handler the consumer's `open-auto-focus` handler
+ * @param previouslyFocused what had focus before the platform moved it, for the undo
+ * @returns whether focus was placed inside the panel
+ * @internal
+ */
+export declare function applyOpenAutoFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily, handler?: (event: AutoFocusEvent) => void, previouslyFocused?: HTMLElement | null): boolean;
+/**
+ * The close-time focus return, run on every close route (Escape, outside press,
+ * the close button, a controlled `open` flipping) so focus never strands on a
+ * panel that is going away. `close-auto-focus` fires *before* the move, and a
+ * veto leaves focus alone; otherwise `finalFocus` wins, and the element that
+ * opened the overlay is the fallback — skipped when it has left the document,
+ * since focusing a detached node silently drops focus onto `<body>`, and skipped
+ * when it *is* `<body>` or `<html>`, which means nothing was focused when the
+ * overlay opened rather than that the page root should take focus.
+ *
+ * @param selector the `finalFocus` selector, or `undefined` to go straight to the opener
+ * @param family which overlay family, for the console warning a missed selector prints
+ * @param opener the element focused before the overlay opened
+ * @param handler the consumer's `close-auto-focus` handler
+ * @returns whether focus was placed
+ * @internal
+ */
+export declare function returnFocus(selector: string | undefined, family: FocusTargetFamily, opener: HTMLElement | null | undefined, handler?: (event: AutoFocusEvent) => void): boolean;

package/dist/utils/focus-targets.js

@@ -0,0 +1,2 @@
+'use client';
+import{autoFocusEvent as u}from"./dismissal.js";import{TABBABLE_SELECTOR as i}from"./tabbable.js";var s={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"},f={Dialog:"[data-skdx-dialog-cancel]"},d={Dialog:"the dialog panel",Drawer:"the drawer panel",Popover:"the popover panel"};function a(e,n,t,o){if(!n)return null;let r;try{r=e.querySelector(n)}catch{return console.warn(`[skdx] ${o}: ${t}="${n}" is not a valid CSS selector. Falling back to the default focus target.`),null}return r||console.warn(t==="initialFocus"?`[skdx] ${o}: initialFocus="${n}" matched no element inside ${d[o]}. Falling back to ${s[o]}.`:`[skdx] ${o}: finalFocus="${n}" matched no element in the document. Falling back to the element that was focused before it opened.`),r}function c(e,n){let t=f[n];return t?e.querySelector(t):null}function T(e,n,t){return a(e,n,"initialFocus",t)??c(e,t)??e.querySelector(i)??e}function m(e,n,t){let o=a(e,n,"initialFocus",t)??c(e,t);if(o){o.focus({preventScroll:!0});return}if(e.contains(document.activeElement))return;let l=e.querySelector(i)??e;l===e&&e.tabIndex<0&&(e.tabIndex=-1),l.focus?.({preventScroll:!0})}function F(e,n){let t=a(document,e,"finalFocus",n);return t?(t.focus({preventScroll:!0}),!0):!1}function h(e,n,t,o,r){let l=document.activeElement;return u("open-auto-focus",o)?(m(e,n,t),!0):(document.activeElement===l&&r?.isConnected&&e.contains(l)&&r.focus({preventScroll:!0}),!1)}function E(e,n,t,o){return u("close-auto-focus",o)?F(e,n)?!0:!t?.isConnected||t===document.body||t===document.documentElement?!1:(t.focus({preventScroll:!0}),!0):!1}export{F as applyFinalFocus,m as applyInitialFocus,h as applyOpenAutoFocus,T as initialFocusTarget,a as resolveFocusSelector,E as returnFocus};

package/dist/utils/formControl.cjs

@@ -1 +1,2 @@
-"use strict";var u=Object.create;var l=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var V=Object.getPrototypeOf,f=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var i in t)l(e,i,{get:t[i],enumerable:!0})},c=(e,t,i,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of m(t))!f.call(e,r)&&r!==i&&l(e,r,{get:()=>t[r],enumerable:!(a=y(t,r))||a.enumerable});return e};var R=(e,t,i)=>(i=e!=null?u(V(e)):{},c(t||!e||!e.__esModule?l(i,"default",{value:e,enumerable:!0}):i,e)),v=e=>c(l({},"__esModule",{value:!0}),e);var F={};p(F,{formValidityHandle:()=>s,formValidityStateView:()=>g,useFormReset:()=>H,useFormValidityHandle:()=>b});module.exports=v(F);var o=R(require("react"),1),d=require("./useCallbackRef.cjs");function s(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0,setCustomValidity:t=>e.current?.setCustomValidity(t)}}function g(e){return{get validity(){return e.current?.validity??null},get validationMessage(){return e.current?.validationMessage??""}}}function b(e,t,i,a){o.useImperativeHandle(e,()=>{let r=s(i),n=t.current?Object.assign(t.current,r):r;return a&&Object.defineProperties(n,Object.getOwnPropertyDescriptors(a)),n})}function H(e,t,i){let a=(0,d.useCallbackRef)(t);o.useEffect(()=>{let r=e.current,n=i?(r?.ownerDocument??document).getElementById(i):r?.closest("form")??null;if(n instanceof HTMLFormElement)return n.addEventListener("reset",a),()=>n.removeEventListener("reset",a)},[e,a,i])}0&&(module.exports={formValidityHandle,formValidityStateView,useFormReset,useFormValidityHandle});
+'use client';
+"use strict";var y=Object.create;var l=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var V=Object.getOwnPropertyNames;var f=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var p=(e,t)=>{for(var i in t)l(e,i,{get:t[i],enumerable:!0})},d=(e,t,i,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of V(t))!R.call(e,a)&&a!==i&&l(e,a,{get:()=>t[a],enumerable:!(r=m(t,a))||r.enumerable});return e};var v=(e,t,i)=>(i=e!=null?y(f(e)):{},d(t||!e||!e.__esModule?l(i,"default",{value:e,enumerable:!0}):i,e)),g=e=>d(l({},"__esModule",{value:!0}),e);var E={};p(E,{formValidityHandle:()=>s,formValidityStateView:()=>u,useFormReset:()=>H,useFormValidityHandle:()=>F,useFormValidityStateView:()=>b});module.exports=g(E);var o=v(require("react"),1),c=require("./useCallbackRef.cjs");function s(e){return{checkValidity:()=>e.current?.checkValidity()??!0,reportValidity:()=>e.current?.reportValidity()??!0,setCustomValidity:t=>e.current?.setCustomValidity(t)}}function u(e){return{get validity(){return e.current?.validity??null},get validationMessage(){return e.current?.validationMessage??""}}}function b(e){return u(e)}function F(e,t,i,r){o.useImperativeHandle(e,()=>{let a=s(i),n=t.current?Object.assign(t.current,a):a;return r&&Object.defineProperties(n,Object.getOwnPropertyDescriptors(r)),n})}function H(e,t,i){let r=(0,c.useCallbackRef)(t);o.useEffect(()=>{let a=e.current,n=i?(a?.ownerDocument??document).getElementById(i):a?.closest("form")??null;if(n instanceof HTMLFormElement)return n.addEventListener("reset",r),()=>n.removeEventListener("reset",r)},[e,r,i])}0&&(module.exports={formValidityHandle,formValidityStateView,useFormReset,useFormValidityHandle,useFormValidityStateView});

package/dist/utils/formControl.d.cts

@@ -1,82 +1,22 @@
 import * as React from 'react';
-/**
- * The two constraint-validation methods every form-associated component
- * publishes — the same pair `<skdx-*>` gets from the `FormAssociated` mixin
- * (`packages/web-components/src/internal/form-associated.ts`), and the same
- * pair a native `HTMLInputElement` has.
- *
- * On a root that renders a DOM element these are hung on that element, so
- * `ref.current` stays the node consumers already focus and measure. On a root
- * that renders no DOM of its own (`Select`, `Combobox`, `DatePicker`) the ref
- * *is* this object and nothing else.
- */
+/** The two constraint-validation methods every form-associated component publishes, the same pair a native `HTMLInputElement` has; hung onto the root's element, or the object itself when the root renders no DOM. */
 export interface FormValidityHandle {
     /** Returns whether the current value satisfies its constraints, firing `invalid` if not. */
     checkValidity(): boolean;
     /** Like {@link checkValidity}, but also shows the browser's validation message. */
     reportValidity(): boolean;
-    /**
-     * Pushes an externally-computed error into the control — a server response,
-     * a cross-field rule — exactly like `HTMLInputElement.setCustomValidity()`:
-     * a non-empty message makes the control invalid (`customError`) and is what
-     * {@link reportValidity} shows; `''` clears it.
-     *
-     * Without this, the only writable half of constraint validation lived on
-     * `<skdx-*>` alone (`FormAssociated` in
-     * `packages/web-components/src/internal/form-associated.ts`), so an error
-     * the browser cannot derive was unrepresentable in React.
-     */
+    /** Pushes an externally-computed error into the control, exactly like `HTMLInputElement.setCustomValidity()`: a non-empty message makes it invalid (`customError`) and is what {@link reportValidity} shows; `''` clears it. */
     setCustomValidity(message: string): void;
 }
-/**
- * Builds {@link FormValidityHandle} on top of whichever native control
- * actually carries the submitted value — the wrapped `<input>` for a
- * TextField, the visually-hidden one a composite renders for its selection.
- *
- * Both methods answer `true` when that control is absent, which is what a
- * control without a `name` is: it submits nothing, so there is nothing for it
- * to be invalid about. This mirrors the `?? true` fallbacks in the Web
- * Components mixin, where `ElementInternals` may not implement constraint
- * validation at all.
- */
+/** Builds {@link FormValidityHandle} on top of whichever native control actually carries the submitted value, both methods answering `true` when that control is absent (nothing to submit, nothing to be invalid about). */
 export declare function formValidityHandle(control: React.RefObject<FormValidityHandle | null>): FormValidityHandle;
-/**
- * The *readable* half of constraint validation: the control's own
- * `ValidityState` and the message the browser would show for it.
- *
- * Deliberately a separate interface from {@link FormValidityHandle} rather than
- * two more members on it, for one hard reason and one soft one.
- *
- * The hard one: `apps/docs/scripts/tsdoc/extract.mjs` finds a React root's
- * imperative API by resolving the handle type reached from a `use*Handle` call
- * and accepting it only when **every** member is a `MethodSignature`. A
- * property on `FormValidityHandle` would make that test fail, and every
- * form-associated React root would publish "no methods" — a documentation
- * regression across a dozen families, caused by adding an accessor to one.
- *
- * The soft one: these are accessors, not methods. They have to be *live* — a
- * snapshot taken when the ref was built would report the validity the control
- * had at mount — so they are installed as getters with
- * `Object.defineProperties`, which is also why `Object.assign` cannot carry
- * them.
- */
+/** The readable half of constraint validation — the control's own `ValidityState` and the message the browser would show — kept as a separate interface of live getters, since `Object.assign` can't carry accessors and a snapshot at ref-build time would go stale. */
 export interface FormValidityStateView {
-    /**
-     * The wrapped control's own `ValidityState`, live — read it to render your
-     * own error text (`validity.valueMissing`, `validity.patternMismatch`, …)
-     * instead of parsing the browser's message. `null` when no control has
-     * mounted, which is the same "nothing to be invalid about" the methods answer
-     * `true` for.
-     */
+    /** The wrapped control's own `ValidityState`, live; `null` when no control has mounted. */
     readonly validity: ValidityState | null;
-    /**
-     * The message the browser would show for the current validity — `''` when the
-     * control is valid, exactly like the native property. `''` too when no
-     * control has mounted.
-     */
+    /** The message the browser would show for the current validity — `''` when valid or when no control has mounted. */
     readonly validationMessage: string;
 }
-/** Something with the two native validity accessors — a real `<input>`, in practice. */
 type ValidityStateSource = Pick<HTMLInputElement, 'validity' | 'validationMessage'>;
 /**
  * Builds {@link FormValidityStateView} over whichever native control carries
@@ -85,22 +25,14 @@ type ValidityStateSource = Pick<HTMLInputElement, 'validity' | 'validationMessag
  */
 export declare function formValidityStateView(control: React.RefObject<ValidityStateSource | null>): FormValidityStateView;
 /**
- * Publishes {@link FormValidityHandle} on the forwarded ref of a root that
- * *does* render an element: the two methods are assigned onto the node rather
- * than replacing it, so every existing use of the ref (`focus()`,
- * `getBoundingClientRect()`, `contains()`) keeps working — this is additive,
- * not a swap.
+ * Render-phase form of {@link formValidityStateView}: the React Compiler reads a ref handed to a
+ * plain function as a render-phase ref access, and a hook boundary is where it stops looking.
  *
- * Attach `nodeRef` to the root element yourself; the forwarded ref must not
- * also be attached, since this hook owns it.
- *
- * `extra` is for accessor-shaped additions — {@link formValidityStateView} is
- * the only one today. It is copied with `Object.defineProperties` rather than
- * `Object.assign`, because assignment would *invoke* each getter once and
- * freeze its answer. Opt-in rather than always-on: a root whose element is
- * itself form-associated (a `<button>`) already has native `validity` and
- * `validationMessage` accessors, and shadowing those on every root to serve one
- * family would be a change nobody asked for.
+ * @internal
+ */
+export declare function useFormValidityStateView(control: React.RefObject<ValidityStateSource | null>): FormValidityStateView;
+/**
+ * Publishes {@link FormValidityHandle} on the forwarded ref of a root that renders an element, assigning the methods onto the node rather than replacing it so existing ref uses keep working; `extra` adds accessor-shaped members like {@link formValidityStateView}.
  *
  * @example
  * ```tsx
@@ -110,29 +42,9 @@ export declare function formValidityStateView(control: React.RefObject<ValidityS
  * return <Primitive.div {...props} ref={rootRef} />;
  * ```
  */
-export declare function useFormValidityHandle<T extends HTMLElement>(forwardedRef: React.ForwardedRef<T>, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>, extra?: object): void;
+export declare function useFormValidityHandle<T extends HTMLElement, E extends object = object>(forwardedRef: React.Ref<T & FormValidityHandle & E> | undefined, nodeRef: React.RefObject<T | null>, control: React.RefObject<FormValidityHandle | null>, extra?: E): void;
 /**
- * Restores a control's declared default when the owning `<form>` is reset —
- * the React counterpart of `formResetCallback()` on `<skdx-*>`.
- *
- * `element` is any node the control always renders (its root, its input, its
- * trigger); the form is found from it with `closest('form')`, so a control
- * outside a form simply never subscribes. Resolved once, on mount — moving a
- * mounted control into a different `<form>` does not re-associate it, the same
- * way a native input's `form` is fixed at parse time.
- *
- * `formId` is the control's `form` prop, a form element's `id`, and it wins over
- * the ancestor lookup exactly as the native `form` attribute does. Without it a
- * control that is not a DOM descendant of its form — one inside a portalled
- * dialog, which is where this matters — submitted with that form (the hidden
- * input carries `form=`) and then quietly ignored its reset, because the reset
- * listener was still looking for an ancestor there was none of.
- *
- * Unlike the Web Components mixin, which writes the property back silently,
- * `onReset` here has to go through the component's normal setter and fire its
- * change callback: a *controlled* React control's value belongs to the parent,
- * and one that reset itself without telling the parent would be overwritten on
- * the very next render.
+ * Restores a control's declared default when the owning `<form>` is reset, found from `element` via `closest('form')` (or `formId`, which wins, for a control outside the DOM subtree of its form — a portalled dialog) and resolved once on mount; `onReset` fires through the component's normal change callback since a controlled value belongs to the parent.
  */
 export declare function useFormReset(element: React.RefObject<HTMLElement | null>, onReset: () => void, formId?: string): void;
 export {};