@iyulab/flex-table 0.38.2 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.40.0] - 2026-09-28
+
+### Changed
+
+- 🔴 **Breaking — the React hooks moved to `./react`.** `useODataSource` and `useArraySource` (and
+  their option/result types) are now exported from `@iyulab/flex-table/react`, next to
+  `FlexTableReact`. `./odata` and `./array` keep only the pure functions — `buildSearchExpression`,
+  `parseOrderBy`, `computeArrayView`, and the new `buildODataQuery` — and no longer load React, so an
+  app without React (a typeahead that is not a table, a Lit app) can use them without installing it.
+  Before, importing `buildSearchExpression` from `./odata` required `react` statically.
+  Migration: `import { useODataSource } from '@iyulab/flex-table/odata'` →
+  `import { useODataSource } from '@iyulab/flex-table/react'` (same for `useArraySource` from
+  `./array`).
+
+- 🔴 **Breaking — column definitions use the same words as `u-rich-table`.** `header` → `label` and
+  `renderer` → `render`, so one column list reads the same in either table (`header-context-menu`'s detail likewise carries
+  `label` instead of `header`). Migration: rename the two keys
+  in your `ColumnDefinition` objects; the types reject the old names.
+- **Headers follow their values.** A header's default alignment is now the column's cell alignment,
+  so a `number` column's header is right-aligned over its right-aligned values instead of sitting
+  at the left edge (on a wide column it read as the neighbour's header). Set `headerAlign` to keep
+  a different header alignment. Cell alignment uses logical values (`text-align: end`), so
+  right-to-left locales mirror.
+
+- **The column menu, the cell context menu and the drag ghost read the shared stacking tokens.**
+  The menus sit on `--u-layer-floating` (1000 — they were at 200, below every other floating
+  surface) and the drag ghost on `--u-layer-overlay` (9999, as before), so they stack the same way
+  as popovers and dialogs from `@iyulab/components`.
+
+### Added
+
+- **`align` on `ColumnDefinition`** (`'start' | 'center' | 'end'`) — cell alignment. Default comes
+  from `type` as before (`number` → end, `boolean` → center, otherwise start); set it for a code or
+  Y/N column that is text but should center. `effectiveAlign(col)` returns what a column renders with.
+- **`buildODataQuery(state)` on `./odata`** — the step `useODataSource` runs on every request (page,
+  page size, sort, search, fixed filter → OData query string), now callable without React. A Lit
+  table or a non-table list doing server paging can send exactly the query the hook would, instead
+  of re-deriving `$top`/`$skip`/`$orderby`/`$search`. The hook now calls it.
+
+## [0.39.0] - 2026-09-27
+
+### Added
+
+- **`enabled` option on `useODataSource`** (default `true`). While `false` the hook makes no
+  request and reports `loading: true`; the first request goes out when it turns `true`, with that
+  render's conditions. For lists whose query depends on a value that arrives asynchronously (a
+  server-decided default filter, the current user, a selected parent): without it the first render
+  sent a wasted request with the wrong conditions — often the heaviest one, unfiltered — before the
+  real one. Turning it `false` mid-request cancels the request; `refresh()` does nothing while
+  disabled.
+
 ## [0.38.2] - 2026-09-24
 
 ### Fixed

package/README.md

@@ -28,9 +28,9 @@ npm install @iyulab/flex-table
   const table = document.getElementById('table');
 
   table.columns = [
-    { key: 'name', header: 'Name', type: 'text', width: 200 },
-    { key: 'age', header: 'Age', type: 'number', width: 100 },
-    { key: 'active', header: 'Active', type: 'boolean', width: 80 },
+    { key: 'name', label: 'Name', type: 'text', width: 200 },
+    { key: 'age', label: 'Age', type: 'number', width: 100 },
+    { key: 'active', label: 'Active', type: 'boolean', width: 80 },
   ];
 
   table.data = [
@@ -113,7 +113,7 @@ guarantee about a *constrained* host. `height-model.browser.test.ts` pins both s
 | `footerData` | `footer-data` | `Record<string, string>` | `null` | Footer/summary row data (keys match column keys) |
 | `emptyMessage` | `empty-message` | `string` | `'No data'` | Shown when `data` is empty |
 | `noMatchingMessage` | `no-matching-message` | `string` | `'No matching data'` | Shown when `data` has rows but every one is hidden by an active column filter |
-| `stylesheets` | — | `CSSStyleSheet[]` | `[]` | Constructable stylesheets adopted into the shadow root alongside the grid's own styles — the escape hatch for styling content a `renderer` inserts, since document CSS doesn't cross the shadow boundary. Reassigning swaps the previous set, it doesn't accumulate |
+| `stylesheets` | — | `CSSStyleSheet[]` | `[]` | Constructable stylesheets adopted into the shadow root alongside the grid's own styles — the escape hatch for styling content a `render` function inserts, since document CSS doesn't cross the shadow boundary. Reassigning swaps the previous set, it doesn't accumulate |
 
 ### Read-only Properties
 
@@ -133,19 +133,20 @@ guarantee about a *constrained* host. `height-model.browser.test.ts` pins both s
 ```typescript
 interface ColumnDefinition {
   key: string;             // Unique key matching data property names
-  header: string;          // Display header text
+  label: string;           // Column header text
   type?: ColumnType;       // 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' (any other string falls back to 'text')
   width?: number;          // Column width in pixels (default: auto)
   minWidth?: number;       // Minimum width in pixels (default: 40, enforced in rendering)
   hidden?: boolean;        // Hide column from view
   sortable?: boolean;      // Enable sorting (default: true)
-  headerAlign?: 'start' | 'center' | 'end'; // Header label alignment (default: 'start'), independent of cell content alignment
+  align?: 'start' | 'center' | 'end';       // Cell alignment (default from type: number → end, boolean → center, else start)
+  headerAlign?: 'start' | 'center' | 'end'; // Header alignment (default: the cell alignment above)
   editable?: boolean;      // Per-column edit control (follows global editable)
   pinned?: 'left' | 'right'; // Freeze column during horizontal scroll
   options?: string[] | SelectOption[]; // Allowed values for type: 'select' (SelectOption = { label, value })
   autocomplete?: boolean | 'strict'; // Suggest existing column values while editing; 'strict' rejects values not in the list
-  format?: string | ((value, row, col) => string); // Display format, see "format vs renderer" below
-  renderer?: CellRenderer; // Custom cell render: (value, row, col) => TemplateResult | string
+  format?: string | ((value, row, col) => string); // Display format, see "format vs render" below
+  render?: CellRenderer;   // Custom cell render: (value, row, col) => TemplateResult | string
   editor?: CellEditor;     // Custom cell editor: (value, row, col) => TemplateResult
   validator?: CellValidator; // Validate before commit: (value, row, col) => string | null
   conditionalRules?: ConditionalRule[]; // Per-cell style rules, see below
@@ -156,32 +157,32 @@ The `editor` callback must return a Lit `TemplateResult` containing an input ele
 
 The `validator` callback returns `null` if valid, or an error message string. On failure, the cell shows a red border for 3 seconds and a `validation-error` event is dispatched.
 
-### `format` vs `renderer`
+### `format` vs `render`
 
 Both control how a cell's raw value is displayed, but they differ in what they replace:
 
 - **`format`**: a plain string pattern (Excel-style, e.g. `'#,##0.00'`, `'0.00%'`, `'$#,##0'`, `'yyyy-MM-dd'`) or a `(value) => string` function. Only the *displayed text* changes — editing, sorting, filtering, and export all keep operating on the raw underlying value. Use this for number/date/currency display formatting.
-- **`renderer`**: a `(value, row, col) => TemplateResult | string` function that replaces the cell's rendered content entirely — badges, links, icons, multi-field composites. Sorting/filtering still use the raw value, but the visual output is fully custom.
+- **`render`**: a `(value, row, col) => TemplateResult | string` function that replaces the cell's rendered content entirely — badges, links, icons, multi-field composites. Sorting/filtering still use the raw value, but the visual output is fully custom.
 
 ```typescript
 const columns: ColumnDefinition<Order>[] = [
-  { key: 'total', header: 'Total', format: '#,##0.00' },                 // "1,234.50"
-  { key: 'placedAt', header: 'Placed', format: 'yyyy-MM-dd' },           // date pattern
-  { key: 'status', header: 'Status', renderer: (v) => html`<span class="badge badge-${v}">${v}</span>` },
+  { key: 'total', label: 'Total', format: '#,##0.00' },                 // "1,234.50"
+  { key: 'placedAt', label: 'Placed', format: 'yyyy-MM-dd' },           // date pattern
+  { key: 'status', label: 'Status', render: (v) => html`<span class="badge badge-${v}">${v}</span>` },
 ];
 ```
 
-If both are set on the same column, `renderer` takes precedence — `format` has no effect once a custom `renderer` fully controls the cell's output.
+If both are set on the same column, `render` takes precedence — `format` has no effect once a custom `render` fully controls the cell's output.
 
 ### Conditional Formatting
 
-`conditionalRules` applies a style to a cell when its `when` predicate matches — a declarative alternative to writing a `renderer` just to color-code status/threshold values:
+`conditionalRules` applies a style to a cell when its `when` predicate matches — a declarative alternative to writing a `render` function just to color-code status/threshold values:
 
 ```typescript
 const columns: ColumnDefinition<Order>[] = [
   {
     key: 'status',
-    header: 'Status',
+    label: 'Status',
     conditionalRules: [
       { when: (v) => v === 'overdue', style: { color: '#dc2626', fontWeight: 'bold' } },
       { when: (v) => v === 'paid', style: { color: '#16a34a' } },
@@ -489,8 +490,8 @@ import { FlexTableReact } from '@iyulab/flex-table/react';
 
 function App() {
   const columns = [
-    { key: 'name', header: 'Name', type: 'text' },
-    { key: 'age', header: 'Age', type: 'number' },
+    { key: 'name', label: 'Name', type: 'text' },
+    { key: 'age', label: 'Age', type: 'number' },
   ];
 
   const data = [
@@ -547,8 +548,8 @@ interface Order {
 }
 
 const columns: ColumnDefinition<Order>[] = [
-  { key: 'id', header: 'ID' },
-  { key: 'total', header: 'Total', renderer: (_value, row) => `${row.total} ${row.currency}` },
+  { key: 'id', label: 'ID' },
+  { key: 'total', label: 'Total', render: (_value, row) => `${row.total} ${row.currency}` },
 ];
 
 <FlexTableReact<Order> data={orders} columns={columns} />
@@ -566,7 +567,7 @@ import { html } from 'lit';
 table.columns = [
   {
     key: 'color',
-    header: 'Color',
+    label: 'Color',
     type: 'text',
     editor: (value) => html`
       <input class="ft-editor" type="color" .value=${String(value ?? '#000000')}
@@ -593,7 +594,7 @@ Use the `validator` callback to validate input before committing. Returns `null`
 table.columns = [
   {
     key: 'age',
-    header: 'Age',
+    label: 'Age',
     type: 'number',
     validator: (value) => {
       const n = Number(value);
@@ -612,10 +613,10 @@ Freeze columns on either side during horizontal scroll:
 
 ```typescript
 table.columns = [
-  { key: 'id', header: 'ID', pinned: 'left' },
-  { key: 'name', header: 'Name' },
+  { key: 'id', label: 'ID', pinned: 'left' },
+  { key: 'name', label: 'Name' },
   // ... many columns ...
-  { key: 'actions', header: 'Actions', pinned: 'right' },
+  { key: 'actions', label: 'Actions', pinned: 'right' },
 ];
 ```
 
@@ -668,7 +669,7 @@ table.addEventListener('sort-change', (e) => {
 `useODataSource(url, options)` fetches paginated/sorted/filtered data from an OData v4 endpoint and returns props ready to bind to `<FlexTableReact dataMode="server" ...>`.
 
 ```tsx
-import { useODataSource } from '@iyulab/flex-table/odata';
+import { useODataSource } from '@iyulab/flex-table/react';
 
 const source = useODataSource('/api/orders', {
   pageSize: 20,
@@ -688,6 +689,7 @@ const source = useODataSource('/api/orders', {
 | `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 |
+| `enabled` | `true` | While `false`, no request is made and `loading` stays `true` — see below |
 
 `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.
 
@@ -704,6 +706,22 @@ rows, a `refresh` landing after a change), and holding the old `$skip` would lea
 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.
 
+Set `enabled: false` while the query depends on a value that has not arrived yet — a default
+filter the server decides, the current user, a selected parent record. Without it, the first
+render requests with the wrong conditions (often the heaviest query: no filter) and then again
+once the value arrives. The first request goes out the moment `enabled` turns `true`, with the
+conditions of that render; until then `loading` is `true`, so the table shows loading rather
+than "no data". Turning it `false` mid-request cancels that request, and `refresh()` does nothing
+while disabled.
+
+```tsx
+const season = useDefaultSeason();   // resolves asynchronously
+const source = useODataSource('/api/orders', {
+  fixedFilter: season ? { Season: season } : undefined,
+  enabled: season !== undefined,
+});
+```
+
 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
@@ -743,7 +761,7 @@ 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:
+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. The `./odata` entry holds only pure functions and does not load React, so an app without React can use it (the hooks live on `./react`):
 
 ```ts
 import { buildSearchExpression, parseOrderBy } from '@iyulab/flex-table/odata';
@@ -753,6 +771,20 @@ buildSearchExpression('');          // undefined
 parseOrderBy('name desc');          // [{ key: 'name', direction: 'desc' }]
 ```
 
+`buildODataQuery(state)` is the step the hook runs on every request — table state in, OData query string out. Use it to drive server paging without React (a Lit table, a list that is not a table) with exactly the query the hook would send:
+
+```ts
+import { buildODataQuery } from '@iyulab/flex-table/odata';
+
+buildODataQuery({
+  page: 2, pageSize: 20,                          // 0-based page → $skip=40
+  sortCriteria: [{ key: 'name', direction: 'desc' }], // else defaultOrderBy
+  search: 'red shirt',                            // encoded by buildSearchExpression
+  fixedFilter: { IsActive: true },                // odata-query filter object
+});
+// '?$filter=IsActive eq true&$orderby=name desc&$count=true&$top=20&$skip=40&$search=%22red%22%20AND%20%22shirt%22'
+```
+
 ### Array Source Hook (React)
 
 `useArraySource(data, options)` runs search/sort/pagination over an in-memory array and
@@ -771,7 +803,7 @@ e.g. a lookup table whose display name lives on a different endpoint than the ro
 so search/sort has to run after the join, in memory:
 
 ```tsx
-import { useArraySource } from '@iyulab/flex-table/array';
+import { useArraySource } from '@iyulab/flex-table/react';
 
 const joined = useMemo(
   () => seasonPrices.map(p => ({ ...p, productName: productsById[p.productId]?.name ?? '' })),

package/dist/array/index.d.ts

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

package/dist/array/index.js

@@ -1,56 +1,2 @@
-import { t as e } from "../sorting-CjfjRxwL.js";
-import { r as t } from "../use-odata-source-l9dVCi9l.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 = d === 0 ? 0 : Math.ceil(d / a) - 1, p = Math.min(Math.max(i, 0), f) * a;
-	return {
-		data: u.slice(p, p + a),
-		totalCount: d
-	};
-}
-function o(e, o = {}) {
-	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 && (v(t), g(0));
-	}, []), C = n(() => {}, []), { data: w, totalCount: T } = r(() => a(e, {
-		search: y,
-		sortCriteria: _,
-		page: h,
-		pageSize: s,
-		columns: f,
-		searchFields: p
-	}), [
-		e,
-		y,
-		_,
-		h,
-		s,
-		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: h,
-		setPage: g,
-		sortCriteria: _,
-		onSortChange: S,
-		search: y,
-		setSearch: x,
-		refresh: C
-	};
-}
-//#endregion
-export { a as computeArrayView, o as useArraySource };
+import { t as e } from "../view-DiLr-TdY.js";
+export { e as computeArrayView };

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

@@ -1,28 +1,5 @@
-import type { SortCriteria } from '../core/sorting.js';
-import type { ColumnDefinition, DataRow } from '../models/types.js';
+import type { 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`/

package/dist/array/view.d.ts

@@ -0,0 +1,24 @@
+import type { SortCriteria } from '../core/sorting.js';
+import type { ColumnDefinition, DataRow } from '../models/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;
+};