kokotable 0.95.0

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

@@ -0,0 +1,114 @@
+import type { FilterOperator } from "./operators";
+/**
+ * 서버 테이블 요청 — 백엔드 `QueryBuilder/types.py` 와 1:1.
+ *
+ * `columnFilterFns` 를 뺀 나머지는 전부 TanStack Table v8 의 상태 모양 그대로다
+ * (`ColumnFiltersState`, `PaginationState`, `SortingState`, `GroupingState`).
+ * 그래서 이 계약은 테이블 구현을 갈아끼워도 그대로 살아남는다.
+ */
+export interface TableRequest {
+    /** 컬럼별 연산자. **클라이언트에서는 상태가 아니라 파생값이다** — `TableSearch.operators` 참조 */
+    columnFilterFns?: Record<string, FilterOperator>;
+    columnFilters?: ColumnFilterEntry[];
+    pagination?: Pagination;
+    sorting?: SortEntry[];
+    globalFilter?: string;
+    grouping?: string[];
+    /**
+     * @deprecated 백엔드 `TableRequest` 에 없는 키다 — 서버는 무시하고, `grouping` 이 있으면
+     * `groupExpansion` 기본값(`path: [], offset: pageIndex*pageSize, limit: pageSize`)으로
+     * 최상위 그룹 노드(`groups.nodes`)를 돌려준다. `useServerTableData` 는 이 키를 wire 에서
+     * 제거하고 `groupExpansion` 을 명시해 보낸다(기존 ERP `useTableQuery.buildParams` 와 동일).
+     */
+    groupHeaderOnly?: boolean;
+    /**
+     * 그룹 확장 요청 (백엔드 `GroupExpansion`).
+     * - `path` 깊이 < `grouping` 깊이 → 다음 레벨 그룹 노드(`groups.nodes`)
+     * - `path` 깊이 = `grouping` 깊이 → 말단 행(`data`)
+     * - `path: []` 가 최상위 헤더 페이지다. 없으면 서버가 `pagination` 으로 같은 값을 만든다.
+     */
+    groupExpansion?: GroupExpansionRequest;
+    virtualColumns?: Record<string, VirtualColumnSpec>;
+    /** `{ "quantity": ["sum", "avg"] }` — 미지정 시 집계 없음 */
+    aggregation?: Record<string, string[]>;
+}
+export interface ColumnFilterEntry<V = unknown> {
+    id: string;
+    value: V;
+}
+export interface SortEntry {
+    id: string;
+    desc: boolean;
+    /** 가상/통합 컬럼이 실제로 정렬할 서버 필드 */
+    key?: string;
+}
+export interface Pagination {
+    pageIndex: number;
+    pageSize: number;
+}
+export interface VirtualColumnSpec {
+    expr: string;
+    type?: "number" | "string" | "boolean";
+}
+/** 백엔드 `GroupPathItem` — 그룹 경로의 한 단계 */
+export interface GroupPathItem {
+    /** 그룹 컬럼명 (요청 `grouping` 의 키, dot-notation 가능) */
+    key: string;
+    value: unknown;
+}
+/** 백엔드 `GroupExpansion` 과 1:1 */
+export interface GroupExpansionRequest {
+    path: GroupPathItem[];
+    offset: number;
+    limit: number;
+}
+/**
+ * 서버 응답 봉투 — 백엔드 `StandardResponse` 의 `data`·`meta`·`groups`.
+ *
+ * 그룹 노드 조회(`grouping` 있고 `groupExpansion.path` 깊이 < `grouping` 깊이)면
+ * `data` 는 비고 `groups.nodes` 가 차며 `meta.total_count` 는 **그 레벨의 전체 그룹 수**다.
+ * 말단 행 조회·일반 조회면 `groups` 가 없고 `data` 가 찬다.
+ */
+export interface TableResponse<T> {
+    data: T[];
+    meta?: TableResponseMeta | null;
+    groups?: GroupsResult | null;
+}
+export interface TableResponseMeta {
+    total_count?: number | null;
+    failed_count?: number | null;
+    success_count?: number | null;
+    [key: string]: unknown;
+}
+/**
+ * 백엔드 `CRUD/schemas.py` 의 `GroupsResult` 와 1:1.
+ *
+ * 실제 서버(`GroupMixin.execute_group`)는 `nodes` 만 채운다. `headers` 는 스키마에
+ * 남아 있는 구 포맷이라 하위 호환으로만 읽는다.
+ */
+export interface GroupsResult {
+    /** @deprecated 구 `groupHeaderOnly` 포맷 — 현행 백엔드는 채우지 않는다 */
+    headers?: GroupHeader[] | null;
+    /** 요청한 경로의 다음 레벨 그룹 노드 (한 레벨, 페이지 단위) */
+    nodes?: GroupNode[] | null;
+}
+/** @deprecated 백엔드 `GroupHeader` — 구 `groupHeaderOnly` 응답. `GroupNode` 를 쓴다 */
+export interface GroupHeader {
+    group_values: Array<{
+        key: string;
+        value: unknown;
+        label?: string | null;
+    }>;
+    count: number;
+    aggregates?: Record<string, Record<string, unknown>>;
+}
+/** 백엔드 `GroupNode` 와 1:1 — 한 레벨의 그룹 하나 */
+export interface GroupNode {
+    /** 이 노드를 만든 그룹 컬럼 (요청 `grouping` 의 키) */
+    group_key: string;
+    group_value: unknown;
+    /** 하위 말단 행 수 */
+    count: number;
+    /** `{ 컬럼: { 함수: 값 } }` — 서버는 항상 싣는다(기본 `{}`) */
+    aggregates?: Record<string, Record<string, unknown>>;
+}

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

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

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

@@ -0,0 +1,112 @@
+import type { RowData } from "@tanstack/react-table";
+import type { FilterOperator } from "./operators";
+import type { FilterSource } from "./filter";
+import type { TableColumnDefs } from "./column";
+import type { ColumnFilterEntry, Pagination, SortEntry, TableRequest, VirtualColumnSpec } from "./request";
+import type { AggregationSpec } from "../client/aggregate";
+/**
+ * 사용자가 편집/적용하는 검색 상태.
+ *
+ * `columnFilterFns` 는 **여기 있어야 한다.** 연산자도 조회 조건의 일부라서,
+ * 상태 밖에 두면 `fuzzy -> equals` 로 바꾸는 순간 검색 버튼을 누르지 않았는데
+ * 결과가 바뀌고 `isDirty` 도 올라가지 않는다 (draft/params 계약 붕괴).
+ *
+ * 다만 **초기화는 effect 가 아니다.** `useState` 초기값에서
+ * `deriveOperators(columns)` 로 동기 계산한다 — 원본의 `useFilterFnsInit` +
+ * `filterFnsReady` 게이트가 사라지는 지점은 그대로다.
+ */
+export interface SearchState {
+    columnFilters: ColumnFilterEntry[];
+    /** 컬럼별 연산자. 컬럼에서 파생된 기본값 위에 사용자 변경분이 얹힌 **완전한 맵** */
+    columnFilterFns: Record<string, FilterOperator>;
+    globalFilter: string;
+    pagination: Pagination;
+    sorting: SortEntry[];
+    grouping?: string[];
+    virtualColumns?: Record<string, VirtualColumnSpec>;
+    /**
+     * 그룹 집계 명세. 미지정이면 컬럼 `meta.enableAgg`/`meta.aggregations` 에서 파생한
+     * 값(`deriveAggregation`)이 그룹핑 요청에 실린다. 명시하면 그쪽이 우선한다.
+     */
+    aggregation?: AggregationSpec;
+}
+export interface TableSearchOptions<T extends RowData> {
+    columns: TableColumnDefs<T>;
+    initial?: Partial<SearchState>;
+    /** 컬럼 기본 연산자를 덮어쓸 초기값 */
+    initialOperators?: Record<string, FilterOperator>;
+    /** `apply()` 직후 호출 — URL 히스토리 push 등 */
+    onApply?: (params: SearchState) => void;
+    /**
+     * 즉시 조회(`applyOnChange` 컬럼 · `globalFilterApplyOnChange`) 의 기본 지연(ms).
+     * 마지막 입력 뒤 이 시간이 지나야 `apply()` 가 나간다. 컬럼의 `filter.debounceMs` 가 우선한다.
+     * 기본 0 = 즉시. 대기 중에는 `TableSearch.pendingApply` 가 true 다.
+     */
+    debounceMs?: number;
+    /**
+     * `setGlobalFilter` 도 값 변경 즉시(`debounceMs` 뒤) 조회한다. 기본 false —
+     * 전역검색은 Enter/검색 버튼으로 적용하는 것이 기본이다.
+     */
+    globalFilterApplyOnChange?: boolean;
+}
+/**
+ * 1층 — 검색 상태. **테이블 인스턴스가 없어도 동작한다.**
+ *
+ * `FilterSource` 를 직접 만족하므로 `<FilterArea source={search} />` 가
+ * 테이블 없이 그대로 붙는다.
+ *
+ * `PaginationSource` 는 **만족하지 않는다** — 총 건수는 2층(`TableData`)만 안다.
+ * 페이지네이션 UI 에는 `paginationSource(search, data)` 로 둘을 합쳐 넘긴다.
+ */
+export interface TableSearch<T extends RowData> extends FilterSource {
+    columns: TableColumnDefs<T>;
+    /** 편집 중인 조건 (검색 버튼 누르기 전) */
+    draft: SearchState;
+    /** 적용된 조건 — 실제 조회에 쓰이는 값 */
+    params: SearchState;
+    /** 마운트 시점의 조건. `reset()` 의 목적지 */
+    initialParams: SearchState;
+    /**
+     * 적용된 연산자 맵 (= `params.columnFilterFns` 에 컬럼 기본값을 덧댄 것).
+     * 컬럼이 나중에 추가돼도 기본값이 비지 않도록 파생값을 밑에 깔아 둔다.
+     */
+    readonly operators: Readonly<Record<string, FilterOperator>>;
+    /** 편집 중인 연산자 맵 — 필터 UI 는 이걸 본다 */
+    readonly draftOperators: Readonly<Record<string, FilterOperator>>;
+    setFilter<V = unknown>(id: string, value: V | undefined): void;
+    setOperator(id: string, operator: FilterOperator): void;
+    setGlobalFilter(value: string): void;
+    setSorting(sorting: SortEntry[]): void;
+    setGrouping(grouping: string[]): void;
+    setPagination(pagination: Pagination): void;
+    /** 페이지 이동 — 검색 버튼을 거치지 않고 즉시 반영된다 */
+    setPageIndex(pageIndex: number): void;
+    /** 페이지 크기 변경 — 첫 페이지로 되돌린다 */
+    setPageSize(pageSize: number): void;
+    setDraft(updater: SearchState | ((prev: SearchState) => SearchState)): void;
+    /** draft 를 건너뛰고 즉시 적용 (정렬·페이지 이동처럼 버튼이 없는 조작). draft 도 같은 값이 된다 */
+    setParams(params: SearchState): void;
+    /**
+     * 부분 상태를 **현재 params 와 병합**해 즉시 적용한다 (`setParams` 의 부분 버전).
+     * `columnFilterFns` 는 얕게 병합한다 — 한 컬럼의 연산자만 바꿔도 나머지 맵이 살아 있다.
+     * 기존 `table.setParams(partial)` 호출부(AI 검색 레지스트리 등)가 그대로 붙는 자리다.
+     */
+    patchParams(partial: Partial<SearchState>): void;
+    /** 부분 상태를 현재 draft 와 병합한다 (`setDraft` 의 부분 버전). 적용은 `apply()` 가 한다 */
+    patchDraft(partial: Partial<SearchState>): void;
+    /**
+     * draft → params. 대기 중인 debounce 타이머가 있으면 취소하고 **즉시** 적용한다.
+     */
+    apply(): void;
+    /**
+     * debounce 대기 중 (`applyOnChange` + `debounceMs`) — 입력 끝에 스피너를 그리는 용도.
+     * `apply()` · `reset()` · 언마운트가 대기를 취소한다.
+     */
+    readonly pendingApply: boolean;
+    /** initialParams 로 복원. 연산자 오버라이드도 함께 비운다 */
+    reset(): void;
+    /** draft ≠ params (미적용 변경 존재) */
+    readonly isDirty: boolean;
+    /** `params` + `operators` → 서버 요청 본문 */
+    readonly request: TableRequest;
+}

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

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

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

@@ -0,0 +1,84 @@
+import type { FilterField } from "./filter";
+import type { SortEntry } from "./request";
+/**
+ * 화면은 세 구역으로 나뉜다 — **필터 / 콘텐츠 / 페이지네이션**.
+ *
+ * 각 구역은 테이블 인스턴스가 아니라 **자기가 필요한 최소 계약**에만 의존한다.
+ * 테이블은 그 계약의 구현 하나일 뿐이라(`*FromTable` 어댑터), 세 구역 모두
+ * `table` 을 받을 수도 있고 `search`/`data` 를 받을 수도 있다.
+ *
+ * 그래서 이런 조합이 전부 성립한다:
+ *
+ * - 필터 + 테이블 본문 + 페이지네이션 (기존 화면)
+ * - 필터 + **카드 그리드** + 페이지네이션 (테이블 인스턴스 없음)
+ * - 필터만, 콘텐츠만, 페이지네이션만
+ *
+ * 세 계약 모두 값이 아니라 **메서드**를 노출한다. 테이블 인스턴스는 in-place 로
+ * 변이되므로 스냅샷을 들고 있으면 갱신을 놓치기 때문이다.
+ */
+/** 필터 구역 */
+export interface FilterSource {
+    getFilterFields(): FilterField[];
+}
+/** 콘텐츠 구역 — 테이블 본문이든 카드 그리드든 차트든 이것만 있으면 그린다 */
+export interface ContentSource<T> {
+    getRows(): T[];
+    getStatus(): ContentStatus;
+    refetch(): void;
+}
+export interface ContentStatus {
+    isLoading: boolean;
+    /** 첫 로드인가 — 이후 refetch 는 기존 행을 유지한 채 갱신된다 */
+    isInitialLoading: boolean;
+    isError: boolean;
+    error?: Error;
+    /** 필터를 걸어 0건인가, 애초에 데이터가 없는가 */
+    isEmpty: boolean;
+}
+/**
+ * 정렬 — **구역이 아니라 계약이다.**
+ *
+ * 테이블에서는 정렬 UI 가 헤더에 붙으므로 콘텐츠 구역 안에 그려진다. 그렇다고
+ * `ContentSource` 에 넣으면 안 된다. 두 축이 독립이기 때문이다:
+ * 카드 그리드는 콘텐츠는 있는데 정렬 UI 가 없고, "정렬: 금액↓" 단독 드롭다운은
+ * 정렬은 있는데 콘텐츠가 없다. 필터를 콘텐츠에서 뺀 것과 같은 이유다.
+ */
+export interface SortSource {
+    getSort(): SortEntry[];
+    /** 이 컬럼의 정렬 상태. 정렬 중이 아니면 null */
+    getColumnSort(columnId: string): ColumnSortState | null;
+    toggleSort(columnId: string, options?: ToggleSortOptions): void;
+    /** columnId 를 주면 그 컬럼만, 안 주면 전체 해제 */
+    clearSort(columnId?: string): void;
+}
+export interface ColumnSortState {
+    desc: boolean;
+    /** 다중 정렬에서의 순서 (0부터) */
+    index: number;
+}
+export interface ToggleSortOptions {
+    /** 명시하면 그 방향으로 고정, 없으면 asc -> desc -> 해제 순환 */
+    desc?: boolean;
+    /** 기존 정렬을 유지한 채 추가 (다중 정렬) */
+    multi?: boolean;
+}
+/** 페이지네이션 구역 */
+export interface PaginationSource {
+    getPagination(): PaginationInfo;
+    setPageIndex(pageIndex: number): void;
+    setPageSize(pageSize: number): void;
+}
+export interface PaginationInfo {
+    pageIndex: number;
+    pageSize: number;
+    total: number;
+    pageCount: number;
+}
+/** 선택 액션바 — 콘텐츠 구역에 얹히는 부가 계약 */
+export interface SelectionSource<T> {
+    getSelectedRows(): T[];
+    selectAll(): void;
+    deselectAll(): void;
+    isAllSelected(): boolean;
+    isSomeSelected(): boolean;
+}

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

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

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

@@ -0,0 +1,40 @@
+import type { RowData, Table, TableOptions } from "@tanstack/react-table";
+import type { TableColumnDefs } from "./column";
+import type { ContentSource, FilterSource, PaginationSource, SelectionSource, SortSource } from "./sources";
+import type { TableSearch } from "./search";
+import type { FieldErrors, TableData } from "./data";
+export interface DataTableOptions<T extends RowData> {
+    columns: TableColumnDefs<T>;
+    search: TableSearch<T>;
+    data: TableData<T>;
+    fieldErrors?: FieldErrors;
+    /** TanStack 원본 옵션 통과구 — 이 패키지가 감싸지 않은 기능을 그대로 쓴다 */
+    tableOptions?: Partial<TableOptions<T>>;
+}
+/**
+ * 3층 — TanStack 인스턴스에 1·2층을 연결한 것. **선택 사항이다.**
+ *
+ * 1·2층만으로 필터·페이지네이션·데이터가 전부 성립하므로, 결과를 카드나 차트로
+ * 그리는 화면은 이 층을 만들지 않아도 된다.
+ *
+ * `search` / `data` 를 프로퍼티로 얹기만 하고 `getState()` 는 건드리지 않는다.
+ * 기존 `extendTableInstance` 는 렌더마다 `getState` 를 다시 감쌌는데, TanStack
+ * 인스턴스는 `useState(() => createTable(...))` 로 생애 내내 같은 객체라서
+ * 래퍼가 렌더 수만큼 중첩됐다 (`getState()` 한 번에 스프레드 N회).
+ */
+export type DataTable<T extends RowData> = Table<T> & {
+    search: TableSearch<T>;
+    data: TableData<T>;
+    fieldErrors?: FieldErrors;
+};
+/**
+ * `FilterArea` 등이 받는 값. 테이블 인스턴스든 검색 상태든 상관없다.
+ *
+ * 기존 호출부 109곳은 `table={table}` 그대로 두면 되고,
+ * 카드 화면만 `source={search}` 로 넘긴다.
+ */
+export type AnyFilterSource<T extends RowData> = FilterSource | Table<T> | DataTable<T>;
+export type AnyPaginationSource<T extends RowData> = PaginationSource | Table<T> | DataTable<T>;
+export type AnySelectionSource<T extends RowData> = SelectionSource<T> | Table<T> | DataTable<T>;
+export type AnyContentSource<T extends RowData> = ContentSource<T> | Table<T> | DataTable<T>;
+export type AnySortSource<T extends RowData> = SortSource | Table<T> | DataTable<T>;

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

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

package/dist/core/src/utils/compare.d.ts

@@ -0,0 +1,13 @@
+/** between 경계가 비어 있는가 — 비어 있으면 그쪽은 무한대로 본다 */
+export declare function isEmptyBound(value: unknown): boolean;
+/**
+ * 두 값 비교 — 양쪽이 숫자로 읽히면 숫자로, 아니면 소문자 trim 문자열로.
+ * (기존 클라이언트 필터 `compareValues` 와 동일 규칙)
+ *
+ * 한쪽이 `Date` 인스턴스면 **시각**으로 비교한다 — `String(Date)` 는
+ * `"Sat Mar 01 2025 …"` 라 ISO 문자열 셀과 섞이면 문자열 순서로 밀려났다.
+ * 상대편을 날짜로 읽을 수 없을 때만 문자열 비교로 떨어진다.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+/** 검색 정규화 — 공백 전부 제거 + 소문자. 백엔드 `normalize_search_text` 와 같다 */
+export declare function normalizeSearchText(text: string): string;

package/dist/core/src/utils/compare.js

@@ -0,0 +1,53 @@
+import { parseDateValue } from "../filters/date";
+/** between 경계가 비어 있는가 — 비어 있으면 그쪽은 무한대로 본다 */
+export function isEmptyBound(value) {
+    return value === null || value === undefined || value === "";
+}
+/**
+ * Date 인스턴스와 섞인 비교에서 상대편을 시각으로 읽는다.
+ * `Date` 그대로, ISO 문자열은 `parseDateValue`, 숫자는 epoch ms. 읽을 수 없으면 null.
+ */
+function toTimeIfDateLike(value) {
+    if (value instanceof Date) {
+        const time = value.getTime();
+        return Number.isNaN(time) ? null : time;
+    }
+    if (typeof value === "number")
+        return Number.isNaN(value) ? null : value;
+    if (typeof value === "string" && value !== "") {
+        const parsed = parseDateValue(value);
+        return parsed === null ? null : parsed.date.getTime();
+    }
+    return null;
+}
+/**
+ * 두 값 비교 — 양쪽이 숫자로 읽히면 숫자로, 아니면 소문자 trim 문자열로.
+ * (기존 클라이언트 필터 `compareValues` 와 동일 규칙)
+ *
+ * 한쪽이 `Date` 인스턴스면 **시각**으로 비교한다 — `String(Date)` 는
+ * `"Sat Mar 01 2025 …"` 라 ISO 문자열 셀과 섞이면 문자열 순서로 밀려났다.
+ * 상대편을 날짜로 읽을 수 없을 때만 문자열 비교로 떨어진다.
+ */
+export function compareValues(a, b) {
+    if (a instanceof Date || b instanceof Date) {
+        const at = toTimeIfDateLike(a);
+        const bt = toTimeIfDateLike(b);
+        if (at !== null && bt !== null)
+            return at - bt;
+    }
+    const an = Number(a);
+    const bn = Number(b);
+    if (!Number.isNaN(an) && !Number.isNaN(bn) && a !== "" && b !== "")
+        return an - bn;
+    const as = String(a ?? "").toLowerCase().trim();
+    const bs = String(b ?? "").toLowerCase().trim();
+    if (as < bs)
+        return -1;
+    if (as > bs)
+        return 1;
+    return 0;
+}
+/** 검색 정규화 — 공백 전부 제거 + 소문자. 백엔드 `normalize_search_text` 와 같다 */
+export function normalizeSearchText(text) {
+    return text.replace(/\s+/g, "").toLowerCase();
+}

package/dist/core/src/utils/dateText.d.ts

@@ -0,0 +1,12 @@
+/** 날짜 문자열 정규화 — codec(URL·프리셋)과 describe 가 같은 규칙을 쓴다 */
+/** `2026-06-30T15:00:00.000Z` / `2026-06-30T15:00:00+09:00` 같은 ISO 시각 문자열 */
+export declare const ISO_DATETIME: RegExp;
+/** 로컬 `YYYY-MM-DD`. 유효하지 않은 Date 면 undefined */
+export declare function formatLocalDate(date: Date): string | undefined;
+/** ISO 시각 문자열 → 로컬 `YYYY-MM-DD`. 패턴이 아니거나 파싱 실패면 원값 */
+export declare function isoToLocalDate(value: unknown): unknown;
+/**
+ * `Date` 인스턴스·ISO 시각 문자열을 `YYYY-MM-DD` 로. 그 외는 원값 (배열은 원소별).
+ * 바뀐 원소가 없으면 **같은 배열 참조**를 돌려준다 — codec 이 "변경 없음" 을 참조로 판단한다.
+ */
+export declare function toDateOnly(value: unknown): unknown;

package/dist/core/src/utils/dateText.js

@@ -0,0 +1,30 @@
+/** 날짜 문자열 정규화 — codec(URL·프리셋)과 describe 가 같은 규칙을 쓴다 */
+/** `2026-06-30T15:00:00.000Z` / `2026-06-30T15:00:00+09:00` 같은 ISO 시각 문자열 */
+export const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/;
+const pad = (n) => String(n).padStart(2, "0");
+/** 로컬 `YYYY-MM-DD`. 유효하지 않은 Date 면 undefined */
+export function formatLocalDate(date) {
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** ISO 시각 문자열 → 로컬 `YYYY-MM-DD`. 패턴이 아니거나 파싱 실패면 원값 */
+export function isoToLocalDate(value) {
+    if (typeof value !== "string" || !ISO_DATETIME.test(value))
+        return value;
+    const date = new Date(value);
+    return formatLocalDate(date) ?? value;
+}
+/**
+ * `Date` 인스턴스·ISO 시각 문자열을 `YYYY-MM-DD` 로. 그 외는 원값 (배열은 원소별).
+ * 바뀐 원소가 없으면 **같은 배열 참조**를 돌려준다 — codec 이 "변경 없음" 을 참조로 판단한다.
+ */
+export function toDateOnly(value) {
+    if (Array.isArray(value)) {
+        const next = value.map(toDateOnly);
+        return next.every((v, i) => v === value[i]) ? value : next;
+    }
+    if (value instanceof Date)
+        return formatLocalDate(value) ?? value;
+    return isoToLocalDate(value);
+}

package/dist/core/src/utils/getValue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * dot-path 값 추출 (lodash `get` 대체 — 코어는 의존성 0 을 유지한다).
+ * `"supplier.name"` 처럼 중첩 경로를 지원한다.
+ */
+export declare function getValue(obj: unknown, path: string): unknown;
+/** 값이 "비어 있음"인가 — NULL/undefined/빈 문자열/공백만 */
+export declare function isBlank(value: unknown): boolean;
+/** 필터 값이 미입력인가 — 미입력 필터는 적용하지 않는다 */
+export declare function isUnsetFilterValue(value: unknown): boolean;

package/dist/core/src/utils/getValue.js

@@ -0,0 +1,32 @@
+/**
+ * dot-path 값 추출 (lodash `get` 대체 — 코어는 의존성 0 을 유지한다).
+ * `"supplier.name"` 처럼 중첩 경로를 지원한다.
+ */
+export function getValue(obj, path) {
+    if (obj == null)
+        return undefined;
+    if (!path.includes("."))
+        return obj[path];
+    let current = obj;
+    for (const key of path.split(".")) {
+        if (current == null)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** 값이 "비어 있음"인가 — NULL/undefined/빈 문자열/공백만 */
+export function isBlank(value) {
+    if (value === null || value === undefined)
+        return true;
+    return typeof value === "string" && value.trim() === "";
+}
+/** 필터 값이 미입력인가 — 미입력 필터는 적용하지 않는다 */
+export function isUnsetFilterValue(value) {
+    if (value === undefined || value === null || value === "")
+        return true;
+    if (Array.isArray(value)) {
+        return !value.some((v) => v !== null && v !== undefined && v !== "");
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core/src/index";

package/dist/index.js

@@ -0,0 +1,2 @@
+// kokotable — 헤드리스 코어
+export * from "./core/src/index";

package/dist/mui/src/TableLayout.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from "react";
+export interface SearchBarProps {
+    onSearch: () => void;
+    onReset: () => void;
+    /** 미적용 변경이 있는지 — 있으면 검색 버튼을 강조한다 */
+    isDirty?: boolean;
+    disabled?: boolean;
+}
+/** 검색·초기화 버튼 — 필터 구역 아래에 붙는다 */
+export declare function SearchBar({ onSearch, onReset, isDirty, disabled }: SearchBarProps): import("react").JSX.Element;
+export interface TableLayoutProps {
+    filter?: ReactNode;
+    content: ReactNode;
+    pagination?: ReactNode;
+    /** 우측 툴바 슬롯의 별칭 (`toolbarRight` 와 같다) — 기존 호출부 호환 */
+    toolbar?: ReactNode;
+    /** 제목 옆 좌측 슬롯 — 기존 `renderTopToolbarCustomActions` 자리(전역검색·AI 버튼 등) */
+    toolbarLeft?: ReactNode;
+    /** 우측 슬롯 — 기존 `renderToolbarInternalActions` 자리(컬럼 토글·내보내기 등) */
+    toolbarRight?: ReactNode;
+    title?: ReactNode;
+}
+/** 필터 구역 접기 — Top/Side 레이아웃이 공유하는 옵션. 상태는 제어(`collapsed`)·비제어(`defaultCollapsed`) 둘 다 된다 */
+export interface CollapsibleFilterProps {
+    /** 접기 버튼을 보인다 */
+    collapsible?: boolean;
+    /** 제어 모드 — 주면 내부 상태를 쓰지 않는다 */
+    collapsed?: boolean;
+    /** 비제어 초기값. 미지정이면 xs 화면에서만 접힌 채 시작한다 */
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** 접힌 상태에 보여 줄 적용 조건 수 (배지) */
+    activeCount?: number;
+    /** 필터 구역 제목 (기본 "검색 조건") */
+    filterTitle?: ReactNode;
+    /**
+     * localStorage 키 — 접힘 상태(와 사이드 패널 폭)를 기억한다.
+     * 화면마다 다른 키를 주면 화면별로 기억된다.
+     */
+    storageKey?: string;
+}
+export interface TopFilterLayoutProps extends TableLayoutProps, CollapsibleFilterProps {
+    /** 접힌 상태에 제목 옆에 보일 요약 문구. 없으면 `activeCount` 로 "N개 조건 적용 중" */
+    collapsedSummary?: ReactNode;
+}
+/**
+ * 상단 필터 레이아웃 — 필터 / 콘텐츠 / 페이지네이션 세 구역을 세로로 쌓는다.
+ *
+ * 레이아웃은 세 구역을 **배치만** 한다. 각 구역이 무엇에 의존하는지는
+ * 구역 컴포넌트가 각자 정하므로, 여기서 테이블 인스턴스를 요구하지 않는다.
+ * `collapsible` 이면 필터 Paper 에 접기 헤더가 생기고, 접힌 상태에는 요약 문구만 남는다.
+ */
+export declare function TopFilterLayout(props: TopFilterLayoutProps): import("react").JSX.Element;
+export interface SideFilterLayoutProps extends TableLayoutProps, CollapsibleFilterProps {
+    /** 사이드 패널 너비. `resizable` 이면 초기값이자(비제어) 외부에서 바꾸면 따라가는 값(제어) */
+    filterWidth?: number;
+    /** 패널 위치 (기본 right) */
+    filterPosition?: "left" | "right";
+    /** 폭 드래그 핸들 */
+    resizable?: boolean;
+    minWidth?: number;
+    maxWidth?: number;
+    /** 드래그 중 폭이 바뀔 때마다 */
+    onFilterWidthChange?: (width: number) => void;
+    /** 접힌 패널의 폭 (기본 44) */
+    collapsedWidth?: number;
+}
+/**
+ * 사이드 필터 레이아웃 — 필터를 옆 패널로 뺀다 (기본 오른쪽).
+ *
+ * - `collapsible`: 패널을 세로 탭으로 접는다. xs 에서는 가로 막대가 된다
+ * - `resizable`: 안쪽 변의 드래그 핸들로 폭을 바꾼다 (`minWidth`~`maxWidth`)
+ * - `storageKey`: 접힘·폭을 localStorage 에 기억한다
+ */
+export declare function SideFilterLayout(props: SideFilterLayoutProps): import("react").JSX.Element;