@vizejs/composable 0.426.2 → 0.427.0

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

@@ -0,0 +1,53 @@
+import { useLocale } from "./locale.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-date-time-format.ts
+function browserLanguage() {
+	return typeof window === "undefined" ? void 0 : window.navigator.language;
+}
+function isValidDate(value) {
+	return !Number.isNaN(value instanceof Date ? value.getTime() : value);
+}
+/**
+* Format dates and times reactively with `Intl.DateTimeFormat`.
+*
+* The formatter follows the reactive options (including `locale`) and is
+* cached per locale and option set through {@link useLocale}. For
+* hydration-stable output pass both `locale` and `timeZone`: otherwise the
+* server uses `"en"` and its own zone. Invalid options surface as the
+* platform's `RangeError` on first read; invalid dates render as `""`.
+* No listeners or timers are created — combine with a clock composable for
+* live-updating output.
+*
+* @example
+* ```ts
+* const { formatted } = useDateTimeFormat(date, { locale: "en-GB", dateStyle: "long", timeZone: "UTC" });
+* ```
+*
+* @param value Reactive date; `null`/`undefined` format as `""`.
+* @param options Reactive locale and `Intl.DateTimeFormat` options.
+* @default value undefined
+* @default options {}
+* @returns Reactive formatted output and formatter helpers.
+*/
+function useDateTimeFormat(value, options = {}) {
+	const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+	const formatter = computed(() => {
+		const { locale: _locale, ...formatOptions } = toValue(options);
+		return localeControls.dateTime(formatOptions);
+	});
+	const formatted = computed(() => {
+		const current = value === void 0 ? void 0 : toValue(value);
+		if (current === null || current === void 0 || !isValidDate(current)) return "";
+		return formatter.value.format(current);
+	});
+	return {
+		locale: localeControls.locale,
+		formatter,
+		formatted,
+		format: (input) => formatter.value.format(input),
+		formatToParts: (input) => formatter.value.formatToParts(input),
+		formatRange: (start, end) => formatter.value.formatRange(start, end)
+	};
+}
+//#endregion
+export { useDateTimeFormat };

package/dist/use-debounced.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-debounced.d.ts

package/dist/use-display-media.d.mts

@@ -0,0 +1,62 @@
+import { MediaStreamControls, MediaStreamLike } from "./use-user-media.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/use-display-media.d.ts
+/** Minimal `MediaDevices` consumed by {@link useDisplayMedia}. */
+interface DisplayMediaHost {
+  /** Ask the user to pick a screen, window, or tab to capture. */
+  getDisplayMedia(options?: DisplayMediaStreamOptions): Promise<MediaStreamLike>;
+}
+/** Options for {@link useDisplayMedia}. */
+interface UseDisplayMediaOptions {
+  /**
+   * Video capture constraints.
+   *
+   * @default true
+   */
+  readonly video?: MaybeRefOrGetter<boolean | MediaTrackConstraints>;
+  /**
+   * Audio capture constraints (tab or system audio where supported).
+   *
+   * @default false
+   */
+  readonly audio?: MaybeRefOrGetter<boolean | MediaTrackConstraints>;
+  /**
+   * Start while `true`, stop while `false`. Browsers require a user gesture
+   * for screen capture, so prefer calling `start` from an event handler.
+   *
+   * @default false
+   */
+  readonly enabled?: MaybeRefOrGetter<boolean>;
+  /**
+   * `MediaDevices` capability for alternate runtimes and tests.
+   *
+   * @default window.navigator.mediaDevices when it implements `getDisplayMedia`
+   */
+  readonly host?: MaybeRefOrGetter<DisplayMediaHost | null | undefined>;
+}
+/**
+ * Capture a screen, window, or tab with `getDisplayMedia`.
+ *
+ * Shares the stream lifecycle of `useMediaStream` (from `use-user-media`):
+ * classified failures (`"permission-denied"` when the user dismisses the
+ * picker), latest-wins requests, and automatic return to `"idle"` when the
+ * user ends sharing from the browser UI (every track `ended`). Tracks are
+ * stopped when the owning reactive scope stops.
+ *
+ * Server rendering: nothing is captured; `status` is `"idle"` and
+ * `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const screen = useDisplayMedia({ audio: true });
+ * const share = () => screen.start();
+ * ```
+ *
+ * @param options Capture constraints, activation, and capability.
+ * @default options {}
+ * @returns Stream state and actions.
+ */
+declare function useDisplayMedia(options?: UseDisplayMediaOptions): MediaStreamControls;
+//#endregion
+export { DisplayMediaHost, UseDisplayMediaOptions, useDisplayMedia };

package/dist/use-display-media.mjs

@@ -0,0 +1,46 @@
+import { useMediaStream } from "./use-user-media.mjs";
+import { toValue } from "vue";
+//#region src/use-display-media.ts
+function browserDisplayMediaHost() {
+	if (typeof window === "undefined") return void 0;
+	const devices = window.navigator.mediaDevices;
+	return devices && typeof devices.getDisplayMedia === "function" ? devices : void 0;
+}
+/**
+* Capture a screen, window, or tab with `getDisplayMedia`.
+*
+* Shares the stream lifecycle of `useMediaStream` (from `use-user-media`):
+* classified failures (`"permission-denied"` when the user dismisses the
+* picker), latest-wins requests, and automatic return to `"idle"` when the
+* user ends sharing from the browser UI (every track `ended`). Tracks are
+* stopped when the owning reactive scope stops.
+*
+* Server rendering: nothing is captured; `status` is `"idle"` and
+* `supported` is false.
+*
+* @example
+* ```ts
+* const screen = useDisplayMedia({ audio: true });
+* const share = () => screen.start();
+* ```
+*
+* @param options Capture constraints, activation, and capability.
+* @default options {}
+* @returns Stream state and actions.
+*/
+function useDisplayMedia(options = {}) {
+	const resolveHost = () => options.host === void 0 ? browserDisplayMediaHost() : toValue(options.host) ?? void 0;
+	return useMediaStream({
+		source: () => {
+			const host = resolveHost();
+			return host ? { request: (constraints) => host.getDisplayMedia(constraints) } : void 0;
+		},
+		constraints: () => ({
+			video: toValue(options.video) ?? true,
+			audio: toValue(options.audio) ?? false
+		}),
+		enabled: () => toValue(options.enabled) ?? false
+	});
+}
+//#endregion
+export { useDisplayMedia };

package/dist/use-display-names.d.mts

@@ -0,0 +1,75 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-display-names.d.ts
+/** Kinds of codes `Intl.DisplayNames` can name. */
+type DisplayNamesKind = "language" | "region" | "script" | "currency" | "calendar" | "dateTimeField";
+/** Options for {@link useDisplayNames}. */
+interface UseDisplayNamesOptions {
+  /** Kind of code to name. */
+  readonly type: DisplayNamesKind;
+  /**
+   * Locale the names are written in. Pass it explicitly for
+   * hydration-stable server rendering.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+  /**
+   * Name length.
+   *
+   * @default "long"
+   */
+  readonly style?: "narrow" | "short" | "long";
+  /**
+   * What to return for a well-formed code without a name: the code itself
+   * or `undefined`.
+   *
+   * @default "code"
+   */
+  readonly fallback?: "code" | "none";
+  /**
+   * Language names: `"dialect"` names `"en-GB"` "British English",
+   * `"standard"` names it "English (United Kingdom)".
+   *
+   * @default "dialect"
+   */
+  readonly languageDisplay?: "dialect" | "standard";
+}
+/** Reactive display names returned by {@link useDisplayNames}. */
+interface DisplayNamesControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+  /** Display names instance for the current locale and options. */
+  readonly displayNames: ComputedRef<Intl.DisplayNames>;
+  /** Name of the reactive code; `undefined` for malformed or unnamed codes. */
+  readonly name: ComputedRef<string | undefined>;
+  /**
+   * Name any code. Malformed codes return `undefined` instead of throwing.
+   *
+   * @param code Language tag, region, script, currency, calendar, or field code.
+   * @returns The localized name.
+   */
+  readonly of: (code: string) => string | undefined;
+}
+/**
+ * Localized names of languages, regions, scripts, currencies, calendars, and
+ * date-time fields (`Intl.DisplayNames`): `"JP"` → "Japan", `"ja"` → "日本語"
+ * in Japanese, `"EUR"` → "Euro".
+ *
+ * Malformed codes yield `undefined` rather than the platform `RangeError`,
+ * so user-entered codes never crash rendering; invalid *options* still
+ * throw on first read. Derived state only: no listeners or timers, and
+ * deterministic during server rendering when the locale is explicit.
+ *
+ * @example
+ * ```ts
+ * const { name } = useDisplayNames(regionCode, { type: "region", locale: "en" });
+ * ```
+ *
+ * @param code Reactive code to name.
+ * @param options Reactive kind, locale, and display options.
+ * @returns Reactive name and a naming helper.
+ */
+declare function useDisplayNames(code: MaybeRefOrGetter<string | null | undefined>, options: MaybeRefOrGetter<UseDisplayNamesOptions>): DisplayNamesControls;
+//#endregion
+export { DisplayNamesControls, DisplayNamesKind, UseDisplayNamesOptions, useDisplayNames };

package/dist/use-display-names.mjs

@@ -0,0 +1,52 @@
+import { useLocale } from "./locale.mjs";
+import { computed, toValue } from "vue";
+//#region src/use-display-names.ts
+function browserLanguage() {
+	return typeof window === "undefined" ? void 0 : window.navigator.language;
+}
+/**
+* Localized names of languages, regions, scripts, currencies, calendars, and
+* date-time fields (`Intl.DisplayNames`): `"JP"` → "Japan", `"ja"` → "日本語"
+* in Japanese, `"EUR"` → "Euro".
+*
+* Malformed codes yield `undefined` rather than the platform `RangeError`,
+* so user-entered codes never crash rendering; invalid *options* still
+* throw on first read. Derived state only: no listeners or timers, and
+* deterministic during server rendering when the locale is explicit.
+*
+* @example
+* ```ts
+* const { name } = useDisplayNames(regionCode, { type: "region", locale: "en" });
+* ```
+*
+* @param code Reactive code to name.
+* @param options Reactive kind, locale, and display options.
+* @returns Reactive name and a naming helper.
+*/
+function useDisplayNames(code, options) {
+	const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+	const displayNames = computed(() => {
+		const { locale: _locale, ...displayOptions } = toValue(options);
+		return new Intl.DisplayNames(localeControls.locale.value, displayOptions);
+	});
+	const of = (value) => {
+		const names = displayNames.value;
+		try {
+			return names.of(value);
+		} catch (error) {
+			if (error instanceof RangeError) return void 0;
+			throw error;
+		}
+	};
+	return {
+		locale: localeControls.locale,
+		displayNames,
+		name: computed(() => {
+			const current = toValue(code);
+			return current === null || current === void 0 || current === "" ? void 0 : of(current);
+		}),
+		of
+	};
+}
+//#endregion
+export { useDisplayNames };

package/dist/use-document-title.d.mts

@@ -0,0 +1,88 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-document-title.d.ts
+/** Document subset used by {@link useDocumentTitle}. */
+interface DocumentTitleHost {
+  /** Current document title (readable and writable). */
+  title: string;
+  /**
+   * Observe external title changes (for example by other libraries).
+   * Returns a function that stops observing.
+   */
+  readonly observeTitle?: (callback: () => void) => () => void;
+}
+/** Title template: a string containing `%s`, or a formatting function. */
+type DocumentTitleTemplate = string | ((title: string) => string);
+/** Title applied when the owning scope stops. */
+type DocumentTitleRestore = false | "previous" | ((originalTitle: string, currentTitle: string) => string);
+/** Options for {@link useDocumentTitle}. */
+interface UseDocumentTitleOptions {
+  /**
+   * Template applied to every title written to the document.
+   *
+   * @default "%s"
+   */
+  readonly template?: DocumentTitleTemplate;
+  /**
+   * Title restored when the owning reactive scope stops: `false` leaves the
+   * current title, `"previous"` restores the title seen at creation, and a
+   * function computes it.
+   *
+   * @default false
+   */
+  readonly restoreOnDispose?: DocumentTitleRestore;
+  /**
+   * Follow title changes made outside this composable.
+   *
+   * @default false
+   */
+  readonly observe?: boolean;
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document (with a MutationObserver on `<title>`)
+   */
+  readonly host?: MaybeRefOrGetter<DocumentTitleHost | null | undefined>;
+}
+/** Reactive state returned by {@link useDocumentTitle}. */
+interface DocumentTitleControls {
+  /**
+   * Title before templating. Writable; `null`/`undefined` leaves the
+   * document title untouched. When a getter was passed, the next getter
+   * change overwrites manual assignments.
+   */
+  readonly title: Ref<string | null | undefined>;
+  /**
+   * Whether a document capability is attached. Inside a component it stays
+   * `false` until mounted, so hydration matches the server render.
+   */
+  readonly supported: ComputedRef<boolean>;
+}
+/**
+ * Bind the document title to reactive state.
+ *
+ * Accepts a writable ref (used as-is), a getter (followed), a plain
+ * string, or nothing (an owned ref seeded from the current title). Every
+ * non-nullish title is passed through `template` before it is written.
+ * With `observe`, external title changes flow back into `title`.
+ *
+ * Server rendering: the document is never touched and `title` keeps the
+ * value it was given (or `undefined`). Head management for server-rendered
+ * markup (`<title>` in the HTML) is the job of the application's head
+ * manager; this composable only updates the live document on the client.
+ * Watchers and the observer are released with the owning reactive scope,
+ * which also applies `restoreOnDispose`.
+ *
+ * @example
+ * ```ts
+ * const { title } = useDocumentTitle(() => route.meta.title, { template: "%s | Vize" });
+ * ```
+ *
+ * @param title Reactive title source.
+ * @param options Template, restore policy, observation, and capability.
+ * @default options {}
+ * @returns The title ref and support flag.
+ */
+declare function useDocumentTitle(title?: MaybeRefOrGetter<string | null | undefined>, options?: UseDocumentTitleOptions): DocumentTitleControls;
+//#endregion
+export { DocumentTitleControls, DocumentTitleHost, DocumentTitleRestore, DocumentTitleTemplate, UseDocumentTitleOptions, useDocumentTitle };

package/dist/use-document-title.mjs

@@ -0,0 +1,100 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { useMounted } from "./use-mounted.mjs";
+import { computed, hasInjectionContext, isRef, ref, toValue, watch } from "vue";
+//#region src/use-document-title.ts
+function browserTitleHost() {
+	if (typeof window === "undefined") return void 0;
+	const { document, MutationObserver } = window;
+	return {
+		get title() {
+			return document.title;
+		},
+		set title(value) {
+			document.title = value;
+		},
+		observeTitle: (callback) => {
+			const observer = new MutationObserver(callback);
+			const element = document.head.querySelector("title");
+			if (element) observer.observe(element, {
+				childList: true,
+				characterData: true,
+				subtree: true
+			});
+			return () => observer.disconnect();
+		}
+	};
+}
+function formatTitle(template, title) {
+	return typeof template === "function" ? template(title) : template.replaceAll("%s", title);
+}
+/**
+* Bind the document title to reactive state.
+*
+* Accepts a writable ref (used as-is), a getter (followed), a plain
+* string, or nothing (an owned ref seeded from the current title). Every
+* non-nullish title is passed through `template` before it is written.
+* With `observe`, external title changes flow back into `title`.
+*
+* Server rendering: the document is never touched and `title` keeps the
+* value it was given (or `undefined`). Head management for server-rendered
+* markup (`<title>` in the HTML) is the job of the application's head
+* manager; this composable only updates the live document on the client.
+* Watchers and the observer are released with the owning reactive scope,
+* which also applies `restoreOnDispose`.
+*
+* @example
+* ```ts
+* const { title } = useDocumentTitle(() => route.meta.title, { template: "%s | Vize" });
+* ```
+*
+* @param title Reactive title source.
+* @param options Template, restore policy, observation, and capability.
+* @default options {}
+* @returns The title ref and support flag.
+*/
+function useDocumentTitle(title, options = {}) {
+	const template = options.template ?? "%s";
+	const resolveHost = () => options.host === void 0 ? browserTitleHost() : toValue(options.host) ?? void 0;
+	const initialHost = resolveHost();
+	const originalTitle = initialHost?.title ?? "";
+	const mounted = hasInjectionContext() ? useMounted() : void 0;
+	const adoptTitle = title === void 0 && mounted !== void 0;
+	const state = isRef(title) ? title : ref(title === void 0 && !adoptTitle ? initialHost?.title : toValue(title));
+	if (adoptTitle) watch(mounted, (isMounted) => {
+		if (isMounted && state.value === void 0) state.value = resolveHost()?.title;
+	});
+	let lastWritten;
+	if (typeof title === "function") watch(title, (next) => {
+		state.value = next;
+	});
+	watch([state, resolveHost], ([next, host]) => {
+		if (!host || next === null || next === void 0) return;
+		const formatted = formatTitle(template, next);
+		lastWritten = formatted;
+		if (host.title !== formatted) host.title = formatted;
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	if (options.observe ?? false) watch(resolveHost, (host, _previous, onCleanup) => {
+		if (!host?.observeTitle) return;
+		onCleanup(host.observeTitle(() => {
+			if (host.title !== lastWritten) state.value = host.title;
+		}));
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const restore = options.restoreOnDispose ?? false;
+	if (restore !== false) tryOnScopeDispose(() => {
+		const host = resolveHost();
+		if (!host) return;
+		host.title = restore === "previous" ? originalTitle : restore(originalTitle, host.title);
+	});
+	return {
+		title: state,
+		supported: computed(() => (mounted?.value ?? true) && resolveHost() !== void 0)
+	};
+}
+//#endregion
+export { useDocumentTitle };

package/dist/use-drop-zone.d.mts

@@ -0,0 +1,128 @@
+import { MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-drop-zone.d.ts
+/** One entry of `DataTransfer.items`. */
+interface DataTransferItemLike {
+  /** `"file"` or `"string"`. */
+  readonly kind: string;
+  /** MIME type of the item. */
+  readonly type: string;
+}
+/** Minimal `DataTransfer` consumed by {@link useDropZone}. */
+interface DataTransferLike {
+  /** Items being dragged; types are readable during the drag. */
+  readonly items?: ArrayLike<DataTransferItemLike>;
+  /** Dropped files; populated on `drop`. */
+  readonly files: ArrayLike<File>;
+  /** Feedback shown to the user (`"copy"`, `"none"`, …). */
+  dropEffect: string;
+}
+/** File name and MIME type used for acceptance checks. */
+interface DropZoneFileInfo {
+  /** File name including extension. Empty while dragging. */
+  readonly name: string;
+  /** MIME type, possibly empty for unknown types. */
+  readonly type: string;
+}
+/**
+ * Accepted files: `accept`-attribute style patterns (`"image/*"`,
+ * `"application/pdf"`, `".png"`), or a predicate over the dragged MIME types.
+ */
+type DropZoneAccept = readonly string[] | ((types: readonly string[]) => boolean);
+/** Options for {@link useDropZone}. */
+interface UseDropZoneOptions {
+  /**
+   * Accepted files. Extension patterns can only be verified on drop
+   * because browsers hide file names while dragging. A ref rather than a
+   * getter, because a predicate is itself a function.
+   *
+   * @default every file
+   */
+  readonly accept?: MaybeRef<DropZoneAccept | undefined>;
+  /**
+   * Accept more than one file per drop.
+   *
+   * @default true
+   */
+  readonly multiple?: MaybeRefOrGetter<boolean>;
+  /**
+   * Call `preventDefault` even for rejected drags, so the browser never
+   * opens a rejected file dropped onto the zone.
+   *
+   * @default false
+   */
+  readonly preventDefaultForUnhandled?: boolean;
+  /**
+   * Called with the accepted files (or `null` when none were accepted).
+   *
+   * @default undefined
+   */
+  readonly onDrop?: (files: readonly File[] | null, event: Event) => void;
+  /**
+   * Called when a drag enters the zone.
+   *
+   * @default undefined
+   */
+  readonly onEnter?: (event: Event) => void;
+  /**
+   * Called when a drag leaves the zone (including its children).
+   *
+   * @default undefined
+   */
+  readonly onLeave?: (event: Event) => void;
+  /**
+   * Called for every `dragover` inside the zone.
+   *
+   * @default undefined
+   */
+  readonly onOver?: (event: Event) => void;
+}
+/** Reactive state returned by {@link useDropZone}. */
+interface DropZoneControls {
+  /** Whether a drag is currently over the zone (children included). */
+  readonly isOverDropZone: Readonly<Ref<boolean>>;
+  /** Whether the current drag is acceptable. */
+  readonly accepted: Readonly<Ref<boolean>>;
+  /** Files accepted by the most recent drop. */
+  readonly files: Readonly<ShallowRef<readonly File[] | null>>;
+}
+/**
+ * Test a file against `accept`-attribute style patterns.
+ *
+ * Supports exact MIME types, wildcard subtypes (`"image/*"`), extensions
+ * (`".png"`, case-insensitive), and `"*"`. An empty pattern list accepts
+ * everything. An empty `name` (the file is still being dragged) makes
+ * extension patterns match provisionally.
+ *
+ * @param accept Patterns to test.
+ * @param file File name and MIME type.
+ * @returns Whether any pattern matches.
+ */
+declare function matchesAccept(accept: readonly string[], file: DropZoneFileInfo): boolean;
+/**
+ * Headless drop-zone logic for any element.
+ *
+ * Tracks whether a drag is over the target (a nesting counter keeps
+ * `dragleave` from child elements from flickering the state), decides
+ * acceptance from the dragged MIME types while dragging, and filters the
+ * dropped files by `accept` (including extension patterns) and `multiple`.
+ * Rejected drags show the `"none"` drop effect. Rendering is entirely up to
+ * the caller. Listeners follow the reactive target and are removed when the
+ * owning reactive scope stops.
+ *
+ * Server rendering: no listener is attached; all state is empty/false.
+ *
+ * @example
+ * ```ts
+ * const zone = useTemplateRef<HTMLElement>("zone");
+ * const { isOverDropZone, files } = useDropZone(zone, { accept: ["image/*"] });
+ * ```
+ *
+ * @param target Reactive drop target.
+ * @param options Acceptance rules and lifecycle callbacks.
+ * @default options {}
+ * @returns Drag and drop state.
+ */
+declare function useDropZone(target: MaybeRefOrGetter<EventTarget | null | undefined>, options?: UseDropZoneOptions): DropZoneControls;
+//#endregion
+export { DataTransferItemLike, DataTransferLike, DropZoneAccept, DropZoneControls, DropZoneFileInfo, UseDropZoneOptions, matchesAccept, useDropZone };