kokotable 0.95.0

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

@@ -0,0 +1,121 @@
+import { BOOLEAN_OPERATORS, DATE_OPERATORS, LINEAR_OPERATORS, LIST_OPERATORS, NUMBER_OPERATORS, RELATION_OPERATORS, SCHEDULE_OPERATORS, TEXT_OPERATORS, } from "../types/operators";
+import { resolveVariant } from "../columns/deriveOperators";
+import { getValue } from "../utils/getValue";
+import { matchText } from "./text";
+import { matchNumber } from "./number";
+import { matchDate } from "./date";
+import { matchList, matchListBetween, matchArrayCell } from "./list";
+import { matchRelation } from "./relation";
+import { matchLinear } from "./linear";
+import { matchSchedule } from "./schedule";
+import { resolveFilterKind } from "./kind";
+const has = (list, op) => list.includes(op);
+/**
+ * 컬럼 타입과 무관하게 **가상 경로**로 해석되는 필터 UI 종류.
+ * 서버도 이 연산자들은 `column_type` 을 보기 전에 갈라낸다.
+ */
+const VIRTUAL_VARIANTS = new Set(["relation", "linear", "schedule"]);
+export function isVirtualColumn(column) {
+    return !!column && VIRTUAL_VARIANTS.has(resolveVariant(column));
+}
+export function resolveDataKind(column) {
+    // kind 가 서버 `column_type` 대응을 선언했으면 그것이 가장 구체적이다
+    const kindDataKind = resolveFilterKind(column)?.dataKind;
+    if (kindDataKind)
+        return kindDataKind;
+    // `filter.variant` 가 가상 경로(관계·선형·일정)면 dataType 보다 먼저 판정한다.
+    // `ColumnBuilder` 는 dataType 을 항상 채우기 때문에(`ColumnIsRelation` 도 "text"),
+    // dataType 을 먼저 보면 관계 필터가 텍스트 fuzzy 폴백으로 떨어져 hasChild 가
+    // 0건, hasAny/hasAll 이 조건을 무시하는 결함이 있었다.
+    if (column?.filter?.variant === "relation")
+        return "relation";
+    const dataType = column?.meta?.dataType;
+    if (dataType === "number")
+        return "number";
+    if (dataType === "date" || dataType === "datetime")
+        return "date";
+    if (dataType === "boolean")
+        return "boolean";
+    if (dataType)
+        return "text";
+    if (!column)
+        return "text";
+    switch (resolveVariant(column)) {
+        case "number": return "number";
+        case "date":
+        case "datetime": return "date";
+        case "boolean": return "boolean";
+        case "relation": return "relation";
+        default: return "text";
+    }
+}
+/**
+ * 컬럼 필터 하나를 행에 적용한다.
+ *
+ * 분기 순서는 백엔드 `_apply_filter_by_type` 을 그대로 따른다 —
+ * 순서가 어긋나면 같은 요청이 client/server 에서 다른 결과를 낸다.
+ * (예: `between` 은 숫자·날짜·리스트 셋 다 지원하므로 컬럼 종류가 먼저 결정돼야 한다)
+ */
+export function matchColumnFilter(row, columnId, filterValue, operator, column, ctx = {}) {
+    // 1. custom — 서버가 필터를 건너뛴다 (호출부가 값 해석을 전담)
+    if (operator === "custom")
+        return true;
+    // 1'. kind 경로 — 컬럼이 kind 를 선언했고 연산자가 그 kind 에 있으면 `operators[op].client` 가 판정한다.
+    // 내장 kind 는 아래 분기와 같은 함수를 부르므로 결과가 같다 (kinds.test.ts 가 대조한다).
+    // 연산자가 kind 에 없으면(사용자가 다른 연산자를 골랐을 때) 아래 variant 경로로 떨어진다.
+    const kind = resolveFilterKind(column);
+    const kindOperator = kind?.operators[operator];
+    if (kind && kindOperator) {
+        return kindOperator.client(getValue(row, columnId), filterValue, { row, columnId, now: ctx.now });
+    }
+    // 2. Linear (가상 경로 — 컬럼 타입과 무관하게 먼저)
+    if (has(LINEAR_OPERATORS, operator)) {
+        return matchLinear(row, columnId, filterValue, operator);
+    }
+    // 3. Schedule (가상 경로)
+    if (has(SCHEDULE_OPERATORS, operator)) {
+        return matchSchedule(row, filterValue, operator);
+    }
+    const dataKind = resolveDataKind(column);
+    const cellValue = getValue(row, columnId);
+    // 4. Relation
+    if (dataKind === "relation" && has(RELATION_OPERATORS, operator)) {
+        return matchRelation(row, columnId, filterValue, operator);
+    }
+    // 5. Number
+    if (dataKind === "number" && has(NUMBER_OPERATORS, operator)) {
+        return matchNumber(cellValue, filterValue, operator);
+    }
+    // 6. Date
+    if (dataKind === "date" && has(DATE_OPERATORS, operator)) {
+        return matchDate(cellValue, filterValue, operator, ctx.now);
+    }
+    // 7. Boolean — 백엔드는 equals 만 지원한다
+    if (dataKind === "boolean" && has(BOOLEAN_OPERATORS, operator)) {
+        return String(cellValue) === String(filterValue);
+    }
+    // 8. List (컬럼 종류와 무관)
+    if (has(LIST_OPERATORS, operator)) {
+        switch (operator) {
+            case "between":
+                return matchListBetween(cellValue, filterValue);
+            case "notIn":
+            case "notInArray":
+                return matchList(cellValue, filterValue, true);
+            case "arrIncludes":
+                return matchArrayCell(cellValue, filterValue, "one");
+            case "arrIncludesSome":
+                return matchArrayCell(cellValue, filterValue, "some");
+            case "arrIncludesAll":
+                return matchArrayCell(cellValue, filterValue, "all");
+            default:
+                return matchList(cellValue, filterValue, false);
+        }
+    }
+    // 9. Text
+    if (has(TEXT_OPERATORS, operator)) {
+        return matchText(cellValue, filterValue, operator);
+    }
+    // 10. 전부 미해당 — 백엔드도 fuzzy 로 떨어진다
+    return matchText(cellValue, filterValue, "fuzzy");
+}

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

@@ -0,0 +1,26 @@
+/** 1:N 관계 필터 연산자 */
+export type RelationOperatorName = "hasAny" | "hasAll" | "hasChild" | "hasNotChild";
+export interface RelationCondition {
+    /** 자식 행의 컬럼 경로 (`"item.name"` 등) */
+    column: string;
+    operator: "equals" | "notEquals" | "contains" | "notContains" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual" | "isNull" | "isNotNull";
+    value: string | number | boolean | Array<string | number>;
+}
+export interface RelationConditionGroup {
+    /** 같은 자식 행에서 모두 만족해야 하는 조건들 (AND) */
+    conditions: RelationCondition[];
+}
+export interface RelationFilterValue {
+    groups: RelationConditionGroup[];
+}
+/**
+ * 느슨한 동등 — 서버는 `inner_column == value` 를 컬럼 타입으로 바인딩하므로
+ * 정수 컬럼에 문자열 `'2'` 를 주면 PG 가 캐스팅해 `2` 와 일치한다.
+ * 양쪽이 숫자로 읽히면 숫자로, 아니면 문자열로 비교한다.
+ */
+export declare function looseEquals(a: unknown, b: unknown): boolean;
+/**
+ * 관계 필터 — 그룹 내 조건은 AND, 그룹 간은 연산자에 따라 OR(`hasAny`) / AND(`hasAll`).
+ * `hasChild` / `hasNotChild` 는 자식 존재 여부만 본다.
+ */
+export declare function matchRelation(row: unknown, columnId: string, filterValue: unknown, operator: RelationOperatorName): boolean;

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

@@ -0,0 +1,75 @@
+import { getValue } from "../utils/getValue";
+const asNumber = (value) => {
+    if (value === null || value === undefined || value === "" || typeof value === "boolean")
+        return null;
+    if (typeof value === "object")
+        return null;
+    const num = Number(value);
+    return Number.isNaN(num) ? null : num;
+};
+/**
+ * 느슨한 동등 — 서버는 `inner_column == value` 를 컬럼 타입으로 바인딩하므로
+ * 정수 컬럼에 문자열 `'2'` 를 주면 PG 가 캐스팅해 `2` 와 일치한다.
+ * 양쪽이 숫자로 읽히면 숫자로, 아니면 문자열로 비교한다.
+ */
+export function looseEquals(a, b) {
+    const an = asNumber(a);
+    const bn = asNumber(b);
+    if (an !== null && bn !== null)
+        return an === bn;
+    return String(a) === String(b);
+}
+function evaluateCondition(item, condition) {
+    const itemValue = getValue(item, condition.column);
+    // isNull 계열을 제외하면 NULL 셀은 SQL 3값 논리상 어떤 비교도 참이 되지 않는다
+    // (`NULL != 'x'` 도 NULL 이라 notEquals/notContains 로도 살아나지 않는다)
+    if (condition.operator === "isNull") {
+        return condition.value === true ? itemValue == null : itemValue != null;
+    }
+    if (condition.operator === "isNotNull")
+        return itemValue != null;
+    if (itemValue === null || itemValue === undefined)
+        return false;
+    switch (condition.operator) {
+        case "equals": return looseEquals(itemValue, condition.value);
+        case "notEquals": return !looseEquals(itemValue, condition.value);
+        case "contains":
+            return String(itemValue).toLowerCase().includes(String(condition.value).toLowerCase());
+        case "notContains":
+            return !String(itemValue).toLowerCase().includes(String(condition.value).toLowerCase());
+        case "greaterThan": return Number(itemValue) > Number(condition.value);
+        case "lessThan": return Number(itemValue) < Number(condition.value);
+        case "greaterThanOrEqual": return Number(itemValue) >= Number(condition.value);
+        case "lessThanOrEqual": return Number(itemValue) <= Number(condition.value);
+        default: return true;
+    }
+}
+function relationItems(row, columnId) {
+    const data = getValue(row, columnId);
+    return Array.isArray(data) ? data : null;
+}
+/** 그룹 하나를 만족하는 자식이 하나라도 있는가 (그룹 내 조건은 AND) */
+function groupMatches(items, group) {
+    if (!group.conditions || group.conditions.length === 0)
+        return true; // 빈 그룹은 항상 참
+    return items.some((item) => group.conditions.every((c) => evaluateCondition(item, c)));
+}
+/**
+ * 관계 필터 — 그룹 내 조건은 AND, 그룹 간은 연산자에 따라 OR(`hasAny`) / AND(`hasAll`).
+ * `hasChild` / `hasNotChild` 는 자식 존재 여부만 본다.
+ */
+export function matchRelation(row, columnId, filterValue, operator) {
+    const items = relationItems(row, columnId);
+    if (operator === "hasChild")
+        return items !== null && items.length > 0;
+    if (operator === "hasNotChild")
+        return items === null || items.length === 0;
+    if (!items || items.length === 0)
+        return false;
+    const value = filterValue;
+    if (!value?.groups || value.groups.length === 0)
+        return true; // 자식 존재만 확인
+    return operator === "hasAll"
+        ? value.groups.every((g) => groupMatches(items, g))
+        : value.groups.some((g) => groupMatches(items, g));
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 일정 필터 — 예정(planned) 기간과 실제(actual) 기간을 **OR 로 동시 검증**한다.
+ * 백엔드 `ScheduleFilter` 와 같은 규칙.
+ */
+export type ScheduleOperatorName = "scheduleContains" | "scheduleOverlaps";
+export interface ScheduleFields {
+    plannedStart?: string;
+    plannedEnd?: string;
+    actualStart?: string;
+    actualEnd?: string;
+}
+export interface ScheduleContainsValue {
+    date: string;
+    fields?: ScheduleFields;
+}
+export interface ScheduleOverlapsValue {
+    start: string;
+    end: string;
+    fields?: ScheduleFields;
+}
+export declare function matchSchedule(row: unknown, filterValue: unknown, operator: ScheduleOperatorName): boolean;

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

@@ -0,0 +1,60 @@
+import { getValue } from "../utils/getValue";
+import { parseDateValue } from "./date";
+const DEFAULT_FIELDS = {
+    plannedStart: "planned_process_date",
+    plannedEnd: "planned_finish_date",
+    actualStart: "actual_process_date",
+    actualEnd: "actual_finish_date",
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function readPair(row, startPath, endPath) {
+    const start = getValue(row, startPath);
+    const end = getValue(row, endPath);
+    return { start, end, present: start !== undefined || end !== undefined };
+}
+function toTime(value) {
+    const parsed = parseDateValue(value);
+    return parsed === null ? null : parsed.date.getTime();
+}
+/**
+ * `start < hi && end >= lo` — 상한은 **반열림**(서버 `start_col < range_end`).
+ * `hi` 는 종료일 다음 날 00:00 이므로, 정확히 그 시각에 시작하는 행은 겹치지 않는다.
+ * NULL 이 하나라도 있으면 SQL 3값 논리상 거짓.
+ */
+function overlaps(pair, lo, hi) {
+    const start = toTime(pair.start);
+    const end = toTime(pair.end);
+    if (start === null || end === null)
+        return false;
+    return start < hi && end >= lo;
+}
+export function matchSchedule(row, filterValue, operator) {
+    if (filterValue === null || typeof filterValue !== "object")
+        return true;
+    const value = filterValue;
+    const fields = { ...DEFAULT_FIELDS, ...(value.fields ?? {}) };
+    let lo;
+    let hi;
+    if (operator === "scheduleOverlaps") {
+        if (!value.start || !value.end)
+            return true; // 값 미입력 — 필터 스킵
+        lo = toTime(value.start);
+        const endTime = toTime(value.end);
+        hi = endTime === null ? null : endTime + MS_PER_DAY;
+    }
+    else {
+        if (!value.date)
+            return true;
+        lo = toTime(value.date);
+        hi = lo === null ? null : lo + MS_PER_DAY;
+    }
+    if (lo === null || hi === null)
+        return true; // 파싱 실패 — 백엔드도 필터를 건너뛴다
+    const planned = readPair(row, fields.plannedStart, fields.plannedEnd);
+    const actual = readPair(row, fields.actualStart, fields.actualEnd);
+    // 유효한 일정 컬럼이 하나도 없으면 조건 없음 (백엔드와 동일)
+    if (!planned.present && !actual.present)
+        return true;
+    return ((planned.present && overlaps(planned, lo, hi)) ||
+        (actual.present && overlaps(actual, lo, hi)));
+}

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

@@ -0,0 +1,44 @@
+/**
+ * 텍스트 논리식 — `배추 ∨ ¬김치` 처럼 글리프로 항을 잇는다.
+ * 백엔드 `TextLogicValue.parse` 와 문법이 같아야 한다 (어긋나면 서버가 400).
+ */
+export declare const OP_SYMBOLS: {
+    readonly or: "∨";
+    readonly and: "∧";
+    readonly not: "¬";
+};
+/** 항 수 상한 — 서버 파서와 같은 값. 초과하면 서버가 400 을 낸다 */
+export declare const MAX_TEXT_LOGIC_TERMS = 20;
+export interface TextLogicTerm {
+    text: string;
+    not: boolean;
+}
+export interface ParsedTextLogic {
+    chain: "or" | "and";
+    terms: TextLogicTerm[];
+}
+export declare function hasLogicGlyph(value: string): boolean;
+export declare function trimTerm(text: string): string;
+/**
+ * 전송 문자열 → 논리식. 글리프가 없거나 문법이 어긋나면 `null`(평문 취급).
+ * 서버는 같은 입력을 400 으로 거절하지만, 입력창은 사용자 텍스트를 잃지 않는 쪽이 낫다.
+ */
+export declare function parseTextLogic(value: string): ParsedTextLogic | null;
+/**
+ * 항 하나의 매칭 — 백엔드 `TextFilter._apply_term` 과 의미를 맞춘다.
+ *
+ * - `fuzzy` 는 검색어와 셀 **양쪽 공백을 제거**하고 대소문자 무시 (DB "듀 벨" ↔ 검색 "듀벨")
+ * - `equals`/`notEquals` 는 대소문자를 **구분한다** (SQL `column_str == value`)
+ * - 나머지 부분일치 계열은 소문자 비교
+ */
+export declare function matchTextTerm(cellValue: unknown, term: string, operator: string): boolean;
+/**
+ * `empty` 판정 — 백엔드는 NULL, 빈 문자열, 공백만 셋 다 "비어 있음"으로 본다.
+ * 값이 false(문자열 "false"/"False"/"0" 포함)면 방향이 뒤집힌다.
+ */
+export declare function matchTextEmpty(cellValue: unknown, filterValue: unknown): boolean;
+/**
+ * 텍스트 필터 전체 — 논리식이면 항별로 매칭 후 결합한다.
+ * 서버 `TextFilter.apply` 와 같은 순서: 글리프 파싱 -> 항별 조건 -> or/and 결합.
+ */
+export declare function matchText(cellValue: unknown, filterValue: unknown, operator: string): boolean;

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

@@ -0,0 +1,127 @@
+import { normalizeSearchText } from "../utils/compare";
+import { isBlank } from "../utils/getValue";
+/**
+ * 텍스트 논리식 — `배추 ∨ ¬김치` 처럼 글리프로 항을 잇는다.
+ * 백엔드 `TextLogicValue.parse` 와 문법이 같아야 한다 (어긋나면 서버가 400).
+ */
+export const OP_SYMBOLS = { or: "∨", and: "∧", not: "¬" };
+/** 항 수 상한 — 서버 파서와 같은 값. 초과하면 서버가 400 을 낸다 */
+export const MAX_TEXT_LOGIC_TERMS = 20;
+export function hasLogicGlyph(value) {
+    return (value.includes(OP_SYMBOLS.or) ||
+        value.includes(OP_SYMBOLS.and) ||
+        value.includes(OP_SYMBOLS.not));
+}
+/**
+ * 항 트림 — 백엔드 `strip()` 과 같은 공백 집합.
+ * JS `trim()` 은 U+0085 를 안 지우고 Python `strip()` 은 U+FEFF 를 안 지운다.
+ * 양끝이 같은 항을 보려면 합집합을 명시해야 한다.
+ */
+const TERM_TRIM_PATTERN = /^[\s\uFEFF\u0085]+|[\s\uFEFF\u0085]+$/g;
+export function trimTerm(text) {
+    return text.replace(TERM_TRIM_PATTERN, "");
+}
+/**
+ * 전송 문자열 → 논리식. 글리프가 없거나 문법이 어긋나면 `null`(평문 취급).
+ * 서버는 같은 입력을 400 으로 거절하지만, 입력창은 사용자 텍스트를 잃지 않는 쪽이 낫다.
+ */
+export function parseTextLogic(value) {
+    if (!hasLogicGlyph(value))
+        return null;
+    const hasOr = value.includes(OP_SYMBOLS.or);
+    const hasAnd = value.includes(OP_SYMBOLS.and);
+    if (hasOr && hasAnd)
+        return null; // 체인 혼합 — 서버가 400 을 내는 문법 위반
+    const chain = hasAnd ? "and" : "or";
+    const rawTerms = hasOr || hasAnd ? value.split(hasAnd ? OP_SYMBOLS.and : OP_SYMBOLS.or) : [value];
+    const terms = [];
+    for (const rawTerm of rawTerms) {
+        const trimmed = trimTerm(rawTerm);
+        const negated = trimmed.startsWith(OP_SYMBOLS.not);
+        const text = negated ? trimTerm(trimmed.slice(OP_SYMBOLS.not.length)) : trimmed;
+        // 빈 항(선두·말단·연속 체인 연산자)과 항 중간 not 글리프는 문법 위반
+        if (text === "" || text.includes(OP_SYMBOLS.not))
+            return null;
+        terms.push({ text, not: negated });
+    }
+    if (terms.length === 0 || terms.length > MAX_TEXT_LOGIC_TERMS)
+        return null;
+    return { chain, terms };
+}
+/**
+ * 항 하나의 매칭 — 백엔드 `TextFilter._apply_term` 과 의미를 맞춘다.
+ *
+ * - `fuzzy` 는 검색어와 셀 **양쪽 공백을 제거**하고 대소문자 무시 (DB "듀 벨" ↔ 검색 "듀벨")
+ * - `equals`/`notEquals` 는 대소문자를 **구분한다** (SQL `column_str == value`)
+ * - 나머지 부분일치 계열은 소문자 비교
+ */
+export function matchTextTerm(cellValue, term, operator) {
+    // NULL 은 SQL 3값 논리상 어떤 조건에도 걸리지 않는다 (부정 항은 결합부에서 처리)
+    if (cellValue === null || cellValue === undefined)
+        return false;
+    const cell = String(cellValue);
+    const lowerCell = cell.toLowerCase();
+    const lowerTerm = term.toLowerCase();
+    switch (operator) {
+        case "fuzzy": {
+            const needle = normalizeSearchText(term);
+            // 공백만인 검색어는 정규화하면 빈 문자열이 된다. 서버 `create_fuzzy_conditions` 는
+            // 이때 조건을 만들지 않고 `ILIKE '%  %'`(원문 그대로 contains) 로 폴백한다 —
+            // 빈 needle 을 includes 하면 전행이 통과해 서버와 달라진다.
+            if (needle === "")
+                return lowerCell.includes(lowerTerm);
+            return normalizeSearchText(cell).includes(needle);
+        }
+        case "equals":
+            return cell === term;
+        case "notEquals":
+            return cell !== term;
+        case "startsWith":
+            return lowerCell.startsWith(lowerTerm);
+        case "endsWith":
+            return lowerCell.endsWith(lowerTerm);
+        case "notContains":
+            return !lowerCell.includes(lowerTerm);
+        case "contains":
+        default:
+            return lowerCell.includes(lowerTerm);
+    }
+}
+/**
+ * `empty` 판정 — 백엔드는 NULL, 빈 문자열, 공백만 셋 다 "비어 있음"으로 본다.
+ * 값이 false(문자열 "false"/"False"/"0" 포함)면 방향이 뒤집힌다.
+ */
+export function matchTextEmpty(cellValue, filterValue) {
+    const wantEmpty = !(filterValue === false ||
+        filterValue === "false" ||
+        filterValue === "False" ||
+        filterValue === "0");
+    const empty = isBlank(cellValue);
+    return wantEmpty ? empty : !empty;
+}
+/**
+ * 텍스트 필터 전체 — 논리식이면 항별로 매칭 후 결합한다.
+ * 서버 `TextFilter.apply` 와 같은 순서: 글리프 파싱 -> 항별 조건 -> or/and 결합.
+ */
+export function matchText(cellValue, filterValue, operator) {
+    if (operator === "empty" || operator === "notEmpty") {
+        // notEmpty 는 방향이 고정 — empty 에 false 를 준 것과 같다
+        return operator === "notEmpty"
+            ? matchTextEmpty(cellValue, false)
+            : matchTextEmpty(cellValue, filterValue);
+    }
+    if (typeof filterValue !== "string") {
+        return matchTextTerm(cellValue, String(filterValue ?? ""), operator);
+    }
+    const parsed = parseTextLogic(filterValue);
+    if (parsed === null)
+        return matchTextTerm(cellValue, filterValue, operator);
+    // NULL 셀은 부정 항으로도 살아나지 않는다 — 서버의 부정 조건이 NULL 을 걸러내는 것과 같다
+    if (cellValue === null || cellValue === undefined)
+        return false;
+    const results = parsed.terms.map((term) => {
+        const matched = matchTextTerm(cellValue, term.text, operator);
+        return term.not ? !matched : matched;
+    });
+    return parsed.chain === "and" ? results.every(Boolean) : results.some(Boolean);
+}

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

@@ -0,0 +1,6 @@
+export { useTableSearch } from "./useTableSearch";
+export { useTableData, resolveMode, type UseTableDataOptions } from "./useTableData";
+export { useDataTable } from "./useDataTable";
+export { useGrouping, type UseGroupingOptions, type GroupingResult, } from "./useGrouping";
+export { useUrlSync, readUrlSearchState, encodeUrlSearchState, decodeUrlSearchState, DEFAULT_URL_PARAM_KEY, type UseUrlSyncOptions, type UrlSync, } from "./useUrlSync";
+export { useSearchHistory, type SearchHistory, type UseSearchHistoryOptions, } from "./useSearchHistory";

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

@@ -0,0 +1,6 @@
+export { useTableSearch } from "./useTableSearch";
+export { useTableData, resolveMode } from "./useTableData";
+export { useDataTable } from "./useDataTable";
+export { useGrouping, } from "./useGrouping";
+export { useUrlSync, readUrlSearchState, encodeUrlSearchState, decodeUrlSearchState, DEFAULT_URL_PARAM_KEY, } from "./useUrlSync";
+export { useSearchHistory, } from "./useSearchHistory";

package/dist/core/src/hooks/useDataTable.d.ts

@@ -0,0 +1,13 @@
+import { type RowData } from "@tanstack/react-table";
+import type { DataTable, DataTableOptions } from "../types/table";
+/**
+ * 3층 — 1·2층을 TanStack 인스턴스에 연결한다. **선택 사항이다.**
+ *
+ * 필터·정렬·페이지는 이미 2층이 계산했으므로 TanStack 에는 `manual*` 을 켜서
+ * 다시 계산하지 않게 한다. 두 번 거르면 client 모드에서 결과가 달라진다
+ * (2층은 서버 의미, TanStack 은 자체 filterFn 의미로 걸기 때문).
+ *
+ * `search` / `data` 는 프로퍼티로 얹기만 하고 `getState()` 는 감싸지 않는다 —
+ * 기존 `extendTableInstance` 는 렌더마다 `getState` 를 다시 감싸 래퍼가 누적됐다.
+ */
+export declare function useDataTable<T extends RowData>(options: DataTableOptions<T>): DataTable<T>;

package/dist/core/src/hooks/useDataTable.js

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { getCoreRowModel, useReactTable, } from "@tanstack/react-table";
+import { columnKey } from "../columns/deriveOperators";
+/**
+ * 비어 있는 grouping 상태의 **고정 참조**.
+ *
+ * `search.params.grouping ?? []` 처럼 렌더마다 새 배열을 넘기면 TanStack 의
+ * row model 메모가 매번 무효화되고, 그 `onChange` 가 `_autoResetExpanded()` 를
+ * 큐에 넣어 상태를 바꾼다 -> 다시 렌더 -> 또 새 배열 -> **무한 루프**로 탭이 멈춘다.
+ * (실측: 그룹 펼치기·단순 리렌더 양쪽에서 렌더러 정지)
+ */
+const EMPTY_GROUPING = [];
+/** `meta.isVisible === false` 인 컬럼의 기본 숨김 맵 */
+function defaultVisibility(columns) {
+    const map = {};
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (!id)
+            continue;
+        if (column.meta?.forceHidden || column.meta?.isVisible === false)
+            map[id] = false;
+    }
+    return map;
+}
+/**
+ * 값 보관 전용 컬럼 — 토글·프리셋보다 우선해 **항상** 숨긴다.
+ * `isVisible: false` 는 기본값일 뿐이라 사용자가 되살릴 수 있지만,
+ * 헤더가 없는 컬럼(통합 cascade 에 흡수된 레벨 등)은 되살아나면 빈 열이 된다.
+ */
+function forceHiddenColumns(columns) {
+    const map = {};
+    for (const column of columns) {
+        const id = columnKey(column);
+        if (id && column.meta?.forceHidden)
+            map[id] = false;
+    }
+    return map;
+}
+/**
+ * 3층 — 1·2층을 TanStack 인스턴스에 연결한다. **선택 사항이다.**
+ *
+ * 필터·정렬·페이지는 이미 2층이 계산했으므로 TanStack 에는 `manual*` 을 켜서
+ * 다시 계산하지 않게 한다. 두 번 거르면 client 모드에서 결과가 달라진다
+ * (2층은 서버 의미, TanStack 은 자체 filterFn 의미로 걸기 때문).
+ *
+ * `search` / `data` 는 프로퍼티로 얹기만 하고 `getState()` 는 감싸지 않는다 —
+ * 기존 `extendTableInstance` 는 렌더마다 `getState` 를 다시 감싸 래퍼가 누적됐다.
+ */
+export function useDataTable(options) {
+    const { columns, search, data, fieldErrors, tableOptions } = options;
+    const sorting = useMemo(() => search.params.sorting.map((s) => ({ id: s.id, desc: s.desc })), [search.params.sorting]);
+    const onSortingChange = (updater) => {
+        const next = typeof updater === "function" ? updater(sorting) : updater;
+        search.setSorting(next.map((s) => ({ id: s.id, desc: s.desc })));
+    };
+    // 컬럼 표시는 **완전 제어형**이다. onChange 를 연결하지 않고 state 만 밀어넣으면
+    // 컬럼 메뉴의 "숨기기"와 프리셋 복원이 다음 렌더에 되돌아간다.
+    const baseVisibility = useMemo(() => defaultVisibility(columns), [columns]);
+    const forced = useMemo(() => forceHiddenColumns(columns), [columns]);
+    const [columnVisibility, setColumnVisibility] = useState(() => ({
+        ...baseVisibility,
+        ...tableOptions?.initialState?.columnVisibility,
+        ...forced,
+    }));
+    // 컬럼 정의가 바뀌면 새 기본값을 합치되 사용자가 바꾼 값은 유지한다
+    useEffect(() => {
+        setColumnVisibility((prev) => {
+            const merged = { ...baseVisibility, ...prev, ...forced };
+            const prevKeys = Object.keys(prev);
+            const same = Object.keys(merged).length === prevKeys.length &&
+                prevKeys.every((key) => merged[key] === prev[key]);
+            return same ? prev : merged;
+        });
+    }, [baseVisibility, forced]);
+    const onColumnVisibilityChange = useCallback((updater) => {
+        setColumnVisibility((prev) => ({
+            ...(typeof updater === "function" ? updater(prev) : updater),
+            // 프리셋 복원은 맵을 통째로 교체하므로 여기서 다시 고정한다
+            ...forced,
+        }));
+    }, [forced]);
+    // state 객체도 매 렌더 새로 만들지 않는다 — 위와 같은 이유다
+    const state = useMemo(() => ({
+        sorting,
+        columnVisibility,
+        pagination: search.params.pagination,
+        globalFilter: search.params.globalFilter,
+        grouping: search.params.grouping ?? EMPTY_GROUPING,
+        ...tableOptions?.state,
+    }), [sorting, columnVisibility, search.params, tableOptions?.state]);
+    const table = useReactTable({
+        data: data.rows,
+        columns: columns,
+        getCoreRowModel: getCoreRowModel(),
+        // 그룹핑·확장은 `useGrouping` 이 따로 계산한다. TanStack 의 grouped/expanded
+        // row model 을 등록하면 쓰지도 않는 auto-reset 기계장치만 딸려온다 —
+        // 필요하면 호출부가 `tableOptions` 로 직접 넣는다.
+        // 2층이 이미 필터·정렬·페이지를 적용했다. 여기서 또 거르면 이중 적용이 된다.
+        manualFiltering: true,
+        manualSorting: true,
+        manualPagination: true,
+        rowCount: data.total,
+        ...tableOptions,
+        state,
+        onSortingChange,
+        onColumnVisibilityChange,
+    });
+    return useMemo(() => Object.assign(table, { search, data, fieldErrors }), [table, search, data, fieldErrors]);
+}

package/dist/core/src/hooks/useGrouping.d.ts

@@ -0,0 +1,33 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TableColumnDefs } from "../types/column";
+import type { ExpandState, FlatItem, GroupTreeNode } from "../types/grouping";
+import type { AggregationDef, AggregationSpec } from "../client/aggregate";
+import type { Registry } from "../registry";
+export interface UseGroupingOptions<T extends RowData> {
+    rows: T[];
+    columns?: TableColumnDefs<T>;
+    /** 상위 → 하위 순서의 그룹 컬럼. 비어 있으면 그룹핑을 하지 않는다 */
+    grouping: string[];
+    aggregation?: AggregationSpec;
+    /** 집계 레지스트리 — 미지정 시 전역 `aggregations`. mui 는 `useAggregations()`(Provider) 결과를 넘긴다 */
+    aggregations?: Registry<AggregationDef>;
+    labelOf?: (columnId: string, value: unknown) => string | undefined;
+    /** 마운트 시 전부 펼침 */
+    initialExpanded?: boolean;
+    includeLeaves?: boolean;
+}
+export interface GroupingResult<T extends RowData> {
+    /** 그룹 트리 — 그룹핑이 꺼져 있으면 빈 배열 */
+    tree: Array<GroupTreeNode<T>>;
+    /** 화면 순서대로 평탄화된 항목 */
+    items: Array<FlatItem<T>>;
+    expand: ExpandState;
+    readonly enabled: boolean;
+}
+/**
+ * 클라이언트 그룹핑 — 이미 필터·정렬이 끝난 행을 트리로 묶는다.
+ *
+ * 서버 그룹핑(`groupExpansion` — 최상위 `path: []` / 경로 확장)과 결과 모양을 맞춰 두었기
+ * 때문에, 나중에 서버 모드를 붙여도 렌더러는 그대로 쓸 수 있다.
+ */
+export declare function useGrouping<T extends RowData>(options: UseGroupingOptions<T>): GroupingResult<T>;