@thewrong/ui 0.1.0

package/dist/src/components/table/components/ColumnSettingsTable.d.ts

@@ -0,0 +1,25 @@
+import { TableColumn, TableColumnGroupMeta } from '../types';
+/** ColumnSettingsTable의 max-height. ColumnPresetSelector의 dropdown 위치 계산에 공유돼요. */
+export declare const COLUMN_SETTINGS_DROPDOWN_MAX_HEIGHT = 500;
+interface ColumnSettingsTableProps<T> {
+    columns: TableColumn<T>[];
+    columnGroups?: TableColumnGroupMeta[];
+    columnOrder: string[];
+    hiddenColumns: string[];
+    /** 컬럼 키 → 픽셀 너비. 프리셋에 저장된 값. */
+    columnWidths: Record<string, number>;
+    num: string;
+    onOrderChange: (newOrder: string[]) => void;
+    onHiddenChange: (key: string, hidden: boolean) => void;
+    /** 단일 컬럼 너비 갱신. 0이면 기본값 복원. */
+    onSetColumnWidth?: (key: string, width: number) => void;
+    onSave: () => void;
+    onReset: () => void;
+}
+/**
+ * 컬럼 설정 드롭다운 내부의 DnD 테이블
+ *
+ * dnd-kit 기반의 컬럼 순서 변경 + 숨김 토글 UI예요.
+ */
+export declare function ColumnSettingsTable<T>({ columns, columnGroups, columnOrder, hiddenColumns, columnWidths, num, onOrderChange, onHiddenChange, onSetColumnWidth, onSave, onReset, }: ColumnSettingsTableProps<T>): import("react").JSX.Element;
+export {};

package/dist/src/components/table/components/KeyboardNavButton.d.ts

@@ -0,0 +1,12 @@
+import { KeyboardEvent } from 'react';
+interface KeyboardNavButtonProps {
+    onKeyDown: (e: KeyboardEvent<HTMLButtonElement>) => void;
+}
+/**
+ * 페이지 키보드 네비게이션 가이드 버튼.
+ *
+ * 포커스되면 ←/→ 키로 페이지 이동이 가능하다는 라벨이 슬라이드 인.
+ * 터치 전용 기기(`pointer: coarse`)에서는 의미가 없으므로 자동 숨김.
+ */
+export declare function KeyboardNavButton({ onKeyDown }: KeyboardNavButtonProps): import("react").JSX.Element;
+export {};

package/dist/src/components/table/components/PageJumpInput.d.ts

@@ -0,0 +1,16 @@
+interface PageJumpInputProps {
+    currentPage: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    className?: string;
+    "data-testid"?: string;
+}
+/**
+ * 페이지 번호 직접 입력 → Enter로 점프.
+ *
+ * - 입력 동안에는 로컬 state, Enter 시점에만 onPageChange 호출.
+ * - 입력 시점에 totalPages를 초과하면 즉시 totalPages로 clamp.
+ * - 빈 값 또는 숫자가 아닐 땐 무시.
+ */
+export declare function PageJumpInput({ currentPage, totalPages, onPageChange, className, "data-testid": testId, }: PageJumpInputProps): import("react").JSX.Element;
+export {};

package/dist/src/components/table/components/Pagination.d.ts

@@ -0,0 +1,38 @@
+import { ComponentPropsWithoutRef } from 'react';
+/**
+ * 페이지네이션 Props
+ */
+export interface PaginationProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** 현재 페이지 (1-base) */
+    currentPage: number;
+    /** 전체 페이지 수 */
+    totalPages: number;
+    /** 페이지 변경 핸들러 */
+    onPageChange: (page: number) => void;
+    /** 이전 페이지 존재 여부 (false면 이전/처음 비활성) */
+    hasPreviousPage?: boolean;
+    /** 다음 페이지 존재 여부 (false면 다음/끝 비활성) */
+    hasNextPage?: boolean;
+    /** 페이지 번호 버튼 최대 표시 개수 (넓은 화면 기준). 컨테이너 폭에 따라 자동 축소. */
+    maxPageButtons?: number;
+    /** 테스트 ID */
+    "data-testid"?: string;
+}
+/**
+ * Pagination 컴포넌트.
+ *
+ * 컨테이너 폭 + 페이지 자릿수에 반응해 표시할 페이지 버튼 개수를 동적으로 결정.
+ * - 기본 후보: 9 → 7 → 5 → 3 → 1.
+ * - 가용 폭에서 가장 큰 후보를 선택.
+ * - 첫/이전/다음/끝 버튼은 항상 표시(가운데 페이지 윈도우만 축소).
+ *
+ * @example
+ * ```tsx
+ * <Pagination
+ *   currentPage={1}
+ *   totalPages={10}
+ *   onPageChange={setPage}
+ * />
+ * ```
+ */
+export declare function Pagination({ currentPage, totalPages, onPageChange, hasPreviousPage, hasNextPage, maxPageButtons, className, "data-testid": testId, ...restProps }: PaginationProps): import("react").JSX.Element | null;

package/dist/src/components/table/components/PaginationFooter.d.ts

@@ -0,0 +1,28 @@
+export interface PaginationFooterProps {
+    currentPage: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    /** 페이지 사이즈 셀렉터 노출 — onPageSizeChange와 pageSize가 함께 있어야 그려짐. */
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    onPageSizeChange?: (size: number) => void;
+    /** 백엔드 메타필드 우선, 미지정 시 currentPage 비교로 폴백. */
+    hasPreviousPage?: boolean;
+    hasNextPage?: boolean;
+    /** "총 N건" 표시용. */
+    totalElements?: number;
+    /** "총 N건" 노출 여부. @default true */
+    showTotalCount?: boolean;
+    /** 페이지 점프 입력 + 키보드 가이드 노출. @default true */
+    enablePageJump?: boolean;
+    /** Alt + ←/→ 네비게이션. @default true */
+    enableKeyboardPagination?: boolean;
+    "data-testid"?: string;
+}
+/**
+ * 페이지네이션 footer — "총 N건" + 페이지당 셀렉터 + PageJump + 키보드 가이드 + Pagination.
+ *
+ * PaginatedTable / PaginatedMiniTable 등이 동일한 footer를 공유하기 위해 분리.
+ * 좁은 footer(< 640px)에선 점프/키보드가 좌측 줄(상단), 넓을 땐 우측 그룹 안에 위치.
+ */
+export declare function PaginationFooter({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, hasPreviousPage, hasNextPage, totalElements, showTotalCount, enablePageJump, enableKeyboardPagination, "data-testid": testId, }: PaginationFooterProps): import("react").JSX.Element;

package/dist/src/components/table/components/SortableHeaderCell.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties, ReactNode } from 'react';
+interface SortableHeaderCellProps {
+    id: string;
+    /**
+     * 드래그 비활성 (시스템 컬럼 등)
+     */
+    disabled?: boolean;
+    /**
+     * 컨테이너 태그 — 가상화는 div, 일반 테이블은 th
+     * @default "div"
+     */
+    as?: "div" | "th";
+    /** `as="th"`일 때만 의미. 컬럼 그룹 헤더에서 사용. */
+    colSpan?: number;
+    /** `as="th"`일 때만 의미. 그룹과 평면 컬럼이 섞일 때 평면 컬럼은 rowSpan=2. */
+    rowSpan?: number;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+/**
+ * 헤더 셀을 드래그 가능한 sortable item으로 감싸요.
+ * 5px 임계는 부모 DndContext의 PointerSensor에서 처리해서, 헤더 클릭(정렬)이나
+ * 리사이즈 핸들 mousedown은 방해하지 않아요.
+ */
+export declare function SortableHeaderCell({ id, disabled, as, colSpan, rowSpan, className, style, children, }: SortableHeaderCellProps): import("react").JSX.Element;
+export {};

package/dist/src/components/table/hooks/useColumnPresets.d.ts

@@ -0,0 +1,48 @@
+import { PresetNumber } from '../../../../lib/column-preset-storage';
+import { TableColumn, TableColumnGroupMeta } from '../types';
+export interface UseColumnPresetsOptions<T> {
+    /** localStorage 페이지 키. 미지정 시 메모리만 사용. */
+    pageKey?: string;
+    columns: TableColumn<T>[];
+    /**
+     * 컬럼 그룹 메타. 정의 시 columnOrder/hiddenColumns가 다루는 단위가 슬롯(그룹키 또는 컬럼키)이 된다.
+     * 옵션 2 정책 — 그룹은 묶음 고정.
+     */
+    columnGroups?: TableColumnGroupMeta[];
+    /** 기존 단일 키로 저장된 width 데이터를 프리셋 시스템으로 1회 마이그레이션. */
+    legacyStorageKey?: string;
+}
+export interface UseColumnPresetsReturn {
+    activePreset: PresetNumber;
+    /** 편집 중 상태(메모리). 헤더 DnD/리사이즈/드롭다운 편집은 여기에만 반영. */
+    columnOrder: string[];
+    hiddenColumns: string[];
+    columnWidths: Record<string, number>;
+    /** 저장본과 편집본이 다를 때 true. */
+    isDirty: boolean;
+    hasPreset: (num: PresetNumber) => boolean;
+    /** 다른 프리셋 활성화. 편집 중 변경분은 버려짐. */
+    applyPreset: (num: PresetNumber) => void;
+    /** 현재 편집 중 상태를 저장본으로 commit. 빈 order 등으로 실패하면 false. */
+    saveActivePreset: () => boolean;
+    /** 지정 프리셋에 현재 편집 중 상태를 저장하고 그 프리셋을 활성화. 실패 시 false. */
+    saveAsPreset: (num: PresetNumber) => boolean;
+    /** 활성 프리셋을 기본값(빈 저장본)으로 되돌리고 편집본도 초기화. */
+    resetActivePreset: () => void;
+    /** 편집 중 상태 변경 (자동 persist 없음). */
+    setColumnOrder: (next: string[]) => void;
+    setHiddenColumns: (next: string[]) => void;
+    setColumnWidths: (next: Record<string, number>) => void;
+    /** 단일 키 너비 갱신. 0 이하면 키 제거(기본값 복원). */
+    setColumnWidth: (key: string, width: number) => void;
+}
+/**
+ * 컬럼 프리셋 관리 훅 (B-2 모델)
+ *
+ * - 활성 프리셋의 (순서/숨김/너비) 셋을 편집 중 상태로 메모리 보유
+ * - 헤더 DnD, 리사이즈, 드롭다운 편집은 모두 편집 중 상태에만 반영 (자동 persist 없음)
+ * - 명시 저장(`saveActivePreset` / `saveAsPreset`) 시에만 localStorage에 commit
+ * - 새로고침 시 마지막 저장본으로 복귀
+ * - 다른 프리셋으로 전환 시 편집 중 변경분은 그대로 버려짐
+ */
+export declare function useColumnPresets<T>({ pageKey, columns, columnGroups, legacyStorageKey, }: UseColumnPresetsOptions<T>): UseColumnPresetsReturn;

package/dist/src/components/table/hooks/useColumnResize.d.ts

@@ -0,0 +1,99 @@
+import { ReactNode } from 'react';
+/**
+ * 컬럼 너비 상태 타입
+ */
+export interface ColumnWidths {
+    [key: string]: number;
+}
+/**
+ * 컬럼 리사이즈 훅 옵션
+ */
+export interface UseColumnResizeOptions<T> {
+    /**
+     * 컬럼 정의 배열
+     */
+    columns: Array<{
+        key: string;
+        header?: string | ReactNode;
+    }>;
+    /**
+     * 테이블 데이터
+     */
+    data: T[];
+    /**
+     * 셀 내용 추출 함수
+     */
+    getCellContent: (row: T, key: string) => ReactNode;
+    /**
+     * 기본 컬럼 너비
+     * @default 150
+     */
+    defaultWidth?: number;
+    /**
+     * 최소 컬럼 너비
+     * @default 50
+     */
+    minWidth?: number;
+    /**
+     * 최대 컬럼 너비
+     */
+    maxWidth?: number;
+    /**
+     * 테이블 요소 ref (실제 DOM 측정용)
+     */
+    tableRef?: React.RefObject<HTMLTableElement | null>;
+    /**
+     * 컬럼 너비 저장 키 (localStorage 키, 저장 기능 활성화).
+     * `controlledWidths`가 주어지면 무시된다.
+     */
+    storageKey?: string;
+    /**
+     * 외부(예: 프리셋 훅)에서 너비를 controlled로 주입. 주어지면 내부 state 대신 사용.
+     */
+    controlledWidths?: ColumnWidths;
+    /**
+     * controlled 모드일 때 너비가 변할 때마다 호출. 외부 store에 반영 책임을 넘긴다.
+     */
+    onColumnWidthsChange?: (widths: ColumnWidths) => void;
+}
+/**
+ * 컬럼 리사이즈 훅 반환값
+ */
+export interface UseColumnResizeReturn {
+    /**
+     * 컬럼 너비 상태
+     */
+    columnWidths: ColumnWidths;
+    /**
+     * 마우스 다운 핸들러 (드래그 시작)
+     */
+    handleMouseDown: (key: string, e: React.MouseEvent) => void;
+    /**
+     * 더블 클릭 핸들러 (자동 너비 조절)
+     */
+    handleDoubleClick: (key: string, e: React.MouseEvent) => void;
+    /**
+     * 컬럼 너비 가져오기
+     */
+    getColumnWidth: (key: string, defaultWidth?: number | string) => string;
+    /**
+     * 측정용 ref
+     */
+    measureRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * 컬럼 리사이즈 훅
+ *
+ * @example
+ * ```tsx
+ * const { columnWidths, handleMouseDown, handleDoubleClick, getColumnWidth, measureRef } = useColumnResize({
+ *   columns,
+ *   data,
+ *   getCellContent: (row, key) => {
+ *     const column = columns.find((col) => col.key === key);
+ *     return column?.accessor ? column.accessor(row) : (row as any)[key];
+ *   },
+ * });
+ * ```
+ */
+export declare function useColumnResize<T = any>({ columns, defaultWidth, minWidth, maxWidth, tableRef, storageKey, controlledWidths, onColumnWidthsChange, }: UseColumnResizeOptions<T>): UseColumnResizeReturn;

package/dist/src/components/table/hooks/useFillEmptyRows.d.ts

@@ -0,0 +1,51 @@
+import { RefObject } from 'react';
+export type FillEmptyRowsRemainingMode = "sum-real-rows" | "tbody-height";
+export interface UseFillEmptyRowsOptions {
+    /** 활성 여부. false면 빈 행 0으로 고정. */
+    enabled: boolean;
+    /** 스크롤 컨테이너 ref — 가용 높이의 기준. */
+    containerRef: RefObject<HTMLElement | null>;
+    /** thead ref — 헤더 높이만큼 가용 영역에서 제외. */
+    theadRef: RefObject<HTMLElement | null>;
+    /** tbody ref — 평균 행 높이 측정 + 잔여 공간 계산. */
+    tbodyRef: RefObject<HTMLElement | null>;
+    /**
+     * 평균 행 높이 측정에서 제외할 행을 가리키는 CSS selector.
+     * 예: `"tr:not([data-empty-row])"`, `"tr:not([data-empty-row]):not([data-expanded-row])"`
+     */
+    excludeRowsSelector: string;
+    /**
+     * 잔여 공간 계산 방식.
+     * - `sum-real-rows`: 측정 대상 행들의 높이 합을 뺀다 (펼침 없는 단순 테이블).
+     * - `tbody-height`: tbody 전체 높이를 뺀다 (펼침 행이 있어 tbody가 동적으로 커지는 경우).
+     */
+    remainingMode: FillEmptyRowsRemainingMode;
+    /**
+     * tbody 자체도 ResizeObserver로 감시할지. 펼침 토글 등 tbody 높이가 변하는 경우 true.
+     * @default false
+     */
+    observeTbody?: boolean;
+    /**
+     * effect deps에 함께 묶을 추가 값들. data/visibleColumns 등 측정에 영향 주는 외부 값.
+     *
+     * **중요**: 호출처에서 안정 참조로 넘겨야 한다. 매 렌더마다 새 배열/객체가 들어오면
+     * effect가 매 렌더 재구독되어 ResizeObserver가 반복 생성/해제된다.
+     * - 배열/객체: `useMemo`로 메모이즈
+     * - 원시값(length, key 등): 그대로 전달 OK
+     * - 펼침 토글 등 DOM 변화는 `observeTbody` ResizeObserver가 잡으므로 deps에 두지 말 것.
+     */
+    deps?: ReadonlyArray<unknown>;
+}
+export interface UseFillEmptyRowsReturn {
+    /** 빈 행으로 채워야 할 개수. */
+    emptyRowCount: number;
+    /** 측정된 평균 행 높이(px). 빈 행의 height에 그대로 적용 가능. */
+    measuredRowHeight: number | null;
+}
+/**
+ * 컨테이너 잔여 공간만큼 빈 행을 채우기 위한 개수/높이를 계산한다.
+ *
+ * `Table`(단순)과 `AccordionTable`(펼침 포함) 모두에서 동일한 측정 흐름을 공유하되,
+ * 측정 대상 행 셀렉터와 잔여 공간 계산 방식만 옵션으로 다르게 받는다.
+ */
+export declare function useFillEmptyRows({ enabled, containerRef, theadRef, tbodyRef, excludeRowsSelector, remainingMode, observeTbody, deps, }: UseFillEmptyRowsOptions): UseFillEmptyRowsReturn;

package/dist/src/components/table/hooks/useInfiniteScroll.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 무한스크롤 훅 옵션
+ */
+export interface UseInfiniteScrollOptions {
+    /**
+     * 다음 페이지 로드 함수
+     */
+    fetchNextPage: () => void;
+    /**
+     * 다음 페이지 존재 여부
+     */
+    hasNextPage: boolean;
+    /**
+     * 다음 페이지 로딩 중 여부
+     */
+    isFetchingNextPage: boolean;
+    /**
+     * 스크롤 컨테이너 ref (없으면 window 사용)
+     */
+    scrollElement?: HTMLElement | null;
+    /**
+     * 스크롤 임계값 (하단에서 얼마나 떨어진 위치에서 로드할지, %)
+     * @default 80
+     */
+    threshold?: number;
+    /**
+     * 활성화 여부
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * 무한스크롤 훅
+ *
+ * 스크롤이 하단에 도달하면 자동으로 다음 페이지를 로드해요.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   data,
+ *   fetchNextPage,
+ *   hasNextPage,
+ *   isFetchingNextPage,
+ * } = useApiInfiniteQuery({ ... });
+ *
+ * const containerRef = useRef<HTMLDivElement>(null);
+ *
+ * useInfiniteScroll({
+ *   fetchNextPage,
+ *   hasNextPage,
+ *   isFetchingNextPage,
+ *   scrollElement: containerRef.current,
+ * });
+ * ```
+ */
+export declare function useInfiniteScroll({ fetchNextPage, hasNextPage, isFetchingNextPage, scrollElement, threshold, enabled, }: UseInfiniteScrollOptions): {
+    sentinelRef: import('react').RefObject<HTMLDivElement | null>;
+};

package/dist/src/components/table/hooks/useTableColumnState.d.ts

@@ -0,0 +1,30 @@
+import { ReactElement } from 'react';
+import { TableColumn, TableColumnGroupMeta, TableColumnState } from '../types';
+interface Options<T> {
+    /** localStorage 페이지 키. 없으면 프리셋 비활성(컬럼 상태는 메모리만). */
+    pageKey?: string;
+    columns: TableColumn<T>[];
+    /** 컬럼 그룹 메타 — 정의 시 슬롯 단위(그룹키 or 컬럼키)로 순서/숨김 관리. */
+    columnGroups?: TableColumnGroupMeta[];
+    /** 컬럼 프리셋 셀렉터 UI 노출 여부. 기본 true. */
+    showSelector?: boolean;
+    /** ColumnPresetSelector에 적용할 className. */
+    selectorClassName?: string;
+}
+interface Result {
+    /** Table에 넘길 controlled column-state 객체. */
+    columnState: TableColumnState;
+    /**
+     * 렌더할 프리셋 셀렉터 element. `showSelector=false`이거나 `pageKey` 미지정 시 null.
+     * 페이지에서 원하는 위치에 그대로 꽂으면 된다.
+     */
+    selector: ReactElement | null;
+}
+/**
+ * Table의 controlled column-state + 프리셋 셀렉터 UI를 한 번에 묶어주는 헬퍼.
+ *
+ * 페이지/widget이 `useColumnPresets`를 직접 부르고 두 군데(셀렉터/Table)에 같은 객체를
+ * 분배하는 보일러플레이트를 줄인다. 더 세밀한 제어가 필요하면 `useColumnPresets`를 직접 사용한다.
+ */
+export declare function useTableColumnState<T>({ pageKey, columns, columnGroups, showSelector, selectorClassName, }: Options<T>): Result;
+export {};

package/dist/src/components/table/hooks/useTableDragSelection.d.ts

@@ -0,0 +1,35 @@
+interface Options<T> {
+    /** 현재 표에 그려진 row들 (순서대로). */
+    rows: T[];
+    /** row의 안정 식별자. */
+    getRowId: (row: T) => string | number;
+    /** 어떤 row가 현재 선택되었는지 알려준다 — 드래그 시작 시 모드(check/uncheck)를 결정한다. */
+    isSelected: (row: T) => boolean;
+    /** 단일 row의 선택 상태를 next로 강제 설정. */
+    setSelected: (row: T, next: boolean) => void;
+    /** 훅을 활성화할지 여부. false면 window 리스너를 등록하지 않는다. */
+    enabled?: boolean;
+    /** 자동 스크롤 컨테이너 ref (window 리스너 + 좌표 비교). */
+    scrollContainerRef?: React.RefObject<HTMLElement | null>;
+    /** 자동 스크롤 트리거 영역(컨테이너 상/하단 px). 기본 60. */
+    edgeSize?: number;
+    /** 자동 스크롤 최대 속도(px/frame). 기본 14. */
+    maxSpeed?: number;
+}
+/**
+ * 표의 다중 행을 드래그로 선택/해제한다 — 비스킷링크의 드래그 체크 패턴을 일반화.
+ *
+ * 동작:
+ * - mouseDown(row 인덱스 i): 드래그 시작. row의 현재 선택 상태를 뒤집은 값을 모드로 잡고, 그 row를 그 모드로 적용
+ * - mouseEnter(row 인덱스 j): 드래그 중이면 [lastIndex, j] 범위의 모든 row를 모드와 다른 항목만 토글
+ * - mouseUp/mouseLeave(window): 드래그 종료
+ * - 드래그 중 컨테이너 상/하 edgeSize 안에 마우스가 들어오면 매 프레임 자동 스크롤
+ *
+ * 드래그 도중 데이터가 refetch 등으로 흔들려도 마지막 식별자(lastIdRef)를 기준으로 인덱스를 다시 찾아
+ * 어긋남 위험을 줄인다.
+ */
+export declare function useTableDragSelection<T>({ rows, getRowId, isSelected, setSelected, enabled, scrollContainerRef, edgeSize, maxSpeed, }: Options<T>): {
+    onRowMouseDown: (index: number) => void;
+    onRowMouseEnter: (index: number) => void;
+};
+export {};

package/dist/src/components/table/hooks/useTableSort.d.ts

@@ -0,0 +1,47 @@
+import { ColumnSort } from '../types';
+/**
+ * 테이블 정렬 훅 옵션
+ */
+export interface UseTableSortOptions {
+    /**
+     * 초기 정렬 상태
+     */
+    initialSort?: ColumnSort;
+    /**
+     * 서버 사이드 정렬 사용 여부
+     * @default false
+     */
+    serverSide?: boolean;
+    /**
+     * 서버 사이드 정렬 콜백
+     */
+    onSort?: (sort: ColumnSort) => void;
+}
+/**
+ * 테이블 정렬 훅 반환값
+ */
+export interface UseTableSortReturn {
+    /**
+     * 현재 정렬 상태
+     */
+    sort: ColumnSort | null;
+    /**
+     * 정렬 핸들러
+     */
+    handleSort: (key: string) => void;
+    /**
+     * 정렬된 데이터 (클라이언트 사이드 정렬 시)
+     */
+    sortedData: <T>(data: T[], getValue: (row: T, key: string) => any) => T[];
+}
+/**
+ * 테이블 정렬 훅
+ *
+ * @example
+ * ```tsx
+ * const { sort, handleSort, sortedData } = useTableSort({
+ *   initialSort: { key: 'date', direction: 'desc' },
+ * });
+ * ```
+ */
+export declare function useTableSort({ initialSort, serverSide, onSort, }?: UseTableSortOptions): UseTableSortReturn;

package/dist/src/components/table/hooks/useVirtualTable.d.ts

@@ -0,0 +1,49 @@
+import { Virtualizer } from '@tanstack/react-virtual';
+/**
+ * 가상화 테이블 훅 옵션
+ */
+export interface UseVirtualTableOptions {
+    /**
+     * 데이터 개수
+     */
+    count: number;
+    /**
+     * 예상 행 높이 (px)
+     * @default 50
+     */
+    estimateSize?: number;
+    /**
+     * 화면 밖 렌더링 범위 (overscan)
+     * @default 5
+     */
+    overscan?: number;
+    /**
+     * 스크롤 컨테이너 ref
+     */
+    scrollElement?: HTMLElement | null;
+}
+/**
+ * 가상화 테이블 훅 반환값
+ */
+export interface UseVirtualTableReturn {
+    /**
+     * 가상화 인스턴스
+     */
+    virtualizer: Virtualizer<HTMLElement, Element>;
+    /**
+     * 스크롤 컨테이너 ref
+     */
+    parentRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * 가상화 테이블 훅
+ *
+ * @example
+ * ```tsx
+ * const { virtualizer, parentRef } = useVirtualTable({
+ *   count: data.length,
+ *   estimateSize: 60,
+ * });
+ * ```
+ */
+export declare function useVirtualTable({ count, estimateSize, overscan, scrollElement, }: UseVirtualTableOptions): UseVirtualTableReturn;

package/dist/src/components/table/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Table 컴포넌트 모듈 export
+ */
+export { Table } from './table';
+export { PaginatedTable } from './paginated-table';
+export { MiniTable } from './mini-table';
+export type { MiniTableProps } from './mini-table';
+export { PaginatedMiniTable } from './paginated-mini-table';
+export type { PaginatedMiniTableProps } from './paginated-mini-table';
+export { AccordionTable } from './accordion-table';
+export type { AccordionTableProps, AccordionExpandable, ExpandedRowId, } from './accordion-table';
+export type { TableProps, PaginatedTableProps, TableColumn, TableColumnGroupMeta, TableColumnState, TableVariant, TableSize, SortDirection, ColumnSort, } from './types';
+export { useVirtualTable } from './hooks/useVirtualTable';
+export type { UseVirtualTableOptions, UseVirtualTableReturn, } from './hooks/useVirtualTable';
+export { useTableSort } from './hooks/useTableSort';
+export type { UseTableSortOptions, UseTableSortReturn, } from './hooks/useTableSort';
+export { useInfiniteScroll } from './hooks/useInfiniteScroll';
+export type { UseInfiniteScrollOptions } from './hooks/useInfiniteScroll';
+export { Pagination } from './components/Pagination';
+export type { PaginationProps } from './components/Pagination';
+export { ColumnPresetSelector } from './components/ColumnPresetSelector';
+export { ColumnSettingsTable } from './components/ColumnSettingsTable';
+export { useColumnPresets } from './hooks/useColumnPresets';
+export type { UseColumnPresetsOptions, UseColumnPresetsReturn, } from './hooks/useColumnPresets';
+export { useTableColumnState } from './hooks/useTableColumnState';
+export { ColumnPresetStorage } from '../../../lib/column-preset-storage';
+export type { PresetNumber, ColumnPresetData, PagePresets, AllPresets, } from '../../../lib/column-preset-storage';

package/dist/src/components/table/mini-table.d.ts

@@ -0,0 +1,44 @@
+import { TableColumn, TableSize, TableVariant } from './types';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+export interface MiniTableProps<T> extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    data: T[];
+    /** 컬럼 정의 — `TableColumn`과 동일 타입이지만 sortable/sticky 등 일부 옵션은 무시한다. */
+    columns: TableColumn<T>[];
+    loading?: boolean;
+    isFetching?: boolean;
+    emptyMessage?: string;
+    rowHeight?: number;
+    height?: number | string;
+    variant?: TableVariant;
+    size?: TableSize;
+    /** 행 부족 시 빈 행으로 채워 컨테이너 높이 유지. @default true */
+    fillEmptyRows?: boolean;
+    /** 행 클릭 핸들러 — 상세 드릴다운 등. */
+    onRowClick?: (row: T, index: number) => void;
+    /** footer 영역 (페이지네이션 등). */
+    footerSlot?: ReactNode;
+    /**
+     * 행의 React key 추출. 데이터가 변경되는 페이지네이션 컨텍스트에서 stale 상태 재사용을 막는다.
+     * 미지정 시 index를 사용(데이터가 정적인 경우만 안전).
+     */
+    getRowKey?: (row: T, index: number) => string | number;
+    "data-testid"?: string;
+}
+/**
+ * MiniTable — 통계 카드/요약 카드용 단순 표.
+ *
+ * Table과의 차이:
+ * - 헤더 DnD / 리사이즈 / grip / 컬럼 프리셋 / 정렬 없음
+ * - 행 선택 / 체크박스 / 드래그 멀티선택 없음
+ * - sticky 헤더 / 가상화 없음
+ * - 우측 더미 컬럼 없음 — 컬럼 너비 합이 부족하면 마지막 컬럼이 잔여폭 흡수
+ * - 본문 컨테이너는 `overflow-x: auto; overflow-y: hidden` 고정 — 통계 카드에서 행 수가
+ *   정확히 표시되고, 가로 스크롤바가 컨테이너 높이를 깎아 의도치 않은 세로 스크롤이 생기는 걸 방지
+ *
+ * **사용 시 주의**: `table-layout: auto`라 컬럼 width는 콘텐츠 우선. 짧은 라벨 + 고정 데이터
+ * 패턴(투자 변동 이력 등)에 적합. 컬럼별 콘텐츠 길이 편차가 큰 페이지에 재사용할 때는
+ * 미리 한 번 다양한 데이터 모양으로 시각 검증.
+ */
+export declare const MiniTable: <T>(props: MiniTableProps<T> & {
+    ref?: React.ForwardedRef<HTMLDivElement>;
+}) => React.ReactElement;