kokotable 0.95.0

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

@@ -0,0 +1,434 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { isListValueOperator, isValuelessOperator } from "../types/operators";
+import { columnKey, deriveOperators, resolveOperatorOptions, resolveVariant, } from "../columns/deriveOperators";
+import { pruneCascadeValues, resolveCascadeOptions } from "../columns/cascade";
+import { expandSorting } from "../columns/expandSorting";
+import { deriveAggregation } from "../client/aggregate";
+import { toListFilterValue } from "../filters/list";
+import { isFilterValueEmpty, wireOperator } from "../filters/kind";
+import { filterKindMap } from "../filters/codec";
+import { DEFAULT_PAGINATION, DEFAULT_PAGE_SIZE } from "../defaults";
+function baseState() {
+    return {
+        columnFilters: [],
+        columnFilterFns: {},
+        globalFilter: "",
+        pagination: DEFAULT_PAGINATION,
+        sorting: [],
+    };
+}
+/**
+ * 초기 상태.
+ *
+ * 연산자는 **컬럼 선언에서 그대로 읽어** 처음부터 채운다. 원본은 이걸 effect 로
+ * 뒤늦게 채우느라(`useFilterFnsInit`) 그동안 첫 조회를 `filterFnsReady` 로 막아야
+ * 했는데, 컬럼 정의는 렌더 시점에 이미 존재하므로 기다릴 이유가 없다.
+ */
+function initialState(columns, initial, initialOperators) {
+    return {
+        ...baseState(),
+        ...initial,
+        columnFilterFns: {
+            ...deriveOperators(columns),
+            ...initialOperators,
+            ...initial?.columnFilterFns,
+        },
+        // 참조 공유를 끊는다 — 날짜 범위처럼 배열 값을 제자리에서 바꾸는 입력이
+        // 초기값까지 함께 바꾸면 reset() 이 돌아갈 곳을 잃는다.
+        columnFilters: (initial?.columnFilters ?? []).map((f) => ({
+            ...f,
+            value: Array.isArray(f.value) ? [...f.value] : f.value,
+        })),
+        sorting: [...(initial?.sorting ?? [])],
+        pagination: { ...(initial?.pagination ?? DEFAULT_PAGINATION) },
+    };
+}
+/**
+ * 미입력 필터를 걷어낸 비교·요청용 형태.
+ *
+ * 값을 쓰지 않는 연산자(`empty`/`isEmpty`/`hasChild` …)의 항목은 **값이 비어 있어도
+ * 남긴다** — 서버는 `value None` 인 필터를 통째로 건너뛰므로 항목이 사라지면
+ * 연산자만 바뀌고 아무 일도 일어나지 않는다. 값은 `true` 로 정규화한다
+ * (`false` 는 방향 반전이라 그대로 둔다).
+ *
+ * 컬럼에 kind 가 있으면 "비어 있음" 은 `kind.isEmpty`, "값 없는 연산자" 는
+ * `operators[op].valueless` 가 정한다. 연산자가 kind 에 없으면 공통 규칙으로 떨어진다.
+ */
+function normalizeFilters(filters, operators, kinds) {
+    const result = [];
+    for (const filter of filters) {
+        if (!filter)
+            continue;
+        const operator = operators[filter.id];
+        const kind = kinds?.get(filter.id);
+        const def = kind && operator ? kind.operators[operator] : undefined;
+        const unset = isFilterValueEmpty(kind, filter.value);
+        const valueless = def ? def.valueless === true : !!operator && isValuelessOperator(operator);
+        if (valueless) {
+            result.push(unset ? { ...filter, value: true } : filter);
+            continue;
+        }
+        if (!unset)
+            result.push(filter);
+    }
+    return result;
+}
+/**
+ * 요청에 실을 필터 값 정규화 — 리스트 연산자의 스칼라 값을 `[value]` 로 감싼다.
+ *
+ * 단일 select 컬럼의 기본 연산자가 `inArray` 인데 값이 문자열 하나면, 서버
+ * `ListFilter.apply` 가 문자열을 글자 단위로 쪼개 enum 컬럼에서 500 을 낸다.
+ * 센티널(`EMPTY`/`_ALL_SELECTED`)도 배열 원소로 감싸져 의미가 보존된다.
+ *
+ * 컬럼 kind 에 연산자가 있으면 `operators[op].serialize` 가 값을 정한다 (내장 enum 류가
+ * 같은 배열 감싸기를 한다). 값 없는 연산자의 `true` 는 직렬화하지 않는다.
+ */
+function toRequestFilters(filters, operators, kinds) {
+    let changed = false;
+    const result = filters.map((filter) => {
+        const operator = operators[filter.id];
+        const kind = kinds?.get(filter.id);
+        const def = kind && operator ? kind.operators[operator] : undefined;
+        if (def) {
+            if (!def.serialize || def.valueless)
+                return filter;
+            const value = def.serialize(filter.value);
+            if (value === filter.value)
+                return filter;
+            changed = true;
+            return { ...filter, value };
+        }
+        if (!operator || !isListValueOperator(operator) || Array.isArray(filter.value))
+            return filter;
+        changed = true;
+        return { ...filter, value: toListFilterValue(filter.value) };
+    });
+    return changed ? result : filters;
+}
+/** 요청에 실을 연산자 이름 — kind 가 `wire` 를 선언한 것만 바꾼다. 바뀐 것이 없으면 같은 참조 */
+function toRequestOperators(operators, kinds) {
+    if (kinds.size === 0)
+        return operators;
+    let changed = false;
+    const result = {};
+    for (const [id, operator] of Object.entries(operators)) {
+        const wire = wireOperator(kinds.get(id), operator);
+        if (wire !== operator)
+            changed = true;
+        result[id] = wire;
+    }
+    return changed ? result : operators;
+}
+function setEntry(filters, id, value) {
+    const rest = filters.filter((f) => f.id !== id);
+    if (value === undefined)
+        return rest;
+    return [...rest, { id, value }];
+}
+/** 부분 상태 병합 — `columnFilterFns` 만 얕게 합친다 */
+function mergeState(base, partial) {
+    const next = { ...base, ...partial };
+    if (partial.columnFilterFns) {
+        next.columnFilterFns = { ...base.columnFilterFns, ...partial.columnFilterFns };
+    }
+    return next;
+}
+/**
+ * 1층 — 검색 상태. **테이블 인스턴스를 만들지 않는다.**
+ *
+ * 반환값이 `FilterSource` 를 만족하므로 필터 패널이 테이블 없이 바로 붙는다.
+ * 페이지네이션 UI 는 총 건수가 필요하므로 `paginationSource(search, data)` 로
+ * 2층과 합쳐 넘긴다.
+ */
+export function useTableSearch(options) {
+    const { columns, initial, initialOperators, onApply, debounceMs = 0, globalFilterApplyOnChange = false, } = options;
+    const initialRef = useRef(null);
+    if (initialRef.current === null) {
+        initialRef.current = initialState(columns, initial, initialOperators);
+    }
+    const [draft, setDraftState] = useState(() => initialState(columns, initialRef.current));
+    const [params, setParamsState] = useState(() => initialRef.current);
+    // 같은 이벤트 핸들러 안에서 setDraft 직후 apply() 를 불러도 최신 값을 보게 한다
+    const draftRef = useRef(draft);
+    draftRef.current = draft;
+    // 정렬·페이지처럼 draft 를 거치지 않는 조작이 **적용된 값** 위에서 일어나게 한다
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
+    /**
+     * 컬럼에서 파생된 기본 연산자. 상태 밑에 깔아 두는 이유는 컬럼이 나중에
+     * 추가돼도 그 컬럼만 연산자가 비지 않게 하기 위해서다.
+     */
+    const derived = useMemo(() => deriveOperators(columns), [columns]);
+    const operators = useMemo(() => ({ ...derived, ...params.columnFilterFns }), [derived, params.columnFilterFns]);
+    const draftOperators = useMemo(() => ({ ...derived, ...draft.columnFilterFns }), [derived, draft.columnFilterFns]);
+    const columnsById = useMemo(() => {
+        const map = new Map();
+        for (const column of columns) {
+            const key = columnKey(column);
+            if (key)
+                map.set(key, column);
+        }
+        return map;
+    }, [columns]);
+    /** 컬럼 id → 필터 kind (kind 를 선언한 컬럼만). 요청 조립·미입력 판정의 근거 */
+    const kindsById = useMemo(() => filterKindMap(columns), [columns]);
+    /**
+     * 다음 draft 를 **호출 시점에 즉시** 계산해 ref 와 state 에 함께 넣는다.
+     *
+     * 원본은 updater 안에서 ref 를 갱신했는데, React 는 updater 를 지연 실행할 수
+     * 있어(eager state 최적화는 큐가 비어 있을 때만 걸린다) 같은 핸들러에서
+     * `setFilter()` 직후 `apply()` 를 부르면 ref 가 낡은 값을 들고 있었다.
+     */
+    const setDraft = useCallback((updater) => {
+        const next = typeof updater === "function" ? updater(draftRef.current) : updater;
+        draftRef.current = next;
+        setDraftState(next);
+    }, []);
+    const setParams = useCallback((next) => {
+        draftRef.current = next;
+        setDraftState(next);
+        paramsRef.current = next;
+        setParamsState(next);
+    }, []);
+    const patchParams = useCallback((partial) => setParams(mergeState(paramsRef.current, partial)), [setParams]);
+    const patchDraft = useCallback((partial) => setDraft((prev) => mergeState(prev, partial)), [setDraft]);
+    /**
+     * 즉시 반영 조작(정렬·페이지·그룹) — **적용된 params 위에** 해당 필드만 갱신한다.
+     *
+     * draft 위에 얹으면 미적용 필터·연산자·전역검색이 정렬 클릭에 딸려 나간다
+     * (기존 구현과 koko 모두 있던 결함). draft 는 유지하되 같은 필드는 같은 값으로
+     * 맞춰 두어 isDirty 가 정렬·페이지 때문에 튀지 않게 한다.
+     */
+    const setImmediate = useCallback((partial) => {
+        const nextParams = { ...paramsRef.current, ...partial };
+        paramsRef.current = nextParams;
+        setParamsState(nextParams);
+        const nextDraft = { ...draftRef.current, ...partial };
+        draftRef.current = nextDraft;
+        setDraftState(nextDraft);
+    }, []);
+    // onApply 는 렌더마다 새 함수일 수 있다 — 타이머 콜백이 최신 것을 보게 ref 로 읽는다
+    const onApplyRef = useRef(onApply);
+    onApplyRef.current = onApply;
+    /** 즉시 적용 — 타이머와 무관한 본체 */
+    const applyNow = useCallback(() => {
+        // 검색은 항상 첫 페이지부터 — 3페이지에서 조건을 바꾸면 빈 화면이 나온다
+        const next = {
+            ...draftRef.current,
+            pagination: {
+                pageIndex: 0,
+                pageSize: draftRef.current.pagination?.pageSize ?? DEFAULT_PAGE_SIZE,
+            },
+        };
+        paramsRef.current = next;
+        setParamsState(next);
+        draftRef.current = next;
+        setDraftState(next);
+        onApplyRef.current?.(next);
+    }, []);
+    // ── debounce ──
+    // applyOnChange 컬럼·전역검색이 글자마다 조회를 내지 않도록 마지막 입력 뒤 `ms` 를 기다린다.
+    // 타이머는 하나뿐이다 — 어느 컬럼이 걸었든 apply 는 draft 전체를 싣기 때문에 합쳐도 결과가 같다.
+    const timerRef = useRef(null);
+    const [pendingApply, setPendingApply] = useState(false);
+    const cancelPending = useCallback(() => {
+        if (timerRef.current !== null) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        setPendingApply(false);
+    }, []);
+    const scheduleApply = useCallback((ms) => {
+        if (!(ms > 0)) {
+            cancelPending();
+            applyNow();
+            return;
+        }
+        if (timerRef.current !== null)
+            clearTimeout(timerRef.current);
+        setPendingApply(true);
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            setPendingApply(false);
+            applyNow();
+        }, ms);
+    }, [cancelPending, applyNow]);
+    // 언마운트 시 대기 중인 조회를 버린다 — 사라진 화면의 요청이 나가면 안 된다
+    useEffect(() => () => {
+        if (timerRef.current !== null)
+            clearTimeout(timerRef.current);
+        timerRef.current = null;
+    }, []);
+    /** 명시 apply — 대기 중인 타이머를 취소하고 즉시 */
+    const apply = useCallback(() => {
+        cancelPending();
+        applyNow();
+    }, [cancelPending, applyNow]);
+    const reset = useCallback(() => {
+        cancelPending();
+        setParams(initialState(columns, initialRef.current));
+    }, [cancelPending, setParams, columns]);
+    const setFilter = useCallback((id, value) => {
+        const spec = columnsById.get(id)?.filter;
+        const immediate = spec?.applyOnChange === true;
+        setDraft((prev) => {
+            const columnFilters = setEntry(prev.columnFilters, id, value);
+            // 상위가 바뀌면 하위 값이 더 이상 고를 수 없는 것이 될 수 있다.
+            // effect 로 뒤늦게 지우면 그 사이 잘못된 조건으로 조회가 나가므로
+            // **값을 넣는 그 자리에서** 정리한다.
+            return {
+                ...prev,
+                columnFilters: pruneCascadeValues(columnFilters, resolveCascadeOptions(columns, columnFilters)),
+            };
+        });
+        // 컬럼 단위 지연이 옵션 기본값보다 우선한다
+        if (immediate)
+            scheduleApply(spec?.debounceMs ?? debounceMs);
+    }, [columnsById, columns, setDraft, scheduleApply, debounceMs]);
+    /**
+     * 연산자 변경도 **draft 에 쌓인다.** 즉시 반영하면 검색 버튼을 누르지 않았는데
+     * 결과가 바뀐다.
+     *
+     * 값을 쓰지 않는 연산자(`empty`/`isEmpty`/`hasChild` 등)로 바꿀 때는 필터 항목을
+     * 함께 만들어 준다. 서버도 클라이언트도 `columnFilters` 를 훑어 조건을 거니까,
+     * 항목이 없으면 연산자만 바뀌고 아무 일도 일어나지 않는다.
+     * (값 `true` = 비어 있는 행 / 자식 있는 행, `false` = 반대)
+     */
+    const setOperator = useCallback((id, operator) => {
+        setDraft((prev) => {
+            const previous = (prev.columnFilterFns[id] ?? derived[id] ?? "fuzzy");
+            // kind 가 연산자를 알면 kind 의 valueless 가, 모르면 공통 목록이 정한다
+            const kind = kindsById.get(id);
+            const valueless = (op) => {
+                const def = kind?.operators[op];
+                return def ? def.valueless === true : isValuelessOperator(op);
+            };
+            const wasValueless = valueless(previous);
+            const nowValueless = valueless(operator);
+            let columnFilters = prev.columnFilters;
+            if (nowValueless && !wasValueless) {
+                columnFilters = setEntry(columnFilters, id, true);
+            }
+            else if (!nowValueless && wasValueless) {
+                // 값 없는 연산자에서 빠져나올 때 남은 true 를 지운다 — 안 지우면
+                // 텍스트 입력에 "true" 가 들어 있는 것처럼 동작한다
+                columnFilters = setEntry(columnFilters, id, undefined);
+            }
+            return {
+                ...prev,
+                columnFilters,
+                columnFilterFns: { ...prev.columnFilterFns, [id]: operator },
+            };
+        });
+    }, [setDraft, derived, kindsById]);
+    const setGlobalFilter = useCallback((value) => {
+        setDraft((prev) => ({ ...prev, globalFilter: value }));
+        if (globalFilterApplyOnChange)
+            scheduleApply(debounceMs);
+    }, [setDraft, globalFilterApplyOnChange, scheduleApply, debounceMs]);
+    // 정렬·페이지·그룹은 검색 버튼을 거치지 않는 즉시 반영 조작이다
+    const setSorting = useCallback((sorting) => setImmediate({ sorting }), [setImmediate]);
+    const setGrouping = useCallback((grouping) => setImmediate({ grouping }), [setImmediate]);
+    const setPagination = useCallback((pagination) => setImmediate({ pagination }), [setImmediate]);
+    const setPageIndex = useCallback((pageIndex) => setPagination({ ...paramsRef.current.pagination, pageIndex }), [setPagination]);
+    const setPageSize = useCallback((pageSize) => setPagination({ pageIndex: 0, pageSize }), [setPagination]);
+    const isDirty = useMemo(() => {
+        // 정렬·페이지는 즉시 반영이므로 비교에서 뺀다 — 넣으면 항상 "검색 필요"가 된다.
+        // 연산자는 **넣는다** — fuzzy 에서 equals 로 바꾸면 값이 그대로여도 결과가 달라진다.
+        const key = (state, ops) => JSON.stringify({
+            columnFilters: normalizeFilters(state.columnFilters, ops, kindsById),
+            globalFilter: state.globalFilter,
+            columnFilterFns: state.columnFilterFns,
+        });
+        return key(draft, draftOperators) !== key(params, operators);
+    }, [draft, params, draftOperators, operators, kindsById]);
+    // 요청용 필터 — 페이지만 바뀌면 `params.columnFilters` 참조가 유지되므로 재계산되지
+    // 않는다. 2층이 필터·정렬 결과를 따로 메모이즈할 수 있는 근거다.
+    const requestFilters = useMemo(() => toRequestFilters(normalizeFilters(params.columnFilters, operators, kindsById), operators, kindsById), [params.columnFilters, operators, kindsById]);
+    // 요청용 연산자 — kind 가 `wire` 로 서버 이름을 달리 정한 것만 바뀐다 (내장 kind 는 그대로)
+    const requestOperators = useMemo(() => toRequestOperators(operators, kindsById), [operators, kindsById]);
+    // 통합 컬럼(`meta.sortExpandsTo`) 정렬은 실제 필드로 펼쳐 싣는다. UI 상태는 그대로다.
+    const requestSorting = useMemo(() => expandSorting(params.sorting, columns), [params.sorting, columns]);
+    const derivedAggregation = useMemo(() => deriveAggregation(columns), [columns]);
+    const request = useMemo(() => {
+        const grouping = params.grouping && params.grouping.length > 0 ? params.grouping : undefined;
+        return {
+            columnFilters: requestFilters,
+            // 원본과 같이 **전체 맵**을 싣는다. 값 없는 연산자나 서버가 컬럼 기본값을
+            // 참조하는 경로가 있어 부분 맵으로는 의미가 달라진다.
+            columnFilterFns: requestOperators,
+            globalFilter: params.globalFilter || undefined,
+            pagination: params.pagination,
+            sorting: requestSorting.length > 0 ? requestSorting : undefined,
+            grouping: params.grouping,
+            virtualColumns: params.virtualColumns,
+            // 그룹핑할 때만 집계를 싣는다 — 서버 `aggregation` 은 그룹 헤더/노드의 aggregates 용이다
+            aggregation: grouping ? params.aggregation ?? derivedAggregation : undefined,
+        };
+    }, [params, requestOperators, requestFilters, requestSorting, derivedAggregation]);
+    /** 편집 중인 값 기준으로 좁혀진 하위 선택지 */
+    const cascadeOptions = useMemo(() => resolveCascadeOptions(columns, draft.columnFilters), [columns, draft.columnFilters]);
+    const getFilterFields = useCallback(() => {
+        const fields = [];
+        for (const column of columns) {
+            const id = columnKey(column);
+            if (!id)
+                continue;
+            const spec = column.filter;
+            if (spec?.hidden || column.meta?.forceHidden)
+                continue;
+            const entry = draft.columnFilters.find((f) => f.id === id);
+            const narrowed = cascadeOptions.get(id);
+            fields.push({
+                id,
+                header: column.filterLabel ?? column.header,
+                variant: resolveVariant(column),
+                kind: kindsById.get(id),
+                // cascade 컬럼은 상위 선택에 따라 선택지가 줄어든다
+                meta: narrowed ? { ...column.meta, selectOptions: narrowed } : column.meta,
+                value: entry?.value,
+                onChange: (value) => setFilter(id, value),
+                // 편집 중인 값을 봐야 한다 — params 를 보면 방금 바꾼 연산자가 반영되지 않는다
+                operator: draftOperators[id] ?? "fuzzy",
+                onOperatorChange: (operator) => setOperator(id, operator),
+                operatorOptions: resolveOperatorOptions(column),
+                apply: spec?.applyOnChange ? apply : undefined,
+                // kind 별 값 타입으로 좁혀진 render 를 필드 계약(unknown) 으로 넘긴다
+                render: spec?.render,
+                detail: spec?.detail,
+            });
+        }
+        return fields;
+    }, [columns, draft.columnFilters, draftOperators, cascadeOptions, kindsById, setFilter, setOperator, apply]);
+    return useMemo(() => ({
+        columns,
+        draft,
+        params,
+        initialParams: initialRef.current,
+        operators,
+        draftOperators,
+        setFilter,
+        setOperator,
+        setGlobalFilter,
+        setSorting,
+        setGrouping,
+        setPagination,
+        setPageIndex,
+        setPageSize,
+        setDraft,
+        setParams,
+        patchParams,
+        patchDraft,
+        apply,
+        pendingApply,
+        reset,
+        isDirty,
+        request,
+        getFilterFields,
+    }), [
+        columns, draft, params, operators, draftOperators, setFilter, setOperator,
+        setGlobalFilter, setSorting, setGrouping, setPagination, setPageIndex,
+        setPageSize, setDraft, setParams, patchParams, patchDraft, apply, pendingApply, reset, isDirty,
+        request, getFilterFields,
+    ]);
+}

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

@@ -0,0 +1,64 @@
+import type { RowData } from "@tanstack/react-table";
+import type { SearchState, TableSearch } from "../types/search";
+import type { TableColumnDefs } from "../types/column";
+export declare const DEFAULT_URL_PARAM_KEY = "tp";
+/**
+ * 검색 상태 → URL-safe base64 (`tp=` 값).
+ *
+ * `useUrlSync` 가 URL 에 쓰는 것과 같은 인코딩이다. 공개하는 이유: 공유 링크를
+ * 현재 창의 URL 이 아니라 **다른 경로**로 만들어야 하는 호출부(알림 공유, 서버
+ * 렌더 링크 등)가 `window.location` 을 거치지 않고 값을 만들 수 있어야 한다.
+ * 실패(순환 참조 등)하면 빈 문자열.
+ */
+export declare function encodeUrlSearchState(state: Partial<SearchState>): string;
+/** `encodeUrlSearchState` 의 역 — koko 인코딩만 읽는다. 구 포맷 폴백은 `readUrlSearchState` 가 한다 */
+export declare function decodeUrlSearchState(text: string): Partial<SearchState> | undefined;
+export interface ReadUrlSearchStateOptions {
+    /** 기본 `tp` */
+    paramKey?: string;
+    /**
+     * `paramKey` 가 없을 때 차례로 훑는 구 스킴 키 (기본 `["filter"]` —
+     * ERP `utils/tableUrlParams.ts` 의 `filter=` + `btoa(encodeURIComponent(JSON))`).
+     * 빈 배열이면 구 스킴을 읽지 않는다.
+     */
+    legacyParamKeys?: readonly string[];
+    /**
+     * 구 포맷 정규화(ISO 시각 → `YYYY-MM-DD`) 에 쓸 컬럼. 주면 date/datetime 컬럼에만
+     * 적용하고, 없으면 ISO 패턴 + 날짜 연산자 항목에만 적용한다.
+     */
+    columns?: TableColumnDefs<any>;
+    /** 구 포맷으로 읽힌 값의 정규화를 끈다 (기본 false) */
+    skipLegacyNormalize?: boolean;
+}
+/**
+ * URL 에서 검색 조건을 읽는다 — `useTableSearch({ initial })` 에 그대로 넘긴다.
+ *
+ * 읽기를 훅에서 분리한 이유: 기존 `useUrlTableParams` 는 초기값을 넘겨줄 방법이
+ * 없어 `connectParams(params, setParams)` 를 **렌더 도중** 호출했다. 읽기가
+ * 순수 함수면 그 우회가 통째로 사라진다.
+ *
+ * 구 포맷 호환: koko 인코딩(UTF-8 base64) 으로 읽히지 않으면
+ * `decodeLegacyTableParams` 로 폴백하고, `paramKey` 가 없으면 `legacyParamKeys`
+ * (기본 `filter`) 를 읽는다. 구 포맷으로 읽힌 값은 `normalizeLegacySearchState` 로
+ * koko `SearchState` 모양에 맞춘다. 첫 인자는 기존처럼 문자열(paramKey) 도 받는다.
+ */
+export declare function readUrlSearchState(paramKeyOrOptions?: string | ReadUrlSearchStateOptions): Partial<SearchState> | undefined;
+export interface UseUrlSyncOptions {
+    enabled?: boolean;
+    paramKey?: string;
+    /** popstate 복원 시 구 스킴 키도 읽는다 (기본 `["filter"]`). 쓰기는 항상 `paramKey` 로만 */
+    legacyParamKeys?: readonly string[];
+}
+export interface UrlSync {
+    /** 현재 조건이 담긴 공유용 URL */
+    shareUrl: string;
+    /** 클립보드 복사 — 실패하면 false */
+    copyShareUrl: () => Promise<boolean>;
+}
+/**
+ * URL 동기화 애드온 — 1층이 독립했으므로 바깥에서 얹는 훅이 된다.
+ *
+ * - `params` 가 바뀌면 URL 을 갱신한다 (`replaceState`)
+ * - 뒤로/앞으로 가면 URL 을 읽어 `setParams` 한다
+ */
+export declare function useUrlSync<T extends RowData>(search: TableSearch<T>, options?: UseUrlSyncOptions): UrlSync;

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

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { DEFAULT_LEGACY_PARAM_KEYS, decodeLegacyTableParams, normalizeLegacySearchState, } from "../contracts/legacyUrl";
+export const DEFAULT_URL_PARAM_KEY = "tp";
+/**
+ * 검색 상태 → URL-safe base64 (`tp=` 값).
+ *
+ * `useUrlSync` 가 URL 에 쓰는 것과 같은 인코딩이다. 공개하는 이유: 공유 링크를
+ * 현재 창의 URL 이 아니라 **다른 경로**로 만들어야 하는 호출부(알림 공유, 서버
+ * 렌더 링크 등)가 `window.location` 을 거치지 않고 값을 만들 수 있어야 한다.
+ * 실패(순환 참조 등)하면 빈 문자열.
+ */
+export function encodeUrlSearchState(state) {
+    return encode(state);
+}
+/** URL-safe base64 */
+function encode(state) {
+    try {
+        const json = JSON.stringify(state);
+        const bytes = new TextEncoder().encode(json);
+        let binary = "";
+        for (const byte of bytes)
+            binary += String.fromCharCode(byte);
+        return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    }
+    catch {
+        return "";
+    }
+}
+/** `encodeUrlSearchState` 의 역 — koko 인코딩만 읽는다. 구 포맷 폴백은 `readUrlSearchState` 가 한다 */
+export function decodeUrlSearchState(text) {
+    return decode(text);
+}
+function decode(text) {
+    try {
+        const base64 = text.replace(/-/g, "+").replace(/_/g, "/");
+        const binary = atob(base64);
+        const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+        // fatal: 잘못된 UTF-8 바이트열(기존 btoa(JSON) 의 Latin1 문자)은 조용히 U+FFFD 로
+        // 바꾸지 말고 실패시켜, readUrlSearchState 가 구 포맷 디코더로 폴백하게 한다
+        const json = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * URL 에서 검색 조건을 읽는다 — `useTableSearch({ initial })` 에 그대로 넘긴다.
+ *
+ * 읽기를 훅에서 분리한 이유: 기존 `useUrlTableParams` 는 초기값을 넘겨줄 방법이
+ * 없어 `connectParams(params, setParams)` 를 **렌더 도중** 호출했다. 읽기가
+ * 순수 함수면 그 우회가 통째로 사라진다.
+ *
+ * 구 포맷 호환: koko 인코딩(UTF-8 base64) 으로 읽히지 않으면
+ * `decodeLegacyTableParams` 로 폴백하고, `paramKey` 가 없으면 `legacyParamKeys`
+ * (기본 `filter`) 를 읽는다. 구 포맷으로 읽힌 값은 `normalizeLegacySearchState` 로
+ * koko `SearchState` 모양에 맞춘다. 첫 인자는 기존처럼 문자열(paramKey) 도 받는다.
+ */
+export function readUrlSearchState(paramKeyOrOptions = DEFAULT_URL_PARAM_KEY) {
+    if (typeof window === "undefined")
+        return undefined;
+    const options = typeof paramKeyOrOptions === "string" ? { paramKey: paramKeyOrOptions } : paramKeyOrOptions;
+    const { paramKey = DEFAULT_URL_PARAM_KEY, legacyParamKeys = DEFAULT_LEGACY_PARAM_KEYS, columns, skipLegacyNormalize = false, } = options;
+    const normalize = (state) => skipLegacyNormalize ? state : normalizeLegacySearchState(state, columns);
+    const searchParams = new URLSearchParams(window.location.search);
+    const encoded = searchParams.get(paramKey);
+    if (encoded) {
+        const own = decode(encoded);
+        if (own)
+            return own;
+        const legacy = decodeLegacyTableParams(encoded);
+        return legacy ? normalize(legacy) : undefined;
+    }
+    for (const key of legacyParamKeys) {
+        if (key === paramKey)
+            continue;
+        const value = searchParams.get(key);
+        if (!value)
+            continue;
+        const legacy = decodeLegacyTableParams(value);
+        if (legacy)
+            return normalize(legacy);
+    }
+    return undefined;
+}
+function writeUrl(state, paramKey, push) {
+    const encoded = encode(state);
+    if (!encoded)
+        return;
+    const url = new URL(window.location.href);
+    url.searchParams.set(paramKey, encoded);
+    const method = push ? "pushState" : "replaceState";
+    window.history[method](window.history.state, "", url.toString());
+}
+/**
+ * URL 동기화 애드온 — 1층이 독립했으므로 바깥에서 얹는 훅이 된다.
+ *
+ * - `params` 가 바뀌면 URL 을 갱신한다 (`replaceState`)
+ * - 뒤로/앞으로 가면 URL 을 읽어 `setParams` 한다
+ */
+export function useUrlSync(search, options = {}) {
+    const { enabled = true, paramKey = DEFAULT_URL_PARAM_KEY, legacyParamKeys } = options;
+    const [shareUrl, setShareUrl] = useState("");
+    // popstate 로 들어온 변경을 다시 URL 에 쓰지 않기 위한 가드
+    const fromUrlRef = useRef(false);
+    const searchRef = useRef(search);
+    searchRef.current = search;
+    useEffect(() => {
+        if (!enabled || typeof window === "undefined")
+            return;
+        if (fromUrlRef.current) {
+            fromUrlRef.current = false;
+            return;
+        }
+        writeUrl(search.params, paramKey, false);
+        setShareUrl(window.location.href);
+    }, [enabled, paramKey, search.params]);
+    useEffect(() => {
+        if (!enabled || typeof window === "undefined")
+            return;
+        const onPopState = () => {
+            const restored = readUrlSearchState({
+                paramKey,
+                legacyParamKeys,
+                columns: searchRef.current.columns,
+            });
+            if (!restored)
+                return;
+            fromUrlRef.current = true;
+            searchRef.current.setParams({ ...searchRef.current.params, ...restored });
+        };
+        window.addEventListener("popstate", onPopState);
+        return () => window.removeEventListener("popstate", onPopState);
+    }, [enabled, paramKey, legacyParamKeys]);
+    const copyShareUrl = useCallback(async () => {
+        try {
+            await navigator.clipboard.writeText(window.location.href);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, []);
+    return { shareUrl, copyShareUrl };
+}

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

@@ -0,0 +1,38 @@
+export * from "./types";
+export * from "./defaults";
+export * from "./utils/getValue";
+export * from "./utils/compare";
+export * from "./filters/text";
+export * from "./filters/number";
+export * from "./filters/date";
+export * from "./filters/list";
+export * from "./filters/relation";
+export * from "./filters/linear";
+export * from "./filters/schedule";
+export * from "./filters/registry";
+export * from "./filters/kind";
+export * from "./filters/kinds";
+export * from "./filters/describe";
+export * from "./filters/codec";
+export { formatLocalDate, toDateOnly, ISO_DATETIME } from "./utils/dateText";
+export * from "./client/runClientQuery";
+export * from "./client/aggregate";
+export * from "./client/groupRows";
+export * from "./types/grouping";
+export * from "./pivot/transforms";
+export * from "./pivot/runClientPivot";
+export * from "./adapters/sources";
+export * from "./columns/deriveOperators";
+export * from "./columns/labels";
+export * from "./columns/cascade";
+export * from "./columns/ColumnBuilder";
+export * from "./columns/expandSorting";
+export { createColumnHelper, type ColumnHelper, type BaseColumnHelper, type ColumnHelperDeps, type ColumnParams, type ColumnFactory, type CompositeComponent, type CommonCodeLookup, type CommonCodeOption, type UserLookup, } from "./columns/helper";
+export * from "./hooks";
+export * from "./contracts";
+export { createLocalStoragePresetStore, createMemoryPresetStore, loadDefaultPreset, newPresetId, type TablePreset, type PresetInput, type PresetScope, type PresetStore, type MemoryPresetStoreOptions, type LocalStoragePresetStoreOptions, } from "./contracts/presetStore";
+export { usePresets, type UsePresetsOptions, type Presets, type SavePresetOptions, type PresetPatch, } from "./contracts/usePresets";
+export * from "./types/definition";
+export * from "./hooks/useTableFromDefinition";
+export * from "./registry";
+export * from "./contract";