@iyulab/flex-table 0.31.5 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## [0.33.0] - 2026-09-08
+
+### Fixed
+
+- **A page could outlive the result set that holds it, leaving an empty table next
+  to a non-zero total and a pager pointing at a page that no longer exists.**
+  Three axes change the size of a result set, and only two of them moved the page.
+
+  - **`useODataSource`: changing `fixedFilter` now resets the page to `0`**, the
+    same way `setSearch` and `onSortChange` already did. Narrowing a filter while
+    on page 5 previously kept the old `$skip` and asked for a range the new set
+    does not have. Comparison is by value, so passing a fresh object literal on
+    every render does not reset anything on its own, and the reset does not run on
+    mount, so it never overrides `initialPage`.
+  - **`useODataSource`: a response reporting fewer rows than the current page needs
+    falls back to the last page that exists.** A result set can shrink without
+    being asked. Reaching that state costs one extra request, only in that case;
+    the page only ever moves down, so it cannot loop.
+  - **`useArraySource`: paging is clamped to the array passed in.** Shrinking the
+    array — the in-memory equivalent of narrowing a filter — falls back to the last
+    page that exists instead of rendering nothing.
+
+  Shrinking clamps rather than resets on purpose: an array or a total can change on
+  a routine refresh, and resetting there would move the page out from under the
+  reader. The dividing question is whether the change was asked for.
+
+### Changed
+
+- **`computeArrayView` returns the last page that exists when given a page past the
+  end**, instead of an empty array. It is exported, so a direct caller had the same
+  defect; returning nothing for an out-of-range page was never the intended
+  contract.
+
+### Internal
+
+- First hook tests for this package — everything here was pure functions until now,
+  so contracts the README states had no executed evidence behind them. They cover
+  the reset and clamp on both hooks, request abort on re-request and on unmount,
+  `onUnauthorized` firing on `401`/`403` but not on `500`, initial state being read
+  on first render only, and `refresh` being a no-op on the array source.
+
+## [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,13 +584,50 @@ const source = useODataSource('/api/orders', {
 |---|---|---|
 | `pageSize` | `20` | Rows per page |
 | `defaultOrderBy` | — | Initial `$orderby` (e.g. `'name asc'`) |
-| `fixedFilter` | — | Filter always applied in addition to search |
+| `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. Changing it resets the page to 0 — see below |
 | `baseUrl` | `window.location.origin` | Override the request origin (proxy/BFF setups) |
 | `fetcher` | global `fetch` | Custom transport — pass a wrapper that injects auth headers |
 | `onUnauthorized` | — | Called on `401`/`403` responses, before the generic error is set |
 
 `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.
 
+Changing `fixedFilter` resets the page to `0`, the same way `setSearch` and `onSortChange`
+already do. All three change the size of the result set, so keeping the old `$skip` would
+request a range the new set no longer has — a filter applied while on page 5 would come back
+empty. Comparison is by value, not by reference, so passing a fresh object literal on every
+render (`fixedFilter={{ IsActive: true }}`) does not reset anything on its own. The reset
+does not run on mount, so it never overrides `initialPage`.
+
+If a response reports fewer rows than the current page needs, the page falls back to the
+last page that exists — a result set can shrink without you asking (another user deleting
+rows, a `refresh` landing after a change), and holding the old `$skip` would leave an empty
+table next to a non-zero total. Reaching that state costs one extra request, only in that
+case; the page only ever moves down, so it cannot loop.
+
+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 |
@@ -626,6 +663,12 @@ returns the **same shape** as `useODataSource` — `data`/`totalCount`/`loading`
 `page`/`setPage`/`sortCriteria`/`onSortChange`/`search`/`setSearch`/`refresh` — so the
 same `<FlexTableReact dataMode="server" ...>` binding code works with either source.
 
+Paging is clamped to the data you pass: if the array shrinks below the current page — the
+in-memory equivalent of narrowing a filter, usually `rows.filter(...)` upstream — the hook
+falls back to the last page that exists instead of rendering an empty table. It only ever
+moves the page down, so an array that changes identity on every poll without changing length
+leaves the current page alone.
+
 Reach for this when the rows come from a client-side join a server query can't express —
 e.g. a lookup table whose display name lives on a different endpoint than the row itself,
 so search/sort has to run after the join, in memory:
@@ -648,6 +691,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,50 +1,55 @@
 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-6fVz-CLu.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 }) {
 	let c = n.trim().toLowerCase(), l = c ? t.filter((e) => (s ? s(e) : Object.values(e)).some((e) => e != null && String(e).toLowerCase().includes(c))) : t, u = l;
 	r.length > 0 && (u = e(l, r, o ?? []).map((e) => l[e]));
-	let d = u.length, f = i * a;
+	let d = u.length, f = d === 0 ? 0 : Math.ceil(d / a) - 1, p = Math.min(Math.max(i, 0), f) * a;
 	return {
-		data: u.slice(f, f + a),
+		data: u.slice(p, p + a),
 		totalCount: d
 	};
 }
 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
-	]);
-	return {
-		data: b,
-		totalCount: x,
+		f,
+		p
+	]), E = T === 0 ? 0 : Math.ceil(T / s) - 1;
+	return h > E && g(E), {
+		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/array/use-array-source.hooks.test.d.ts

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

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-6fVz-CLu.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/odata/use-odata-source.hooks.test.d.ts

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

package/dist/use-odata-source-6fVz-CLu.js

@@ -0,0 +1,102 @@
+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, L] = r(v);
+	v !== I && (L(v), k(0));
+	let R = n(null), z = e(() => {
+		F((e) => e + 1);
+	}, []), B = e((e) => {
+		N(e), k(0);
+	}, []), V = e((e) => {
+		let t = e.detail?.criteria;
+		t && (j(t), k(0));
+	}, []);
+	return t(() => {
+		R.current?.abort();
+		let e = new AbortController();
+		R.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) => {
+			if (e.signal.aborted) return;
+			let n = t["@odata.count"] ?? 0;
+			b(t.value ?? t), S(n), E(null);
+			let r = n === 0 ? 0 : Math.ceil(n / l) - 1;
+			O > r && k(r);
+		}).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: V,
+		search: M,
+		setSearch: B,
+		refresh: z
+	};
+}
+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.33.0",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",
@@ -88,6 +88,7 @@
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.7",
     "@typescript-eslint/eslint-plugin": "^8.64.0",
     "@typescript-eslint/parser": "^8.64.0",
     "eslint": "^10.1.0",
@@ -95,6 +96,7 @@
     "jsdom": "^29.1.1",
     "loupe": "^3.2.1",
     "react": "^19.2.7",
+    "react-dom": "^19.2.8",
     "strip-literal": "^3.1.0",
     "typescript": "~5.7.0",
     "vite": "^8.1.4",

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 };