kokotable 0.95.0

package/dist/mui/src/content/TableContent.js

@@ -0,0 +1,525 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment, useMemo, useState, } from "react";
+import { Box, Button, CircularProgress, IconButton, LinearProgress, Skeleton, Stack, Table, TableBody, TableCell, TableContainer, TableFooter, TableHead, TableRow, Tooltip, Typography, } from "@mui/material";
+import KeyboardArrowDownIcon from "@mui/icons-material/KeyboardArrowDown";
+import KeyboardArrowRightIcon from "@mui/icons-material/KeyboardArrowRight";
+import { flexRender, } from "@tanstack/react-table";
+import { columnMetaOf } from "../../../core/src/index";
+import { HeaderCell, resolveCellAlign } from "./HeaderCell";
+import { EditCell } from "./EditCell";
+import { TableErrorFallback } from "./TableErrorFallback";
+import { renderCellValue } from "./cellValue";
+import { useCellRenderers } from "./cellRenderers";
+import { useAggregations } from "../grouping/AggregateChip";
+import { cellErrorSx, getCellError } from "./cellError";
+import { explicitWidth, pinnedSx } from "./pinning";
+import { resolveDensity } from "./density";
+import { canExpandRow, isDisplayColumnId } from "../columns/displayColumns";
+import { AggregateCellBox, GROUP_DEPTH_INDENT, GroupValueText, groupRowBgColor, groupRowHoverColor, renderAggregateCellContent, resolveGroupValue, } from "../grouping/groupRow";
+import { resolveTableProps, useKokoTableConfig } from "../provider/KokoTableProvider";
+import { ContextMenu, createRowMenuCtx, defaultRowMenuItems, } from "./menuItems";
+/**
+ * 그룹 컬럼 배치 — 렌더 순서만 바꾼다.
+ * `reorder`: 왼쪽 고정 → 그룹 컬럼(grouping 순) → 나머지 → 오른쪽 고정.
+ * `remove`: 그룹 컬럼 제외.
+ * `false`: 선언 순서. `declaredRank`(선언 순서 + `columnOrder`, 그룹핑 무시)를 주면 그 순서로 되돌린다 —
+ *   TanStack 은 `grouping` 상태가 있으면 자체 `groupedColumnMode`(기본 `reorder`)로 이미 그룹 컬럼을
+ *   앞으로 당겨 놓기 때문에, "그대로" 를 그리려면 되돌려야 한다.
+ * 고정 컬럼은 sticky 오프셋(`getStart`)이 TanStack 순서 기준이므로 자리를 옮기지 않는다.
+ */
+export function arrangeGroupedColumns(columns, grouping, mode, declaredRank) {
+    if (grouping.length === 0)
+        return columns;
+    const groupSet = new Set(grouping);
+    if (mode === "remove")
+        return columns.filter((column) => !groupSet.has(column.id));
+    if (!mode && !declaredRank)
+        return columns;
+    const left = [];
+    const right = [];
+    const rest = [];
+    const byId = new Map();
+    for (const column of columns) {
+        const pinned = column.getIsPinned();
+        if (pinned === "left")
+            left.push(column);
+        else if (pinned === "right")
+            right.push(column);
+        else if (mode && groupSet.has(column.id))
+            byId.set(column.id, column);
+        else
+            rest.push(column);
+    }
+    if (declaredRank) {
+        const rank = (column) => declaredRank.get(column.id) ?? Number.MAX_SAFE_INTEGER;
+        rest.sort((a, b) => rank(a) - rank(b));
+    }
+    const groupColumns = grouping.map((id) => byId.get(id)).filter((c) => !!c);
+    return [...left, ...groupColumns, ...rest, ...right];
+}
+/**
+ * 선언 순서(+ `columnOrder` 상태) 기준 리프 컬럼 순위 — TanStack `_getOrderColumnsFn` 과 같은 규칙에서
+ * 그룹핑 재배치만 뺀 것. `getAllFlatColumns()` 는 `orderColumns` 를 거치지 않아 선언 순서가 살아 있다.
+ */
+function declaredLeafRank(table) {
+    const leaves = table.getAllFlatColumns().filter((column) => !column.columns || column.columns.length === 0);
+    const order = table.getState().columnOrder ?? [];
+    let ordered = leaves;
+    if (order.length > 0) {
+        const remaining = [...leaves];
+        const picked = [];
+        for (const id of order) {
+            const index = remaining.findIndex((column) => column.id === id);
+            if (index > -1)
+                picked.push(remaining.splice(index, 1)[0]);
+        }
+        ordered = [...picked, ...remaining];
+    }
+    return new Map(ordered.map((column, index) => [column.id, index]));
+}
+/** 열 가상화에서 비어 있는 좌·우 폭을 채우는 셀 */
+function PadCell({ width, component = "td" }) {
+    return (_jsx(TableCell, { component: component, "aria-hidden": true, "data-testid": `virtual-pad-${component === "th" ? "head" : "cell"}`, sx: { p: 0, border: 0, width, minWidth: width, maxWidth: width } }));
+}
+function formatAggregate(value) {
+    if (value === null || value === undefined)
+        return "-";
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? value.toLocaleString("ko-KR") : value.toFixed(2);
+    }
+    return String(value);
+}
+function mergeSx(...parts) {
+    const list = [];
+    for (const part of parts) {
+        if (!part)
+            continue;
+        if (Array.isArray(part))
+            list.push(...part);
+        else
+            list.push(part);
+    }
+    return list;
+}
+/**
+ * 콘텐츠 구역 — 테이블 본문.
+ *
+ * 로딩·에러·빈 상태를 **제자리에서** 그린다. 조회 실패를 throw 해서 상위
+ * ErrorBoundary 로 올리면 테이블 트리가 통째로 파괴되고, 리마운트가 캐시의
+ * 에러를 다시 읽어 즉시 재-throw 하므로 경계 리셋으로 복구가 안 된다.
+ *
+ * 행 선택·확장·고정·리사이즈·순서는 TanStack 상태를 그대로 그린다. 기능을 켜는 것은
+ * `useDataTable` 의 `tableOptions` (`enableRowSelection`, `enableColumnResizing`,
+ * `getRowCanExpand` …) 몫이고, 체크박스·확장 토글·행 번호·행 액션 열은
+ * `withDisplayColumns()` 로 컬럼 목록에 끼운다.
+ */
+export function TableContent(props) {
+    return _jsx(TableContentBase, { ...props });
+}
+export function TableContentBase(rawProps) {
+    const config = useKokoTableConfig();
+    const { components, labels } = config;
+    const { table, content, sort, groupItems, onToggleGroup, isGroupExpanded, onLoadMore, emptyMessage = labels.ui.empty, renderEmpty, skeletonRows = 5, onResetFilters, renderError, dense = true, density, maxHeight, stickyHeader = true, getRowProps, selectOnRowClick = false, renderDetailPanel, getDetailPanelProps, editing, renderEditDialog, fieldErrors: fieldErrorsProp, onNavigate, enableColumnMenu = true, columnMenuItems, onGroupingChange, aggregation: aggregationProp, onAggregationChange, onOpenFilter, headerCellProps, renderHeader, rowMenuItems, onExpandGroupToDepth, groupedColumnMode = "reorder", grouping: groupingProp, groupRowLayout = "columns", groupRowHeight, aggregateSelection: aggregateSelectionProp, onAggregateSelectionChange, virtual, virtualColumns, containerRef, } = resolveTableProps(rawProps, config.defaults);
+    const HeaderCellComponent = (components.HeaderCell ?? HeaderCell);
+    const EditCellComponent = (components.EditCell ?? EditCell);
+    const status = content?.getStatus();
+    const visibleLeafColumns = table.getVisibleLeafColumns();
+    const rows = table.getRowModel().rows;
+    const grouped = !!groupItems && groupItems.length > 0;
+    const headerGroupCount = table.getHeaderGroups().length;
+    /**
+     * 그룹 컬럼 배치가 실제로 적용되는 기준. 열 가상화·다단 헤더에서는 끈다 —
+     * 가상화는 가운데 컬럼 인덱스로 그리고, 다단 헤더는 colSpan 을 다시 계산할 수 없다.
+     * `null` 이면 TanStack 이 준 순서를 그대로 쓴다.
+     *
+     * TanStack 은 `grouping` 상태만 있어도 자체 `groupedColumnMode`(기본 `reorder`)로 리프 순서를
+     * 바꿔 놓는다. 그래서 `false` 도 "아무것도 안 함" 이 아니라 **선언 순서로 되돌리는** 일이다.
+     * (TanStack 옵션이 `remove` 면 컬럼 자체가 없어 여기서 되살릴 수 없다 — `tableOptions` 에서 끄면 된다.)
+     */
+    const groupingIds = groupingProp ?? table.getState().grouping ?? [];
+    const activeGroupedMode = grouped && groupingIds.length > 0 && !virtualColumns && headerGroupCount === 1
+        ? groupedColumnMode
+        : null;
+    const groupingKey = groupingIds.join("|");
+    const columnOrderState = table.getState().columnOrder;
+    const allFlatColumns = table.getAllFlatColumns();
+    const declaredRank = useMemo(() => (activeGroupedMode === null ? undefined : declaredLeafRank(table)), [table, activeGroupedMode, columnOrderState, allFlatColumns]);
+    const leafColumns = useMemo(() => activeGroupedMode === null
+        ? visibleLeafColumns
+        : arrangeGroupedColumns(visibleLeafColumns, groupingIds, activeGroupedMode, declaredRank), [visibleLeafColumns, groupingKey, activeGroupedMode, declaredRank]);
+    /**
+     * 열 가상화 — 고정(left/right) 컬럼은 전부, 가운데 컬럼은 보이는 범위만 그린다.
+     * 그려지지 않은 폭은 좌·우 패딩 셀 하나씩이 대신 차지해 스크롤 폭·고정 오프셋이 유지된다.
+     * 컬럼 그룹 헤더(2단 이상)는 colSpan 을 맞출 수 없어 가상화하지 않는다.
+     */
+    const columnLayout = useMemo(() => {
+        const headerGroups = table.getHeaderGroups();
+        if (!virtualColumns || headerGroups.length !== 1)
+            return null;
+        const center = table.getCenterVisibleLeafColumns();
+        const items = virtualColumns.items;
+        const padLeft = items.length > 0 ? items[0].start : 0;
+        const padRight = items.length > 0 ? virtualColumns.totalSize - items[items.length - 1].end : 0;
+        return {
+            left: table.getLeftVisibleLeafColumns(),
+            center: items.map((item) => center[item.index]).filter(Boolean),
+            right: table.getRightVisibleLeafColumns(),
+            padLeft,
+            padRight,
+        };
+    }, [table, virtualColumns, leafColumns]);
+    /** 실제로 그려지는 열 수 — colSpan 이 이 값을 넘으면 표가 넓어진다 */
+    const columnCount = columnLayout
+        ? columnLayout.left.length + columnLayout.center.length + columnLayout.right.length
+            + (columnLayout.padLeft > 0 ? 1 : 0) + (columnLayout.padRight > 0 ? 1 : 0)
+        : leafColumns.length;
+    const renderedColumns = columnLayout
+        ? [...columnLayout.left, ...columnLayout.center, ...columnLayout.right]
+        : leafColumns;
+    const spec = resolveDensity(density, dense);
+    const resizingEnabled = !!table.options.enableColumnResizing;
+    const fieldErrors = fieldErrorsProp ?? table.fieldErrors;
+    // Provider 레지스트리(셀·집계)는 내장 세트 위에 얹힌 것 — 예전 맵(`config.cellRenderers`)도 같은 레지스트리에 들어간다
+    const cellRegistry = useCellRenderers();
+    const aggregationRegistry = useAggregations();
+    const cellOptions = useMemo(() => ({ onNavigate, renderers: config.cellRenderers, registry: cellRegistry }), [onNavigate, config.cellRenderers, cellRegistry]);
+    // ── 행 컨텍스트 메뉴 ──
+    const [rowMenu, setRowMenu] = useState(null);
+    const openRowMenu = (event, partial) => {
+        if (event.defaultPrevented)
+            return;
+        const defaultItems = defaultRowMenuItems(partial, labels, config.menus.row);
+        const ctx = { ...createRowMenuCtx(partial, labels), defaultItems };
+        const items = rowMenuItems ? rowMenuItems(ctx) : defaultItems;
+        if (items.length === 0)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        setRowMenu({ position: { top: event.clientY, left: event.clientX }, ctx, items });
+    };
+    // ── 그룹 행 집계 함수 선택 ──
+    const [internalSelection, setInternalSelection] = useState({});
+    const aggregateSelection = aggregateSelectionProp ?? internalSelection;
+    const selectAggregate = (columnId, fn) => {
+        onAggregateSelectionChange?.(columnId, fn);
+        if (aggregateSelectionProp === undefined)
+            setInternalSelection((prev) => ({ ...prev, [columnId]: fn }));
+    };
+    // ── 편집 상태 ──
+    const [editingCell, setEditingCell] = useState(null);
+    const [internalEditingRowId, setInternalEditingRowId] = useState(null);
+    const [modalRow, setModalRow] = useState(null);
+    const editingRowId = editing?.editingRowId !== undefined ? editing.editingRowId : internalEditingRowId;
+    const commit = (value, row, columnId) => {
+        if (editing?.onCommit) {
+            editing.onCommit(value, row, columnId);
+            return;
+        }
+        const editSpec = columnMetaOf(row.getAllCells().find((c) => c.column.id === columnId)?.column.columnDef)?.edit;
+        if (editSpec?.onCommit) {
+            editSpec.onCommit(value, row.original);
+            return;
+        }
+        row.original[columnId] = value;
+    };
+    const enterRowEdit = (row) => {
+        editing?.onEditRow?.(row);
+        if (editing?.mode === "row" && editing.editingRowId === undefined)
+            setInternalEditingRowId(row.id);
+        if (editing?.mode === "modal" && renderEditDialog)
+            setModalRow(row);
+    };
+    /**
+     * 원본 행 객체 → TanStack Row.
+     *
+     * 그룹 트리의 말단은 **그룹 순서**로 정렬돼 있고 `table.getRowModel().rows` 는
+     * 원본(정렬) 순서다. 순번으로 맞추면 펼친 그룹 아래에 다른 그룹의 행이 뜬다.
+     * 객체 동일성으로 찾아야 한다.
+     */
+    const rowByOriginal = useMemo(() => {
+        const map = new Map();
+        for (const row of rows)
+            map.set(row.original, row);
+        return map;
+    }, [rows]);
+    const renderCell = (cell, row, index, indent, rowEditing) => {
+        const column = cell.column;
+        const meta = columnMetaOf(column.columnDef);
+        const isDisplay = isDisplayColumnId(column.id);
+        const editSpec = meta?.edit;
+        const editable = !!editing && !!editSpec?.enabled && !isDisplay;
+        const isEditingCell = editable && (editing.mode === "cell"
+            ? editingCell?.rowId === row.id && editingCell.columnId === column.id
+            : editing.mode === "row" && rowEditing);
+        const error = fieldErrors ? getCellError(fieldErrors, row.index, column.id) : { hasError: false };
+        // 열 가상화는 모든 셀에 명시 폭이 있어야 패딩 셀과 합이 맞는다
+        const width = columnLayout ? column.getSize() : explicitWidth(column, table);
+        const sx = mergeSx(index === 0 && indent > 0 && { pl: 2 + indent * 2 }, meta?.ellipsis && { whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis", maxWidth: width ?? 200 }, spec.cellPy !== undefined && { py: spec.cellPy }, spec.cellPx !== undefined && { px: spec.cellPx }, width !== undefined && { width, minWidth: width, ...(resizingEnabled ? { maxWidth: width } : {}) }, pinnedSx(column, 1), editable && editing.mode === "cell" && !isEditingCell && {
+            cursor: "cell", "&:hover": { backgroundColor: "action.hover" },
+        }, isEditingCell && { py: 0.25 }, error.hasError && cellErrorSx);
+        const inner = isEditingCell ? (_jsx(EditCellComponent, { spec: editSpec, value: cell.getValue(), row: row.original, onCommit: (value) => {
+                commit(value, row, column.id);
+                if (editing.mode === "cell")
+                    setEditingCell(null);
+            }, onCancel: () => {
+                if (editing.mode === "cell")
+                    setEditingCell(null);
+                else if (editing.editingRowId === undefined)
+                    setInternalEditingRowId(null);
+                editing.onCancel?.(row);
+            } })) : renderCellValue(cell, cellOptions);
+        const cellEl = (_jsx(TableCell, { align: isDisplay ? "center" : resolveCellAlign(column.columnDef), size: spec.size, "data-column-id": column.id, "aria-invalid": error.hasError || undefined, onDoubleClick: editable && editing.mode === "cell"
+                ? (event) => { event.stopPropagation(); setEditingCell({ rowId: row.id, columnId: column.id }); }
+                : undefined, sx: sx, children: inner }, cell.id));
+        return error.hasError && error.message ? (_jsx(Tooltip, { title: error.message, arrow: true, placement: "top", children: cellEl }, cell.id)) : cellEl;
+    };
+    /** 행의 셀 — 열 가상화가 켜져 있으면 고정 + 보이는 가운데 + 패딩으로 구성한다 */
+    const renderRowCells = (row, indent, rowEditing) => {
+        if (!columnLayout) {
+            const cells = activeGroupedMode !== null
+                ? arrangeGroupedColumns(row.getVisibleCells().map((cell) => ({ id: cell.column.id, getIsPinned: () => cell.column.getIsPinned(), cell })), groupingIds, activeGroupedMode, declaredRank).map((entry) => entry.cell)
+                : row.getVisibleCells();
+            return cells.map((cell, index) => renderCell(cell, row, index, indent, rowEditing));
+        }
+        const byColumn = new Map(row.getAllCells().map((cell) => [cell.column.id, cell]));
+        const cellOf = (columnId) => byColumn.get(columnId);
+        const out = [];
+        let index = 0;
+        for (const column of columnLayout.left)
+            out.push(renderCell(cellOf(column.id), row, index++, indent, rowEditing));
+        if (columnLayout.padLeft > 0)
+            out.push(_jsx(PadCell, { width: columnLayout.padLeft }, "pad-left"));
+        for (const column of columnLayout.center)
+            out.push(renderCell(cellOf(column.id), row, index++, indent, rowEditing));
+        if (columnLayout.padRight > 0)
+            out.push(_jsx(PadCell, { width: columnLayout.padRight }, "pad-right"));
+        for (const column of columnLayout.right)
+            out.push(renderCell(cellOf(column.id), row, index++, indent, rowEditing));
+        return out;
+    };
+    const renderLeafRow = (row, key, indent = 0, virtualIndex) => {
+        const rowProps = getRowProps?.(row, table) ?? {};
+        const { sx: rowSx, onClick: rowOnClick, onDoubleClick: rowOnDoubleClick, onContextMenu: rowOnContextMenu, selected, hover, ...restRowProps } = rowProps;
+        const rowEditing = editing?.mode === "row" && editingRowId === row.id;
+        const expanded = !!renderDetailPanel && canExpandRow(row, table) && row.getIsExpanded();
+        const clickable = selectOnRowClick && row.getCanSelect();
+        const onClick = (event) => {
+            rowOnClick?.(event);
+            if (clickable && !event.defaultPrevented)
+                row.toggleSelected();
+        };
+        const onDoubleClick = (event) => {
+            rowOnDoubleClick?.(event);
+            if (editing && (editing.mode === "row" || editing.mode === "modal") && !event.defaultPrevented)
+                enterRowEdit(row);
+        };
+        const onContextMenu = (event) => {
+            rowOnContextMenu?.(event);
+            openRowMenu(event, { row, table });
+        };
+        return (_jsxs(Fragment, { children: [_jsx(TableRow, { hover: hover ?? true, selected: selected ?? row.getIsSelected(), "data-index": virtualIndex, "data-row-id": row.id, ref: virtual?.measureElement, ...restRowProps, onClick: onClick, onDoubleClick: onDoubleClick, onContextMenu: onContextMenu, sx: mergeSx(clickable && { cursor: "pointer" }, rowEditing && { backgroundColor: "action.selected" }, rowSx), children: renderRowCells(row, indent, rowEditing) }), expanded && (() => {
+                    const panelProps = getDetailPanelProps?.(row, table);
+                    const { sx: panelRowSx, ...panelRowRest } = panelProps?.row ?? {};
+                    const { sx: panelCellSx, ...panelCellRest } = panelProps?.cell ?? {};
+                    const panelContent = renderDetailPanel(row, table);
+                    if (components.DetailPanelRow) {
+                        return components.DetailPanelRow({ row, table, columnCount, content: panelContent });
+                    }
+                    return (_jsx(TableRow, { className: "koko-detail-row", "data-row-id": row.id, ...panelRowRest, sx: panelRowSx, children: _jsx(TableCell, { colSpan: columnCount, ...panelCellRest, sx: mergeSx({ p: 0, borderBottom: "1px solid", borderColor: "divider" }, panelCellSx), children: _jsx(Box, { sx: { p: 2, backgroundColor: "background.default", borderTop: "1px solid", borderColor: "divider" }, children: panelContent }) }) }));
+                })()] }, key));
+    };
+    /**
+     * 그룹 행.
+     *
+     * `groupRowLayout="columns"`(기본) 는 ERP 의 `ReorderGroupRow`/`RemoveGroupRow` 와 같은 배치다 —
+     * 현재 depth 의 그룹 컬럼 셀에 펼침 아이콘 + 그룹값 + `(n)`, 다른 그룹 컬럼은 빈 셀,
+     * 나머지 컬럼에는 그 컬럼의 집계 칩. 그룹 컬럼이 그려지지 않는 경우(`remove` 모드·숨김)는 첫 데이터
+     * 컬럼 셀이 그룹값을 맡는다. 열 가상화가 켜져 있으면 말단 행과 같은 `PadCell` 규칙으로 채운다.
+     * 배경은 depth 별 단계 색이고 sticky 는 하지 않는다 — 가상화의 위치 계산과 충돌한다.
+     */
+    const renderGroupRow = (item, virtualIndex) => {
+        const node = item.node;
+        const depth = item.depth;
+        const expanded = isGroupExpanded?.(node) ?? false;
+        const toggle = () => onToggleGroup?.(node);
+        const groupColumnId = groupingIds[depth] ?? node.groupKey;
+        const groupColumn = table.getAllFlatColumns().find((column) => column.id === groupColumnId);
+        const groupSet = new Set(groupingIds.length > 0 ? groupingIds : [node.groupKey]);
+        const toggleButton = (_jsx(IconButton, { size: "small", "aria-label": expanded ? labels.ui.collapse : labels.ui.expand, sx: { p: 0.25, color: expanded ? "primary.main" : "action.active" }, 
+            // 행에도 핸들러가 있으므로 버블링을 막지 않으면 두 번 토글된다
+            onClick: (event) => {
+                event.stopPropagation();
+                toggle();
+            }, children: node.isPending
+                ? _jsx(CircularProgress, { size: 14 })
+                : expanded ? _jsx(KeyboardArrowDownIcon, { fontSize: "small" }) : _jsx(KeyboardArrowRightIcon, { fontSize: "small" }) }));
+        const groupValue = (_jsxs(_Fragment, { children: [_jsx(GroupValueText, { children: resolveGroupValue(node, groupColumn) }), _jsxs(Typography, { component: "span", variant: "caption", color: "text.secondary", sx: { whiteSpace: "nowrap" }, children: ["(", node.count, ")"] })] }));
+        const rowProps = {
+            "data-index": virtualIndex,
+            "data-group-depth": depth,
+            ref: virtual?.measureElement,
+            // 화살표만 누를 수 있으면 표적이 너무 작다 — 행 전체를 누를 수 있게 한다
+            onClick: toggle,
+            onKeyDown: (event) => {
+                if (event.key === "Enter" || event.key === " ") {
+                    event.preventDefault();
+                    toggle();
+                }
+            },
+            tabIndex: onToggleGroup ? 0 : -1,
+            onContextMenu: (event) => openRowMenu(event, {
+                table,
+                group: {
+                    node, depth, expanded, toggle,
+                    subLevels: groupingIds.slice(depth + 1),
+                    expandToDepth: onExpandGroupToDepth ? (target) => onExpandGroupToDepth(target, node) : undefined,
+                },
+            }),
+            sx: mergeSx({ backgroundColor: groupRowBgColor(depth) }, groupRowHeight !== undefined && { height: groupRowHeight }, !!onToggleGroup && { cursor: "pointer", "&:hover": { backgroundColor: groupRowHoverColor(depth) } }),
+        };
+        const rowKey = `group-${node.path.map((p) => String(p.value)).join("/")}`;
+        if (components.GroupRow) {
+            return (_jsx(Fragment, { children: components.GroupRow({
+                    node, depth, columns: renderedColumns, aggregates: node.aggregates ?? {}, toggle, expanded, table,
+                    columnCount, groupColumn, groupValue: resolveGroupValue(node, groupColumn), rowProps,
+                }) }, rowKey));
+        }
+        // 그룹값을 맡을 셀 — 그룹 컬럼이 그려지면 그 셀, 아니면(remove·숨김) 첫 데이터 컬럼
+        const dataColumns = renderedColumns.filter((column) => !isDisplayColumnId(column.id));
+        const hostId = dataColumns.some((column) => column.id === groupColumnId)
+            ? groupColumnId
+            : (dataColumns.find((column) => !groupSet.has(column.id)) ?? dataColumns[0])?.id;
+        if (groupRowLayout === "inline" || hostId === undefined) {
+            const aggregates = node.aggregates ?? {};
+            return (_jsx(TableRow, { ...rowProps, children: _jsx(TableCell, { colSpan: columnCount, size: spec.size, sx: { pl: 1 + depth * GROUP_DEPTH_INDENT, py: 0.5 }, children: _jsxs(Stack, { direction: "row", alignItems: "center", spacing: 1, sx: { flexWrap: "wrap", rowGap: 0.25 }, children: [toggleButton, groupValue, Object.entries(aggregates).map(([columnId, perFn]) => Object.entries(perFn).map(([fn, value]) => (_jsxs(Typography, { variant: "caption", color: "text.secondary", children: [columnId, " ", labels.aggregationsShort[fn] ?? fn, " ", formatAggregate(value)] }, `${columnId}-${fn}`))))] }) }) }, rowKey));
+        }
+        const groupCell = (column) => {
+            const width = columnLayout ? column.getSize() : explicitWidth(column, table);
+            const pinned = !!column.getIsPinned();
+            const base = mergeSx({ py: 0.5 }, spec.cellPx !== undefined && { px: spec.cellPx }, width !== undefined && { width, minWidth: width, ...(resizingEnabled || columnLayout ? { maxWidth: width } : {}) }, pinnedSx(column, 1), 
+            // 고정 셀은 sticky 배경이 필요하다 — 행 배경 대신 같은 단계 색을 준다
+            pinned && { backgroundColor: groupRowBgColor(depth) });
+            if (column.id === hostId) {
+                return (_jsx(TableCell, { size: spec.size, "data-column-id": column.id, "data-group-cell": "value", sx: base, children: _jsxs(Stack, { direction: "row", alignItems: "center", spacing: 0.5, sx: { pl: depth * GROUP_DEPTH_INDENT, minWidth: 0 }, children: [toggleButton, groupValue] }) }, column.id));
+            }
+            if (isDisplayColumnId(column.id)) {
+                return _jsx(TableCell, { size: spec.size, "data-column-id": column.id, "data-group-cell": "display", sx: base }, column.id);
+            }
+            if (groupSet.has(column.id)) {
+                return (_jsx(TableCell, { size: spec.size, "data-column-id": column.id, "data-group-cell": "empty", sx: mergeSx(base, { borderBottom: "none" }) }, column.id));
+            }
+            const content = renderAggregateCellContent({
+                column, node, selection: aggregateSelection, onSelect: selectAggregate, chip: components.AggregateChip,
+                registry: aggregationRegistry,
+            });
+            return (_jsx(TableCell, { size: spec.size, "data-column-id": column.id, "data-group-cell": "aggregate", align: "center", sx: base, children: content === null || content === undefined ? null : _jsx(AggregateCellBox, { children: content }) }, column.id));
+        };
+        let cells;
+        if (!columnLayout) {
+            cells = renderedColumns.map(groupCell);
+        }
+        else {
+            const out = [];
+            for (const column of columnLayout.left)
+                out.push(groupCell(column));
+            if (columnLayout.padLeft > 0)
+                out.push(_jsx(PadCell, { width: columnLayout.padLeft }, "pad-left"));
+            for (const column of columnLayout.center)
+                out.push(groupCell(column));
+            if (columnLayout.padRight > 0)
+                out.push(_jsx(PadCell, { width: columnLayout.padRight }, "pad-right"));
+            for (const column of columnLayout.right)
+                out.push(groupCell(column));
+            cells = out;
+        }
+        return _jsx(TableRow, { ...rowProps, children: cells }, rowKey);
+    };
+    /**
+     * 서버 그룹핑에서 하위가 페이지 단위로 온다. 몇 개 중 몇 개를 받았는지
+     * 같이 보여 주지 않으면 사용자가 "이게 전부인가" 를 알 수 없다.
+     */
+    const renderLoadMoreRow = (item, virtualIndex) => (_jsx(TableRow, { "data-index": virtualIndex, ref: virtual?.measureElement, children: _jsx(TableCell, { colSpan: columnCount, size: spec.size, sx: { pl: 1 + item.depth * 2, py: 0.25 }, children: _jsx(Button, { size: "small", disabled: item.isPending, onClick: () => onLoadMore?.(item.path), children: item.isPending ? labels.ui.loading : labels.ui.loadMore(item.loaded, item.total) }) }) }, `more-${item.index}`));
+    const renderGroupItem = (item, virtualIndex) => {
+        if (item.type === "group")
+            return renderGroupRow(item, virtualIndex);
+        if (item.type === "loadMore")
+            return renderLoadMoreRow(item, virtualIndex);
+        const row = rowByOriginal.get(item.row);
+        if (row)
+            return renderLeafRow(row, `leaf-${item.index}`, item.depth, virtualIndex);
+        // 그룹 트리에는 있는데 테이블 행 모델에 없다 — 서버 그룹핑에서
+        // `useServerGrouping().rows` 를 3층에 안 넘긴 경우다.
+        // 조용히 비우면 "행이 없는 그룹" 으로 보여 원인을 찾기 어렵다.
+        return (_jsx(TableRow, { "data-index": virtualIndex, ref: virtual?.measureElement, children: _jsx(TableCell, { colSpan: columnCount, sx: { pl: 1 + item.depth * 2, py: 0.5, color: "warning.main" }, children: labels.ui.missingRows }) }, `missing-${item.index}`));
+    };
+    const renderItem = (index, virtualIndex) => grouped ? renderGroupItem(groupItems[index], virtualIndex) : renderLeafRow(rows[index], rows[index].id, 0, virtualIndex);
+    const itemCount = grouped ? groupItems.length : rows.length;
+    const renderSkeleton = () => {
+        if (components.LoadingSkeleton) {
+            const LoadingSkeleton = components.LoadingSkeleton;
+            return _jsx(LoadingSkeleton, { rows: skeletonRows, columns: renderedColumns, columnCount: columnCount, size: spec.size });
+        }
+        if (skeletonRows <= 0) {
+            return (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columnCount, sx: { py: 6, textAlign: "center", color: "text.secondary" }, children: labels.ui.loading }) }));
+        }
+        return Array.from({ length: skeletonRows }, (_, i) => (_jsx(TableRow, { "data-testid": "skeleton-row", children: renderedColumns.map((column) => (_jsx(TableCell, { size: spec.size, children: _jsx(Skeleton, { variant: "text", animation: "wave" }) }, column.id))) }, `skeleton-${i}`)));
+    };
+    const body = () => {
+        if (status?.isError) {
+            const retry = () => content?.refetch();
+            const ErrorFallback = components.ErrorFallback ?? TableErrorFallback;
+            return (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columnCount, sx: { py: 2 }, children: renderError
+                        ? renderError(status.error, retry)
+                        : (_jsx(ErrorFallback, { compact: true, error: status.error, onRetry: content ? retry : undefined, onResetFilters: onResetFilters })) }) }));
+        }
+        if (status?.isInitialLoading)
+            return renderSkeleton();
+        if (itemCount === 0) {
+            const EmptyState = components.EmptyState;
+            return (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: columnCount, sx: { py: 6, textAlign: "center", color: "text.secondary" }, children: renderEmpty
+                        ? renderEmpty()
+                        : EmptyState
+                            ? _jsx(EmptyState, { message: emptyMessage, table: table, columnCount: columnCount })
+                            : emptyMessage }) }));
+        }
+        if (virtual) {
+            const items = virtual.items;
+            const paddingTop = items.length > 0 ? items[0].start : 0;
+            const paddingBottom = items.length > 0 ? virtual.totalSize - items[items.length - 1].end : 0;
+            return (_jsxs(_Fragment, { children: [paddingTop > 0 && (_jsx(TableRow, { "aria-hidden": true, "data-testid": "virtual-pad-top", children: _jsx(TableCell, { colSpan: columnCount, sx: { p: 0, border: 0, height: paddingTop } }) })), items.map((item) => renderItem(item.index, item.index)), paddingBottom > 0 && (_jsx(TableRow, { "aria-hidden": true, "data-testid": "virtual-pad-bottom", children: _jsx(TableCell, { colSpan: columnCount, sx: { p: 0, border: 0, height: paddingBottom } }) }))] }));
+        }
+        return _jsx(_Fragment, { children: Array.from({ length: itemCount }, (_, index) => renderItem(index)) });
+    };
+    const hasFooter = leafColumns.some((column) => column.columnDef.footer !== undefined);
+    /**
+     * 열 가상화 헤더/푸터 — 단일 헤더 그룹의 header 를 컬럼 id 로 찾아 고정·가운데·패딩 순으로 놓는다.
+     * `HeaderCell` 은 그대로 쓴다(가상화를 몰라도 된다).
+     */
+    const renderVirtualHeaderRow = (headers, renderOne) => {
+        if (!columnLayout)
+            return null;
+        const byColumn = new Map(headers.map((header) => [header.column.id, header]));
+        const one = (columnId) => {
+            const header = byColumn.get(columnId);
+            return header ? renderOne(header) : null;
+        };
+        return (_jsxs(_Fragment, { children: [columnLayout.left.map((column) => one(column.id)), columnLayout.padLeft > 0 && _jsx(PadCell, { component: "th", width: columnLayout.padLeft }, "pad-left"), columnLayout.center.map((column) => one(column.id)), columnLayout.padRight > 0 && _jsx(PadCell, { component: "th", width: columnLayout.padRight }, "pad-right"), columnLayout.right.map((column) => one(column.id))] }));
+    };
+    /** 그룹 컬럼 배치를 헤더·푸터 행에도 적용한다 (가상화가 아닐 때만 — 가상화는 위 함수가 맡는다) */
+    const arrangeHeaders = (headers) => {
+        if (activeGroupedMode === null)
+            return headers;
+        return arrangeGroupedColumns(headers.map((header) => ({ id: header.column.id, getIsPinned: () => header.column.getIsPinned(), header })), groupingIds, activeGroupedMode, declaredRank).map((entry) => entry.header);
+    };
+    const renderFooterCell = (header) => (_jsx(TableCell, { colSpan: header.colSpan, size: spec.size, sx: mergeSx({ fontWeight: 600, color: "text.primary", borderTop: "2px solid", borderColor: "divider", whiteSpace: "nowrap" }, columnLayout && { width: header.column.getSize(), minWidth: header.column.getSize() }, pinnedSx(header.column, 1)), children: header.isPlaceholder ? null : flexRender(header.column.columnDef.footer, header.getContext()) }, header.id));
+    const fixedLayout = resizingEnabled || !!columnLayout;
+    const renderHeaderCell = (header) => (_jsx(HeaderCellComponent, { header: header, sort: sort, table: table, enableColumnMenu: enableColumnMenu, size: spec.size, columnMenuItems: columnMenuItems, grouping: groupingProp, onGroupingChange: onGroupingChange, aggregation: aggregationProp, onAggregationChange: onAggregationChange, onOpenFilter: onOpenFilter, headerCellProps: headerCellProps ? (header, tbl) => headerCellProps(header, tbl ?? table) : undefined, renderHeader: renderHeader }, header.id));
+    return (_jsxs(Box, { sx: { position: "relative" }, children: [status?.isLoading && !status.isInitialLoading && (_jsx(LinearProgress, { sx: { position: "absolute", top: 0, left: 0, right: 0, zIndex: 2 } })), _jsx(TableContainer, { ref: containerRef, sx: { maxHeight, border: "1px solid", borderColor: "divider", borderRadius: 1 }, children: _jsxs(Table, { stickyHeader: stickyHeader, size: spec.size, sx: fixedLayout ? { tableLayout: "fixed", width: table.getTotalSize() } : undefined, children: [columnLayout && (
+                        // 고정 레이아웃에서 열 폭은 첫 행(헤더)이 정한다 — 헤더 셀에 폭이 없는 컬럼(기본 150)도
+                        // 패딩 셀과 합이 맞아야 하므로 colgroup 으로 폭을 못박는다
+                        _jsxs("colgroup", { children: [columnLayout.left.map((column) => _jsx("col", { style: { width: column.getSize() } }, column.id)), columnLayout.padLeft > 0 && _jsx("col", { style: { width: columnLayout.padLeft } }, "pad-left"), columnLayout.center.map((column) => _jsx("col", { style: { width: column.getSize() } }, column.id)), columnLayout.padRight > 0 && _jsx("col", { style: { width: columnLayout.padRight } }, "pad-right"), columnLayout.right.map((column) => _jsx("col", { style: { width: column.getSize() } }, column.id))] })), _jsx(TableHead, { children: table.getHeaderGroups().map((headerGroup) => (_jsx(TableRow, { children: columnLayout
+                                    ? renderVirtualHeaderRow(headerGroup.headers, (header) => renderHeaderCell(header))
+                                    : arrangeHeaders(headerGroup.headers).map((header) => renderHeaderCell(header)) }, headerGroup.id))) }), _jsx(TableBody, { children: body() }), hasFooter && (_jsx(TableFooter, { children: table.getFooterGroups().map((footerGroup) => (_jsx(TableRow, { children: columnLayout
+                                    ? renderVirtualHeaderRow(footerGroup.headers, (header) => renderFooterCell(header))
+                                    : arrangeHeaders(footerGroup.headers).map((header) => renderFooterCell(header)) }, footerGroup.id))) }))] }) }), modalRow && renderEditDialog && renderEditDialog(modalRow, () => setModalRow(null)), _jsx(ContextMenu, { position: rowMenu?.position ?? null, items: rowMenu?.items ?? [], ctx: rowMenu?.ctx ?? { ...createRowMenuCtx({ table }, labels), defaultItems: [] }, onClose: () => setRowMenu(null) })] }));
+}

package/dist/mui/src/content/TableErrorFallback.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+export interface TableErrorFallbackProps {
+    error?: Error | null;
+    /** 같은 조건으로 다시 조회 (`data.refetch`) */
+    onRetry?: () => void;
+    /** 있으면 "필터 초기화" 버튼을 그린다 (`search.reset`) */
+    onResetFilters?: () => void;
+    /** 400 이 아닐 때의 제목. 기본 `labels.ui.loadFailed` */
+    title?: ReactNode;
+    /** 표 본문 안의 행에 들어갈 때 여백을 줄인다 */
+    compact?: boolean;
+}
+/** axios(`response.status`)·fetch 래퍼(`status`) 양쪽에서 HTTP 상태를 읽는다 */
+export declare function errorStatus(error: unknown): number | undefined;
+export declare function isBadRequestError(error: unknown): boolean;
+/**
+ * 조회 실패 UI — 기존 `TableErrorFallback.tsx` 대응.
+ *
+ * 400 이면 "필터를 해석할 수 없습니다"(서버가 컬럼 경로·연산자를 거부한 것) 로 구분하고,
+ * 재시도와 함께 `onResetFilters` 가 있을 때만 "필터 초기화" 를 보여 준다.
+ * ErrorBoundary 를 쓰지 않으므로 "테이블 재시작" 은 없다 — 에러는 `TableData.error` 로
+ * 내려와 제자리에서 그려지고, 재조회하면 그대로 복구된다.
+ */
+export declare function TableErrorFallback({ error, onRetry, onResetFilters, title, compact, }: TableErrorFallbackProps): import("react").JSX.Element;

package/dist/mui/src/content/TableErrorFallback.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Box, Button, Stack, Typography } from "@mui/material";
+import ErrorOutlineIcon from "@mui/icons-material/ErrorOutline";
+import RefreshIcon from "@mui/icons-material/Refresh";
+import { useKokoTableConfig } from "../provider/KokoTableProvider";
+/** axios(`response.status`)·fetch 래퍼(`status`) 양쪽에서 HTTP 상태를 읽는다 */
+export function errorStatus(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const e = error;
+    const status = e.status ?? e.response?.status;
+    return typeof status === "number" ? status : undefined;
+}
+export function isBadRequestError(error) {
+    return errorStatus(error) === 400;
+}
+/**
+ * 조회 실패 UI — 기존 `TableErrorFallback.tsx` 대응.
+ *
+ * 400 이면 "필터를 해석할 수 없습니다"(서버가 컬럼 경로·연산자를 거부한 것) 로 구분하고,
+ * 재시도와 함께 `onResetFilters` 가 있을 때만 "필터 초기화" 를 보여 준다.
+ * ErrorBoundary 를 쓰지 않으므로 "테이블 재시작" 은 없다 — 에러는 `TableData.error` 로
+ * 내려와 제자리에서 그려지고, 재조회하면 그대로 복구된다.
+ */
+export function TableErrorFallback({ error, onRetry, onResetFilters, title, compact = false, }) {
+    const { labels } = useKokoTableConfig();
+    const badRequest = isBadRequestError(error);
+    return (_jsxs(Box, { role: "alert", sx: { p: compact ? 1 : 3, textAlign: "center" }, children: [_jsxs(Alert, { severity: "error", icon: _jsx(ErrorOutlineIcon, {}), sx: { mb: compact ? 1 : 2, textAlign: "left" }, children: [_jsx(Typography, { variant: compact ? "subtitle2" : "h6", sx: { mb: 0.5 }, children: badRequest ? labels.ui.badRequest : (title ?? labels.ui.loadFailed) }), error?.message && (_jsx(Typography, { variant: "body2", color: "text.secondary", children: error.message }))] }), _jsxs(Stack, { direction: "row", spacing: 1.5, justifyContent: "center", children: [onRetry && (_jsx(Button, { size: "small", variant: "contained", startIcon: _jsx(RefreshIcon, {}), onClick: onRetry, children: labels.ui.retry })), onResetFilters && (_jsx(Button, { size: "small", variant: "outlined", onClick: onResetFilters, children: labels.ui.resetFilters }))] })] }));
+}

package/dist/mui/src/content/cellError.d.ts

@@ -0,0 +1,13 @@
+import type { SxProps, Theme } from "@mui/material";
+import type { FieldErrors } from "../../../core/src/index";
+export interface CellErrorInfo {
+    hasError: boolean;
+    message?: string;
+}
+/**
+ * `fieldErrors[rowIndex][columnId]` 를 읽는다. react-hook-form `FieldErrors` 와 같은 모양이라
+ * 폼 검증 결과를 그대로 넘길 수 있다. `rowIndex` 는 TanStack `row.index`(페이지 내 순번)다.
+ */
+export declare function getCellError(fieldErrors: FieldErrors, rowIndex: number, columnId: string): CellErrorInfo;
+/** 에러 셀 스타일 — 빨간 배경 + 셀 안쪽 outline (기존 `CellError.tsx` 와 같다) */
+export declare const cellErrorSx: SxProps<Theme>;

package/dist/mui/src/content/cellError.js

@@ -0,0 +1,20 @@
+/**
+ * `fieldErrors[rowIndex][columnId]` 를 읽는다. react-hook-form `FieldErrors` 와 같은 모양이라
+ * 폼 검증 결과를 그대로 넘길 수 있다. `rowIndex` 는 TanStack `row.index`(페이지 내 순번)다.
+ */
+export function getCellError(fieldErrors, rowIndex, columnId) {
+    const cellError = fieldErrors?.[rowIndex]?.[columnId];
+    if (!cellError)
+        return { hasError: false };
+    const message = typeof cellError === "object" && "message" in cellError
+        ? cellError.message
+        : undefined;
+    return { hasError: true, message };
+}
+/** 에러 셀 스타일 — 빨간 배경 + 셀 안쪽 outline (기존 `CellError.tsx` 와 같다) */
+export const cellErrorSx = {
+    backgroundColor: "rgba(211, 47, 47, 0.08)",
+    outline: "1px solid",
+    outlineColor: "error.main",
+    outlineOffset: "-2px",
+};