kokotable 0.95.0

package/dist/core/src/types/filter.d.ts

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+import type { FilterOperator, FilterVariant } from "./operators";
+import type { ColumnMeta } from "./column";
+import type { AnyFilterKind, CheckedFilterSpec, FilterKindRef, RegisteredFilterSpec, UnregisteredFilterSpec } from "./filterKind";
+export * from "./filterKind";
+/**
+ * 필터 입력 하나가 그려지는 데 필요한 전부.
+ *
+ * 여기에 **table 도 column 인스턴스도 없다**. 그래서 이 계약으로 그린 필터는
+ * 사이드패널·상단바·모달·카드 화면 어디서든 같은 코드로 동작한다.
+ */
+export interface FilterField<V = unknown> {
+    /** 컬럼 id (= 서버 요청의 필터 키) */
+    id: string;
+    /** 필터 라벨. 컬럼 헤더에서 옴 */
+    header: ReactNode;
+    /** 입력 UI 종류. kind 가 있으면 `filter.variant ?? kind.variant` (editor 폴백 선택용) */
+    variant: FilterVariant;
+    /** 컬럼이 선언한 필터 kind (해석된 객체). 렌더러는 `kind.editor` 를 폴백으로 쓴다 */
+    kind?: AnyFilterKind;
+    meta?: ColumnMeta;
+    value: V | undefined;
+    onChange: (value: V | undefined) => void;
+    operator: FilterOperator;
+    onOperatorChange: (operator: FilterOperator) => void;
+    /** 이 컬럼이 허용하는 연산자. 길이 1 이하면 연산자 선택 UI 를 숨긴다 */
+    operatorOptions: readonly FilterOperator[];
+    /**
+     * 값을 즉시 조회에 반영한다 (검색 버튼을 거치지 않는 필터용).
+     * 미지정이면 draft 에만 쌓이고 `TableSearch.apply()` 를 기다린다.
+     */
+    apply?: () => void;
+    /** 컬럼이 선언한 커스텀 렌더러 (`FilterSpec.render`) */
+    render?: FilterRender<V>;
+    /** "상세 조건" 접이식 그룹으로 내릴 필드인가 (`FilterSpec.detail`) */
+    detail?: boolean;
+    disabled?: boolean;
+}
+export type FilterRender<V = unknown> = (field: FilterField<V>) => ReactNode;
+/**
+ * 필터 UI 를 그리는 컴포넌트가 의존하는 계약은 `./sources` 로 옮겼다.
+ * 화면을 필터/콘텐츠/페이지네이션 세 구역으로 나누는 계약이 한자리에 모여 있어야
+ * "어느 구역이 무엇에 의존하는가"가 한눈에 보인다.
+ */
+export type { FilterSource, ContentSource, ContentStatus, PaginationSource, PaginationInfo, SelectionSource, } from "./sources";
+/**
+ * 컬럼 정의에 붙는 필터 선언.
+ *
+ * 기존에 `filterFn` + `columnFilterModeOptions` + `Filter` 렌더 prop +
+ * `meta.hideFilter` 로 흩어져 있던 것을 한 곳으로 모은 것이다.
+ */
+export interface FilterSpec<V = unknown> {
+    /**
+     * 필터 kind — 정의 객체(`defineFilterKind`) 또는 등록된 문자열 id.
+     * 있으면 연산자 후보·판정·직렬화·문구·codec 을 kind 가 결정하고, 없으면 `variant` 경로다.
+     * 이 타입은 **읽기용(느슨한)** 모양이다. 컬럼 정의(`TableColumnDef.filter`)는 `FilterSpecInput` 으로
+     * kind 별로 좁혀진다.
+     */
+    kind?: FilterKindRef;
+    variant?: FilterVariant;
+    /** 미지정 시 `OPERATORS_BY_VARIANT[variant]` */
+    operators?: readonly FilterOperator[];
+    /** 미지정 시 `operators[0]` */
+    defaultOperator?: FilterOperator;
+    /** 커스텀 입력. 지정하면 variant 기본 렌더러 대신 이것이 쓰인다 */
+    render?: FilterRender<V>;
+    /** 필터 UI 에서 완전히 제외 (기존 `meta.hideFilter` / `meta.forceHidden`) */
+    hidden?: boolean;
+    /** "상세 조건" 접이식 그룹으로 내림 (기존 `meta.isVisible === false` 파생) */
+    detail?: boolean;
+    /** 값 변경 즉시 조회 — 검색 버튼을 기다리지 않는다 */
+    applyOnChange?: boolean;
+    /**
+     * `applyOnChange` 의 지연(ms). 마지막 입력 뒤 이 시간이 지나야 `apply()` 가 나간다.
+     * 컬럼 단위 값이 `TableSearchOptions.debounceMs` 보다 우선한다. 미지정·0 이면 즉시.
+     */
+    debounceMs?: number;
+    /** 초기값 */
+    defaultValue?: V;
+}
+/**
+ * 컬럼 정의의 `filter` 자리 — **쓰기용(좁혀진)** 모양.
+ *
+ * - kind 없음: 지금의 variant 경로(`FilterSpec<V>`, 연산자는 백엔드 목록 `FilterOperator`)
+ * - 등록된 kind(내장·augmentation): `FilterSpecOf<K>` — 연산자·기본값이 kind 로 좁혀진다
+ * - 등록되지 않은 kind 객체: 인라인이면 연산자·기본값 없이 kind 만 (`UnregisteredFilterSpec`),
+ *   `filterSpec(kind, { … })` 를 거치면 제네릭 자리에서 검사된 뒤 들어간다 (`CheckedFilterSpec`)
+ *
+ * 필터 값 타입은 kind 가 정하고 셀 값 `V` 와 독립이다. `V` 는 variant 경로의 `render`/`defaultValue`
+ * 편의 타입으로만 남는다.
+ */
+export type FilterSpecInput<V = unknown> = (FilterSpec<V> & {
+    kind?: undefined;
+}) | RegisteredFilterSpec | UnregisteredFilterSpec | CheckedFilterSpec;

package/dist/core/src/types/filter.js

@@ -0,0 +1 @@
+export * from "./filterKind";

package/dist/core/src/types/filterKind.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 필터 kind — 확장 계약 (docs/extension-design.md 1절).
+ *
+ * 컬럼의 `filter.kind` 자리에 넣는 **정의 객체**다. 의미 부분(판정·직렬화·문구·codec)은
+ * core 가, 표시 부분(editor·chip)은 mui 가 같은 id 로 합친다(`withEditor`).
+ * 내장 kind(text·number·date·…)도 같은 `defineFilterKind` 로 정의한다(dogfooding).
+ */
+import type { ReactNode } from "react";
+import type { FilterOperator, FilterVariant } from "./operators";
+import type { FilterRender } from "./filter";
+import type { SelectOption } from "./column";
+/** `operators[op].client` 가 받는 행 문맥 */
+export interface FilterClientContext<TRow = unknown> {
+    row: TRow;
+    columnId: string;
+    /** 상대 기간(`inPeriod`) 기준 시각 — 테스트에서 고정한다 */
+    now?: Date;
+}
+/**
+ * describe 가 쓰는 문구. core 는 React·Provider 를 모르므로 **문자열 묶음**만 받는다
+ * (설계 문서의 `labels: Labels` 자리 — mui 가 자기 `labels` 에서 이 모양으로 뽑아 넘긴다).
+ */
+export interface FilterDescribeLabels {
+    /** 값이 비어 있음 — 기본 "(없음)" */
+    empty: string;
+    /** 값 없는 연산자의 값 칸 — 기본 "-" */
+    valueless: string;
+    yes: string;
+    no: string;
+    /** "외 N개" */
+    more: (count: number) => string;
+    /** "N개 그룹 · 조건 M개" */
+    relationGroups: (groups: number, conditions: number) => string;
+    matchAll: string;
+    matchAny: string;
+    /** 연산자 라벨 (문구에 연산자를 섞는 kind 용) */
+    operators?: Partial<Record<string, string>>;
+    /** 상대 기간 토큰 라벨 (`period` kind) */
+    periods?: Partial<Record<string, string>>;
+}
+export interface FilterDescribeContext {
+    header: string;
+    labels: FilterDescribeLabels;
+    /** 선택지 라벨 — enum/commonCode 류가 값 대신 라벨을 보일 때 (`meta.selectOptions`) */
+    options?: readonly SelectOption[];
+    /** 관계 컬럼의 하위 컬럼 라벨 (`meta.relationColumns`) */
+    relationColumns?: ReadonlyArray<{
+        key: string;
+        label: string;
+    }>;
+    /** 배열 값이 이보다 길면 앞부분만 (기본 5) */
+    maxListItems?: number;
+}
+export interface FilterOperatorDef<TValue, TRow = unknown> {
+    /** 클라이언트 모드 판정. 서버 QueryBuilder 와 같은 의미여야 한다 */
+    client(cell: unknown, value: TValue, ctx: FilterClientContext<TRow>): boolean;
+    /** 요청(`columnFilters[].value`)에 실을 값. 미지정 시 그대로 */
+    serialize?(value: TValue): unknown;
+    /**
+     * 사람이 읽는 문구 — 필터 상태 모달·칩·AI 컨텍스트.
+     * 값이 비어 있거나(`isEmpty`) 값 없는 연산자면 `describeFilter` 가 먼저 처리하므로
+     * 여기는 **값이 있을 때만** 불린다.
+     */
+    describe(value: TValue, ctx: FilterDescribeContext): string;
+    /** 값 없는 연산자(empty/hasChild 류) — 값은 `true` 로 실리고 입력창을 그리지 않는다 */
+    valueless?: boolean;
+    /** 서버 연산자 이름이 다르면 매핑 (기본 = 키) */
+    wire?: FilterOperator;
+}
+export type FilterDataKind = "text" | "number" | "date" | "boolean" | "relation";
+export interface FilterKindCodec<TValue> {
+    encode(value: TValue): unknown;
+    decode(raw: unknown): TValue | undefined;
+}
+export interface FilterKindDef<Id extends string, TValue, TOp extends string, TRow = unknown> {
+    id: Id;
+    operators: Record<TOp, FilterOperatorDef<TValue, TRow>>;
+    defaultOperator: TOp;
+    /**
+     * 드롭다운에 **노출**할 축약 목록 (`OFFERED_OPERATORS` 대응). 미지정 시 `operators` 전부.
+     * 첫 항목이 기본 연산자가 아니어도 된다 — 기본은 `defaultOperator` 다.
+     */
+    offered?: readonly TOp[];
+    /** URL·프리셋 직렬화 (JSON 안전 값으로). 미지정 시 그대로 */
+    codec?: FilterKindCodec<TValue>;
+    /** 비어 있음 판정 — 미입력 필터를 요청에서 뺄 때. 미지정 시 `isUnsetFilterValue` */
+    isEmpty?(value: TValue | undefined): boolean;
+    /** 서버 `column_type` 대응 — `resolveDataKind` 분기용 */
+    dataKind?: FilterDataKind;
+    /**
+     * 기본 입력 UI 힌트 — `editor` 가 없을 때 mui 가 variant 별 기본 입력을 고른다.
+     * 미지정 시 `dataKind` 에서 유추, 그것도 없으면 `"custom"`(입력을 그리지 않는다).
+     */
+    variant?: FilterVariant;
+    /** 렌더러가 채우는 자리 (core 는 타입만 안다) — mui `withEditor(kind, { editor })` */
+    editor?: FilterRender<TValue>;
+    /** 메서드 문법 — Provider 의 느슨한 `(value: unknown, operator: string)` 자리에 그대로 들어간다 */
+    chip?(value: TValue, operator: TOp): ReactNode;
+}
+/**
+ * `defineFilterKind` 의 **입력** 모양 — `FilterKindDef` 와 같은 필드지만 추론 위치를 고정한다.
+ * `TOp` 는 `operators` 의 키에서만, `TValue` 는 `operators[*].client/describe` 의 값 인자에서만 추론되고
+ * 나머지(`defaultOperator`·`offered`·`isEmpty`·`codec`·`editor`·`chip`)는 `NoInfer` 로 **검사만** 받는다.
+ * (그렇지 않으면 `defaultOperator: "a"` 가 TOp 를 `"a"` 로, `isEmpty: isUnsetFilterValue` 가 TValue 를 `unknown` 으로 끌어내린다.)
+ */
+export interface FilterKindInput<Id extends string, TValue, TOp extends string, TRow = unknown> {
+    id: Id;
+    operators: Record<TOp, FilterOperatorDef<TValue, TRow>>;
+    defaultOperator: NoInfer<TOp>;
+    offered?: readonly NoInfer<TOp>[];
+    codec?: FilterKindCodec<NoInfer<TValue>>;
+    isEmpty?(value: NoInfer<TValue> | undefined): boolean;
+    dataKind?: FilterDataKind;
+    variant?: FilterVariant;
+    editor?: FilterRender<NoInfer<TValue>>;
+    chip?(value: NoInfer<TValue>, operator: NoInfer<TOp>): ReactNode;
+}
+/** `defineFilterKind` 가 돌려주는 브랜드된 정의 객체 (`as const` 불필요) */
+export interface FilterKind<Id extends string = string, TValue = unknown, TOp extends string = string, TRow = unknown> extends FilterKindDef<Id, TValue, TOp, TRow> {
+    readonly __filterKind: true;
+    /** `operators` 의 키 (선언 순서) */
+    readonly operatorNames: readonly TOp[];
+}
+export type AnyFilterKind = FilterKind<any, any, any, any>;
+export type FilterKindValue<K> = K extends FilterKind<any, infer V, any, any> ? V : never;
+export type FilterKindOperator<K> = K extends FilterKind<any, any, infer O, any> ? O : never;
+export type FilterKindId<K> = K extends FilterKind<infer Id, any, any, any> ? Id : never;
+/**
+ * 문자열 id → kind 타입 맵. 소비자가 module augmentation 으로 병합한다:
+ *
+ * ```ts
+ * declare module "kokotable" { interface FilterKindRegistry { money: typeof moneyKind } }
+ * // 이후 filter: { kind: "money", defaultOperator: "gte" } — 틀리면 컴파일 에러
+ * ```
+ * 내장 kind 는 `BuiltinFilterKindMap` 으로 미리 들어 있다.
+ */
+export interface FilterKindRegistry extends BuiltinFilterKindMap {
+}
+/** 내장 kind 맵 — `filters/kinds/index.ts` 가 채운다 (타입만 순환 참조) */
+export interface BuiltinFilterKindMap {
+}
+/** 컬럼 `filter.kind` 자리에 올 수 있는 것 — kind 객체 또는 등록된 문자열 id */
+export type FilterKindRef = AnyFilterKind | (keyof FilterKindRegistry & string);
+/** kind 와 무관한 공통 항목 */
+export interface FilterSpecCommon<V = unknown> {
+    /** 커스텀 입력. 지정하면 kind.editor·variant 기본 렌더러보다 우선한다 */
+    render?: FilterRender<V>;
+    /** 필터 UI 에서 완전히 제외 */
+    hidden?: boolean;
+    /** "상세 조건" 접이식 그룹으로 내림 */
+    detail?: boolean;
+    /** 값 변경 즉시 조회 */
+    applyOnChange?: boolean;
+    /** `applyOnChange` 의 지연(ms) */
+    debounceMs?: number;
+    /**
+     * 입력 UI 힌트. kind 가 있으면 **editor 선택에만** 쓰인다 (enum kind 의 select/multiSelect 구분 등).
+     * 없으면 지금의 variant 경로(연산자 후보·판정의 근거).
+     */
+    variant?: FilterVariant;
+}
+/** 컬럼 정의의 filter 자리 — kind 객체를 넣으면 value/operator 가 좁혀진다 */
+export interface FilterSpecOf<K extends AnyFilterKind> extends FilterSpecCommon<FilterKindValue<K>> {
+    kind: K;
+    operators?: readonly FilterKindOperator<K>[];
+    defaultOperator?: FilterKindOperator<K>;
+    defaultValue?: FilterKindValue<K>;
+}
+/** 등록된 문자열 id 로 좁히는 버전 (`FilterKindRegistry` 병합 후) */
+export type FilterSpecOfId<Id extends keyof FilterKindRegistry> = FilterKindRegistry[Id] extends AnyFilterKind ? FilterSpecOf<FilterKindRegistry[Id]> : never;
+/**
+ * 등록된 kind(내장 + augmentation) 하나하나에 대한 좁혀진 spec 의 유니온.
+ * `kind` 는 객체(`numberKind`)로도 문자열(`"number"`)로도 쓸 수 있다.
+ */
+export type RegisteredFilterSpec = {
+    [Id in keyof FilterKindRegistry & string]: FilterKindRegistry[Id] extends AnyFilterKind ? Omit<FilterSpecOf<FilterKindRegistry[Id]>, "kind"> & {
+        kind: FilterKindRegistry[Id] | Id;
+    } : never;
+}[keyof FilterKindRegistry & string];
+/**
+ * 등록되지 않은 kind 객체를 **인라인**으로 쓸 때 — 좁힐 근거가 없으므로 연산자·기본값을 여기서 줄 수 없다.
+ * 연산자·기본값을 주려면 (1) `FilterKindRegistry` 를 병합하거나 (2) `filterSpec(kind, spec)` /
+ * `ColumnBuilder.setFilterKind(kind, spec)` 처럼 kind 가 제네릭 인자로 잡히는 자리를 쓴다(`CheckedFilterSpec`).
+ * (TS 는 객체 리터럴 안에서 한 속성의 타입을 다른 속성의 값으로 좁히지 못한다 — 등록이 그 대체다.)
+ */
+export interface UnregisteredFilterSpec extends FilterSpecCommon<any> {
+    kind: AnyFilterKind;
+    operators?: never;
+    defaultOperator?: never;
+    defaultValue?: never;
+}
+declare const FILTER_SPEC_CHECKED: unique symbol;
+/**
+ * `filterSpec(kind, spec)` 이 돌려주는 모양 — 제네릭 자리에서 이미 검사됐으므로 느슨하게 들어간다.
+ * 브랜드 심볼은 타입에만 있다(런타임 속성 없음). 인라인 리터럴은 이 멤버에 맞지 않는다.
+ */
+export interface CheckedFilterSpec extends FilterSpecCommon<any> {
+    readonly [FILTER_SPEC_CHECKED]: true;
+    kind: AnyFilterKind;
+    operators?: readonly string[];
+    defaultOperator?: string;
+    defaultValue?: unknown;
+}
+export {};

package/dist/core/src/types/filterKind.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/types/grouping.d.ts

@@ -0,0 +1,80 @@
+import type { AggregateResult } from "../client/aggregate";
+/** 그룹 경로 — `[{ key: "department", value: "영업부" }, ...]` */
+export type GroupPath = Array<{
+    key: string;
+    value: unknown;
+}>;
+/**
+ * 그룹 트리 노드 — **클라이언트 트리**다.
+ * 서버 응답의 `GroupNode`(`types/request.ts`)는 평평한 한 레벨 요약이라 다른 타입이다.
+ */
+export interface GroupTreeNode<T> {
+    /** 이 노드를 만든 컬럼 */
+    groupKey: string;
+    groupValue: unknown;
+    /** 표시용 라벨 (선택지가 있는 컬럼) */
+    label?: string;
+    /** 하위 말단 행 총 개수 */
+    count: number;
+    aggregates?: AggregateResult;
+    /** 하위 그룹 (마지막 레벨이면 없음) */
+    children?: Array<GroupTreeNode<T>>;
+    /** 마지막 레벨의 말단 행 */
+    rows?: T[];
+    /** 루트부터 이 노드까지의 경로 */
+    path: GroupPath;
+    depth: number;
+    /** 하위를 더 받을 수 있는가. 클라이언트 그룹핑에서는 항상 undefined */
+    hasMore?: boolean;
+    /** 지금까지 받은 하위 개수 */
+    loadedCount?: number;
+    /** 하위 전체 개수 (서버 meta.total_count) */
+    totalCount?: number;
+    /** 이 경로의 하위를 받는 중인가 — 행 단위 로딩 표시 */
+    isPending?: boolean;
+}
+/**
+ * 가상화용 평탄화 항목.
+ *
+ * `parentIndex` 는 직전 조상 그룹의 평탄 인덱스다 — sticky 헤더가 조상을
+ * 역추적할 때 O(depth) 로 끝내기 위해 평탄화 시점에 기록한다.
+ */
+export type FlatItem<T> = {
+    type: "group";
+    node: GroupTreeNode<T>;
+    depth: number;
+    index: number;
+    parentIndex?: number;
+} | {
+    type: "leaf";
+    row: T;
+    depth: number;
+    index: number;
+    parentIndex?: number;
+    leafIndex: number;
+}
+/** 서버 그룹핑의 "더 보기" 행 — 하위를 페이지 단위로 받아 온다 */
+ | {
+    type: "loadMore";
+    path: GroupPath;
+    depth: number;
+    index: number;
+    parentIndex?: number;
+    loaded: number;
+    total?: number;
+    isPending?: boolean;
+};
+/** 경로를 문자열 키로 — 확장 상태의 Set 키 */
+export declare function pathKey(path: GroupPath): string;
+export interface ExpandState {
+    isExpanded(path: GroupPath): boolean;
+    toggle(path: GroupPath): void;
+    expandAll(): void;
+    collapseAll(): void;
+    /** 지정 깊이까지만 펼친다 (0 = 전부 접기) */
+    expandToDepth(depth: number): void;
+    /** 현재 펼침 깊이 — 단계 펼치기 버튼이 다음 단계를 계산할 때 쓴다 */
+    readonly depth: number;
+    readonly maxDepth: number;
+    readonly canExpand: boolean;
+}

package/dist/core/src/types/grouping.js

@@ -0,0 +1,4 @@
+/** 경로를 문자열 키로 — 확장 상태의 Set 키 */
+export function pathKey(path) {
+    return path.map((step) => `${step.key}=${String(step.value)}`).join("/");
+}

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

@@ -0,0 +1,8 @@
+export * from "./operators";
+export * from "./request";
+export * from "./column";
+export * from "./sources";
+export * from "./filter";
+export * from "./search";
+export * from "./data";
+export * from "./table";

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

@@ -0,0 +1,8 @@
+export * from "./operators";
+export * from "./request";
+export * from "./column";
+export * from "./sources";
+export * from "./filter";
+export * from "./search";
+export * from "./data";
+export * from "./table";

package/dist/core/src/types/operators.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 필터 연산자 — 백엔드 `QueryBuilder/types.py` 와 1:1 대응한다.
+ *
+ * 이 목록이 프론트/백 공통 계약의 전부다. 여기 없는 문자열은 서버가
+ * 기본 연산자로 강등하므로(TextFilter → "contains", NumberFilter → "equals"),
+ * 새 연산자는 반드시 양쪽을 같이 늘린다.
+ */
+export type TextOperator = "equals" | "notEquals" | "lessThan" | "lessThanOrEqualTo" | "greaterThan" | "greaterThanOrEqualTo" | "contains" | "notContains" | "startsWith" | "endsWith" | "fuzzy" | "empty" | "notEmpty";
+export type NumberOperator = "equals" | "notEquals" | "lessThan" | "lessThanOrEqualTo" | "greaterThan" | "greaterThanOrEqualTo" | "between" | "betweenInclusive" | "outsideRange" | "isEmpty";
+export type DateOperator = "equals" | "notEquals" | "lessThan" | "lessThanOrEqualTo" | "greaterThan" | "greaterThanOrEqualTo" | "between" | "betweenInclusive" | "dateBetween" | "inPeriod";
+export type ListOperator = "in" | "notIn" | "between" | "arrIncludes" | "arrIncludesSome" | "arrIncludesAll" | "inArray" | "inArrayFilter" | "notInArray";
+export type BooleanOperator = "equals";
+export type RelationOperator = "hasAny" | "hasAll" | "hasChild" | "hasNotChild";
+export type LinearOperator = "linearExact" | "linearContains" | "linearExists";
+export type ScheduleOperator = "scheduleContains" | "scheduleOverlaps";
+/** 서버가 필터를 건너뛰는 연산자 — 값 해석을 호출부가 전담한다 */
+export type PassOperator = "auto" | "custom";
+export type FilterOperator = TextOperator | NumberOperator | DateOperator | ListOperator | BooleanOperator | RelationOperator | LinearOperator | ScheduleOperator | PassOperator;
+/** 필터 입력 UI 의 종류. 연산자 기본 후보를 고르는 기준이기도 하다. */
+export type FilterVariant = "text" | "number" | "date" | "datetime" | "boolean" | "select" | "multiSelect" | "relation" | "linear" | "schedule" | "custom";
+export declare const TEXT_OPERATORS: readonly ["equals", "notEquals", "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo", "contains", "notContains", "startsWith", "endsWith", "fuzzy", "empty", "notEmpty"];
+export declare const NUMBER_OPERATORS: readonly ["equals", "notEquals", "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo", "between", "betweenInclusive", "outsideRange", "isEmpty"];
+export declare const DATE_OPERATORS: readonly ["equals", "notEquals", "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo", "between", "betweenInclusive", "dateBetween", "inPeriod"];
+export declare const LIST_OPERATORS: readonly ["in", "notIn", "between", "arrIncludes", "arrIncludesSome", "arrIncludesAll", "inArray", "inArrayFilter", "notInArray"];
+export declare const BOOLEAN_OPERATORS: readonly ["equals"];
+export declare const RELATION_OPERATORS: readonly ["hasAny", "hasAll", "hasChild", "hasNotChild"];
+export declare const LINEAR_OPERATORS: readonly ["linearExact", "linearContains", "linearExists"];
+export declare const SCHEDULE_OPERATORS: readonly ["scheduleContains", "scheduleOverlaps"];
+/**
+ * variant → 연산자 후보. `FilterSpec.operators` 미지정 시의 기본값이다.
+ *
+ * 위의 `*_OPERATORS` 는 **백엔드 검증 목록**(`types.py` 와 같은 순서)이고,
+ * 이 표는 **UI 노출 순서**다. 둘을 같은 배열로 쓰면 안 된다 —
+ * 검증 목록의 첫 항목은 아무 의미가 없는데, 이 표는 **첫 항목이 기본 연산자**이기
+ * 때문이다 (기존 `columnFilterModeOptions[0]` 규칙 계승). 실제로 그렇게 묶었더니
+ * 텍스트 컬럼의 기본이 `equals` 가 되어, 기존 기본값 `fuzzy` 로 걸리던
+ * "듀벨" ↔ "듀 벨 상사" 매칭이 조용히 깨졌다.
+ */
+export declare const OPERATORS_BY_VARIANT: Record<FilterVariant, readonly FilterOperator[]>;
+/**
+ * variant 별 **노출 연산자** — 컬럼을 만들 때 드롭다운에 실제로 띄우는 축약본.
+ * `OPERATORS_BY_VARIANT` 는 그 variant 가 지원하는 전체 목록(첫 항목 = 기본값)이고,
+ * 이쪽은 기존 `getColumnFilterModeOptions` 와 같은 짧은 목록이다. 전부 띄우면
+ * 선택지가 13개가 된다. 없는 variant 는 전체 목록을 그대로 쓴다.
+ */
+export declare const OFFERED_OPERATORS: Partial<Record<FilterVariant, readonly FilterOperator[]>>;
+export declare function offeredOperators(variant: FilterVariant): readonly FilterOperator[];
+/**
+ * 값을 소비하지 않는 연산자 — 입력창을 그리지 않는다 (백엔드 VALUELESS_OPERATORS 대응).
+ *
+ * `hasChild`/`hasNotChild` 도 여기 든다. 서버는 `value None` 인 필터를 통째로
+ * 건너뛰므로 항목은 있어야 하고 값은 `true` 로 실린다 — 목록에서 빠져 있으면
+ * `useTableSearch.normalizeFilters` 가 "미입력" 으로 지워 훅 경로에서 걸리지 않았다.
+ */
+export declare const VALUELESS_OPERATORS: readonly ["empty", "notEmpty", "isEmpty", "hasChild", "hasNotChild"];
+export type ValuelessOperator = (typeof VALUELESS_OPERATORS)[number];
+export declare function isValuelessOperator(op: FilterOperator): op is ValuelessOperator;
+/**
+ * 값이 **목록**인 리스트 연산자 — `between` 은 `[lo, hi]` 쌍이라 제외한다.
+ * 이 연산자의 값이 스칼라로 실리면 서버가 문자열을 글자 단위로 쪼개므로
+ * (`ListFilter.apply` 의 `if "" in value`), 요청 조립 시 `[value]` 로 감싼다.
+ */
+export declare const LIST_VALUE_OPERATORS: readonly ["in", "notIn", "arrIncludes", "arrIncludesSome", "arrIncludesAll", "inArray", "inArrayFilter", "notInArray"];
+export declare function isListValueOperator(op: FilterOperator): boolean;

package/dist/core/src/types/operators.js

@@ -0,0 +1,108 @@
+/**
+ * 필터 연산자 — 백엔드 `QueryBuilder/types.py` 와 1:1 대응한다.
+ *
+ * 이 목록이 프론트/백 공통 계약의 전부다. 여기 없는 문자열은 서버가
+ * 기본 연산자로 강등하므로(TextFilter → "contains", NumberFilter → "equals"),
+ * 새 연산자는 반드시 양쪽을 같이 늘린다.
+ */
+export const TEXT_OPERATORS = [
+    "equals", "notEquals", "lessThan", "lessThanOrEqualTo",
+    "greaterThan", "greaterThanOrEqualTo", "contains", "notContains",
+    "startsWith", "endsWith", "fuzzy", "empty", "notEmpty",
+];
+export const NUMBER_OPERATORS = [
+    "equals", "notEquals", "lessThan", "lessThanOrEqualTo",
+    "greaterThan", "greaterThanOrEqualTo", "between", "betweenInclusive",
+    "outsideRange", "isEmpty",
+];
+export const DATE_OPERATORS = [
+    "equals", "notEquals", "lessThan", "lessThanOrEqualTo",
+    "greaterThan", "greaterThanOrEqualTo", "between", "betweenInclusive",
+    "dateBetween", "inPeriod",
+];
+export const LIST_OPERATORS = [
+    "in", "notIn", "between", "arrIncludes", "arrIncludesSome",
+    "arrIncludesAll", "inArray", "inArrayFilter", "notInArray",
+];
+export const BOOLEAN_OPERATORS = ["equals"];
+export const RELATION_OPERATORS = ["hasAny", "hasAll", "hasChild", "hasNotChild"];
+export const LINEAR_OPERATORS = ["linearExact", "linearContains", "linearExists"];
+export const SCHEDULE_OPERATORS = ["scheduleContains", "scheduleOverlaps"];
+/**
+ * variant → 연산자 후보. `FilterSpec.operators` 미지정 시의 기본값이다.
+ *
+ * 위의 `*_OPERATORS` 는 **백엔드 검증 목록**(`types.py` 와 같은 순서)이고,
+ * 이 표는 **UI 노출 순서**다. 둘을 같은 배열로 쓰면 안 된다 —
+ * 검증 목록의 첫 항목은 아무 의미가 없는데, 이 표는 **첫 항목이 기본 연산자**이기
+ * 때문이다 (기존 `columnFilterModeOptions[0]` 규칙 계승). 실제로 그렇게 묶었더니
+ * 텍스트 컬럼의 기본이 `equals` 가 되어, 기존 기본값 `fuzzy` 로 걸리던
+ * "듀벨" ↔ "듀 벨 상사" 매칭이 조용히 깨졌다.
+ */
+export const OPERATORS_BY_VARIANT = {
+    text: [
+        "fuzzy", "contains", "notContains", "equals", "notEquals",
+        "startsWith", "endsWith", "empty", "notEmpty",
+    ],
+    number: [
+        "betweenInclusive", "between", "outsideRange", "equals", "notEquals",
+        "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo", "isEmpty",
+    ],
+    date: [
+        "betweenInclusive", "between", "inPeriod", "equals", "notEquals",
+        "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo",
+    ],
+    datetime: [
+        "betweenInclusive", "between", "inPeriod", "equals", "notEquals",
+        "lessThan", "lessThanOrEqualTo", "greaterThan", "greaterThanOrEqualTo",
+    ],
+    boolean: BOOLEAN_OPERATORS,
+    select: ["inArray", "notInArray", "equals"],
+    multiSelect: ["inArray", "notInArray", "arrIncludesSome", "arrIncludesAll"],
+    relation: RELATION_OPERATORS,
+    linear: ["linearContains", "linearExists", "linearExact"],
+    schedule: SCHEDULE_OPERATORS,
+    custom: ["custom"],
+};
+/**
+ * variant 별 **노출 연산자** — 컬럼을 만들 때 드롭다운에 실제로 띄우는 축약본.
+ * `OPERATORS_BY_VARIANT` 는 그 variant 가 지원하는 전체 목록(첫 항목 = 기본값)이고,
+ * 이쪽은 기존 `getColumnFilterModeOptions` 와 같은 짧은 목록이다. 전부 띄우면
+ * 선택지가 13개가 된다. 없는 variant 는 전체 목록을 그대로 쓴다.
+ */
+export const OFFERED_OPERATORS = {
+    text: ["fuzzy", "equals", "empty"],
+    number: ["betweenInclusive", "outsideRange", "isEmpty"],
+    date: ["betweenInclusive", "inPeriod"],
+    datetime: ["betweenInclusive", "inPeriod"],
+    boolean: ["equals"],
+    select: ["inArray", "notInArray"],
+    multiSelect: ["inArray", "notInArray"],
+};
+export function offeredOperators(variant) {
+    return OFFERED_OPERATORS[variant] ?? OPERATORS_BY_VARIANT[variant];
+}
+/**
+ * 값을 소비하지 않는 연산자 — 입력창을 그리지 않는다 (백엔드 VALUELESS_OPERATORS 대응).
+ *
+ * `hasChild`/`hasNotChild` 도 여기 든다. 서버는 `value None` 인 필터를 통째로
+ * 건너뛰므로 항목은 있어야 하고 값은 `true` 로 실린다 — 목록에서 빠져 있으면
+ * `useTableSearch.normalizeFilters` 가 "미입력" 으로 지워 훅 경로에서 걸리지 않았다.
+ */
+export const VALUELESS_OPERATORS = [
+    "empty", "notEmpty", "isEmpty", "hasChild", "hasNotChild",
+];
+export function isValuelessOperator(op) {
+    return VALUELESS_OPERATORS.includes(op);
+}
+/**
+ * 값이 **목록**인 리스트 연산자 — `between` 은 `[lo, hi]` 쌍이라 제외한다.
+ * 이 연산자의 값이 스칼라로 실리면 서버가 문자열을 글자 단위로 쪼개므로
+ * (`ListFilter.apply` 의 `if "" in value`), 요청 조립 시 `[value]` 로 감싼다.
+ */
+export const LIST_VALUE_OPERATORS = [
+    "in", "notIn", "arrIncludes", "arrIncludesSome", "arrIncludesAll",
+    "inArray", "inArrayFilter", "notInArray",
+];
+export function isListValueOperator(op) {
+    return LIST_VALUE_OPERATORS.includes(op);
+}