kokotable 0.95.0

package/dist/core/src/adapters/sources.js

@@ -0,0 +1,235 @@
+import { resolveOperatorOptions, resolveVariant } from "../columns/deriveOperators";
+import { resolveFilterKind } from "../filters/kind";
+/**
+ * 어댑터 — 테이블 인스턴스를 좁은 계약으로 좁힌다.
+ *
+ * MRT 를 걷어내면 `MRT_TableHeadCellFilterContainer` 가 하던
+ * "헤더 -> { value, onChange, operator }" 변환을 어차피 직접 짜야 한다.
+ * 그 변환의 결과 타입을 `FilterSource` 로 고정한 것이 이 어댑터고,
+ * 그래서 `TableSearch` 도 같은 자리에 꽂힌다 — 추가 비용이 거의 없다.
+ */
+export function isFilterSource(value) {
+    return typeof value?.getFilterFields === "function";
+}
+export function isPaginationSource(value) {
+    return typeof value?.getPagination === "function";
+}
+export function isSelectionSource(value) {
+    return typeof value?.getSelectedRows === "function";
+}
+function hasSearch(value) {
+    return isFilterSource(value?.search);
+}
+/**
+ * TanStack 인스턴스에서 필터 필드를 뽑는다.
+ *
+ * 대상 컬럼은 `getAllLeafColumns()` 기준이다 — 숨김·그룹핑으로
+ * `getLeafHeaders()` 에서 빠진 컬럼도 필터는 살아 있어야 하기 때문.
+ *
+ * `useDataTable` 로 만든 인스턴스는 `search` 를 들고 있으므로 그쪽에 위임한다.
+ * 그래야 값이 draft 한 곳에서만 관리된다 (이중 소스 방지).
+ */
+export function filterSourceFromTable(table) {
+    if (hasSearch(table))
+        return table.search;
+    return {
+        getFilterFields() {
+            const fields = [];
+            for (const column of table.getAllLeafColumns()) {
+                if (!column.getCanFilter())
+                    continue;
+                const def = column.columnDef;
+                if (def.filter?.hidden || def.meta?.forceHidden)
+                    continue;
+                fields.push({
+                    id: column.id,
+                    header: def.filterLabel ?? def.header,
+                    variant: resolveVariant(def),
+                    kind: resolveFilterKind(def),
+                    meta: def.meta,
+                    value: column.getFilterValue(),
+                    onChange: (value) => column.setFilterValue(value),
+                    operator: (def.filter?.defaultOperator ?? "fuzzy"),
+                    // 제어형 테이블만으로는 연산자를 바꿀 곳이 없다 — 연산자 변경이
+                    // 필요하면 `useTableSearch` 를 쓰거나 `search` 를 얹은 인스턴스를 넘긴다.
+                    onOperatorChange: () => { },
+                    operatorOptions: resolveOperatorOptions(def),
+                    // kind 별 값 타입으로 좁혀진 render 를 필드 계약(unknown) 으로 넘긴다
+                    render: def.filter?.render,
+                    detail: def.filter?.detail,
+                });
+            }
+            return fields;
+        },
+    };
+}
+/**
+ * 페이지네이션 계약 — 현재 페이지는 검색 상태가, 총 건수는 데이터가 안다.
+ * 둘을 합쳐야 비로소 `PaginationSource` 가 성립한다.
+ */
+export function paginationSource(search, data) {
+    return {
+        getPagination() {
+            const { pageIndex, pageSize } = search.params.pagination;
+            return {
+                pageIndex,
+                pageSize,
+                total: data.total,
+                pageCount: pageSize > 0 ? Math.ceil(data.total / pageSize) : 0,
+            };
+        },
+        setPageIndex: search.setPageIndex,
+        setPageSize: search.setPageSize,
+    };
+}
+export function paginationSourceFromTable(table) {
+    return {
+        getPagination() {
+            const { pageIndex, pageSize } = table.getState().pagination;
+            const total = table.getRowCount();
+            return {
+                pageIndex,
+                pageSize,
+                total,
+                pageCount: pageSize > 0 ? Math.ceil(total / pageSize) : 0,
+            };
+        },
+        setPageIndex: (pageIndex) => table.setPageIndex(pageIndex),
+        setPageSize: (pageSize) => table.setPageSize(pageSize),
+    };
+}
+export function selectionSourceFromTable(table) {
+    return {
+        getSelectedRows: () => table.getSelectedRowModel().rows.map((row) => row.original),
+        selectAll: () => table.toggleAllRowsSelected(true),
+        deselectAll: () => table.toggleAllRowsSelected(false),
+        isAllSelected: () => table.getIsAllRowsSelected(),
+        isSomeSelected: () => table.getIsSomeRowsSelected(),
+    };
+}
+/** 컴포넌트 진입점에서 한 번 정규화한다 */
+export function toFilterSource(src) {
+    return isFilterSource(src) ? src : filterSourceFromTable(src);
+}
+export function toPaginationSource(src) {
+    return isPaginationSource(src) ? src : paginationSourceFromTable(src);
+}
+export function toSelectionSource(src) {
+    return isSelectionSource(src) ? src : selectionSourceFromTable(src);
+}
+/**
+ * 콘텐츠 구역 — 데이터에서 직접.
+ * 카드 그리드·차트처럼 테이블 인스턴스가 없는 화면이 쓰는 경로다.
+ */
+export function contentSource(data) {
+    return {
+        getRows: () => data.rows,
+        getStatus: () => ({
+            isLoading: data.isLoading,
+            isInitialLoading: data.isInitialLoading,
+            isError: data.isError,
+            error: data.error,
+            isEmpty: data.rows.length === 0,
+        }),
+        refetch: data.refetch,
+    };
+}
+/**
+ * 콘텐츠 구역 — 테이블 인스턴스에서.
+ * `useDataTable` 로 만든 인스턴스는 `data` 를 들고 있으므로 상태를 그대로 쓴다.
+ */
+export function contentSourceFromTable(table) {
+    const attached = table.data;
+    return {
+        getRows: () => table.getRowModel().rows.map((row) => row.original),
+        getStatus: () => ({
+            isLoading: attached?.isLoading ?? false,
+            isInitialLoading: attached?.isInitialLoading ?? false,
+            isError: attached?.isError ?? false,
+            error: attached?.error,
+            isEmpty: table.getRowModel().rows.length === 0,
+        }),
+        refetch: () => attached?.refetch(),
+    };
+}
+export function isContentSource(value) {
+    return typeof value?.getRows === "function";
+}
+export function toContentSource(src) {
+    return isContentSource(src) ? src : contentSourceFromTable(src);
+}
+/**
+ * 정렬 계약 — 검색 상태에서.
+ *
+ * 토글 순환은 TanStack 기본과 같다: 해제 -> 오름차순 -> 내림차순 -> 해제.
+ * `multi` 를 주면 기존 정렬을 유지한 채 뒤에 붙인다.
+ */
+export function sortSource(search) {
+    const current = () => search.params.sorting;
+    const columnSort = (columnId) => {
+        const index = current().findIndex((s) => s.id === columnId);
+        if (index < 0)
+            return null;
+        return { desc: current()[index].desc, index };
+    };
+    return {
+        getSort: current,
+        getColumnSort: columnSort,
+        toggleSort(columnId, options = {}) {
+            const existing = columnSort(columnId);
+            const others = options.multi ? current().filter((s) => s.id !== columnId) : [];
+            let next;
+            if (options.desc !== undefined) {
+                next = [...others, { id: columnId, desc: options.desc }];
+            }
+            else if (existing === null) {
+                next = [...others, { id: columnId, desc: false }];
+            }
+            else if (!existing.desc) {
+                next = [...others, { id: columnId, desc: true }];
+            }
+            else {
+                next = others; // 내림차순 다음은 해제
+            }
+            search.setSorting(next);
+        },
+        clearSort(columnId) {
+            search.setSorting(columnId ? current().filter((s) => s.id !== columnId) : []);
+        },
+    };
+}
+export function sortSourceFromTable(table) {
+    const attached = table.search;
+    if (attached)
+        return sortSource(attached);
+    return {
+        getSort: () => table.getState().sorting.map((s) => ({ id: s.id, desc: s.desc })),
+        getColumnSort(columnId) {
+            const index = table.getState().sorting.findIndex((s) => s.id === columnId);
+            if (index < 0)
+                return null;
+            return { desc: table.getState().sorting[index].desc, index };
+        },
+        toggleSort(columnId, options = {}) {
+            const column = table.getColumn(columnId);
+            if (!column)
+                return;
+            if (options.desc !== undefined)
+                column.toggleSorting(options.desc, options.multi);
+            else
+                column.toggleSorting(undefined, options.multi);
+        },
+        clearSort(columnId) {
+            if (columnId)
+                table.getColumn(columnId)?.clearSorting();
+            else
+                table.resetSorting(true);
+        },
+    };
+}
+export function isSortSource(value) {
+    return typeof value?.toggleSort === "function";
+}
+export function toSortSource(src) {
+    return isSortSource(src) ? src : sortSourceFromTable(src);
+}

package/dist/core/src/client/aggregate.d.ts

@@ -0,0 +1,94 @@
+import type { RowData } from "@tanstack/react-table";
+import type { ColumnDataType, TableColumnDefs } from "../types/column";
+import { type Registry } from "../registry";
+/**
+ * 내장 집계 함수 키 — 백엔드 `AGG_FUNCS` 와 이름을 맞춘다.
+ * 서버에 없는 것(`median`·`stddev`·`ratio`·`mode`)은 클라이언트 전용이다.
+ * `Record<AggFnKey, …>`(라벨·칩 색) 는 내장 키만 가진다.
+ */
+export type AggFnKey = "sum" | "avg" | "median" | "min" | "max" | "stddev" | "count_distinct" | "count_true" | "ratio" | "mode";
+/** `AggFnKey` 의 다른 이름 — 사용자 집계와 구분할 때 */
+export type BuiltinAggFnKey = AggFnKey;
+/**
+ * 집계 함수 id — 내장 키는 자동완성되고, 레지스트리에 등록한 사용자 집계(`p90` 등)는 문자열로 들어온다.
+ * 명세(`AggregationSpec`)·결과(`AggregateResult`)·칩은 이 타입을 쓴다.
+ */
+export type AggregationId = AggFnKey | (string & {});
+export interface AggregateContext {
+    /** `ratio` 계산 기준 — 전체 건수 */
+    totalCount?: number;
+    /** 집계 대상 컬럼 (`aggregateRows` 가 채운다) */
+    columnId?: string;
+}
+/**
+ * 집계 정의 — 설계 문서 4절. core 가 계산·적용 조건·라벨을 알고, mui 는 같은 id 로 칩·아이콘을 붙인다.
+ *
+ * - `applies(dataType)` — 어떤 컬럼 타입에 후보로 뜨는가 (`AggregationChips`·그룹 행 칩)
+ * - `compute(values, ctx)` — 클라이언트 모드 계산. NULL 은 SQL 처럼 무시하는 것이 규약
+ * - `server` — 백엔드가 계산할 수 있으면 true. 서버 그룹핑 화면은 이것만 고르게 한다
+ * - `format` — 칩에 찍을 문자열 (미지정 시 숫자 규칙: 정수 천 단위, 소수 2자리)
+ */
+export interface AggregationDef {
+    id: AggregationId;
+    label: string;
+    shortLabel: string;
+    applies: (dataType?: ColumnDataType) => boolean;
+    compute: (values: unknown[], ctx: AggregateContext) => unknown;
+    server?: boolean;
+    format?: (value: unknown) => string;
+}
+/** 정의 헬퍼 — 타입만 고정한다 (`as const` 불필요) */
+export declare function defineAggregation(def: AggregationDef): AggregationDef;
+/**
+ * 내장 집계 정의. 배열 순서가 칩·메뉴의 기본 순서다.
+ * `applies` 는 예전 `NUMERIC_AGG_KEYS`(number) / `ENUM_AGG_KEYS`(그 외) / boolean 후보와 같은 결과를 낸다.
+ */
+export declare const BUILTIN_AGGREGATIONS: readonly AggregationDef[];
+/**
+ * 전역 기본 레지스트리. 내장 세트가 들어 있고, `aggregations.register(def)` 로 앱 전체에 추가한다.
+ * 화면 단위로 바꾸려면 `aggregations.with({ add: [...] })` 결과를 `groupRows`/`useGrouping`/칩에 넘긴다
+ * (mui 는 `KokoTableProvider aggregations` 로 같은 일을 한다).
+ */
+export declare const aggregations: Registry<AggregationDef>;
+/** 내장 키인가 */
+export declare function isBuiltinAggregation(id: string): id is AggFnKey;
+/** `dataType` 에 뜨는 집계 키. `serverOnly` 면 서버가 계산할 수 있는 것만 */
+export declare function aggregationKeysFor(dataType: ColumnDataType | undefined, registry?: Registry<AggregationDef>, options?: {
+    serverOnly?: boolean;
+}): AggregationId[];
+/** 백엔드가 계산할 수 있는 집계 키 */
+export declare function serverAggregationKeys(registry?: Registry<AggregationDef>): AggregationId[];
+export declare function isServerAggregation(id: AggregationId, registry?: Registry<AggregationDef>): boolean;
+/** `{ id: label }` — `kind` 로 짧은 라벨을 고른다 */
+export declare function aggregationLabels(registry?: Registry<AggregationDef>, kind?: "label" | "shortLabel"): Record<AggregationId, string>;
+/** 라벨 하나 — 레지스트리에 없으면 id 그대로 */
+export declare function aggregationLabel(id: AggregationId, registry?: Registry<AggregationDef>, kind?: "label" | "shortLabel"): string;
+/** 숫자 컬럼에 뜨는 집계 (내장 세트 기준 — 동적 조회는 `aggregationKeysFor("number", registry)`) */
+export declare const NUMERIC_AGG_KEYS: AggFnKey[];
+/** enum/텍스트 컬럼에 뜨는 집계 (내장 세트 기준) */
+export declare const ENUM_AGG_KEYS: AggFnKey[];
+/** boolean 컬럼에 뜨는 집계 (내장 세트 기준) — "참인 개수" 가 본래 의미라 앞에 둔다 */
+export declare const BOOLEAN_AGG_KEYS: AggFnKey[];
+/** 백엔드가 실제로 계산할 수 있는 집계 (내장 세트 기준 — 동적 조회는 `serverAggregationKeys(registry)`) */
+export declare const SERVER_AGG_KEYS: AggFnKey[];
+export declare const AGG_LABELS: Record<AggFnKey, string>;
+export declare const AGG_SHORT_LABELS: Record<AggFnKey, string>;
+/** 컬럼 → 적용할 집계 함수들 (사용자 집계 id 포함) */
+export type AggregationSpec = Record<string, AggregationId[]>;
+/** 컬럼 하나의 `{ 함수: 값 }` — 내장 키는 자동완성, 사용자 집계는 문자열 키 */
+export type AggregateValues = Partial<Record<AggFnKey, unknown>> & Record<string, unknown>;
+/** `{ 컬럼: { 함수: 값 } }` — 서버 응답 `aggregates` 와 같은 모양 */
+export type AggregateResult = Record<string, AggregateValues>;
+/** 값 배열 하나에 집계 함수 하나를 적용한다. 레지스트리에 없는 함수는 `null` */
+export declare function aggregateValues(values: unknown[], fn: AggregationId, ctx?: AggregateContext, registry?: Registry<AggregationDef>): unknown;
+/**
+ * 컬럼 선언(`meta.enableAgg` + `meta.aggregations`)에서 집계 명세를 만든다.
+ *
+ * 그룹핑 요청의 `aggregation` 은 기존 `useTable` 이 컬럼의 `aggregationFn` 을 모아
+ * `{ 컬럼: [함수, …] }` 로 실었던 것과 같은 모양이다. `useTableSearch.request` 가
+ * `grouping` 이 있을 때 이 값을 싣고, `SearchState.aggregation` 이 명시돼 있으면
+ * 그쪽을 우선한다. 빈 명세면 `undefined` (요청에 키가 실리지 않는다).
+ */
+export declare function deriveAggregation<T extends RowData>(columns: TableColumnDefs<T>): AggregationSpec | undefined;
+/** 행 묶음에 집계 명세를 적용한다 */
+export declare function aggregateRows<T>(rows: T[], spec: AggregationSpec, ctx?: AggregateContext, registry?: Registry<AggregationDef>): AggregateResult;

package/dist/core/src/client/aggregate.js

@@ -0,0 +1,222 @@
+import { columnKey } from "../columns/deriveOperators";
+import { getValue } from "../utils/getValue";
+import { createRegistry } from "../registry";
+/** 정의 헬퍼 — 타입만 고정한다 (`as const` 불필요) */
+export function defineAggregation(def) {
+    return def;
+}
+// ─────────────────────────────────────────────────────────────
+// 내장 세트 — 같은 API 로 등록한다 (dogfooding)
+// ─────────────────────────────────────────────────────────────
+const numbers = (values) => {
+    const result = [];
+    for (const value of values) {
+        if (value === null || value === undefined || value === "")
+            continue;
+        const num = Number(value);
+        if (!Number.isNaN(num))
+            result.push(num);
+    }
+    return result;
+};
+/** NULL 은 SQL 집계와 마찬가지로 전부 무시한다 */
+const present = (values) => values.filter((v) => v !== null && v !== undefined);
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/** 표본 표준편차 (n-1). PostgreSQL `stddev` 와 같은 정의 */
+function stddev(values) {
+    if (values.length < 2)
+        return null;
+    const mean = values.reduce((a, b) => a + b, 0) / values.length;
+    const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / (values.length - 1);
+    return Math.sqrt(variance);
+}
+function mode(values) {
+    const counts = new Map();
+    for (const value of values) {
+        const key = String(value);
+        const entry = counts.get(key);
+        if (entry)
+            entry.count += 1;
+        else
+            counts.set(key, { value, count: 1 });
+    }
+    let best;
+    for (const entry of counts.values()) {
+        if (!best || entry.count > best.count)
+            best = entry;
+    }
+    return best?.value ?? null;
+}
+const isNumeric = (dataType) => dataType === "number";
+const isBoolean = (dataType) => dataType === "boolean";
+/** 숫자·boolean 이 아닌 것 — enum/select/text/date 와 타입 미지정 */
+const isCategorical = (dataType) => !isNumeric(dataType) && !isBoolean(dataType);
+const any = () => true;
+/**
+ * 내장 집계 정의. 배열 순서가 칩·메뉴의 기본 순서다.
+ * `applies` 는 예전 `NUMERIC_AGG_KEYS`(number) / `ENUM_AGG_KEYS`(그 외) / boolean 후보와 같은 결과를 낸다.
+ */
+export const BUILTIN_AGGREGATIONS = [
+    defineAggregation({
+        id: "sum", label: "합계", shortLabel: "합", applies: isNumeric, server: true,
+        compute: (values) => {
+            const nums = numbers(values);
+            return nums.length === 0 ? null : nums.reduce((a, b) => a + b, 0);
+        },
+    }),
+    defineAggregation({
+        id: "avg", label: "평균", shortLabel: "평균", applies: isNumeric, server: true,
+        compute: (values) => {
+            const nums = numbers(values);
+            return nums.length === 0 ? null : nums.reduce((a, b) => a + b, 0) / nums.length;
+        },
+    }),
+    defineAggregation({
+        id: "median", label: "중간값", shortLabel: "중앙", applies: isNumeric,
+        compute: (values) => median(numbers(values)),
+    }),
+    defineAggregation({
+        id: "min", label: "최소", shortLabel: "최소", applies: isNumeric, server: true,
+        compute: (values) => {
+            const nums = numbers(values);
+            if (nums.length > 0)
+                return Math.min(...nums);
+            const rest = present(values).map(String).sort();
+            return rest[0] ?? null;
+        },
+    }),
+    defineAggregation({
+        id: "max", label: "최대", shortLabel: "최대", applies: isNumeric, server: true,
+        compute: (values) => {
+            const nums = numbers(values);
+            if (nums.length > 0)
+                return Math.max(...nums);
+            const rest = present(values).map(String).sort();
+            return rest[rest.length - 1] ?? null;
+        },
+    }),
+    defineAggregation({
+        id: "stddev", label: "표준편차", shortLabel: "편차", applies: isNumeric,
+        compute: (values) => stddev(numbers(values)),
+    }),
+    defineAggregation({
+        id: "count_distinct", label: "고유", shortLabel: "고유", applies: any, server: true,
+        compute: (values) => new Set(present(values).map(String)).size,
+    }),
+    defineAggregation({
+        id: "count_true", label: "개수", shortLabel: "개수", applies: any, server: true,
+        // 백엔드는 boolean 을 정수로 캐스팅해 sum 한다 — 참인 행의 개수
+        compute: (values) => present(values).filter((v) => v === true || v === "true" || v === 1 || v === "1").length,
+    }),
+    defineAggregation({
+        id: "ratio", label: "점유율", shortLabel: "점유", applies: any,
+        compute: (values, ctx) => {
+            const total = ctx.totalCount ?? 0;
+            return total === 0 ? null : present(values).length / total;
+        },
+        format: (value) => typeof value === "number" && Number.isFinite(value)
+            ? `${(value * 100).toLocaleString("ko-KR", { maximumFractionDigits: 1 })}%`
+            : value === null || value === undefined ? "" : String(value),
+    }),
+    defineAggregation({
+        id: "mode", label: "최빈값", shortLabel: "최빈", applies: isCategorical,
+        compute: (values) => mode(present(values)),
+    }),
+];
+/**
+ * 전역 기본 레지스트리. 내장 세트가 들어 있고, `aggregations.register(def)` 로 앱 전체에 추가한다.
+ * 화면 단위로 바꾸려면 `aggregations.with({ add: [...] })` 결과를 `groupRows`/`useGrouping`/칩에 넘긴다
+ * (mui 는 `KokoTableProvider aggregations` 로 같은 일을 한다).
+ */
+export const aggregations = createRegistry([...BUILTIN_AGGREGATIONS]);
+/** 내장 키인가 */
+export function isBuiltinAggregation(id) {
+    return BUILTIN_AGGREGATIONS.some((def) => def.id === id);
+}
+// ─────────────────────────────────────────────────────────────
+// 레지스트리에서 파생하는 조회 — 이름은 예전 상수와 호환
+// ─────────────────────────────────────────────────────────────
+/** `dataType` 에 뜨는 집계 키. `serverOnly` 면 서버가 계산할 수 있는 것만 */
+export function aggregationKeysFor(dataType, registry = aggregations, options = {}) {
+    return registry.list()
+        .filter((def) => def.applies(dataType) && (!options.serverOnly || def.server))
+        .map((def) => def.id);
+}
+/** 백엔드가 계산할 수 있는 집계 키 */
+export function serverAggregationKeys(registry = aggregations) {
+    return registry.list().filter((def) => def.server).map((def) => def.id);
+}
+export function isServerAggregation(id, registry = aggregations) {
+    return !!registry.get(id)?.server;
+}
+/** `{ id: label }` — `kind` 로 짧은 라벨을 고른다 */
+export function aggregationLabels(registry = aggregations, kind = "label") {
+    const result = {};
+    for (const def of registry.list())
+        result[def.id] = def[kind];
+    return result;
+}
+/** 라벨 하나 — 레지스트리에 없으면 id 그대로 */
+export function aggregationLabel(id, registry = aggregations, kind = "label") {
+    return registry.get(id)?.[kind] ?? id;
+}
+const builtins = createRegistry([...BUILTIN_AGGREGATIONS]);
+/** 숫자 컬럼에 뜨는 집계 (내장 세트 기준 — 동적 조회는 `aggregationKeysFor("number", registry)`) */
+export const NUMERIC_AGG_KEYS = aggregationKeysFor("number", builtins);
+/** enum/텍스트 컬럼에 뜨는 집계 (내장 세트 기준) */
+export const ENUM_AGG_KEYS = aggregationKeysFor("enum", builtins);
+/** boolean 컬럼에 뜨는 집계 (내장 세트 기준) — "참인 개수" 가 본래 의미라 앞에 둔다 */
+export const BOOLEAN_AGG_KEYS = ["count_true", "count_distinct", "ratio"];
+/** 백엔드가 실제로 계산할 수 있는 집계 (내장 세트 기준 — 동적 조회는 `serverAggregationKeys(registry)`) */
+export const SERVER_AGG_KEYS = serverAggregationKeys(builtins);
+export const AGG_LABELS = aggregationLabels(builtins, "label");
+export const AGG_SHORT_LABELS = aggregationLabels(builtins, "shortLabel");
+/** 값 배열 하나에 집계 함수 하나를 적용한다. 레지스트리에 없는 함수는 `null` */
+export function aggregateValues(values, fn, ctx = {}, registry = aggregations) {
+    const def = registry.get(fn);
+    return def ? def.compute(values, ctx) : null;
+}
+/**
+ * 컬럼 선언(`meta.enableAgg` + `meta.aggregations`)에서 집계 명세를 만든다.
+ *
+ * 그룹핑 요청의 `aggregation` 은 기존 `useTable` 이 컬럼의 `aggregationFn` 을 모아
+ * `{ 컬럼: [함수, …] }` 로 실었던 것과 같은 모양이다. `useTableSearch.request` 가
+ * `grouping` 이 있을 때 이 값을 싣고, `SearchState.aggregation` 이 명시돼 있으면
+ * 그쪽을 우선한다. 빈 명세면 `undefined` (요청에 키가 실리지 않는다).
+ */
+export function deriveAggregation(columns) {
+    const result = {};
+    for (const column of columns) {
+        const meta = column.meta;
+        if (!meta?.enableAgg)
+            continue;
+        const key = columnKey(column);
+        if (!key)
+            continue;
+        const fns = (meta.aggregations ?? []).filter((fn) => typeof fn === "string" && fn !== "");
+        if (fns.length === 0)
+            continue;
+        result[key] = fns;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/** 행 묶음에 집계 명세를 적용한다 */
+export function aggregateRows(rows, spec, ctx = {}, registry = aggregations) {
+    const result = {};
+    for (const [columnId, fns] of Object.entries(spec)) {
+        if (!fns || fns.length === 0)
+            continue;
+        const values = rows.map((row) => getValue(row, columnId));
+        const perColumn = {};
+        for (const fn of fns)
+            perColumn[fn] = aggregateValues(values, fn, { ...ctx, columnId }, registry);
+        result[columnId] = perColumn;
+    }
+    return result;
+}

package/dist/core/src/client/groupRows.d.ts

@@ -0,0 +1,40 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { FlatItem, GroupTreeNode } from "../types/grouping";
+import { type LabelResolver } from "../columns/labels";
+import { type AggregationDef, type AggregationSpec } from "./aggregate";
+import type { Registry } from "../registry";
+export interface GroupOptions<T extends RowData> {
+    /** 상위 → 하위 순서의 그룹 컬럼 */
+    grouping: string[];
+    columns?: TableColumnDefs<T>;
+    aggregation?: AggregationSpec;
+    /** 그룹 값 → 라벨. 미지정 시 컬럼의 `selectOptions` 에서 찾는다 */
+    labelOf?: LabelResolver;
+    /** 집계 레지스트리 — 미지정 시 전역 `aggregations` (Provider 로 등록한 것은 여기로 넘긴다) */
+    aggregations?: Registry<AggregationDef>;
+}
+/**
+ * 행을 그룹 트리로 묶는다.
+ *
+ * 그룹 순서는 **값 오름차순**이고 NULL 이 뒤로 간다 — 정렬 규칙(`applySorting`)과
+ * 같은 규약이라 그룹을 켰다 껐을 때 순서가 뒤집히지 않는다.
+ */
+export declare function groupRows<T extends RowData>(rows: T[], options: GroupOptions<T>): Array<GroupTreeNode<T>>;
+/** 트리의 최대 깊이 (그룹 레벨 수) */
+export declare function groupDepth<T>(nodes: Array<GroupTreeNode<T>>): number;
+export interface FlattenOptions {
+    /** 펼쳐진 경로 키 집합 */
+    expanded: Set<string>;
+    /** 말단 행까지 그릴지 — 그룹 헤더만 필요한 화면은 false */
+    includeLeaves?: boolean;
+}
+/**
+ * 트리를 화면 순서대로 평탄화한다. 접힌 그룹의 하위는 건너뛴다.
+ * 가상화 리스트가 그대로 소비할 수 있는 형태다.
+ */
+export declare function flattenGroups<T extends RowData>(nodes: Array<GroupTreeNode<T>>, options: FlattenOptions): Array<FlatItem<T>>;
+/** 트리 전체의 경로 키 — expandAll 용 */
+export declare function allGroupPaths<T>(nodes: Array<GroupTreeNode<T>>): string[];
+/** 특정 깊이까지의 경로 키 — 단계 펼치기 용 */
+export declare function pathsToDepth<T>(nodes: Array<GroupTreeNode<T>>, depth: number): string[];