@skdx/vue 0.28.0 → 0.29.0

package/dist/utils/timer.d.ts

@@ -0,0 +1,82 @@
+/** Where the clock stands: never started, running, held by a pause, or finished. */
+export type TimerPhase = 'idle' | 'running' | 'paused' | 'complete';
+/** The clock as a consumer renders it, computed fresh on every read. */
+export interface TimerState {
+    /** Where the clock stands right now, as one of the four phases. */
+    phase: TimerPhase;
+    /** Milliseconds the clock has actually run, never counting paused time. */
+    elapsed: number;
+    /** Milliseconds left before completion, or `Infinity` when counting up. */
+    remaining: number;
+    /** The countdown length in force, `Infinity` for an open-ended count-up. */
+    duration: number;
+}
+/** How one clock is configured; every field has a working default. */
+export interface TimerOptions {
+    /**
+     * Countdown length in milliseconds; leave it out to count up with no end.
+     *
+     * @default Infinity
+     */
+    duration?: number | undefined;
+    /**
+     * Milliseconds between `onTick` calls while running; `0` reports no ticks.
+     *
+     * @default 0
+     */
+    tickMs?: number | undefined;
+    /**
+     * Whether a hidden or unloading page pauses the clock and a returning page resumes it.
+     *
+     * @default true
+     */
+    pauseWhenHidden?: boolean | undefined;
+    /**
+     * Called on every tick and once more at completion, for rendering the clock only.
+     *
+     * Ticks are far too frequent to announce: write them to a progress bar or a
+     * `<time>`, never to a live region.
+     */
+    onTick?: ((state: TimerState) => void) | undefined;
+    /**
+     * Called when the phase changes, and only on an actual change, so it is the one place announcements belong.
+     */
+    onPhaseChange?: ((state: TimerState) => void) | undefined;
+}
+/** A framework-neutral countdown or count-up: `start`, `pause`, `resume`, `reset`, and a completion phase. */
+export declare class Timer {
+    private readonly options;
+    private readonly tickMs;
+    private duration;
+    private phase;
+    private accrued;
+    private startedAt;
+    private completion;
+    private ticker;
+    private pausedByPage;
+    constructor(options?: TimerOptions);
+    /** The phase, elapsed, remaining and duration as they read at this instant. */
+    get state(): TimerState;
+    /**
+     * Runs the clock from zero, replacing whatever it was doing.
+     *
+     * @param duration a new countdown length to adopt, in milliseconds
+     */
+    start(duration?: number): void;
+    /** Holds the clock where it stands; a second call while already paused changes nothing. */
+    pause(): void;
+    /** Runs the clock on from where a pause left it; ignored unless it is paused. */
+    resume(): void;
+    /** Stops the clock and returns it to zero, as it was before the first `start`. */
+    reset(): void;
+    /** Stops the clock and releases every listener and handle it holds. */
+    destroy(): void;
+    private measure;
+    private run;
+    private complete;
+    private setPhase;
+    private clearHandles;
+    private readonly onVisibilityChange;
+    private readonly onPageHide;
+    private pauseForPage;
+}

package/dist/utils/timer.js

@@ -0,0 +1 @@
+var t=class{constructor(t={}){this.phase="idle",this.accrued=0,this.startedAt=0,this.pausedByPage=!1,this.onVisibilityChange=()=>{document.hidden?this.pauseForPage():this.pausedByPage&&this.resume()},this.onPageHide=()=>{this.pauseForPage()},this.options=t,this.duration=t.duration??Number.POSITIVE_INFINITY,this.tickMs=t.tickMs??0,!(!1===t.pauseWhenHidden||typeof document>"u")&&(document.addEventListener("visibilitychange",this.onVisibilityChange),window.addEventListener("pagehide",this.onPageHide))}get state(){const t=this.measure();return{phase:this.phase,elapsed:t,remaining:this.duration-t,duration:this.duration}}start(t){void 0!==t&&(this.duration=t),this.clearHandles(),this.accrued=0,this.pausedByPage=!1,this.run()}pause(){this.pausedByPage=!1,"running"===this.phase&&(this.accrued=this.measure(),this.clearHandles(),this.setPhase("paused"))}resume(){this.pausedByPage=!1,"paused"===this.phase&&this.run()}reset(){this.clearHandles(),this.accrued=0,this.startedAt=0,this.pausedByPage=!1,this.setPhase("idle")}destroy(){this.clearHandles(),!(!1===this.options.pauseWhenHidden||typeof document>"u")&&(document.removeEventListener("visibilitychange",this.onVisibilityChange),window.removeEventListener("pagehide",this.onPageHide))}measure(){const t="running"===this.phase?Date.now()-this.startedAt:0;return Math.min(this.accrued+t,this.duration)}run(){this.startedAt=Date.now();const t=this.duration-this.accrued;Number.isFinite(t)&&(this.completion=setTimeout(()=>this.complete(),Math.max(t,0))),this.tickMs>0&&(this.ticker=setInterval(()=>this.options.onTick?.(this.state),this.tickMs)),this.setPhase("running")}complete(){this.clearHandles(),this.accrued=this.duration,this.setPhase("complete"),this.tickMs>0&&this.options.onTick?.(this.state)}setPhase(t){this.phase!==t&&(this.phase=t,this.options.onPhaseChange?.(this.state))}clearHandles(){clearTimeout(this.completion),clearInterval(this.ticker),this.completion=void 0,this.ticker=void 0}pauseForPage(){"running"===this.phase&&(this.pause(),this.pausedByPage=!0)}};export{t as Timer};

package/dist/utils/tree-columns.cjs

@@ -0,0 +1 @@
+function a(u,o){const r=new Set(o),l=[{parent:null,nodes:u}],s=new Set;let n=u;for(;;){const e=n.find(t=>r.has(t.value)&&!s.has(t.value)&&((t.children?.length??0)>0||t.hasChildren===!0));if(!e)return l;s.add(e.value),n=e.children??[],l.push({parent:e.value,nodes:n})}}function c(u,o){const r=(l,s)=>{for(const n of l){const e=[...s,n.value];if(n.value===o)return e;const t=n.children?r(n.children,e):null;if(t)return t}return null};return r(u,[])??[]}function d(u,o){return u.findIndex(r=>r.nodes.some(l=>l.value===o))}exports.columnIndexOf=d;exports.pathTo=c;exports.treeColumns=a;

package/dist/utils/tree-columns.d.cts

@@ -0,0 +1,48 @@
+/** The minimal node shape the projection reads; the adapters' own node types are supersets of it. */
+export interface TreeColumnNode {
+    value: string;
+    disabled?: boolean | undefined;
+    /** Declares a branch whose children have not loaded yet, so its column exists while still empty. */
+    hasChildren?: boolean | undefined;
+    children?: readonly TreeColumnNode[] | undefined;
+}
+/** One rendered column: the sibling set at a single depth. */
+export interface TreeColumn {
+    /** The branch whose children this column lists, or `null` for the root column. */
+    parent: string | null;
+    /** The column's nodes in collection order; empty while a lazy branch is still loading. */
+    nodes: readonly TreeColumnNode[];
+}
+/**
+ * The columns showing for an expanded set: the roots, then one column per expanded branch along a single open path.
+ *
+ * Columns are a chain, so at most one branch per depth can be open. An
+ * `expanded` set naming two branches at the same depth is not an error: the
+ * first in collection order wins and the rest are ignored, which keeps the
+ * projection total and lets a consumer hand the same `expanded` array to
+ * either layout.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param expanded every expanded node's value, in any order
+ * @returns the columns left to right; always at least the root column
+ */
+export declare function treeColumns(collection: readonly TreeColumnNode[], expanded: Iterable<string>): TreeColumn[];
+/**
+ * The chain of values from the root down to `value`, inclusive, or empty when the collection does not hold it.
+ *
+ * This is the expanded set that opens `value`'s own column: passing it to
+ * {@link treeColumns} shows every ancestor's column and closes every branch off
+ * the path. Dropping its last entry is the set that closes `value`'s column
+ * instead, which is what moving back a column needs.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param value the node to reach
+ */
+export declare function pathTo(collection: readonly TreeColumnNode[], value: string): string[];
+/**
+ * The index of the column holding `value`, or `-1` when no showing column does.
+ *
+ * @param columns the projection {@link treeColumns} returned
+ * @param value the node to locate
+ */
+export declare function columnIndexOf(columns: readonly TreeColumn[], value: string): number;

package/dist/utils/tree-columns.d.ts

@@ -0,0 +1,48 @@
+/** The minimal node shape the projection reads; the adapters' own node types are supersets of it. */
+export interface TreeColumnNode {
+    value: string;
+    disabled?: boolean | undefined;
+    /** Declares a branch whose children have not loaded yet, so its column exists while still empty. */
+    hasChildren?: boolean | undefined;
+    children?: readonly TreeColumnNode[] | undefined;
+}
+/** One rendered column: the sibling set at a single depth. */
+export interface TreeColumn {
+    /** The branch whose children this column lists, or `null` for the root column. */
+    parent: string | null;
+    /** The column's nodes in collection order; empty while a lazy branch is still loading. */
+    nodes: readonly TreeColumnNode[];
+}
+/**
+ * The columns showing for an expanded set: the roots, then one column per expanded branch along a single open path.
+ *
+ * Columns are a chain, so at most one branch per depth can be open. An
+ * `expanded` set naming two branches at the same depth is not an error: the
+ * first in collection order wins and the rest are ignored, which keeps the
+ * projection total and lets a consumer hand the same `expanded` array to
+ * either layout.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param expanded every expanded node's value, in any order
+ * @returns the columns left to right; always at least the root column
+ */
+export declare function treeColumns(collection: readonly TreeColumnNode[], expanded: Iterable<string>): TreeColumn[];
+/**
+ * The chain of values from the root down to `value`, inclusive, or empty when the collection does not hold it.
+ *
+ * This is the expanded set that opens `value`'s own column: passing it to
+ * {@link treeColumns} shows every ancestor's column and closes every branch off
+ * the path. Dropping its last entry is the set that closes `value`'s column
+ * instead, which is what moving back a column needs.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param value the node to reach
+ */
+export declare function pathTo(collection: readonly TreeColumnNode[], value: string): string[];
+/**
+ * The index of the column holding `value`, or `-1` when no showing column does.
+ *
+ * @param columns the projection {@link treeColumns} returned
+ * @param value the node to locate
+ */
+export declare function columnIndexOf(columns: readonly TreeColumn[], value: string): number;

package/dist/utils/tree-columns.js

@@ -0,0 +1 @@
+function n(n,e){const t=new Set(e),r=[{parent:null,nodes:n}],l=/* @__PURE__ */new Set;let u=n;for(;;){const n=u.find(n=>t.has(n.value)&&!l.has(n.value)&&((n.children?.length??0)>0||!0===n.hasChildren));if(!n)return r;l.add(n.value),u=n.children??[],r.push({parent:n.value,nodes:u})}}function e(n,e){const t=(n,r)=>{for(const l of n){const n=[...r,l.value];if(l.value===e)return n;const u=l.children?t(l.children,n):null;if(u)return u}return null};return t(n,[])??[]}function t(n,e){return n.findIndex(n=>n.nodes.some(n=>n.value===e))}export{t as columnIndexOf,e as pathTo,n as treeColumns};

package/dist/utils/typeahead.cjs

@@ -0,0 +1 @@
+var f=1e3;function u(t){return t.key.length===1&&!t.ctrlKey&&!t.metaKey&&!t.altKey}function c(t){return t.getAttribute("data-text-value")??t.textContent??""}var T=class{constructor(){this.buffer=""}match(t,i,a){if(t===" "&&this.buffer==="")return-1;clearTimeout(this.timer),this.buffer+=t.toLowerCase(),this.timer=setTimeout(()=>this.buffer="",f);const e=this.buffer,s=e.length>1&&[...e].every(r=>r===e[0]),n=s?e[0]:e,o=s||e.length===1?a+1:a;for(let r=0;r<i.length;r++){const h=(Math.max(o,0)+r)%i.length;if(i[h].trim().toLowerCase().startsWith(n))return h}return-1}clear(){clearTimeout(this.timer),this.buffer=""}};exports.TYPEAHEAD_TIMEOUT_MS=f;exports.Typeahead=T;exports.isTypeaheadKey=u;exports.itemText=c;

package/dist/utils/typeahead.d.cts

@@ -0,0 +1,27 @@
+/** How long successive keys keep merging into one search before the buffer resets. */
+export declare const TYPEAHEAD_TIMEOUT_MS = 1000;
+/** Plain printable character, not a shortcut or named key. */
+export declare function isTypeaheadKey(event: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}): boolean;
+/**
+ * Text typeahead matches: explicit `data-text-value`, else rendered text, since raw `textContent` fails for items rendering beyond their label.
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/** Letter-key search like native `<select>` (accumulating buffer and timer), shared by every collection and menu family. */
+export declare class Typeahead {
+    private buffer;
+    private timer?;
+    /**
+     * Matches `key` against the label collection, accumulating a 1s buffer (`"s"` + `"a"` = `"sa"`); repeating one letter cycles through matches.
+     *
+     * @returns the index to move to, or `-1` for no match.
+     */
+    match(key: string, labels: string[], currentIndex: number): number;
+    /** Drops the pending buffer and its timer. Call when the owner unmounts or closes. */
+    clear(): void;
+}

package/dist/utils/typeahead.d.ts

@@ -0,0 +1,27 @@
+/** How long successive keys keep merging into one search before the buffer resets. */
+export declare const TYPEAHEAD_TIMEOUT_MS = 1000;
+/** Plain printable character, not a shortcut or named key. */
+export declare function isTypeaheadKey(event: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}): boolean;
+/**
+ * Text typeahead matches: explicit `data-text-value`, else rendered text, since raw `textContent` fails for items rendering beyond their label.
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/** Letter-key search like native `<select>` (accumulating buffer and timer), shared by every collection and menu family. */
+export declare class Typeahead {
+    private buffer;
+    private timer?;
+    /**
+     * Matches `key` against the label collection, accumulating a 1s buffer (`"s"` + `"a"` = `"sa"`); repeating one letter cycles through matches.
+     *
+     * @returns the index to move to, or `-1` for no match.
+     */
+    match(key: string, labels: string[], currentIndex: number): number;
+    /** Drops the pending buffer and its timer. Call when the owner unmounts or closes. */
+    clear(): void;
+}

package/dist/utils/typeahead.js

@@ -0,0 +1 @@
+var t=1e3;function e(t){return 1===t.key.length&&!t.ctrlKey&&!t.metaKey&&!t.altKey}function r(t){return t.getAttribute("data-text-value")??t.textContent??""}var a=class{constructor(){this.buffer=""}match(t,e,r){if(" "===t&&""===this.buffer)return-1;clearTimeout(this.timer),this.buffer+=t.toLowerCase(),this.timer=setTimeout(()=>this.buffer="",1e3);const a=this.buffer,i=a.length>1&&[...a].every(t=>t===a[0]),s=i?a[0]:a,h=i||1===a.length?r+1:r;for(let t=0;t<e.length;t++){const r=(Math.max(h,0)+t)%e.length;if(e[r].trim().toLowerCase().startsWith(s))return r}return-1}clear(){clearTimeout(this.timer),this.buffer=""}};export{t as TYPEAHEAD_TIMEOUT_MS,a as Typeahead,e as isTypeaheadKey,r as itemText};

package/dist/utils/useBodyScrollLock.d.cts

@@ -1,7 +1,6 @@
 import { type Ref } from 'vue';
 /**
- * Lock body scroll while enabled, compensating for scrollbar width.
- * Reference-counted: only 0→1 and 1→0 transitions modify `document.body.style`.
+ * Locks body scroll while enabled, compensating for scrollbar width; reference-counted so only 0→1/1→0 transitions touch `document.body.style`.
  * @internal
  */
 export declare function useBodyScrollLock(enabled: Ref<boolean>): void;

package/dist/utils/useBodyScrollLock.d.ts

@@ -1,7 +1,6 @@
 import { type Ref } from 'vue';
 /**
- * Lock body scroll while enabled, compensating for scrollbar width.
- * Reference-counted: only 0→1 and 1→0 transitions modify `document.body.style`.
+ * Locks body scroll while enabled, compensating for scrollbar width; reference-counted so only 0→1/1→0 transitions touch `document.body.style`.
  * @internal
  */
 export declare function useBodyScrollLock(enabled: Ref<boolean>): void;

package/dist/utils/useCheckable.cjs

@@ -0,0 +1 @@
+const n=require("./useFormReset.cjs");let r=require("vue");function l(e){const t=(0,r.ref)(e.defaultChecked()),a=()=>e.checked()!==void 0,u=(0,r.computed)(()=>e.checked()??t.value);function c(d){a()||(t.value=d),e.onChange(d)}return n.useFormReset(e.resetTarget,()=>c(e.defaultChecked())),{checked:u,state:(0,r.computed)(()=>u.value==="indeterminate"?"indeterminate":u.value?"checked":"unchecked"),ariaChecked:(0,r.computed)(()=>u.value==="indeterminate"?"mixed":u.value?"true":"false"),hiddenChecked:(0,r.computed)(()=>u.value===!0),toggle(){e.disabled()||e.readOnly()||c(u.value==="indeterminate"?!0:!u.value)}}}exports.useCheckable=l;

package/dist/utils/useCheckable.d.cts

@@ -0,0 +1,38 @@
+import { type ComputedRef } from 'vue';
+/** @internal Checked state of a two- or three-state control; only a checkbox reaches `indeterminate`. */
+export type CheckedState = boolean | 'indeterminate';
+/** @internal What a checkable control hands the shared engine. */
+export interface UseCheckableOptions {
+    /** The consumer's controlled state; `undefined` leaves the control holding its own. */
+    checked: () => CheckedState | undefined;
+    /** The state an uncontrolled control starts at and a form reset restores. */
+    defaultChecked: () => CheckedState;
+    /** Whether toggling is refused; a read-only control keeps its tab stop. */
+    readOnly: () => boolean;
+    /** Whether toggling is refused because the control is out of use entirely. */
+    disabled: () => boolean;
+    /** Called with the state in force after a toggle or a form reset. */
+    onChange: (next: CheckedState) => void;
+    /** The element a form reset is observed through — the hidden input, or the control itself. */
+    resetTarget: () => HTMLElement | null;
+}
+/** @internal The checked state, its rendered spellings, and the toggle every checkable control shares. */
+export interface Checkable {
+    /** The state in force: the controlled one when there is one, the control's own otherwise. */
+    checked: ComputedRef<CheckedState>;
+    /** `data-state`: `checked`, `unchecked` or `indeterminate`. */
+    state: ComputedRef<'checked' | 'unchecked' | 'indeterminate'>;
+    /** `aria-checked`, where an indeterminate box announces as `mixed`. */
+    ariaChecked: ComputedRef<'true' | 'false' | 'mixed'>;
+    /** What the hidden form input carries, where indeterminate submits as unchecked. */
+    hiddenChecked: ComputedRef<boolean>;
+    /** Flips the state unless the control is disabled or read-only; indeterminate resolves to checked. */
+    toggle: () => void;
+}
+/**
+ * Shared checked-state engine for `role="checkbox"` and `role="switch"`: the
+ * controlled/uncontrolled split, the toggle, and the form-reset commit that
+ * keeps the button from drifting from the hidden input the browser restores.
+ * @internal
+ */
+export declare function useCheckable(options: UseCheckableOptions): Checkable;

package/dist/utils/useCheckable.d.ts

@@ -0,0 +1,38 @@
+import { type ComputedRef } from 'vue';
+/** @internal Checked state of a two- or three-state control; only a checkbox reaches `indeterminate`. */
+export type CheckedState = boolean | 'indeterminate';
+/** @internal What a checkable control hands the shared engine. */
+export interface UseCheckableOptions {
+    /** The consumer's controlled state; `undefined` leaves the control holding its own. */
+    checked: () => CheckedState | undefined;
+    /** The state an uncontrolled control starts at and a form reset restores. */
+    defaultChecked: () => CheckedState;
+    /** Whether toggling is refused; a read-only control keeps its tab stop. */
+    readOnly: () => boolean;
+    /** Whether toggling is refused because the control is out of use entirely. */
+    disabled: () => boolean;
+    /** Called with the state in force after a toggle or a form reset. */
+    onChange: (next: CheckedState) => void;
+    /** The element a form reset is observed through — the hidden input, or the control itself. */
+    resetTarget: () => HTMLElement | null;
+}
+/** @internal The checked state, its rendered spellings, and the toggle every checkable control shares. */
+export interface Checkable {
+    /** The state in force: the controlled one when there is one, the control's own otherwise. */
+    checked: ComputedRef<CheckedState>;
+    /** `data-state`: `checked`, `unchecked` or `indeterminate`. */
+    state: ComputedRef<'checked' | 'unchecked' | 'indeterminate'>;
+    /** `aria-checked`, where an indeterminate box announces as `mixed`. */
+    ariaChecked: ComputedRef<'true' | 'false' | 'mixed'>;
+    /** What the hidden form input carries, where indeterminate submits as unchecked. */
+    hiddenChecked: ComputedRef<boolean>;
+    /** Flips the state unless the control is disabled or read-only; indeterminate resolves to checked. */
+    toggle: () => void;
+}
+/**
+ * Shared checked-state engine for `role="checkbox"` and `role="switch"`: the
+ * controlled/uncontrolled split, the toggle, and the form-reset commit that
+ * keeps the button from drifting from the hidden input the browser restores.
+ * @internal
+ */
+export declare function useCheckable(options: UseCheckableOptions): Checkable;

package/dist/utils/useCheckable.js

@@ -0,0 +1 @@
+import{useFormReset as e}from"./useFormReset.js";import{computed as a,ref as t}from"vue";function d(d){const u=t(d.defaultChecked()),c=a(()=>d.checked()??u.value);function n(e){void 0!==d.checked()||(u.value=e),d.onChange(e)}return e(d.resetTarget,()=>n(d.defaultChecked())),{checked:c,state:a(()=>"indeterminate"===c.value?"indeterminate":c.value?"checked":"unchecked"),ariaChecked:a(()=>"indeterminate"===c.value?"mixed":c.value?"true":"false"),hiddenChecked:a(()=>!0===c.value),toggle(){d.disabled()||d.readOnly()||n("indeterminate"===c.value||!c.value)}}}export{d as useCheckable};

package/dist/utils/useControllable.cjs

@@ -0,0 +1 @@
+const l=require("./controllable.cjs");let i=require("vue");function b({controlled:s,defaultValue:n,onChange:a}){const r=(0,i.ref)(n?.()),o=()=>({controlled:s(),uncontrolled:r.value}),d=(0,i.computed)(()=>l.controllableValue(o()));function u(t){const c=o(),v=l.controllableValue(c),e=l.decideControllable(c,t);return e.write&&(r.value=e.value),e.emit&&a?.(e.value,v),e.emit}return{value:d,set:t=>u(t),reset:()=>u(l.decideReset(o(),n?.()).value)}}exports.useControllable=b;

package/dist/utils/useControllable.d.cts

@@ -0,0 +1,28 @@
+import { type ComputedRef } from 'vue';
+/** @internal What a controllable value needs from its component: the two props, and where a real change goes. */
+export interface UseControllableOptions<T> {
+    /** Reads the controlled prop; `undefined` means the control owns its own value. */
+    controlled: () => T | undefined;
+    /** Reads the `defaultValue` prop, live, so a reset restores the current one rather than the one captured at mount. */
+    defaultValue?: () => T | undefined;
+    /** Runs once per actual change, after the value in force has moved; a no-op write never reaches it. */
+    onChange?: (value: T, previous: T | undefined) => void;
+}
+/** @internal A controlled/uncontrolled value and the two ways it moves. */
+export interface Controllable<T> {
+    /** The value in force: the controlled prop when there is one, the control's own otherwise. */
+    value: ComputedRef<T | undefined>;
+    /** Proposes a value; returns whether it was an actual change, so the caller can pair extra work with the event. */
+    set: (next: T) => boolean;
+    /** Restores the `defaultValue` prop as it reads now; returns whether that changed anything. */
+    reset: () => boolean;
+}
+/**
+ * One controlled/uncontrolled value: the controlled prop always wins, a
+ * controlled control never writes its own state, and the change callback runs
+ * exactly once per actual change.
+ *
+ * @param options the two props and the change callback
+ * @internal
+ */
+export declare function useControllable<T>({ controlled, defaultValue, onChange, }: UseControllableOptions<T>): Controllable<T>;

package/dist/utils/useControllable.d.ts

@@ -0,0 +1,28 @@
+import { type ComputedRef } from 'vue';
+/** @internal What a controllable value needs from its component: the two props, and where a real change goes. */
+export interface UseControllableOptions<T> {
+    /** Reads the controlled prop; `undefined` means the control owns its own value. */
+    controlled: () => T | undefined;
+    /** Reads the `defaultValue` prop, live, so a reset restores the current one rather than the one captured at mount. */
+    defaultValue?: () => T | undefined;
+    /** Runs once per actual change, after the value in force has moved; a no-op write never reaches it. */
+    onChange?: (value: T, previous: T | undefined) => void;
+}
+/** @internal A controlled/uncontrolled value and the two ways it moves. */
+export interface Controllable<T> {
+    /** The value in force: the controlled prop when there is one, the control's own otherwise. */
+    value: ComputedRef<T | undefined>;
+    /** Proposes a value; returns whether it was an actual change, so the caller can pair extra work with the event. */
+    set: (next: T) => boolean;
+    /** Restores the `defaultValue` prop as it reads now; returns whether that changed anything. */
+    reset: () => boolean;
+}
+/**
+ * One controlled/uncontrolled value: the controlled prop always wins, a
+ * controlled control never writes its own state, and the change callback runs
+ * exactly once per actual change.
+ *
+ * @param options the two props and the change callback
+ * @internal
+ */
+export declare function useControllable<T>({ controlled, defaultValue, onChange, }: UseControllableOptions<T>): Controllable<T>;

package/dist/utils/useControllable.js

@@ -0,0 +1 @@
+import{controllableValue as e,decideControllable as l,decideReset as o}from"./controllable.js";import{computed as t,ref as a}from"vue";function r({controlled:r,defaultValue:n,onChange:u}){const s=a(n?.()),c=()=>({controlled:r(),uncontrolled:s.value});function d(o){const t=c(),a=e(t),r=l(t,o);return r.write&&(s.value=r.value),r.emit&&u?.(r.value,a),r.emit}return{value:t(()=>e(c())),set:e=>d(e),reset:()=>d(o(c(),n?.()).value)}}export{r as useControllable};

package/dist/utils/useDismiss.cjs

@@ -1 +1 @@
-let f=require("vue");function E({enabled:e,onEscapeKeyDown:o,onPointerDownOutside:l,onFocusOutside:y,onInteractOutside:r},b){if(typeof document>"u")return;let i;const u=t=>!b.some(n=>n.value?.contains(t)),c=t=>{t.key==="Escape"&&o?.(t)},s=t=>{const n=t.target;n&&u(n)&&(r?.(t),l?.(t))},d=t=>{const n=t.target;if(!n||n===document.body||!u(n))return;const m=new CustomEvent("focus-outside",{detail:t,cancelable:!0});r?.(m),y?.(m)};function w(){document.addEventListener("keydown",c),i=setTimeout(()=>{document.addEventListener("pointerdown",s,!0),document.addEventListener("focusin",d,!0)},0)}function a(){document.removeEventListener("keydown",c),clearTimeout(i),document.removeEventListener("pointerdown",s,!0),document.removeEventListener("focusin",d,!0)}(0,f.watch)(e,t=>{a(),t&&w()},{immediate:!0}),(0,f.onBeforeUnmount)(a)}function p(e,o){return!o||e.target!==o?null:e instanceof PointerEvent?e:new PointerEvent("pointerdown",{bubbles:!0,cancelable:!0,composed:!0,pointerType:"mouse",clientX:e.clientX,clientY:e.clientY,screenX:e.screenX,screenY:e.screenY,button:e.button,buttons:e.buttons,ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey})}exports.backdropPointerDown=p;exports.useDismiss=E;
+const n=require("./dismissal.cjs");let l=require("vue");function L({enabled:w,onEscapeKeyDown:E,onPointerDownOutside:p,onFocusOutside:y,onInteractOutside:r},i){if(typeof document>"u")return;let s,o;const u={insideElements:()=>i.map(e=>e.value)},c=e=>!i.some(t=>t.value?.contains(e)),d=e=>{n.handleEscapeKeyDown(e,u,E)},a=e=>{const t=e.target;t&&c(t)&&(r?.(e),p?.(e))},m=e=>{const t=n.focusOutsideTarget(e);if(!t||!c(t))return;const v=n.focusOutsideEvent(e);r?.(v),y?.(v)};function D(){o=n.pushDismissLayer(u),document.addEventListener("keydown",d),s=setTimeout(()=>{document.addEventListener("pointerdown",a,!0),document.addEventListener("focusin",m,!0)},0)}function f(){o?.(),o=void 0,document.removeEventListener("keydown",d),clearTimeout(s),document.removeEventListener("pointerdown",a,!0),document.removeEventListener("focusin",m,!0)}(0,l.watch)(w,e=>{f(),e&&D()},{immediate:!0}),(0,l.onBeforeUnmount)(f)}exports.backdropPointerDown=n.backdropPointerDown;exports.useDismiss=L;

package/dist/utils/useDismiss.d.cts

@@ -1,11 +1,6 @@
 import { type Ref } from 'vue';
-/**
- * FocusOutside event; wraps the original FocusEvent as detail since focusin
- * itself is not cancelable.
- */
-export type FocusOutsideEvent = CustomEvent<FocusEvent>;
-/** Outside interaction type: either pointer or focus. */
-export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+import { type FocusOutsideEvent, type InteractOutsideEvent } from './dismissal.cjs';
+export { backdropPointerDown, type FocusOutsideEvent, type InteractOutsideEvent, } from './dismissal.cjs';
 /** @internal Options for useDismiss: whether it is active and the Escape / outside-interaction callbacks. */
 export interface UseDismissOptions {
     /** Whether dismiss listeners are active (usually the open state). */
@@ -16,45 +11,8 @@ export interface UseDismissOptions {
     onPointerDownOutside?: (event: PointerEvent) => void;
     /** Called when focus moves to an element outside every element in `insideRefs`. */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
-    /**
-     * Called for either interaction type before the specific handler, same event
-     * object — preventDefault() here vetos dismissal either way.
-     */
+    /** Called for either interaction type before the specific handler, on the same event object; `preventDefault()` here vetoes dismissal either way. */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }
-/**
- * Dismissal behavior for Dialog-like content. Reports Escape/outside interaction;
- * caller decides dismissal strategy via defaultPrevented. @internal
- */
+/** Dismissal behavior for Dialog-like content; reports Escape/outside interaction, and the caller decides strategy via `defaultPrevented`. @internal */
 export declare function useDismiss({ enabled, onEscapeKeyDown, onPointerDownOutside, onFocusOutside, onInteractOutside, }: UseDismissOptions, insideRefs: Array<Ref<Element | null>>): void;
-/**
- * @internal The native `<dialog>` backdrop, normalised onto the same channel —
- * and the same payload type — that {@link useDismiss} reports every other
- * outside pointer-down on.
- *
- * **Why the backdrop needs its own path.** A modal `<dialog>`'s backdrop is not
- * an element: a pointer landing on it targets the `<dialog>` itself. An element
- * contains itself, so `isOutside` above reads that pointer-down as *inside* and
- * the document-level listener can never report it. Every port that renders a
- * native `<dialog>` therefore handles the backdrop separately.
- *
- * **Why it is a `pointerdown`.** Those ports used to handle it from `click` —
- * one phase later than React's capture-phase `pointerdown`, and carrying a
- * `MouseEvent` where React carries a `PointerEvent`, so a consumer reading
- * `event.pointerType` got `undefined` in four frameworks out of five and a
- * consumer vetoing dismissal had a whole press-and-hold to do it in on one
- * framework and no time at all on another.
- *
- * Returns the `PointerEvent` to report, or `null` when the pointer-down landed
- * inside the panel rather than on the backdrop. A real `PointerEvent` — which
- * is what every browser and every test DOM in this repo dispatches for
- * `pointerdown` — is forwarded untouched, so the payload is the same object
- * React hands its own consumers rather than a copy of it. Anything else (a
- * hand-built `MouseEvent`, an old polyfill) is copied into a
- * `PointerEvent`-shaped stand-in instead of being passed through, because one
- * payload type across five frameworks is the whole point of the exercise.
- *
- * @param event - the `pointerdown` listened for on the `<dialog>` element itself.
- * @param dialog - that `<dialog>`; the backdrop is a pointer-down whose target *is* it.
- */
-export declare function backdropPointerDown(event: MouseEvent, dialog: Element | null): PointerEvent | null;

package/dist/utils/useDismiss.d.ts

@@ -1,11 +1,6 @@
 import { type Ref } from 'vue';
-/**
- * FocusOutside event; wraps the original FocusEvent as detail since focusin
- * itself is not cancelable.
- */
-export type FocusOutsideEvent = CustomEvent<FocusEvent>;
-/** Outside interaction type: either pointer or focus. */
-export type InteractOutsideEvent = PointerEvent | FocusOutsideEvent;
+import { type FocusOutsideEvent, type InteractOutsideEvent } from './dismissal.js';
+export { backdropPointerDown, type FocusOutsideEvent, type InteractOutsideEvent, } from './dismissal.js';
 /** @internal Options for useDismiss: whether it is active and the Escape / outside-interaction callbacks. */
 export interface UseDismissOptions {
     /** Whether dismiss listeners are active (usually the open state). */
@@ -16,45 +11,8 @@ export interface UseDismissOptions {
     onPointerDownOutside?: (event: PointerEvent) => void;
     /** Called when focus moves to an element outside every element in `insideRefs`. */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
-    /**
-     * Called for either interaction type before the specific handler, same event
-     * object — preventDefault() here vetos dismissal either way.
-     */
+    /** Called for either interaction type before the specific handler, on the same event object; `preventDefault()` here vetoes dismissal either way. */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }
-/**
- * Dismissal behavior for Dialog-like content. Reports Escape/outside interaction;
- * caller decides dismissal strategy via defaultPrevented. @internal
- */
+/** Dismissal behavior for Dialog-like content; reports Escape/outside interaction, and the caller decides strategy via `defaultPrevented`. @internal */
 export declare function useDismiss({ enabled, onEscapeKeyDown, onPointerDownOutside, onFocusOutside, onInteractOutside, }: UseDismissOptions, insideRefs: Array<Ref<Element | null>>): void;
-/**
- * @internal The native `<dialog>` backdrop, normalised onto the same channel —
- * and the same payload type — that {@link useDismiss} reports every other
- * outside pointer-down on.
- *
- * **Why the backdrop needs its own path.** A modal `<dialog>`'s backdrop is not
- * an element: a pointer landing on it targets the `<dialog>` itself. An element
- * contains itself, so `isOutside` above reads that pointer-down as *inside* and
- * the document-level listener can never report it. Every port that renders a
- * native `<dialog>` therefore handles the backdrop separately.
- *
- * **Why it is a `pointerdown`.** Those ports used to handle it from `click` —
- * one phase later than React's capture-phase `pointerdown`, and carrying a
- * `MouseEvent` where React carries a `PointerEvent`, so a consumer reading
- * `event.pointerType` got `undefined` in four frameworks out of five and a
- * consumer vetoing dismissal had a whole press-and-hold to do it in on one
- * framework and no time at all on another.
- *
- * Returns the `PointerEvent` to report, or `null` when the pointer-down landed
- * inside the panel rather than on the backdrop. A real `PointerEvent` — which
- * is what every browser and every test DOM in this repo dispatches for
- * `pointerdown` — is forwarded untouched, so the payload is the same object
- * React hands its own consumers rather than a copy of it. Anything else (a
- * hand-built `MouseEvent`, an old polyfill) is copied into a
- * `PointerEvent`-shaped stand-in instead of being passed through, because one
- * payload type across five frameworks is the whole point of the exercise.
- *
- * @param event - the `pointerdown` listened for on the `<dialog>` element itself.
- * @param dialog - that `<dialog>`; the backdrop is a pointer-down whose target *is* it.
- */
-export declare function backdropPointerDown(event: MouseEvent, dialog: Element | null): PointerEvent | null;

package/dist/utils/useDismiss.js

@@ -1 +1 @@
-import{onBeforeUnmount as e,watch as t}from"vue";function n({enabled:n,onEscapeKeyDown:o,onPointerDownOutside:s,onFocusOutside:c,onInteractOutside:i},r){if(typeof document>"u")return;let u;const a=e=>!r.some(t=>t.value?.contains(e)),d=e=>{"Escape"===e.key&&o?.(e)},m=e=>{const t=e.target;t&&a(t)&&(i?.(e),s?.(e))},l=e=>{const t=e.target;if(!t||t===document.body||!a(t))return;const n=new CustomEvent("focus-outside",{detail:e,cancelable:!0});i?.(n),c?.(n)};function y(){document.removeEventListener("keydown",d),clearTimeout(u),document.removeEventListener("pointerdown",m,!0),document.removeEventListener("focusin",l,!0)}t(n,e=>{y(),e&&(document.addEventListener("keydown",d),u=setTimeout(()=>{document.addEventListener("pointerdown",m,!0),document.addEventListener("focusin",l,!0)},0))},{immediate:!0}),e(y)}function o(e,t){return t&&e.target===t?e instanceof PointerEvent?e:new PointerEvent("pointerdown",{bubbles:!0,cancelable:!0,composed:!0,pointerType:"mouse",clientX:e.clientX,clientY:e.clientY,screenX:e.screenX,screenY:e.screenY,button:e.button,buttons:e.buttons,ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey}):null}export{o as backdropPointerDown,n as useDismiss};
+import{backdropPointerDown as e,focusOutsideEvent as n,focusOutsideTarget as t,handleEscapeKeyDown as o,pushDismissLayer as s}from"./dismissal.js";import{onBeforeUnmount as i,watch as r}from"vue";function a({enabled:e,onEscapeKeyDown:a,onPointerDownOutside:d,onFocusOutside:u,onInteractOutside:c},m){if(typeof document>"u")return;let v,f;const p={insideElements:()=>m.map(e=>e.value)},w=e=>!m.some(n=>n.value?.contains(e)),E=e=>{o(e,p,a)},l=e=>{const n=e.target;n&&w(n)&&(c?.(e),d?.(e))},D=e=>{const o=t(e);if(!o||!w(o))return;const s=n(e);c?.(s),u?.(s)};function L(){f?.(),f=void 0,document.removeEventListener("keydown",E),clearTimeout(v),document.removeEventListener("pointerdown",l,!0),document.removeEventListener("focusin",D,!0)}r(e,e=>{L(),e&&(f=s(p),document.addEventListener("keydown",E),v=setTimeout(()=>{document.addEventListener("pointerdown",l,!0),document.addEventListener("focusin",D,!0)},0))},{immediate:!0}),i(L)}export{e as backdropPointerDown,a as useDismiss};

package/dist/utils/useFocusFirstItemOnOpen.cjs

@@ -1 +1 @@
-let i=require("vue");function c(t,u,o,r,a){let e;(0,i.watch)([u,a??(()=>0)],([m])=>{e!==void 0&&cancelAnimationFrame(e),!(!m||typeof document>"u")&&(e=requestAnimationFrame(()=>{const n=t.value?.querySelectorAll(o)??[];((r?.()==="last"?n[n.length-1]:n[0])??t.value)?.focus()}))},{immediate:!0}),(0,i.onBeforeUnmount)(()=>{e!==void 0&&cancelAnimationFrame(e)})}exports.useFocusFirstItemOnOpen=c;
+const l=require("./dismissal.cjs");let i=require("vue");function f(r,o,u,c,s){let e;(0,i.watch)([o,s??(()=>0)],([a])=>{e!==void 0&&cancelAnimationFrame(e),!(!a||typeof document>"u")&&(e=requestAnimationFrame(()=>{const n=r.value;if(!n||n.contains(document.activeElement))return;const t=n.querySelectorAll(u),m=c?.()==="last"?t[t.length-1]:t[0];l.focusOnOpen(()=>(m??n).focus({preventScroll:!0}))}))},{immediate:!0}),(0,i.onBeforeUnmount)(()=>{e!==void 0&&cancelAnimationFrame(e)})}exports.useFocusFirstItemOnOpen=f;

package/dist/utils/useFocusFirstItemOnOpen.d.cts

@@ -4,13 +4,5 @@ import { type Ref } from 'vue';
  * @internal
  */
 export type FocusOnOpenEnd = 'first' | 'last';
-/**
- * Moves focus into a panel one frame after it opens (first item, or container
- * if none). `end` overrides which item — DropdownMenu uses it for ArrowUp to
- * open on the last item per WAI-ARIA menu-button. `requestId` is an optional
- * extra trigger, for callers (Menubar) whose "open" boolean can stay
- * unchanged on a fresh open request — an already-open menu re-clicked no-ops
- * the underlying ref write, so `open` alone never re-fires this watcher.
- * Shared by DropdownMenuContent, MenubarContent, SpeedDialContent. @internal
- */
+/** Moves focus into a panel one frame after it opens (first item, or container if none); `end` picks last, `requestId` forces a re-fire. @internal */
 export declare function useFocusFirstItemOnOpen(contentRef: Ref<HTMLElement | null>, open: Readonly<Ref<boolean>>, selector: string, end?: () => FocusOnOpenEnd, requestId?: Readonly<Ref<number>>): void;

package/dist/utils/useFocusFirstItemOnOpen.d.ts

@@ -4,13 +4,5 @@ import { type Ref } from 'vue';
  * @internal
  */
 export type FocusOnOpenEnd = 'first' | 'last';
-/**
- * Moves focus into a panel one frame after it opens (first item, or container
- * if none). `end` overrides which item — DropdownMenu uses it for ArrowUp to
- * open on the last item per WAI-ARIA menu-button. `requestId` is an optional
- * extra trigger, for callers (Menubar) whose "open" boolean can stay
- * unchanged on a fresh open request — an already-open menu re-clicked no-ops
- * the underlying ref write, so `open` alone never re-fires this watcher.
- * Shared by DropdownMenuContent, MenubarContent, SpeedDialContent. @internal
- */
+/** Moves focus into a panel one frame after it opens (first item, or container if none); `end` picks last, `requestId` forces a re-fire. @internal */
 export declare function useFocusFirstItemOnOpen(contentRef: Ref<HTMLElement | null>, open: Readonly<Ref<boolean>>, selector: string, end?: () => FocusOnOpenEnd, requestId?: Readonly<Ref<number>>): void;

package/dist/utils/useFocusFirstItemOnOpen.js

@@ -1 +1 @@
-import{onBeforeUnmount as e,watch as t}from"vue";function n(n,o,a,i,m){let u;t([o,m??(()=>0)],([e])=>{void 0!==u&&cancelAnimationFrame(u),e&&!(typeof document>"u")&&(u=requestAnimationFrame(()=>{const e=n.value?.querySelectorAll(a)??[];(("last"===i?.()?e[e.length-1]:e[0])??n.value)?.focus()}))},{immediate:!0}),e(()=>{void 0!==u&&cancelAnimationFrame(u)})}export{n as useFocusFirstItemOnOpen};
+import{focusOnOpen as e}from"./dismissal.js";import{onBeforeUnmount as n,watch as t}from"vue";function o(o,a,i,m,s){let c;t([a,s??(()=>0)],([n])=>{void 0!==c&&cancelAnimationFrame(c),n&&!(typeof document>"u")&&(c=requestAnimationFrame(()=>{const n=o.value;if(!n||n.contains(document.activeElement))return;const t=n.querySelectorAll(i),a="last"===m?.()?t[t.length-1]:t[0];e(()=>(a??n).focus({preventScroll:!0}))}))},{immediate:!0}),n(()=>{void 0!==c&&cancelAnimationFrame(c)})}export{o as useFocusFirstItemOnOpen};