@vjdesigns/vjdesigns-ui 0.0.0-stage → 2.0.0

package/dist/hooks/useElementObservers.d.ts

@@ -0,0 +1,70 @@
+import { RefObject } from 'react';
+type ListenerTarget = Window | Document | HTMLElement | MediaQueryList | null | undefined;
+/**
+ * Adds an event listener and removes it on unmount. Always calls the latest
+ * `handler` (no re-subscribing when it changes). `target` defaults to
+ * `window`; pass an element, `document`, or a ref.
+ *
+ * ```tsx
+ * useEventListener("beforeunload", (e) => { if (dirty) e.preventDefault(); });
+ * useEventListener("scroll", onScroll, panelRef, { passive: true });
+ * ```
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(type: K, handler: (event: WindowEventMap[K]) => void, target?: ListenerTarget | RefObject<HTMLElement | null>, options?: boolean | AddEventListenerOptions): void;
+export declare function useEventListener(type: string, handler: (event: Event) => void, target?: ListenerTarget | RefObject<HTMLElement | null>, options?: boolean | AddEventListenerOptions): void;
+/**
+ * Calls `handler` when a pointer press or a focus move lands outside the
+ * returned ref's element (and outside any `ignore` elements). Use it for
+ * custom popups; the library's own overlays already close on outside
+ * presses, through the shared layer stack.
+ *
+ * ```tsx
+ * const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
+ * <div ref={ref}>…</div>
+ * ```
+ */
+export declare function useClickOutside<T extends HTMLElement = HTMLElement>(handler: (event: Event) => void, { enabled, ignore }?: {
+    enabled?: boolean;
+    ignore?: Array<RefObject<HTMLElement | null> | HTMLElement | null>;
+}): RefObject<T | null>;
+export interface UseIntersectionOptions {
+    /** Scroll container to observe within. @default the viewport */
+    root?: Element | Document | null;
+    /** Grows or shrinks the root's box, e.g. `"200px"` to start loading early. */
+    rootMargin?: string;
+    /** Visible share (0-1) that counts as intersecting. @default 0 */
+    threshold?: number | number[];
+    /** Stop observing after the first intersection (lazy loading, entrance effects). @default false */
+    once?: boolean;
+}
+/**
+ * Whether an element is in view (IntersectionObserver). Attach the returned
+ * `ref`; read `isIntersecting` or the full `entry`. Returns false during
+ * server rendering.
+ *
+ * ```tsx
+ * const { ref, isIntersecting } = useIntersection<HTMLDivElement>({ rootMargin: "200px", once: true });
+ * <div ref={ref}>{isIntersecting && <HeavyChart />}</div>
+ * ```
+ */
+export declare function useIntersection<T extends Element = HTMLElement>({ root, rootMargin, threshold, once, }?: UseIntersectionOptions): {
+    ref: (node: T | null) => void;
+    entry: IntersectionObserverEntry | null;
+    isIntersecting: boolean;
+};
+/**
+ * An element's content-box size, kept current as it resizes
+ * (ResizeObserver). Attach the returned `ref`. Both are 0 until measured
+ * (and during server rendering).
+ *
+ * ```tsx
+ * const { ref, width } = useElementSize<HTMLDivElement>();
+ * <div ref={ref}>{width > 600 ? <WideLayout /> : <NarrowLayout />}</div>
+ * ```
+ */
+export declare function useElementSize<T extends Element = HTMLElement>(): {
+    ref: (node: T | null) => void;
+    width: number;
+    height: number;
+};
+export {};

package/dist/hooks/useElementObservers.mjs

@@ -0,0 +1,88 @@
+import { useCallback as e, useEffect as t, useRef as n, useState as r } from "react";
+//#region src/hooks/useElementObservers.ts
+function i(e, r, i, a) {
+	let o = n(r);
+	o.current = r;
+	let s = typeof a == "boolean" ? a : a?.capture, c = typeof a == "object" ? a.passive : void 0, l = typeof a == "object" ? a.once : void 0;
+	t(() => {
+		let t = i && "current" in i ? i.current : i ?? (typeof window < "u" ? window : void 0);
+		if (!t) return;
+		let n = (e) => o.current(e);
+		return t.addEventListener(e, n, {
+			capture: s,
+			passive: c,
+			once: l
+		}), () => t.removeEventListener(e, n, { capture: s });
+	}, [
+		e,
+		i,
+		s,
+		c,
+		l
+	]);
+}
+function a(e, { enabled: r = !0, ignore: i = [] } = {}) {
+	let a = n(null), o = n({
+		handler: e,
+		ignore: i
+	});
+	return o.current = {
+		handler: e,
+		ignore: i
+	}, t(() => {
+		if (!r || typeof document > "u") return;
+		let e = (e) => {
+			let t = e.target;
+			t && t.isConnected && ([a.current, ...o.current.ignore.map((e) => e && "current" in e ? e.current : e)].some((e) => e?.contains(t)) || o.current.handler(e));
+		};
+		return document.addEventListener("pointerdown", e), document.addEventListener("focusin", e), () => {
+			document.removeEventListener("pointerdown", e), document.removeEventListener("focusin", e);
+		};
+	}, [r]), a;
+}
+function o({ root: i, rootMargin: a, threshold: o = 0, once: s = !1 } = {}) {
+	let [c, l] = r(null), [u, d] = r(null), f = n(!1), p = Array.isArray(o) ? o.join(",") : String(o);
+	return t(() => {
+		if (!c || typeof IntersectionObserver > "u" || f.current) return;
+		let e = new IntersectionObserver(([t]) => {
+			d(t), s && t.isIntersecting && (f.current = !0, e.disconnect());
+		}, {
+			root: i,
+			rootMargin: a,
+			threshold: p.split(",").map(Number)
+		});
+		return e.observe(c), () => e.disconnect();
+	}, [
+		c,
+		i,
+		a,
+		p,
+		s
+	]), {
+		ref: e((e) => l(e), []),
+		entry: u,
+		isIntersecting: u?.isIntersecting ?? !1
+	};
+}
+function s() {
+	let [n, i] = r(null), [a, o] = r({
+		width: 0,
+		height: 0
+	});
+	return t(() => {
+		if (!n || typeof ResizeObserver > "u") return;
+		let e = new ResizeObserver(([e]) => {
+			let { width: t, height: n } = e.contentRect;
+			o((e) => e.width === t && e.height === n ? e : {
+				width: t,
+				height: n
+			});
+		});
+		return e.observe(n), () => e.disconnect();
+	}, [n]), {
+		ref: e((e) => i(e), []),
+		...a
+	};
+}
+//#endregion
+export { a as useClickOutside, s as useElementSize, i as useEventListener, o as useIntersection };

package/dist/hooks/useEnvironment.cjs.js

@@ -0,0 +1 @@
+const e=require("./useMediaQuery.cjs.js");let t=require("react");var n=()=>()=>{};function r(){return(0,t.useSyncExternalStore)(n,()=>!0,()=>!1)}function i(){return e.useMediaQuery(`(prefers-reduced-motion: reduce)`)}function a(){return e.useMediaQuery(`(prefers-color-scheme: dark)`)?`dark`:`light`}var o=e=>(window.addEventListener(`online`,e),window.addEventListener(`offline`,e),()=>{window.removeEventListener(`online`,e),window.removeEventListener(`offline`,e)});function s(){return(0,t.useSyncExternalStore)(o,()=>navigator.onLine,()=>!0)}var c=e=>(document.addEventListener(`visibilitychange`,e),()=>document.removeEventListener(`visibilitychange`,e));function l(){return(0,t.useSyncExternalStore)(c,()=>document.visibilityState,()=>`visible`)}var u=e=>(window.addEventListener(`resize`,e),()=>window.removeEventListener(`resize`,e));function d(){let e=(0,t.useSyncExternalStore)(u,()=>`${window.innerWidth}x${window.innerHeight}`,()=>`0x0`);return(0,t.useMemo)(()=>{let[t,n]=e.split(`x`).map(Number);return{width:t,height:n}},[e])}exports.useColorScheme=a,exports.useDocumentVisibility=l,exports.useHydrated=r,exports.useOnline=s,exports.useReducedMotion=i,exports.useViewportSize=d;

package/dist/hooks/useEnvironment.d.ts

@@ -0,0 +1,42 @@
+/**
+ * False during server rendering and hydration, true after. Use it to render
+ * browser-only content (dates in the user's time zone, `window` values)
+ * without a hydration mismatch.
+ *
+ * ```tsx
+ * const hydrated = useHydrated();
+ * return <span>{hydrated ? new Date().toLocaleTimeString() : null}</span>;
+ * ```
+ */
+export declare function useHydrated(): boolean;
+/**
+ * True when the user asked the system to reduce motion. The library's own
+ * transitions already respect it (through the duration tokens); use this for
+ * motion you drive from JavaScript (autoplay, scroll animations).
+ */
+export declare function useReducedMotion(): boolean;
+/**
+ * The system color scheme, `"light"` or `"dark"`, kept in sync (`"light"`
+ * during server rendering). To follow it, pass it to `Theme mode`.
+ */
+export declare function useColorScheme(): "light" | "dark";
+/**
+ * Whether the browser has a network connection, kept in sync (true during
+ * server rendering). Pair a visible change (a Banner) with a polite
+ * announcement when it goes offline.
+ */
+export declare function useOnline(): boolean;
+/**
+ * `"visible"` or `"hidden"` (another tab, minimized window), kept in sync.
+ * Use it to pause polling, video, or animations in the background.
+ */
+export declare function useDocumentVisibility(): DocumentVisibilityState;
+/**
+ * The viewport's width and height in CSS pixels, kept in sync (0 × 0 during
+ * server rendering). For layout decisions, prefer CSS or `useMediaQuery`;
+ * use this when you need the numbers.
+ */
+export declare function useViewportSize(): {
+    width: number;
+    height: number;
+};

package/dist/hooks/useEnvironment.mjs

@@ -0,0 +1,36 @@
+import { useMediaQuery as e } from "./useMediaQuery.mjs";
+import { useMemo as t, useSyncExternalStore as n } from "react";
+//#region src/hooks/useEnvironment.ts
+var r = () => () => {};
+function i() {
+	return n(r, () => !0, () => !1);
+}
+function a() {
+	return e("(prefers-reduced-motion: reduce)");
+}
+function o() {
+	return e("(prefers-color-scheme: dark)") ? "dark" : "light";
+}
+var s = (e) => (window.addEventListener("online", e), window.addEventListener("offline", e), () => {
+	window.removeEventListener("online", e), window.removeEventListener("offline", e);
+});
+function c() {
+	return n(s, () => navigator.onLine, () => !0);
+}
+var l = (e) => (document.addEventListener("visibilitychange", e), () => document.removeEventListener("visibilitychange", e));
+function u() {
+	return n(l, () => document.visibilityState, () => "visible");
+}
+var d = (e) => (window.addEventListener("resize", e), () => window.removeEventListener("resize", e));
+function f() {
+	let e = n(d, () => `${window.innerWidth}x${window.innerHeight}`, () => "0x0");
+	return t(() => {
+		let [t, n] = e.split("x").map(Number);
+		return {
+			width: t,
+			height: n
+		};
+	}, [e]);
+}
+//#endregion
+export { o as useColorScheme, u as useDocumentVisibility, i as useHydrated, c as useOnline, a as useReducedMotion, f as useViewportSize };

package/dist/hooks/useFloatingPosition.cjs.js

@@ -0,0 +1 @@
+const e=require("./elementSource.cjs.js");let t=require("react");var n={top:`bottom`,bottom:`top`,left:`right`,right:`left`};function r(e,t,n,r){let[i,a]=n.split(`-`);return i===`top`||i===`bottom`?{top:i===`top`?e.top-t.height-r:e.bottom+r,left:a===`start`?e.left:a===`end`?e.right-t.width:e.left+e.width/2-t.width/2}:{left:i===`left`?e.left-t.width-r:e.right+r,top:a===`start`?e.top:a===`end`?e.bottom-t.height:e.top+e.height/2-t.height/2}}function i(e,t,n,r){switch(e){case`top`:return t.top>=r;case`bottom`:return t.top+n.height<=window.innerHeight-r;case`left`:return t.left>=r;case`right`:return t.left+n.width<=window.innerWidth-r}}function a(e,t){switch(e){case`top`:return t.top;case`bottom`:return window.innerHeight-t.bottom;case`left`:return t.left;case`right`:return window.innerWidth-t.right}}function o(e,t,n){return t-2*n<0?t/2:Math.min(Math.max(e,n),t-n)}function s(e,t){return!!e&&Math.abs(e.top-t.top)<.5&&Math.abs(e.left-t.left)<.5&&e.placement===t.placement&&e.arrow.side===t.arrow.side&&Math.abs((e.arrow.x??0)-(t.arrow.x??0))<.5&&Math.abs((e.arrow.y??0)-(t.arrow.y??0))<.5}function c(c,l,{open:u,placement:d=`bottom`,offset:f=8,flip:p=!0,padding:m=8,arrowPadding:h=0}){let[g,_]=(0,t.useState)(null),v=e.useResolvedElement(c),y=e.useResolvedElement(l),b=(0,t.useRef)({anchor:c,floating:l});b.current={anchor:c,floating:l};let x=(0,t.useCallback)(()=>{let t=e.resolveElement(b.current.anchor),c=e.resolveElement(b.current.floating);if(!t||!c)return;let l=t.getBoundingClientRect(),u=c.getBoundingClientRect(),[g,v]=d.split(`-`),y=g,x=r(l,u,d,f);if(p&&!i(g,x,u,m)){let e=n[g],t=r(l,u,v?`${e}-${v}`:e,f);(i(e,t,u,m)||a(e,l)>a(g,l))&&(y=e,x=t)}let S=y===g?d:v?`${y}-${v}`:y;x.left=Math.max(m,Math.min(x.left,window.innerWidth-u.width-m)),x.top=Math.max(m,Math.min(x.top,window.innerHeight-u.height-m));let C=y===`top`||y===`bottom`?{side:y,x:o(l.left+l.width/2-x.left,u.width,h)}:{side:y,y:o(l.top+l.height/2-x.top,u.height,h)},w={...x,placement:S,arrow:C};_(e=>s(e,w)?e:w)},[d,f,p,m,h]);(0,t.useLayoutEffect)(()=>{if(!u){_(null);return}if(!v||!y)return;x(),window.addEventListener(`resize`,x),window.addEventListener(`scroll`,x,!0);let e=typeof ResizeObserver<`u`?new ResizeObserver(()=>x()):null;return e?.observe(v),e?.observe(y),()=>{window.removeEventListener(`resize`,x),window.removeEventListener(`scroll`,x,!0),e?.disconnect()}},[u,x,v,y]);let S=u&&g!==null;return{style:S?{position:`fixed`,top:g.top,left:g.left}:{position:`fixed`,top:0,left:0,visibility:`hidden`},placement:S?g.placement:d,arrow:S?g.arrow:null,isPositioned:S,update:x}}exports.useFloatingPosition=c;

package/dist/hooks/useFloatingPosition.d.ts

@@ -0,0 +1,55 @@
+import { CSSProperties } from 'react';
+import { Placement } from '../types/common';
+import { ElementSource } from './elementSource';
+export interface UseFloatingPositionOptions {
+    /** Compute only while open. */
+    open: boolean;
+    placement?: Placement;
+    /** Gap between anchor and floating element, in px. Default 8. */
+    offset?: number;
+    /** Flip to the opposite side when there isn't room on the main axis. Default true. */
+    flip?: boolean;
+    /** Minimum distance from the viewport edge, in px. Default 8. */
+    padding?: number;
+    /**
+     * Minimum distance between the arrow's center and the floating element's
+     * corners, in px (e.g. corner radius plus half the arrow). Default 0.
+     */
+    arrowPadding?: number;
+}
+/** Which side of the anchor the floating element ended up on. */
+export type FloatingSide = "top" | "bottom" | "left" | "right";
+/**
+ * Where to put an arrow so it points at the anchor's center, in px relative
+ * to the floating element's border box. `x` is set for `top`/`bottom`
+ * placements, `y` for `left`/`right`. `side` is the side of the anchor the
+ * floating element sits on, so the arrow goes on the opposite edge.
+ */
+export interface FloatingArrow {
+    x?: number;
+    y?: number;
+    side: FloatingSide;
+}
+export interface FloatingPosition {
+    /** Apply to the floating element (it is positioned `fixed`). Hidden until measured. */
+    style: CSSProperties;
+    /** The placement actually used after flipping. */
+    placement: Placement;
+    /** Arrow coordinates, or null until measured. */
+    arrow: FloatingArrow | null;
+    /** True once a position has been computed for the current open session. */
+    isPositioned: boolean;
+    /** Recompute manually, e.g. after content changes size. */
+    update: () => void;
+}
+/**
+ * Positions a floating element (Tooltip, Popover, Menu, Select listbox)
+ * next to an anchor. Flips to the opposite side when the main axis doesn't
+ * fit, clamps to the viewport, and reports arrow coordinates. Uses
+ * `position: fixed`, so render the floating element in a Portal.
+ *
+ * Both elements may be passed as elements or refs; refs are re-checked
+ * after every commit, so a floating element that mounts late is measured
+ * and observed as soon as it exists.
+ */
+export declare function useFloatingPosition(anchor: ElementSource, floating: ElementSource, { open, placement, offset, flip, padding, arrowPadding, }: UseFloatingPositionOptions): FloatingPosition;

package/dist/hooks/useFloatingPosition.mjs

@@ -0,0 +1,116 @@
+import { resolveElement as e, useResolvedElement as t } from "./elementSource.mjs";
+import { useCallback as n, useLayoutEffect as r, useRef as i, useState as a } from "react";
+//#region src/hooks/useFloatingPosition.ts
+var o = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+function s(e, t, n, r) {
+	let [i, a] = n.split("-");
+	return i === "top" || i === "bottom" ? {
+		top: i === "top" ? e.top - t.height - r : e.bottom + r,
+		left: a === "start" ? e.left : a === "end" ? e.right - t.width : e.left + e.width / 2 - t.width / 2
+	} : {
+		left: i === "left" ? e.left - t.width - r : e.right + r,
+		top: a === "start" ? e.top : a === "end" ? e.bottom - t.height : e.top + e.height / 2 - t.height / 2
+	};
+}
+function c(e, t, n, r) {
+	switch (e) {
+		case "top": return t.top >= r;
+		case "bottom": return t.top + n.height <= window.innerHeight - r;
+		case "left": return t.left >= r;
+		case "right": return t.left + n.width <= window.innerWidth - r;
+	}
+}
+function l(e, t) {
+	switch (e) {
+		case "top": return t.top;
+		case "bottom": return window.innerHeight - t.bottom;
+		case "left": return t.left;
+		case "right": return window.innerWidth - t.right;
+	}
+}
+function u(e, t, n) {
+	return t - 2 * n < 0 ? t / 2 : Math.min(Math.max(e, n), t - n);
+}
+function d(e, t) {
+	return !!e && Math.abs(e.top - t.top) < .5 && Math.abs(e.left - t.left) < .5 && e.placement === t.placement && e.arrow.side === t.arrow.side && Math.abs((e.arrow.x ?? 0) - (t.arrow.x ?? 0)) < .5 && Math.abs((e.arrow.y ?? 0) - (t.arrow.y ?? 0)) < .5;
+}
+function f(f, p, { open: m, placement: h = "bottom", offset: g = 8, flip: _ = !0, padding: v = 8, arrowPadding: y = 0 }) {
+	let [b, x] = a(null), S = t(f), C = t(p), w = i({
+		anchor: f,
+		floating: p
+	});
+	w.current = {
+		anchor: f,
+		floating: p
+	};
+	let T = n(() => {
+		let t = e(w.current.anchor), n = e(w.current.floating);
+		if (!t || !n) return;
+		let r = t.getBoundingClientRect(), i = n.getBoundingClientRect(), [a, f] = h.split("-"), p = a, m = s(r, i, h, g);
+		if (_ && !c(a, m, i, v)) {
+			let e = o[a], t = s(r, i, f ? `${e}-${f}` : e, g);
+			(c(e, t, i, v) || l(e, r) > l(a, r)) && (p = e, m = t);
+		}
+		let b = p === a ? h : f ? `${p}-${f}` : p;
+		m.left = Math.max(v, Math.min(m.left, window.innerWidth - i.width - v)), m.top = Math.max(v, Math.min(m.top, window.innerHeight - i.height - v));
+		let S = p === "top" || p === "bottom" ? {
+			side: p,
+			x: u(r.left + r.width / 2 - m.left, i.width, y)
+		} : {
+			side: p,
+			y: u(r.top + r.height / 2 - m.top, i.height, y)
+		}, C = {
+			...m,
+			placement: b,
+			arrow: S
+		};
+		x((e) => d(e, C) ? e : C);
+	}, [
+		h,
+		g,
+		_,
+		v,
+		y
+	]);
+	r(() => {
+		if (!m) {
+			x(null);
+			return;
+		}
+		if (!S || !C) return;
+		T(), window.addEventListener("resize", T), window.addEventListener("scroll", T, !0);
+		let e = typeof ResizeObserver < "u" ? new ResizeObserver(() => T()) : null;
+		return e?.observe(S), e?.observe(C), () => {
+			window.removeEventListener("resize", T), window.removeEventListener("scroll", T, !0), e?.disconnect();
+		};
+	}, [
+		m,
+		T,
+		S,
+		C
+	]);
+	let E = m && b !== null;
+	return {
+		style: E ? {
+			position: "fixed",
+			top: b.top,
+			left: b.left
+		} : {
+			position: "fixed",
+			top: 0,
+			left: 0,
+			visibility: "hidden"
+		},
+		placement: E ? b.placement : h,
+		arrow: E ? b.arrow : null,
+		isPositioned: E,
+		update: T
+	};
+}
+//#endregion
+export { f as useFloatingPosition };

package/dist/hooks/useFocusTrap.cjs.js

@@ -0,0 +1 @@
+const e=require("./elementSource.cjs.js"),t=require("./useOverlayLayer.cjs.js");let n=require("react");var r=[`a[href]`,`area[href]`,`button:not([disabled])`,`input:not([disabled]):not([type='hidden'])`,`select:not([disabled])`,`textarea:not([disabled])`,`iframe`,`summary`,`[contenteditable='true']`,`[tabindex]:not([tabindex='-1'])`].join(`,`);function i(e){return!e.isConnected||e.closest(`[inert]`)||e.getClientRects().length===0?!1:window.getComputedStyle(e).visibility!==`hidden`}function a(e){return Array.from(e.querySelectorAll(r)).filter(i)}function o(t){return typeof t==`function`?t()??null:e.resolveElement(t)}function s(e){return!e||!e.isConnected||e.closest(`[inert]`)?!1:(e.focus({preventScroll:!0}),document.activeElement===e)}function c(e,{frames:t=10}={}){let n=!1,r=0;if(s(e()))return()=>{};let i=t=>{n||t<=0||(r=requestAnimationFrame(()=>{n||s(e())||i(t-1)}))};return queueMicrotask(()=>{n||s(e())||i(t)}),()=>{n=!0,cancelAnimationFrame(r)}}function l(r,i){let{active:l,layer:u,paused:d=!1}=i,f=e.useResolvedElement(r),p=t.useOverlayLayer({active:l&&!u,modal:!0,elements:()=>[f]}),m=u??p,h=(0,n.useRef)(i);h.current=i;let g=(0,n.useRef)(m);g.current=m;let _=(0,n.useRef)(null);(0,n.useLayoutEffect)(()=>{if(!l)return;let e=document.activeElement;return _.current=e instanceof HTMLElement&&e!==document.body?e:null,()=>{let{restoreFocus:e=!0,finalFocus:t,finalFocusRef:n}=h.current;if(!e)return;let r=_.current;_.current=null,c(()=>{let e=o(t)??n?.current??null,i=e?.isConnected?e:r;return i?.isConnected?i:null})}},[l]);let v=l&&!!f&&!d&&!m.hasModalAbove;(0,n.useEffect)(()=>{if(!v||!f)return;let e=()=>{let e=document.activeElement;return!!e&&(f.contains(e)||g.current.childContains(e))},t=()=>{let{initialFocus:e,initialFocusRef:t}=h.current,n=o(e)??t?.current??a(f)[0]??f;return n===f&&!f.hasAttribute(`tabindex`)&&f.setAttribute(`tabindex`,`-1`),n},n=e()?()=>{}:c(()=>e()?document.activeElement:t()),r=e=>{if(e.key!==`Tab`||e.defaultPrevented)return;let t=document.activeElement;if(t&&!f.contains(t)&&g.current.childContains(t))return;let n=a(f);if(n.length===0){e.preventDefault(),t!==f&&s(f);return}let r=n[0],i=n[n.length-1];e.shiftKey&&(t===r||t===f||!f.contains(t))?(e.preventDefault(),i.focus()):!e.shiftKey&&(t===i||!f.contains(t))&&(e.preventDefault(),r.focus())};return document.addEventListener(`keydown`,r),()=>{n(),document.removeEventListener(`keydown`,r)}},[v,f])}exports.FOCUSABLE=r,exports.focusWhenReady=c,exports.getFocusable=a,exports.isFocusableNow=i,exports.useFocusTrap=l;

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,52 @@
+import { RefObject } from 'react';
+import { ElementSource } from './elementSource';
+import { OverlayLayer } from './useOverlayLayer';
+/** Selector for elements that can take keyboard focus. */
+export declare const FOCUSABLE: string;
+/** True when `el` is rendered, not inert, and not `visibility: hidden`. */
+export declare function isFocusableNow(el: HTMLElement): boolean;
+/** Returns the visible, focusable elements inside `container`, in DOM order. */
+export declare function getFocusable(container: HTMLElement): HTMLElement[];
+/** An element, a ref to one, or a function returning one (read when needed). */
+export type FocusTarget = ElementSource | (() => HTMLElement | null | undefined);
+/**
+ * Moves focus to `el` once it can take it. Tries right away, then after a
+ * microtask (so inert set by the closing overlay is gone), then for a few
+ * animation frames. Returns a cancel function.
+ */
+export declare function focusWhenReady(getTarget: () => HTMLElement | null, { frames }?: {
+    frames?: number;
+}): () => void;
+export interface UseFocusTrapOptions {
+    /** Trap only while active (e.g. while a Modal is open). */
+    active: boolean;
+    /** Element to focus on activation. Defaults to the first focusable element, then the container. */
+    initialFocus?: FocusTarget;
+    /** Same as `initialFocus`, as a ref. Kept for compatibility. */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Element to focus on deactivation. Defaults to the element focused before activation. */
+    finalFocus?: FocusTarget;
+    /** Same as `finalFocus`, as a ref. */
+    finalFocusRef?: RefObject<HTMLElement | null>;
+    /** Return focus on deactivation (to `finalFocus`, or the previously focused element). Default true. */
+    restoreFocus?: boolean;
+    /**
+     * The overlay layer this trap belongs to (from `useOverlayLayer`, with
+     * `modal: true`). When omitted, the trap registers its own modal layer.
+     * Either way the trap pauses while a modal layer is open above it.
+     */
+    layer?: OverlayLayer;
+    /** Pause the trap without deactivating it (no focus restore). */
+    paused?: boolean;
+}
+/**
+ * Keeps Tab / Shift+Tab focus inside `container` while active, and
+ * restores focus when it deactivates (WCAG 2.1.2, 2.4.3). Used by Modal,
+ * Drawer, and any other modal surface.
+ *
+ * `container` can be an element (re-runs when it appears) or a ref (checked
+ * after every commit). Only the topmost modal layer's trap runs; focus
+ * inside a child layer (a Popover or Tooltip opened from the trapped
+ * surface) is left alone.
+ */
+export declare function useFocusTrap(container: ElementSource, options: UseFocusTrapOptions): void;

package/dist/hooks/useFocusTrap.mjs

@@ -0,0 +1,93 @@
+import { resolveElement as e, useResolvedElement as t } from "./elementSource.mjs";
+import { useOverlayLayer as n } from "./useOverlayLayer.mjs";
+import { useEffect as r, useLayoutEffect as i, useRef as a } from "react";
+//#region src/hooks/useFocusTrap.ts
+var o = [
+	"a[href]",
+	"area[href]",
+	"button:not([disabled])",
+	"input:not([disabled]):not([type='hidden'])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"iframe",
+	"summary",
+	"[contenteditable='true']",
+	"[tabindex]:not([tabindex='-1'])"
+].join(",");
+function s(e) {
+	return !e.isConnected || e.closest("[inert]") || e.getClientRects().length === 0 ? !1 : window.getComputedStyle(e).visibility !== "hidden";
+}
+function c(e) {
+	return Array.from(e.querySelectorAll(o)).filter(s);
+}
+function l(t) {
+	return typeof t == "function" ? t() ?? null : e(t);
+}
+function u(e) {
+	return !e || !e.isConnected || e.closest("[inert]") ? !1 : (e.focus({ preventScroll: !0 }), document.activeElement === e);
+}
+function d(e, { frames: t = 10 } = {}) {
+	let n = !1, r = 0;
+	if (u(e())) return () => {};
+	let i = (t) => {
+		n || t <= 0 || (r = requestAnimationFrame(() => {
+			n || u(e()) || i(t - 1);
+		}));
+	};
+	return queueMicrotask(() => {
+		n || u(e()) || i(t);
+	}), () => {
+		n = !0, cancelAnimationFrame(r);
+	};
+}
+function f(e, o) {
+	let { active: s, layer: f, paused: p = !1 } = o, m = t(e), h = n({
+		active: s && !f,
+		modal: !0,
+		elements: () => [m]
+	}), g = f ?? h, _ = a(o);
+	_.current = o;
+	let v = a(g);
+	v.current = g;
+	let y = a(null);
+	i(() => {
+		if (!s) return;
+		let e = document.activeElement;
+		return y.current = e instanceof HTMLElement && e !== document.body ? e : null, () => {
+			let { restoreFocus: e = !0, finalFocus: t, finalFocusRef: n } = _.current;
+			if (!e) return;
+			let r = y.current;
+			y.current = null, d(() => {
+				let e = l(t) ?? n?.current ?? null, i = e?.isConnected ? e : r;
+				return i?.isConnected ? i : null;
+			});
+		};
+	}, [s]);
+	let b = s && !!m && !p && !g.hasModalAbove;
+	r(() => {
+		if (!b || !m) return;
+		let e = () => {
+			let e = document.activeElement;
+			return !!e && (m.contains(e) || v.current.childContains(e));
+		}, t = () => {
+			let { initialFocus: e, initialFocusRef: t } = _.current, n = l(e) ?? t?.current ?? c(m)[0] ?? m;
+			return n === m && !m.hasAttribute("tabindex") && m.setAttribute("tabindex", "-1"), n;
+		}, n = e() ? () => {} : d(() => e() ? document.activeElement : t()), r = (e) => {
+			if (e.key !== "Tab" || e.defaultPrevented) return;
+			let t = document.activeElement;
+			if (t && !m.contains(t) && v.current.childContains(t)) return;
+			let n = c(m);
+			if (n.length === 0) {
+				e.preventDefault(), t !== m && u(m);
+				return;
+			}
+			let r = n[0], i = n[n.length - 1];
+			e.shiftKey && (t === r || t === m || !m.contains(t)) ? (e.preventDefault(), i.focus()) : !e.shiftKey && (t === i || !m.contains(t)) && (e.preventDefault(), r.focus());
+		};
+		return document.addEventListener("keydown", r), () => {
+			n(), document.removeEventListener("keydown", r);
+		};
+	}, [b, m]);
+}
+//#endregion
+export { o as FOCUSABLE, d as focusWhenReady, c as getFocusable, s as isFocusableNow, f as useFocusTrap };

package/dist/hooks/useFormReset.cjs.js

@@ -0,0 +1 @@
+let e=require("react");function t(t,n,r=!0){let i=(0,e.useRef)(n);i.current=n,(0,e.useEffect)(()=>{if(!r)return;let e=typeof t==`function`?t():t.current;if(!e)return;let n=(`form`in e?e.form:null)??e.closest(`form`);if(!n)return;let a=()=>i.current();return n.addEventListener(`reset`,a),()=>n.removeEventListener(`reset`,a)},[r])}exports.useFormReset=t;

package/dist/hooks/useFormReset.d.ts

@@ -0,0 +1,17 @@
+import { RefObject } from 'react';
+/**
+ * Calls `onReset` when the form that contains `target`'s element is reset
+ * (`<button type="reset">` or `form.reset()`).
+ *
+ * Controls that keep their value in React state (so the DOM input is always
+ * controlled) don't follow a native reset on their own; uncontrolled ones
+ * use this to restore their `defaultValue`. Pass `enabled: false` while the
+ * component is controlled, since then the parent owns the value.
+ *
+ * The form is found from the element's `form` property (a form control,
+ * including one associated with the `form` attribute) or its closest
+ * `<form>` ancestor. `onReset` always sees the latest props.
+ */
+export declare function useFormReset(
+/** An element inside the form: a ref, or a getter (e.g. `() => document.getElementById(id)`). */
+target: RefObject<HTMLElement | null> | (() => HTMLElement | null), onReset: () => void, enabled?: boolean): void;

package/dist/hooks/useFormReset.mjs

@@ -0,0 +1,16 @@
+import { useEffect as e, useRef as t } from "react";
+//#region src/hooks/useFormReset.ts
+function n(n, r, i = !0) {
+	let a = t(r);
+	a.current = r, e(() => {
+		if (!i) return;
+		let e = typeof n == "function" ? n() : n.current;
+		if (!e) return;
+		let t = ("form" in e ? e.form : null) ?? e.closest("form");
+		if (!t) return;
+		let r = () => a.current();
+		return t.addEventListener("reset", r), () => t.removeEventListener("reset", r);
+	}, [i]);
+}
+//#endregion
+export { n as useFormReset };

package/dist/hooks/useFormValidation.cjs.js

@@ -0,0 +1 @@
+const e=require("../components/utilities/LocaleProvider/LocaleProvider.cjs.js"),t=require("../utils/validators.cjs.js");let n=require("react");var r=`input:not([type="hidden"]):not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]`,i=e=>e.getClientRects().length>0,a=e=>e instanceof HTMLElement&&e.matches(r)&&i(e)&&!(e instanceof HTMLInputElement&&e.type===`hidden`);function o(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 s(e,t){return e.name||o(e,t)||e.id||void 0}function c(e,t){let n=Array.from(t.querySelectorAll(`[name="${CSS.escape(e)}"]`)),i=n.find(a);if(i)return i;for(let e of n)for(let n=e.parentElement,i=0;n&&n!==t&&i<6;n=n.parentElement,i++){let e=Array.from(n.querySelectorAll(r)).find(a);if(e)return e}let o=t.querySelector(`#${CSS.escape(e)}`);return o&&a(o)?o:void 0}function l(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 u(e,n,r){let i=e instanceof HTMLInputElement&&e.type===`email`&&e.value&&!e.multiple&&!t.isEmail(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 d=(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 f(e,t){if(!t)return e;let n=e=>{let n=c(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 p(t={}){let{rules:r={},onValid:i,focusOnError:a=!0}=t,{messages:o,locale:p}=e.useLocale(),m=(0,n.useRef)(null),h=(0,n.useRef)(null),[g,_]=(0,n.useState)([]),[v,y]=(0,n.useState)(0),[b,x]=(0,n.useState)(!1),[S,C]=(0,n.useState)(0),w=(0,n.useRef)({rules:r,onValid:i,messages:o.validation,locale:p});w.current={rules:r,onValid:i,messages:o.validation,locale:p};let T=(0,n.useCallback)((e,t,n)=>({name:e,message:t,source:n,get id(){let t=m.current;return t&&c(e,t)?.id||void 0},focus:()=>{let t=m.current;(t&&c(e,t))?.focus()}}),[]),E=(0,n.useCallback)(e=>{let t=m.current,n=new Map;if(!t)return n;let{rules:r,messages:i,locale:a}=w.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=s(e,t);if(!r||!o(r)||n.has(r))continue;let c=u(e,i,a);c&&n.set(r,c)}let c=l(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(c[e],{name:e,values:c,messages:i});if(t){n.set(e,t);break}}return n},[]),D=(0,n.useCallback)((e,t,{onlyClear:n=!1}={})=>{_(r=>{let i=e=>!t||t.includes(e),a=[];for(let o of r)i(o.name)?n?e.has(o.name)&&a.push(o):t&&o.source===`server`&&!e.has(o.name)&&a.push(o):a.push(o);if(!n)for(let[t,n]of e)a.push(T(t,n,`client`));let o=f(a,m.current);return d(r,o)?r:o})},[T]),O=(0,n.useCallback)(e=>{let t=E(e);return D(t,e),t.size===0},[E,D]),k=(0,n.useCallback)(e=>{let t=Object.entries(e).filter(([,e])=>e);t.length&&(_(n=>f([...n.filter(t=>!(t.name in e)),...t.map(([e,t])=>T(e,t,`server`))],m.current)),a&&C(e=>e+1))},[T,a]),A=(0,n.useCallback)(e=>{_(t=>e?t.filter(t=>!e.includes(t.name)):[])},[]),j=(0,n.useCallback)(()=>m.current?l(m.current):{},[]);(0,n.useEffect)(()=>{S&&a&&(h.current&&h.current.isConnected?h.current.focus():g[0]?.focus())},[S]);let M=(0,n.useCallback)(e=>{y(e=>e+1);let t=E();if(D(t),t.size>0){e.preventDefault(),a&&C(e=>e+1);return}let n=w.current.onValid;if(!n)return;e.preventDefault();let r=n(l(e.currentTarget),e);r&&typeof r.then==`function`?(x(!0),r.then(e=>{e&&k(e)}).finally(()=>x(!1))):r&&k(r)},[E,D,k,a]),N=e=>{let t=m.current,n=e.target;if(t&&v!==0&&n instanceof Element)return s(n,t)},P=e=>{if(e.target instanceof HTMLSelectElement)return;let t=N(e);t&&(_(e=>e.some(e=>e.name===t&&e.source===`server`)?e.filter(e=>e.name!==t||e.source!==`server`):e),D(E([t]),[t],{onlyClear:!0}))},F=e=>{let t=N(e);if(!t)return;let n=g.filter(e=>e.source===`client`).map(e=>e.name),r=Array.from(new Set([t,...n]));D(E(r),r)},I=(0,n.useMemo)(()=>Object.fromEntries(g.map(e=>[e.name,e.message])),[g]);return{formProps:{ref:e=>{m.current=e},noValidate:!0,onSubmit:M,onInput:P,onChange:e=>{let t=e.target;t instanceof HTMLTextAreaElement||t instanceof HTMLInputElement&&![`checkbox`,`radio`,`file`].includes(t.type)||F(e)},onBlur:F},formRef:m,errors:I,errorList:g,summaryRef:h,isSubmitting:b,submitCount:v,validate:O,setErrors:k,clearErrors:A,getValues:j}}exports.useFormValidation=p;