kokotable 0.95.0

package/dist/core/src/columns/helper.d.ts

@@ -0,0 +1,196 @@
+import type { ReactNode } from "react";
+import type { RowData } from "@tanstack/react-table";
+import type { AggRenderFn, SelectOption, TableColumnDef, ValueOfKey } from "../types/column";
+import type { RelationOperatorName } from "../filters/relation";
+import type { LinearFilterValue, LinearOperatorName } from "../filters/linear";
+import type { ScheduleFields } from "../filters/schedule";
+import { ColumnBuilder, type CellRenderProps, type EditSpec } from "./ColumnBuilder";
+export interface CommonCodeOption {
+    idx: number;
+    name: string;
+    parentIdx?: number;
+    ancestorChain?: string;
+}
+export interface CommonCodeLookup {
+    /** 코드 경로의 선택지 */
+    getOptions(codePath: string, options?: {
+        activeOnly?: boolean;
+    }): CommonCodeOption[];
+    /** 저장값 → 표시 라벨 */
+    getLabel(codePath: string, value: unknown): string;
+}
+export interface UserLookup {
+    getAll(): Array<{
+        idx: number;
+        name: string;
+    }>;
+    getById(idx: number): {
+        idx: number;
+        name: string;
+    } | undefined;
+}
+export interface ColumnHelperDeps {
+    commonCodeLookup?: CommonCodeLookup;
+    userLookup?: UserLookup;
+    /** 폐기된 코드를 선택지에서 뺄지 */
+    activeOnly?: boolean;
+}
+/**
+ * 프리셋 공통 파라미터. `K` 는 `key` 리터럴 — `keyof T` 이면 빌더의 셀 값 타입 `V` 가
+ * `T[K]` 로 추론되고, 점 경로나 동적 문자열이면 `unknown` 이다 (`ValueOfKey`).
+ * 기존처럼 `ColumnParams` 로만 쓰면 `K = string` 이라 `unknown` 으로 남는다.
+ */
+export interface ColumnParams<K extends string = string> {
+    key: K;
+    header: string;
+    size?: number;
+}
+export interface CompositeComponent {
+    key: string;
+    /** 서버 집계 함수 — `sum` / `avg` / `min` / `max` / `count_distinct` */
+    agg: string;
+}
+export type ColumnFactory<T extends RowData> = (...args: never[]) => ColumnBuilder<T, any> | ColumnBuilder<T, any>[];
+declare function makeBase<T extends RowData>(deps: ColumnHelperDeps): {
+    ColumnIsText: <K extends string>(p: ColumnParams<K>) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    ColumnIsBoolean: <K extends string>(p: ColumnParams<K>) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    ColumnIsDate: <K extends string>(p: ColumnParams<K> & {
+        withTime?: boolean;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /** 콤마 포맷 + 통화/단위 + 소수점 자릿수 */
+    ColumnIsNumber: <K extends string>(p: ColumnParams<K> & {
+        decimals?: number;
+        currency?: string;
+        endAdornment?: ReactNode;
+        editable?: boolean;
+        onCommit?: (value: unknown, row: T) => void;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /**
+     * 특정 숫자 — 기본 `inArray`(쉼표로 구분한 번호 여러 개 → 서버 `IN`), 보조 `equals`(하나).
+     * 참조번호처럼 "그 값"을 찾는 컬럼에 범위 필터를 주면 오히려 방해가 된다.
+     * 하나만 넣어도 `[값]` 배열로 나가므로 equals 와 결과가 같다.
+     */
+    ColumnIsSpecificNumber: <K extends string>(p: ColumnParams<K>) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /** IDX 참조번호 — equals 전용 + 칩 표시. 기본은 숨김 */
+    ColumnIsIDX: <K extends string>(p: Omit<ColumnParams<K>, "header"> & {
+        header?: string;
+        display?: {
+            display: boolean;
+            hideFilter: boolean;
+        };
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    ColumnIsEnum: <K extends string>(p: ColumnParams<K> & {
+        options: SelectOption[];
+        multiple?: boolean;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    ColumnIsCommonCode: <K extends string>(p: ColumnParams<K> & {
+        codePath: string;
+        /** 기본 `true` — 기존 `ColumnIsCommonCode` 의 `isMultiSelect` 기본값과 같다 */
+        multiple?: boolean;
+        /**
+         * 상위 컬럼 id. 주면 **종속 필터**가 된다 — 상위에서 고른 값의 자식만
+         * 선택지에 남고, 상위가 바뀌면 무효해진 하위 값이 자동으로 지워진다
+         * (`resolveCascadeOptions` / `pruneCascadeValues`).
+         */
+        dependsOn?: string;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    ColumnIsUser: <K extends string>(p: ColumnParams<K> & {
+        multiple?: boolean;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /**
+     * 링크 컬럼. `to` 는 반드시 "/" 로 시작하는 **절대 경로**여야 한다 —
+     * 상대 경로는 라우터가 현재 URL 기준으로 해석해 연타 시
+     * `/item/view/1/view/1/...` 처럼 경로가 누적된다.
+     */
+    ColumnIsLink: <K extends string>(p: ColumnParams<K> & {
+        to: (props: CellRenderProps<T, ValueOfKey<T, K>>) => string;
+        placeholder?: string;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /** 필터·정렬 없는 표시 전용 컬럼 */
+    ColumnIsCustom: <K extends string>(p: ColumnParams<K> & {
+        cell: (props: CellRenderProps<T, ValueOfKey<T, K>>) => ReactNode;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /**
+     * 참조 컬럼. `key` 는 서버가 응답에 실어 준 **라벨 컬럼**이라 텍스트 컬럼
+     * 그대로다 — 서버측 라벨 검색·정렬이 다른 텍스트 컬럼과 같은 경로로 걸린다.
+     * `ColumnIsCustom` 은 accessor 를 죽이고 필터를 끄므로 참조에 쓰면 안 된다.
+     */
+    ColumnIsReference: <K extends string>(p: ColumnParams<K> & {
+        cell: (props: CellRenderProps<T, ValueOfKey<T, K>>) => ReactNode;
+        /** 참조 타입 컬럼 — 비어 있는 행은 placeholder 로 그린다 */
+        typeKey?: string;
+        placeholder?: string;
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /** 1:N 관계 필터 컬럼 */
+    ColumnIsRelation: <K extends string>(p: ColumnParams<K> & {
+        innerColumns: Array<{
+            key: string;
+            label: string;
+            type?: string;
+        }>;
+        cell?: (props: CellRenderProps<T, ValueOfKey<T, K>>) => ReactNode;
+        operators?: RelationOperatorName[];
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /** 선형결합(수량 조건) 필터 컬럼 */
+    ColumnIsLinear: <K extends string>(p: ColumnParams<K> & {
+        config: Partial<LinearFilterValue>;
+        cell?: (props: CellRenderProps<T, ValueOfKey<T, K>>) => ReactNode;
+        operators?: LinearOperatorName[];
+    }) => ColumnBuilder<T, ValueOfKey<T, K>>;
+    /**
+     * 일정 통합 컬럼 — 예정/실제 4개 날짜를 컬럼 하나로 묶는다.
+     *
+     * 반환: `[통합 컬럼, 숨김 날짜 컬럼 4개]`. 숨김 컬럼의 id 가 실제 필드명이라
+     * 서버 QueryBuilder 가 그대로 해석한다.
+     */
+    ColumnIsSchedule: (p: Omit<ColumnParams, "key"> & {
+        key?: string;
+        fields?: ScheduleFields;
+    }) => ColumnBuilder<T, any>[];
+    /**
+     * 합성 집계 컬럼 — 여러 컴포넌트를 서버에서 집계하고 하나로 합쳐 보여준다.
+     * 반환: `[숨김 컴포넌트 컬럼들, 표시 컬럼]`.
+     */
+    ColumnIsComposite: <K extends string>(p: ColumnParams<K> & {
+        components: CompositeComponent[];
+        cell: (props: CellRenderProps<T, ValueOfKey<T, K>>) => ReactNode;
+        /** `({ value, columnId, allAggregates }, column)` — 렌더러가 실제로 부르는 규약 (ERP `AggCustomRender`) */
+        aggRender?: AggRenderFn;
+    }) => ColumnBuilder<T, any>[];
+    /**
+     * Cascade 컬럼 그룹 — N단계 종속 필터.
+     *
+     * 통합 컬럼 하나만 표시하고, 레벨별 실제 필드는 `meta.cascadeFilterLevels` 로
+     * 남긴다. 레벨 컬럼을 따로 만들지 않는 이유: 헤더 없는 고스트 컬럼이 생기고
+     * 사용자 토글로 되살아나기 때문이다. 서버 필터 연산자는 `deriveOperators` 가
+     * 이 메타를 펼쳐서 채운다.
+     */
+    ColumnIsCascade: <K extends string>(p: ColumnParams<K> & {
+        /** 상위 → 하위 순서의 실제 필드 경로 */
+        levels: string[];
+        codePath?: string;
+        multiple?: boolean;
+    }) => ColumnBuilder<T, any>[];
+};
+export type BaseColumnHelper<T extends RowData> = ReturnType<typeof makeBase<T>>;
+/**
+ * 확장 가능한 컬럼 헬퍼.
+ *
+ * 원본 `class ColumnHelper` 는 메서드가 인스턴스 화살표 프로퍼티라 런타임
+ * `Object.assign` 은 됐지만 타입이 따라오지 않았다. `.extend()` 가 교차 타입을
+ * 반환하므로 확장분도 그대로 추론된다.
+ *
+ * @example
+ * const helper = createColumnHelper<Row>({ commonCodeLookup })
+ *   .extend((self) => ({
+ *     ColumnIsMoney: (p: ColumnParams) => self.ColumnIsNumber({ ...p, currency: "KRW" }),
+ *   }));
+ * helper.ColumnIsMoney({ key: "amount", header: "금액" }); // 타입 추론됨
+ */
+export type ColumnHelper<T extends RowData, Ext extends Record<string, ColumnFactory<T>> = Record<never, never>> = BaseColumnHelper<T> & Ext & {
+    extend<E extends Record<string, ColumnFactory<T>>>(ext: E | ((self: ColumnHelper<T, Ext>) => E)): ColumnHelper<T, Ext & E>;
+};
+export declare function createColumnHelper<T extends RowData>(deps?: ColumnHelperDeps): ColumnHelper<T>;
+export type { CellRenderProps, EditSpec };
+export { ColumnBuilder };
+export type { TableColumnDef };

package/dist/core/src/columns/helper.js

@@ -0,0 +1,250 @@
+import { ColumnBuilder } from "./ColumnBuilder";
+import { getValue } from "../utils/getValue";
+import { cascadeKind, commonCodeKind } from "../filters/kinds";
+const toSelectOption = (option) => ({
+    label: option.name,
+    value: String(option.idx),
+    ...(option.ancestorChain ? { ancestorChain: option.ancestorChain } : {}),
+});
+function requireDep(dep, name, preset) {
+    if (!dep) {
+        throw new Error(`[koko-table] ${preset} 에는 ${name} 이 필요합니다. ` +
+            `createColumnHelper({ ${name} }) 로 주입하세요.`);
+    }
+    return dep;
+}
+// ─────────────────────────────────────────────────────────────
+// 기본 헬퍼
+// ─────────────────────────────────────────────────────────────
+function makeBase(deps) {
+    // `key` 리터럴 K → 셀 값 타입 V = T[K] (keyof T 가 아니면 unknown)
+    const create = (key, header, type, size) => {
+        const builder = new ColumnBuilder(key, header, type);
+        if (size !== undefined)
+            builder.setSizing({ size });
+        return builder;
+    };
+    const base = {
+        ColumnIsText: (p) => create(p.key, p.header, "text", p.size),
+        ColumnIsBoolean: (p) => create(p.key, p.header, "boolean", p.size),
+        ColumnIsDate: (p) => create(p.key, p.header, p.withTime ? "datetime" : "date", p.size),
+        /** 콤마 포맷 + 통화/단위 + 소수점 자릿수 */
+        ColumnIsNumber: (p) => {
+            const builder = create(p.key, p.header, "number", p.size);
+            builder.setMeta({ decimals: p.decimals, currency: p.currency, endAdornment: p.endAdornment });
+            if (p.decimals != null) {
+                builder.setCell(({ value }) => value == null
+                    ? ""
+                    : Number(value).toLocaleString("ko-KR", {
+                        minimumFractionDigits: p.decimals,
+                        maximumFractionDigits: p.decimals,
+                    }));
+            }
+            if (p.editable)
+                builder.setEditable(true, p.onCommit);
+            return builder;
+        },
+        /**
+         * 특정 숫자 — 기본 `inArray`(쉼표로 구분한 번호 여러 개 → 서버 `IN`), 보조 `equals`(하나).
+         * 참조번호처럼 "그 값"을 찾는 컬럼에 범위 필터를 주면 오히려 방해가 된다.
+         * 하나만 넣어도 `[값]` 배열로 나가므로 equals 와 결과가 같다.
+         */
+        ColumnIsSpecificNumber: (p) => create(p.key, p.header, "number", p.size)
+            .setOperators(["inArray", "equals"], "inArray")
+            // 번호는 합계·평균이 뜻이 없다 — 집계 후보(AggregationChips·그룹 헤더)에서 뺀다
+            .setMeta({ enableAgg: false }),
+        /** IDX 참조번호 — equals 전용 + 칩 표시. 기본은 숨김 */
+        ColumnIsIDX: (p) => {
+            const builder = base
+                .ColumnIsSpecificNumber({ key: p.key, header: p.header ?? "참조번호", size: p.size })
+                .setMeta({ chip: true });
+            builder.setDisplay(p.display ?? { display: false, hideFilter: true });
+            return builder;
+        },
+        ColumnIsEnum: (p) => {
+            const builder = create(p.key, p.header, "enum", p.size);
+            builder.setVariant(p.multiple ? "multiSelect" : "select");
+            builder.setFilterOptions(p.options);
+            return builder;
+        },
+        ColumnIsCommonCode: (p) => {
+            const lookup = requireDep(deps.commonCodeLookup, "commonCodeLookup", "ColumnIsCommonCode");
+            const all = lookup.getOptions(p.codePath, { activeOnly: deps.activeOnly });
+            // 공통코드는 다중 선택이 기본이다. 단일(select) 로 두면 스칼라 값 + `inArray` 로
+            // 요청이 나가던 경로라(현재는 배열로 감싸 막아 두었다) 기존 기본값과도 어긋났다.
+            const multiple = p.multiple ?? true;
+            const builder = base.ColumnIsEnum({ ...p, multiple, options: all.map(toSelectOption) });
+            // enum 과 판정은 같지만 id 가 다르다 — Provider 가 공통코드 입력만 따로 바꿀 수 있다
+            builder.setFilterKind(commonCodeKind, { variant: multiple ? "multiSelect" : "select" });
+            builder.setMeta({ commonCodeParentPath: p.codePath });
+            builder.setCell(({ value }) => (value == null ? "" : lookup.getLabel(p.codePath, value)));
+            if (p.dependsOn) {
+                const children = all.filter((option) => option.parentIdx != null);
+                if (children.length === 0 && all.length > 0) {
+                    // 부모 정보가 없는 코드 목록에 dependsOn 을 걸면 선택지가 영영 비어
+                    // 필터를 못 쓰게 된다. 조용히 넘어가면 원인을 찾기 어렵다.
+                    throw new Error(`[koko-table] ColumnIsCascade/dependsOn: "${p.codePath}" 의 코드에 ` +
+                        "parentIdx 가 없습니다. commonCodeLookup.getOptions 가 부모 idx 를 실어 주어야 합니다.");
+                }
+                builder.setMeta({
+                    dependentFilter: {
+                        dependsOn: p.dependsOn,
+                        isMultiSelect: multiple,
+                        allChildOptions: children.map((option) => ({
+                            idx: option.idx,
+                            name: option.name,
+                            parentIdx: option.parentIdx,
+                            ...(option.ancestorChain ? { ancestorChain: option.ancestorChain } : {}),
+                        })),
+                    },
+                });
+            }
+            return builder;
+        },
+        ColumnIsUser: (p) => {
+            const lookup = requireDep(deps.userLookup, "userLookup", "ColumnIsUser");
+            const options = lookup
+                .getAll()
+                .map((user) => ({ label: user.name, value: String(user.idx) }));
+            const builder = base.ColumnIsEnum({ ...p, options });
+            builder.setCell(({ value }) => value == null ? "" : lookup.getById(Number(value))?.name ?? "");
+            return builder;
+        },
+        /**
+         * 링크 컬럼. `to` 는 반드시 "/" 로 시작하는 **절대 경로**여야 한다 —
+         * 상대 경로는 라우터가 현재 URL 기준으로 해석해 연타 시
+         * `/item/view/1/view/1/...` 처럼 경로가 누적된다.
+         */
+        ColumnIsLink: (p) => {
+            const builder = create(p.key, p.header, "text", p.size);
+            builder.setMeta({ link: { to: p.to }, placeholder: p.placeholder ?? "-" });
+            return builder;
+        },
+        /** 필터·정렬 없는 표시 전용 컬럼 */
+        ColumnIsCustom: (p) => {
+            const builder = create(p.key, p.header, "text", p.size);
+            builder.setProps({ enableSorting: false, enableGrouping: false });
+            builder.setFilter({ hidden: true });
+            builder.setCell(p.cell);
+            return builder;
+        },
+        /**
+         * 참조 컬럼. `key` 는 서버가 응답에 실어 준 **라벨 컬럼**이라 텍스트 컬럼
+         * 그대로다 — 서버측 라벨 검색·정렬이 다른 텍스트 컬럼과 같은 경로로 걸린다.
+         * `ColumnIsCustom` 은 accessor 를 죽이고 필터를 끄므로 참조에 쓰면 안 된다.
+         */
+        ColumnIsReference: (p) => {
+            const builder = create(p.key, p.header, "text", p.size);
+            const typeKey = p.typeKey ?? "reference";
+            builder.setCell((props) => getValue(props.row, typeKey) ? p.cell(props) : p.placeholder ?? "-");
+            return builder;
+        },
+        /** 1:N 관계 필터 컬럼 */
+        ColumnIsRelation: (p) => {
+            const builder = create(p.key, p.header, "text", p.size);
+            builder.setVariant("relation", p.operators ?? ["hasAny", "hasAll", "hasChild", "hasNotChild"]);
+            builder.setProps({ enableSorting: false });
+            // 하위 컬럼을 meta 에 남긴다 — 필터 UI 는 렌더 prop 으로 받지만, 컬럼 정의만
+            // 읽는 쪽(AI 컨텍스트 추출 등)은 여기를 봐야 자식 구조를 알 수 있다
+            builder.setMeta({ relationColumns: p.innerColumns });
+            builder.setCell((props) => p.cell?.(props) ?? "-");
+            return builder;
+        },
+        /** 선형결합(수량 조건) 필터 컬럼 */
+        ColumnIsLinear: (p) => {
+            const builder = create(p.key, p.header, "text", p.size);
+            builder.setVariant("linear", p.operators ?? ["linearContains", "linearExists", "linearExact"]);
+            builder.setProps({ enableSorting: false });
+            builder.setMeta({ linearConfig: p.config });
+            builder.setCell((props) => p.cell?.(props) ?? "-");
+            return builder;
+        },
+        /**
+         * 일정 통합 컬럼 — 예정/실제 4개 날짜를 컬럼 하나로 묶는다.
+         *
+         * 반환: `[통합 컬럼, 숨김 날짜 컬럼 4개]`. 숨김 컬럼의 id 가 실제 필드명이라
+         * 서버 QueryBuilder 가 그대로 해석한다.
+         */
+        ColumnIsSchedule: (p) => {
+            const fields = {
+                plannedStart: "planned_process_date",
+                plannedEnd: "planned_finish_date",
+                actualStart: "actual_process_date",
+                actualEnd: "actual_finish_date",
+                ...p.fields,
+            };
+            const key = p.key ?? "schedule";
+            const main = create(key, p.header, "text", p.size);
+            main.setVariant("schedule");
+            main.setMeta({ scheduleFields: fields, sortExpandsTo: [fields.plannedStart] });
+            main.setProps({ accessorFn: (row) => getValue(row, fields.plannedStart) ?? "" });
+            const hidden = (path) => new ColumnBuilder(path, "", "date").setDisplay({ display: false, hideFilter: true });
+            return [
+                main,
+                hidden(fields.plannedStart),
+                hidden(fields.plannedEnd),
+                hidden(fields.actualStart),
+                hidden(fields.actualEnd),
+            ];
+        },
+        /**
+         * 합성 집계 컬럼 — 여러 컴포넌트를 서버에서 집계하고 하나로 합쳐 보여준다.
+         * 반환: `[숨김 컴포넌트 컬럼들, 표시 컬럼]`.
+         */
+        ColumnIsComposite: (p) => {
+            const hidden = p.components.map(({ key, agg }) => new ColumnBuilder(key, key, "number")
+                .setDisplay({ display: false, hideFilter: true })
+                .setAgg(true, [agg]));
+            const display = create(p.key, p.header, "text", p.size);
+            display.setProps({ enableSorting: false, enableGrouping: false });
+            display.setFilter({ hidden: true });
+            display.setCell(p.cell);
+            if (p.aggRender)
+                display.setMeta({ aggRender: p.aggRender });
+            return [...hidden, display];
+        },
+        /**
+         * Cascade 컬럼 그룹 — N단계 종속 필터.
+         *
+         * 통합 컬럼 하나만 표시하고, 레벨별 실제 필드는 `meta.cascadeFilterLevels` 로
+         * 남긴다. 레벨 컬럼을 따로 만들지 않는 이유: 헤더 없는 고스트 컬럼이 생기고
+         * 사용자 토글로 되살아나기 때문이다. 서버 필터 연산자는 `deriveOperators` 가
+         * 이 메타를 펼쳐서 채운다.
+         */
+        ColumnIsCascade: (p) => {
+            const operator = p.multiple === false ? "equals" : "inArray";
+            const builder = create(p.key, p.header, "text", p.size);
+            builder.setFilterKind(cascadeKind, { variant: "select", operators: ["inArray", "notInArray"] });
+            builder.setMeta({
+                cascadeFilterLevels: p.levels.map((key) => ({
+                    key,
+                    operator,
+                    operatorOptions: ["inArray", "notInArray"],
+                })),
+                sortExpandsTo: p.levels,
+                ...(p.codePath ? { commonCodeParentPath: p.codePath } : {}),
+            });
+            if (deps.commonCodeLookup && p.codePath) {
+                const lookup = deps.commonCodeLookup;
+                const options = lookup
+                    .getOptions(p.codePath, { activeOnly: deps.activeOnly })
+                    .map(toSelectOption);
+                builder.setFilterOptions(options);
+            }
+            return [builder];
+        },
+    };
+    return base;
+}
+export function createColumnHelper(deps = {}) {
+    const attach = (helper) => {
+        const withExtend = helper;
+        withExtend.extend = (ext) => {
+            const resolved = typeof ext === "function" ? ext(withExtend) : ext;
+            return attach(Object.assign(Object.create(Object.getPrototypeOf(withExtend)), withExtend, resolved));
+        };
+        return withExtend;
+    };
+    return attach(makeBase(deps));
+}
+export { ColumnBuilder };

package/dist/core/src/columns/labels.d.ts

@@ -0,0 +1,12 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+/** 컬럼 값 → 표시 라벨. 못 찾으면 undefined */
+export type LabelResolver = (columnId: string, value: unknown) => string | undefined;
+/**
+ * 컬럼의 `selectOptions` 에서 라벨을 찾는 해석기.
+ *
+ * CommonCode 컬럼은 셀에 idx 를 담고 화면에는 이름을 보여준다. 그룹 헤더나
+ * 피벗 축이 이걸 해석하지 않으면 "완료" 대신 "3" 이 뜬다.
+ * **그룹핑과 피벗이 같은 해석기를 쓰도록** 여기 한 곳에 둔다.
+ */
+export declare function createLabelResolver<T extends RowData>(columns: TableColumnDefs<T> | undefined, override?: LabelResolver): LabelResolver;

package/dist/core/src/columns/labels.js

@@ -0,0 +1,21 @@
+import { columnKey } from "./deriveOperators";
+/**
+ * 컬럼의 `selectOptions` 에서 라벨을 찾는 해석기.
+ *
+ * CommonCode 컬럼은 셀에 idx 를 담고 화면에는 이름을 보여준다. 그룹 헤더나
+ * 피벗 축이 이걸 해석하지 않으면 "완료" 대신 "3" 이 뜬다.
+ * **그룹핑과 피벗이 같은 해석기를 쓰도록** 여기 한 곳에 둔다.
+ */
+export function createLabelResolver(columns, override) {
+    if (override)
+        return override;
+    const byColumn = new Map();
+    for (const column of columns ?? []) {
+        const id = columnKey(column);
+        const options = column.meta?.selectOptions;
+        if (!id || !options)
+            continue;
+        byColumn.set(id, new Map(options.map((option) => [option.value, option.label])));
+    }
+    return (columnId, value) => byColumn.get(columnId)?.get(String(value));
+}

package/dist/core/src/contract.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 백엔드 계약 버전.
+ *
+ * 프론트는 백엔드 코드를 직접 쓰지 않는다. 서버 모드를 켰을 때 wire 계약
+ * (`TableRequest`/`TableResponse`)으로만 호환을 보증하며, 그 계약은 이 패키지에 실린
+ * `contract/table-request.schema.json`(백엔드 pydantic `TableRequest` 에서 생성, `kokotable/contract/table-request.schema.json`) 이다.
+ * 백엔드 패키지 `koko-table-server` 의 `CONTRACT_VERSION` 과 같은 값이어야 하고,
+ * 계약이 바뀌는 릴리스에서만 minor 를 올린다.
+ */
+export declare const CONTRACT_VERSION = "0.95.0";
+/** `kokotable/contract/table-request.schema.json` 의 패키지 내 경로 */
+export declare const TABLE_REQUEST_SCHEMA_PATH = "contract/table-request.schema.json";

package/dist/core/src/contract.js

@@ -0,0 +1,12 @@
+/**
+ * 백엔드 계약 버전.
+ *
+ * 프론트는 백엔드 코드를 직접 쓰지 않는다. 서버 모드를 켰을 때 wire 계약
+ * (`TableRequest`/`TableResponse`)으로만 호환을 보증하며, 그 계약은 이 패키지에 실린
+ * `contract/table-request.schema.json`(백엔드 pydantic `TableRequest` 에서 생성, `kokotable/contract/table-request.schema.json`) 이다.
+ * 백엔드 패키지 `koko-table-server` 의 `CONTRACT_VERSION` 과 같은 값이어야 하고,
+ * 계약이 바뀌는 릴리스에서만 minor 를 올린다.
+ */
+export const CONTRACT_VERSION = "0.95.0";
+/** `kokotable/contract/table-request.schema.json` 의 패키지 내 경로 */
+export const TABLE_REQUEST_SCHEMA_PATH = "contract/table-request.schema.json";

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

@@ -0,0 +1,102 @@
+/**
+ * AI 검색 연동용 컬럼 메타 계약.
+ *
+ * 왜 필요한가: ERP `features/ai-search/hooks/use-register-table.ts` 는
+ * `extractColumnMeta(table.options.columns)` 로 컬럼을 AI 컨텍스트에 올린다.
+ * 기존 `features/ai-search/utils/extract-column-meta.ts` 는 MRT 컬럼의
+ * `accessorKey` / `meta.columnType` / `filterVariant` / `filterSelectOptions` 를
+ * 읽는데, koko 컬럼은 `id` + `accessorFn` / `meta.dataType` + `filter.variant` /
+ * `meta.selectOptions` 라서 **0개가 추출된다** (server.md D-3 실측).
+ *
+ * 두 갈래를 제공한다.
+ * - `extractColumnMeta(columns)` — koko 컬럼에서 곧바로 AI 계약 모양을 만든다.
+ *   규칙은 기존 extract-column-meta.ts 를 그대로 옮겼다.
+ * - `toLegacyColumnDefs(columns)` — 기존 ERP `extractColumnMeta` 를 **수정 없이**
+ *   통과하도록 `accessorKey` / `meta.columnType` / `filterVariant` /
+ *   `filterSelectOptions` 를 덧붙인 사본을 돌려준다. 원본 컬럼은 변형하지 않는다.
+ */
+import type { RowData } from "@tanstack/react-table";
+import type { CascadeFilterLevel, ColumnMeta, SelectOption, TableColumnDef, TableColumnDefs } from "../types/column";
+export type AiColumnType = "text" | "number" | "date" | "select" | "multiSelect" | "boolean" | "relation";
+/** 관계(1:N) 컬럼 안쪽 필드 — 구성품·주문상세처럼 자식 행을 가진 컬럼용 */
+export interface AiInnerColumnMeta {
+    key: string;
+    header: string;
+    type: "text" | "number" | "date";
+}
+/** AI 에 전달할 컬럼 메타데이터 */
+export interface AiColumnMeta {
+    key: string;
+    header: string;
+    type: AiColumnType;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** relation 타입일 때의 하위 컬럼 — groups 조건의 column 으로 쓸 수 있는 것들 */
+    inner?: AiInnerColumnMeta[];
+}
+export interface ExtractColumnMetaOptions {
+    /**
+     * "전체"(`_ALL_SELECTED`) / "(비어있음)"(`EMPTY`) 센티널을 옵션에서 뺀다.
+     * 기본 false — 기존 extract-column-meta.ts 는 센티널을 걸러내지 않았으므로
+     * 같은 출력을 유지한다.
+     */
+    stripSentinels?: boolean;
+}
+/** `filter.variant`(없으면 dataType 유추) → AI 계약 타입 */
+export declare function toAiColumnType<T extends RowData>(column: TableColumnDef<T, any>): AiColumnType;
+/**
+ * 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 declare function extractColumnMeta<T extends RowData>(columns: TableColumnDefs<T>, options?: ExtractColumnMetaOptions): AiColumnMeta[];
+/** 기존 `types/columnMeta.ts` → `types/table.ts` 의 `ColumnFilterType` */
+export type LegacyColumnType = "text" | "select" | "date" | "datetime" | "number" | "boolean" | "custom" | "multiSelect" | "relation";
+/** 기존 `columns/utils/filterUtils.ts getFilterVariant` 가 내던 MRT filterVariant */
+export type LegacyFilterVariant = "autocomplete" | "text" | "select" | "multi-select";
+/** 기존 `ColumnMetaData.cascadeFilterLevels` 원소 모양 (koko 는 operator/operatorOptions) */
+export interface LegacyCascadeFilterLevel extends CascadeFilterLevel {
+    filterFn: string;
+    columnFilterModeOptions: string[];
+}
+export type LegacyCompatColumnMeta = Omit<ColumnMeta, "cascadeFilterLevels"> & {
+    columnType: LegacyColumnType;
+    cascadeFilterLevels?: LegacyCascadeFilterLevel[];
+};
+/**
+ * 기존 ERP `extractColumnMeta` / `getAllColumns().map(c => c.columnDef.meta.columnType)`
+ * 가 읽는 필드만 보장한다. 나머지는 koko 컬럼을 그대로 스프레드한다.
+ */
+export interface LegacyCompatColumnDef {
+    id: string;
+    accessorKey: string;
+    header?: unknown;
+    filterVariant: LegacyFilterVariant;
+    filterSelectOptions?: SelectOption[];
+    meta: LegacyCompatColumnMeta;
+    [key: string]: unknown;
+}
+/**
+ * koko `filter.variant` → 기존 `meta.columnType`.
+ *
+ * 기존 columnType ≈ koko variant 이고, relation 은 기존이 `custom` 으로 찍었다
+ * (server.md D-3/D-4 실측). linear/schedule/custom 도 기존에 대응이 없어 `custom`.
+ */
+export declare function toLegacyColumnType<T extends RowData>(column: TableColumnDef<T, any>): LegacyColumnType;
+/** 기존 `getFilterVariant(columnType)` 표 */
+export declare function toLegacyFilterVariant(columnType: LegacyColumnType): LegacyFilterVariant;
+/**
+ * koko 컬럼 배열 → 기존 `extractColumnMeta` 가 그대로 읽을 수 있는 사본.
+ *
+ * 키가 없는 컬럼(display)은 결과에서 제외한다 — 기존 함수도 accessorKey 없는 컬럼은
+ * 건너뛰므로 결과는 같다. 원본 객체는 변형하지 않는다.
+ */
+export declare function toLegacyColumnDefs<T extends RowData>(columns: TableColumnDefs<T>): LegacyCompatColumnDef[];