@iyulab/flex-table 0.31.5 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.32.0] - 2026-09-08
+
+### Added
+
+- **Both source hooks accept their initial page, search term and sort.**
+  `useODataSource` and `useArraySource` now take `initialPage` (zero-based, the same
+  axis as the returned `page`/`setPage`), `initialSearch` and `initialSort`. They are
+  read on the first render only — the same contract `defaultOrderBy` has always had —
+  and every default matches today's behaviour exactly, so existing callers are
+  unaffected.
+
+  Restoring a list the way the user left it — returning from a detail screen, or
+  restoring from a URL — was previously only expressible as a mount effect calling
+  `setPage()` after the hook had already fetched page 0. That shape carries two problems
+  a caller cannot solve from outside: the first request is issued and then discarded,
+  and `setSearch()` resets the page by design, so "restore the page, then set the search
+  term" has no ordering that works.
+
+  `initialSort` takes precedence over `defaultOrderBy` — the two express the same thing
+  in different notations, and the array form is the shape `onSortChange` hands back, so a
+  stored sort round-trips without being re-serialized. An empty `initialSort: []` means
+  *no sort* and does not fall back to `defaultOrderBy`.
+
+### Internal
+
+- Both hooks now resolve their initial state through one shared function rather than two
+  copies, so the two sources cannot drift apart on the shape the README declares they
+  share.
+
 ## [0.31.5] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -584,6 +584,9 @@ const source = useODataSource('/api/orders', {
 |---|---|---|
 | `pageSize` | `20` | Rows per page |
 | `defaultOrderBy` | — | Initial `$orderby` (e.g. `'name asc'`) |
+| `initialPage` | `0` | Initial page, **zero-based** — the same axis as the returned `page`/`setPage`, and `$skip` is `page * pageSize` |
+| `initialSearch` | `''` | Initial search term |
+| `initialSort` | — | Initial sort as `SortCriteria[]`. Takes precedence over `defaultOrderBy` — it is the shape `onSortChange` hands you, so a stored sort round-trips without re-serializing it |
 | `fixedFilter` | — | Filter always applied in addition to search |
 | `baseUrl` | `window.location.origin` | Override the request origin (proxy/BFF setups) |
 | `fetcher` | global `fetch` | Custom transport — pass a wrapper that injects auth headers |
@@ -591,6 +594,27 @@ const source = useODataSource('/api/orders', {
 
 `fetcher`/`onUnauthorized` should be stable references (e.g. wrap in `useCallback`) — they are intentionally excluded from the hook's internal effect dependencies to avoid refetch loops on every render.
 
+The three `initial*` options are read **on the first render only** (the same contract
+`defaultOrderBy` has always had); use `setPage`/`setSearch` to move afterwards. Reach for
+them when a list has to come back the way the user left it — going to a detail screen and
+returning, or restoring from a URL:
+
+```tsx
+const source = useODataSource('/api/orders', {
+  pageSize: 20,
+  initialPage: restored.page,       // no mount effect, no discarded first request
+  initialSearch: restored.search,
+  initialSort: restored.sort,
+});
+```
+
+Setting them up front rather than calling `setPage(...)` from a mount effect matters for
+two reasons that are otherwise hard to work around: the effect version issues a request for
+page 0 that is thrown away as soon as the second one lands, and `setSearch` resets the page
+to 0 by design — so "restore the page, then set the search term" is not expressible from
+outside the hook. Passing an empty `initialSort: []` means *no sort*, and does not fall
+back to `defaultOrderBy`.
+
 The hook returns:
 
 | Field | Description |
@@ -648,6 +672,7 @@ const source = useArraySource(joined, {
 |---|---|---|
 | `pageSize` | `20` | Rows per page |
 | `defaultOrderBy` | — | Initial sort (e.g. `'name asc'`), same syntax as `useODataSource` |
+| `initialPage` / `initialSearch` / `initialSort` | `0` / `''` / — | Same names, same meanings, same first-render-only contract as `useODataSource` — the shared shape covers initial state too, so swapping sources needs no other change |
 | `columns` | — | `ColumnDefinition[]` — enables value-aware sort (numbers/dates/booleans compared by value, not as text). Omit and every column sorts as text. |
 | `searchFields` | all values | `(row) => value[]` — narrows or widens what free-text search matches; the default searches every property on the row, including client-joined ones |
 

package/dist/array/index.js

@@ -1,5 +1,5 @@
 import { t as e } from "../sorting-CjfjRxwL.js";
-import { n as t } from "../use-odata-source-5gOJiMFj.js";
+import { r as t } from "../use-odata-source--wXFYeqA.js";
 import { useCallback as n, useMemo as r, useState as i } from "react";
 //#region src/array/use-array-source.ts
 function a(t, { search: n, sortCriteria: r, page: i, pageSize: a, columns: o, searchFields: s }) {
@@ -12,39 +12,44 @@ function a(t, { search: n, sortCriteria: r, page: i, pageSize: a, columns: o, se
 	};
 }
 function o(e, o = {}) {
-	let { pageSize: s = 20, defaultOrderBy: c, columns: l, searchFields: u } = o, [d, f] = i(0), [p, m] = i(() => c ? t(c) : []), [h, g] = i(""), _ = n((e) => {
-		g(e), f(0);
-	}, []), v = n((e) => {
+	let { pageSize: s = 20, defaultOrderBy: c, initialPage: l = 0, initialSearch: u = "", initialSort: d, columns: f, searchFields: p } = o, m = t({
+		defaultOrderBy: c,
+		initialPage: l,
+		initialSearch: u,
+		initialSort: d
+	}), [h, g] = i(m.page), [_, v] = i(m.sortCriteria), [y, b] = i(m.search), x = n((e) => {
+		b(e), g(0);
+	}, []), S = n((e) => {
 		let t = e.detail?.criteria;
-		t && (m(t), f(0));
-	}, []), y = n(() => {}, []), { data: b, totalCount: x } = r(() => a(e, {
-		search: h,
-		sortCriteria: p,
-		page: d,
+		t && (v(t), g(0));
+	}, []), C = n(() => {}, []), { data: w, totalCount: T } = r(() => a(e, {
+		search: y,
+		sortCriteria: _,
+		page: h,
 		pageSize: s,
-		columns: l,
-		searchFields: u
+		columns: f,
+		searchFields: p
 	}), [
 		e,
+		y,
+		_,
 		h,
-		p,
-		d,
 		s,
-		l,
-		u
+		f,
+		p
 	]);
 	return {
-		data: b,
-		totalCount: x,
+		data: w,
+		totalCount: T,
 		loading: !1,
 		error: null,
-		page: d,
-		setPage: f,
-		sortCriteria: p,
-		onSortChange: v,
-		search: h,
-		setSearch: _,
-		refresh: y
+		page: h,
+		setPage: g,
+		sortCriteria: _,
+		onSortChange: S,
+		search: y,
+		setSearch: x,
+		refresh: C
 	};
 }
 //#endregion

package/dist/array/types.d.ts

@@ -4,6 +4,16 @@ export interface UseArraySourceOptions<T> {
     pageSize?: number;
     /** 초기 정렬(`'a asc, b desc'` 형식, `useODataSource`와 동일 문법). */
     defaultOrderBy?: string;
+    /**
+     * 초기 페이지. **0-based** — `useODataSource`와 같은 축이다. 기본값 `0`.
+     *
+     * ⚠`useState`의 초기값이라 **첫 렌더에서만** 읽힌다. 이후 이동은 `setPage`.
+     */
+    initialPage?: number;
+    /** 초기 검색어. 기본값 `''`. `initialPage`와 같은 「첫 렌더에서만」 계약이다. */
+    initialSearch?: string;
+    /** 초기 정렬. 주면 `defaultOrderBy` 파싱보다 **우선**한다(`useODataSource`와 동일). */
+    initialSort?: SortCriteria[];
     /**
      * 타입 인지 정렬 비교(숫자/불리언/날짜/텍스트)에 쓸 컬럼 정의. 생략하면 전부
      * 텍스트로 비교한다(숫자 컬럼도 문자열 정렬 순서를 따름) — 그리드에 이미 넘기는

package/dist/odata/index.js

@@ -1,2 +1,2 @@
-import { n as e, r as t, t as n } from "../use-odata-source-5gOJiMFj.js";
-export { n as buildSearchExpression, e as parseOrderBy, t as useODataSource };
+import { i as e, n as t, t as n } from "../use-odata-source--wXFYeqA.js";
+export { n as buildSearchExpression, t as parseOrderBy, e as useODataSource };

package/dist/odata/types.d.ts

@@ -2,6 +2,22 @@ import type { SortCriteria } from '../core/sorting.js';
 export interface UseODataSourceOptions {
     pageSize?: number;
     defaultOrderBy?: string;
+    /**
+     * 초기 페이지. **0-based** — 반환되는 `page`/`setPage`와 같은 축이고, 요청의
+     * `$skip`은 `page * pageSize`다. 기본값 `0`.
+     *
+     * ⚠`useState`의 초기값이므로 **첫 렌더에서만** 읽힌다(`defaultOrderBy`와 같은 계약).
+     * 마운트 이후에 페이지를 옮기려면 `setPage`를 쓴다.
+     */
+    initialPage?: number;
+    /** 초기 검색어. 기본값 `''`. `initialPage`와 같은 「첫 렌더에서만」 계약이다. */
+    initialSearch?: string;
+    /**
+     * 초기 정렬. 주면 `defaultOrderBy` 파싱보다 **우선**한다 — 두 옵션은 같은 것을 서로
+     * 다른 표기로 말하고, 이쪽은 `sortCriteria`/`onSortChange`가 주고받는 모양 그대로라
+     * 저장해 둔 정렬 상태를 파싱 없이 되돌릴 수 있다.
+     */
+    initialSort?: SortCriteria[];
     fixedFilter?: Record<string, unknown>;
     /** 기본값: `window.location.origin`. 프록시/BFF 등 다른 origin으로 요청해야 할 때 지정. */
     baseUrl?: string;

package/dist/odata/use-odata-source.d.ts

@@ -17,6 +17,34 @@ import type { UseODataSourceOptions, UseODataSourceResult } from './types.js';
  * @returns `$search` 표현식, 또는 유효 토큰이 없으면 `undefined`
  */
 export declare function buildSearchExpression(term: string): string | undefined;
+/** `resolveInitialState`가 읽는 옵션 — 두 소스 훅의 옵션 타입이 공통으로 갖는 부분. */
+export interface InitialSourceStateOptions {
+    defaultOrderBy?: string;
+    initialPage?: number;
+    initialSearch?: string;
+    initialSort?: SortCriteria[];
+}
+/**
+ * 옵션에서 `page`/`search`/`sortCriteria`의 **초기값**을 뽑는다.
+ *
+ * ★**두 훅이 이 함수 하나를 공유하는 것이 요점이다.** README가 *"same shape … so the same
+ * binding code works with either source"*를 계약으로 선언하는데, 초기값 해석을 양쪽에
+ * 복제하면 그 계약이 **문장으로만** 유지된다 — 이 리포가 반복 기록한 실패 형태다.
+ * 구현이 하나면 드리프트가 없다.
+ *
+ * ⚠**`initialSort`가 `defaultOrderBy`를 이긴다.** 둘은 같은 것을 서로 다른 표기로
+ * 말하고(`SortCriteria[]` ↔ `$orderby` 문자열), 더 구체적인 쪽을 우선한다.
+ * `initialSort`는 `onSortChange`가 주는 모양 그대로라 저장해 둔 정렬을 파싱 없이 되돌린다.
+ *
+ * ⚠**React가 useState 초기값을 첫 렌더에서만 읽는다는 사실이 계약의 일부다** — 이후의
+ * 옵션 변경은 무시되고, 이동은 `setPage`/`setSearch`로 한다. `defaultOrderBy`가 이미
+ * 그렇게 동작해 왔으므로 새 규칙이 아니다.
+ */
+export declare function resolveInitialState(options: InitialSourceStateOptions): {
+    page: number;
+    search: string;
+    sortCriteria: SortCriteria[];
+};
 /**
  * OData v4 서버 사이드 데이터소스 React 훅.
  * flex-table의 dataMode="server"와 함께 사용한다.

package/dist/use-odata-source--wXFYeqA.js

@@ -0,0 +1,96 @@
+import { useCallback as e, useEffect as t, useRef as n, useState as r } from "react";
+import i from "odata-query";
+//#region src/odata/use-odata-source.ts
+function a(e) {
+	let t = e.split(/\s+/).map((e) => e.replace(/"/g, "")).filter((e) => e.length > 0);
+	if (t.length !== 0) return t.map((e) => `"${e}"`).join(" AND ");
+}
+function o(e) {
+	let { defaultOrderBy: t, initialPage: n = 0, initialSearch: r = "", initialSort: i } = e;
+	return {
+		page: n,
+		search: r,
+		sortCriteria: i ?? (t ? c(t) : [])
+	};
+}
+function s(s, c = {}) {
+	let { pageSize: l = 20, defaultOrderBy: u, initialPage: d = 0, initialSearch: f = "", initialSort: p, fixedFilter: m, baseUrl: h, fetcher: g = fetch, onUnauthorized: _ } = c, v = m ? JSON.stringify(m) : "", [y, b] = r([]), [x, S] = r(0), [C, w] = r(!1), [T, E] = r(null), D = o({
+		defaultOrderBy: u,
+		initialPage: d,
+		initialSearch: f,
+		initialSort: p
+	}), [O, k] = r(D.page), [A, j] = r(D.sortCriteria), [M, N] = r(D.search), [P, F] = r(0), I = n(null), L = e(() => {
+		F((e) => e + 1);
+	}, []), R = e((e) => {
+		N(e), k(0);
+	}, []), z = e((e) => {
+		let t = e.detail?.criteria;
+		t && (j(t), k(0));
+	}, []);
+	return t(() => {
+		I.current?.abort();
+		let e = new AbortController();
+		I.current = e, w(!0), E(null);
+		let t = A.length > 0 ? A.map((e) => `${e.key} ${e.direction}`).join(", ") : u, n = {
+			top: l,
+			skip: O * l,
+			count: !0
+		};
+		if (t && (n.orderBy = t), m && (n.filter = m), M) {
+			let e = a(M);
+			e && (n.search = e);
+		}
+		let r = i(n), o = `${h ?? window.location.origin}${s}${r}`;
+		return g(o, { signal: e.signal }).then(async (e) => {
+			if (!e.ok) {
+				(e.status === 401 || e.status === 403) && _ && _(e);
+				let t = await e.text().catch(() => ""), n = `Request failed (${e.status})`;
+				try {
+					let e = JSON.parse(t);
+					n = e?.error?.message ?? e?.message ?? n;
+				} catch {}
+				throw Error(n);
+			}
+			return e.json();
+		}).then((t) => {
+			e.signal.aborted || (b(t.value ?? t), S(t["@odata.count"] ?? 0), E(null));
+		}).catch((t) => {
+			e.signal.aborted || t.name !== "AbortError" && (E(t.message), b([]), S(0));
+		}).finally(() => {
+			e.signal.aborted || w(!1);
+		}), () => e.abort();
+	}, [
+		s,
+		O,
+		l,
+		A,
+		M,
+		v,
+		u,
+		P,
+		h
+	]), {
+		data: y,
+		totalCount: x,
+		loading: C,
+		error: T,
+		page: O,
+		setPage: k,
+		sortCriteria: A,
+		onSortChange: z,
+		search: M,
+		setSearch: R,
+		refresh: L
+	};
+}
+function c(e) {
+	return e.split(",").map((e) => {
+		let t = e.trim().split(/\s+/);
+		return {
+			key: t[0],
+			direction: t[1]?.toLowerCase() === "desc" ? "desc" : "asc"
+		};
+	});
+}
+//#endregion
+export { s as i, c as n, o as r, a as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.31.5",
+  "version": "0.32.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",

package/dist/use-odata-source-5gOJiMFj.js

@@ -1,83 +0,0 @@
-import { useCallback as e, useEffect as t, useRef as n, useState as r } from "react";
-import i from "odata-query";
-//#region src/odata/use-odata-source.ts
-function a(e) {
-	let t = e.split(/\s+/).map((e) => e.replace(/"/g, "")).filter((e) => e.length > 0);
-	if (t.length !== 0) return t.map((e) => `"${e}"`).join(" AND ");
-}
-function o(o, c = {}) {
-	let { pageSize: l = 20, defaultOrderBy: u, fixedFilter: d, baseUrl: f, fetcher: p = fetch, onUnauthorized: m } = c, h = d ? JSON.stringify(d) : "", [g, _] = r([]), [v, y] = r(0), [b, x] = r(!1), [S, C] = r(null), [w, T] = r(0), [E, D] = r(() => u ? s(u) : []), [O, k] = r(""), [A, j] = r(0), M = n(null), N = e(() => {
-		j((e) => e + 1);
-	}, []), P = e((e) => {
-		k(e), T(0);
-	}, []), F = e((e) => {
-		let t = e.detail?.criteria;
-		t && (D(t), T(0));
-	}, []);
-	return t(() => {
-		M.current?.abort();
-		let e = new AbortController();
-		M.current = e, x(!0), C(null);
-		let t = E.length > 0 ? E.map((e) => `${e.key} ${e.direction}`).join(", ") : u, n = {
-			top: l,
-			skip: w * l,
-			count: !0
-		};
-		if (t && (n.orderBy = t), d && (n.filter = d), O) {
-			let e = a(O);
-			e && (n.search = e);
-		}
-		let r = i(n), s = `${f ?? window.location.origin}${o}${r}`;
-		return p(s, { signal: e.signal }).then(async (e) => {
-			if (!e.ok) {
-				(e.status === 401 || e.status === 403) && m && m(e);
-				let t = await e.text().catch(() => ""), n = `Request failed (${e.status})`;
-				try {
-					let e = JSON.parse(t);
-					n = e?.error?.message ?? e?.message ?? n;
-				} catch {}
-				throw Error(n);
-			}
-			return e.json();
-		}).then((t) => {
-			e.signal.aborted || (_(t.value ?? t), y(t["@odata.count"] ?? 0), C(null));
-		}).catch((t) => {
-			e.signal.aborted || t.name !== "AbortError" && (C(t.message), _([]), y(0));
-		}).finally(() => {
-			e.signal.aborted || x(!1);
-		}), () => e.abort();
-	}, [
-		o,
-		w,
-		l,
-		E,
-		O,
-		h,
-		u,
-		A,
-		f
-	]), {
-		data: g,
-		totalCount: v,
-		loading: b,
-		error: S,
-		page: w,
-		setPage: T,
-		sortCriteria: E,
-		onSortChange: F,
-		search: O,
-		setSearch: P,
-		refresh: N
-	};
-}
-function s(e) {
-	return e.split(",").map((e) => {
-		let t = e.trim().split(/\s+/);
-		return {
-			key: t[0],
-			direction: t[1]?.toLowerCase() === "desc" ? "desc" : "asc"
-		};
-	});
-}
-//#endregion
-export { s as n, o as r, a as t };