@thewrong/ui 0.2.0 → 0.3.0

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/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 };

package/dist/hooks/useInfiniteScroll.cjs

@@ -0,0 +1 @@
+let e=require("react");function t(t){let n=`onLoadMore`in t,r=n?t.onLoadMore:t.fetchNextPage,i=n?t.hasMore:t.hasNextPage,a=n?t.isFetching:t.isFetchingNextPage,o=n?t.scrollElementRef:void 0,s=n?void 0:t.scrollElement,c=t.rootMarginPx??(n?120:100),l=t.enabled??!0,u=(0,e.useRef)(null),d=(0,e.useCallback)(e=>{e[0]?.isIntersecting&&i&&!a&&l&&r()},[r,i,a,l]);return(0,e.useEffect)(()=>{let e=u.current;if(!l||!i||!e)return;let t=new IntersectionObserver(d,{root:o?.current??s??null,rootMargin:`${c}px`,threshold:0});return t.observe(e),()=>t.disconnect()},[d,o,s,c,l,i]),{sentinelRef:u}}exports.useInfiniteScroll=t;

package/dist/hooks/useInfiniteScroll.d.ts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+interface CommonOptions {
+    /** 감지 활성 여부. 기본 true. */
+    enabled?: boolean;
+    /** 경계보다 일찍 감지할 거리(px). 새 API의 기본값은 120, 기존 API는 100. */
+    rootMarginPx?: number;
+}
+/** 콜백과 스크롤 컨테이너 ref를 받는 범용 옵션. */
+export interface InfiniteScrollOptions extends CommonOptions {
+    onLoadMore: () => void;
+    hasMore: boolean;
+    isFetching: boolean;
+    /** 없거나 current가 null이면 뷰포트에서 감지한다. */
+    scrollElementRef?: RefObject<HTMLElement | null>;
+}
+/** 기존 테이블 사용자와 호환되는 옵션. */
+export interface LegacyInfiniteScrollOptions extends CommonOptions {
+    fetchNextPage: () => void;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+    scrollElement?: HTMLElement | null;
+    /** 기존 API에서 실제로 사용되지 않았던 값. 선제 감지는 rootMarginPx를 쓴다. */
+    threshold?: number;
+}
+export type UseInfiniteScrollOptions = InfiniteScrollOptions | LegacyInfiniteScrollOptions;
+export interface UseInfiniteScrollReturn {
+    /** 스크롤 영역 끝에 렌더할 감지 요소의 ref. */
+    sentinelRef: RefObject<HTMLDivElement | null>;
+}
+/**
+ * IntersectionObserver로 스크롤 끝의 sentinel을 감지해 다음 데이터를 요청한다.
+ * sentinel을 실제 스크롤 영역 끝에 렌더해야 감지되며, ref가 없으면 감시가 시작되지 않는다.
+ * 컨테이너를 쓰면 scrollElementRef를 지정하고, 뷰포트 스크롤이면 생략한다.
+ */
+export declare function useInfiniteScroll(options: UseInfiniteScrollOptions): UseInfiniteScrollReturn;
+export {};

package/dist/hooks/useInfiniteScroll.esm.js

@@ -0,0 +1,31 @@
+import { useCallback as e, useEffect as t, useRef as n } from "react";
+//#region src/hooks/useInfiniteScroll.ts
+function r(r) {
+	let i = "onLoadMore" in r, a = i ? r.onLoadMore : r.fetchNextPage, o = i ? r.hasMore : r.hasNextPage, s = i ? r.isFetching : r.isFetchingNextPage, c = i ? r.scrollElementRef : void 0, l = i ? void 0 : r.scrollElement, u = r.rootMarginPx ?? (i ? 120 : 100), d = r.enabled ?? !0, f = n(null), p = e((e) => {
+		e[0]?.isIntersecting && o && !s && d && a();
+	}, [
+		a,
+		o,
+		s,
+		d
+	]);
+	return t(() => {
+		let e = f.current;
+		if (!d || !o || !e) return;
+		let t = new IntersectionObserver(p, {
+			root: c?.current ?? l ?? null,
+			rootMargin: `${u}px`,
+			threshold: 0
+		});
+		return t.observe(e), () => t.disconnect();
+	}, [
+		p,
+		c,
+		l,
+		u,
+		d,
+		o
+	]), { sentinelRef: f };
+}
+//#endregion
+export { r as useInfiniteScroll };

package/dist/hooks/useTableDragSelection.cjs

@@ -0,0 +1 @@
+let e=require("react");function t({rows:t,getRowId:n,isSelected:r,setSelected:i,enabled:a=!0,scrollContainerRef:o,edgeSize:s=60,maxSpeed:c=14}){let l=(0,e.useRef)(!1),u=(0,e.useRef)(!0),d=(0,e.useRef)(null),f=(0,e.useRef)(null),p=(0,e.useRef)(null),m=(0,e.useRef)(t);m.current=t;let h=(0,e.useRef)(n);h.current=n;let g=(0,e.useRef)(r);g.current=r;let _=(0,e.useRef)(i);_.current=i;let v=(0,e.useMemo)(()=>{let e=new Map;for(let n=0;n<t.length;n++){let r=t[n];r!==void 0&&e.set(h.current(r),n)}return e},[t]),y=(0,e.useRef)(v);y.current=v;let b=(0,e.useCallback)(()=>{p.current!=null&&(cancelAnimationFrame(p.current),p.current=null),f.current=null},[]),x=(0,e.useCallback)(()=>{if(p.current=null,!l.current)return;let e=o?.current,t=f.current;if(!e||t==null)return;let n=e.getBoundingClientRect(),r=0;if(t<n.top+s){let e=(n.top+s-t)/s;r=-Math.ceil(c*Math.min(1,Math.max(0,e)))}else if(t>n.bottom-s){let e=(t-(n.bottom-s))/s;r=Math.ceil(c*Math.min(1,Math.max(0,e)))}r!==0&&(e.scrollTop+=r),p.current=requestAnimationFrame(x)},[s,c,o]);(0,e.useEffect)(()=>{if(!a)return;let e=()=>{l.current=!1,d.current=null,b()},t=e=>{l.current&&(f.current=e.clientY,p.current??=requestAnimationFrame(x))};return window.addEventListener(`mouseup`,e),window.addEventListener(`mousemove`,t),()=>{window.removeEventListener(`mouseup`,e),window.removeEventListener(`mousemove`,t),l.current=!1,d.current=null,b()}},[a,b,x]);let S=e=>e==null?-1:y.current.get(e)??-1;return{onRowMouseDown:(0,e.useCallback)(e=>{if(!a)return;let t=m.current[e];t!==void 0&&(l.current=!0,d.current=h.current(t),u.current=!g.current(t),_.current(t,u.current))},[a]),onRowMouseEnter:(0,e.useCallback)(e=>{if(!a||!l.current)return;let t=m.current,n=t[e];if(n===void 0)return;let r=h.current(n);if(r===d.current)return;let i=S(d.current),o=i===-1?e:i,s=Math.min(o,e),c=Math.max(o,e);for(let e=s;e<=c;e++){let n=t[e];n!==void 0&&g.current(n)!==u.current&&_.current(n,u.current)}d.current=r},[a])}}exports.useTableDragSelection=t;

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

@@ -1,4 +1,4 @@
-interface Options<T> {
+export interface UseTableDragSelectionOptions<T> {
     /** 현재 표에 그려진 row들 (순서대로). */
     rows: T[];
     /** row의 안정 식별자. */
@@ -17,7 +17,7 @@ interface Options<T> {
     maxSpeed?: number;
 }
 /**
- * 표의 다중 행을 드래그로 선택/해제한다 — 비스킷링크의 드래그 체크 패턴을 일반화.
+ * 표의 다중 행을 드래그로 선택하거나 해제한다.
  *
  * 동작:
  * - mouseDown(row 인덱스 i): 드래그 시작. row의 현재 선택 상태를 뒤집은 값을 모드로 잡고, 그 row를 그 모드로 적용
@@ -28,8 +28,7 @@ interface Options<T> {
  * 드래그 도중 데이터가 refetch 등으로 흔들려도 마지막 식별자(lastIdRef)를 기준으로 인덱스를 다시 찾아
  * 어긋남 위험을 줄인다.
  */
-export declare function useTableDragSelection<T>({ rows, getRowId, isSelected, setSelected, enabled, scrollContainerRef, edgeSize, maxSpeed, }: Options<T>): {
+export declare function useTableDragSelection<T>({ rows, getRowId, isSelected, setSelected, enabled, scrollContainerRef, edgeSize, maxSpeed, }: UseTableDragSelectionOptions<T>): {
     onRowMouseDown: (index: number) => void;
     onRowMouseEnter: (index: number) => void;
 };
-export {};

package/dist/{components/table/hooks → hooks}/useTableDragSelection.esm.js

@@ -1,5 +1,5 @@
 import { useCallback as e, useEffect as t, useMemo as n, useRef as r } from "react";
-//#region src/components/table/hooks/useTableDragSelection.ts
+//#region src/hooks/useTableDragSelection.ts
 function i({ rows: i, getRowId: a, isSelected: o, setSelected: s, enabled: c = !0, scrollContainerRef: l, edgeSize: u = 60, maxSpeed: d = 14 }) {
 	let f = r(!1), p = r(!0), m = r(null), h = r(null), g = r(null), _ = r(i);
 	_.current = i;
@@ -11,7 +11,10 @@ function i({ rows: i, getRowId: a, isSelected: o, setSelected: s, enabled: c = !
 	b.current = s;
 	let x = n(() => {
 		let e = /* @__PURE__ */ new Map();
-		for (let t = 0; t < i.length; t++) e.set(a(i[t]), t);
+		for (let t = 0; t < i.length; t++) {
+			let n = i[t];
+			n !== void 0 && e.set(v.current(n), t);
+		}
 		return e;
 	}, [i]), S = r(x);
 	S.current = x;
@@ -43,7 +46,7 @@ function i({ rows: i, getRowId: a, isSelected: o, setSelected: s, enabled: c = !
 			f.current && (h.current = e.clientY, g.current ??= requestAnimationFrame(w));
 		};
 		return window.addEventListener("mouseup", e), window.addEventListener("mousemove", t), () => {
-			window.removeEventListener("mouseup", e), window.removeEventListener("mousemove", t), C();
+			window.removeEventListener("mouseup", e), window.removeEventListener("mousemove", t), f.current = !1, m.current = null, C();
 		};
 	}, [
 		c,
@@ -55,18 +58,18 @@ function i({ rows: i, getRowId: a, isSelected: o, setSelected: s, enabled: c = !
 		onRowMouseDown: e((e) => {
 			if (!c) return;
 			let t = _.current[e];
-			t && (f.current = !0, m.current = v.current(t), p.current = !y.current(t), b.current(t, p.current));
+			t !== void 0 && (f.current = !0, m.current = v.current(t), p.current = !y.current(t), b.current(t, p.current));
 		}, [c]),
 		onRowMouseEnter: e((e) => {
 			if (!c || !f.current) return;
 			let t = _.current, n = t[e];
-			if (!n) return;
+			if (n === void 0) return;
 			let r = v.current(n);
 			if (r === m.current) return;
 			let i = T(m.current), a = i === -1 ? e : i, o = Math.min(a, e), s = Math.max(a, e);
 			for (let e = o; e <= s; e++) {
 				let n = t[e];
-				n && y.current(n) !== p.current && b.current(n, p.current);
+				n !== void 0 && y.current(n) !== p.current && b.current(n, p.current);
 			}
 			m.current = r;
 		}, [c])

package/dist/hooks/useVirtualRows.cjs

@@ -0,0 +1 @@
+let e=require("@tanstack/react-virtual");function t({scrollElementRef:t,scrollElement:n,count:r,estimateSize:i=48,overscan:a=5}){let o=(0,e.useVirtualizer)({count:r,getScrollElement:()=>n??t.current,estimateSize:()=>i,overscan:a,enabled:r>0}),s=o.getVirtualItems(),c=o.getTotalSize();return{virtualizer:o,virtualItems:s,totalSize:c,topSpacerHeight:s.length>0?s[0]?.start??0:0,bottomSpacerHeight:s.length>0?c-(s[s.length-1]?.end??0):0}}exports.useVirtualRows=t;

package/dist/hooks/useVirtualRows.d.ts

@@ -0,0 +1,56 @@
+import { Virtualizer, VirtualItem } from '@tanstack/react-virtual';
+import { RefObject } from 'react';
+export interface UseVirtualRowsOptions {
+    /**
+     * 스크롤 컨테이너 ref.
+     * null이면 스크롤 영역을 아직 측정할 수 없다.
+     */
+    scrollElementRef: RefObject<HTMLElement | null>;
+    /** 기존 테이블의 직접 전달 요소. 없으면 scrollElementRef를 사용한다. */
+    scrollElement?: HTMLElement | null;
+    /**
+     * 가상화할 행 수.
+     */
+    count: number;
+    /**
+     * 예상 행 높이(px). 실제 행 높이와 다르면 virtualizer가 동적 보정한다.
+     * @default 48
+     */
+    estimateSize?: number;
+    /**
+     * 뷰포트 밖 미리 렌더할 행 수(위아래 각각).
+     * 스크롤이 빠를수록 높은 값이 유리하나, 과하면 DOM 노드 수 증가.
+     * @default 5
+     */
+    overscan?: number;
+}
+export interface UseVirtualRowsReturn {
+    /**
+     * @tanstack/react-virtual 인스턴스.
+     * measureElement(ref 콜백), scrollToIndex 등 고급 API 접근용.
+     */
+    virtualizer: Virtualizer<HTMLElement, Element>;
+    /**
+     * 현재 렌더해야 할 가상 행 목록.
+     * 각 아이템의 `index`로 원본 데이터 배열에 접근한다.
+     */
+    virtualItems: VirtualItem[];
+    /**
+     * 전체 스크롤 영역 높이(px).
+     * 스크롤 컨테이너 자식의 `height` 또는 `minHeight`에 적용한다.
+     */
+    totalSize: number;
+    /**
+     * 첫 번째 가상 행 위의 빈 공간 높이(px).
+     * `<tr style={{ height: topSpacerHeight }} />` 또는 paddingTop에 사용.
+     */
+    topSpacerHeight: number;
+    /**
+     * 마지막 가상 행 아래의 빈 공간 높이(px).
+     * `<tr style={{ height: bottomSpacerHeight }} />` 또는 paddingBottom에 사용.
+     */
+    bottomSpacerHeight: number;
+}
+/** 행 수와 스크롤 요소로 가상 항목과 스페이서를 계산한다.
+ * 스크롤 영역에 고정 높이와 overflow가 필요하다. 고급 측정은 반환된 virtualizer를 사용한다. */
+export declare function useVirtualRows({ scrollElementRef, scrollElement, count, estimateSize, overscan, }: UseVirtualRowsOptions): UseVirtualRowsReturn;