react-glide-table 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,22 +1,41 @@
 import * as react from 'react';
-import { ReactNode, ReactElement } from 'react';
-import { ColumnDef, RowSelectionState, Updater, Row } from '@tanstack/react-table';
+import { ReactNode, ComponentType, RefObject } from 'react';
+import { ColumnDef, RowSelectionState, Updater, Row, Table } from '@tanstack/react-table';
 export { ColumnDef, RowSelectionState } from '@tanstack/react-table';
+import { Virtualizer, VirtualItem } from '@tanstack/react-virtual';
+
+type DataTableLabels = {
+    empty: string;
+    loading: string;
+    selection: (selectedCount: number) => ReactNode;
+    expandRow: string;
+    collapseRow: string;
+};
+/** Default copy. Override via the `labels` option. */
+declare const DEFAULT_DATA_TABLE_LABELS: DataTableLabels;
+declare function resolveDataTableLabels(partial?: Partial<DataTableLabels>): DataTableLabels;
+
+/** Neutral default field names for tree conversion */
+declare const DEFAULT_TREE_ID_FIELD = "id";
+declare const DEFAULT_TREE_PARENT_ID_FIELD = "parentId";
+declare const DEFAULT_TREE_CHILDREN_FIELD = "children";
+declare const DEFAULT_TREE_QTY_FIELD = "qty";
 
 type RowSelectionMode = "none" | "single" | "multi";
 type CellEditType = "text" | "number";
+
 declare module "@tanstack/react-table" {
     interface ColumnMeta<TData, TValue> {
-        /** 세로 병합 대상 컬럼 여부 */
+        /** Whether this column participates in vertical row spanning */
         rowSpan?: boolean;
-        /** 병합 기준 필드. 미지정 시 컬럼 id 사용 */
+        /** Merge key field. Falls back to the column id when omitted */
         rowSpanKey?: string;
         align?: "left" | "center" | "right";
         className?: string;
         headerClassName?: string;
-        /** true면 더블클릭으로 인라인 편집 가능 */
+        /** When true, double-click starts inline editing */
         editable?: boolean;
-        /** 편집 입력 타입. 기본 text */
+        /** Inline editor input type. Defaults to text */
         editType?: CellEditType;
     }
 }
@@ -26,56 +45,116 @@ type DataTableProps<T extends Record<string, unknown>> = {
     rowSelectionMode?: RowSelectionMode;
     rowSelection?: RowSelectionState;
     onRowSelectionChange?: (updater: Updater<RowSelectionState>) => void;
-    /** 전체 건수 (검색 전) */
+    /** Total row count before filtering */
     totalCount?: number;
-    /** 현재 표시 건수 (검색 후) */
+    /** Visible row count after filtering */
     filteredCount?: number;
-    /** 좌측 요약 영역 (예: 총 생산수량) */
+    /** Left-side summary slot */
     summary?: ReactNode;
-    /** 우측 액션 슬롯 (Excel, 삭제, 작업전송 등) */
+    /** Right-side action slot */
     toolbar?: ReactNode;
-    /** 선택 문구 커스터마이즈. 미지정 시 기본 "N개 선택됨" */
+    /**
+     * UI copy overrides.
+     * Takes precedence over `emptyText` / `selectionLabel`.
+     */
+    labels?: Partial<DataTableLabels>;
+    /** @deprecated Prefer `labels.selection` */
     selectionLabel?: (selectedCount: number) => ReactNode;
     isPending?: boolean;
+    /** @deprecated Prefer `labels.empty` */
     emptyText?: string;
+    /** @deprecated Prefer `labels.loading` */
+    loadingText?: string;
     enableRowSpan?: boolean;
     getRowId?: (row: T, index: number) => string;
     onRowClick?: (row: T, index: number) => void;
     preserveRowSelection?: boolean;
     getRowClassName?: (row: T, index: number) => string | undefined;
-    /** false를 반환하면 해당 행은 선택할 수 없음 (행 클릭·체크박스 모두 적용) */
+    /** Return false to make the row unselectable (row click and checkbox) */
     getRowCanSelect?: (row: T, index: number) => boolean;
-    /** false면 행 클릭으로 선택 토글하지 않음 (체크박스 컬럼만 선택할 때) */
+    /** When false, row click does not toggle selection (checkbox-only) */
     selectOnRowClick?: boolean;
-    /** 셀 편집·채우기 핸들 완료 시 데이터 갱신 콜백 */
+    /**
+     * Enable cell drag selection and fill handle. Defaults to true.
+     * When false, browser text selection is allowed and cell selection UI is off.
+     */
+    enableCellSelection?: boolean;
+    /**
+     * @deprecated Combining with paged/tree-transformed data can corrupt the source.
+     * Prefer onCellChange / onBatchChange.
+     */
     onDataChange?: (data: T[]) => void;
+    /** Single-cell change (edit commit). Takes precedence over onDataChange */
+    onCellChange?: (rowId: string, columnId: string, value: unknown) => void;
+    /** Multi-cell change (fill handle, etc.). Takes precedence over onDataChange */
+    onBatchChange?: (changes: Array<{
+        rowId: string;
+        columnId: string;
+        value: unknown;
+    }>) => void;
     className?: string;
-    /** 확장 키 필드. 지정 시 트리 변환·로우 확장 UI 활성화 (예: materialCode) */
+    /** Expand key field. Enables tree conversion / expand UI when set. Default `id` */
     toggleField?: string;
-    /** 자식 → 부모 참조 필드 (기본: assemblyCode) */
+    /** Child → parent reference field. Default `parentId` */
     childField?: string;
-    /** 중첩 자식 배열 필드 (기본: assemblyMaterials) */
+    /** Nested children array field. Default `children` */
     flattenField?: string;
-    /** 펼쳐진 행 키 Set (controlled) */
+    /** Parent quantity field used for parentCount. Default `qty` */
+    qtyField?: string;
+    /** Expanded row key set (controlled) */
     expandedRows?: Set<string>;
     onExpandedRowsChange?: (next: Set<string>) => void;
-    /** true면 토글 비활성(자식 항상 표시) */
+    /** When true, expand is disabled (children always visible) */
     preventExpand?: boolean;
     /**
-     * 행 가상화 활성화. 기본 true.
-     * enableRowSpan이 true면 셀 병합 유지를 위해 가상화를 강제 비활성화합니다.
-     * (HTML table + spacer 방식 유지, absolute/translateY 미사용)
+     * Enable row virtualization. Defaults to true.
+     * Forced off when enableRowSpan is true to preserve merges
+     * (HTML table + spacer rows; no absolute/translateY positioning).
      */
     enableVirtualization?: boolean;
-    /** 가상화 행 예상 높이(px). 기본 44. 실측은 measureElement로 보정 */
+    /** Estimated virtual row height in px. Default 44; refined via measureElement */
     estimateRowHeight?: number;
-    /** 가상화 overscan 행 수. 기본 8 */
+    /** Virtualization overscan row count. Default 8 */
     virtualOverscan?: number;
+    /**
+     * Optional UI part replacements for the reference DataTable renderer.
+     * Works with the playground `createTable` / `Table.Column` API.
+     */
+    slots?: DataTableSlots<T>;
+};
+type DataTableToolbarSlotProps = {
+    filteredCount?: number;
+    totalCount?: number;
+    summary?: ReactNode;
+    selectedCount: number;
+    selectionLabel?: (selectedCount: number) => ReactNode;
+    toolbar?: ReactNode;
+    className?: string;
+};
+type DataTableRowSlotProps<T extends Record<string, unknown>> = {
+    row: Row<T>;
+    onToggleSelect: () => void;
+    virtualIndex?: number;
+    measureElement?: (node: Element | null) => void;
+};
+type DataTableSlots<T extends Record<string, unknown>> = {
+    Toolbar?: ComponentType<DataTableToolbarSlotProps>;
+    Row?: ComponentType<DataTableRowSlotProps<T>>;
+    /** Replace the pending state view */
+    Pending?: ComponentType<{
+        loadingText: string;
+        className?: string;
+    }>;
+    /** Replace the empty-state cell content */
+    Empty?: ComponentType<{
+        emptyText: string;
+        columnCount: number;
+    }>;
 };
 type TableColumnProps<T extends Record<string, unknown>, K extends string = keyof T & string> = {
-    /** 컬럼 id. 데이터 필드명이거나 virtual 컬럼용 임의 문자열 */
+    /** Column id: data field name, or an arbitrary id for virtual columns */
     field: K;
-    /** true면 accessorKey 없이 id만 사용하는 가상 컬럼 (선택 체크박스, No. 등) */
+    /** When true, uses id only (no accessorKey) — e.g. checkbox / No. columns */
     virtual?: boolean;
     children?: ReactNode;
     sortable?: boolean;
@@ -93,54 +172,244 @@ type TableProps<T extends Record<string, unknown>> = Omit<DataTableProps<T>, "co
     children: ReactNode;
 };
 
-declare function DataTable<T extends Record<string, unknown>>({ data, columns, rowSelectionMode, rowSelection: controlledRowSelection, onRowSelectionChange, totalCount, filteredCount, summary, toolbar, selectionLabel, isPending, emptyText, enableRowSpan, getRowId, onRowClick, getRowClassName, getRowCanSelect, selectOnRowClick, onDataChange, className, preserveRowSelection, toggleField, childField, flattenField, expandedRows: controlledExpandedRows, onExpandedRowsChange, preventExpand, enableVirtualization, estimateRowHeight, virtualOverscan, }: DataTableProps<T>): react.JSX.Element;
+type EditingCell = {
+    rowIndex: number;
+    colIndex: number;
+};
+type ColumnDefLike = {
+    id?: string;
+    accessorKey?: unknown;
+    meta?: {
+        editable?: boolean;
+        editType?: CellEditType;
+    };
+};
+declare function isColumnEditable(columnDef: ColumnDefLike): boolean;
+declare function getColumnEditType(columnDef: ColumnDefLike): CellEditType;
+declare function parseCellEditValue(raw: string, editType: CellEditType): {
+    ok: true;
+    value: string | number | null;
+} | {
+    ok: false;
+};
+declare function getCellEditDraftValue(value: unknown): string;
+/** Returns updated data on success; null if parsing fails or the cell is not editable */
+declare function applyCellEdit<T extends Record<string, unknown>>(data: T[], rows: Row<T>[], rowIndex: number, colIndex: number, raw: string): T[] | null;
 
-/** 본문 슬롯 마커. 실제 tbody는 DataTable이 렌더합니다. */
-declare function TableBody(): null;
-declare namespace TableBody {
-    var displayName: string;
-}
+type CellPosition = {
+    row: number;
+    col: number;
+};
+type CellSelectionBounds = {
+    startRow: number;
+    endRow: number;
+    startCol: number;
+    endCol: number;
+};
+type DragState = {
+    isSelecting: boolean;
+    isFillDragging: boolean;
+    start: CellPosition | null;
+    end: CellPosition | null;
+    /** Fixed anchor opposite the fill handle (top-left) */
+    fillAnchor: CellPosition | null;
+    fillEnd: CellPosition | null;
+};
+declare function getRowIndexInMergedCell(clientY: number, cellElement: HTMLElement, rowIndex: number, rowSpan: number): number;
+declare function isCellInSelection(rowIndex: number, colIndex: number, bounds: CellSelectionBounds | null, rowSpan?: number): boolean;
+declare const CELL_SELECTION_EDGES_CLASS = "cell-selection-edges";
+type CellSelectionEdgeStyle = {
+    /** Full-side inset border applied via ::after */
+    ["--selection-edge-shadows"]?: string;
+    /** Partial vertical border for merged-cell step (stair) segments */
+    ["--selection-edge-gradients"]?: string;
+    ["--selection-edge-sizes"]?: string;
+    ["--selection-edge-positions"]?: string;
+    /** Hide internal horizontal grid lines inside the selection with background color */
+    borderBottomColor?: string;
+};
+/**
+ * Draws the selection border with ::after (extended -1px at the bottom) plus
+ * inset box-shadow / partial gradients so it does not break on the cell's
+ * border-bottom.
+ *
+ * @param isVisuallySelectedAt Whether a logical cell is visually selected
+ *   (including adjacent merged cells). Used to suppress internal step borders
+ *   when multiple columns have rowSpan.
+ */
+declare function getCellSelectionEdgeStyle(rowIndex: number, colIndex: number, bounds: CellSelectionBounds | null, rowSpan?: number, isVisuallySelectedAt?: (row: number, col: number) => boolean): CellSelectionEdgeStyle | undefined;
+declare function hasCellSelectionEdges(style: CellSelectionEdgeStyle | undefined): boolean;
 
-/** Table.Header 안에서만 사용합니다. DOM을 렌더하지 않고 컬럼 정의만 등록합니다. */
-declare function TableColumn<T extends Record<string, unknown>, K extends string = keyof T & string>(props: TableColumnProps<T, K>): null;
-declare namespace TableColumn {
-    var displayName: string;
-}
+type RowSpanInfo = {
+    /** 0 means skip render (merged into a parent row) */
+    rowSpan: number;
+    isFirstInGroup: boolean;
+};
+type ColumnRowSpanMap = Map<string, RowSpanInfo[]>;
+/**
+ * Returns the start row and rowSpan of the merged cell covering a given row.
+ * Rows with rowSpan === 0 walk up to the merge origin.
+ */
+declare function resolveRowSpanAt(rowSpans: RowSpanInfo[] | undefined, rowIndex: number): {
+    startRow: number;
+    rowSpan: number;
+};
+/**
+ * Computes merge info for every column that has rowSpan meta.
+ */
+declare function buildColumnRowSpanMap<T extends Record<string, unknown>>(data: T[], columnKeys: Array<{
+    columnId: string;
+    rowSpanKey: string;
+}>): ColumnRowSpanMap;
+declare function collectRowSpanColumns<T extends Record<string, unknown>>(columns: ColumnDef<T, unknown>[]): Array<{
+    columnId: string;
+    rowSpanKey: string;
+}>;
 
-type TableHeaderProps = {
-    children: ReactNode;
+type RowData = Record<string, unknown>;
+type DataTableRowContextValue = {
+    rowSpan: {
+        enableRowSpan: boolean;
+        primaryRowSpanKey?: string;
+        columnRowSpanMap: ColumnRowSpanMap;
+        hoveredRowIndex: number | null;
+        hoveredGroupKey: string | null;
+        selectedGroupKeys: Set<string>;
+        onRowHover: (rowIndex: number, rowData: RowData) => void;
+    };
+    selection: {
+        rowSelectionMode: RowSelectionMode;
+        selectOnRowClick: boolean;
+        onRowClick?: (row: RowData, index: number) => void;
+        getRowClassName?: (row: RowData, index: number) => string | undefined;
+    };
+    cellSelection: {
+        enableCellSelection: boolean;
+        activeSelectionBounds: CellSelectionBounds | null;
+        dragState: DragState;
+        onCellMouseDown: (rowIndex: number, colIndex: number) => void;
+        onCellMouseEnter: (rowIndex: number, colIndex: number) => void;
+        onFillHandleMouseDown: (rowIndex: number, colIndex: number) => void;
+    };
+    cellEdit: {
+        editingCell: EditingCell | null;
+        draftValue: string;
+        onDraftValueChange: (value: string) => void;
+        onStartEdit: (rowIndex: number, colIndex: number) => void;
+        onCommitEdit: (raw?: string) => boolean;
+        onCancelEdit: () => void;
+    };
+    expand: {
+        enableExpand: boolean;
+        toggleField?: string;
+        expandedRows?: Set<string>;
+        preventExpand: boolean;
+        onToggleExpand?: (rowKey: string) => void;
+        expandRowLabel: string;
+        collapseRowLabel: string;
+    };
 };
-/** 컬럼 선언 슬롯. DOM을 렌더하지 않습니다. */
-declare function TableHeader(props: TableHeaderProps): null;
-declare namespace TableHeader {
-    var displayName: string;
-}
 
-type TablePaginationProps = {
-    page: number;
-    pageSize?: number;
-    totalCount?: number;
-    onChange: (page: number) => void;
-    className?: string;
+type UseGlideTableOptions<T extends Record<string, unknown>> = Omit<DataTableProps<T>, "className" | "slots" | "summary" | "toolbar" | "isPending" | "totalCount" | "filteredCount">;
+type UseGlideTableResult<T extends Record<string, unknown>> = {
+    table: Table<T>;
+    tableData: T[];
+    rows: Row<T>[];
+    columnCount: number;
+    selectedCount: number;
+    labels: DataTableLabels;
+    emptyText: string;
+    loadingText: string;
+    selectionLabel: DataTableLabels["selection"];
+    enableCellSelection: boolean;
+    shouldVirtualize: boolean;
+    scrollRef: RefObject<HTMLDivElement | null>;
+    rowVirtualizer: Virtualizer<HTMLDivElement, Element>;
+    virtualRows: VirtualItem[];
+    paddingTop: number;
+    paddingBottom: number;
+    rowContextValue: DataTableRowContextValue;
+    handleToggleSelect: (row: Row<T>) => void;
+    clearHover: () => void;
+};
+declare function useGlideTable<T extends Record<string, unknown>>(options: UseGlideTableOptions<T>): UseGlideTableResult<T>;
+
+type UseCellEditOptions<T extends Record<string, unknown>> = {
+    data: T[];
+    rows: Row<T>[];
+    onDataChange?: (data: T[]) => void;
+    onCellChange?: (rowId: string, columnId: string, value: unknown) => void;
+};
+declare function useCellEdit<T extends Record<string, unknown>>({ data, rows, onDataChange, onCellChange, }: UseCellEditOptions<T>): {
+    editingCell: EditingCell | null;
+    draftValue: string;
+    setDraftValue: react.Dispatch<react.SetStateAction<string>>;
+    startEdit: (rowIndex: number, colIndex: number) => void;
+    commitEdit: (raw?: string) => boolean;
+    cancelEdit: () => void;
 };
-declare function TablePagination({ page, pageSize, totalCount, onChange, className, }: TablePaginationProps): react.JSX.Element;
-declare namespace TablePagination {
-    var displayName: string;
-}
 
-type TableCompoundComponent<T extends Record<string, unknown>> = ((props: TableProps<T>) => ReactElement) & {
-    Header: typeof TableHeader;
-    Column: <K extends string>(props: TableColumnProps<T, K>) => null;
-    Body: typeof TableBody;
-    Pagination: typeof TablePagination;
-};
-declare function TableRoot<T extends Record<string, unknown>>({ data, children, className, totalCount, filteredCount, ...dataTableProps }: TableProps<T>): react.JSX.Element;
-declare function createTable<T extends Record<string, unknown>>(): TableCompoundComponent<T>;
-declare const Table: typeof TableRoot & {
-    Header: typeof TableHeader;
-    Column: typeof TableColumn;
-    Body: typeof TableBody;
-    Pagination: typeof TablePagination;
+type UseCellSelectionOptions<T extends Record<string, unknown>> = {
+    data: T[];
+    rows: Row<T>[];
+    enabled?: boolean;
+    onDataChange?: (data: T[]) => void;
+    onBatchChange?: (changes: Array<{
+        rowId: string;
+        columnId: string;
+        value: unknown;
+    }>) => void;
+};
+declare function useCellSelection<T extends Record<string, unknown>>({ data, rows, enabled, onDataChange, onBatchChange, }: UseCellSelectionOptions<T>): {
+    dragState: DragState;
+    activeSelectionBounds: CellSelectionBounds | null;
+    handleCellMouseDown: (rowIndex: number, colIndex: number) => void;
+    handleCellMouseEnter: (rowIndex: number, colIndex: number) => void;
+    handleFillHandleMouseDown: (rowIndex: number, colIndex: number) => void;
+};
+
+type CellChange = {
+    rowId: string;
+    columnId: string;
+    value: unknown;
+};
+declare function collectFillChanges<T extends Record<string, unknown>>(rows: Row<T>[], sourceBounds: CellSelectionBounds, fillBounds: CellSelectionBounds): CellChange[];
+declare function applyFillData<T extends Record<string, unknown>>(data: T[], rows: Row<T>[], sourceBounds: CellSelectionBounds, fillBounds: CellSelectionBounds): T[];
+
+type TreeRow<T extends Record<string, unknown> = Record<string, unknown>> = T & {
+    level: number;
+    children: TreeRow<T>[];
+    treeNo?: string;
+    uniqueId?: string;
+    parentCount?: number;
+    processed?: boolean;
 };
+type UseConvertTreeDataParams<T extends Record<string, unknown>> = {
+    data: T[] | null;
+    /** When false, returns data unchanged (plain DataTable) */
+    enabled?: boolean;
+    /** Row id / expand key field (idField). Defaults to `id` */
+    toggleField?: string;
+    /** Child → parent reference field (parentIdField). Defaults to `parentId` */
+    childField?: string;
+    /** Nested children array field (childrenField). Defaults to `children` */
+    flattenField?: string;
+    /** Parent quantity field (qtyField). Used for parentCount. Defaults to `qty` */
+    qtyField?: string;
+    preventExpand?: boolean;
+    startIndex?: number;
+    expandedRows?: Set<string>;
+    onExpandedRowsChange?: (next: Set<string>) => void;
+};
+declare function canExpandRow(row: Record<string, unknown>): boolean;
+declare function toggleExpandedRowId(rowId: string, previous: Set<string>): Set<string>;
+/**
+ * Builds a tree from flat/nested data, then returns only rows visible under expandedRows.
+ * When enabled=false, returns data as-is.
+ */
+declare const useConvertTreeData: <T extends Record<string, unknown>>({ data, enabled, toggleField, childField, flattenField, qtyField, preventExpand, startIndex, expandedRows, onExpandedRowsChange, }: UseConvertTreeDataParams<T>) => T[];
+
+declare function resolveRowSelection(mode: RowSelectionMode, controlledSelection: RowSelectionState | undefined, internalSelection: RowSelectionState): RowSelectionState;
+declare function applySelectionUpdater(mode: RowSelectionMode, updater: Updater<RowSelectionState>, previous: RowSelectionState): RowSelectionState;
 
-export { DataTable, type DataTableProps, type RowSelectionMode, Table, type TableColumnProps, type TableCompoundComponent, type TableProps, createTable };
+export { CELL_SELECTION_EDGES_CLASS, type CellSelectionBounds, type ColumnRowSpanMap, DEFAULT_DATA_TABLE_LABELS, DEFAULT_TREE_CHILDREN_FIELD, DEFAULT_TREE_ID_FIELD, DEFAULT_TREE_PARENT_ID_FIELD, DEFAULT_TREE_QTY_FIELD, type DataTableLabels, type DataTableProps, type DataTableSlots, type DragState, type EditingCell, type RowSelectionMode, type RowSpanInfo, type TableColumnProps, type TableProps, type TreeRow, type UseConvertTreeDataParams, type UseGlideTableOptions, type UseGlideTableResult, applyCellEdit, applyFillData, applySelectionUpdater, buildColumnRowSpanMap, canExpandRow, collectFillChanges, collectRowSpanColumns, getCellEditDraftValue, getCellSelectionEdgeStyle, getColumnEditType, getRowIndexInMergedCell, hasCellSelectionEdges, isCellInSelection, isColumnEditable, parseCellEditValue, resolveDataTableLabels, resolveRowSelection, resolveRowSpanAt, toggleExpandedRowId, useCellEdit, useCellSelection, useConvertTreeData, useGlideTable };