@vunset/vue 0.0.0-stage → 1.0.0-rc.2

package/dist/components/tooltip/TooltipTrigger.vue.d.ts

@@ -0,0 +1,24 @@
+type __VLS_Props = {
+    /** Element or component to render. */
+    as?: string | object;
+};
+declare var __VLS_8: {
+    open: boolean;
+    side: import("../..").Side;
+    align: import("../..").Align;
+    transitionStatus: import("../..").TransitionStatus;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    as: string | object;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/tooltip/TooltipTrigger.vue_vue_type_script_setup_true_lang.js

@@ -0,0 +1,24 @@
+import { Part } from "../../shared/part.js";
+import { usePartProps } from "../../shared/use-part-props.js";
+import { useTooltipContext } from "./use-tooltip.js";
+import { createBlock, defineComponent, guardReactiveProps, mergeProps, normalizeProps, openBlock, renderSlot, unref, withCtx } from "vue";
+//#region src/components/tooltip/TooltipTrigger.vue?vue&type=script&setup=true&lang.ts
+var TooltipTrigger_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
+	name: "TooltipTrigger",
+	inheritAttrs: false,
+	__name: "TooltipTrigger",
+	props: { as: { default: "button" } },
+	setup(__props) {
+		const props = __props;
+		const { triggerProps, state } = useTooltipContext();
+		const merged = usePartProps(triggerProps);
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(unref(Part), mergeProps({ as: props.as }, unref(merged)), {
+				default: withCtx(() => [renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(unref(state))))]),
+				_: 3
+			}, 16, ["as"]);
+		};
+	}
+});
+//#endregion
+export { TooltipTrigger_vue_vue_type_script_setup_true_lang_default as default };

package/dist/components/tooltip/tooltip-group.d.ts

@@ -0,0 +1,41 @@
+export interface TooltipGroupOptions {
+    /** How long the pointer must rest before the first tooltip opens. */
+    delay: number;
+    /** How long after the pointer leaves before a tooltip hides. */
+    closeDelay: number;
+    /**
+     * How long after the last tooltip closes that the group keeps skipping the
+     * open delay.
+     */
+    timeout: number;
+}
+export interface TooltipGroup {
+    options: () => TooltipGroupOptions;
+    /** Whether the next tooltip should skip its open delay. */
+    isInstant: () => boolean;
+    /** How many members are currently open. */
+    openCount: () => number;
+    /** Called when a member opens, with how to close it when a neighbor takes over. */
+    onOpen: (close: () => void) => void;
+    /** Called when a member closes. */
+    onClose: (close: () => void) => void;
+}
+export declare const DEFAULT_GROUP_OPTIONS: TooltipGroupOptions;
+/**
+ * Shared timing for a set of tooltips.
+ *
+ * A lone tooltip should wait before appearing, or pointers merely crossing the
+ * screen would flash tooltips everywhere. But once one is showing, the user has
+ * clearly asked for them, and making each neighbor re-serve the full delay
+ * feels broken — so while any member is open, and briefly after the last one
+ * closes, the rest open instantly.
+ *
+ * That "briefly after" window is why this cannot live in a single tooltip: the
+ * state has to outlive the component that created it.
+ */
+export declare function createTooltipGroup(getOptions: () => TooltipGroupOptions): TooltipGroup;
+/**
+ * The group used by tooltips with no `TooltipGroup` above them. Shared across the app
+ * so that unrelated tooltips still cooperate, which is what users expect.
+ */
+export declare const defaultTooltipGroup: TooltipGroup;

package/dist/components/tooltip/tooltip-group.js

@@ -0,0 +1,51 @@
+//#region src/components/tooltip/tooltip-group.ts
+var DEFAULT_GROUP_OPTIONS = {
+	delay: 600,
+	closeDelay: 0,
+	timeout: 400
+};
+/**
+* Shared timing for a set of tooltips.
+*
+* A lone tooltip should wait before appearing, or pointers merely crossing the
+* screen would flash tooltips everywhere. But once one is showing, the user has
+* clearly asked for them, and making each neighbor re-serve the full delay
+* feels broken — so while any member is open, and briefly after the last one
+* closes, the rest open instantly.
+*
+* That "briefly after" window is why this cannot live in a single tooltip: the
+* state has to outlive the component that created it.
+*/
+function createTooltipGroup(getOptions) {
+	const open = /* @__PURE__ */ new Set();
+	let instant = false;
+	let graceTimer;
+	return {
+		options: getOptions,
+		isInstant: () => instant,
+		openCount: () => open.size,
+		onOpen(close) {
+			open.add(close);
+			instant = true;
+			clearTimeout(graceTimer);
+			graceTimer = void 0;
+			for (const other of [...open]) if (other !== close) other();
+		},
+		onClose(close) {
+			open.delete(close);
+			if (open.size > 0) return;
+			clearTimeout(graceTimer);
+			graceTimer = setTimeout(() => {
+				instant = false;
+				graceTimer = void 0;
+			}, getOptions().timeout);
+		}
+	};
+}
+/**
+* The group used by tooltips with no `TooltipGroup` above them. Shared across the app
+* so that unrelated tooltips still cooperate, which is what users expect.
+*/
+var defaultTooltipGroup = createTooltipGroup(() => DEFAULT_GROUP_OPTIONS);
+//#endregion
+export { DEFAULT_GROUP_OPTIONS, createTooltipGroup, defaultTooltipGroup };

package/dist/components/tooltip/use-tooltip.d.ts

@@ -0,0 +1,60 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from 'vue';
+import { type TransitionStatus } from '../../shared/use-transition-status';
+import { type Align, type Side, type UsePositioningOptions } from '../../shared/use-positioning';
+import { type TooltipGroup } from './tooltip-group';
+export declare const provideTooltipGroup: (value: TooltipGroup) => TooltipGroup, useTooltipGroupContext: () => TooltipGroup | null;
+export interface UseTooltipGroupOptions {
+    /** How long the pointer must rest before the first tooltip opens. */
+    delay?: MaybeRefOrGetter<number | undefined>;
+    /** How long after the pointer leaves before a tooltip hides. */
+    closeDelay?: MaybeRefOrGetter<number | undefined>;
+    /** How long after the last tooltip closes that neighbors still open instantly. */
+    timeout?: MaybeRefOrGetter<number | undefined>;
+}
+export declare function useTooltipGroup(options?: UseTooltipGroupOptions): TooltipGroup;
+export interface TooltipState {
+    /**
+     * Whether the tooltip is open.
+     * @attribute `data-open` while open, `data-closed` otherwise
+     */
+    open: boolean;
+    /**
+     * The side of the trigger the tooltip ended up on.
+     * @attribute `data-side="…"`
+     */
+    side: Side;
+    /**
+     * How the tooltip lines up along that side.
+     * @attribute `data-align="…"`
+     */
+    align: Align;
+    /**
+     * Where the tooltip is in its enter or exit animation.
+     * @attribute `data-enter-from` as it enters, `data-leave-to` as it leaves
+     */
+    transitionStatus: TransitionStatus;
+}
+export interface UseTooltipOptions extends UsePositioningOptions {
+    open?: MaybeRefOrGetter<boolean | undefined>;
+    defaultOpen?: MaybeRefOrGetter<boolean | undefined>;
+    /** Overrides the group's open delay, in milliseconds. */
+    delay?: MaybeRefOrGetter<number | undefined>;
+    /** Overrides the group's close delay, in milliseconds. */
+    closeDelay?: MaybeRefOrGetter<number | undefined>;
+    /** Allow the pointer to move into the tooltip without closing it. */
+    hoverable?: MaybeRefOrGetter<boolean | undefined>;
+    /** Never open. */
+    disabled?: MaybeRefOrGetter<boolean | undefined>;
+    onChange?: (open: boolean) => void;
+}
+export interface UseTooltipReturn {
+    open: WritableComputedRef<boolean>;
+    state: ComputedRef<TooltipState>;
+    present: Ref<boolean>;
+    triggerProps: ComputedRef<Record<string, unknown>>;
+    positionerProps: ComputedRef<Record<string, unknown>>;
+    popupProps: ComputedRef<Record<string, unknown>>;
+    arrowProps: ComputedRef<Record<string, unknown>>;
+}
+export declare function useTooltip(options?: UseTooltipOptions): UseTooltipReturn;
+export declare const provideTooltipContext: (value: UseTooltipReturn) => UseTooltipReturn, useTooltipContext: () => UseTooltipReturn;

package/dist/components/tooltip/use-tooltip.js

@@ -0,0 +1,169 @@
+import { dataAttrs } from "../../shared/data-attrs.js";
+import { useControlled } from "../../shared/use-controlled.js";
+import { createContext } from "../../shared/context.js";
+import { anchoredStateAttrs } from "../../shared/popup-state-attrs.js";
+import { useTransitionStatus } from "../../shared/use-transition-status.js";
+import { useExitAnimation } from "../../shared/use-exit-animation.js";
+import { provideSurface } from "../../shared/surface.js";
+import { usePositioning } from "../../shared/use-positioning.js";
+import { useDismiss } from "../../shared/use-dismiss.js";
+import { elementOf } from "../../shared/element-of.js";
+import { isKeyboardFocus } from "../../shared/input-modality.js";
+import { DEFAULT_GROUP_OPTIONS, createTooltipGroup, defaultTooltipGroup } from "./tooltip-group.js";
+import { computed, onScopeDispose, ref, toValue, useId, watch } from "vue";
+//#region src/components/tooltip/use-tooltip.ts
+var { provideContext: provideTooltipGroup, useOptionalContext: useTooltipGroupContext } = createContext("TooltipGroup");
+function useTooltipGroup(options = {}) {
+	const group = createTooltipGroup(() => ({
+		delay: toValue(options.delay) ?? DEFAULT_GROUP_OPTIONS.delay,
+		closeDelay: toValue(options.closeDelay) ?? DEFAULT_GROUP_OPTIONS.closeDelay,
+		timeout: toValue(options.timeout) ?? DEFAULT_GROUP_OPTIONS.timeout
+	}));
+	provideTooltipGroup(group);
+	return group;
+}
+var HOVER_GRACE = 100;
+function useTooltip(options = {}) {
+	const tooltipId = useId();
+	const group = useTooltipGroupContext() ?? defaultTooltipGroup;
+	const disabled = () => toValue(options.disabled) ?? false;
+	const hoverable = () => toValue(options.hoverable) ?? true;
+	const openDelay = () => toValue(options.delay) ?? group.options().delay;
+	const closeDelay = () => toValue(options.closeDelay) ?? group.options().closeDelay;
+	const open = useControlled({
+		value: () => toValue(options.open),
+		defaultValue: () => toValue(options.defaultOpen) ?? false,
+		onChange: options.onChange,
+		prop: "open",
+		empty: false,
+		name: "useTooltip",
+		label: "open"
+	});
+	const { mounted, transitionStatus, setMounted } = useTransitionStatus(() => open.value, {
+		skipEnter: () => group.isInstant(),
+		skipExit: () => group.openCount() > 1
+	});
+	const positioning = usePositioning({
+		...options,
+		side: () => toValue(options.side) ?? "top",
+		align: () => toValue(options.align) ?? "center",
+		sideOffset: () => toValue(options.sideOffset) ?? 8,
+		enabled: () => mounted.value
+	});
+	const triggerEl = positioning.anchorRef;
+	const surfaceEl = ref(null);
+	let timer;
+	const cancel = () => {
+		clearTimeout(timer);
+		timer = void 0;
+	};
+	function show(immediate = false) {
+		if (disabled()) return;
+		cancel();
+		if (open.value) return;
+		const wait = immediate || group.isInstant() ? 0 : openDelay();
+		if (wait <= 0) {
+			open.value = true;
+			return;
+		}
+		timer = setTimeout(() => {
+			open.value = true;
+		}, wait);
+	}
+	function hide(immediate = false) {
+		cancel();
+		if (!open.value) return;
+		const wait = immediate ? 0 : hoverable() ? Math.max(closeDelay(), HOVER_GRACE) : closeDelay();
+		if (wait <= 0) {
+			open.value = false;
+			return;
+		}
+		timer = setTimeout(() => {
+			open.value = false;
+		}, wait);
+	}
+	const closeNow = () => hide(true);
+	watch(open, (isOpen) => isOpen ? group.onOpen(closeNow) : group.onClose(closeNow), { flush: "post" });
+	onScopeDispose(() => {
+		cancel();
+		if (open.value) group.onClose(closeNow);
+	});
+	const state = computed(() => ({
+		open: open.value,
+		side: positioning.renderedSide.value,
+		align: positioning.renderedAlign.value,
+		transitionStatus: transitionStatus.value
+	}));
+	const hooks = computed(() => dataAttrs(state.value, { ...anchoredStateAttrs }));
+	useDismiss({
+		enabled: () => mounted.value,
+		elements: () => [surfaceEl.value, triggerEl.value],
+		escapeKey: true,
+		outsidePress: false,
+		onDismiss: () => hide(true)
+	});
+	useExitAnimation({
+		open: () => open.value,
+		mounted,
+		setMounted,
+		element: surfaceEl
+	});
+	const triggerProps = computed(() => ({
+		...hooks.value,
+		"data-part": "trigger",
+		"aria-describedby": mounted.value ? tooltipId : void 0,
+		ref: (el) => {
+			triggerEl.value = elementOf(el);
+		},
+		onPointerenter(event) {
+			if (event.pointerType === "touch") return;
+			show();
+		},
+		onPointerleave(event) {
+			if (event.pointerType === "touch") return;
+			hide();
+		},
+		onPointerdown() {
+			hide(true);
+		},
+		onFocus() {
+			if (isKeyboardFocus()) show(true);
+		},
+		onBlur() {
+			hide(true);
+		}
+	}));
+	const popupProps = computed(() => ({
+		...hooks.value,
+		id: tooltipId,
+		role: "tooltip",
+		ref: (el) => {
+			surfaceEl.value = el ?? null;
+		},
+		onPointerenter() {
+			if (hoverable()) cancel();
+		},
+		onPointerleave() {
+			if (hoverable()) hide();
+		}
+	}));
+	provideSurface({
+		present: mounted,
+		state,
+		popupProps,
+		positionerProps: positioning.positionerProps,
+		arrowProps: positioning.arrowProps
+	});
+	return {
+		open,
+		state,
+		present: mounted,
+		triggerProps,
+		positionerProps: positioning.positionerProps,
+		popupProps,
+		arrowProps: positioning.arrowProps
+	};
+}
+var { provideContext: provideTooltipContext, useContext: useTooltipContext } = createContext("Tooltip");
+//#endregion
+export { provideTooltipContext, provideTooltipGroup, useTooltip, useTooltipContext, useTooltipGroup, useTooltipGroupContext };

package/dist/composables/use-click-outside.d.ts

@@ -0,0 +1,16 @@
+import { type MaybeRefOrGetter } from 'vue';
+/** An element, a component, or a list of either: a template ref, a getter or the value itself. */
+export type ClickOutsideTarget = MaybeRefOrGetter<unknown>;
+export interface UseClickOutsideOptions {
+    /** More that counts as inside: the button that toggles the target, say. */
+    ignore?: ClickOutsideTarget[];
+    /** @default true */
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+/**
+ * Calls `handler` on a press outside `target`. A press inside an open overlay
+ * (a menu, a select's list) counts as inside, wherever it is portaled to, and
+ * nothing fires while `target` isn't on the page. Returns a function that stops
+ * listening; it also stops with the component.
+ */
+export declare function useClickOutside(target: ClickOutsideTarget, handler: (event: PointerEvent) => void, options?: UseClickOutsideOptions): () => void;

package/dist/composables/use-click-outside.js

@@ -0,0 +1,34 @@
+import { isInsideDismissLayer } from "../shared/dismiss-stack.js";
+import { elementOf } from "../shared/element-of.js";
+import { getCurrentScope, onScopeDispose, toValue } from "vue";
+//#region src/composables/use-click-outside.ts
+function elementsOf(targets) {
+	return targets.flatMap((target) => {
+		const value = toValue(target);
+		return Array.isArray(value) ? value.map((item) => toValue(item)) : [value];
+	}).map(elementOf).filter((element) => element !== null);
+}
+/**
+* Calls `handler` on a press outside `target`. A press inside an open overlay
+* (a menu, a select's list) counts as inside, wherever it is portaled to, and
+* nothing fires while `target` isn't on the page. Returns a function that stops
+* listening; it also stops with the component.
+*/
+function useClickOutside(target, handler, options = {}) {
+	if (typeof document === "undefined") return () => {};
+	function onPointerDown(event) {
+		if (!(toValue(options.enabled) ?? true)) return;
+		const inside = elementsOf([target]);
+		if (inside.length === 0) return;
+		const path = event.composedPath();
+		if ([...inside, ...elementsOf(options.ignore ?? [])].some((element) => path.includes(element))) return;
+		if (isInsideDismissLayer(path)) return;
+		handler(event);
+	}
+	document.addEventListener("pointerdown", onPointerDown, true);
+	const stop = () => document.removeEventListener("pointerdown", onPointerDown, true);
+	if (getCurrentScope()) onScopeDispose(stop);
+	return stop;
+}
+//#endregion
+export { useClickOutside };

package/dist/composables/use-clipboard.d.ts

@@ -0,0 +1,17 @@
+import { type ComputedRef, type MaybeRefOrGetter, type Ref } from 'vue';
+export type ClipboardStatus = 'idle' | 'copied' | 'error';
+export type ClipboardId = string | number;
+export interface UseClipboardOptions {
+    /** How long `copied` (or `error`) stays up before settling back. @default 1500 */
+    timeout?: MaybeRefOrGetter<number | undefined>;
+}
+export interface UseClipboardReturn {
+    copy: (text: string, id?: ClipboardId) => Promise<boolean>;
+    status: Readonly<Ref<ClipboardStatus>>;
+    copied: ComputedRef<boolean>;
+    /** The id passed with the last successful copy, so one instance can serve a list. */
+    copiedId: Readonly<Ref<ClipboardId | null>>;
+    error: Readonly<Ref<unknown>>;
+    reset: () => void;
+}
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

package/dist/composables/use-clipboard.js

@@ -0,0 +1,45 @@
+import { computed, onScopeDispose, readonly, ref, toValue } from "vue";
+//#region src/composables/use-clipboard.ts
+function useClipboard(options = {}) {
+	const status = ref("idle");
+	const copiedId = ref(null);
+	const error = ref(null);
+	let timer;
+	function reset() {
+		clearTimeout(timer);
+		status.value = "idle";
+		copiedId.value = null;
+		error.value = null;
+	}
+	function settle(next) {
+		clearTimeout(timer);
+		status.value = next;
+		timer = setTimeout(reset, toValue(options.timeout) ?? 1500);
+	}
+	async function copy(text, id) {
+		if (!text) return false;
+		try {
+			await navigator.clipboard.writeText(text);
+			copiedId.value = id ?? null;
+			error.value = null;
+			settle("copied");
+			return true;
+		} catch (reason) {
+			copiedId.value = null;
+			error.value = reason;
+			settle("error");
+			return false;
+		}
+	}
+	onScopeDispose(() => clearTimeout(timer));
+	return {
+		copy,
+		status: readonly(status),
+		copied: computed(() => status.value === "copied"),
+		copiedId: readonly(copiedId),
+		error: readonly(error),
+		reset
+	};
+}
+//#endregion
+export { useClipboard };

package/dist/composables/use-download.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Saves `content` as a file: a `Blob` as it is, anything else as JSON. A CSV
+ * gets `.csv` when `filename` has no such ending.
+ */
+export declare function useDownload(content: unknown, filename: string): void;
+/** Saves rows as a CSV file, its columns the first row's keys. Nothing for no rows. */
+export declare function useExportCsv<T extends object>(data: T[], filename: string): void;

package/dist/composables/use-download.js

@@ -0,0 +1,27 @@
+import { formatCsv } from "@vunset/utils";
+//#region src/composables/use-download.ts
+/**
+* Saves `content` as a file: a `Blob` as it is, anything else as JSON. A CSV
+* gets `.csv` when `filename` has no such ending.
+*/
+function useDownload(content, filename) {
+	const blob = content instanceof Blob ? content : new Blob([JSON.stringify(content, null, 2)], { type: "application/json;charset=utf-8" });
+	const extension = blob.type.startsWith("text/csv") && !/\.csv$/i.test(filename) ? ".csv" : "";
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = filename + extension;
+	document.body.appendChild(link);
+	link.click();
+	link.remove();
+	URL.revokeObjectURL(url);
+}
+/** Saves rows as a CSV file, its columns the first row's keys. Nothing for no rows. */
+function useExportCsv(data, filename) {
+	if (data.length === 0) return;
+	const headers = Object.keys(data[0]);
+	const rows = data.map((row) => headers.map((key) => row[key]));
+	useDownload(formatCsv(headers, rows), filename);
+}
+//#endregion
+export { useDownload, useExportCsv };

package/dist/composables/use-local-storage.d.ts

@@ -0,0 +1,11 @@
+export interface UseLocalStorageReturn {
+    /** The value stored under `key`, parsed; `undefined` when there is none, or it doesn't parse. */
+    getItem: <T>(key: string) => T | undefined;
+    /** Stores `data` as JSON. Nothing to store (`null`, `undefined`, an empty list) removes the key. */
+    setItem: (key: string, data: unknown) => void;
+    removeItem: (key: string) => void;
+}
+/** @internal Also `useTheme`'s. */
+export declare function storage(): Storage | undefined;
+/** JSON in `localStorage`, safe to call where there is none. */
+export declare function useLocalStorage(): UseLocalStorageReturn;

package/dist/composables/use-local-storage.js

@@ -0,0 +1,34 @@
+//#region src/composables/use-local-storage.ts
+/** @internal Also `useTheme`'s. */
+function storage() {
+	try {
+		return typeof localStorage === "undefined" ? void 0 : localStorage;
+	} catch {
+		return;
+	}
+}
+/** JSON in `localStorage`, safe to call where there is none. */
+function useLocalStorage() {
+	return {
+		getItem(key) {
+			const store = storage();
+			const raw = store?.getItem(key);
+			if (!raw) return void 0;
+			try {
+				return JSON.parse(raw);
+			} catch {
+				store?.removeItem(key);
+				return;
+			}
+		},
+		setItem(key, data) {
+			if (data === null || data === void 0 || Array.isArray(data) && data.length === 0) storage()?.removeItem(key);
+			else storage()?.setItem(key, JSON.stringify(data));
+		},
+		removeItem(key) {
+			storage()?.removeItem(key);
+		}
+	};
+}
+//#endregion
+export { storage, useLocalStorage };

package/dist/composables/use-theme.d.ts

@@ -0,0 +1,44 @@
+import { type ComputedRef, type WritableComputedRef } from 'vue';
+/** What the user chose: a scheme, or whatever the system prefers. */
+export type ThemeMode = 'light' | 'dark' | 'system';
+/** Where the choice is kept: `localStorage` by default, or anything else, an app's settings object included. */
+export interface ThemeStorage {
+    /** The stored choice; anything but a `ThemeMode` counts as none. */
+    get: () => unknown;
+    set: (theme: ThemeMode) => void;
+}
+export interface UseThemeOptions {
+    /** Where the choice is remembered, in `localStorage`. `null` keeps it for the page's life only. @default 'theme' */
+    storageKey?: string | null;
+    /** Keeps the choice somewhere else than `localStorage`; `storageKey` is then unused. */
+    storage?: ThemeStorage;
+    /** The choice before anything is stored. @default 'system' */
+    defaultTheme?: ThemeMode;
+    /** The browser's UI color for each scheme, written to `<meta name="theme-color">`. */
+    themeColor?: {
+        light: string;
+        dark: string;
+    };
+    /** Cross-fades the page on a change, where the browser has view transitions and motion isn't reduced. */
+    viewTransition?: boolean;
+}
+export interface UseThemeReturn {
+    /** The choice, settable: `light`, `dark` or `system`. */
+    theme: WritableComputedRef<ThemeMode>;
+    /** What is showing: `system` resolved to `light` or `dark`. */
+    resolved: ComputedRef<'light' | 'dark'>;
+    setTheme: (theme: ThemeMode) => void;
+    /** Light to dark and back, from what is showing; leaves `system`. */
+    toggle: () => void;
+}
+/**
+ * The page's color scheme: light, dark, or the system's, applied to `<html>` and
+ * remembered. Every call shares one choice; the first call's options set it up.
+ */
+export declare function useTheme(options?: UseThemeOptions): UseThemeReturn;
+/**
+ * For a test, or an app that tears its page down: forgets the choice and the
+ * listeners, so the next `useTheme` starts over.
+ * @internal
+ */
+export declare function resetTheme(): void;