@skdx/react 0.28.0 → 0.30.0

package/dist/utils/usePointerAngle.cjs

@@ -1 +1,2 @@
-"use strict";var R=Object.create;var f=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var A=Object.getPrototypeOf,C=Object.prototype.hasOwnProperty;var L=(n,e)=>{for(var r in e)f(n,r,{get:e[r],enumerable:!0})},E=(n,e,r,g)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of h(e))!C.call(n,t)&&t!==r&&f(n,t,{get:()=>e[t],enumerable:!(g=b(e,t))||g.enumerable});return n};var w=(n,e,r)=>(r=n!=null?R(A(n)):{},E(e||!n||!n.__esModule?f(r,"default",{value:n,enumerable:!0}):r,n)),x=n=>E(f({},"__esModule",{value:!0}),n);var U={};L(U,{usePointerAngle:()=>M});module.exports=x(U);var i=w(require("react"),1);function D(n,e){return(Math.atan2(n,-e)*180/Math.PI+360)%360}function I(n,e){return e?Math.round(Math.round(n/e)*e*1e6)/1e6%360:n}function M(n){let e=i.useRef(n);i.useEffect(()=>{e.current=n});let[r,g]=i.useState(!1),t=i.useRef(null),v=(u,c)=>{let o=c.getBoundingClientRect(),s=u.clientX-(o.left+o.width/2),d=u.clientY-(o.top+o.height/2);return I(D(s,d),e.current.step??0)},P=u=>{if(t.current)return;let c=u.currentTarget,{pointerId:o}=u;c.setPointerCapture?.(o);let s=v(u,c);g(!0),e.current.onAngleChange(s,u.nativeEvent);let d=l=>{if(l.pointerId!==o)return;let p=v(l,c);p!==s&&(s=p,e.current.onAngleChange(p,l))},m=l=>{l.pointerId===o&&(t.current?.(),g(!1),e.current.onAngleChangeEnd?.(s,l))},a=c.ownerDocument;a.addEventListener("pointermove",d),a.addEventListener("pointerup",m),a.addEventListener("pointercancel",m),t.current=()=>{a.removeEventListener("pointermove",d),a.removeEventListener("pointerup",m),a.removeEventListener("pointercancel",m),t.current=null}};return i.useEffect(()=>()=>t.current?.(),[]),{onPointerDown:P,dragging:r}}0&&(module.exports={usePointerAngle});
+'use client';
+"use strict";var R=Object.create;var m=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var A=Object.getPrototypeOf,C=Object.prototype.hasOwnProperty;var L=(n,e)=>{for(var r in e)m(n,r,{get:e[r],enumerable:!0})},E=(n,e,r,g)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of h(e))!C.call(n,t)&&t!==r&&m(n,t,{get:()=>e[t],enumerable:!(g=b(e,t))||g.enumerable});return n};var w=(n,e,r)=>(r=n!=null?R(A(n)):{},E(e||!n||!n.__esModule?m(r,"default",{value:n,enumerable:!0}):r,n)),x=n=>E(m({},"__esModule",{value:!0}),n);var U={};L(U,{usePointerAngle:()=>M});module.exports=x(U);var i=w(require("react"),1);function D(n,e){return(Math.atan2(n,-e)*180/Math.PI+360)%360}function I(n,e){return e?Math.round(Math.round(n/e)*e*1e6)/1e6%360:n}function M(n){let e=i.useRef(n);i.useEffect(()=>{e.current=n});let[r,g]=i.useState(!1),t=i.useRef(null),v=(u,c)=>{let o=c.getBoundingClientRect(),s=u.clientX-(o.left+o.width/2),d=u.clientY-(o.top+o.height/2);return I(D(s,d),e.current.step??0)},P=u=>{if(t.current)return;let c=u.currentTarget,{pointerId:o}=u;c.setPointerCapture?.(o);let s=v(u,c);g(!0),e.current.onAngleChange(s,u.nativeEvent);let d=l=>{if(l.pointerId!==o)return;let p=v(l,c);p!==s&&(s=p,e.current.onAngleChange(p,l))},f=l=>{l.pointerId===o&&(t.current?.(),g(!1),e.current.onAngleChangeEnd?.(s,l))},a=c.ownerDocument;a.addEventListener("pointermove",d),a.addEventListener("pointerup",f),a.addEventListener("pointercancel",f),t.current=()=>{a.removeEventListener("pointermove",d),a.removeEventListener("pointerup",f),a.removeEventListener("pointercancel",f),t.current=null}};return i.useEffect(()=>()=>t.current?.(),[]),{onPointerDown:P,dragging:r}}0&&(module.exports={usePointerAngle});

package/dist/utils/usePointerAngle.d.cts

@@ -2,62 +2,30 @@ import * as React from 'react';
 /** Options for {@link usePointerAngle}. */
 export interface UsePointerAngleOptions {
     /**
-     * Snap increment in degrees. Angles are rounded to the nearest multiple
-     * before either callback sees them, and a drag that stays within one
-     * increment emits nothing — which is what keeps a per-pixel `pointermove`
-     * from becoming a per-pixel render.
+     * Snap increment in degrees; angles are rounded before either callback sees them, and a drag that stays within one increment emits nothing.
      * @default 0 — continuous; every pixel of movement reports a fresh angle.
      */
-    step?: number;
+    step?: number | undefined;
     /**
      * Fires with the angle in `[0, 360)` on pointer down and on every subsequent
      * move that changes it, plus the native event that produced it.
      */
     onAngleChange: (angle: number, event: PointerEvent) => void;
     /**
-     * Fires once with the final angle when the drag ends — `pointerup` or
-     * `pointercancel`. This is the hook that lets a consumer avoid one network
-     * call per frame; `onAngleChange` is the per-frame signal.
+     * Fires once with the final angle when the drag ends (`pointerup` or `pointercancel`), for a consumer avoiding one network call per frame.
      * @default undefined — no-op if omitted.
      */
-    onAngleChangeEnd?: (angle: number, event: PointerEvent) => void;
+    onAngleChangeEnd?: ((angle: number, event: PointerEvent) => void) | undefined;
 }
 /** Return value of {@link usePointerAngle}. */
 export interface UsePointerAngleResult {
-    /**
-     * Spread onto the element that defines the circle. That element's border box
-     * is the measurement source: its centre is the pivot, and it is re-measured
-     * on every move, so a page that scrolls or resizes mid-drag stays correct.
-     */
+    /** Spread onto the element that defines the circle; its border box is the measurement source, re-measured on every move so scrolling/resizing mid-drag stays correct. */
     onPointerDown: (event: React.PointerEvent<Element>) => void;
-    /**
-     * `true` between pointer down and pointer up/cancel. Suitable for a
-     * `data-dragging` styling hook; it is state, so it re-renders once per drag
-     * boundary and never per move.
-     */
+    /** `true` between pointer down and pointer up/cancel, suitable for a `data-dragging` hook; it's state, so it re-renders once per drag boundary, never per move. */
     dragging: boolean;
 }
 /**
- * Turns a pointer position inside an element into a normalized angle, for any
- * widget whose input is a direction rather than a distance — an angle slider,
- * a hue wheel, a gradient-angle picker, a compass.
- *
- * **Convention: 0° is at 12 o'clock and the angle increases clockwise**, so 90°
- * is 3 o'clock, 180° is 6 o'clock and 270° is 9 o'clock. Screen coordinates
- * have +y pointing *down*, which this hook already accounts for — callers pass
- * raw `clientX`/`clientY` and never touch the sign themselves. Values are
- * always in `[0, 360)`; 360 is never emitted.
- *
- * The hook knows nothing about what the angle *means*. It has no notion of a
- * value range, no ARIA, and no `disabled`/`readOnly` policy — a component that
- * should ignore input simply does not wire up `onPointerDown`.
- *
- * It takes pointer capture on the element so a drag survives leaving it, and
- * tracks the drag through document-level listeners so it survives leaving the
- * *window* too. Those listeners are removed on pointer up, on `pointercancel`
- * (which also fires `onAngleChangeEnd`, so a drag interrupted by a system
- * gesture still commits rather than hanging), and on unmount — where nothing is
- * fired, because an unmounted component has no value to commit to.
+ * Turns a pointer position inside an element into a normalized angle in `[0, 360)` — 0° at 12 o'clock, increasing clockwise — for any widget whose input is a direction rather than a distance; takes pointer capture and tracks the drag through document-level listeners so it survives leaving the element or window.
  *
  * @example
  * ```tsx

package/dist/utils/usePointerAngle.d.ts

@@ -2,62 +2,30 @@ import * as React from 'react';
 /** Options for {@link usePointerAngle}. */
 export interface UsePointerAngleOptions {
     /**
-     * Snap increment in degrees. Angles are rounded to the nearest multiple
-     * before either callback sees them, and a drag that stays within one
-     * increment emits nothing — which is what keeps a per-pixel `pointermove`
-     * from becoming a per-pixel render.
+     * Snap increment in degrees; angles are rounded before either callback sees them, and a drag that stays within one increment emits nothing.
      * @default 0 — continuous; every pixel of movement reports a fresh angle.
      */
-    step?: number;
+    step?: number | undefined;
     /**
      * Fires with the angle in `[0, 360)` on pointer down and on every subsequent
      * move that changes it, plus the native event that produced it.
      */
     onAngleChange: (angle: number, event: PointerEvent) => void;
     /**
-     * Fires once with the final angle when the drag ends — `pointerup` or
-     * `pointercancel`. This is the hook that lets a consumer avoid one network
-     * call per frame; `onAngleChange` is the per-frame signal.
+     * Fires once with the final angle when the drag ends (`pointerup` or `pointercancel`), for a consumer avoiding one network call per frame.
      * @default undefined — no-op if omitted.
      */
-    onAngleChangeEnd?: (angle: number, event: PointerEvent) => void;
+    onAngleChangeEnd?: ((angle: number, event: PointerEvent) => void) | undefined;
 }
 /** Return value of {@link usePointerAngle}. */
 export interface UsePointerAngleResult {
-    /**
-     * Spread onto the element that defines the circle. That element's border box
-     * is the measurement source: its centre is the pivot, and it is re-measured
-     * on every move, so a page that scrolls or resizes mid-drag stays correct.
-     */
+    /** Spread onto the element that defines the circle; its border box is the measurement source, re-measured on every move so scrolling/resizing mid-drag stays correct. */
     onPointerDown: (event: React.PointerEvent<Element>) => void;
-    /**
-     * `true` between pointer down and pointer up/cancel. Suitable for a
-     * `data-dragging` styling hook; it is state, so it re-renders once per drag
-     * boundary and never per move.
-     */
+    /** `true` between pointer down and pointer up/cancel, suitable for a `data-dragging` hook; it's state, so it re-renders once per drag boundary, never per move. */
     dragging: boolean;
 }
 /**
- * Turns a pointer position inside an element into a normalized angle, for any
- * widget whose input is a direction rather than a distance — an angle slider,
- * a hue wheel, a gradient-angle picker, a compass.
- *
- * **Convention: 0° is at 12 o'clock and the angle increases clockwise**, so 90°
- * is 3 o'clock, 180° is 6 o'clock and 270° is 9 o'clock. Screen coordinates
- * have +y pointing *down*, which this hook already accounts for — callers pass
- * raw `clientX`/`clientY` and never touch the sign themselves. Values are
- * always in `[0, 360)`; 360 is never emitted.
- *
- * The hook knows nothing about what the angle *means*. It has no notion of a
- * value range, no ARIA, and no `disabled`/`readOnly` policy — a component that
- * should ignore input simply does not wire up `onPointerDown`.
- *
- * It takes pointer capture on the element so a drag survives leaving it, and
- * tracks the drag through document-level listeners so it survives leaving the
- * *window* too. Those listeners are removed on pointer up, on `pointercancel`
- * (which also fires `onAngleChangeEnd`, so a drag interrupted by a system
- * gesture still commits rather than hanging), and on unmount — where nothing is
- * fired, because an unmounted component has no value to commit to.
+ * Turns a pointer position inside an element into a normalized angle in `[0, 360)` — 0° at 12 o'clock, increasing clockwise — for any widget whose input is a direction rather than a distance; takes pointer capture and tracks the drag through document-level listeners so it survives leaving the element or window.
  *
  * @example
  * ```tsx

package/dist/utils/usePointerAngle.js

@@ -1 +1,2 @@
-import*as t from"react";function E(r,e){return(Math.atan2(r,-e)*180/Math.PI+360)%360}function P(r,e){return e?Math.round(Math.round(r/e)*e*1e6)/1e6%360:r}function R(r){let e=t.useRef(r);t.useEffect(()=>{e.current=r});let[p,m]=t.useState(!1),a=t.useRef(null),f=(o,i)=>{let n=i.getBoundingClientRect(),u=o.clientX-(n.left+n.width/2),l=o.clientY-(n.top+n.height/2);return P(E(u,l),e.current.step??0)},v=o=>{if(a.current)return;let i=o.currentTarget,{pointerId:n}=o;i.setPointerCapture?.(n);let u=f(o,i);m(!0),e.current.onAngleChange(u,o.nativeEvent);let l=s=>{if(s.pointerId!==n)return;let d=f(s,i);d!==u&&(u=d,e.current.onAngleChange(d,s))},g=s=>{s.pointerId===n&&(a.current?.(),m(!1),e.current.onAngleChangeEnd?.(u,s))},c=i.ownerDocument;c.addEventListener("pointermove",l),c.addEventListener("pointerup",g),c.addEventListener("pointercancel",g),a.current=()=>{c.removeEventListener("pointermove",l),c.removeEventListener("pointerup",g),c.removeEventListener("pointercancel",g),a.current=null}};return t.useEffect(()=>()=>a.current?.(),[]),{onPointerDown:v,dragging:p}}export{R as usePointerAngle};
+'use client';
+import*as t from"react";function E(r,e){return(Math.atan2(r,-e)*180/Math.PI+360)%360}function P(r,e){return e?Math.round(Math.round(r/e)*e*1e6)/1e6%360:r}function R(r){let e=t.useRef(r);t.useEffect(()=>{e.current=r});let[p,f]=t.useState(!1),a=t.useRef(null),m=(o,i)=>{let n=i.getBoundingClientRect(),u=o.clientX-(n.left+n.width/2),l=o.clientY-(n.top+n.height/2);return P(E(u,l),e.current.step??0)},v=o=>{if(a.current)return;let i=o.currentTarget,{pointerId:n}=o;i.setPointerCapture?.(n);let u=m(o,i);f(!0),e.current.onAngleChange(u,o.nativeEvent);let l=s=>{if(s.pointerId!==n)return;let d=m(s,i);d!==u&&(u=d,e.current.onAngleChange(d,s))},g=s=>{s.pointerId===n&&(a.current?.(),f(!1),e.current.onAngleChangeEnd?.(u,s))},c=i.ownerDocument;c.addEventListener("pointermove",l),c.addEventListener("pointerup",g),c.addEventListener("pointercancel",g),a.current=()=>{c.removeEventListener("pointermove",l),c.removeEventListener("pointerup",g),c.removeEventListener("pointercancel",g),a.current=null}};return t.useEffect(()=>()=>a.current?.(),[]),{onPointerDown:v,dragging:p}}export{R as usePointerAngle};

package/dist/utils/useRovingFocus.cjs

@@ -1 +1,2 @@
-"use strict";var w=Object.create;var b=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var L=Object.getOwnPropertyNames;var H=Object.getPrototypeOf,M=Object.prototype.hasOwnProperty;var K=(e,t)=>{for(var r in t)b(e,r,{get:t[r],enumerable:!0})},A=(e,t,r,c)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of L(t))!M.call(e,o)&&o!==r&&b(e,o,{get:()=>t[o],enumerable:!(c=O(t,o))||c.enumerable});return e};var k=(e,t,r)=>(r=e!=null?w(H(e)):{},A(t||!e||!e.__esModule?b(r,"default",{value:e,enumerable:!0}):r,e)),D=e=>A(b({},"__esModule",{value:!0}),e);var F={};K(F,{itemText:()=>E,rovingTabIndex:()=>v,useRovingFocus:()=>z,useRovingTabStop:()=>U});module.exports=D(F);var u=k(require("react"),1),R=require("./direction.cjs"),S=1e3;function E(e){return e.getAttribute("data-text-value")??e.textContent??""}function U(e,t,r,c,o){u.useLayoutEffect(()=>{let f=Array.from(e.current?.querySelectorAll(t)??[],l=>l.getAttribute(r)).filter(l=>l!==null&&l!==""),a=f[0];a===void 0||c!==null&&f.includes(c)||o(a)})}function v(e,t,r=!1){return e||r?t?0:-1:0}var C={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},_={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function z({orientation:e="both",loop:t=!0,itemSelector:r,scopeSelector:c,typeahead:o=!1,includeDisabled:f=!1}){let a=u.useRef(""),l=u.useRef(void 0),T=(0,R.useDirection)();return u.useEffect(()=>()=>clearTimeout(l.current),[]),u.useCallback(i=>{let h=i.currentTarget,s=Array.from(h.querySelectorAll(r)).filter(d=>(f||!d.hasAttribute("disabled")&&d.getAttribute("data-disabled")===null)&&(!c||d.closest(c)===h));if(s.length===0)return;let g=s.indexOf(i.target),m=(0,R.directionalKey)(i.key,h,T),n;if(C[e].includes(m))n=g+1,n>=s.length&&(n=t?0:s.length-1);else if(_[e].includes(m))n=g-1,n<0&&(n=t?s.length-1:0);else if(m==="Home")n=0;else if(m==="End")n=s.length-1;else if(o&&i.key.length===1&&!i.ctrlKey&&!i.metaKey&&!i.altKey&&(i.key!==" "||a.current!=="")){clearTimeout(l.current),a.current+=i.key.toLowerCase(),l.current=setTimeout(()=>{a.current=""},S);let d=a.current,p=x=>E(x).trim().toLowerCase().startsWith(d),y=[...s.slice(g+1),...s.slice(0,g+1)].find(p);y&&(n=s.indexOf(y))}n!==void 0&&(i.preventDefault(),s[n]?.focus())},[e,t,r,c,o,f,T])}0&&(module.exports={itemText,rovingTabIndex,useRovingFocus,useRovingTabStop});
+'use client';
+"use strict";var T=Object.create;var b=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var x=Object.getPrototypeOf,L=Object.prototype.hasOwnProperty;var O=(e,t)=>{for(var n in t)b(e,n,{get:t[n],enumerable:!0})},v=(e,t,n,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of w(t))!L.call(e,o)&&o!==n&&b(e,o,{get:()=>t[o],enumerable:!(i=A(t,o))||i.enumerable});return e};var H=(e,t,n)=>(n=e!=null?T(x(e)):{},v(t||!e||!e.__esModule?b(n,"default",{value:e,enumerable:!0}):n,e)),I=e=>v(b({},"__esModule",{value:!0}),e);var D={};O(D,{rovingTabIndex:()=>y.rovingTabIndex,useRovingFocus:()=>k,useRovingTabStop:()=>K});module.exports=I(D);var l=H(require("react"),1),h=require("./direction.cjs"),f=require("./roving-tab-stop.cjs"),u=require("./typeahead.cjs"),y=require("./roving-tab-stop.cjs");function K(e,t,n,i,o){l.useLayoutEffect(()=>{let g=(0,f.rovingItemIds)((0,f.enabledRovingItems)(e.current,t),n),s=(0,f.resolveTabStopId)(g,[],i);s===null||s===i||o(s)})}var M={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},S={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function k({orientation:e="both",loop:t=!0,itemSelector:n,scopeSelector:i,typeahead:o=!1,includeDisabled:g=!1}){let[s]=l.useState(()=>new u.Typeahead),E=(0,h.useDirection)();return l.useEffect(()=>()=>s.clear(),[s]),l.useCallback(c=>{let R=c.currentTarget,a=Array.from(R.querySelectorAll(n)).filter(d=>(g||!d.hasAttribute("disabled")&&d.getAttribute("data-disabled")===null)&&(!i||d.closest(i)===R));if(a.length===0)return;let p=a.indexOf(c.target),m=(0,h.directionalKey)(c.key,R,E),r;if(M[e].includes(m))r=p+1,r>=a.length&&(r=t?0:a.length-1);else if(S[e].includes(m))r=p-1,r<0&&(r=t?a.length-1:0);else if(m==="Home")r=0;else if(m==="End")r=a.length-1;else if(o&&(0,u.isTypeaheadKey)(c)){let d=s.match(c.key,a.map(u.itemText),p);d!==-1&&(r=d)}r!==void 0&&(c.preventDefault(),a[r]?.focus())},[e,t,n,i,o,g,E,s])}0&&(module.exports={rovingTabIndex,useRovingFocus,useRovingTabStop});

package/dist/utils/useRovingFocus.d.cts

@@ -1,115 +1,24 @@
 import * as React from 'react';
+export { rovingTabIndex } from './roving-tab-stop.cjs';
 /** @internal Which arrow keys move focus within a roving-focus group: horizontal, vertical, or `'both'` (all four arrows). */
 export type Orientation = 'horizontal' | 'vertical' | 'both';
 interface UseRovingFocusOptions {
-    orientation?: Orientation;
-    loop?: boolean;
-    /** CSS selector matching focusable items inside the group. */
+    orientation?: Orientation | undefined;
+    loop?: boolean | undefined;
     itemSelector: string;
-    /**
-     * Selector matching *this kind of group*, so a nested group's items are not
-     * navigated by its ancestor. Items whose nearest matching ancestor is not
-     * the element the handler is attached to are dropped.
-     *
-     * `itemSelector` is run as an unscoped descendant query, so without this a
-     * TagGroup nested inside another would match every `[data-skdx-tag]` at any
-     * depth, and the outer group's arrow keys would walk the inner group's tags
-     * — disagreeing with `focusTagNeighbor`, the other half of the same family,
-     * which scopes to `closest('[data-skdx-tag-group]')`.
-     *
-     * Omit it for a group that cannot nest; the cost when set is one `closest()`
-     * per candidate.
-     * @default undefined — every descendant match is an item, whoever owns it.
-     */
-    scopeSelector?: string;
-    /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
-    typeahead?: boolean;
-    /**
-     * Keep disabled items in the navigable list instead of skipping them.
-     *
-     * Opt-in, because the two conventions are both correct and belong to
-     * different patterns. A tab, a toolbar button, a toggle or a radio is a
-     * *control*: a disabled one is inert, and APG's roving-tabindex guidance for
-     * those has focus pass over it. A menu item is a *command*: APG states
-     * plainly that "disabled menu items are focusable but cannot be activated",
-     * so skipping one hides from a keyboard user that the command exists at all.
-     *
-     * Only the three menu families and their submenus pass it. Tabs, Toolbar,
-     * ToggleGroup, Listbox, Transfer and TagGroup share this hook and keep the
-     * default, so their behaviour is unchanged.
-     * @default false — a disabled item is skipped, as it is in every non-menu family.
-     */
-    includeDisabled?: boolean;
+    scopeSelector?: string | undefined;
+    typeahead?: boolean | undefined;
+    includeDisabled?: boolean | undefined;
 }
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
- * @internal
- */
-export declare function itemText(el: Element): string;
-/**
- * Keeps a roving-tabindex group's tab stop on an item that actually exists.
- *
- * Seeding "when nothing is focused yet, make the first item tabbable" is only
- * half the job: when the item *holding* the tab stop is removed, the stored id
- * still points at it, so a `currentId !== null` guard sees nothing to do — and
- * then no item carries `tabIndex` 0 and the whole group silently drops out of
- * the tab order, with nothing on screen to explain it. So the check is
- * "does any item claim the current id", not "is the current id set".
- *
- * Deliberately runs on every render with no dependency array: an item can
- * disappear without `currentId` changing, which is exactly the case that
- * breaks. Each run is one `querySelectorAll` over a group that is small by
- * construction, and it settles after at most one `setCurrentId`.
+ * @internal Keeps a roving-tabindex group's tab stop on an item that actually exists, checking whether any item claims the current id rather than just whether one is set; runs on every render with no dependency array, since an item can disappear without `currentId` changing.
  *
  * @param rootRef the group element owning the items
  * @param itemSelector selector matching the group's items
  * @param idAttribute attribute on each item holding its id
  * @param currentId the id currently holding the tab stop
  * @param setCurrentId hands the tab stop to another item
- * @internal
  */
 export declare function useRovingTabStop(rootRef: React.RefObject<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: string | null, setCurrentId: (id: string) => void): void;
-/**
- * The `tabIndex` for one item of a roving-tabindex group.
- *
- * {@link useRovingTabStop} resolves which item holds the group's single tab
- * stop from a *layout effect*, and effects never run during server rendering.
- * So in server HTML `resolved` is false, and a group with no selected or
- * pressed item to fall back on rendered `tabIndex={-1}` on every item — the
- * whole group had no tab stop at all and was unreachable by keyboard. That is
- * the markup a non-hydrated consumer (an Astro island, an RSC subtree) ships,
- * and all its users ever get.
- *
- * So until the stop is resolved, every enabled item is a tab stop. Tabbing
- * through N items is a degradation; being unable to reach any of them is a
- * defect — and it is the *correct* arrangement for markup whose arrow keys
- * (the other half of roving tabindex, and pure JavaScript) may never arrive.
- * A `0` rather than an omitted attribute because the items are not always
- * natively focusable: a `[role="treeitem"]` is a `<div>`.
- *
- * A disabled item never claims a stop it could not hold, resolved or not.
- *
- * From the first layout effect onward this is exactly `isTabStop ? 0 : -1`, so
- * behaviour after hydration is unchanged.
- *
- * @param resolved whether the group has settled which item holds the tab stop
- * @param isTabStop whether this item is the one holding it
- * @param disabled whether this item is disabled
- * @internal
- */
-export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;
-/**
- * DOM-driven roving focus for composite widgets (tabs, radio groups, menus,
- * toolbars). Returns a keydown handler to spread on the group element.
- * Items are discovered by selector, so no registration plumbing is needed.
- */
+/** DOM-driven roving focus for composite widgets (tabs, radio groups, menus, toolbars), returning a keydown handler to spread on the group element; items are discovered by selector, no registration plumbing needed. */
 export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
-export {};

package/dist/utils/useRovingFocus.d.ts

@@ -1,115 +1,24 @@
 import * as React from 'react';
+export { rovingTabIndex } from './roving-tab-stop.js';
 /** @internal Which arrow keys move focus within a roving-focus group: horizontal, vertical, or `'both'` (all four arrows). */
 export type Orientation = 'horizontal' | 'vertical' | 'both';
 interface UseRovingFocusOptions {
-    orientation?: Orientation;
-    loop?: boolean;
-    /** CSS selector matching focusable items inside the group. */
+    orientation?: Orientation | undefined;
+    loop?: boolean | undefined;
     itemSelector: string;
-    /**
-     * Selector matching *this kind of group*, so a nested group's items are not
-     * navigated by its ancestor. Items whose nearest matching ancestor is not
-     * the element the handler is attached to are dropped.
-     *
-     * `itemSelector` is run as an unscoped descendant query, so without this a
-     * TagGroup nested inside another would match every `[data-skdx-tag]` at any
-     * depth, and the outer group's arrow keys would walk the inner group's tags
-     * — disagreeing with `focusTagNeighbor`, the other half of the same family,
-     * which scopes to `closest('[data-skdx-tag-group]')`.
-     *
-     * Omit it for a group that cannot nest; the cost when set is one `closest()`
-     * per candidate.
-     * @default undefined — every descendant match is an item, whoever owns it.
-     */
-    scopeSelector?: string;
-    /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
-    typeahead?: boolean;
-    /**
-     * Keep disabled items in the navigable list instead of skipping them.
-     *
-     * Opt-in, because the two conventions are both correct and belong to
-     * different patterns. A tab, a toolbar button, a toggle or a radio is a
-     * *control*: a disabled one is inert, and APG's roving-tabindex guidance for
-     * those has focus pass over it. A menu item is a *command*: APG states
-     * plainly that "disabled menu items are focusable but cannot be activated",
-     * so skipping one hides from a keyboard user that the command exists at all.
-     *
-     * Only the three menu families and their submenus pass it. Tabs, Toolbar,
-     * ToggleGroup, Listbox, Transfer and TagGroup share this hook and keep the
-     * default, so their behaviour is unchanged.
-     * @default false — a disabled item is skipped, as it is in every non-menu family.
-     */
-    includeDisabled?: boolean;
+    scopeSelector?: string | undefined;
+    typeahead?: boolean | undefined;
+    includeDisabled?: boolean | undefined;
 }
 /**
- * The text typeahead matches an item against: its explicit `data-text-value`
- * if it has one, else its rendered text.
- *
- * Raw `textContent` alone is wrong for any item that renders more than its
- * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
- * skips exactly the items that are currently selected. `data-text-value` is
- * the escape hatch, and this is the one precedence rule every matcher in the
- * repo follows.
- *
- * @internal
- */
-export declare function itemText(el: Element): string;
-/**
- * Keeps a roving-tabindex group's tab stop on an item that actually exists.
- *
- * Seeding "when nothing is focused yet, make the first item tabbable" is only
- * half the job: when the item *holding* the tab stop is removed, the stored id
- * still points at it, so a `currentId !== null` guard sees nothing to do — and
- * then no item carries `tabIndex` 0 and the whole group silently drops out of
- * the tab order, with nothing on screen to explain it. So the check is
- * "does any item claim the current id", not "is the current id set".
- *
- * Deliberately runs on every render with no dependency array: an item can
- * disappear without `currentId` changing, which is exactly the case that
- * breaks. Each run is one `querySelectorAll` over a group that is small by
- * construction, and it settles after at most one `setCurrentId`.
+ * @internal Keeps a roving-tabindex group's tab stop on an item that actually exists, checking whether any item claims the current id rather than just whether one is set; runs on every render with no dependency array, since an item can disappear without `currentId` changing.
  *
  * @param rootRef the group element owning the items
  * @param itemSelector selector matching the group's items
  * @param idAttribute attribute on each item holding its id
  * @param currentId the id currently holding the tab stop
  * @param setCurrentId hands the tab stop to another item
- * @internal
  */
 export declare function useRovingTabStop(rootRef: React.RefObject<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: string | null, setCurrentId: (id: string) => void): void;
-/**
- * The `tabIndex` for one item of a roving-tabindex group.
- *
- * {@link useRovingTabStop} resolves which item holds the group's single tab
- * stop from a *layout effect*, and effects never run during server rendering.
- * So in server HTML `resolved` is false, and a group with no selected or
- * pressed item to fall back on rendered `tabIndex={-1}` on every item — the
- * whole group had no tab stop at all and was unreachable by keyboard. That is
- * the markup a non-hydrated consumer (an Astro island, an RSC subtree) ships,
- * and all its users ever get.
- *
- * So until the stop is resolved, every enabled item is a tab stop. Tabbing
- * through N items is a degradation; being unable to reach any of them is a
- * defect — and it is the *correct* arrangement for markup whose arrow keys
- * (the other half of roving tabindex, and pure JavaScript) may never arrive.
- * A `0` rather than an omitted attribute because the items are not always
- * natively focusable: a `[role="treeitem"]` is a `<div>`.
- *
- * A disabled item never claims a stop it could not hold, resolved or not.
- *
- * From the first layout effect onward this is exactly `isTabStop ? 0 : -1`, so
- * behaviour after hydration is unchanged.
- *
- * @param resolved whether the group has settled which item holds the tab stop
- * @param isTabStop whether this item is the one holding it
- * @param disabled whether this item is disabled
- * @internal
- */
-export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;
-/**
- * DOM-driven roving focus for composite widgets (tabs, radio groups, menus,
- * toolbars). Returns a keydown handler to spread on the group element.
- * Items are discovered by selector, so no registration plumbing is needed.
- */
+/** DOM-driven roving focus for composite widgets (tabs, radio groups, menus, toolbars), returning a keydown handler to spread on the group element; items are discovered by selector, no registration plumbing needed. */
 export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
-export {};

package/dist/utils/useRovingFocus.js

@@ -1 +1,2 @@
-import*as o from"react";import{directionalKey as A,useDirection as E}from"./direction.js";var p=1e3;function x(t){return t.getAttribute("data-text-value")??t.textContent??""}function M(t,s,u,l,d){o.useLayoutEffect(()=>{let a=Array.from(t.current?.querySelectorAll(s)??[],i=>i.getAttribute(u)).filter(i=>i!==null&&i!==""),c=a[0];c===void 0||l!==null&&a.includes(l)||d(c)})}function K(t,s,u=!1){return t||u?s?0:-1:0}var w={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},O={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function k({orientation:t="both",loop:s=!0,itemSelector:u,scopeSelector:l,typeahead:d=!1,includeDisabled:a=!1}){let c=o.useRef(""),i=o.useRef(void 0),R=E();return o.useEffect(()=>()=>clearTimeout(i.current),[]),o.useCallback(r=>{let b=r.currentTarget,n=Array.from(b.querySelectorAll(u)).filter(f=>(a||!f.hasAttribute("disabled")&&f.getAttribute("data-disabled")===null)&&(!l||f.closest(l)===b));if(n.length===0)return;let g=n.indexOf(r.target),m=A(r.key,b,R),e;if(w[t].includes(m))e=g+1,e>=n.length&&(e=s?0:n.length-1);else if(O[t].includes(m))e=g-1,e<0&&(e=s?n.length-1:0);else if(m==="Home")e=0;else if(m==="End")e=n.length-1;else if(d&&r.key.length===1&&!r.ctrlKey&&!r.metaKey&&!r.altKey&&(r.key!==" "||c.current!=="")){clearTimeout(i.current),c.current+=r.key.toLowerCase(),i.current=setTimeout(()=>{c.current=""},p);let f=c.current,T=y=>x(y).trim().toLowerCase().startsWith(f),h=[...n.slice(g+1),...n.slice(0,g+1)].find(T);h&&(e=n.indexOf(h))}e!==void 0&&(r.preventDefault(),n[e]?.focus())},[t,s,u,l,d,a,R])}export{x as itemText,K as rovingTabIndex,k as useRovingFocus,M as useRovingTabStop};
+'use client';
+import*as r from"react";import{directionalKey as h,useDirection as R}from"./direction.js";import{enabledRovingItems as p,resolveTabStopId as E,rovingItemIds as v}from"./roving-tab-stop.js";import{isTypeaheadKey as y,itemText as T,Typeahead as A}from"./typeahead.js";import{rovingTabIndex as k}from"./roving-tab-stop.js";function I(a,l,c,o,d){r.useLayoutEffect(()=>{let f=v(p(a.current,l),c),t=E(f,[],o);t===null||t===o||d(t)})}var w={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},x={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function K({orientation:a="both",loop:l=!0,itemSelector:c,scopeSelector:o,typeahead:d=!1,includeDisabled:f=!1}){let[t]=r.useState(()=>new A),b=R();return r.useEffect(()=>()=>t.clear(),[t]),r.useCallback(i=>{let g=i.currentTarget,n=Array.from(g.querySelectorAll(c)).filter(s=>(f||!s.hasAttribute("disabled")&&s.getAttribute("data-disabled")===null)&&(!o||s.closest(o)===g));if(n.length===0)return;let m=n.indexOf(i.target),u=h(i.key,g,b),e;if(w[a].includes(u))e=m+1,e>=n.length&&(e=l?0:n.length-1);else if(x[a].includes(u))e=m-1,e<0&&(e=l?n.length-1:0);else if(u==="Home")e=0;else if(u==="End")e=n.length-1;else if(d&&y(i)){let s=t.match(i.key,n.map(T),m);s!==-1&&(e=s)}e!==void 0&&(i.preventDefault(),n[e]?.focus())},[a,l,c,o,d,f,b,t])}export{k as rovingTabIndex,K as useRovingFocus,I as useRovingTabStop};

package/dist/utils/useSelection.cjs

@@ -1 +1,2 @@
-"use strict";var C=Object.create;var u=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var k=Object.getPrototypeOf,D=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)u(e,t,{get:n[t],enumerable:!0})},d=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of $(n))!D.call(e,r)&&r!==t&&u(e,r,{get:()=>n[r],enumerable:!(o=O(n,r))||o.enumerable});return e};var w=(e,n,t)=>(t=e!=null?C(k(e)):{},d(n||!e||!e.__esModule?u(t,"default",{value:e,enumerable:!0}):t,e)),E=e=>d(u({},"__esModule",{value:!0}),e);var M={};R(M,{nextSelection:()=>v,selectedValueOf:()=>h,toSelectionValues:()=>g,toValues:()=>N,useSelection:()=>j});module.exports=E(M);var a=w(require("react"),1),y=require("./is-dev-mode.cjs"),S=require("./useControllableState.cjs");function N(e){return e===void 0?[]:Array.isArray(e)?e:[e]}function A(){try{let e=process.env.NODE_ENV;return e!==void 0&&e!=="production"}catch{return!1}}function p(e){if(A())throw new RangeError(e);(0,y.isDevMode)()&&console.error(e)}function g(e,{multiple:n,label:t}){let o=Array.isArray(e)?e:e==null?[]:[e],r=[];for(let i of o){if(typeof i!="string"){p(`[skdx] ${t}: a selection value must be a string, got ${i===null?"null":typeof i} (${JSON.stringify(i)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}i!==""&&r.push(i)}return n||r.length<=1?r:(p(`[skdx] ${t}: a single-selection control was given ${r.length} values (${r.join(", ")}). Only one can be held \u2014 pass a single value, or turn the control multiple. Set multiple (or type="multiple") to keep them all.`),[r[0]])}function h(e){return e.length>0?e[0]:null}function v(e,n,t,o=!1){return t?e.includes(n)?e.filter(r=>r!==n):[...e,n]:o&&e.length===1&&e[0]===n?[]:[n]}function I(e,n){return e.length===n.length&&e.every((t,o)=>t===n[o])}function j({value:e,defaultValue:n,onValueChange:t,multiple:o=!1,deselectable:r=!1,label:i}){let V=a.useMemo(()=>e===void 0?void 0:g(e,{multiple:o,label:`${i} value`}),[e,o,i]),[s=[],c]=(0,S.useControllableState)({prop:V,defaultProp:g(n,{multiple:o,label:`${i} defaultValue`}),onChange:l=>t?.({value:l,selectedValue:h(l)})}),b=a.useCallback(l=>s.includes(l),[s]),x=a.useCallback(l=>{let f=v(s,l,o,r);I(f,s)||c(f)},[r,o,s,c]),m=a.useCallback(l=>c(g(l,{multiple:o,label:`${i} value`})),[i,o,c]);return{selectedValues:s,isSelected:b,selectItem:x,setSelection:m}}0&&(module.exports={nextSelection,selectedValueOf,toSelectionValues,toValues,useSelection});
+'use client';
+"use strict";var x=Object.create;var S=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var k=Object.getPrototypeOf,D=Object.prototype.hasOwnProperty;var $=(e,n)=>{for(var t in n)S(e,t,{get:n[t],enumerable:!0})},p=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let l of O(n))!D.call(e,l)&&l!==t&&S(e,l,{get:()=>n[l],enumerable:!(o=y(n,l))||o.enumerable});return e};var I=(e,n,t)=>(t=e!=null?x(k(e)):{},p(n||!e||!e.__esModule?S(t,"default",{value:e,enumerable:!0}):t,e)),U=e=>p(S({},"__esModule",{value:!0}),e);var P={};$(P,{nextSelection:()=>c.nextSelection,selectedValueOf:()=>c.selectedValueOf,toSelectionValues:()=>c.toSelectionValues,toValues:()=>c.toValues,useSelection:()=>M});module.exports=U(P);var a=I(require("react"),1),s=require("./selection.cjs"),V=require("./useControllableState.cjs"),c=require("./selection.cjs");function M({value:e,defaultValue:n,onValueChange:t,multiple:o=!1,deselectable:l=!1,label:u}){let C=a.useMemo(()=>e===void 0?void 0:(0,s.toSelectionValues)(e,{multiple:o,label:`${u} value`}),[e,o,u]),d=a.useRef({previousValue:[],reason:"programmatic"}),[v]=a.useState(()=>(0,s.toSelectionValues)(n,{multiple:o,label:`${u} defaultValue`})),[i=[],g]=(0,V.useControllableState)({prop:C,defaultProp:v,onChange:r=>t?.({value:r,selectedValue:(0,s.selectedValueOf)(r),previousValue:d.current.previousValue,reason:d.current.reason})}),R=a.useCallback(r=>i.includes(r),[i]),m=a.useCallback((r,b="programmatic")=>{let f=(0,s.nextSelection)(i,r,o,l);(0,s.sameSelection)(f,i)||(d.current={previousValue:i,reason:b},g(f))},[l,o,i,g]),h=a.useCallback(r=>{d.current={previousValue:i,reason:"programmatic"},g((0,s.toSelectionValues)(r,{multiple:o,label:`${u} value`}))},[u,o,i,g]);return{selectedValues:i,isSelected:R,selectItem:m,setSelection:h}}0&&(module.exports={nextSelection,selectedValueOf,toSelectionValues,toValues,useSelection});

package/dist/utils/useSelection.d.cts

@@ -1,82 +1,17 @@
-/**
- * The canonical single-vs-multiple selection-value rule, copied from
- * `@skdx/shared`'s contract (dev-only dependency, so copied in all five packages).
- * Asymmetric: inputs are lenient (bare `string` or `string[]`), outputs strict
- * (always `string[]` with `selectedValue`). Single-selection controls reject
- * multiple values in dev, silently take the first in production.
- *
- * @see `@skdx/shared`'s `selection-value` contract
- */
-/**
- * Normalizes every selected value to an array. Lenient in for backward compat
- * (Calendar and Transfer); superseded by {@link toSelectionValues} elsewhere.
- */
-export declare function toValues(value: string | string[] | undefined): string[];
-/** Options {@link toSelectionValues} needs to apply the selection-value rule. */
-export interface SelectionValueOptions {
-    /**
-     * Whether the control may hold more than one value at once — `multiple`, or
-     * `type === 'multiple'` on the families that spell it that way.
-     */
-    multiple: boolean;
-    /**
-     * The component and member named in the development error, for example
-     * `Select value` — the message has to say which of a page's selects is
-     * wrong, and a bare stack trace through a normalizer does not.
-     */
-    label: string;
-}
-/**
- * Normalizes every selection value to `string[]`, enforcing the single-selection
- * rule. Called once at the boundary (`value`/`defaultValue` arrival), never
- * again downstream. `undefined`, `null`, `''`, and `[]` all normalize to `[]`.
- * Empty array entries are dropped (silent data corruption otherwise). Rejects
- * non-string entries and multiple values on single-selection controls.
- *
- * @param input the value the consumer supplied, in any accepted shape
- * @param options cardinality and label for errors — see {@link SelectionValueOptions}
- * @returns the selection as an array; at most one element unless `multiple`
- * @throws RangeError in development when entry is not a string or single-select gets multiple values
- */
-export declare function toSelectionValues(input: string | readonly string[] | null | undefined, { multiple, label }: SelectionValueOptions): string[];
-/**
- * The `selectedValue` half of the rule's output: the first selected value,
- * or `null` (not `undefined` or `''`). Pinned here to prevent drift across five implementations.
- *
- * @param values the normalized selection, as {@link toSelectionValues} returns it
- * @returns the first selected value, or `null` when nothing is selected
- */
-export declare function selectedValueOf(values: readonly string[]): string | null;
-/**
- * The new selection after choosing `value`: replaces it, or toggles it within
- * the set when `multiple`. Always returns an array (strict-out rule).
- *
- * @param selected the current selection, already normalized
- * @param value the option value the user committed
- * @param multiple whether choosing toggles within a set rather than replacing
- * @param deselectable whether re-choosing the only selected value clears it (single-select only)
- * @returns the new selection as an array in both cardinalities
- */
-export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
-/** The payload every single-or-many control's change event carries — the selection-value rule's strict-out shape. */
-export interface SelectionChangeDetail {
-    /** The whole selection, always an array, in single and multiple mode alike. */
-    value: string[];
-    /** The first selected value, or `null` when nothing is selected. */
-    selectedValue: string | null;
-}
+import { type SelectionChangeDetail, type SelectionChangeReason } from './selection.cjs';
+export { nextSelection, selectedValueOf, toSelectionValues, toValues, type SelectionChangeDetail, type SelectionChangeReason, type SelectionValueOptions, } from './selection.cjs';
 /** Options for {@link useSelection}. */
 export interface UseSelectionOptions {
     /** Selected value(s), for controlled usage — a bare `string` or a `string[]` under either cardinality. */
-    value?: string | string[];
+    value?: string | string[] | undefined;
     /** Initially selected value(s), for uncontrolled usage — same shapes as `value`. */
-    defaultValue?: string | string[];
+    defaultValue?: string | string[] | undefined;
     /** Fires with the selection-value rule's strict-out change detail whenever the selection changes. */
-    onValueChange?: (detail: SelectionChangeDetail) => void;
+    onValueChange?: ((detail: SelectionChangeDetail) => void) | undefined;
     /** Whether choosing an option toggles it within a set rather than replacing the selection. */
-    multiple?: boolean;
+    multiple?: boolean | undefined;
     /** Whether re-choosing the only selected value clears it; single-selection only. */
-    deselectable?: boolean;
+    deselectable?: boolean | undefined;
     /** Component name used in the selection-value error, e.g. `Select` — the member is appended. */
     label: string;
 }
@@ -87,7 +22,7 @@ export interface Selection {
     /** Whether one option value is currently selected. */
     isSelected: (value: string) => boolean;
     /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
-    selectItem: (value: string) => void;
+    selectItem: (value: string, reason?: SelectionChangeReason) => void;
     /**
      * Replaces the whole selection outright, without going through the
      * replace-or-toggle decision — what a `<form>` reset needs, since it
@@ -95,11 +30,5 @@ export interface Selection {
      */
     setSelection: (value: string | string[]) => void;
 }
-/**
- * Shared selection model for Listbox, Select, Combobox, and toggle families.
- * Handles all three decisions identically: normalize to array, check selection,
- * commit by replace or toggle. Owns only selection; side effects stay in each
- * component (Combobox closes, Select keeps focus, etc.).
- * The selection-value rule's boundary: only place where values are normalized.
- */
+/** Shared selection model for Listbox, Select, Combobox and toggle families, owning only selection normalization; side effects (Combobox closing, Select keeping focus) stay in each component. */
 export declare function useSelection({ value, defaultValue, onValueChange, multiple, deselectable, label, }: UseSelectionOptions): Selection;