@thewrong/ui 0.1.0 → 0.3.0

package/dist/components/typewriter-text/TypewriterText.esm.js

@@ -0,0 +1,58 @@
+import { useEffect as e, useRef as t, useState as n } from "react";
+import { jsx as r, jsxs as i } from "react/jsx-runtime";
+import { motion as a, useReducedMotion as o } from "motion/react";
+//#region src/components/typewriter-text/TypewriterText.tsx
+var s = 32, c = 90;
+function l(e) {
+	let t = [], n = /\S+\s*/g, r = n.exec(e);
+	for (; r !== null;) t.push(r.index + r[0].length), r = n.exec(e);
+	return t.length === 0 && e.length > 0 && t.push(e.length), t;
+}
+function u({ text: u, delay: d = 0, animate: f = !0, onComplete: p, unit: m = "character" }) {
+	let h = o() ?? !1, g = f && !h, [_, v] = n(() => g ? 0 : u.length), y = t(p), b = t(null);
+	y.current = p, e(() => {
+		if (!g || u.length === 0) {
+			v(u.length), b.current !== u && (b.current = u, y.current?.());
+			return;
+		}
+		b.current = null, v(0);
+		let e, t = m === "word" ? l(u) : Array.from({ length: u.length }, (e, t) => t + 1), n = m === "word" ? c : s, r = 0, i = window.setTimeout(() => {
+			e = window.setInterval(() => {
+				let n = t[r] ?? u.length;
+				r += 1, v(n), r >= t.length && (e !== void 0 && window.clearInterval(e), y.current?.());
+			}, n);
+		}, d);
+		return () => {
+			window.clearTimeout(i), e !== void 0 && window.clearInterval(e);
+		};
+	}, [
+		d,
+		g,
+		u,
+		m
+	]);
+	let x = g && _ < u.length;
+	return /* @__PURE__ */ i("span", {
+		"aria-label": u,
+		children: [/* @__PURE__ */ r("span", {
+			"aria-hidden": "true",
+			children: u.slice(0, _)
+		}), x ? /* @__PURE__ */ r(a.span, {
+			"aria-hidden": "true",
+			animate: { opacity: [
+				0,
+				1,
+				1,
+				0
+			] },
+			transition: {
+				duration: .8,
+				ease: "linear",
+				repeat: Infinity
+			},
+			children: "|"
+		}) : null]
+	});
+}
+//#endregion
+export { u as TypewriterText };

package/dist/components/typewriter-text/index.d.ts

@@ -0,0 +1,2 @@
+export { TypewriterText } from './TypewriterText.js';
+export type { TypewriterTextProps } from './types.js';

package/dist/components/typewriter-text/types.d.ts

@@ -0,0 +1,12 @@
+export interface TypewriterTextProps {
+    /** 표시할 전체 문자열. */
+    text: string;
+    /** 시작 전 대기 시간(ms). 기본 0. */
+    delay?: number;
+    /** false면 즉시 표시한다. 재방문 시 효과를 생략하려면 상위에서 이 값을 관리한다. */
+    animate?: boolean;
+    /** 타이핑 또는 즉시 표시가 끝나면 호출된다. */
+    onComplete?: () => void;
+    /** 글자 또는 공백을 포함한 단어 단위로 표시한다. 기본 character. */
+    unit?: "character" | "word";
+}

package/dist/components/typing-dots/TypingDots.cjs

@@ -0,0 +1 @@
+let e=require("react/jsx-runtime"),t=require("motion/react");var n=3,r=1.2,i=r/n;function a({label:a}){let o=(0,t.useReducedMotion)()??!1;return(0,e.jsx)(`span`,{role:`status`,"aria-label":a,className:`inline-flex items-center gap-[0.2em] align-baseline`,children:Array.from({length:n},(n,a)=>(0,e.jsx)(t.motion.span,{"aria-hidden":`true`,className:`inline-block size-[0.35em] rounded-full bg-current`,style:{opacity:o?.4:void 0},animate:o?void 0:{opacity:[.3,1,.3],y:[`0em`,`-0.22em`,`0em`]},transition:o?void 0:{duration:r,ease:`easeInOut`,repeat:1/0,delay:a*i}},a))})}exports.TypingDots=a;

package/dist/components/typing-dots/TypingDots.d.ts

@@ -0,0 +1,10 @@
+import { TypingDotsProps } from './types.js';
+/**
+ * 값이 아직 없는 자리에 놓는 점 3개 인디케이터입니다. 채팅의 "입력 중"과
+ * 값 로딩("잔고를 불러오는 중")에 모두 씁니다.
+ *
+ * **색과 크기를 스스로 정하지 않습니다.** 점은 `currentColor`를 쓰고 지름은
+ * `em`이라 놓인 자리의 글자색·글자크기를 그대로 따릅니다.
+ * 색을 바꾸려면 부모의 text 색을 바꿉니다.
+ */
+export declare function TypingDots({ label }: TypingDotsProps): import("react").JSX.Element;

package/dist/components/typing-dots/TypingDots.esm.js

@@ -0,0 +1,37 @@
+import { jsx as e } from "react/jsx-runtime";
+import { motion as t, useReducedMotion as n } from "motion/react";
+//#region src/components/typing-dots/TypingDots.tsx
+var r = 3, i = 1.2, a = i / r;
+function o({ label: o }) {
+	let s = n() ?? !1;
+	return /* @__PURE__ */ e("span", {
+		role: "status",
+		"aria-label": o,
+		className: "inline-flex items-center gap-[0.2em] align-baseline",
+		children: Array.from({ length: r }, (n, r) => /* @__PURE__ */ e(t.span, {
+			"aria-hidden": "true",
+			className: "inline-block size-[0.35em] rounded-full bg-current",
+			style: { opacity: s ? .4 : void 0 },
+			animate: s ? void 0 : {
+				opacity: [
+					.3,
+					1,
+					.3
+				],
+				y: [
+					"0em",
+					"-0.22em",
+					"0em"
+				]
+			},
+			transition: s ? void 0 : {
+				duration: i,
+				ease: "easeInOut",
+				repeat: Infinity,
+				delay: r * a
+			}
+		}, r))
+	});
+}
+//#endregion
+export { o as TypingDots };

package/dist/components/typing-dots/index.d.ts

@@ -0,0 +1,2 @@
+export { TypingDots } from './TypingDots.js';
+export type { TypingDotsProps } from './types.js';

package/dist/components/typing-dots/types.d.ts

@@ -0,0 +1,4 @@
+export interface TypingDotsProps {
+    /** 스크린리더에 읽히는 상태 문구. 점 자체는 aria-hidden이다. */
+    label: string;
+}

package/dist/hooks/awaitableOverlayController.cjs

@@ -0,0 +1 @@
+function e(){let e=null,t=t=>{if(!e)return!1;let n=e;return e=null,n(t),!0};return{open(){return t({type:`cancel`}),new Promise(t=>{e=t})},settle:t}}exports.createAwaitableOverlayController=e;

package/dist/hooks/awaitableOverlayController.d.ts

@@ -0,0 +1,6 @@
+import { AwaitableOverlayResult } from './useAwaitableOverlay.js';
+/** 한 번에 하나의 응답만 기다리고 이전 요청은 취소로 끝낸다. */
+export declare function createAwaitableOverlayController<TResult>(): {
+    open(): Promise<AwaitableOverlayResult<TResult>>;
+    settle: (result: AwaitableOverlayResult<TResult>) => boolean;
+};

package/dist/hooks/awaitableOverlayController.esm.js

@@ -0,0 +1,18 @@
+//#region src/hooks/awaitableOverlayController.ts
+function e() {
+	let e = null, t = (t) => {
+		if (!e) return !1;
+		let n = e;
+		return e = null, n(t), !0;
+	};
+	return {
+		open() {
+			return t({ type: "cancel" }), new Promise((t) => {
+				e = t;
+			});
+		},
+		settle: t
+	};
+}
+//#endregion
+export { e as createAwaitableOverlayController };

package/dist/hooks/index.d.ts

@@ -0,0 +1,17 @@
+export { useClickOutside } from './useClickOutside.js';
+export { useMediaQuery, useIsMobile, MOBILE_MEDIA_QUERY, } from './useMediaQuery.js';
+export { useBottomSheetDrag } from './useBottomSheetDrag.js';
+export { useScrollLock } from './useScrollLock.js';
+export { useFocusTrap, type UseFocusTrapOptions } from './useFocusTrap.js';
+export { useInfiniteScroll } from './useInfiniteScroll.js';
+export type { UseInfiniteScrollOptions, UseInfiniteScrollReturn, InfiniteScrollOptions, LegacyInfiniteScrollOptions, } from './useInfiniteScroll.js';
+export { useFillEmptyRows } from './useFillEmptyRows.js';
+export type { FillEmptyRowsRemainingMode, UseFillEmptyRowsOptions, UseFillEmptyRowsReturn, } from './useFillEmptyRows.js';
+export { useTableDragSelection } from './useTableDragSelection.js';
+export type { UseTableDragSelectionOptions } from './useTableDragSelection.js';
+export { useVirtualRows } from './useVirtualRows.js';
+export type { UseVirtualRowsOptions, UseVirtualRowsReturn, } from './useVirtualRows.js';
+export { useAwaitableOverlay } from './useAwaitableOverlay.js';
+export type { AwaitableOverlayResult } from './useAwaitableOverlay.js';
+export { useStepper } from '../components/stepper/use-stepper.js';
+export type { UseStepperOptions, StepperState, } from '../components/stepper/use-stepper.js';

package/dist/hooks/useAwaitableOverlay.cjs

@@ -0,0 +1 @@
+const e=require("./awaitableOverlayController.cjs");let t=require("react");function n(){let[n,r]=(0,t.useState)(!1),i=(0,t.useRef)(null);i.current||=e.createAwaitableOverlayController();let a=i.current;return(0,t.useEffect)(()=>()=>{a.settle({type:`cancel`})},[a]),{isOpen:n,open:(0,t.useCallback)(()=>{let e=a.open();return r(!0),e},[a]),settle:(0,t.useCallback)(e=>{a.settle(e)&&r(!1)},[a])}}exports.useAwaitableOverlay=n;

package/dist/hooks/useAwaitableOverlay.d.ts

@@ -0,0 +1,16 @@
+export type AwaitableOverlayResult<TResult = void> = {
+    type: "confirm";
+    value: TResult;
+} | {
+    type: "cancel";
+};
+/**
+ * 오버레이 응답을 Promise로 기다린다. 내용과 표시 방식은 호출부가 관리한다.
+ * 중복 open과 언마운트는 이전 요청을 cancel로 완료한다. ESC·백드롭 등 모든 닫기 경로에서
+ * settle({ type: "cancel" })을 호출해야 열린 Promise가 남지 않는다.
+ */
+export declare function useAwaitableOverlay<TResult = void>(): {
+    isOpen: boolean;
+    open: () => Promise<AwaitableOverlayResult<TResult>>;
+    settle: (result: AwaitableOverlayResult<TResult>) => void;
+};

package/dist/hooks/useAwaitableOverlay.esm.js

@@ -0,0 +1,22 @@
+import { createAwaitableOverlayController as e } from "./awaitableOverlayController.esm.js";
+import { useCallback as t, useEffect as n, useRef as r, useState as i } from "react";
+//#region src/hooks/useAwaitableOverlay.ts
+function a() {
+	let [a, o] = i(!1), s = r(null);
+	s.current ||= e();
+	let c = s.current;
+	return n(() => () => {
+		c.settle({ type: "cancel" });
+	}, [c]), {
+		isOpen: a,
+		open: t(() => {
+			let e = c.open();
+			return o(!0), e;
+		}, [c]),
+		settle: t((e) => {
+			c.settle(e) && o(!1);
+		}, [c])
+	};
+}
+//#endregion
+export { a as useAwaitableOverlay };

package/dist/hooks/useBottomSheetDrag.cjs

@@ -0,0 +1 @@
+let e=require("motion/react");var t=100,n=500;function r({onDismiss:r}){let i=(0,e.useDragControls)();return{dragControls:i,handleDragEnd:(e,i)=>{(i.offset.y>t||i.velocity.y>n)&&r()},startDrag:e=>{i.start(e)}}}exports.useBottomSheetDrag=r;

package/dist/hooks/useBottomSheetDrag.esm.js

@@ -0,0 +1,17 @@
+import { useDragControls as e } from "motion/react";
+//#region src/hooks/useBottomSheetDrag.ts
+var t = 100, n = 500;
+function r({ onDismiss: r }) {
+	let i = e();
+	return {
+		dragControls: i,
+		handleDragEnd: (e, i) => {
+			(i.offset.y > t || i.velocity.y > n) && r();
+		},
+		startDrag: (e) => {
+			i.start(e);
+		}
+	};
+}
+//#endregion
+export { r as useBottomSheetDrag };

package/dist/hooks/useClickOutside.cjs

@@ -0,0 +1 @@
+let e=require("react");function t(t,n,r=!0){(0,e.useEffect)(()=>{if(!r)return;let e=e=>{let r=e.target;!t.current||t.current.contains(r)||n(e)};return document.addEventListener(`mousedown`,e),document.addEventListener(`touchstart`,e),()=>{document.removeEventListener(`mousedown`,e),document.removeEventListener(`touchstart`,e)}},[t,n,r])}exports.useClickOutside=t;

package/dist/hooks/useClickOutside.esm.js

@@ -0,0 +1,20 @@
+import { useEffect as e } from "react";
+//#region src/hooks/useClickOutside.ts
+function t(t, n, r = !0) {
+	e(() => {
+		if (!r) return;
+		let e = (e) => {
+			let r = e.target;
+			!t.current || t.current.contains(r) || n(e);
+		};
+		return document.addEventListener("mousedown", e), document.addEventListener("touchstart", e), () => {
+			document.removeEventListener("mousedown", e), document.removeEventListener("touchstart", e);
+		};
+	}, [
+		t,
+		n,
+		r
+	]);
+}
+//#endregion
+export { t as useClickOutside };

package/dist/hooks/useFillEmptyRows.cjs

@@ -0,0 +1 @@
+let e=require("react");function t({containerHeight:e,headerHeight:t,rowHeights:n,remainingMode:r,tbodyHeight:i,emptyRowsHeight:a}){if(n.length===0)return{emptyRowCount:0,measuredRowHeight:null};let o=n.reduce((e,t)=>e+t,0),s=o/n.length;if(s<=0)return null;let c=r===`tbody-height`?Math.max(0,i-a):o,l=e-t-c;return{emptyRowCount:l>0?Math.floor(l/s):0,measuredRowHeight:s}}function n({enabled:n,containerRef:r,theadRef:i,tbodyRef:a,excludeRowsSelector:o,remainingMode:s,observeTbody:c=!1,deps:l=[]}){let[u,d]=(0,e.useState)(0),[f,p]=(0,e.useState)(null),[m,h]=(0,e.useState)(()=>[...l]);return(m.length!==l.length||l.some((e,t)=>!Object.is(e,m[t])))&&h([...l]),(0,e.useLayoutEffect)(()=>{if(!n){d(e=>e===0?e:0);return}let e=r.current,l=i.current,u=a.current;if(!e||!l||!u)return;let f=()=>{let n=Array.from(u.querySelectorAll(o)).map(e=>e.offsetHeight),r=s===`tbody-height`?Array.from(u.querySelectorAll(`tr[data-empty-row]`)).reduce((e,t)=>e+t.offsetHeight,0):0,i=t({containerHeight:e.clientHeight,headerHeight:l.offsetHeight,rowHeights:n,remainingMode:s,tbodyHeight:u.offsetHeight,emptyRowsHeight:r});i&&(p(e=>e===i.measuredRowHeight?e:i.measuredRowHeight),d(e=>e===i.emptyRowCount?e:i.emptyRowCount))};f();let m=null,h=new ResizeObserver(()=>{m===null&&(m=requestAnimationFrame(()=>{m=null,f()}))});return h.observe(e),c&&h.observe(u),()=>{h.disconnect(),m!==null&&cancelAnimationFrame(m)}},[n,r,i,a,o,s,c,m]),{emptyRowCount:u,measuredRowHeight:f}}exports.useFillEmptyRows=n;

package/dist/{src/components/table/hooks → hooks}/useFillEmptyRows.d.ts

@@ -17,7 +17,7 @@ export interface UseFillEmptyRowsOptions {
     /**
      * 잔여 공간 계산 방식.
      * - `sum-real-rows`: 측정 대상 행들의 높이 합을 뺀다 (펼침 없는 단순 테이블).
-     * - `tbody-height`: tbody 전체 높이를 뺀다 (펼침 행이 있어 tbody가 동적으로 커지는 경우).
+     * - `tbody-height`: 빈 행을 뺀 tbody 높이를 뺀다 (펼침 행이 있는 경우).
      */
     remainingMode: FillEmptyRowsRemainingMode;
     /**
@@ -42,6 +42,15 @@ export interface UseFillEmptyRowsReturn {
     /** 측정된 평균 행 높이(px). 빈 행의 height에 그대로 적용 가능. */
     measuredRowHeight: number | null;
 }
+/** 빈 행을 제외한 높이로 남은 행 수를 계산한다. */
+export declare function calculateFillEmptyRows({ containerHeight, headerHeight, rowHeights, remainingMode, tbodyHeight, emptyRowsHeight, }: {
+    containerHeight: number;
+    headerHeight: number;
+    rowHeights: number[];
+    remainingMode: FillEmptyRowsRemainingMode;
+    tbodyHeight: number;
+    emptyRowsHeight: number;
+}): UseFillEmptyRowsReturn | null;
 /**
  * 컨테이너 잔여 공간만큼 빈 행을 채우기 위한 개수/높이를 계산한다.
  *

package/dist/hooks/useFillEmptyRows.esm.js

@@ -0,0 +1,60 @@
+import { useLayoutEffect as e, useState as t } from "react";
+//#region src/hooks/useFillEmptyRows.ts
+function n({ containerHeight: e, headerHeight: t, rowHeights: n, remainingMode: r, tbodyHeight: i, emptyRowsHeight: a }) {
+	if (n.length === 0) return {
+		emptyRowCount: 0,
+		measuredRowHeight: null
+	};
+	let o = n.reduce((e, t) => e + t, 0), s = o / n.length;
+	if (s <= 0) return null;
+	let c = r === "tbody-height" ? Math.max(0, i - a) : o, l = e - t - c;
+	return {
+		emptyRowCount: l > 0 ? Math.floor(l / s) : 0,
+		measuredRowHeight: s
+	};
+}
+function r({ enabled: r, containerRef: i, theadRef: a, tbodyRef: o, excludeRowsSelector: s, remainingMode: c, observeTbody: l = !1, deps: u = [] }) {
+	let [d, f] = t(0), [p, m] = t(null), [h, g] = t(() => [...u]);
+	return (h.length !== u.length || u.some((e, t) => !Object.is(e, h[t]))) && g([...u]), e(() => {
+		if (!r) {
+			f((e) => e === 0 ? e : 0);
+			return;
+		}
+		let e = i.current, t = a.current, u = o.current;
+		if (!e || !t || !u) return;
+		let d = () => {
+			let r = Array.from(u.querySelectorAll(s)).map((e) => e.offsetHeight), i = c === "tbody-height" ? Array.from(u.querySelectorAll("tr[data-empty-row]")).reduce((e, t) => e + t.offsetHeight, 0) : 0, a = n({
+				containerHeight: e.clientHeight,
+				headerHeight: t.offsetHeight,
+				rowHeights: r,
+				remainingMode: c,
+				tbodyHeight: u.offsetHeight,
+				emptyRowsHeight: i
+			});
+			a && (m((e) => e === a.measuredRowHeight ? e : a.measuredRowHeight), f((e) => e === a.emptyRowCount ? e : a.emptyRowCount));
+		};
+		d();
+		let p = null, h = new ResizeObserver(() => {
+			p === null && (p = requestAnimationFrame(() => {
+				p = null, d();
+			}));
+		});
+		return h.observe(e), l && h.observe(u), () => {
+			h.disconnect(), p !== null && cancelAnimationFrame(p);
+		};
+	}, [
+		r,
+		i,
+		a,
+		o,
+		s,
+		c,
+		l,
+		h
+	]), {
+		emptyRowCount: d,
+		measuredRowHeight: p
+	};
+}
+//#endregion
+export { r as useFillEmptyRows };

package/dist/hooks/useFocusTrap.cjs

@@ -0,0 +1 @@
+let e=require("react");var t=[`a[href]`,`area[href]`,`button`,`input`,`select`,`textarea`,`iframe`,`summary`,`audio[controls]`,`video[controls]`,`[contenteditable]:not([contenteditable='false'])`,`[tabindex]`].join(`,`);function n(e,n=!1){let r=Array.from(e.querySelectorAll(t));n&&e.matches(t)&&r.unshift(e);let i=e=>{let t=n?e.getAttribute(`data-tabindex`):null;return t===null?e.tabIndex:t===``?0:Number(t)},a=e=>{if(!(e instanceof HTMLInputElement)||e.type!==`radio`||!e.name||e.checked)return!0;let t=(e.form??document).querySelectorAll(`input[type="radio"][name="${CSS.escape(e.name)}"]`);return!Array.from(t).some(t=>t.checked&&t.form===e.form)};return r.filter(e=>{let t=window.getComputedStyle(e);return i(e)>=0&&a(e)&&!e.matches(`:disabled`)&&!e.hasAttribute(`data-floating-ui-focus-guard`)&&!e.closest(`[hidden], [inert], [aria-hidden='true']`)&&t.visibility!==`hidden`&&t.visibility!==`collapse`&&e.getClientRects().length>0}).sort((e,t)=>{let n=i(e)>0?i(e):1/0,r=i(t)>0?i(t):1/0;return n===r?0:n-r})}var r=`[data-floating-ui-portal]`,i=`[data-focus-trap-layer]`,a=`[data-floating-ui-focus-guard]`,o=`[data-picker-panel]`,s=`[role="dialog"][aria-modal="true"]`,c=[`Shift`,`Alt`,`Control`,`Meta`];function l(e,t=()=>!0){let n=[],a=[e];for(let e of document.querySelectorAll(i))!e.closest(s)&&!e.querySelector(s)&&(n.push(e),a.push(e));for(let i of a)for(let o of i.querySelectorAll(`[aria-controls]`))if(!(i===e&&!t(o)))for(let e of(o.getAttribute(`aria-controls`)??``).split(/\s+/)){let t=document.getElementById(e)?.closest(r);t&&!n.includes(t)&&!t.closest(s)&&!t.querySelector(s)&&(n.push(t),a.push(t))}return n.sort((e,t)=>e.compareDocumentPosition(t)&Node.DOCUMENT_POSITION_FOLLOWING?-1:1)}function u(e,t,i){let a=[e,...l(e,i)];for(let o of a)for(let a of o.querySelectorAll(`[aria-controls]`))if(!(o===e&&!i(a))&&(a.getAttribute(`aria-controls`)??``).split(/\s+/).some(e=>document.getElementById(e)?.closest(r)===t))return a.tabIndex>=0?a:n(a)[0]??null;return null}function d(e){let t=e.closest(`${r}, ${i}`);return!!(e.closest(`[data-ui-action-toast]`)||t&&!e.closest(s))}function f(e,t,n){let r=n?Node.DOCUMENT_POSITION_PRECEDING:Node.DOCUMENT_POSITION_FOLLOWING,i=e=>e!==t&&!!(t.compareDocumentPosition(e)&r);if(!n)return e.find(i)??e[0];for(let t=e.length-1;t>=0;t--)if(i(e[t]))return e[t];return e[e.length-1]}function p(t,{enabled:r,canTrap:i,trapFocus:p=!0,cover:m}){let h=(0,e.useRef)(null),g=(0,e.useRef)(null),_=(0,e.useRef)(null),v=(0,e.useRef)(!1),y=(0,e.useRef)(i);y.current=i,r&&!v.current&&typeof document<`u`&&(h.current=document.activeElement instanceof HTMLElement?document.activeElement:null),v.current=r,(0,e.useEffect)(()=>{g.current=t,_.current=t?.parentElement?.closest(s)??null,!t&&!r&&(h.current=null)},[t,r]),(0,e.useEffect)(()=>{if(r)return()=>{let e=h.current,t=document.activeElement,r=g.current;if(t&&t!==document.body&&t.isConnected&&!r?.contains(t)&&!d(t))return;let i=_.current;i?.isConnected&&(!e?.isConnected||!i.contains(e))?(n(i).find(e=>!r?.contains(e))??i).focus({preventScroll:!0}):e?.isConnected&&e.focus({preventScroll:!0})}},[r]),(0,e.useEffect)(()=>{if(!(!r||!t)&&!t.contains(document.activeElement)){let e=n(t)[0];e?e.focus({preventScroll:!0}):(t.hasAttribute(`tabindex`)||(t.tabIndex=-1),t.focus({preventScroll:!0}))}},[t,r]),(0,e.useEffect)(()=>{if(!r||!t||!p)return;let e=t.parentElement?.closest(s)??null,i=()=>{if(!m||!e?.isConnected||!e.contains(m))return null;let t=m.offsetParent,n=t instanceof HTMLElement&&e.contains(t)?t:m.parentElement;return n?{parent:e,covered:n}:null},d=e=>n=>t.contains(n)||!!e&&e.parent.contains(n)&&!e.covered.contains(n),h=(e,r)=>{let i=e?.parent??t,o=e?n(i).filter(r):n(t),s=l(i,r),c=[o],u=new Set(o);for(let e of s){if(e.querySelector(a))continue;let t=n(e,!0).filter(e=>u.has(e)?!1:(u.add(e),!0));t.length&&c.push(t)}return{tabbables:o,layers:s,groups:c,ring:c.flat()}},g=null,_=!1,v=!1,b,x,S=()=>t.isConnected&&!(y.current&&!y.current()),C=e=>{v=!0;try{e.focus({preventScroll:!0})}finally{v=!1}},w=document.activeElement instanceof HTMLElement&&d(i())(document.activeElement)?document.activeElement:null,T=null,E,D=e=>!!e&&e.isConnected&&!e.matches(`:disabled`)&&e.getClientRects().length>0,O=new MutationObserver(()=>{if(!T||T.element.isConnected)return;let e=T.restore;T=null,O.disconnect(),clearTimeout(E),E=setTimeout(()=>{let r=document.activeElement;!t.isConnected||r&&r!==document.body&&r.isConnected||y.current&&!y.current()||([e,w&&d(i())(w)?w:null].find(D)??n(t)[0]??t).focus({preventScroll:!0})})}),k=e=>{let n=e.target;if(!(n instanceof HTMLElement)||n!==document.activeElement)return;let r=i(),a=d(r);if(a(n))w=n,T=null,document.hasFocus()&&(_=!1);else if(n.closest(`[data-ui-action-toast]`))T={element:n,restore:w};else{let e=r?.parent??t,i=l(e,a).find(e=>e.contains(n));if(T=i?{element:n,restore:u(e,i,a)}:null,!i&&(g||_)&&!v&&S()){let e=g?g.backward:!!(t.compareDocumentPosition(n)&Node.DOCUMENT_POSITION_FOLLOWING);_=!1;let{ring:i}=h(r,a);C(f(i,n,e)??w??t);return}}T?O.observe(document.body,{childList:!0,subtree:!0}):O.disconnect()};document.addEventListener(`focusin`,k);let A=e=>{if(!g||e.relatedTarget!==null||!(e.target instanceof Node)||!e.target.isConnected)return;let n=g.backward;_=!0,clearTimeout(x),x=setTimeout(()=>{let e=document.activeElement;if(!_||e&&e!==document.body||!S())return;let r=i(),{ring:a}=h(r,d(r));C((n?a[a.length-1]:a[0])??t)})};document.addEventListener(`focusout`,A);let j=e=>{c.includes(e.key)||(_=!1,g=e.key===`Tab`&&!e.ctrlKey&&!e.metaKey?{backward:e.shiftKey}:null,clearTimeout(b),g&&(b=setTimeout(()=>{g=null})))},M=()=>{g=null,_=!1};document.addEventListener(`keydown`,j,!0),document.addEventListener(`pointerdown`,M,!0);let N=e=>{if(e.key!==`Tab`||e.defaultPrevented||e.ctrlKey||e.metaKey||y.current&&!y.current())return;let r=document.activeElement,s=i(),c=d(s),{tabbables:l,layers:p,groups:m,ring:g}=h(s,c),_=p.find(e=>r&&e.contains(r)),v=g[0],b=g[g.length-1];if(_?.querySelector(a)){let i=s?.parent??t,l=n(_,!0),d=(r instanceof Element?r.closest(o):null)?.nextElementSibling;!e.shiftKey&&v&&d instanceof HTMLElement&&d.matches(a)&&r===l[l.length-1]&&u(i,_,c)===b&&(e.preventDefault(),d.focus({preventScroll:!0}),v.focus({preventScroll:!0}));return}if(v&&b&&(!e.shiftKey&&r===b||e.shiftKey&&r===v)){let n=s?.parent??t,r=p.find(e=>e.querySelector(a)&&u(n,e,c)===b),i=r?.id?n.querySelector(`[aria-owns="${CSS.escape(r.id)}"]`):null,o=e.shiftKey?i?.nextElementSibling:i?.previousElementSibling;if(o instanceof HTMLElement&&o.matches(a)){e.preventDefault(),o.focus({preventScroll:!0});return}}if(s&&r instanceof HTMLElement){let t=e.shiftKey?-1:1,i=n(s.parent),a=i[i.indexOf(r)+t],o=l.indexOf(r),u=o>=0?l[o+t]:void 0;if(u&&a&&!c(a)){e.preventDefault(),u.focus({preventScroll:!0});return}}if(!v||!b)e.preventDefault(),t.focus({preventScroll:!0});else if(!(r&&c(r))&&!_)e.preventDefault(),(e.shiftKey?b:v).focus({preventScroll:!0});else if(r instanceof HTMLElement&&!r.shadowRoot&&!g.includes(r))e.preventDefault(),f(g,r,e.shiftKey)?.focus({preventScroll:!0});else{let t=m.findIndex(e=>e.some(e=>e===r)),n=m[t];if(e.shiftKey&&r===n?.[0]){e.preventDefault();let n=m[(t<=0?m.length:t)-1];(n[n.length-1]??b).focus({preventScroll:!0})}else !e.shiftKey&&r===n?.[n.length-1]&&(e.preventDefault(),(m[(t+1)%m.length][0]??v).focus({preventScroll:!0}))}};return document.addEventListener(`keydown`,N),()=>{document.removeEventListener(`keydown`,N),document.removeEventListener(`focusin`,k),document.removeEventListener(`focusout`,A),document.removeEventListener(`keydown`,j,!0),document.removeEventListener(`pointerdown`,M,!0),O.disconnect(),clearTimeout(E),clearTimeout(x),clearTimeout(b)}},[t,r,p,m])}exports.useFocusTrap=p;

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,47 @@
+export interface UseFocusTrapOptions {
+    enabled: boolean;
+    canTrap?: () => boolean;
+    trapFocus?: boolean;
+    cover?: HTMLElement | null;
+}
+/**
+ * 열린 컨테이너 안에서 Tab 포커스를 순환하고 닫힐 때 이전 포커스를 복원한다.
+ * Portal처럼 노드가 늦게 연결되면 `container`에 연결된 노드를 전달한다.
+ * 열리면 첫 tabbable에 포커스한다. 이미 내부에 포커스가 있으면 유지하고, 대상이 없으면 컨테이너 자체에 포커스한다.
+ * `canTrap`은 중첩 오버레이에서 현재 트랩이 Tab을 처리할 수 있는지 판정한다.
+ * 닫힐 때 포커스가 컨테이너·부유 레이어 안이거나 body이면 열기 직전 요소로 복원하고,
+ * 소비자가 배경의 다른 요소로 옮겨 둔 포커스는 그대로 둔다. 컨테이너가 부모 dialog 안에 있고
+ * 열기 직전 요소가 그 부모 밖이면(부모와 함께 열린 서브뷰 등) 부모의 첫 tabbable로 복원한다.
+ * `trapFocus`가 false여도 초기 포커스와 이 복원 규칙은 유지한다.
+ * `cover`는 부모 dialog 시트의 일부만 덮는 서브뷰용이다. 덮는 요소를 전달하면 Tab 고리는
+ * 부모 시트에서 덮인 영역을 뺀 나머지(헤더·footer 등)와 컨테이너를 DOM 순서로 잇는다.
+ * 덮인 영역은 `cover`의 offsetParent(없으면 부모 요소)로 판정한다 — 절대 위치로 덮는 범위가
+ * 곧 그 기준 요소이기 때문이다.
+ * 부유 레이어는 `aria-controls`로 연결된 Floating UI 포털 또는 `data-focus-trap-layer`가
+ * 붙은 포털만 인정한다. 연결을 알 수 없는 포털의 Tab은 컨테이너로 돌아오므로 해당 포털에
+ * 표식을 붙이거나 `trapFocus: false`를 사용한다. 표식은 문서 전체에서 찾으므로 현재 트랩에
+ * 편입할 포털에만 붙인다. `role="dialog"` + `aria-modal="true"`인 포털(서드파티 다이얼로그 등)은
+ * 자기 트랩을 가진 별도 모달로 보고 표식이 있어도 편입하지 않는다 — 그 위에서 조작해야 하면
+ * `trapFocus: false`를 사용한다.
+ * 가드 없는 부유 레이어(Popover·표식 포털)는 트리거 바로 뒤가 아닌 컨테이너의
+ * 모든 tabbable 뒤에 붙는다. 포털 DOM 위치와 무관하게 순환을 일정하게 하기 위해 트리거에서
+ * Tab을 누르면 다음 필드로 가고, 패널은 한 바퀴의 마지막에 지난다. 열자마자 패널을 조작하려면
+ * 패널 안으로 바로 포커스를 옮기는 컴포넌트나 Select·DatePicker처럼 floating-ui 포커스 관리가 있는 패널을 쓴다.
+ * 액션 토스트가 top이면 트랩은 양보한다. 그동안에는 Tab이 컨테이너 밖으로 나갈 수 있다
+ * (`backdrop: false` 알림성 토스트 포함).
+ * Tab 이동으로 범위·편입 레이어·토스트 밖(배경, 서브뷰에 덮인 본문 등)에 떨어진 포커스는
+ * 진행 방향의 다음 고리 요소로 되돌린다 — 라디오 그룹·스크롤 컨테이너처럼 브라우저의 Tab 순서를
+ * 미리 알 수 없는 경로도 고리를 벗어나지 않게 하기 위해서다. Tab 키가 일으킨 이동(브라우저 UI로
+ * 나갔다 키보드로 돌아오는 경우 포함)에만 반응하고, 클릭·터치, 다른 키, 프로그램 `focus()`로 옮긴
+ * 포커스(Enter로 연 포털, 닫는 핸들러의 `focus()` 등)는 건드리지 않는다 — 연결·표식 없는 포털도
+ * 클릭하면 조작할 수 있다. 그 포털을 Tab으로도 오가야 하면 표식을 붙인다.
+ * 포커스가 있던 레이어나 토스트가 사라져 포커스가 body로 유실되면 연결 트리거, 컨테이너에서
+ * 마지막으로 포커스됐던 요소, 컨테이너 첫 tabbable 순으로 되돌린다. 포커스 이동 도중에는
+ * 잠시 body가 활성 요소가 되므로, 복구는 다음 태스크에서도 body일 때만 한다.
+ *
+ * @example
+ * const [sheet, setSheet] = useState<HTMLDivElement | null>(null);
+ * useFocusTrap(sheet, { enabled: open });
+ * return <div ref={setSheet} tabIndex={-1}>...</div>;
+ */
+export declare function useFocusTrap(container: HTMLElement | null, { enabled, canTrap, trapFocus, cover }: UseFocusTrapOptions): void;

package/dist/hooks/useFocusTrap.esm.js

@@ -0,0 +1,210 @@
+import { useEffect as e, useRef as t } from "react";
+//#region src/hooks/useFocusTrap.ts
+var n = [
+	"a[href]",
+	"area[href]",
+	"button",
+	"input",
+	"select",
+	"textarea",
+	"iframe",
+	"summary",
+	"audio[controls]",
+	"video[controls]",
+	"[contenteditable]:not([contenteditable='false'])",
+	"[tabindex]"
+].join(",");
+function r(e, t = !1) {
+	let r = Array.from(e.querySelectorAll(n));
+	t && e.matches(n) && r.unshift(e);
+	let i = (e) => {
+		let n = t ? e.getAttribute("data-tabindex") : null;
+		return n === null ? e.tabIndex : n === "" ? 0 : Number(n);
+	}, a = (e) => {
+		if (!(e instanceof HTMLInputElement) || e.type !== "radio" || !e.name || e.checked) return !0;
+		let t = (e.form ?? document).querySelectorAll(`input[type="radio"][name="${CSS.escape(e.name)}"]`);
+		return !Array.from(t).some((t) => t.checked && t.form === e.form);
+	};
+	return r.filter((e) => {
+		let t = window.getComputedStyle(e);
+		return i(e) >= 0 && a(e) && !e.matches(":disabled") && !e.hasAttribute("data-floating-ui-focus-guard") && !e.closest("[hidden], [inert], [aria-hidden='true']") && t.visibility !== "hidden" && t.visibility !== "collapse" && e.getClientRects().length > 0;
+	}).sort((e, t) => {
+		let n = i(e) > 0 ? i(e) : Infinity, r = i(t) > 0 ? i(t) : Infinity;
+		return n === r ? 0 : n - r;
+	});
+}
+var i = "[data-floating-ui-portal]", a = "[data-focus-trap-layer]", o = "[data-floating-ui-focus-guard]", s = "[data-picker-panel]", c = "[role=\"dialog\"][aria-modal=\"true\"]", l = [
+	"Shift",
+	"Alt",
+	"Control",
+	"Meta"
+];
+function u(e, t = () => !0) {
+	let n = [], r = [e];
+	for (let e of document.querySelectorAll(a)) !e.closest(c) && !e.querySelector(c) && (n.push(e), r.push(e));
+	for (let a of r) for (let o of a.querySelectorAll("[aria-controls]")) if (!(a === e && !t(o))) for (let e of (o.getAttribute("aria-controls") ?? "").split(/\s+/)) {
+		let t = document.getElementById(e)?.closest(i);
+		t && !n.includes(t) && !t.closest(c) && !t.querySelector(c) && (n.push(t), r.push(t));
+	}
+	return n.sort((e, t) => e.compareDocumentPosition(t) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
+}
+function d(e, t, n) {
+	let a = [e, ...u(e, n)];
+	for (let o of a) for (let a of o.querySelectorAll("[aria-controls]")) if (!(o === e && !n(a)) && (a.getAttribute("aria-controls") ?? "").split(/\s+/).some((e) => document.getElementById(e)?.closest(i) === t)) return a.tabIndex >= 0 ? a : r(a)[0] ?? null;
+	return null;
+}
+function f(e) {
+	let t = e.closest(`${i}, ${a}`);
+	return !!(e.closest("[data-ui-action-toast]") || t && !e.closest(c));
+}
+function p(e, t, n) {
+	let r = n ? Node.DOCUMENT_POSITION_PRECEDING : Node.DOCUMENT_POSITION_FOLLOWING, i = (e) => e !== t && !!(t.compareDocumentPosition(e) & r);
+	if (!n) return e.find(i) ?? e[0];
+	for (let t = e.length - 1; t >= 0; t--) if (i(e[t])) return e[t];
+	return e[e.length - 1];
+}
+function m(n, { enabled: i, canTrap: a, trapFocus: m = !0, cover: h }) {
+	let g = t(null), _ = t(null), v = t(null), y = t(!1), b = t(a);
+	b.current = a, i && !y.current && typeof document < "u" && (g.current = document.activeElement instanceof HTMLElement ? document.activeElement : null), y.current = i, e(() => {
+		_.current = n, v.current = n?.parentElement?.closest(c) ?? null, !n && !i && (g.current = null);
+	}, [n, i]), e(() => {
+		if (i) return () => {
+			let e = g.current, t = document.activeElement, n = _.current;
+			if (t && t !== document.body && t.isConnected && !n?.contains(t) && !f(t)) return;
+			let i = v.current;
+			i?.isConnected && (!e?.isConnected || !i.contains(e)) ? (r(i).find((e) => !n?.contains(e)) ?? i).focus({ preventScroll: !0 }) : e?.isConnected && e.focus({ preventScroll: !0 });
+		};
+	}, [i]), e(() => {
+		if (!(!i || !n) && !n.contains(document.activeElement)) {
+			let e = r(n)[0];
+			e ? e.focus({ preventScroll: !0 }) : (n.hasAttribute("tabindex") || (n.tabIndex = -1), n.focus({ preventScroll: !0 }));
+		}
+	}, [n, i]), e(() => {
+		if (!i || !n || !m) return;
+		let e = n.parentElement?.closest(c) ?? null, t = () => {
+			if (!h || !e?.isConnected || !e.contains(h)) return null;
+			let t = h.offsetParent, n = t instanceof HTMLElement && e.contains(t) ? t : h.parentElement;
+			return n ? {
+				parent: e,
+				covered: n
+			} : null;
+		}, a = (e) => (t) => n.contains(t) || !!e && e.parent.contains(t) && !e.covered.contains(t), f = (e, t) => {
+			let i = e?.parent ?? n, a = e ? r(i).filter(t) : r(n), s = u(i, t), c = [a], l = new Set(a);
+			for (let e of s) {
+				if (e.querySelector(o)) continue;
+				let t = r(e, !0).filter((e) => l.has(e) ? !1 : (l.add(e), !0));
+				t.length && c.push(t);
+			}
+			return {
+				tabbables: a,
+				layers: s,
+				groups: c,
+				ring: c.flat()
+			};
+		}, g = null, _ = !1, v = !1, y, x, S = () => n.isConnected && !(b.current && !b.current()), C = (e) => {
+			v = !0;
+			try {
+				e.focus({ preventScroll: !0 });
+			} finally {
+				v = !1;
+			}
+		}, w = document.activeElement instanceof HTMLElement && a(t())(document.activeElement) ? document.activeElement : null, T = null, E, D = (e) => !!e && e.isConnected && !e.matches(":disabled") && e.getClientRects().length > 0, O = new MutationObserver(() => {
+			if (!T || T.element.isConnected) return;
+			let e = T.restore;
+			T = null, O.disconnect(), clearTimeout(E), E = setTimeout(() => {
+				let i = document.activeElement;
+				!n.isConnected || i && i !== document.body && i.isConnected || b.current && !b.current() || ([e, w && a(t())(w) ? w : null].find(D) ?? r(n)[0] ?? n).focus({ preventScroll: !0 });
+			});
+		}), k = (e) => {
+			let r = e.target;
+			if (!(r instanceof HTMLElement) || r !== document.activeElement) return;
+			let i = t(), o = a(i);
+			if (o(r)) w = r, T = null, document.hasFocus() && (_ = !1);
+			else if (r.closest("[data-ui-action-toast]")) T = {
+				element: r,
+				restore: w
+			};
+			else {
+				let e = i?.parent ?? n, t = u(e, o).find((e) => e.contains(r));
+				if (T = t ? {
+					element: r,
+					restore: d(e, t, o)
+				} : null, !t && (g || _) && !v && S()) {
+					let e = g ? g.backward : !!(n.compareDocumentPosition(r) & Node.DOCUMENT_POSITION_FOLLOWING);
+					_ = !1;
+					let { ring: t } = f(i, o);
+					C(p(t, r, e) ?? w ?? n);
+					return;
+				}
+			}
+			T ? O.observe(document.body, {
+				childList: !0,
+				subtree: !0
+			}) : O.disconnect();
+		};
+		document.addEventListener("focusin", k);
+		let A = (e) => {
+			if (!g || e.relatedTarget !== null || !(e.target instanceof Node) || !e.target.isConnected) return;
+			let r = g.backward;
+			_ = !0, clearTimeout(x), x = setTimeout(() => {
+				let e = document.activeElement;
+				if (!_ || e && e !== document.body || !S()) return;
+				let i = t(), { ring: o } = f(i, a(i));
+				C((r ? o[o.length - 1] : o[0]) ?? n);
+			});
+		};
+		document.addEventListener("focusout", A);
+		let j = (e) => {
+			l.includes(e.key) || (_ = !1, g = e.key === "Tab" && !e.ctrlKey && !e.metaKey ? { backward: e.shiftKey } : null, clearTimeout(y), g && (y = setTimeout(() => {
+				g = null;
+			})));
+		}, M = () => {
+			g = null, _ = !1;
+		};
+		document.addEventListener("keydown", j, !0), document.addEventListener("pointerdown", M, !0);
+		let N = (e) => {
+			if (e.key !== "Tab" || e.defaultPrevented || e.ctrlKey || e.metaKey || b.current && !b.current()) return;
+			let i = document.activeElement, c = t(), l = a(c), { tabbables: u, layers: m, groups: h, ring: g } = f(c, l), _ = m.find((e) => i && e.contains(i)), v = g[0], y = g[g.length - 1];
+			if (_?.querySelector(o)) {
+				let t = c?.parent ?? n, a = r(_, !0), u = (i instanceof Element ? i.closest(s) : null)?.nextElementSibling;
+				!e.shiftKey && v && u instanceof HTMLElement && u.matches(o) && i === a[a.length - 1] && d(t, _, l) === y && (e.preventDefault(), u.focus({ preventScroll: !0 }), v.focus({ preventScroll: !0 }));
+				return;
+			}
+			if (v && y && (!e.shiftKey && i === y || e.shiftKey && i === v)) {
+				let t = c?.parent ?? n, r = m.find((e) => e.querySelector(o) && d(t, e, l) === y), i = r?.id ? t.querySelector(`[aria-owns="${CSS.escape(r.id)}"]`) : null, a = e.shiftKey ? i?.nextElementSibling : i?.previousElementSibling;
+				if (a instanceof HTMLElement && a.matches(o)) {
+					e.preventDefault(), a.focus({ preventScroll: !0 });
+					return;
+				}
+			}
+			if (c && i instanceof HTMLElement) {
+				let t = e.shiftKey ? -1 : 1, n = r(c.parent), a = n[n.indexOf(i) + t], o = u.indexOf(i), s = o >= 0 ? u[o + t] : void 0;
+				if (s && a && !l(a)) {
+					e.preventDefault(), s.focus({ preventScroll: !0 });
+					return;
+				}
+			}
+			if (!v || !y) e.preventDefault(), n.focus({ preventScroll: !0 });
+			else if (!(i && l(i)) && !_) e.preventDefault(), (e.shiftKey ? y : v).focus({ preventScroll: !0 });
+			else if (i instanceof HTMLElement && !i.shadowRoot && !g.includes(i)) e.preventDefault(), p(g, i, e.shiftKey)?.focus({ preventScroll: !0 });
+			else {
+				let t = h.findIndex((e) => e.some((e) => e === i)), n = h[t];
+				if (e.shiftKey && i === n?.[0]) {
+					e.preventDefault();
+					let n = h[(t <= 0 ? h.length : t) - 1];
+					(n[n.length - 1] ?? y).focus({ preventScroll: !0 });
+				} else !e.shiftKey && i === n?.[n.length - 1] && (e.preventDefault(), (h[(t + 1) % h.length][0] ?? v).focus({ preventScroll: !0 }));
+			}
+		};
+		return document.addEventListener("keydown", N), () => {
+			document.removeEventListener("keydown", N), document.removeEventListener("focusin", k), document.removeEventListener("focusout", A), document.removeEventListener("keydown", j, !0), document.removeEventListener("pointerdown", M, !0), O.disconnect(), clearTimeout(E), clearTimeout(x), clearTimeout(y);
+		};
+	}, [
+		n,
+		i,
+		m,
+		h
+	]);
+}
+//#endregion
+export { m as useFocusTrap };