@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-v-model.d.mts

@@ -0,0 +1,113 @@
+import { Ref } from "vue";
+
+//#region src/use-v-model.d.ts
+/** Emit function able to send `event` with a value of type `Value`. */
+type VModelEmit<Event extends string, Value> = (event: Event, value: Value) => void;
+/** Options for {@link useVModel}. */
+interface UseVModelOptions<Value, Event extends string = string, Default extends Exclude<Value, undefined> | undefined = Exclude<Value, undefined>> {
+  /**
+   * Keep a local copy that works even when the parent does not bind
+   * `v-model`: writes update the copy and emit, prop changes overwrite it.
+   *
+   * @default false
+   */
+  readonly passive?: boolean;
+  /**
+   * Event name to emit.
+   *
+   * @default `update:${key}`
+   */
+  readonly eventName?: Event;
+  /**
+   * In passive mode, store the local copy deeply reactive and also emit on
+   * nested mutations of it.
+   *
+   * @default false
+   */
+  readonly deep?: boolean;
+  /**
+   * Value read while the prop is `undefined`.
+   *
+   * @default undefined
+   */
+  readonly defaultValue?: Default;
+  /**
+   * In passive mode, copy prop values before storing them locally so local
+   * mutations never touch the parent's object: `true` uses
+   * `structuredClone` on the raw (unproxied) value, a function is used as
+   * the cloner.
+   *
+   * @default false
+   */
+  readonly clone?: boolean | ((value: Value) => Value);
+  /**
+   * Veto emitting a value.
+   *
+   * @default undefined (always emit)
+   */
+  readonly shouldEmit?: (value: Value) => boolean;
+}
+/** Model value type: `undefined` is removed when a default is configured. */
+type VModelValue<Value, Default> = [Default] extends [undefined] ? Value : Exclude<Value, undefined>;
+/**
+ * Two-way binding helper for a component prop.
+ *
+ * Reads the prop and emits `update:<key>` (or `eventName`) on write, typed
+ * end to end: the key must be a prop, the emitted value has the prop's type,
+ * and `emit` must accept that exact event (a `defineEmits` result with the
+ * matching overload qualifies). With `passive: true` a local ref mirrors the
+ * prop so the component also works uncontrolled. Relies only on the props
+ * and emit you pass (no component internals), so it is SSR- and
+ * Vapor-friendly; the passive watchers follow the owning scope.
+ *
+ * @example
+ * ```ts
+ * const props = defineProps<{ modelValue: string }>();
+ * const emit = defineEmits<{ "update:modelValue": [value: string] }>();
+ * const model = useVModel(props, "modelValue", emit);
+ * model.value = "next"; // emits update:modelValue
+ * ```
+ *
+ * @param props Component props object.
+ * @param key Prop to bind.
+ * @param emit Component emit function.
+ * @param options Passive mode, event name, default, clone, and emit guard.
+ * @default options {}
+ * @returns A writable ref over the prop.
+ */
+declare function useVModel<Props extends object, Key extends keyof Props & string, Event extends string = `update:${Key}`, Default extends Exclude<Props[Key], undefined> | undefined = undefined>(props: Props, key: Key, emit: VModelEmit<NoInfer<Event>, NoInfer<Props[Key]>>, options?: UseVModelOptions<Props[Key], Event, Default>): Ref<VModelValue<Props[Key], Default>>;
+/** Options for {@link useVModels}. */
+interface UseVModelsOptions<Key extends string> extends Omit<UseVModelOptions<unknown>, "eventName" | "defaultValue" | "shouldEmit" | "clone"> {
+  /**
+   * Props to bind. Defaults to every prop, which then requires an
+   * `update:<prop>` emit for each of them.
+   *
+   * @default all prop keys
+   */
+  readonly keys?: readonly Key[];
+}
+/** Turn a union into the intersection of its members. */
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends ((value: infer Intersection) => void) ? Intersection : never;
+/** Emit overloads required by {@link useVModels} for the bound keys. */
+type VModelsEmit<Props, Key extends keyof Props & string> = UnionToIntersection<{ [Name in Key]: VModelEmit<`update:${Name}`, Props[Name]> }[Key]>;
+/**
+ * {@link useVModel} for several props at once.
+ *
+ * Returns one writable ref per bound prop, each emitting its own
+ * `update:<prop>` event. `emit` must declare an update event for every bound
+ * key; restrict the set with `keys`.
+ *
+ * @example
+ * ```ts
+ * const { open, value } = useVModels(props, emit, { keys: ["open", "value"] });
+ * ```
+ *
+ * @param props Component props object.
+ * @param emit Component emit function.
+ * @param options Passive mode, depth, and the keys to bind.
+ * @default options {}
+ * @returns One writable ref per bound prop.
+ */
+declare function useVModels<Props extends object, const Key extends keyof Props & string = keyof Props & string>(props: Props, emit: NoInfer<VModelsEmit<Props, Key>>, options?: UseVModelsOptions<Key>): { readonly [Name in Key]: Ref<Props[Name]> };
+//#endregion
+export { UseVModelOptions, UseVModelsOptions, VModelEmit, VModelValue, VModelsEmit, useVModel, useVModels };

package/dist/use-v-model.mjs

@@ -0,0 +1,40 @@
+import { computed, ref, shallowRef, toRaw, watch } from "vue";
+//#region src/use-v-model.ts
+function useVModel(props, key, emit, options = {}) {
+	const event = options.eventName ?? `update:${key}`;
+	const read = () => props[key] ?? options.defaultValue;
+	const send = (value) => {
+		if (options.shouldEmit?.(value) ?? true) emit(event, value);
+	};
+	if (!(options.passive ?? false)) return computed({
+		get: read,
+		set: send
+	});
+	const clone = options.clone === true ? (value) => structuredClone(toRaw(value)) : typeof options.clone === "function" ? options.clone : (value) => value;
+	const deep = options.deep ?? false;
+	const local = deep ? ref(clone(read())) : shallowRef(clone(read()));
+	let fromProp = false;
+	watch(read, (value) => {
+		fromProp = true;
+		local.value = clone(value);
+		fromProp = false;
+	});
+	watch(local, (value) => {
+		if (!fromProp && (deep || value !== props[key])) send(value);
+	}, {
+		deep,
+		flush: "sync"
+	});
+	return local;
+}
+function useVModels(props, emit, options = {}) {
+	const keys = options.keys ?? Object.keys(props);
+	const models = {};
+	for (const key of keys) models[key] = useVModel(props, key, emit, {
+		...options.passive === void 0 ? {} : { passive: options.passive },
+		...options.deep === void 0 ? {} : { deep: options.deep }
+	});
+	return models;
+}
+//#endregion
+export { useVModel, useVModels };

package/dist/use-vibrate.d.mts

@@ -0,0 +1,81 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-vibrate.d.ts
+/** A single duration or an alternating vibrate/pause pattern in milliseconds. */
+type VibrationPattern = number | readonly number[];
+/** Minimal Vibration API (`navigator`). */
+interface VibrationHost {
+  /** Start (or with `0`/`[]`, cancel) a vibration. Returns whether it was accepted. */
+  vibrate(pattern: VibrationPattern): boolean;
+}
+/** Options for {@link useVibrate}. */
+interface UseVibrateOptions {
+  /**
+   * Default pattern used by `vibrate()`.
+   *
+   * @default []
+   */
+  readonly pattern?: MaybeRefOrGetter<VibrationPattern>;
+  /**
+   * Repeat the pattern every `interval` milliseconds until `stop`; `0`
+   * vibrates once.
+   *
+   * @default 0
+   */
+  readonly interval?: number;
+  /**
+   * Vibration capability for alternate runtimes and tests.
+   *
+   * @default window.navigator when it implements `vibrate`
+   */
+  readonly host?: MaybeRefOrGetter<VibrationHost | null | undefined>;
+  /**
+   * Timer host used for repetition.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive state and actions returned by {@link useVibrate}. */
+interface VibrateControls {
+  /** Whether the Vibration API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether a (possibly repeating) vibration started by this composable is active. */
+  readonly vibrating: Readonly<Ref<boolean>>;
+  /**
+   * Vibrate with `pattern` or the default pattern.
+   *
+   * @param pattern Pattern overriding the default.
+   * @returns Whether the platform accepted the pattern.
+   * @throws {RangeError} `[VIZE_COMPOSE_VIBRATE_INVALID_PATTERN]` for negative,
+   * fractional, or non-finite durations.
+   */
+  readonly vibrate: (pattern?: VibrationPattern) => boolean;
+  /** Cancel the vibration and any repetition. */
+  readonly stop: () => void;
+}
+/**
+ * Drive the Vibration API with validated, optionally repeating patterns.
+ *
+ * Patterns alternate vibration and pause durations. With `interval > 0`
+ * the pattern repeats until `stop` is called or the owning reactive scope
+ * stops, which also cancels an ongoing vibration.
+ *
+ * Server rendering: nothing vibrates and no timer starts; `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const { vibrate, stop } = useVibrate({ pattern: [200, 100, 200] });
+ * vibrate();
+ * ```
+ *
+ * @param options Default pattern, repetition, and capability.
+ * @default options {}
+ * @returns Vibration state and actions.
+ * @throws {RangeError} `[VIZE_COMPOSE_VIBRATE_INVALID_INTERVAL]` for a negative
+ * or non-finite interval.
+ */
+declare function useVibrate(options?: UseVibrateOptions): VibrateControls;
+//#endregion
+export { UseVibrateOptions, VibrateControls, VibrationHost, VibrationPattern, useVibrate };

package/dist/use-vibrate.mjs

@@ -0,0 +1,90 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, readonly, ref, toValue } from "vue";
+//#region src/use-vibrate.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function browserVibrationHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	return typeof navigator.vibrate === "function" ? navigator : void 0;
+}
+function validatePattern(pattern) {
+	const durations = typeof pattern === "number" ? [pattern] : pattern;
+	for (const duration of durations) if (!Number.isSafeInteger(duration) || duration < 0) throw new RangeError(`[VIZE_COMPOSE_VIBRATE_INVALID_PATTERN] vibration durations must be non-negative integers; received ${String(duration)}`);
+	return durations;
+}
+/**
+* Drive the Vibration API with validated, optionally repeating patterns.
+*
+* Patterns alternate vibration and pause durations. With `interval > 0`
+* the pattern repeats until `stop` is called or the owning reactive scope
+* stops, which also cancels an ongoing vibration.
+*
+* Server rendering: nothing vibrates and no timer starts; `supported` is false.
+*
+* @example
+* ```ts
+* const { vibrate, stop } = useVibrate({ pattern: [200, 100, 200] });
+* vibrate();
+* ```
+*
+* @param options Default pattern, repetition, and capability.
+* @default options {}
+* @returns Vibration state and actions.
+* @throws {RangeError} `[VIZE_COMPOSE_VIBRATE_INVALID_INTERVAL]` for a negative
+* or non-finite interval.
+*/
+function useVibrate(options = {}) {
+	const interval = options.interval ?? 0;
+	if (!Number.isFinite(interval) || interval < 0) throw new RangeError(`[VIZE_COMPOSE_VIBRATE_INVALID_INTERVAL] interval must be a non-negative finite number; received ${String(interval)}`);
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const vibrating = ref(false);
+	let handle;
+	let scheduled = false;
+	const resolveHost = () => options.host === void 0 ? browserVibrationHost() : toValue(options.host) ?? void 0;
+	const clearRepeat = () => {
+		if (scheduled) scheduler.clearTimeout(handle);
+		scheduled = false;
+	};
+	const stop = () => {
+		clearRepeat();
+		if (vibrating.value) resolveHost()?.vibrate(0);
+		vibrating.value = false;
+	};
+	const vibrate = (pattern) => {
+		const durations = validatePattern(pattern ?? toValue(options.pattern) ?? []);
+		const host = resolveHost();
+		clearRepeat();
+		if (!host) return false;
+		const accepted = host.vibrate(durations);
+		const total = durations.reduce((sum, duration) => sum + duration, 0);
+		vibrating.value = accepted && total > 0;
+		if (vibrating.value && interval > 0) {
+			const repeat = () => {
+				scheduled = false;
+				if (!vibrating.value) return;
+				vibrating.value = host.vibrate(durations);
+				if (vibrating.value) {
+					scheduled = true;
+					handle = scheduler.setTimeout(repeat, interval);
+				}
+			};
+			scheduled = true;
+			handle = scheduler.setTimeout(repeat, interval);
+		}
+		return accepted;
+	};
+	tryOnScopeDispose(stop);
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		vibrating: readonly(vibrating),
+		vibrate,
+		stop
+	};
+}
+//#endregion
+export { useVibrate };

package/dist/use-view-transition.d.mts

@@ -0,0 +1,106 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/use-view-transition.d.ts
+/** Minimal `ViewTransition`. */
+interface ViewTransitionLike {
+  /** Settles when the transition animation finished (or was skipped). */
+  readonly finished: Promise<void>;
+  /** Resolves when the animation is about to start; rejects when skipped. */
+  readonly ready: Promise<void>;
+  /** Settles when the update callback settled. */
+  readonly updateCallbackDone: Promise<void>;
+  /** Skip the animation; the update still runs. */
+  skipTransition(): void;
+}
+/** Argument accepted by `document.startViewTransition`. */
+type StartViewTransitionArgument = (() => unknown) | {
+  /** DOM update callback. */readonly update?: () => unknown; /** Active transition types (`:active-view-transition-type()`). */
+  readonly types?: string[];
+};
+/** Minimal document consumed by {@link useViewTransition}. */
+interface ViewTransitionDocumentHost {
+  /** Start a same-document view transition. */
+  startViewTransition(update?: StartViewTransitionArgument): ViewTransitionLike;
+}
+/** Options for {@link useViewTransition}. */
+interface UseViewTransitionOptions {
+  /**
+   * Document for alternate runtimes and tests.
+   *
+   * @default window.document when it implements startViewTransition
+   */
+  readonly document?: MaybeRefOrGetter<ViewTransitionDocumentHost | null | undefined>;
+  /**
+   * Run updates without a transition while reduced motion is preferred.
+   *
+   * @default true
+   */
+  readonly respectReducedMotion?: boolean;
+  /**
+   * Whether reduced motion is preferred.
+   *
+   * @default useReducedMotion() === "reduce"
+   */
+  readonly reducedMotion?: MaybeRefOrGetter<boolean>;
+}
+/** Per-call options of {@link ViewTransitionControls.start}. */
+interface ViewTransitionStartOptions {
+  /**
+   * Transition types. Runtimes without typed transitions fall back to an
+   * untyped transition.
+   *
+   * @default []
+   */
+  readonly types?: readonly string[];
+}
+/** Reactive state and actions returned by {@link useViewTransition}. */
+interface ViewTransitionControls {
+  /** Whether `document.startViewTransition` is available. */
+  readonly supported: ComputedRef<boolean>;
+  /**
+   * The running transition (the host object itself, not a readonly proxy, so
+   * native methods keep working), cleared once it finished.
+   */
+  readonly transition: ComputedRef<ViewTransitionLike | null>;
+  /** Whether a transition started by this composable is running. */
+  readonly isTransitioning: Readonly<ShallowRef<boolean>>;
+  /**
+   * Run `update` inside a view transition, or directly when unsupported or
+   * reduced motion is preferred.
+   *
+   * @param update DOM update; may return a value or a promise.
+   * @param options Transition types.
+   * @default options {}
+   * @returns Resolves with the update result once the DOM was updated (the
+   * animation may still run; await `transition.value?.finished` for it);
+   * rejects with the update error.
+   */
+  readonly start: <Result>(update: () => Result | PromiseLike<Result>, options?: ViewTransitionStartOptions) => Promise<Result>;
+  /** Skip the running transition's animation. */
+  readonly skip: () => void;
+}
+/**
+ * Animate DOM updates with the View Transition API.
+ *
+ * Starting a new transition skips the running one (browser behavior). The
+ * running transition is skipped when the owning reactive scope stops.
+ *
+ * Server rendering: `start` runs the update directly; `supported` and
+ * `isTransitioning` are false.
+ *
+ * @example
+ * ```ts
+ * const { start } = useViewTransition();
+ * await start(async () => {
+ *   page.value = next;
+ *   await nextTick();
+ * }, { types: ["forward"] });
+ * ```
+ *
+ * @param options Document host and reduced-motion policy.
+ * @default options {}
+ * @returns Transition state and actions.
+ */
+declare function useViewTransition(options?: UseViewTransitionOptions): ViewTransitionControls;
+//#endregion
+export { StartViewTransitionArgument, UseViewTransitionOptions, ViewTransitionControls, ViewTransitionDocumentHost, ViewTransitionLike, ViewTransitionStartOptions, useViewTransition };

package/dist/use-view-transition.mjs

@@ -0,0 +1,101 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { useReducedMotion } from "./media-query.mjs";
+import { computed, hasInjectionContext, readonly, shallowRef, toValue, watchPostEffect } from "vue";
+//#region src/use-view-transition.ts
+function browserDocument() {
+	return typeof window !== "undefined" && typeof window.document.startViewTransition === "function" ? window.document : void 0;
+}
+function ignore() {}
+/**
+* Animate DOM updates with the View Transition API.
+*
+* Starting a new transition skips the running one (browser behavior). The
+* running transition is skipped when the owning reactive scope stops.
+*
+* Server rendering: `start` runs the update directly; `supported` and
+* `isTransitioning` are false.
+*
+* @example
+* ```ts
+* const { start } = useViewTransition();
+* await start(async () => {
+*   page.value = next;
+*   await nextTick();
+* }, { types: ["forward"] });
+* ```
+*
+* @param options Document host and reduced-motion policy.
+* @default options {}
+* @returns Transition state and actions.
+*/
+function useViewTransition(options = {}) {
+	const transition = shallowRef(null);
+	const isTransitioning = shallowRef(false);
+	const respect = options.respectReducedMotion ?? true;
+	const preference = respect && options.reducedMotion === void 0 ? useReducedMotion() : void 0;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveDocument = () => !hydrated.value ? void 0 : options.document === void 0 ? browserDocument() : toValue(options.document) ?? void 0;
+	const prefersReducedMotion = () => {
+		if (!respect) return false;
+		return preference ? preference.value === "reduce" : toValue(options.reducedMotion) === true;
+	};
+	const begin = (host, run, types) => {
+		if (types.length === 0) return host.startViewTransition(run);
+		try {
+			return host.startViewTransition({
+				update: run,
+				types: [...types]
+			});
+		} catch {
+			return host.startViewTransition(run);
+		}
+	};
+	const start = async (update, startOptions = {}) => {
+		const host = resolveDocument();
+		if (!host || prefersReducedMotion()) return update();
+		let run = async () => void 0;
+		const outcome = new Promise((resolve, reject) => {
+			run = async () => {
+				try {
+					resolve(await update());
+				} catch (cause) {
+					reject(cause);
+					throw cause;
+				}
+			};
+		});
+		let current;
+		try {
+			current = begin(host, run, startOptions.types ?? []);
+		} catch {
+			return update();
+		}
+		transition.value = current;
+		isTransitioning.value = true;
+		const clear = () => {
+			if (transition.value !== current) return;
+			transition.value = null;
+			isTransitioning.value = false;
+		};
+		current.ready.catch(ignore);
+		current.updateCallbackDone.catch(ignore);
+		current.finished.then(clear, clear);
+		return outcome;
+	};
+	const skip = () => {
+		transition.value?.skipTransition();
+	};
+	tryOnScopeDispose(skip);
+	return {
+		supported: computed(() => resolveDocument() !== void 0),
+		transition: computed(() => transition.value),
+		isTransitioning: readonly(isTransitioning),
+		start,
+		skip
+	};
+}
+//#endregion
+export { useViewTransition };

package/dist/use-visual-viewport.d.mts

@@ -0,0 +1,105 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-visual-viewport.d.ts
+/** Structural `VisualViewport` observed by {@link useVisualViewport}. */
+interface VisualViewportHost extends EventTarget {
+  /** Visible width in CSS pixels. */
+  readonly width: number;
+  /** Visible height in CSS pixels (shrinks when an on-screen keyboard overlays the page). */
+  readonly height: number;
+  /** Offset of the visual viewport from the layout viewport's top edge. */
+  readonly offsetTop: number;
+  /** Offset of the visual viewport from the layout viewport's left edge. */
+  readonly offsetLeft: number;
+  /** Pinch-zoom scale factor. */
+  readonly scale: number;
+}
+/** Structural VirtualKeyboard API (`navigator.virtualKeyboard`). */
+interface VirtualKeyboardHost extends EventTarget {
+  /** Whether the keyboard overlays content instead of resizing the viewport. */
+  overlaysContent: boolean;
+  /** Keyboard rectangle in CSS pixels. */
+  readonly boundingRect: {
+    readonly height: number;
+  };
+}
+/** Window-like capability read by {@link useVisualViewport}. */
+interface VisualViewportWindowHost {
+  /** Layout viewport height. */
+  readonly innerHeight: number;
+  /** Visual viewport, when the engine supports it. */
+  readonly visualViewport?: VisualViewportHost | null;
+  /** Navigator that may expose the VirtualKeyboard API as `virtualKeyboard`. */
+  readonly navigator?: object;
+}
+/** Options for {@link useVisualViewport}. */
+interface UseVisualViewportOptions {
+  /**
+   * Minimum occluded height (CSS px) reported as an open keyboard, filtering
+   * browser toolbars that collapse while scrolling.
+   *
+   * @default 120
+   */
+  readonly keyboardThreshold?: number;
+  /**
+   * Opt in to `navigator.virtualKeyboard.overlaysContent = true` (Chromium) so
+   * the keyboard height comes from the VirtualKeyboard API and the layout
+   * viewport no longer resizes. The previous value is restored on cleanup.
+   *
+   * @default false
+   */
+  readonly overlaysContent?: boolean;
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<VisualViewportWindowHost | null | undefined>;
+}
+/** Reactive viewport geometry returned by {@link useVisualViewport}. */
+interface VisualViewportControls {
+  /** Visual viewport width (0 on the server). */
+  readonly width: Readonly<Ref<number>>;
+  /** Visual viewport height (0 on the server). */
+  readonly height: Readonly<Ref<number>>;
+  /** Visual viewport top offset within the layout viewport. */
+  readonly offsetTop: Readonly<Ref<number>>;
+  /** Visual viewport left offset within the layout viewport. */
+  readonly offsetLeft: Readonly<Ref<number>>;
+  /** Pinch-zoom scale (1 on the server). */
+  readonly scale: Readonly<Ref<number>>;
+  /** Height of the bottom area hidden by an on-screen keyboard, in CSS px. */
+  readonly keyboardHeight: Readonly<Ref<number>>;
+  /** Whether `keyboardHeight` exceeds `keyboardThreshold`. */
+  readonly keyboardOpen: ComputedRef<boolean>;
+  /** Whether a VisualViewport (or VirtualKeyboard) capability is attached. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+}
+/**
+ * Track the visual viewport and on-screen keyboard.
+ *
+ * On mobile browsers the visual viewport shrinks (or scrolls) when a virtual
+ * keyboard opens while the layout viewport stays put; `keyboardHeight` is the
+ * occluded bottom area (`innerHeight - height - offsetTop`), or the
+ * VirtualKeyboard API rectangle when `overlaysContent` is enabled. Pin
+ * toolbars above the keyboard with `bottom: calc(var(--kb, 0px))` bound to it.
+ *
+ * Server rendering reports zeros (scale 1) and attaches nothing; inside a
+ * component the host attaches after mount, so hydration renders the same
+ * zeros first. Listeners
+ * (`resize`, `scroll`, `geometrychange`) are passive and removed with the
+ * owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * const { keyboardHeight, keyboardOpen } = useVisualViewport();
+ * const toolbarStyle = computed(() => ({ bottom: `${keyboardHeight.value}px` }));
+ * ```
+ *
+ * @param options Keyboard threshold, VirtualKeyboard opt-in, and capability.
+ * @default options {}
+ * @returns Reactive viewport geometry and keyboard state.
+ */
+declare function useVisualViewport(options?: UseVisualViewportOptions): VisualViewportControls;
+//#endregion
+export { UseVisualViewportOptions, VirtualKeyboardHost, VisualViewportControls, VisualViewportHost, VisualViewportWindowHost, useVisualViewport };