kokotable 0.95.0

package/dist/core/src/contracts/presetStore.js

@@ -0,0 +1,146 @@
+const now = () => new Date().toISOString();
+export function newPresetId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/** 같은 표에서 기본 프리셋은 하나 — `id` 만 남기고 나머지의 `isDefault` 를 내린다 */
+function applyDefault(list, tableKey, id) {
+    return list.map((p) => p.tableKey !== tableKey ? p : { ...p, isDefault: id !== null && p.id === id });
+}
+/** 목록에 하나를 넣거나 바꾼다 (id 기준). 새 항목이면 시각도 채운다 */
+function upsert(list, input) {
+    const existing = input.id ? list.find((p) => p.id === input.id) : undefined;
+    const saved = {
+        ...existing,
+        ...input,
+        id: input.id ?? newPresetId(),
+        createdAt: existing?.createdAt ?? input.createdAt ?? now(),
+        updatedAt: now(),
+    };
+    let next = existing ? list.map((p) => (p.id === saved.id ? saved : p)) : [...list, saved];
+    if (saved.isDefault)
+        next = applyDefault(next, saved.tableKey, saved.id);
+    return { list: next, saved };
+}
+/**
+ * 메모리 저장소 — 테스트·스토리·"서버가 아직 없는" 화면용.
+ * 돌려주는 객체는 매번 복사본이라 호출부가 바꿔도 내부 상태가 오염되지 않는다.
+ */
+export function createMemoryPresetStore(options = {}) {
+    let list = (options.seed ?? []).map((p) => ({ ...p }));
+    const wait = (value) => options.delayMs ? new Promise((resolve) => setTimeout(() => resolve(value), options.delayMs)) : Promise.resolve(value);
+    const clone = (items) => items.map((p) => ({ ...p, state: { ...p.state } }));
+    return {
+        list: (tableKey) => wait(clone(list.filter((p) => p.tableKey === tableKey))),
+        save: (input) => {
+            const result = upsert(list, { ...input, state: { ...input.state } });
+            list = result.list;
+            return wait({ ...result.saved });
+        },
+        remove: (id) => {
+            list = list.filter((p) => p.id !== id);
+            return wait(undefined);
+        },
+        setDefault: (tableKey, id) => {
+            list = applyDefault(list, tableKey, id);
+            return wait(undefined);
+        },
+        dump: () => clone(list),
+    };
+}
+/**
+ * localStorage 저장소 — 서버 없이 브라우저에만 남긴다.
+ * 접근 실패(사파리 프라이빗 모드·권한)는 삼키고 빈 목록으로 동작한다.
+ */
+export function createLocalStoragePresetStore(namespaceOrOptions = {}) {
+    const options = typeof namespaceOrOptions === "string" ? { namespace: namespaceOrOptions } : namespaceOrOptions;
+    const namespace = options.namespace ?? "koko-table:presets";
+    const storage = options.storage ?? globalThis.localStorage;
+    // storage 가 없거나 깨졌을 때의 폴백
+    const memory = new Map();
+    const keyOf = (tableKey) => `${namespace}:${tableKey}`;
+    const read = (tableKey) => {
+        if (!storage)
+            return memory.get(tableKey) ?? [];
+        try {
+            const raw = storage.getItem(keyOf(tableKey));
+            const parsed = raw ? JSON.parse(raw) : [];
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return memory.get(tableKey) ?? [];
+        }
+    };
+    const write = (tableKey, list) => {
+        memory.set(tableKey, list);
+        if (!storage)
+            return;
+        try {
+            if (list.length === 0)
+                storage.removeItem(keyOf(tableKey));
+            else
+                storage.setItem(keyOf(tableKey), JSON.stringify(list));
+        }
+        catch {
+            // 저장이 막혀도 화면은 동작해야 한다 — 메모리 폴백이 이번 세션을 버틴다
+        }
+    };
+    // remove 는 tableKey 를 받지 않는다 — id 로 어느 표인지 찾아야 하므로 id → tableKey 색인을 둔다
+    const indexKey = `${namespace}:__index`;
+    const readIndex = () => {
+        if (!storage)
+            return {};
+        try {
+            const raw = storage.getItem(indexKey);
+            return raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            return {};
+        }
+    };
+    const writeIndex = (index) => {
+        if (!storage)
+            return;
+        try {
+            storage.setItem(indexKey, JSON.stringify(index));
+        }
+        catch {
+            // 위와 같다
+        }
+    };
+    const memoryIndex = new Map();
+    return {
+        list: async (tableKey) => read(tableKey).map((p) => ({ ...p })),
+        save: async (input) => {
+            const result = upsert(read(input.tableKey), input);
+            write(input.tableKey, result.list);
+            memoryIndex.set(result.saved.id, input.tableKey);
+            writeIndex({ ...readIndex(), [result.saved.id]: input.tableKey });
+            return { ...result.saved };
+        },
+        remove: async (id) => {
+            const tableKey = memoryIndex.get(id) ?? readIndex()[id];
+            if (!tableKey)
+                return;
+            write(tableKey, read(tableKey).filter((p) => p.id !== id));
+            memoryIndex.delete(id);
+            const index = readIndex();
+            delete index[id];
+            writeIndex(index);
+        },
+        setDefault: async (tableKey, id) => {
+            write(tableKey, applyDefault(read(tableKey), tableKey, id));
+        },
+    };
+}
+/**
+ * 기본 프리셋 하나를 미리 읽는다 — 마운트 시점에 `useTableSearch({ initial })` 의 초기값으로
+ * 쓰려면 훅보다 먼저(라우트 loader·상위 컴포넌트) 불러 `presetToSearchInitial(preset.state)` 를
+ * 넘긴다. 이미 마운트된 표에는 `usePresets({ autoApplyDefault: true })` 가 같은 일을 한다.
+ */
+export async function loadDefaultPreset(store, tableKey) {
+    const list = await store.list(tableKey);
+    return list.find((p) => p.isDefault) ?? null;
+}

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

@@ -0,0 +1,51 @@
+import type { RowData } from "@tanstack/react-table";
+import type { DataTable } from "../types/table";
+import { type PresetDensity, type PresetState } from "./preset";
+import type { PresetScope, PresetStore, TablePreset } from "./presetStore";
+export interface UsePresetsOptions<T extends RowData> {
+    tableKey: string;
+    store: PresetStore;
+    /** 3층 인스턴스 — 있으면 `extractCurrent` / `apply` 가 표 상태를 읽고 쓴다 */
+    table?: DataTable<T>;
+    /** 표에 없는 density 상태 — 저장 시 실리고 적용 시 `setDensity` 로 돌아온다 */
+    density?: PresetDensity;
+    setDensity?: (density: PresetDensity) => void;
+    /** 첫 목록 로드 때 기본 프리셋을 자동 적용한다 (마운트 이후라 첫 조회가 한 번 더 나간다) */
+    autoApplyDefault?: boolean;
+    /** `table` 없이 쓰거나 적용 뒤 추가 작업이 필요할 때 — `apply(id)` 직후 불린다 */
+    onApply?: (preset: TablePreset) => void;
+    onError?: (error: unknown) => void;
+}
+export interface SavePresetOptions {
+    scope?: PresetScope;
+    isDefault?: boolean;
+    /** 미지정이면 `extractCurrent()` */
+    state?: PresetState;
+}
+export type PresetPatch = Partial<Pick<TablePreset, "name" | "scope" | "isDefault" | "state">>;
+export interface Presets {
+    presets: TablePreset[];
+    /** 마지막으로 적용(또는 저장)한 프리셋 id. 표 상태를 손으로 바꿔도 유지된다 — "출발점" 표시용 */
+    activeId: string | null;
+    activePreset: TablePreset | null;
+    defaultPreset: TablePreset | null;
+    /** 목록을 읽는 중 (첫 로드·refresh) */
+    loading: boolean;
+    /** 저장·삭제·기본 지정이 진행 중 — 버튼 비활성화용 */
+    busy: boolean;
+    error: unknown | null;
+    /** 현재 표 상태를 새 프리셋으로 저장하고 활성으로 표시한다 */
+    save(name: string, options?: SavePresetOptions): Promise<TablePreset>;
+    /** 이름·범위·기본·상태 일부를 바꾼다 */
+    update(id: string, patch: PresetPatch): Promise<TablePreset>;
+    /** "현재 상태를 덮어쓰기" — `update(id, { state: extractCurrent() })` */
+    overwrite(id: string): Promise<TablePreset>;
+    remove(id: string): Promise<void>;
+    /** 표에 적용 (동기 — 이미 읽어 둔 목록에서 찾는다) */
+    apply(id: string): void;
+    setDefault(id: string | null): Promise<void>;
+    refresh(): Promise<void>;
+    extractCurrent(): PresetState;
+    setActiveId(id: string | null): void;
+}
+export declare function usePresets<T extends RowData>(options: UsePresetsOptions<T>): Presets;

package/dist/core/src/contracts/usePresets.js

@@ -0,0 +1,170 @@
+/**
+ * 프리셋 훅 — `PresetStore` 를 붙여 목록·저장·적용·기본 지정을 한 곳에서 한다.
+ *
+ * react-query 에 의존하지 않는다(useState/useEffect 만). ERP 의 `usePreset` 은 react-query
+ * 캐시 무효화로 목록을 다시 받았는데, 여기서는 각 조작이 끝난 뒤 `store.list` 를 다시 읽어
+ * 같은 효과를 낸다 — 서버가 채운 id·시각·기본 플래그가 그대로 화면에 온다.
+ *
+ * 적용은 `applyPresetState(table, state, { setDensity })` 그대로다. `table` 이 없으면
+ * (검색 상태만 있는 카드 화면 등) `activeId` 만 바뀌고 실제 적용은 `onApply` 가 한다.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { applyPresetState, extractPresetState } from "./preset";
+export function usePresets(options) {
+    const { tableKey, store, table, density, setDensity, autoApplyDefault = false, onApply, onError } = options;
+    const [presets, setPresets] = useState([]);
+    const [activeId, setActiveId] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    // 최신 값을 콜백 안에서 읽는다 — 의존성 배열이 매 렌더 바뀌어 effect 가 재실행되는 것을 막는다
+    const latest = useRef({ table, density, setDensity, onApply, onError, store });
+    latest.current = { table, density, setDensity, onApply, onError, store };
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => { mounted.current = false; };
+    }, []);
+    // 늦게 도착한 옛 응답이 새 목록을 덮지 않도록 요청 번호를 매긴다
+    const requestSeq = useRef(0);
+    const fail = useCallback((err) => {
+        if (!mounted.current)
+            return;
+        setError(err);
+        latest.current.onError?.(err);
+    }, []);
+    const load = useCallback(async (opts = {}) => {
+        const seq = ++requestSeq.current;
+        if (!opts.silent)
+            setLoading(true);
+        try {
+            const list = await latest.current.store.list(tableKey);
+            if (!mounted.current || seq !== requestSeq.current)
+                return;
+            setPresets(list);
+            setError(null);
+        }
+        catch (err) {
+            if (seq === requestSeq.current)
+                fail(err);
+        }
+        finally {
+            if (mounted.current && seq === requestSeq.current)
+                setLoading(false);
+        }
+    }, [tableKey, fail]);
+    // tableKey 나 store 가 바뀌면 다시 읽는다
+    useEffect(() => {
+        void load();
+    }, [load, store]);
+    const extractCurrent = useCallback(() => {
+        const { table: t, density: d } = latest.current;
+        if (!t)
+            return {};
+        return extractPresetState(t, d !== undefined ? { density: d } : {});
+    }, []);
+    const applyPreset = useCallback((preset) => {
+        const { table: t, setDensity: sd, onApply: cb } = latest.current;
+        if (t)
+            applyPresetState(t, preset.state, sd ? { setDensity: sd } : {});
+        setActiveId(preset.id);
+        cb?.(preset);
+    }, []);
+    // 첫 로드 뒤 기본 프리셋 자동 적용 — 한 번만
+    const autoApplied = useRef(false);
+    useEffect(() => {
+        if (!autoApplyDefault || loading || autoApplied.current)
+            return;
+        const preset = presets.find((p) => p.isDefault);
+        if (!preset)
+            return;
+        autoApplied.current = true;
+        applyPreset(preset);
+    }, [autoApplyDefault, loading, presets, applyPreset]);
+    const run = useCallback(async (work) => {
+        setBusy(true);
+        try {
+            const result = await work();
+            await load({ silent: true });
+            return result;
+        }
+        catch (err) {
+            fail(err);
+            throw err;
+        }
+        finally {
+            if (mounted.current)
+                setBusy(false);
+        }
+    }, [load, fail]);
+    const save = useCallback((name, opts = {}) => run(async () => {
+        const input = {
+            tableKey,
+            name,
+            state: opts.state ?? extractCurrent(),
+            scope: opts.scope ?? "user",
+            isDefault: opts.isDefault ?? false,
+        };
+        const saved = await latest.current.store.save(input);
+        if (mounted.current)
+            setActiveId(saved.id);
+        return saved;
+    }), [run, tableKey, extractCurrent]);
+    const setDefault = useCallback((id) => run(async () => {
+        const s = latest.current.store;
+        if (s.setDefault) {
+            await s.setDefault(tableKey, id);
+            return;
+        }
+        // setDefault 가 없는 저장소 — 표의 기본 플래그를 save 로 하나씩 맞춘다
+        const current = await s.list(tableKey);
+        for (const p of current) {
+            const shouldBe = id !== null && p.id === id;
+            if ((p.isDefault ?? false) !== shouldBe)
+                await s.save({ ...p, isDefault: shouldBe });
+        }
+    }), [run, tableKey]);
+    const update = useCallback((id, patch) => run(async () => {
+        const s = latest.current.store;
+        const current = presets.find((p) => p.id === id) ?? (await s.list(tableKey)).find((p) => p.id === id);
+        if (!current)
+            throw new Error(`[koko-table] 프리셋을 찾을 수 없습니다: ${id}`);
+        const { isDefault, ...rest } = patch;
+        let saved = current;
+        if (Object.keys(rest).length > 0)
+            saved = await s.save({ ...current, ...rest });
+        if (isDefault !== undefined && isDefault !== (current.isDefault ?? false)) {
+            if (s.setDefault)
+                await s.setDefault(tableKey, isDefault ? id : null);
+            else
+                saved = await s.save({ ...saved, isDefault });
+        }
+        return { ...saved, ...(isDefault !== undefined ? { isDefault } : {}) };
+    }), [run, presets, tableKey]);
+    const overwrite = useCallback((id) => update(id, { state: extractCurrent() }).then((saved) => {
+        if (mounted.current)
+            setActiveId(saved.id);
+        return saved;
+    }), [update, extractCurrent]);
+    const remove = useCallback((id) => run(async () => {
+        await latest.current.store.remove(id);
+        if (mounted.current)
+            setActiveId((prev) => (prev === id ? null : prev));
+    }), [run]);
+    const apply = useCallback((id) => {
+        const preset = presets.find((p) => p.id === id);
+        if (!preset)
+            return;
+        applyPreset(preset);
+    }, [presets, applyPreset]);
+    const refresh = useCallback(() => load(), [load]);
+    const activePreset = useMemo(() => presets.find((p) => p.id === activeId) ?? null, [presets, activeId]);
+    const defaultPreset = useMemo(() => presets.find((p) => p.isDefault) ?? null, [presets]);
+    return useMemo(() => ({
+        presets, activeId, activePreset, defaultPreset, loading, busy, error,
+        save, update, overwrite, remove, apply, setDefault, refresh, extractCurrent, setActiveId,
+    }), [
+        presets, activeId, activePreset, defaultPreset, loading, busy, error,
+        save, update, overwrite, remove, apply, setDefault, refresh, extractCurrent,
+    ]);
+}

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

@@ -0,0 +1,7 @@
+import type { Pagination } from "./types/request";
+/** "전체" 페이지 크기 — 서버가 페이지네이션을 사실상 끄는 값 */
+export declare const PAGE_SIZE_ALL = 999999;
+export declare const DEFAULT_PAGE_SIZE = 30;
+export declare const DEFAULT_PAGINATION: Pagination;
+export declare const DEFAULT_GROUP_BATCH_SIZE = 50;
+export declare const DEFAULT_TABLE_STALE_TIME: number;

package/dist/core/src/defaults.js

@@ -0,0 +1,9 @@
+/** "전체" 페이지 크기 — 서버가 페이지네이션을 사실상 끄는 값 */
+export const PAGE_SIZE_ALL = 999999;
+export const DEFAULT_PAGE_SIZE = 30;
+export const DEFAULT_PAGINATION = {
+    pageIndex: 0,
+    pageSize: DEFAULT_PAGE_SIZE,
+};
+export const DEFAULT_GROUP_BATCH_SIZE = 50;
+export const DEFAULT_TABLE_STALE_TIME = 5 * 60_000;

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

@@ -0,0 +1,20 @@
+/**
+ * kind codec 연결 — URL·프리셋에 실리는 필터 값의 encode/decode.
+ *
+ * kind 가 `codec` 을 선언한 컬럼만 바꾸고 나머지는 그대로 둔다. 바뀐 것이 없으면
+ * 같은 배열 참조를 돌려주므로 호출부가 메모이즈 근거로 써도 된다.
+ */
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { ColumnFilterEntry } from "../types/request";
+import type { AnyFilterKind } from "../types/filterKind";
+import { type FilterKindStore } from "./kind";
+/** 컬럼 id → 해석된 kind (kind 없는 컬럼은 빠진다) */
+export declare function filterKindMap<T extends RowData>(columns: TableColumnDefs<T> | undefined, store?: FilterKindStore): Map<string, AnyFilterKind>;
+/** 저장용(JSON 안전) 값으로 — `kind.codec.encode` */
+export declare function encodeFilterValues<T extends RowData>(columns: TableColumnDefs<T> | undefined, filters: ColumnFilterEntry[], store?: FilterKindStore): ColumnFilterEntry[];
+/**
+ * 저장된 값 → 필터 값 — `kind.codec.decode`. decode 가 `undefined` 를 돌려주면(읽을 수 없는 값)
+ * 그 항목을 뺀다 — 잘못된 값이 조건으로 남아 조용히 0건이 되는 것보다 낫다.
+ */
+export declare function decodeFilterValues<T extends RowData>(columns: TableColumnDefs<T> | undefined, filters: ColumnFilterEntry[], store?: FilterKindStore): ColumnFilterEntry[];

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

@@ -0,0 +1,61 @@
+import { columnKey } from "../columns/deriveOperators";
+import { resolveFilterKind } from "./kind";
+/** 컬럼 id → 해석된 kind (kind 없는 컬럼은 빠진다) */
+export function filterKindMap(columns, store) {
+    const map = new Map();
+    for (const column of columns ?? []) {
+        const id = columnKey(column);
+        const kind = resolveFilterKind(column, store);
+        if (id && kind)
+            map.set(id, kind);
+    }
+    return map;
+}
+/** 저장용(JSON 안전) 값으로 — `kind.codec.encode` */
+export function encodeFilterValues(columns, filters, store) {
+    const kinds = filterKindMap(columns, store);
+    if (kinds.size === 0)
+        return filters;
+    let changed = false;
+    const result = filters.map((entry) => {
+        const codec = entry ? kinds.get(entry.id)?.codec : undefined;
+        if (!codec)
+            return entry;
+        const value = codec.encode(entry.value);
+        if (value === entry.value)
+            return entry;
+        changed = true;
+        return { id: entry.id, value };
+    });
+    return changed ? result : filters;
+}
+/**
+ * 저장된 값 → 필터 값 — `kind.codec.decode`. decode 가 `undefined` 를 돌려주면(읽을 수 없는 값)
+ * 그 항목을 뺀다 — 잘못된 값이 조건으로 남아 조용히 0건이 되는 것보다 낫다.
+ */
+export function decodeFilterValues(columns, filters, store) {
+    const kinds = filterKindMap(columns, store);
+    if (kinds.size === 0)
+        return filters;
+    let changed = false;
+    const result = [];
+    for (const entry of filters) {
+        const codec = entry ? kinds.get(entry.id)?.codec : undefined;
+        if (!codec) {
+            result.push(entry);
+            continue;
+        }
+        const value = codec.decode(entry.value);
+        if (value === undefined) {
+            changed = true;
+            continue;
+        }
+        if (value === entry.value) {
+            result.push(entry);
+            continue;
+        }
+        changed = true;
+        result.push({ id: entry.id, value });
+    }
+    return changed ? result : filters;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 날짜 필터 — 백엔드 `DateFilter` 의 **반열림 경계 규칙**을 그대로 옮긴다.
+ *
+ * `"2025-01-31"` 과 `"2025-01-31T00:00:00"` 은 다른 뜻이다. 전자는 "그 날",
+ * 후자는 "그 날 자정". 프론트는 전자를 보낸다. 이 구분이 없으면
+ * `<= 2025-01-31 00:00` 이 되어 **마지막 날이 통째로 빠진다**
+ * (백엔드 주석의 실측: 6,963행 중 684행 = 9.8% 유실).
+ *
+ * 기존 클라이언트 `dateBetween` 은 닫힌 구간이라 서버와 결과가 달랐다.
+ */
+export interface ParsedDate {
+    date: Date;
+    dateOnly: boolean;
+}
+export declare function parseDateValue(value: unknown): ParsedDate | null;
+/** 그 날 00:00 의 다음 날 00:00 */
+export declare function dayAfter(date: Date): Date;
+/** 단일 비교 — 백엔드 `DateFilter._single` */
+export declare function matchDateSingle(cellValue: unknown, filterValue: unknown, operator: string): boolean;
+/**
+ * 구간 비교 — 백엔드 `DateFilter._between`.
+ * 끝값이 날짜만이면 경계가 하루 단위로 움직이고, 하한과 상한이 **대칭**으로 움직인다.
+ */
+export declare function matchDateBetween(cellValue: unknown, filterValue: unknown, operator: "between" | "betweenInclusive" | "dateBetween"): boolean;
+export declare const PERIODS: Record<string, (now: Date) => [Date, Date]>;
+export declare const PERIOD_TOKENS: string[];
+/** 토큰 → 반열림 [start, end). 모르는 토큰이면 null */
+export declare function resolvePeriod(token: string, now?: Date): [Date, Date] | null;
+export declare function matchInPeriod(cellValue: unknown, filterValue: unknown, now?: Date): boolean;
+export declare function matchDate(cellValue: unknown, filterValue: unknown, operator: string, now?: Date): boolean;

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

@@ -0,0 +1,179 @@
+/**
+ * 날짜 필터 — 백엔드 `DateFilter` 의 **반열림 경계 규칙**을 그대로 옮긴다.
+ *
+ * `"2025-01-31"` 과 `"2025-01-31T00:00:00"` 은 다른 뜻이다. 전자는 "그 날",
+ * 후자는 "그 날 자정". 프론트는 전자를 보낸다. 이 구분이 없으면
+ * `<= 2025-01-31 00:00` 이 되어 **마지막 날이 통째로 빠진다**
+ * (백엔드 주석의 실측: 6,963행 중 684행 = 9.8% 유실).
+ *
+ * 기존 클라이언트 `dateBetween` 은 닫힌 구간이라 서버와 결과가 달랐다.
+ */
+/** 시각 표기가 없으면 "날짜만" — 백엔드 `_TIME_MARKS` 와 같은 판정 */
+const TIME_MARKS = ["T", " ", ":"];
+export function parseDateValue(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : { date: value, dateOnly: false };
+    }
+    if (typeof value === "number") {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : { date: d, dateOnly: false };
+    }
+    if (typeof value !== "string" || value === "")
+        return null;
+    const dateOnly = !TIME_MARKS.some((mark) => value.includes(mark));
+    // 날짜만인 값은 **로컬 자정**으로 읽는다. new Date("2025-01-31") 은 UTC 자정이라
+    // KST 에서 하루 밀린다 — 백엔드 datetime.fromisoformat 은 로컬 naive 다.
+    if (dateOnly) {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        if (match) {
+            const [, y, m, d] = match;
+            return { date: new Date(Number(y), Number(m) - 1, Number(d)), dateOnly: true };
+        }
+    }
+    const parsed = new Date(value.replace("Z", "+00:00"));
+    return Number.isNaN(parsed.getTime()) ? null : { date: parsed, dateOnly };
+}
+/** 그 날 00:00 의 다음 날 00:00 */
+export function dayAfter(date) {
+    const d = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    d.setDate(d.getDate() + 1);
+    return d;
+}
+function cellDate(cellValue) {
+    if (cellValue == null)
+        return null;
+    const parsed = parseDateValue(cellValue);
+    return parsed?.date ?? null;
+}
+/** 단일 비교 — 백엔드 `DateFilter._single` */
+export function matchDateSingle(cellValue, filterValue, operator) {
+    const bound = parseDateValue(filterValue);
+    const cell = cellDate(cellValue);
+    if (cell === null)
+        return false;
+    if (bound === null)
+        return false;
+    const dt = bound.date.getTime();
+    const nxt = bound.dateOnly ? dayAfter(bound.date).getTime() : dt;
+    const c = cell.getTime();
+    switch (operator) {
+        case "notEquals":
+            return bound.dateOnly ? c < dt || c >= nxt : c !== dt;
+        case "lessThan":
+            return c < dt;
+        case "lessThanOrEqualTo":
+            // "1/31 까지" = 1/31 을 포함 = 2/1 미만
+            return bound.dateOnly ? c < nxt : c <= dt;
+        case "greaterThan":
+            // "1/31 초과" = 1/31 을 제외 = 2/1 이상
+            return bound.dateOnly ? c >= nxt : c > dt;
+        case "greaterThanOrEqualTo":
+            return c >= dt;
+        case "equals":
+        default:
+            return bound.dateOnly ? c >= dt && c < nxt : c === dt;
+    }
+}
+/**
+ * 구간 비교 — 백엔드 `DateFilter._between`.
+ * 끝값이 날짜만이면 경계가 하루 단위로 움직이고, 하한과 상한이 **대칭**으로 움직인다.
+ */
+export function matchDateBetween(cellValue, filterValue, operator) {
+    if (!Array.isArray(filterValue) || filterValue.length !== 2)
+        return true;
+    const [rawLo, rawHi] = filterValue;
+    const lo = rawLo == null || rawLo === "" ? null : parseDateValue(rawLo);
+    const hi = rawHi == null || rawHi === "" ? null : parseDateValue(rawHi);
+    if (lo === null && hi === null)
+        return true;
+    const cell = cellDate(cellValue);
+    if (cell === null)
+        return false;
+    const c = cell.getTime();
+    const open = operator === "between";
+    if (lo !== null) {
+        if (!open) {
+            if (c < lo.date.getTime())
+                return false;
+        }
+        else if (lo.dateOnly) {
+            if (c < dayAfter(lo.date).getTime())
+                return false;
+        }
+        else if (c <= lo.date.getTime()) {
+            return false;
+        }
+    }
+    if (hi !== null) {
+        if (!open) {
+            const limit = hi.dateOnly ? dayAfter(hi.date).getTime() : hi.date.getTime();
+            if (hi.dateOnly ? c >= limit : c > limit)
+                return false;
+        }
+        else if (c >= hi.date.getTime()) {
+            return false;
+        }
+    }
+    return true;
+}
+// ─────────────────────────────────────────────────────────────
+// 상대 기간 토큰 — 백엔드 period.py 와 1:1
+// ─────────────────────────────────────────────────────────────
+const startOfDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+const startOfMonth = (d) => new Date(d.getFullYear(), d.getMonth(), 1);
+const addMonths = (d, n) => new Date(d.getFullYear(), d.getMonth() + n, 1);
+const startOfQuarter = (d) => new Date(d.getFullYear(), Math.floor(d.getMonth() / 3) * 3, 1);
+const startOfYear = (d) => new Date(d.getFullYear(), 0, 1);
+const addDays = (d, n) => {
+    const next = new Date(d);
+    next.setDate(next.getDate() + n);
+    return next;
+};
+/** ISO 주 시작(월요일) */
+const startOfWeek = (d) => {
+    const day = startOfDay(d);
+    const weekday = (day.getDay() + 6) % 7; // 월=0
+    return addDays(day, -weekday);
+};
+const trailingDays = (n) => (now) => [addDays(startOfDay(now), -(n - 1)), addDays(startOfDay(now), 1)];
+const trailingMonths = (n) => (now) => [addMonths(startOfMonth(now), -(n - 1)), addMonths(startOfMonth(now), 1)];
+export const PERIODS = {
+    today: (now) => [startOfDay(now), addDays(startOfDay(now), 1)],
+    yesterday: (now) => [addDays(startOfDay(now), -1), startOfDay(now)],
+    thisWeek: (now) => [startOfWeek(now), addDays(startOfWeek(now), 7)],
+    lastWeek: (now) => [addDays(startOfWeek(now), -7), startOfWeek(now)],
+    thisMonth: (now) => [startOfMonth(now), addMonths(startOfMonth(now), 1)],
+    lastMonth: (now) => [addMonths(startOfMonth(now), -1), startOfMonth(now)],
+    thisQuarter: (now) => [startOfQuarter(now), addMonths(startOfQuarter(now), 3)],
+    lastQuarter: (now) => [addMonths(startOfQuarter(now), -3), startOfQuarter(now)],
+    thisYear: (now) => [startOfYear(now), new Date(now.getFullYear() + 1, 0, 1)],
+    lastYear: (now) => [new Date(now.getFullYear() - 1, 0, 1), startOfYear(now)],
+    last7days: trailingDays(7),
+    last30days: trailingDays(30),
+    last90days: trailingDays(90),
+    last12months: trailingMonths(12),
+};
+export const PERIOD_TOKENS = Object.keys(PERIODS);
+/** 토큰 → 반열림 [start, end). 모르는 토큰이면 null */
+export function resolvePeriod(token, now = new Date()) {
+    const resolver = PERIODS[token];
+    return resolver ? resolver(now) : null;
+}
+export function matchInPeriod(cellValue, filterValue, now) {
+    const range = resolvePeriod(String(filterValue), now ?? new Date());
+    if (range === null)
+        return true; // 모르는 토큰은 서버가 400 — 클라이언트는 필터를 무시한다
+    const cell = cellDate(cellValue);
+    if (cell === null)
+        return false;
+    const c = cell.getTime();
+    return c >= range[0].getTime() && c < range[1].getTime();
+}
+export function matchDate(cellValue, filterValue, operator, now) {
+    if (operator === "inPeriod")
+        return matchInPeriod(cellValue, filterValue, now);
+    if (operator === "between" || operator === "betweenInclusive" || operator === "dateBetween") {
+        return matchDateBetween(cellValue, filterValue, operator);
+    }
+    return matchDateSingle(cellValue, filterValue, operator);
+}