@skdx/react 0.28.0 → 0.29.0

package/dist/utils/declaredChildren.d.cts

@@ -1,14 +1,5 @@
 import * as React from 'react';
-/**
- * Walks the elements a consumer *declared* in `children`, reporting each one's
- * component `displayName` and props.
- *
- * Needed on the server where registration effects don't run. Uses `displayName`
- * to avoid cycles; wrapped parts won't be detected and fall back to the
- * registration effect. Fragments and host elements are traversed.
- *
- * @internal
- */
+/** @internal Walks the elements a consumer declared in `children`, reporting each one's component `displayName` and props, needed on the server where registration effects don't run. */
 export declare function forEachDeclaredElement(children: React.ReactNode, visit: (displayName: string | undefined, props: Record<string, unknown>) => void): void;
 /** Whether `children` declares an element whose component `displayName` is `displayName`. @internal */
 export declare function hasDeclaredChild(children: React.ReactNode, displayName: string): boolean;

package/dist/utils/declaredChildren.d.ts

@@ -1,14 +1,5 @@
 import * as React from 'react';
-/**
- * Walks the elements a consumer *declared* in `children`, reporting each one's
- * component `displayName` and props.
- *
- * Needed on the server where registration effects don't run. Uses `displayName`
- * to avoid cycles; wrapped parts won't be detected and fall back to the
- * registration effect. Fragments and host elements are traversed.
- *
- * @internal
- */
+/** @internal Walks the elements a consumer declared in `children`, reporting each one's component `displayName` and props, needed on the server where registration effects don't run. */
 export declare function forEachDeclaredElement(children: React.ReactNode, visit: (displayName: string | undefined, props: Record<string, unknown>) => void): void;
 /** Whether `children` declares an element whose component `displayName` is `displayName`. @internal */
 export declare function hasDeclaredChild(children: React.ReactNode, displayName: string): boolean;

package/dist/utils/declaredChildren.js

@@ -1 +1,2 @@
+'use client';
 import*as t from"react";function o(r,a){t.Children.forEach(r,e=>{if(!t.isValidElement(e))return;let n=e.props;if(e.type===t.Fragment||typeof e.type=="string"){o(n.children,a);return}a(e.type.displayName,n),o(n.children,a)})}function c(r,a){let e=!1;return o(r,n=>{n===a&&(e=!0)}),e}export{o as forEachDeclaredElement,c as hasDeclaredChild};

package/dist/utils/dev-mode.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var o=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var i=Object.prototype.hasOwnProperty;var s=(n,e)=>{for(var t in e)o(n,t,{get:e[t],enumerable:!0})},f=(n,e,t,d)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of u(e))!i.call(n,r)&&r!==t&&o(n,r,{get:()=>e[r],enumerable:!(d=c(e,r))||d.enumerable});return n};var v=n=>f(o({},"__esModule",{value:!0}),n);var p={};s(p,{isDevMode:()=>a});module.exports=v(p);var g={};function a(){try{if(typeof process<"u"&&process.env.NODE_ENV==="development")return!0}catch{}try{if(g.env?.DEV===!0)return!0}catch{}return typeof ngDevMode<"u"&&ngDevMode===!0}0&&(module.exports={isDevMode});

package/dist/utils/dev-mode.d.cts

@@ -0,0 +1,12 @@
+/**
+ * Whether this build is a development build, so dev-only diagnostics may throw rather than log.
+ *
+ * Only an explicit development signal answers yes; an unset or unrecognised flag says
+ * nothing, so a bundle that defines none of the three is treated as production. The
+ * probes read build-time constants rather than arguments, so a test that needs a
+ * particular answer mocks this module.
+ *
+ * @returns `true` in development, `false` in production and when nothing says.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

package/dist/utils/dev-mode.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether this build is a development build, so dev-only diagnostics may throw rather than log.
+ *
+ * Only an explicit development signal answers yes; an unset or unrecognised flag says
+ * nothing, so a bundle that defines none of the three is treated as production. The
+ * probes read build-time constants rather than arguments, so a test that needs a
+ * particular answer mocks this module.
+ *
+ * @returns `true` in development, `false` in production and when nothing says.
+ * @internal
+ */
+export declare function isDevMode(): boolean;

package/dist/utils/dev-mode.js

@@ -0,0 +1,2 @@
+'use client';
+function e(){try{if(typeof process<"u"&&process.env.NODE_ENV==="development")return!0}catch{}try{if(import.meta.env?.DEV===!0)return!0}catch{}return typeof ngDevMode<"u"&&ngDevMode===!0}export{e as isDevMode};

package/dist/utils/direction.cjs

@@ -1 +1,2 @@
-"use strict";var a=Object.create;var n=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var x=Object.getPrototypeOf,g=Object.prototype.hasOwnProperty;var m=(t,e)=>{for(var r in e)n(t,r,{get:e[r],enumerable:!0})},l=(t,e,r,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of p(e))!g.call(t,i)&&i!==r&&n(t,i,{get:()=>e[i],enumerable:!(c=D(e,i))||c.enumerable});return t};var R=(t,e,r)=>(r=t!=null?a(x(t)):{},l(e||!t||!t.__esModule?n(r,"default",{value:t,enumerable:!0}):r,t)),P=t=>l(n({},"__esModule",{value:!0}),t);var C={};m(C,{DirectionProvider:()=>h,directionalKey:()=>A,resolveDirection:()=>d,resolvePhysicalSide:()=>y,useDirection:()=>f,usePortalledDirection:()=>v});module.exports=P(C);var o=R(require("react"),1),s=require("react/jsx-runtime"),u=o.createContext(void 0);function h({dir:t,children:e}){return(0,s.jsx)(u.Provider,{value:t,children:e})}function f(t){let e=o.useContext(u);return t??e}function v(t,e){let r=f(e);return d(t.current,r)}function d(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function y(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var w={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function A(t,e,r){return d(e,r)==="rtl"?w[t]??t:t}0&&(module.exports={DirectionProvider,directionalKey,resolveDirection,resolvePhysicalSide,useDirection,usePortalledDirection});
+'use client';
+"use strict";var a=Object.create;var n=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var m=Object.getPrototypeOf,x=Object.prototype.hasOwnProperty;var R=(t,e)=>{for(var r in e)n(t,r,{get:e[r],enumerable:!0})},l=(t,e,r,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of p(e))!x.call(t,i)&&i!==r&&n(t,i,{get:()=>e[i],enumerable:!(c=D(e,i))||c.enumerable});return t};var g=(t,e,r)=>(r=t!=null?a(m(t)):{},l(e||!t||!t.__esModule?n(r,"default",{value:t,enumerable:!0}):r,t)),P=t=>l(n({},"__esModule",{value:!0}),t);var A={};R(A,{DirectionProvider:()=>h,directionalKey:()=>w,resolveDirection:()=>d,resolvePhysicalSide:()=>y,useDirection:()=>f,usePortalledDirection:()=>v});module.exports=P(A);var o=g(require("react"),1),s=require("react/jsx-runtime"),u=o.createContext(void 0);function h({dir:t,children:e}){return(0,s.jsx)(u.Provider,{value:t,children:e})}function f(t){let e=o.useContext(u);return t??e}function v(t,e){let r=f(e);return d(t.current,r)}function d(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function y(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var S={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function w(t,e,r){return d(e,r)==="rtl"?S[t]??t:t}0&&(module.exports={DirectionProvider,directionalKey,resolveDirection,resolvePhysicalSide,useDirection,usePortalledDirection});

package/dist/utils/direction.d.cts

@@ -1,42 +1,14 @@
 import * as React from 'react';
-/**
- * Writing direction resolution, shared by every component whose keyboard
- * behaviour is horizontal (arrow-key navigation, submenu open/close, slider
- * stepping, resize handles).
- *
- * There is exactly one rule to apply: **under `dir="rtl"`, ArrowLeft and
- * ArrowRight swap meaning.** Everything else — Home/End, the vertical arrows,
- * typeahead — is direction-agnostic, so handlers call {@link directionalKey}
- * once at the top and then keep their existing LTR-authored branches.
- *
- * Direction is resolved in this order:
- *
- * 1. an explicit `dir` prop on the component, if it accepts one;
- * 2. the nearest {@link DirectionProvider};
- * 3. the nearest `[dir]` ancestor **in the DOM** — which is what a plain
- *    `dir="rtl"` prop on any skdx component produces, since `dir` is a
- *    global HTML attribute and `Primitive` spreads it onto the element;
- * 4. `document.dir`.
- *
- * Step 3 is why most components need no `dir` prop of their own and no
- * provider: `<Tabs dir="rtl">` already renders `dir="rtl"` on the tablist,
- * and the handler reads it back off `event.currentTarget`. The provider
- * exists for the case that has no element to hang the attribute on — a whole
- * app rendered RTL without touching every subtree's markup.
- */
 /** Writing direction of a subtree. */
 export type Direction = 'ltr' | 'rtl';
 /** Props for {@link DirectionProvider}. */
 export interface DirectionProviderProps {
     /** Writing direction every descendant skdx component should assume. */
     dir: Direction;
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 }
 /**
- * Declares the writing direction for every skdx component beneath it,
- * without rendering an element of its own. Wrap your app (or an RTL subtree)
- * in one when the direction is not already expressed as a `dir` attribute in
- * the DOM.
+ * Declares the writing direction for every skdx component beneath it without rendering an element of its own, for when direction isn't already expressed as a `dir` attribute in the DOM.
  *
  * @example
  * ```tsx
@@ -46,33 +18,12 @@ export interface DirectionProviderProps {
  * ```
  */
 export declare function DirectionProvider({ dir, children }: DirectionProviderProps): React.JSX.Element;
-/**
- * The direction declared by an explicit prop or the nearest
- * {@link DirectionProvider}, or `undefined` when neither is present — in
- * which case {@link directionalKey} falls back to the DOM.
- */
+/** The direction declared by an explicit prop or the nearest {@link DirectionProvider}, or `undefined` when neither is present. */
 export declare function useDirection(dirProp?: Direction): Direction | undefined;
 /**
- * The direction a **portalled** panel has to carry on itself, resolved from an
- * element still standing in the logical tree — its trigger.
- *
- * Step 3 of the resolution order above is a DOM walk, and a portalled panel has
- * been moved out of the DOM subtree it logically belongs to: an application
- * that expresses direction as `<div dir="rtl">` around its tree leaves the
- * panel's own `closest('[dir]')` reaching nothing but `<html>`, so its submenu
- * arrows stopped mirroring and its logical CSS laid out LTR. Resolving from
- * the trigger and writing the answer onto
- * the panel restores both at once, and re-roots the walk for everything inside
- * it — an item, a SubTrigger, and the SubContent that resolves from *that*.
- *
- * The ref is read during render deliberately: the panel mounts in a commit
- * after the trigger's, so `current` is already set on the render that first
- * produces the panel, and the attribute is rewritten on every subsequent render
- * anyway.
- *
+ * @internal The direction a portalled panel must carry on itself, resolved from an element still in the logical tree (its trigger) since the panel's own DOM walk would miss an ancestor `[dir]`.
  * @param anchorRef the trigger, or anything else still in the logical tree
  * @param dirProp an explicit `dir` prop, if the component takes one
- * @internal
  */
 export declare function usePortalledDirection(anchorRef: React.RefObject<Element | null>, dirProp?: Direction): Direction;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
@@ -81,25 +32,7 @@ export declare function resolveDirection(el: Element | null | undefined, overrid
 export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
 /** @internal An edge named physically, which is what CSS `left`/`right` and `data-side` mean. */
 export type PhysicalSide = 'left' | 'right' | 'top' | 'bottom';
-/**
- * Resolves a logical edge to the physical one it lands on: `start`/`end` swap
- * under RTL, `top`/`bottom` and already-physical `left`/`right` pass through.
- *
- * Components keep publishing the *logical* value (Drawer's `data-placement`,
- * an overlay's `side` prop) and only resolve at the last moment — a component
- * that stored `left` instead of `start` would break RTL for every consumer
- * downstream.
- *
- * @internal
- */
+/** @internal Resolves a logical edge to the physical one it lands on: `start`/`end` swap under RTL, `top`/`bottom` and already-physical values pass through. */
 export declare function resolvePhysicalSide(side: LogicalSide | PhysicalSide, direction: Direction): PhysicalSide;
-/**
- * Translates the key the user physically pressed into the key an
- * LTR-authored handler should act on: in RTL, ArrowLeft and ArrowRight swap.
- * Every other key is returned unchanged, so this is safe to apply
- * unconditionally — including in vertical widgets, where neither key means
- * anything.
- *
- * @internal
- */
+/** @internal Translates the physically-pressed key into the key an LTR-authored handler should act on: ArrowLeft/ArrowRight swap under RTL, every other key passes through unchanged. */
 export declare function directionalKey(key: string, el: Element | null | undefined, override?: Direction): string;

package/dist/utils/direction.d.ts

@@ -1,42 +1,14 @@
 import * as React from 'react';
-/**
- * Writing direction resolution, shared by every component whose keyboard
- * behaviour is horizontal (arrow-key navigation, submenu open/close, slider
- * stepping, resize handles).
- *
- * There is exactly one rule to apply: **under `dir="rtl"`, ArrowLeft and
- * ArrowRight swap meaning.** Everything else — Home/End, the vertical arrows,
- * typeahead — is direction-agnostic, so handlers call {@link directionalKey}
- * once at the top and then keep their existing LTR-authored branches.
- *
- * Direction is resolved in this order:
- *
- * 1. an explicit `dir` prop on the component, if it accepts one;
- * 2. the nearest {@link DirectionProvider};
- * 3. the nearest `[dir]` ancestor **in the DOM** — which is what a plain
- *    `dir="rtl"` prop on any skdx component produces, since `dir` is a
- *    global HTML attribute and `Primitive` spreads it onto the element;
- * 4. `document.dir`.
- *
- * Step 3 is why most components need no `dir` prop of their own and no
- * provider: `<Tabs dir="rtl">` already renders `dir="rtl"` on the tablist,
- * and the handler reads it back off `event.currentTarget`. The provider
- * exists for the case that has no element to hang the attribute on — a whole
- * app rendered RTL without touching every subtree's markup.
- */
 /** Writing direction of a subtree. */
 export type Direction = 'ltr' | 'rtl';
 /** Props for {@link DirectionProvider}. */
 export interface DirectionProviderProps {
     /** Writing direction every descendant skdx component should assume. */
     dir: Direction;
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 }
 /**
- * Declares the writing direction for every skdx component beneath it,
- * without rendering an element of its own. Wrap your app (or an RTL subtree)
- * in one when the direction is not already expressed as a `dir` attribute in
- * the DOM.
+ * Declares the writing direction for every skdx component beneath it without rendering an element of its own, for when direction isn't already expressed as a `dir` attribute in the DOM.
  *
  * @example
  * ```tsx
@@ -46,33 +18,12 @@ export interface DirectionProviderProps {
  * ```
  */
 export declare function DirectionProvider({ dir, children }: DirectionProviderProps): React.JSX.Element;
-/**
- * The direction declared by an explicit prop or the nearest
- * {@link DirectionProvider}, or `undefined` when neither is present — in
- * which case {@link directionalKey} falls back to the DOM.
- */
+/** The direction declared by an explicit prop or the nearest {@link DirectionProvider}, or `undefined` when neither is present. */
 export declare function useDirection(dirProp?: Direction): Direction | undefined;
 /**
- * The direction a **portalled** panel has to carry on itself, resolved from an
- * element still standing in the logical tree — its trigger.
- *
- * Step 3 of the resolution order above is a DOM walk, and a portalled panel has
- * been moved out of the DOM subtree it logically belongs to: an application
- * that expresses direction as `<div dir="rtl">` around its tree leaves the
- * panel's own `closest('[dir]')` reaching nothing but `<html>`, so its submenu
- * arrows stopped mirroring and its logical CSS laid out LTR. Resolving from
- * the trigger and writing the answer onto
- * the panel restores both at once, and re-roots the walk for everything inside
- * it — an item, a SubTrigger, and the SubContent that resolves from *that*.
- *
- * The ref is read during render deliberately: the panel mounts in a commit
- * after the trigger's, so `current` is already set on the render that first
- * produces the panel, and the attribute is rewritten on every subsequent render
- * anyway.
- *
+ * @internal The direction a portalled panel must carry on itself, resolved from an element still in the logical tree (its trigger) since the panel's own DOM walk would miss an ancestor `[dir]`.
  * @param anchorRef the trigger, or anything else still in the logical tree
  * @param dirProp an explicit `dir` prop, if the component takes one
- * @internal
  */
 export declare function usePortalledDirection(anchorRef: React.RefObject<Element | null>, dirProp?: Direction): Direction;
 /** @internal Resolves `el`'s direction, with `override` (prop/provider) winning when set. */
@@ -81,25 +32,7 @@ export declare function resolveDirection(el: Element | null | undefined, overrid
 export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
 /** @internal An edge named physically, which is what CSS `left`/`right` and `data-side` mean. */
 export type PhysicalSide = 'left' | 'right' | 'top' | 'bottom';
-/**
- * Resolves a logical edge to the physical one it lands on: `start`/`end` swap
- * under RTL, `top`/`bottom` and already-physical `left`/`right` pass through.
- *
- * Components keep publishing the *logical* value (Drawer's `data-placement`,
- * an overlay's `side` prop) and only resolve at the last moment — a component
- * that stored `left` instead of `start` would break RTL for every consumer
- * downstream.
- *
- * @internal
- */
+/** @internal Resolves a logical edge to the physical one it lands on: `start`/`end` swap under RTL, `top`/`bottom` and already-physical values pass through. */
 export declare function resolvePhysicalSide(side: LogicalSide | PhysicalSide, direction: Direction): PhysicalSide;
-/**
- * Translates the key the user physically pressed into the key an
- * LTR-authored handler should act on: in RTL, ArrowLeft and ArrowRight swap.
- * Every other key is returned unchanged, so this is safe to apply
- * unconditionally — including in vertical widgets, where neither key means
- * anything.
- *
- * @internal
- */
+/** @internal Translates the physically-pressed key into the key an LTR-authored handler should act on: ArrowLeft/ArrowRight swap under RTL, every other key passes through unchanged. */
 export declare function directionalKey(key: string, el: Element | null | undefined, override?: Direction): string;

package/dist/utils/direction.js

@@ -1 +1,2 @@
+'use client';
 import*as i from"react";import{jsx as l}from"react/jsx-runtime";var n=i.createContext(void 0);function f({dir:t,children:e}){return l(n.Provider,{value:t,children:e})}function c(t){let e=i.useContext(n);return t??e}function s(t,e){let r=c(e);return o(t.current,r)}function o(t,e){if(e)return e;let r=t?.closest("[dir]")?.getAttribute("dir")?.toLowerCase();return r==="rtl"||r==="ltr"?r:typeof document>"u"?"ltr":(document.dir||document.documentElement?.getAttribute("dir")||"").toLowerCase()==="rtl"?"rtl":"ltr"}function a(t,e){return t==="start"?e==="rtl"?"right":"left":t==="end"?e==="rtl"?"left":"right":t}var d={ArrowLeft:"ArrowRight",ArrowRight:"ArrowLeft"};function D(t,e,r){return o(e,r)==="rtl"?d[t]??t:t}export{f as DirectionProvider,D as directionalKey,o as resolveDirection,a as resolvePhysicalSide,c as useDirection,s as usePortalledDirection};

package/dist/utils/dismissal.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var r=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var y=(e,n)=>{for(var t in n)r(e,t,{get:n[t],enumerable:!0})},p=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let s of f(n))!d.call(e,s)&&s!==t&&r(e,s,{get:()=>n[s],enumerable:!(o=a(n,s))||o.enumerable});return e};var E=e=>p(r({},"__esModule",{value:!0}),e);var w={};y(w,{autoFocusEvent:()=>x,backdropPointerDown:()=>O,escapeLayer:()=>c,focusOnOpen:()=>L,focusOutsideEvent:()=>D,focusOutsideTarget:()=>K,handleEscapeKeyDown:()=>v,pushDismissLayer:()=>b,topDismissLayer:()=>i,triggerContains:()=>F});module.exports=E(w);var u=[];function m(e,n){return e.insideElements().some(t=>n.insideElements().some(o=>o&&t?.contains(o)))}function b(e){return u.push(e),()=>{let n=u.indexOf(e);n!==-1&&u.splice(n,1)}}function i(e=u){for(let n=e.length-1;n>=0;n--){let t=e[n];if(!e.some(o=>o!==t&&m(t,o)))return t}}function c(e){let n=e?u.filter(t=>t.insideElements().some(o=>o?.contains(e))):[];return i(n)??i()}function v(e,n,t){return e.key!=="Escape"||!t||c(e.target)!==n?!1:(t(e),e.preventDefault(),!0)}function x(e,n){if(!n)return!0;let t=new CustomEvent(e,{cancelable:!0,detail:null});return n(t),!t.defaultPrevented}function D(e){return new CustomEvent("focus-outside",{detail:e,cancelable:!0})}var l=0;function L(e){l+=1;try{e()}finally{queueMicrotask(()=>{l-=1})}}function K(e){if(l>0)return null;let n=e.target;return!n||n===document.body?null:n}function F(e,n){if(!e||!n)return!1;if(e.contains(n))return!0;let t=e.getRootNode();return t instanceof ShadowRoot&&t.host.contains(n)}function O(e,n){return!n||e.target!==n?null:e instanceof PointerEvent?e:new PointerEvent("pointerdown",{bubbles:!0,cancelable:!0,composed:!0,pointerType:"mouse",clientX:e.clientX,clientY:e.clientY,screenX:e.screenX,screenY:e.screenY,button:e.button,buttons:e.buttons,ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey})}0&&(module.exports={autoFocusEvent,backdropPointerDown,escapeLayer,focusOnOpen,focusOutsideEvent,focusOutsideTarget,handleEscapeKeyDown,pushDismissLayer,topDismissLayer,triggerContains});

package/dist/utils/dismissal.d.cts

@@ -0,0 +1,49 @@
+/** What `onFocusOutside` receives: `focusin` is not cancelable, so the handler gets a cancelable stand-in carrying the original as its `detail`. */
+export type FocusOutsideEvent = CustomEvent<FocusEvent>;
+/** Either flavour of outside interaction, as `onInteractOutside` sees it. */
+export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+/** One open dismissible layer, as the stack knows it: only what counts as inside it. */
+export interface DismissLayer {
+    /** The layer's own elements, read fresh each time since a panel mounts and unmounts under the same layer. */
+    insideElements: () => Array<Element | null | undefined>;
+}
+/** Registers an open layer and returns its teardown; layers close out of order (a parent unmount takes its children), so the teardown removes by identity, not by position. */
+export declare function pushDismissLayer(layer: DismissLayer): () => void;
+/** The layer nothing else is open inside: push order cannot rank nested layers, because a framework's effects run child-first. */
+export declare function topDismissLayer(candidates?: readonly DismissLayer[]): DismissLayer | undefined;
+/** The one layer an Escape belongs to: sibling non-modal layers can be open at once, so the layer holding the key's target answers, and the top layer only when none does. */
+export declare function escapeLayer(target: Node | null): DismissLayer | undefined;
+/**
+ * Runs one layer's share of a document-level Escape keydown: at most one layer
+ * handles a given Escape, and `preventDefault()` comes after the consumer's
+ * handler — never before, so a veto is read from the same event — and only when
+ * this layer was the one that handled it. Preventing matters because the close
+ * watcher of an ancestor native `<dialog>` skips a canceled Escape, which is
+ * what stops one press from closing both the top layer and the Dialog around it.
+ *
+ * Listen on the document, not the panel: a layer must answer Escape while focus
+ * sits outside it (virtual focus, a portalled submenu), which a panel-level
+ * listener never sees.
+ *
+ * @param event the document keydown
+ * @param layer the layer asking whether the key is its own
+ * @param handler the consumer's Escape handler, or `undefined` for a layer that leaves Escape to the platform (a native `<dialog>`)
+ * @returns whether this layer handled the key
+ */
+export declare function handleEscapeKeyDown(event: KeyboardEvent, layer: DismissLayer, handler: ((event: KeyboardEvent) => void) | undefined): boolean;
+/** The cancelable stand-in an auto-focus handler receives; there is no native event for "about to move focus". */
+export type AutoFocusEvent = CustomEvent<null>;
+/** Announces an automatic focus move as a cancelable event and reports whether it may go ahead. */
+export declare function autoFocusEvent(type: 'open-auto-focus' | 'close-auto-focus', handler?: (event: AutoFocusEvent) => void): boolean;
+/** The cancelable stand-in for a `focusin` that landed outside the layer. */
+export declare function focusOutsideEvent(event: FocusEvent): FocusOutsideEvent;
+/** Marks an overlay's open-time focus move so other layers don't read it as outside interaction; released in a microtask because `focus()` dispatches `focusin` synchronously. */
+export declare function focusOnOpen(move: () => void): void;
+/** The node a `focusin` moved focus to, or `null` when it is not a move this layer may be dismissed by: another layer opening, or focus clearing to `<body>`. */
+export declare function focusOutsideTarget(event: FocusEvent): Node | null;
+/** Whether an outside-interaction target is the overlay's own trigger, including through the trigger's shadow root. */
+export declare function triggerContains(trigger: Element | null | undefined, target: Node | null): boolean;
+/**
+ * The native `<dialog>` backdrop, normalised onto the same `PointerEvent` channel as every other outside pointer-down, or `null` when the press landed inside the panel. The backdrop is not an element: a pointer on it targets the dialog itself, which `contains()` would misread as inside.
+ */
+export declare function backdropPointerDown(event: MouseEvent, dialog: Element | null | undefined): PointerEvent | null;

package/dist/utils/dismissal.d.ts

@@ -0,0 +1,49 @@
+/** What `onFocusOutside` receives: `focusin` is not cancelable, so the handler gets a cancelable stand-in carrying the original as its `detail`. */
+export type FocusOutsideEvent = CustomEvent<FocusEvent>;
+/** Either flavour of outside interaction, as `onInteractOutside` sees it. */
+export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+/** One open dismissible layer, as the stack knows it: only what counts as inside it. */
+export interface DismissLayer {
+    /** The layer's own elements, read fresh each time since a panel mounts and unmounts under the same layer. */
+    insideElements: () => Array<Element | null | undefined>;
+}
+/** Registers an open layer and returns its teardown; layers close out of order (a parent unmount takes its children), so the teardown removes by identity, not by position. */
+export declare function pushDismissLayer(layer: DismissLayer): () => void;
+/** The layer nothing else is open inside: push order cannot rank nested layers, because a framework's effects run child-first. */
+export declare function topDismissLayer(candidates?: readonly DismissLayer[]): DismissLayer | undefined;
+/** The one layer an Escape belongs to: sibling non-modal layers can be open at once, so the layer holding the key's target answers, and the top layer only when none does. */
+export declare function escapeLayer(target: Node | null): DismissLayer | undefined;
+/**
+ * Runs one layer's share of a document-level Escape keydown: at most one layer
+ * handles a given Escape, and `preventDefault()` comes after the consumer's
+ * handler — never before, so a veto is read from the same event — and only when
+ * this layer was the one that handled it. Preventing matters because the close
+ * watcher of an ancestor native `<dialog>` skips a canceled Escape, which is
+ * what stops one press from closing both the top layer and the Dialog around it.
+ *
+ * Listen on the document, not the panel: a layer must answer Escape while focus
+ * sits outside it (virtual focus, a portalled submenu), which a panel-level
+ * listener never sees.
+ *
+ * @param event the document keydown
+ * @param layer the layer asking whether the key is its own
+ * @param handler the consumer's Escape handler, or `undefined` for a layer that leaves Escape to the platform (a native `<dialog>`)
+ * @returns whether this layer handled the key
+ */
+export declare function handleEscapeKeyDown(event: KeyboardEvent, layer: DismissLayer, handler: ((event: KeyboardEvent) => void) | undefined): boolean;
+/** The cancelable stand-in an auto-focus handler receives; there is no native event for "about to move focus". */
+export type AutoFocusEvent = CustomEvent<null>;
+/** Announces an automatic focus move as a cancelable event and reports whether it may go ahead. */
+export declare function autoFocusEvent(type: 'open-auto-focus' | 'close-auto-focus', handler?: (event: AutoFocusEvent) => void): boolean;
+/** The cancelable stand-in for a `focusin` that landed outside the layer. */
+export declare function focusOutsideEvent(event: FocusEvent): FocusOutsideEvent;
+/** Marks an overlay's open-time focus move so other layers don't read it as outside interaction; released in a microtask because `focus()` dispatches `focusin` synchronously. */
+export declare function focusOnOpen(move: () => void): void;
+/** The node a `focusin` moved focus to, or `null` when it is not a move this layer may be dismissed by: another layer opening, or focus clearing to `<body>`. */
+export declare function focusOutsideTarget(event: FocusEvent): Node | null;
+/** Whether an outside-interaction target is the overlay's own trigger, including through the trigger's shadow root. */
+export declare function triggerContains(trigger: Element | null | undefined, target: Node | null): boolean;
+/**
+ * The native `<dialog>` backdrop, normalised onto the same `PointerEvent` channel as every other outside pointer-down, or `null` when the press landed inside the panel. The backdrop is not an element: a pointer on it targets the dialog itself, which `contains()` would misread as inside.
+ */
+export declare function backdropPointerDown(event: MouseEvent, dialog: Element | null | undefined): PointerEvent | null;

package/dist/utils/dismissal.js

@@ -0,0 +1,2 @@
+'use client';
+var s=[];function i(e,n){return e.insideElements().some(t=>n.insideElements().some(o=>o&&t?.contains(o)))}function c(e){return s.push(e),()=>{let n=s.indexOf(e);n!==-1&&s.splice(n,1)}}function r(e=s){for(let n=e.length-1;n>=0;n--){let t=e[n];if(!e.some(o=>o!==t&&i(t,o)))return t}}function l(e){let n=e?s.filter(t=>t.insideElements().some(o=>o?.contains(e))):[];return r(n)??r()}function a(e,n,t){return e.key!=="Escape"||!t||l(e.target)!==n?!1:(t(e),e.preventDefault(),!0)}function f(e,n){if(!n)return!0;let t=new CustomEvent(e,{cancelable:!0,detail:null});return n(t),!t.defaultPrevented}function d(e){return new CustomEvent("focus-outside",{detail:e,cancelable:!0})}var u=0;function y(e){u+=1;try{e()}finally{queueMicrotask(()=>{u-=1})}}function p(e){if(u>0)return null;let n=e.target;return!n||n===document.body?null:n}function E(e,n){if(!e||!n)return!1;if(e.contains(n))return!0;let t=e.getRootNode();return t instanceof ShadowRoot&&t.host.contains(n)}function m(e,n){return!n||e.target!==n?null:e instanceof PointerEvent?e:new PointerEvent("pointerdown",{bubbles:!0,cancelable:!0,composed:!0,pointerType:"mouse",clientX:e.clientX,clientY:e.clientY,screenX:e.screenX,screenY:e.screenY,button:e.button,buttons:e.buttons,ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey})}export{f as autoFocusEvent,m as backdropPointerDown,l as escapeLayer,y as focusOnOpen,d as focusOutsideEvent,p as focusOutsideTarget,a as handleEscapeKeyDown,c as pushDismissLayer,r as topDismissLayer,E as triggerContains};

package/dist/utils/field-core.cjs

@@ -0,0 +1,2 @@
+'use client';
+"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/{field/fieldCore.d.cts → utils/field-core.d.cts}

@@ -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. */