kokotable 0.95.0

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

@@ -0,0 +1,6 @@
+export { extractColumnMeta, toAiColumnType, toLegacyColumnDefs, toLegacyColumnType, toLegacyFilterVariant, type AiColumnMeta, type AiInnerColumnMeta, type AiColumnType, type ExtractColumnMetaOptions, type LegacyColumnType, type LegacyFilterVariant, type LegacyCascadeFilterLevel, type LegacyCompatColumnDef, type LegacyCompatColumnMeta, } from "./aiColumnMeta";
+export { extractPresetState, applyPresetState, reconcileColumnOrder, presetToSearchState, presetToSearchInitial, type PresetState, type PresetDensity, type PresetSearchPart, type ExtractPresetExtras, type ApplyPresetHandlers, } from "./preset";
+export { extractTableData, extractExportData, extractRowValues, formatValueForExport, isDisplayColumn, toCsv, useTableExport, DISPLAY_COLUMN_PREFIXES, exportFormatters, defineExportFormatter, resolveExportFormatter, formatExportValue, formatRowForExport, exportColumnsOf, BUILTIN_EXPORT_FORMATTERS, type ExtractedTableData, type ExtractTableDataOptions, type ExtractExportDataSource, type CsvOptions, type ExportAdapter, type TableExport, type UseTableExportOptions, type ExportColumn, type ExportFormatterDef, type ExportFormatters, } from "./exportData";
+export { decodeLegacyTableParams, normalizeLegacySearchState, isoToLocalDate, DEFAULT_LEGACY_PARAM_KEYS, type LegacyTableParams, } from "./legacyUrl";
+export { type ReadUrlSearchStateOptions } from "../hooks/useUrlSync";
+export { describeColumns, type ColumnDescription } from "./describeColumns";

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

@@ -0,0 +1,12 @@
+// 소비 앱(ERP) 연동 계약 — AI 검색 컬럼 메타, 프리셋, 내보내기, 구 URL 포맷
+//
+// 각 파일 상단 주석에 "어떤 ERP 파일이 왜 소비하는가" 를 적어 두었다.
+// `readUrlSearchState` / `useUrlSync` 자체는 `hooks/index.ts` 가 노출한다 —
+// 여기서는 이번에 추가된 심볼만 덧붙인다.
+export { extractColumnMeta, toAiColumnType, toLegacyColumnDefs, toLegacyColumnType, toLegacyFilterVariant, } from "./aiColumnMeta";
+export { extractPresetState, applyPresetState, reconcileColumnOrder, presetToSearchState, presetToSearchInitial, } from "./preset";
+export { extractTableData, extractExportData, extractRowValues, formatValueForExport, isDisplayColumn, toCsv, useTableExport, DISPLAY_COLUMN_PREFIXES, 
+// 포맷터 레지스트리
+exportFormatters, defineExportFormatter, resolveExportFormatter, formatExportValue, formatRowForExport, exportColumnsOf, BUILTIN_EXPORT_FORMATTERS, } from "./exportData";
+export { decodeLegacyTableParams, normalizeLegacySearchState, isoToLocalDate, DEFAULT_LEGACY_PARAM_KEYS, } from "./legacyUrl";
+export { describeColumns } from "./describeColumns";

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

@@ -0,0 +1,47 @@
+/**
+ * 구(舊) URL 포맷 디코더.
+ *
+ * 왜 필요한가: ERP 는 두 가지 URL 인코딩을 쓰고 있었다 (server.md D-2, gap.md 1절 42).
+ * - `core/useUrlTableParams.ts` — `tp=` + `btoa(JSON)` URL-safe (ASCII 한정, 한글이면 실패)
+ * - `utils/tableUrlParams.ts` — `filter=` + `btoa(encodeURIComponent(JSON))`
+ *   (`buildTransactionFilterUrl` 등 22 호출부가 공유 링크로 뿌려 놓았다)
+ * koko `readUrlSearchState` 는 UTF-8 base64 라 ASCII `tp` 는 이미 읽히지만
+ * `filter=` 스킴은 읽지 못하고, 값 모양(SearchConfig — 날짜가 ISO 시각 문자열)도
+ * koko `SearchState`(날짜는 `YYYY-MM-DD`) 와 다르다.
+ *
+ * - `decodeLegacyTableParams(text)` — UTF-8 base64 → 순수 atob JSON → atob+decodeURIComponent
+ *   JSON 순으로 시도한다.
+ * - `normalizeLegacySearchState(state, columns?)` — 기존 `SearchConfig` 모양을 koko
+ *   `SearchState` 로 정규화한다. 날짜 필터의 ISO 시각 문자열을 로컬 `YYYY-MM-DD` 로 바꾼다.
+ * `readUrlSearchState`(hooks/useUrlSync.ts) 가 실패 시 이 디코더로 폴백한다.
+ */
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { SearchState } from "../types/search";
+import { isoToLocalDate } from "../utils/dateText";
+export { isoToLocalDate };
+/** 구 스킴이 쓰던 파라미터 키 — `readUrlSearchState` 가 `paramKey` 다음으로 훑는다 */
+export declare const DEFAULT_LEGACY_PARAM_KEYS: readonly string[];
+/** 기존 `GenericFilterData`/`SearchConfig` 를 느슨하게 받는 모양 */
+export type LegacyTableParams = Partial<Omit<SearchState, "columnFilterFns">> & {
+    columnFilterFns?: Record<string, string>;
+    [key: string]: unknown;
+};
+/**
+ * URL 파라미터 값 하나를 세 인코딩으로 순서대로 디코드한다.
+ * 어느 것도 JSON 객체를 내지 못하면 undefined.
+ */
+export declare function decodeLegacyTableParams(text: string): LegacyTableParams | undefined;
+/**
+ * 기존 `SearchConfig` 모양의 객체 → koko `Partial<SearchState>`.
+ *
+ * - 컬럼에 필터 kind 가 있고 `codec` 을 선언했으면 그 `decode` 를 거친다 (내장 date kind 가
+ *   ISO 시각 → `YYYY-MM-DD` 를 맡는다). decode 가 undefined 면 항목을 뺀다.
+ * - 그 외 날짜 필터 값이 ISO 시각 문자열이면 로컬 `YYYY-MM-DD` 로 바꾼다.
+ *   `columns` 가 주어지면 date/datetime 컬럼에만, 없으면 ISO 패턴이면서 연산자가
+ *   `dateBetween`/`betweenInclusive` 인 항목에만 적용한다.
+ * - `columnFilterFns` 값이 문자열이면 그대로 둔다.
+ * - 알려진 필드(columnFilters/columnFilterFns/globalFilter/pagination/sorting/grouping/
+ *   virtualColumns) 만 남긴다.
+ */
+export declare function normalizeLegacySearchState<T extends RowData = RowData>(state: LegacyTableParams | Record<string, unknown>, columns?: TableColumnDefs<T>): Partial<SearchState>;

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

@@ -0,0 +1,156 @@
+import { columnKey, resolveVariant } from "../columns/deriveOperators";
+import { isoToLocalDate } from "../utils/dateText";
+import { decodeFilterValues, filterKindMap } from "../filters/codec";
+export { isoToLocalDate };
+/** 구 스킴이 쓰던 파라미터 키 — `readUrlSearchState` 가 `paramKey` 다음으로 훑는다 */
+export const DEFAULT_LEGACY_PARAM_KEYS = ["filter"];
+const toStandardBase64 = (text) => text.replace(/-/g, "+").replace(/_/g, "/");
+function parseJsonObject(json) {
+    const parsed = JSON.parse(json);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+}
+/** koko 방식 — base64 바이트를 UTF-8 로 해석. 잘못된 바이트열이면 throw (fatal) */
+function decodeUtf8Base64(text) {
+    const binary = atob(toStandardBase64(text));
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return parseJsonObject(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+}
+/** 기존 `useUrlTableParams` — `btoa(JSON)` (Latin1 문자열 그대로) */
+function decodePlainBase64(text) {
+    return parseJsonObject(atob(toStandardBase64(text)));
+}
+/** 기존 `tableUrlParams` — `btoa(encodeURIComponent(JSON))` */
+function decodeUriBase64(text) {
+    return parseJsonObject(decodeURIComponent(atob(toStandardBase64(text))));
+}
+/**
+ * URL 파라미터 값 하나를 세 인코딩으로 순서대로 디코드한다.
+ * 어느 것도 JSON 객체를 내지 못하면 undefined.
+ */
+export function decodeLegacyTableParams(text) {
+    if (!text)
+        return undefined;
+    const decoders = [decodeUtf8Base64, decodePlainBase64, decodeUriBase64];
+    for (const decode of decoders) {
+        try {
+            const result = decode(text);
+            if (result)
+                return result;
+        }
+        catch {
+            // 다음 인코딩 시도
+        }
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────
+// SearchConfig → SearchState 정규화
+// ─────────────────────────────────────────────────────────────
+/** 컬럼 정보가 없을 때 "날짜 항목" 으로 보는 연산자 */
+const LEGACY_DATE_OPERATORS = new Set(["dateBetween", "betweenInclusive"]);
+function convertDateValue(value) {
+    if (Array.isArray(value))
+        return value.map((v) => isoToLocalDate(v));
+    return isoToLocalDate(value);
+}
+function isDateColumnSet(columns) {
+    const ids = new Set();
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        const variant = resolveVariant(column);
+        const dataType = column.meta?.dataType;
+        if (variant === "date" || variant === "datetime" || dataType === "date" || dataType === "datetime") {
+            ids.add(id);
+        }
+    }
+    return ids;
+}
+function normalizeFilterFns(fns) {
+    if (!fns || typeof fns !== "object" || Array.isArray(fns))
+        return undefined;
+    const out = {};
+    for (const [id, op] of Object.entries(fns)) {
+        // 문자열이면 그대로 — 검증은 서버가 한다 (모르는 연산자는 기본값으로 강등)
+        if (typeof op === "string" && op.length > 0)
+            out[id] = op;
+    }
+    return out;
+}
+function normalizeFilters(filters) {
+    if (!Array.isArray(filters))
+        return undefined;
+    const out = [];
+    for (const entry of filters) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const { id, value } = entry;
+        if (typeof id !== "string" || !id)
+            continue;
+        out.push({ id, value });
+    }
+    return out;
+}
+/**
+ * 기존 `SearchConfig` 모양의 객체 → koko `Partial<SearchState>`.
+ *
+ * - 컬럼에 필터 kind 가 있고 `codec` 을 선언했으면 그 `decode` 를 거친다 (내장 date kind 가
+ *   ISO 시각 → `YYYY-MM-DD` 를 맡는다). decode 가 undefined 면 항목을 뺀다.
+ * - 그 외 날짜 필터 값이 ISO 시각 문자열이면 로컬 `YYYY-MM-DD` 로 바꾼다.
+ *   `columns` 가 주어지면 date/datetime 컬럼에만, 없으면 ISO 패턴이면서 연산자가
+ *   `dateBetween`/`betweenInclusive` 인 항목에만 적용한다.
+ * - `columnFilterFns` 값이 문자열이면 그대로 둔다.
+ * - 알려진 필드(columnFilters/columnFilterFns/globalFilter/pagination/sorting/grouping/
+ *   virtualColumns) 만 남긴다.
+ */
+export function normalizeLegacySearchState(state, columns) {
+    const src = state;
+    const result = {};
+    const fns = normalizeFilterFns(src.columnFilterFns);
+    if (fns)
+        result.columnFilterFns = fns;
+    const filters = normalizeFilters(src.columnFilters);
+    if (filters) {
+        const dateColumns = columns ? isDateColumnSet(columns) : undefined;
+        const withCodec = columns ? filterKindMap(columns) : undefined;
+        const legacyConverted = filters.map((entry) => {
+            // kind codec 이 있는 컬럼은 아래 decodeFilterValues 가 맡는다
+            if (withCodec?.get(entry.id)?.codec)
+                return entry;
+            const isDate = dateColumns
+                ? dateColumns.has(entry.id)
+                : LEGACY_DATE_OPERATORS.has(fns?.[entry.id] ?? "");
+            return isDate ? { id: entry.id, value: convertDateValue(entry.value) } : entry;
+        });
+        result.columnFilters = columns ? decodeFilterValues(columns, legacyConverted) : legacyConverted;
+    }
+    if (typeof src.globalFilter === "string")
+        result.globalFilter = src.globalFilter;
+    const pagination = src.pagination;
+    if (pagination && typeof pagination === "object") {
+        const pageIndex = Number(pagination.pageIndex);
+        const pageSize = Number(pagination.pageSize);
+        if (Number.isFinite(pageIndex) && Number.isFinite(pageSize)) {
+            result.pagination = { pageIndex, pageSize };
+        }
+    }
+    if (Array.isArray(src.sorting)) {
+        result.sorting = src.sorting
+            .filter((s) => s && typeof s.id === "string")
+            .map((s) => ({
+            id: s.id,
+            desc: Boolean(s.desc),
+            ...(typeof s.key === "string" ? { key: s.key } : {}),
+        }));
+    }
+    if (Array.isArray(src.grouping)) {
+        result.grouping = src.grouping.filter((g) => typeof g === "string");
+    }
+    if (src.virtualColumns && typeof src.virtualColumns === "object" && !Array.isArray(src.virtualColumns)) {
+        result.virtualColumns = src.virtualColumns;
+    }
+    return result;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * 프리셋(TablePreset `state_json`) 계약.
+ *
+ * 왜 필요한가: ERP `packages/table/preset/usePreset.ts`(서버 API 훅) 와
+ * `Save/Edit/ManagePresetsDialog` 는 MRT 무의존이라 그대로 재사용하지만,
+ * `preset/presetStateUtils.ts` 의 `extractPresetState` / `applyPresetToTable` 은
+ * `table.params` / `table.setParams` / `table.setDensity` 라는 MRT 확장 인스턴스에
+ * 붙어 있어 koko `DataTable` 에서는 동작하지 않는다 (server.md D-1, gap.md 1절 13).
+ *
+ * 여기서는 같은 `PresetState` 모양을 core 에 정의하고
+ * - 검색 부분은 `table.search.params` / `table.search.setParams`(완전한 SearchState —
+ *   현재 params 와 병합해서 넘긴다),
+ * - 컬럼 UI 부분은 TanStack `table.getState()` / `setColumnVisibility` 등,
+ * - `density` 는 TanStack 상태에 없으므로 `extras` / `handlers` 로 무손실 왕복
+ * 하도록 옮겼다. `usePreset` 자체는 만들지 않는다 — ERP 가 기존 것을 쓴다.
+ *
+ * `usePreset` 이 요구하는 것은 `PresetState` 직렬화 가능 객체 하나뿐이다:
+ *   savePreset(name, extractPresetState(table, { density }), scope)
+ *   applyPresetState(table, preset.state_json, { setDensity })
+ */
+import type { RowData } from "@tanstack/react-table";
+import type { DataTable } from "../types/table";
+import type { SearchState } from "../types/search";
+import type { FilterOperator } from "../types/operators";
+import type { TableColumnDefs } from "../types/column";
+export type PresetDensity = "comfortable" | "compact" | "spacious";
+/** 기존 `preset/types.ts PresetState` 와 필드 동일 (sorting[].key 만 optional 로 추가) */
+export interface PresetState {
+    columnVisibility?: Record<string, boolean>;
+    columnOrder?: string[];
+    columnSizing?: Record<string, number>;
+    columnPinning?: {
+        left?: string[];
+        right?: string[];
+    };
+    columnFilters?: Array<{
+        id: string;
+        value: unknown;
+    }>;
+    columnFilterFns?: Record<string, string>;
+    globalFilter?: string;
+    sorting?: Array<{
+        id: string;
+        desc: boolean;
+        key?: string;
+    }>;
+    grouping?: string[];
+    density?: PresetDensity;
+    pagination?: {
+        pageIndex: number;
+        pageSize: number;
+    };
+}
+export interface ExtractPresetExtras {
+    /** koko 에는 density 상태가 없다 — 렌더러/호출부가 들고 있는 값을 넘긴다 */
+    density?: PresetDensity;
+}
+export interface ApplyPresetHandlers {
+    /** 저장된 density 를 받을 곳. 미지정이면 density 는 무시된다 */
+    setDensity?: (density: PresetDensity) => void;
+}
+/** 검색 부분만 — `usePreset` 없이 `useTableSearch({ initial })` 에 넘길 때 */
+export type PresetSearchPart = Pick<PresetState, "columnFilters" | "columnFilterFns" | "globalFilter" | "sorting" | "grouping" | "pagination">;
+/**
+ * `DataTable` 에서 저장할 상태를 추출한다.
+ *
+ * - 컬럼 UI(columnVisibility/Order/Sizing/Pinning)는 `table.getState()`
+ * - 검색(columnFilters/columnFilterFns/globalFilter/sorting/grouping/pagination)은
+ *   `table.search.params`. 연산자는 `search.operators`(컬럼 기본값 + 사용자 변경분의
+ *   완전한 맵)를 싣는다 — 기존도 `params.columnFilterFns` 완전 맵을 저장했다.
+ * - density 는 `extras.density`
+ * - 필터 값은 컬럼 kind 의 `codec.encode` 를 거친다 (내장 date kind: Date/ISO → `YYYY-MM-DD`)
+ */
+export declare function extractPresetState<T extends RowData>(table: DataTable<T>, extras?: ExtractPresetExtras): PresetState;
+/**
+ * 저장된 columnOrder 를 현재 컬럼 정의와 맞춘다 (기존 `reconcileColumnOrder` 그대로).
+ *
+ * TanStack 은 order 배열에 없는 컬럼을 맨 뒤에 append 하므로, 프리셋 저장 이후
+ * 추가된 컬럼이 표 오른쪽 끝으로 밀려난다. 정의 순서상 바로 앞 컬럼 뒤에 끼워넣어
+ * 원래 자리에 가깝게 복원한다. 사라진 컬럼 id 는 제거.
+ */
+export declare function reconcileColumnOrder(currentIds: string[], storedOrder: string[]): string[];
+/**
+ * 프리셋의 검색 부분을 **완전한 SearchState** 로 만든다.
+ *
+ * `table.search.setParams` 는 부분 상태를 받지 않으므로 현재 params 위에 얹는다.
+ * 연산자는 기존 `applyPresetToTable` 과 같은 방향으로 병합한다 — 컬럼 기본값
+ * (`baseOperators`, 보통 `search.operators`)이 새 컬럼을 보완하고, 프리셋 값이 덮어쓴다.
+ * `columns` 를 주면 필터 값이 컬럼 kind 의 `codec.decode` 를 거친다.
+ */
+export declare function presetToSearchState(preset: PresetSearchPart, current: SearchState, baseOperators?: Record<string, FilterOperator>, columns?: TableColumnDefs<any>): SearchState;
+/**
+ * `useTableSearch({ initial })` 에 넘길 검색 초기값 — 마운트 시점에 기본 프리셋을
+ * 적용할 때 쓴다. 연산자는 `initialState` 가 `deriveOperators(columns)` 위에 얹는다.
+ */
+export declare function presetToSearchInitial(preset: PresetSearchPart, columns?: TableColumnDefs<any>): Partial<SearchState>;
+/**
+ * 프리셋 상태를 `DataTable` 에 적용한다.
+ *
+ * - 검색 부분은 `table.search.setParams(완전한 상태)` 로 즉시 적용 (조회 트리거)
+ * - 컬럼 UI 부분은 TanStack setter 로 즉시 적용 (시각 변경만)
+ * - density 는 `handlers.setDensity` 가 있을 때만
+ */
+export declare function applyPresetState<T extends RowData>(table: DataTable<T>, preset: PresetState, handlers?: ApplyPresetHandlers): void;

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

@@ -0,0 +1,141 @@
+import { DEFAULT_PAGE_SIZE } from "../defaults";
+import { decodeFilterValues, encodeFilterValues } from "../filters/codec";
+const toOperators = (fns) => {
+    const out = {};
+    for (const [id, op] of Object.entries(fns ?? {})) {
+        if (typeof op === "string" && op.length > 0)
+            out[id] = op;
+    }
+    return out;
+};
+/**
+ * `DataTable` 에서 저장할 상태를 추출한다.
+ *
+ * - 컬럼 UI(columnVisibility/Order/Sizing/Pinning)는 `table.getState()`
+ * - 검색(columnFilters/columnFilterFns/globalFilter/sorting/grouping/pagination)은
+ *   `table.search.params`. 연산자는 `search.operators`(컬럼 기본값 + 사용자 변경분의
+ *   완전한 맵)를 싣는다 — 기존도 `params.columnFilterFns` 완전 맵을 저장했다.
+ * - density 는 `extras.density`
+ * - 필터 값은 컬럼 kind 의 `codec.encode` 를 거친다 (내장 date kind: Date/ISO → `YYYY-MM-DD`)
+ */
+export function extractPresetState(table, extras = {}) {
+    const state = table.getState();
+    const params = table.search.params;
+    return {
+        columnVisibility: { ...state.columnVisibility },
+        columnOrder: [...(state.columnOrder ?? [])],
+        columnSizing: { ...state.columnSizing },
+        columnPinning: {
+            left: [...(state.columnPinning?.left ?? [])],
+            right: [...(state.columnPinning?.right ?? [])],
+        },
+        columnFilters: encodeFilterValues(table.search.columns, params.columnFilters)
+            .map((f) => ({ id: f.id, value: f.value })),
+        columnFilterFns: { ...table.search.operators },
+        globalFilter: params.globalFilter ?? "",
+        sorting: params.sorting.map((s) => ({ id: s.id, desc: s.desc, ...(s.key ? { key: s.key } : {}) })),
+        grouping: [...(params.grouping ?? [])],
+        ...(extras.density !== undefined ? { density: extras.density } : {}),
+        pagination: {
+            pageIndex: params.pagination?.pageIndex ?? state.pagination?.pageIndex ?? 0,
+            pageSize: params.pagination?.pageSize ?? state.pagination?.pageSize ?? DEFAULT_PAGE_SIZE,
+        },
+    };
+}
+/**
+ * 저장된 columnOrder 를 현재 컬럼 정의와 맞춘다 (기존 `reconcileColumnOrder` 그대로).
+ *
+ * TanStack 은 order 배열에 없는 컬럼을 맨 뒤에 append 하므로, 프리셋 저장 이후
+ * 추가된 컬럼이 표 오른쪽 끝으로 밀려난다. 정의 순서상 바로 앞 컬럼 뒤에 끼워넣어
+ * 원래 자리에 가깝게 복원한다. 사라진 컬럼 id 는 제거.
+ */
+export function reconcileColumnOrder(currentIds, storedOrder) {
+    const currentSet = new Set(currentIds);
+    const result = storedOrder.filter((id) => currentSet.has(id));
+    const kept = new Set(result);
+    currentIds.forEach((id, i) => {
+        if (kept.has(id))
+            return;
+        let anchor = -1;
+        for (let j = i - 1; j >= 0; j--) {
+            const pos = result.indexOf(currentIds[j]);
+            if (pos !== -1) {
+                anchor = pos;
+                break;
+            }
+        }
+        result.splice(anchor + 1, 0, id);
+        kept.add(id);
+    });
+    return result;
+}
+/**
+ * 프리셋의 검색 부분을 **완전한 SearchState** 로 만든다.
+ *
+ * `table.search.setParams` 는 부분 상태를 받지 않으므로 현재 params 위에 얹는다.
+ * 연산자는 기존 `applyPresetToTable` 과 같은 방향으로 병합한다 — 컬럼 기본값
+ * (`baseOperators`, 보통 `search.operators`)이 새 컬럼을 보완하고, 프리셋 값이 덮어쓴다.
+ * `columns` 를 주면 필터 값이 컬럼 kind 의 `codec.decode` 를 거친다.
+ */
+export function presetToSearchState(preset, current, baseOperators = current.columnFilterFns, columns) {
+    return {
+        ...current,
+        columnFilters: decodeFilterValues(columns, (preset.columnFilters ?? []).map((f) => ({
+            id: f.id,
+            value: Array.isArray(f.value) ? [...f.value] : f.value,
+        }))),
+        columnFilterFns: { ...baseOperators, ...toOperators(preset.columnFilterFns) },
+        sorting: (preset.sorting ?? []).map((s) => ({ ...s })),
+        grouping: [...(preset.grouping ?? [])],
+        globalFilter: preset.globalFilter ?? "",
+        pagination: {
+            pageIndex: preset.pagination?.pageIndex ?? 0,
+            pageSize: preset.pagination?.pageSize ?? DEFAULT_PAGE_SIZE,
+        },
+    };
+}
+/**
+ * `useTableSearch({ initial })` 에 넘길 검색 초기값 — 마운트 시점에 기본 프리셋을
+ * 적용할 때 쓴다. 연산자는 `initialState` 가 `deriveOperators(columns)` 위에 얹는다.
+ */
+export function presetToSearchInitial(preset, columns) {
+    return {
+        columnFilters: decodeFilterValues(columns, (preset.columnFilters ?? []).map((f) => ({ id: f.id, value: f.value }))),
+        columnFilterFns: toOperators(preset.columnFilterFns),
+        globalFilter: preset.globalFilter ?? "",
+        sorting: (preset.sorting ?? []).map((s) => ({ ...s })),
+        ...(preset.grouping !== undefined ? { grouping: [...preset.grouping] } : {}),
+        ...(preset.pagination !== undefined ? { pagination: { ...preset.pagination } } : {}),
+    };
+}
+/**
+ * 프리셋 상태를 `DataTable` 에 적용한다.
+ *
+ * - 검색 부분은 `table.search.setParams(완전한 상태)` 로 즉시 적용 (조회 트리거)
+ * - 컬럼 UI 부분은 TanStack setter 로 즉시 적용 (시각 변경만)
+ * - density 는 `handlers.setDensity` 가 있을 때만
+ */
+export function applyPresetState(table, preset, handlers = {}) {
+    table.search.setParams(presetToSearchState(preset, table.search.params, { ...table.search.operators }, table.search.columns));
+    if (preset.columnVisibility !== undefined) {
+        table.setColumnVisibility({ ...preset.columnVisibility });
+    }
+    if (preset.columnOrder !== undefined) {
+        const currentIds = table.getAllLeafColumns().map((c) => c.id);
+        table.setColumnOrder(currentIds.length > 0
+            ? reconcileColumnOrder(currentIds, preset.columnOrder)
+            : [...preset.columnOrder]);
+    }
+    if (preset.columnSizing !== undefined) {
+        table.setColumnSizing({ ...preset.columnSizing });
+    }
+    if (preset.columnPinning !== undefined) {
+        table.setColumnPinning({
+            left: [...(preset.columnPinning.left ?? [])],
+            right: [...(preset.columnPinning.right ?? [])],
+        });
+    }
+    if (preset.density !== undefined) {
+        handlers.setDensity?.(preset.density);
+    }
+}

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

@@ -0,0 +1,81 @@
+/**
+ * 프리셋 저장소 계약.
+ *
+ * `preset.ts` 는 "상태를 JSON 으로 뽑고 되돌리는" 순수 함수만 두고, 어디에 저장하는가는
+ * 소비 앱 몫으로 남겨 두었다. 그 결과 스토리마다 localStorage 조립 코드가 반복됐고,
+ * ERP 는 react-query `usePreset` 을 따로 들고 있어 mui `PresetBar` 같은 공용 UI 를 만들 수
+ * 없었다. 여기서는 저장소를 **비동기 인터페이스 하나**(`PresetStore`) 로 고정한다 —
+ * localStorage 든 서버 API 든 같은 네 메서드만 있으면 `usePresets` / `PresetBar` 가 붙는다.
+ *
+ * ERP 서버(`TablePresetApi`) 연결 예:
+ *   const store: PresetStore = {
+ *     list: (tableKey) => fetchPresets(tableKey).then((rows) => rows.map(fromErp)),
+ *     save: (p) => (p.id ? patchPreset(Number(p.id), toErp(p)) : createPreset(toErp(p))).then(fromErp),
+ *     remove: (id) => removePreset(Number(id)),
+ *     setDefault: (tableKey, id) => (id ? setDefaultPreset(Number(id), tableKey).then(() => undefined) : Promise.resolve()),
+ *   };
+ */
+import type { PresetState } from "./preset";
+/** `"user"` = 나만 · `"shared"` = 같은 표를 쓰는 모두 (ERP `private`/`shared` 대응) */
+export type PresetScope = "user" | "shared";
+export interface TablePreset {
+    id: string;
+    /** 표 식별자 — 같은 컬럼 세트를 쓰는 화면끼리 공유한다 (`useTable` 의 tableKey 와 같은 값) */
+    tableKey: string;
+    name: string;
+    state: PresetState;
+    scope?: PresetScope;
+    /** 표를 열 때 자동 적용되는 프리셋. 표 하나에 하나만 */
+    isDefault?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    /** 만든 사람 식별자 — 공유 프리셋의 수정 권한 판정은 소비 앱 몫 */
+    owner?: string;
+}
+/** `save` 입력 — `id` 가 있으면 갱신, 없으면 생성 */
+export type PresetInput = Omit<TablePreset, "id"> & {
+    id?: string;
+};
+export interface PresetStore {
+    list(tableKey: string): Promise<TablePreset[]>;
+    /** `id` 없으면 생성, 있으면 덮어쓰기. 저장된 결과(서버가 채운 id·시각 포함)를 돌려준다 */
+    save(preset: PresetInput): Promise<TablePreset>;
+    remove(id: string): Promise<void>;
+    /**
+     * 기본 프리셋 지정(`null` 이면 해제). 미구현이면 `usePresets` 가 `save` 로 `isDefault` 를
+     * 바꿔 가며 흉내 낸다 — 서버가 "표당 하나" 를 보장하는 API 가 있으면 여기에 연결한다.
+     */
+    setDefault?(tableKey: string, id: string | null): Promise<void>;
+}
+export declare function newPresetId(): string;
+export interface MemoryPresetStoreOptions {
+    /** 초기 데이터 */
+    seed?: TablePreset[];
+    /** 모든 호출을 이만큼 늦춘다 — 서버 왕복을 흉내 낼 때 (스토리·테스트) */
+    delayMs?: number;
+}
+/**
+ * 메모리 저장소 — 테스트·스토리·"서버가 아직 없는" 화면용.
+ * 돌려주는 객체는 매번 복사본이라 호출부가 바꿔도 내부 상태가 오염되지 않는다.
+ */
+export declare function createMemoryPresetStore(options?: MemoryPresetStoreOptions): PresetStore & {
+    /** 현재 내용 (테스트용) */
+    dump(): TablePreset[];
+};
+export interface LocalStoragePresetStoreOptions {
+    /** 저장 키 접두어. 기본 `"koko-table:presets"` — 표마다 `${namespace}:${tableKey}` 에 저장 */
+    namespace?: string;
+    /** 기본 `globalThis.localStorage`. SSR 등에서 없으면 메모리로 동작한다 */
+    storage?: Pick<Storage, "getItem" | "setItem" | "removeItem">;
+}
+/**
+ * localStorage 저장소 — 서버 없이 브라우저에만 남긴다.
+ * 접근 실패(사파리 프라이빗 모드·권한)는 삼키고 빈 목록으로 동작한다.
+ */
+export declare function createLocalStoragePresetStore(namespaceOrOptions?: string | LocalStoragePresetStoreOptions): PresetStore;
+/**
+ * 기본 프리셋 하나를 미리 읽는다 — 마운트 시점에 `useTableSearch({ initial })` 의 초기값으로
+ * 쓰려면 훅보다 먼저(라우트 loader·상위 컴포넌트) 불러 `presetToSearchInitial(preset.state)` 를
+ * 넘긴다. 이미 마운트된 표에는 `usePresets({ autoApplyDefault: true })` 가 같은 일을 한다.
+ */
+export declare function loadDefaultPreset(store: PresetStore, tableKey: string): Promise<TablePreset | null>;