kokotable 0.95.0

package/dist/mui/src/virtualColumns/VirtualColumnSection.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Grid, Typography } from "@mui/material";
+import AddIcon from "@mui/icons-material/Add";
+import { VirtualColumnCard } from "./VirtualColumnCard";
+import { VirtualColumnDialog } from "./VirtualColumnDialog";
+/**
+ * 가상 열 섹션 — 카드 목록 + 추가 버튼 + 추가/편집 다이얼로그.
+ *
+ * 기존 ERP `VirtualColumnSection` 대응. `FilterArea` 의 children 이나 툴바 어디든 놓을 수 있고
+ * 다이얼로그 상태를 스스로 관리한다. 상태는 훅(`useVirtualColumns`)이 검색 상태 위에서 들고 있다.
+ */
+export function VirtualColumnSection({ virtualColumns, fields: fieldsProp, gridSize, enableFilter = false, addLabel = "가상 열 추가", cardWidth = 220, }) {
+    const [dialogOpen, setDialogOpen] = useState(false);
+    const [editing, setEditing] = useState(undefined);
+    const fields = fieldsProp ?? virtualColumns.fields;
+    const { search } = virtualColumns;
+    const filterOf = (column) => {
+        if (!enableFilter)
+            return undefined;
+        const entry = search.draft.columnFilters.find((f) => f.id === column.slotKey);
+        const fallback = column.type === "number" ? "greaterThanOrEqualTo" : "contains";
+        const operator = (search.draft.columnFilterFns[column.slotKey] ?? fallback);
+        return {
+            value: entry?.value,
+            operator,
+            onChange: (value, nextOperator) => {
+                if (nextOperator !== operator)
+                    search.setOperator(column.slotKey, nextOperator);
+                search.setFilter(column.slotKey, value);
+            },
+        };
+    };
+    const openAdd = () => { setEditing(undefined); setDialogOpen(true); };
+    const openEdit = (column) => { setEditing(column); setDialogOpen(true); };
+    const close = () => { setDialogOpen(false); setEditing(undefined); };
+    const cards = virtualColumns.columns.map((column) => (_jsx(VirtualColumnCard, { column: column, fields: fields, onEdit: () => openEdit(column), onRemove: () => virtualColumns.remove(column.slotKey), filter: filterOf(column) }, column.slotKey)));
+    const addButton = !virtualColumns.isMaxReached && (_jsxs(Box, { role: "button", tabIndex: 0, "aria-label": typeof addLabel === "string" ? addLabel : "가상 열 추가", onClick: openAdd, onKeyDown: (event) => {
+            if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                openAdd();
+            }
+        }, sx: {
+            display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center",
+            border: "2px dashed", borderColor: "divider", borderRadius: 1, p: 1, minHeight: 64,
+            cursor: "pointer", color: "text.secondary",
+            "&:hover": { borderColor: "info.main", color: "info.main" },
+            transition: "all 0.2s",
+        }, children: [_jsx(AddIcon, { sx: { fontSize: 22 } }), _jsx(Typography, { variant: "caption", sx: { fontWeight: 500, mt: 0.25 }, children: addLabel })] }));
+    const dialog = (_jsx(VirtualColumnDialog, { open: dialogOpen, onClose: close, initialValues: editing, fields: fields, validate: virtualColumns.validate, onSubmit: (column) => (editing ? virtualColumns.update(editing.slotKey, column) : virtualColumns.add(column)) }));
+    if (gridSize) {
+        return (_jsxs(_Fragment, { children: [virtualColumns.columns.map((column, index) => (_jsx(Grid, { size: gridSize, children: cards[index] }, column.slotKey))), addButton && _jsx(Grid, { size: gridSize, children: addButton }), dialog] }));
+    }
+    return (_jsxs(Box, { "data-testid": "virtual-column-section", sx: { display: "flex", flexWrap: "wrap", gap: 1, alignItems: "stretch" }, children: [cards.map((card, index) => (_jsx(Box, { sx: { width: cardWidth, minWidth: 0 }, children: card }, virtualColumns.columns[index].slotKey))), addButton && _jsx(Box, { sx: { width: cardWidth }, children: addButton }), dialog] }));
+}

package/dist/mui/src/virtualColumns/expression.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 가상 컬럼 수식 — 클라이언트 검증·평가.
+ *
+ * 서버 `QueryBuilder/core/expression_parser.py` 의 문법을 그대로 옮겼다. 서버가 400 을
+ * 줄 식은 **여기서 먼저 거른다** — 다이얼로그가 저장을 막고 이유를 보여 줄 수 있어야
+ * 하고, 스토리·테스트에서 서버 없이 같은 규칙으로 값을 계산할 수 있어야 한다.
+ *
+ * 1. 산술 수식 (`number` / `boolean`): 식별자 · 숫자 · `+ - * /` · 괄호 ·
+ *    함수 `DATE_TRUNC('month', col)` / `EXTRACT('year', col)`.
+ *    컬럼 참조는 `{column}` 으로 통일한다 (서버가 `{x}` → `x` 로 정규화한다).
+ * 2. 문자열 템플릿 (`string`): `"{product} / {option}"` — `{field}` 참조가 하나 이상 있어야 한다.
+ */
+export type VirtualColumnType = "number" | "string" | "boolean";
+export interface VirtualColumnField {
+    /** 컬럼 id — 서버 필드명 */
+    key: string;
+    /** 사용자에게 보이는 이름 */
+    header: string;
+}
+export type ExpressionValidation = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export type TokenType = "identifier" | "number" | "operator" | "lparen" | "rparen" | "function" | "string_literal" | "comma";
+export interface Token {
+    type: TokenType;
+    value: string;
+}
+/** `{field}` / `{relation.field}` 참조 */
+export declare const TEMPLATE_FIELD_PATTERN: RegExp;
+/** 산술 수식에서 `{field}` → `field` (서버 `_normalize_expr`) */
+export declare function normalizeExpression(expr: string): string;
+/** 수식·템플릿이 참조하는 필드 목록 (중복 제거, 등장 순) */
+export declare function referencedFields(expr: string, type?: VirtualColumnType): string[];
+/** 수식을 토큰으로 나눈다. 인식할 수 없는 문자가 있으면 throw */
+export declare function tokenizeExpression(expr: string): Token[];
+/**
+ * 수식 검증. `fields` 를 주면 식별자를 그 목록으로 제한한다(서버의 모델 컬럼 검사와 같은 역할).
+ * 주지 않으면 문법만 본다.
+ */
+export declare function validateExpression(expr: string, options?: {
+    type?: VirtualColumnType;
+    fields?: ReadonlyArray<VirtualColumnField | string>;
+}): ExpressionValidation;
+/**
+ * 산술 수식을 행 값으로 평가한다. 0 으로 나누면 `null`.
+ * 검증을 통과한 식만 넣는다 — 문법 오류는 throw 한다.
+ */
+export declare function evaluateExpression(row: unknown, expr: string): unknown;
+/** 문자열 템플릿 평가 — `{field}` 를 행 값으로 치환한다. NULL 은 빈 문자열 */
+export declare function evaluateTemplate(row: unknown, template: string): string;
+/**
+ * 타입에 맞춰 평가한다 — `string` 은 템플릿, 나머지는 산술.
+ * `boolean` 은 0/NULL 을 false 로 강제한다 (서버 `fill_virtual_columns` 와 같다).
+ */
+export declare function evaluateVirtualColumn(row: unknown, spec: {
+    expr: string;
+    type?: VirtualColumnType;
+}): unknown;
+/** 응답 행마다 가상 컬럼 값을 얹는다 — 스토리의 로컬 서버가 쓴다 */
+export declare function applyVirtualColumns<T>(rows: T[], spec: Record<string, {
+    expr: string;
+    type?: VirtualColumnType;
+}> | undefined): T[];
+/** 수식의 `{key}` / `key` 를 컬럼 헤더로 바꿔 사람이 읽을 형태로 만든다 (카드·미리보기용) */
+export declare function describeExpression(expr: string, fields: ReadonlyArray<VirtualColumnField>): string;

package/dist/mui/src/virtualColumns/expression.js

@@ -0,0 +1,489 @@
+/**
+ * 가상 컬럼 수식 — 클라이언트 검증·평가.
+ *
+ * 서버 `QueryBuilder/core/expression_parser.py` 의 문법을 그대로 옮겼다. 서버가 400 을
+ * 줄 식은 **여기서 먼저 거른다** — 다이얼로그가 저장을 막고 이유를 보여 줄 수 있어야
+ * 하고, 스토리·테스트에서 서버 없이 같은 규칙으로 값을 계산할 수 있어야 한다.
+ *
+ * 1. 산술 수식 (`number` / `boolean`): 식별자 · 숫자 · `+ - * /` · 괄호 ·
+ *    함수 `DATE_TRUNC('month', col)` / `EXTRACT('year', col)`.
+ *    컬럼 참조는 `{column}` 으로 통일한다 (서버가 `{x}` → `x` 로 정규화한다).
+ * 2. 문자열 템플릿 (`string`): `"{product} / {option}"` — `{field}` 참조가 하나 이상 있어야 한다.
+ */
+const OPERATOR_PRECEDENCE = { "+": 1, "-": 1, "*": 2, "/": 2 };
+const ALLOWED_FUNCTIONS = {
+    DATE_TRUNC: { args: 2 },
+    EXTRACT: { args: 2 },
+};
+const VALID_DATE_PRECISIONS = new Set(["year", "quarter", "month", "week", "day", "hour", "minute", "second"]);
+const VALID_EXTRACT_FIELDS = new Set([
+    "year", "quarter", "month", "week", "day", "hour", "minute", "second", "dow", "doy", "epoch",
+]);
+/** 서버 `TOKEN_PATTERN` 과 같은 순서: 문자열 리터럴 > 숫자 > 식별자 > 연산자 > 쉼표 > 괄호 > 공백 */
+const TOKEN_PATTERN = /('(?:[^']*)')|(\d+\.?\d*)|([a-zA-Z_]\w*(?:\.\w+)*)|([+\-*/])|(,)|(\()|(\))|(\s+)/y;
+/** `{field}` / `{relation.field}` 참조 */
+export const TEMPLATE_FIELD_PATTERN = /\{([\w.]+)\}/g;
+/** 산술 수식에서 `{field}` → `field` (서버 `_normalize_expr`) */
+export function normalizeExpression(expr) {
+    return expr.replace(TEMPLATE_FIELD_PATTERN, "$1");
+}
+/** 수식·템플릿이 참조하는 필드 목록 (중복 제거, 등장 순) */
+export function referencedFields(expr, type = "number") {
+    const seen = new Set();
+    if (type === "string") {
+        for (const match of expr.matchAll(TEMPLATE_FIELD_PATTERN))
+            seen.add(match[1]);
+        return [...seen];
+    }
+    try {
+        for (const token of tokenizeExpression(normalizeExpression(expr))) {
+            if (token.type === "identifier")
+                seen.add(token.value);
+        }
+    }
+    catch {
+        // 토큰화가 안 되는 식이면 참조도 없다 — 검증이 따로 이유를 만든다
+    }
+    return [...seen];
+}
+/** 수식을 토큰으로 나눈다. 인식할 수 없는 문자가 있으면 throw */
+export function tokenizeExpression(expr) {
+    const tokens = [];
+    let pos = 0;
+    while (pos < expr.length) {
+        TOKEN_PATTERN.lastIndex = pos;
+        const match = TOKEN_PATTERN.exec(expr);
+        if (!match || match.index !== pos) {
+            throw new Error(`수식에서 인식할 수 없는 문자: '${expr[pos]}' (위치 ${pos})`);
+        }
+        if (match[1] !== undefined) {
+            tokens.push({ type: "string_literal", value: match[1].slice(1, -1) });
+        }
+        else if (match[2] !== undefined) {
+            tokens.push({ type: "number", value: match[2] });
+        }
+        else if (match[3] !== undefined) {
+            const name = match[3];
+            const upper = name.toUpperCase();
+            if (upper in ALLOWED_FUNCTIONS && expr.slice(pos + name.length).trimStart().startsWith("(")) {
+                tokens.push({ type: "function", value: upper });
+            }
+            else {
+                tokens.push({ type: "identifier", value: name });
+            }
+        }
+        else if (match[4] !== undefined) {
+            tokens.push({ type: "operator", value: match[4] });
+        }
+        else if (match[5] !== undefined) {
+            tokens.push({ type: "comma", value: "," });
+        }
+        else if (match[6] !== undefined) {
+            tokens.push({ type: "lparen", value: "(" });
+        }
+        else if (match[7] !== undefined) {
+            tokens.push({ type: "rparen", value: ")" });
+        }
+        pos += match[0].length;
+    }
+    if (tokens.length === 0)
+        throw new Error("빈 수식입니다.");
+    return tokens;
+}
+/** 밑줄로 시작하는 세그먼트는 서버가 무조건 거부한다 (`__class__` 류 내부 경로 차단) */
+function isSafeIdentifier(name) {
+    return name.split(".").every((part) => part.length > 0 && !part.startsWith("_"));
+}
+function validateTokens(tokens, allowed) {
+    let depth = 0;
+    const funcStack = [];
+    const funcArgCount = [];
+    tokens.forEach((token, i) => {
+        const prev = tokens[i - 1];
+        switch (token.type) {
+            case "identifier": {
+                const known = allowed === null ? true : allowed.has(token.value);
+                if (!isSafeIdentifier(token.value) || !known) {
+                    const hint = allowed ? ` 사용 가능한 컬럼: ${[...allowed].sort().join(", ")}` : "";
+                    throw new Error(`허용되지 않는 식별자: '${token.value}'.${hint}`);
+                }
+                break;
+            }
+            case "function":
+                if (!(token.value in ALLOWED_FUNCTIONS))
+                    throw new Error(`허용되지 않는 함수: '${token.value}'`);
+                break;
+            case "string_literal": {
+                const fn = funcStack[funcStack.length - 1];
+                if (!fn)
+                    throw new Error(`문자열 리터럴 '${token.value}'은(는) 함수 인자로만 사용할 수 있습니다.`);
+                const value = token.value.toLowerCase();
+                if (fn === "DATE_TRUNC" && !VALID_DATE_PRECISIONS.has(value)) {
+                    throw new Error(`DATE_TRUNC의 유효하지 않은 precision: '${token.value}'. 허용값: ${[...VALID_DATE_PRECISIONS].sort().join(", ")}`);
+                }
+                if (fn === "EXTRACT" && !VALID_EXTRACT_FIELDS.has(value)) {
+                    throw new Error(`EXTRACT의 유효하지 않은 field: '${token.value}'. 허용값: ${[...VALID_EXTRACT_FIELDS].sort().join(", ")}`);
+                }
+                break;
+            }
+            case "operator":
+                if (!(token.value in OPERATOR_PRECEDENCE))
+                    throw new Error(`허용되지 않는 연산자: '${token.value}'`);
+                break;
+            case "lparen":
+                depth += 1;
+                if (prev?.type === "function") {
+                    funcStack.push(prev.value);
+                    funcArgCount.push(1);
+                }
+                else {
+                    funcStack.push("");
+                    funcArgCount.push(0);
+                }
+                break;
+            case "rparen": {
+                depth -= 1;
+                if (depth < 0)
+                    throw new Error("괄호 짝이 맞지 않습니다: 닫는 괄호 초과");
+                const fn = funcStack.pop();
+                const count = funcArgCount.pop() ?? 0;
+                if (fn) {
+                    const expected = ALLOWED_FUNCTIONS[fn].args;
+                    if (count !== expected)
+                        throw new Error(`${fn} 는 인자 ${expected}개가 필요합니다.`);
+                }
+                break;
+            }
+            case "comma": {
+                const fn = funcStack[funcStack.length - 1];
+                if (!fn)
+                    throw new Error("쉼표 위치가 올바르지 않습니다.");
+                funcArgCount[funcArgCount.length - 1] = (funcArgCount[funcArgCount.length - 1] ?? 0) + 1;
+                break;
+            }
+            default:
+                break;
+        }
+    });
+    if (depth > 0)
+        throw new Error("괄호 짝이 맞지 않습니다: 여는 괄호 초과");
+}
+/**
+ * Shunting-yard → 후위 표기. 구조 오류(피연산자 부족 등)는 여기서 드러난다.
+ * 함수 호출은 `function` 토큰 하나로 접어 인자를 뒤에 둔다: `'month' col DATE_TRUNC`.
+ */
+function toPostfix(tokens) {
+    const output = [];
+    const stack = [];
+    for (const token of tokens) {
+        switch (token.type) {
+            case "number":
+            case "identifier":
+            case "string_literal":
+                output.push(token);
+                break;
+            case "function":
+                stack.push(token);
+                break;
+            case "comma":
+                while (stack.length > 0 && stack[stack.length - 1].type !== "lparen")
+                    output.push(stack.pop());
+                if (stack.length === 0)
+                    throw new Error("쉼표 위치가 올바르지 않습니다.");
+                break;
+            case "operator": {
+                const prec = OPERATOR_PRECEDENCE[token.value];
+                while (stack.length > 0) {
+                    const top = stack[stack.length - 1];
+                    if (top.type === "operator" && OPERATOR_PRECEDENCE[top.value] >= prec)
+                        output.push(stack.pop());
+                    else
+                        break;
+                }
+                stack.push(token);
+                break;
+            }
+            case "lparen":
+                stack.push(token);
+                break;
+            case "rparen": {
+                while (stack.length > 0 && stack[stack.length - 1].type !== "lparen")
+                    output.push(stack.pop());
+                if (stack.length === 0)
+                    throw new Error("괄호 짝이 맞지 않습니다.");
+                stack.pop();
+                if (stack.length > 0 && stack[stack.length - 1].type === "function")
+                    output.push(stack.pop());
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    while (stack.length > 0) {
+        const top = stack.pop();
+        if (top.type === "lparen")
+            throw new Error("괄호 짝이 맞지 않습니다.");
+        output.push(top);
+    }
+    return output;
+}
+/** 후위식이 값 하나로 닫히는지 — 평가 없이 스택 깊이만 센다 */
+function checkPostfix(postfix) {
+    let depth = 0;
+    for (const token of postfix) {
+        if (token.type === "operator") {
+            if (depth < 2)
+                throw new Error(`연산자 '${token.value}'에 대한 피연산자가 부족합니다.`);
+            depth -= 1;
+        }
+        else if (token.type === "function") {
+            const args = ALLOWED_FUNCTIONS[token.value].args;
+            if (depth < args)
+                throw new Error(`${token.value} 는 인자 ${args}개가 필요합니다.`);
+            depth -= args - 1;
+        }
+        else {
+            depth += 1;
+        }
+    }
+    if (depth !== 1)
+        throw new Error("수식이 올바르지 않습니다: 최종 결과가 하나가 아닙니다.");
+}
+/**
+ * 수식 검증. `fields` 를 주면 식별자를 그 목록으로 제한한다(서버의 모델 컬럼 검사와 같은 역할).
+ * 주지 않으면 문법만 본다.
+ */
+export function validateExpression(expr, options = {}) {
+    const { type = "number", fields } = options;
+    const allowed = fields ? new Set(fields.map((f) => (typeof f === "string" ? f : f.key))) : null;
+    try {
+        if (type === "string") {
+            if (!expr.trim())
+                throw new Error("빈 수식입니다.");
+            const refs = referencedFields(expr, "string");
+            if (refs.length === 0)
+                throw new Error("템플릿에 {field} 참조가 없습니다.");
+            for (const field of refs) {
+                if (!isSafeIdentifier(field) || (allowed && !allowed.has(field))) {
+                    const hint = allowed ? ` 사용 가능한 컬럼: ${[...allowed].sort().join(", ")}` : "";
+                    throw new Error(`허용되지 않는 필드: '${field}'.${hint}`);
+                }
+            }
+            return { ok: true };
+        }
+        const tokens = tokenizeExpression(normalizeExpression(expr));
+        validateTokens(tokens, allowed);
+        checkPostfix(toPostfix(tokens));
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+}
+function readPath(row, path) {
+    let current = row;
+    for (const part of path.split(".")) {
+        if (current === null || current === undefined || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/** NULL/NaN 은 0 으로 본다 — 서버 `evaluate` 와 같은 규칙 */
+function toNumber(value) {
+    if (value === null || value === undefined)
+        return 0;
+    if (typeof value === "number")
+        return Number.isNaN(value) ? 0 : value;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (value instanceof Date)
+        return value.getTime();
+    const parsed = Number(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === "string" || typeof value === "number") {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}
+function truncateDate(date, precision) {
+    const d = new Date(date.getTime());
+    switch (precision) {
+        case "year":
+            d.setMonth(0, 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case "quarter":
+            d.setMonth(Math.floor(d.getMonth() / 3) * 3, 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case "month":
+            d.setDate(1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case "week": {
+            // ISO 주 시작(월요일)
+            const day = (d.getDay() + 6) % 7;
+            d.setDate(d.getDate() - day);
+            d.setHours(0, 0, 0, 0);
+            break;
+        }
+        case "day":
+            d.setHours(0, 0, 0, 0);
+            break;
+        case "hour":
+            d.setMinutes(0, 0, 0);
+            break;
+        case "minute":
+            d.setSeconds(0, 0);
+            break;
+        case "second":
+            d.setMilliseconds(0);
+            break;
+        default: break;
+    }
+    return d;
+}
+function extractField(date, field) {
+    switch (field) {
+        case "year": return date.getFullYear();
+        case "quarter": return Math.floor(date.getMonth() / 3) + 1;
+        case "month": return date.getMonth() + 1;
+        case "week": {
+            const target = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+            const dayNum = target.getUTCDay() || 7;
+            target.setUTCDate(target.getUTCDate() + 4 - dayNum);
+            const yearStart = Date.UTC(target.getUTCFullYear(), 0, 1);
+            return Math.ceil(((target.getTime() - yearStart) / 86_400_000 + 1) / 7);
+        }
+        case "day": return date.getDate();
+        case "hour": return date.getHours();
+        case "minute": return date.getMinutes();
+        case "second": return date.getSeconds();
+        case "dow": return date.getDay();
+        case "doy": {
+            const start = new Date(date.getFullYear(), 0, 0);
+            return Math.floor((date.getTime() - start.getTime()) / 86_400_000);
+        }
+        case "epoch": return Math.floor(date.getTime() / 1000);
+        default: return 0;
+    }
+}
+/**
+ * 산술 수식을 행 값으로 평가한다. 0 으로 나누면 `null`.
+ * 검증을 통과한 식만 넣는다 — 문법 오류는 throw 한다.
+ */
+export function evaluateExpression(row, expr) {
+    const tokens = tokenizeExpression(normalizeExpression(expr));
+    validateTokens(tokens, null);
+    const postfix = toPostfix(tokens);
+    checkPostfix(postfix);
+    const stack = [];
+    const source = (row ?? {});
+    for (const token of postfix) {
+        switch (token.type) {
+            case "number":
+                stack.push(Number(token.value));
+                break;
+            case "identifier":
+                stack.push(readPath(source, token.value));
+                break;
+            case "string_literal":
+                stack.push(token.value);
+                break;
+            case "operator": {
+                // NULL 피연산자는 0 — 서버 `evaluate` 가 namespace 를 그렇게 채운다
+                const y = toNumber(stack.pop());
+                const x = toNumber(stack.pop());
+                switch (token.value) {
+                    case "+":
+                        stack.push(x + y);
+                        break;
+                    case "-":
+                        stack.push(x - y);
+                        break;
+                    case "*":
+                        stack.push(x * y);
+                        break;
+                    case "/":
+                        stack.push(y === 0 ? null : x / y);
+                        break;
+                    default: break;
+                }
+                break;
+            }
+            case "function": {
+                const column = stack.pop();
+                const literal = String(stack.pop() ?? "").toLowerCase();
+                const date = toDate(column);
+                if (!date) {
+                    stack.push(null);
+                    break;
+                }
+                if (token.value === "DATE_TRUNC")
+                    stack.push(truncateDate(date, literal).toISOString());
+                else
+                    stack.push(extractField(date, literal));
+                break;
+            }
+            default: break;
+        }
+    }
+    return stack[0] ?? null;
+}
+/** 문자열 템플릿 평가 — `{field}` 를 행 값으로 치환한다. NULL 은 빈 문자열 */
+export function evaluateTemplate(row, template) {
+    const source = (row ?? {});
+    return template.replace(TEMPLATE_FIELD_PATTERN, (_, field) => {
+        const value = readPath(source, field);
+        return value === null || value === undefined ? "" : String(value);
+    });
+}
+/**
+ * 타입에 맞춰 평가한다 — `string` 은 템플릿, 나머지는 산술.
+ * `boolean` 은 0/NULL 을 false 로 강제한다 (서버 `fill_virtual_columns` 와 같다).
+ */
+export function evaluateVirtualColumn(row, spec) {
+    const type = spec.type ?? "number";
+    if (type === "string")
+        return evaluateTemplate(row, spec.expr);
+    const value = evaluateExpression(row, spec.expr);
+    if (type === "boolean")
+        return value === null || value === undefined ? null : Boolean(value);
+    return value;
+}
+/** 응답 행마다 가상 컬럼 값을 얹는다 — 스토리의 로컬 서버가 쓴다 */
+export function applyVirtualColumns(rows, spec) {
+    if (!spec || Object.keys(spec).length === 0)
+        return rows;
+    return rows.map((row) => {
+        const next = { ...row };
+        for (const [slot, column] of Object.entries(spec)) {
+            try {
+                next[slot] = evaluateVirtualColumn(row, column);
+            }
+            catch {
+                next[slot] = null;
+            }
+        }
+        return next;
+    });
+}
+/** 수식의 `{key}` / `key` 를 컬럼 헤더로 바꿔 사람이 읽을 형태로 만든다 (카드·미리보기용) */
+export function describeExpression(expr, fields) {
+    const byKey = new Map(fields.map((f) => [f.key, f.header]));
+    const withBraces = expr.replace(TEMPLATE_FIELD_PATTERN, (whole, key) => byKey.get(key) ?? whole);
+    // 괄호 없이 쓴 식별자도 치환한다 — 긴 키부터 바꿔야 접두 충돌이 없다
+    const sorted = [...byKey.entries()].sort((a, b) => b[0].length - a[0].length);
+    let result = withBraces;
+    for (const [key, header] of sorted) {
+        result = result.replace(new RegExp(`(?<![\\w.{])${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w.}])`, "g"), header);
+    }
+    return result;
+}

package/dist/mui/src/virtualColumns/useVirtualColumns.d.ts

@@ -0,0 +1,67 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableSearch, VirtualColumnSpec } from "../../../core/src/index";
+import { type ExpressionValidation, type VirtualColumnField, type VirtualColumnType } from "./expression";
+/** 가상 열 (사용자 정의 계산 컬럼) — 기존 ERP `VirtualColumn` 과 같은 모양 */
+export interface VirtualColumn {
+    /** vc 슬롯 키 (`vc_1` …) — 요청 `virtualColumns` 의 키이자 응답 행의 필드명 */
+    slotKey: string;
+    /** 사용자 지정 이름 (예: "할인액"). 요청에는 실리지 않는다 — 헤더 표시용 */
+    name: string;
+    /** 계산 수식 (예: `{amount} * {quantity}`) */
+    expr: string;
+    type: VirtualColumnType;
+}
+export type VirtualColumnInput = Omit<VirtualColumn, "slotKey">;
+export type VirtualColumnResult = {
+    ok: true;
+    slotKey: string;
+} | {
+    ok: false;
+    message: string;
+};
+export interface UseVirtualColumnsOptions {
+    /**
+     * true(기본) — 추가·수정·삭제가 `patchParams` 로 **즉시 적용**된다 (정렬·페이지처럼 버튼 없는 조작).
+     * false — `patchDraft` 에 쌓이고 `search.apply()` 가 반영한다 (필터와 함께 검색 버튼으로).
+     */
+    applyImmediately?: boolean;
+    /** 슬롯 상한. 기본 10 (`vc_1` ~ `vc_10`) */
+    maxSlots?: number;
+    /** 슬롯 접두. 기본 `vc_` */
+    slotPrefix?: string;
+    /** 수식이 참조할 수 있는 필드. 주면 식별자 검증을 건다 (`virtualColumnFields(columns)`) */
+    fields?: ReadonlyArray<VirtualColumnField>;
+    /** 슬롯별 이름 초기값 — 이름은 검색 상태에 없으므로 URL 복원 등에서 따로 넘긴다 */
+    initialNames?: Record<string, string>;
+}
+export interface UseVirtualColumnsReturn<T extends RowData = RowData> {
+    search: TableSearch<T>;
+    /** 현재 가상 열 목록 (즉시 모드면 params, draft 모드면 draft 기준) */
+    columns: VirtualColumn[];
+    /** 추가 — 슬롯은 빈 것 중 가장 앞 번호. 검증 실패면 상태를 바꾸지 않고 이유를 돌려준다 */
+    add: (column: VirtualColumnInput) => VirtualColumnResult;
+    update: (slotKey: string, patch: Partial<VirtualColumnInput>) => VirtualColumnResult;
+    remove: (slotKey: string) => void;
+    /** 저장 전 검증 — 다이얼로그가 같은 규칙으로 미리 보여 준다 */
+    validate: (column: VirtualColumnInput, slotKey?: string) => ExpressionValidation;
+    /** 요청에 실리는 값 (`search.request.virtualColumns` 와 같다 — 즉시 모드 기준) */
+    request: Record<string, VirtualColumnSpec>;
+    isMaxReached: boolean;
+    /** 다음에 배정될 슬롯. 꽉 찼으면 null */
+    nextSlot: string | null;
+    applyImmediately: boolean;
+    /** 슬롯별 표시 이름 — `virtualColumnDefs(spec, { names })` 에 넘긴다 */
+    names: Record<string, string>;
+    fields: ReadonlyArray<VirtualColumnField>;
+}
+/** 슬롯 목록 `vc_1 … vc_N` (기존 ERP 규칙) */
+export declare function virtualColumnSlots(maxSlots?: number, prefix?: string): string[];
+/**
+ * 가상 열 상태 — `SearchState.virtualColumns` 위에서 CRUD 를 제공한다.
+ *
+ * 기존 ERP `useVirtualColumns` 는 목록을 로컬 state 로 들고 `virtualColumnsForRequest` 를
+ * 호출부가 요청에 직접 얹었다. 여기서는 검색 상태가 **원본**이다 — `search.request.virtualColumns`
+ * 로 자동으로 실리고, URL 동기화·프리셋·reset 도 같은 경로를 탄다. 이름만 로컬이다
+ * (요청 계약 `VirtualColumnSpec` 에 이름 자리가 없다).
+ */
+export declare function useVirtualColumns<T extends RowData>(search: TableSearch<T>, options?: UseVirtualColumnsOptions): UseVirtualColumnsReturn<T>;