@skdx/vue 0.26.0

package/dist/utils/useFormReset.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @internal Runs `restore` whenever the `<form>` owning `control` is reset.
+ *
+ * A native input resets itself, but a value Vue owns does not: the component
+ * has to put its declared default back by hand. `control` is whatever element
+ * actually carries the value into the form — the wrapped native input, or the
+ * first hidden one — which is also how the form is found, since
+ * `HTMLInputElement.form` follows a `form=""` attribute as well as an
+ * enclosing `<form>`. It is read through a getter because that element only
+ * exists after mount, and can be replaced (or removed with `name`) later.
+ *
+ * `restore` runs from the `reset` event, i.e. *before* the browser resets the
+ * form's native controls. Components restoring a value Vue re-renders from
+ * (a hidden input bound with `:value.attr`, whose reset default is the
+ * attribute Vue keeps up to date) need nothing else; one writing into a native
+ * input's `value` property has to write it again on `nextTick`, after the
+ * browser's own reset has run.
+ */
+export declare function useFormReset(control: () => HTMLInputElement | null | undefined, restore: () => void): void;

package/dist/utils/useFormReset.js

@@ -0,0 +1 @@
+import{onBeforeUnmount as e,watch as t}from"vue";function n(n,r){let s=null;const o=()=>r();t(n,e=>{s?.removeEventListener("reset",o),s=e?.form??null,s?.addEventListener("reset",o)},{immediate:!0,flush:"post"}),e(()=>s?.removeEventListener("reset",o))}export{n as useFormReset};

package/dist/utils/useMenuItem.cjs

@@ -0,0 +1 @@
+let i=require("vue");function o({disabled:t,onSelect:u,onSelected:r,contentRef:a}){function n(){if(t.value)return;const e=new CustomEvent("skdx-menu-item-select",{cancelable:!0});u?.(e),e.defaultPrevented||r()}return{itemAttrs:(0,i.computed)(()=>({"data-disabled":t.value?"":void 0,"aria-disabled":t.value||void 0,tabindex:t.value?void 0:-1})),onItemClick(){n()},onItemKeydown(e){[" ","Enter"].includes(e.key)&&(e.preventDefault(),n())},onItemPointerenter(e){t.value||e.currentTarget?.focus()},onItemPointerleave(e){e.currentTarget===document.activeElement&&a.value?.focus()}}}exports.useMenuItem=o;

package/dist/utils/useMenuItem.d.cts

@@ -0,0 +1,31 @@
+import { type ComputedRef, type Ref } from 'vue';
+/** @internal Options for useMenuItem: disabled state, select callbacks, and the container to refocus on pointer-leave. */
+export interface UseMenuItemOptions {
+    disabled: Ref<boolean | undefined>;
+    /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
+    onSelect?: (event: Event) => void;
+    /** 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: Ref<HTMLElement | null>;
+}
+/** @internal Attributes and event handlers useMenuItem returns for a component to bind on its menuitem element. */
+export interface MenuItemBindings {
+    itemAttrs: ComputedRef<{
+        'data-disabled': string | undefined;
+        'aria-disabled': true | undefined;
+        tabindex: number | undefined;
+    }>;
+    onItemClick(): void;
+    onItemKeydown(event: KeyboardEvent): void;
+    onItemPointerenter(event: PointerEvent): void;
+    onItemPointerleave(event: PointerEvent): void;
+}
+/**
+ * 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. Mirrors `packages/react/src/utils/useMenuItem.ts`.
+ * @internal
+ */
+export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, }: UseMenuItemOptions): MenuItemBindings;

package/dist/utils/useMenuItem.d.ts

@@ -0,0 +1,31 @@
+import { type ComputedRef, type Ref } from 'vue';
+/** @internal Options for useMenuItem: disabled state, select callbacks, and the container to refocus on pointer-leave. */
+export interface UseMenuItemOptions {
+    disabled: Ref<boolean | undefined>;
+    /** Called when the item is activated. `event.preventDefault()` keeps the menu open. */
+    onSelect?: (event: Event) => void;
+    /** 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: Ref<HTMLElement | null>;
+}
+/** @internal Attributes and event handlers useMenuItem returns for a component to bind on its menuitem element. */
+export interface MenuItemBindings {
+    itemAttrs: ComputedRef<{
+        'data-disabled': string | undefined;
+        'aria-disabled': true | undefined;
+        tabindex: number | undefined;
+    }>;
+    onItemClick(): void;
+    onItemKeydown(event: KeyboardEvent): void;
+    onItemPointerenter(event: PointerEvent): void;
+    onItemPointerleave(event: PointerEvent): void;
+}
+/**
+ * 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. Mirrors `packages/react/src/utils/useMenuItem.ts`.
+ * @internal
+ */
+export declare function useMenuItem({ disabled, onSelect, onSelected, contentRef, }: UseMenuItemOptions): MenuItemBindings;

package/dist/utils/useMenuItem.js

@@ -0,0 +1 @@
+import{computed as e}from"vue";function t({disabled:t,onSelect:n,onSelected:a,contentRef:o}){function u(){if(t.value)return;const e=new CustomEvent("skdx-menu-item-select",{cancelable:!0});n?.(e),e.defaultPrevented||a()}return{itemAttrs:e(()=>({"data-disabled":t.value?"":void 0,"aria-disabled":t.value||void 0,tabindex:t.value?void 0:-1})),onItemClick(){u()},onItemKeydown(e){[" ","Enter"].includes(e.key)&&(e.preventDefault(),u())},onItemPointerenter(e){t.value||e.currentTarget?.focus()},onItemPointerleave(e){e.currentTarget===document.activeElement&&o.value?.focus()}}}export{t as useMenuItem};

package/dist/utils/useOpenChangeComplete.cjs

@@ -0,0 +1 @@
+let d=require("vue");var m=["animationend","animationcancel","transitionend","transitioncancel"];function p(i){const{animationName:n,transitionDuration:o,display:t}=getComputedStyle(i);return t==="none"?!1:n!==""&&n!=="none"?!0:o.split(",").some(r=>Number.parseFloat(r)>0)}function v(i,n,o){(0,d.watch)(i,(t,r,f)=>{let s;const u=()=>{const e=n.value;if(!e||!e.isConnected||!p(e)){o(t);return}const c=a=>{a.target===e&&o(t)};for(const a of m)e.addEventListener(a,c);s=()=>{for(const a of m)e.removeEventListener(a,c)}};let l=0;t&&!n.value?l=requestAnimationFrame(u):u(),f(()=>{cancelAnimationFrame(l),s?.()})},{flush:"post"})}exports.useOpenChangeComplete=v;

package/dist/utils/useOpenChangeComplete.d.cts

@@ -0,0 +1,28 @@
+import { type Ref } from 'vue';
+/**
+ * Calls `onComplete` 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 it declares no motion (the same task on close, the
+ * next frame on an open whose content is not in the DOM yet).
+ *
+ * The settled counterpart to `open-change`, 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` Vue has already unmounted it and cleared the ref, which is
+ * itself the signal that nothing is animating and the close is complete.
+ *
+ * The watcher is `flush: 'post'` so it reads the ref *after* the content has
+ * mounted, and it is deliberately not `immediate`: the initial state is not a
+ * *change*, so it never completes one — without that a mounted-closed overlay
+ * would announce a close nobody asked for.
+ *
+ * @example
+ * ```ts
+ * useOpenChangeComplete(open, contentRef, (next) => emit('open-change-complete', next));
+ * ```
+ * @internal
+ */
+export declare function useOpenChangeComplete(open: Ref<boolean>, nodeRef: Ref<HTMLElement | null>, onComplete: (open: boolean) => void): void;

package/dist/utils/useOpenChangeComplete.d.ts

@@ -0,0 +1,28 @@
+import { type Ref } from 'vue';
+/**
+ * Calls `onComplete` 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 it declares no motion (the same task on close, the
+ * next frame on an open whose content is not in the DOM yet).
+ *
+ * The settled counterpart to `open-change`, 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` Vue has already unmounted it and cleared the ref, which is
+ * itself the signal that nothing is animating and the close is complete.
+ *
+ * The watcher is `flush: 'post'` so it reads the ref *after* the content has
+ * mounted, and it is deliberately not `immediate`: the initial state is not a
+ * *change*, so it never completes one — without that a mounted-closed overlay
+ * would announce a close nobody asked for.
+ *
+ * @example
+ * ```ts
+ * useOpenChangeComplete(open, contentRef, (next) => emit('open-change-complete', next));
+ * ```
+ * @internal
+ */
+export declare function useOpenChangeComplete(open: Ref<boolean>, nodeRef: Ref<HTMLElement | null>, onComplete: (open: boolean) => void): void;

package/dist/utils/useOpenChangeComplete.js

@@ -0,0 +1 @@
+import{watch as n}from"vue";var e=["animationend","animationcancel","transitionend","transitioncancel"];function t(t,o,a){n(t,(n,t,i)=>{let r;const s=()=>{const t=o.value;if(!t||!t.isConnected||!function(n){const{animationName:e,transitionDuration:t,display:o}=getComputedStyle(n);return"none"!==o&&(""!==e&&"none"!==e||t.split(",").some(n=>Number.parseFloat(n)>0))}(t))return void a(n);const i=e=>{e.target===t&&a(n)};for(const n of e)t.addEventListener(n,i);r=()=>{for(const n of e)t.removeEventListener(n,i)}};let c=0;n&&!o.value?c=requestAnimationFrame(s):s(),i(()=>{cancelAnimationFrame(c),r?.()})},{flush:"post"})}export{t as useOpenChangeComplete};

package/dist/utils/usePointerAngle.cjs

@@ -0,0 +1 @@
+let g=require("vue");function m(r,e){return(Math.atan2(r,-e)*180/Math.PI+360)%360}function v(r,e){return e?Math.round(Math.round(r/e)*e*1e6)/1e6%360:r}function A(r,e){const d=(0,g.ref)(!1);let l=null;const f=(o,t)=>{const n=t.getBoundingClientRect();return v(m(o.clientX-(n.left+n.width/2),o.clientY-(n.top+n.height/2)),(0,g.toValue)(e.step)??0)};function p(o){if(l)return;const t=r.value;if(!t)return;const{pointerId:n}=o;t.setPointerCapture?.(n);let a=f(o,t);d.value=!0,e.onAngleChange(a,o);const h=u=>{if(u.pointerId!==n)return;const s=f(u,t);s!==a&&(a=s,e.onAngleChange(s,u))},c=u=>{u.pointerId===n&&(l?.(),d.value=!1,e.onAngleChangeEnd?.(a,u))},i=t.ownerDocument;i.addEventListener("pointermove",h),i.addEventListener("pointerup",c),i.addEventListener("pointercancel",c),l=()=>{i.removeEventListener("pointermove",h),i.removeEventListener("pointerup",c),i.removeEventListener("pointercancel",c),l=null}}return(0,g.onUnmounted)(()=>l?.()),{onPointerDown:p,dragging:d}}exports.usePointerAngle=A;

package/dist/utils/usePointerAngle.d.cts

@@ -0,0 +1,89 @@
+/**
+ * Pointer-drag-to-angle, for widgets whose input is a *direction* rather than a
+ * distance (angle slider, hue wheel, gradient-angle picker, compass). Mirrors
+ * `packages/react/src/utils/usePointerAngle.ts`. @internal
+ */
+import { type MaybeRefOrGetter, type Ref } from 'vue';
+/** Options for {@link usePointerAngle}. @internal */
+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. Accepts a ref or getter, so a component
+     * whose `step` is a reactive prop is read fresh on every move.
+     * @default 0 — continuous; every pixel of movement reports a fresh angle.
+     */
+    step?: MaybeRefOrGetter<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 callback 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}. @internal */
+export interface UsePointerAngleResult {
+    /**
+     * Bind on the element that defines the circle via `@pointerdown`. The
+     * measurement source is the element in the ref handed to the composable —
+     * its border box 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: PointerEvent) => void;
+    /**
+     * `true` between pointer down and pointer up/cancel. Suitable for a
+     * `data-dragging` styling hook; it flips once per drag boundary and never
+     * per move.
+     */
+    dragging: Readonly<Ref<boolean>>;
+}
+/**
+ * Turns a pointer position inside an element into a normalized angle.
+ *
+ * **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 composable already accounts for — callers
+ * pass raw `clientX`/`clientY` and never touch the sign themselves. Values are
+ * always in `[0, 360)`; 360 is never emitted.
+ *
+ * It 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 call `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.
+ *
+ * Nothing is measured or subscribed during `setup`, so it is safe under SSR.
+ *
+ * @param elementRef Template ref for the element whose border box defines the circle.
+ * @example
+ * ```ts
+ * const wheelRef = ref<HTMLElement | null>(null);
+ * const hue = ref(0);
+ * const { onPointerDown, dragging } = usePointerAngle(wheelRef, {
+ *   step: () => props.step,
+ *   onAngleChange: (angle) => (hue.value = angle),
+ *   onAngleChangeEnd: (angle) => emit('value-commit', angle),
+ * });
+ * ```
+ * ```vue
+ * <div
+ *   ref="wheelRef"
+ *   :data-dragging="dragging ? '' : undefined"
+ *   :style="{ touchAction: 'none', '--hue': `${hue}deg` }"
+ *   @pointerdown="onPointerDown"
+ * />
+ * ```
+ */
+export declare function usePointerAngle(elementRef: Ref<HTMLElement | null>, options: UsePointerAngleOptions): UsePointerAngleResult;

package/dist/utils/usePointerAngle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pointer-drag-to-angle, for widgets whose input is a *direction* rather than a
+ * distance (angle slider, hue wheel, gradient-angle picker, compass). Mirrors
+ * `packages/react/src/utils/usePointerAngle.ts`. @internal
+ */
+import { type MaybeRefOrGetter, type Ref } from 'vue';
+/** Options for {@link usePointerAngle}. @internal */
+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. Accepts a ref or getter, so a component
+     * whose `step` is a reactive prop is read fresh on every move.
+     * @default 0 — continuous; every pixel of movement reports a fresh angle.
+     */
+    step?: MaybeRefOrGetter<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 callback 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}. @internal */
+export interface UsePointerAngleResult {
+    /**
+     * Bind on the element that defines the circle via `@pointerdown`. The
+     * measurement source is the element in the ref handed to the composable —
+     * its border box 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: PointerEvent) => void;
+    /**
+     * `true` between pointer down and pointer up/cancel. Suitable for a
+     * `data-dragging` styling hook; it flips once per drag boundary and never
+     * per move.
+     */
+    dragging: Readonly<Ref<boolean>>;
+}
+/**
+ * Turns a pointer position inside an element into a normalized angle.
+ *
+ * **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 composable already accounts for — callers
+ * pass raw `clientX`/`clientY` and never touch the sign themselves. Values are
+ * always in `[0, 360)`; 360 is never emitted.
+ *
+ * It 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 call `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.
+ *
+ * Nothing is measured or subscribed during `setup`, so it is safe under SSR.
+ *
+ * @param elementRef Template ref for the element whose border box defines the circle.
+ * @example
+ * ```ts
+ * const wheelRef = ref<HTMLElement | null>(null);
+ * const hue = ref(0);
+ * const { onPointerDown, dragging } = usePointerAngle(wheelRef, {
+ *   step: () => props.step,
+ *   onAngleChange: (angle) => (hue.value = angle),
+ *   onAngleChangeEnd: (angle) => emit('value-commit', angle),
+ * });
+ * ```
+ * ```vue
+ * <div
+ *   ref="wheelRef"
+ *   :data-dragging="dragging ? '' : undefined"
+ *   :style="{ touchAction: 'none', '--hue': `${hue}deg` }"
+ *   @pointerdown="onPointerDown"
+ * />
+ * ```
+ */
+export declare function usePointerAngle(elementRef: Ref<HTMLElement | null>, options: UsePointerAngleOptions): UsePointerAngleResult;

package/dist/utils/usePointerAngle.js

@@ -0,0 +1 @@
+import{onUnmounted as e,ref as n,toValue as t}from"vue";function o(o,r){const i=n(!1);let u=null;const a=(e,n)=>{const o=n.getBoundingClientRect();return function(e,n){return n?Math.round(Math.round(e/n)*n*1e6)/1e6%360:e}(function(e,n){return(180*Math.atan2(e,-n)/Math.PI+360)%360}(e.clientX-(o.left+o.width/2),e.clientY-(o.top+o.height/2)),t(r.step)??0)};return e(()=>u?.()),{onPointerDown:function(e){if(u)return;const n=o.value;if(!n)return;const{pointerId:t}=e;n.setPointerCapture?.(t);let l=a(e,n);i.value=!0,r.onAngleChange(l,e);const s=e=>{if(e.pointerId!==t)return;const o=a(e,n);o!==l&&(l=o,r.onAngleChange(o,e))},c=e=>{e.pointerId===t&&(u?.(),i.value=!1,r.onAngleChangeEnd?.(l,e))},d=n.ownerDocument;d.addEventListener("pointermove",s),d.addEventListener("pointerup",c),d.addEventListener("pointercancel",c),u=()=>{d.removeEventListener("pointermove",s),d.removeEventListener("pointerup",c),d.removeEventListener("pointercancel",c),u=null}},dragging:i}}export{o as usePointerAngle};

package/dist/utils/useRovingFocus.cjs

@@ -0,0 +1 @@
+const T=require("./direction.cjs");let b=require("vue");function v(o,a,g,n){const u=()=>{const i=Array.from(o.value?.querySelectorAll(a)??[],s=>s.getAttribute(g)).filter(s=>s!==null&&s!==""),l=i[0];l===void 0||n.value!==null&&i.includes(n.value)||(n.value=l)};return(0,b.onMounted)(u),(0,b.onUpdated)(u),u}var x=1e3;function m(o){return o.getAttribute("data-text-value")??o.textContent??""}var E={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},R={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function K({orientation:o="both",loop:a=!0,itemSelector:g,typeahead:n=!1,direction:u}){let i="",l;return function(r){const h=r.currentTarget,t=Array.from(h.querySelectorAll(g)).filter(d=>!d.hasAttribute("disabled")&&d.getAttribute("data-disabled")===null);if(t.length===0)return;const f=t.indexOf(r.target),c=T.directionalKey(r.key,h,u?.());let e;if(E[o].includes(c))e=f+1,e>=t.length&&(e=a?0:t.length-1);else if(R[o].includes(c))e=f-1,e<0&&(e=a?t.length-1:0);else if(c==="Home")e=0;else if(c==="End")e=t.length-1;else if(n&&r.key.length===1&&!r.ctrlKey&&!r.metaKey&&!r.altKey){clearTimeout(l),i+=r.key.toLowerCase(),l=setTimeout(()=>{i=""},x);const d=i,w=y=>m(y).trim().toLowerCase().startsWith(d),A=[...t.slice(f+1),...t.slice(0,f+1)].find(w);A&&(e=t.indexOf(A))}e!==void 0&&(r.preventDefault(),t[e]?.focus())}}exports.itemText=m;exports.useRovingFocus=K;exports.useRovingTabStop=v;

package/dist/utils/useRovingFocus.d.cts

@@ -0,0 +1,59 @@
+/**
+ * DOM-driven roving focus for composite widgets (menus, menubars). Returns a
+ * keydown handler to bind on the group element via `@keydown`. Items are
+ * discovered by selector, so no registration plumbing is needed. Mirrors
+ * `packages/react/src/utils/useRovingFocus.ts`. @internal
+ */
+import { type Ref } from 'vue';
+import { type Direction } from './direction.cjs';
+export type Orientation = 'horizontal' | 'vertical' | 'both';
+/**
+ * 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".
+ *
+ * Runs on mount and after every re-render of the group, since 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 assignment. The reseed is
+ * returned so a group whose items unmount *without* it re-rendering (a tree
+ * collapsing a branch its own children own) can re-run it from a post-flush
+ * watcher.
+ *
+ * Mirrors `packages/react/src/utils/useRovingFocus.ts`'s `useRovingTabStop`.
+ * @internal
+ */
+export declare function useRovingTabStop(rootRef: Ref<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: Ref<string | null>): () => void;
+interface UseRovingFocusOptions {
+    /** Axis the arrow keys navigate (defaults to both). */
+    orientation?: Orientation;
+    /** Whether moving past the last/first item wraps around to the other end. */
+    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;
+    /** Writing direction override; omit to resolve from the nearest `[dir]` ancestor. */
+    direction?: () => Direction | undefined;
+}
+/**
+ * The text typeahead matches an item against: its explicit `data-text-value`
+ * if it has one, else its rendered text.
+ *
+ * Raw `textContent` alone is wrong for any item that renders more than its
+ * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
+ * skips exactly the items that are currently selected. `data-text-value` is
+ * the escape hatch, and this is the one precedence rule every matcher in the
+ * repo follows.
+ *
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/** @internal Returns a group keydown handler that moves focus between items via arrow/Home/End keys and optional typeahead. */
+export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
+export {};

package/dist/utils/useRovingFocus.d.ts

@@ -0,0 +1,59 @@
+/**
+ * DOM-driven roving focus for composite widgets (menus, menubars). Returns a
+ * keydown handler to bind on the group element via `@keydown`. Items are
+ * discovered by selector, so no registration plumbing is needed. Mirrors
+ * `packages/react/src/utils/useRovingFocus.ts`. @internal
+ */
+import { type Ref } from 'vue';
+import { type Direction } from './direction.js';
+export type Orientation = 'horizontal' | 'vertical' | 'both';
+/**
+ * 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".
+ *
+ * Runs on mount and after every re-render of the group, since 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 assignment. The reseed is
+ * returned so a group whose items unmount *without* it re-rendering (a tree
+ * collapsing a branch its own children own) can re-run it from a post-flush
+ * watcher.
+ *
+ * Mirrors `packages/react/src/utils/useRovingFocus.ts`'s `useRovingTabStop`.
+ * @internal
+ */
+export declare function useRovingTabStop(rootRef: Ref<HTMLElement | null>, itemSelector: string, idAttribute: string, currentId: Ref<string | null>): () => void;
+interface UseRovingFocusOptions {
+    /** Axis the arrow keys navigate (defaults to both). */
+    orientation?: Orientation;
+    /** Whether moving past the last/first item wraps around to the other end. */
+    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;
+    /** Writing direction override; omit to resolve from the nearest `[dir]` ancestor. */
+    direction?: () => Direction | undefined;
+}
+/**
+ * The text typeahead matches an item against: its explicit `data-text-value`
+ * if it has one, else its rendered text.
+ *
+ * Raw `textContent` alone is wrong for any item that renders more than its
+ * label — an item with an `ItemIndicator` reads as `"✓Apple"`, so typing `a`
+ * skips exactly the items that are currently selected. `data-text-value` is
+ * the escape hatch, and this is the one precedence rule every matcher in the
+ * repo follows.
+ *
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/** @internal Returns a group keydown handler that moves focus between items via arrow/Home/End keys and optional typeahead. */
+export declare function useRovingFocus({ orientation, loop, itemSelector, typeahead, direction, }: UseRovingFocusOptions): (event: KeyboardEvent) => void;
+export {};

package/dist/utils/useRovingFocus.js

@@ -0,0 +1 @@
+import{directionalKey as e}from"./direction.js";import{onMounted as t,onUpdated as r}from"vue";function o(e,o,i,n){const l=()=>{const t=Array.from(e.value?.querySelectorAll(o)??[],e=>e.getAttribute(i)).filter(e=>null!==e&&""!==e),r=t[0];void 0===r||null!==n.value&&t.includes(n.value)||(n.value=r)};return t(l),r(l),l}function i(e){return e.getAttribute("data-text-value")??e.textContent??""}var n={horizontal:["ArrowRight"],vertical:["ArrowDown"],both:["ArrowRight","ArrowDown"]},l={horizontal:["ArrowLeft"],vertical:["ArrowUp"],both:["ArrowLeft","ArrowUp"]};function a({orientation:t="both",loop:r=!0,itemSelector:o,typeahead:a=!1,direction:u}){let s,c="";return function(f){const d=f.currentTarget,h=Array.from(d.querySelectorAll(o)).filter(e=>!e.hasAttribute("disabled")&&null===e.getAttribute("data-disabled"));if(0===h.length)return;const A=h.indexOf(f.target),g=e(f.key,d,u?.());let v;if(n[t].includes(g))v=A+1,v>=h.length&&(v=r?0:h.length-1);else if(l[t].includes(g))v=A-1,v<0&&(v=r?h.length-1:0);else if("Home"===g)v=0;else if("End"===g)v=h.length-1;else if(a&&1===f.key.length&&!f.ctrlKey&&!f.metaKey&&!f.altKey){clearTimeout(s),c+=f.key.toLowerCase(),s=setTimeout(()=>{c=""},1e3);const e=c,t=t=>i(t).trim().toLowerCase().startsWith(e),r=[...h.slice(A+1),...h.slice(0,A+1)].find(t);r&&(v=h.indexOf(r))}void 0!==v&&(f.preventDefault(),h[v]?.focus())}}export{i as itemText,a as useRovingFocus,o as useRovingTabStop};

package/dist/utils/useSelection.cjs

@@ -0,0 +1 @@
+function o(n){return n===void 0?[]:Array.isArray(n)?n:[n]}function f(n,r,t){return t?n.includes(r)?n.filter(i=>i!==r):[...n,r]:r}exports.nextSelection=f;exports.toValues=o;

package/dist/utils/useSelection.d.cts

@@ -0,0 +1,28 @@
+/**
+ * The single/multiple selection model shared by every option-list component:
+ * Listbox, Select, and Combobox. Mirrors `packages/react/src/utils/useSelection.ts`,
+ * minus its `useSelection` hook: Vue's controlled/uncontrolled plumbing is
+ * per-component (`SkdxSelect` mirrors props into a `reactive` state object,
+ * `SkdxCombobox` pairs `uncontrolled*` refs with `computed`s), so what the three
+ * genuinely share here is the decision, not the plumbing. @internal
+ */
+/**
+ * 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 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[];

package/dist/utils/useSelection.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The single/multiple selection model shared by every option-list component:
+ * Listbox, Select, and Combobox. Mirrors `packages/react/src/utils/useSelection.ts`,
+ * minus its `useSelection` hook: Vue's controlled/uncontrolled plumbing is
+ * per-component (`SkdxSelect` mirrors props into a `reactive` state object,
+ * `SkdxCombobox` pairs `uncontrolled*` refs with `computed`s), so what the three
+ * genuinely share here is the decision, not the plumbing. @internal
+ */
+/**
+ * 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 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[];

package/dist/utils/useSelection.js

@@ -0,0 +1 @@
+function r(r){return void 0===r?[]:Array.isArray(r)?r:[r]}function e(r,e,n){return n?r.includes(e)?r.filter(r=>r!==e):[...r,e]:e}export{e as nextSelection,r as toValues};

package/dist/utils/useTypeahead.cjs

@@ -0,0 +1 @@
+let y=require("vue");var c=1e3;function T(e){return e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey}function f(){let e="",r;return(0,y.onBeforeUnmount)(()=>clearTimeout(r)),function(u,a,n){clearTimeout(r),e+=u.toLowerCase(),r=setTimeout(()=>{e=""},c);const o=e.length>1&&[...e].every(t=>t===e[0]),h=o?e[0]:e,s=o||e.length===1?n+1:n;for(let t=0;t<a.length;t++){const i=(Math.max(s,0)+t)%a.length;if(a[i].trim().toLowerCase().startsWith(h))return i}return-1}}exports.isTypeaheadKey=T;exports.useTypeahead=f;

package/dist/utils/useTypeahead.d.cts

@@ -0,0 +1,16 @@
+/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
+/**
+ * The letter-key search a closed trigger runs against the root's *collection*
+ * rather than against mounted DOM nodes — which is the whole point: a listbox
+ * that has never opened has no option elements to search. Returns 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.
+ *
+ * A composable, not a bare function, because the buffer and its timer belong to
+ * one component instance: call it during `setup()` so the timer is cleared when
+ * that instance unmounts.
+ */
+export declare function useTypeahead(): (key: string, labels: string[], currentIndex: number) => number;

package/dist/utils/useTypeahead.d.ts

@@ -0,0 +1,16 @@
+/** Whether a keydown is a plain printable character rather than a shortcut or a named key. */
+export declare function isTypeaheadKey(event: KeyboardEvent): boolean;
+/**
+ * The letter-key search a closed trigger runs against the root's *collection*
+ * rather than against mounted DOM nodes — which is the whole point: a listbox
+ * that has never opened has no option elements to search. Returns 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.
+ *
+ * A composable, not a bare function, because the buffer and its timer belong to
+ * one component instance: call it during `setup()` so the timer is cleared when
+ * that instance unmounts.
+ */
+export declare function useTypeahead(): (key: string, labels: string[], currentIndex: number) => number;

package/dist/utils/useTypeahead.js

@@ -0,0 +1 @@
+import{onBeforeUnmount as e}from"vue";function t(e){return 1===e.key.length&&!e.ctrlKey&&!e.metaKey&&!e.altKey}function r(){let t,r="";return e(()=>clearTimeout(t)),function(e,n,o){clearTimeout(t),r+=e.toLowerCase(),t=setTimeout(()=>{r=""},1e3);const a=r.length>1&&[...r].every(e=>e===r[0]),u=a?r[0]:r,s=a||1===r.length?o+1:o;for(let e=0;e<n.length;e++){const t=(Math.max(s,0)+e)%n.length;if(n[t].trim().toLowerCase().startsWith(u))return t}return-1}}export{t as isTypeaheadKey,r as useTypeahead};