@skdx/react 0.27.0 → 0.29.0

package/dist/utils/useDismiss.d.ts

@@ -1,47 +1,27 @@
 import * as React from 'react';
-/**
- * What `onFocusOutside` receives. `focusin` is not cancelable, so there would
- * be nothing to `preventDefault()` on the real event — the handler gets a
- * cancelable stand-in carrying the original as its `detail` instead.
- */
-export type FocusOutsideEvent = CustomEvent<FocusEvent>;
-/** Either flavour of outside interaction, as `onInteractOutside` sees it. */
-export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+import { type FocusOutsideEvent, type InteractOutsideEvent } from './dismissal.js';
+export type { FocusOutsideEvent, InteractOutsideEvent } from './dismissal.js';
 interface UseDismissOptions {
     /** Whether dismiss listeners are active (usually the open state). */
     enabled: boolean;
     /** Called on Escape keydown. */
-    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    onEscapeKeyDown?: ((event: KeyboardEvent) => void) | undefined;
     /** Called on pointerdown outside every element in `insideRefs`. */
-    onPointerDownOutside?: (event: PointerEvent) => void;
+    onPointerDownOutside?: ((event: PointerEvent) => void) | undefined;
     /** Called when focus moves to an element outside every element in `insideRefs`. */
-    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    onFocusOutside?: ((event: FocusOutsideEvent) => void) | undefined;
     /**
-     * Called for *either* kind of outside interaction, immediately **before**
-     * the specific handler above and with the same event object — so a single
-     * `preventDefault()` here is already visible to that handler and vetoes the
-     * dismissal whichever way it was triggered.
+     * Called for either kind of outside interaction, immediately before the
+     * specific handler above, with the same event object — so a single
+     * `preventDefault()` here vetoes the dismissal either way.
      */
-    onInteractOutside?: (event: InteractOutsideEvent) => void;
+    onInteractOutside?: ((event: InteractOutsideEvent) => void) | undefined;
     /**
-     * Extra "inside" region, as a selector the target is matched against with
-     * `closest()`. `insideRefs` covers the elements the layer holds a ref to; this
-     * covers the ones it does not — a submenu panel portalled out of the menu it
-     * belongs to is not `contains()`-reachable from the menu's content ref, yet a
-     * pointer-down or a focus landing in it is unambiguously inside the menu.
+     * Extra "inside" region, as a selector matched against the target with
+     * `closest()` — for elements `insideRefs` can't reach, like a submenu panel
+     * portalled out of the menu it belongs to.
      */
-    insideSelector?: string;
+    insideSelector?: string | undefined;
 }
-/**
- * Layer dismissal behavior shared by every dismissible overlay. Consumers pass
- * refs of elements that count as "inside" — which for the input-driven
- * families (Combobox, Autocomplete, MultiSelect, TreeSelect) includes the
- * input and any toggle button, not just the floating panel: real DOM focus
- * lives out there for the whole interaction.
- *
- * This hook only *reports*: the caller decides what dismissal means (Dialog
- * ignores outside interaction unless modal, AlertDialog ignores it entirely)
- * by checking `event.defaultPrevented` in its own handler.
- */
+/** Layer dismissal behavior shared by every dismissible overlay; only reports, since the caller decides dismissal meaning by checking `event.defaultPrevented`. */
 export declare function useDismiss({ enabled, onEscapeKeyDown, onPointerDownOutside, onFocusOutside, onInteractOutside, insideSelector, }: UseDismissOptions, insideRefs: Array<React.RefObject<Element | null>>): void;
-export {};

package/dist/utils/useDismiss.js

@@ -1 +1,2 @@
-import*as O from"react";import{useCallbackRef as r}from"./useCallbackRef.js";var o=[];function I({enabled:d,onEscapeKeyDown:w,onPointerDownOutside:y,onFocusOutside:b,onInteractOutside:D,insideSelector:i},F){let a=r(w),E=r(y),l=r(b),u=r(D);O.useEffect(()=>{if(!d)return;let n=globalThis.document,c={};o.push(c);let v=e=>{if(F.some(s=>s.current?.contains(e)))return!1;let t=e.nodeType===Node.ELEMENT_NODE?e:e.parentElement;return!(i&&t?.closest(i))},f=e=>{e.key==="Escape"&&o[o.length-1]===c&&a(e)},m=e=>{let t=e.target;t&&v(t)&&(u(e),E(e))},p=e=>{let t=e.target;if(!t||t===n.body||!v(t))return;let s=new CustomEvent("focus-outside",{detail:e,cancelable:!0});u(s),l(s)};n.addEventListener("keydown",f);let h=window.setTimeout(()=>{n.addEventListener("pointerdown",m,!0),n.addEventListener("focusin",p,!0)},0);return()=>{let e=o.indexOf(c);e!==-1&&o.splice(e,1),n.removeEventListener("keydown",f),window.clearTimeout(h),n.removeEventListener("pointerdown",m,!0),n.removeEventListener("focusin",p,!0)}},[d,a,E,l,u,i])}export{I as useDismiss};
+'use client';
+import*as L from"react";import{focusOutsideEvent as T,focusOutsideTarget as N,handleEscapeKeyDown as P,pushDismissLayer as R}from"./dismissal.js";import{useCallbackRef as t}from"./useCallbackRef.js";function k({enabled:u,onEscapeKeyDown:c,onPointerDownOutside:h,onFocusOutside:I,onInteractOutside:F,insideSelector:a},E){let f=t(c),m=c!==void 0,v=t(()=>E),l=t(h),p=t(I),i=t(F),r=t(e=>{if(E.some(d=>d.current?.contains(e)))return!1;let o=e.nodeType===Node.ELEMENT_NODE?e:e.parentElement;return!(a&&o?.closest(a))});L.useEffect(()=>{if(!u)return;let e=globalThis.document,o={insideElements:()=>v().map(n=>n.current)},d=R(o),O=n=>{P(n,o,m?f:void 0)},y=n=>{let s=n.target;s&&r(s)&&(i(n),l(n))},w=n=>{let s=N(n);if(!s||!r(s))return;let D=T(n);i(D),p(D)};e.addEventListener("keydown",O);let b=window.setTimeout(()=>{e.addEventListener("pointerdown",y,!0),e.addEventListener("focusin",w,!0)},0);return()=>{d(),e.removeEventListener("keydown",O),window.clearTimeout(b),e.removeEventListener("pointerdown",y,!0),e.removeEventListener("focusin",w,!0)}},[u,m,f,l,p,i,r,v])}export{k as useDismiss};

package/dist/utils/useFocusTrap.cjs

@@ -1 +1,2 @@
-"use strict";var F=Object.create;var a=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var T=Object.getPrototypeOf,x=Object.prototype.hasOwnProperty;var L=(e,t)=>{for(var o in t)a(e,o,{get:t[o],enumerable:!0})},m=(e,t,o,c)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of y(t))!x.call(e,n)&&n!==o&&a(e,n,{get:()=>t[n],enumerable:!(c=A(t,n))||c.enumerable});return e};var R=(e,t,o)=>(o=e!=null?F(T(e)):{},m(t||!e||!e.__esModule?a(o,"default",{value:e,enumerable:!0}):o,e)),O=e=>m(a({},"__esModule",{value:!0}),e);var H={};L(H,{autoFocusEvent:()=>f,useFocusTrap:()=>C});module.exports=O(H);var s=R(require("react"),1),h=["a[href]","button:not([disabled])",'input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function E(e){return Array.from(e.querySelectorAll(h)).filter(t=>t.offsetParent!==null||t===document.activeElement)}function f(e,t){if(!t)return!0;let o=new CustomEvent(e,{cancelable:!0,detail:null});return t(o),!o.defaultPrevented}function C(e,t,o={}){let c=s.useRef(o);s.useEffect(()=>{c.current=o}),s.useEffect(()=>{if(!t)return;let n=e.current;if(!n)return;let l=document.activeElement,p=requestAnimationFrame(()=>{if(n.contains(document.activeElement)||!f("open-auto-focus",c.current.onOpenAutoFocus))return;let r=E(n)[0]??n;n.tabIndex=n.tabIndex>=0?n.tabIndex:-1,r.focus({preventScroll:!0})}),d=u=>{if(u.key!=="Tab")return;let r=E(n);if(r.length===0){u.preventDefault();return}let b=r[0],v=r[r.length-1],i=document.activeElement;u.shiftKey&&(i===b||i===n)?(u.preventDefault(),v.focus()):!u.shiftKey&&i===v&&(u.preventDefault(),b.focus())};return n.addEventListener("keydown",d),()=>{cancelAnimationFrame(p),n.removeEventListener("keydown",d),f("close-auto-focus",c.current.onCloseAutoFocus)&&l&&document.contains(l)&&l.focus?.({preventScroll:!0})}},[e,t])}0&&(module.exports={autoFocusEvent,useFocusTrap});
+'use client';
+"use strict";var v=Object.create;var i=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var b=Object.getPrototypeOf,A=Object.prototype.hasOwnProperty;var L=(t,e)=>{for(var o in e)i(t,o,{get:e[o],enumerable:!0})},d=(t,e,o,u)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of T(e))!A.call(t,n)&&n!==o&&i(t,n,{get:()=>e[n],enumerable:!(u=y(e,n))||u.enumerable});return t};var O=(t,e,o)=>(o=t!=null?v(b(t)):{},d(e||!t||!t.__esModule?i(o,"default",{value:t,enumerable:!0}):o,t)),R=t=>d(i({},"__esModule",{value:!0}),t);var x={};L(x,{useFocusTrap:()=>M});module.exports=R(x);var s=O(require("react"),1),p=require("./dismissal.cjs"),a=require("./focus-targets.cjs"),F=require("./tabbable.cjs");function g(t){return Array.from(t.querySelectorAll(F.TABBABLE_SELECTOR)).filter(e=>e.offsetParent!==null||e===document.activeElement)}function H(t,e){let o=g(t);if(o.length===0){e.preventDefault();return}let u=o[0],n=o[o.length-1],c=document.activeElement;e.shiftKey&&(c===u||c===t)?(e.preventDefault(),n.focus()):!e.shiftKey&&c===n&&(e.preventDefault(),u.focus())}function M(t,e,o={}){let u=s.useRef(o);s.useEffect(()=>{u.current=o}),s.useEffect(()=>{if(!e)return;let n=t.current;if(!n)return;let c=document.activeElement,E=requestAnimationFrame(()=>{let{onOpenAutoFocus:r,initialFocus:f,family:l="Popover"}=u.current;n.tabIndex=n.tabIndex>=0?n.tabIndex:-1,(0,p.focusOnOpen)(()=>(0,a.applyOpenAutoFocus)(n,f,l,r))}),m=r=>{r.key==="Tab"&&H(n,r)};return n.addEventListener("keydown",m),()=>{cancelAnimationFrame(E),n.removeEventListener("keydown",m);let{onCloseAutoFocus:r,finalFocus:f,family:l="Popover"}=u.current;(0,a.returnFocus)(f,l,c,r)}},[t,e])}0&&(module.exports={useFocusTrap});

package/dist/utils/useFocusTrap.d.cts

@@ -1,25 +1,24 @@
 import * as React from 'react';
-/** The cancelable stand-in an auto-focus handler receives — there is no native event for "I am about to move focus". */
-export type AutoFocusEvent = CustomEvent<null>;
-/**
- * Announces an automatic focus move as a cancelable event and reports whether
- * it may go ahead. Shared by the focus trap and by the overlays that return
- * focus to their trigger by hand, so the veto means the same thing in both.
- */
-export declare function autoFocusEvent(type: 'open-auto-focus' | 'close-auto-focus', handler?: (event: AutoFocusEvent) => void): boolean;
+import { type AutoFocusEvent } from './dismissal.cjs';
+import { type FocusTargetFamily } from './focus-targets.cjs';
 /** Consumer overrides for the two focus moves the trap makes on the overlay's behalf. */
 export interface FocusTrapOptions {
     /** Fired before focus moves into the container; `preventDefault()` leaves focus where it is. */
-    onOpenAutoFocus?: (event: AutoFocusEvent) => void;
+    onOpenAutoFocus?: ((event: AutoFocusEvent) => void) | undefined;
     /** Fired before focus returns to the previously focused element; `preventDefault()` suppresses the return. */
-    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
+    onCloseAutoFocus?: ((event: AutoFocusEvent) => void) | undefined;
+    /** CSS selector for the element inside the container that takes initial focus, ahead of the first tabbable one. */
+    initialFocus?: string | undefined;
+    /** CSS selector, resolved against the document, for the element focus returns to instead of the opener. */
+    finalFocus?: string | undefined;
+    /** Which overlay family the trap serves, for the console warning a missed selector prints. */
+    family?: FocusTargetFamily | undefined;
 }
 /**
- * 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.d.ts

@@ -1,25 +1,24 @@
 import * as React from 'react';
-/** The cancelable stand-in an auto-focus handler receives — there is no native event for "I am about to move focus". */
-export type AutoFocusEvent = CustomEvent<null>;
-/**
- * Announces an automatic focus move as a cancelable event and reports whether
- * it may go ahead. Shared by the focus trap and by the overlays that return
- * focus to their trigger by hand, so the veto means the same thing in both.
- */
-export declare function autoFocusEvent(type: 'open-auto-focus' | 'close-auto-focus', handler?: (event: AutoFocusEvent) => void): boolean;
+import { type AutoFocusEvent } from './dismissal.js';
+import { type FocusTargetFamily } from './focus-targets.js';
 /** Consumer overrides for the two focus moves the trap makes on the overlay's behalf. */
 export interface FocusTrapOptions {
     /** Fired before focus moves into the container; `preventDefault()` leaves focus where it is. */
-    onOpenAutoFocus?: (event: AutoFocusEvent) => void;
+    onOpenAutoFocus?: ((event: AutoFocusEvent) => void) | undefined;
     /** Fired before focus returns to the previously focused element; `preventDefault()` suppresses the return. */
-    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
+    onCloseAutoFocus?: ((event: AutoFocusEvent) => void) | undefined;
+    /** CSS selector for the element inside the container that takes initial focus, ahead of the first tabbable one. */
+    initialFocus?: string | undefined;
+    /** CSS selector, resolved against the document, for the element focus returns to instead of the opener. */
+    finalFocus?: string | undefined;
+    /** Which overlay family the trap serves, for the console warning a missed selector prints. */
+    family?: FocusTargetFamily | undefined;
 }
 /**
- * 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,2 @@
-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};
+'use client';
+import*as s from"react";import{focusOnOpen as m}from"./dismissal.js";import{applyOpenAutoFocus as d,returnFocus as p}from"./focus-targets.js";import{TABBABLE_SELECTOR as F}from"./tabbable.js";function E(n){return Array.from(n.querySelectorAll(F)).filter(e=>e.offsetParent!==null||e===document.activeElement)}function v(n,e){let o=E(n);if(o.length===0){e.preventDefault();return}let u=o[0],t=o[o.length-1],c=document.activeElement;e.shiftKey&&(c===u||c===n)?(e.preventDefault(),t.focus()):!e.shiftKey&&c===t&&(e.preventDefault(),u.focus())}function A(n,e,o={}){let u=s.useRef(o);s.useEffect(()=>{u.current=o}),s.useEffect(()=>{if(!e)return;let t=n.current;if(!t)return;let c=document.activeElement,l=requestAnimationFrame(()=>{let{onOpenAutoFocus:r,initialFocus:i,family:a="Popover"}=u.current;t.tabIndex=t.tabIndex>=0?t.tabIndex:-1,m(()=>d(t,i,a,r))}),f=r=>{r.key==="Tab"&&v(t,r)};return t.addEventListener("keydown",f),()=>{cancelAnimationFrame(l),t.removeEventListener("keydown",f);let{onCloseAutoFocus:r,finalFocus:i,family:a="Popover"}=u.current;p(i,a,c,r)}},[n,e])}export{A as useFocusTrap};

package/dist/utils/useMenuItem.cjs

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

package/dist/utils/useMenuItem.d.cts

@@ -1,27 +1,34 @@
 import type * as React from 'react';
 /** @internal Options for {@link useMenuItem}, the shared menu-item interaction hook. */
 export interface UseMenuItemOptions {
-    disabled?: boolean;
+    disabled?: boolean | undefined;
+    /** Typeahead override, reflected to `data-text-value`. Falls back to the item's rendered text. */
+    textValue?: string | undefined;
     /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
-    onSelect?: (event: Event) => void;
+    onSelect?: ((event: Event) => void) | undefined;
+    /**
+     * Whether an un-prevented select runs {@link UseMenuItemOptions.onSelected} — in practice, whether it closes the menu — letting `closeOnSelect` default per part alongside `onSelect`'s per-activation veto.
+     * @defaultValue true
+     */
+    closeOnSelect?: boolean | undefined;
     /** 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. */
     contentRef: React.RefObject<HTMLElement | null>;
     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.
- */
-export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, props }: UseMenuItemOptions): {
-    'data-disabled': string | undefined;
+/** @internal Attributes and handlers {@link useMenuItem} spreads onto a menu item. */
+export interface MenuItemInteractionProps {
+    'data-disabled': '' | undefined;
+    'data-text-value': string | undefined;
     'aria-disabled': true | undefined;
-    tabIndex: number | undefined;
-    onClick: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+    tabIndex: number;
+    onClick: (event: React.MouseEvent<HTMLDivElement>) => void;
     onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
     onPointerEnter: (event: React.PointerEvent<HTMLDivElement>) => void;
     onPointerLeave: (event: React.PointerEvent<HTMLDivElement>) => void;
-};
+}
+/**
+ * Shared `menuitem` interaction wiring across all menu families.
+ */
+export declare function useMenuItem({ disabled, textValue, onSelect, onSelected, closeOnSelect, contentRef, props, }: UseMenuItemOptions): MenuItemInteractionProps;

package/dist/utils/useMenuItem.d.ts

@@ -1,27 +1,34 @@
 import type * as React from 'react';
 /** @internal Options for {@link useMenuItem}, the shared menu-item interaction hook. */
 export interface UseMenuItemOptions {
-    disabled?: boolean;
+    disabled?: boolean | undefined;
+    /** Typeahead override, reflected to `data-text-value`. Falls back to the item's rendered text. */
+    textValue?: string | undefined;
     /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
-    onSelect?: (event: Event) => void;
+    onSelect?: ((event: Event) => void) | undefined;
+    /**
+     * Whether an un-prevented select runs {@link UseMenuItemOptions.onSelected} — in practice, whether it closes the menu — letting `closeOnSelect` default per part alongside `onSelect`'s per-activation veto.
+     * @defaultValue true
+     */
+    closeOnSelect?: boolean | undefined;
     /** 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. */
     contentRef: React.RefObject<HTMLElement | null>;
     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.
- */
-export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, props }: UseMenuItemOptions): {
-    'data-disabled': string | undefined;
+/** @internal Attributes and handlers {@link useMenuItem} spreads onto a menu item. */
+export interface MenuItemInteractionProps {
+    'data-disabled': '' | undefined;
+    'data-text-value': string | undefined;
     'aria-disabled': true | undefined;
-    tabIndex: number | undefined;
-    onClick: (event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+    tabIndex: number;
+    onClick: (event: React.MouseEvent<HTMLDivElement>) => void;
     onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
     onPointerEnter: (event: React.PointerEvent<HTMLDivElement>) => void;
     onPointerLeave: (event: React.PointerEvent<HTMLDivElement>) => void;
-};
+}
+/**
+ * Shared `menuitem` interaction wiring across all menu families.
+ */
+export declare function useMenuItem({ disabled, textValue, onSelect, onSelected, closeOnSelect, contentRef, props, }: UseMenuItemOptions): MenuItemInteractionProps;

package/dist/utils/useMenuItem.js

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

package/dist/utils/useOpenChangeComplete.cjs

@@ -1 +1,2 @@
-"use strict";var E=Object.create;var s=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var C=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,h=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)s(e,t,{get:n[t],enumerable:!0})},v=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of C(n))!h.call(e,o)&&o!==t&&s(e,o,{get:()=>n[o],enumerable:!(r=b(n,o))||r.enumerable});return e};var g=(e,n,t)=>(t=e!=null?E(L(e)):{},v(n||!e||!e.__esModule?s(t,"default",{value:e,enumerable:!0}):t,e)),y=e=>v(s({},"__esModule",{value:!0}),e);var M={};R(M,{useOpenChangeComplete:()=>F});module.exports=y(M);var c=g(require("react"),1),p=require("./useCallbackRef.cjs");function A(e){let{animationName:n,transitionDuration:t,display:r}=getComputedStyle(e);return r==="none"?!1:n!==""&&n!=="none"?!0:t.split(",").some(o=>Number.parseFloat(o)>0)}function F(e,n,t){let r=(0,p.useCallbackRef)(t),o=c.useRef(!0);c.useEffect(()=>{if(o.current){o.current=!1;return}let l=["animationend","animationcancel","transitionend","transitioncancel"],u,m=()=>{let a=n.current;if(!a||!a.isConnected||!A(a)){r(e);return}let d=i=>{i.target===a&&r(e)};for(let i of l)a.addEventListener(i,d);u=()=>{for(let i of l)a.removeEventListener(i,d)}},f=0;return e&&!n.current?f=requestAnimationFrame(m):m(),()=>{cancelAnimationFrame(f),u?.()}},[e,n,r])}0&&(module.exports={useOpenChangeComplete});
+'use client';
+"use strict";var E=Object.create;var a=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var L=Object.getPrototypeOf,b=Object.prototype.hasOwnProperty;var C=(e,n)=>{for(var t in n)a(e,t,{get:n[t],enumerable:!0})},m=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of p(n))!b.call(e,i)&&i!==t&&a(e,i,{get:()=>n[i],enumerable:!(o=v(n,i))||o.enumerable});return e};var M=(e,n,t)=>(t=e!=null?E(L(e)):{},m(n||!e||!e.__esModule?a(t,"default",{value:e,enumerable:!0}):t,e)),T=e=>m(a({},"__esModule",{value:!0}),e);var y={};C(y,{useOpenChangeComplete:()=>g});module.exports=T(y);var s=M(require("react"),1),d=require("./useCallbackRef.cjs");function h(e){let{animationName:n,transitionDuration:t,display:o}=getComputedStyle(e);return o==="none"?!1:n!==""&&n!=="none"?!0:t.split(",").some(i=>Number.parseFloat(i)>0)}var f=["animationend","animationcancel","transitionend","transitioncancel"];function R(e,n){let t=o=>{o.target===e&&n()};for(let o of f)e.addEventListener(o,t);return()=>{for(let o of f)e.removeEventListener(o,t)}}function g(e,n,t){let o=(0,d.useCallbackRef)(t),i=s.useRef(!0);s.useEffect(()=>{if(i.current){i.current=!1;return}let c,l=()=>{let r=n.current;if(!r||!r.isConnected||!h(r)){o(e);return}c=R(r,()=>o(e))},u=0;return e&&!n.current?u=requestAnimationFrame(l):l(),()=>{cancelAnimationFrame(u),c?.()}},[e,n,o])}0&&(module.exports={useOpenChangeComplete});

package/dist/utils/useOpenChangeComplete.d.cts

@@ -1,19 +1,6 @@
 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).
- *
- * 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.
+ * Calls `onOpenChangeComplete` once the open/close change has settled on screen, after the enter/exit animation ends or immediately if no motion is declared.
  *
  * @example
  * ```tsx

package/dist/utils/useOpenChangeComplete.d.ts

@@ -1,19 +1,6 @@
 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).
- *
- * 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.
+ * Calls `onOpenChangeComplete` once the open/close change has settled on screen, after the enter/exit animation ends or immediately if no motion is declared.
  *
  * @example
  * ```tsx

package/dist/utils/useOpenChangeComplete.js

@@ -1 +1,2 @@
-import*as i from"react";import{useCallbackRef as d}from"./useCallbackRef.js";function v(e){let{animationName:n,transitionDuration:s,display:o}=getComputedStyle(e);return o==="none"?!1:n!==""&&n!=="none"?!0:s.split(",").some(a=>Number.parseFloat(a)>0)}function E(e,n,s){let o=d(s),a=i.useRef(!0);i.useEffect(()=>{if(a.current){a.current=!1;return}let c=["animationend","animationcancel","transitionend","transitioncancel"],l,u=()=>{let t=n.current;if(!t||!t.isConnected||!v(t)){o(e);return}let f=r=>{r.target===t&&o(e)};for(let r of c)t.addEventListener(r,f);l=()=>{for(let r of c)t.removeEventListener(r,f)}},m=0;return e&&!n.current?m=requestAnimationFrame(u):u(),()=>{cancelAnimationFrame(m),l?.()}},[e,n,o])}export{E as useOpenChangeComplete};
+'use client';
+import*as a from"react";import{useCallbackRef as m}from"./useCallbackRef.js";function f(n){let{animationName:t,transitionDuration:o,display:e}=getComputedStyle(n);return e==="none"?!1:t!==""&&t!=="none"?!0:o.split(",").some(i=>Number.parseFloat(i)>0)}var u=["animationend","animationcancel","transitionend","transitioncancel"];function d(n,t){let o=e=>{e.target===n&&t()};for(let e of u)n.addEventListener(e,o);return()=>{for(let e of u)n.removeEventListener(e,o)}}function v(n,t,o){let e=m(o),i=a.useRef(!0);a.useEffect(()=>{if(i.current){i.current=!1;return}let s,c=()=>{let r=t.current;if(!r||!r.isConnected||!f(r)){e(n);return}s=d(r,()=>e(n))},l=0;return n&&!t.current?l=requestAnimationFrame(c):c(),()=>{cancelAnimationFrame(l),s?.()}},[n,t,e])}export{v as useOpenChangeComplete};

package/dist/utils/useOptionCollection.cjs

@@ -1 +1,2 @@
-"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 client';
+"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[d,f]=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||f(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 g=s==="last"?a[a.length-1]:a[0],E=!1;f(x=>x!==null?x:(E=!0,g.id)),E&&z(i,g)});return()=>cancelAnimationFrame(e)},[t,n,h]),r.useLayoutEffect(()=>{if(d===null)return;let e=h(n.current);e.some(s=>s.id===d)||f(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 g=new Map(i);return g.set(e,s),g})},[]),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=>(f(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===d),g=a;a===-1&&(g=e===1?-1:0);let E=u?(g+e+i.length)%i.length:Math.min(i.length-1,Math.max(0,g+e));return R(i[E])},[d,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:d,itemOrder:p,setActiveId:f,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:d,unregisterItem:f}){let[c,O]=r.useState(n??null);r.useLayoutEffect(()=>{let p=(n??u.current?.textContent)?.trim();p&&p!==c&&O(p)});let m=c===null||o(c);return r.useEffect(()=>{if(m)return d(t,{value:l,text:c??""}),()=>f(t)},[t,m,l,c,d,f]),{text:c,visible:m}}0&&(module.exports={OPTION_SELECTOR,useOptionCollection,useOptionEntry});

package/dist/utils/useOptionCollection.d.cts

@@ -1,22 +1,6 @@
 import * as React from 'react';
-/**
- * The virtual-focus option collection behind every listbox-with-a-textbox in
- * this package — `Combobox`, `Autocomplete`, `MultiSelect`.
- *
- * All three face the identical set of problems: real DOM focus never leaves
- * the input, so the highlighted option is tracked as an id and mirrored into
- * `aria-activedescendant`; the highlighted option can be filtered out from
- * under the highlight; opening with Arrow Down has to wait for the popup's
- * items to mount before "first" means anything; and moving the highlight is a
- * DOM question, not a state question, because items register in a passive
- * effect one commit behind the DOM they describe.
- *
- * Extracted here rather than copied into each family: the answers are the
- * same in all three, and the two-pass convergence in the layout effect below
- * is exactly the kind of thing that rots when it exists three times.
- *
- * @internal
- */
+/** Enabled options selector, duplicated rather than imported across Combobox/Listbox/Transfer since each component folder is its own bundle. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /** @internal What one registered option contributes to a {@link useOptionCollection} collection. */
 export interface OptionEntry {
     /** Identifier committed to the owning root's value when this option is chosen. */
@@ -32,11 +16,23 @@ 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.
+     * @default false
+     */
+    loop?: boolean | undefined;
+    /**
+     * Scores a registered entry for ranking: return a number to rank it, `null` to leave it unscored, or omit entirely for a family with no ranking filter.
+     * @default undefined — no ranking.
+     */
+    scoreItem?: ((entry: OptionEntry) => number | null) | undefined;
 }
 /** @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; `null` when nothing scored numerically. */
+    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 +45,18 @@ 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 `loop` is set, clamped otherwise, and scrolls it into view.
+     * @returns the element id now highlighted, or `null` when there was nothing to move to.
+     */
+    moveActive: (direction: 1 | -1) => string | null;
+    /**
+     * Moves the highlight to the first or last option and scrolls it into view, for Home/End while the popup is open.
+     * @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. */
@@ -71,18 +75,8 @@ export interface UseOptionEntryOptions {
     unregisterItem: (id: string) => void;
 }
 /**
- * The measure-then-filter-then-register cycle every `*Item` part runs, shared
- * by `Autocomplete` and `MultiSelect`.
- *
- * The ordering is the whole point and is easy to get wrong: an option's text
- * has to exist in the DOM before the filter can measure it, so an unmeasured
- * option always renders; a rejected option renders *nothing at all* rather
- * than hiding, because a hidden option is still reachable through
- * `aria-activedescendant` and would still be counted as a result.
- *
- * @returns The option's measured text (or `null` before the first measurement)
- * and whether it should render.
- * @internal
+ * @internal The measure-then-filter-then-register cycle every `*Item` part runs; an unmeasured option always renders, and a rejected one renders nothing at all rather than hiding, since a hidden option would still be reachable via `aria-activedescendant`.
+ * @returns The option's measured text (or `null` before the first measurement) and whether it should render.
  */
 export declare function useOptionEntry({ id, value, textValue, itemRef, matchesFilter, registerItem, unregisterItem, }: UseOptionEntryOptions): {
     text: string | null;

package/dist/utils/useOptionCollection.d.ts

@@ -1,22 +1,6 @@
 import * as React from 'react';
-/**
- * The virtual-focus option collection behind every listbox-with-a-textbox in
- * this package — `Combobox`, `Autocomplete`, `MultiSelect`.
- *
- * All three face the identical set of problems: real DOM focus never leaves
- * the input, so the highlighted option is tracked as an id and mirrored into
- * `aria-activedescendant`; the highlighted option can be filtered out from
- * under the highlight; opening with Arrow Down has to wait for the popup's
- * items to mount before "first" means anything; and moving the highlight is a
- * DOM question, not a state question, because items register in a passive
- * effect one commit behind the DOM they describe.
- *
- * Extracted here rather than copied into each family: the answers are the
- * same in all three, and the two-pass convergence in the layout effect below
- * is exactly the kind of thing that rots when it exists three times.
- *
- * @internal
- */
+/** Enabled options selector, duplicated rather than imported across Combobox/Listbox/Transfer since each component folder is its own bundle. */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
 /** @internal What one registered option contributes to a {@link useOptionCollection} collection. */
 export interface OptionEntry {
     /** Identifier committed to the owning root's value when this option is chosen. */
@@ -32,11 +16,23 @@ 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.
+     * @default false
+     */
+    loop?: boolean | undefined;
+    /**
+     * Scores a registered entry for ranking: return a number to rank it, `null` to leave it unscored, or omit entirely for a family with no ranking filter.
+     * @default undefined — no ranking.
+     */
+    scoreItem?: ((entry: OptionEntry) => number | null) | undefined;
 }
 /** @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; `null` when nothing scored numerically. */
+    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 +45,18 @@ 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 `loop` is set, clamped otherwise, and scrolls it into view.
+     * @returns the element id now highlighted, or `null` when there was nothing to move to.
+     */
+    moveActive: (direction: 1 | -1) => string | null;
+    /**
+     * Moves the highlight to the first or last option and scrolls it into view, for Home/End while the popup is open.
+     * @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. */
@@ -71,18 +75,8 @@ export interface UseOptionEntryOptions {
     unregisterItem: (id: string) => void;
 }
 /**
- * The measure-then-filter-then-register cycle every `*Item` part runs, shared
- * by `Autocomplete` and `MultiSelect`.
- *
- * The ordering is the whole point and is easy to get wrong: an option's text
- * has to exist in the DOM before the filter can measure it, so an unmeasured
- * option always renders; a rejected option renders *nothing at all* rather
- * than hiding, because a hidden option is still reachable through
- * `aria-activedescendant` and would still be counted as a result.
- *
- * @returns The option's measured text (or `null` before the first measurement)
- * and whether it should render.
- * @internal
+ * @internal The measure-then-filter-then-register cycle every `*Item` part runs; an unmeasured option always renders, and a rejected one renders nothing at all rather than hiding, since a hidden option would still be reachable via `aria-activedescendant`.
+ * @returns The option's measured text (or `null` before the first measurement) and whether it should render.
  */
 export declare function useOptionEntry({ id, value, textValue, itemRef, matchesFilter, registerItem, unregisterItem, }: UseOptionEntryOptions): {
     text: string | null;

package/dist/utils/useOptionCollection.js

@@ -1 +1,2 @@
-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};
+'use client';
+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(),a=c.getBoundingClientRect();i.scrollTop+=a.top-f.top-(f.height-a.height)/2}function B({open:l,setOpen:c,contentRef:i,loop:f=!1,scoreItem:a}){let[g,d]=e.useState(null),[s,O]=e.useState(()=>new Map),m=e.useRef(null),p=e.useMemo(()=>a?L([...s.keys()],t=>{let r=s.get(t);return r?a(r):null}):null,[s,a]),h=e.useCallback(t=>k(Array.from(t?.querySelectorAll(A)??[]),p),[p]),[b,v]=e.useState(l);l!==b&&(v(l),l||d(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 u=r==="last"?o[o.length-1]:o[0],E=!1;d(x=>x!==null?x:(E=!0,u.id)),E&&S(n,u)});return()=>cancelAnimationFrame(t)},[l,i,h]),e.useLayoutEffect(()=>{if(g===null)return;let t=h(i.current);t.some(r=>r.id===g)||d(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 u=new Map(n);return u.set(t,r),u})},[]),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=>(d(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===g),u=o;o===-1&&(u=t===1?-1:0);let E=f?(u+t+n.length)%n.length:Math.min(n.length-1,Math.max(0,u+t));return R(n[E])},[g,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:g,itemOrder:p,setActiveId:d,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:a,registerItem:g,unregisterItem:d}){let[s,O]=e.useState(i??null);e.useLayoutEffect(()=>{let p=(i??f.current?.textContent)?.trim();p&&p!==s&&O(p)});let m=s===null||a(s);return e.useEffect(()=>{if(m)return g(l,{value:c,text:s??""}),()=>d(l)},[l,m,c,s,g,d]),{text:s,visible:m}}export{A as OPTION_SELECTOR,B as useOptionCollection,U as useOptionEntry};

package/dist/utils/useOutsideInert.cjs

@@ -0,0 +1,2 @@
+'use client';
+"use strict";var f=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})},l=(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 h=(t,e,n)=>(n=t!=null?f(b(t)):{},l(e||!t||!t.__esModule?c(n,"default",{value:t,enumerable:!0}):n,t)),w=t=>l(c({},"__esModule",{value:!0}),t);var I={};p(I,{releaseOutsideInert:()=>A,useOutsideInert:()=>y});module.exports=w(I);var s=h(require("react"),1),o=new Map,u=new Set;function v(t){let e=t.ownerDocument.body,n=t;for(;n.parentElement&&n.parentElement!==e;)n=n.parentElement;return n.parentElement===e?n:null}function a(t){if(u.size===0){for(let[e,n]of o)n||e.removeAttribute("inert");o.clear();return}for(let e of Array.from(t.children))if(!e.hasAttribute("data-skdx-live-announcer")){if(u.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 y(t,e){s.useEffect(()=>{if(!e)return;let n=t.current;if(!n)return;let i=v(n);if(!i)return;let r=n.ownerDocument.body;return u.add(i),a(r),()=>{u.delete(i),a(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,10 @@
+import * as React from 'react';
+/**
+ * Marks everything outside the overlay's portal container `inert` while enabled, stackable so nested overlays each keep their own container live; `enabled` must be `false` for non-modal overlays.
+ *
+ * @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 an overlay that returns focus to its trigger from an event handler — which runs before React's passive cleanup, so the trigger would still be inert without this. */
+export declare function releaseOutsideInert(): void;

package/dist/utils/useOutsideInert.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+/**
+ * Marks everything outside the overlay's portal container `inert` while enabled, stackable so nested overlays each keep their own container live; `enabled` must be `false` for non-modal overlays.
+ *
+ * @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 an overlay that returns focus to its trigger from an event handler — which runs before React's passive cleanup, so the trigger would still be inert without this. */
+export declare function releaseOutsideInert(): void;