@skdx/react 0.26.0

package/dist/utils/usePointerAngle.d.cts

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

package/dist/utils/usePointerAngle.d.ts

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

package/dist/utils/usePointerAngle.js

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

package/dist/utils/useRovingFocus.cjs

@@ -0,0 +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});

package/dist/utils/useRovingFocus.d.cts

@@ -0,0 +1,83 @@
+import * as React from 'react';
+/** @internal Which arrow keys move focus within a roving-focus group: horizontal, vertical, or `'both'` (all four arrows). */
+export type Orientation = 'horizontal' | 'vertical' | 'both';
+interface UseRovingFocusOptions {
+    orientation?: Orientation;
+    loop?: boolean;
+    /** CSS selector matching focusable items inside the group. */
+    itemSelector: string;
+    /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
+    typeahead?: boolean;
+}
+/**
+ * The text typeahead matches an item against: its explicit `data-text-value`
+ * if it has one, else its rendered text.
+ *
+ * Raw `textContent` alone is wrong for any item that renders more than its
+ * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
+ * skips exactly the items that are currently selected. `data-text-value` is
+ * the escape hatch, and this is the one precedence rule every matcher in the
+ * repo follows.
+ *
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/**
+ * Keeps a roving-tabindex group's tab stop on an item that actually exists.
+ *
+ * Seeding "when nothing is focused yet, make the first item tabbable" is only
+ * half the job: when the item *holding* the tab stop is removed, the stored id
+ * still points at it, so a `currentId !== null` guard sees nothing to do — and
+ * then no item carries `tabIndex` 0 and the whole group silently drops out of
+ * the tab order, with nothing on screen to explain it. So the check is
+ * "does any item claim the current id", not "is the current id set".
+ *
+ * Deliberately runs on every render with no dependency array: an item can
+ * disappear without `currentId` changing, which is exactly the case that
+ * breaks. Each run is one `querySelectorAll` over a group that is small by
+ * construction, and it settles after at most one `setCurrentId`.
+ *
+ * @param rootRef the group element owning the items
+ * @param itemSelector selector matching the group's items
+ * @param idAttribute attribute on each item holding its id
+ * @param currentId the id currently holding the tab stop
+ * @param setCurrentId hands the tab stop to another item
+ * @internal
+ */
+export declare function useRovingTabStop(rootRef: React.RefObject<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: string | null, setCurrentId: (id: string) => void): void;
+/**
+ * The `tabIndex` for one item of a roving-tabindex group.
+ *
+ * {@link useRovingTabStop} resolves which item holds the group's single tab
+ * stop from a *layout effect*, and effects never run during server rendering.
+ * So in server HTML `resolved` is false, and a group with no selected or
+ * pressed item to fall back on rendered `tabIndex={-1}` on every item — the
+ * whole group had no tab stop at all and was unreachable by keyboard. That is
+ * the markup a non-hydrated consumer (an Astro island, an RSC subtree) ships,
+ * and all its users ever get.
+ *
+ * So until the stop is resolved, every enabled item is a tab stop. Tabbing
+ * through N items is a degradation; being unable to reach any of them is a
+ * defect — and it is the *correct* arrangement for markup whose arrow keys
+ * (the other half of roving tabindex, and pure JavaScript) may never arrive.
+ * A `0` rather than an omitted attribute because the items are not always
+ * natively focusable: a `[role="treeitem"]` is a `<div>`.
+ *
+ * A disabled item never claims a stop it could not hold, resolved or not.
+ *
+ * From the first layout effect onward this is exactly `isTabStop ? 0 : -1`, so
+ * behaviour after hydration is unchanged.
+ *
+ * @param resolved whether the group has settled which item holds the tab stop
+ * @param isTabStop whether this item is the one holding it
+ * @param disabled whether this item is disabled
+ * @internal
+ */
+export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;
+/**
+ * DOM-driven roving focus for composite widgets (tabs, radio groups, menus,
+ * toolbars). Returns a keydown handler to spread on the group element.
+ * Items are discovered by selector, so no registration plumbing is needed.
+ */
+export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
+export {};

package/dist/utils/useRovingFocus.d.ts

@@ -0,0 +1,83 @@
+import * as React from 'react';
+/** @internal Which arrow keys move focus within a roving-focus group: horizontal, vertical, or `'both'` (all four arrows). */
+export type Orientation = 'horizontal' | 'vertical' | 'both';
+interface UseRovingFocusOptions {
+    orientation?: Orientation;
+    loop?: boolean;
+    /** CSS selector matching focusable items inside the group. */
+    itemSelector: string;
+    /** Enable letter-key typeahead (jumps to the next item whose text starts with what was typed). */
+    typeahead?: boolean;
+}
+/**
+ * The text typeahead matches an item against: its explicit `data-text-value`
+ * if it has one, else its rendered text.
+ *
+ * Raw `textContent` alone is wrong for any item that renders more than its
+ * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
+ * skips exactly the items that are currently selected. `data-text-value` is
+ * the escape hatch, and this is the one precedence rule every matcher in the
+ * repo follows.
+ *
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/**
+ * Keeps a roving-tabindex group's tab stop on an item that actually exists.
+ *
+ * Seeding "when nothing is focused yet, make the first item tabbable" is only
+ * half the job: when the item *holding* the tab stop is removed, the stored id
+ * still points at it, so a `currentId !== null` guard sees nothing to do — and
+ * then no item carries `tabIndex` 0 and the whole group silently drops out of
+ * the tab order, with nothing on screen to explain it. So the check is
+ * "does any item claim the current id", not "is the current id set".
+ *
+ * Deliberately runs on every render with no dependency array: an item can
+ * disappear without `currentId` changing, which is exactly the case that
+ * breaks. Each run is one `querySelectorAll` over a group that is small by
+ * construction, and it settles after at most one `setCurrentId`.
+ *
+ * @param rootRef the group element owning the items
+ * @param itemSelector selector matching the group's items
+ * @param idAttribute attribute on each item holding its id
+ * @param currentId the id currently holding the tab stop
+ * @param setCurrentId hands the tab stop to another item
+ * @internal
+ */
+export declare function useRovingTabStop(rootRef: React.RefObject<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: string | null, setCurrentId: (id: string) => void): void;
+/**
+ * The `tabIndex` for one item of a roving-tabindex group.
+ *
+ * {@link useRovingTabStop} resolves which item holds the group's single tab
+ * stop from a *layout effect*, and effects never run during server rendering.
+ * So in server HTML `resolved` is false, and a group with no selected or
+ * pressed item to fall back on rendered `tabIndex={-1}` on every item — the
+ * whole group had no tab stop at all and was unreachable by keyboard. That is
+ * the markup a non-hydrated consumer (an Astro island, an RSC subtree) ships,
+ * and all its users ever get.
+ *
+ * So until the stop is resolved, every enabled item is a tab stop. Tabbing
+ * through N items is a degradation; being unable to reach any of them is a
+ * defect — and it is the *correct* arrangement for markup whose arrow keys
+ * (the other half of roving tabindex, and pure JavaScript) may never arrive.
+ * A `0` rather than an omitted attribute because the items are not always
+ * natively focusable: a `[role="treeitem"]` is a `<div>`.
+ *
+ * A disabled item never claims a stop it could not hold, resolved or not.
+ *
+ * From the first layout effect onward this is exactly `isTabStop ? 0 : -1`, so
+ * behaviour after hydration is unchanged.
+ *
+ * @param resolved whether the group has settled which item holds the tab stop
+ * @param isTabStop whether this item is the one holding it
+ * @param disabled whether this item is disabled
+ * @internal
+ */
+export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;
+/**
+ * DOM-driven roving focus for composite widgets (tabs, radio groups, menus,
+ * toolbars). Returns a keydown handler to spread on the group element.
+ * Items are discovered by selector, so no registration plumbing is needed.
+ */
+export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, }: UseRovingFocusOptions): (event: React.KeyboardEvent<HTMLElement>) => void;
+export {};

package/dist/utils/useRovingFocus.js

@@ -0,0 +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};

package/dist/utils/useSelection.cjs

@@ -0,0 +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});

package/dist/utils/useSelection.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Every selected value as an array, whatever shape the consumer passed.
+ *
+ * The `string | string[] | undefined` public value shape exists because a
+ * single-select's value reads better as a bare string, but every consumer
+ * downstream — `aria-selected`, chips, hidden inputs, "is this option
+ * checked" — wants an array. Normalise once, here.
+ */
+export declare function toValues(value: string | string[] | undefined): string[];
+/**
+ * The value a selection becomes once `value` is chosen: replacing the
+ * selection, or toggling `value` within it when `multiple`.
+ *
+ * Split out from {@link useSelection} because this branch — and only this
+ * branch — is what Listbox, Select, and Combobox genuinely share. Their
+ * controlled/uncontrolled plumbing is framework-idiomatic and different in
+ * every package; this decision is identical in all of them, and the other four
+ * framework packages carry a line-for-line port of exactly this function.
+ */
+export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+/** Options for {@link useSelection}. */
+export interface UseSelectionOptions {
+    /** Selected value(s), for controlled usage — a `string[]` when `multiple`. */
+    value?: string | string[];
+    /** Initially selected value(s), for uncontrolled usage. */
+    defaultValue?: string | string[];
+    /** Fires with the whole new value whenever the selection changes. */
+    onValueChange?: (value: string | string[]) => void;
+    /** Whether choosing an option toggles it within a set rather than replacing the selection. */
+    multiple?: boolean;
+}
+/** What {@link useSelection} hands back to a component's context. */
+export interface Selection {
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    selectedValues: string[];
+    /** Whether one option value is currently selected. */
+    isSelected: (value: string) => boolean;
+    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
+    selectItem: (value: string) => void;
+    /**
+     * Replaces the whole selection outright, without going through the
+     * replace-or-toggle decision — what a `<form>` reset needs, since it
+     * restores a value rather than choosing an option.
+     */
+    setSelection: (value: string | string[]) => void;
+}
+/**
+ * The single/multiple selection model shared by every option-list component:
+ * Listbox, Select, and Combobox. All three faced the same three decisions —
+ * normalise the value to an array, answer "is this one selected", and commit
+ * an option by replacing or toggling — and all three answered them
+ * identically, so the answer lives here once.
+ *
+ * Deliberately owns *only* selection. A component's own side effects on
+ * commit (Combobox writing the option's text back into its input and closing;
+ * Select keeping focus in the listbox while `multiple`) stay in that
+ * component, wrapping `selectItem` rather than being configured into it —
+ * that is the one thing the three genuinely disagree about.
+ */
+export declare function useSelection({ value, defaultValue, onValueChange, multiple, }: UseSelectionOptions): Selection;

package/dist/utils/useSelection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Every selected value as an array, whatever shape the consumer passed.
+ *
+ * The `string | string[] | undefined` public value shape exists because a
+ * single-select's value reads better as a bare string, but every consumer
+ * downstream — `aria-selected`, chips, hidden inputs, "is this option
+ * checked" — wants an array. Normalise once, here.
+ */
+export declare function toValues(value: string | string[] | undefined): string[];
+/**
+ * The value a selection becomes once `value` is chosen: replacing the
+ * selection, or toggling `value` within it when `multiple`.
+ *
+ * Split out from {@link useSelection} because this branch — and only this
+ * branch — is what Listbox, Select, and Combobox genuinely share. Their
+ * controlled/uncontrolled plumbing is framework-idiomatic and different in
+ * every package; this decision is identical in all of them, and the other four
+ * framework packages carry a line-for-line port of exactly this function.
+ */
+export declare function nextSelection(selectedValues: string[], value: string, multiple: boolean): string | string[];
+/** Options for {@link useSelection}. */
+export interface UseSelectionOptions {
+    /** Selected value(s), for controlled usage — a `string[]` when `multiple`. */
+    value?: string | string[];
+    /** Initially selected value(s), for uncontrolled usage. */
+    defaultValue?: string | string[];
+    /** Fires with the whole new value whenever the selection changes. */
+    onValueChange?: (value: string | string[]) => void;
+    /** Whether choosing an option toggles it within a set rather than replacing the selection. */
+    multiple?: boolean;
+}
+/** What {@link useSelection} hands back to a component's context. */
+export interface Selection {
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    selectedValues: string[];
+    /** Whether one option value is currently selected. */
+    isSelected: (value: string) => boolean;
+    /** Commits an option: replaces the selection, or toggles it within it when `multiple`. */
+    selectItem: (value: string) => void;
+    /**
+     * Replaces the whole selection outright, without going through the
+     * replace-or-toggle decision — what a `<form>` reset needs, since it
+     * restores a value rather than choosing an option.
+     */
+    setSelection: (value: string | string[]) => void;
+}
+/**
+ * The single/multiple selection model shared by every option-list component:
+ * Listbox, Select, and Combobox. All three faced the same three decisions —
+ * normalise the value to an array, answer "is this one selected", and commit
+ * an option by replacing or toggling — and all three answered them
+ * identically, so the answer lives here once.
+ *
+ * Deliberately owns *only* selection. A component's own side effects on
+ * commit (Combobox writing the option's text back into its input and closing;
+ * Select keeping focus in the listbox while `multiple`) stay in that
+ * component, wrapping `selectItem` rather than being configured into it —
+ * that is the one thing the three genuinely disagree about.
+ */
+export declare function useSelection({ value, defaultValue, onValueChange, multiple, }: UseSelectionOptions): Selection;

package/dist/utils/useSelection.js

@@ -0,0 +1 @@
+import*as n from"react";import{useControllableState as f}from"./useControllableState.js";function d(e){return e===void 0?[]:Array.isArray(e)?e:[e]}function p(e,t,c){return c?e.includes(t)?e.filter(s=>s!==t):[...e,t]:t}function b({value:e,defaultValue:t,onValueChange:c,multiple:s=!1}){let[l,o]=f({prop:e,defaultProp:t,onChange:c}),r=n.useMemo(()=>d(l),[l]),a=n.useCallback(i=>r.includes(i),[r]),g=n.useCallback(i=>o(p(r,i,s)),[s,r,o]),u=n.useCallback(i=>o(i),[o]);return{selectedValues:r,isSelected:a,selectItem:g,setSelection:u}}export{p as nextSelection,d as toValues,b as useSelection};

package/dist/utils/useTypeahead.cjs

@@ -0,0 +1 @@
+"use strict";var h=Object.create;var s=Object.defineProperty;var T=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var K=Object.getPrototypeOf,d=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0})},y=(e,t,r,u)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of p(t))!d.call(e,n)&&n!==r&&s(e,n,{get:()=>t[n],enumerable:!(u=T(t,n))||u.enumerable});return e};var b=(e,t,r)=>(r=e!=null?h(K(e)):{},y(t||!e||!e.__esModule?s(r,"default",{value:e,enumerable:!0}):r,e)),E=e=>y(s({},"__esModule",{value:!0}),e);var C={};g(C,{isTypeaheadKey:()=>x,useTypeahead:()=>A});module.exports=E(C);var c=b(require("react"),1),k=1e3;function x(e){return e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey}function A(e){let t=c.useRef(""),r=c.useRef(void 0);return c.useEffect(()=>()=>clearTimeout(r.current),[]),c.useCallback((u,n)=>{clearTimeout(r.current),t.current+=u.toLowerCase(),r.current=setTimeout(()=>{t.current=""},k);let a=t.current,f=e(),i=a.length>1&&[...a].every(o=>o===a[0]),m=i?a[0]:a,R=i||a.length===1?n+1:n;for(let o=0;o<f.length;o++){let l=(Math.max(R,0)+o)%f.length;if(f[l].trim().toLowerCase().startsWith(m))return l}return-1},[e])}0&&(module.exports={isTypeaheadKey,useTypeahead});

package/dist/utils/useTypeahead.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+export declare function isTypeaheadKey(event: Pick<React.KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey'>): boolean;
+/**
+ * The letter-key search a listbox runs against a *collection* rather than
+ * against focusable DOM nodes — which is the whole point: `useRovingFocus`'s
+ * built-in typeahead can only see mounted elements, so a Select whose listbox
+ * has never been opened has nothing to search. This one takes the labels the
+ * root already knows, so typeahead works on a closed trigger.
+ *
+ * Returns a matcher: feed it a key and the currently-selected index, get back
+ * the index to move to, or `-1` for no match. The 1s buffer means `"s"`,
+ * `"a"` in quick succession searches for `"sa"`, while the same two keys a
+ * second apart are two separate single-letter searches — and repeating one
+ * letter cycles through the entries starting with it, the way a native
+ * `<select>` does.
+ */
+export declare function useTypeahead(getLabels: () => string[]): (key: string, currentIndex: number) => number;

package/dist/utils/useTypeahead.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+export declare function isTypeaheadKey(event: Pick<React.KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey'>): boolean;
+/**
+ * The letter-key search a listbox runs against a *collection* rather than
+ * against focusable DOM nodes — which is the whole point: `useRovingFocus`'s
+ * built-in typeahead can only see mounted elements, so a Select whose listbox
+ * has never been opened has nothing to search. This one takes the labels the
+ * root already knows, so typeahead works on a closed trigger.
+ *
+ * Returns a matcher: feed it a key and the currently-selected index, get back
+ * the index to move to, or `-1` for no match. The 1s buffer means `"s"`,
+ * `"a"` in quick succession searches for `"sa"`, while the same two keys a
+ * second apart are two separate single-letter searches — and repeating one
+ * letter cycles through the entries starting with it, the way a native
+ * `<select>` does.
+ */
+export declare function useTypeahead(getLabels: () => string[]): (key: string, currentIndex: number) => number;

package/dist/utils/useTypeahead.js

@@ -0,0 +1 @@
+import*as t from"react";var m=1e3;function R(e){return e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey}function h(e){let c=t.useRef(""),a=t.useRef(void 0);return t.useEffect(()=>()=>clearTimeout(a.current),[]),t.useCallback((i,u)=>{clearTimeout(a.current),c.current+=i.toLowerCase(),a.current=setTimeout(()=>{c.current=""},m);let r=c.current,o=e(),s=r.length>1&&[...r].every(n=>n===r[0]),l=s?r[0]:r,y=s||r.length===1?u+1:u;for(let n=0;n<o.length;n++){let f=(Math.max(y,0)+n)%o.length;if(o[f].trim().toLowerCase().startsWith(l))return f}return-1},[e])}export{R as isTypeaheadKey,h as useTypeahead};

package/dist/utils/visuallyHidden.cjs

@@ -0,0 +1 @@
+"use strict";var m=Object.create;var a=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var w=Object.getPrototypeOf,y=Object.prototype.hasOwnProperty;var c=(i,e)=>{for(var r in e)a(i,r,{get:e[r],enumerable:!0})},p=(i,e,r,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of h(e))!y.call(i,t)&&t!==r&&a(i,t,{get:()=>e[t],enumerable:!(o=f(e,t))||o.enumerable});return i};var P=(i,e,r)=>(r=i!=null?m(w(i)):{},p(e||!i||!i.__esModule?a(r,"default",{value:i,enumerable:!0}):r,i)),R=i=>p(a({},"__esModule",{value:!0}),i);var v={};c(v,{VisuallyHidden:()=>n});module.exports=R(v);var d=P(require("react"),1),l=require("./primitive.cjs"),s=require("react/jsx-runtime"),n=d.forwardRef((i,e)=>(0,s.jsx)(l.Primitive.span,{...i,ref:e,style:{position:"absolute",border:0,width:1,height:1,padding:0,margin:-1,overflow:"hidden",clip:"rect(0, 0, 0, 0)",whiteSpace:"nowrap",wordWrap:"normal",...i.style}}));n.displayName="VisuallyHidden";0&&(module.exports={VisuallyHidden});

package/dist/utils/visuallyHidden.d.cts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { type PrimitivePropsWithRef } from './primitive.cjs';
+/**
+ * Renders its children off-screen but keeps them in the accessibility tree —
+ * for text that a screen reader should announce without being visible, such
+ * as an icon-only button's label.
+ *
+ * @example
+ * ```tsx
+ * <Button>
+ *   <VisuallyHidden>Close</VisuallyHidden>
+ *   <XIcon />
+ * </Button>
+ * ```
+ */
+export declare const VisuallyHidden: React.ForwardRefExoticComponent<Omit<PrimitivePropsWithRef<"span">, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/utils/visuallyHidden.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { type PrimitivePropsWithRef } from './primitive.js';
+/**
+ * Renders its children off-screen but keeps them in the accessibility tree —
+ * for text that a screen reader should announce without being visible, such
+ * as an icon-only button's label.
+ *
+ * @example
+ * ```tsx
+ * <Button>
+ *   <VisuallyHidden>Close</VisuallyHidden>
+ *   <XIcon />
+ * </Button>
+ * ```
+ */
+export declare const VisuallyHidden: React.ForwardRefExoticComponent<Omit<PrimitivePropsWithRef<"span">, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/utils/visuallyHidden.js

@@ -0,0 +1 @@
+import*as e from"react";import{Primitive as t}from"./primitive.js";import{jsx as o}from"react/jsx-runtime";var a=e.forwardRef((i,r)=>o(t.span,{...i,ref:r,style:{position:"absolute",border:0,width:1,height:1,padding:0,margin:-1,overflow:"hidden",clip:"rect(0, 0, 0, 0)",whiteSpace:"nowrap",wordWrap:"normal",...i.style}}));a.displayName="VisuallyHidden";export{a as VisuallyHidden};