kokotable 0.95.0

package/dist/core/src/hooks/useGrouping.js

@@ -0,0 +1,57 @@
+import { useCallback, useMemo, useState } from "react";
+import { pathKey } from "../types/grouping";
+import { allGroupPaths, flattenGroups, groupDepth, groupRows, pathsToDepth, } from "../client/groupRows";
+/**
+ * 클라이언트 그룹핑 — 이미 필터·정렬이 끝난 행을 트리로 묶는다.
+ *
+ * 서버 그룹핑(`groupExpansion` — 최상위 `path: []` / 경로 확장)과 결과 모양을 맞춰 두었기
+ * 때문에, 나중에 서버 모드를 붙여도 렌더러는 그대로 쓸 수 있다.
+ */
+export function useGrouping(options) {
+    const { rows, columns, grouping, aggregation, aggregations, labelOf, initialExpanded = false, includeLeaves = true, } = options;
+    const enabled = grouping.length > 0;
+    const tree = useMemo(() => (enabled ? groupRows(rows, { grouping, columns, aggregation, aggregations, labelOf }) : []), [enabled, rows, grouping, columns, aggregation, aggregations, labelOf]);
+    const maxDepth = useMemo(() => groupDepth(tree), [tree]);
+    // 초기 펼침은 트리가 처음 생길 때 한 번만 반영한다 — 매 렌더 계산하면
+    // 사용자가 접은 그룹이 데이터 갱신마다 다시 펼쳐진다.
+    const [expandedKeys, setExpandedKeys] = useState(null);
+    const resolvedExpanded = useMemo(() => {
+        if (expandedKeys !== null)
+            return expandedKeys;
+        return initialExpanded ? new Set(allGroupPaths(tree)) : new Set();
+    }, [expandedKeys, initialExpanded, tree]);
+    const currentDepth = useMemo(() => {
+        if (resolvedExpanded.size === 0)
+            return 0;
+        for (let depth = maxDepth; depth >= 1; depth -= 1) {
+            const needed = pathsToDepth(tree, depth);
+            if (needed.every((key) => resolvedExpanded.has(key)))
+                return depth;
+        }
+        return 0;
+    }, [resolvedExpanded, tree, maxDepth]);
+    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);
+            return next;
+        });
+    }, []);
+    const expandToDepth = useCallback((depth) => setExpandedKeys(new Set(pathsToDepth(tree, depth))), [tree]);
+    const expand = useMemo(() => ({
+        isExpanded: (path) => resolvedExpanded.has(pathKey(path)),
+        toggle,
+        expandAll: () => setExpandedKeys(new Set(allGroupPaths(tree))),
+        collapseAll: () => setExpandedKeys(new Set()),
+        expandToDepth,
+        depth: currentDepth,
+        maxDepth,
+        canExpand: maxDepth > 0,
+    }), [resolvedExpanded, toggle, tree, expandToDepth, currentDepth, maxDepth]);
+    const items = useMemo(() => (enabled ? flattenGroups(tree, { expanded: resolvedExpanded, includeLeaves }) : []), [enabled, tree, resolvedExpanded, includeLeaves]);
+    return { tree, items, expand, enabled };
+}

package/dist/core/src/hooks/useSearchHistory.d.ts

@@ -0,0 +1,20 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableSearch } from "../types/search";
+export interface SearchHistory {
+    back: () => void;
+    forward: () => void;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    size: number;
+}
+export interface UseSearchHistoryOptions {
+    /** 보관할 최대 항목 수 */
+    limit?: number;
+}
+/**
+ * 검색 조건 히스토리 애드온 — 적용된 조건(`params`)만 기록한다.
+ *
+ * 뒤로/앞으로 이동해서 생긴 변경은 기록하지 않는다. 기록하면 되돌아간 지점이
+ * 다시 스택 맨 위로 쌓여 앞으로 가기가 영영 살아나지 않는다.
+ */
+export declare function useSearchHistory<T extends RowData>(search: TableSearch<T>, options?: UseSearchHistoryOptions): SearchHistory;

package/dist/core/src/hooks/useSearchHistory.js

@@ -0,0 +1,52 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+const sameState = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * 검색 조건 히스토리 애드온 — 적용된 조건(`params`)만 기록한다.
+ *
+ * 뒤로/앞으로 이동해서 생긴 변경은 기록하지 않는다. 기록하면 되돌아간 지점이
+ * 다시 스택 맨 위로 쌓여 앞으로 가기가 영영 살아나지 않는다.
+ */
+export function useSearchHistory(search, options = {}) {
+    const { limit = 50 } = options;
+    const stackRef = useRef([search.params]);
+    const indexRef = useRef(0);
+    const navigatingRef = useRef(false);
+    const [version, setVersion] = useState(0);
+    const searchRef = useRef(search);
+    searchRef.current = search;
+    useEffect(() => {
+        if (navigatingRef.current) {
+            navigatingRef.current = false;
+            return;
+        }
+        const current = stackRef.current[indexRef.current];
+        if (current && sameState(current, search.params))
+            return;
+        // 새 조건은 현재 위치 뒤를 잘라내고 쌓는다 (브라우저 히스토리와 같은 규약)
+        const next = [...stackRef.current.slice(0, indexRef.current + 1), search.params];
+        const trimmed = next.length > limit ? next.slice(next.length - limit) : next;
+        stackRef.current = trimmed;
+        indexRef.current = trimmed.length - 1;
+        setVersion((v) => v + 1);
+    }, [search.params, limit]);
+    const go = useCallback((delta) => {
+        const target = indexRef.current + delta;
+        const state = stackRef.current[target];
+        if (!state)
+            return;
+        indexRef.current = target;
+        navigatingRef.current = true;
+        searchRef.current.setParams(state);
+        setVersion((v) => v + 1);
+    }, []);
+    const back = useCallback(() => go(-1), [go]);
+    const forward = useCallback(() => go(1), [go]);
+    void version; // 스택은 ref 에 있으므로 리렌더 트리거용으로만 쓴다
+    return {
+        back,
+        forward,
+        canGoBack: indexRef.current > 0,
+        canGoForward: indexRef.current < stackRef.current.length - 1,
+        size: stackRef.current.length,
+    };
+}

package/dist/core/src/hooks/useTableData.d.ts

@@ -0,0 +1,25 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { TableData, TableDataOptions, TableMode } from "../types/data";
+import { type ClientQueryOptions } from "../client/runClientQuery";
+export interface UseTableDataOptions<T extends RowData> extends TableDataOptions<T>, ClientQueryOptions<T> {
+    /** 클라이언트 모드 필터링에 쓸 컬럼 정의 */
+    columns: TableColumnDefs<T>;
+}
+/** `mode` 미지정 시의 판정 — 기존 `useTableQuery` 규칙과 같다 */
+export declare function resolveMode<T extends RowData>(options: TableDataOptions<T>): TableMode;
+/**
+ * 2층 — 데이터. **테이블 인스턴스를 만들지 않는다.**
+ *
+ * 지금은 클라이언트 모드만 구현돼 있다. 서버 모드는 요청 캐싱·취소가 필요해
+ * `kokotable/query`(react-query 어댑터)로 분리하며, 코어는 의존성 0 을 유지한다.
+ *
+ * 파이프라인은 두 단계로 메모이즈한다. `request` 는 페이지만 넘겨도 새 객체가 되므로
+ * 통째로 의존하면 페이지 이동마다 필터·정렬(50k 행이면 수십 ms)을 다시 돌린다.
+ * 필터·전역검색·정렬에 관여하는 필드만 1단계의 의존성으로 두고, 2단계는 슬라이스만 한다.
+ * (`useTableSearch` 는 페이지 이동 시 `columnFilters`/`sorting` 의 참조를 유지한다.)
+ *
+ * `now` 는 `inPeriod` 의 기준 시각이다. 서버는 서버 시각(KST)으로 계산하므로
+ * 브라우저 시간대가 다르면 경계가 어긋날 수 있다 — 맞춰야 하면 주입한다.
+ */
+export declare function useTableData<T extends RowData>(options: UseTableDataOptions<T>): TableData<T>;

package/dist/core/src/hooks/useTableData.js

@@ -0,0 +1,49 @@
+import { useMemo } from "react";
+import { filterAndSortRows, paginateRows, } from "../client/runClientQuery";
+/** `mode` 미지정 시의 판정 — 기존 `useTableQuery` 규칙과 같다 */
+export function resolveMode(options) {
+    if (options.mode)
+        return options.mode;
+    return options.queryFn ? "server" : "client";
+}
+const noop = () => { };
+const EMPTY_ROWS = [];
+/**
+ * 2층 — 데이터. **테이블 인스턴스를 만들지 않는다.**
+ *
+ * 지금은 클라이언트 모드만 구현돼 있다. 서버 모드는 요청 캐싱·취소가 필요해
+ * `kokotable/query`(react-query 어댑터)로 분리하며, 코어는 의존성 0 을 유지한다.
+ *
+ * 파이프라인은 두 단계로 메모이즈한다. `request` 는 페이지만 넘겨도 새 객체가 되므로
+ * 통째로 의존하면 페이지 이동마다 필터·정렬(50k 행이면 수십 ms)을 다시 돌린다.
+ * 필터·전역검색·정렬에 관여하는 필드만 1단계의 의존성으로 두고, 2단계는 슬라이스만 한다.
+ * (`useTableSearch` 는 페이지 이동 시 `columnFilters`/`sorting` 의 참조를 유지한다.)
+ *
+ * `now` 는 `inPeriod` 의 기준 시각이다. 서버는 서버 시각(KST)으로 계산하므로
+ * 브라우저 시간대가 다르면 경계가 어긋날 수 있다 — 맞춰야 하면 주입한다.
+ */
+export function useTableData(options) {
+    const { columns, request, data, now, globalFilterFields } = options;
+    const mode = resolveMode(options);
+    const { columnFilters, columnFilterFns, globalFilter, sorting, pagination } = request;
+    // 훅 호출은 조건 없이 — 모드 판정보다 먼저 실행돼야 순서가 흔들리지 않는다
+    const filtered = useMemo(() => filterAndSortRows(data ?? EMPTY_ROWS, columns, { columnFilters, columnFilterFns, globalFilter, sorting }, { now, globalFilterFields }), [data, columns, columnFilters, columnFilterFns, globalFilter, sorting, now, globalFilterFields]);
+    const rows = useMemo(() => paginateRows(filtered, pagination), [filtered, pagination]);
+    const value = useMemo(() => ({
+        rows,
+        total: filtered.length,
+        meta: { total_count: filtered.length },
+        groups: null,
+        isLoading: false,
+        isInitialLoading: false,
+        isError: false,
+        error: undefined,
+        refetch: noop,
+        mode: "client",
+    }), [rows, filtered]);
+    if (mode === "server") {
+        throw new Error("[koko-table] 서버 모드는 코어에 없습니다 (코어는 의존성 0 을 유지한다). " +
+            'kokotable/query 의 useServerTableData 를 쓰거나 mode: "client" 로 두세요.');
+    }
+    return value;
+}

package/dist/core/src/hooks/useTableFromDefinition.d.ts

@@ -0,0 +1,47 @@
+import type { RowData, TableOptions } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { TableData } from "../types/data";
+import type { DataTable } from "../types/table";
+import type { TableSearch } from "../types/search";
+import type { TableBundle, TableDefinition } from "../types/definition";
+import { type UrlSync } from "./useUrlSync";
+import { type SearchHistory } from "./useSearchHistory";
+export interface DefinitionSearch<T extends RowData> {
+    search: TableSearch<T>;
+    urlSync?: UrlSync;
+    history?: SearchHistory;
+}
+/**
+ * 1층 + 애드온 — 정의에서 검색 상태·URL 동기화·이력을 만든다.
+ * 클라이언트(`useTableFromDefinition`)와 서버(`useServerTable`) 조립이 공유하는 부분이다.
+ */
+export declare function useDefinitionSearch<T extends RowData>(definition: TableDefinition<T>): DefinitionSearch<T>;
+/**
+ * `features` → TanStack 옵션. `definition.tableOptions` 가 위에 덮이고 `getRowId` 는 정의가 우선한다.
+ */
+export declare function definitionTableOptions<T extends RowData>(definition: TableDefinition<T>): Partial<TableOptions<T>>;
+export interface UseDefinitionTableOptions<T extends RowData> {
+    definition: TableDefinition<T>;
+    search: TableSearch<T>;
+    data: TableData<T>;
+}
+export interface DefinitionTable<T extends RowData> {
+    table: DataTable<T>;
+    tableColumns: TableColumnDefs<T>;
+    setTableColumns: (columns: TableColumnDefs<T> | null) => void;
+}
+/**
+ * 3층 — 정의의 `features`/`getRowId`/`tableOptions` 로 TanStack 인스턴스를 만든다.
+ *
+ * 표시 전용 열(선택·확장·번호·액션)과 가상 컬럼은 렌더러 패키지가 만든다(코어는 MUI 를 모른다).
+ * 그래서 컬럼 목록을 **등록하는 자리**(`setTableColumns`)를 둔다 — `TableScreen` 이 마운트 시
+ * `withDisplayColumns(...)` 결과를 넣고, 직접 조립하는 화면은 원하는 목록을 넣는다.
+ */
+export declare function useDefinitionTable<T extends RowData>(options: UseDefinitionTableOptions<T>): DefinitionTable<T>;
+/**
+ * 클라이언트 모드 조립 — `useTableSearch` → `useTableData` → `useGrouping` → `useDataTable` + URL 동기화.
+ *
+ * 서버 모드 정의는 `kokotable/query` 의 `useServerTable(definition)` 으로 조립한다 (코어는 의존성 0).
+ * 반환값은 의존성이 바뀔 때만 새 객체다.
+ */
+export declare function useTableFromDefinition<T extends RowData>(definition: TableDefinition<T>): TableBundle<T>;

package/dist/core/src/hooks/useTableFromDefinition.js

@@ -0,0 +1,174 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { resolveDefinitionMode } from "../types/definition";
+import { runClientQuery } from "../client/runClientQuery";
+import { PAGE_SIZE_ALL } from "../defaults";
+import { useTableSearch } from "./useTableSearch";
+import { useTableData } from "./useTableData";
+import { useDataTable } from "./useDataTable";
+import { useGrouping } from "./useGrouping";
+import { readUrlSearchState, useUrlSync } from "./useUrlSync";
+import { useSearchHistory } from "./useSearchHistory";
+/** 비어 있는 그룹 배열의 고정 참조 — 렌더마다 새 배열이면 그룹 트리 메모가 매번 무효화된다 */
+const EMPTY_GROUPING = [];
+/**
+ * 정의의 검색 초기값 — `initial` 위에 `grouping.initial/aggregation` 을 깔고,
+ * URL 동기화가 켜져 있으면 주소창의 값이 마지막에 덮는다 (공유 링크가 기본값을 이긴다).
+ */
+function resolveInitialSearch(definition) {
+    let initial = definition.initial;
+    const grouping = definition.grouping;
+    if (grouping?.initial && initial?.grouping === undefined) {
+        initial = { ...initial, grouping: [...grouping.initial] };
+    }
+    if (grouping?.aggregation && initial?.aggregation === undefined) {
+        initial = { ...initial, aggregation: grouping.aggregation };
+    }
+    if (definition.urlSync) {
+        const options = typeof definition.urlSync === "object" ? definition.urlSync : {};
+        const fromUrl = readUrlSearchState({ ...options, columns: definition.columns });
+        if (fromUrl)
+            initial = { ...initial, ...fromUrl };
+    }
+    return initial;
+}
+/**
+ * 1층 + 애드온 — 정의에서 검색 상태·URL 동기화·이력을 만든다.
+ * 클라이언트(`useTableFromDefinition`)와 서버(`useServerTable`) 조립이 공유하는 부분이다.
+ */
+export function useDefinitionSearch(definition) {
+    // 초기값은 마운트 시 한 번만 계산한다 — URL 읽기가 렌더마다 돌면 popstate 복원과 경쟁한다
+    const initialRef = useRef(null);
+    if (initialRef.current === null)
+        initialRef.current = { value: resolveInitialSearch(definition) };
+    const searchOptions = {
+        columns: definition.columns,
+        initial: initialRef.current.value,
+        initialOperators: definition.initialOperators,
+    };
+    // `TableSearchOptions.debounceMs` 는 1층이 지원할 때만 의미가 있다 — 없으면 무시된다
+    if (definition.debounceMs !== undefined)
+        searchOptions.debounceMs = definition.debounceMs;
+    const search = useTableSearch(searchOptions);
+    const urlOptions = definition.urlSync
+        ? (typeof definition.urlSync === "object" ? definition.urlSync : {})
+        : undefined;
+    const urlSync = useUrlSync(search, {
+        enabled: !!urlOptions,
+        paramKey: urlOptions?.paramKey,
+        legacyParamKeys: urlOptions?.legacyParamKeys,
+    });
+    const historyLimit = typeof definition.history === "object" ? definition.history.limit : undefined;
+    const history = useSearchHistory(search, { limit: historyLimit });
+    return useMemo(() => ({
+        search,
+        urlSync: urlOptions ? urlSync : undefined,
+        history: definition.history ? history : undefined,
+    }), [search, urlSync, history, !!urlOptions, !!definition.history]);
+}
+/**
+ * `features` → TanStack 옵션. `definition.tableOptions` 가 위에 덮이고 `getRowId` 는 정의가 우선한다.
+ */
+export function definitionTableOptions(definition) {
+    const features = definition.features ?? {};
+    const options = {};
+    if (features.selection) {
+        const selection = typeof features.selection === "object" ? features.selection : {};
+        options.enableRowSelection = selection.canSelect ?? true;
+        if (selection.multi === false)
+            options.enableMultiRowSelection = false;
+    }
+    if (features.expand && typeof features.expand === "object" && features.expand.canExpand) {
+        options.getRowCanExpand = features.expand.canExpand;
+    }
+    const merged = { ...options, ...definition.tableOptions };
+    if (definition.getRowId)
+        merged.getRowId = definition.getRowId;
+    return merged;
+}
+/**
+ * 3층 — 정의의 `features`/`getRowId`/`tableOptions` 로 TanStack 인스턴스를 만든다.
+ *
+ * 표시 전용 열(선택·확장·번호·액션)과 가상 컬럼은 렌더러 패키지가 만든다(코어는 MUI 를 모른다).
+ * 그래서 컬럼 목록을 **등록하는 자리**(`setTableColumns`)를 둔다 — `TableScreen` 이 마운트 시
+ * `withDisplayColumns(...)` 결과를 넣고, 직접 조립하는 화면은 원하는 목록을 넣는다.
+ */
+export function useDefinitionTable(options) {
+    const { definition, search, data } = options;
+    const [registered, setRegistered] = useState(null);
+    const tableColumns = registered ?? definition.columns;
+    const setTableColumns = useCallback((columns) => {
+        setRegistered((prev) => (prev === columns ? prev : columns));
+    }, []);
+    const tableOptions = useMemo(() => definitionTableOptions(definition), [definition]);
+    const table = useDataTable({
+        columns: tableColumns,
+        search,
+        data,
+        fieldErrors: definition.fieldErrors,
+        tableOptions,
+    });
+    return useMemo(() => ({ table, tableColumns, setTableColumns }), [table, tableColumns, setTableColumns]);
+}
+/**
+ * 클라이언트 모드 조립 — `useTableSearch` → `useTableData` → `useGrouping` → `useDataTable` + URL 동기화.
+ *
+ * 서버 모드 정의는 `kokotable/query` 의 `useServerTable(definition)` 으로 조립한다 (코어는 의존성 0).
+ * 반환값은 의존성이 바뀔 때만 새 객체다.
+ */
+export function useTableFromDefinition(definition) {
+    const mode = resolveDefinitionMode(definition);
+    if (mode === "server") {
+        throw new Error(`[koko-table] useTableFromDefinition("${definition.key}"): 서버 모드 정의는 ` +
+            "kokotable/query 의 useServerTable(definition) 으로 조립하세요.");
+    }
+    const { search, urlSync, history } = useDefinitionSearch(definition);
+    const data = useTableData({
+        columns: definition.columns,
+        request: search.request,
+        data: definition.data,
+        mode: "client",
+        now: definition.now,
+        globalFilterFields: definition.globalFilterFields,
+    });
+    const groupingEnabled = !!definition.grouping?.enabled;
+    const groupingColumns = groupingEnabled ? (search.params.grouping ?? EMPTY_GROUPING) : EMPTY_GROUPING;
+    const group = useGrouping({
+        rows: data.rows,
+        columns: definition.columns,
+        grouping: groupingColumns,
+        // 요청에 실리는 것과 같은 명세 — 서버 모드와 집계 기준이 같아진다
+        aggregation: search.request.aggregation,
+        initialExpanded: definition.grouping?.initialExpanded,
+    });
+    const { table, tableColumns, setTableColumns } = useDefinitionTable({ definition, search, data });
+    const fetchAllRows = useCallback(async () => {
+        const { filtered } = runClientQuery(definition.data ?? [], definition.columns, { ...search.request, pagination: { pageIndex: 0, pageSize: PAGE_SIZE_ALL } }, { now: definition.now, globalFilterFields: definition.globalFilterFields });
+        return filtered;
+    }, [definition.data, definition.columns, definition.now, definition.globalFilterFields, search.request]);
+    const grouping = useMemo(() => {
+        if (!groupingEnabled)
+            return undefined;
+        return {
+            enabled: group.enabled,
+            grouping: groupingColumns,
+            setGrouping: search.setGrouping,
+            items: group.items,
+            expand: group.expand,
+            rows: data.rows,
+        };
+    }, [groupingEnabled, group.enabled, group.items, group.expand, groupingColumns, search.setGrouping, data.rows]);
+    return useMemo(() => ({
+        definition,
+        mode: "client",
+        search,
+        data,
+        table,
+        grouping,
+        urlSync,
+        history,
+        request: search.request,
+        tableColumns,
+        setTableColumns,
+        fetchAllRows,
+    }), [definition, search, data, table, grouping, urlSync, history, tableColumns, setTableColumns, fetchAllRows]);
+}

package/dist/core/src/hooks/useTableSearch.d.ts

@@ -0,0 +1,10 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableSearch, TableSearchOptions } from "../types/search";
+/**
+ * 1층 — 검색 상태. **테이블 인스턴스를 만들지 않는다.**
+ *
+ * 반환값이 `FilterSource` 를 만족하므로 필터 패널이 테이블 없이 바로 붙는다.
+ * 페이지네이션 UI 는 총 건수가 필요하므로 `paginationSource(search, data)` 로
+ * 2층과 합쳐 넘긴다.
+ */
+export declare function useTableSearch<T extends RowData>(options: TableSearchOptions<T>): TableSearch<T>;