kokotable 0.95.0

package/dist/mui/src/grouping/AggregationChips.d.ts

@@ -0,0 +1,49 @@
+import type { RowData } from "@tanstack/react-table";
+import type { AggregationDef, AggregationId, AggregationSpec, Registry, TableColumnDefs } from "../../../core/src/index";
+export interface AggregationChipsProps<T extends RowData> {
+    /** 현재 집계 명세 `{ 컬럼: [함수, …] }` */
+    value: AggregationSpec;
+    onChange: (value: AggregationSpec) => void;
+    /** 집계 후보를 고를 컬럼 정의 — `meta.enableAgg` 이거나 숫자/enum/boolean 컬럼 */
+    columns: TableColumnDefs<T>;
+    /**
+     * 서버가 계산할 수 있는 함수만 보인다 (정의의 `server: true`).
+     * 서버 그룹핑 화면에서 켠다 — median/stddev 를 골라 보내면 서버가 400 을 준다.
+     */
+    serverOnly?: boolean;
+    /** 특정 컬럼만 보이게 좁힌다 */
+    columnIds?: string[];
+    size?: "small" | "medium";
+    /** 집계 레지스트리 — 미지정 시 Provider(`useAggregations()`) */
+    registry?: Registry<AggregationDef>;
+}
+interface AggregatableColumn {
+    id: string;
+    label: string;
+    keys: AggregationId[];
+}
+/**
+ * 집계를 걸 수 있는 컬럼과 그 컬럼에 허용되는 함수 목록.
+ *
+ * 함수 후보는 레지스트리 정의의 `applies(dataType)` 로 정한다 (내장: 숫자 → sum·avg·median·min·max·stddev·고유·개수·점유율,
+ * boolean → 고유·개수·점유율, 나머지 → 고유·개수·점유율·최빈값). 사용자 집계(`p90` 등)도 `applies` 가 참이면 뜬다.
+ * `enableAgg` 가 꺼져 있어도 숫자/enum/boolean 은 후보에 올린다 — 칩은 "켤 수 있는 것"
+ * 을 보여 주는 UI 라서, 선언에 없는 컬럼을 사용자가 즉석에서 집계할 수 있어야 한다.
+ */
+export declare function aggregatableColumns<T extends RowData>(columns: TableColumnDefs<T>, options?: {
+    serverOnly?: boolean;
+    columnIds?: string[];
+    registry?: Registry<AggregationDef>;
+}): AggregatableColumn[];
+/** 명세에서 함수 하나를 켜거나 끈다. 컬럼의 함수가 모두 꺼지면 키 자체를 지운다 */
+export declare function toggleAggregation(spec: AggregationSpec, columnId: string, fn: AggregationId): AggregationSpec;
+/**
+ * 집계 함수 선택 칩 — 컬럼별로 어떤 집계를 그룹 헤더에 띄울지 토글한다.
+ *
+ * 결과는 `AggregationSpec` 그대로라 `useGrouping({ aggregation })` 에 넣으면
+ * 클라이언트 그룹 헤더가 바뀌고, `search.patchParams({ aggregation })` 에 넣으면
+ * 서버 요청의 `aggregation` 이 바뀐다. 두 경로가 같은 값을 쓰므로 화면이 모드를
+ * 바꿔도 이 컴포넌트는 그대로다.
+ */
+export declare function AggregationChips<T extends RowData>({ value, onChange, columns, serverOnly, columnIds, size, registry: givenRegistry, }: AggregationChipsProps<T>): import("react").JSX.Element;
+export {};

package/dist/mui/src/grouping/AggregationChips.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Chip, Stack, Tooltip, Typography } from "@mui/material";
+import { aggregations as defaultAggregations, aggregationKeysFor, aggregationLabel, columnKey, isServerAggregation, } from "../../../core/src/index";
+import { useKokoTableConfig } from "../provider/KokoTableProvider";
+import { useAggregations } from "./AggregateChip";
+/**
+ * 집계를 걸 수 있는 컬럼과 그 컬럼에 허용되는 함수 목록.
+ *
+ * 함수 후보는 레지스트리 정의의 `applies(dataType)` 로 정한다 (내장: 숫자 → sum·avg·median·min·max·stddev·고유·개수·점유율,
+ * boolean → 고유·개수·점유율, 나머지 → 고유·개수·점유율·최빈값). 사용자 집계(`p90` 등)도 `applies` 가 참이면 뜬다.
+ * `enableAgg` 가 꺼져 있어도 숫자/enum/boolean 은 후보에 올린다 — 칩은 "켤 수 있는 것"
+ * 을 보여 주는 UI 라서, 선언에 없는 컬럼을 사용자가 즉석에서 집계할 수 있어야 한다.
+ */
+export function aggregatableColumns(columns, options = {}) {
+    const registry = options.registry ?? defaultAggregations;
+    const list = [];
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        if (options.columnIds && !options.columnIds.includes(id))
+            continue;
+        const meta = column.meta;
+        if (meta?.forceHidden)
+            continue;
+        // enableAgg: false 는 "집계 대상 아님" 명시 — 참조번호(ColumnIsIDX/SpecificNumber)처럼
+        // 숫자지만 합계·평균이 뜻이 없는 컬럼이 여기 든다
+        if (meta?.enableAgg === false)
+            continue;
+        const dataType = meta?.dataType;
+        const typed = dataType === "number" || dataType === "enum" || dataType === "select" || dataType === "boolean";
+        if (!meta?.enableAgg && !typed)
+            continue;
+        const keys = aggregationKeysFor(dataType, registry, { serverOnly: options.serverOnly });
+        if (keys.length === 0)
+            continue;
+        const header = column.filterLabel ?? column.header;
+        list.push({ id, label: typeof header === "string" ? header : id, keys });
+    }
+    return list;
+}
+/** 명세에서 함수 하나를 켜거나 끈다. 컬럼의 함수가 모두 꺼지면 키 자체를 지운다 */
+export function toggleAggregation(spec, columnId, fn) {
+    const current = spec[columnId] ?? [];
+    const next = current.includes(fn) ? current.filter((key) => key !== fn) : [...current, fn];
+    const result = { ...spec };
+    if (next.length === 0)
+        delete result[columnId];
+    else
+        result[columnId] = next;
+    return result;
+}
+/**
+ * 집계 함수 선택 칩 — 컬럼별로 어떤 집계를 그룹 헤더에 띄울지 토글한다.
+ *
+ * 결과는 `AggregationSpec` 그대로라 `useGrouping({ aggregation })` 에 넣으면
+ * 클라이언트 그룹 헤더가 바뀌고, `search.patchParams({ aggregation })` 에 넣으면
+ * 서버 요청의 `aggregation` 이 바뀐다. 두 경로가 같은 값을 쓰므로 화면이 모드를
+ * 바꿔도 이 컴포넌트는 그대로다.
+ */
+export function AggregationChips({ value, onChange, columns, serverOnly = false, columnIds, size = "small", registry: givenRegistry, }) {
+    const { labels } = useKokoTableConfig();
+    const provided = useAggregations();
+    const registry = givenRegistry ?? provided;
+    const aggLabels = labels.aggregations;
+    const labelOf = (fn) => aggLabels[fn] ?? aggregationLabel(fn, registry);
+    const targets = aggregatableColumns(columns, { serverOnly, columnIds, registry });
+    if (targets.length === 0) {
+        return (_jsx(Typography, { variant: "body2", color: "text.disabled", children: "\uC9D1\uACC4\uD560 \uC218 \uC788\uB294 \uCEEC\uB7FC\uC774 \uC5C6\uC2B5\uB2C8\uB2E4" }));
+    }
+    return (_jsx(Stack, { spacing: 0.5, role: "group", "aria-label": "\uC9D1\uACC4 \uD568\uC218", children: targets.map((target) => {
+            const selected = value[target.id] ?? [];
+            return (_jsxs(Stack, { direction: "row", alignItems: "center", sx: { flexWrap: "wrap", gap: 0.5 }, children: [_jsx(Typography, { variant: "body2", sx: { minWidth: 64, fontWeight: 600 }, children: target.label }), target.keys.map((fn) => {
+                        const on = selected.includes(fn);
+                        const serverCannot = !isServerAggregation(fn, registry);
+                        const fnLabel = labelOf(fn);
+                        return (_jsx(Tooltip, { title: serverCannot ? `${fnLabel} — 클라이언트 전용 (서버 집계 없음)` : fnLabel, enterDelay: 500, children: _jsx(Chip, { size: size, label: fnLabel, color: on ? "primary" : "default", variant: on ? "filled" : "outlined", "aria-pressed": on, "aria-label": `${target.label} ${fnLabel}`, onClick: () => onChange(toggleAggregation(value, target.id, fn)), sx: serverCannot ? { borderStyle: "dashed" } : undefined }) }, fn));
+                    })] }, target.id));
+        }) }));
+}

package/dist/mui/src/grouping/AggregationSettingsButton.d.ts

@@ -0,0 +1,14 @@
+import type { RowData } from "@tanstack/react-table";
+import { type AggregationChipsProps } from "./AggregationChips";
+export interface AggregationSettingsButtonProps<T extends RowData> extends AggregationChipsProps<T> {
+    tooltip?: string;
+    size?: "small" | "medium";
+}
+/**
+ * 집계 함수 선택을 **상세 설정** 뒤로 숨긴다.
+ *
+ * 초기 집계는 컬럼 정의(`setAgg`)에서 파생되므로 보통 사용자가 만질 일이 없다. 그래서
+ * 칩 묶음을 화면에 늘어놓지 않고 톱니 버튼 하나만 두고, 누르면 팝오버에 `AggregationChips` 를 연다.
+ * 그룹 행의 집계 칩 클릭(함수 전환)·헤더 메뉴 "집계" 항목과 같은 상태를 바꾼다.
+ */
+export declare function AggregationSettingsButton<T extends RowData>({ tooltip, size, ...chips }: AggregationSettingsButtonProps<T>): import("react").JSX.Element;

package/dist/mui/src/grouping/AggregationSettingsButton.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, IconButton, Popover, Tooltip, Typography } from "@mui/material";
+import TuneIcon from "@mui/icons-material/Tune";
+import { AggregationChips } from "./AggregationChips";
+import { useKokoTableConfig } from "../provider/KokoTableProvider";
+/**
+ * 집계 함수 선택을 **상세 설정** 뒤로 숨긴다.
+ *
+ * 초기 집계는 컬럼 정의(`setAgg`)에서 파생되므로 보통 사용자가 만질 일이 없다. 그래서
+ * 칩 묶음을 화면에 늘어놓지 않고 톱니 버튼 하나만 두고, 누르면 팝오버에 `AggregationChips` 를 연다.
+ * 그룹 행의 집계 칩 클릭(함수 전환)·헤더 메뉴 "집계" 항목과 같은 상태를 바꾼다.
+ */
+export function AggregationSettingsButton({ tooltip, size = "small", ...chips }) {
+    const { labels } = useKokoTableConfig();
+    const [anchor, setAnchor] = useState(null);
+    const title = tooltip ?? labels.ui.aggregationSettings;
+    return (_jsxs(_Fragment, { children: [_jsx(Tooltip, { title: title, children: _jsx(IconButton, { size: size, "aria-label": title, onClick: (e) => setAnchor(e.currentTarget), sx: { color: "text.secondary" }, children: _jsx(TuneIcon, { fontSize: "small" }) }) }), _jsx(Popover, { open: !!anchor, anchorEl: anchor, onClose: () => setAnchor(null), anchorOrigin: { vertical: "bottom", horizontal: "right" }, transformOrigin: { vertical: "top", horizontal: "right" }, children: _jsxs(Box, { sx: { p: 1.5, maxWidth: 520 }, children: [_jsx(Typography, { variant: "caption", color: "text.secondary", sx: { display: "block", mb: 1 }, children: title }), _jsx(AggregationChips, { ...chips })] }) })] }));
+}

package/dist/mui/src/grouping/GroupingBar.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from "react";
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../../../core/src/index";
+import type { GroupedColumnMode } from "../content/TableContent";
+/**
+ * 헤더 셀·그룹 칩이 드래그할 때 `dataTransfer` 에 싣는 MIME 키.
+ *
+ * `HeaderCell` 의 `draggableGroup` 이 같은 키로 컬럼 id 를 싣는다 — 바는 이 키만
+ * 보고 "그룹으로 추가할 컬럼" 인지 판단하므로, 다른 드래그(텍스트·파일)는 무시된다.
+ */
+export declare const GROUP_DRAG_COLUMN_TYPE = "text/koko-column";
+/** 바 안의 칩을 끌 때 함께 싣는 출발 인덱스 — 있으면 "순서 변경" 이다 */
+export declare const GROUP_DRAG_INDEX_TYPE = "text/koko-group-index";
+/** 배치 크기 선택지 — 서버 그룹핑 `useServerGrouping({ batchSize })` */
+export declare const GROUP_BATCH_SIZE_OPTIONS: readonly [20, 50, 100, 150, 200, 250, 500];
+/** 그룹 불가 컬럼을 놓았을 때 문구 */
+export declare const GROUP_REJECTED_MESSAGE = "\uC774 \uC5F4\uC740 \uADF8\uB8F9\uD551\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4";
+export interface GroupingBarProps<T extends RowData> {
+    /** 상위 → 하위 순서의 그룹 컬럼 */
+    grouping: string[];
+    onChange: (grouping: string[]) => void;
+    /** 그룹 후보 컬럼 */
+    columns: TableColumnDefs<T>;
+    /** 그룹핑이 꺼져 있을 때 힌트 문구 */
+    placeholder?: string;
+    /**
+     * 드래그 조작. 기본 true.
+     * - 칩을 끌어 순서 변경, 바 밖에 놓으면 해제
+     * - `HeaderCell draggableGroup` 헤더를 끌어와 놓으면 추가
+     * 키보드(좌우 버튼·x)는 이 값과 무관하게 항상 동작한다.
+     */
+    enableDrag?: boolean;
+    /** 그룹 컬럼 배치 — `onGroupedColumnModeChange` 와 함께 주면 Remove/Reorder 토글이 생긴다 */
+    groupedColumnMode?: GroupedColumnMode;
+    onGroupedColumnModeChange?: (mode: GroupedColumnMode) => void;
+    /** 서버 그룹핑 배치 크기 — `onBatchSizeChange` 와 함께 주면 선택 상자가 생긴다 */
+    batchSize?: number;
+    onBatchSizeChange?: (size: number) => void;
+    /** 옵션 슬롯 맨 오른쪽에 놓을 것 */
+    extra?: ReactNode;
+}
+/**
+ * 그룹 기준 바 — 그룹 컬럼을 추가·제거하고 **순서를 바꾼다.**
+ *
+ * 순서가 곧 계층이다. `["channel", "region"]` 은 채널 아래 지역이고, 뒤집으면
+ * 완전히 다른 트리가 된다. 그래서 제거보다 **순서 이동이 더 중요한 조작**이라
+ * 칩마다 좌우 이동 버튼을 붙였고, 마우스로는 칩을 끌어 옮길 수 있다.
+ *
+ * 드래그는 HTML5 DnD 만 쓴다(라이브러리 없음). 세 가지 조작이 붙는다:
+ * 1. 칩 → 바 안 다른 틈: 순서 변경
+ * 2. 헤더(`HeaderCell draggableGroup`) → 바: 그룹 추가 (`text/koko-column`)
+ * 3. 칩 → 바 밖: 해제 (`dragend` 의 `dropEffect === "none"` 판정)
+ * 키보드·터치는 좌우 버튼과 x, 추가 메뉴로 같은 일을 할 수 있다.
+ *
+ * 바 배경이 상태를 말한다 — 드래그 중 놓을 수 있으면 primary.100 + 굵은 하단선, 놓을 수 없으면
+ * error.light + 안내 문구, 그룹이 있으면 primary.50, 없으면 grey.50. 오른쪽 옵션 슬롯에는
+ * `groupedColumnMode` 토글·`batchSize` 선택·`extra` 가 놓인다.
+ */
+export declare function GroupingBar<T extends RowData>({ grouping, onChange, columns, placeholder, enableDrag, groupedColumnMode, onGroupedColumnModeChange, batchSize, onBatchSizeChange, extra, }: GroupingBarProps<T>): import("react").JSX.Element;

package/dist/mui/src/grouping/GroupingBar.js

@@ -0,0 +1,267 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useRef, useState } from "react";
+import { Autocomplete, Box, Chip, IconButton, ListItemText, Menu, MenuItem, Stack, TextField, ToggleButton, ToggleButtonGroup, Tooltip, Typography, } from "@mui/material";
+import AddIcon from "@mui/icons-material/Add";
+import ArrowBackIcon from "@mui/icons-material/ArrowBack";
+import ArrowForwardIcon from "@mui/icons-material/ArrowForward";
+import CloseIcon from "@mui/icons-material/Close";
+import DragIndicatorIcon from "@mui/icons-material/DragIndicator";
+import LayersIcon from "@mui/icons-material/Layers";
+import { columnKey } from "../../../core/src/index";
+/**
+ * 헤더 셀·그룹 칩이 드래그할 때 `dataTransfer` 에 싣는 MIME 키.
+ *
+ * `HeaderCell` 의 `draggableGroup` 이 같은 키로 컬럼 id 를 싣는다 — 바는 이 키만
+ * 보고 "그룹으로 추가할 컬럼" 인지 판단하므로, 다른 드래그(텍스트·파일)는 무시된다.
+ */
+export const GROUP_DRAG_COLUMN_TYPE = "text/koko-column";
+/** 바 안의 칩을 끌 때 함께 싣는 출발 인덱스 — 있으면 "순서 변경" 이다 */
+export const GROUP_DRAG_INDEX_TYPE = "text/koko-group-index";
+/** 배치 크기 선택지 — 서버 그룹핑 `useServerGrouping({ batchSize })` */
+export const GROUP_BATCH_SIZE_OPTIONS = [20, 50, 100, 150, 200, 250, 500];
+/** 그룹 불가 컬럼을 놓았을 때 문구 */
+export const GROUP_REJECTED_MESSAGE = "이 열은 그룹핑할 수 없습니다";
+function candidates(columns) {
+    const list = [];
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        if (column.enableGrouping === false)
+            continue;
+        if (column.meta?.forceHidden)
+            continue;
+        // 숫자·날짜는 값이 거의 다 달라 그룹이 행 수만큼 생긴다 — 후보에서 뺀다.
+        // 굳이 묶고 싶으면 변환을 건 파생 컬럼을 만들어 쓰는 쪽이 맞다.
+        const dataType = column.meta?.dataType;
+        if (dataType === "number" || dataType === "date" || dataType === "datetime")
+            continue;
+        const header = column.filterLabel ?? column.header;
+        list.push({ id, label: typeof header === "string" ? header : id });
+    }
+    return list;
+}
+const IDLE = { fromIndex: null, columnId: null, dropIndex: null, rejected: false, over: false };
+/**
+ * 드롭 위치 표시 세로선.
+ * - `active` — 여기에 놓인다 (primary)
+ * - `beside` — 끌고 있는 칩의 바로 옆 틈 (놓아도 이동이 아님) — 점선
+ * - 그 외 드래그 중이면 옅은 선, 아니면 투명
+ */
+function DropLine({ active, beside, dragging }) {
+    return (_jsx(Box, { "aria-hidden": true, "data-testid": "group-drop-line", "data-active": active || undefined, sx: {
+            width: 3, height: 28, borderRadius: 1, flexShrink: 0, mx: 0.25, boxSizing: "border-box",
+            bgcolor: active ? "primary.main" : beside || !dragging ? "transparent" : "divider",
+            borderLeft: beside ? "2px dashed" : undefined,
+            borderColor: "divider",
+            transition: "background-color 0.15s, border-color 0.15s",
+        } }));
+}
+/**
+ * 그룹 기준 바 — 그룹 컬럼을 추가·제거하고 **순서를 바꾼다.**
+ *
+ * 순서가 곧 계층이다. `["channel", "region"]` 은 채널 아래 지역이고, 뒤집으면
+ * 완전히 다른 트리가 된다. 그래서 제거보다 **순서 이동이 더 중요한 조작**이라
+ * 칩마다 좌우 이동 버튼을 붙였고, 마우스로는 칩을 끌어 옮길 수 있다.
+ *
+ * 드래그는 HTML5 DnD 만 쓴다(라이브러리 없음). 세 가지 조작이 붙는다:
+ * 1. 칩 → 바 안 다른 틈: 순서 변경
+ * 2. 헤더(`HeaderCell draggableGroup`) → 바: 그룹 추가 (`text/koko-column`)
+ * 3. 칩 → 바 밖: 해제 (`dragend` 의 `dropEffect === "none"` 판정)
+ * 키보드·터치는 좌우 버튼과 x, 추가 메뉴로 같은 일을 할 수 있다.
+ *
+ * 바 배경이 상태를 말한다 — 드래그 중 놓을 수 있으면 primary.100 + 굵은 하단선, 놓을 수 없으면
+ * error.light + 안내 문구, 그룹이 있으면 primary.50, 없으면 grey.50. 오른쪽 옵션 슬롯에는
+ * `groupedColumnMode` 토글·`batchSize` 선택·`extra` 가 놓인다.
+ */
+export function GroupingBar({ grouping, onChange, columns, placeholder = "열을 드래그하여 그룹핑", enableDrag = true, groupedColumnMode, onGroupedColumnModeChange, batchSize, onBatchSizeChange, extra, }) {
+    const [anchorEl, setAnchorEl] = useState(null);
+    const [drag, setDrag] = useState(IDLE);
+    // 바 안에서 drop 이 실제로 처리됐는지 — dragend 에서 "밖에 놓았다" 를 판정할 때 본다
+    const droppedInsideRef = useRef(false);
+    const chipRefs = useRef(new Map());
+    const barRef = useRef(null);
+    const all = candidates(columns);
+    const labelOf = (id) => all.find((c) => c.id === id)?.label ?? id;
+    const remaining = all.filter((c) => !grouping.includes(c.id));
+    const isCandidate = (id) => all.some((c) => c.id === id);
+    const isGrouped = grouping.length > 0;
+    const move = (index, delta) => {
+        const target = index + delta;
+        if (target < 0 || target >= grouping.length)
+            return;
+        onChange(reorder(grouping, index, target));
+    };
+    // ── 드래그 ──
+    /** 커서 x → 칩 중앙 기준으로 놓일 틈 인덱스 */
+    const dropIndexFromX = (clientX) => {
+        for (let i = 0; i < grouping.length; i += 1) {
+            const el = chipRefs.current.get(i);
+            if (!el)
+                continue;
+            const rect = el.getBoundingClientRect();
+            if (clientX < rect.left + rect.width / 2)
+                return i;
+        }
+        return grouping.length;
+    };
+    const handleChipDragStart = (event, index) => {
+        const id = grouping[index];
+        event.dataTransfer.effectAllowed = "move";
+        event.dataTransfer.setData(GROUP_DRAG_INDEX_TYPE, String(index));
+        event.dataTransfer.setData(GROUP_DRAG_COLUMN_TYPE, id);
+        droppedInsideRef.current = false;
+        setDrag({ fromIndex: index, columnId: id, dropIndex: null, rejected: false, over: true });
+    };
+    const handleChipDragEnd = (event, index) => {
+        // 바 밖(유효한 드롭 대상이 없는 곳)에 놓으면 브라우저가 dropEffect 를 "none" 으로 준다.
+        // 그 경우 그룹에서 뺀다 — 칩을 "끌어내는" 동작이 곧 해제다.
+        // 단, Escape 취소도 dropEffect 가 "none" 이므로 좌표로 구분한다: 취소 시 브라우저는
+        // (0, 0) 을 주고, 바 rect 안에서 끝난 것도 "밖에 놓은" 게 아니다.
+        const cancelled = event.clientX === 0 && event.clientY === 0;
+        const barRect = barRef.current?.getBoundingClientRect();
+        const insideBar = !!barRect
+            && event.clientX >= barRect.left && event.clientX <= barRect.right
+            && event.clientY >= barRect.top && event.clientY <= barRect.bottom;
+        const outside = !droppedInsideRef.current
+            && event.dataTransfer.dropEffect === "none"
+            && !cancelled && !insideBar;
+        if (outside) {
+            const id = grouping[index];
+            if (id)
+                onChange(grouping.filter((key) => key !== id));
+        }
+        droppedInsideRef.current = false;
+        setDrag(IDLE);
+    };
+    const handleBarDragOver = (event) => {
+        if (!enableDrag)
+            return;
+        const types = Array.from(event.dataTransfer.types ?? []);
+        const isChip = types.includes(GROUP_DRAG_INDEX_TYPE);
+        const isColumn = types.includes(GROUP_DRAG_COLUMN_TYPE);
+        if (!isChip && !isColumn)
+            return; // 텍스트·파일 등 무관한 드래그는 기본 동작
+        event.preventDefault();
+        event.dataTransfer.dropEffect = isChip ? "move" : "copy";
+        const dropIndex = dropIndexFromX(event.clientX);
+        setDrag((prev) => {
+            const fromIndex = prev.fromIndex;
+            // 자기 자리(또는 바로 옆 틈)에 놓는 건 이동이 아니다 — 표시하지 않는다
+            const noop = fromIndex !== null && (dropIndex === fromIndex || dropIndex === fromIndex + 1);
+            const next = {
+                fromIndex, columnId: prev.columnId,
+                dropIndex: noop ? null : dropIndex,
+                rejected: false,
+                over: true,
+            };
+            return prev.dropIndex === next.dropIndex && prev.rejected === next.rejected
+                && prev.fromIndex === next.fromIndex && prev.over
+                ? prev
+                : next;
+        });
+    };
+    const handleBarDragLeave = (event) => {
+        const related = event.relatedTarget;
+        if (related && event.currentTarget.contains(related))
+            return;
+        setDrag((prev) => {
+            // 칩을 끌고 바 밖으로 나가는 중이면 fromIndex 는 남긴다 (dragend 가 정리)
+            if (prev.dropIndex === null && !prev.rejected && !prev.over)
+                return prev;
+            return { ...prev, dropIndex: null, rejected: false, over: prev.fromIndex !== null };
+        });
+    };
+    const handleBarDrop = (event) => {
+        if (!enableDrag)
+            return;
+        const rawIndex = event.dataTransfer.getData(GROUP_DRAG_INDEX_TYPE);
+        const columnId = event.dataTransfer.getData(GROUP_DRAG_COLUMN_TYPE);
+        if (!rawIndex && !columnId)
+            return;
+        event.preventDefault();
+        droppedInsideRef.current = true;
+        const dropIndex = dropIndexFromX(event.clientX);
+        if (rawIndex !== "") {
+            // 칩 순서 변경
+            const from = Number(rawIndex);
+            if (Number.isInteger(from) && from >= 0 && from < grouping.length) {
+                const insertAt = dropIndex > from ? dropIndex - 1 : dropIndex;
+                if (insertAt !== from)
+                    onChange(reorder(grouping, from, insertAt));
+            }
+        }
+        else if (columnId) {
+            // 헤더에서 끌어온 컬럼 — 후보여야 하고, 이미 있으면 그 자리로 옮긴다
+            if (!isCandidate(columnId)) {
+                setDrag({ ...IDLE, rejected: true });
+                return;
+            }
+            const existing = grouping.indexOf(columnId);
+            if (existing >= 0) {
+                const insertAt = dropIndex > existing ? dropIndex - 1 : dropIndex;
+                if (insertAt !== existing)
+                    onChange(reorder(grouping, existing, insertAt));
+            }
+            else {
+                const next = [...grouping];
+                next.splice(dropIndex, 0, columnId);
+                onChange(next);
+            }
+        }
+        setDrag(IDLE);
+    };
+    const dragging = drag.fromIndex !== null || drag.over;
+    const rejected = drag.rejected;
+    const reordering = drag.fromIndex !== null;
+    const beside = (gap) => reordering && (drag.fromIndex === gap || drag.fromIndex === gap - 1);
+    const hint = rejected
+        ? GROUP_REJECTED_MESSAGE
+        : dragging
+            ? (reordering ? "놓아서 순서 변경 · 바 밖에 놓으면 해제" : "여기에 놓아 그룹 추가")
+            : !isGrouped ? placeholder : "";
+    const bgcolor = rejected ? "error.light" : dragging ? "primary.100" : isGrouped ? "primary.50" : "grey.50";
+    const borderColor = rejected ? "error.main" : dragging ? "primary.main" : "divider";
+    return (_jsxs(Stack, { direction: "row", alignItems: "center", role: "group", "aria-label": "\uADF8\uB8F9 \uAE30\uC900", "data-testid": "grouping-bar", "data-drag-state": rejected ? "rejected" : dragging ? "dragging" : isGrouped ? "grouped" : "empty", ref: barRef, onDragOver: handleBarDragOver, onDragLeave: handleBarDragLeave, onDrop: handleBarDrop, sx: {
+            flexWrap: "wrap", gap: 0.5, minHeight: "3rem", px: 1, borderRadius: 1,
+            bgcolor,
+            borderBottom: dragging || rejected ? 3 : 1,
+            borderColor,
+            cursor: rejected ? "not-allowed" : undefined,
+            transition: "background-color 0.2s, border-color 0.2s",
+        }, children: [_jsx(LayersIcon, { fontSize: "small", sx: { color: isGrouped ? "primary.main" : "text.disabled", flexShrink: 0 } }), grouping.map((id, index) => (_jsxs(Fragment, { children: [_jsx(DropLine, { active: drag.dropIndex === index, beside: beside(index), dragging: dragging }), _jsxs(Stack, { direction: "row", alignItems: "center", spacing: 0, children: [_jsx(Chip, { ref: (el) => {
+                                    if (el)
+                                        chipRefs.current.set(index, el);
+                                    else
+                                        chipRefs.current.delete(index);
+                                }, size: "small", color: "primary", variant: "outlined", icon: enableDrag ? _jsx(DragIndicatorIcon, { sx: { fontSize: 16, color: "grey.500", cursor: "grab" } }) : undefined, label: `${index + 1}. ${labelOf(id)}`, onDelete: () => onChange(grouping.filter((key) => key !== id)), deleteIcon: _jsx(CloseIcon, { sx: { fontSize: 16 } }), draggable: enableDrag, "data-group-index": index, onDragStart: enableDrag ? (event) => handleChipDragStart(event, index) : undefined, onDragEnd: enableDrag ? (event) => handleChipDragEnd(event, index) : undefined, sx: {
+                                    height: 32, bgcolor: "background.paper", flexShrink: 0,
+                                    opacity: drag.fromIndex === index ? 0.5 : 1,
+                                    "& .MuiChip-icon": { ml: 0.5, mr: -0.5 },
+                                    ...(enableDrag ? { cursor: "grab", "&:active": { cursor: "grabbing" } } : {}),
+                                } }), _jsx(Tooltip, { title: "\uC704\uB85C (\uC0C1\uC704 \uACC4\uCE35)", children: _jsx("span", { children: _jsx(IconButton, { size: "small", "aria-label": `${labelOf(id)} 상위로`, disabled: index === 0, onClick: () => move(index, -1), children: _jsx(ArrowBackIcon, { sx: { fontSize: 14 } }) }) }) }), _jsx(Tooltip, { title: "\uC544\uB798\uB85C (\uD558\uC704 \uACC4\uCE35)", children: _jsx("span", { children: _jsx(IconButton, { size: "small", "aria-label": `${labelOf(id)} 하위로`, disabled: index === grouping.length - 1, onClick: () => move(index, 1), children: _jsx(ArrowForwardIcon, { sx: { fontSize: 14 } }) }) }) })] })] }, id))), _jsx(DropLine, { active: drag.dropIndex === grouping.length, beside: beside(grouping.length), dragging: dragging }), _jsx(Tooltip, { title: remaining.length === 0 ? "추가할 컬럼이 없습니다" : "그룹 기준 추가", children: _jsx("span", { children: _jsx(IconButton, { size: "small", "aria-label": "\uADF8\uB8F9 \uAE30\uC900 \uCD94\uAC00", disabled: remaining.length === 0, onClick: (event) => setAnchorEl(event.currentTarget), children: _jsx(AddIcon, { fontSize: "small" }) }) }) }), isGrouped && (_jsx(Chip, { size: "small", variant: "outlined", label: "\uD574\uC81C", onClick: () => onChange([]), sx: { bgcolor: "background.paper" } })), _jsx(Box, { sx: { flex: 1, display: "flex", alignItems: "center", minHeight: 32, pl: 0.5, minWidth: 0 }, children: hint && (_jsx(Typography, { variant: "overline", color: rejected ? "error" : dragging ? "primary" : "text.secondary", sx: { userSelect: "none", lineHeight: 1.4, fontWeight: rejected ? 600 : undefined, whiteSpace: "nowrap" }, children: hint })) }), isGrouped && onGroupedColumnModeChange && (_jsxs(ToggleButtonGroup, { exclusive: true, size: "small", "aria-label": "\uADF8\uB8F9 \uCEEC\uB7FC \uBC30\uCE58", value: groupedColumnMode === false ? "false" : groupedColumnMode ?? "reorder", onChange: (_, next) => {
+                    if (next === null)
+                        return;
+                    onGroupedColumnModeChange(next === "false" ? false : next);
+                }, sx: { flexShrink: 0, bgcolor: "background.paper", "& .MuiToggleButton-root": { py: 0.25, px: 1, fontSize: 11 } }, children: [_jsx(ToggleButton, { value: "remove", "aria-label": "\uADF8\uB8F9 \uCEEC\uB7FC \uC81C\uAC70", children: "Remove" }), _jsx(ToggleButton, { value: "reorder", "aria-label": "\uADF8\uB8F9 \uCEEC\uB7FC \uC55E\uC73C\uB85C", children: "Reorder" })] })), isGrouped && onBatchSizeChange && (_jsx(Autocomplete, { size: "small", freeSolo: true, disableClearable: true, options: GROUP_BATCH_SIZE_OPTIONS.map(String), value: batchSize !== undefined ? String(batchSize) : "", onChange: (_, next) => {
+                    const num = parseInt(String(next), 10);
+                    if (num > 0)
+                        onBatchSizeChange(num);
+                }, onBlur: (event) => {
+                    const num = parseInt(event.target.value, 10);
+                    if (num > 0 && num !== batchSize)
+                        onBatchSizeChange(num);
+                }, sx: { width: 96, flexShrink: 0 }, renderInput: (params) => (_jsx(TextField, { ...params, variant: "standard", label: "\uBC30\uCE58", slotProps: {
+                        htmlInput: { ...params.inputProps, "aria-label": "배치 크기", style: { textAlign: "right", padding: "2px 0" } },
+                    } })) })), extra, _jsx(Menu, { anchorEl: anchorEl, open: !!anchorEl, onClose: () => setAnchorEl(null), children: remaining.map((candidate) => (_jsx(MenuItem, { onClick: () => {
+                        onChange([...grouping, candidate.id]);
+                        setAnchorEl(null);
+                    }, children: _jsx(ListItemText, { primary: candidate.label }) }, candidate.id))) })] }));
+}
+/** `from` 의 항목을 빼서 `to` 위치에 넣은 새 배열 */
+function reorder(list, from, to) {
+    const next = [...list];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    return next;
+}

package/dist/mui/src/grouping/StepExpandButton.d.ts

@@ -0,0 +1,12 @@
+import type { ExpandState } from "../../../core/src/index";
+export interface StepExpandButtonProps {
+    expand: ExpandState;
+}
+/**
+ * 단계 펼치기 — 한 번에 한 계층씩 여닫는다.
+ *
+ * 3단 그룹에서 "전부 펼치기"는 말단 행까지 쏟아져 오히려 안 보인다.
+ * 계층을 하나씩 여는 쪽이 실제로 쓰는 조작이라 기본 버튼으로 둔다
+ * (`expand.depth` 가 현재 열린 깊이, `maxDepth` 가 한계).
+ */
+export declare function StepExpandButton({ expand }: StepExpandButtonProps): import("react").JSX.Element | null;

package/dist/mui/src/grouping/StepExpandButton.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button, ButtonGroup, Tooltip } from "@mui/material";
+import UnfoldLessIcon from "@mui/icons-material/UnfoldLess";
+import UnfoldMoreIcon from "@mui/icons-material/UnfoldMore";
+/**
+ * 단계 펼치기 — 한 번에 한 계층씩 여닫는다.
+ *
+ * 3단 그룹에서 "전부 펼치기"는 말단 행까지 쏟아져 오히려 안 보인다.
+ * 계층을 하나씩 여는 쪽이 실제로 쓰는 조작이라 기본 버튼으로 둔다
+ * (`expand.depth` 가 현재 열린 깊이, `maxDepth` 가 한계).
+ */
+export function StepExpandButton({ expand }) {
+    if (!expand.canExpand)
+        return null;
+    const canMore = expand.depth < expand.maxDepth;
+    const canLess = expand.depth > 0;
+    return (_jsxs(ButtonGroup, { size: "small", variant: "outlined", children: [_jsx(Tooltip, { title: canLess ? "한 단계 접기" : "이미 다 접혀 있습니다", children: _jsx("span", { children: _jsx(Button, { "aria-label": "\uD55C \uB2E8\uACC4 \uC811\uAE30", disabled: !canLess, onClick: () => expand.expandToDepth(expand.depth - 1), startIcon: _jsx(UnfoldLessIcon, {}), children: "\uC811\uAE30" }) }) }), _jsx(Tooltip, { title: canMore ? "한 단계 펼치기" : "이미 다 펼쳐져 있습니다", children: _jsx("span", { children: _jsx(Button, { "aria-label": "\uD55C \uB2E8\uACC4 \uD3BC\uCE58\uAE30", disabled: !canMore, onClick: () => expand.expandToDepth(expand.depth + 1), startIcon: _jsx(UnfoldMoreIcon, {}), children: "\uD3BC\uCE58\uAE30" }) }) }), _jsxs(Button, { "aria-label": "\uB2E8\uACC4 \uD45C\uC2DC", disabled: true, sx: { minWidth: 52 }, children: [expand.depth, "/", expand.maxDepth] })] }));
+}

package/dist/mui/src/grouping/groupRow.d.ts

@@ -0,0 +1,68 @@
+import type { ComponentType, ReactNode } from "react";
+import { type Column, type RowData } from "@tanstack/react-table";
+import type { AggregateResult, AggregationDef, AggregationId, GroupTreeNode, Registry } from "../../../core/src/index";
+import { type AggregateChipProps } from "./AggregateChip";
+/** depth 1단계당 들여쓰기 (MUI spacing 단위). 그룹값 셀과 집계 셀에 같이 적용한다 */
+export declare const GROUP_DEPTH_INDENT = 2;
+/** depth 별 그룹 행 배경 — 깊어질수록 한 단계씩 어둡다 */
+export declare const GROUP_ROW_BG_SHADES: readonly ["grey.50", "grey.100", "grey.200", "grey.300"];
+export declare function groupRowBgColor(depth: number): string;
+/** 그룹 행 hover 색 — 한 단계 더 어두운 색 */
+export declare function groupRowHoverColor(depth: number): string;
+/** `meta.aggRender` 가 받는 값 — ERP `AggValues` 와 같은 모양 */
+export interface AggRenderProps {
+    /** 선택된(또는 첫) 함수의 값 */
+    value: unknown;
+    columnId: string;
+    /** 이 그룹 노드의 집계 전체 (`node.aggregates`) */
+    allAggregates: AggregateResult;
+}
+/**
+ * 합성 집계 렌더러. 코어의 `ColumnMeta.aggRender` 선언은 `(aggregates) => unknown` 으로 느슨하지만
+ * 렌더러는 ERP 와 같은 `(values, column)` 규약으로 부른다 — `allAggregates` 로 전체를 볼 수 있다.
+ */
+export type AggRender<T extends RowData> = (values: AggRenderProps, column: Column<T, unknown>) => ReactNode;
+/** 카테고리형(enum/select/text) — 고유 개수 외의 집계는 뜻이 없다 */
+export declare function isCategoricalColumn<T extends RowData>(column: Column<T, unknown>): boolean;
+/** 그룹 컬럼의 표시 이름 — 헤더가 문자열이면 그것, 아니면 id */
+export declare function columnLabelOf<T extends RowData>(column: Column<T, unknown>): string;
+/**
+ * 그룹값 라벨 — `node.label`(코어가 `selectOptions` 로 해석) → 컬럼 `cell` 렌더러 → 문자열.
+ *
+ * `cell` 렌더러는 TanStack 셀 컨텍스트를 기대하므로 최소한의 모조 컨텍스트로 부른다 —
+ * `row.original` 에는 현재 값과 조상 그룹 값을 넣어 상위 필드를 참조하는 렌더러도 동작한다.
+ * 렌더러가 던지면 문자열로 물러선다.
+ */
+export declare function resolveGroupValue<T extends RowData>(node: GroupTreeNode<T>, column: Column<T, unknown> | undefined): ReactNode;
+export interface AggregateCellContentOptions<T extends RowData> {
+    column: Column<T, unknown>;
+    node: GroupTreeNode<T>;
+    /** 컬럼별 선택된 함수 */
+    selection: Record<string, AggregationId>;
+    /** 없으면 칩은 읽기 전용 (메서드 시그니처 — `(id, fn: AggFnKey) => void` 처럼 좁은 콜백도 받는다) */
+    onSelect?(columnId: string, fn: AggregationId): void;
+    /** 칩 컴포넌트 교체 — `KokoTableProvider components.AggregateChip` */
+    chip?: ComponentType<AggregateChipProps>;
+    /**
+     * 집계 레지스트리 — boolean/카테고리형 컬럼에서 뜻 있는 함수를 고를 때 본다.
+     * 미지정 시 전역 `aggregations`, 칩(`AggregateChip`)은 Provider 것(`useAggregations()`)을 본다.
+     */
+    registry?: Registry<AggregationDef>;
+}
+/**
+ * 집계 셀 내용. 그릴 것이 없으면 `null`.
+ *
+ * 우선순위: `meta.aggRender` → 카테고리형은 `count_distinct` + 사용자 집계(`applies` 참)만, boolean 은 `applies("boolean")` 인 것만
+ * (내장: `count_true`·`count_distinct`·`ratio`) → `AggregateChip`
+ * (선택된 함수 = `selection[columnId]`, 없으면 첫 값. 함수가 둘 이상이면 칩을 눌러 바꾼다).
+ * 대상은 `meta.enableAgg` / `meta.aggRender` 가 있거나 `node.aggregates[columnId]` 가 있는 컬럼뿐이다.
+ */
+export declare function renderAggregateCellContent<T extends RowData>({ column, node, selection, onSelect, chip, registry: givenRegistry, }: AggregateCellContentOptions<T>): ReactNode;
+/** 그룹값 텍스트 — 굵게 */
+export declare function GroupValueText({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** 집계 셀 내용을 가운데 놓는다 (ERP `aggCellContentSx`) */
+export declare function AggregateCellBox({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;