kokotable 0.95.0

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

@@ -0,0 +1,20 @@
+import type { UseQueryResult } from "@tanstack/react-query";
+import type { RowData } from "@tanstack/react-table";
+import type { TableBundle, TableDefinition, TableResponse } from "../../core/src/index";
+export interface ServerTableBundle<T extends RowData> extends TableBundle<T> {
+    readonly mode: "server";
+    /** react-query 결과 — 무효화·수동 재시도 등 */
+    query: UseQueryResult<TableResponse<T>, Error>;
+}
+/**
+ * 서버 모드 조립 — 1층·3층·애드온은 코어(`useDefinitionSearch` / `useDefinitionTable`)를 그대로 쓰고,
+ * 2층만 `useServerTableData` + `useServerGrouping` 으로 바꿔 끼운다.
+ *
+ * 그룹 컬럼이 있으면 **최상위 그룹 노드부터** 받고(`groupExpansion: { path: [] … }` — 서버 응답
+ * `groups.nodes`), 펼칠 때 그 경로의 `groupExpansion` 으로 하위를 배치 단위로 받는다.
+ * 그때 3층에는 펼쳐서 받은 말단 행(`grouping.rows`)이 실린다.
+ *
+ * 반환 모양은 클라이언트 조립(`useTableFromDefinition`)과 같은 `TableBundle` 이라
+ * `<TableScreen bundle={…} />` 이 어느 쪽인지 몰라도 된다.
+ */
+export declare function useServerTable<T extends RowData>(definition: TableDefinition<T>): ServerTableBundle<T>;

package/dist/query/src/useServerTable.js

@@ -0,0 +1,106 @@
+import { useCallback, useMemo, useState } from "react";
+import { PAGE_SIZE_ALL, DEFAULT_GROUP_BATCH_SIZE, resolveDefinitionMode, useDefinitionSearch, useDefinitionTable, } from "../../core/src/index";
+import { useServerTableData } from "./useServerTableData";
+import { useServerGrouping } from "./useServerGrouping";
+const EMPTY_GROUPING = [];
+/**
+ * 서버 모드 조립 — 1층·3층·애드온은 코어(`useDefinitionSearch` / `useDefinitionTable`)를 그대로 쓰고,
+ * 2층만 `useServerTableData` + `useServerGrouping` 으로 바꿔 끼운다.
+ *
+ * 그룹 컬럼이 있으면 **최상위 그룹 노드부터** 받고(`groupExpansion: { path: [] … }` — 서버 응답
+ * `groups.nodes`), 펼칠 때 그 경로의 `groupExpansion` 으로 하위를 배치 단위로 받는다.
+ * 그때 3층에는 펼쳐서 받은 말단 행(`grouping.rows`)이 실린다.
+ *
+ * 반환 모양은 클라이언트 조립(`useTableFromDefinition`)과 같은 `TableBundle` 이라
+ * `<TableScreen bundle={…} />` 이 어느 쪽인지 몰라도 된다.
+ */
+export function useServerTable(definition) {
+    const server = definition.server;
+    if (resolveDefinitionMode(definition) !== "server" || !server) {
+        throw new Error(`[koko-table] useServerTable("${definition.key}"): 서버 모드 정의(\`server.queryFn\`)가 아닙니다 — ` +
+            "클라이언트 모드는 kokotable 의 useTableFromDefinition 을 쓰세요.");
+    }
+    const { search, urlSync, history } = useDefinitionSearch(definition);
+    // 응답 가공은 목록·그룹 확장·전체 조회가 같은 함수를 거친다
+    const rawQueryFn = server.queryFn;
+    const transform = server.transformResponse;
+    const queryFn = useMemo(() => (transform
+        ? async (request, context) => transform(await rawQueryFn(request, context), request)
+        : rawQueryFn), [rawQueryFn, transform]);
+    const groupingEnabled = !!definition.grouping?.enabled;
+    const groupingColumns = groupingEnabled ? (search.params.grouping ?? EMPTY_GROUPING) : EMPTY_GROUPING;
+    const grouped = groupingColumns.length > 0;
+    const [batchSize, setBatchSize] = useState(definition.grouping?.batchSize ?? DEFAULT_GROUP_BATCH_SIZE);
+    const queryKey = useMemo(() => [definition.key, ...(server.queryKey ?? [])], [definition.key, server.queryKey]);
+    const serverData = useServerTableData({
+        request: search.request,
+        queryFn,
+        queryKey,
+        enabled: server.enabled,
+        staleTime: server.staleTime,
+        keepPreviousData: server.keepPreviousData,
+        refetchInterval: server.refetchInterval,
+        retry: server.retry,
+    });
+    const group = useServerGrouping({
+        request: search.request,
+        queryFn,
+        grouping: groupingColumns,
+        columns: definition.columns,
+        headers: serverData.groups,
+        batchSize,
+    });
+    // 그룹 노드 응답은 `data` 가 비어 있다 — 펼쳐서 받아 온 말단 행을 3층에 실어야
+    // 셀이 컬럼 정의대로 그려진다
+    const data = useMemo(() => (grouped ? { ...serverData, rows: group.rows } : serverData), [serverData, grouped, group.rows]);
+    const { table, tableColumns, setTableColumns } = useDefinitionTable({ definition, search, data });
+    const fetchAllRows = useCallback(async () => {
+        const request = {
+            ...search.request,
+            // "전체" 는 PAGE_SIZE_ALL 을 명시한다 — 기존 ERP 백엔드는 pagination 미지정을 기본 10건으로
+            // 해석하므로, 미지정으로 보내면 서버 버전에 따라 결과가 갈린다
+            pagination: { pageIndex: 0, pageSize: PAGE_SIZE_ALL },
+            grouping: undefined,
+            aggregation: undefined,
+            groupExpansion: undefined,
+        };
+        const response = await queryFn(request, { signal: new AbortController().signal });
+        return response.data ?? [];
+    }, [queryFn, search.request]);
+    const grouping = useMemo(() => {
+        if (!groupingEnabled)
+            return undefined;
+        return {
+            enabled: group.enabled,
+            grouping: groupingColumns,
+            setGrouping: search.setGrouping,
+            items: group.items,
+            expand: group.expand,
+            loadMore: group.loadMore,
+            rows: group.rows,
+            batchSize,
+            setBatchSize,
+        };
+    }, [
+        groupingEnabled, group.enabled, group.items, group.expand, group.loadMore, group.rows,
+        groupingColumns, search.setGrouping, batchSize,
+    ]);
+    return useMemo(() => ({
+        definition,
+        mode: "server",
+        search,
+        data,
+        table,
+        grouping,
+        urlSync,
+        history,
+        request: search.request,
+        tableColumns,
+        setTableColumns,
+        fetchAllRows,
+        query: serverData.query,
+    }), [
+        definition, search, data, table, grouping, urlSync, history, tableColumns, setTableColumns,
+        fetchAllRows, serverData.query,
+    ]);
+}

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

@@ -0,0 +1,48 @@
+import { type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+import type { RowData } from "@tanstack/react-table";
+import type { TableData, TableQueryFn, TableRequest, TableResponse } from "../../core/src/index";
+/** 코어 `TableQueryFn` 과 같은 타입 — 기존 import 경로 호환을 위해 다시 내보낸다 */
+export type { TableQueryFn };
+/** `useQuery` 원본 옵션 통과구 — 이 훅이 직접 다루는 키는 뺀다 */
+export type ServerTableQueryOptions<T> = Omit<UseQueryOptions<TableResponse<T>, Error>, "queryKey" | "queryFn" | "enabled" | "staleTime" | "placeholderData" | "throwOnError" | "select">;
+export interface ServerTableDataOptions<T extends RowData> {
+    request: TableRequest;
+    queryFn: TableQueryFn<T>;
+    /** 캐시 구분용 접두 키. 화면마다 달라야 서로의 캐시를 밟지 않는다 */
+    queryKey?: readonly unknown[];
+    enabled?: boolean;
+    staleTime?: number;
+    /**
+     * @deprecated 효과 없음. 백엔드 `TableRequest` 에 `groupHeaderOnly` 가 없어서 wire 에 싣지
+     * 않는다 — `grouping` 이 있으면 항상 `groupExpansion: { path: [] … }` 로 최상위 그룹 노드를
+     * 받는다(`toWireRequest`). 옵션은 호출부 호환을 위해 받기만 한다.
+     */
+    groupHeaderOnly?: boolean;
+    /**
+     * 응답 가공 — **캐시에 들어가기 전** 한 번 적용된다.
+     * `select` 는 렌더마다 돌고 `onSuccess` 는 v5 에서 사라졌으므로 queryFn 안에서 적용한다.
+     */
+    transformResponse?: (response: TableResponse<T>, request: TableRequest) => TableResponse<T>;
+    /**
+     * 조건이 바뀌어 재조회하는 동안 이전 행을 유지한다 (기본 true).
+     * 끄면 조건이 바뀔 때마다 `isInitialLoading` 이 다시 true 가 되어 스켈레톤이 뜬다.
+     */
+    keepPreviousData?: boolean;
+    refetchInterval?: number | false;
+    /** 실패 재시도. 미지정이면 QueryClient 기본값 */
+    retry?: boolean | number | ((failureCount: number, error: Error) => boolean);
+    /** 나머지 `useQuery` 옵션 */
+    queryOptions?: ServerTableQueryOptions<T>;
+}
+export interface ServerTableData<T extends RowData> extends TableData<T> {
+    /** 재시도·캐시 무효화 등 세밀한 제어가 필요할 때 */
+    query: UseQueryResult<TableResponse<T>, Error>;
+}
+/**
+ * 2층 서버 모드 — 요청을 그대로 서버에 보낸다.
+ *
+ * 코어(`useTableData`)는 클라이언트 모드만 담당하고 의존성이 0이다. 서버 모드는
+ * 캐싱·취소가 필요해 react-query 를 쓰므로 이 패키지로 분리했다. 반환 타입은
+ * 같은 `TableData` 라서 3층·렌더러는 어느 쪽인지 몰라도 된다.
+ */
+export declare function useServerTableData<T extends RowData>(options: ServerTableDataOptions<T>): ServerTableData<T>;

package/dist/query/src/useServerTableData.js

@@ -0,0 +1,64 @@
+import { useMemo } from "react";
+import { keepPreviousData as keepPreviousDataFn, useQuery, } from "@tanstack/react-query";
+import { DEFAULT_TABLE_STALE_TIME } from "../../core/src/index";
+import { toWireRequest } from "./wire";
+const EMPTY = [];
+/**
+ * 2층 서버 모드 — 요청을 그대로 서버에 보낸다.
+ *
+ * 코어(`useTableData`)는 클라이언트 모드만 담당하고 의존성이 0이다. 서버 모드는
+ * 캐싱·취소가 필요해 react-query 를 쓰므로 이 패키지로 분리했다. 반환 타입은
+ * 같은 `TableData` 라서 3층·렌더러는 어느 쪽인지 몰라도 된다.
+ */
+export function useServerTableData(options) {
+    const { request, queryFn, queryKey, enabled = true, staleTime = DEFAULT_TABLE_STALE_TIME, transformResponse, keepPreviousData = true, refetchInterval, retry, queryOptions, } = options;
+    // 서버 계약(백엔드 `TableRequest`)에 맞춘 본문 — `grouping` 이 있으면 최상위 `groupExpansion`,
+    // `groupHeaderOnly` 는 제거. 그룹이 없으면 요청 객체 그대로(참조 동일)다.
+    const effectiveRequest = useMemo(() => toWireRequest(request), [request]);
+    const query = useQuery({
+        ...queryOptions,
+        queryKey: [...(queryKey ?? ["koko-table"]), effectiveRequest],
+        queryFn: async ({ signal }) => {
+            const response = await queryFn(effectiveRequest, { signal });
+            return transformResponse ? transformResponse(response, effectiveRequest) : response;
+        },
+        enabled,
+        staleTime,
+        // 조건을 바꿔 재조회하는 동안 이전 행을 유지한다 — 매번 빈 표가 번쩍이면
+        // 스크롤 위치도 잃고 화면이 튄다
+        placeholderData: keepPreviousData ? keepPreviousDataFn : undefined,
+        ...(refetchInterval !== undefined ? { refetchInterval } : {}),
+        ...(retry !== undefined ? { retry } : {}),
+        /**
+         * 조회 실패를 렌더 중 throw 하지 않는다.
+         *
+         * 상위 ErrorBoundary 가 테이블 트리를 파괴하면 리마운트가 캐시의 error 를
+         * 다시 읽어 즉시 재-throw 하므로 경계 리셋으로 복구가 안 된다.
+         * 에러는 결과에 실어 보내고 콘텐츠 구역이 제자리에서 재시도 UI 를 그린다.
+         */
+        throwOnError: false,
+    });
+    // react-query 는 결과를 렌더마다 새 추적 프록시로 돌려준다(`trackResult`). 그 객체를 의존성으로
+    // 두면 아무것도 안 바뀌어도 매 렌더 새 값이 되므로, 실제로 읽는 필드만 의존성에 둔다 —
+    // 읽는 순간 그 필드가 추적되어 바뀔 때 다시 렌더된다.
+    const { data: response, isLoading, isFetching, isError, error, refetch, fetchStatus, dataUpdatedAt } = query;
+    return useMemo(() => {
+        const rows = response?.data ?? EMPTY;
+        return {
+            rows,
+            // 서버가 총 건수를 안 주면 받은 만큼만 안다 — 페이지 수가 1로 보이는 게
+            // 없는 수를 지어내는 것보다 낫다
+            total: response?.meta?.total_count ?? rows.length,
+            meta: response?.meta ?? null,
+            groups: response?.groups ?? null,
+            isLoading: isLoading || isFetching,
+            isInitialLoading: isLoading,
+            isError,
+            error: error ?? undefined,
+            refetch: () => void refetch(),
+            mode: "server",
+            query,
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [response, isLoading, isFetching, isError, error, refetch, fetchStatus, dataUpdatedAt]);
+}

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

@@ -0,0 +1,16 @@
+import type { TableRequest } from "../../core/src/index";
+/**
+ * 서버에 실제로 보내는 본문 — 백엔드 `QueryBuilder/types.py` 의 `TableRequest` 모양으로 맞춘다.
+ *
+ * 기존 ERP `useTableQuery.buildParams` 와 같은 규칙이다:
+ * - `grouping` 이 있으면 최상위에 `groupExpansion: { path: [], offset: pageIndex*pageSize, limit: pageSize }`
+ *   를 싣는다 (`pageSize` = 페이지당 최상위 그룹 수). 서버는 이 값으로 최상위 그룹 노드
+ *   (`groups.nodes`)를 돌려준다. 하위 확장(`useServerGrouping`)은 이미 `groupExpansion` 을
+ *   들고 오므로 그대로 둔다.
+ * - `groupHeaderOnly` 는 백엔드 `TableRequest` 에 없는 키라 wire 에서 뺀다 (서버는 무시했고,
+ *   있으면 `extra="forbid"` 검증에서 걸린다).
+ *
+ * `grouping` 이 없으면 요청 객체를 **그대로**(참조 동일) 돌려준다 — react-query 키가
+ * 매 렌더 바뀌지 않게 하려는 것이다.
+ */
+export declare function toWireRequest(request: TableRequest): TableRequest;

package/dist/query/src/wire.js

@@ -0,0 +1,32 @@
+import { DEFAULT_PAGINATION } from "../../core/src/index";
+/**
+ * 서버에 실제로 보내는 본문 — 백엔드 `QueryBuilder/types.py` 의 `TableRequest` 모양으로 맞춘다.
+ *
+ * 기존 ERP `useTableQuery.buildParams` 와 같은 규칙이다:
+ * - `grouping` 이 있으면 최상위에 `groupExpansion: { path: [], offset: pageIndex*pageSize, limit: pageSize }`
+ *   를 싣는다 (`pageSize` = 페이지당 최상위 그룹 수). 서버는 이 값으로 최상위 그룹 노드
+ *   (`groups.nodes`)를 돌려준다. 하위 확장(`useServerGrouping`)은 이미 `groupExpansion` 을
+ *   들고 오므로 그대로 둔다.
+ * - `groupHeaderOnly` 는 백엔드 `TableRequest` 에 없는 키라 wire 에서 뺀다 (서버는 무시했고,
+ *   있으면 `extra="forbid"` 검증에서 걸린다).
+ *
+ * `grouping` 이 없으면 요청 객체를 **그대로**(참조 동일) 돌려준다 — react-query 키가
+ * 매 렌더 바뀌지 않게 하려는 것이다.
+ */
+export function toWireRequest(request) {
+    const grouping = request.grouping ?? [];
+    const hasGrouping = grouping.length > 0;
+    const hasLegacyKey = "groupHeaderOnly" in request;
+    if (!hasGrouping && !hasLegacyKey)
+        return request;
+    const { groupHeaderOnly: _dropped, ...rest } = request;
+    if (!hasGrouping)
+        return rest;
+    if (rest.groupExpansion)
+        return rest;
+    const { pageIndex, pageSize } = rest.pagination ?? DEFAULT_PAGINATION;
+    return {
+        ...rest,
+        groupExpansion: { path: [], offset: pageIndex * pageSize, limit: pageSize },
+    };
+}

package/dist/query.d.ts

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

package/dist/query.js

@@ -0,0 +1,2 @@
+// kokotable/query — 서버 모드
+export * from "./query/src/index";

package/package.json

@@ -0,0 +1,125 @@
+{
+  "name": "kokotable",
+  "version": "0.95.0",
+  "description": "헤드리스 테이블 코어 + MUI 렌더러 + 서버 모드 — 백엔드 QueryBuilder 와 같은 의미의 필터, 검색 상태, 확장 계약",
+  "keywords": [
+    "table",
+    "headless",
+    "mui",
+    "material-ui",
+    "react",
+    "tanstack-table",
+    "react-query",
+    "server-side"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kokotu0/koko-table.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mui": {
+      "types": "./dist/mui.d.ts",
+      "default": "./dist/mui.js"
+    },
+    "./mui/virtual": {
+      "types": "./dist/mui-virtual.d.ts",
+      "default": "./dist/mui-virtual.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./contract/table-request.schema.json": "./contract/table-request.schema.json",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "contract",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "koko": {
+    "contractVersion": "0.95.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "@tanstack/react-table": "^8.21.0",
+    "@mui/material": "^6 || ^7",
+    "@mui/icons-material": "^6 || ^7",
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@tanstack/react-query": "^5",
+    "@tanstack/react-virtual": "^3.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@mui/material": {
+      "optional": true
+    },
+    "@mui/icons-material": {
+      "optional": true
+    },
+    "@emotion/react": {
+      "optional": true
+    },
+    "@emotion/styled": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "@tanstack/react-virtual": {
+      "optional": true
+    }
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p packages/core/checks && tsc -p packages/mui/checks",
+    "test": "vitest run",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "storybook:build": "storybook build -o storybook-static",
+    "bench": "tsx packages/core/bench/clientPipeline.bench.ts",
+    "contract:check": "vitest run packages/query/src/contract.test.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck:tests": "tsc -p tsconfig.tests.json --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run typecheck && npm run typecheck:tests && npm test && npm run build && npm run pack:check",
+    "live:check": "vitest run packages/query/src/live.test.ts",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^7.3.11",
+    "@mui/material": "^7.3.11",
+    "@storybook/react-vite": "^9.1.20",
+    "@tanstack/react-query": "^5.102.2",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.14.10",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "jsdom": "^26.1.0",
+    "react-dom": "^19.2.8",
+    "storybook": "^9.1.20",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.6",
+    "vitest": "^3.2.7"
+  }
+}