@vizejs/composable 0.426.3 → 0.428.0

package/dist/standard-schema-DmNgFVK5.d.mts

@@ -0,0 +1,107 @@
+//#region src/standard-schema.d.ts
+/**
+ * Minimal, dependency-free Standard Schema v1 interop.
+ *
+ * Any validation library implementing the `~standard` protocol (Zod,
+ * Valibot, ArkType, Effect Schema, …) satisfies {@link StandardSchemaV1}
+ * structurally; nothing from those libraries is imported.
+ */
+/** One segment of a Standard Schema issue path. */
+type StandardSchemaPathSegment = PropertyKey | {
+  readonly key: PropertyKey;
+};
+/** One validation issue reported by a Standard Schema. */
+interface StandardSchemaIssue {
+  /** Human-readable message. */
+  readonly message: string;
+  /** Location of the issue inside the validated value; absent for root issues. */
+  readonly path?: readonly StandardSchemaPathSegment[] | undefined;
+}
+/** Successful Standard Schema result. */
+interface StandardSchemaSuccess<Output> {
+  /** Parsed (possibly transformed) output. */
+  readonly value: Output;
+  /** Always absent on success. */
+  readonly issues?: undefined;
+}
+/** Failed Standard Schema result. */
+interface StandardSchemaFailure {
+  /** Non-empty list of issues. */
+  readonly issues: readonly StandardSchemaIssue[];
+}
+/** Result of `~standard.validate`. */
+type StandardSchemaResult<Output> = StandardSchemaSuccess<Output> | StandardSchemaFailure;
+/** The `~standard` property of a Standard Schema v1 validator. */
+interface StandardSchemaProps<Input, Output> {
+  /** Protocol version. */
+  readonly version: 1;
+  /** Library that produced the schema. */
+  readonly vendor: string;
+  /** Validate an unknown value, synchronously or asynchronously. */
+  readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+  /** Type-only carrier of the input and output types. */
+  readonly types?: {
+    readonly input: Input;
+    readonly output: Output;
+  } | undefined;
+}
+/** Any Standard Schema v1 validator. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** Standard Schema protocol entry point. */
+  readonly "~standard": StandardSchemaProps<Input, Output>;
+}
+/** Input type accepted by a Standard Schema. */
+type InferStandardSchemaInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+/** Output type produced by a Standard Schema. */
+type InferStandardSchemaOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+/** Issue normalized to a dotted path (`""` for the root). */
+interface NormalizedSchemaIssue {
+  /** Dotted path such as `address.city` or `items.0.name`; `""` for the root. */
+  readonly path: string;
+  /** Human-readable message. */
+  readonly message: string;
+}
+/** Normalized outcome of {@link validateStandardSchema}. */
+type NormalizedSchemaResult<Output> = {
+  /** Validation passed. */readonly status: "valid"; /** Parsed output. */
+  readonly value: Output;
+} | {
+  /** Validation failed. */readonly status: "invalid"; /** Issues with dotted paths, in schema order. */
+  readonly issues: readonly NormalizedSchemaIssue[];
+};
+/**
+ * Whether a value implements the Standard Schema v1 protocol.
+ *
+ * @param candidate Value to test.
+ * @returns Whether `candidate["~standard"].validate` is callable with version 1.
+ */
+declare function isStandardSchema(candidate: unknown): candidate is StandardSchemaV1;
+/**
+ * Convert a Standard Schema issue path to a dotted path.
+ *
+ * `{ key }` segments are unwrapped; symbols use their description.
+ *
+ * @param path Issue path.
+ * @returns Dotted path, `""` for the root.
+ */
+declare function formatSchemaPath(path: readonly StandardSchemaPathSegment[] | undefined): string;
+/**
+ * Validate a value with a Standard Schema and normalize the result.
+ *
+ * Synchronous and asynchronous schemas are handled identically. Throwing
+ * schemas propagate their error. Pure: safe on the server.
+ *
+ * @example
+ * ```ts
+ * const result = await validateStandardSchema(zodSchema, formValues);
+ * if (result.status === "invalid") console.log(result.issues);
+ * ```
+ *
+ * @typeParam Output Schema output type.
+ * @param schema Standard Schema v1 validator.
+ * @param value Value to validate.
+ * @returns The normalized result.
+ */
+declare function validateStandardSchema<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<NormalizedSchemaResult<Output>>;
+//#endregion
+export { StandardSchemaFailure as a, StandardSchemaProps as c, StandardSchemaV1 as d, formatSchemaPath as f, NormalizedSchemaResult as i, StandardSchemaResult as l, validateStandardSchema as m, InferStandardSchemaOutput as n, StandardSchemaIssue as o, isStandardSchema as p, NormalizedSchemaIssue as r, StandardSchemaPathSegment as s, InferStandardSchemaInput as t, StandardSchemaSuccess as u };

package/dist/standard-schema.d.mts

@@ -0,0 +1,2 @@
+import { a as StandardSchemaFailure, c as StandardSchemaProps, d as StandardSchemaV1, f as formatSchemaPath, i as NormalizedSchemaResult, l as StandardSchemaResult, m as validateStandardSchema, n as InferStandardSchemaOutput, o as StandardSchemaIssue, p as isStandardSchema, r as NormalizedSchemaIssue, s as StandardSchemaPathSegment, t as InferStandardSchemaInput, u as StandardSchemaSuccess } from "./standard-schema-DmNgFVK5.mjs";
+export { InferStandardSchemaInput, InferStandardSchemaOutput, NormalizedSchemaIssue, NormalizedSchemaResult, StandardSchemaFailure, StandardSchemaIssue, StandardSchemaPathSegment, StandardSchemaProps, StandardSchemaResult, StandardSchemaSuccess, StandardSchemaV1, formatSchemaPath, isStandardSchema, validateStandardSchema };

package/dist/standard-schema.mjs

@@ -0,0 +1,60 @@
+//#region src/standard-schema.ts
+/**
+* Whether a value implements the Standard Schema v1 protocol.
+*
+* @param candidate Value to test.
+* @returns Whether `candidate["~standard"].validate` is callable with version 1.
+*/
+function isStandardSchema(candidate) {
+	if (typeof candidate !== "object" && typeof candidate !== "function" || candidate === null) return false;
+	const props = Reflect.get(candidate, "~standard");
+	return typeof props === "object" && props !== null && Reflect.get(props, "version") === 1 && typeof Reflect.get(props, "validate") === "function";
+}
+/**
+* Convert a Standard Schema issue path to a dotted path.
+*
+* `{ key }` segments are unwrapped; symbols use their description.
+*
+* @param path Issue path.
+* @returns Dotted path, `""` for the root.
+*/
+function formatSchemaPath(path) {
+	if (!path) return "";
+	return path.map((segment) => {
+		const key = typeof segment === "object" ? segment.key : segment;
+		return typeof key === "symbol" ? key.description ?? "" : String(key);
+	}).join(".");
+}
+/**
+* Validate a value with a Standard Schema and normalize the result.
+*
+* Synchronous and asynchronous schemas are handled identically. Throwing
+* schemas propagate their error. Pure: safe on the server.
+*
+* @example
+* ```ts
+* const result = await validateStandardSchema(zodSchema, formValues);
+* if (result.status === "invalid") console.log(result.issues);
+* ```
+*
+* @typeParam Output Schema output type.
+* @param schema Standard Schema v1 validator.
+* @param value Value to validate.
+* @returns The normalized result.
+*/
+async function validateStandardSchema(schema, value) {
+	const result = await schema["~standard"].validate(value);
+	if (result.issues === void 0) return {
+		status: "valid",
+		value: result.value
+	};
+	return {
+		status: "invalid",
+		issues: result.issues.map((issue) => ({
+			path: formatSchemaPath(issue.path),
+			message: issue.message
+		}))
+	};
+}
+//#endregion
+export { formatSchemaPath, isStandardSchema, validateStandardSchema };

package/dist/swipe.d.mts

@@ -0,0 +1,125 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { Point } from "./mouse.mjs";
+import { PointerKind } from "./pointer.mjs";
+import { ComputedRef, Ref } from "vue";
+
+//#region src/swipe.d.ts
+/** Dominant direction of a swipe gesture. `"none"` below the threshold. */
+type SwipeDirection = "up" | "down" | "left" | "right" | "none";
+/** Callbacks shared by {@link useSwipe} and {@link usePointerSwipe}. */
+interface SwipeCallbacks<GestureEvent extends Event> {
+  /**
+   * Called when a gesture starts.
+   *
+   * @default undefined
+   */
+  readonly onSwipeStart?: (event: GestureEvent) => void;
+  /**
+   * Called on every move after the threshold has been exceeded.
+   *
+   * @default undefined
+   */
+  readonly onSwipe?: (event: GestureEvent) => void;
+  /**
+   * Called when a gesture that exceeded the threshold ends.
+   *
+   * @default undefined
+   */
+  readonly onSwipeEnd?: (event: GestureEvent, direction: SwipeDirection) => void;
+}
+/** Options for {@link useSwipe}. */
+interface UseSwipeOptions extends SwipeCallbacks<TouchEvent> {
+  /**
+   * Minimum travel in CSS pixels before a gesture counts as a swipe.
+   *
+   * @default 50
+   */
+  readonly threshold?: number;
+  /**
+   * Register passive touch listeners. Set to `false` to call
+   * `preventDefault()` on moves while swiping (for example to block
+   * pull-to-refresh).
+   *
+   * @default true
+   */
+  readonly passive?: boolean;
+}
+/** Reactive gesture state shared by the swipe composables. */
+interface SwipeControls {
+  /** Whether a gesture past the threshold is in progress. */
+  readonly isSwiping: Readonly<Ref<boolean>>;
+  /** Dominant direction of the current (or last) gesture. */
+  readonly direction: ComputedRef<SwipeDirection>;
+  /** Gesture start coordinates. */
+  readonly coordsStart: Readonly<Point>;
+  /** Latest gesture coordinates. */
+  readonly coordsEnd: Readonly<Point>;
+  /** `start.x - end.x`: positive when moving left. */
+  readonly lengthX: ComputedRef<number>;
+  /** `start.y - end.y`: positive when moving up. */
+  readonly lengthY: ComputedRef<number>;
+  /** Remove listeners. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Classify a displacement into a {@link SwipeDirection}.
+ *
+ * Pure helper shared by the swipe composables and usable for custom gesture
+ * recognizers.
+ *
+ * @param lengthX `start.x - end.x`.
+ * @param lengthY `start.y - end.y`.
+ * @param threshold Minimum travel before a direction is reported.
+ * @returns The dominant axis direction, or `"none"`.
+ */
+declare function swipeDirection(lengthX: number, lengthY: number, threshold: number): SwipeDirection;
+/**
+ * Detect touch swipes on an element.
+ *
+ * Tracks the first touch point from `touchstart` through `touchend`/
+ * `touchcancel`. Direction is derived from the dominant axis once the travel
+ * exceeds `threshold`. Server renders expose zeroed coordinates and
+ * `direction: "none"`; listeners are removed with the owning scope.
+ *
+ * @param target Reactive element target.
+ * @param options Threshold, passivity, and callbacks.
+ * @default options {}
+ * @returns Reactive gesture state and stop control.
+ */
+declare function useSwipe(target: MaybeElementTarget, options?: UseSwipeOptions): SwipeControls;
+/** Options for {@link usePointerSwipe}. */
+interface UsePointerSwipeOptions extends SwipeCallbacks<PointerEvent> {
+  /**
+   * Minimum travel in CSS pixels before a gesture counts as a swipe.
+   *
+   * @default 50
+   */
+  readonly threshold?: number;
+  /**
+   * Device kinds that may start a gesture.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+  /**
+   * Suppress text selection on the element while a gesture is active.
+   *
+   * @default false
+   */
+  readonly disableTextSelect?: boolean;
+}
+/**
+ * Detect swipes from any pointer device (mouse, touch, pen).
+ *
+ * Captures the pointer on `pointerdown` so moves outside the element still
+ * count, and ignores secondary pointers during a gesture. Shares the state
+ * shape and SSR defaults of {@link useSwipe}.
+ *
+ * @param target Reactive element target.
+ * @param options Threshold, device filter, selection handling, and callbacks.
+ * @default options {}
+ * @returns Reactive gesture state and stop control.
+ */
+declare function usePointerSwipe(target: MaybeElementTarget, options?: UsePointerSwipeOptions): SwipeControls;
+//#endregion
+export { SwipeCallbacks, SwipeControls, SwipeDirection, UsePointerSwipeOptions, UseSwipeOptions, swipeDirection, usePointerSwipe, useSwipe };

package/dist/swipe.mjs

@@ -0,0 +1,225 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { toPointerKind } from "./pointer.mjs";
+import { computed, readonly, ref, shallowReactive, shallowReadonly, watch } from "vue";
+//#region src/swipe.ts
+/**
+* Classify a displacement into a {@link SwipeDirection}.
+*
+* Pure helper shared by the swipe composables and usable for custom gesture
+* recognizers.
+*
+* @param lengthX `start.x - end.x`.
+* @param lengthY `start.y - end.y`.
+* @param threshold Minimum travel before a direction is reported.
+* @returns The dominant axis direction, or `"none"`.
+*/
+function swipeDirection(lengthX, lengthY, threshold) {
+	if (Math.max(Math.abs(lengthX), Math.abs(lengthY)) < threshold) return "none";
+	if (Math.abs(lengthX) > Math.abs(lengthY)) return lengthX > 0 ? "left" : "right";
+	return lengthY > 0 ? "up" : "down";
+}
+function createGesture(threshold) {
+	const coordsStart = shallowReactive({
+		x: 0,
+		y: 0
+	});
+	const coordsEnd = shallowReactive({
+		x: 0,
+		y: 0
+	});
+	const swiping = ref(false);
+	const lengthX = computed(() => coordsStart.x - coordsEnd.x);
+	const lengthY = computed(() => coordsStart.y - coordsEnd.y);
+	const direction = computed(() => swipeDirection(lengthX.value, lengthY.value, threshold));
+	return {
+		controls: {
+			isSwiping: readonly(swiping),
+			direction,
+			coordsStart: shallowReadonly(coordsStart),
+			coordsEnd: shallowReadonly(coordsEnd),
+			lengthX,
+			lengthY
+		},
+		begin: (point) => {
+			coordsStart.x = point.x;
+			coordsStart.y = point.y;
+			coordsEnd.x = point.x;
+			coordsEnd.y = point.y;
+		},
+		move: (point) => {
+			coordsEnd.x = point.x;
+			coordsEnd.y = point.y;
+			if (!swiping.value && direction.value !== "none") swiping.value = true;
+			return swiping.value;
+		},
+		reset: () => {
+			swiping.value = false;
+		},
+		swiping
+	};
+}
+/**
+* Detect touch swipes on an element.
+*
+* Tracks the first touch point from `touchstart` through `touchend`/
+* `touchcancel`. Direction is derived from the dominant axis once the travel
+* exceeds `threshold`. Server renders expose zeroed coordinates and
+* `direction: "none"`; listeners are removed with the owning scope.
+*
+* @param target Reactive element target.
+* @param options Threshold, passivity, and callbacks.
+* @default options {}
+* @returns Reactive gesture state and stop control.
+*/
+function useSwipe(target, options = {}) {
+	const gesture = createGesture(options.threshold ?? 50);
+	const passive = options.passive ?? true;
+	const firstTouch = (event) => {
+		const touch = event.touches[0] ?? event.changedTouches[0];
+		return touch ? {
+			x: touch.clientX,
+			y: touch.clientY
+		} : null;
+	};
+	const onStart = (event) => {
+		if (!isTouchEvent(event)) return;
+		const point = firstTouch(event);
+		if (!point || event.touches.length > 1) return;
+		gesture.begin(point);
+		options.onSwipeStart?.(event);
+	};
+	const onMove = (event) => {
+		if (!isTouchEvent(event)) return;
+		const point = firstTouch(event);
+		if (!point) return;
+		if (!gesture.move(point)) return;
+		if (!passive && event.cancelable) event.preventDefault();
+		options.onSwipe?.(event);
+	};
+	const onEnd = (event) => {
+		if (!isTouchEvent(event)) return;
+		if (gesture.swiping.value) options.onSwipeEnd?.(event, gesture.controls.direction.value);
+		gesture.reset();
+	};
+	const stopWatch = watch(() => resolveElement(target), (element, _previous, onCleanup) => {
+		if (!element) return;
+		const listenerOptions = { passive };
+		element.addEventListener("touchstart", onStart, { passive: true });
+		element.addEventListener("touchmove", onMove, listenerOptions);
+		element.addEventListener("touchend", onEnd, { passive: true });
+		element.addEventListener("touchcancel", onEnd, { passive: true });
+		onCleanup(() => {
+			element.removeEventListener("touchstart", onStart);
+			element.removeEventListener("touchmove", onMove);
+			element.removeEventListener("touchend", onEnd);
+			element.removeEventListener("touchcancel", onEnd);
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return {
+		...gesture.controls,
+		stop
+	};
+}
+/**
+* Detect swipes from any pointer device (mouse, touch, pen).
+*
+* Captures the pointer on `pointerdown` so moves outside the element still
+* count, and ignores secondary pointers during a gesture. Shares the state
+* shape and SSR defaults of {@link useSwipe}.
+*
+* @param target Reactive element target.
+* @param options Threshold, device filter, selection handling, and callbacks.
+* @default options {}
+* @returns Reactive gesture state and stop control.
+*/
+function usePointerSwipe(target, options = {}) {
+	const gesture = createGesture(options.threshold ?? 50);
+	const pointerTypes = options.pointerTypes ?? [
+		"mouse",
+		"touch",
+		"pen"
+	];
+	let activePointer = null;
+	const accepts = (event) => {
+		if (!isPointerEvent(event)) return false;
+		const kind = toPointerKind(event.pointerType);
+		return kind !== null && pointerTypes.includes(kind);
+	};
+	const setSelection = (element, disabled) => {
+		if (!options.disableTextSelect || !hasStyle(element)) return;
+		element.style.setProperty("user-select", disabled ? "none" : "");
+		element.style.setProperty("-webkit-user-select", disabled ? "none" : "");
+	};
+	const stopWatch = watch(() => resolveElement(target), (element, _previous, onCleanup) => {
+		if (!element) return;
+		const onDown = (event) => {
+			if (!accepts(event) || activePointer !== null) return;
+			if (event.pointerType === "mouse" && event.button !== 0) return;
+			activePointer = event.pointerId;
+			if (hasPointerCapture(element)) element.setPointerCapture(event.pointerId);
+			gesture.begin({
+				x: event.clientX,
+				y: event.clientY
+			});
+			setSelection(element, true);
+			options.onSwipeStart?.(event);
+		};
+		const onMove = (event) => {
+			if (!accepts(event) || event.pointerId !== activePointer) return;
+			if (gesture.move({
+				x: event.clientX,
+				y: event.clientY
+			})) options.onSwipe?.(event);
+		};
+		const onUp = (event) => {
+			if (!accepts(event) || event.pointerId !== activePointer) return;
+			activePointer = null;
+			if (hasPointerCapture(element)) element.releasePointerCapture(event.pointerId);
+			if (gesture.swiping.value) options.onSwipeEnd?.(event, gesture.controls.direction.value);
+			gesture.reset();
+			setSelection(element, false);
+		};
+		element.addEventListener("pointerdown", onDown, { passive: true });
+		element.addEventListener("pointermove", onMove, { passive: true });
+		element.addEventListener("pointerup", onUp, { passive: true });
+		element.addEventListener("pointercancel", onUp, { passive: true });
+		onCleanup(() => {
+			element.removeEventListener("pointerdown", onDown);
+			element.removeEventListener("pointermove", onMove);
+			element.removeEventListener("pointerup", onUp);
+			element.removeEventListener("pointercancel", onUp);
+			activePointer = null;
+			gesture.reset();
+			setSelection(element, false);
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return {
+		...gesture.controls,
+		stop
+	};
+}
+function isTouchEvent(event) {
+	return "touches" in event && "changedTouches" in event;
+}
+function isPointerEvent(event) {
+	return "pointerId" in event && "pointerType" in event;
+}
+function hasPointerCapture(element) {
+	return typeof element.setPointerCapture === "function";
+}
+function hasStyle(element) {
+	return "style" in element && typeof element.style === "object" && element.style !== null;
+}
+//#endregion
+export { swipeDirection, usePointerSwipe, useSwipe };

package/dist/sync-ref.d.mts

@@ -0,0 +1,80 @@
+import { Ref } from "vue";
+
+//#region src/sync-ref.d.ts
+/** Which way {@link syncRef} copies values. */
+type SyncRefDirection = "ltr" | "rtl" | "both";
+/** Converters required by {@link syncRef} for the chosen direction. */
+type SyncRefTransform<Left, Right, Direction extends SyncRefDirection> = Direction extends "ltr" ? {
+  readonly ltr: (left: Left) => Right;
+} : Direction extends "rtl" ? {
+  readonly rtl: (right: Right) => Left;
+} : {
+  readonly ltr: (left: Left) => Right;
+  readonly rtl: (right: Right) => Left;
+};
+/** Whether two types are mutually assignable (identical for syncing purposes). */
+type SameType<Left, Right> = [Left] extends [Right] ? [Right] extends [Left] ? true : false : false;
+/** Options for {@link syncRef}; `transform` is required when the ref types differ. */
+type SyncRefOptions<Left, Right, Direction extends SyncRefDirection = "both"> = SyncRefBaseOptions<Direction> & (SameType<Left, Right> extends true ? {
+  /**
+   * Converters between the two refs.
+   *
+   * @default identity
+   */
+  readonly transform?: Partial<SyncRefTransform<Left, Right, Direction>>;
+} : {
+  /** Converters between the two refs (required: the types differ). */readonly transform: SyncRefTransform<Left, Right, Direction>;
+});
+/** Direction and timing options shared by every {@link syncRef} call. */
+interface SyncRefBaseOptions<Direction extends SyncRefDirection = "both"> {
+  /**
+   * `"ltr"` copies left to right, `"rtl"` right to left, `"both"` both ways.
+   *
+   * @default "both"
+   */
+  readonly direction?: Direction;
+  /**
+   * Watch flush timing.
+   *
+   * @default "sync"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+  /**
+   * Watch nested changes.
+   *
+   * @default false
+   */
+  readonly deep?: boolean;
+  /**
+   * Copy once right away (left wins for `"both"`/`"ltr"`, right for `"rtl"`).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+}
+/**
+ * Keep two refs in sync, optionally converting between their types.
+ *
+ * The option type is computed from both ref types: converters may be
+ * omitted only when the types are identical, and exactly the converters the
+ * direction needs are required otherwise. A re-entrancy guard prevents
+ * ping-pong when converters are not exact inverses. Watchers follow the
+ * owning reactive scope; SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const celsius = ref(20);
+ * const label = ref("");
+ * syncRef(celsius, label, {
+ *   transform: { ltr: (c) => `${c}°C`, rtl: (text) => Number.parseFloat(text) },
+ * });
+ * ```
+ *
+ * @param left First ref.
+ * @param right Second ref.
+ * @param options Direction, timing, and converters.
+ * @returns Stops every sync watcher.
+ */
+declare function syncRef<Left, Right = Left, const Direction extends SyncRefDirection = "both">(left: Ref<Left>, right: Ref<Right>, ...options: SameType<Left, Right> extends true ? [options?: SyncRefOptions<Left, Right, Direction>] : [options: SyncRefOptions<Left, Right, Direction>]): () => void;
+//#endregion
+export { SyncRefBaseOptions, SyncRefDirection, SyncRefOptions, SyncRefTransform, syncRef };

package/dist/sync-ref.mjs

@@ -0,0 +1,43 @@
+import { watch } from "vue";
+//#region src/sync-ref.ts
+function syncRef(left, right, options = {}) {
+	const direction = options.direction ?? "both";
+	const toRight = options.transform?.ltr ?? ((value) => value);
+	const toLeft = options.transform?.rtl ?? ((value) => value);
+	const watchOptions = {
+		flush: options.flush ?? "sync",
+		deep: options.deep ?? false
+	};
+	const stops = [];
+	let syncing = false;
+	const guarded = (copy) => {
+		if (syncing) return;
+		syncing = true;
+		try {
+			copy();
+		} finally {
+			syncing = false;
+		}
+	};
+	if (direction !== "rtl") stops.push(watch(left, (value) => {
+		guarded(() => {
+			right.value = toRight(value);
+		});
+	}, {
+		...watchOptions,
+		immediate: options.immediate ?? true
+	}));
+	if (direction !== "ltr") stops.push(watch(right, (value) => {
+		guarded(() => {
+			left.value = toLeft(value);
+		});
+	}, {
+		...watchOptions,
+		immediate: direction === "rtl" && (options.immediate ?? true)
+	}));
+	return () => {
+		for (const stop of stops) stop();
+	};
+}
+//#endregion
+export { syncRef };

package/dist/text-selection.d.mts

@@ -0,0 +1,46 @@
+import { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/text-selection.d.ts
+/** Document-like capability observed by {@link useTextSelection}. */
+interface TextSelectionHost extends EventTarget {
+  /** Current selection. */
+  getSelection(): Selection | null;
+}
+/** Options for {@link useTextSelection}. */
+interface UseTextSelectionOptions {
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<TextSelectionHost | null | undefined>;
+}
+/** Reactive selection state returned by {@link useTextSelection}. */
+interface TextSelectionControls {
+  /** Current `Selection` object; `null` during server rendering. */
+  readonly selection: Readonly<ShallowRef<Selection | null>>;
+  /** Selected text. Empty during server rendering. */
+  readonly text: ComputedRef<string>;
+  /** Selected ranges. */
+  readonly ranges: ComputedRef<readonly Range[]>;
+  /** Client rectangles of each selected range. */
+  readonly rects: ComputedRef<readonly DOMRect[]>;
+}
+/**
+ * Track the document text selection.
+ *
+ * Re-reads the selection on every `selectionchange`. Because the platform
+ * mutates the same `Selection` object in place, a revision counter is used to
+ * invalidate the derived `text`, `ranges`, and `rects`. Server renders expose
+ * an empty selection; the listener is removed with the owning scope.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param options Document capability.
+ * @default options {}
+ * @returns Reactive selection, text, ranges, and rectangles.
+ */
+declare function useTextSelection(options?: UseTextSelectionOptions): TextSelectionControls;
+//#endregion
+export { TextSelectionControls, TextSelectionHost, UseTextSelectionOptions, useTextSelection };