@vizejs/composable 0.345.0 → 0.347.7

package/dist/index.d.mts

@@ -1,786 +1,19 @@
-import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
-
-//#region src/async-resource.d.ts
-/** Lifecycle state of an asynchronous resource. */
-type AsyncResourceStatus = "idle" | "pending" | "success" | "error" | "cancelled";
-/** Context supplied to an asynchronous resource loader. */
-interface AsyncResourceContext {
-  /** Signal aborted by cancellation, reset, scope disposal, or a newer execution. */
-  readonly signal: AbortSignal;
-}
-/** Explicit result of one asynchronous resource execution. */
-type AsyncResourceExecution<Data, Failure> = {
-  readonly status: "success";
-  readonly data: Data;
-} | {
-  readonly status: "error";
-  readonly error: Failure;
-} | {
-  readonly status: "cancelled";
-  readonly reason: unknown;
-} | {
-  readonly status: "superseded";
-};
-/** Options for {@link useAsyncResource}. */
-interface UseAsyncResourceOptions<Data> {
-  /**
-   * Initial data restored by {@link AsyncResource.reset}.
-   *
-   * @default undefined
-   */
-  readonly initialData?: Data;
-  /**
-   * Abort the active execution when a newer execution starts.
-   *
-   * @default true
-   */
-  readonly cancelPrevious?: boolean;
-  /**
-   * Retain the current data while a new execution is pending.
-   *
-   * @default true
-   */
-  readonly keepData?: boolean;
-  /**
-   * Cancel an active execution when the current reactive scope is disposed.
-   *
-   * @default true
-   */
-  readonly scope?: boolean;
-}
-/** Reactive state and controls for an asynchronous loader. */
-interface AsyncResource<Data, Arguments extends readonly unknown[], Failure> {
-  /** Data of the newest successful execution, retained according to `keepData`. */
-  readonly data: Readonly<ShallowRef<Data | undefined>>;
-  /** Failure of the newest settled execution, cleared when a new one starts. */
-  readonly error: Readonly<ShallowRef<Failure | undefined>>;
-  /** Current lifecycle status, driven only by the newest execution. */
-  readonly status: Readonly<Ref<AsyncResourceStatus>>;
-  /** Whether an execution is currently pending. */
-  readonly pending: ComputedRef<boolean>;
-  /**
-   * Run the loader. The returned promise never rejects: loader failures,
-   * cancellation, and supersession are reported as the discriminated result,
-   * and stale executions leave the reactive state untouched.
-   */
-  readonly execute: (...arguments_: Arguments) => Promise<AsyncResourceExecution<Data, Failure>>;
-  /**
-   * Abort the active execution and mark the resource cancelled.
-   *
-   * @param reason Abort reason forwarded to the loader's signal.
-   * @default reason DOMException("AbortError")
-   * @returns Whether an active execution was cancelled.
-   */
-  readonly cancel: (reason?: unknown) => boolean;
-  /** Cancel any active execution and restore the initial idle state. */
-  readonly reset: () => void;
-}
-/**
- * Create a scoped, abortable asynchronous resource with latest-result-wins
- * state. Every execution returns a discriminated result, so cancellation,
- * supersession, loader failure, and successful `undefined` data stay distinct.
- *
- * When created inside an active reactive scope (and `scope` is enabled), the
- * active execution is aborted when that scope stops; outside a scope,
- * cancellation ownership stays with the caller. The execute promise never
- * rejects — synchronous and asynchronous loader failures both settle into
- * the `"error"` result. Safe during server rendering: no browser globals are
- * read and abort reasons use the runtime-native `DOMException`.
- *
- * @param loader Asynchronous loader receiving the abort context first.
- * @param options Data retention, supersession, and scope behavior.
- * @default options {}
- * @returns Reactive state and controls for the loader.
- */
-declare function useAsyncResource<Data, Arguments extends readonly unknown[], Failure = unknown>(loader: (context: AsyncResourceContext, ...arguments_: Arguments) => Promise<Data>, options?: UseAsyncResourceOptions<Data>): AsyncResource<Data, Arguments, Failure>;
-//#endregion
-//#region src/event-listener.d.ts
-/** Options for {@link useEventListener}. */
-interface UseEventListenerOptions {
-  /**
-   * Invoke the listener during the capture phase.
-   *
-   * @default false
-   */
-  readonly capture?: boolean;
-  /**
-   * Stop listening after the first event.
-   *
-   * @default false
-   */
-  readonly once?: boolean;
-  /**
-   * Declare that the listener does not cancel the event's default action.
-   *
-   * @default false
-   */
-  readonly passive?: boolean;
-  /**
-   * Stop listening when this signal is aborted. An already-aborted signal
-   * prevents listening from ever starting.
-   *
-   * @default undefined
-   */
-  readonly signal?: AbortSignal;
-  /**
-   * Start listening during composable creation.
-   *
-   * @default true
-   */
-  readonly immediate?: boolean;
-  /**
-   * Reactive target update timing.
-   *
-   * @default "pre"
-   */
-  readonly flush?: "pre" | "post" | "sync";
-}
-/** Reactive controls returned by {@link useEventListener}. */
-interface EventListenerControls {
-  /** Whether a concrete target currently owns the listener. */
-  readonly isListening: Readonly<Ref<boolean>>;
-  /**
-   * Begin listening.
-   *
-   * @returns Whether a new reactive watcher was started. `false` while the
-   * watcher is already active (including a null-target watcher with no
-   * listener attached), after the abort signal has fired, and after the
-   * owning reactive scope has been disposed.
-   */
-  readonly start: () => boolean;
-  /** Stop listening. Repeated calls are safe. */
-  readonly stop: () => void;
-}
-/**
- * Attach an event listener to a reactive target and clean it up with the
- * current reactive scope. Missing targets are valid during server rendering:
- * a `null`/`undefined` target keeps the listener detached until a concrete
- * target appears, so no browser globals are required.
- *
- * The listener is re-attached whenever the reactive target changes and is
- * removed when the owning reactive scope stops, when
- * {@link EventListenerControls.stop} is called, or when the abort signal
- * fires. Outside an active scope, teardown ownership stays with the caller,
- * who must call `stop` explicitly. Errors thrown by a custom target's
- * add/remove methods propagate to the active watcher run.
- *
- * @param target Reactive event target.
- * @param event Event name.
- * @param listener Typed event listener.
- * @param options Listener lifecycle and scheduling options.
- * @default options {}
- * @returns Controls to observe and change the listening state.
- */
-declare function useEventListener<Key extends keyof WindowEventMap>(target: MaybeRefOrGetter<Window | null | undefined>, event: Key, listener: (event: WindowEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
-declare function useEventListener<Key extends keyof DocumentEventMap>(target: MaybeRefOrGetter<Document | null | undefined>, event: Key, listener: (event: DocumentEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
-declare function useEventListener<Key extends keyof HTMLElementEventMap>(target: MaybeRefOrGetter<HTMLElement | null | undefined>, event: Key, listener: (event: HTMLElementEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
-declare function useEventListener(target: MaybeRefOrGetter<EventTarget | null | undefined>, event: string, listener: EventListener, options?: UseEventListenerOptions): EventListenerControls;
-//#endregion
-//#region src/locale.d.ts
-/** Text flow reported by the internationalization runtime. */
-type TextDirection = "ltr" | "rtl";
-/** Locale selection options for {@link useLocale}. */
-interface UseLocaleOptions {
-  /**
-   * Locale detector used when the reactive source has no value.
-   *
-   * @default navigator.language when available; otherwise undefined
-   */
-  readonly detect?: () => Intl.Locale | string | null | undefined;
-  /**
-   * Locale used when neither the source nor detector provides one.
-   *
-   * @default "en"
-   */
-  readonly fallback?: Intl.Locale | string;
-}
-/**
- * Reactive locale metadata and cached formatter factories.
- *
- * Formatter factories propagate `TypeError` and `RangeError` from the
- * platform `Intl` constructors when the supplied options are invalid.
- */
-interface LocaleControls {
-  /** Canonical Unicode locale identifier. */
-  readonly locale: ComputedRef<string>;
-  /** Parsed locale details supplied by the internationalization runtime. */
-  readonly details: ComputedRef<Intl.Locale>;
-  /** Native writing direction for the active locale. */
-  readonly direction: ComputedRef<TextDirection>;
-  /** Return a cached number formatter for the active locale and options. */
-  readonly number: (options?: Intl.NumberFormatOptions) => Intl.NumberFormat;
-  /** Return a cached date and time formatter for the active locale and options. */
-  readonly dateTime: (options?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormat;
-  /** Return a cached list formatter for the active locale and options. */
-  readonly list: (options?: Intl.ListFormatOptions) => Intl.ListFormat;
-  /** Return a cached relative-time formatter for the active locale and options. */
-  readonly relativeTime: (options?: Intl.RelativeTimeFormatOptions) => Intl.RelativeTimeFormat;
-}
-/**
- * Create reactive locale metadata and platform-native formatter factories.
- *
- * Equivalent formatter options reuse instances. The bounded cache follows the
- * active locale automatically and prevents repeated constructor overhead in
- * reactive render paths.
- *
- * Detection is lazy and guarded: the default detector reads
- * `navigator.language` behind a `typeof` check at call time, so importing and
- * calling this during server rendering is safe, and runtimes without a
- * `navigator` resolve to the fallback locale. The composable owns no timers
- * or listeners, so no scope cleanup is required.
- *
- * @param source Reactive locale source. Empty values defer to the detector.
- * @param options Detection and fallback behavior.
- * @default options {}
- * @throws `RangeError` on first read of the reactive values when the winning
- * candidate is not a structurally valid locale identifier.
- * @returns Reactive locale metadata and cached formatter factories.
- */
-declare function useLocale(source?: MaybeRefOrGetter<Intl.Locale | string | null | undefined>, options?: UseLocaleOptions): LocaleControls;
-//#endregion
-//#region src/media-query.d.ts
-/** Capability required to evaluate media queries. */
-interface MediaQueryHost {
-  /** Create an observable result for a media query. */
-  readonly matchMedia: (query: string) => MediaQueryList;
-}
-/** Options for {@link useMediaQuery}. */
-interface UseMediaQueryOptions {
-  /**
-   * Value exposed when no media-query capability is available.
-   *
-   * @default false
-   */
-  readonly ssrValue?: boolean;
-  /**
-   * Reactive media-query capability for alternate runtimes and tests.
-   *
-   * @default globalThis.window when available
-   */
-  readonly host?: MaybeRefOrGetter<MediaQueryHost | null | undefined>;
-}
-/**
- * Evaluate a reactive media query without requiring browser globals.
- *
- * During server rendering (or whenever no capability host resolves) the ref
- * holds the configured server value and no subscription is created. The
- * change subscription follows the reactive query and host: each
- * re-evaluation removes the previous listener, and the final listener is
- * removed when the owning reactive scope stops. Call inside an active scope
- * so the subscription is released. A host whose matcher throws propagates
- * the error to the active effect run; the browser default never throws.
- *
- * @param query Reactive media-query source.
- * @param options Runtime capability and server-rendered fallback.
- * @default options {}
- * @returns Readonly ref that is `true` while the query matches.
- */
-declare function useMediaQuery(query: MaybeRefOrGetter<string>, options?: UseMediaQueryOptions): Readonly<Ref<boolean>>;
-/** User motion preference exposed by {@link useReducedMotion}. */
-type MotionPreference = "reduce" | "no-preference";
-/**
- * Return the reactive user motion preference.
- *
- * Shares {@link useMediaQuery} semantics: during server rendering the
- * preference is `"no-preference"` unless `ssrValue` is `true`, and the
- * underlying subscription is removed when the owning reactive scope stops.
- *
- * @param options Runtime capability and server-rendered fallback.
- * @default options {}
- * @returns Computed preference for `(prefers-reduced-motion: reduce)`.
- */
-declare function useReducedMotion(options?: UseMediaQueryOptions): ComputedRef<MotionPreference>;
-//#endregion
-//#region src/scope.d.ts
-/**
- * Register cleanup in the active reactive scope when one exists.
- *
- * This is the shared lifecycle primitive of the package: composables hand
- * their teardown here so owned resources are released when the surrounding
- * scope stops.
- *
- * Never throws and is safe during server rendering; no browser globals are
- * read. When no scope is active the cleanup is not registered and disposal
- * ownership stays with the caller.
- *
- * @param cleanup Cleanup invoked exactly once when the scope is disposed.
- * @returns Whether the cleanup was registered.
- */
-declare function tryOnScopeDispose(cleanup: () => void): boolean;
-//#endregion
-//#region src/timeout-scheduler.d.ts
-/**
- * Single-shot timer host used by the debounced and throttled state
- * utilities.
- *
- * Implement this interface to integrate a deterministic test clock, a native
- * runtime timer, or an application-owned scheduler. Handles are opaque: the
- * utilities only hand them back to {@link TimeoutScheduler.clearTimeout}.
- * This module declares types only and contributes no runtime code.
- */
-interface TimeoutScheduler {
-  /** Starts a single-shot callback and returns its opaque cancellation handle. */
-  readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
-  /** Cancels a handle previously returned by {@link TimeoutScheduler.setTimeout}. */
-  readonly clearTimeout: (handle: unknown) => void;
-}
-//#endregion
-//#region src/use-counter.d.ts
-/** Options for {@link useCounter}. */
-interface UseCounterOptions {
-  /**
-   * Inclusive lower bound applied to every value the counter takes.
-   *
-   * @default Number.NEGATIVE_INFINITY
-   */
-  readonly min?: number;
-  /**
-   * Inclusive upper bound applied to every value the counter takes.
-   *
-   * @default Number.POSITIVE_INFINITY
-   */
-  readonly max?: number;
-}
-/** Reactive controls returned by {@link useCounter}. */
-interface CounterControls {
-  /** Current count. Changes only through the controls, never by assignment. */
-  readonly count: Readonly<ShallowRef<number>>;
-  /** Whether the count currently sits on the configured lower bound. */
-  readonly atMin: ComputedRef<boolean>;
-  /** Whether the count currently sits on the configured upper bound. */
-  readonly atMax: ComputedRef<boolean>;
-  /**
-   * Add `delta` (default `1`) to the count and clamp into the bounds.
-   *
-   * @param delta Amount added; may be negative or infinite.
-   * @returns The count after clamping.
-   */
-  readonly increment: (delta?: number) => number;
-  /**
-   * Subtract `delta` (default `1`) from the count and clamp into the bounds.
-   *
-   * @param delta Amount subtracted; may be negative or infinite.
-   * @returns The count after clamping.
-   */
-  readonly decrement: (delta?: number) => number;
-  /**
-   * Assign a value directly, clamped into the bounds.
-   *
-   * @returns The count after clamping.
-   */
-  readonly set: (value: number) => number;
-  /**
-   * Restore the reset baseline, or establish a new one.
-   *
-   * Without an argument the count returns to the creation-time initial value
-   * (after its original clamping). With an argument, the clamped value
-   * becomes both the new count and the baseline used by later `reset()`
-   * calls.
-   *
-   * @param value Replacement baseline.
-   * @returns The count after clamping.
-   */
-  readonly reset: (value?: number) => number;
-}
-/**
- * Create a clamped counter whose every transition stays inside `[min, max]`.
- *
- * All operations clamp instead of failing, including the initial value, so
- * the count is inside the bounds at every observable moment. Only `NaN` is
- * rejected — silently corrupting the count is never an option. Purely
- * synchronous state: safe during server rendering (no browser globals, no
- * timers) and nothing to dispose, so it works inside and outside reactive
- * scopes alike. Bounds are fixed at creation and not reactive.
- *
- * @example
- * ```ts
- * const { count, increment, atMax } = useCounter(9, { min: 0, max: 10 });
- * increment(); // 10
- * increment(); // 10 (clamped)
- * atMax.value; // true
- * ```
- *
- * @param initial Count before any operation, clamped into the bounds.
- * @default initial 0
- * @param options Inclusive bounds for every value the counter takes.
- * @default options {}
- * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_RANGE` when a
- * bound is `NaN` or `min` exceeds `max`.
- * @throws `RangeError` tagged `VIZE_COMPOSE_COUNTER_INVALID_VALUE` when an
- * initial value, operand, or arithmetic result is `NaN` (for example
- * incrementing `-Infinity` by `Infinity`); the count is left unchanged.
- * @returns Reactive count, bound flags, and mutation controls.
- */
-declare function useCounter(initial?: number, options?: UseCounterOptions): CounterControls;
-//#endregion
-//#region src/use-debounced.d.ts
-/** Options for {@link useDebounced}. */
-interface UseDebouncedOptions {
-  /**
-   * Applies the timing policy when no browser `window` is available.
-   *
-   * Keep this disabled during server rendering, where the debounced view
-   * mirrors the source synchronously instead of starting timers. Enable it
-   * for native, desktop, worker, and test runtimes whose scheduler is
-   * lifecycle-bound.
-   *
-   * @default false
-   */
-  readonly runOnServer?: boolean;
-  /**
-   * Owns the single-shot timer.
-   *
-   * @default globalThis timer functions
-   */
-  readonly scheduler?: TimeoutScheduler;
-}
-/** Reactive debounced view and controls returned by {@link useDebounced}. */
-interface DebouncedControls<Value> {
-  /** Readonly view of the source that settles `waitMs` after the last change. */
-  readonly debounced: Readonly<ShallowRef<Value>>;
-  /** Whether a trailing update is currently scheduled. */
-  readonly pending: Readonly<ShallowRef<boolean>>;
-  /**
-   * Discard the scheduled trailing update and keep the last settled value.
-   * Later source changes debounce again as usual.
-   *
-   * @returns Whether a scheduled update was discarded.
-   */
-  readonly cancel: () => boolean;
-  /**
-   * Apply the current source value immediately instead of waiting out the
-   * delay.
-   *
-   * @returns Whether a scheduled update was applied.
-   */
-  readonly flush: () => boolean;
-}
-/**
- * Create a readonly debounced view of a reactive source.
- *
- * The view starts at the current source value. Each source change (observed
- * with `flush: "sync"`, so every synchronous write counts) restarts a
- * single-shot timer of `waitMs` milliseconds; when it fires, the view takes
- * the source value current at that moment. `waitMs` is reactive and is read
- * when a timer is scheduled; changing it does not restart an already-pending
- * timer. A wait of `0` still defers to the next scheduler tick.
- *
- * Server rendering is explicit: without a browser `window` (and with
- * {@link UseDebouncedOptions.runOnServer} disabled) no timer ever starts and
- * the view mirrors the source synchronously, so server-rendered output shows
- * current values and nothing leaks. `pending` stays `false` and the controls
- * report `false` in that mode.
- *
- * Cleanup rule: the watcher and any pending timer are released when the
- * owning reactive scope stops; call inside an active scope. Outside one, the
- * watcher lives as long as the source and `cancel()` only clears the pending
- * timer.
- *
- * @example
- * ```ts
- * const query = shallowRef("");
- * const { debounced, flush } = useDebounced(query, 300);
- * query.value = "vize"; // debounced.value still "" for 300ms
- * flush(); // debounced.value === "vize" immediately
- * ```
- *
- * @param source Reactive source to debounce.
- * @param waitMs Reactive delay in milliseconds; must be finite and at least
- * zero. Fractions are truncated.
- * @param options Runtime scheduling overrides.
- * @default options {}
- * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` when the
- * resolved wait is not finite or is negative, both synchronously at creation
- * (even in mirror mode) and again for every scheduled delay.
- * @returns Readonly debounced view, pending flag, and cancel/flush controls.
- */
-declare function useDebounced<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseDebouncedOptions): DebouncedControls<Value>;
-//#endregion
-//#region src/use-history.d.ts
-/** Options for {@link useHistory}. */
-interface UseHistoryOptions<Value> {
-  /**
-   * Maximum number of undo entries retained; recording a change beyond it
-   * drops the oldest entry. The redo stack is bounded by construction, since
-   * redo entries only ever come from undone changes. Must be an integer
-   * greater than zero and is fixed at creation.
-   *
-   * @default 100
-   */
-  readonly capacity?: number;
-  /**
-   * Clone applied to every value captured into history and to every value
-   * restored out of it, isolating snapshots from later in-place mutation.
-   *
-   * @default identity — values are stored and restored by reference
-   */
-  readonly clone?: (value: Value) => Value;
-}
-/** Reactive undo/redo controls returned by {@link useHistory}. */
-interface HistoryControls {
-  /** Whether {@link HistoryControls.undo} currently has an entry to restore. */
-  readonly canUndo: ComputedRef<boolean>;
-  /** Whether {@link HistoryControls.redo} currently has an entry to restore. */
-  readonly canRedo: ComputedRef<boolean>;
-  /** Number of retained undo entries. */
-  readonly undoCount: ComputedRef<number>;
-  /** Number of retained redo entries. */
-  readonly redoCount: ComputedRef<number>;
-  /**
-   * Restore the newest undo entry and move the current value onto the redo
-   * stack. The restoring write is not recorded.
-   *
-   * @returns Whether an entry was restored.
-   */
-  readonly undo: () => boolean;
-  /**
-   * Restore the newest redo entry and move the current value back onto the
-   * undo stack. The restoring write is not recorded.
-   *
-   * @returns Whether an entry was restored.
-   */
-  readonly redo: () => boolean;
-  /**
-   * Group every source write inside `run` into at most one undo entry.
-   *
-   * The entry restores the value from just before the batch. It is committed
-   * only when the final value differs (`Object.is`) from the starting value,
-   * and it is committed even when `run` throws, so a partially applied batch
-   * stays undoable as one step. Nested calls collapse into the outermost
-   * batch. The callback's return value is passed through.
-   */
-  readonly batch: <Result>(run: () => Result) => Result;
-  /** Drop every undo and redo entry while keeping the current value. */
-  readonly clear: () => void;
-}
-/**
- * Record bounded undo/redo history over the writes of a ref.
- *
- * Recording is shallow and identity-based, matching Vue's own change
- * detection: assignments to `source.value` are recorded (observed with
- * `flush: "sync"`, so every synchronous write counts), writes that are
- * `Object.is`-equal to the current value are not changes, and in-place
- * mutations of object values are invisible — pair mutable values with
- * {@link UseHistoryOptions.clone} and reassign. Undoing and redoing restore
- * values through `clone` as well, so snapshots never share identity with the
- * live value unless the default identity clone is kept. When a
- * user-provided `clone` throws, the failed operation leaves history
- * unchanged and the error propagates.
- *
- * Safe during server rendering: no browser globals are read and no timers
- * start. Cleanup rule: when the owning reactive scope stops, recording stops
- * and every retained snapshot is released, so `undo`/`redo` return `false`
- * afterwards; call inside an active scope, or the watcher lives as long as
- * the source.
- *
- * @example
- * ```ts
- * const text = shallowRef("");
- * const { undo, redo, batch } = useHistory(text);
- * text.value = "a";
- * batch(() => {
- *   text.value = "ab";
- *   text.value = "abc";
- * });
- * undo(); // text.value === "a" (the batch is one step)
- * redo(); // text.value === "abc"
- * ```
- *
- * @param source Ref whose writes are recorded.
- * @param options Retention bound and snapshot cloning.
- * @default options {}
- * @throws `RangeError` tagged `VIZE_COMPOSE_HISTORY_INVALID_CAPACITY` when
- * the capacity is not an integer greater than zero.
- * @throws `Error` tagged `VIZE_COMPOSE_HISTORY_IN_BATCH` when `undo`,
- * `redo`, or `clear` is called inside {@link HistoryControls.batch}, where
- * stack movement would corrupt the pending group.
- * @returns Reactive undo/redo state and controls.
- */
-declare function useHistory<Value>(source: Ref<Value>, options?: UseHistoryOptions<Value>): HistoryControls;
-//#endregion
-//#region src/use-previous.d.ts
-/**
- * Track the value a reactive source held before its latest change.
- *
- * The semantics are precise and arity-based:
- *
- * - Without an `initial` argument the ref holds `undefined` until the source
- *   changes for the first time.
- * - With an `initial` argument (including an explicit `undefined` when
- *   `Value` allows it) the ref holds that value until the first change, and
- *   the return type never widens with `undefined`.
- * - Every synchronous write is observed (`flush: "sync"`), so a sequence of
- *   writes in one tick shifts the previous value step by step instead of
- *   collapsing into one batch.
- * - Writes whose value is `Object.is`-equal to the current value do not
- *   count as changes, matching Vue's own change detection.
- * - Tracking is shallow: reassignments are observed, in-place mutations of
- *   object values are not.
- *
- * Safe during server rendering: no browser globals are read and no timers
- * start. The underlying watcher is bound to the current reactive scope and
- * stops with it; call inside an active scope, or the watcher lives as long
- * as the source. A plain non-reactive source never changes, so the ref stays
- * at its initial value.
- *
- * @example
- * ```ts
- * const route = shallowRef("/home");
- * const previousRoute = usePrevious(route, "/");
- * route.value = "/settings";
- * previousRoute.value; // "/home"
- * ```
- *
- * @param source Reactive source to observe.
- * @param initial Value reported before the first change.
- * @returns Readonly shallow ref holding the previous source value.
- */
-declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>): Readonly<ShallowRef<Value | undefined>>;
-declare function usePrevious<Value>(source: MaybeRefOrGetter<Value>, initial: Value): Readonly<ShallowRef<Value>>;
-//#endregion
-//#region src/use-throttled.d.ts
-/** Options for {@link useThrottled}. */
-interface UseThrottledOptions {
-  /**
-   * Apply the first change of a cooldown window immediately.
-   *
-   * @default true
-   */
-  readonly leading?: boolean;
-  /**
-   * Apply the newest change collected during a cooldown window when the
-   * window ends. When disabled, changes inside a window are dropped.
-   *
-   * @default true
-   */
-  readonly trailing?: boolean;
-  /**
-   * Applies the timing policy when no browser `window` is available.
-   *
-   * Keep this disabled during server rendering, where the throttled view
-   * mirrors the source synchronously instead of starting timers. Enable it
-   * for native, desktop, worker, and test runtimes whose scheduler is
-   * lifecycle-bound.
-   *
-   * @default false
-   */
-  readonly runOnServer?: boolean;
-  /**
-   * Owns the single-shot cooldown timer.
-   *
-   * @default globalThis timer functions
-   */
-  readonly scheduler?: TimeoutScheduler;
-}
-/** Reactive throttled view and controls returned by {@link useThrottled}. */
-interface ThrottledControls<Value> {
-  /** Readonly view of the source updated at most once per cooldown window. */
-  readonly throttled: Readonly<ShallowRef<Value>>;
-  /** Whether a trailing update is waiting for the current window to end. */
-  readonly pending: Readonly<ShallowRef<boolean>>;
-  /**
-   * Discard the waiting trailing update and close the cooldown window, so
-   * the next change starts fresh on a leading edge.
-   *
-   * @returns Whether a waiting trailing update was discarded.
-   */
-  readonly cancel: () => boolean;
-  /**
-   * Apply the waiting trailing update immediately and close the cooldown
-   * window. Without a waiting update the window is left untouched.
-   *
-   * @returns Whether a waiting trailing update was applied.
-   */
-  readonly flush: () => boolean;
-}
-/**
- * Create a readonly throttled view of a reactive source.
- *
- * Changes are observed with `flush: "sync"`, so every synchronous write
- * counts. Outside a cooldown window, a change applies immediately when
- * {@link UseThrottledOptions.leading} is enabled (otherwise it waits as a
- * trailing update) and opens a window of `waitMs` milliseconds. Changes
- * inside a window are collected as the trailing candidate; when the window
- * ends with a candidate waiting, the source value current at that moment is
- * applied and the next window opens back to back, keeping applications
- * spaced by `waitMs`. A window that ends without a candidate closes silently.
- * `waitMs` is reactive and is read each time a window opens; changing it
- * never disturbs an already-open window. A wait of `0` still defers trailing
- * updates to the next scheduler tick.
- *
- * Server rendering is explicit: without a browser `window` (and with
- * {@link UseThrottledOptions.runOnServer} disabled) no timer ever starts and
- * the view mirrors the source synchronously, so server-rendered output shows
- * current values and nothing leaks. `pending` stays `false` and the controls
- * report `false` in that mode.
- *
- * Cleanup rule: the watcher and any open window timer are released when the
- * owning reactive scope stops; call inside an active scope. Outside one, the
- * watcher lives as long as the source and `cancel()` only clears the window.
- *
- * @example
- * ```ts
- * const scrollY = shallowRef(0);
- * const { throttled } = useThrottled(scrollY, 100);
- * scrollY.value = 40; // applied immediately (leading edge)
- * scrollY.value = 80; // applied when the 100ms window ends
- * ```
- *
- * @param source Reactive source to throttle.
- * @param waitMs Reactive cooldown in milliseconds; must be finite and at
- * least zero. Fractions are truncated.
- * @param options Edge policy and runtime scheduling overrides.
- * @default options {}
- * @throws `RangeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_WAIT` when the
- * resolved wait is not finite or is negative, both synchronously at creation
- * (even in mirror mode) and again each time a window opens.
- * @throws `TypeError` tagged `VIZE_COMPOSE_THROTTLE_INVALID_EDGES` when both
- * `leading` and `trailing` are disabled, because updates could then never
- * propagate.
- * @returns Readonly throttled view, pending flag, and cancel/flush controls.
- */
-declare function useThrottled<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseThrottledOptions): ThrottledControls<Value>;
-//#endregion
-//#region src/use-toggle.d.ts
-/** Reactive controls returned by {@link useToggle}. */
-interface ToggleControls {
-  /**
-   * Owned boolean state.
-   *
-   * Deliberately writable: unlike the derived views elsewhere in this
-   * package, the toggle owns its state, so assigning the ref directly (for
-   * example through `v-model`) is equivalent to calling
-   * {@link ToggleControls.toggle} with a forced value.
-   */
-  readonly state: Ref<boolean>;
-  /**
-   * Invert the state, or force it to `force` when the argument is given.
-   * Passing an explicit `undefined` behaves like passing no argument.
-   *
-   * @param force Value assigned instead of inverting.
-   * @returns The state after the change.
-   */
-  readonly toggle: (force?: boolean) => boolean;
-}
-/**
- * Create owned boolean state with an inverting control.
- *
- * Purely synchronous state: safe during server rendering (no browser
- * globals, no timers) and nothing to dispose, so it works inside and
- * outside reactive scopes alike.
- *
- * @example
- * ```ts
- * const { state: open, toggle } = useToggle();
- * toggle(); // true
- * toggle(false); // false
- * open.value; // false
- * ```
- *
- * @param initial State before the first toggle.
- * @default initial false
- * @returns The writable state and its toggle control.
- */
-declare function useToggle(initial?: boolean): ToggleControls;
-//#endregion
-export { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, CounterControls, DebouncedControls, EventListenerControls, HistoryControls, LocaleControls, MediaQueryHost, MotionPreference, TextDirection, ThrottledControls, TimeoutScheduler, ToggleControls, UseAsyncResourceOptions, UseCounterOptions, UseDebouncedOptions, UseEventListenerOptions, UseHistoryOptions, UseLocaleOptions, UseMediaQueryOptions, UseThrottledOptions, tryOnScopeDispose, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };
+import { TimeoutScheduler } from "./timeout-scheduler.mjs";
+import { DeadlineAbortSignalOptions, TimeoutAbortSignalOptions, anyAbortSignal, deadlineAbortSignal, timeoutAbortSignal } from "./abort-signal.mjs";
+import { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, UseAsyncResourceOptions, useAsyncResource } from "./async-resource.mjs";
+import { a as CapabilityUnavailableReason, c as isCapabilityAvailable, i as CapabilityTarget, l as isCapabilityUnavailable, n as CapabilityResult, o as UnavailableCapability, r as CapabilitySource, s as availableCapability, t as AvailableCapability, u as unavailableCapability } from "./capability-BNpkvSy5.mjs";
+import { a as ComposableEntryMetadata, c as ComposableRootEntryMetadata, d as ComposableUtilityMetadata, i as ComposableCleanupOwner, l as ComposableSsrBehavior, n as ComposableCatalog, o as ComposableHydrationBehavior, r as ComposableCategory, s as ComposableInstallationAvailability, t as COMPOSABLE_CATALOG, u as ComposableStability } from "./catalog-CuWhR-0q.mjs";
+import { CleanupRegistration, CreateDisposalScopeOptions, DISPOSAL_ERROR_CODE, DisposalError, DisposalScope, createDisposalScope } from "./disposal-scope.mjs";
+import { EventListenerControls, UseEventListenerOptions, useEventListener } from "./event-listener.mjs";
+import { LocaleControls, TextDirection, UseLocaleOptions, useLocale } from "./locale.mjs";
+import { MediaQueryHost, MotionPreference, UseMediaQueryOptions, useMediaQuery, useReducedMotion } from "./media-query.mjs";
+import { RetryDelayOptions, calculateRetryDelay } from "./retry-delay.mjs";
+import { RetryAsyncOptions, RetryAttemptContext, RetryFailureContext, RetryScheduledContext, retryAsync } from "./retry-async.mjs";
+import { tryOnScopeDispose } from "./scope.mjs";
+import { CounterControls, UseCounterOptions, useCounter } from "./use-counter.mjs";
+import { DebouncedControls, UseDebouncedOptions, useDebounced } from "./use-debounced.mjs";
+import { HistoryControls, UseHistoryOptions, useHistory } from "./use-history.mjs";
+import { usePrevious } from "./use-previous.mjs";
+import { ThrottledControls, UseThrottledOptions, useThrottled } from "./use-throttled.mjs";
+import { ToggleControls, useToggle } from "./use-toggle.mjs";
+export { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, AvailableCapability, COMPOSABLE_CATALOG, CapabilityResult, CapabilitySource, CapabilityTarget, CapabilityUnavailableReason, CleanupRegistration, ComposableCatalog, ComposableCategory, ComposableCleanupOwner, ComposableEntryMetadata, ComposableHydrationBehavior, ComposableInstallationAvailability, ComposableRootEntryMetadata, ComposableSsrBehavior, ComposableStability, ComposableUtilityMetadata, CounterControls, CreateDisposalScopeOptions, DISPOSAL_ERROR_CODE, DeadlineAbortSignalOptions, DebouncedControls, DisposalError, DisposalScope, EventListenerControls, HistoryControls, LocaleControls, MediaQueryHost, MotionPreference, RetryAsyncOptions, RetryAttemptContext, RetryDelayOptions, RetryFailureContext, RetryScheduledContext, TextDirection, ThrottledControls, TimeoutAbortSignalOptions, TimeoutScheduler, ToggleControls, UnavailableCapability, UseAsyncResourceOptions, UseCounterOptions, UseDebouncedOptions, UseEventListenerOptions, UseHistoryOptions, UseLocaleOptions, UseMediaQueryOptions, UseThrottledOptions, anyAbortSignal, availableCapability, calculateRetryDelay, createDisposalScope, deadlineAbortSignal, isCapabilityAvailable, isCapabilityUnavailable, retryAsync, timeoutAbortSignal, tryOnScopeDispose, unavailableCapability, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };