@iyulab/flex-table 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.54.0] - 2026-10-07
+
+### Added
+
+- **`error`** property — the last load failure (`{ message }`, so a data source's `SourceError` goes in as is). While
+  set, the grid shows `error.message` as an alert where the rows or the empty state would be; a failed query used to
+  look like "No data" unless the app drew its own message beside the grid.
+
+## [0.53.0] - 2026-10-07
+
+### Added
+
+- **`createODataSource(url, options)`** (`@iyulab/flex-table/odata`) — the OData source without React. It is what
+  `useODataSource` now runs on: the same options and state, the request, `@odata.nextLink` following, the page
+  fallback, the `fixedFilter` reset, `enabled`, cancellation and the structured `error`. `getState()` · `subscribe()` ·
+  `setPage` · `setSort` · `setSearch` · `refresh` · `update(url, options)`. Requests go out while someone is subscribed,
+  and changes in the same tick become one request.
+- **`ODataSourceController`** — a Lit reactive controller over that source: subscribes when the element connects,
+  cancels when it disconnects, re-renders it on every change. A custom-element list page gets the same server paging
+  a React page gets from the hook.
+
+### Changed
+
+- `useODataSource` reads `fetcher` and `onUnauthorized` when each request starts. A fresh function on every render no
+  longer needs `useCallback`; before, the one captured by the last request kept being used.
+
 ## [0.52.0] - 2026-10-07
 
 ### Changed

package/README.md

@@ -113,6 +113,7 @@ guarantee about a *constrained* host. `height-model.browser.test.ts` pins both s
 | `footerData` | `footer-data` | `Record<string, string \| TemplateResult> \| null` | `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 |
+| `error` | — | `{ message: string } \| null` | `null` | The last load failure. While set, `error.message` is shown as an alert where the rows or the empty state would be, so a failed query does not look like "no data". Pass a data source's `error` as is |
 | `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
@@ -758,7 +759,7 @@ const source = useODataSource('/api/orders', {
 | `onUnauthorized` | — | Called on `401` responses, before the generic error is set. A `403` (signed in, not permitted) does not call it — it surfaces as `error` |
 | `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.
+`fetcher`/`onUnauthorized` are read when each request starts, so a fresh function on every render is fine — it neither refetches nor is ignored.
 
 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
@@ -816,7 +817,7 @@ The hook returns:
 |---|---|
 | `data` / `totalCount` | Current page rows and the server's total (`@odata.count`). When the server pages its response (`@odata.nextLink`, e.g. a page size smaller than `pageSize`), the hook follows the link until the page is filled; a link outside the request's origin, or one that returns to a page already read, is reported through `error` instead of showing a short page |
 | `loading` | A request is in flight, or none has answered yet (true from the first render until the first response settles, and while `enabled: false`) |
-| `error` | The last failed request, or `null`: `{ message, status?, code?, details?, body? }`. **Render `error.message`** — a failed request otherwise leaves the grid silently empty. Branch on `status` (HTTP), `code` (the server's rejection code, OData `error.code`) and `details` (OData `error.details`); `body` is the parsed response (or its text). A failure with no response — a network error, or a `@odata.nextLink` the hook refused — has a `message` only |
+| `error` | The last failed request, or `null`: `{ message, status?, code?, details?, body? }`. **Pass it to the table** (`error={source.error}`) or render `error.message` yourself — a failed request otherwise leaves the grid silently empty. Branch on `status` (HTTP), `code` (the server's rejection code, OData `error.code`) and `details` (OData `error.details`); `body` is the parsed response (or its text). A failure with no response — a network error, or a `@odata.nextLink` the hook refused — has a `message` only |
 | `page` / `setPage` | Zero-based page index |
 | `sortCriteria` / `onSortChange` | Bind `onSortChange` to the table's `sort-change` event |
 | `search` / `setSearch` | Current search term and its setter (resets to page 0) |
@@ -828,7 +829,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 `./odata` entry holds only pure functions and does not load React, so an app without React can use it (the hooks live on `./react`):
+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 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';
@@ -852,6 +853,48 @@ buildODataQuery({
 // '?$filter=IsActive eq true&$orderby=name desc&$count=true&$top=20&$skip=40&$search=%22red%22%20AND%20%22shirt%22'
 ```
 
+### OData Source without React
+
+`useODataSource` is a thin adapter over a framework-neutral source, and that source is public: `createODataSource(url, options)` takes the same options and does everything the hook does — the request, `@odata.nextLink` following, page fallback, `fixedFilter` reset, `enabled`, cancellation and the structured `error`. Use it from a Lit element, another framework, or plain code.
+
+```ts
+import { createODataSource } from '@iyulab/flex-table/odata';
+
+const orders = createODataSource<Order>('/api/orders', { pageSize: 20 });
+const off = orders.subscribe(() => render(orders.getState())); // the first subscriber starts loading
+orders.setSort([{ key: 'name', direction: 'asc' }]);           // also: setPage, setSearch, refresh
+orders.update('/api/orders', { pageSize: 20, fixedFilter: { IsActive: true } }); // changed options
+off();                                                          // the last unsubscribe cancels a request in flight
+```
+
+| Member | Description |
+|---|---|
+| `getState()` | `{ data, totalCount, loading, error, page, sortCriteria, search }` — the same fields the hook returns. A new object only when something changed |
+| `subscribe(listener)` | Called on every change; returns the unsubscribe function. Requests go out only while someone is subscribed |
+| `setPage(page)` | Zero-based |
+| `setSort(criteria)` / `setSearch(term)` | Change the sort or search and go back to page 0 |
+| `refresh()` | Re-read with the same conditions (nothing while `enabled: false`) |
+| `update(url, options)` | New options. Only a changed request re-reads; a changed `fixedFilter` value goes back to page 0; `initial*` are read at creation only |
+
+Changes made in the same tick become one request with the final conditions, so `setSearch` followed by `setPage` does not send the intermediate one.
+
+For a Lit element, `ODataSourceController` ties a source to the element's lifecycle — it subscribes when the element connects, cancels when it disconnects, and re-renders it on every change:
+
+```ts
+import { ODataSourceController } from '@iyulab/flex-table/odata';
+
+class OrdersPage extends LitElement {
+  private orders = new ODataSourceController<Order>(this, '/api/orders', { pageSize: 20 });
+
+  render() {
+    const { data, loading, error } = this.orders.state;
+    return html`
+      <flex-table data-mode="server" .data=${data} .loading=${loading} .error=${error}
+        @sort-change=${(e: CustomEvent) => this.orders.source.setSort(e.detail.criteria)}></flex-table>`;
+  }
+}
+```
+
 ### Array Source Hook (React)
 
 `useArraySource(data, options)` runs search/sort/pagination over an in-memory array and