@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-memoize.d.mts

@@ -0,0 +1,73 @@
+//#region src/use-memoize.d.ts
+/** Minimal cache contract used by {@link useMemoize}; a `Map` satisfies it. */
+interface MemoizeCache<Key, Result> {
+  /** Read a cached result. */
+  get(key: Key): Result | undefined;
+  /** Store a result. */
+  set(key: Key, value: Result): unknown;
+  /** Whether a result is cached for `key`. */
+  has(key: Key): boolean;
+  /** Drop one result. */
+  delete(key: Key): unknown;
+  /** Drop every result. */
+  clear(): void;
+}
+/** Options for {@link useMemoize}. */
+interface UseMemoizeOptions<Arguments extends readonly unknown[], Key, Result> {
+  /**
+   * Derive the cache key from the arguments.
+   *
+   * @default JSON.stringify of the argument list
+   */
+  readonly getKey?: (...args: Arguments) => Key;
+  /**
+   * Storage for results; supply an LRU or a persistent cache here.
+   *
+   * @default a reactive Map
+   */
+  readonly cache?: MemoizeCache<Key, Result>;
+}
+/** Memoized function returned by {@link useMemoize}. */
+interface Memoized<Arguments extends readonly unknown[], Result, Key> {
+  /** Return the cached result for these arguments, computing it on a miss. */
+  (...args: Arguments): Result;
+  /** Recompute and re-cache the result for these arguments. */
+  readonly load: (...args: Arguments) => Result;
+  /** Drop the cached result for these arguments. */
+  readonly delete: (...args: Arguments) => void;
+  /** Drop every cached result. */
+  readonly clear: () => void;
+  /** Cache key for these arguments. */
+  readonly generateKey: (...args: Arguments) => Key;
+  /** The underlying cache. */
+  readonly cache: MemoizeCache<Key, Result>;
+}
+/**
+ * Cache a function's results per argument list.
+ *
+ * The default cache is a reactive `Map`, so computeds and templates that
+ * read a memoized value re-evaluate after `load`, `delete`, or `clear`.
+ * Promise-returning resolvers cache the promise itself, which deduplicates
+ * concurrent requests. Keys default to `JSON.stringify(args)` (a `string`);
+ * a custom `getKey` sets the key type, and a custom `cache` must use that
+ * key type. On the server keep memoized caches request-local (create them in
+ * `setup`), since a module-level cache is shared across requests.
+ *
+ * @example
+ * ```ts
+ * const getUser = useMemoize((id: string) => fetchUser(id), { getKey: (id) => id });
+ * const user = computed(() => getUser(props.id));
+ * getUser.load(props.id); // refresh
+ * ```
+ *
+ * @param resolver Function whose results are cached.
+ * @param options Key derivation and cache storage.
+ * @default options {}
+ * @returns The memoized function with cache controls.
+ */
+declare function useMemoize<Arguments extends readonly unknown[], Result, Key>(resolver: (...args: Arguments) => Result, options: UseMemoizeOptions<Arguments, Key, Result> & {
+  readonly getKey: (...args: Arguments) => Key;
+}): Memoized<Arguments, Result, Key>;
+declare function useMemoize<Arguments extends readonly unknown[], Result>(resolver: (...args: Arguments) => Result, options?: UseMemoizeOptions<Arguments, string, Result>): Memoized<Arguments, Result, string>;
+//#endregion
+export { MemoizeCache, Memoized, UseMemoizeOptions, useMemoize };

package/dist/use-memoize.mjs

@@ -0,0 +1,28 @@
+import { shallowReactive } from "vue";
+//#region src/use-memoize.ts
+function useMemoize(resolver, options = {}) {
+	const cache = options.cache ?? shallowReactive(/* @__PURE__ */ new Map());
+	const generateKey = (...args) => options.getKey === void 0 ? JSON.stringify(args) : options.getKey(...args);
+	const load = (...args) => {
+		const result = resolver(...args);
+		cache.set(generateKey(...args), result);
+		return result;
+	};
+	const memoized = (...args) => {
+		const key = generateKey(...args);
+		return cache.has(key) ? cache.get(key) : load(...args);
+	};
+	return Object.assign(memoized, {
+		load,
+		delete: (...args) => {
+			cache.delete(generateKey(...args));
+		},
+		clear: () => {
+			cache.clear();
+		},
+		generateKey,
+		cache
+	});
+}
+//#endregion
+export { useMemoize };

package/dist/use-mounted.d.mts

@@ -0,0 +1,24 @@
+import { ShallowRef } from "vue";
+
+//#region src/use-mounted.d.ts
+/**
+ * Whether the calling component has mounted.
+ *
+ * `false` during server rendering and during hydration, `true` from the
+ * component's `onMounted` on: gate client-only rendering behind it to keep
+ * hydration stable. Outside a component (no instance to mount) it stays
+ * `false`. Component detection uses `hasInjectionContext()` rather than
+ * `getCurrentInstance()`, which returns `null` inside Vapor components, so
+ * the flag also flips in Vapor.
+ *
+ * @example
+ * ```ts
+ * const mounted = useMounted();
+ * // <ClientOnlyChart v-if="mounted" />
+ * ```
+ *
+ * @returns Readonly mounted flag.
+ */
+declare function useMounted(): Readonly<ShallowRef<boolean>>;
+//#endregion
+export { useMounted };

package/dist/use-mounted.mjs

@@ -0,0 +1,29 @@
+import { hasInjectionContext, onMounted, shallowRef } from "vue";
+//#region src/use-mounted.ts
+/**
+* Whether the calling component has mounted.
+*
+* `false` during server rendering and during hydration, `true` from the
+* component's `onMounted` on: gate client-only rendering behind it to keep
+* hydration stable. Outside a component (no instance to mount) it stays
+* `false`. Component detection uses `hasInjectionContext()` rather than
+* `getCurrentInstance()`, which returns `null` inside Vapor components, so
+* the flag also flips in Vapor.
+*
+* @example
+* ```ts
+* const mounted = useMounted();
+* // <ClientOnlyChart v-if="mounted" />
+* ```
+*
+* @returns Readonly mounted flag.
+*/
+function useMounted() {
+	const mounted = shallowRef(false);
+	if (hasInjectionContext()) onMounted(() => {
+		mounted.value = true;
+	});
+	return mounted;
+}
+//#endregion
+export { useMounted };

package/dist/use-navigation-api.d.mts

@@ -0,0 +1,360 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-navigation-api.d.ts
+/** Navigation types of the Navigation API. */
+type NavigationTypeName = "push" | "replace" | "reload" | "traverse";
+/** History handling requested by `navigate`. */
+type NavigationHistoryMode = "auto" | "push" | "replace";
+/** Events of the Navigation API observed by {@link useNavigationApi}. */
+type NavigationEventName = "navigate" | "navigatesuccess" | "navigateerror" | "currententrychange";
+/** Minimal `NavigationHistoryEntry`. */
+interface NavigationHistoryEntryLike {
+  /** Entry URL, or null when hidden (cross-origin). */
+  readonly url: string | null;
+  /** Key identifying the history slot. */
+  readonly key: string;
+  /** Unique identifier of the entry. */
+  readonly id: string;
+  /** Index in the entry list, or -1. */
+  readonly index: number;
+  /** Whether the entry belongs to the current document. */
+  readonly sameDocument: boolean;
+  /** Developer-defined state. */
+  getState(): unknown;
+}
+/** Minimal `NavigationDestination`. */
+interface NavigationDestinationLike {
+  /** Destination URL. */
+  readonly url: string;
+  /** Index of the destination entry for traversals, otherwise -1. */
+  readonly index: number;
+  /** Whether the destination is the current document. */
+  readonly sameDocument: boolean;
+  /** State of the destination. */
+  getState(): unknown;
+}
+/** Options accepted by {@link NavigateEventLike.intercept}. */
+interface NavigationInterceptInit {
+  /** Performs the same-document navigation. */
+  readonly handler?: () => Promise<void>;
+  /** Focus behavior after the navigation. */
+  readonly focusReset?: "after-transition" | "manual";
+  /** Scroll behavior after the navigation. */
+  readonly scroll?: "after-transition" | "manual";
+}
+/** Minimal `NavigateEvent`. */
+interface NavigateEventLike {
+  /** Navigation type. */
+  readonly navigationType: NavigationTypeName;
+  /** Where the navigation goes. */
+  readonly destination: NavigationDestinationLike;
+  /** Whether `intercept` may be called. */
+  readonly canIntercept: boolean;
+  /** Whether the user initiated the navigation. */
+  readonly userInitiated: boolean;
+  /** Whether only the fragment changes. */
+  readonly hashChange: boolean;
+  /** Download file name for `<a download>` navigations, else null. */
+  readonly downloadRequest: string | null;
+  /** Aborted when the navigation is cancelled. */
+  readonly signal: AbortSignal;
+  /** Info passed by the initiator. */
+  readonly info: unknown;
+  /** Convert the navigation into a same-document navigation. */
+  intercept(options?: NavigationInterceptInit): void;
+  /** Cancel the navigation when cancelable. */
+  preventDefault(): void;
+}
+/** Minimal result of a Navigation API action. */
+interface NavigationResultLike {
+  /** Resolves when the URL and entry changed. */
+  readonly committed?: Promise<NavigationHistoryEntryLike>;
+  /** Resolves when the navigation finished (handlers settled). */
+  readonly finished?: Promise<NavigationHistoryEntryLike>;
+}
+/** Minimal `window.navigation`. */
+interface NavigationHost {
+  /** Current entry. */
+  readonly currentEntry: NavigationHistoryEntryLike | null;
+  /** Ongoing intercepted navigation. */
+  readonly transition: {
+    /** Navigation type. */readonly navigationType: NavigationTypeName; /** Entry navigated away from. */
+    readonly from: NavigationHistoryEntryLike;
+  } | null;
+  /** Whether `back` is possible. */
+  readonly canGoBack: boolean;
+  /** Whether `forward` is possible. */
+  readonly canGoForward: boolean;
+  /** Same-origin entries of the session history. */
+  entries(): readonly NavigationHistoryEntryLike[];
+  /** Navigate to `url`. */
+  navigate(url: string, options?: {
+    state?: unknown;
+    history?: NavigationHistoryMode;
+    info?: unknown;
+  }): NavigationResultLike;
+  /** Traverse one entry back. */
+  back(options?: {
+    info?: unknown;
+  }): NavigationResultLike;
+  /** Traverse one entry forward. */
+  forward(options?: {
+    info?: unknown;
+  }): NavigationResultLike;
+  /** Traverse to the entry with `key`. */
+  traverseTo(key: string, options?: {
+    info?: unknown;
+  }): NavigationResultLike;
+  /** Reload the current entry. */
+  reload(options?: {
+    state?: unknown;
+    info?: unknown;
+  }): NavigationResultLike;
+  /** Replace the current entry's state without navigating. */
+  updateCurrentEntry(options: {
+    state: unknown;
+  }): void;
+  /** Subscribe to a navigation event. */
+  addEventListener(type: NavigationEventName, listener: (event: Event) => void): void;
+  /** Unsubscribe from a navigation event. */
+  removeEventListener(type: NavigationEventName, listener: (event: Event) => void): void;
+}
+/** Plain snapshot of a history entry. */
+interface NavigationEntrySnapshot {
+  /** Entry URL, or null when hidden. */
+  readonly url: string | null;
+  /** Key identifying the history slot. */
+  readonly key: string;
+  /** Unique identifier of the entry. */
+  readonly id: string;
+  /** Index in the entry list. */
+  readonly index: number;
+  /** Whether the entry belongs to the current document. */
+  readonly sameDocument: boolean;
+}
+/** Plain snapshot of the ongoing navigation. */
+interface NavigationTransitionSnapshot {
+  /** Navigation type. */
+  readonly navigationType: NavigationTypeName;
+  /** Entry navigated away from. */
+  readonly from: NavigationEntrySnapshot;
+}
+/** Details passed to `onCurrentEntryChange` listeners. */
+interface NavigationEntryChange {
+  /** Navigation type, or null for `updateCurrentEntry`. */
+  readonly navigationType: NavigationTypeName | null;
+  /** Previous entry. */
+  readonly from: NavigationEntrySnapshot;
+}
+/** Discriminated outcome of a navigation action. */
+type NavigationOutcome = {
+  /** The navigation finished. */readonly status: "success"; /** Entry navigated to. */
+  readonly entry: NavigationEntrySnapshot;
+} | {
+  /** The Navigation API is missing. */readonly status: "unsupported";
+} | {
+  /** The navigation failed or was aborted. */readonly status: "error"; /** Error thrown or rejected by the host. */
+  readonly error: unknown;
+};
+/** Options of {@link NavigationApiControls.navigate}. */
+interface NavigationNavigateOptions<State> {
+  /**
+   * State stored on the new entry.
+   *
+   * @default undefined
+   */
+  readonly state?: State;
+  /**
+   * History handling.
+   *
+   * @default "auto"
+   */
+  readonly history?: NavigationHistoryMode;
+  /**
+   * Info handed to `navigate` listeners.
+   *
+   * @default undefined
+   */
+  readonly info?: unknown;
+}
+/** Options of {@link NavigationApiControls.intercept}. */
+interface NavigationInterceptOptions {
+  /**
+   * Runs the same-document navigation.
+   *
+   * @default undefined (commit the URL only)
+   */
+  readonly handler?: (event: NavigateEventLike) => Promise<void> | void;
+  /**
+   * Focus behavior after the navigation.
+   *
+   * @default "after-transition"
+   */
+  readonly focusReset?: "after-transition" | "manual";
+  /**
+   * Scroll behavior after the navigation.
+   *
+   * @default "after-transition"
+   */
+  readonly scroll?: "after-transition" | "manual";
+}
+/** Options for {@link useNavigationApi}. */
+interface UseNavigationApiOptions<State = unknown> {
+  /**
+   * Navigation API capability for alternate runtimes and tests.
+   *
+   * @default window.navigation when it exists
+   */
+  readonly navigation?: MaybeRefOrGetter<NavigationHost | null | undefined>;
+  /**
+   * Validate or convert raw entry state into `State`; return undefined for
+   * foreign state.
+   *
+   * @default the raw state, trusted as `State`
+   */
+  readonly parseState?: (raw: unknown) => State | undefined;
+}
+/** Reactive state and actions returned by {@link useNavigationApi}. */
+interface NavigationApiControls<State> {
+  /** Whether the Navigation API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Snapshot of the current entry. */
+  readonly currentEntry: Readonly<ShallowRef<NavigationEntrySnapshot | null>>;
+  /** Snapshots of the same-origin session entries. */
+  readonly entries: Readonly<ShallowRef<readonly NavigationEntrySnapshot[]>>;
+  /** Whether `back` is possible. */
+  readonly canGoBack: Readonly<ShallowRef<boolean>>;
+  /** Whether `forward` is possible. */
+  readonly canGoForward: Readonly<ShallowRef<boolean>>;
+  /** Ongoing intercepted navigation. */
+  readonly transition: Readonly<ShallowRef<NavigationTransitionSnapshot | null>>;
+  /** State of the current entry (not proxied), refreshed with the entry. */
+  readonly state: ComputedRef<State | undefined>;
+  /** Most recent failed action or `navigateerror`, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Read the current entry's state now.
+   *
+   * @returns The parsed state.
+   */
+  readonly getState: () => State | undefined;
+  /**
+   * Listen to `navigate`.
+   *
+   * @param listener Receives the navigate event.
+   * @returns Removes the listener.
+   */
+  readonly onNavigate: (listener: (event: NavigateEventLike) => void) => () => void;
+  /**
+   * Listen to `navigatesuccess`.
+   *
+   * @param listener Called after a navigation finished.
+   * @returns Removes the listener.
+   */
+  readonly onNavigateSuccess: (listener: () => void) => () => void;
+  /**
+   * Listen to `navigateerror`.
+   *
+   * @param listener Receives the navigation error.
+   * @returns Removes the listener.
+   */
+  readonly onNavigateError: (listener: (error: unknown) => void) => () => void;
+  /**
+   * Listen to `currententrychange`.
+   *
+   * @param listener Receives the navigation type and previous entry.
+   * @returns Removes the listener.
+   */
+  readonly onCurrentEntryChange: (listener: (change: NavigationEntryChange) => void) => () => void;
+  /**
+   * Intercept interceptable, same-origin, non-download, non-hash navigations
+   * whose destination matches `predicate`.
+   *
+   * @param predicate Receives the destination URL and the event.
+   * @param options Handler, focus and scroll behavior.
+   * @default options {}
+   * @returns Removes the interceptor.
+   */
+  readonly intercept: (predicate: (url: URL, event: NavigateEventLike) => boolean, options?: NavigationInterceptOptions) => () => void;
+  /**
+   * Navigate to `url`.
+   *
+   * @param url Destination.
+   * @param options State, history mode and info.
+   * @default options {}
+   * @returns The outcome once finished.
+   */
+  readonly navigate: (url: string, options?: NavigationNavigateOptions<State>) => Promise<NavigationOutcome>;
+  /**
+   * Go back one entry.
+   *
+   * @param info Info handed to `navigate` listeners.
+   * @returns The outcome once finished.
+   */
+  readonly back: (info?: unknown) => Promise<NavigationOutcome>;
+  /**
+   * Go forward one entry.
+   *
+   * @param info Info handed to `navigate` listeners.
+   * @returns The outcome once finished.
+   */
+  readonly forward: (info?: unknown) => Promise<NavigationOutcome>;
+  /**
+   * Traverse to the entry with `key`.
+   *
+   * @param key Entry key.
+   * @param info Info handed to `navigate` listeners.
+   * @returns The outcome once finished.
+   */
+  readonly traverseTo: (key: string, info?: unknown) => Promise<NavigationOutcome>;
+  /**
+   * Reload the current entry, optionally replacing its state.
+   *
+   * @param options New state and info.
+   * @default options {}
+   * @returns The outcome once finished.
+   */
+  readonly reload: (options?: {
+    readonly state?: State;
+    readonly info?: unknown;
+  }) => Promise<NavigationOutcome>;
+  /**
+   * Replace the current entry's state without navigating.
+   *
+   * @param options New state.
+   * @returns Whether the state was updated.
+   */
+  readonly updateCurrentEntry: (options: {
+    readonly state: State;
+  }) => boolean;
+}
+/**
+ * Reactive access to the Navigation API (`window.navigation`).
+ *
+ * Entry snapshots refresh on `currententrychange`, `navigatesuccess` and
+ * `navigateerror`. Actions resolve to a {@link NavigationOutcome} and never
+ * reject; failures also land in `error`. Listeners (including interceptors)
+ * are removed when the owning reactive scope stops; outside a scope the
+ * caller removes them with the returned functions.
+ *
+ * Server rendering: nothing is read or subscribed; `supported` is false,
+ * `currentEntry` null, `entries` empty, and actions resolve to
+ * `{ status: "unsupported" }`.
+ * Inside a component the host is resolved after mounting, so hydration
+ * renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const nav = useNavigationApi<{ tab: string }>();
+ * nav.intercept((url) => url.pathname.startsWith("/app/"), {
+ *   handler: async () => renderRoute(location.pathname),
+ * });
+ * ```
+ *
+ * @param options Navigation host and state parser.
+ * @default options {}
+ * @returns Navigation state, hooks and actions.
+ */
+declare function useNavigationApi<State = unknown>(options?: UseNavigationApiOptions<State>): NavigationApiControls<State>;
+//#endregion
+export { NavigateEventLike, NavigationApiControls, NavigationDestinationLike, NavigationEntryChange, NavigationEntrySnapshot, NavigationEventName, NavigationHistoryEntryLike, NavigationHistoryMode, NavigationHost, NavigationInterceptInit, NavigationInterceptOptions, NavigationNavigateOptions, NavigationOutcome, NavigationResultLike, NavigationTransitionSnapshot, NavigationTypeName, UseNavigationApiOptions, useNavigationApi };