@iyulab/flex-table 0.29.0 → 0.31.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.31.1] - 2026-09-01
+
+### Fixed
+
+- **`0.31.0`'s release pipeline never actually published to npm** — the repo's
+  `preversion` guard script assumed a monorepo layout this repo doesn't have,
+  so the workflow's own version-sync step failed before publishing. No package
+  code changed; this release exists to get `0.31.0`'s content onto the
+  registry with a working pipeline.
+
+## [0.31.0] - 2026-08-31
+
+### Added
+
+- **`useArraySource`, a client-array sibling to `useODataSource`.** `useODataSource`
+  is server-mode only, so a lookup table needing a client-side join (a display
+  field living on a different endpoint than the row) had no library-level path
+  and required reimplementing filter/sort/pagination by hand. `useArraySource`
+  returns the exact same shape (`data`/`totalCount`/`loading`/`error`/`page`/
+  `setPage`/`sortCriteria`/`onSortChange`/`search`/`setSearch`/`refresh`) driven
+  off a local array instead of a fetch, so the same `<FlexTableReact
+  dataMode="server" ...>` binding code works with either source. Sorting reuses
+  the grid's own `computeSortedIndices` for value-aware (not string) comparison.
+  New `./array` subpath export, mirroring `./odata`'s shape.
+
+## [0.30.0] - 2026-08-28
+
+### Added
+
+- **`buildSearchExpression` and `parseOrderBy` are now exported from
+  `./odata`.** Both were already implemented as pure, tested functions used
+  internally by `useODataSource`, but the public barrel only re-exported
+  the hook itself. A consumer needing the same `$search`/`$orderby`
+  encoding without the pagination hook (a typeahead, a standalone sort
+  control) had to reimplement the OData 4.0 search-quoting workaround
+  from scratch.
+
 ## [0.29.0] - 2026-08-28
 
 ### Added

package/README.md

@@ -606,6 +606,53 @@ The hook returns:
 
 Terms are always quoted because OData 4.0 only allows letters in an unquoted `searchWord`, so `2026` or `ZT-E2E-A` would be rejected by servers that follow it (4.01 relaxed this, but [Microsoft.OData still lexes as 4.0](https://github.com/OData/odata.net/issues/2445)). Quoting keeps any term valid regardless of server version. Since a `$search` phrase cannot contain `"` and OData defines no escape for it, double quotes are stripped from the term.
 
+The quoting/escaping logic above is also available standalone as `buildSearchExpression(term)`, for consumers that need the same `$search` encoding without the pagination hook (e.g. a typeahead/combobox that isn't a table). `parseOrderBy(orderBy)` (`'a asc, b desc'` → `SortCriteria[]`) is exported the same way, for consumers driving a sort UI that isn't `useODataSource` either:
+
+```ts
+import { buildSearchExpression, parseOrderBy } from '@iyulab/flex-table/odata';
+
+buildSearchExpression('red shirt'); // '"red" AND "shirt"'
+buildSearchExpression('');          // undefined
+parseOrderBy('name desc');          // [{ key: 'name', direction: 'desc' }]
+```
+
+### Array Source Hook (React)
+
+`useArraySource(data, options)` runs search/sort/pagination over an in-memory array and
+returns the **same shape** as `useODataSource` — `data`/`totalCount`/`loading`/`error`/
+`page`/`setPage`/`sortCriteria`/`onSortChange`/`search`/`setSearch`/`refresh` — so the
+same `<FlexTableReact dataMode="server" ...>` binding code works with either source.
+
+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:
+
+```tsx
+import { useArraySource } from '@iyulab/flex-table/array';
+
+const joined = useMemo(
+  () => seasonPrices.map(p => ({ ...p, productName: productsById[p.productId]?.name ?? '' })),
+  [seasonPrices, productsById]
+);
+
+const source = useArraySource(joined, {
+  pageSize: 20,
+  columns, // pass the same ColumnDefinition[] used by <FlexTableReact> for value-aware sort
+});
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `pageSize` | `20` | Rows per page |
+| `defaultOrderBy` | — | Initial sort (e.g. `'name asc'`), same syntax as `useODataSource` |
+| `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 |
+
+The returned fields mean the same thing as `useODataSource`'s, except `totalCount` is the
+count after search (not a server-reported total), and `loading`/`error` are always
+`false`/`null` — there's no request to fail. `refresh` is a no-op kept only so a
+"refresh" button wired unconditionally against either hook doesn't need a branch.
+
 ## Development
 
 ```bash

package/dist/array/index.d.ts

@@ -0,0 +1,3 @@
+export { useArraySource, computeArrayView } from './use-array-source.js';
+export type { UseArraySourceOptions, UseArraySourceResult } from './types.js';
+export type { ComputeArrayViewOptions } from './use-array-source.js';

package/dist/array/index.js

@@ -0,0 +1,51 @@
+import { t as e } from "../sorting-CjfjRxwL.js";
+import { n as t } from "../use-odata-source-5gOJiMFj.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;
+	return {
+		data: u.slice(f, f + 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 t = e.detail?.criteria;
+		t && (m(t), f(0));
+	}, []), y = n(() => {}, []), { data: b, totalCount: x } = r(() => a(e, {
+		search: h,
+		sortCriteria: p,
+		page: d,
+		pageSize: s,
+		columns: l,
+		searchFields: u
+	}), [
+		e,
+		h,
+		p,
+		d,
+		s,
+		l,
+		u
+	]);
+	return {
+		data: b,
+		totalCount: x,
+		loading: !1,
+		error: null,
+		page: d,
+		setPage: f,
+		sortCriteria: p,
+		onSortChange: v,
+		search: h,
+		setSearch: _,
+		refresh: y
+	};
+}
+//#endregion
+export { a as computeArrayView, o as useArraySource };

package/dist/array/types.d.ts

@@ -0,0 +1,39 @@
+import type { SortCriteria } from '../core/sorting.js';
+export interface UseArraySourceOptions<T> {
+    /** 페이지당 행 수. `useODataSource`와 동일 기본값. */
+    pageSize?: number;
+    /** 초기 정렬(`'a asc, b desc'` 형식, `useODataSource`와 동일 문법). */
+    defaultOrderBy?: string;
+    /**
+     * 타입 인지 정렬 비교(숫자/불리언/날짜/텍스트)에 쓸 컬럼 정의. 생략하면 전부
+     * 텍스트로 비교한다(숫자 컬럼도 문자열 정렬 순서를 따름) — 그리드에 이미 넘기는
+     * `columns`를 그대로 전달하면 된다.
+     */
+    columns?: import('../models/types.js').ColumnDefinition<T>[];
+    /**
+     * 자유 텍스트 검색이 대조할 값들을 행에서 뽑아낸다. 생략하면 행의 모든 값
+     * (`Object.values`)을 대상으로 한다 — 서버 read 모델에 없는 클라이언트 조인
+     * 파생 필드(예: 조인해 붙인 상품명)도 이 행 객체에 실제로 들어있는 한 기본
+     * 동작만으로 검색된다. 명시적으로 검색 범위를 좁히거나 넓히고 싶을 때만 지정.
+     */
+    searchFields?: (row: T) => Array<string | number | boolean | null | undefined>;
+}
+export interface UseArraySourceResult<T> {
+    /** 현재 페이지의 행(검색+정렬 적용 후 slice). */
+    data: T[];
+    /** 검색+정렬 적용 후, 페이지 나누기 전의 총 건수(`useODataSource`의 `@odata.count`와 동일 의미). */
+    totalCount: number;
+    /** 항상 `false` — 로컬 배열은 동기 처리라 로딩 상태가 없다. `useODataSource`와의 반환 형태 동일성을 위해 유지. */
+    loading: boolean;
+    /** 항상 `null` — 로컬 배열 처리는 실패하지 않는다. 위와 같은 이유로 유지. */
+    error: string | null;
+    page: number;
+    setPage: (page: number) => void;
+    sortCriteria: SortCriteria[];
+    onSortChange: (e: CustomEvent) => void;
+    setSearch: (term: string) => void;
+    search: string;
+    /** no-op — 로컬 배열에는 다시 불러올 원격 상태가 없다. 소비자가 `useODataSource`와
+     *  같은 자리에 무조건 배선한 refresh 버튼이 있어도 안전하게 아무 일도 하지 않는다. */
+    refresh: () => void;
+}

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

@@ -0,0 +1,39 @@
+import type { SortCriteria } from '../core/sorting.js';
+import type { ColumnDefinition, DataRow } from '../models/types.js';
+import type { UseArraySourceOptions, UseArraySourceResult } from './types.js';
+export interface ComputeArrayViewOptions<T> {
+    search: string;
+    sortCriteria: SortCriteria[];
+    page: number;
+    pageSize: number;
+    columns?: ColumnDefinition<T>[];
+    searchFields?: (row: T) => Array<string | number | boolean | null | undefined>;
+}
+/**
+ * `useArraySource`의 검색→정렬→페이지 파이프라인을 React 없이 순수하게 계산한다
+ * (훅은 이 함수를 `useMemo`로 감싸기만 한다) — React 훅 렌더 인프라 없이 이 패키지의
+ * 다른 순수 헬퍼(`buildSearchExpression`/`parseOrderBy`)와 같은 방식으로 단위
+ * 테스트하기 위해 분리했다.
+ *
+ * 정렬은 그리드 자신의 클라이언트 정렬 파이프라인이 쓰는 `computeSortedIndices`를
+ * 그대로 재사용한다 — `columns`를 넘기면 숫자/날짜/불리언도 값 기준으로 비교되고,
+ * 생략하면 전부 텍스트 비교로 낮아진다.
+ */
+export declare function computeArrayView<T extends DataRow>(data: T[], { search, sortCriteria, page, pageSize, columns, searchFields }: ComputeArrayViewOptions<T>): {
+    data: T[];
+    totalCount: number;
+};
+/**
+ * 클라이언트 배열(이미 메모리에 있는 데이터, 흔히 여러 출처를 조인해 만든 파생
+ * 행 배열) 전용 React 훅. `useODataSource`와 **같은 반환 형태**(`data`/`totalCount`/
+ * `loading`/`error`/`page`/`setPage`/`sortCriteria`/`onSortChange`/`search`/
+ * `setSearch`/`refresh`)를 제공해, `dataMode="server"` + `<FlexTableReact>` 배선
+ * 코드를 서버·클라이언트 소스 사이에서 그대로 재사용할 수 있게 한다.
+ *
+ * `useODataSource`가 서버에 `$search`/`$orderby`/`$top`/`$skip`을 보내 처리를
+ * 위임하는 것과 달리, 이 훅은 검색·정렬·페이지 나누기를 전부 로컬에서 계산한다
+ * (`computeArrayView`) — 서버 read 모델에 없는 클라이언트 조인 파생 필드(예: 별도
+ * 엔드포인트에서 가져와 붙인 상품명)로 검색/정렬해야 해서 서버 쿼리로 표현할 수
+ * 없는 lookup 테이블에 쓴다.
+ */
+export declare function useArraySource<T extends DataRow = DataRow>(data: T[], options?: UseArraySourceOptions<T>): UseArraySourceResult<T>;

package/dist/array/use-array-source.test.d.ts

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