@vjdesigns/vjdesigns-ui 0.0.0-stage → 1.5.0

package/dist/hooks/useFormValidation.d.ts

@@ -0,0 +1,101 @@
+import { FocusEvent, FormEvent, RefObject, SyntheticEvent } from 'react';
+import { FormValues, ValidationRule } from '../utils/validators';
+/** Error messages by field name. */
+export type FormErrors = Record<string, string>;
+/** One error, in page order, for an error summary. */
+export interface FormErrorItem {
+    /** The field's name. */
+    name: string;
+    message: string;
+    /** Id of the field's focusable control, for a `#id` link (when it has one). */
+    id?: string;
+    /** Moves focus to the field. */
+    focus: () => void;
+    /** `server` errors (from `setErrors` or `onValid`) stay until the field is edited. */
+    source: "client" | "server";
+}
+/** What `onValid` may return: errors from the server, or nothing when the submit succeeded. */
+type SubmitResult = FormErrors | void | undefined | null;
+export interface UseFormValidationOptions {
+    /**
+     * Extra rules per field name, run after the browser's own checks
+     * (`required`, `type="email"`, `min`, `pattern`, ...). Use the helpers in
+     * `rules` (`rules.email()`, `rules.ip()`, `rules.matches("password")`, ...)
+     * or your own functions returning a message.
+     */
+    rules?: Record<string, ValidationRule | ValidationRule[]>;
+    /**
+     * Called on submit when every field is valid, with the form's values. Return
+     * (or resolve to) errors from the server to show them on their fields. When
+     * omitted, a valid form submits natively (to its `action`).
+     */
+    onValid?: (values: FormValues, event: FormEvent<HTMLFormElement>) => SubmitResult | Promise<SubmitResult>;
+    /**
+     * After a failed submit, focus moves to the error summary (when an
+     * `ErrorSummary` has `summaryRef`) or to the first invalid field. @default true
+     */
+    focusOnError?: boolean;
+}
+export interface FormValidation {
+    /** Spread on the `<form>`: `ref`, `noValidate`, and the submit, input, and blur handlers. */
+    formProps: {
+        ref: (node: HTMLFormElement | null) => void;
+        noValidate: true;
+        onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+        onInput: (event: SyntheticEvent<HTMLFormElement>) => void;
+        onChange: (event: SyntheticEvent<HTMLFormElement>) => void;
+        onBlur: (event: FocusEvent<HTMLFormElement>) => void;
+    };
+    /** The form element. */
+    formRef: RefObject<HTMLFormElement | null>;
+    /** Current errors by field name: pass `errors.email` to the email `Field`'s `error`. */
+    errors: FormErrors;
+    /** Current errors in page order, for `ErrorSummary`. */
+    errorList: FormErrorItem[];
+    /** Attach to an `ErrorSummary` so a failed submit moves focus to it. */
+    summaryRef: RefObject<HTMLDivElement | null>;
+    /** True while an async `onValid` is running. */
+    isSubmitting: boolean;
+    /** Number of submit attempts; fields re-check as they're edited after the first. */
+    submitCount: number;
+    /** Validates now (every field, or only `names`); returns true when they're valid. */
+    validate: (names?: string[]) => boolean;
+    /** Shows errors (for example from the server) on their fields, next to the current ones. */
+    setErrors: (errors: FormErrors) => void;
+    /** Removes errors (all of them, or only `names`). */
+    clearErrors: (names?: string[]) => void;
+    /** The form's current values, by field name. */
+    getValues: () => FormValues;
+}
+/**
+ * Form validation built on the browser's own constraints (`required`,
+ * `type="email"`, `min`, `maxLength`, `pattern`, ...) plus your own `rules`,
+ * with the messages in the current language. It works with plain inputs and
+ * every form component in this library; pass each field's message to its
+ * `Field`:
+ *
+ * ```tsx
+ * const form = useFormValidation({
+ *   rules: { server: rules.ip(), confirm: rules.matches("password") },
+ *   onValid: async (values) => (await save(values)).errors,
+ * });
+ *
+ * <form {...form.formProps}>
+ *   <ErrorSummary ref={form.summaryRef} errors={form.errorList} />
+ *   <Field label="Email" required error={form.errors.email}>
+ *     <Input name="email" type="email" />
+ *   </Field>
+ *   <Button type="submit" loading={form.isSubmitting}>Save</Button>
+ * </form>
+ * ```
+ *
+ * Validates on submit. After that, an error clears as soon as its field is
+ * fixed while typing, and a field is fully re-checked when focus leaves it.
+ * A failed submit moves focus to the error summary (or the first invalid
+ * field). Errors from the server stay until their field is edited.
+ *
+ * This is for the user's convenience, not security: validate again on the
+ * server, since anyone can bypass the browser.
+ */
+export declare function useFormValidation(options?: UseFormValidationOptions): FormValidation;
+export {};

package/dist/hooks/useFormValidation.mjs

@@ -0,0 +1,187 @@
+import { useLocale as e } from "../components/utilities/LocaleProvider/LocaleProvider.mjs";
+import { isEmail as t } from "../utils/validators.mjs";
+import { useCallback as n, useEffect as r, useMemo as i, useRef as a, useState as o } from "react";
+//#region src/hooks/useFormValidation.ts
+var s = "input:not([type=\"hidden\"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex=\"-1\"]), [contenteditable=\"true\"]", c = (e) => e.getClientRects().length > 0, l = (e) => e instanceof HTMLElement && e.matches(s) && c(e) && !(e instanceof HTMLInputElement && e.type === "hidden");
+function u(e, t) {
+	for (let n = e.parentElement, r = 0; n && n !== t && r < 6; n = n.parentElement, r++) {
+		let e = new Set(Array.from(n.querySelectorAll("input[type=\"hidden\"][name]")).map((e) => e.name));
+		if (e.size === 1) return [...e][0];
+		if (e.size > 1) return;
+	}
+}
+function d(e, t) {
+	return e.name || u(e, t) || e.id || void 0;
+}
+function f(e, t) {
+	let n = Array.from(t.querySelectorAll(`[name="${CSS.escape(e)}"]`)), r = n.find(l);
+	if (r) return r;
+	for (let e of n) for (let n = e.parentElement, r = 0; n && n !== t && r < 6; n = n.parentElement, r++) {
+		let e = Array.from(n.querySelectorAll(s)).find(l);
+		if (e) return e;
+	}
+	let i = t.querySelector(`#${CSS.escape(e)}`);
+	return i && l(i) ? i : void 0;
+}
+function p(e) {
+	let t = {};
+	return new FormData(e).forEach((e, n) => {
+		let r = t[n];
+		t[n] = r === void 0 ? e : Array.isArray(r) ? [...r, e] : [r, e];
+	}), t;
+}
+function m(e, n, r) {
+	let i = e instanceof HTMLInputElement && e.type === "email" && e.value && !e.multiple && !t(e.value.trim()), a = e instanceof HTMLInputElement || e instanceof HTMLTextAreaElement ? e : void 0, o = a ? a.value.length : 0, s = a && o > 0 && a.minLength > 0 && o < a.minLength ? n.tooShort(a.minLength) : a && a.maxLength >= 0 && o > a.maxLength ? n.tooLong(a.maxLength) : void 0, c = e.validity;
+	if (c.valid && !i && !s) return;
+	if (c.customError) return e.validationMessage;
+	if (c.valueMissing) return n.required;
+	let l = e instanceof HTMLInputElement ? e : void 0;
+	if (c.typeMismatch || i) return l?.type === "email" ? n.email : l?.type === "url" ? n.url : n.invalid;
+	if (c.badInput) return l?.type === "number" ? n.number : n.invalid;
+	if (c.patternMismatch) return l?.title || n.pattern;
+	if (s) return s;
+	let u = (e) => l && (l.type === "number" || l.type === "range") && e !== "" && !Number.isNaN(Number(e)) ? new Intl.NumberFormat(r).format(Number(e)) : e;
+	return c.rangeUnderflow && l ? n.min(u(l.min)) : c.rangeOverflow && l ? n.max(u(l.max)) : c.stepMismatch ? n.step : n.invalid;
+}
+var h = (e, t) => e.length === t.length && e.every((e, n) => e.name === t[n].name && e.message === t[n].message && e.source === t[n].source);
+function g(e, t) {
+	if (!t) return e;
+	let n = (e) => {
+		let n = f(e.name, t);
+		return n ? Array.from(t.querySelectorAll("*")).indexOf(n) : 2 ** 53 - 1;
+	}, r = new Map(e.map((e) => [e, n(e)]));
+	return [...e].sort((e, t) => r.get(e) - r.get(t));
+}
+function _(t = {}) {
+	let { rules: s = {}, onValid: c, focusOnError: l = !0 } = t, { messages: u, locale: _ } = e(), v = a(null), y = a(null), [b, x] = o([]), [S, C] = o(0), [w, T] = o(!1), [E, D] = o(0), O = a({
+		rules: s,
+		onValid: c,
+		messages: u.validation,
+		locale: _
+	});
+	O.current = {
+		rules: s,
+		onValid: c,
+		messages: u.validation,
+		locale: _
+	};
+	let k = n((e, t, n) => ({
+		name: e,
+		message: t,
+		source: n,
+		get id() {
+			let t = v.current;
+			return t && f(e, t)?.id || void 0;
+		},
+		focus: () => {
+			let t = v.current;
+			(t && f(e, t))?.focus();
+		}
+	}), []), A = n((e) => {
+		let t = v.current, n = /* @__PURE__ */ new Map();
+		if (!t) return n;
+		let { rules: r, messages: i, locale: a } = O.current, o = (t) => !e || e.includes(t);
+		for (let e of Array.from(t.elements)) {
+			if (!("validity" in e) || !e.willValidate || e.disabled) continue;
+			let r = d(e, t);
+			if (!r || !o(r) || n.has(r)) continue;
+			let s = m(e, i, a);
+			s && n.set(r, s);
+		}
+		let s = p(t);
+		for (let [e, t] of Object.entries(r)) if (o(e) && !n.has(e)) for (let r of Array.isArray(t) ? t : [t]) {
+			let t = r(s[e], {
+				name: e,
+				values: s,
+				messages: i
+			});
+			if (t) {
+				n.set(e, t);
+				break;
+			}
+		}
+		return n;
+	}, []), j = n((e, t, { onlyClear: n = !1 } = {}) => {
+		x((r) => {
+			let i = (e) => !t || t.includes(e), a = [];
+			for (let t of r) i(t.name) ? n && e.has(t.name) && a.push(t) : a.push(t);
+			if (!n) for (let [t, n] of e) a.push(k(t, n, "client"));
+			let o = g(a, v.current);
+			return h(r, o) ? r : o;
+		});
+	}, [k]), M = n((e) => {
+		let t = A(e);
+		return j(t, e), t.size === 0;
+	}, [A, j]), N = n((e) => {
+		let t = Object.entries(e).filter(([, e]) => e);
+		t.length && (x((n) => g([...n.filter((t) => !(t.name in e)), ...t.map(([e, t]) => k(e, t, "server"))], v.current)), l && D((e) => e + 1));
+	}, [k, l]), P = n((e) => {
+		x((t) => e ? t.filter((t) => !e.includes(t.name)) : []);
+	}, []), F = n(() => v.current ? p(v.current) : {}, []);
+	r(() => {
+		E && l && (y.current && y.current.isConnected ? y.current.focus() : b[0]?.focus());
+	}, [E]);
+	let I = n((e) => {
+		C((e) => e + 1);
+		let t = A();
+		if (j(t), t.size > 0) {
+			e.preventDefault(), l && D((e) => e + 1);
+			return;
+		}
+		let n = O.current.onValid;
+		if (!n) return;
+		e.preventDefault();
+		let r = n(p(e.currentTarget), e);
+		r && typeof r.then == "function" ? (T(!0), r.then((e) => {
+			e && N(e);
+		}).finally(() => T(!1))) : r && N(r);
+	}, [
+		A,
+		j,
+		N,
+		l
+	]), L = (e) => {
+		let t = v.current, n = e.target;
+		if (t && S !== 0 && n instanceof Element) return d(n, t);
+	}, R = (e) => {
+		if (e.target instanceof HTMLSelectElement) return;
+		let t = L(e);
+		t && (x((e) => e.some((e) => e.name === t && e.source === "server") ? e.filter((e) => e.name !== t || e.source !== "server") : e), j(A([t]), [t], { onlyClear: !0 }));
+	}, z = (e) => {
+		let t = L(e);
+		if (!t) return;
+		let n = b.filter((e) => e.source === "client").map((e) => e.name), r = Array.from(/* @__PURE__ */ new Set([t, ...n]));
+		j(A(r), r);
+	}, B = i(() => Object.fromEntries(b.map((e) => [e.name, e.message])), [b]);
+	return {
+		formProps: {
+			ref: (e) => {
+				v.current = e;
+			},
+			noValidate: !0,
+			onSubmit: I,
+			onInput: R,
+			onChange: (e) => {
+				let t = e.target;
+				t instanceof HTMLTextAreaElement || t instanceof HTMLInputElement && ![
+					"checkbox",
+					"radio",
+					"file"
+				].includes(t.type) || z(e);
+			},
+			onBlur: z
+		},
+		formRef: v,
+		errors: B,
+		errorList: b,
+		summaryRef: y,
+		isSubmitting: w,
+		submitCount: S,
+		validate: M,
+		setErrors: N,
+		clearErrors: P,
+		getValues: F
+	};
+}
+//#endregion
+export { _ as useFormValidation };

package/dist/hooks/useHotkeys.cjs.js

@@ -0,0 +1 @@
+const e=require("../utils/hotkeys.cjs.js");let t=require("react");var n=e=>e.meta||e.ctrl||e.alt;function r(t,r){let i=e.detectPlatform();for(let[a,o,s={}]of t)for(let t of a.split(`,`)){let a=e.parseHotkey(t.trim(),i);if(a&&e.matchesHotkey(r,a)&&(!e.isTypingTarget(r.target)||n(a)||s.allowInInputs)){s.preventDefault!==!1&&r.preventDefault(),o(r);return}}}function i(e,{enabled:n=!0,target:i}={}){let a=(0,t.useRef)(e);a.current=e,(0,t.useEffect)(()=>{if(!n)return;let e=i??(typeof document<`u`?document:void 0);if(!e)return;let t=e=>r(a.current,e);return e.addEventListener(`keydown`,t),()=>e.removeEventListener(`keydown`,t)},[n,i])}function a(e){return t=>{let n=`nativeEvent`in t?t.nativeEvent:t;r(e.map(([e,t,n])=>[e,t,{allowInInputs:!0,...n}]),n)}}exports.getHotkeyHandler=a,exports.useHotkeys=i;

package/dist/hooks/useHotkeys.d.ts

@@ -0,0 +1,50 @@
+import { KeyboardEvent as ReactKeyboardEvent } from 'react';
+/** One shortcut: the keys, the handler, and per-shortcut options. */
+export type HotkeyItem = [
+    hotkey: string,
+    handler: (event: KeyboardEvent) => void,
+    options?: HotkeyItemOptions
+];
+export interface HotkeyItemOptions {
+    /** Call `preventDefault()` when the shortcut matches. @default true */
+    preventDefault?: boolean;
+    /**
+     * Also fire while typing in a text field. By default, shortcuts with ⌘,
+     * Ctrl, or Alt fire anywhere, and plain keys (`"/"`, `"?"`, `"g"`) don't
+     * fire while typing, so they never steal characters.
+     */
+    allowInInputs?: boolean;
+}
+export interface UseHotkeysOptions {
+    /** Turn every shortcut off (e.g. while a dialog is open). @default true */
+    enabled?: boolean;
+    /** Listen on this element instead of the whole document. */
+    target?: EventTarget | null;
+}
+/**
+ * Keyboard shortcuts for the whole page (or one element). `mod` is ⌘ on Mac
+ * and Ctrl elsewhere; separate alternatives with commas (`"mod+k, /"`).
+ * Shortcuts with ⌘, Ctrl, or Alt work everywhere; plain keys don't fire while
+ * typing in a text field. Show each shortcut to users (`Kbd`,
+ * `aria-keyshortcuts`) so it can be found, and avoid single-key shortcuts that
+ * screen readers or browsers use, or let users turn them off (WCAG 2.1.4).
+ *
+ * ```tsx
+ * useHotkeys([
+ *   ["mod+k", () => setPaletteOpen(true)],
+ *   ["/", () => searchRef.current?.focus()],
+ *   ["shift+?", () => setHelpOpen(true)],
+ * ]);
+ * ```
+ */
+export declare function useHotkeys(hotkeys: HotkeyItem[], { enabled, target }?: UseHotkeysOptions): void;
+/**
+ * A `keydown` handler for one element (an editor, a list): pass it to
+ * `onKeyDown`. Same shortcut format as `useHotkeys`; shortcuts fire while
+ * typing in that element.
+ *
+ * ```tsx
+ * <Textarea onKeyDown={getHotkeyHandler([["mod+enter", send]])} />
+ * ```
+ */
+export declare function getHotkeyHandler(hotkeys: HotkeyItem[]): (event: ReactKeyboardEvent | KeyboardEvent) => void;

package/dist/hooks/useHotkeys.mjs

@@ -0,0 +1,39 @@
+import { detectPlatform as e, isTypingTarget as t, matchesHotkey as n, parseHotkey as r } from "../utils/hotkeys.mjs";
+import { useEffect as i, useRef as a } from "react";
+//#region src/hooks/useHotkeys.ts
+var o = (e) => e.meta || e.ctrl || e.alt;
+function s(i, a) {
+	let s = e();
+	for (let [e, c, l = {}] of i) for (let i of e.split(",")) {
+		let e = r(i.trim(), s);
+		if (e && n(a, e) && (!t(a.target) || o(e) || l.allowInInputs)) {
+			l.preventDefault !== !1 && a.preventDefault(), c(a);
+			return;
+		}
+	}
+}
+function c(e, { enabled: t = !0, target: n } = {}) {
+	let r = a(e);
+	r.current = e, i(() => {
+		if (!t) return;
+		let e = n ?? (typeof document < "u" ? document : void 0);
+		if (!e) return;
+		let i = (e) => s(r.current, e);
+		return e.addEventListener("keydown", i), () => e.removeEventListener("keydown", i);
+	}, [t, n]);
+}
+function l(e) {
+	return (t) => {
+		let n = "nativeEvent" in t ? t.nativeEvent : t;
+		s(e.map(([e, t, n]) => [
+			e,
+			t,
+			{
+				allowInInputs: !0,
+				...n
+			}
+		]), n);
+	};
+}
+//#endregion
+export { l as getHotkeyHandler, c as useHotkeys };

package/dist/hooks/useInertOutside.cjs.js

@@ -0,0 +1 @@
+const e=require("./elementSource.cjs.js"),t=require("./useOverlayLayer.cjs.js");let n=require("react");var r=new Map,i=new Set([`SCRIPT`,`STYLE`,`TEMPLATE`,`LINK`,`META`,`NOSCRIPT`]),a=`[aria-live]:not([aria-live='off']), [role='status'], [role='alert'], [role='log']`;function o(e){let t=r.get(e);if(t){t.count+=1;return}r.set(e,{count:1,inert:e.inert,ariaHidden:e.getAttribute(`aria-hidden`)}),e.inert=!0,e.setAttribute(`aria-hidden`,`true`)}function s(e){let t=r.get(e);t&&(--t.count,!(t.count>0)&&(r.delete(e),e.inert=t.inert,t.ariaHidden===null?e.removeAttribute(`aria-hidden`):e.setAttribute(`aria-hidden`,t.ariaHidden)))}function c(e){if(typeof document>`u`)return()=>{};let t=(Array.isArray(e)?e:[e]).filter(e=>!!e&&e.isConnected);if(t.length===0)return()=>{};let n=document.body,r=Array.from(n.querySelectorAll(a)).filter(e=>!e.closest(`[inert]`)),c=new Set([...t,...r]),l=new Set;c.forEach(e=>{let t=e.parentElement;for(;t&&t!==n;)l.add(t),t=t.parentElement});let u=[],d=e=>{for(let t of Array.from(e.children))c.has(t)||i.has(t.tagName)||(l.has(t)?d(t):t instanceof HTMLElement&&u.push(t))};d(n),u.forEach(o);let f=!1;return()=>{f||(f=!0,u.forEach(s))}}function l(e,n){if(typeof document>`u`)return()=>{};let r=Array.isArray(n)?n:[n],i=()=>c([...r,...t.getChildLayerElements(e),...t.getLayerElementsAbove(e)]),a=i(),o=t.subscribeOverlayLayers(()=>{let e=i();a(),a=e}),s=!1;return()=>{s||(s=!0,o(),a())}}function u(t,r,i){let a=i?.id,o=(0,n.useRef)({key:[],release:null});(0,n.useLayoutEffect)(()=>{let n=r?t.map(t=>e.resolveElement(t)).filter(e=>!!e):[],i=o.current.key;if(n.length===i.length&&n.every((e,t)=>e===i[t]))return;o.current.release?.();let s=n.length===0?null:a?l(a,n):c(n);o.current={key:n,release:s}}),(0,n.useLayoutEffect)(()=>()=>{o.current.release?.(),o.current={key:[],release:null}},[])}exports.inertOutside=c,exports.inertOutsideLayer=l,exports.useInertOutside=u;

package/dist/hooks/useInertOutside.d.ts

@@ -0,0 +1,23 @@
+import { ElementSource } from './elementSource';
+/**
+ * Marks everything outside `keep` as inert. Returns a function that
+ * restores exactly what it changed (safe to call twice).
+ */
+export declare function inertOutside(keep: HTMLElement | Array<HTMLElement | null | undefined>): () => void;
+/**
+ * Like `inertOutside`, but also keeps reachable the elements of every open
+ * child layer of `layerId` (a Tooltip or Popover portaled out of the modal
+ * surface, even one that mounted in the same commit) and of every layer
+ * stacked above it (a Modal opened from elsewhere on top of this one),
+ * re-applying the marks whenever the layer stack changes. Returns the
+ * release function.
+ */
+export declare function inertOutsideLayer(layerId: string, keep: HTMLElement | HTMLElement[]): () => void;
+/**
+ * Makes everything outside `elements` inert while `active`. Pass the
+ * overlay's `layer` so its child layers stay reachable. Run it only for
+ * the topmost modal layer's session (Modal and Drawer apply it while open).
+ */
+export declare function useInertOutside(elements: ElementSource[], active: boolean, layer?: {
+    id: string;
+}): void;

package/dist/hooks/useInertOutside.mjs

@@ -0,0 +1,83 @@
+import { resolveElement as e } from "./elementSource.mjs";
+import { getChildLayerElements as t, getLayerElementsAbove as n, subscribeOverlayLayers as r } from "./useOverlayLayer.mjs";
+import { useLayoutEffect as i, useRef as a } from "react";
+//#region src/hooks/useInertOutside.ts
+var o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Set([
+	"SCRIPT",
+	"STYLE",
+	"TEMPLATE",
+	"LINK",
+	"META",
+	"NOSCRIPT"
+]), c = "[aria-live]:not([aria-live='off']), [role='status'], [role='alert'], [role='log']";
+function l(e) {
+	let t = o.get(e);
+	if (t) {
+		t.count += 1;
+		return;
+	}
+	o.set(e, {
+		count: 1,
+		inert: e.inert,
+		ariaHidden: e.getAttribute("aria-hidden")
+	}), e.inert = !0, e.setAttribute("aria-hidden", "true");
+}
+function u(e) {
+	let t = o.get(e);
+	t && (--t.count, !(t.count > 0) && (o.delete(e), e.inert = t.inert, t.ariaHidden === null ? e.removeAttribute("aria-hidden") : e.setAttribute("aria-hidden", t.ariaHidden)));
+}
+function d(e) {
+	if (typeof document > "u") return () => {};
+	let t = (Array.isArray(e) ? e : [e]).filter((e) => !!e && e.isConnected);
+	if (t.length === 0) return () => {};
+	let n = document.body, r = Array.from(n.querySelectorAll(c)).filter((e) => !e.closest("[inert]")), i = /* @__PURE__ */ new Set([...t, ...r]), a = /* @__PURE__ */ new Set();
+	i.forEach((e) => {
+		let t = e.parentElement;
+		for (; t && t !== n;) a.add(t), t = t.parentElement;
+	});
+	let o = [], d = (e) => {
+		for (let t of Array.from(e.children)) i.has(t) || s.has(t.tagName) || (a.has(t) ? d(t) : t instanceof HTMLElement && o.push(t));
+	};
+	d(n), o.forEach(l);
+	let f = !1;
+	return () => {
+		f || (f = !0, o.forEach(u));
+	};
+}
+function f(e, i) {
+	if (typeof document > "u") return () => {};
+	let a = Array.isArray(i) ? i : [i], o = () => d([
+		...a,
+		...t(e),
+		...n(e)
+	]), s = o(), c = r(() => {
+		let e = o();
+		s(), s = e;
+	}), l = !1;
+	return () => {
+		l || (l = !0, c(), s());
+	};
+}
+function p(t, n, r) {
+	let o = r?.id, s = a({
+		key: [],
+		release: null
+	});
+	i(() => {
+		let r = n ? t.map((t) => e(t)).filter((e) => !!e) : [], i = s.current.key;
+		if (r.length === i.length && r.every((e, t) => e === i[t])) return;
+		s.current.release?.();
+		let a = r.length === 0 ? null : o ? f(o, r) : d(r);
+		s.current = {
+			key: r,
+			release: a
+		};
+	}), i(() => () => {
+		s.current.release?.(), s.current = {
+			key: [],
+			release: null
+		};
+	}, []);
+}
+//#endregion
+export { d as inertOutside, f as inertOutsideLayer, p as useInertOutside };

package/dist/hooks/useMediaQuery.cjs.js

@@ -0,0 +1 @@
+let e=require("react");var t=()=>typeof window<`u`&&typeof window.matchMedia==`function`;function n(n,r=!1){let i=(0,e.useCallback)(e=>{if(!n||!t())return()=>{};let r=window.matchMedia(n);return r.addEventListener(`change`,e),()=>r.removeEventListener(`change`,e)},[n]);return(0,e.useSyncExternalStore)(i,()=>n&&t()?window.matchMedia(n).matches:r,()=>r)}exports.useMediaQuery=n;

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a CSS media query matches, kept in sync as the viewport or user
+ * preferences change. Returns `serverValue` (default `false`) during server
+ * rendering, when `query` is undefined, or where `matchMedia` is missing.
+ *
+ * ```ts
+ * const wide = useMediaQuery("(min-width: 768px)");
+ * const reduceMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
+ * ```
+ */
+export declare function useMediaQuery(query: string | undefined, serverValue?: boolean): boolean;

package/dist/hooks/useMediaQuery.mjs

@@ -0,0 +1,13 @@
+import { useCallback as e, useSyncExternalStore as t } from "react";
+//#region src/hooks/useMediaQuery.ts
+var n = () => typeof window < "u" && typeof window.matchMedia == "function";
+function r(r, i = !1) {
+	let a = e((e) => {
+		if (!r || !n()) return () => {};
+		let t = window.matchMedia(r);
+		return t.addEventListener("change", e), () => t.removeEventListener("change", e);
+	}, [r]);
+	return t(a, () => r && n() ? window.matchMedia(r).matches : i, () => i);
+}
+//#endregion
+export { r as useMediaQuery };

package/dist/hooks/useMergedRef.cjs.js

@@ -0,0 +1 @@
+const e=require("../utils/refs.cjs.js");let t=require("react");function n(...n){return(0,t.useMemo)(()=>e.mergeRefs(...n),n)}exports.useMergedRef=n;

package/dist/hooks/useMergedRef.d.ts

@@ -0,0 +1,7 @@
+import { Ref, RefCallback } from 'react';
+/**
+ * A callback ref that writes to every given ref (callback or object), stable
+ * while the refs are. Use it to combine a component's own ref with the
+ * consumer's `ref` prop (or a slot child's ref).
+ */
+export declare function useMergedRef<T>(...refs: Array<Ref<T> | undefined | null>): RefCallback<T>;

package/dist/hooks/useMergedRef.mjs

@@ -0,0 +1,8 @@
+import { mergeRefs as e } from "../utils/refs.mjs";
+import { useMemo as t } from "react";
+//#region src/hooks/useMergedRef.ts
+function n(...n) {
+	return t(() => e(...n), n);
+}
+//#endregion
+export { n as useMergedRef };

package/dist/hooks/useOverlayLayer.cjs.js

@@ -0,0 +1 @@
+const e=require("./elementSource.cjs.js");let t=require("react");var n=[],r=new Map,i=new Set;function a(){i.forEach(e=>e())}function o(e){return i.add(e),()=>{i.delete(e)}}function s(e){return e===null?void 0:n.find(t=>t.id===e)}function c(e,t){let n=e,r=new Set;for(;n&&!r.has(n.id);){if(n.id===t||n.parentId===t)return!0;r.add(n.id),n=s(n.parentId)}return!1}function l(e){let t=new Set,n=[],r=new Map(e.map(e=>[e.id,e])),i=(e,a)=>{if(t.has(e.id)||a.has(e.id))return;a.add(e.id);let o=e.parentId?r.get(e.parentId):void 0;o&&i(o,a),t.add(e.id),n.push(e)};return e.forEach(e=>i(e,new Set)),n}function u(t,n){let i=r.get(t);if(!i)return!1;for(let t of i){let r=t.current.elements?.()??[];for(let t of r)if(e.resolveElement(t)?.contains(n))return!0}return!1}function d(t){let n=[];for(let i of r.get(t)??[])for(let t of i.current.elements?.()??[]){let r=e.resolveElement(t);r&&!n.includes(r)&&n.push(r)}return n}function f(e){return n.filter(t=>t.id!==e&&c(t,e)).flatMap(e=>d(e.id))}function p(e){let t=n.findIndex(t=>t.id===e);return t===-1?[]:n.slice(t+1).flatMap(e=>d(e.id))}function m(e){return o(e)}function h(e,t){return t?n.some(n=>n.id!==e&&c(n,e)&&u(n.id,t)):!1}function g(e,t){return t?u(e,t)||h(e,t):!1}function _(e){return Array.from(r.get(e)??[],e=>e.current)}function v(e){if(e.key!==`Escape`||e.defaultPrevented||e.isComposing)return;let t=n[n.length-1];if(t)for(let n of _(t.id))n.onEscape?.(e)}function y(e){if(e.defaultPrevented)return;let t=e.target instanceof Node?e.target:null;if(!t)return;let r=[...n];for(let n=r.length-1;n>=0;--n){let i=r[n];if(g(i.id,t))break;for(let t of _(i.id))t.onOutsidePress?.(e);if(i.modal)break}}var b=!1;function x(){typeof document>`u`||(n.length>0&&!b?(document.addEventListener(`keydown`,v),document.addEventListener(`pointerdown`,y),b=!0):n.length===0&&b&&(document.removeEventListener(`keydown`,v),document.removeEventListener(`pointerdown`,y),b=!1))}function S(e){return n=l([...n.filter(t=>t.id!==e.id),e]),x(),a(),()=>{n=n.filter(t=>t!==e),x(),a()}}function C(e,t){let n=r.get(e);return n||(n=new Set,r.set(e,n)),n.add(t),()=>{let n=r.get(e);n?.delete(t),n&&n.size===0&&r.delete(e)}}function w(e){return n.length>0&&n[n.length-1].id===e}function T(e){let t=n.findIndex(t=>t.id===e);return t!==-1&&n.slice(t+1).some(e=>e.modal)}function E(){return n.map(({id:e,parentId:t,modal:n})=>({id:e,parentId:t,modal:n}))}var D=(0,t.createContext)(null);function O(){return(0,t.useContext)(D)}function k({layer:e,children:n}){return(0,t.createElement)(D.Provider,{value:e.id},n)}function A({active:e,modal:n=!1,parentId:r,onEscape:i,onOutsidePress:a,elements:s}){let c=`layer-${(0,t.useId)()}`,l=(0,t.useContext)(D),u=r===void 0?l:r,d=(0,t.useRef)({});d.current={onEscape:i,onOutsidePress:a,elements:s},(0,t.useLayoutEffect)(()=>C(c,d),[c]),(0,t.useLayoutEffect)(()=>{if(e)return S({id:c,parentId:u??null,modal:n})},[e,c,u,n]);let f=(0,t.useSyncExternalStore)(o,()=>e&&w(c),()=>!1),p=(0,t.useSyncExternalStore)(o,()=>e&&T(c),()=>!1),m=(0,t.useCallback)(()=>w(c),[c]),_=(0,t.useCallback)(e=>g(c,e),[c]),v=(0,t.useCallback)(e=>h(c,e),[c]),y=(0,t.useCallback)(e=>C(c,e),[c]);return(0,t.useMemo)(()=>({id:c,parentId:u??null,isTopmost:f,hasModalAbove:p,getIsTopmost:m,contains:_,childContains:v,addHandlers:y}),[c,u,f,p,m,_,v,y])}exports.OverlayLayerProvider=k,exports.childLayerContains=h,exports.getChildLayerElements=f,exports.getLayerElementsAbove=p,exports.getOverlayLayerStack=E,exports.layerContains=g,exports.subscribeOverlayLayers=m,exports.useOverlayLayer=A,exports.useParentOverlayLayer=O;

package/dist/hooks/useOverlayLayer.d.ts

@@ -0,0 +1,92 @@
+import { ReactNode } from 'react';
+import { ElementSource } from './elementSource';
+/** What a layer does when it is dismissed. Read at event time. */
+export interface LayerHandlers {
+    /** Called when Escape is pressed and this layer is topmost. */
+    onEscape?: (event: KeyboardEvent) => void;
+    /** Called when a press lands outside this layer and its child layers. */
+    onOutsidePress?: (event: PointerEvent) => void;
+    /** Extra elements that count as inside this layer (trigger, anchor). */
+    elements?: () => ElementSource[];
+}
+/**
+ * Elements of every open descendant layer of layer `id` (for example a
+ * Tooltip or Popover portaled out of a Modal). A modal surface keeps these
+ * out of its inert marks.
+ */
+export declare function getChildLayerElements(id: string): HTMLElement[];
+/**
+ * Elements of every open layer stacked above layer `id`, related or not
+ * (for example a page-level Modal opened while this one stays open). A
+ * modal surface keeps these out of its inert marks; the topmost modal
+ * inerts everything below it on its own.
+ */
+export declare function getLayerElementsAbove(id: string): HTMLElement[];
+/** Subscribes to every change of the layer stack. Returns the unsubscribe function. */
+export declare function subscribeOverlayLayers(listener: () => void): () => void;
+/** True when `node` is inside one of the (open) child layers of layer `id`. */
+export declare function childLayerContains(id: string, node: Node | null): boolean;
+/** True when `node` is inside layer `id` or inside any of its child layers. */
+export declare function layerContains(id: string, node: Node | null): boolean;
+/** Ids of the open layers, bottom first. Useful for debugging and tests. */
+export declare function getOverlayLayerStack(): ReadonlyArray<{
+    id: string;
+    parentId: string | null;
+    modal: boolean;
+}>;
+/** The id of the nearest enclosing overlay layer, or null at the page level. */
+export declare function useParentOverlayLayer(): string | null;
+export interface OverlayLayerProviderProps {
+    /** The layer that overlays rendered inside `children` belong to. */
+    layer: Pick<OverlayLayer, "id">;
+    children?: ReactNode;
+}
+/**
+ * Makes `layer` the parent of every overlay rendered inside. Wrap an
+ * overlay's content with it (inside the Portal is fine: context crosses
+ * portals), so a Popover or Tooltip inside it counts as a child layer.
+ */
+export declare function OverlayLayerProvider({ layer, children }: OverlayLayerProviderProps): import('react').FunctionComponentElement<import('react').ProviderProps<string | null>>;
+export interface UseOverlayLayerOptions extends LayerHandlers {
+    /** Registered on the stack only while active (usually while open and mounted). */
+    active: boolean;
+    /**
+     * A modal layer blocks the layers below it: they stop trapping focus, and
+     * outside presses don't reach them. @default false
+     */
+    modal?: boolean;
+    /**
+     * Parent layer id. Defaults to the nearest `OverlayLayerProvider`. Pass
+     * `null` to make this a top-level layer.
+     */
+    parentId?: string | null;
+}
+export interface OverlayLayer {
+    /** Stable id of this layer. */
+    id: string;
+    /** Id of the parent layer, or null. */
+    parentId: string | null;
+    /** True while this layer is the topmost open layer (reactive). */
+    isTopmost: boolean;
+    /** True while a modal layer is open above this one (reactive). Traps should pause. */
+    hasModalAbove: boolean;
+    /** Live (non-reactive) topmost check, for use inside event handlers. */
+    getIsTopmost: () => boolean;
+    /** True when `node` is inside this layer's elements or any child layer. */
+    contains: (node: Node | null) => boolean;
+    /** True when `node` is inside one of this layer's open child layers (not its own elements). */
+    childContains: (node: Node | null) => boolean;
+    /**
+     * Adds dismiss handlers and inside elements to this layer. `useDismiss`
+     * calls this when given `layer`. Returns the remover.
+     */
+    addHandlers: (ref: {
+        current: LayerHandlers;
+    }) => () => void;
+}
+/**
+ * Registers an overlay on the shared layer stack while `active`. Render
+ * `<OverlayLayerProvider layer={layer}>` around the overlay's content so
+ * nested overlays become child layers.
+ */
+export declare function useOverlayLayer({ active, modal, parentId: parentIdOption, onEscape, onOutsidePress, elements, }: UseOverlayLayerOptions): OverlayLayer;