@mkbabb/glass-ui 3.3.0 → 3.5.0

package/dist/composables/dark/useGlobalDark.d.ts

@@ -1,4 +1,20 @@
 import type { BasicColorSchema } from "@vueuse/core";
+import { type Ref, type WritableComputedRef } from "vue";
+/**
+ * The `useGlobalDark` return shape (AW.W15 — named `Use<Name>Return`). The
+ * single shared dark-mode instance: the reactive `isDark` flag, a `toggleDark`
+ * that optionally suppresses transitions, and the transition-suppression switch.
+ */
+export interface UseGlobalDarkReturn {
+    /** Reactive dark-mode flag (vueuse `useDark` ref — writable). */
+    isDark: WritableComputedRef<boolean>;
+    /** Toggle dark mode (suppresses transitions when configured). */
+    toggleDark: () => void;
+    /** Whether transitions are suppressed during a toggle. */
+    disableTransitions: Ref<boolean>;
+    /** Configure transition suppression during the dark-mode toggle. */
+    setDisableTransitions: (value: boolean) => void;
+}
 export interface UseGlobalDarkOptions {
     /**
      * The first-paint color scheme seed, threaded to `useDark({ initialValue })`.
@@ -16,9 +32,4 @@ export interface UseGlobalDarkOptions {
  * `initialValue` seed (one-shot — see `UseGlobalDarkOptions`); subsequent calls
  * receive the already-constructed singleton and their `initialValue` is ignored.
  */
-export declare function useGlobalDark(options?: UseGlobalDarkOptions): {
-    isDark: import("@vueuse/core").UseDarkReturn;
-    toggleDark: () => void;
-    disableTransitions: import("vue").Ref<boolean, boolean>;
-    setDisableTransitions: (value: boolean) => void;
-};
+export declare function useGlobalDark(options?: UseGlobalDarkOptions): UseGlobalDarkReturn;

package/dist/composables/dom/index.d.ts

@@ -4,3 +4,6 @@ export * from "./useTokenColor";
 export * from "./useClipboard";
 export * from "./useUserInvalidAria";
 export * from "./useTextHighlight";
+export * from "./useBreakpoint";
+export * from "./useIdleReady";
+export * from "./useViewportReady";

package/dist/composables/dom/useBreakpoint.d.ts

@@ -0,0 +1,38 @@
+import { type Ref } from "vue";
+export interface UseBreakpointControls {
+    /** Live `matches` state for the given media query. */
+    readonly matches: Readonly<Ref<boolean>>;
+    /** Tear down the `matchMedia` listener. Auto-called on scope dispose. */
+    stop: () => void;
+}
+/**
+ * `useBreakpoint(query)` — a reactive read of a CSS media query's `matches`
+ * state, kept live across resize / orientation / display-mode changes.
+ *
+ * Wraps `window.matchMedia(query)`, subscribes a single `change` handler,
+ * and mirrors `mql.matches` into a `Ref<boolean>`. Auto-cleans on Vue scope
+ * disposal (mirrors `useResizeObserver` / `useInterval` upstream); outside
+ * a scope callers use the returned `stop()` control.
+ *
+ * SSR-safe: when `window` is undefined the composable returns a
+ * permanently-`false` ref. Consumers should treat the initial frame as
+ * "mobile-first / narrow-default" because the matchMedia subscription only
+ * mounts client-side. This is the same shape consumers wrote by hand at the
+ * speedtest origin sites.
+ *
+ * Why this exists (speedtest origin, glass-ui promotion W6-β): the survey
+ * cockpit (`SurveyWizard.vue`) and the admin data-source toggle
+ * (`AdminDataSourceToggle.vue`) both hand-rolled the same `matchMedia`
+ * subscribe-on-mount + tear-down-on-unmount pattern. Two hand-rolls of one
+ * pattern is the `feedback_generic_components` 2-consumer trigger;
+ * absorbed publisher-side per `feedback_library_gaps`.
+ *
+ * Usage:
+ *   const { matches: isDesktop } = useBreakpoint("(min-width: 720px)");
+ *   const wide = isDesktop.value;  // live across resize.
+ *
+ * @param query A CSS `@media` query string, e.g. `"(min-width: 720px)"`.
+ * @returns Object with `matches: Ref<boolean>` and `stop()` for manual
+ *          disposal outside a Vue scope.
+ */
+export declare function useBreakpoint(query: string): UseBreakpointControls;

package/dist/composables/dom/useIdleReady.d.ts

@@ -0,0 +1,63 @@
+import { type Ref } from "vue";
+export interface UseIdleReadyOptions {
+    /**
+     * `requestIdleCallback` timeout, in ms. Default 2_000 — the canonical
+     * value at every speedtest hand-rolled site (App.vue + useIPInfo both
+     * pass `{ timeout: 2000 }`). Unlike useViewportReady's 10s (which fronts
+     * the budget with an IO gate), useIdleReady has no visibility stage, so
+     * the timeout is the only ceiling — 2s matches the consumer sites and
+     * keeps the deferred work inside a reasonable post-paint window.
+     */
+    timeout?: number;
+    /**
+     * Optional task run the moment the gate flips (the scope-aware variant —
+     * useIPInfo's `() => void refresh()`). Runs exactly once; auto-cancelled
+     * on scope dispose with the rIC handle so a short-lived consumer cannot
+     * leak a deferred write to disposed refs. Consumers that only need the
+     * `ready` ref omit it.
+     */
+    onReady?: () => void;
+}
+export interface UseIdleReadyControls {
+    /** Flips `false → true` exactly once on the first idle tick (post-mount). */
+    readonly ready: Ref<boolean>;
+    /** Tear down the pending idle/timer handle. Auto-called on scope dispose. */
+    stop: () => void;
+}
+/**
+ * `useIdleReady(options?)` — `requestIdleCallback` (+ `setTimeout(0)` Safari
+ * fallback) post-mount idle gate that flips a `Ref<boolean>` exactly once on
+ * the first idle tick, and optionally runs an `onReady` task at that moment.
+ *
+ * The rIC-only sibling of `useViewportReady` — same one-shot `ready` ref +
+ * `stop()` shape, same auto-dispose discipline — minus the
+ * `IntersectionObserver` visibility stage. The gate is "idle, full stop", not
+ * "visible AND idle"; reach for it when there is no element to gate on (a
+ * top-level lazy mount, a composable's first-idle data fetch).
+ *
+ * Two unified use shapes:
+ *
+ *   1. `ready`-flag — `v-if`-gate a heavy mount on the returned ref:
+ *        const { ready } = useIdleReady();
+ *        // <Aurora v-if="ready" />
+ *   2. scope-aware task — run a callback on first idle, cancelled on dispose:
+ *        useIdleReady({ onReady: () => void refresh() });
+ *      The handle is auto-cancelled on Vue scope disposal so a short-lived
+ *      consumer cannot leak a deferred write to disposed refs.
+ *
+ * The composable schedules synchronously at call time (NOT inside an
+ * `onMounted`) so it works outside a component too (e.g. inside `useIPInfo`,
+ * a composable not a component). SSR / non-browser flips synchronously so
+ * consumers don't stall.
+ *
+ * Why this exists (speedtest origin, glass-ui promotion AO.W3): the gate is
+ * hand-rolled at 5 speedtest sites (App.vue, MapView.vue, DashboardMap.vue,
+ * useAutoStart.ts, useIPInfo.ts) — the ≥2-consumer substrate-promotion gate
+ * (J inv 10 / L inv 8) fires for a publisher-side absorption.
+ *
+ * @param options.timeout Default `2000` ms — forwarded to `requestIdleCallback`.
+ * @param options.onReady Optional one-shot task run on the idle flip.
+ * @returns Object with `ready: Ref<boolean>` (flips false → true once) and
+ *          `stop()` for manual disposal outside a Vue scope.
+ */
+export declare function useIdleReady(options?: UseIdleReadyOptions): UseIdleReadyControls;

package/dist/composables/dom/useTokenColor.d.ts

@@ -1,9 +1,22 @@
 import { type MaybeRefOrGetter, type Ref } from "vue";
+/**
+ * The resolver seam (AW.W15) — given a property name + the resolved element,
+ * return the property's value. Defaults to the live
+ * `getComputedStyle(el).getPropertyValue(prop)` read; an injected resolver lets
+ * SSR / tests close the DI loop without touching `document.documentElement`.
+ */
+export type TokenColorResolver = (prop: string, el?: HTMLElement) => string;
 export interface UseTokenColorOptions {
     /** Element to resolve the property against. Defaults to `<html>`. */
     element?: MaybeRefOrGetter<HTMLElement | null | undefined>;
     /** Fallback when the property is unset or `document` is unavailable (SSR). */
     fallback?: string;
+    /**
+     * Injected property resolver (AW.W15 DI seam). Defaults to the live
+     * `getComputedStyle(el).getPropertyValue(prop)` read. Pass a custom resolver
+     * for SSR / tests / a themed-context override without reaching the DOM.
+     */
+    resolver?: TokenColorResolver;
 }
 export interface UseTokenColorControls {
     /** Reactive resolved value. Trimmed; falls back to `options.fallback` when empty. */

package/dist/composables/dom/useViewportReady.d.ts

@@ -0,0 +1,87 @@
+import { type Ref } from "vue";
+/**
+ * Structural Ref shape — accepts the consumer's `Ref<T>` regardless of which
+ * `@vue/reactivity` package the brand symbol comes from. Glass-ui may sit at
+ * a different vue minor than the consumer, and Vue 3.5's `[RefSymbol]`
+ * phantom is nominal-by-package; structural-by-`.value` is the correct
+ * contract for a consumer-facing API. Same shape `useResizeObserver` uses.
+ */
+type RefLike<T> = {
+    value: T;
+};
+export interface UseViewportReadyOptions {
+    /**
+     * IntersectionObserver `rootMargin`. Default `"200px"` so the gate flips
+     * before the host actually crosses the viewport edge — gives the
+     * consumer a quiet window for lazy-mount (`echarts`, `<canvas>` re-init,
+     * heavy widget hydration) to land off the LCP frame.
+     */
+    rootMargin?: string;
+    /**
+     * `requestIdleCallback` timeout, in ms. Default 10_000.
+     *
+     * Why 10s and not the conventional 1–2s: a cold-loading consumer (slow
+     * throughput, weak device) may not sustainably idle inside a 1–2s
+     * window — the timeout fires inside the LCP measurement window and
+     * defeats the IO gate's "wait for viewport AND idle main thread"
+     * semantic. The IO gate fronts the budget, so the timeout only fires
+     * after intersection has already resolved; ten seconds gives the main
+     * thread room to idle naturally.
+     */
+    idleTimeout?: number;
+    /**
+     * IntersectionObserver `threshold`. Default 0.01 (1 % visible). Mirrors
+     * the speedtest origin-site semantic — "any pixel visible counts".
+     */
+    threshold?: number;
+}
+export interface UseViewportReadyControls {
+    /** Flips `false → true` exactly once when the host is visible + idle. */
+    readonly ready: Ref<boolean>;
+    /** Tear down observer + idle handle. Auto-called on scope dispose. */
+    stop: () => void;
+}
+/**
+ * `useViewportReady(host)` — two-stage `IntersectionObserver` +
+ * `requestIdleCallback` gate that flips a `Ref<boolean>` exactly once when
+ * the host element has entered the viewport AND the main thread has idled.
+ *
+ * The intended use is lazy-mount of a heavy widget (echarts, leaflet,
+ * three.js, codemirror, custom canvas) that would otherwise pull its chunk
+ * into the first-paint critical path. The two-stage gate ensures:
+ *
+ *   1. Visibility-first — `IntersectionObserver` watches `host`. Until the
+ *      host crosses into the viewport (+ `rootMargin`), no fetch fires.
+ *   2. Idle-second — once visible, `requestIdleCallback` schedules the flip
+ *      so the chunk fetch waits for an idle main thread. Safari (no rIC)
+ *      falls back to `setTimeout(fire, 16)` — one frame later — so the
+ *      composition still defers past the IO callback's paint frame.
+ *
+ * The composable is one-shot: once the gate flips to `true` it disconnects
+ * its observer and clears any pending idle handle. Auto-cleans on Vue scope
+ * disposal (mirrors `useResizeObserver` / `useInterval` upstream); outside
+ * a scope callers receive the manual `stop()` control.
+ *
+ * Why this exists (speedtest origin, glass-ui promotion AJ.W6-α): both
+ * `AdminOverviewView` and `ChartsView` shipped a near-identical `chartReady`
+ * flag flipped by `requestIdleCallback` alone. The W3-R1 idiom in those
+ * sites — gate visibility first, then schedule rIC inside the IO callback —
+ * is generic across heavy-widget hydration; the speedtest 2-consumer trigger
+ * fired for a publisher-side absorption per `feedback_generic_components`.
+ *
+ * Usage:
+ *   const host = ref<HTMLElement | null>(null);
+ *   const { ready } = useViewportReady(host);
+ *   // <Chart v-if="ready" /> — fetched lazily once host is visible + idle.
+ *
+ * @param host A `Ref<Element | null>` for the element to gate visibility on.
+ *             The observer watches THIS element, not the lazy-mounted
+ *             widget (which doesn't exist pre-flip).
+ * @param options.rootMargin Default `"200px"`.
+ * @param options.idleTimeout Default `10000` ms.
+ * @param options.threshold   Default `0.01`.
+ * @returns Object with `ready: Ref<boolean>` (flips false → true once) and
+ *          `stop()` for manual disposal outside a Vue scope.
+ */
+export declare function useViewportReady(host: RefLike<Element | null>, options?: UseViewportReadyOptions): UseViewportReadyControls;
+export {};

package/dist/composables/glass/index.d.ts

@@ -1 +1 @@
-export { useGlassRenderer, createGlassFilter, destroyGlassFilter, type GlassTier, type GlassFilterState, } from "./useGlassRenderer";
+export { useGlassRenderer, createGlassFilter, destroyGlassFilter, type GlassTier, type GlassFilterState, type UseGlassRendererReturn, } from "./useGlassRenderer";

package/dist/composables/glass/useGlassRenderer.d.ts

@@ -1,4 +1,13 @@
+import { type Ref } from "vue";
 export type GlassTier = "svg-filter" | "css" | "fallback";
+/**
+ * The `useGlassRenderer` return shape (AW.W15 — named `Use<Name>Return`). The
+ * detected (or forced) glass rendering tier as a reactive ref.
+ */
+export interface UseGlassRendererReturn {
+    /** The active rendering tier — `preferredTier` if forced, else auto-detected on mount. */
+    tier: Ref<GlassTier>;
+}
 export interface GlassFilterState {
     filterId: string;
     svgEl: SVGSVGElement;
@@ -32,6 +41,4 @@ export declare function destroyGlassFilter(state: GlassFilterState): void;
  */
 export declare function useGlassRenderer(options?: {
     preferredTier?: GlassTier;
-}): {
-    tier: import("vue").Ref<GlassTier, GlassTier>;
-};
+}): UseGlassRendererReturn;

package/dist/composables/motion/useAnimatedNumber.d.ts

@@ -18,7 +18,11 @@ export interface UseAnimatedNumberOptions {
     /** Per-frame side-effect hook. Receives the smoothed current value. */
     onValue?: (value: number) => void;
 }
-export interface AnimatedNumber {
+/**
+ * The `useAnimatedNumber` return shape (AW.W15 — named `Use<Name>Return`
+ * convention). `AnimatedNumber` is the preserved alias so import sites stay put.
+ */
+export interface UseAnimatedNumberReturn {
     /** Reactive smoothed value. Bind in templates. */
     current: Readonly<Ref<number>>;
     /** True while the rAF loop is running and not settled. */
@@ -30,6 +34,8 @@ export interface AnimatedNumber {
     /** Stop the smoother and target watcher. */
     dispose: () => void;
 }
+/** Preserved alias for {@link UseAnimatedNumberReturn} (AW.W15). */
+export type AnimatedNumber = UseAnimatedNumberReturn;
 /**
  * Track a live numeric target with exponentially damped hysteresis.
  *
@@ -37,4 +43,4 @@ export interface AnimatedNumber {
  * composable wires Vue reactivity, reduced-motion handling, and lifecycle
  * cleanup.
  */
-export declare function useAnimatedNumber(target: MaybeRefOrGetter<number | null | undefined>, options?: UseAnimatedNumberOptions): AnimatedNumber;
+export declare function useAnimatedNumber(target: MaybeRefOrGetter<number | null | undefined>, options?: UseAnimatedNumberOptions): UseAnimatedNumberReturn;

package/dist/composables/motion/useCountup.d.ts

@@ -1,5 +1,9 @@
 import { type Ref } from "vue";
-export interface Countup {
+/**
+ * The `useCountup` return shape (AW.W15 — named `Use<Name>Return` convention).
+ * `Countup` is the preserved alias so existing import sites do not break.
+ */
+export interface UseCountupReturn {
     /** Animate the count-ups inside the currently-active slide/region. */
     runActive: () => void;
     /** Snap EVERY `[data-countup]` in the document to its end value (still capture). */
@@ -7,6 +11,8 @@ export interface Countup {
     /** Cancel every in-flight tween (also runs on scope-dispose). */
     cancel: () => void;
 }
+/** Preserved alias for {@link UseCountupReturn} — keeps import sites stable (AW.W15). */
+export type Countup = UseCountupReturn;
 export interface UseCountupOptions {
     /**
      * Easing applied to tween progress — a value.js-FREE callable
@@ -26,4 +32,4 @@ export interface UseCountupOptions {
  * // on slide-activate: runActive();
  * // on still-capture:  settle();
  */
-export declare function useCountup(hostRef: Ref<HTMLElement | null>, opts: UseCountupOptions): Countup;
+export declare function useCountup(hostRef: Ref<HTMLElement | null>, opts: UseCountupOptions): UseCountupReturn;

package/dist/composables/motion/useNumericTransition.d.ts

@@ -1,13 +1,40 @@
-import type { TimingFunction, TimingFunctionNames } from "@mkbabb/keyframes.js";
+import type { TimingFunction } from "@mkbabb/keyframes.js";
+import { type Ref } from "vue";
 export type SpringSnapshot<K extends string> = Record<K, number>;
+/**
+ * The `useNumericTransition` return shape (AW.W15 — named `Use<Name>Return`).
+ * The transition is driver-only: `start`/`stop` control playback, `progress`
+ * (0..1) + `playing` are reactive read-outs.
+ */
+export interface UseNumericTransitionReturn {
+    /** Play the transition from `from` → `to`; resolves at completion. */
+    start: () => Promise<void>;
+    /** Stop the in-flight transition. */
+    stop: () => void;
+    /** Reactive 0..1 progress derived from the first interpolated key. */
+    progress: Ref<number>;
+    /** Reactive true-while-playing flag. */
+    playing: Ref<boolean>;
+}
 export interface UseNumericTransitionOptions<K extends string> {
     /** Named numeric endpoints to interpolate between. */
     from: SpringSnapshot<K>;
     to: SpringSnapshot<K>;
     /** Playback duration in ms. */
     duration: number;
-    /** keyframes.js timing function — string name or explicit function. */
-    timingFunction?: TimingFunction | TimingFunctionNames;
+    /**
+     * keyframes.js timing function — an explicit callable `(t) => number`.
+     *
+     * AW.W27: this is a CALLABLE `TimingFunction`, NOT a string easing name.
+     * keyframes 4 removed string-name acceptance from `NumericAnimationOptions`
+     * (a name now resolves only through the ASYNC `resolveEasing`, which crosses
+     * the value.js dynamic boundary the dock/motion light surface must never
+     * pull in). Narrowing glass-ui's public option to a callable decouples it
+     * from keyframes' name-resolution churn AND is assignable to every supported
+     * keyframes major (2.2 / 3 / 4). A consumer wanting a named curve passes the
+     * function directly (e.g. `(t) => 1 - Math.pow(1 - t, 3)` for easeOutCubic).
+     */
+    timingFunction?: TimingFunction;
     /** Per-frame consumer. Receives the same zero-allocation record each tick. */
     onFrame?: (values: SpringSnapshot<K>) => void;
 }
@@ -24,9 +51,4 @@ export interface UseNumericTransitionOptions<K extends string> {
  *
  * For physics-based motion (mass / stiffness / damping), use `useSpring`.
  */
-export declare function useNumericTransition<K extends string>(options: UseNumericTransitionOptions<K>): {
-    start: () => Promise<void>;
-    stop: () => void;
-    progress: import("vue").Ref<number, number>;
-    playing: import("vue").Ref<boolean, boolean>;
-};
+export declare function useNumericTransition<K extends string>(options: UseNumericTransitionOptions<K>): UseNumericTransitionReturn;

package/dist/composables/motion/useViewTransition.d.ts

@@ -1,3 +1,11 @@
+/** Options for `startViewTransition`. `types` (Chrome 140+, absent on Firefox
+ *  144) tag the active transition so `:active-view-transition-type(<t>)` CSS can
+ *  author DIRECTION-specific curves. Feature-detected — when the engine lacks the
+ *  object-with-`types` overload the call degrades to the plain-callback form
+ *  (one symmetric curve), which is functionally identical (the swap still runs). */
+export interface ViewTransitionOptions {
+    types?: string[];
+}
 export interface ViewTransitionResult {
     /**
      * Resolves when the transition's `finished` promise settles (or
@@ -21,11 +29,18 @@ export declare function supportsViewTransitions(): boolean;
  * is identical regardless of support.
  *
  * @param mutate the synchronous DOM/state change to animate between.
+ * @param options optional `{ types }` — directional transition types tagged on
+ *   the active transition for `:active-view-transition-type(<t>)` CSS curves
+ *   (Chrome 140+; feature-detected, degrades to one symmetric curve elsewhere).
  * @returns `{ finished, transitioned }` — await `finished` to route focus.
  *
  * @example
  *   const { finished } = startViewTransition(() => { rows.value = reranked });
  *   await finished;            // animation done
  *   firstRow.value?.focus();   // consumer routes focus (the a11y MANDATORY)
+ *
+ * @example
+ *   // directional intent — snappier exit on collapse, softer entry on expand
+ *   startViewTransition(() => mutate(), { types: ["dock-expand"] });
  */
-export declare function startViewTransition(mutate: () => void): ViewTransitionResult;
+export declare function startViewTransition(mutate: () => void, options?: ViewTransitionOptions): ViewTransitionResult;

package/dist/confirm-dialog.js

@@ -1,5 +1,5 @@
 import { t as e } from "./createLucideIcon-DuDoe_ra.js";
-import { n as t } from "./button-Ckn3eDfB.js";
+import { n as t } from "./button-i8Ek5vvg.js";
 import { t as n } from "./_plugin-vue_export-helper-C1je1s0u.js";
 import { Transition as r, createBlock as i, createCommentVNode as a, createElementBlock as o, createElementVNode as s, createTextVNode as c, createVNode as l, defineComponent as u, mergeModels as d, openBlock as f, renderSlot as p, toDisplayString as m, unref as h, useModel as g, withCtx as _, withKeys as v, withModifiers as y } from "vue";
 var b = e("loader-circle", [["path", {

package/dist/data-table.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./DataTable-FfkaAg2z.js";
+import { n as e, t } from "./DataTable-DyKc_26a.js";
 export { t as DataTable, e as DataTablePagination };