@iyulab/flex-table 0.40.0 → 0.40.2

package/dist/flex-table.js

@@ -1,2 +1,2 @@
-import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-CDEu8YQE.js";
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./flex-table-CbIsTvod.js";
 export { o as FlexTable, e as RowSelectionState, t as UndoStack, n as effectiveAlign, i as exportData, r as flexTableLocale, a as renderCell };

package/dist/react-events.test.d.ts

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

package/dist/react.d.ts

@@ -27,6 +27,13 @@ declare const FlexTableReactBase: import("@lit/react").ReactWebComponent<FlexTab
     onBatchUpdate: EventName<CustomEvent>;
     onContextMenu: EventName<CustomEvent>;
     onFilterError: EventName<CustomEvent>;
+    onRowReorder: EventName<CustomEvent>;
+    onColumnVisibilityChange: EventName<CustomEvent>;
+    onCommentChange: EventName<CustomEvent>;
+    onDataImport: EventName<CustomEvent>;
+    onFillHandleApply: EventName<CustomEvent>;
+    onFindReplace: EventName<CustomEvent>;
+    onHeaderContextMenu: EventName<CustomEvent>;
 }>;
 type BaseProps = React.ComponentProps<typeof FlexTableReactBase>;
 /**

package/dist/react.js

@@ -1,4 +1,4 @@
-import { t as e } from "./flex-table-CDEu8YQE.js";
+import { t as e } from "./flex-table-CbIsTvod.js";
 import { i as t, t as n } from "./query-Dw4iO0ir.js";
 import { t as r } from "./view-DiLr-TdY.js";
 import i, { useCallback as a, useEffect as o, useMemo as s, useRef as c, useState as l } from "react";
@@ -165,7 +165,14 @@ var p = u({
 		onValidationError: "validation-error",
 		onBatchUpdate: "batch-update",
 		onContextMenu: "context-menu",
-		onFilterError: "filter-error"
+		onFilterError: "filter-error",
+		onRowReorder: "row-reorder",
+		onColumnVisibilityChange: "column-visibility-change",
+		onCommentChange: "comment-change",
+		onDataImport: "data-import",
+		onFillHandleApply: "fill-handle-apply",
+		onFindReplace: "find-replace",
+		onHeaderContextMenu: "header-context-menu"
 	}
 });
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/flex-table",
-  "version": "0.40.0",
+  "version": "0.40.2",
   "description": "A minimalist, input-centric data grid web component",
   "type": "module",
   "main": "./dist/flex-table.js",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
     "CHANGELOG.md",
@@ -71,7 +72,7 @@
     "odata-query": "^8.1.0"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.27.0",
+    "@iyulab/components": ">=1.52.0",
     "@lit/react": "^1.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },

package/skills/iyulab-flex-table/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: iyulab-flex-table
+description: Spreadsheet-grade data grid web component (`<flex-table>`, built with Lit) with virtual scrolling, inline cell editing, validation, range selection, clipboard, undo/redo, sorting, filtering, pinned columns, and CSV/TSV/JSON/XLSX export, plus a React wrapper and OData / in-memory data-source hooks. Use when working with @iyulab/flex-table — defining columns, editing cells, handling grid events, wiring server-side paging with useODataSource or useArraySource, or styling the grid.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.40.1"
+---
+
+# @iyulab/flex-table
+
+A schema-agnostic data grid custom element (`<flex-table>`) for large datasets and cell-level editing.
+Rows are plain objects (`DataRow = Record<string, unknown>`); columns describe how to show and edit them.
+
+## Install
+
+```bash
+npm install @iyulab/flex-table @iyulab/components
+# React wrapper and hooks (optional peers)
+npm install @lit/react react
+```
+
+`@iyulab/components` is a peer dependency (locale, formatting, design tokens).
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@iyulab/flex-table` | Registers `<flex-table>`; exports `FlexTable`, types, `exportData`, `renderCell`, `flexTableLocale`, `RowSelectionState`, `UndoStack`, `effectiveAlign` |
+| `@iyulab/flex-table/react` | `FlexTableReact`, `useODataSource`, `useArraySource` |
+| `@iyulab/flex-table/odata` | Pure helpers, no React: `buildODataQuery`, `buildSearchExpression`, `parseOrderBy` |
+| `@iyulab/flex-table/array` | Pure helper, no React: `computeArrayView` |
+
+## Quick start
+
+```html
+<flex-table id="table" style="height: 400px" show-row-numbers></flex-table>
+
+<script type="module">
+  import '@iyulab/flex-table';
+
+  const table = document.getElementById('table');
+  table.columns = [
+    { 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 = [
+    { name: 'Alice', age: 30, active: true },
+    { name: 'Bob', age: 25, active: false },
+  ];
+  table.addEventListener('cell-edit-commit', (e) => console.log(e.detail));
+</script>
+```
+
+## Key concepts
+
+**Give it a height.** The host is its own scroll container and virtualizes against its own height.
+Without a height (or a constrained flex parent with `min-height: 0`), every row is rendered.
+
+**Columns.** Each `ColumnDefinition` needs `key` and `label`. `type` picks the built-in
+renderer/editor (`text`, `number`, `boolean`, `date`, `datetime`, `select`; unknown strings behave
+as `text`). See `references/api.md` for every field.
+
+- `format` changes only the displayed text (`'#,##0.00'`, `'0.00%'`, `'yyyy-MM-dd'`, or a function); sorting, filtering, editing and export keep the raw value.
+- `render` replaces the cell content (`(value, row, col) => TemplateResult | string`) and wins over `format`.
+- `editor` returns a Lit template containing an element with class `ft-editor`; its `.value` is committed.
+- `validator` returns `null` when valid, or an error message (the edit is rejected and `validation-error` fires).
+- `conditionalRules` applies `{ when, style }` rules in order; later matches override earlier ones.
+- `pinned: 'left' | 'right'` freezes a column during horizontal scroll.
+
+**Data is mutated in place.** Assigning a new array re-renders; changing a row object does not.
+Use `updateRows([{ row, key, value }])` for programmatic edits (undoable, fires `batch-update`) or
+`refreshData()` after an external in-place mutation.
+
+**Editing and read-only.** `editable` defaults to `true`. For a read-only grid set
+`table.editable = false` (a property, since a boolean attribute cannot express `false`) — Enter on a non-editable cell then fires
+`row-activate`, the grid's "open this row" contract.
+
+**Row selection is index-based.** Enable with `selectable` (`selection-mode="single|multi"`).
+There is no row key, so set `clear-selection-on-data-change` when selection drives bulk actions and
+`data` can be replaced. `selectWhere(predicate)` selects rows by content.
+
+**Client vs server mode.** `data-mode="client"` (default) sorts and filters locally.
+`data-mode="server"` only emits `sort-change` / `filter-change`; you supply already-processed rows.
+
+**Filtering.** Programmatic `setFilter(key, (value, row) => boolean)`; `show-filters` adds a
+**Filter…** entry to each column's header menu (text, number range, boolean, date/datetime range).
+Both share one filter state.
+
+**Undo/redo** covers edits, row and column operations, paste and comments (`max-undo-size`, default 100).
+
+## React
+
+```tsx
+import { useRef } from 'react';
+import { FlexTableReact, type FlexTable, type ColumnDefinition } from '@iyulab/flex-table/react';
+
+interface Order { id: string; total: number; currency: string }
+
+const columns: ColumnDefinition<Order>[] = [
+  { key: 'id', label: 'ID' },
+  { key: 'total', label: 'Total', render: (_v, row) => `${row.total} ${row.currency}` },
+];
+
+function Orders({ orders }: { orders: Order[] }) {
+  const ref = useRef<FlexTable>(null);
+  return (
+    <FlexTableReact<Order>
+      ref={ref}
+      data={orders}
+      columns={columns}
+      selectable
+      onCellEditCommit={(e) => console.log(e.detail)}
+    />
+  );
+}
+```
+
+Server paging from OData or an in-memory array uses the same binding — see `references/react.md`.
+
+## Common pitfalls
+
+- No height → no virtualization.
+- `--ft-row-height` is read once at first render; change row height later via `rowHeight` / `row-height`.
+- Styles for elements returned by `render` must be passed through the `stylesheets` property
+  (constructable `CSSStyleSheet[]`); document CSS does not cross the shadow boundary.
+- `useODataSource` `fetcher` / `onUnauthorized` must be stable references (`useCallback`).
+- Always render `error` from `useODataSource`; a failed request otherwise leaves the grid empty.
+
+## References
+
+- [references/api.md](references/api.md) — properties, column definition, methods, events
+- [references/react.md](references/react.md) — `FlexTableReact`, `useODataSource`, `useArraySource`, pure OData/array helpers
+- [references/styling.md](references/styling.md) — CSS custom properties, density, keyboard shortcuts, localization

package/skills/iyulab-flex-table/references/api.md

@@ -0,0 +1,173 @@
+# flex-table API reference
+
+All names below are members of the `FlexTable` class (`<flex-table>`).
+
+## Properties
+
+| Property | Attribute | Type | Default | Notes |
+|---|---|---|---|---|
+| `columns` | — | `ColumnDefinition[]` | `[]` | Column definitions |
+| `data` | — | `DataRow[]` | `[]` | Rows; mutated in place by the grid |
+| `rowHeight` | `row-height` | `number` | `32` | Explicit value > `--ft-row-height` token > 32 |
+| `showRowNumbers` | `show-row-numbers` | `boolean` | `false` | Sticky row-number column |
+| `theme` | `theme` | `'light' \| 'dark' \| undefined` | auto | Auto follows `prefers-color-scheme` |
+| `editable` | `editable` | `boolean` | `true` | `false` = read-only grid; Enter then fires `row-activate` |
+| `showFilters` | `show-filters` | `boolean` | `false` | Adds **Filter…** to each column menu |
+| `showContextMenu` | `show-context-menu` | `boolean` | `false` | Built-in cell context menu |
+| `frozenRows` | `frozen-rows` | `number` | `0` | Rows kept visible at the top |
+| `maxRows` | `max-rows` | `number` | `0` | 0 = unlimited; blocks `addRow()` and paste expansion |
+| `maxUndoSize` | `max-undo-size` | `number` | `100` | Undo stack size |
+| `selectable` | `selectable` | `boolean` | `false` | Row checkbox selection |
+| `selectionMode` | `selection-mode` | `'single' \| 'multi'` | `'multi'` | |
+| `dataMode` | `data-mode` | `'client' \| 'server'` | `'client'` | Server mode only emits sort/filter events |
+| `footerData` | `footer-data` | `Record<string, string \| TemplateResult> \| null` | `null` | Summary row keyed by column key |
+| `emptyMessage` | `empty-message` | `string` | `'No data'` | |
+| `noMatchingMessage` | `no-matching-message` | `string` | `'No matching data'` | All rows hidden by filters |
+| `loading` | `loading` | `boolean` | `false` | Loading overlay + `aria-busy` |
+| `importEnabled` | `import-enabled` | `boolean` | `false` | Drag-and-drop `.xlsx` / `.csv` import |
+| `clearUndoOnDataChange` | `clear-undo-on-data-change` | `boolean` | `false` | Replacing `data` clears undo history |
+| `clearSelectionOnDataChange` | `clear-selection-on-data-change` | `boolean` | `false` | Replacing `data` clears row selection |
+| `stylesheets` | — | `CSSStyleSheet[]` | `[]` | Adopted into the shadow root; styles `render` output |
+
+Replacing `data` with the same array reference does not trigger the clear-on-change behaviors.
+
+### Read-only
+
+| Getter | Type |
+|---|---|
+| `visibleColumns` | `ColumnDefinition[]` (non-hidden) |
+| `filteredRowCount` | `number` |
+| `filterKeys` | `string[]` |
+| `sortCriteria` | `SortCriteria[]` — `{ key, direction: 'asc' \| 'desc' }` |
+| `activeCell` / `editingCell` | `CellPosition \| null` — `{ row, col }` |
+| `canUndo` / `canRedo` | `boolean` |
+
+## Column definition
+
+`ColumnDefinition<T = DataRow>` fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `key` | `string` | Property name in the row (required) |
+| `label` | `string` | Header text (required) |
+| `type` | `ColumnType` | `'text' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'select'`; other strings act as text |
+| `width` / `minWidth` | `number` | px; `minWidth` defaults to 40 |
+| `hidden` | `boolean` | |
+| `sortable` | `boolean` | default `true` |
+| `align` | `'start' \| 'center' \| 'end'` | Default from type: number → end, boolean → center, else start |
+| `headerAlign` | `'start' \| 'center' \| 'end'` | Defaults to the cell alignment |
+| `editable` | `boolean` | Per-column; the global `editable` still applies |
+| `pinned` | `'left' \| 'right'` | |
+| `options` | `string[] \| SelectOption[]` | For `select`; `SelectOption` = `{ label, value }` |
+| `autocomplete` | `boolean \| 'strict'` | Suggest existing values; `'strict'` rejects others |
+| `format` | `string \| (value, row, col) => string` | Display only |
+| `render` | `CellRenderer<T>` | `(value, row, col) => TemplateResult \| string` |
+| `editor` | `CellEditor<T>` | `(value, row, col) => TemplateResult` with an `.ft-editor` element |
+| `validator` | `CellValidator<T>` | `(value, row, col) => string \| null \| undefined` |
+| `conditionalRules` | `ConditionalRule<T>[]` | `{ when(value, row, col): boolean, style: CellStyle }` |
+
+`CellStyle` = `{ background?, color?, fontWeight?: 'bold' | 'normal', fontStyle?: 'italic' | 'normal' }`.
+
+```ts
+import { html } from 'lit';
+
+table.columns = [
+  { key: 'total', label: 'Total', type: 'number', format: '#,##0.00' },
+  { key: 'status', label: 'Status',
+    conditionalRules: [{ when: (v) => v === 'overdue', style: { color: '#dc2626', fontWeight: 'bold' } }] },
+  { key: 'age', label: 'Age', type: 'number',
+    validator: (v) => (Number(v) < 0 ? 'Must be positive' : null) },
+  { key: 'color', label: 'Color',
+    editor: (v) => html`<input class="ft-editor" type="color" .value=${String(v ?? '#000000')}>` },
+];
+```
+
+Custom editors: clicking another cell auto-commits; handle `@keydown` / `@blur` in the template for
+Enter/Escape and blur-to-commit behavior.
+
+## Methods
+
+### Rows
+
+| Method | Returns | Notes |
+|---|---|---|
+| `addRow(row?, index?)` | `DataRow \| null` | `null` when `maxRows` reached |
+| `deleteRows(indices?)` | `void` | Data indices; default = selected rows |
+| `updateRows(changes)` | `void` | `Array<{ row, key, value }>`, one undo step |
+| `refreshData()` | `void` | Re-render after in-place mutation |
+
+### Columns
+
+| Method | Returns |
+|---|---|
+| `addColumn(def, index?)` | `ColumnDefinition` |
+| `deleteColumn(key)` | `void` (also clears its filter, sort and width) |
+| `moveColumn(key, newIndex)` | `void` (index clamped) |
+| `hideColumn(key)` / `showColumn(key)` | `void` |
+| `getHiddenColumns()` | `ColumnDefinition[]` |
+| `getColumnWidth(key)` | `number \| undefined` (resized width) |
+| `selectColumn(colIndex)` | `void` (range-selects the column) |
+
+### Row selection
+
+| Method | Notes |
+|---|---|
+| `selectAll()` / `deselectAll()` | `selectAll` is multi mode only |
+| `selectWhere(predicate)` | `(row, dataIndex) => boolean` over the visible rows |
+| `getSelectedRows()` | `{ selectedIndices, selectedRows }` |
+
+### Filtering, undo, comments, import/export
+
+| Method | Notes |
+|---|---|
+| `setFilter(key, predicate)` / `removeFilter(key)` / `clearFilters()` | `predicate: (value, row) => boolean`; filters combine with AND |
+| `undo()` / `redo()` / `clearUndoHistory()` | |
+| `setComment(dataIndex, colKey, text)` | `null` or `''` removes; undoable |
+| `getComment(dataIndex, colKey)` / `clearComments()` | |
+| `importFromFile(file)` | `Promise<void>`; `.xlsx`, `.csv`, `.tsv`; fires `data-import` |
+| `exportToString(format, { selectionOnly? })` | `string \| Uint8Array`; format `'csv' \| 'tsv' \| 'json' \| 'xlsx'` (xlsx returns bytes) |
+| `exportToFile(format, filename?)` | Triggers a download |
+
+## Events
+
+All are `CustomEvent`s with `bubbles: true, composed: true`. `row`/`index` are data indices.
+
+| Event | `detail` |
+|---|---|
+| `cell-select` | `{ row, col }` (or `null`) |
+| `cell-edit-start` | `{ row, col, key, value }` |
+| `cell-edit-commit` | `{ row, col, key, oldValue, newValue }` |
+| `cell-edit-cancel` | `{ row, col }` |
+| `validation-error` | `{ row, col, key, value, error }` |
+| `row-add` | `{ row, index }` |
+| `row-delete` | `{ indices, rows }` |
+| `row-activate` | `{ row, index, col, key }` — Enter on a non-editable cell |
+| `row-reorder` | `{ from, to }` |
+| `batch-update` | `{ changes }` |
+| `column-add` | `{ column, index }` |
+| `column-delete` | `{ column, key, index }` |
+| `column-reorder` | `{ key, oldIndex, newIndex }` |
+| `column-resize` | `{ key, width, colIndex }` |
+| `column-select` | `{ colIndex, key, rowCount }` |
+| `column-visibility-change` | `{ key, hidden }` |
+| `sort-change` | `{ criteria }` |
+| `filter-change` | `{ keys, filteredCount }` |
+| `filter-error` | `{ error, row, filterKey }` |
+| `selection-change` | `{ selectedIndices, selectedRows }` |
+| `clipboard-copy` / `clipboard-cut` | `{ range, text }` (TSV) |
+| `clipboard-paste` | `{ changes, addedRows }` |
+| `clipboard-error` | `{ action: 'copy' \| 'paste', error }` |
+| `fill-handle-apply` | `{ sourceRange, targetRange, cells }` |
+| `find-replace` | `{ type: 'replace' \| 'replace-all', cells }` |
+| `comment-change` | `{ dataIndex, colKey, text }` |
+| `data-import` | `{ count }` |
+| `undo-state-change` | `{ canUndo, canRedo }` |
+| `context-menu` | `{ x, y, row, col, key, value, rowData }` — cancelable; `preventDefault()` suppresses the built-in menu |
+| `header-context-menu` | `{ key, label, x, y }` |
+
+## Other exports
+
+`exportData(rows, columns, format)`, `renderCell`, `effectiveAlign(col)`, `RowSelectionState`,
+`UndoStack`, `flexTableLocale`, and the types `CellPosition`, `CellRange`, `SortCriteria`,
+`SortDirection`, `ColumnFilter`, `FilterPredicate`, `FilterErrorCallback`, `ExportFormat`,
+`UndoAction`, `FlexTableMessageKey`.

package/skills/iyulab-flex-table/references/react.md

@@ -0,0 +1,177 @@
+# React: `@iyulab/flex-table/react`
+
+Requires the optional peers `react` and `@lit/react`.
+
+## `FlexTableReact`
+
+A `@lit/react` wrapper around `<flex-table>`, generic over the row type `T` (default `DataRow`).
+Every element property is a prop; `ref` resolves to the `FlexTable` instance, so all methods
+(`addRow`, `deleteRows`, `setFilter`, `selectWhere`, …) are reachable imperatively.
+
+```tsx
+import { useRef } from 'react';
+import { FlexTableReact, type FlexTable, type ColumnDefinition } from '@iyulab/flex-table/react';
+
+const columns: ColumnDefinition<Order>[] = [
+  { key: 'id', label: 'ID' },
+  { key: 'total', label: 'Total', type: 'number', format: '#,##0.00' },
+];
+
+function Orders({ orders }: { orders: Order[] }) {
+  const ref = useRef<FlexTable>(null);
+  return (
+    <>
+      <button onClick={() => ref.current?.addRow({ id: '', total: 0 })}>Add</button>
+      <FlexTableReact<Order> ref={ref} data={orders} columns={columns} selectable
+        onSelectionChange={(e) => console.log(e.detail.selectedRows)} />
+    </>
+  );
+}
+```
+
+### Mapped event props
+
+| Prop | Event | Prop | Event |
+|---|---|---|---|
+| `onCellSelect` | `cell-select` | `onColumnSelect` | `column-select` |
+| `onCellEditStart` | `cell-edit-start` | `onColumnAdd` | `column-add` |
+| `onCellEditCommit` | `cell-edit-commit` | `onColumnDelete` | `column-delete` |
+| `onCellEditCancel` | `cell-edit-cancel` | `onColumnReorder` | `column-reorder` |
+| `onValidationError` | `validation-error` | `onColumnResize` | `column-resize` |
+| `onSortChange` | `sort-change` | `onSelectionChange` | `selection-change` |
+| `onFilterChange` | `filter-change` | `onClipboardCopy` | `clipboard-copy` |
+| `onFilterError` | `filter-error` | `onClipboardCut` | `clipboard-cut` |
+| `onRowAdd` | `row-add` | `onClipboardPaste` | `clipboard-paste` |
+| `onRowDelete` | `row-delete` | `onClipboardError` | `clipboard-error` |
+| `onRowActivate` | `row-activate` | `onUndoStateChange` | `undo-state-change` |
+| `onBatchUpdate` | `batch-update` | `onContextMenu` | `context-menu` |
+| `onRowReorder` | `row-reorder` | `onHeaderContextMenu` | `header-context-menu` |
+| `onColumnVisibilityChange` | `column-visibility-change` | `onCommentChange` | `comment-change` |
+| `onDataImport` | `data-import` | `onFillHandleApply` | `fill-handle-apply` |
+| `onFindReplace` | `find-replace` | | |
+
+Every custom event of `<flex-table>` has a prop.
+
+Type exports from this entry: `FlexTable`, `FlexTableReactProps`, `ColumnDefinition`, `DataRow`,
+`ColumnType`, `ColumnAlign`, `CellRenderer`, `CellEditor`, `CellValidator`, `ConditionalRule`,
+`SelectionMode`, `DataMode`, `UseODataSourceOptions`, `UseODataSourceResult`,
+`UseArraySourceOptions`, `UseArraySourceResult`.
+
+## `useODataSource(url, options)`
+
+Fetches paged, sorted, searched rows from an OData v4 endpoint. Bind the result to a
+server-mode table:
+
+```tsx
+import { useCallback } from 'react';
+import { FlexTableReact, useODataSource } from '@iyulab/flex-table/react';
+
+function Orders() {
+  const fetcher = useCallback((input: string, init: RequestInit) => fetch(input, init), []);
+  const source = useODataSource<Order>('/api/orders', { pageSize: 20, fetcher });
+
+  return (
+    <>
+      <input value={source.search} onChange={(e) => source.setSearch(e.target.value)} />
+      {source.error && <p role="alert">{source.error}</p>}
+      <FlexTableReact<Order>
+        dataMode="server"
+        columns={columns}
+        data={source.data}
+        loading={source.loading}
+        onSortChange={source.onSortChange}
+        clearSelectionOnDataChange
+      />
+      <button disabled={source.page === 0} onClick={() => source.setPage(source.page - 1)}>Prev</button>
+      <span>{source.page + 1} / {Math.max(1, Math.ceil(source.totalCount / 20))}</span>
+      <button onClick={() => source.setPage(source.page + 1)}>Next</button>
+    </>
+  );
+}
+```
+
+### Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `pageSize` | `20` | |
+| `defaultOrderBy` | — | `$orderby` string, e.g. `'name asc'` |
+| `initialPage` | `0` | Zero-based; first render only |
+| `initialSearch` | `''` | First render only |
+| `initialSort` | — | `SortCriteria[]`; overrides `defaultOrderBy`; `[]` means no sort |
+| `fixedFilter` | — | odata-query filter object, always applied; value change resets to page 0 (compared by value) |
+| `baseUrl` | `window.location.origin` | For proxy/BFF setups |
+| `fetcher` | global `fetch` | `(input, init) => Promise<Response>`; keep stable |
+| `onUnauthorized` | — | `(response) => void` on 401/403; keep stable |
+| `enabled` | `true` | While `false`: no request, `loading` stays `true`, `refresh()` is a no-op, in-flight request is cancelled |
+
+### Result
+
+| Field | Notes |
+|---|---|
+| `data`, `totalCount` | Current page and `@odata.count`; `@odata.nextLink` is followed to fill a page |
+| `loading` | Request in flight |
+| `error` | `string \| null` — render it |
+| `page`, `setPage` | Zero-based |
+| `sortCriteria`, `onSortChange` | Pass `onSortChange` to the table's `sort-change` (resets to page 0) |
+| `search`, `setSearch` | Literal text (resets to page 0) |
+| `refresh` | Re-run the current request |
+
+Search is literal: each whitespace-separated token becomes a quoted phrase joined with `AND`
+(`red shirt` → `"red" AND "shirt"`); double quotes are stripped. If the result set shrinks below
+the current page, the page moves down to the last existing page.
+
+Use `enabled` when the query depends on an async value:
+
+```tsx
+const source = useODataSource('/api/orders', {
+  fixedFilter: season ? { Season: season } : undefined,
+  enabled: season !== undefined,
+});
+```
+
+## `useArraySource(data, options)`
+
+Search, sort and paging over an in-memory array, returning **the same shape** as
+`useODataSource` — the same `dataMode="server"` binding works with either.
+
+```tsx
+import { useMemo } from 'react';
+import { useArraySource } from '@iyulab/flex-table/react';
+
+const joined = useMemo(
+  () => prices.map((p) => ({ ...p, productName: productsById[p.productId]?.name ?? '' })),
+  [prices, productsById],
+);
+const source = useArraySource(joined, { pageSize: 20, columns });
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `pageSize` | `20` | |
+| `defaultOrderBy` | — | Same syntax as `useODataSource` |
+| `initialPage` / `initialSearch` / `initialSort` | `0` / `''` / — | Same first-render-only contract |
+| `columns` | — | Enables value-aware sort (number/date/boolean); otherwise text sort |
+| `searchFields` | all row values | `(row) => Array<string \| number \| boolean \| null \| undefined>` |
+
+Differences: `totalCount` is the count after search, `loading` is always `false`, `error` always
+`null`, and `refresh` is a no-op. The page is clamped down if the array shrinks.
+
+## Without React
+
+```ts
+import { buildODataQuery, buildSearchExpression, parseOrderBy } from '@iyulab/flex-table/odata';
+import { computeArrayView } from '@iyulab/flex-table/array';
+
+buildSearchExpression('red shirt'); // '"red" AND "shirt"'  ('' → undefined)
+parseOrderBy('name desc');          // [{ key: 'name', direction: 'desc' }]
+buildODataQuery({ page: 2, pageSize: 20, search: 'red', fixedFilter: { IsActive: true } });
+// '?$filter=...&$count=true&$top=20&$skip=40&$search=...'
+
+const { data, totalCount } = computeArrayView(rows, {
+  search: '', sortCriteria: [], page: 0, pageSize: 20, columns,
+});
+```
+
+`buildODataQuery` state fields: `page`, `pageSize`, and optional `sortCriteria`, `defaultOrderBy`,
+`search`, `fixedFilter` — exactly what the hook sends per request.

package/skills/iyulab-flex-table/references/styling.md

@@ -0,0 +1,108 @@
+# Styling, keyboard, localization
+
+## Sizing
+
+The host is the scroll container and virtualizes against its own height:
+
+```css
+flex-table { height: 400px; }
+/* or inside a flex column */
+.page { height: 100%; display: flex; flex-direction: column; }
+.page flex-table { flex: 1 1 auto; min-height: 0; }
+```
+
+## Theming
+
+Every `--ft-*` color falls back to an `@iyulab/components` design token, so loading that token sheet
+makes the grid follow the app theme (e.g. `:root { --u-primary-color: #7b1fa2; }`). Without the sheet,
+literal fallbacks and the built-in dark theme (`prefers-color-scheme` or `theme="dark"`) still apply.
+
+Override individual properties to make the table differ from the rest of the app:
+
+| Group | Custom properties |
+|---|---|
+| Font | `--ft-font-family`, `--ft-font-size` |
+| Surfaces / text | `--ft-bg`, `--ft-text-color`, `--ft-border-color`, `--ft-editor-bg`, `--ft-empty-color` |
+| Header | `--ft-header-bg`, `--ft-header-hover-bg`, `--ft-header-text-color`, `--ft-sort-indicator-color` |
+| Rows | `--ft-row-even-bg`, `--ft-row-odd-bg`, `--ft-row-hover-bg`, `--ft-row-odd-hover-bg` |
+| Accent | `--ft-active-color`, `--ft-selection-bg`, `--ft-bool-color` |
+| State overlays | `--ft-invalid-color`, `--ft-drop-color`, `--ft-find-color` (translucent backgrounds derive from these) |
+
+```css
+flex-table {
+  --ft-font-size: 13px;
+  --ft-active-color: #1a73e8;
+  --ft-row-odd-bg: #fafafa;
+}
+```
+
+### Styling custom cell content
+
+`render` output lives in the shadow root, so page CSS does not reach it. Pass constructable
+stylesheets instead (reassigning replaces the previous set):
+
+```ts
+const sheet = new CSSStyleSheet();
+sheet.replaceSync('.badge { padding: 0 6px; border-radius: 4px; }');
+table.stylesheets = [sheet];
+```
+
+## Density and header hierarchy
+
+```css
+flex-table {
+  --ft-row-height: 28px;
+  --ft-cell-padding-block: 4px;
+  --ft-cell-padding-inline: 8px;
+  --ft-header-font-size: 13px;   /* defaults to --ft-font-size */
+  --ft-header-font-weight: 600;
+}
+```
+
+- `--ft-row-height` is read once at first render and only in `px`; to change it later set the
+  `rowHeight` property / `row-height` attribute (which always win over the token).
+- Cells are single-line. When reducing row height, reduce `--ft-cell-padding-block` too
+  (`padding-block × 2 + line box ≤ row height`), or text is clipped.
+
+## Keyboard
+
+| Key | Action |
+|---|---|
+| Arrows / Tab / Shift+Tab | Move between cells |
+| Home / End, Ctrl+Home / Ctrl+End | Row start/end, table start/end |
+| Shift+Arrow, Shift+Click | Extend range selection |
+| Ctrl+Click header | Select column |
+| Enter / F2 | Edit (Enter on a non-editable cell fires `row-activate`) |
+| Typing a printable character | Start editing an editable cell |
+| Escape | Cancel edit / clear selection / close find panel |
+| Delete / Backspace | Clear selected cells |
+| Ctrl+C / Ctrl+X / Ctrl+V | Copy / cut / paste as TSV (Excel / Google Sheets compatible) |
+| Ctrl+D / Ctrl+R | Fill down / fill right |
+| Ctrl+F / Ctrl+H | Find / find and replace |
+| Ctrl+Z, Ctrl+Y or Ctrl+Shift+Z | Undo, redo |
+| Alt+ArrowLeft / Alt+ArrowRight | Resize current column |
+| Enter / Space on a column menu button | Open the column menu (arrows, Home/End navigate; Escape closes) |
+
+Ctrl also matches Cmd on macOS. Editing shortcuts are ignored when `editable` is `false`.
+
+## Localization
+
+The grid's own chrome (column menu, filters, find/replace, context menu, empty states) uses a locale
+namespace. English and Korean are built in and follow the active `@iyulab/components` locale:
+
+```ts
+import { Locale } from '@iyulab/components';
+Locale.set('ko');
+```
+
+Add a language or reword strings with partial tables; `FlexTableMessageKey` lists the valid keys:
+
+```ts
+import { flexTableLocale } from '@iyulab/flex-table';
+
+flexTableLocale.register('ja', { contains: '含む', startsWith: '前方一致' });
+flexTableLocale.register('en', { replaceAll: 'Replace everything' });
+flexTableLocale.register('ja', { columnMenuFor: '{header} の列メニュー' }); // {header} placeholder
+```
+
+`emptyMessage` and `noMatchingMessage` can also be set per table.