kokotable 0.95.0

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

@@ -0,0 +1,273 @@
+import { offeredOperators } from "../types/operators";
+import { inferVariant } from "./deriveOperators";
+import { getValue } from "../utils/getValue";
+import { ALL_FILTER_VALUE } from "../filters/list";
+import { filterKindVariant } from "../filters/kind";
+import { builtinKindForVariant } from "../filters/kinds";
+/** `dataType` → 기본 필터 UI 종류 (`deriveOperators.inferVariant` 와 같은 표) */
+export const inferFilterVariant = (dataType) => inferVariant({ dataType });
+const pad = (n) => String(n).padStart(2, "0");
+/** 기본 포맷터 — 순수 함수라 렌더러가 없어도 동작한다 (CSV·PDF 내보내기 공용) */
+export function formatByDataType(value, dataType) {
+    if (value === null || value === undefined)
+        return "";
+    switch (dataType) {
+        case "number": {
+            const num = Number(value);
+            return Number.isNaN(num) ? "" : num.toLocaleString("ko-KR");
+        }
+        case "date":
+        case "datetime": {
+            const date = value instanceof Date ? value : new Date(String(value));
+            if (Number.isNaN(date.getTime()))
+                return String(value);
+            const ymd = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+            return dataType === "datetime"
+                ? `${ymd} ${pad(date.getHours())}:${pad(date.getMinutes())}`
+                : ymd;
+        }
+        default:
+            return String(value);
+    }
+}
+/**
+ * 컬럼 빌더 — 체이닝으로 컬럼 정의를 조립한다.
+ *
+ * 원본과 달리 **MUI 를 모른다.** 편집 입력·칩 같은 렌더 선언은 `meta.edit` 에
+ * 데이터로 남기고, 실제 컴포넌트는 렌더러 패키지가 읽어서 그린다. 그래야
+ * 같은 컬럼 정의로 테이블도, 카드도, 내보내기도 그릴 수 있다.
+ */
+export class ColumnBuilder {
+    column;
+    key;
+    dataType;
+    constructor(key, header, dataType = "text") {
+        this.key = String(key);
+        this.dataType = dataType;
+        const variant = inferVariant({ dataType });
+        this.column = {
+            id: this.key,
+            header,
+            meta: { dataType },
+            filter: {
+                // 내장 kind 를 같이 붙인다 — 판정·직렬화·문구·codec 이 kind 경로로 간다 (dogfooding)
+                kind: builtinKindForVariant(variant),
+                variant,
+                operators: offeredOperators(variant),
+            },
+        };
+        this.applyAccessor();
+        this.applyDefaultCell();
+        return this;
+    }
+    /**
+     * 점 표기 key 는 `accessorKey` 대신 `accessorFn` 으로 읽는다.
+     * TanStack 의 깊은 `accessorKey` 접근은 중간 객체가 없으면 행마다 경고를 낸다
+     * (확장 자식 행 등) — 안전 접근으로 대체해 조용히 undefined 를 돌려준다.
+     *
+     * 값은 **변환하지 않는다.** 필터·정렬·집계는 2층이 원값(`getValue`)으로 계산하므로
+     * 셀만 다른 값(boolean 문자열, NaN→0, Date 객체)을 보면 두 경로가 어긋난다.
+     * 표시 포맷은 `formatByDataType` 이 원값에서 만든다.
+     */
+    applyAccessor() {
+        const key = this.key;
+        this.column.accessorFn = (row) => getValue(row, key);
+    }
+    applyDefaultCell() {
+        const dataType = this.dataType;
+        this.column.cell = ({ getValue: get }) => formatByDataType(get(), dataType);
+        if (dataType === "boolean") {
+            this.setFilterOptions([
+                { label: "true", value: "true" },
+                { label: "false", value: "false" },
+            ]);
+        }
+    }
+    /** 필터 UI 종류 변경 — 연산자 후보와 내장 kind 도 함께 갈아끼운다 (`custom` 은 kind 없음) */
+    setVariant(variant, operators) {
+        this.column.filter = {
+            ...this.column.filter,
+            kind: builtinKindForVariant(variant),
+            variant,
+            operators: operators ?? offeredOperators(variant),
+        };
+        return this;
+    }
+    /**
+     * 필터 kind 지정 — 연산자·기본값이 kind 로 좁혀진다 (`filter: { kind }` 를 인라인으로 쓸 때와 달리
+     * 레지스트리에 등록하지 않은 kind 에도 연산자·기본값을 줄 수 있다).
+     * 연산자 후보는 `spec.operators` > kind 의 `offered` > 전체, variant 는 `spec.variant` > kind 의 힌트.
+     */
+    setFilterKind(kind, spec = {}) {
+        this.column.filter = {
+            ...this.column.filter,
+            ...spec,
+            kind,
+            variant: spec.variant ?? filterKindVariant(kind),
+            operators: spec.operators ?? kind.offered ?? kind.operatorNames,
+        };
+        return this;
+    }
+    /** 필터 선언 병합. 필터 값 타입은 셀 값 `V` 와 다를 수 있어 `FilterSpec<any>` 로 받는다 */
+    setFilter(spec) {
+        this.column.filter = { ...this.column.filter, ...spec };
+        return this;
+    }
+    setOperators(operators, defaultOperator) {
+        return this.setFilter({ operators, ...(defaultOperator ? { defaultOperator } : {}) });
+    }
+    setDateFilterMode(mode) {
+        return this.setMeta({ dateFilterMode: mode });
+    }
+    setMeta(meta) {
+        this.column.meta = { ...this.column.meta, ...meta };
+        return this;
+    }
+    setProps(props) {
+        // ColumnDef 는 accessorKey/accessorFn/display 세 갈래 유니온이라 스프레드가
+        // 어느 갈래인지 잃는다. 빌더는 항상 accessorFn 갈래를 유지하므로 단언한다.
+        this.column = { ...this.column, ...props };
+        return this;
+    }
+    /**
+     * 소비 앱 확장 메타 (`meta.custom`) — 여러 번 부르면 얕게 병합된다.
+     * 읽는 쪽은 `columnMetaOf<Ext>(column)?.custom` 으로 타입을 살린다.
+     */
+    setCustom(ext) {
+        const previous = (this.column.meta?.custom ?? {});
+        return this.setMeta({ custom: { ...previous, ...ext } });
+    }
+    /** 헤더 규칙 — 툴팁·셀 정렬·헤더 정렬. 렌더러가 `meta.headerTooltip` / `meta.align` / `meta.headerAlign` 을 읽는다 */
+    setHeaderRule(rule) {
+        return this.setMeta({
+            ...(rule.tooltip !== undefined ? { headerTooltip: rule.tooltip } : {}),
+            ...(rule.align !== undefined ? { align: rule.align } : {}),
+            ...(rule.headerAlign !== undefined ? { headerAlign: rule.headerAlign } : {}),
+        });
+    }
+    setHeader(header) {
+        this.column.header = header;
+        return this;
+    }
+    /** 필터 패널에만 쓰는 라벨 (헤더가 ReactNode 일 때) */
+    setFilterLabel(label) {
+        this.column.filterLabel = label;
+        return this;
+    }
+    setSizing(options) {
+        const { ellipsis, ...sizing } = options;
+        this.setProps(sizing);
+        if (ellipsis)
+            this.setMeta({ ellipsis: true });
+        return this;
+    }
+    /** TanStack 셀 컨텍스트 → 순수 값 props (setCell/setCellWrapper 공용) */
+    toCellProps(ctx) {
+        return {
+            value: ctx.getValue(),
+            row: ctx.row.original,
+            rowIndex: ctx.row.index,
+            columnId: this.key,
+            renderedValue: formatByDataType(ctx.getValue(), this.dataType),
+        };
+    }
+    /** 셀 렌더러 교체 — `value` 는 셀 값 타입 `V` 로 온다 */
+    setCell(render) {
+        this.column.cell = (ctx) => render(this.toCellProps(ctx));
+        return this;
+    }
+    /** 기존 렌더 결과를 감싼다 (링크·칩 등) */
+    setCellWrapper(wrap) {
+        const previous = this.column.cell;
+        this.column.cell = (ctx) => {
+            const props = this.toCellProps(ctx);
+            const rendered = previous ? previous(ctx) : props.renderedValue;
+            return wrap(rendered, props);
+        };
+        return this;
+    }
+    /**
+     * 표시 여부.
+     *
+     * `forceHidden` 은 값 보관 전용 — 사용자 토글이나 프리셋 복원으로도 되살아나지
+     * 않는다. `isVisible: false` 는 "기본 숨김"일 뿐이라 되살아난다. 헤더가 없는
+     * 컬럼(통합 cascade 에 흡수된 레벨 등)은 반드시 `forceHidden` 을 쓴다.
+     */
+    setDisplay(options = {}) {
+        const display = options.display ?? true;
+        const forceHidden = options.forceHidden ?? false;
+        const hideFilter = (options.hideFilter ?? false) || forceHidden;
+        this.setMeta({
+            isVisible: forceHidden ? false : display,
+            ...(forceHidden ? { forceHidden: true } : {}),
+        });
+        // 필터 숨김은 FilterSpec 으로 — 원본이 meta.hideFilter 로 흩어 놨던 것을 모았다
+        this.setFilter({ hidden: hideFilter });
+        // 표시는 접고 필터만 남긴 컬럼은 "상세 조건" 그룹으로 내린다
+        if (!display && !hideFilter)
+            this.setFilter({ detail: true });
+        return this;
+    }
+    setEditable(enabled = true, onCommit) {
+        const kind = this.dataType === "number" ? "number" : "text";
+        return this.setEdit({ enabled, kind, onCommit });
+    }
+    /**
+     * 선택 편집 — 선언만 남긴다. dropdown/chip/button 컴포넌트는 렌더러가 그린다.
+     */
+    setEditSelect(config) {
+        return this.setEdit({ ...config, enabled: true, kind: "select" });
+    }
+    setEdit(spec) {
+        return this.setMeta({ edit: spec });
+    }
+    /**
+     * 필터 선택지. 목록이 있는 컬럼은 자유 텍스트 입력 대상이 아니다 —
+     * 라벨과 저장값이 달라 드롭다운이 사라지면 화면의 라벨을 쳐서 조용히 0건이 된다.
+     */
+    setFilterOptions(options, includeAll = true) {
+        const withAll = includeAll
+            ? [{ label: "전체", value: ALL_FILTER_VALUE }, ...options]
+            : options;
+        this.setMeta({ selectOptions: withAll });
+        const variant = this.column.filter?.variant;
+        if (variant === "text")
+            this.setVariant("select");
+        return this;
+    }
+    /** 집계 활성 — 서버 집계 키와 클라이언트 그룹 집계에 함께 쓰인다 */
+    setAgg(enabled, aggregations) {
+        const fallback = this.dataType === "number" ? ["sum"] : ["count_distinct"];
+        return this.setMeta({
+            enableAgg: enabled,
+            ...(enabled ? { aggregations: aggregations ?? fallback } : {}),
+        });
+    }
+    setFooter(footer) {
+        this.column.footer = footer;
+        return this;
+    }
+    /** 이 컬럼으로 정렬할 때 서버에 대신 보낼 실제 필드 (가상/통합 컬럼) */
+    setSortExpandsTo(fields) {
+        return this.setMeta({ sortExpandsTo: fields });
+    }
+    getColumn() {
+        return this.column;
+    }
+    build() {
+        return this.column;
+    }
+}
+/** 빌더 배열을 컬럼 정의 배열로 */
+export function buildColumns(builders) {
+    const result = [];
+    for (const entry of builders) {
+        if (Array.isArray(entry))
+            result.push(...entry.map((b) => b.build()));
+        else if (entry instanceof ColumnBuilder)
+            result.push(entry.build());
+        else
+            result.push(entry);
+    }
+    return result;
+}

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

@@ -0,0 +1,24 @@
+import type { RowData } from "@tanstack/react-table";
+import type { SelectOption, TableColumnDefs } from "../types/column";
+import type { ColumnFilterEntry } from "../types/request";
+/** 컬럼 id → 상위 선택으로 좁혀진 선택지 */
+export type CascadeOptionMap = Map<string, SelectOption[]>;
+/**
+ * 상위 필터 값에 따라 하위 컬럼의 선택지를 좁힌다.
+ *
+ * 두 가지 선언을 함께 처리한다:
+ * - `meta.dependentFilter` — CommonCode 계층. `allChildOptions` 를 상위 idx 로 거른다
+ * - `meta.customCascadeFilter` — 호출부가 준 `getOptions(...상위값)`
+ *
+ * **상위가 안 골라졌으면 빈 목록**이다. 전체를 보여 주면 상위와 무관한 값을 고를 수
+ * 있게 되고, 그렇게 만들어진 조합은 서버에서 0건이 된다.
+ */
+export declare function resolveCascadeOptions<T extends RowData>(columns: TableColumnDefs<T>, filters: ColumnFilterEntry[]): CascadeOptionMap;
+/**
+ * 상위가 바뀌어 더 이상 고를 수 없게 된 하위 값을 걷어낸다.
+ *
+ * 안 걷어내면 화면에는 없는 값이 조건으로 남아 조용히 0건이 된다.
+ * 선택지가 **비어 있으면 건너뛴다** — CommonCode 가 아직 안 실린 상태일 수 있어서,
+ * 그때 지우면 사용자가 고른 조건이 로딩 타이밍 때문에 날아간다.
+ */
+export declare function pruneCascadeValues(filters: ColumnFilterEntry[], options: CascadeOptionMap): ColumnFilterEntry[];

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

@@ -0,0 +1,93 @@
+import { ALL_FILTER_VALUE } from "../filters/list";
+import { columnKey } from "./deriveOperators";
+function filterValueOf(filters, id) {
+    return filters.find((f) => f?.id === id)?.value;
+}
+/** 필터 값에서 숫자 목록을 뽑는다. 비었으면 null */
+function numericSelections(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const list = Array.isArray(value) ? value : [value];
+    const numbers = list
+        .filter((v) => v !== ALL_FILTER_VALUE)
+        .map(Number)
+        .filter((v) => !Number.isNaN(v));
+    return numbers.length > 0 ? numbers : null;
+}
+/** 원래 선택지에 "전체" 센티널이 있었으면 좁힌 목록에도 유지한다 */
+function keepAllSentinel(original, narrowed) {
+    const all = original?.find((option) => option.value === ALL_FILTER_VALUE);
+    return all ? [all, ...narrowed] : narrowed;
+}
+/**
+ * 상위 필터 값에 따라 하위 컬럼의 선택지를 좁힌다.
+ *
+ * 두 가지 선언을 함께 처리한다:
+ * - `meta.dependentFilter` — CommonCode 계층. `allChildOptions` 를 상위 idx 로 거른다
+ * - `meta.customCascadeFilter` — 호출부가 준 `getOptions(...상위값)`
+ *
+ * **상위가 안 골라졌으면 빈 목록**이다. 전체를 보여 주면 상위와 무관한 값을 고를 수
+ * 있게 되고, 그렇게 만들어진 조합은 서버에서 0건이 된다.
+ */
+export function resolveCascadeOptions(columns, filters) {
+    const map = new Map();
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        const meta = column.meta;
+        const dependent = meta?.dependentFilter;
+        if (dependent) {
+            const parent = numericSelections(filterValueOf(filters, dependent.dependsOn));
+            if (parent === null) {
+                map.set(id, keepAllSentinel(meta?.selectOptions, []));
+                continue;
+            }
+            const narrowed = dependent.allChildOptions
+                .filter((option) => parent.includes(option.parentIdx))
+                .map((option) => ({
+                // 계층 체인이 있으면 그걸 보여 준다 — 같은 이름의 하위가 여럿일 때 구분된다
+                label: option.ancestorChain || option.name,
+                value: String(option.idx),
+            }));
+            map.set(id, keepAllSentinel(meta?.selectOptions, narrowed));
+            continue;
+        }
+        const custom = meta?.customCascadeFilter;
+        if (custom) {
+            const parents = custom.ancestorKeys.map((key) => numericSelections(filterValueOf(filters, key)));
+            try {
+                map.set(id, keepAllSentinel(meta?.selectOptions, custom.getOptions(...parents)));
+            }
+            catch {
+                // 호출부 함수가 던지면 필터를 못 그리는 것보다 빈 목록이 낫다
+                map.set(id, keepAllSentinel(meta?.selectOptions, []));
+            }
+        }
+    }
+    return map;
+}
+/**
+ * 상위가 바뀌어 더 이상 고를 수 없게 된 하위 값을 걷어낸다.
+ *
+ * 안 걷어내면 화면에는 없는 값이 조건으로 남아 조용히 0건이 된다.
+ * 선택지가 **비어 있으면 건너뛴다** — CommonCode 가 아직 안 실린 상태일 수 있어서,
+ * 그때 지우면 사용자가 고른 조건이 로딩 타이밍 때문에 날아간다.
+ */
+export function pruneCascadeValues(filters, options) {
+    if (options.size === 0)
+        return filters;
+    const invalid = new Set();
+    for (const [id, valid] of options) {
+        if (valid.length === 0)
+            continue;
+        const current = filterValueOf(filters, id);
+        if (current === null || current === undefined || current === "")
+            continue;
+        const allowed = new Set(valid.map((option) => option.value));
+        const values = Array.isArray(current) ? current : [current];
+        if (values.some((value) => !allowed.has(String(value))))
+            invalid.add(id);
+    }
+    return invalid.size === 0 ? filters : filters.filter((f) => !invalid.has(f.id));
+}

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

@@ -0,0 +1,38 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDef, TableColumnDefs, ColumnMeta } from "../types/column";
+import type { FilterOperator, FilterVariant } from "../types/operators";
+/** 컬럼 id — `id` 우선, 없으면 `accessorKey` */
+export declare function columnKey<T extends RowData>(column: TableColumnDef<T>): string | undefined;
+/** `filter.variant` 미지정 시 데이터 타입에서 유추 */
+export declare function inferVariant(meta?: ColumnMeta): FilterVariant;
+/** `filter.variant` > kind 의 힌트(`variant`/`dataKind`) > `meta.dataType` 유추 */
+export declare function resolveVariant<T extends RowData>(column: TableColumnDef<T>): FilterVariant;
+/** `filter.operators` > kind 의 `offered`(없으면 전체) > `OPERATORS_BY_VARIANT[variant]` */
+export declare function resolveOperatorOptions<T extends RowData>(column: TableColumnDef<T>): readonly FilterOperator[];
+/**
+ * 컬럼 정의에서 기본 연산자 맵을 만든다.
+ *
+ * **이것이 상태가 아니라 파생값이라는 점이 핵심이다.** 기존 구조는 같은 값을
+ * `generateColumnFilterFns` 로 계산해 `useFilterFnsInit` 이 effect 로 state 에
+ * 밀어 넣었고, 그동안 `filterFnsReady` 가 첫 조회를 막았다. 여기서는
+ * `useMemo(() => deriveOperators(columns), [columns])` 한 줄이면 끝이라
+ * 초기화 effect·게이트·중복 계산이 전부 사라진다.
+ */
+export declare function deriveOperators<T extends RowData>(columns: TableColumnDefs<T>): Record<string, FilterOperator>;
+/**
+ * 파생 → 초기 오버라이드 → 사용자 변경분 순으로 겹친다.
+ * `reset()` 은 `overrides` 만 비우면 되므로, 기존 `reset` 이
+ * `paramsRef.current.columnFilterFns` 를 특례로 보존하던 코드가 필요 없다.
+ */
+export declare function mergeOperators(derived: Record<string, FilterOperator>, initial?: Record<string, FilterOperator>, overrides?: Record<string, FilterOperator>): Record<string, FilterOperator>;
+/**
+ * 테이블 인스턴스에서 우리 `ColumnMeta` 를 꺼낸다.
+ *
+ * `ColumnDef.meta` 의 타입은 TanStack 의 `ColumnMeta` 인터페이스다. 우리는 전역
+ * module augmentation 대신 `TableColumnDef` 교차 타입으로 meta 를 얹었기 때문에
+ * (augmentation 은 이 패키지를 안 쓰는 소비자에게까지 새어 나간다), 인스턴스
+ * 경유로 읽을 때는 이 헬퍼로 한 번만 좁힌다.
+ */
+export declare function columnMetaOf<Ext = {}>(columnDef: {
+    meta?: unknown;
+} | undefined): ColumnMeta<Ext> | undefined;

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

@@ -0,0 +1,94 @@
+import { OPERATORS_BY_VARIANT } from "../types/operators";
+import { filterKindVariant, resolveFilterKind } from "../filters/kind";
+/** 컬럼 id — `id` 우선, 없으면 `accessorKey` */
+export function columnKey(column) {
+    const withKey = column;
+    if (withKey.id)
+        return withKey.id;
+    if (withKey.accessorKey != null)
+        return String(withKey.accessorKey);
+    return undefined;
+}
+/** `filter.variant` 미지정 시 데이터 타입에서 유추 */
+export function inferVariant(meta) {
+    switch (meta?.dataType) {
+        case "number": return "number";
+        case "date": return "date";
+        case "datetime": return "datetime";
+        case "boolean": return "boolean";
+        case "enum":
+        case "select": return "select";
+        default: return "text";
+    }
+}
+/** `filter.variant` > kind 의 힌트(`variant`/`dataKind`) > `meta.dataType` 유추 */
+export function resolveVariant(column) {
+    if (column.filter?.variant)
+        return column.filter.variant;
+    const kind = resolveFilterKind(column);
+    if (kind)
+        return filterKindVariant(kind);
+    return inferVariant(column.meta);
+}
+/** `filter.operators` > kind 의 `offered`(없으면 전체) > `OPERATORS_BY_VARIANT[variant]` */
+export function resolveOperatorOptions(column) {
+    const declared = column.filter?.operators;
+    if (declared)
+        return declared;
+    const kind = resolveFilterKind(column);
+    if (kind)
+        return (kind.offered ?? kind.operatorNames);
+    return OPERATORS_BY_VARIANT[resolveVariant(column)];
+}
+/**
+ * 컬럼 정의에서 기본 연산자 맵을 만든다.
+ *
+ * **이것이 상태가 아니라 파생값이라는 점이 핵심이다.** 기존 구조는 같은 값을
+ * `generateColumnFilterFns` 로 계산해 `useFilterFnsInit` 이 effect 로 state 에
+ * 밀어 넣었고, 그동안 `filterFnsReady` 가 첫 조회를 막았다. 여기서는
+ * `useMemo(() => deriveOperators(columns), [columns])` 한 줄이면 끝이라
+ * 초기화 effect·게이트·중복 계산이 전부 사라진다.
+ */
+export function deriveOperators(columns) {
+    const result = {};
+    for (const column of columns) {
+        const key = columnKey(column);
+        if (!key)
+            continue;
+        const spec = column.filter;
+        const options = resolveOperatorOptions(column);
+        // 명시 기본값 > 명시 목록의 첫 항목(기존 규칙) > kind 의 기본 연산자 > 후보 첫 항목
+        const kindDefault = resolveFilterKind(column)?.defaultOperator;
+        result[key] = spec?.defaultOperator
+            ?? (spec?.operators ? options[0] : undefined)
+            ?? kindDefault
+            ?? options[0]
+            ?? "contains";
+        // 통합 cascade: 레벨 키는 컬럼이 없어도 서버 필터 연산자가 필요하다
+        for (const level of column.meta?.cascadeFilterLevels ?? []) {
+            result[level.key] = (level.operator ||
+                level.operatorOptions?.[0] ||
+                "inArray");
+        }
+    }
+    return result;
+}
+/**
+ * 파생 → 초기 오버라이드 → 사용자 변경분 순으로 겹친다.
+ * `reset()` 은 `overrides` 만 비우면 되므로, 기존 `reset` 이
+ * `paramsRef.current.columnFilterFns` 를 특례로 보존하던 코드가 필요 없다.
+ */
+export function mergeOperators(derived, initial, overrides) {
+    return { ...derived, ...initial, ...overrides };
+}
+/**
+ * 테이블 인스턴스에서 우리 `ColumnMeta` 를 꺼낸다.
+ *
+ * `ColumnDef.meta` 의 타입은 TanStack 의 `ColumnMeta` 인터페이스다. 우리는 전역
+ * module augmentation 대신 `TableColumnDef` 교차 타입으로 meta 를 얹었기 때문에
+ * (augmentation 은 이 패키지를 안 쓰는 소비자에게까지 새어 나간다), 인스턴스
+ * 경유로 읽을 때는 이 헬퍼로 한 번만 좁힌다.
+ */
+export function columnMetaOf(columnDef) {
+    return columnDef?.meta;
+}

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

@@ -0,0 +1,19 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { SortEntry } from "../types/request";
+/**
+ * 통합 컬럼의 정렬을 실제 필드로 펼친다 (기존 `expandCascadeSorting` 계승).
+ *
+ * cascade 통합 컬럼이나 일정 통합 컬럼은 행에 없는 가상 컬럼이라 그 id 를 그대로
+ * 서버에 보내면 정렬이 먹지 않거나 400 이 난다. `meta.sortExpandsTo` 에 적힌
+ * 실제 필드 순서(상위 → 하위)로, 원래 항목과 **같은 방향**의 정렬 항목들로 바꾼다.
+ *
+ * - UI 상태(`SearchState.sorting`)는 통합 컬럼 id 를 유지한다 — 헤더의 정렬 화살표는
+ *   통합 컬럼에 그려져야 한다. 펼치는 곳은 요청(`TableSearch.request`) 조립부다.
+ * - 같은 id 가 두 번 나오면 앞의 것만 남긴다 (두 통합 컬럼이 같은 필드를 공유할 때
+ *   뒤쪽은 어차피 순서에 영향이 없다).
+ * - 펼친 항목은 `key` 를 갖지 않는다 — 통합 컬럼의 `key` 는 통합 컬럼용이다.
+ *
+ * 클라이언트 `applySorting` 은 `key ?? id` 를 읽으므로 펼친 요청이 그대로 동작한다.
+ */
+export declare function expandSorting<T extends RowData>(sorting: SortEntry[] | undefined, columns: TableColumnDefs<T>): SortEntry[];

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

@@ -0,0 +1,52 @@
+import { columnKey } from "./deriveOperators";
+/**
+ * 통합 컬럼의 정렬을 실제 필드로 펼친다 (기존 `expandCascadeSorting` 계승).
+ *
+ * cascade 통합 컬럼이나 일정 통합 컬럼은 행에 없는 가상 컬럼이라 그 id 를 그대로
+ * 서버에 보내면 정렬이 먹지 않거나 400 이 난다. `meta.sortExpandsTo` 에 적힌
+ * 실제 필드 순서(상위 → 하위)로, 원래 항목과 **같은 방향**의 정렬 항목들로 바꾼다.
+ *
+ * - UI 상태(`SearchState.sorting`)는 통합 컬럼 id 를 유지한다 — 헤더의 정렬 화살표는
+ *   통합 컬럼에 그려져야 한다. 펼치는 곳은 요청(`TableSearch.request`) 조립부다.
+ * - 같은 id 가 두 번 나오면 앞의 것만 남긴다 (두 통합 컬럼이 같은 필드를 공유할 때
+ *   뒤쪽은 어차피 순서에 영향이 없다).
+ * - 펼친 항목은 `key` 를 갖지 않는다 — 통합 컬럼의 `key` 는 통합 컬럼용이다.
+ *
+ * 클라이언트 `applySorting` 은 `key ?? id` 를 읽으므로 펼친 요청이 그대로 동작한다.
+ */
+export function expandSorting(sorting, columns) {
+    if (!sorting || sorting.length === 0)
+        return sorting ?? [];
+    const aliases = new Map();
+    for (const column of columns) {
+        const id = columnKey(column);
+        const targets = column.meta?.sortExpandsTo;
+        if (id && targets && targets.length > 0)
+            aliases.set(id, targets);
+    }
+    if (aliases.size === 0)
+        return sorting;
+    const seen = new Set();
+    const expanded = [];
+    let changed = false;
+    for (const entry of sorting) {
+        const targets = aliases.get(entry.id);
+        if (!targets) {
+            if (seen.has(entry.id)) {
+                changed = true;
+                continue;
+            }
+            seen.add(entry.id);
+            expanded.push(entry);
+            continue;
+        }
+        changed = true;
+        for (const id of targets) {
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            expanded.push({ id, desc: entry.desc });
+        }
+    }
+    return changed ? expanded : sorting;
+}