@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-css-var.d.mts

@@ -0,0 +1,96 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-css-var.d.ts
+/** Style declaration subset used by {@link useCssVar}. */
+interface CssVarStyle {
+  /** Read a property value. */
+  getPropertyValue(name: string): string;
+  /** Write a property value. */
+  setProperty(name: string, value: string | null): void;
+  /** Remove a property. */
+  removeProperty(name: string): string;
+}
+/** Element subset used by {@link useCssVar}. */
+interface CssVarTarget {
+  /** Inline style declaration. */
+  readonly style: CssVarStyle;
+}
+/** Minimal `MutationObserver` instance. */
+interface CssVarObserver {
+  /** Start observing `target`. */
+  observe(target: CssVarTarget, options: {
+    attributes: true;
+    attributeFilter: string[];
+  }): void;
+  /** Stop observing. */
+  disconnect(): void;
+}
+/** Capabilities used by {@link useCssVar}. */
+interface CssVarHost {
+  /** Resolved (computed) style of a target. */
+  getComputedStyle(target: CssVarTarget): Pick<CssVarStyle, "getPropertyValue">;
+  /** Target used when none is given (the document root element). */
+  readonly documentElement: CssVarTarget;
+  /** Observer factory used when `observe` is enabled. */
+  readonly createObserver?: (callback: () => void) => CssVarObserver;
+}
+/** Options for {@link useCssVar}. */
+interface UseCssVarOptions {
+  /**
+   * Value used while the variable is unset and during server rendering.
+   *
+   * @default ""
+   */
+  readonly initialValue?: string;
+  /**
+   * Re-read the variable when the target's `style` or `class` attribute
+   * changes (MutationObserver).
+   *
+   * @default false
+   */
+  readonly observe?: boolean;
+  /**
+   * Style capability for alternate runtimes and tests.
+   *
+   * @default window.getComputedStyle, document.documentElement, and MutationObserver
+   */
+  readonly host?: MaybeRefOrGetter<CssVarHost | null | undefined>;
+}
+/** Reactive state returned by {@link useCssVar}. */
+interface CssVarControls {
+  /** Writable variable value; assignments are written as inline style. */
+  readonly value: Ref<string>;
+  /** Whether a style capability and target are attached. */
+  readonly supported: ComputedRef<boolean>;
+}
+/**
+ * Read and write a CSS custom property reactively.
+ *
+ * The value is read from the target's computed style whenever the
+ * reactive name, target, or host changes (and, with `observe`, when its
+ * `style`/`class` attribute changes). Assigning `value` writes an inline
+ * `style.setProperty`; assigning `""` removes the inline declaration. Values
+ * read from the element are never written back, so a stylesheet-provided
+ * variable is not frozen into inline style.
+ *
+ * Server rendering: nothing is read or written; `value` holds
+ * `initialValue`. Keep server markup and the first client render identical
+ * by rendering from `initialValue` until mounted. The observer and
+ * watchers are released with the owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * const accent = useCssVar("--accent", rootRef, { initialValue: "#0af" });
+ * accent.value.value = "#f60";
+ * ```
+ *
+ * @param name Reactive custom property name, starting with `--`.
+ * @param target Reactive element; defaults to the document root element.
+ * @param options Initial value, observation, and capability.
+ * @default options {}
+ * @returns The writable variable value.
+ * @throws {TypeError} `[VIZE_COMPOSE_CSS_VAR_INVALID_NAME]` when the name does not start with `--`.
+ */
+declare function useCssVar(name: MaybeRefOrGetter<string>, target?: MaybeRefOrGetter<CssVarTarget | null | undefined>, options?: UseCssVarOptions): CssVarControls;
+//#endregion
+export { CssVarControls, CssVarHost, CssVarObserver, CssVarStyle, CssVarTarget, UseCssVarOptions, useCssVar };

package/dist/use-css-var.mjs

@@ -0,0 +1,104 @@
+import { computed, ref, toValue, watch } from "vue";
+//#region src/use-css-var.ts
+function browserCssVarHost() {
+	if (typeof window === "undefined") return void 0;
+	const view = window;
+	return {
+		getComputedStyle: (target) => target instanceof view.Element ? view.getComputedStyle(target) : target.style,
+		documentElement: view.document.documentElement,
+		createObserver: (callback) => {
+			const observer = new view.MutationObserver(callback);
+			return {
+				observe: (target, init) => {
+					if (target instanceof view.Node) observer.observe(target, init);
+				},
+				disconnect: () => observer.disconnect()
+			};
+		}
+	};
+}
+function assertVariableName(name) {
+	if (!name.startsWith("--")) throw new TypeError(`[VIZE_COMPOSE_CSS_VAR_INVALID_NAME] custom property names must start with "--"; received ${JSON.stringify(name)}`);
+}
+/**
+* Read and write a CSS custom property reactively.
+*
+* The value is read from the target's computed style whenever the
+* reactive name, target, or host changes (and, with `observe`, when its
+* `style`/`class` attribute changes). Assigning `value` writes an inline
+* `style.setProperty`; assigning `""` removes the inline declaration. Values
+* read from the element are never written back, so a stylesheet-provided
+* variable is not frozen into inline style.
+*
+* Server rendering: nothing is read or written; `value` holds
+* `initialValue`. Keep server markup and the first client render identical
+* by rendering from `initialValue` until mounted. The observer and
+* watchers are released with the owning reactive scope.
+*
+* @example
+* ```ts
+* const accent = useCssVar("--accent", rootRef, { initialValue: "#0af" });
+* accent.value.value = "#f60";
+* ```
+*
+* @param name Reactive custom property name, starting with `--`.
+* @param target Reactive element; defaults to the document root element.
+* @param options Initial value, observation, and capability.
+* @default options {}
+* @returns The writable variable value.
+* @throws {TypeError} `[VIZE_COMPOSE_CSS_VAR_INVALID_NAME]` when the name does not start with `--`.
+*/
+function useCssVar(name, target, options = {}) {
+	const initialValue = options.initialValue ?? "";
+	assertVariableName(toValue(name));
+	const value = ref(initialValue);
+	let lastRead;
+	const resolveHost = () => options.host === void 0 ? browserCssVarHost() : toValue(options.host) ?? void 0;
+	const resolveTarget = (host) => {
+		if (!host) return void 0;
+		return target === void 0 ? host.documentElement : toValue(target) ?? void 0;
+	};
+	const read = (host, element, variable) => {
+		const current = host.getComputedStyle(element).getPropertyValue(variable).trim();
+		const next = current === "" ? initialValue : current;
+		lastRead = next;
+		value.value = next;
+	};
+	watch(() => {
+		const host = resolveHost();
+		return [
+			host,
+			resolveTarget(host),
+			toValue(name)
+		];
+	}, ([host, element, variable], _previous, onCleanup) => {
+		assertVariableName(variable);
+		if (!host || !element) return;
+		read(host, element, variable);
+		if (!(options.observe ?? false) || !host.createObserver) return;
+		const observer = host.createObserver(() => read(host, element, variable));
+		observer.observe(element, {
+			attributes: true,
+			attributeFilter: ["style", "class"]
+		});
+		onCleanup(() => observer.disconnect());
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	watch(value, (next) => {
+		if (next === lastRead) return;
+		lastRead = void 0;
+		const element = resolveTarget(resolveHost());
+		if (!element) return;
+		const variable = toValue(name);
+		if (next === "") element.style.removeProperty(variable);
+		else element.style.setProperty(variable, next);
+	}, { flush: "sync" });
+	return {
+		value,
+		supported: computed(() => resolveTarget(resolveHost()) !== void 0)
+	};
+}
+//#endregion
+export { useCssVar };

package/dist/use-cycle-list.d.mts

@@ -0,0 +1,76 @@
+import { MaybeRefOrGetter, ShallowRef, WritableComputedRef } from "vue";
+
+//#region src/use-cycle-list.d.ts
+/** Options for {@link useCycleList}. */
+interface UseCycleListOptions<Item> {
+  /**
+   * Item selected initially.
+   *
+   * @default the first item
+   */
+  readonly initialValue?: Item;
+  /**
+   * Index used when the current item is not in the list.
+   *
+   * @default 0
+   */
+  readonly fallbackIndex?: number;
+  /**
+   * Locate an item in the list, for example by id.
+   *
+   * @default Array.prototype.indexOf
+   */
+  readonly getIndexOf?: (item: Item, list: readonly Item[]) => number;
+}
+/** Cursor over a list returned by {@link useCycleList}. */
+interface CycleList<Current, Item> {
+  /** Current item. Writable: assigning moves the cursor to that item. */
+  readonly state: ShallowRef<Current>;
+  /** Current index. Writable: assigning wraps around the list. */
+  readonly index: WritableComputedRef<number>;
+  /**
+   * Move forward `steps` items (default `1`), wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly next: (steps?: number) => Current;
+  /**
+   * Move backward `steps` items (default `1`), wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly prev: (steps?: number) => Current;
+  /**
+   * Jump to `index`, wrapping around.
+   *
+   * @returns The new current item.
+   */
+  readonly go: (index: number) => Current;
+  /** The list items, for convenience. */
+  readonly list: Readonly<ShallowRef<readonly Item[]>>;
+}
+/**
+ * Cycle through a list with wrap-around navigation.
+ *
+ * Non-empty tuple sources (`["light", "dark", "system"] as const`) yield a
+ * `state` typed as the element union; general arrays may be empty, so their
+ * `state` includes `undefined`. When the list changes, the cursor keeps the
+ * current item if it is still present and otherwise moves to
+ * `fallbackIndex`. Synchronous state: SSR-safe; the list watcher follows the
+ * owning scope.
+ *
+ * @example
+ * ```ts
+ * const { state, next } = useCycleList(["light", "dark", "system"] as const);
+ * next(); // "dark"
+ * ```
+ *
+ * @param list Reactive list to cycle through.
+ * @param options Initial item, fallback index, and item lookup.
+ * @default options {}
+ * @returns The cursor and navigation controls.
+ */
+declare function useCycleList<const List extends readonly [unknown, ...unknown[]]>(list: MaybeRefOrGetter<List>, options?: UseCycleListOptions<List[number]>): CycleList<List[number], List[number]>;
+declare function useCycleList<Item>(list: MaybeRefOrGetter<readonly Item[]>, options?: UseCycleListOptions<Item>): CycleList<Item | undefined, Item>;
+//#endregion
+export { CycleList, UseCycleListOptions, useCycleList };

package/dist/use-cycle-list.mjs

@@ -0,0 +1,39 @@
+import { computed, shallowRef, toValue, watch } from "vue";
+//#region src/use-cycle-list.ts
+function useCycleList(list, options = {}) {
+	const items = computed(() => toValue(list));
+	const locate = options.getIndexOf ?? ((item, all) => all.indexOf(item));
+	const state = shallowRef("initialValue" in options ? options.initialValue : items.value[0]);
+	const wrap = (index) => {
+		const length = items.value.length;
+		return length === 0 ? 0 : (Math.trunc(index) % length + length) % length;
+	};
+	const index = computed({
+		get: () => {
+			const current = state.value;
+			const found = current === void 0 ? -1 : locate(current, items.value);
+			return found === -1 ? wrap(options.fallbackIndex ?? 0) : found;
+		},
+		set: (next) => {
+			state.value = items.value[wrap(next)];
+		}
+	});
+	const go = (target) => {
+		index.value = target;
+		return state.value;
+	};
+	watch(items, () => {
+		const current = state.value;
+		if (current === void 0 || locate(current, items.value) === -1) state.value = items.value[wrap(options.fallbackIndex ?? 0)];
+	});
+	return {
+		state,
+		index,
+		next: (steps = 1) => go(index.value + steps),
+		prev: (steps = 1) => go(index.value - steps),
+		go,
+		list: items
+	};
+}
+//#endregion
+export { useCycleList };

package/dist/use-date-format.d.mts

@@ -0,0 +1,103 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-date-format.d.ts
+/** Date input accepted by {@link formatDate} and {@link useDateFormat}. */
+type DateFormatInput = Date | number | string;
+/**
+ * Tokens understood by the pattern form of {@link formatDate}.
+ *
+ * | Token | Output | Token | Output |
+ * | --- | --- | --- | --- |
+ * | `YYYY` | 2026 | `YY` | 26 |
+ * | `M` / `MM` | 1 / 01 | `MMM` / `MMMM` | Jan / January (localized) |
+ * | `D` / `DD` | 5 / 05 | `d` | 0–6, Sunday is 0 |
+ * | `dd` / `ddd` / `dddd` | S / Sun / Sunday (localized) | `H` / `HH` | 0–23 |
+ * | `h` / `hh` | 1–12 | `m` / `mm`, `s` / `ss` | minutes, seconds |
+ * | `SSS` | milliseconds | `A` / `a` | AM / am (localized) |
+ * | `Z` / `ZZ` | +09:00 / +0900 | `[text]` | literal text |
+ */
+type DateFormatToken = "YYYY" | "YY" | "M" | "MM" | "MMM" | "MMMM" | "D" | "DD" | "d" | "dd" | "ddd" | "dddd" | "H" | "HH" | "h" | "hh" | "m" | "mm" | "s" | "ss" | "SSS" | "A" | "a" | "Z" | "ZZ";
+/** Options for {@link formatDate}. */
+interface FormatDateOptions {
+  /**
+   * BCP 47 locale(s) for names and `Intl` option formats. Defaults to a fixed
+   * locale (not the host default) so server and client output agree.
+   *
+   * @default "en"
+   */
+  readonly locale?: string | readonly string[];
+  /**
+   * IANA time zone the date is rendered in. Defaults to UTC (not the host
+   * zone) for SSR determinism; pass the user's zone explicitly.
+   *
+   * @default "UTC"
+   */
+  readonly timeZone?: string;
+}
+/** Options for {@link useDateFormat}. */
+interface UseDateFormatOptions {
+  /**
+   * Reactive BCP 47 locale(s).
+   *
+   * @default "en"
+   */
+  readonly locale?: MaybeRefOrGetter<string | readonly string[]>;
+  /**
+   * Reactive IANA time zone.
+   *
+   * @default "UTC"
+   */
+  readonly timeZone?: MaybeRefOrGetter<string>;
+}
+/**
+ * Format a date with a token pattern or `Intl.DateTimeFormat` options.
+ *
+ * Pure and deterministic: locale and time zone default to fixed values
+ * (`"en"`, `"UTC"`) rather than host settings, so the same input renders
+ * identically on server and client. Calendar fields are computed in the
+ * requested time zone through `Intl`, so no host-zone arithmetic leaks in.
+ *
+ * @example
+ * ```ts
+ * formatDate(0, "YYYY-MM-DD HH:mm:ss"); // "1970-01-01 00:00:00"
+ * formatDate(0, "dddd, MMMM D [at] h:mm A", { locale: "en", timeZone: "Asia/Tokyo" });
+ * formatDate(0, { dateStyle: "long" }, { locale: "ja" }); // "1970年1月1日"
+ * ```
+ *
+ * @param input Date to format.
+ * @param format Token pattern (see {@link DateFormatToken}) or `Intl` options.
+ * @param options Locale and time zone.
+ * @default format "HH:mm:ss"
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DATE_FORMAT_INVALID_DATE` for
+ * invalid dates, and `RangeError` from `Intl` for invalid locales or zones.
+ * @returns The formatted string.
+ */
+declare function formatDate(input: DateFormatInput, format?: string | Intl.DateTimeFormatOptions, options?: FormatDateOptions): string;
+/**
+ * Reactive formatted date.
+ *
+ * Wraps {@link formatDate} in a computed ref; the date, the format, the
+ * locale, and the time zone are all reactive. Deterministic defaults (`"en"`,
+ * `"UTC"`) keep server and client output identical. No timers, no globals,
+ * nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const label = useDateFormat(() => event.value.startsAt, "ddd, MMM D HH:mm", {
+ *   locale: () => locale.value,
+ *   timeZone: "Europe/Paris",
+ * });
+ * ```
+ *
+ * @param input Reactive date.
+ * @param format Reactive token pattern or `Intl` options.
+ * @param options Reactive locale and time zone.
+ * @default format "HH:mm:ss"
+ * @default options {}
+ * @throws `RangeError` on read for invalid dates, locales, or zones.
+ * @returns Computed formatted string.
+ */
+declare function useDateFormat(input: MaybeRefOrGetter<DateFormatInput>, format?: MaybeRefOrGetter<string | Intl.DateTimeFormatOptions>, options?: UseDateFormatOptions): ComputedRef<string>;
+//#endregion
+export { DateFormatInput, DateFormatToken, FormatDateOptions, UseDateFormatOptions, formatDate, useDateFormat };

package/dist/use-date-format.mjs

@@ -0,0 +1,147 @@
+import { computed, toValue } from "vue";
+//#region src/use-date-format.ts
+const tokenPattern = /\[([^\]]*)]|YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|dd|d|HH|H|hh|h|mm|m|ss|s|SSS|A|a|ZZ|Z/g;
+const weekdayIndex = {
+	Sun: 0,
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6
+};
+function toDate(input) {
+	const date = input instanceof Date ? new Date(input.getTime()) : new Date(input);
+	if (Number.isNaN(date.getTime())) throw new RangeError(`[VIZE_COMPOSE_DATE_FORMAT_INVALID_DATE] expected a valid date; received ${String(input)}`);
+	return date;
+}
+function pad(value, length) {
+	return String(value).padStart(length, "0");
+}
+function partsOf(formatter, date) {
+	return new Map(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+}
+/**
+* Format a date with a token pattern or `Intl.DateTimeFormat` options.
+*
+* Pure and deterministic: locale and time zone default to fixed values
+* (`"en"`, `"UTC"`) rather than host settings, so the same input renders
+* identically on server and client. Calendar fields are computed in the
+* requested time zone through `Intl`, so no host-zone arithmetic leaks in.
+*
+* @example
+* ```ts
+* formatDate(0, "YYYY-MM-DD HH:mm:ss"); // "1970-01-01 00:00:00"
+* formatDate(0, "dddd, MMMM D [at] h:mm A", { locale: "en", timeZone: "Asia/Tokyo" });
+* formatDate(0, { dateStyle: "long" }, { locale: "ja" }); // "1970年1月1日"
+* ```
+*
+* @param input Date to format.
+* @param format Token pattern (see {@link DateFormatToken}) or `Intl` options.
+* @param options Locale and time zone.
+* @default format "HH:mm:ss"
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_DATE_FORMAT_INVALID_DATE` for
+* invalid dates, and `RangeError` from `Intl` for invalid locales or zones.
+* @returns The formatted string.
+*/
+function formatDate(input, format = "HH:mm:ss", options = {}) {
+	const date = toDate(input);
+	const locales = typeof options.locale === "string" ? options.locale : [...options.locale ?? ["en"]];
+	const timeZone = options.timeZone ?? "UTC";
+	if (typeof format !== "string") return new Intl.DateTimeFormat(locales, {
+		...format,
+		timeZone
+	}).format(date);
+	const numeric = partsOf(new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		hourCycle: "h23",
+		year: "numeric",
+		month: "numeric",
+		day: "numeric",
+		hour: "numeric",
+		minute: "numeric",
+		second: "numeric",
+		weekday: "short",
+		timeZoneName: "longOffset"
+	}), date);
+	const field = (type) => Number(numeric.get(type) ?? "0");
+	const localized = (formatOptions) => new Intl.DateTimeFormat(locales, {
+		...formatOptions,
+		timeZone
+	}).format(date);
+	const year = field("year");
+	const month = field("month");
+	const day = field("day");
+	const hour = field("hour") % 24;
+	const minute = field("minute");
+	const second = field("second");
+	const offset = (numeric.get("timeZoneName") ?? "GMT").replace("GMT", "") || "+00:00";
+	const meridiem = () => partsOf(new Intl.DateTimeFormat(locales, {
+		hour: "numeric",
+		hourCycle: "h12",
+		timeZone
+	}), date).get("dayPeriod") ?? (hour < 12 ? "AM" : "PM");
+	const render = (token) => {
+		switch (token) {
+			case "YYYY": return pad(year, 4);
+			case "YY": return pad(year % 100, 2);
+			case "M": return String(month);
+			case "MM": return pad(month, 2);
+			case "MMM": return localized({ month: "short" });
+			case "MMMM": return localized({ month: "long" });
+			case "D": return String(day);
+			case "DD": return pad(day, 2);
+			case "d": return String(weekdayIndex[numeric.get("weekday") ?? "Sun"] ?? 0);
+			case "dd": return localized({ weekday: "narrow" });
+			case "ddd": return localized({ weekday: "short" });
+			case "dddd": return localized({ weekday: "long" });
+			case "H": return String(hour);
+			case "HH": return pad(hour, 2);
+			case "h": return String(hour % 12 || 12);
+			case "hh": return pad(hour % 12 || 12, 2);
+			case "m": return String(minute);
+			case "mm": return pad(minute, 2);
+			case "s": return String(second);
+			case "ss": return pad(second, 2);
+			case "SSS": return pad(date.getUTCMilliseconds(), 3);
+			case "A": return meridiem();
+			case "a": return meridiem().toLowerCase();
+			case "Z": return offset;
+			default: return offset.replace(":", "");
+		}
+	};
+	return format.replaceAll(tokenPattern, (match, literal) => literal ?? render(match));
+}
+/**
+* Reactive formatted date.
+*
+* Wraps {@link formatDate} in a computed ref; the date, the format, the
+* locale, and the time zone are all reactive. Deterministic defaults (`"en"`,
+* `"UTC"`) keep server and client output identical. No timers, no globals,
+* nothing to dispose.
+*
+* @example
+* ```ts
+* const label = useDateFormat(() => event.value.startsAt, "ddd, MMM D HH:mm", {
+*   locale: () => locale.value,
+*   timeZone: "Europe/Paris",
+* });
+* ```
+*
+* @param input Reactive date.
+* @param format Reactive token pattern or `Intl` options.
+* @param options Reactive locale and time zone.
+* @default format "HH:mm:ss"
+* @default options {}
+* @throws `RangeError` on read for invalid dates, locales, or zones.
+* @returns Computed formatted string.
+*/
+function useDateFormat(input, format = "HH:mm:ss", options = {}) {
+	return computed(() => formatDate(toValue(input), toValue(format), {
+		locale: toValue(options.locale) ?? "en",
+		timeZone: toValue(options.timeZone) ?? "UTC"
+	}));
+}
+//#endregion
+export { formatDate, useDateFormat };

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

@@ -0,0 +1,75 @@
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/use-date-time-format.d.ts
+/** Values accepted by `Intl.DateTimeFormat`: a `Date` or Unix milliseconds. */
+type FormattableDate = Date | number;
+/** Options for {@link useDateTimeFormat}. */
+interface UseDateTimeFormatOptions extends Intl.DateTimeFormatOptions {
+  /**
+   * Locale used for formatting. Pass it explicitly (and a `timeZone`) for
+   * server rendering: the server falls back to `"en"` and its own time zone.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+/** Reactive date formatting returned by {@link useDateTimeFormat}. */
+interface DateTimeFormatControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+  /** Cached formatter for the current locale and options. */
+  readonly formatter: ComputedRef<Intl.DateTimeFormat>;
+  /**
+   * Formatted `value`, or `""` while the value is `null`/`undefined` or an
+   * invalid date.
+   */
+  readonly formatted: ComputedRef<string>;
+  /**
+   * Format any date with the current formatter.
+   *
+   * @param value Date or Unix milliseconds.
+   * @returns The formatted string.
+   * @throws {RangeError} For an invalid date, as `Intl.DateTimeFormat` does.
+   */
+  readonly format: (value: FormattableDate) => string;
+  /**
+   * Format any date into locale-aware parts.
+   *
+   * @param value Date or Unix milliseconds.
+   * @returns The formatted parts.
+   */
+  readonly formatToParts: (value: FormattableDate) => Intl.DateTimeFormatPart[];
+  /**
+   * Format a date range, collapsing shared fields (for example `"Jan 3 – 5, 2026"`).
+   *
+   * @param start Range start.
+   * @param end Range end.
+   * @returns The formatted range.
+   */
+  readonly formatRange: (start: FormattableDate, end: FormattableDate) => string;
+}
+/**
+ * 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.
+ */
+declare function useDateTimeFormat(value?: MaybeRefOrGetter<FormattableDate | null | undefined>, options?: MaybeRefOrGetter<UseDateTimeFormatOptions>): DateTimeFormatControls;
+//#endregion
+export { DateTimeFormatControls, FormattableDate, UseDateTimeFormatOptions, useDateTimeFormat };