@vizejs/ui 0.347.7 → 0.350.2

package/dist/focus-guards-DhMPQAT8.mjs

@@ -0,0 +1,299 @@
+import { a as focusableElements, c as documentOrder, i as focusElement, o as isUsableTarget, p as surfaceErrors, s as capture, t as containsComposed } from "./focus-scope-dom-DBwNEWxG.mjs";
+import { getCurrentInstance, getCurrentScope, onMounted, onScopeDispose, shallowReadonly, shallowRef, toValue, watch } from "vue";
+//#region src/focus-guards-internal.ts
+const optionDiagnostic = "VIZE_UI_FOCUS_GUARDS_OPTION";
+/** Resolve an event target without relying on the current realm's Element constructor. */
+function eventElement(value) {
+	const candidate = value;
+	return candidate?.nodeType === 1 && typeof candidate.getRootNode === "function" ? candidate : null;
+}
+function readBoolean(source, name, fallback) {
+	const value = toValue(source);
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") throw new TypeError(`${optionDiagnostic}: ${name} must resolve to a boolean`);
+	return value;
+}
+function readRoot(source) {
+	const value = toValue(source);
+	if (value === void 0 || value === null) return null;
+	const candidate = value;
+	if (candidate.nodeType !== 1 || !candidate.ownerDocument) throw new TypeError(`${optionDiagnostic}: root must resolve to an Element or null`);
+	return value;
+}
+function readBranches(source, document) {
+	const value = toValue(source);
+	if (value === void 0 || value === null) return [];
+	if (!Array.isArray(value)) throw new TypeError(`${optionDiagnostic}: branches must resolve to a readonly Element array`);
+	const branches = value;
+	for (const branch of branches) {
+		if (branch?.nodeType !== 1 || !branch.ownerDocument) throw new TypeError(`${optionDiagnostic}: every branch must be an Element`);
+		if (document && branch.ownerDocument !== document) throw new TypeError(`${optionDiagnostic}: branches must share the root Document`);
+	}
+	return [...new Set(branches)];
+}
+function readTarget(value) {
+	if (value === void 0 || value === null) return null;
+	const candidate = value;
+	if (candidate.nodeType !== 1 || candidate.namespaceURI !== "http://www.w3.org/1999/xhtml" || typeof candidate.focus !== "function") throw new TypeError(`${optionDiagnostic}: fallbackFocus must resolve to an HTMLElement or null`);
+	return value;
+}
+function validateOptions(options) {
+	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError(`${optionDiagnostic}: options must be an object`);
+	const root = readRoot(options.root);
+	readBranches(options.branches, root?.ownerDocument ?? null);
+	readBoolean(options.enabled, "enabled", true);
+	readBoolean(options.preventScroll, "preventScroll", true);
+	for (const name of [
+		"accept",
+		"fallbackFocus",
+		"onRedirect"
+	]) if (options[name] !== void 0 && typeof options[name] !== "function") throw new TypeError(`${optionDiagnostic}: ${name} must be a function`);
+}
+function createRedirectEvent(position, direction, reason, target, relatedTarget, originalEvent) {
+	let prevented = false;
+	return Object.freeze({
+		type: "focus-guard-redirect",
+		position,
+		direction,
+		reason,
+		target,
+		relatedTarget,
+		originalEvent,
+		get defaultPrevented() {
+			return prevented;
+		},
+		preventDefault: () => {
+			prevented = true;
+		}
+	});
+}
+//#endregion
+//#region src/focus-guards-stack.ts
+const documentStacks = /* @__PURE__ */ new WeakMap();
+function stackFor(document) {
+	let stack = documentStacks.get(document);
+	if (!stack) {
+		stack = [];
+		documentStacks.set(document, stack);
+	}
+	return stack;
+}
+function recomputeFocusGuards(document) {
+	const stack = stackFor(document);
+	let owner = null;
+	for (let index = stack.length - 1; index >= 0; index--) {
+		const token = stack[index];
+		if (token?.root?.isConnected && token.readEnabled()) {
+			owner = token;
+			break;
+		}
+	}
+	for (const token of stack) token.setTopmost(token === owner);
+}
+function attachFocusGuards(token, root) {
+	if (token.document === root.ownerDocument) {
+		token.root = root;
+		recomputeFocusGuards(root.ownerDocument);
+		return;
+	}
+	detachFocusGuards(token);
+	token.document = root.ownerDocument;
+	token.root = root;
+	stackFor(root.ownerDocument).push(token);
+	recomputeFocusGuards(root.ownerDocument);
+}
+function detachFocusGuards(token) {
+	const document = token.document;
+	if (!document) {
+		token.root = null;
+		token.setTopmost(false);
+		return;
+	}
+	const stack = stackFor(document);
+	const index = stack.indexOf(token);
+	if (index >= 0) stack.splice(index, 1);
+	token.document = null;
+	token.root = null;
+	token.setTopmost(false);
+	if (stack.length === 0) documentStacks.delete(document);
+	else recomputeFocusGuards(document);
+}
+//#endregion
+//#region src/focus-guards.ts
+const disposedDiagnostic = "VIZE_UI_FOCUS_GUARDS_DISPOSED";
+const rootDiagnostic = "VIZE_UI_FOCUS_GUARDS_ROOT";
+const setupDiagnostic = "VIZE_UI_FOCUS_GUARDS_SETUP";
+/** Optional invisible sentinel preset; consumers remain free to replace every value. */
+const focusGuardPreset = Object.freeze({
+	blockSize: "1px",
+	borderWidth: "0",
+	inlineSize: "1px",
+	insetBlockStart: "0",
+	insetInlineStart: "0",
+	opacity: "0",
+	outline: "none",
+	padding: "0",
+	pointerEvents: "none",
+	position: "fixed"
+});
+/** Create an SSR-safe pair of nested, portal-aware focus sentinels. */
+function createFocusGuards(options) {
+	validateOptions(options);
+	const activeState = shallowRef(false);
+	const guardingState = shallowRef(false);
+	const token = {
+		document: null,
+		root: null,
+		readEnabled: () => readBoolean(options.enabled, "enabled", true),
+		setTopmost: (value) => {
+			guardingState.value = value;
+		}
+	};
+	let disposed = false;
+	let redirecting = false;
+	let tabDirection = null;
+	let observer = null;
+	const assertAlive = () => {
+		if (disposed) throw new Error(`${disposedDiagnostic}: the controller has been disposed`);
+	};
+	const roots = () => {
+		const root = token.root;
+		return root ? [root, ...readBranches(options.branches, root.ownerDocument)] : [];
+	};
+	const candidates = () => documentOrder(roots().flatMap((root) => focusableElements(root, { accept: (element) => !element.hasAttribute("data-vize-focus-guard") && options.accept?.(element) !== false })));
+	const fallback = () => {
+		const ownedRoots = roots();
+		const preferred = readTarget(options.fallbackFocus?.());
+		if (preferred && !ownedRoots.some((root) => containsComposed(root, preferred))) throw new Error(`${rootDiagnostic}: fallbackFocus must resolve inside a guarded region`);
+		if (preferred?.hasAttribute("data-vize-focus-guard")) return null;
+		if (isUsableTarget(preferred)) return preferred;
+		const root = token.root;
+		return root?.hasAttribute("tabindex") && isUsableTarget(root) ? root : null;
+	};
+	const owns = (element) => element !== null && roots().some((root) => containsComposed(root, element));
+	const onKeydown = (event) => {
+		if (event.key === "Tab" && !event.altKey && !event.ctrlKey && !event.metaKey) tabDirection = event.shiftKey ? "backward" : "forward";
+	};
+	const redirect = (position, originalEvent) => {
+		if (!guardingState.value || redirecting) return;
+		const related = eventElement(originalEvent.relatedTarget);
+		const wrapped = owns(related);
+		const direction = wrapped || related ? position === "before" ? wrapped ? "backward" : "forward" : wrapped ? "forward" : "backward" : tabDirection ?? (position === "before" ? "forward" : "backward");
+		tabDirection = null;
+		const values = candidates();
+		const target = (direction === "forward" ? values[0] : values.at(-1)) ?? fallback();
+		const event = createRedirectEvent(position, direction, wrapped ? "wrap" : "enter", target, related, originalEvent);
+		const errors = [];
+		redirecting = true;
+		try {
+			capture(errors, () => options.onRedirect?.(event));
+			if (!event.defaultPrevented && target) capture(errors, () => focusElement(target, readBoolean(options.preventScroll, "preventScroll", true)));
+		} finally {
+			redirecting = false;
+		}
+		surfaceErrors(errors, "Focus guard redirection failed");
+	};
+	const props = (position) => Object.freeze({
+		"data-vize-focus-guard": position,
+		get tabindex() {
+			return guardingState.value ? 0 : -1;
+		},
+		onFocus: (event) => redirect(position, event)
+	});
+	const beforeProps = props("before");
+	const afterProps = props("after");
+	const detachDom = () => {
+		observer?.disconnect();
+		observer = null;
+		token.document?.removeEventListener("keydown", onKeydown, true);
+		detachFocusGuards(token);
+	};
+	const observe = (root) => {
+		const Observer = root.ownerDocument.defaultView?.MutationObserver;
+		const documentRoot = root.ownerDocument.documentElement;
+		if (!Observer || !documentRoot) return;
+		observer = new Observer(() => recomputeFocusGuards(root.ownerDocument));
+		observer.observe(documentRoot, {
+			childList: true,
+			subtree: true
+		});
+	};
+	const refresh = () => {
+		assertAlive();
+		if (!activeState.value) return;
+		const nextRoot = readRoot(options.root);
+		readBoolean(options.enabled, "enabled", true);
+		readBoolean(options.preventScroll, "preventScroll", true);
+		readBranches(options.branches, nextRoot?.ownerDocument ?? null);
+		if (nextRoot !== token.root) {
+			const sameDocument = nextRoot !== null && token.document === nextRoot.ownerDocument;
+			if (sameDocument) attachFocusGuards(token, nextRoot);
+			else detachDom();
+			if (nextRoot && !sameDocument) {
+				attachFocusGuards(token, nextRoot);
+				nextRoot.ownerDocument.addEventListener("keydown", onKeydown, true);
+				observe(nextRoot);
+			}
+		} else if (token.document) recomputeFocusGuards(token.document);
+	};
+	const activate = () => {
+		assertAlive();
+		if (activeState.value) return;
+		activeState.value = true;
+		try {
+			refresh();
+		} catch (error) {
+			activeState.value = false;
+			detachDom();
+			throw error;
+		}
+	};
+	const deactivate = () => {
+		assertAlive();
+		if (!activeState.value) return;
+		try {
+			detachDom();
+		} finally {
+			activeState.value = false;
+			tabDirection = null;
+		}
+	};
+	const stopWatch = watch(() => [
+		toValue(options.root),
+		toValue(options.branches),
+		toValue(options.enabled),
+		toValue(options.preventScroll)
+	], () => {
+		if (activeState.value) refresh();
+	}, { flush: "sync" });
+	return Object.freeze({
+		isActive: shallowReadonly(activeState),
+		isGuarding: shallowReadonly(guardingState),
+		beforeProps,
+		afterProps,
+		activate,
+		deactivate,
+		refresh,
+		dispose: () => {
+			if (disposed) return;
+			try {
+				detachDom();
+			} finally {
+				activeState.value = false;
+				disposed = true;
+				stopWatch();
+			}
+		}
+	});
+}
+/** Create, mount-activate, and scope-dispose a focus-guard pair. */
+function useFocusGuards(options) {
+	if (!getCurrentScope()) throw new Error(`${setupDiagnostic}: use inside component setup or an active effect scope`);
+	const controller = createFocusGuards(options);
+	if (getCurrentInstance()) onMounted(controller.activate);
+	else controller.activate();
+	onScopeDispose(controller.dispose);
+	return controller;
+}
+//#endregion
+export { focusGuardPreset as n, useFocusGuards as r, createFocusGuards as t };

package/dist/focus-guards.d.mts

@@ -0,0 +1,2 @@
+import { a as FocusGuardPosition, c as FocusGuardRedirectEvent, d as FocusGuardsOptions, i as FocusGuardDirection, l as FocusGuardStylePreset, n as focusGuardPreset, o as FocusGuardProps, r as useFocusGuards, s as FocusGuardReason, t as createFocusGuards, u as FocusGuardsController } from "./focus-guards-Bt0C-0qS.mjs";
+export { type FocusGuardDirection, type FocusGuardPosition, type FocusGuardProps, type FocusGuardReason, type FocusGuardRedirectEvent, type FocusGuardStylePreset, type FocusGuardsController, type FocusGuardsOptions, createFocusGuards, focusGuardPreset, useFocusGuards };

package/dist/focus-guards.mjs

@@ -0,0 +1,2 @@
+import { n as focusGuardPreset, r as useFocusGuards, t as createFocusGuards } from "./focus-guards-DhMPQAT8.mjs";
+export { createFocusGuards, focusGuardPreset, useFocusGuards };

package/dist/focus-scope-CavhKWx0.d.mts

@@ -0,0 +1,100 @@
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/focus-scope-types.d.ts
+/** Preventable lifecycle notification for automatic focus movement. */
+interface FocusScopeAutoFocusEvent {
+  readonly type: "mount" | "unmount";
+  readonly target: HTMLElement | null;
+  readonly defaultPrevented: boolean;
+  readonly preventDefault: () => void;
+}
+/** Programmatic movement options shared by the focus manager methods. */
+interface FocusScopeMoveOptions {
+  /** Element from which traversal begins. Defaults to the deep active element. */
+  readonly from?: Element | null;
+  /**
+   * Include focusable elements excluded from sequential Tab order.
+   *
+   * @default false
+   */
+  readonly includeProgrammatic?: boolean;
+  /**
+   * Wrap traversal at the scope boundary.
+   *
+   * @default false
+   */
+  readonly wrap?: boolean;
+  /**
+   * Avoid browser scrolling while focus moves.
+   *
+   * @default true
+   */
+  readonly preventScroll?: boolean;
+  /** Additional consumer filter applied after native focusability checks. */
+  readonly accept?: (element: HTMLElement) => boolean;
+}
+/** Focus containment, entry, and restoration options for one DOM subtree. */
+interface FocusScopeOptions {
+  /** Scope root. It may be `null` during SSR and before mount. */
+  readonly root: MaybeRefOrGetter<Element | null | undefined>;
+  /**
+   * Trap sequential and programmatic focus inside the active, topmost scope.
+   *
+   * @default false
+   */
+  readonly contain?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Focus an initial target when the activated scope receives a mounted root.
+   *
+   * @default false
+   */
+  readonly autoFocus?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Restore focus when the scope deactivates.
+   *
+   * @default false
+   */
+  readonly restoreFocus?: MaybeRefOrGetter<boolean | undefined>;
+  /** Preferred initial target. It must resolve inside the current scope. */
+  readonly initialFocus?: () => HTMLElement | null | undefined;
+  /** Explicit restoration target, evaluated at deactivation time. */
+  readonly restoreTarget?: () => HTMLElement | null | undefined;
+  /** Fallback target when a scope has no tabbable descendants. */
+  readonly fallbackFocus?: () => HTMLElement | null | undefined;
+  /** Consumer filter applied to automatically discovered focusable descendants. */
+  readonly accept?: (element: HTMLElement) => boolean;
+  /** Called before automatic entry focus. Call `preventDefault` to retain focus. */
+  readonly onMountAutoFocus?: (event: FocusScopeAutoFocusEvent) => void;
+  /** Called before automatic restoration. Call `preventDefault` to retain focus. */
+  readonly onUnmountAutoFocus?: (event: FocusScopeAutoFocusEvent) => void;
+}
+/** Stable focus traversal interface for one scope. */
+interface FocusScopeManager {
+  readonly focusFirst: (options?: FocusScopeMoveOptions) => HTMLElement | null;
+  readonly focusLast: (options?: FocusScopeMoveOptions) => HTMLElement | null;
+  readonly focusNext: (options?: FocusScopeMoveOptions) => HTMLElement | null;
+  readonly focusPrevious: (options?: FocusScopeMoveOptions) => HTMLElement | null;
+}
+/** Lifecycle and traversal controller returned by `createFocusScope`. */
+interface FocusScopeController extends FocusScopeManager {
+  /** Whether this controller has been activated and not deactivated. */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+  /** Activate once, capture restoration context, and attach when a root exists. */
+  readonly activate: () => void;
+  /** Deactivate once, detach containment, and restore focus when configured. */
+  readonly deactivate: () => void;
+  /** Re-read the root and recover containment after imperative DOM changes. */
+  readonly refresh: () => void;
+  /** Permanently release watches and lifecycle ownership. */
+  readonly dispose: () => void;
+}
+//#endregion
+//#region src/use-focus-scope.d.ts
+/** Create, mount-activate, and scope-dispose a focus scope from Vue setup. */
+declare function useFocusScope(options: FocusScopeOptions): FocusScopeController;
+//#endregion
+//#region src/focus-scope.d.ts
+/** Create an SSR-safe focus scope with containment, traversal, and restoration. */
+declare function createFocusScope(options: FocusScopeOptions): FocusScopeController;
+//#endregion
+export { FocusScopeManager as a, FocusScopeController as i, useFocusScope as n, FocusScopeMoveOptions as o, FocusScopeAutoFocusEvent as r, FocusScopeOptions as s, createFocusScope as t };