kokotable 0.95.0

package/dist/core/src/contracts/aiColumnMeta.js

@@ -0,0 +1,197 @@
+import { columnKey, resolveVariant } from "../columns/deriveOperators";
+import { ALL_FILTER_VALUE, EMPTY_FILTER_VALUE } from "../filters/list";
+// ─────────────────────────────────────────────────────────────
+// koko 컬럼 → AI 계약
+// ─────────────────────────────────────────────────────────────
+/**
+ * 값을 가진 데이터 컬럼인가.
+ *
+ * 기존 함수는 `accessorKey` 유무로 display 컬럼을 걸렀다. koko 는 `id` + `accessorFn`
+ * 이므로 접근자가 하나라도 있으면 데이터 컬럼이고, 접근자가 없어도 필터/타입 선언이
+ * 있으면(필터 전용 컬럼) 데이터 컬럼으로 본다. `koko-`/`mrt-` 접두 id 는 합성 display 컬럼.
+ */
+function isDataColumnDef(column, key) {
+    if (key.startsWith("koko-") || key.startsWith("mrt-"))
+        return false;
+    const withAccessor = column;
+    if (typeof withAccessor.accessorFn === "function" || withAccessor.accessorKey != null)
+        return true;
+    return column.filter !== undefined || column.meta?.dataType !== undefined;
+}
+function headerText(column, fallback) {
+    const header = column.header;
+    return typeof header === "string" ? header : fallback;
+}
+/** meta.selectOptions → AI 용 {value,label} */
+function toAiOptions(options, stripSentinels) {
+    if (!Array.isArray(options))
+        return undefined;
+    const list = stripSentinels
+        ? options.filter((o) => o.value !== ALL_FILTER_VALUE && o.value !== EMPTY_FILTER_VALUE)
+        : options;
+    return list.map((o) => ({ value: String(o.value), label: o.label ?? String(o.value) }));
+}
+/** true/false 두 개짜리 선택지는 boolean 으로 본다 (기존 fromVariant 규칙) */
+function isBooleanOptions(options) {
+    if (!Array.isArray(options))
+        return false;
+    const values = options
+        .map((o) => String(o.value))
+        .filter((v) => v !== ALL_FILTER_VALUE && v !== EMPTY_FILTER_VALUE);
+    return values.length === 2 && values.includes("true") && values.includes("false");
+}
+/** `filter.variant`(없으면 dataType 유추) → AI 계약 타입 */
+export function toAiColumnType(column) {
+    if (column.meta?.relationColumns?.length)
+        return "relation";
+    const variant = resolveVariant(column);
+    switch (variant) {
+        case "number": return "number";
+        case "date":
+        case "datetime": return "date";
+        case "boolean": return "boolean";
+        case "multiSelect": return "multiSelect";
+        case "select":
+            if (column.meta?.dataType === "boolean" || isBooleanOptions(column.meta?.selectOptions)) {
+                return "boolean";
+            }
+            return "select";
+        case "relation": return "relation";
+        default:
+            // text / linear / schedule / custom — 자유 텍스트로 취급
+            return column.meta?.dataType === "number" ? "number"
+                : column.meta?.dataType === "date" || column.meta?.dataType === "datetime" ? "date"
+                    : column.meta?.dataType === "boolean" ? "boolean"
+                        : "text";
+    }
+}
+function innerType(type) {
+    return type === "number" ? "number" : type === "date" || type === "datetime" ? "date" : "text";
+}
+/**
+ * koko 컬럼 정의에서 AI 용 메타데이터를 추출한다.
+ *
+ * 기존 규칙(`extract-column-meta.ts`)을 그대로 따른다:
+ * - 키가 없는 컬럼(display 등)은 건너뛴다
+ * - `meta.forceHidden` 은 값 보관 전용이라 AI 컨텍스트에 올리지 않는다
+ * - 통합 cascade 는 가상 컬럼 대신 `cascadeFilterLevels` 의 실제 레벨 키를 올린다
+ *   (연산자가 equals/notEquals 면 select, 아니면 multiSelect)
+ * - `meta.relationColumns` 가 있으면 relation + inner
+ * - 그 외는 `filter.variant`/`meta.dataType` 으로 타입, select/multiSelect 는 옵션 동봉
+ */
+export function extractColumnMeta(columns, options = {}) {
+    const stripSentinels = options.stripSentinels ?? false;
+    const result = [];
+    for (const column of columns) {
+        const key = columnKey(column);
+        if (!key || !isDataColumnDef(column, key))
+            continue;
+        if (column.meta?.forceHidden)
+            continue;
+        const cascadeLevels = column.meta?.cascadeFilterLevels;
+        if (cascadeLevels?.length) {
+            const header = column.header;
+            for (const level of cascadeLevels) {
+                result.push({
+                    key: level.key,
+                    header: typeof header === "string" ? `${header}:${level.key}` : level.key,
+                    type: level.operator === "equals" || level.operator === "notEquals" ? "select" : "multiSelect",
+                });
+            }
+            continue;
+        }
+        const header = headerText(column, key);
+        const relationColumns = column.meta?.relationColumns;
+        if (relationColumns?.length) {
+            const inner = relationColumns.map((c) => ({
+                key: c.key,
+                header: c.label,
+                type: innerType(c.type),
+            }));
+            result.push({ key, header, type: "relation", inner });
+            continue;
+        }
+        const type = toAiColumnType(column);
+        const aiOptions = type === "select" || type === "multiSelect"
+            ? toAiOptions(column.meta?.selectOptions, stripSentinels)
+            : undefined;
+        result.push({ key, header, type, options: aiOptions });
+    }
+    return result;
+}
+/**
+ * koko `filter.variant` → 기존 `meta.columnType`.
+ *
+ * 기존 columnType ≈ koko variant 이고, relation 은 기존이 `custom` 으로 찍었다
+ * (server.md D-3/D-4 실측). linear/schedule/custom 도 기존에 대응이 없어 `custom`.
+ */
+export function toLegacyColumnType(column) {
+    const variant = resolveVariant(column);
+    switch (variant) {
+        case "text": return "text";
+        case "number": return "number";
+        case "date": return "date";
+        case "datetime": return "datetime";
+        case "boolean": return "boolean";
+        case "select": return "select";
+        case "multiSelect": return "multiSelect";
+        case "relation":
+        case "linear":
+        case "schedule":
+        case "custom":
+        default:
+            return "custom";
+    }
+}
+/** 기존 `getFilterVariant(columnType)` 표 */
+export function toLegacyFilterVariant(columnType) {
+    switch (columnType) {
+        case "text": return "autocomplete";
+        case "boolean":
+        case "select": return "select";
+        case "multiSelect": return "multi-select";
+        default: return "text";
+    }
+}
+function toLegacyCascadeLevels(levels) {
+    if (!levels)
+        return undefined;
+    return levels.map((level) => ({
+        ...level,
+        filterFn: level.operator,
+        columnFilterModeOptions: [...(level.operatorOptions ?? [])],
+    }));
+}
+/**
+ * koko 컬럼 배열 → 기존 `extractColumnMeta` 가 그대로 읽을 수 있는 사본.
+ *
+ * 키가 없는 컬럼(display)은 결과에서 제외한다 — 기존 함수도 accessorKey 없는 컬럼은
+ * 건너뛰므로 결과는 같다. 원본 객체는 변형하지 않는다.
+ */
+export function toLegacyColumnDefs(columns) {
+    const result = [];
+    for (const column of columns) {
+        const key = columnKey(column);
+        if (!key || !isDataColumnDef(column, key))
+            continue;
+        const columnType = toLegacyColumnType(column);
+        const { cascadeFilterLevels, ...restMeta } = column.meta ?? {};
+        const legacyLevels = toLegacyCascadeLevels(cascadeFilterLevels);
+        const meta = {
+            ...restMeta,
+            columnType,
+            ...(legacyLevels ? { cascadeFilterLevels: legacyLevels } : {}),
+        };
+        result.push({
+            ...column,
+            id: key,
+            accessorKey: key,
+            filterVariant: toLegacyFilterVariant(columnType),
+            ...(column.meta?.selectOptions
+                ? { filterSelectOptions: column.meta.selectOptions.map((o) => ({ ...o })) }
+                : {}),
+            meta,
+        });
+    }
+    return result;
+}

package/dist/core/src/contracts/describeColumns.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 컬럼 선언 요약 — ERP 요청 R11 이 원한 모양.
+ *
+ * 왜 필요한가: ERP `REQUESTS-from-erp.md` R11 은 AI 검색 외에도 어댑터가 컬럼의
+ * 필터 타입·연산자·선택지·관계 하위 컬럼을 **한 번에** 읽는 함수를 원했다.
+ * `extractColumnMeta` 는 AI 계약 모양(type 7종)으로 좁혀 내보내므로, 연산자 목록이나
+ * `dataType` 이 필요한 어댑터(기존 `ColumnMetaData.columnType` 기반 분기, 연산자
+ * 라벨 매핑, 통합 컬럼 정렬 펼침 등)는 이쪽을 쓴다.
+ */
+import type { RowData } from "@tanstack/react-table";
+import type { ColumnDataType, SelectOption, TableColumnDefs } from "../types/column";
+import type { FilterOperator, FilterVariant } from "../types/operators";
+import { type LegacyColumnType } from "./aiColumnMeta";
+export interface ColumnDescription {
+    /** 컬럼 id (= 서버 요청의 필터·정렬 키) */
+    id: string;
+    header: string;
+    /** 기존 `ColumnMetaData.columnType` 과 같은 어휘 (relation/linear/schedule 은 `custom`) */
+    columnType: LegacyColumnType;
+    /** koko 필터 UI 종류 — `columnType` 보다 세밀하다 (relation/linear/schedule/cascade …) */
+    variant: FilterVariant;
+    dataType?: ColumnDataType;
+    /** 이 컬럼이 허용하는 연산자 */
+    operators: readonly FilterOperator[];
+    /** 컬럼 정의에서 파생된 기본 연산자 */
+    defaultOperator: FilterOperator;
+    selectOptions?: SelectOption[];
+    relationColumns?: Array<{
+        key: string;
+        label: string;
+        type?: string;
+    }>;
+    sortExpandsTo?: string[];
+    cascadeFilterLevels?: Array<{
+        key: string;
+        operator: string;
+        operatorOptions: string[];
+    }>;
+    /** 필터 UI 에서 빠지는 컬럼인가 (`filter.hidden` 또는 `meta.forceHidden`) */
+    filterHidden: boolean;
+    /** 값 보관 전용 컬럼 (표시·토글·AI 컨텍스트 모두 제외 대상) */
+    forceHidden: boolean;
+}
+/**
+ * 선언된 컬럼 전부를 요약한다. display 컬럼(`koko-`/`mrt-` 접두)은 제외한다.
+ * 필터가 숨겨진 컬럼도 포함하되 `filterHidden` 으로 표시한다 — 걸러내는 기준은 호출부가 정한다.
+ */
+export declare function describeColumns<T extends RowData>(columns: TableColumnDefs<T>): ColumnDescription[];

package/dist/core/src/contracts/describeColumns.js

@@ -0,0 +1,40 @@
+import { columnKey, deriveOperators, resolveOperatorOptions, resolveVariant } from "../columns/deriveOperators";
+import { toLegacyColumnType } from "./aiColumnMeta";
+function headerText(column, fallback) {
+    const header = column.header;
+    if (typeof header === "string")
+        return header;
+    const label = column.filterLabel;
+    return typeof label === "string" ? label : fallback;
+}
+/**
+ * 선언된 컬럼 전부를 요약한다. display 컬럼(`koko-`/`mrt-` 접두)은 제외한다.
+ * 필터가 숨겨진 컬럼도 포함하되 `filterHidden` 으로 표시한다 — 걸러내는 기준은 호출부가 정한다.
+ */
+export function describeColumns(columns) {
+    const defaults = deriveOperators(columns);
+    const result = [];
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id || id.startsWith("koko-") || id.startsWith("mrt-"))
+            continue;
+        const meta = column.meta;
+        const operators = resolveOperatorOptions(column);
+        result.push({
+            id,
+            header: headerText(column, id),
+            columnType: toLegacyColumnType(column),
+            variant: resolveVariant(column),
+            dataType: meta?.dataType,
+            operators,
+            defaultOperator: defaults[id] ?? operators[0] ?? "fuzzy",
+            ...(meta?.selectOptions ? { selectOptions: meta.selectOptions } : {}),
+            ...(meta?.relationColumns ? { relationColumns: meta.relationColumns } : {}),
+            ...(meta?.sortExpandsTo ? { sortExpandsTo: meta.sortExpandsTo } : {}),
+            ...(meta?.cascadeFilterLevels ? { cascadeFilterLevels: meta.cascadeFilterLevels } : {}),
+            filterHidden: column.filter?.hidden === true || meta?.forceHidden === true,
+            forceHidden: meta?.forceHidden === true,
+        });
+    }
+    return result;
+}

package/dist/core/src/contracts/exportData.d.ts

@@ -0,0 +1,150 @@
+import type { Column, Row, RowData, Table } from "@tanstack/react-table";
+import type { ColumnDataType, ColumnMeta, TableColumnDefs } from "../types/column";
+import type { DataTable } from "../types/table";
+import { type Registry } from "../registry";
+/** 포맷터가 보는 컬럼 — TanStack 인스턴스·컬럼 정의 어느 쪽에서 왔든 같은 모양 */
+export interface ExportColumn {
+    id: string;
+    header: string;
+    dataType?: ColumnDataType;
+    meta?: ColumnMeta;
+}
+/** 기존 `export/types.ts ExtractedTableData` 와 필드 동일 (+ 포맷터용 `columns`) */
+export interface ExtractedTableData<T> {
+    headers: string[];
+    columnKeys: string[];
+    rows: T[];
+    /** `columnKeys` 순서의 컬럼 설명 — 포맷터 해석용. 직접 만든 데이터에는 없을 수 있다 */
+    columns?: ExportColumn[];
+}
+export interface ExtractTableDataOptions<T extends RowData> {
+    /** 선택된 행 — 있으면 이 행들만 내보낸다 (기존 두 번째 인자) */
+    selectedRows?: Row<T>[];
+    /** 행 모델 대신 쓸 원본 행 — 서버 모드에서 전체 조회 결과를 넘길 때 */
+    rows?: T[];
+    /** 보이는 컬럼만 (기본 true). false 면 숨김 컬럼도 포함 */
+    visibleOnly?: boolean;
+    /** 행 번호·선택·액션 같은 display 컬럼 제외 (기본 true) */
+    excludeDisplayColumns?: boolean;
+}
+/** koko/MRT 가 합성하는 display 컬럼 id 접두사 */
+export declare const DISPLAY_COLUMN_PREFIXES: readonly ["koko-", "mrt-"];
+/**
+ * display 컬럼인가 — id 가 `koko-`/`mrt-` 로 시작하거나 accessor 가 없는 컬럼.
+ * 값이 없으니 내보내기에서 뺀다.
+ */
+export declare function isDisplayColumn<T extends RowData>(column: Column<T, unknown>): boolean;
+/**
+ * TanStack 테이블에서 내보내기용 데이터를 추출한다.
+ *
+ * 기본값은 기존과 같다: 보이는 leaf 컬럼 중 display 컬럼을 뺀 것, 행은 선택 행이
+ * 있으면 그것만 아니면 `getPrePaginationRowModel().rows`.
+ */
+export declare function extractTableData<T extends RowData>(table: Table<T>, options?: ExtractTableDataOptions<T>): ExtractedTableData<T>;
+export interface ExtractExportDataSource<T extends RowData> {
+    columns: TableColumnDefs<T>;
+    rows: T[];
+    /** `table.getState().columnVisibility` — 주면 false 인 컬럼을 뺀다 */
+    columnVisibility?: Record<string, boolean>;
+    /** `table.getState().columnOrder` — 주면 이 순서로 정렬(없는 id 는 정의 순서로 뒤에) */
+    columnOrder?: string[];
+}
+/**
+ * 인스턴스 없이 컬럼 정의 + 행 배열로 추출한다.
+ *
+ * 서버 모드에서 "전체 내보내기"는 별도 조회(예: `pageSize: PAGE_SIZE_ALL`)로 받은
+ * 행을 여기에 넘긴다. `meta.forceHidden` 컬럼과 키 없는 컬럼은 항상 뺀다.
+ */
+export declare function extractExportData<T extends RowData>(source: ExtractExportDataSource<T>): ExtractedTableData<T>;
+/** 행에서 컬럼 키 순서대로 값을 뽑는다 — 점 경로(`item.name`) 지원 (기존과 동일) */
+export declare function extractRowValues<T>(row: T, columnKeys: string[]): unknown[];
+/** 값을 내보내기용 문자열로 (기존 `formatValueForExport` 와 같은 규칙) — 포맷터가 없을 때의 기본 */
+export declare function formatValueForExport(value: unknown): string;
+/**
+ * export 포맷터 정의. `id` 가 dataType 과 같으면 그 타입 컬럼에 쓰이고,
+ * `when(column)` 을 주면 타입과 무관하게 조건이 참인 컬럼에 먼저 쓰인다 (등록 순서).
+ */
+export interface ExportFormatterDef {
+    id: ColumnDataType | (string & {});
+    when?: (column: ExportColumn) => boolean;
+    format: (value: unknown, column: ExportColumn) => string;
+}
+/** 정의 헬퍼 — 타입만 고정한다 */
+export declare function defineExportFormatter(def: ExportFormatterDef): ExportFormatterDef;
+/** 배열·레지스트리 어느 쪽으로도 받는다 */
+export type ExportFormatters = ExportFormatterDef[] | Registry<ExportFormatterDef>;
+/**
+ * 내장 포맷터 — 기존 `formatValueForExport` 규칙을 dataType 별로 나눈 것 (dogfooding).
+ * 값 문자열은 예전과 같다: 문자열 날짜는 그대로, `Date` 객체만 ko-KR 로. `select` 는 `enum` 별칭.
+ */
+export declare const BUILTIN_EXPORT_FORMATTERS: readonly ExportFormatterDef[];
+/**
+ * 전역 기본 레지스트리. `exportFormatters.register(def)` 로 앱 전체에 추가하고,
+ * 화면 단위는 `exportFormatters.with({ add })` 나 mui `KokoTableProvider exportFormatters` 로.
+ */
+export declare const exportFormatters: Registry<ExportFormatterDef>;
+/**
+ * 컬럼에 쓸 포맷터. `when` 이 참인 정의(등록 순서) → `id === dataType` → 없음(`undefined`).
+ * `id` 가 dataType 과 같아도 `when` 이 있으면 조건으로만 판단한다.
+ */
+export declare function resolveExportFormatter(column: ExportColumn, registry?: Registry<ExportFormatterDef>): ExportFormatterDef | undefined;
+/** 값 하나를 포맷한다 — 포맷터가 없으면 `formatValueForExport` */
+export declare function formatExportValue(value: unknown, column: ExportColumn, registry?: Registry<ExportFormatterDef>): string;
+/** `data.columns` 가 없으면 키만 있는 컬럼으로 (dataType 없음 → 기본 규칙) */
+export declare function exportColumnsOf<T>(data: ExtractedTableData<T>): ExportColumn[];
+/** 행 하나를 컬럼 순서의 문자열 배열로 — XLSX/PDF 어댑터가 셀 값을 만들 때 쓴다 */
+export declare function formatRowForExport<T>(row: T, data: ExtractedTableData<T>, formatters?: ExportFormatters): string[];
+export interface CsvOptions {
+    /** 구분자 (기본 `,`) */
+    fieldSeparator?: string;
+    /** 모든 필드를 따옴표로 감싼다 (기본 true — 기존 export-to-csv 설정과 동일) */
+    quoteStrings?: boolean;
+    /** 헤더 행 포함 (기본 true) */
+    showColumnHeaders?: boolean;
+    /** UTF-8 BOM 접두 — Excel 이 한글을 바로 읽게 (기본 true) */
+    bom?: boolean;
+    /** 줄바꿈 (기본 `\r\n`) */
+    lineEnding?: string;
+    /** 값 포맷터 — 주면 `formatters` 보다 우선한다 (기본은 포맷터 레지스트리 → `formatValueForExport`) */
+    format?: (value: unknown, columnKey: string) => string;
+    /** 포맷터 레지스트리 또는 정의 배열(내장 세트 위에 add). 미지정 시 전역 `exportFormatters` */
+    formatters?: ExportFormatters;
+}
+/** `ExtractedTableData` → CSV 문자열 */
+export declare function toCsv<T>(data: ExtractedTableData<T>, options?: CsvOptions): string;
+export interface ExportAdapter<T> {
+    /** exceljs 등으로 워크북을 만들어 저장/반환 */
+    toXlsx?: (data: ExtractedTableData<T>, options?: Record<string, unknown>) => Promise<unknown>;
+    /** jspdf 등 */
+    toPdf?: (data: ExtractedTableData<T>, options?: Record<string, unknown>) => Promise<unknown>;
+    /** 새 창 인쇄 */
+    print?: (data: ExtractedTableData<T>, options?: Record<string, unknown>) => void | Promise<void>;
+}
+export interface TableExport<T extends RowData> {
+    /** 행·컬럼 추출 — 기본은 보이는 컬럼 + 현재 행 모델 */
+    getData: (options?: ExtractTableDataOptions<T>) => ExtractedTableData<T>;
+    /** 선택된 행만 */
+    getSelectedData: (options?: Omit<ExtractTableDataOptions<T>, "selectedRows">) => ExtractedTableData<T>;
+    /** CSV 문자열. `data` 미지정이면 `getData()`. 훅의 `formatters` 가 기본으로 들어간다 */
+    toCsv: (data?: ExtractedTableData<T>, options?: CsvOptions) => string;
+    /** 행 하나를 문자열 배열로 — 훅의 `formatters` 로 포맷한다 (XLSX/PDF 어댑터용) */
+    formatRow: (row: T, data: ExtractedTableData<T>) => string[];
+    /** 주입된 어댑터 (없으면 빈 객체) */
+    adapter: ExportAdapter<T>;
+    /** 이 훅이 쓰는 포맷터 레지스트리 */
+    formatters: Registry<ExportFormatterDef>;
+}
+export interface UseTableExportOptions {
+    /** 포맷터 레지스트리 또는 정의 배열. mui 는 `useExportFormatters()` 결과를 넣는다 */
+    formatters?: ExportFormatters;
+}
+/**
+ * 내보내기 훅 — 계약을 테이블 인스턴스에 묶어 준다.
+ *
+ * ```ts
+ * const exp = useTableExport(table, { toXlsx: (d) => import("./xlsx").then(m => m.write(d)) });
+ * download("a.csv", exp.toCsv());
+ * exp.adapter.toXlsx?.(exp.getSelectedData());
+ * ```
+ */
+export declare function useTableExport<T extends RowData>(table: Table<T> | DataTable<T>, adapter?: ExportAdapter<T>, options?: UseTableExportOptions): TableExport<T>;

package/dist/core/src/contracts/exportData.js

@@ -0,0 +1,228 @@
+/**
+ * 내보내기(export) 데이터 계약.
+ *
+ * 왜 필요한가: ERP `packages/table/export/{exportCsv,exportXlsx,exportPdf,printTable}.ts`
+ * 는 모두 `export/extractTableData.ts` 의 `extractTableData(table, selectedRows)` →
+ * `{ headers, columnKeys, rows }` 위에서 동작하고, 이 함수만 MRT 인스턴스
+ * (`getVisibleLeafColumns` / `getPrePaginationRowModel`, `mrt-` 접두 컬럼)에 의존한다
+ * (gap.md 1절 11). CSV/XLSX/PDF 변환 라이브러리는 소비 앱이 동적 import 로 들고 있으므로
+ * koko 는 **행·컬럼을 내주는 계약**과 라이브러리 없이 가능한 CSV 문자열 생성만 제공한다.
+ *
+ * - `extractTableData(table, options)` — TanStack `Table` 기준. 기존과 같은 반환 모양.
+ * - `extractExportData({ columns, rows })` — 인스턴스 없이 컬럼 정의 + 행 배열로.
+ *   서버 모드에서는 `getPrePaginationRowModel()` 이 현재 페이지뿐이라, 전체를 따로
+ *   조회한 뒤 이 오버로드(또는 `options.rows`)로 넘긴다.
+ * - `extractRowValues` / `formatValueForExport` — 기존과 같은 규칙.
+ * - `toCsv(data)` — RFC 4180 CSV 문자열. `useTableExport(table)` 훅이 셋을 묶는다.
+ * - `exportFormatters` — 값 → 문자열 포맷터 레지스트리(설계 문서 4절). dataType 별 내장 세트가 들어 있고,
+ *   `when(column)` 이 참인 정의가 먼저, 그다음 `id === dataType`, 없으면 `formatValueForExport` 다.
+ *   `toCsv`/`useTableExport` 는 `formatters` 옵션(배열·레지스트리)으로 받는다 — mui `useExportFormatters()` 가 Provider 것을 준다.
+ */
+import { useCallback, useMemo } from "react";
+import { columnKey, columnMetaOf } from "../columns/deriveOperators";
+import { getValue } from "../utils/getValue";
+import { createRegistry, toRegistry } from "../registry";
+/** koko/MRT 가 합성하는 display 컬럼 id 접두사 */
+export const DISPLAY_COLUMN_PREFIXES = ["koko-", "mrt-"];
+/**
+ * display 컬럼인가 — id 가 `koko-`/`mrt-` 로 시작하거나 accessor 가 없는 컬럼.
+ * 값이 없으니 내보내기에서 뺀다.
+ */
+export function isDisplayColumn(column) {
+    if (DISPLAY_COLUMN_PREFIXES.some((prefix) => column.id.startsWith(prefix)))
+        return true;
+    return typeof column.accessorFn !== "function";
+}
+function headerOf(header, id) {
+    return (typeof header === "string" ? header : id) || id;
+}
+/**
+ * TanStack 테이블에서 내보내기용 데이터를 추출한다.
+ *
+ * 기본값은 기존과 같다: 보이는 leaf 컬럼 중 display 컬럼을 뺀 것, 행은 선택 행이
+ * 있으면 그것만 아니면 `getPrePaginationRowModel().rows`.
+ */
+export function extractTableData(table, options = {}) {
+    const { selectedRows, rows: rowsOverride, visibleOnly = true, excludeDisplayColumns = true } = options;
+    const leafColumns = visibleOnly ? table.getVisibleLeafColumns() : table.getAllLeafColumns();
+    const columns = excludeDisplayColumns ? leafColumns.filter((c) => !isDisplayColumn(c)) : leafColumns;
+    const headers = columns.map((c) => headerOf(c.columnDef.header, c.id));
+    const columnKeys = columns.map((c) => c.id);
+    const exportColumns = columns.map((c, i) => {
+        const meta = columnMetaOf(c.columnDef);
+        return { id: c.id, header: headers[i], dataType: meta?.dataType, meta };
+    });
+    const rows = rowsOverride
+        ? rowsOverride
+        : selectedRows?.length
+            ? selectedRows.map((r) => r.original)
+            : table.getPrePaginationRowModel().rows.map((r) => r.original);
+    return { headers, columnKeys, rows, columns: exportColumns };
+}
+/**
+ * 인스턴스 없이 컬럼 정의 + 행 배열로 추출한다.
+ *
+ * 서버 모드에서 "전체 내보내기"는 별도 조회(예: `pageSize: PAGE_SIZE_ALL`)로 받은
+ * 행을 여기에 넘긴다. `meta.forceHidden` 컬럼과 키 없는 컬럼은 항상 뺀다.
+ */
+export function extractExportData(source) {
+    const { columns, rows, columnVisibility, columnOrder } = source;
+    const entries = [];
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        if (column.meta?.forceHidden)
+            continue;
+        if (DISPLAY_COLUMN_PREFIXES.some((prefix) => id.startsWith(prefix)))
+            continue;
+        if (columnVisibility && columnVisibility[id] === false)
+            continue;
+        if (!columnVisibility && column.meta?.isVisible === false)
+            continue;
+        entries.push({
+            id, header: headerOf(column.header, id),
+            dataType: column.meta?.dataType, meta: column.meta,
+        });
+    }
+    if (columnOrder?.length) {
+        const rank = new Map(columnOrder.map((id, i) => [id, i]));
+        entries.sort((a, b) => {
+            const ra = rank.get(a.id) ?? Number.MAX_SAFE_INTEGER;
+            const rb = rank.get(b.id) ?? Number.MAX_SAFE_INTEGER;
+            return ra - rb;
+        });
+    }
+    return {
+        headers: entries.map((e) => e.header),
+        columnKeys: entries.map((e) => e.id),
+        rows,
+        columns: entries,
+    };
+}
+/** 행에서 컬럼 키 순서대로 값을 뽑는다 — 점 경로(`item.name`) 지원 (기존과 동일) */
+export function extractRowValues(row, columnKeys) {
+    return columnKeys.map((key) => getValue(row, key));
+}
+/** 값을 내보내기용 문자열로 (기존 `formatValueForExport` 와 같은 규칙) — 포맷터가 없을 때의 기본 */
+export function formatValueForExport(value) {
+    if (value == null)
+        return "";
+    if (value instanceof Date)
+        return value.toLocaleDateString("ko-KR");
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
+/** 정의 헬퍼 — 타입만 고정한다 */
+export function defineExportFormatter(def) {
+    return def;
+}
+const toDate = (value) => {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === "string" || typeof value === "number") {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    return undefined;
+};
+/**
+ * 내장 포맷터 — 기존 `formatValueForExport` 규칙을 dataType 별로 나눈 것 (dogfooding).
+ * 값 문자열은 예전과 같다: 문자열 날짜는 그대로, `Date` 객체만 ko-KR 로. `select` 는 `enum` 별칭.
+ */
+export const BUILTIN_EXPORT_FORMATTERS = [
+    defineExportFormatter({ id: "text", format: (value) => formatValueForExport(value) }),
+    defineExportFormatter({ id: "number", format: (value) => formatValueForExport(value) }),
+    defineExportFormatter({
+        id: "date",
+        format: (value) => (value instanceof Date ? value.toLocaleDateString("ko-KR") : formatValueForExport(value)),
+    }),
+    defineExportFormatter({
+        id: "datetime",
+        format: (value) => (value instanceof Date ? value.toLocaleString("ko-KR") : formatValueForExport(value)),
+    }),
+    defineExportFormatter({ id: "boolean", format: (value) => formatValueForExport(value) }),
+    defineExportFormatter({ id: "enum", format: (value) => formatValueForExport(value) }),
+    defineExportFormatter({ id: "select", format: (value) => formatValueForExport(value) }),
+];
+/**
+ * 전역 기본 레지스트리. `exportFormatters.register(def)` 로 앱 전체에 추가하고,
+ * 화면 단위는 `exportFormatters.with({ add })` 나 mui `KokoTableProvider exportFormatters` 로.
+ */
+export const exportFormatters = createRegistry([...BUILTIN_EXPORT_FORMATTERS]);
+/**
+ * 컬럼에 쓸 포맷터. `when` 이 참인 정의(등록 순서) → `id === dataType` → 없음(`undefined`).
+ * `id` 가 dataType 과 같아도 `when` 이 있으면 조건으로만 판단한다.
+ */
+export function resolveExportFormatter(column, registry = exportFormatters) {
+    const defs = registry.list();
+    for (const def of defs)
+        if (def.when && def.when(column))
+            return def;
+    if (column.dataType) {
+        const byType = defs.find((def) => def.id === column.dataType && !def.when);
+        if (byType)
+            return byType;
+    }
+    return undefined;
+}
+/** 값 하나를 포맷한다 — 포맷터가 없으면 `formatValueForExport` */
+export function formatExportValue(value, column, registry = exportFormatters) {
+    const def = resolveExportFormatter(column, registry);
+    return def ? def.format(value, column) : formatValueForExport(value);
+}
+/** `data.columns` 가 없으면 키만 있는 컬럼으로 (dataType 없음 → 기본 규칙) */
+export function exportColumnsOf(data) {
+    if (data.columns && data.columns.length === data.columnKeys.length)
+        return data.columns;
+    return data.columnKeys.map((id, i) => ({ id, header: data.headers[i] ?? id }));
+}
+/** 행 하나를 컬럼 순서의 문자열 배열로 — XLSX/PDF 어댑터가 셀 값을 만들 때 쓴다 */
+export function formatRowForExport(row, data, formatters) {
+    const registry = formatters ? toRegistry(formatters, [...BUILTIN_EXPORT_FORMATTERS]) : exportFormatters;
+    const columns = exportColumnsOf(data);
+    return extractRowValues(row, data.columnKeys).map((value, i) => formatExportValue(value, columns[i], registry));
+}
+function csvField(text, separator, quoteAll) {
+    const needsQuote = quoteAll || text.includes(separator) || /["\r\n]/.test(text);
+    return needsQuote ? `"${text.replace(/"/g, '""')}"` : text;
+}
+/** `ExtractedTableData` → CSV 문자열 */
+export function toCsv(data, options = {}) {
+    const { fieldSeparator = ",", quoteStrings = true, showColumnHeaders = true, bom = true, lineEnding = "\r\n", format, formatters, } = options;
+    const registry = formatters ? toRegistry(formatters, [...BUILTIN_EXPORT_FORMATTERS]) : exportFormatters;
+    const columns = exportColumnsOf(data);
+    const formatCell = format
+        ? (value, i) => format(value, data.columnKeys[i])
+        : (value, i) => formatExportValue(value, columns[i], registry);
+    const lines = [];
+    if (showColumnHeaders) {
+        lines.push(data.headers.map((h) => csvField(h, fieldSeparator, quoteStrings)).join(fieldSeparator));
+    }
+    for (const row of data.rows) {
+        const values = extractRowValues(row, data.columnKeys);
+        lines.push(values
+            .map((v, i) => csvField(formatCell(v, i), fieldSeparator, quoteStrings))
+            .join(fieldSeparator));
+    }
+    return (bom ? "\uFEFF" : "") + lines.join(lineEnding);
+}
+/**
+ * 내보내기 훅 — 계약을 테이블 인스턴스에 묶어 준다.
+ *
+ * ```ts
+ * const exp = useTableExport(table, { toXlsx: (d) => import("./xlsx").then(m => m.write(d)) });
+ * download("a.csv", exp.toCsv());
+ * exp.adapter.toXlsx?.(exp.getSelectedData());
+ * ```
+ */
+export function useTableExport(table, adapter = {}, options = {}) {
+    const { formatters: given } = options;
+    const formatters = useMemo(() => (given ? toRegistry(given, [...BUILTIN_EXPORT_FORMATTERS]) : exportFormatters), [given]);
+    const getData = useCallback((options) => extractTableData(table, options), [table]);
+    const getSelectedData = useCallback((options) => extractTableData(table, { ...options, selectedRows: table.getSelectedRowModel().rows }), [table]);
+    const csv = useCallback((data, csvOptions) => toCsv(data ?? getData(), { formatters, ...csvOptions }), [getData, formatters]);
+    const formatRow = useCallback((row, data) => formatRowForExport(row, data, formatters), [formatters]);
+    return useMemo(() => ({ getData, getSelectedData, toCsv: csv, formatRow, adapter, formatters }), [getData, getSelectedData, csv, formatRow, adapter, formatters]);
+}