@skdx/react 0.26.0 → 0.28.0

package/dist/utils/useFocusTrap.d.ts

@@ -15,11 +15,10 @@ export interface FocusTrapOptions {
     onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
 /**
- * Traps Tab focus inside `containerRef` while `enabled`. Focuses the first
- * tabbable element (or the container) on mount and restores focus to the
- * previously focused element on unmount — each of those two moves first
- * announced as a cancelable `open-auto-focus` / `close-auto-focus` event, so
- * a consumer can redirect initial focus or take over the return when the
- * trigger no longer exists (the WAI-ARIA modal pattern's two escape hatches).
+ * Traps Tab focus inside `containerRef` while `enabled`: focuses the first
+ * tabbable element (or the container) on mount, restores focus on unmount —
+ * each move first announced as a cancelable `open-auto-focus`/`close-auto-focus`
+ * event, so a consumer can redirect initial focus or take over the return
+ * (the WAI-ARIA modal pattern's two escape hatches).
  */
 export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, enabled: boolean, options?: FocusTrapOptions): void;

package/dist/utils/useFocusTrap.js

@@ -1 +1 @@
-import*as r from"react";var E=["a[href]","button:not([disabled])",'input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function b(o){return Array.from(o.querySelectorAll(E)).filter(t=>t.offsetParent!==null||t===document.activeElement)}function v(o,t){if(!t)return!0;let c=new CustomEvent(o,{cancelable:!0,detail:null});return t(c),!c.defaultPrevented}function p(o,t,c={}){let s=r.useRef(c);r.useEffect(()=>{s.current=c}),r.useEffect(()=>{if(!t)return;let e=o.current;if(!e)return;let a=document.activeElement,m=requestAnimationFrame(()=>{if(e.contains(document.activeElement)||!v("open-auto-focus",s.current.onOpenAutoFocus))return;let u=b(e)[0]??e;e.tabIndex=e.tabIndex>=0?e.tabIndex:-1,u.focus({preventScroll:!0})}),i=n=>{if(n.key!=="Tab")return;let u=b(e);if(u.length===0){n.preventDefault();return}let f=u[0],d=u[u.length-1],l=document.activeElement;n.shiftKey&&(l===f||l===e)?(n.preventDefault(),d.focus()):!n.shiftKey&&l===d&&(n.preventDefault(),f.focus())};return e.addEventListener("keydown",i),()=>{cancelAnimationFrame(m),e.removeEventListener("keydown",i),v("close-auto-focus",s.current.onCloseAutoFocus)&&a&&document.contains(a)&&a.focus?.({preventScroll:!0})}},[o,t])}export{v as autoFocusEvent,p as useFocusTrap};
+import*as r from"react";import{TABBABLE_SELECTOR as p}from"./tabbable.js";function v(n){return Array.from(n.querySelectorAll(p)).filter(t=>t.offsetParent!==null||t===document.activeElement)}function E(n,t){if(!t)return!0;let c=new CustomEvent(n,{cancelable:!0,detail:null});return t(c),!c.defaultPrevented}function F(n,t,c={}){let a=r.useRef(c);r.useEffect(()=>{a.current=c}),r.useEffect(()=>{if(!t)return;let e=n.current;if(!e)return;let s=document.activeElement,b=requestAnimationFrame(()=>{if(e.contains(document.activeElement)||!E("open-auto-focus",a.current.onOpenAutoFocus))return;let u=v(e)[0]??e;e.tabIndex=e.tabIndex>=0?e.tabIndex:-1,u.focus({preventScroll:!0})}),f=o=>{if(o.key!=="Tab")return;let u=v(e);if(u.length===0){o.preventDefault();return}let i=u[0],m=u[u.length-1],l=document.activeElement;o.shiftKey&&(l===i||l===e)?(o.preventDefault(),m.focus()):!o.shiftKey&&l===m&&(o.preventDefault(),i.focus())};return e.addEventListener("keydown",f),()=>{cancelAnimationFrame(b),e.removeEventListener("keydown",f),E("close-auto-focus",a.current.onCloseAutoFocus)&&s&&s!==document.body&&document.contains(s)&&s.focus?.({preventScroll:!0})}},[n,t])}export{E as autoFocusEvent,F as useFocusTrap};

package/dist/utils/useMenuItem.cjs

@@ -1 +1 @@
-"use strict";var a=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var m=(e,n)=>{for(var r in n)a(e,r,{get:n[r],enumerable:!0})},s=(e,n,r,i)=>{if(n&&typeof n=="object"||typeof n=="function")for(let t of f(n))!d.call(e,t)&&t!==r&&a(e,t,{get:()=>n[t],enumerable:!(i=l(n,t))||i.enumerable});return e};var v=e=>s(a({},"__esModule",{value:!0}),e);var P={};m(P,{useMenuItem:()=>E});module.exports=v(P);var c=require("./primitive.cjs");function E({disabled:e,onSelect:n,onSelected:r,contentRef:i,props:t}){let u=()=>{if(e)return;let o=new CustomEvent("skdx-menu-item-select",{cancelable:!0});n?.(o),o.defaultPrevented||r()};return{"data-disabled":e?"":void 0,"aria-disabled":e||void 0,tabIndex:e?void 0:-1,onClick:(0,c.composeEventHandlers)(t.onClick,u),onKeyDown:(0,c.composeEventHandlers)(t.onKeyDown,o=>{[" ","Enter"].includes(o.key)&&(o.preventDefault(),u())}),onPointerEnter:(0,c.composeEventHandlers)(t.onPointerEnter,o=>{e||o.currentTarget.focus()}),onPointerLeave:(0,c.composeEventHandlers)(t.onPointerLeave,o=>{o.currentTarget===document.activeElement&&i.current?.focus()})}}0&&(module.exports={useMenuItem});
+"use strict";var l=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var v=Object.prototype.hasOwnProperty;var m=(e,t)=>{for(var r in t)l(e,r,{get:t[r],enumerable:!0})},E=(e,t,r,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of f(t))!v.call(e,o)&&o!==r&&l(e,o,{get:()=>t[o],enumerable:!(a=s(t,o))||a.enumerable});return e};var P=e=>E(l({},"__esModule",{value:!0}),e);var p={};m(p,{useMenuItem:()=>R});module.exports=P(p);var c=require("./primitive.cjs");function R({disabled:e,textValue:t,onSelect:r,onSelected:a,closeOnSelect:o=!0,contentRef:d,props:i}){let u=()=>{if(e)return;let n=new CustomEvent("skdx-menu-item-select",{cancelable:!0});r?.(n),!n.defaultPrevented&&o&&a()};return{"data-disabled":e?"":void 0,"data-text-value":t,"aria-disabled":e||void 0,tabIndex:-1,onClick:(0,c.composeEventHandlers)(i.onClick,u),onKeyDown:(0,c.composeEventHandlers)(i.onKeyDown,n=>{[" ","Enter"].includes(n.key)&&(n.preventDefault(),u())}),onPointerEnter:(0,c.composeEventHandlers)(i.onPointerEnter,n=>{e||n.currentTarget.focus()}),onPointerLeave:(0,c.composeEventHandlers)(i.onPointerLeave,n=>{n.currentTarget===document.activeElement&&d.current?.focus()})}}0&&(module.exports={useMenuItem});

package/dist/utils/useMenuItem.d.cts

@@ -2,8 +2,21 @@ import type * as React from 'react';
 /** @internal Options for {@link useMenuItem}, the shared menu-item interaction hook. */
 export interface UseMenuItemOptions {
     disabled?: boolean;
+    /** Typeahead override, reflected to `data-text-value`. Falls back to the item's rendered text. */
+    textValue?: string;
     /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
     onSelect?: (event: Event) => void;
+    /**
+     * Whether an un-prevented select runs {@link UseMenuItemOptions.onSelected}
+     * — in practice, whether it closes the menu.
+     *
+     * The declarative veto: `onSelect`'s `preventDefault()` is a per-activation
+     * decision, this is a property of the item. Either veto is enough, which
+     * lets `closeOnSelect` default per part (`false` on a checkbox item,
+     * `true` on the rest).
+     * @defaultValue true
+     */
+    closeOnSelect?: boolean;
     /** Called after a select that wasn't prevented — typically closes the menu (and may refocus its trigger). */
     onSelected: () => void;
     /** Where focus returns to on pointer-leave, so keyboard nav resumes at the container. */
@@ -11,15 +24,13 @@ export interface UseMenuItemOptions {
     props: Pick<React.ComponentPropsWithRef<'div'>, 'onClick' | 'onKeyDown' | 'onPointerEnter' | 'onPointerLeave'>;
 }
 /**
- * Shared interaction wiring for DropdownMenuItem, ContextMenuItem, and
- * MenubarItem — the three menu families differ in how a menu opens and
- * closes, but a `menuitem`'s own click/keyboard/hover behavior is identical
- * across all of them.
+ * Shared `menuitem` interaction wiring across all menu families.
  */
-export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, props }: UseMenuItemOptions): {
+export declare function useMenuItem({ disabled, textValue, onSelect, onSelected, closeOnSelect, contentRef, props, }: UseMenuItemOptions): {
     'data-disabled': string | undefined;
+    'data-text-value': string | undefined;
     'aria-disabled': true | undefined;
-    tabIndex: number | undefined;
+    tabIndex: number;
     onClick: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
     onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
     onPointerEnter: (event: React.PointerEvent<HTMLDivElement>) => void;

package/dist/utils/useMenuItem.d.ts

@@ -2,8 +2,21 @@ import type * as React from 'react';
 /** @internal Options for {@link useMenuItem}, the shared menu-item interaction hook. */
 export interface UseMenuItemOptions {
     disabled?: boolean;
+    /** Typeahead override, reflected to `data-text-value`. Falls back to the item's rendered text. */
+    textValue?: string;
     /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
     onSelect?: (event: Event) => void;
+    /**
+     * Whether an un-prevented select runs {@link UseMenuItemOptions.onSelected}
+     * — in practice, whether it closes the menu.
+     *
+     * The declarative veto: `onSelect`'s `preventDefault()` is a per-activation
+     * decision, this is a property of the item. Either veto is enough, which
+     * lets `closeOnSelect` default per part (`false` on a checkbox item,
+     * `true` on the rest).
+     * @defaultValue true
+     */
+    closeOnSelect?: boolean;
     /** Called after a select that wasn't prevented — typically closes the menu (and may refocus its trigger). */
     onSelected: () => void;
     /** Where focus returns to on pointer-leave, so keyboard nav resumes at the container. */
@@ -11,15 +24,13 @@ export interface UseMenuItemOptions {
     props: Pick<React.ComponentPropsWithRef<'div'>, 'onClick' | 'onKeyDown' | 'onPointerEnter' | 'onPointerLeave'>;
 }
 /**
- * Shared interaction wiring for DropdownMenuItem, ContextMenuItem, and
- * MenubarItem — the three menu families differ in how a menu opens and
- * closes, but a `menuitem`'s own click/keyboard/hover behavior is identical
- * across all of them.
+ * Shared `menuitem` interaction wiring across all menu families.
  */
-export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, props }: UseMenuItemOptions): {
+export declare function useMenuItem({ disabled, textValue, onSelect, onSelected, closeOnSelect, contentRef, props, }: UseMenuItemOptions): {
     'data-disabled': string | undefined;
+    'data-text-value': string | undefined;
     'aria-disabled': true | undefined;
-    tabIndex: number | undefined;
+    tabIndex: number;
     onClick: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
     onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
     onPointerEnter: (event: React.PointerEvent<HTMLDivElement>) => void;

package/dist/utils/useMenuItem.js

@@ -1 +1 @@
-import{composeEventHandlers as o}from"./primitive.js";function l({disabled:n,onSelect:c,onSelected:i,contentRef:a,props:t}){let r=()=>{if(n)return;let e=new CustomEvent("skdx-menu-item-select",{cancelable:!0});c?.(e),e.defaultPrevented||i()};return{"data-disabled":n?"":void 0,"aria-disabled":n||void 0,tabIndex:n?void 0:-1,onClick:o(t.onClick,r),onKeyDown:o(t.onKeyDown,e=>{[" ","Enter"].includes(e.key)&&(e.preventDefault(),r())}),onPointerEnter:o(t.onPointerEnter,e=>{n||e.currentTarget.focus()}),onPointerLeave:o(t.onPointerLeave,e=>{e.currentTarget===document.activeElement&&a.current?.focus()})}}export{l as useMenuItem};
+import{composeEventHandlers as o}from"./primitive.js";function s({disabled:t,textValue:c,onSelect:a,onSelected:i,closeOnSelect:l=!0,contentRef:u,props:n}){let r=()=>{if(t)return;let e=new CustomEvent("skdx-menu-item-select",{cancelable:!0});a?.(e),!e.defaultPrevented&&l&&i()};return{"data-disabled":t?"":void 0,"data-text-value":c,"aria-disabled":t||void 0,tabIndex:-1,onClick:o(n.onClick,r),onKeyDown:o(n.onKeyDown,e=>{[" ","Enter"].includes(e.key)&&(e.preventDefault(),r())}),onPointerEnter:o(n.onPointerEnter,e=>{t||e.currentTarget.focus()}),onPointerLeave:o(n.onPointerLeave,e=>{e.currentTarget===document.activeElement&&u.current?.focus()})}}export{s as useMenuItem};

package/dist/utils/useOpenChangeComplete.d.cts

@@ -1,19 +1,11 @@
 import * as React from 'react';
 /**
- * Calls `onOpenChangeComplete` with the new open state once the change has
- * finished on screen — after the content's enter or exit animation ends, or
- * as soon as the content has settled when there is no motion declared (the
- * same task on close, the next frame on open, where the portal needs a second
- * commit to put the element in the DOM).
+ * Calls `onOpenChangeComplete` once the open/close change has settled on screen.
+ * Fires after enter/exit animation ends, or immediately if no motion is declared.
+ * Portal's second commit puts elements in the DOM on open; React clears the ref on close.
  *
- * The settled counterpart to `onOpenChange`, which fires the instant the state
- * flips. Use it for work that must not race the transition: measuring the
- * panel, moving focus after an entrance, or tearing down an expensive child
- * once the exit has played.
- *
- * Pass the ref the content element is attached to. On close without
- * `forceMount` React has already cleared it, which is itself the signal that
- * nothing is animating and the close is complete.
+ * Use for work that must not race the transition: measuring panels, moving focus,
+ * or tearing down expensive children.
  *
  * @example
  * ```tsx

package/dist/utils/useOpenChangeComplete.d.ts

@@ -1,19 +1,11 @@
 import * as React from 'react';
 /**
- * Calls `onOpenChangeComplete` with the new open state once the change has
- * finished on screen — after the content's enter or exit animation ends, or
- * as soon as the content has settled when there is no motion declared (the
- * same task on close, the next frame on open, where the portal needs a second
- * commit to put the element in the DOM).
+ * Calls `onOpenChangeComplete` once the open/close change has settled on screen.
+ * Fires after enter/exit animation ends, or immediately if no motion is declared.
+ * Portal's second commit puts elements in the DOM on open; React clears the ref on close.
  *
- * The settled counterpart to `onOpenChange`, which fires the instant the state
- * flips. Use it for work that must not race the transition: measuring the
- * panel, moving focus after an entrance, or tearing down an expensive child
- * once the exit has played.
- *
- * Pass the ref the content element is attached to. On close without
- * `forceMount` React has already cleared it, which is itself the signal that
- * nothing is animating and the close is complete.
+ * Use for work that must not race the transition: measuring panels, moving focus,
+ * or tearing down expensive children.
  *
  * @example
  * ```tsx

package/dist/utils/useOptionCollection.cjs

@@ -1 +1 @@
-"use strict";var C=Object.create;var O=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var H=Object.getPrototypeOf,L=Object.prototype.hasOwnProperty;var S=(t,i)=>{for(var r in i)O(t,r,{get:i[r],enumerable:!0})},E=(t,i,r,c)=>{if(i&&typeof i=="object"||typeof i=="function")for(let l of M(i))!L.call(t,l)&&l!==r&&O(t,l,{get:()=>i[l],enumerable:!(c=A(i,l))||c.enumerable});return t};var T=(t,i,r)=>(r=t!=null?C(H(t)):{},E(i||!t||!t.__esModule?O(r,"default",{value:t,enumerable:!0}):r,t)),k=t=>E(O({},"__esModule",{value:!0}),t);var U={};S(U,{useOptionCollection:()=>q,useOptionEntry:()=>w});module.exports=k(U);var e=T(require("react"),1),R='[role="option"]:not([data-disabled])';function q({open:t,setOpen:i,contentRef:r}){let[c,l]=e.useState(null),[g,p]=e.useState(()=>new Map),u=e.useRef(null),[x,f]=e.useState(t);t!==x&&(f(t),t||l(null)),e.useEffect(()=>{if(!t)return;let s=requestAnimationFrame(()=>{let o=u.current;if(u.current=null,!o)return;let n=r.current?.querySelectorAll(R);if(!n||n.length===0)return;let m=o==="last"?n[n.length-1]:n[0];l(a=>a??m.id)});return()=>cancelAnimationFrame(s)},[t,r]),e.useLayoutEffect(()=>{if(c===null)return;let s=Array.from(r.current?.querySelectorAll(R)??[]);s.some(o=>o.id===c)||l(s[0]?.id??null)});let d=e.useCallback((s,o)=>{p(n=>{let m=n.get(s);if(m?.value===o.value&&m.text===o.text)return n;let a=new Map(n);return a.set(s,o),a})},[]),v=e.useCallback(s=>{p(o=>{if(!o.has(s))return o;let n=new Map(o);return n.delete(s),n})},[]),I=e.useCallback(s=>g.get(s),[g]),y=e.useCallback(s=>{u.current=s,i(!0)},[i]),b=e.useCallback(s=>{let o=r.current;if(!o)return;let n=Array.from(o.querySelectorAll(R));if(n.length===0)return;let a=n.findIndex(h=>h.id===c)+s;a<0&&(a=0),a>=n.length&&(a=n.length-1),l(n[a].id)},[c,r]);return{activeId:c,setActiveId:l,itemCount:g.size,registerItem:d,unregisterItem:v,getItem:I,openWithHighlight:y,moveActive:b}}function w({id:t,value:i,textValue:r,itemRef:c,matchesFilter:l,registerItem:g,unregisterItem:p}){let[u,x]=e.useState(r??null);e.useLayoutEffect(()=>{let d=r??c.current?.textContent;d!=null&&d!==u&&x(d)});let f=u===null||l(u);return e.useEffect(()=>{if(f)return g(t,{value:i,text:u??""}),()=>p(t)},[t,f,i,u]),{text:u,visible:f}}0&&(module.exports={useOptionCollection,useOptionEntry});
+"use strict";var w=Object.create;var b=Object.defineProperty;var B=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var q=Object.getPrototypeOf,F=Object.prototype.hasOwnProperty;var W=(t,l)=>{for(var n in l)b(t,n,{get:l[n],enumerable:!0})},y=(t,l,n,u)=>{if(l&&typeof l=="object"||typeof l=="function")for(let o of U(l))!F.call(t,o)&&o!==n&&b(t,o,{get:()=>l[o],enumerable:!(u=B(l,o))||u.enumerable});return t};var j=(t,l,n)=>(n=t!=null?w(q(t)):{},y(l||!t||!t.__esModule?b(n,"default",{value:t,enumerable:!0}):n,t)),P=t=>y(b({},"__esModule",{value:!0}),t);var V={};W(V,{OPTION_SELECTOR:()=>C,useOptionCollection:()=>D,useOptionEntry:()=>N});module.exports=P(V);var r=j(require("react"),1),v=require("./scoredFilter.cjs"),C='[role="option"]:not([data-disabled])';function z(t,l){let n=t.querySelector('[data-part="viewport"]')??t;if(n===l||!n.contains(l))return;let u=n.getBoundingClientRect(),o=l.getBoundingClientRect();n.scrollTop+=o.top-u.top-(u.height-o.height)/2}function D({open:t,setOpen:l,contentRef:n,loop:u=!1,scoreItem:o}){let[g,d]=r.useState(null),[c,O]=r.useState(()=>new Map),m=r.useRef(null),p=r.useMemo(()=>o?(0,v.rankByScore)([...c.keys()],e=>{let s=c.get(e);return s?o(s):null}):null,[c,o]),h=r.useCallback(e=>(0,v.sortByOrder)(Array.from(e?.querySelectorAll(C)??[]),p),[p]),[M,I]=r.useState(t);t!==M&&(I(t),t||d(null)),r.useEffect(()=>{if(!t)return;let e=requestAnimationFrame(()=>{let s=m.current;if(m.current=null,!s)return;let i=n.current,a=h(i);if(!i||a.length===0)return;let f=s==="last"?a[a.length-1]:a[0],E=!1;d(x=>x!==null?x:(E=!0,f.id)),E&&z(i,f)});return()=>cancelAnimationFrame(e)},[t,n,h]),r.useLayoutEffect(()=>{if(g===null)return;let e=h(n.current);e.some(s=>s.id===g)||d(e[0]?.id??null)});let T=r.useCallback((e,s)=>{O(i=>{let a=i.get(e);if(a?.value===s.value&&a.text===s.text)return i;let f=new Map(i);return f.set(e,s),f})},[]),H=r.useCallback(e=>{O(s=>{if(!s.has(e))return s;let i=new Map(s);return i.delete(e),i})},[]),L=r.useCallback(e=>c.get(e),[c]),k=r.useCallback(e=>{m.current=e,l(!0)},[l]),R=r.useCallback(e=>(d(e.id),e.scrollIntoView?.({block:"nearest"}),e.id),[]),A=r.useCallback(e=>{let s=n.current;if(!s)return null;let i=h(s);if(i.length===0)return null;let a=i.findIndex(x=>x.id===g),f=a===-1?e===1?-1:0:a,E=u?(f+e+i.length)%i.length:Math.min(i.length-1,Math.max(0,f+e));return R(i[E])},[g,n,R,u,h]),S=r.useCallback(e=>{let s=n.current;if(!s)return null;let i=h(s);return i.length===0?null:R(e==="last"?i[i.length-1]:i[0])},[n,R,h]);return{activeId:g,itemOrder:p,setActiveId:d,itemCount:c.size,registerItem:T,unregisterItem:H,getItem:L,openWithHighlight:k,moveActive:A,moveActiveToEdge:S}}function N({id:t,value:l,textValue:n,itemRef:u,matchesFilter:o,registerItem:g,unregisterItem:d}){let[c,O]=r.useState(n??null);r.useLayoutEffect(()=>{let p=n??u.current?.textContent;p!=null&&p!==c&&O(p)});let m=c===null||o(c);return r.useEffect(()=>{if(m)return g(t,{value:l,text:c??""}),()=>d(t)},[t,m,l,c,g,d]),{text:c,visible:m}}0&&(module.exports={OPTION_SELECTOR,useOptionCollection,useOptionEntry});

package/dist/utils/useOptionCollection.d.cts

@@ -1,4 +1,11 @@
 import * as React from 'react';
+/**
+ * Enabled options, the same string Combobox, Listbox and Transfer each declare
+ * for themselves. Duplicated rather than imported across folders on purpose:
+ * every component folder is its own bundle, so reaching into another one for a
+ * one-line constant would pull that whole bundle in behind it.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /**
  * The virtual-focus option collection behind every listbox-with-a-textbox in
  * this package — `Combobox`, `Autocomplete`, `MultiSelect`.
@@ -32,11 +39,37 @@ export interface UseOptionCollectionOptions {
     setOpen: (open: boolean) => void;
     /** The popup element the options are rendered inside; read directly for highlight moves. */
     contentRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Whether {@link OptionCollection.moveActive} wraps around the ends of the
+     * list instead of clamping at them.
+     *
+     * Defaults to `false` — the behaviour every caller had before this existed —
+     * so a root opts in rather than being changed underneath. `Autocomplete`
+     * passes its own `loop` prop (which defaults `true`); `MultiSelect` does not
+     * pass one and keeps clamping.
+     *
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Scores a registered entry for ranking: return a number to
+     * rank it, `null` to leave it unscored. Omit for a family with no ranking
+     * filter — the collection then never reorders.
+     * @default undefined — no ranking.
+     */
+    scoreItem?: (entry: OptionEntry) => number | null;
 }
 /** @internal What {@link useOptionCollection} hands back to a root's context. */
 export interface OptionCollection {
     /** Element id of the virtually-focused option, mirrored into the input's `aria-activedescendant`. */
     activeId: string | null;
+    /**
+     * Rank (`0` = first) each currently-visible option traverses and renders in
+     * when `scoreItem` also scores it — descending by score, ties keeping
+     * registration order. `null` when nothing scored numerically, leaving
+     * traversal and visual order untouched.
+     */
+    itemOrder: ReadonlyMap<string, number> | null;
     /** Moves the virtual focus, or clears it with `null`. */
     setActiveId: (id: string | null) => void;
     /** How many options are currently registered (i.e. rendered and surviving the filter). */
@@ -49,10 +82,27 @@ export interface OptionCollection {
     getItem: (id: string) => OptionEntry | undefined;
     /** Opens the popup and, once its options are mounted, highlights the first (or last) one. */
     openWithHighlight: (edge: 'first' | 'last') => void;
-    /** Moves the highlight one option forward (`1`) or back (`-1`), clamped at both ends. */
-    moveActive: (direction: 1 | -1) => void;
+    /**
+     * Moves the highlight one option forward (`1`) or back (`-1`) — wrapping
+     * around the ends when the root asked to `loop`, clamped at them otherwise —
+     * and scrolls the newly highlighted option into view.
+     *
+     * @returns the element id now highlighted, or `null` when there was nothing
+     * to move to. Callers that also act on the option they landed on — a
+     * multi-select extending its selection with Shift+Arrow — need the id, and
+     * reading `activeId` back would give them the value from before this call.
+     */
+    moveActive: (direction: 1 | -1) => string | null;
+    /**
+     * Moves the highlight to the first or last option and scrolls it into view —
+     * Home and End, which are only ever handled while the popup is open, since
+     * closed they are the text field's own caret keys.
+     *
+     * @returns the element id now highlighted, or `null` when the list is empty.
+     */
+    moveActiveToEdge: (edge: 'first' | 'last') => string | null;
 }
-export declare function useOptionCollection({ open, setOpen, contentRef, }: UseOptionCollectionOptions): OptionCollection;
+export declare function useOptionCollection({ open, setOpen, contentRef, loop, scoreItem, }: UseOptionCollectionOptions): OptionCollection;
 /** @internal Parameters for {@link useOptionEntry}. */
 export interface UseOptionEntryOptions {
     /** This option's element id — the value the input's `aria-activedescendant` carries while it is highlighted. */

package/dist/utils/useOptionCollection.d.ts

@@ -1,4 +1,11 @@
 import * as React from 'react';
+/**
+ * Enabled options, the same string Combobox, Listbox and Transfer each declare
+ * for themselves. Duplicated rather than imported across folders on purpose:
+ * every component folder is its own bundle, so reaching into another one for a
+ * one-line constant would pull that whole bundle in behind it.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /**
  * The virtual-focus option collection behind every listbox-with-a-textbox in
  * this package — `Combobox`, `Autocomplete`, `MultiSelect`.
@@ -32,11 +39,37 @@ export interface UseOptionCollectionOptions {
     setOpen: (open: boolean) => void;
     /** The popup element the options are rendered inside; read directly for highlight moves. */
     contentRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Whether {@link OptionCollection.moveActive} wraps around the ends of the
+     * list instead of clamping at them.
+     *
+     * Defaults to `false` — the behaviour every caller had before this existed —
+     * so a root opts in rather than being changed underneath. `Autocomplete`
+     * passes its own `loop` prop (which defaults `true`); `MultiSelect` does not
+     * pass one and keeps clamping.
+     *
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Scores a registered entry for ranking: return a number to
+     * rank it, `null` to leave it unscored. Omit for a family with no ranking
+     * filter — the collection then never reorders.
+     * @default undefined — no ranking.
+     */
+    scoreItem?: (entry: OptionEntry) => number | null;
 }
 /** @internal What {@link useOptionCollection} hands back to a root's context. */
 export interface OptionCollection {
     /** Element id of the virtually-focused option, mirrored into the input's `aria-activedescendant`. */
     activeId: string | null;
+    /**
+     * Rank (`0` = first) each currently-visible option traverses and renders in
+     * when `scoreItem` also scores it — descending by score, ties keeping
+     * registration order. `null` when nothing scored numerically, leaving
+     * traversal and visual order untouched.
+     */
+    itemOrder: ReadonlyMap<string, number> | null;
     /** Moves the virtual focus, or clears it with `null`. */
     setActiveId: (id: string | null) => void;
     /** How many options are currently registered (i.e. rendered and surviving the filter). */
@@ -49,10 +82,27 @@ export interface OptionCollection {
     getItem: (id: string) => OptionEntry | undefined;
     /** Opens the popup and, once its options are mounted, highlights the first (or last) one. */
     openWithHighlight: (edge: 'first' | 'last') => void;
-    /** Moves the highlight one option forward (`1`) or back (`-1`), clamped at both ends. */
-    moveActive: (direction: 1 | -1) => void;
+    /**
+     * Moves the highlight one option forward (`1`) or back (`-1`) — wrapping
+     * around the ends when the root asked to `loop`, clamped at them otherwise —
+     * and scrolls the newly highlighted option into view.
+     *
+     * @returns the element id now highlighted, or `null` when there was nothing
+     * to move to. Callers that also act on the option they landed on — a
+     * multi-select extending its selection with Shift+Arrow — need the id, and
+     * reading `activeId` back would give them the value from before this call.
+     */
+    moveActive: (direction: 1 | -1) => string | null;
+    /**
+     * Moves the highlight to the first or last option and scrolls it into view —
+     * Home and End, which are only ever handled while the popup is open, since
+     * closed they are the text field's own caret keys.
+     *
+     * @returns the element id now highlighted, or `null` when the list is empty.
+     */
+    moveActiveToEdge: (edge: 'first' | 'last') => string | null;
 }
-export declare function useOptionCollection({ open, setOpen, contentRef, }: UseOptionCollectionOptions): OptionCollection;
+export declare function useOptionCollection({ open, setOpen, contentRef, loop, scoreItem, }: UseOptionCollectionOptions): OptionCollection;
 /** @internal Parameters for {@link useOptionEntry}. */
 export interface UseOptionEntryOptions {
     /** This option's element id — the value the input's `aria-activedescendant` carries while it is highlighted. */

package/dist/utils/useOptionCollection.js

@@ -1 +1 @@
-import*as t from"react";var x='[role="option"]:not([data-disabled])';function b({open:r,setOpen:a,contentRef:l}){let[c,u]=t.useState(null),[g,p]=t.useState(()=>new Map),s=t.useRef(null),[O,f]=t.useState(r);r!==O&&(f(r),r||u(null)),t.useEffect(()=>{if(!r)return;let n=requestAnimationFrame(()=>{let i=s.current;if(s.current=null,!i)return;let e=l.current?.querySelectorAll(x);if(!e||e.length===0)return;let m=i==="last"?e[e.length-1]:e[0];u(o=>o??m.id)});return()=>cancelAnimationFrame(n)},[r,l]),t.useLayoutEffect(()=>{if(c===null)return;let n=Array.from(l.current?.querySelectorAll(x)??[]);n.some(i=>i.id===c)||u(n[0]?.id??null)});let d=t.useCallback((n,i)=>{p(e=>{let m=e.get(n);if(m?.value===i.value&&m.text===i.text)return e;let o=new Map(e);return o.set(n,i),o})},[]),R=t.useCallback(n=>{p(i=>{if(!i.has(n))return i;let e=new Map(i);return e.delete(n),e})},[]),E=t.useCallback(n=>g.get(n),[g]),v=t.useCallback(n=>{s.current=n,a(!0)},[a]),I=t.useCallback(n=>{let i=l.current;if(!i)return;let e=Array.from(i.querySelectorAll(x));if(e.length===0)return;let o=e.findIndex(y=>y.id===c)+n;o<0&&(o=0),o>=e.length&&(o=e.length-1),u(e[o].id)},[c,l]);return{activeId:c,setActiveId:u,itemCount:g.size,registerItem:d,unregisterItem:R,getItem:E,openWithHighlight:v,moveActive:I}}function h({id:r,value:a,textValue:l,itemRef:c,matchesFilter:u,registerItem:g,unregisterItem:p}){let[s,O]=t.useState(l??null);t.useLayoutEffect(()=>{let d=l??c.current?.textContent;d!=null&&d!==s&&O(d)});let f=s===null||u(s);return t.useEffect(()=>{if(f)return g(r,{value:a,text:s??""}),()=>p(r)},[r,f,a,s]),{text:s,visible:f}}export{b as useOptionCollection,h as useOptionEntry};
+import*as e from"react";import{rankByScore as L,sortByOrder as k}from"./scoredFilter.js";var A='[role="option"]:not([data-disabled])';function S(l,c){let i=l.querySelector('[data-part="viewport"]')??l;if(i===c||!i.contains(c))return;let f=i.getBoundingClientRect(),u=c.getBoundingClientRect();i.scrollTop+=u.top-f.top-(f.height-u.height)/2}function B({open:l,setOpen:c,contentRef:i,loop:f=!1,scoreItem:u}){let[a,g]=e.useState(null),[s,O]=e.useState(()=>new Map),m=e.useRef(null),p=e.useMemo(()=>u?L([...s.keys()],t=>{let r=s.get(t);return r?u(r):null}):null,[s,u]),h=e.useCallback(t=>k(Array.from(t?.querySelectorAll(A)??[]),p),[p]),[b,v]=e.useState(l);l!==b&&(v(l),l||g(null)),e.useEffect(()=>{if(!l)return;let t=requestAnimationFrame(()=>{let r=m.current;if(m.current=null,!r)return;let n=i.current,o=h(n);if(!n||o.length===0)return;let d=r==="last"?o[o.length-1]:o[0],E=!1;g(x=>x!==null?x:(E=!0,d.id)),E&&S(n,d)});return()=>cancelAnimationFrame(t)},[l,i,h]),e.useLayoutEffect(()=>{if(a===null)return;let t=h(i.current);t.some(r=>r.id===a)||g(t[0]?.id??null)});let y=e.useCallback((t,r)=>{O(n=>{let o=n.get(t);if(o?.value===r.value&&o.text===r.text)return n;let d=new Map(n);return d.set(t,r),d})},[]),C=e.useCallback(t=>{O(r=>{if(!r.has(t))return r;let n=new Map(r);return n.delete(t),n})},[]),M=e.useCallback(t=>s.get(t),[s]),I=e.useCallback(t=>{m.current=t,c(!0)},[c]),R=e.useCallback(t=>(g(t.id),t.scrollIntoView?.({block:"nearest"}),t.id),[]),T=e.useCallback(t=>{let r=i.current;if(!r)return null;let n=h(r);if(n.length===0)return null;let o=n.findIndex(x=>x.id===a),d=o===-1?t===1?-1:0:o,E=f?(d+t+n.length)%n.length:Math.min(n.length-1,Math.max(0,d+t));return R(n[E])},[a,i,R,f,h]),H=e.useCallback(t=>{let r=i.current;if(!r)return null;let n=h(r);return n.length===0?null:R(t==="last"?n[n.length-1]:n[0])},[i,R,h]);return{activeId:a,itemOrder:p,setActiveId:g,itemCount:s.size,registerItem:y,unregisterItem:C,getItem:M,openWithHighlight:I,moveActive:T,moveActiveToEdge:H}}function U({id:l,value:c,textValue:i,itemRef:f,matchesFilter:u,registerItem:a,unregisterItem:g}){let[s,O]=e.useState(i??null);e.useLayoutEffect(()=>{let p=i??f.current?.textContent;p!=null&&p!==s&&O(p)});let m=s===null||u(s);return e.useEffect(()=>{if(m)return a(l,{value:c,text:s??""}),()=>g(l)},[l,m,c,s,a,g]),{text:s,visible:m}}export{A as OPTION_SELECTOR,B as useOptionCollection,U as useOptionEntry};

package/dist/utils/useOutsideInert.cjs

@@ -0,0 +1 @@
+"use strict";var a=Object.create;var c=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var b=Object.getPrototypeOf,E=Object.prototype.hasOwnProperty;var p=(t,e)=>{for(var n in e)c(t,n,{get:e[n],enumerable:!0})},u=(t,e,n,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of d(e))!E.call(t,r)&&r!==n&&c(t,r,{get:()=>e[r],enumerable:!(i=m(e,r))||i.enumerable});return t};var w=(t,e,n)=>(n=t!=null?a(b(t)):{},u(e||!t||!t.__esModule?c(n,"default",{value:t,enumerable:!0}):n,t)),h=t=>u(c({},"__esModule",{value:!0}),t);var I={};p(I,{releaseOutsideInert:()=>A,useOutsideInert:()=>v});module.exports=h(I);var f=w(require("react"),1),o=new Map,l=new Set;function y(t){let e=t.ownerDocument.body,n=t;for(;n.parentElement&&n.parentElement!==e;)n=n.parentElement;return n.parentElement===e?n:null}function s(t){if(l.size===0){for(let[e,n]of o)n||e.removeAttribute("inert");o.clear();return}for(let e of Array.from(t.children)){if(l.has(e)){let n=o.get(e);n!==void 0&&(n||e.removeAttribute("inert"),o.delete(e));continue}o.has(e)||(o.set(e,e.hasAttribute("inert")),e.setAttribute("inert",""))}}function v(t,e){f.useEffect(()=>{if(!e)return;let n=t.current;if(!n)return;let i=y(n);if(!i)return;let r=n.ownerDocument.body;return l.add(i),s(r),()=>{l.delete(i),s(r)}},[t,e])}function A(){for(let[t,e]of o)e||t.removeAttribute("inert");o.clear()}0&&(module.exports={releaseOutsideInert,useOutsideInert});

package/dist/utils/useOutsideInert.d.cts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+/**
+ * Marks everything outside the overlay's portal container `inert` while enabled.
+ * Stackable: nested overlays each keep their own container live. `enabled`
+ * must be `false` for non-modal overlays (inertness behind adjacent panels
+ * contradicts their purpose).
+ *
+ * @param contentRef ref to overlay panel; nearest `<body>` child stays interactive
+ * @param enabled whether the overlay is currently open and modal
+ */
+export declare function useOutsideInert(contentRef: React.RefObject<HTMLElement | null>, enabled: boolean): void;
+/**
+ * Clears `inert` marks synchronously, before effect cleanup (for overlays that
+ * return focus to trigger from event handler). Event handlers run before React's
+ * passive cleanup; without this, the trigger would still be inert.
+ * (DropdownMenu: WAI-ARIA menu pattern has Tab close and focus trigger before
+ * browser continues tab sequence, before passive cleanup runs.)
+ * Used on close path only; next `useOutsideInert` cleanup re-syncs from exempt set.
+ */
+export declare function releaseOutsideInert(): void;

package/dist/utils/useOutsideInert.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+/**
+ * Marks everything outside the overlay's portal container `inert` while enabled.
+ * Stackable: nested overlays each keep their own container live. `enabled`
+ * must be `false` for non-modal overlays (inertness behind adjacent panels
+ * contradicts their purpose).
+ *
+ * @param contentRef ref to overlay panel; nearest `<body>` child stays interactive
+ * @param enabled whether the overlay is currently open and modal
+ */
+export declare function useOutsideInert(contentRef: React.RefObject<HTMLElement | null>, enabled: boolean): void;
+/**
+ * Clears `inert` marks synchronously, before effect cleanup (for overlays that
+ * return focus to trigger from event handler). Event handlers run before React's
+ * passive cleanup; without this, the trigger would still be inert.
+ * (DropdownMenu: WAI-ARIA menu pattern has Tab close and focus trigger before
+ * browser continues tab sequence, before passive cleanup runs.)
+ * Used on close path only; next `useOutsideInert` cleanup re-syncs from exempt set.
+ */
+export declare function releaseOutsideInert(): void;

package/dist/utils/useOutsideInert.js

@@ -0,0 +1 @@
+import*as u from"react";var r=new Map,o=new Set;function s(n){let e=n.ownerDocument.body,t=n;for(;t.parentElement&&t.parentElement!==e;)t=t.parentElement;return t.parentElement===e?t:null}function l(n){if(o.size===0){for(let[e,t]of r)t||e.removeAttribute("inert");r.clear();return}for(let e of Array.from(n.children)){if(o.has(e)){let t=r.get(e);t!==void 0&&(t||e.removeAttribute("inert"),r.delete(e));continue}r.has(e)||(r.set(e,e.hasAttribute("inert")),e.setAttribute("inert",""))}}function f(n,e){u.useEffect(()=>{if(!e)return;let t=n.current;if(!t)return;let i=s(t);if(!i)return;let c=t.ownerDocument.body;return o.add(i),l(c),()=>{o.delete(i),l(c)}},[n,e])}function a(){for(let[n,e]of r)e||n.removeAttribute("inert");r.clear()}export{a as releaseOutsideInert,f as useOutsideInert};

package/dist/utils/useRovingFocus.cjs

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

package/dist/utils/useRovingFocus.d.cts

@@ -6,8 +6,40 @@ interface UseRovingFocusOptions {
     loop?: boolean;
     /** CSS selector matching focusable items inside the group. */
     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;
 }
 /**
  * The text typeahead matches an item against: its explicit `data-text-value`
@@ -79,5 +111,5 @@ export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, di
  * toolbars). Returns a keydown handler to spread on the group element.
  * Items are discovered by selector, so no registration plumbing is needed.
  */
-export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
+export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
 export {};

package/dist/utils/useRovingFocus.d.ts

@@ -6,8 +6,40 @@ interface UseRovingFocusOptions {
     loop?: boolean;
     /** CSS selector matching focusable items inside the group. */
     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;
 }
 /**
  * The text typeahead matches an item against: its explicit `data-text-value`
@@ -79,5 +111,5 @@ export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, di
  * toolbars). Returns a keydown handler to spread on the group element.
  * Items are discovered by selector, so no registration plumbing is needed.
  */
-export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
+export declare function useRovingFocus({ orientation, loop, itemSelector, scopeSelector, typeahead, includeDisabled, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
 export {};

package/dist/utils/useRovingFocus.js

@@ -1 +1 @@
-import*as o from"react";import{directionalKey as T,useDirection as A}from"./direction.js";var E=1e3;function y(r){return r.getAttribute("data-text-value")??r.textContent??""}function L(r,i,s,u,l){o.useLayoutEffect(()=>{let c=Array.from(r.current?.querySelectorAll(i)??[],e=>e.getAttribute(s)).filter(e=>e!==null&&e!==""),a=c[0];a===void 0||u!==null&&c.includes(u)||l(a)})}function H(r,i,s=!1){return r||s?i?0:-1:0}var p={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},x={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function M({orientation:r="both",loop:i=!0,itemSelector:s,typeahead:u=!1}){let l=o.useRef(""),c=o.useRef(void 0),a=A();return o.useEffect(()=>()=>clearTimeout(c.current),[]),o.useCallback(e=>{let m=e.currentTarget,n=Array.from(m.querySelectorAll(s)).filter(g=>!g.hasAttribute("disabled")&&g.getAttribute("data-disabled")===null);if(n.length===0)return;let f=n.indexOf(e.target),d=T(e.key,m,a),t;if(p[r].includes(d))t=f+1,t>=n.length&&(t=i?0:n.length-1);else if(x[r].includes(d))t=f-1,t<0&&(t=i?n.length-1:0);else if(d==="Home")t=0;else if(d==="End")t=n.length-1;else if(u&&e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey){clearTimeout(c.current),l.current+=e.key.toLowerCase(),c.current=setTimeout(()=>{l.current=""},E);let g=l.current,R=h=>y(h).trim().toLowerCase().startsWith(g),b=[...n.slice(f+1),...n.slice(0,f+1)].find(R);b&&(t=n.indexOf(b))}t!==void 0&&(e.preventDefault(),n[t]?.focus())},[r,i,s,u,a])}export{y as itemText,H as rovingTabIndex,M as useRovingFocus,L as useRovingTabStop};
+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};

package/dist/utils/useSelection.cjs

@@ -1 +1 @@
-"use strict";var m=Object.create;var a=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var R=Object.getPrototypeOf,k=Object.prototype.hasOwnProperty;var V=(e,t)=>{for(var n in t)a(e,n,{get:t[n],enumerable:!0})},g=(e,t,n,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of x(t))!k.call(e,r)&&r!==n&&a(e,r,{get:()=>t[r],enumerable:!(i=C(t,r))||i.enumerable});return e};var h=(e,t,n)=>(n=e!=null?m(R(e)):{},g(t||!e||!e.__esModule?a(n,"default",{value:e,enumerable:!0}):n,e)),v=e=>g(a({},"__esModule",{value:!0}),e);var A={};V(A,{nextSelection:()=>d,toValues:()=>f,useSelection:()=>y});module.exports=v(A);var s=h(require("react"),1),u=require("./useControllableState.cjs");function f(e){return e===void 0?[]:Array.isArray(e)?e:[e]}function d(e,t,n){return n?e.includes(t)?e.filter(i=>i!==t):[...e,t]:t}function y({value:e,defaultValue:t,onValueChange:n,multiple:i=!1}){let[r,l]=(0,u.useControllableState)({prop:e,defaultProp:t,onChange:n}),o=s.useMemo(()=>f(r),[r]),p=s.useCallback(c=>o.includes(c),[o]),S=s.useCallback(c=>l(d(o,c,i)),[i,o,l]),b=s.useCallback(c=>l(c),[l]);return{selectedValues:o,isSelected:p,selectItem:S,setSelection:b}}0&&(module.exports={nextSelection,toValues,useSelection});
+"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});