@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-queue.d.mts

@@ -0,0 +1,89 @@
+import { ComputedRef } from "vue";
+
+//#region src/use-queue.d.ts
+/** What happens when an item arrives while a bounded queue is full. */
+type QueueOverflowPolicy = "drop-oldest" | "reject";
+/** Options for {@link useQueue}. */
+interface UseQueueOptions {
+  /**
+   * Maximum number of queued items. A positive integer, or
+   * `Number.POSITIVE_INFINITY` for an unbounded queue.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly capacity?: number;
+  /**
+   * Policy applied when an item arrives at capacity: `"drop-oldest"` evicts
+   * the head to make room, `"reject"` refuses the new item.
+   *
+   * @default "drop-oldest"
+   */
+  readonly overflow?: QueueOverflowPolicy;
+}
+/** Reactive first-in, first-out queue returned by {@link useQueue}. */
+interface QueueControls<Item> {
+  /** Snapshot of the queued items, head first. Recomputed after every change. */
+  readonly items: ComputedRef<readonly Item[]>;
+  /** Number of queued items. */
+  readonly size: ComputedRef<number>;
+  /** Whether the queue holds no items. */
+  readonly isEmpty: ComputedRef<boolean>;
+  /**
+   * Read the head without removing it. Reactive when read inside an effect.
+   *
+   * @returns The head item, or `undefined` when empty.
+   */
+  readonly peek: () => Item | undefined;
+  /**
+   * Append items at the tail in argument order, applying the overflow policy.
+   *
+   * @param items Items to append.
+   * @returns How many of the given items were accepted.
+   */
+  readonly enqueue: (...items: Item[]) => number;
+  /**
+   * Remove and return the head.
+   *
+   * @returns The removed item, or `undefined` when empty.
+   */
+  readonly dequeue: () => Item | undefined;
+  /**
+   * Remove and return every queued item, head first.
+   *
+   * @returns The removed items.
+   */
+  readonly drain: () => Item[];
+  /** Remove every item. */
+  readonly clear: () => void;
+}
+/**
+ * Create a typed reactive FIFO queue.
+ *
+ * Dequeueing is amortized O(1): the head advances through a backing buffer
+ * that is compacted only after enough slots have been consumed, so large
+ * queues never pay for `Array.prototype.shift`. Reactivity is driven by a
+ * single version counter; `items`, `size`, `isEmpty`, and `peek` all
+ * re-evaluate after each mutation.
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const jobs = useQueue<string>([], { capacity: 100, overflow: "reject" });
+ * jobs.enqueue("a", "b");
+ * jobs.dequeue(); // "a"
+ * ```
+ *
+ * @typeParam Item Queued item type, inferred from `initial` when given.
+ * @param initial Items enqueued at creation, head first (overflow applies).
+ * @param options Capacity and overflow policy.
+ * @default initial []
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_QUEUE_INVALID_CAPACITY]` when `capacity`
+ * is not a positive integer or `Infinity`.
+ * @returns The reactive queue and its controls.
+ */
+declare function useQueue<Item>(initial?: Iterable<Item>, options?: UseQueueOptions): QueueControls<Item>;
+//#endregion
+export { QueueControls, QueueOverflowPolicy, UseQueueOptions, useQueue };

package/dist/use-queue.mjs

@@ -0,0 +1,116 @@
+import { computed, shallowRef } from "vue";
+//#region src/use-queue.ts
+/** Compact the backing buffer once this many dequeued slots accumulate. */
+const COMPACT_THRESHOLD = 32;
+function validateCapacity(capacity) {
+	if (capacity === Number.POSITIVE_INFINITY) return capacity;
+	if (!Number.isSafeInteger(capacity) || capacity < 1) throw new RangeError(`[VIZE_COMPOSE_QUEUE_INVALID_CAPACITY] capacity must be a positive integer or Infinity; received ${String(capacity)}`);
+	return capacity;
+}
+/**
+* Create a typed reactive FIFO queue.
+*
+* Dequeueing is amortized O(1): the head advances through a backing buffer
+* that is compacted only after enough slots have been consumed, so large
+* queues never pay for `Array.prototype.shift`. Reactivity is driven by a
+* single version counter; `items`, `size`, `isEmpty`, and `peek` all
+* re-evaluate after each mutation.
+*
+* Purely synchronous state: safe during server rendering (no host globals,
+* no timers) and nothing to dispose.
+*
+* @example
+* ```ts
+* const jobs = useQueue<string>([], { capacity: 100, overflow: "reject" });
+* jobs.enqueue("a", "b");
+* jobs.dequeue(); // "a"
+* ```
+*
+* @typeParam Item Queued item type, inferred from `initial` when given.
+* @param initial Items enqueued at creation, head first (overflow applies).
+* @param options Capacity and overflow policy.
+* @default initial []
+* @default options {}
+* @throws {RangeError} `[VIZE_COMPOSE_QUEUE_INVALID_CAPACITY]` when `capacity`
+* is not a positive integer or `Infinity`.
+* @returns The reactive queue and its controls.
+*/
+function useQueue(initial = [], options = {}) {
+	const capacity = validateCapacity(options.capacity ?? Number.POSITIVE_INFINITY);
+	const overflow = options.overflow ?? "drop-oldest";
+	let buffer = [];
+	let head = 0;
+	const version = shallowRef(0);
+	const touch = () => {
+		version.value += 1;
+	};
+	const length = () => buffer.length - head;
+	const compact = () => {
+		if (head >= COMPACT_THRESHOLD && head * 2 >= buffer.length) {
+			buffer = buffer.slice(head);
+			head = 0;
+		}
+	};
+	const append = (items) => {
+		let accepted = 0;
+		for (const item of items) {
+			if (length() >= capacity) {
+				if (overflow === "reject") continue;
+				head += 1;
+			}
+			buffer.push(item);
+			accepted += 1;
+		}
+		compact();
+		return accepted;
+	};
+	append([...initial]);
+	const items = computed(() => {
+		version.value;
+		return buffer.slice(head);
+	});
+	const size = computed(() => {
+		version.value;
+		return length();
+	});
+	return {
+		items,
+		size,
+		isEmpty: computed(() => size.value === 0),
+		peek: () => {
+			version.value;
+			return length() > 0 ? buffer[head] : void 0;
+		},
+		enqueue: (...added) => {
+			const accepted = append(added);
+			if (accepted > 0) touch();
+			return accepted;
+		},
+		dequeue: () => {
+			if (length() === 0) return void 0;
+			const item = buffer[head];
+			head += 1;
+			if (head === buffer.length) {
+				buffer = [];
+				head = 0;
+			} else compact();
+			touch();
+			return item;
+		},
+		drain: () => {
+			const drained = buffer.slice(head);
+			buffer = [];
+			head = 0;
+			if (drained.length > 0) touch();
+			return drained;
+		},
+		clear: () => {
+			if (length() === 0) return;
+			buffer = [];
+			head = 0;
+			touch();
+		}
+	};
+}
+//#endregion
+export { useQueue };

package/dist/use-raf-fn.d.mts

@@ -0,0 +1,87 @@
+import { r as PausableControls } from "./use-interval-BA55gTHT.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/use-raf-fn.d.ts
+/**
+ * Animation-frame host used by {@link useRafFn}.
+ *
+ * Implement this interface to drive frames from a deterministic test clock,
+ * a native display link, or an offscreen renderer.
+ */
+interface FrameScheduler {
+  /** Requests one frame callback and returns its opaque cancellation handle. */
+  readonly requestAnimationFrame: (callback: (timestamp: number) => void) => unknown;
+  /** Cancels a handle previously returned by {@link FrameScheduler.requestAnimationFrame}. */
+  readonly cancelAnimationFrame: (handle: unknown) => void;
+}
+/** Timing information passed to every {@link useRafFn} callback. */
+interface RafFrame {
+  /** Milliseconds since the previous delivered frame (`0` for the first). */
+  readonly delta: number;
+  /** High-resolution frame timestamp supplied by the host. */
+  readonly timestamp: number;
+}
+/** Options for {@link useRafFn}. */
+interface UseRafFnOptions {
+  /**
+   * Start the frame loop as soon as the composable is created.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Maximum callback rate in frames per second. Frames arriving sooner than
+   * `1000 / fpsLimit` ms after the last delivered frame are skipped.
+   * `undefined` delivers every frame. Reactive.
+   *
+   * @default undefined
+   */
+  readonly fpsLimit?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * Deliver a single frame and then pause.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+  /**
+   * Requests frames when no browser `window` is available, for example from
+   * a native or offscreen frame host passed as `scheduler`.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Frame host. When omitted, `globalThis.requestAnimationFrame` is used if
+   * it exists; without one (server rendering, workers without frames) the
+   * loop only tracks its requested state.
+   *
+   * @default globalThis animation-frame functions when available
+   */
+  readonly scheduler?: FrameScheduler;
+}
+/**
+ * Run a callback on every animation frame, with pause/resume controls and an
+ * optional frame-rate cap.
+ *
+ * The host is resolved lazily on `resume()`, so importing and calling this
+ * during server rendering is safe: without a browser `window` (and without
+ * {@link UseRafFnOptions.runOnServer}), or without any frame host,
+ * `isActive` reports the requested state and no callbacks run, matching the
+ * client's initial render. The pending frame is cancelled when the owning reactive scope
+ * stops.
+ *
+ * @example
+ * ```ts
+ * const { pause } = useRafFn(({ delta }) => step(delta), { fpsLimit: 30 });
+ * ```
+ *
+ * @param callback Invoked with frame timing for every delivered frame.
+ * @param options Start, rate-limit, and host policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT` when a
+ * resolved `fpsLimit` is not finite and greater than zero.
+ * @returns Pause/resume controls.
+ */
+declare function useRafFn(callback: (frame: RafFrame) => void, options?: UseRafFnOptions): PausableControls;
+//#endregion
+export { FrameScheduler, RafFrame, UseRafFnOptions, useRafFn };

package/dist/use-raf-fn.mjs

@@ -0,0 +1,99 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { shallowRef, toValue } from "vue";
+//#region src/use-raf-fn.ts
+function resolveHost(scheduler) {
+	if (scheduler !== void 0) return scheduler;
+	if (typeof globalThis.requestAnimationFrame !== "function") return void 0;
+	return {
+		requestAnimationFrame: (callback) => globalThis.requestAnimationFrame(callback),
+		cancelAnimationFrame: (handle) => {
+			globalThis.cancelAnimationFrame(handle);
+		}
+	};
+}
+/**
+* Run a callback on every animation frame, with pause/resume controls and an
+* optional frame-rate cap.
+*
+* The host is resolved lazily on `resume()`, so importing and calling this
+* during server rendering is safe: without a browser `window` (and without
+* {@link UseRafFnOptions.runOnServer}), or without any frame host,
+* `isActive` reports the requested state and no callbacks run, matching the
+* client's initial render. The pending frame is cancelled when the owning reactive scope
+* stops.
+*
+* @example
+* ```ts
+* const { pause } = useRafFn(({ delta }) => step(delta), { fpsLimit: 30 });
+* ```
+*
+* @param callback Invoked with frame timing for every delivered frame.
+* @param options Start, rate-limit, and host policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT` when a
+* resolved `fpsLimit` is not finite and greater than zero.
+* @returns Pause/resume controls.
+*/
+function useRafFn(callback, options = {}) {
+	const isActive = shallowRef(false);
+	let host;
+	let handle;
+	let requested = false;
+	let previous;
+	const readInterval = () => {
+		const limit = toValue(options.fpsLimit);
+		if (limit === void 0) return 0;
+		if (!Number.isFinite(limit) || limit <= 0) throw new RangeError(`[VIZE_COMPOSE_RAF_INVALID_FPS_LIMIT] fpsLimit must be finite and greater than zero; received ${String(limit)}`);
+		return 1e3 / limit;
+	};
+	readInterval();
+	const request = () => {
+		if (host === void 0) return;
+		requested = true;
+		handle = host.requestAnimationFrame(loop);
+	};
+	function loop(timestamp) {
+		requested = false;
+		if (!isActive.value) return;
+		previous ??= timestamp;
+		const delta = timestamp - previous;
+		const interval = readInterval();
+		if (interval > 0 && delta > 0 && delta < interval) {
+			request();
+			return;
+		}
+		previous = timestamp;
+		callback({
+			delta,
+			timestamp
+		});
+		if (options.once ?? false) {
+			pause();
+			return;
+		}
+		request();
+	}
+	const pause = () => {
+		isActive.value = false;
+		if (requested && host !== void 0) host.cancelAnimationFrame(handle);
+		requested = false;
+		handle = void 0;
+	};
+	const resume = () => {
+		if (isActive.value) return;
+		isActive.value = true;
+		previous = void 0;
+		if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+		host ??= resolveHost(options.scheduler);
+		request();
+	};
+	if (options.immediate ?? true) resume();
+	tryOnScopeDispose(pause);
+	return {
+		isActive,
+		pause,
+		resume
+	};
+}
+//#endregion
+export { useRafFn };

package/dist/use-relative-time-format.d.mts

@@ -0,0 +1,111 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-relative-time-format.d.ts
+/** Units selected by {@link selectRelativeTimeUnit}. */
+type RelativeTimeUnitSelection = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+/** A signed amount in one relative-time unit. */
+interface RelativeTimeValue {
+  /** Signed, rounded amount; negative values are in the past. */
+  readonly value: number;
+  /** Unit the amount is expressed in. */
+  readonly unit: RelativeTimeUnitSelection;
+}
+/** Options for {@link useRelativeTimeFormat}. */
+interface UseRelativeTimeFormatOptions extends Intl.RelativeTimeFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly for hydration-stable
+   * server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+/** Options for {@link RelativeTimeFormatControls.formatFrom}. */
+interface RelativeTimeFromOptions {
+  /**
+   * Reference time in Unix milliseconds. Pass it explicitly to keep server
+   * and client output identical.
+   *
+   * @default Date.now()
+   */
+  readonly now?: number;
+}
+/** Reactive relative-time formatting returned by {@link useRelativeTimeFormat}. */
+interface RelativeTimeFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.RelativeTimeFormat>;
+  /** Formatted `value` in `unit`, or `""` while either is missing. */
+  readonly formatted: ComputedRef<string>;
+  /**
+   * Format an amount in a unit.
+   *
+   * @param value Signed amount; negative is in the past.
+   * @param unit Relative-time unit.
+   * @returns The formatted string.
+   */
+  readonly format: (value: number, unit: Intl.RelativeTimeFormatUnit) => string;
+  /**
+   * Format an amount in a unit into parts.
+   *
+   * @param value Signed amount.
+   * @param unit Relative-time unit.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (value: number, unit: Intl.RelativeTimeFormatUnit) => Intl.RelativeTimeFormatPart[];
+  /**
+   * Format a signed millisecond difference using the best-fitting unit
+   * (see {@link selectRelativeTimeUnit}).
+   *
+   * @param diffMs Signed difference; negative is in the past.
+   * @returns The formatted string.
+   */
+  readonly formatDiff: (diffMs: number) => string;
+  /**
+   * Format a date relative to a reference time using the best-fitting unit.
+   *
+   * @param date Date or Unix milliseconds.
+   * @param options Reference time.
+   * @default options {}
+   * @returns The formatted string.
+   */
+  readonly formatFrom: (date: Date | number, options?: RelativeTimeFromOptions) => string;
+}
+/**
+ * Pick the largest unit that expresses a millisecond difference as a
+ * non-zero rounded amount: seconds below a minute, minutes below an hour,
+ * hours below a day, days below a week, weeks below a month, months below
+ * a year, and years otherwise (Gregorian average month/year lengths).
+ *
+ * @param diffMs Signed difference; negative is in the past.
+ * @returns The rounded amount and its unit.
+ * @throws {RangeError} `[VIZE_COMPOSE_RELATIVE_TIME_INVALID_DIFF]` for a
+ * non-finite difference.
+ */
+declare function selectRelativeTimeUnit(diffMs: number): RelativeTimeValue;
+/**
+ * Format relative times ("in 3 days", "yesterday") with `Intl.RelativeTimeFormat`.
+ *
+ * A pure formatting wrapper: it owns no clock or timer, so it never
+ * re-renders on its own and stays deterministic during server rendering
+ * (pair it with a clock composable for live "time ago" labels). The
+ * formatter follows the reactive options and is cached per locale and
+ * option set through {@link useLocale}; invalid options surface as the
+ * platform's `RangeError`.
+ *
+ * @example
+ * ```ts
+ * const { formatted } = useRelativeTimeFormat(-1, "day", { locale: "en", numeric: "auto" });
+ * formatted.value; // "yesterday"
+ * ```
+ *
+ * @param value Reactive signed amount; `null`/`undefined` format as `""`.
+ * @param unit Reactive unit.
+ * @param options Reactive locale and `Intl.RelativeTimeFormat` options.
+ * @default options {}
+ * @returns Reactive formatted output and formatting helpers.
+ */
+declare function useRelativeTimeFormat(value: MaybeRefOrGetter<number | null | undefined>, unit: MaybeRefOrGetter<Intl.RelativeTimeFormatUnit>, options?: MaybeRefOrGetter<UseRelativeTimeFormatOptions>): RelativeTimeFormatControls;
+//#endregion
+export { RelativeTimeFormatControls, RelativeTimeFromOptions, RelativeTimeUnitSelection, RelativeTimeValue, UseRelativeTimeFormatOptions, selectRelativeTimeUnit, useRelativeTimeFormat };

package/dist/use-relative-time-format.mjs

@@ -0,0 +1,119 @@
+import { useLocale } from "./locale.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-relative-time-format.ts
+const SECOND = 1e3;
+const MINUTE = 6e4;
+const HOUR = 36e5;
+const DAY = 864e5;
+const WEEK = 6048e5;
+/** Gregorian average month: 30.436875 days. */
+const MONTH = 2629746e3;
+/** Gregorian average year: 365.2425 days. */
+const YEAR = 31556952e3;
+const thresholds = [
+	[
+		MINUTE,
+		SECOND,
+		"second"
+	],
+	[
+		HOUR,
+		MINUTE,
+		"minute"
+	],
+	[
+		DAY,
+		HOUR,
+		"hour"
+	],
+	[
+		WEEK,
+		DAY,
+		"day"
+	],
+	[
+		MONTH,
+		WEEK,
+		"week"
+	],
+	[
+		YEAR,
+		MONTH,
+		"month"
+	]
+];
+/**
+* Pick the largest unit that expresses a millisecond difference as a
+* non-zero rounded amount: seconds below a minute, minutes below an hour,
+* hours below a day, days below a week, weeks below a month, months below
+* a year, and years otherwise (Gregorian average month/year lengths).
+*
+* @param diffMs Signed difference; negative is in the past.
+* @returns The rounded amount and its unit.
+* @throws {RangeError} `[VIZE_COMPOSE_RELATIVE_TIME_INVALID_DIFF]` for a
+* non-finite difference.
+*/
+function selectRelativeTimeUnit(diffMs) {
+	if (!Number.isFinite(diffMs)) throw new RangeError(`[VIZE_COMPOSE_RELATIVE_TIME_INVALID_DIFF] the difference must be finite; received ${String(diffMs)}`);
+	const magnitude = Math.abs(diffMs);
+	for (const [limit, size, unit] of thresholds) if (magnitude < limit) return {
+		value: Math.round(diffMs / size) + 0,
+		unit
+	};
+	return {
+		value: Math.round(diffMs / YEAR) + 0,
+		unit: "year"
+	};
+}
+function browserLanguage() {
+	return typeof window === "undefined" ? void 0 : window.navigator.language;
+}
+/**
+* Format relative times ("in 3 days", "yesterday") with `Intl.RelativeTimeFormat`.
+*
+* A pure formatting wrapper: it owns no clock or timer, so it never
+* re-renders on its own and stays deterministic during server rendering
+* (pair it with a clock composable for live "time ago" labels). The
+* formatter follows the reactive options and is cached per locale and
+* option set through {@link useLocale}; invalid options surface as the
+* platform's `RangeError`.
+*
+* @example
+* ```ts
+* const { formatted } = useRelativeTimeFormat(-1, "day", { locale: "en", numeric: "auto" });
+* formatted.value; // "yesterday"
+* ```
+*
+* @param value Reactive signed amount; `null`/`undefined` format as `""`.
+* @param unit Reactive unit.
+* @param options Reactive locale and `Intl.RelativeTimeFormat` options.
+* @default options {}
+* @returns Reactive formatted output and formatting helpers.
+*/
+function useRelativeTimeFormat(value, unit, options = {}) {
+	const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+	const formatter = computed(() => {
+		const { locale: _locale, ...formatOptions } = toValue(options);
+		return localeControls.relativeTime(formatOptions);
+	});
+	const formatDiff = (diffMs) => {
+		const selected = selectRelativeTimeUnit(diffMs);
+		return formatter.value.format(selected.value, selected.unit);
+	};
+	return {
+		locale: localeControls.locale,
+		formatter,
+		formatted: computed(() => {
+			const current = toValue(value);
+			return current === null || current === void 0 ? "" : formatter.value.format(current, toValue(unit));
+		}),
+		format: (amount, amountUnit) => formatter.value.format(amount, amountUnit),
+		formatToParts: (amount, amountUnit) => formatter.value.formatToParts(amount, amountUnit),
+		formatDiff,
+		formatFrom: (date, fromOptions = {}) => {
+			return formatDiff((date instanceof Date ? date.getTime() : date) - (fromOptions.now ?? Date.now()));
+		}
+	};
+}
+//#endregion
+export { selectRelativeTimeUnit, useRelativeTimeFormat };