kokotable 0.95.0

package/dist/core/src/types/column.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 컬럼 정의 시 받는 타입 — 한눈에 보는 표.
+ *
+ * `TableColumnDef<T, V, Ext>` = TanStack `ColumnDef<T, V>` + 아래 세 필드.
+ * `V` 는 셀 값 타입(helper 프리셋은 `key` 의 값 타입으로 추론한다. 점 경로는 `unknown`),
+ * `Ext` 는 `meta.custom` 의 타입(소비 앱 확장 슬롯. 기본 `{}`).
+ *
+ * | 위치 | 필드 | 뜻 |
+ * |---|---|---|
+ * | `TableColumnDef` | `id` / `accessorKey` / `accessorFn` | 컬럼 키·값 접근 (TanStack) |
+ * | `TableColumnDef` | `header` / `cell` / `footer` | 렌더 (TanStack) |
+ * | `TableColumnDef` | `size` / `minSize` / `maxSize` / `enableSorting` / `enableGrouping` … | TanStack 옵션 통과 |
+ * | `TableColumnDef` | `meta?: ColumnMeta<Ext>` | 렌더·집계·종속 선언 (아래) |
+ * | `TableColumnDef` | `filter?: FilterSpec<V>` | 필터 선언 (아래) |
+ * | `TableColumnDef` | `filterLabel?: ReactNode` | 필터 패널 전용 라벨 (헤더가 ReactNode 일 때) |
+ * | `ColumnMeta` | `dataType` | `"number" \| "text" \| "date" \| "datetime" \| "boolean" \| "enum"` — 필터 variant·포맷·집계 기본값의 근거 |
+ * | `ColumnMeta` | `isVisible` / `forceHidden` | 기본 숨김 / 값 보관 전용(토글·프리셋으로도 안 살아남) |
+ * | `ColumnMeta` | `align` / `headerAlign` / `headerTooltip` | 셀 정렬 · 헤더 정렬 · 헤더 툴팁 (렌더러가 읽는다) |
+ * | `ColumnMeta` | `ellipsis` / `decimals` / `currency` / `endAdornment` / `chip` / `placeholder` / `link` | 표시 보조 |
+ * | `ColumnMeta` | `selectOptions` | select/multiSelect 선택지 |
+ * | `ColumnMeta` | `enableAgg` / `aggregations` / `aggRender` | 그룹 집계 활성 · 함수 목록 · 커스텀 집계 렌더러 |
+ * | `ColumnMeta` | `sortExpandsTo` / `cascadeFilterLevels` / `relationColumns` / `dependentFilter` / `customCascadeFilter` / `commonCodeParentPath` / `scheduleFields` / `linearConfig` | 서버 필드 매핑 · 종속/통합 컬럼 |
+ * | `ColumnMeta` | `edit?: EditSpec` | 편집 선언 (`enabled` · `kind` · `variant` · `options` · `onCommit` · `inputProps`) |
+ * | `ColumnMeta` | `custom?: Ext` | 소비 앱 확장 슬롯 — `columnMetaOf<Ext>(def)?.custom` 으로 읽는다 |
+ * | `FilterSpec` | `kind` | 필터 kind (`defineFilterKind` 객체 또는 등록된 id) — 있으면 연산자·판정·직렬화·문구·codec 의 근거 |
+ * | `FilterSpec` | `variant` / `operators` / `defaultOperator` | 필터 UI 종류 · 허용 연산자 · 기본 연산자 (kind 가 있으면 kind 의 연산자로 좁혀진다) |
+ * | `FilterSpec` | `render` / `hidden` / `detail` | 커스텀 입력 · 필터 제외 · "상세 조건" 그룹 |
+ * | `FilterSpec` | `applyOnChange` / `debounceMs` | 값 변경 즉시 조회 · 그 지연(ms, 컬럼 단위가 `TableSearchOptions.debounceMs` 보다 우선) |
+ * | `FilterSpec` | `defaultValue` | 초기값 |
+ *
+ * 필터 값 타입은 셀 값 타입 `V` 와 **독립**이다(숫자 컬럼의 범위 필터는 `[number, number]`).
+ * `filter.kind` 가 있으면 필터 값·연산자 타입은 kind 가 정한다(`FilterSpecOf<K>`, `FilterSpecInput`).
+ * kind 가 없는 variant 경로에서만 `FilterSpec<V>` 의 `V` 가 `render`/`defaultValue` 의 편의 타입이며,
+ * 다르면 `FilterSpec<any>` 로 둔다.
+ */
+import type { ReactNode } from "react";
+import type { ColumnDef, RowData } from "@tanstack/react-table";
+import type { FilterSpecInput } from "./filter";
+/** 편집 선언 — `ColumnMeta.edit` 와 `ColumnBuilder.setEdit` 가 같은 타입을 쓴다 */
+export interface EditSpec<T extends RowData = any> {
+    enabled: boolean;
+    kind?: "text" | "number" | "select";
+    variant?: "dropdown" | "chip" | "button";
+    options?: SelectOption[] | ((row: T) => SelectOption[]);
+    color?: string;
+    size?: "small" | "medium";
+    /** 미지정 시 `row[key]` 에 직접 반영한다. 렌더러는 세 번째 인자로 columnId 를 준다 */
+    onCommit?: (value: unknown, row: T, columnId?: string) => void;
+    /** 렌더러가 그대로 전달할 입력 props */
+    inputProps?: Record<string, unknown>;
+}
+/** select/multiSelect 필터의 선택지 (MRT `DropdownOption` 대체) */
+export interface SelectOption {
+    label: string;
+    value: string;
+    /** 계층 옵션의 상위 체인 표시용 ("대분류 > 중분류") */
+    ancestorChain?: string;
+}
+/**
+ * 컬럼의 실제 데이터 타입. 필터 UI 종류(`FilterVariant`)와는 직교다.
+ * `"select"` 는 `"enum"` 의 별칭이다(모든 판정에서 같게 취급) — 새 코드는 `"enum"` 을 쓴다.
+ */
+export type ColumnDataType = "number" | "text" | "date" | "datetime" | "boolean" | "enum" | "select";
+export type DateFilterMode = "month" | "quarter" | "year" | "range" | "period";
+/** 상위 컬럼 값에 종속되는 필터 (CommonCode 계층) */
+export interface DependentFilterMeta {
+    dependsOn: string;
+    parentCodePath?: string;
+    allChildOptions: Array<{
+        idx: number;
+        name: string;
+        parentIdx: number;
+        ancestorChain?: string;
+    }>;
+    isMultiSelect: boolean;
+}
+/** CommonCode 가 아닌 컬럼의 커스텀 종속 필터 */
+export interface CustomCascadeFilterMeta {
+    /** 상위 컬럼 키 (상위 → 하위 순서) */
+    ancestorKeys: string[];
+    /** 상위 필터값을 `ancestorKeys` 순서대로 받아 옵션을 반환. 전부 null 이면 전체 옵션 */
+    getOptions: (...parentFilterValues: (number[] | null)[]) => SelectOption[];
+    isMultiSelect: boolean;
+}
+/** 통합 cascade 트리가 실제로 필터를 거는 레벨 필드들 */
+export interface CascadeFilterLevel {
+    key: string;
+    operator: string;
+    operatorOptions: string[];
+}
+/**
+ * 컬럼 메타 — 렌더/집계/종속에 관한 선언.
+ *
+ * 기존 `ColumnMetaData` 에서 **필터 관련 항목은 `FilterSpec` 으로 옮겼다**
+ * (`hideFilter` → `filter.hidden`, `isVisible=false` 파생 → `filter.detail`,
+ *  `dateFilterMode` → `filter.variant` + 자체 옵션).
+ * 여기 남은 `isVisible` 은 순수하게 **컬럼 표시** 여부다.
+ */
+export type CellAlign = "left" | "center" | "right";
+/** `meta.aggRender` 가 받는 값 — ERP `AggValues` / mui `AggRenderProps` 와 같은 모양 */
+export interface AggRenderValues {
+    /** 선택된(또는 첫) 집계 함수의 값 */
+    value: unknown;
+    columnId: string;
+    /** 이 그룹 노드의 집계 전체 (`node.aggregates`) — 다른 컬럼의 값도 볼 수 있다 */
+    allAggregates: Record<string, Record<string, unknown>>;
+}
+/**
+ * 커스텀 집계 렌더러 — ERP `AggCustomRender` 와 같은 `(values, column)` 규약.
+ * `column` 은 렌더러 패키지의 컬럼 인스턴스(TanStack `Column`)라 코어에서는 `unknown` 이다.
+ */
+export type AggRenderFn = (values: AggRenderValues, column?: unknown) => ReactNode;
+export interface ColumnMeta<Ext = {}> {
+    dataType?: ColumnDataType;
+    /** 기본 숨김 — 사용자 토글·프리셋으로 다시 켜질 수 있다 */
+    isVisible?: boolean;
+    /**
+     * 값 보관 전용 — 절대 표시되지 않는다.
+     * `isVisible: false` 는 초기값일 뿐이라 토글로 되살아나므로,
+     * 헤더가 없는 컬럼(통합 cascade 에 흡수된 레벨 등)은 이 플래그를 쓴다.
+     */
+    forceHidden?: boolean;
+    /** 이 컬럼으로 정렬할 때 서버에 대신 보낼 실제 필드 (상위 → 하위) */
+    sortExpandsTo?: string[];
+    cascadeFilterLevels?: CascadeFilterLevel[];
+    /** 1:N 관계 컬럼의 하위 필드 — 컬럼 정의만 읽는 쪽(AI 컨텍스트 등)이 구조를 알 수 있게 */
+    relationColumns?: Array<{
+        key: string;
+        label: string;
+        type?: string;
+    }>;
+    dependentFilter?: DependentFilterMeta;
+    commonCodeParentPath?: string;
+    customCascadeFilter?: CustomCascadeFilterMeta;
+    dateFilterMode?: DateFilterMode;
+    selectOptions?: SelectOption[];
+    /** 집계 활성 여부 */
+    enableAgg?: boolean;
+    aggregations?: string[];
+    /** 좁은 컬럼 말줄임 — 렌더러가 읽는다 */
+    ellipsis?: boolean;
+    /** 숫자 표시 보조 — 렌더러가 읽는다 */
+    decimals?: number;
+    currency?: string;
+    endAdornment?: unknown;
+    /** 값을 칩으로 감싼다 */
+    chip?: boolean;
+    /** 값이 비었을 때 대신 그릴 것 */
+    placeholder?: string;
+    /** 링크 컬럼 — `to` 는 "/" 로 시작하는 절대 경로를 반환해야 한다 */
+    link?: {
+        to: (props: unknown) => string;
+    };
+    /** 일정 통합 컬럼의 필드 매핑 */
+    scheduleFields?: {
+        plannedStart: string;
+        plannedEnd: string;
+        actualStart: string;
+        actualEnd: string;
+    };
+    /** 선형결합 필터 기본 설정 */
+    linearConfig?: unknown;
+    /** 합성 집계 행 렌더러 — `({ value, columnId, allAggregates }, column)` 로 불린다 */
+    aggRender?: AggRenderFn;
+    /** 셀 내용 정렬 — 렌더러가 읽는다. 미지정 시 number 는 오른쪽, 나머지 왼쪽이 관례 */
+    align?: CellAlign;
+    /** 헤더 정렬 — 미지정 시 `align` 을 따른다 */
+    headerAlign?: CellAlign;
+    /** 헤더에 마우스를 올리면 보이는 설명 */
+    headerTooltip?: string;
+    /**
+     * 소비 앱 확장 슬롯. 코어·렌더러는 읽지 않는다.
+     * `TableColumnDef<T, V, Ext>` / `columnMetaOf<Ext>(def)` 로 타입을 살린다.
+     */
+    custom?: Ext;
+    /**
+     * 편집 선언. 실제 입력 컴포넌트는 렌더러 패키지가 그린다 —
+     * 코어가 MUI 를 모르는 채로 편집 가능 여부·방식을 표현하기 위한 자리다.
+     */
+    edit?: EditSpec<any>;
+}
+/**
+ * 이 패키지의 컬럼 정의 = TanStack `ColumnDef` + `meta` + `filter`.
+ *
+ * 교차 타입으로 얹는 이유: `ColumnDef` 는 유니온이라 `interface extends` 가 안 되고,
+ * 전역 module augmentation 은 이 패키지를 쓰지 않는 소비자에게까지 새어 나간다.
+ *
+ * `V` 의 기본값이 `any` 인 이유: `ColumnDef<T, V>` 는 `cell` 콜백 때문에 `V` 에 반변이라
+ * `TableColumnDef<T, number>` 가 `TableColumnDef<T, unknown>` 에 들어가지 않는다.
+ * helper 가 값 타입을 추론해 내놓는 컬럼을 `TableColumnDef<T>` 파라미터가 그대로 받으려면
+ * 기본값이 `any` 여야 한다 (기존 호출부는 전부 `TableColumnDef<T, any>` 를 받고 있었다).
+ */
+export type TableColumnDef<T extends RowData, V = any, Ext = {}> = ColumnDef<T, V> & {
+    meta?: ColumnMeta<Ext>;
+    /** 필터 선언 — kind 별로 좁혀진 유니온. 읽을 때는 `FilterSpec` 모양으로 보면 된다 */
+    filter?: FilterSpecInput<V>;
+    /** 필터 라벨 전용 오버라이드 — 헤더가 ReactNode 일 때 사용 */
+    filterLabel?: ReactNode;
+};
+/**
+ * 행 타입 `T` 에서 키 `K` 의 값 타입. `keyof T` 가 아니면(점 경로·동적 문자열) `unknown`.
+ * helper 프리셋이 `key` 리터럴로 `TableColumnDef<T, V>` 의 `V` 를 추론하는 데 쓴다.
+ */
+export type ValueOfKey<T, K extends string> = K extends keyof T ? T[K] : unknown;
+/**
+ * 이종 컬럼 배열.
+ *
+ * 컬럼마다 필터 값 타입이 다른데(텍스트는 string, 상태는 string[], 기간은 [Date, Date])
+ * 동종 배열 하나로는 "원소마다 각자의 V" 를 표현할 수 없다 — 존재 타입이 필요한데
+ * TS 에 없다. TanStack 이 `ColumnDef<T, any>[]` 를 권장하는 것과 같은 이유이고,
+ * 같은 관례를 따른다. 개별 컬럼을 만들 때는 `TableColumnDef<T, V>` 로 V 를 살린다.
+ */
+export type TableColumnDefs<T extends RowData, Ext = {}> = Array<TableColumnDef<T, any, Ext>>;

package/dist/core/src/types/column.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/types/data.d.ts

@@ -0,0 +1,63 @@
+import type { RowData } from "@tanstack/react-table";
+import type { SelectionSource } from "./filter";
+import type { GroupsResult, TableRequest, TableResponse, TableResponseMeta } from "./request";
+/**
+ * `"server"` — 요청을 그대로 서버에 보낸다 (필터/정렬/페이지 전부 서버 계산).
+ * `"client"` — 메모리 배열에 같은 요청을 적용한다.
+ * 미지정이면 `queryFn` 유무로 판단한다 (기존 `useTableQuery` 규칙 그대로).
+ */
+export type TableMode = "client" | "server";
+/**
+ * 서버 조회 함수 — 요청 본문과 취소 신호를 받아 응답을 돌려준다.
+ *
+ * `kokotable/query` 의 `useServerTableData` / `useServerGrouping` 과 테이블 정의
+ * (`TableDefinition.server.queryFn`) 가 같은 타입을 쓴다. 두 번째 인자를 무시하는
+ * `(request) => Promise<TableResponse<T>>` 도 그대로 대입된다.
+ */
+export type TableQueryFn<T> = (request: TableRequest, context: {
+    signal: AbortSignal;
+}) => Promise<TableResponse<T>>;
+export interface TableDataOptions<T extends RowData> {
+    request: TableRequest;
+    /** 서버 모드 */
+    queryFn?: TableQueryFn<T>;
+    queryKey?: readonly unknown[];
+    /** 클라이언트 모드 원본 배열 */
+    data?: T[];
+    mode?: TableMode;
+    enabled?: boolean;
+    staleTime?: number;
+}
+/**
+ * 2층 — 데이터. **테이블 인스턴스가 없어도 동작한다.**
+ * 카드/차트 화면은 여기까지만 쓰고 3층을 만들지 않는다.
+ */
+export interface TableData<T extends RowData> {
+    rows: T[];
+    /** 서버 총 건수. 클라이언트 모드면 필터 적용 후 길이 */
+    total: number;
+    meta?: TableResponseMeta | null;
+    /** 서버 그룹 조회 응답의 `groups` (백엔드 `GroupsResult`). 클라이언트 모드면 null */
+    groups?: GroupsResult | null;
+    isLoading: boolean;
+    /** 첫 로드 여부 — 이후 refetch 는 기존 행을 유지한 채 갱신된다 */
+    isInitialLoading: boolean;
+    isError: boolean;
+    error?: Error;
+    /**
+     * 조회 실패를 렌더 중 throw 하지 않는 이유:
+     * 상위 ErrorBoundary 가 테이블 트리를 파괴하면 리마운트가 캐시의 error 를
+     * 다시 읽어 즉시 재-throw 하므로 경계 리셋으로 복구가 안 된다.
+     * 에러는 여기 실어 보내고 레이아웃이 제자리에서 재시도 UI 를 그린다.
+     */
+    refetch: () => void;
+    readonly mode: TableMode;
+}
+/** 행 단위 필드 에러 (react-hook-form `FieldErrors` 호환) */
+export type FieldErrors = {
+    [index: number]: Record<string, {
+        message?: string;
+        type?: string;
+    }> | undefined;
+} | undefined;
+export type { SelectionSource };

package/dist/core/src/types/data.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/types/definition.d.ts

@@ -0,0 +1,239 @@
+import type { ReactNode } from "react";
+import type { Row, RowData, Table, TableOptions } from "@tanstack/react-table";
+import type { TableColumnDefs } from "./column";
+import type { FieldErrors, TableData, TableMode, TableQueryFn } from "./data";
+import type { FilterOperator } from "./operators";
+import type { TableRequest, TableResponse } from "./request";
+import type { SearchState, TableSearch } from "./search";
+import type { DataTable } from "./table";
+import type { ExpandState, FlatItem, GroupPath } from "./grouping";
+import type { AggregationSpec } from "../client/aggregate";
+import type { UrlSync } from "../hooks/useUrlSync";
+import type { SearchHistory } from "../hooks/useSearchHistory";
+/**
+ * 테이블 정의 — **화면 하나를 선언하는 객체.**
+ *
+ * 소비자는 필요한 것만 채운다: 컬럼·기본값·서버 연결·기능 토글·그룹핑·URL 동기화.
+ * 조립은 `useTableFromDefinition(definition)`(클라이언트 모드, core) 또는
+ * `useServerTable(definition)`(서버 모드, `kokotable/query`) 이 하고, 렌더는
+ * `<TableScreen bundle={…} />`(`kokotable/mui`) 이 정의의 `features` 대로 한다.
+ *
+ * 기존 ERP `useTable(UseTableOptions)` 의 옵션 모양(columns/data/mode/queryFn/queryKey/
+ * syncWithUrl/initialExpand/fieldErrors/initialSearchParams/groupBatchSize)을 그대로
+ * 옮기되 MRT 옵션(`mrtOptions`, `enable*`)은 `features` 로 모았다.
+ *
+ * 정의 객체는 **참조가 안정적**이어야 한다 — 모듈 상수(`defineTable`)나 `useMemo` 로 만든다.
+ * 렌더마다 새로 만들면 컬럼 참조가 흔들려 검색 상태·컬럼 표시가 매번 다시 파생된다.
+ */
+export interface TableDefinition<T extends RowData> {
+    /** 화면 식별자 — 서버 캐시 키 접두·URL·프리셋 저장 키의 기준 */
+    key: string;
+    columns: TableColumnDefs<T>;
+    /** 미지정이면 `server` 유무로 판단한다 */
+    mode?: TableMode;
+    /** 클라이언트 모드 원본 배열 */
+    data?: T[];
+    /** 서버 모드 — `queryFn` 이 있어야 한다 */
+    server?: TableServerOptions<T>;
+    initial?: Partial<SearchState>;
+    /** 컬럼 기본 연산자를 덮어쓸 초기값 */
+    initialOperators?: Record<string, FilterOperator>;
+    /** 전역검색 입력 디바운스(ms) — `useTableSearch` 가 지원할 때만 전달된다 */
+    debounceMs?: number;
+    /** 클라이언트 모드 전역검색 대상 경로. 미지정이면 선언된 텍스트 계열 컬럼 전부 */
+    globalFilterFields?: string[];
+    /** `inPeriod` 기준 시각 (클라이언트 모드) */
+    now?: Date;
+    /** URL 동기화(`tp=`). `true` 면 기본 키, 객체면 키·구 스킴 키 지정 */
+    urlSync?: boolean | TableUrlSyncOptions;
+    /** 검색 조건 이력(뒤로/앞으로) */
+    history?: boolean | {
+        limit?: number;
+    };
+    grouping?: TableGroupingOptions;
+    features?: TableFeatures<T>;
+    /** 행 식별자. 서버 모드에서 선택·확장 상태가 재조회 후에도 유지되려면 **필수**다 */
+    getRowId?: (row: T, index: number, parent?: Row<T>) => string;
+    fieldErrors?: FieldErrors;
+    /** TanStack 원본 옵션 통과구 — `features` 가 만든 값 위에 덮인다 */
+    tableOptions?: Partial<TableOptions<T>>;
+}
+export interface TableServerOptions<T extends RowData> {
+    queryFn: TableQueryFn<T>;
+    /** 캐시 구분 키. `definition.key` 뒤에 붙는다 */
+    queryKey?: readonly unknown[];
+    staleTime?: number;
+    enabled?: boolean;
+    /** 응답 가공 — 캐시에 들어가기 전에 한 번 적용된다 (`select` 와 달리 렌더마다 돌지 않는다) */
+    transformResponse?: (response: TableResponse<T>, request: TableRequest) => TableResponse<T>;
+    /** 조건이 바뀌어 재조회하는 동안 이전 행을 유지한다 (기본 true) */
+    keepPreviousData?: boolean;
+    refetchInterval?: number | false;
+    retry?: boolean | number | ((failureCount: number, error: Error) => boolean);
+}
+export interface TableUrlSyncOptions {
+    /** 기본 `tp` */
+    paramKey?: string;
+    /** 구 스킴 키 (기본 `["filter"]`) */
+    legacyParamKeys?: readonly string[];
+}
+export interface TableGroupingOptions {
+    enabled: boolean;
+    /** 마운트 시 그룹 컬럼 (상위 → 하위). `initial.grouping` 이 있으면 그쪽이 우선 */
+    initial?: string[];
+    /** 서버 그룹핑 "더 보기" 배치 크기 (기본 50) */
+    batchSize?: number;
+    /** 집계 명세. 미지정이면 컬럼 `meta.enableAgg/aggregations` 에서 파생한다 */
+    aggregation?: AggregationSpec;
+    /** 클라이언트 그룹핑: 마운트 시 전부 펼침 */
+    initialExpanded?: boolean;
+}
+export interface TableRowNumbersFeature {
+    header?: ReactNode;
+    size?: number;
+    id?: string;
+}
+export interface TableSelectionFeature<T extends RowData> {
+    /** 다중 선택 (기본 true). false 면 라디오 */
+    multi?: boolean;
+    /** 행 아무 곳을 눌러도 토글 */
+    selectOnRowClick?: boolean;
+    /** 헤더 전체 선택 (기본 true) */
+    selectAll?: boolean;
+    /** 선택 가능한 행 판정 */
+    canSelect?: (row: Row<T>) => boolean;
+}
+export interface TableExpandFeature<T extends RowData> {
+    /** 헤더 "모두 펼치기" (기본 true) */
+    expandAll?: boolean;
+    /** 펼칠 수 있는 행 판정 */
+    canExpand?: (row: Row<T>) => boolean;
+}
+/** `kokotable/mui` 의 `RowActionsColumnOptions<T>` 와 구조가 같다 */
+export interface TableRowActionsFeature<T extends RowData> {
+    render: (row: Row<T>, table: Table<T>) => ReactNode;
+    position?: "first" | "last";
+    header?: ReactNode;
+    size?: number;
+    id?: string;
+}
+export interface TableVirtualizeFeature {
+    /** 행 가상화 (기본 true) */
+    rows?: boolean | {
+        estimateRowHeight?: number;
+        overscan?: number;
+    };
+    /** 열 가상화 (기본 false) */
+    columns?: boolean | {
+        overscan?: number;
+    };
+    estimateRowHeight?: number;
+    /** 스크롤 컨테이너 높이 — 가상화에 필수. 기본 520 */
+    maxHeight?: number | string;
+}
+export interface TableVirtualColumnsFeature {
+    /** 슬롯 상한 (기본 10) */
+    maxSlots?: number;
+    /** true(기본) — 카드 변경이 즉시 조회된다. false — 검색 버튼으로 적용 */
+    applyImmediately?: boolean;
+    /** 카드에 필터 입력을 붙인다 (기본 true) */
+    enableFilter?: boolean;
+}
+export interface TableFeatures<T extends RowData> {
+    /** 행 번호 열 */
+    rowNumbers?: boolean | TableRowNumbersFeature;
+    /** 행 선택 열 + 선택 액션바 */
+    selection?: boolean | TableSelectionFeature<T>;
+    /** 확장 토글 열 — `TableScreen slots.detailPanel` 과 짝. 슬롯만 줘도 켜진다 */
+    expand?: boolean | TableExpandFeature<T>;
+    /** 행 액션 열 — `slots.rowActions` 가 있으면 그쪽 렌더가 우선한다 */
+    rowActions?: TableRowActionsFeature<T>;
+    /** 표시 전용 열 id 를 MRT 것(`mrt-row-*`)으로 — 저장된 프리셋 호환 */
+    legacyIds?: boolean;
+    /** 그룹핑 중 그룹 컬럼 배치 (기본 reorder) */
+    groupedColumnMode?: "reorder" | "remove" | false;
+    /**
+     * 행(·열) 가상화 — `kokotable/mui/virtual` 의 `VirtualTableScreen` 만 그린다.
+     * 메인 `TableScreen` 은 무시하고 경고만 낸다 (`@tanstack/react-virtual` 이 optional peer 라서).
+     */
+    virtualize?: boolean | TableVirtualizeFeature;
+    density?: "comfortable" | "compact" | "spacious";
+    /** 헤더 컬럼 메뉴 (기본 true) */
+    columnMenu?: boolean;
+    /** 툴바 왼쪽 전역검색 입력 */
+    globalFilter?: boolean;
+    /** 툴바 오른쪽 "적용 조건" 버튼(필터 상태 모달) */
+    filterStatus?: boolean;
+    /** 툴바 오른쪽 컬럼 표시 토글 */
+    columnVisibilityMenu?: boolean;
+    /** 필터 구역 끝의 가상 열 섹션 — 서버가 식을 평가해 응답 행에 값을 실어 준다 */
+    virtualColumns?: boolean | TableVirtualColumnsFeature;
+}
+/** `mode` 미지정 시의 판정 — `server` 가 있으면 서버 모드 */
+export declare function resolveDefinitionMode<T extends RowData>(definition: TableDefinition<T>): TableMode;
+/**
+ * 정의 검증 — 잘못된 정의는 **마운트 전에** 던진다.
+ *
+ * - 중복 컬럼 id: 필터·정렬 상태가 한 키에 두 컬럼을 매달아 조용히 어긋난다
+ * - 서버 모드인데 `queryFn` 없음
+ * - 서버 모드 + 선택/확장인데 `getRowId` 없음: 재조회 후 행 순번이 바뀌면 선택이 다른 행으로
+ *   옮겨 간다 — 던지지 않고 경고만 한다 (읽기 전용 화면은 문제가 없다)
+ */
+export declare function validateTableDefinition<T extends RowData>(definition: TableDefinition<T>): void;
+/**
+ * 타입 추론용 identity + 검증. 잘못된 정의는 여기서 던진다.
+ *
+ * ```ts
+ * const salesTable = defineTable<SalesRow>({ key: "sales", columns, data });
+ * ```
+ */
+export declare function defineTable<T extends RowData>(definition: TableDefinition<T>): TableDefinition<T>;
+export interface TableBundleGrouping<T extends RowData> {
+    /** 그룹 컬럼이 하나라도 있는가 */
+    readonly enabled: boolean;
+    /** 현재 그룹 컬럼 (상위 → 하위) = `search.params.grouping` */
+    grouping: string[];
+    setGrouping: (grouping: string[]) => void;
+    /** 화면 순서대로 평탄화된 항목 — `TableContent groupItems` */
+    items: Array<FlatItem<T>>;
+    expand: ExpandState;
+    /** 서버 그룹핑 "더 보기" */
+    loadMore?: (path: GroupPath) => void;
+    /** 3층에 실린 말단 행 (서버 헤더 우선 모드에서는 펼쳐서 받은 행) */
+    rows: T[];
+    /** 서버 그룹핑 배치 크기 */
+    batchSize?: number;
+    setBatchSize?: (size: number) => void;
+}
+/**
+ * 조립 결과 — 클라이언트(`useTableFromDefinition`)·서버(`useServerTable`) 모두 이 모양이다.
+ * 렌더러(`TableScreen`)는 어느 쪽에서 왔는지 몰라도 된다.
+ */
+export interface TableBundle<T extends RowData> {
+    definition: TableDefinition<T>;
+    readonly mode: TableMode;
+    search: TableSearch<T>;
+    /** 3층에 실린 데이터 — 서버 헤더 우선 그룹핑에서는 `rows` 가 펼쳐서 받은 말단 행이다 */
+    data: TableData<T>;
+    table: DataTable<T>;
+    /** `definition.grouping.enabled` 일 때만 */
+    grouping?: TableBundleGrouping<T>;
+    /** `definition.urlSync` 일 때만 */
+    urlSync?: UrlSync;
+    /** `definition.history` 일 때만 */
+    history?: SearchHistory;
+    /** = `search.request` */
+    request: TableRequest;
+    /**
+     * 3층(TanStack)에 실린 컬럼. 기본은 `definition.columns` 이고, 렌더러가 `setTableColumns` 로
+     * 표시 전용 열·가상 컬럼을 끼운 목록을 등록하면 그것이 된다.
+     */
+    tableColumns: TableColumnDefs<T>;
+    /** 3층 컬럼 등록 — `null` 이면 `definition.columns` 로 되돌린다 */
+    setTableColumns: (columns: TableColumnDefs<T> | null) => void;
+    /**
+     * 현재 조건의 **전체 행**(페이지 무시). 내보내기용 — 클라이언트 모드는 필터·정렬 결과,
+     * 서버 모드는 `pagination` 없이 한 번 더 조회한 응답이다.
+     */
+    fetchAllRows: () => Promise<T[]>;
+}

package/dist/core/src/types/definition.js

@@ -0,0 +1,59 @@
+import { columnKey } from "../columns/deriveOperators";
+// ── 검증 ──
+/** `mode` 미지정 시의 판정 — `server` 가 있으면 서버 모드 */
+export function resolveDefinitionMode(definition) {
+    if (definition.mode)
+        return definition.mode;
+    return definition.server ? "server" : "client";
+}
+/**
+ * 정의 검증 — 잘못된 정의는 **마운트 전에** 던진다.
+ *
+ * - 중복 컬럼 id: 필터·정렬 상태가 한 키에 두 컬럼을 매달아 조용히 어긋난다
+ * - 서버 모드인데 `queryFn` 없음
+ * - 서버 모드 + 선택/확장인데 `getRowId` 없음: 재조회 후 행 순번이 바뀌면 선택이 다른 행으로
+ *   옮겨 간다 — 던지지 않고 경고만 한다 (읽기 전용 화면은 문제가 없다)
+ */
+export function validateTableDefinition(definition) {
+    if (!definition.key || typeof definition.key !== "string") {
+        throw new Error("[koko-table] defineTable: `key` 는 비어 있지 않은 문자열이어야 합니다.");
+    }
+    if (!Array.isArray(definition.columns)) {
+        throw new Error(`[koko-table] defineTable("${definition.key}"): \`columns\` 배열이 필요합니다.`);
+    }
+    const seen = new Set();
+    for (const column of definition.columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        if (seen.has(id)) {
+            throw new Error(`[koko-table] defineTable("${definition.key}"): 컬럼 id "${id}" 가 중복됩니다.`);
+        }
+        seen.add(id);
+    }
+    const mode = resolveDefinitionMode(definition);
+    if (mode === "server" && typeof definition.server?.queryFn !== "function") {
+        throw new Error(`[koko-table] defineTable("${definition.key}"): 서버 모드는 \`server.queryFn\` 이 필요합니다.`);
+    }
+    if (mode === "client" && definition.server) {
+        throw new Error(`[koko-table] defineTable("${definition.key}"): mode "client" 인데 \`server\` 가 있습니다 — 하나만 두세요.`);
+    }
+    const features = definition.features;
+    const needsRowId = !!features && (!!features.selection || !!features.expand);
+    const hasRowId = !!definition.getRowId || !!definition.tableOptions?.getRowId;
+    if (mode === "server" && needsRowId && !hasRowId && typeof console !== "undefined") {
+        console.warn(`[koko-table] defineTable("${definition.key}"): 서버 모드에서 선택·확장 상태를 재조회 뒤에도 유지하려면 ` +
+            "`getRowId` 가 필요합니다. 없으면 행 순번(index) 이 id 가 되어 캐시 갱신 후 다른 행에 선택이 옮겨 갑니다.");
+    }
+}
+/**
+ * 타입 추론용 identity + 검증. 잘못된 정의는 여기서 던진다.
+ *
+ * ```ts
+ * const salesTable = defineTable<SalesRow>({ key: "sales", columns, data });
+ * ```
+ */
+export function defineTable(definition) {
+    validateTableDefinition(definition);
+    return definition;
+}