@ai-matrx/records 0.58.19 → 0.58.21

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog — @ai-matrx/records
 
+## 0.58.21
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.58.20..npm/records/v0.58.21 -- apps/shared/records`).
+No source changes intended and no consumer action required.
+
+## 0.58.20 (2026-09-26 — cut by the automatic republish; carries lane data-tables-grid-overhaul, merge tranche 6k)
+
+* **`useRecordPage(tableId, { pageSize, page, filter, search, sort, viewId })`** (`/react`) — one page
+  through `client.listPage` (`custom.read_records_page`): the store sorts, searches, filters and
+  counts; `total` is the matching set this reader may see. Realtime-aware exactly like
+  `useRecords`: a notice re-reads only the ids it names and patches them into the page (a row the
+  page does not hold costs one page read). `tableId: null` reads nothing. The realtime half is one
+  shared helper for both hooks. New types `UseRecordPageOptions`, `UseRecordPageState`.
+
 ## 0.58.19
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/react/index.cjs

@@ -2328,6 +2328,7 @@ __export(react_exports, {
   useRecord: () => useRecord,
   useRecordChangeRevision: () => useRecordChangeRevision,
   useRecordMutation: () => useRecordMutation,
+  useRecordPage: () => useRecordPage,
   useRecords: () => useRecords,
   useRecordsActor: () => useRecordsActor,
   useRecordsClient: () => useRecordsClient,
@@ -8122,26 +8123,8 @@ function useFields(tableId, recordType) {
     tableId ? `fields:${tableId}:${recordType ?? ""}:${revision}` : null
   );
 }
-function useRecords(tableId, options = {}) {
+function useLiveRows(tableId, base) {
   const client = useRecordsClient();
-  const pageSize = options.pageSize ?? 50;
-  const page = options.page ?? 0;
-  const filterKey = stableFilterKey(options.filter);
-  const base = useAsync(
-    async (c) => {
-      if (!tableId) return { ok: true, data: { rows: [], total: null } };
-      return c.list({
-        table_id: tableId,
-        ...filterKey === "{}" ? {} : { filter: options.filter },
-        limit: pageSize,
-        offset: page * pageSize
-      });
-    },
-    // The QUESTION, not the object: a parent that rebuilds `{status: "Cancelled"}`
-    // on every render must not re-read the page on every render, and a parent
-    // that changes the question must re-read on the first one.
-    [tableId, pageSize, page, filterKey]
-  );
   const realtime = client.config.realtime;
   const { reload, setData } = base;
   (0, import_react2.useEffect)(() => {
@@ -8188,6 +8171,54 @@ function useRecords(tableId, options = {}) {
   }, [realtime, tableId, client, reload, setData, base.data]);
   const live = Boolean(realtime && tableId);
   const liveReason = realtime ? tableId ? "Live: changes to this table re-read through the read door." : "Not live: no table selected." : "Not live: this host bound no realtime port, so this list updates when you reload it.";
+  return { live, liveReason };
+}
+function useRecords(tableId, options = {}) {
+  const pageSize = options.pageSize ?? 50;
+  const page = options.page ?? 0;
+  const filterKey = stableFilterKey(options.filter);
+  const base = useAsync(
+    async (c) => {
+      if (!tableId) return { ok: true, data: { rows: [], total: null } };
+      return c.list({
+        table_id: tableId,
+        ...filterKey === "{}" ? {} : { filter: options.filter },
+        limit: pageSize,
+        offset: page * pageSize
+      });
+    },
+    // The QUESTION, not the object: a parent that rebuilds `{status: "Cancelled"}`
+    // on every render must not re-read the page on every render, and a parent
+    // that changes the question must re-read on the first one.
+    [tableId, pageSize, page, filterKey]
+  );
+  const { live, liveReason } = useLiveRows(tableId, base);
+  return { ...base, live, liveReason };
+}
+function useRecordPage(tableId, options = {}) {
+  const pageSize = options.pageSize ?? 50;
+  const page = options.page ?? 0;
+  const filterKey = stableFilterKey(options.filter);
+  const search = options.search && options.search.trim() !== "" ? options.search.trim() : null;
+  const sortKey = JSON.stringify(options.sort ?? []);
+  const viewId = options.viewId ?? null;
+  const base = useAsync(
+    async (c) => {
+      if (!tableId) return { ok: true, data: { rows: [], total: null } };
+      const answered = await c.listPage({
+        table_id: tableId,
+        ...filterKey === "{}" ? {} : { filter: options.filter },
+        search,
+        sort: JSON.parse(sortKey),
+        view_id: viewId,
+        limit: pageSize,
+        offset: page * pageSize
+      });
+      return answered.ok ? { ok: true, data: { rows: answered.data.rows, total: answered.data.total } } : answered;
+    },
+    [tableId, pageSize, page, filterKey, search, sortKey, viewId]
+  );
+  const { live, liveReason } = useLiveRows(tableId, base);
   return { ...base, live, liveReason };
 }
 function useRecordChangeRevision(recordId) {