kokotable 0.95.0

package/dist/mui/src/virtualColumns/useVirtualColumns.js

@@ -0,0 +1,111 @@
+import { useCallback, useMemo, useState } from "react";
+import { validateExpression, } from "./expression";
+const DEFAULT_MAX_SLOTS = 10;
+const DEFAULT_PREFIX = "vc_";
+/** 슬롯 목록 `vc_1 … vc_N` (기존 ERP 규칙) */
+export function virtualColumnSlots(maxSlots = DEFAULT_MAX_SLOTS, prefix = DEFAULT_PREFIX) {
+    return Array.from({ length: maxSlots }, (_, i) => `${prefix}${i + 1}`);
+}
+function slotOrder(slot, prefix) {
+    const n = Number(slot.slice(prefix.length));
+    return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER;
+}
+/**
+ * 가상 열 상태 — `SearchState.virtualColumns` 위에서 CRUD 를 제공한다.
+ *
+ * 기존 ERP `useVirtualColumns` 는 목록을 로컬 state 로 들고 `virtualColumnsForRequest` 를
+ * 호출부가 요청에 직접 얹었다. 여기서는 검색 상태가 **원본**이다 — `search.request.virtualColumns`
+ * 로 자동으로 실리고, URL 동기화·프리셋·reset 도 같은 경로를 탄다. 이름만 로컬이다
+ * (요청 계약 `VirtualColumnSpec` 에 이름 자리가 없다).
+ */
+export function useVirtualColumns(search, options = {}) {
+    const { applyImmediately = true, maxSlots = DEFAULT_MAX_SLOTS, slotPrefix = DEFAULT_PREFIX, fields = [], initialNames, } = options;
+    const [names, setNames] = useState(() => ({ ...initialNames }));
+    const source = applyImmediately ? search.params : search.draft;
+    const spec = source.virtualColumns;
+    const columns = useMemo(() => {
+        if (!spec)
+            return [];
+        return Object.entries(spec)
+            .sort(([a], [b]) => slotOrder(a, slotPrefix) - slotOrder(b, slotPrefix))
+            .map(([slotKey, value]) => ({
+            slotKey,
+            name: names[slotKey] ?? slotKey,
+            expr: value.expr,
+            type: value.type ?? "number",
+        }));
+    }, [spec, names, slotPrefix]);
+    const nextSlot = useMemo(() => {
+        const used = new Set(Object.keys(spec ?? {}));
+        return virtualColumnSlots(maxSlots, slotPrefix).find((slot) => !used.has(slot)) ?? null;
+    }, [spec, maxSlots, slotPrefix]);
+    const write = useCallback((next) => {
+        const value = Object.keys(next).length > 0 ? next : undefined;
+        if (applyImmediately)
+            search.patchParams({ virtualColumns: value });
+        else
+            search.patchDraft({ virtualColumns: value });
+    }, [applyImmediately, search]);
+    const validate = useCallback((column) => {
+        if (!column.name.trim())
+            return { ok: false, message: "이름을 입력하세요." };
+        return validateExpression(column.expr, { type: column.type, fields: fields.length > 0 ? fields : undefined });
+    }, [fields]);
+    const add = useCallback((column) => {
+        const check = validate(column);
+        if (!check.ok)
+            return check;
+        const current = (applyImmediately ? search.params : search.draft).virtualColumns ?? {};
+        const used = new Set(Object.keys(current));
+        const slot = virtualColumnSlots(maxSlots, slotPrefix).find((s) => !used.has(s));
+        if (!slot)
+            return { ok: false, message: `가상 열은 최대 ${maxSlots}개까지 만들 수 있습니다.` };
+        setNames((prev) => ({ ...prev, [slot]: column.name.trim() }));
+        write({ ...current, [slot]: { expr: column.expr.trim(), type: column.type } });
+        return { ok: true, slotKey: slot };
+    }, [validate, applyImmediately, search, maxSlots, slotPrefix, write]);
+    const update = useCallback((slotKey, patch) => {
+        const current = (applyImmediately ? search.params : search.draft).virtualColumns ?? {};
+        const existing = current[slotKey];
+        if (!existing)
+            return { ok: false, message: `'${slotKey}' 슬롯이 없습니다.` };
+        const merged = {
+            name: patch.name ?? names[slotKey] ?? slotKey,
+            expr: patch.expr ?? existing.expr,
+            type: patch.type ?? existing.type ?? "number",
+        };
+        const check = validate(merged);
+        if (!check.ok)
+            return check;
+        if (patch.name !== undefined)
+            setNames((prev) => ({ ...prev, [slotKey]: merged.name.trim() }));
+        write({ ...current, [slotKey]: { expr: merged.expr.trim(), type: merged.type } });
+        return { ok: true, slotKey };
+    }, [applyImmediately, search, names, validate, write]);
+    const remove = useCallback((slotKey) => {
+        const current = (applyImmediately ? search.params : search.draft).virtualColumns ?? {};
+        if (!(slotKey in current))
+            return;
+        const { [slotKey]: _removed, ...rest } = current;
+        setNames((prev) => {
+            const { [slotKey]: _name, ...others } = prev;
+            return others;
+        });
+        write(rest);
+    }, [applyImmediately, search, write]);
+    const request = useMemo(() => search.request.virtualColumns ?? {}, [search.request.virtualColumns]);
+    return useMemo(() => ({
+        search,
+        columns,
+        add,
+        update,
+        remove,
+        validate,
+        request,
+        isMaxReached: nextSlot === null,
+        nextSlot,
+        applyImmediately,
+        names,
+        fields,
+    }), [search, columns, add, update, remove, validate, request, nextSlot, applyImmediately, names, fields]);
+}

package/dist/mui/src/virtualColumns/virtualColumnDefs.d.ts

@@ -0,0 +1,29 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs, VirtualColumnSpec } from "../../../core/src/index";
+import type { VirtualColumnField } from "./expression";
+import type { VirtualColumn } from "./useVirtualColumns";
+export interface VirtualColumnDefsOptions {
+    /** 슬롯 → 헤더 이름. 없으면 슬롯 키가 헤더가 된다 (`useVirtualColumns().names`) */
+    names?: Record<string, string>;
+    /** 열 폭 */
+    size?: number;
+    /** 필터 UI 에 노출할지. 기본 false — 카드 섹션이 필터를 맡는다 */
+    filterable?: boolean;
+}
+/**
+ * 가상 컬럼을 **표시 컬럼**으로 만든다.
+ *
+ * 값은 서버가 식을 평가해 응답 행에 `{ vc_1: 123 }` 처럼 실어 준다 — 클라이언트 모드에서는
+ * 값이 없다(2층 엔진은 식을 평가하지 않는다). 이 헬퍼는 그 필드를 읽는 `accessorFn` 컬럼을
+ * 만들어 응답에 실린 값이 표에 보이게 한다. `useDataTable({ columns })` 에 기본 컬럼과 함께 넘긴다.
+ *
+ * `spec` 은 `search.request.virtualColumns` 든 `useVirtualColumns().columns` 든 받는다.
+ */
+export declare function virtualColumnDefs<T extends RowData>(spec: Record<string, VirtualColumnSpec> | ReadonlyArray<VirtualColumn> | undefined, options?: VirtualColumnDefsOptions): TableColumnDefs<T>;
+/**
+ * 수식에 참조할 수 있는 필드 목록 — `describeColumns(columns)` 로 컬럼 id·헤더를 뽑는다.
+ * 표시 전용 컬럼(`koko-`)과 값 보관 전용(`forceHidden`) 컬럼, 가상 컬럼 자신(`vc_`)은 제외한다.
+ */
+export declare function virtualColumnFields<T extends RowData>(columns: TableColumnDefs<T>, options?: {
+    slotPrefix?: string;
+}): VirtualColumnField[];

package/dist/mui/src/virtualColumns/virtualColumnDefs.js

@@ -0,0 +1,51 @@
+import { describeColumns, formatByDataType } from "../../../core/src/index";
+function dataTypeOf(type) {
+    return type === "boolean" ? "boolean" : type === "string" ? "text" : "number";
+}
+/**
+ * 가상 컬럼을 **표시 컬럼**으로 만든다.
+ *
+ * 값은 서버가 식을 평가해 응답 행에 `{ vc_1: 123 }` 처럼 실어 준다 — 클라이언트 모드에서는
+ * 값이 없다(2층 엔진은 식을 평가하지 않는다). 이 헬퍼는 그 필드를 읽는 `accessorFn` 컬럼을
+ * 만들어 응답에 실린 값이 표에 보이게 한다. `useDataTable({ columns })` 에 기본 컬럼과 함께 넘긴다.
+ *
+ * `spec` 은 `search.request.virtualColumns` 든 `useVirtualColumns().columns` 든 받는다.
+ */
+export function virtualColumnDefs(spec, options = {}) {
+    if (!spec)
+        return [];
+    const entries = Array.isArray(spec)
+        ? spec.map((c) => ({ slotKey: c.slotKey, name: c.name, type: c.type }))
+        : Object.entries(spec).map(([slotKey, value]) => ({
+            slotKey,
+            name: options.names?.[slotKey] ?? slotKey,
+            type: value.type ?? "number",
+        }));
+    return entries.map(({ slotKey, name, type }) => ({
+        id: slotKey,
+        header: options.names?.[slotKey] ?? name,
+        accessorFn: (row) => row[slotKey],
+        // 숫자는 콤마 포맷(`ColumnIsNumber` 와 같은 규칙), 참/거짓은 글자로
+        cell: ({ getValue }) => {
+            const value = getValue();
+            if (type === "boolean")
+                return value === null || value === undefined ? "" : value ? "참" : "거짓";
+            return formatByDataType(value, dataTypeOf(type));
+        },
+        ...(options.size !== undefined ? { size: options.size } : {}),
+        enableSorting: true,
+        enableGrouping: false,
+        meta: { dataType: dataTypeOf(type) },
+        filter: options.filterable ? { variant: type === "number" ? "number" : type === "boolean" ? "boolean" : "text" } : { hidden: true },
+    }));
+}
+/**
+ * 수식에 참조할 수 있는 필드 목록 — `describeColumns(columns)` 로 컬럼 id·헤더를 뽑는다.
+ * 표시 전용 컬럼(`koko-`)과 값 보관 전용(`forceHidden`) 컬럼, 가상 컬럼 자신(`vc_`)은 제외한다.
+ */
+export function virtualColumnFields(columns, options = {}) {
+    const prefix = options.slotPrefix ?? "vc_";
+    return describeColumns(columns)
+        .filter((c) => !c.forceHidden && !c.id.startsWith(prefix))
+        .map((c) => ({ key: c.id, header: c.header }));
+}

package/dist/mui-virtual.d.ts

@@ -0,0 +1 @@
+export * from "./mui/src/virtual";

package/dist/mui-virtual.js

@@ -0,0 +1,2 @@
+// kokotable/mui/virtual — 행·열 가상화 (react-virtual 필요)
+export * from "./mui/src/virtual";

package/dist/mui.d.ts

@@ -0,0 +1 @@
+export * from "./mui/src/index";

package/dist/mui.js

@@ -0,0 +1,2 @@
+// kokotable/mui — MUI 렌더러·애드온
+export * from "./mui/src/index";

package/dist/query/src/index.d.ts

@@ -0,0 +1,6 @@
+export { useServerTableData, type ServerTableDataOptions, type ServerTableData, type TableQueryFn, } from "./useServerTableData";
+export { useServerGrouping, type UseServerGroupingOptions, type ServerGroupingResult, } from "./useServerGrouping";
+export { serverPivotResult, type ServerPivotResponse } from "./serverPivot";
+export { useServerTable, type ServerTableBundle } from "./useServerTable";
+export type { ServerTableQueryOptions } from "./useServerTableData";
+export { toWireRequest } from "./wire";

package/dist/query/src/index.js

@@ -0,0 +1,7 @@
+export { useServerTableData, } from "./useServerTableData";
+export { useServerGrouping, } from "./useServerGrouping";
+export { serverPivotResult } from "./serverPivot";
+// ── 테이블 정의 ──
+export { useServerTable } from "./useServerTable";
+// ── 서버 계약 ──
+export { toWireRequest } from "./wire";

package/dist/query/src/serverPivot.d.ts

@@ -0,0 +1,42 @@
+import type { LabelResolver, PivotResult } from "../../core/src/index";
+/**
+ * 백엔드 `PivotBuilder` 응답.
+ *
+ * 서버는 **평평한 행**과 **컬럼 메타 트리**를 준다. 행에는 축 컬럼 값과
+ * `채널|1월` 처럼 합쳐진 피벗 키가 한 객체에 섞여 있다.
+ */
+export interface ServerPivotResponse {
+    /** 평평한 결과 행 — 축 값 + 피벗 키가 한 객체에 섞여 있다 */
+    data: Array<Record<string, unknown>>;
+    /** 열 축 메타 트리 */
+    columns: ServerPivotColumn[];
+    /** 행 축 컬럼명 (상위 → 하위) */
+    rowKeys?: string[];
+    /** 값 키 (`payment_amount_SUM` 등) */
+    valueKeys?: string[];
+    meta?: {
+        total_count?: number | null;
+    } | null;
+}
+export interface ServerPivotColumn {
+    key: string;
+    label: string;
+    /** `row` = 행 축 컬럼, `value` = 집계 값, `group` = 열 축 그룹 */
+    type?: "row" | "value" | "group";
+    columns?: ServerPivotColumn[];
+}
+export interface ServerPivotOptions {
+    /** 축 값 → 라벨. CommonCode idx 를 이름으로 바꿀 때 쓴다 */
+    labelOf?: LabelResolver;
+    /** 값 키. 미지정이면 응답의 `valueKeys`, 그것도 없으면 첫 leaf 에서 유추 */
+    valueKeys?: string[];
+}
+/**
+ * 서버 피벗 응답 → 렌더러가 쓰는 `PivotResult`.
+ *
+ * 클라이언트 계산(`runClientPivot`)과 **같은 타입**을 내므로 `PivotTable` 은
+ * 어느 쪽에서 왔는지 몰라도 된다. 데이터 규모에 따라 계산 위치만 갈아끼운다.
+ *
+ * 서버는 평평한 행을 주므로 행 축 컬럼값을 따라 트리로 되접는다.
+ */
+export declare function serverPivotResult(response: ServerPivotResponse, options?: ServerPivotOptions): PivotResult;

package/dist/query/src/serverPivot.js

@@ -0,0 +1,153 @@
+import { PIVOT_SEPARATOR } from "../../core/src/index";
+function collectLeafKeys(nodes, into = []) {
+    for (const node of nodes) {
+        if (node.columns && node.columns.length > 0)
+            collectLeafKeys(node.columns, into);
+        else
+            into.push(node.key);
+    }
+    return into;
+}
+function toAxisNodes(nodes, depth, labels, parentLabels) {
+    return nodes.map((node) => {
+        const chain = [...parentLabels, node.label];
+        const children = node.columns && node.columns.length > 0
+            ? toAxisNodes(node.columns, depth + 1, labels, chain)
+            : undefined;
+        if (!children)
+            labels[node.key] = chain;
+        return {
+            key: node.key,
+            label: node.label,
+            // 서버 키는 이미 합쳐진 문자열이라 원자 값이 없다 — 마지막 조각을 쓴다
+            value: node.key.split(PIVOT_SEPARATOR).pop() ?? node.key,
+            source: "",
+            depth,
+            children,
+        };
+    });
+}
+/**
+ * 서버 피벗 응답 → 렌더러가 쓰는 `PivotResult`.
+ *
+ * 클라이언트 계산(`runClientPivot`)과 **같은 타입**을 내므로 `PivotTable` 은
+ * 어느 쪽에서 왔는지 몰라도 된다. 데이터 규모에 따라 계산 위치만 갈아끼운다.
+ *
+ * 서버는 평평한 행을 주므로 행 축 컬럼값을 따라 트리로 되접는다.
+ */
+export function serverPivotResult(response, options = {}) {
+    const leafLabels = {};
+    const groupColumns = response.columns.filter((column) => column.type !== "row" && column.type !== "value");
+    const columns = toAxisNodes(groupColumns, 0, leafLabels, []);
+    const leafKeys = collectLeafKeys(groupColumns);
+    const rowKeys = response.rowKeys ??
+        response.columns.filter((column) => column.type === "row").map((column) => column.key);
+    const valueKeys = options.valueKeys ??
+        response.valueKeys ??
+        response.columns.filter((column) => column.type === "value").map((column) => column.key);
+    const label = (source, value) => options.labelOf?.(source, value) ?? (value === null || value === undefined ? "(비어 있음)" : String(value));
+    const sumOf = (rows, key) => {
+        let total = 0;
+        let seen = false;
+        for (const row of rows) {
+            const value = row[key];
+            if (typeof value === "number") {
+                total += value;
+                seen = true;
+            }
+        }
+        return seen ? total : null;
+    };
+    /**
+     * 행 축 값으로 트리를 되접는다.
+     *
+     * 상위 노드의 값은 **하위 합**이다. 서버가 소계 행을 따로 주지 않기 때문인데,
+     * `AVG`/`MIN`/`MAX` 는 합으로 굴릴 수 없다 — 그런 집계를 상위에서 봐야 하면
+     * 서버가 소계를 내려 주거나 클라이언트 계산을 써야 한다.
+     */
+    const build = (rows, depth, parentKey) => {
+        const source = rowKeys[depth];
+        if (!source)
+            return [];
+        const buckets = new Map();
+        for (const row of rows) {
+            const value = row[source];
+            const bucketKey = String(value);
+            const bucket = buckets.get(bucketKey);
+            if (bucket)
+                bucket.rows.push(row);
+            else
+                buckets.set(bucketKey, { value, rows: [row] });
+        }
+        const nodes = [];
+        for (const bucket of buckets.values()) {
+            const key = parentKey ? `${parentKey}${PIVOT_SEPARATOR}${String(bucket.value)}` : String(bucket.value);
+            const isLeaf = depth === rowKeys.length - 1;
+            const cells = {};
+            for (const leafKey of leafKeys) {
+                const perValue = {};
+                let any = false;
+                for (const valueKey of valueKeys) {
+                    // 서버 행의 셀 키는 `열키` 또는 `열키__값키` 형태를 모두 허용한다
+                    const combined = `${leafKey}${PIVOT_SEPARATOR}${valueKey}`;
+                    const has = bucket.rows.some((row) => combined in row);
+                    const cellKey = has ? combined : leafKey;
+                    const value = sumOf(bucket.rows, cellKey);
+                    if (value !== null)
+                        any = true;
+                    perValue[valueKey] = value;
+                }
+                if (any)
+                    cells[leafKey] = perValue;
+            }
+            const total = {};
+            for (const valueKey of valueKeys) {
+                total[valueKey] = sumOf(bucket.rows, valueKey) ?? sumOf(bucket.rows, leafKeys[0] ?? valueKey);
+            }
+            nodes.push({
+                key,
+                label: label(source, bucket.value),
+                value: bucket.value,
+                source,
+                depth,
+                cells,
+                total,
+                count: bucket.rows.length,
+                children: isLeaf ? undefined : build(bucket.rows, depth + 1, key),
+            });
+        }
+        return nodes;
+    };
+    const rows = build(response.data, 0, "");
+    const grandTotal = {};
+    for (const valueKey of valueKeys)
+        grandTotal[valueKey] = sumOf(response.data, valueKey);
+    // 열 합계 — 응답 행 전체에서 열 leaf 별 셀을 합산한다. 행 트리의 상위 노드와 같은
+    // 이유로 SUM 만 정확하다 (서버가 열 소계를 내려 주지 않는다).
+    const colTotals = {};
+    for (const leafKey of leafKeys) {
+        const perValue = {};
+        let any = false;
+        for (const valueKey of valueKeys) {
+            const combined = `${leafKey}${PIVOT_SEPARATOR}${valueKey}`;
+            const has = response.data.some((row) => combined in row);
+            const value = sumOf(response.data, has ? combined : leafKey);
+            if (value !== null)
+                any = true;
+            perValue[valueKey] = value;
+        }
+        if (any)
+            colTotals[leafKey] = perValue;
+    }
+    return {
+        rows,
+        columns,
+        leafKeys,
+        leafLabels,
+        valueKeys,
+        grandTotal,
+        colTotals,
+        // 서버는 상한을 넘긴 열을 응답에서 이미 빼고 준다 — 여기선 알 수 없다
+        droppedColumns: 0,
+    };
+}

package/dist/query/src/useServerGrouping.d.ts

@@ -0,0 +1,52 @@
+import type { RowData } from "@tanstack/react-table";
+import type { ExpandState, FlatItem, GroupPath, GroupTreeNode, TableColumnDefs, TableRequest, TableResponse } from "../../core/src/index";
+import type { TableQueryFn } from "./useServerTableData";
+export interface UseServerGroupingOptions<T extends RowData> {
+    /** 적용된 요청 — 필터·정렬이 그대로 그룹 조회에 실린다 */
+    request: TableRequest;
+    queryFn: TableQueryFn<T>;
+    /** 상위 → 하위 순서의 그룹 컬럼. 비어 있으면 아무것도 하지 않는다 */
+    grouping: string[];
+    columns?: TableColumnDefs<T>;
+    /**
+     * 최상위 그룹 조회 응답의 `groups` (`useServerTableData(...).groups`).
+     *
+     * 현행 백엔드는 `groupExpansion: { path: [] … }` 에 `groups.nodes`(한 레벨 `GroupNode[]`)로
+     * 답한다. 구 `groupHeaderOnly` 포맷의 `groups.headers` 도 하위 호환으로 읽는다
+     * (`nodes` 가 비어 있을 때만).
+     */
+    headers?: TableResponse<T>["groups"];
+    /** 한 번에 받아 올 하위 개수 */
+    batchSize?: number;
+}
+export interface ServerGroupingResult<T extends RowData> {
+    tree: Array<GroupTreeNode<T>>;
+    items: Array<FlatItem<T>>;
+    /**
+     * 지금까지 받아 온 **말단 행 전체**.
+     *
+     * 3층(`useDataTable`)에 넘겨야 셀이 컬럼 정의대로 그려진다. 헤더만 받는
+     * 모드에서는 `data.rows` 가 비어 있어서, 이걸 안 넘기면 그룹을 펼쳐도
+     * 행이 조용히 빈 채로 남는다.
+     */
+    rows: T[];
+    expand: ExpandState;
+    /** "더 보기" — 그 경로의 하위를 배치만큼 더 받는다 */
+    loadMore: (path: GroupPath) => void;
+    readonly enabled: boolean;
+}
+/**
+ * 서버 그룹핑 — 최상위 그룹 노드를 먼저 받고, 펼칠 때 하위를 가져온다.
+ *
+ * 요청은 백엔드 `GroupMixin._build_group_query` 규칙 그대로다: `groupExpansion.path` 깊이가
+ * `grouping` 깊이보다 얕으면 다음 레벨 노드(`groups.nodes`), 같으면 말단 행(`data`)이 오고,
+ * `meta.total_count` 는 그 레벨의 전체 개수(노드 수 또는 행 수)다.
+ *
+ * 클라이언트 그룹핑(`useGrouping`)과 **결과 모양이 같다** (`tree` / `items` /
+ * `expand`). 그래서 렌더러는 어느 쪽인지 몰라도 되고, 같은 화면을 데이터 규모에
+ * 따라 갈아끼울 수 있다.
+ *
+ * 차이는 하나: 하위가 페이지 단위로 오므로 `items` 에 "더 보기"(`loadMore`) 행이
+ * 섞인다. 전부 받아 놓고 자르는 게 아니라 **필요할 때만** 요청한다.
+ */
+export declare function useServerGrouping<T extends RowData>(options: UseServerGroupingOptions<T>): ServerGroupingResult<T>;

package/dist/query/src/useServerGrouping.js

@@ -0,0 +1,186 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { createLabelResolver, flattenGroups, pathKey } from "../../core/src/index";
+import { toWireRequest } from "./wire";
+const DEFAULT_BATCH = 50;
+function toAggregates(raw) {
+    return raw;
+}
+/**
+ * 서버 그룹핑 — 최상위 그룹 노드를 먼저 받고, 펼칠 때 하위를 가져온다.
+ *
+ * 요청은 백엔드 `GroupMixin._build_group_query` 규칙 그대로다: `groupExpansion.path` 깊이가
+ * `grouping` 깊이보다 얕으면 다음 레벨 노드(`groups.nodes`), 같으면 말단 행(`data`)이 오고,
+ * `meta.total_count` 는 그 레벨의 전체 개수(노드 수 또는 행 수)다.
+ *
+ * 클라이언트 그룹핑(`useGrouping`)과 **결과 모양이 같다** (`tree` / `items` /
+ * `expand`). 그래서 렌더러는 어느 쪽인지 몰라도 되고, 같은 화면을 데이터 규모에
+ * 따라 갈아끼울 수 있다.
+ *
+ * 차이는 하나: 하위가 페이지 단위로 오므로 `items` 에 "더 보기"(`loadMore`) 행이
+ * 섞인다. 전부 받아 놓고 자르는 게 아니라 **필요할 때만** 요청한다.
+ */
+export function useServerGrouping(options) {
+    const { request, queryFn, grouping, columns, headers, batchSize = DEFAULT_BATCH, } = options;
+    const enabled = grouping.length > 0;
+    const resolveLabel = useMemo(() => createLabelResolver(columns), [columns]);
+    const [levels, setLevels] = useState({});
+    const [expandedKeys, setExpandedKeys] = useState(new Set());
+    // 요청이 바뀌면(필터·정렬) 받아 둔 하위는 전부 무효다 — 안 버리면 새 조건에
+    // 맞지 않는 행이 펼친 그룹 아래 그대로 남는다
+    const requestRef = useRef(request);
+    if (requestRef.current !== request) {
+        requestRef.current = request;
+        if (Object.keys(levels).length > 0)
+            setLevels({});
+        if (expandedKeys.size > 0)
+            setExpandedKeys(new Set());
+    }
+    /** 서버 응답 `groups` → 최상위 노드. `nodes`(현행) 우선, 비어 있으면 `headers`(구 포맷) */
+    const roots = useMemo(() => {
+        const nodes = headers?.nodes ?? [];
+        if (nodes.length > 0) {
+            return nodes.map((node) => {
+                const key = node.group_key || grouping[0] || "";
+                return {
+                    groupKey: key,
+                    groupValue: node.group_value ?? null,
+                    label: resolveLabel(key, node.group_value) ?? undefined,
+                    count: node.count,
+                    aggregates: toAggregates(node.aggregates),
+                    path: [{ key, value: node.group_value ?? null }],
+                    depth: 0,
+                };
+            });
+        }
+        const list = headers?.headers ?? [];
+        return list.map((header) => {
+            const path = header.group_values.map((step) => ({
+                key: step.key,
+                value: step.value,
+            }));
+            const last = header.group_values[header.group_values.length - 1];
+            return {
+                groupKey: last?.key ?? grouping[0] ?? "",
+                groupValue: last?.value ?? null,
+                label: last?.label ?? resolveLabel(last?.key ?? "", last?.value) ?? undefined,
+                count: header.count,
+                aggregates: toAggregates(header.aggregates),
+                path,
+                depth: 0,
+            };
+        });
+    }, [headers, grouping, resolveLabel]);
+    /** 받아 둔 레벨을 노드에 붙여 트리를 만든다 */
+    const attach = useCallback((node) => {
+        const level = levels[pathKey(node.path)];
+        if (!level) {
+            // 아직 안 받았으면 "펼칠 수 있다"만 표시한다 — 자식 배열을 비워 두면
+            // 렌더러가 "자식 없음"으로 오해한다
+            return { ...node, hasMore: false };
+        }
+        const children = level.nodes?.map((child) => attach({ ...child, depth: node.depth + 1 }));
+        return {
+            ...node,
+            children,
+            rows: level.rows,
+            hasMore: level.hasMore,
+            loadedCount: level.loaded,
+            totalCount: level.total,
+            isPending: level.pending,
+        };
+    }, [levels]);
+    const tree = useMemo(() => (enabled ? roots.map(attach) : []), [enabled, roots, attach]);
+    const fetchLevel = useCallback(async (path, offset) => {
+        const key = pathKey(path);
+        setLevels((prev) => ({
+            ...prev,
+            [key]: { ...(prev[key] ?? { loaded: 0, hasMore: false }), pending: true },
+        }));
+        try {
+            // 백엔드 `GroupExpansion` — path 깊이로 노드/말단을 가른다. `toWireRequest` 가
+            // 호출부가 남긴 `groupHeaderOnly` 를 걷어낸다(백엔드 계약에 없는 키).
+            const response = await queryFn(toWireRequest({
+                ...requestRef.current,
+                groupExpansion: { path: [...path], offset, limit: batchSize },
+            }), { signal: new AbortController().signal });
+            const nodes = (response.groups?.nodes ?? []).map((node) => ({
+                groupKey: node.group_key,
+                groupValue: node.group_value,
+                label: resolveLabel(node.group_key, node.group_value),
+                count: node.count,
+                aggregates: toAggregates(node.aggregates),
+                path: [...path, { key: node.group_key, value: node.group_value }],
+                depth: path.length,
+            }));
+            const rows = response.data ?? [];
+            const received = nodes.length > 0 ? nodes.length : rows.length;
+            // 백엔드는 has_more 를 주지 않는다 — ERP 와 같이 `meta.total_count`(그 레벨의 전체
+            // 노드/행 수, 그룹 노드는 `_total` 윈도우 값)로 판정하고, 없으면 배치 크기로 추정한다
+            const total = response.meta?.total_count ?? undefined;
+            setLevels((prev) => {
+                const before = prev[key];
+                const loaded = offset + received;
+                return {
+                    ...prev,
+                    [key]: {
+                        nodes: nodes.length > 0 ? [...(before?.nodes ?? []), ...nodes] : before?.nodes,
+                        rows: rows.length > 0 ? [...(before?.rows ?? []), ...rows] : before?.rows,
+                        loaded,
+                        total: total ?? undefined,
+                        // 총 개수를 모르면 배치가 가득 찼는지로 판단한다
+                        hasMore: total != null ? loaded < total : received === batchSize,
+                        pending: false,
+                    },
+                };
+            });
+        }
+        catch {
+            // 실패해도 펼침 상태는 유지한다 — 접혀 버리면 사용자가 뭘 눌렀는지 잃는다
+            setLevels((prev) => ({
+                ...prev,
+                [key]: { ...(prev[key] ?? { loaded: 0, hasMore: false }), pending: false },
+            }));
+        }
+    }, [queryFn, batchSize, resolveLabel]);
+    const toggle = useCallback((path) => {
+        const key = pathKey(path);
+        setExpandedKeys((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else {
+                next.add(key);
+                // 처음 펼치는 경로면 그때 받아 온다
+                if (!levels[key])
+                    void fetchLevel(path, 0);
+            }
+            return next;
+        });
+    }, [levels, fetchLevel]);
+    const loadMore = useCallback((path) => {
+        const level = levels[pathKey(path)];
+        void fetchLevel(path, level?.loaded ?? 0);
+    }, [levels, fetchLevel]);
+    const expand = useMemo(() => ({
+        isExpanded: (path) => expandedKeys.has(pathKey(path)),
+        toggle,
+        // 서버 모드는 전부 펼치면 트리 전체를 받아 와야 한다. 몇 건인지 모르는 채
+        // 그렇게 하면 화면이 멈추므로 최상위만 펼친다.
+        expandAll: () => setExpandedKeys(new Set(roots.map((node) => pathKey(node.path)))),
+        collapseAll: () => setExpandedKeys(new Set()),
+        expandToDepth: (depth) => setExpandedKeys(depth <= 0 ? new Set() : new Set(roots.map((n) => pathKey(n.path)))),
+        depth: expandedKeys.size > 0 ? 1 : 0,
+        maxDepth: grouping.length,
+        canExpand: grouping.length > 0,
+    }), [expandedKeys, toggle, roots, grouping.length]);
+    const items = useMemo(() => (enabled ? flattenGroups(tree, { expanded: expandedKeys }) : []), [enabled, tree, expandedKeys]);
+    const rows = useMemo(() => {
+        const collected = [];
+        for (const level of Object.values(levels)) {
+            if (level.rows)
+                collected.push(...level.rows);
+        }
+        return collected;
+    }, [levels]);
+    return { tree, items, rows, expand, loadMore, enabled };
+}