@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-style-tag.d.mts

@@ -0,0 +1,102 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-style-tag.d.ts
+/** `<style>` subset used by {@link useStyleTag}. */
+interface StyleTagElement {
+  /** Style sheet text. */
+  textContent: string | null;
+  /** Write an attribute. */
+  setAttribute(name: string, value: string): void;
+}
+/** Document capability used by {@link useStyleTag}. */
+interface StyleTagHost {
+  /** Find an existing `<style>` with the given `id`. */
+  findStyle(id: string): StyleTagElement | undefined;
+  /** Create a detached `<style>`. */
+  createStyle(): StyleTagElement;
+  /** Attach a style element to `<head>`. */
+  append(element: StyleTagElement): void;
+  /** Detach a style element. */
+  remove(element: StyleTagElement): void;
+}
+/** Options for {@link useStyleTag}. */
+interface UseStyleTagOptions {
+  /**
+   * Element `id`. Instances sharing an id share one element (last write
+   * wins, first unload removes it), so give every independent style sheet
+   * its own stable id. The default is a constant rather than a generated
+   * counter because generated ids differ between server and client.
+   *
+   * @default "vize-style"
+   */
+  readonly id?: string;
+  /**
+   * `media` attribute.
+   *
+   * @default undefined
+   */
+  readonly media?: string;
+  /**
+   * CSP nonce.
+   *
+   * @default undefined
+   */
+  readonly nonce?: string;
+  /**
+   * Attach the style element when created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document's `<head>`
+   */
+  readonly host?: MaybeRefOrGetter<StyleTagHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useStyleTag}. */
+interface StyleTagControls {
+  /** Element id in use. */
+  readonly id: string;
+  /**
+   * Style sheet text. Writable; when a getter was passed, the next getter
+   * change overwrites manual assignments.
+   */
+  readonly css: Ref<string>;
+  /** Whether the style element is attached. */
+  readonly loaded: Readonly<Ref<boolean>>;
+  /**
+   * Attach (or adopt an existing element with the same id) and apply `css`.
+   *
+   * @returns Whether a style element is attached afterwards.
+   */
+  readonly load: () => boolean;
+  /** Remove the style element. */
+  readonly unload: () => void;
+}
+/**
+ * Inject a reactive `<style>` element.
+ *
+ * The element's text follows `css`. An existing `<style>` with the same
+ * id — for example one emitted in server-rendered HTML — is adopted instead
+ * of duplicated, which keeps hydration free of flashes. The element is
+ * removed when the owning reactive scope stops or `unload` is called.
+ *
+ * Server rendering: nothing is injected and `loaded` is false. Emit the
+ * server-side `<style id>` through the application's head manager using the
+ * same id to make the client adopt it.
+ *
+ * @example
+ * ```ts
+ * const { css } = useStyleTag(() => `:root { --accent: ${accent.value} }`, { id: "theme" });
+ * ```
+ *
+ * @param css Reactive style sheet text.
+ * @param options Id, attributes, timing, and capability.
+ * @default options {}
+ * @returns Style state and actions.
+ */
+declare function useStyleTag(css: MaybeRefOrGetter<string>, options?: UseStyleTagOptions): StyleTagControls;
+//#endregion
+export { StyleTagControls, StyleTagElement, StyleTagHost, UseStyleTagOptions, useStyleTag };

package/dist/use-style-tag.mjs

@@ -0,0 +1,91 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, isRef, onMounted, readonly, ref, toValue, watch } from "vue";
+//#region src/use-style-tag.ts
+function browserStyleHost() {
+	if (typeof window === "undefined") return void 0;
+	const { document, HTMLStyleElement } = window;
+	return {
+		findStyle: (id) => {
+			const found = document.getElementById(id);
+			return found instanceof HTMLStyleElement ? found : void 0;
+		},
+		createStyle: () => document.createElement("style"),
+		append: (element) => {
+			if (element instanceof HTMLStyleElement) document.head.append(element);
+		},
+		remove: (element) => {
+			if (element instanceof HTMLStyleElement) element.remove();
+		}
+	};
+}
+/**
+* Inject a reactive `<style>` element.
+*
+* The element's text follows `css`. An existing `<style>` with the same
+* id — for example one emitted in server-rendered HTML — is adopted instead
+* of duplicated, which keeps hydration free of flashes. The element is
+* removed when the owning reactive scope stops or `unload` is called.
+*
+* Server rendering: nothing is injected and `loaded` is false. Emit the
+* server-side `<style id>` through the application's head manager using the
+* same id to make the client adopt it.
+*
+* @example
+* ```ts
+* const { css } = useStyleTag(() => `:root { --accent: ${accent.value} }`, { id: "theme" });
+* ```
+*
+* @param css Reactive style sheet text.
+* @param options Id, attributes, timing, and capability.
+* @default options {}
+* @returns Style state and actions.
+*/
+function useStyleTag(css, options = {}) {
+	const id = options.id ?? "vize-style";
+	const state = isRef(css) ? css : ref(toValue(css));
+	const loaded = ref(false);
+	let element;
+	const resolveHost = () => options.host === void 0 ? browserStyleHost() : toValue(options.host) ?? void 0;
+	if (typeof css === "function") watch(css, (next) => {
+		state.value = next;
+	});
+	const load = () => {
+		if (element) return true;
+		const host = resolveHost();
+		if (!host) return false;
+		const existing = host.findStyle(id);
+		const target = existing ?? host.createStyle();
+		if (!existing) {
+			target.setAttribute("id", id);
+			if (options.media !== void 0) target.setAttribute("media", options.media);
+			if (options.nonce !== void 0) target.setAttribute("nonce", options.nonce);
+		}
+		if (target.textContent !== state.value) target.textContent = state.value;
+		if (!existing) host.append(target);
+		element = target;
+		loaded.value = true;
+		return true;
+	};
+	const unload = () => {
+		if (element) resolveHost()?.remove(element);
+		element = void 0;
+		loaded.value = false;
+	};
+	watch(state, (next) => {
+		if (element && element.textContent !== next) element.textContent = next;
+	}, { flush: "sync" });
+	if (options.immediate ?? true) if (hasInjectionContext()) onMounted(() => {
+		load();
+	});
+	else load();
+	tryOnScopeDispose(unload);
+	return {
+		id,
+		css: state,
+		loaded: readonly(loaded),
+		load,
+		unload
+	};
+}
+//#endregion
+export { useStyleTag };

package/dist/use-supported.d.mts

@@ -0,0 +1,23 @@
+import { ComputedRef } from "vue";
+
+//#region src/use-supported.d.ts
+/**
+ * Hydration-stable feature detection.
+ *
+ * Inside a component the result is `false` until the component mounts and
+ * then reflects `check()`, so server and hydrating client render the same
+ * fallback first. Outside a component it is evaluated right away when a
+ * browser `window` exists and stays `false` otherwise. `check` may read
+ * reactive state; the result recomputes when it changes.
+ *
+ * @example
+ * ```ts
+ * const isSupported = useSupported(() => "share" in navigator);
+ * ```
+ *
+ * @param check Returns a truthy value when the feature is available.
+ * @returns Computed support flag.
+ */
+declare function useSupported(check: () => unknown): ComputedRef<boolean>;
+//#endregion
+export { useSupported };

package/dist/use-supported.mjs

@@ -0,0 +1,26 @@
+import { useMounted } from "./use-mounted.mjs";
+import { computed, hasInjectionContext, shallowRef } from "vue";
+//#region src/use-supported.ts
+/**
+* Hydration-stable feature detection.
+*
+* Inside a component the result is `false` until the component mounts and
+* then reflects `check()`, so server and hydrating client render the same
+* fallback first. Outside a component it is evaluated right away when a
+* browser `window` exists and stays `false` otherwise. `check` may read
+* reactive state; the result recomputes when it changes.
+*
+* @example
+* ```ts
+* const isSupported = useSupported(() => "share" in navigator);
+* ```
+*
+* @param check Returns a truthy value when the feature is available.
+* @returns Computed support flag.
+*/
+function useSupported(check) {
+	const ready = hasInjectionContext() ? useMounted() : shallowRef(typeof window !== "undefined");
+	return computed(() => ready.value && Boolean(check()));
+}
+//#endregion
+export { useSupported };

package/dist/use-throttled.d.mts

@@ -1,4 +1,4 @@
-import { TimeoutScheduler } from "./timeout-scheduler.mjs";
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
 import { MaybeRefOrGetter, ShallowRef } from "vue";
 
 //#region src/use-throttled.d.ts

package/dist/use-time-ago.d.mts

@@ -0,0 +1,163 @@
+import { n as IntervalScheduler, r as PausableControls } from "./use-interval-BA55gTHT.mjs";
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-time-ago.d.ts
+/** Calendar units {@link formatTimeAgo} can express a distance in. */
+type TimeAgoUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/** Date input accepted by the time formatting helpers. */
+type TimeAgoInput = Date | number | string;
+/** Options for {@link formatTimeAgo}. */
+interface FormatTimeAgoOptions {
+  /**
+   * BCP 47 locale(s) for `Intl.RelativeTimeFormat`. Defaults to a fixed
+   * locale (not the host default) so server and client output agree.
+   *
+   * @default "en"
+   */
+  readonly locale?: string | readonly string[];
+  /**
+   * `"auto"` allows phrases such as "yesterday" and "now"; `"always"` keeps
+   * numeric output such as "1 day ago".
+   *
+   * @default "auto"
+   */
+  readonly numeric?: "always" | "auto";
+  /**
+   * Length of the unit wording.
+   *
+   * @default "long"
+   */
+  readonly style?: "long" | "short" | "narrow";
+  /**
+   * Units allowed in the output, in any order. The largest allowed unit
+   * that fits the distance wins; smaller distances use the smallest unit.
+   *
+   * @default all units from second to year
+   */
+  readonly units?: readonly TimeAgoUnit[];
+  /**
+   * How a fractional unit count becomes an integer.
+   *
+   * @default "round"
+   */
+  readonly rounding?: "round" | "floor" | "ceil";
+  /**
+   * Distances below this many milliseconds are reported as zero of the
+   * smallest unit ("now" with `numeric: "auto"`).
+   *
+   * @default 0
+   */
+  readonly justNowMs?: number;
+  /**
+   * Distances of at least this many milliseconds are delegated to
+   * {@link FormatTimeAgoOptions.fullDateFormatter}.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly maxMs?: number;
+  /**
+   * Formats dates beyond {@link FormatTimeAgoOptions.maxMs}.
+   *
+   * @default medium date style in UTC for the configured locale
+   */
+  readonly fullDateFormatter?: (date: Date) => string;
+}
+/** Options for {@link useTimeAgo}. */
+interface UseTimeAgoOptions<Controls extends boolean = false> extends Omit<FormatTimeAgoOptions, "locale"> {
+  /**
+   * Reactive BCP 47 locale(s). Pair with `useLocale()` to follow the user.
+   *
+   * @default "en"
+   */
+  readonly locale?: MaybeRefOrGetter<string | readonly string[]>;
+  /**
+   * How often the relative phrase is recomputed, in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly updateIntervalMs?: MaybeRefOrGetter<number>;
+  /**
+   * Clock source returning Unix epoch milliseconds.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+  /**
+   * Hydration-stable "now" used for the first render on server and client.
+   *
+   * @default undefined (read the clock immediately)
+   */
+  readonly initialNow?: number;
+  /**
+   * Starts host timers when no browser `window` is available.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Repeating timer host.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: IntervalScheduler;
+  /**
+   * Return the full control object instead of the bare phrase ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+}
+/** Phrase and controls returned by `useTimeAgo(time, { controls: true })`. */
+interface TimeAgoControls extends PausableControls {
+  /** Localized relative phrase such as "3 minutes ago". */
+  readonly timeAgo: ComputedRef<string>;
+  /** The reference "now" in Unix epoch milliseconds. */
+  readonly now: Readonly<ShallowRef<number>>;
+}
+/**
+ * Format the distance between two instants as a localized relative phrase.
+ *
+ * Pure and deterministic: the output depends only on the arguments (the
+ * locale defaults to `"en"`, never the host default), which makes it safe
+ * for server rendering and hydration.
+ *
+ * @example
+ * ```ts
+ * formatTimeAgo(Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2)); // "yesterday"
+ * formatTimeAgo(0, 90_000, { numeric: "always" }); // "2 minutes ago"
+ * ```
+ *
+ * @param time Instant being described.
+ * @param now Reference instant.
+ * @param options Locale, wording, unit, and threshold policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIME_AGO_INVALID_DATE` when
+ * either input is not a valid date, and `RangeError` from `Intl` for invalid
+ * locales.
+ * @returns The localized phrase.
+ */
+declare function formatTimeAgo(time: TimeAgoInput, now: TimeAgoInput, options?: FormatTimeAgoOptions): string;
+/**
+ * Reactive localized "time ago" phrase that refreshes on an interval.
+ *
+ * Combines {@link formatTimeAgo} with a pausable clock. For SSR, inject
+ * `initialNow` (the server render time) and a fixed `locale`: both sides
+ * then produce the same phrase and the client clock takes over on its first
+ * tick. No timer runs on the server; the timer stops with the owning scope.
+ *
+ * @example
+ * ```ts
+ * const phrase = useTimeAgo(() => post.value.createdAt, { locale: useLocale().locale });
+ * ```
+ *
+ * @param time Reactive instant being described.
+ * @param options Formatting, cadence, clock, and SSR policy.
+ * @default options {}
+ * @throws `RangeError` on read for invalid dates or locales, and for invalid
+ * update intervals at creation.
+ * @returns The phrase ref, or the full controls when `controls` is `true`.
+ */
+declare function useTimeAgo(time: MaybeRefOrGetter<TimeAgoInput>, options?: UseTimeAgoOptions<false>): ComputedRef<string>;
+declare function useTimeAgo(time: MaybeRefOrGetter<TimeAgoInput>, options: UseTimeAgoOptions<true>): TimeAgoControls;
+//#endregion
+export { FormatTimeAgoOptions, TimeAgoControls, TimeAgoInput, TimeAgoUnit, UseTimeAgoOptions, formatTimeAgo, useTimeAgo };

package/dist/use-time-ago.mjs

@@ -0,0 +1,95 @@
+import { useTimestamp } from "./use-now.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-time-ago.ts
+const unitMs = {
+	second: 1e3,
+	minute: 6e4,
+	hour: 36e5,
+	day: 864e5,
+	week: 6048e5,
+	month: 2592e6,
+	year: 31536e6
+};
+const allUnits = [
+	"second",
+	"minute",
+	"hour",
+	"day",
+	"week",
+	"month",
+	"year"
+];
+function toEpochMs(input) {
+	const value = input instanceof Date ? input.getTime() : new Date(input).getTime();
+	if (Number.isNaN(value)) throw new RangeError(`[VIZE_COMPOSE_TIME_AGO_INVALID_DATE] expected a valid date; received ${String(input)}`);
+	return value;
+}
+/**
+* Format the distance between two instants as a localized relative phrase.
+*
+* Pure and deterministic: the output depends only on the arguments (the
+* locale defaults to `"en"`, never the host default), which makes it safe
+* for server rendering and hydration.
+*
+* @example
+* ```ts
+* formatTimeAgo(Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2)); // "yesterday"
+* formatTimeAgo(0, 90_000, { numeric: "always" }); // "2 minutes ago"
+* ```
+*
+* @param time Instant being described.
+* @param now Reference instant.
+* @param options Locale, wording, unit, and threshold policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_TIME_AGO_INVALID_DATE` when
+* either input is not a valid date, and `RangeError` from `Intl` for invalid
+* locales.
+* @returns The localized phrase.
+*/
+function formatTimeAgo(time, now, options = {}) {
+	const target = toEpochMs(time);
+	const diff = target - toEpochMs(now);
+	const distance = Math.abs(diff);
+	const locales = typeof options.locale === "string" ? options.locale : [...options.locale ?? ["en"]];
+	if (distance >= (options.maxMs ?? Number.POSITIVE_INFINITY)) {
+		const date = new Date(target);
+		return options.fullDateFormatter === void 0 ? new Intl.DateTimeFormat(locales, {
+			dateStyle: "medium",
+			timeZone: "UTC"
+		}).format(date) : options.fullDateFormatter(date);
+	}
+	const allowed = allUnits.filter((unit) => (options.units ?? allUnits).includes(unit));
+	const smallest = allowed[0] ?? "second";
+	let unit = smallest;
+	for (const candidate of allowed) if (distance >= unitMs[candidate]) unit = candidate;
+	const round = Math[options.rounding ?? "round"];
+	const magnitude = distance < (options.justNowMs ?? 0) ? 0 : round(distance / unitMs[unit]);
+	return new Intl.RelativeTimeFormat(locales, {
+		numeric: options.numeric ?? "auto",
+		style: options.style ?? "long"
+	}).format(diff <= 0 ? -magnitude : magnitude, magnitude === 0 ? smallest : unit);
+}
+function useTimeAgo(time, options = {}) {
+	const { timestamp, pause, resume, isActive } = useTimestamp({
+		interval: options.updateIntervalMs ?? 3e4,
+		controls: true,
+		runOnServer: options.runOnServer ?? false,
+		...options.now === void 0 ? {} : { now: options.now },
+		...options.initialNow === void 0 ? {} : { initial: options.initialNow },
+		...options.scheduler === void 0 ? {} : { scheduler: options.scheduler }
+	});
+	const timeAgo = computed(() => formatTimeAgo(toValue(time), timestamp.value, {
+		...options,
+		locale: toValue(options.locale) ?? "en"
+	}));
+	if (options.controls !== true) return timeAgo;
+	return {
+		timeAgo,
+		now: timestamp,
+		pause,
+		resume,
+		isActive
+	};
+}
+//#endregion
+export { formatTimeAgo, useTimeAgo };

package/dist/use-timeout.d.mts

@@ -0,0 +1,122 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-timeout.d.ts
+/** Options for {@link useTimeoutFn}. */
+interface UseTimeoutFnOptions {
+  /**
+   * Start the timer as soon as the composable is created. Only available
+   * for callbacks without arguments; pass `false` to schedule a callback
+   * that takes arguments through {@link TimeoutFnControls.start}.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Starts host timers when no browser `window` is available.
+   *
+   * Keep this disabled during server rendering: `isPending` then reports the
+   * requested state but no timer is created and the callback never runs.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the single-shot timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Controls returned by {@link useTimeoutFn}. */
+interface TimeoutFnControls<Args extends readonly unknown[]> {
+  /** Whether a call is scheduled and has not fired or been stopped yet. */
+  readonly isPending: Readonly<ShallowRef<boolean>>;
+  /**
+   * (Re)start the timer. A pending call is replaced, and the callback later
+   * receives exactly these arguments.
+   */
+  readonly start: (...args: Args) => void;
+  /**
+   * Cancel the pending call.
+   *
+   * @returns Whether a pending call was cancelled.
+   */
+  readonly stop: () => boolean;
+}
+/** Options for {@link useTimeout}. */
+interface UseTimeoutOptions<Controls extends boolean = false> extends UseTimeoutFnOptions {
+  /**
+   * Return the full control object instead of the bare readiness ref.
+   *
+   * @default false
+   */
+  readonly controls?: Controls;
+  /**
+   * Invoked when the timeout elapses.
+   *
+   * @default undefined
+   */
+  readonly callback?: () => void;
+}
+/** Readiness and controls returned by `useTimeout(ms, { controls: true })`. */
+interface TimeoutControls extends TimeoutFnControls<[]> {
+  /** `true` once the timer elapsed or was stopped, `false` while pending. */
+  readonly ready: ComputedRef<boolean>;
+}
+/**
+ * Call a function once after a delay, with restart and cancel controls.
+ *
+ * The typing is arity-aware: a zero-argument callback may start
+ * immediately, while a callback with parameters requires
+ * `{ immediate: false }` so it can only ever run with arguments supplied to
+ * `start(...)`. `delayMs` is reactive and read on every `start`.
+ *
+ * Server rendering is hydration-stable: without a browser `window` (and with
+ * {@link UseTimeoutFnOptions.runOnServer} disabled) `isPending` reports the
+ * requested state but no timer is created. A pending timer is cleared when
+ * the owning reactive scope stops.
+ *
+ * @example
+ * ```ts
+ * const { start, stop } = useTimeoutFn((id: string) => save(id), 500, { immediate: false });
+ * start("draft-1");
+ * ```
+ *
+ * @param callback Invoked once the delay elapses.
+ * @param delayMs Reactive delay in milliseconds; finite and at least zero.
+ * @param options Start, server, and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIMEOUT_INVALID_DELAY` for invalid
+ * delays, synchronously at creation and on every `start`.
+ * @returns Pending flag and start/stop controls.
+ */
+declare function useTimeoutFn(callback: () => void, delayMs: MaybeRefOrGetter<number>, options?: UseTimeoutFnOptions): TimeoutFnControls<[]>;
+declare function useTimeoutFn<Args extends readonly unknown[]>(callback: (...args: Args) => void, delayMs: MaybeRefOrGetter<number>, options: UseTimeoutFnOptions & {
+  readonly immediate: false;
+}): TimeoutFnControls<Args>;
+/**
+ * Reactive "has the delay elapsed yet?" flag.
+ *
+ * A wrapper over {@link useTimeoutFn}. Pass `{ controls: true }` to receive
+ * start/stop alongside the flag; the return type follows the literal flag.
+ * Stopping a pending timer marks it ready.
+ *
+ * @example
+ * ```ts
+ * const ready = useTimeout(300); // ComputedRef<boolean>
+ * const { ready: done, start } = useTimeout(300, { controls: true, immediate: false });
+ * ```
+ *
+ * @param delayMs Reactive delay in milliseconds.
+ * @param options Timeout options plus the `controls` flag.
+ * @default delayMs 1000
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_TIMEOUT_INVALID_DELAY` for invalid
+ * delays (see {@link useTimeoutFn}).
+ * @returns The readiness ref, or the full controls when `controls` is `true`.
+ */
+declare function useTimeout(delayMs?: MaybeRefOrGetter<number>, options?: UseTimeoutOptions<false>): ComputedRef<boolean>;
+declare function useTimeout(delayMs: MaybeRefOrGetter<number>, options: UseTimeoutOptions<true>): TimeoutControls;
+//#endregion
+export { TimeoutControls, TimeoutFnControls, UseTimeoutFnOptions, UseTimeoutOptions, useTimeout, useTimeoutFn };