kokotable 0.95.0

package/dist/core/src/filters/kinds/index.js

@@ -0,0 +1,39 @@
+import { filterKinds } from "../kind";
+import { textKind } from "./text";
+import { numberKind } from "./number";
+import { dateKind } from "./date";
+import { periodKind } from "./period";
+import { booleanKind } from "./boolean";
+import { enumKind } from "./enum";
+import { commonCodeKind } from "./commonCode";
+import { cascadeKind } from "./cascade";
+import { relationKind } from "./relation";
+import { scheduleKind } from "./schedule";
+import { linearKind } from "./linear";
+export { textKind, numberKind, dateKind, periodKind, booleanKind, enumKind, commonCodeKind, cascadeKind, relationKind, scheduleKind, linearKind };
+export { ENUM_OPERATORS, matchListOperator } from "./_list";
+export const BUILTIN_FILTER_KINDS = [
+    textKind, numberKind, dateKind, periodKind, booleanKind, enumKind,
+    commonCodeKind, cascadeKind, relationKind, scheduleKind, linearKind,
+];
+for (const kind of BUILTIN_FILTER_KINDS)
+    filterKinds.register(kind);
+/**
+ * variant → 내장 kind. `ColumnBuilder.setVariant` / `dataType` 유추가 kind 를 함께 붙이는 표.
+ * `custom` 은 kind 가 없다(호출부가 `render` 로 값 해석을 전담).
+ */
+export const BUILTIN_KIND_BY_VARIANT = {
+    text: textKind,
+    number: numberKind,
+    date: dateKind,
+    datetime: dateKind,
+    boolean: booleanKind,
+    select: enumKind,
+    multiSelect: enumKind,
+    relation: relationKind,
+    linear: linearKind,
+    schedule: scheduleKind,
+};
+export function builtinKindForVariant(variant) {
+    return BUILTIN_KIND_BY_VARIANT[variant];
+}

package/dist/core/src/filters/kinds/linear.d.ts

@@ -0,0 +1,5 @@
+import type { LinearOperator } from "../../types/operators";
+import { type LinearFilterValue } from "../linear";
+export type { LinearFilterValue };
+/** 선형결합(수량 조건) — `terms` 가 비면 미입력 */
+export declare const linearKind: import("../..").FilterKind<"linear", LinearFilterValue, LinearOperator, unknown>;

package/dist/core/src/filters/kinds/linear.js

@@ -0,0 +1,16 @@
+import { LINEAR_OPERATORS } from "../../types/operators";
+import { defineFilterKind, operatorTable } from "../kind";
+import { matchLinear } from "../linear";
+import { describeLinear } from "../describe";
+/** 선형결합(수량 조건) — `terms` 가 비면 미입력 */
+export const linearKind = defineFilterKind({
+    id: "linear",
+    variant: "linear",
+    operators: operatorTable(LINEAR_OPERATORS, (op) => ({
+        client: (_cell, value, ctx) => matchLinear(ctx.row, ctx.columnId, value, op),
+        describe: (value, ctx) => describeLinear(value, ctx),
+    })),
+    defaultOperator: "linearContains",
+    offered: ["linearContains", "linearExists", "linearExact"],
+    isEmpty: (value) => !value?.terms?.length,
+});

package/dist/core/src/filters/kinds/number.d.ts

@@ -0,0 +1,5 @@
+import type { NumberOperator } from "../../types/operators";
+export type NumberBound = number | null;
+/** 단일 값 · 범위 `[lo, hi]`(빈 쪽 null) · `isEmpty` 방향 boolean */
+export type NumberFilterValue = number | [NumberBound, NumberBound] | boolean;
+export declare const numberKind: import("../..").FilterKind<"number", NumberFilterValue, NumberOperator, unknown>;

package/dist/core/src/filters/kinds/number.js

@@ -0,0 +1,19 @@
+import { NUMBER_OPERATORS } from "../../types/operators";
+import { defineFilterKind, operatorTable } from "../kind";
+import { matchNumber } from "../number";
+import { describeRange, describeScalar } from "../describe";
+import { isUnsetFilterValue } from "../../utils/getValue";
+const RANGE = new Set(["between", "betweenInclusive", "outsideRange"]);
+export const numberKind = defineFilterKind({
+    id: "number",
+    dataKind: "number",
+    variant: "number",
+    operators: operatorTable(NUMBER_OPERATORS, (op) => ({
+        client: (cell, value) => matchNumber(cell, value, op),
+        describe: (value, ctx) => (RANGE.has(op) ? describeRange(value, ctx) : describeScalar(value, ctx)),
+        valueless: op === "isEmpty",
+    })),
+    defaultOperator: "betweenInclusive",
+    offered: ["betweenInclusive", "outsideRange", "isEmpty"],
+    isEmpty: isUnsetFilterValue,
+});

package/dist/core/src/filters/kinds/period.d.ts

@@ -0,0 +1,4 @@
+/** 상대 기간 토큰 (`thisMonth` …) — 백엔드 `period.py` 와 1:1 */
+export type PeriodFilterValue = string;
+/** 기간 토큰만 고르는 날짜 컬럼 — `date` kind 의 `inPeriod` 하나를 떼어 낸 것 */
+export declare const periodKind: import("../..").FilterKind<"period", string, "inPeriod", unknown>;

package/dist/core/src/filters/kinds/period.js

@@ -0,0 +1,17 @@
+import { defineFilterKind } from "../kind";
+import { matchInPeriod, PERIOD_TOKENS } from "../date";
+import { describeScalar } from "../describe";
+/** 기간 토큰만 고르는 날짜 컬럼 — `date` kind 의 `inPeriod` 하나를 떼어 낸 것 */
+export const periodKind = defineFilterKind({
+    id: "period",
+    dataKind: "date",
+    variant: "date",
+    operators: {
+        inPeriod: {
+            client: (cell, value, ctx) => matchInPeriod(cell, value, ctx.now),
+            describe: (value, ctx) => ctx.labels.periods?.[value] ?? describeScalar(value, ctx),
+        },
+    },
+    defaultOperator: "inPeriod",
+    isEmpty: (value) => !value || !PERIOD_TOKENS.includes(String(value)),
+});

package/dist/core/src/filters/kinds/relation.d.ts

@@ -0,0 +1,5 @@
+import type { RelationOperator } from "../../types/operators";
+import { type RelationFilterValue } from "../relation";
+/** `{ groups }` · `hasChild`/`hasNotChild` 는 방향 boolean */
+export type RelationKindValue = RelationFilterValue | boolean;
+export declare const relationKind: import("../..").FilterKind<"relation", RelationKindValue, RelationOperator, unknown>;

package/dist/core/src/filters/kinds/relation.js

@@ -0,0 +1,17 @@
+import { RELATION_OPERATORS } from "../../types/operators";
+import { defineFilterKind, operatorTable } from "../kind";
+import { matchRelation } from "../relation";
+import { describeRelation } from "../describe";
+import { isUnsetFilterValue } from "../../utils/getValue";
+export const relationKind = defineFilterKind({
+    id: "relation",
+    dataKind: "relation",
+    variant: "relation",
+    operators: operatorTable(RELATION_OPERATORS, (op) => ({
+        client: (_cell, value, ctx) => matchRelation(ctx.row, ctx.columnId, value, op),
+        describe: (value, ctx) => describeRelation(value, ctx),
+        valueless: op === "hasChild" || op === "hasNotChild",
+    })),
+    defaultOperator: "hasAny",
+    isEmpty: isUnsetFilterValue,
+});

package/dist/core/src/filters/kinds/schedule.d.ts

@@ -0,0 +1,5 @@
+import type { ScheduleOperator } from "../../types/operators";
+import { type ScheduleContainsValue, type ScheduleOverlapsValue } from "../schedule";
+export type ScheduleFilterValue = ScheduleContainsValue | ScheduleOverlapsValue;
+/** 예정/실제 기간을 OR 로 보는 일정 통합 컬럼 — 값 객체는 URL·프리셋에 그대로 실린다 */
+export declare const scheduleKind: import("../..").FilterKind<"schedule", ScheduleFilterValue, ScheduleOperator, unknown>;

package/dist/core/src/filters/kinds/schedule.js

@@ -0,0 +1,16 @@
+import { SCHEDULE_OPERATORS } from "../../types/operators";
+import { defineFilterKind, operatorTable } from "../kind";
+import { matchSchedule } from "../schedule";
+import { describeSchedule } from "../describe";
+import { isUnsetFilterValue } from "../../utils/getValue";
+/** 예정/실제 기간을 OR 로 보는 일정 통합 컬럼 — 값 객체는 URL·프리셋에 그대로 실린다 */
+export const scheduleKind = defineFilterKind({
+    id: "schedule",
+    variant: "schedule",
+    operators: operatorTable(SCHEDULE_OPERATORS, (op) => ({
+        client: (_cell, value, ctx) => matchSchedule(ctx.row, value, op),
+        describe: (value, ctx) => describeSchedule(value, ctx),
+    })),
+    defaultOperator: "scheduleContains",
+    isEmpty: isUnsetFilterValue,
+});

package/dist/core/src/filters/kinds/text.d.ts

@@ -0,0 +1,4 @@
+import type { TextOperator } from "../../types/operators";
+/** 문자열 하나(논리식 포함). `empty` 계열은 방향 boolean */
+export type TextFilterValue = string | boolean;
+export declare const textKind: import("../..").FilterKind<"text", TextFilterValue, TextOperator, unknown>;

package/dist/core/src/filters/kinds/text.js

@@ -0,0 +1,18 @@
+import { TEXT_OPERATORS } from "../../types/operators";
+import { defineFilterKind, operatorTable } from "../kind";
+import { matchText } from "../text";
+import { describeScalar } from "../describe";
+import { isUnsetFilterValue } from "../../utils/getValue";
+export const textKind = defineFilterKind({
+    id: "text",
+    dataKind: "text",
+    variant: "text",
+    operators: operatorTable(TEXT_OPERATORS, (op) => ({
+        client: (cell, value) => matchText(cell, value, op),
+        describe: (value, ctx) => describeScalar(value, ctx),
+        valueless: op === "empty" || op === "notEmpty",
+    })),
+    defaultOperator: "fuzzy",
+    offered: ["fuzzy", "equals", "empty"],
+    isEmpty: isUnsetFilterValue,
+});

package/dist/core/src/filters/linear.d.ts

@@ -0,0 +1,33 @@
+/** 수량 비교 연산자 — 백엔드 `LINEAR_QUANTITY_OPERATORS` 와 같다 */
+export type LinearQuantityOp = "eq" | "gte" | "lte" | "gt" | "lt";
+export type LinearOperatorName = "linearExact" | "linearContains" | "linearExists";
+export interface LinearFilterTerm {
+    /** 대상 엔티티 idx (SKU, Item 등) */
+    target_idx: number;
+    target_name?: string;
+    target_code?: string;
+    /** 수량 조건. 없으면 수량 무관 */
+    quantity?: number;
+    /** 기본값 `"gte"` */
+    quantity_op?: LinearQuantityOp;
+}
+export interface LinearFilterValue {
+    /** 관계 경로 (`"composition.items"`) */
+    relation: string;
+    mode: "exact" | "contains" | "exists";
+    terms: LinearFilterTerm[];
+    /** true = 모든 term 충족(AND), false = 하나라도(OR) */
+    match_all: boolean;
+    /** 대상 FK 컬럼명. 기본 `"idx"` */
+    target_fk?: string;
+    /** 수량 필드명. 기본 `"quantity"` */
+    quantity_field?: string;
+}
+/**
+ * 선형결합 필터 — 1:N 관계에 "무엇을 몇 개 이상" 조건을 건다.
+ *
+ * - `linearExists`: 수량 무관, 항목 존재만
+ * - `linearContains`: 수량 조건 포함
+ * - `linearExact`: 지정 항목만 정확히 (여분 항목 없음)
+ */
+export declare function matchLinear(row: unknown, columnId: string, filterValue: unknown, operator: LinearOperatorName): boolean;

package/dist/core/src/filters/linear.js

@@ -0,0 +1,65 @@
+import { getValue } from "../utils/getValue";
+function evalQuantity(itemQty, required, op = "gte") {
+    switch (op) {
+        case "eq": return itemQty === required;
+        case "gte": return itemQty >= required;
+        case "lte": return itemQty <= required;
+        case "gt": return itemQty > required;
+        case "lt": return itemQty < required;
+        default: return true;
+    }
+}
+function relationItems(row, columnId, relation) {
+    const data = getValue(row, relation || columnId);
+    return Array.isArray(data) ? data : [];
+}
+const termExists = (items, term, fk) => items.some((item) => getValue(item, fk) === term.target_idx);
+function termContains(items, term, fk, quantityField) {
+    const matched = items.find((item) => getValue(item, fk) === term.target_idx);
+    if (!matched)
+        return false;
+    if (term.quantity == null)
+        return true;
+    const qty = Number(getValue(matched, quantityField) ?? 0);
+    return evalQuantity(qty, term.quantity, term.quantity_op ?? "gte");
+}
+/**
+ * exact 모드의 항 — 서버 `_apply_exact` 는 `quantity_op` 를 **무시**하고
+ * `quantity_column == quantity` 로 판정한다. contains 의 `gte` 기본값을 재사용하면
+ * "정확히 1개" 가 "1개 이상" 이 되어 서버보다 많은 행이 나온다.
+ */
+function termExact(items, term, fk, quantityField) {
+    return items.some((item) => {
+        if (getValue(item, fk) !== term.target_idx)
+            return false;
+        if (term.quantity == null)
+            return true;
+        return Number(getValue(item, quantityField) ?? 0) === term.quantity;
+    });
+}
+/**
+ * 선형결합 필터 — 1:N 관계에 "무엇을 몇 개 이상" 조건을 건다.
+ *
+ * - `linearExists`: 수량 무관, 항목 존재만
+ * - `linearContains`: 수량 조건 포함
+ * - `linearExact`: 지정 항목만 정확히 (여분 항목 없음)
+ */
+export function matchLinear(row, columnId, filterValue, operator) {
+    const value = filterValue;
+    if (!value?.terms?.length)
+        return true;
+    const items = relationItems(row, columnId, value.relation);
+    const fk = value.target_fk || "idx";
+    const quantityField = value.quantity_field || "quantity";
+    if (operator === "linearExact") {
+        // 서버와 같은 두 조건: (1) 각 항이 정확한 수량으로 존재 (2) 항에 없는 대상이 없음.
+        // 항목 수 비교는 하지 않는다 — 서버도 (parent, target) 유니크를 전제로 개수를 세지 않는다.
+        const allMatched = value.terms.every((t) => termExact(items, t, fk, quantityField));
+        const noExtra = items.every((item) => value.terms.some((t) => t.target_idx === getValue(item, fk)));
+        return allMatched && noExtra;
+    }
+    const check = operator === "linearExists"
+        ? (t) => termExists(items, t, fk)
+        : (t) => termContains(items, t, fk, quantityField);
+    return value.match_all ? value.terms.every(check) : value.terms.some(check);
+}

package/dist/core/src/filters/list.d.ts

@@ -0,0 +1,32 @@
+/**
+ * "비어 있음"을 선택지로 쓰는 센티널 값.
+ * 백엔드 `list_filter.EMPTY_FILTER_VALUE` 와 같은 문자열이어야 한다.
+ */
+export declare const EMPTY_FILTER_VALUE = "EMPTY";
+/** "전체" 선택 — 서버가 필터를 통째로 건너뛴다 */
+export declare const ALL_FILTER_VALUE = "_ALL_SELECTED";
+/**
+ * 리스트 연산자의 값은 **항상 배열**이어야 한다.
+ *
+ * 서버 `ListFilter.apply` 는 `if "" in value` 를 문자열에도 그대로 돌려 스칼라
+ * `"NORMAL"` 을 글자 단위 리스트 `['N','O',…]` 로 쪼갠다 — enum 컬럼에서 500 이
+ * 났던 원인이다. 요청을 만드는 쪽(`TableSearch.request`)과 클라이언트 매칭이
+ * 같은 규칙으로 감싼다. 센티널(`EMPTY`, `_ALL_SELECTED`)도 배열 원소가 되어
+ * 의미가 보존된다.
+ */
+export declare function toListFilterValue(value: unknown): unknown[];
+/**
+ * 리스트 필터 — `inArray` / `notInArray` / `in` / `notIn` 계열.
+ *
+ * 백엔드 `ListFilter._build_condition_with_empty` 규칙:
+ * - 빈 문자열 값은 목록에서 제거한다 (EMPTY 센티널은 유지)
+ * - EMPTY 가 선택되면 NULL/빈 문자열도 대상에 포함 (negate 면 반대)
+ * - EMPTY 만 선택된 경우, 비어 있지 않은 값은 포함 모드에서 탈락 / 제외 모드에서 통과
+ * - 제외 모드(`~column.in_()`)는 SQL 3값 논리라 **NULL 행을 제외**한다 —
+ *   NULL 은 "목록에 없음" 이 아니라 "알 수 없음" 이다
+ */
+export declare function matchList(cellValue: unknown, filterValue: unknown, negate: boolean): boolean;
+/** 리스트 `between` — 백엔드는 닫힌 구간(`>= lo && <= hi`) */
+export declare function matchListBetween(cellValue: unknown, filterValue: unknown): boolean;
+/** `arrIncludes*` — 셀 값이 배열인 경우의 포함 판정 */
+export declare function matchArrayCell(cellValue: unknown, filterValue: unknown, mode: "some" | "all" | "one"): boolean;

package/dist/core/src/filters/list.js

@@ -0,0 +1,87 @@
+import { compareValues } from "../utils/compare";
+/**
+ * "비어 있음"을 선택지로 쓰는 센티널 값.
+ * 백엔드 `list_filter.EMPTY_FILTER_VALUE` 와 같은 문자열이어야 한다.
+ */
+export const EMPTY_FILTER_VALUE = "EMPTY";
+/** "전체" 선택 — 서버가 필터를 통째로 건너뛴다 */
+export const ALL_FILTER_VALUE = "_ALL_SELECTED";
+/**
+ * 리스트 연산자의 값은 **항상 배열**이어야 한다.
+ *
+ * 서버 `ListFilter.apply` 는 `if "" in value` 를 문자열에도 그대로 돌려 스칼라
+ * `"NORMAL"` 을 글자 단위 리스트 `['N','O',…]` 로 쪼갠다 — enum 컬럼에서 500 이
+ * 났던 원인이다. 요청을 만드는 쪽(`TableSearch.request`)과 클라이언트 매칭이
+ * 같은 규칙으로 감싼다. 센티널(`EMPTY`, `_ALL_SELECTED`)도 배열 원소가 되어
+ * 의미가 보존된다.
+ */
+export function toListFilterValue(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value === null || value === undefined)
+        return [];
+    return [value];
+}
+/**
+ * 리스트 필터 — `inArray` / `notInArray` / `in` / `notIn` 계열.
+ *
+ * 백엔드 `ListFilter._build_condition_with_empty` 규칙:
+ * - 빈 문자열 값은 목록에서 제거한다 (EMPTY 센티널은 유지)
+ * - EMPTY 가 선택되면 NULL/빈 문자열도 대상에 포함 (negate 면 반대)
+ * - EMPTY 만 선택된 경우, 비어 있지 않은 값은 포함 모드에서 탈락 / 제외 모드에서 통과
+ * - 제외 모드(`~column.in_()`)는 SQL 3값 논리라 **NULL 행을 제외**한다 —
+ *   NULL 은 "목록에 없음" 이 아니라 "알 수 없음" 이다
+ */
+export function matchList(cellValue, filterValue, negate) {
+    if (filterValue === null || filterValue === undefined)
+        return true;
+    const list = toListFilterValue(filterValue);
+    if (list.length === 0)
+        return true;
+    // 빈 문자열 제거 (EMPTY 센티널은 유지)
+    const values = list.filter((v) => v !== "");
+    // 전부 제거되면 걸 조건이 없다 — 백엔드 `_build_condition_with_empty` 도
+    // `if not conditions: return 항상 참` 으로 전행을 통과시킨다.
+    if (values.length === 0)
+        return true;
+    const includeEmpty = values.includes(EMPTY_FILTER_VALUE);
+    const actual = values.filter((v) => v !== EMPTY_FILTER_VALUE);
+    const isNull = cellValue === null || cellValue === undefined;
+    const isEmpty = isNull || cellValue === "";
+    if (negate) {
+        // notIn + EMPTY: `column IS NOT NULL AND column != ''` 가 AND 로 붙는다
+        if (includeEmpty && isEmpty)
+            return false;
+        // 실제 값이 없으면(EMPTY 만 선택) 남은 조건이 없어 통과
+        if (actual.length === 0)
+            return true;
+        // `NULL NOT IN (...)` 은 NULL → 행 제외 (빈 문자열은 값이라 비교된다)
+        if (isNull)
+            return false;
+        return !actual.some((v) => String(v) === String(cellValue));
+    }
+    // 포함 모드: NULL/빈 문자열은 EMPTY 를 골랐을 때만 통과
+    if (isEmpty)
+        return includeEmpty;
+    // EMPTY 만 선택됨 — 비어 있지 않은 값은 탈락
+    if (actual.length === 0)
+        return false;
+    return actual.some((v) => String(v) === String(cellValue));
+}
+/** 리스트 `between` — 백엔드는 닫힌 구간(`>= lo && <= hi`) */
+export function matchListBetween(cellValue, filterValue) {
+    if (!Array.isArray(filterValue) || filterValue.length !== 2)
+        return true;
+    const [lo, hi] = filterValue;
+    return compareValues(cellValue, lo) >= 0 && compareValues(cellValue, hi) <= 0;
+}
+/** `arrIncludes*` — 셀 값이 배열인 경우의 포함 판정 */
+export function matchArrayCell(cellValue, filterValue, mode) {
+    const cells = Array.isArray(cellValue) ? cellValue.map(String) : [String(cellValue)];
+    const wanted = (Array.isArray(filterValue) ? filterValue : [filterValue]).map(String);
+    if (wanted.length === 0)
+        return true;
+    if (mode === "all")
+        return wanted.every((w) => cells.includes(w));
+    return wanted.some((w) => cells.includes(w));
+}

package/dist/core/src/filters/number.d.ts

@@ -0,0 +1,17 @@
+/** 문자열 값을 숫자로 (실패 시 원본 유지 — 백엔드 `_to_number` 와 같다) */
+export declare function toNumber(value: unknown): unknown;
+/**
+ * 범위 필터 — `between`(열림) / `betweenInclusive`(닫힘) / `outsideRange`.
+ *
+ * 백엔드 `NumberFilter.apply` 의 한쪽-경계 규칙을 따른다:
+ * 하한만 있으면 `>= lo`, 상한만 있으면 `<= hi` (열림/닫힘 무관).
+ * `outsideRange` 는 두 경계가 **모두** 있어야 뜻이 정해지므로 하나라도 비면 전행 통과.
+ */
+export declare function matchRange(cellValue: unknown, filterValue: unknown, operator: "between" | "betweenInclusive" | "outsideRange"): boolean;
+/**
+ * 숫자 NULL 필터. 값이 `false` 면 방향이 뒤집힌다
+ * (텍스트 `empty` 와 같은 boolean 방향 규약).
+ */
+export declare function matchIsEmpty(cellValue: unknown, filterValue: unknown): boolean;
+/** 단일 값 비교 — 백엔드 `NumberFilter` 의 스칼라 분기 */
+export declare function matchNumber(cellValue: unknown, filterValue: unknown, operator: string): boolean;

package/dist/core/src/filters/number.js

@@ -0,0 +1,82 @@
+import { compareValues, isEmptyBound } from "../utils/compare";
+/** 문자열 값을 숫자로 (실패 시 원본 유지 — 백엔드 `_to_number` 와 같다) */
+export function toNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed === "")
+            return null;
+        const parsed = trimmed.includes(".") ? Number.parseFloat(trimmed) : Number.parseInt(trimmed, 10);
+        return Number.isNaN(parsed) ? value : parsed;
+    }
+    return value;
+}
+/**
+ * 범위 필터 — `between`(열림) / `betweenInclusive`(닫힘) / `outsideRange`.
+ *
+ * 백엔드 `NumberFilter.apply` 의 한쪽-경계 규칙을 따른다:
+ * 하한만 있으면 `>= lo`, 상한만 있으면 `<= hi` (열림/닫힘 무관).
+ * `outsideRange` 는 두 경계가 **모두** 있어야 뜻이 정해지므로 하나라도 비면 전행 통과.
+ */
+export function matchRange(cellValue, filterValue, operator) {
+    if (!Array.isArray(filterValue))
+        return true;
+    const [rawLo, rawHi] = filterValue;
+    const loEmpty = isEmptyBound(rawLo);
+    const hiEmpty = isEmptyBound(rawHi);
+    if (operator === "outsideRange") {
+        if (loEmpty || hiEmpty)
+            return true;
+    }
+    else if (loEmpty && hiEmpty) {
+        return true;
+    }
+    if (cellValue === null || cellValue === undefined || cellValue === "")
+        return false;
+    if (operator === "outsideRange") {
+        return compareValues(cellValue, rawLo) < 0 || compareValues(cellValue, rawHi) > 0;
+    }
+    // 한쪽만 있으면 열림/닫힘 구분 없이 포함 비교 (백엔드와 동일)
+    if (loEmpty || hiEmpty) {
+        if (!loEmpty)
+            return compareValues(cellValue, rawLo) >= 0;
+        return compareValues(cellValue, rawHi) <= 0;
+    }
+    if (operator === "between") {
+        return compareValues(cellValue, rawLo) > 0 && compareValues(cellValue, rawHi) < 0;
+    }
+    return compareValues(cellValue, rawLo) >= 0 && compareValues(cellValue, rawHi) <= 0;
+}
+/**
+ * 숫자 NULL 필터. 값이 `false` 면 방향이 뒤집힌다
+ * (텍스트 `empty` 와 같은 boolean 방향 규약).
+ */
+export function matchIsEmpty(cellValue, filterValue) {
+    const isNull = cellValue === null || cellValue === undefined;
+    return filterValue === false ? !isNull : isNull;
+}
+/** 단일 값 비교 — 백엔드 `NumberFilter` 의 스칼라 분기 */
+export function matchNumber(cellValue, filterValue, operator) {
+    if (operator === "isEmpty")
+        return matchIsEmpty(cellValue, filterValue);
+    if (operator === "between" || operator === "betweenInclusive" || operator === "outsideRange") {
+        return matchRange(cellValue, filterValue, operator);
+    }
+    // 리스트가 오면 첫 값을 쓴다 (백엔드와 동일)
+    const raw = Array.isArray(filterValue) ? filterValue[0] : filterValue;
+    if (cellValue === null || cellValue === undefined)
+        return false;
+    const cmp = compareValues(cellValue, raw);
+    switch (operator) {
+        case "notEquals": return cmp !== 0;
+        case "lessThan": return cmp < 0;
+        case "lessThanOrEqualTo": return cmp <= 0;
+        case "greaterThan": return cmp > 0;
+        case "greaterThanOrEqualTo": return cmp >= 0;
+        case "equals":
+        default: return cmp === 0;
+    }
+}

package/dist/core/src/filters/registry.d.ts

@@ -0,0 +1,23 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDef } from "../types/column";
+import type { FilterOperator } from "../types/operators";
+/**
+ * 필터를 고르는 기준이 되는 데이터 종류.
+ * 백엔드는 SQLAlchemy 컬럼 타입(`path_info.column_type`)으로 고르는데,
+ * 클라이언트의 대응물은 `meta.dataType` 이고 없으면 `filter.variant` 로 유추한다.
+ */
+export type DataKind = "number" | "date" | "boolean" | "relation" | "text";
+export declare function isVirtualColumn<T extends RowData>(column?: TableColumnDef<T>): boolean;
+export declare function resolveDataKind<T extends RowData>(column?: TableColumnDef<T>): DataKind;
+export interface MatchContext {
+    /** 상대 기간(`inPeriod`) 해석 기준 시각. 테스트에서 고정한다 */
+    now?: Date;
+}
+/**
+ * 컬럼 필터 하나를 행에 적용한다.
+ *
+ * 분기 순서는 백엔드 `_apply_filter_by_type` 을 그대로 따른다 —
+ * 순서가 어긋나면 같은 요청이 client/server 에서 다른 결과를 낸다.
+ * (예: `between` 은 숫자·날짜·리스트 셋 다 지원하므로 컬럼 종류가 먼저 결정돼야 한다)
+ */
+export declare function matchColumnFilter<T extends RowData>(row: unknown, columnId: string, filterValue: unknown, operator: FilterOperator, column?: TableColumnDef<T>, ctx?: MatchContext): boolean;