@colixsystems/widget-sdk 0.281.0 → 0.283.0

package/README.md

@@ -51,6 +51,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities, live }`, applied on the server: see *Querying records*. `live: true` re-reads when anyone else changes the table: see *Live lists*. |
+| **DATASTORE** | `usePagedDatastoreQuery(table, { pageSize, ...query })` | `{ data, total, hasMore, loadingMore, error, loadMore, retry, … }` | A growing list, a page at a time: see *Querying records*. |
 | **DATASTORE** | `useDatastoreFigure(table, { aggregate, column, filter })` (optional: options) | `{ value, text, truncated, loading, fetching, error, refetch }` | `records(table).list` (a count reads the envelope total; a sum or average up to 1000 rows) — `datastore.read:*`. One count / sum / average for a `<Stat>`, computed exactly as the built-in Stat widget does. |
 | **DATASTORE** | `useDatastoreRecord(table, id, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching`; `{ includeCapabilities: true }` adds `data._capabilities` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -88,7 +89,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.281.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.283.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.283.0 (contract 1.232.0)
+
+**`usePagedDatastoreQuery(tableId, { pageSize, sort, filter, … })` — a list of records a page at a time.** A custom list read `useDatastoreQuery` with no `limit`, so it showed one server page and nothing said the rest existed. The new hook reads the first `pageSize` rows (default 25, 1-500), and `loadMore()` appends the next page by offset, so a tap reads one page instead of the whole list again. It returns `{ data, total, hasMore, loading, fetching, loadingMore, error, loadMore, retry, refetch }`: show a Load more `<Button busy={loadingMore}>` while `hasMore`. A failed page sets `error` and keeps the rows shown, and `retry()` fetches it again. A changed sort, filter, search or page size starts from the first page. A write, `live`, `refetch()` or pull-to-refresh re-reads every page shown. `PAGE_SIZE_PROPERTY` is the standard "Rows per page" property, the one the stock Data List shows: declare `pageSize: PAGE_SIZE_PROPERTY` in your `propertySchema` and pass the prop to the hook. The stock Data List now pages through this hook.
 
 ### What's new in 0.281.0 (contract 1.230.0)
 
@@ -3699,44 +3704,39 @@ export default function OpenTasks({ tableId, titleField, statusField }) {
 
 The filter operators are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (a case-insensitive substring), `empty` and `nempty` (no value). On a list column (`STRING_ARRAY`, `INT_ARRAY`), `eq` keeps the rows whose list holds the value exactly, `empty` / `nempty` test whether it holds any, and every other operator is refused. In the array form a condition may carry `valueMode`: `"currentUser"` or `"currentUserGroup"` with `eq` or `neq` matches the signed-in user (or their groups) on a USER or USER_GROUP column, and `"relativeDate"` with an ordering operator reads `value` as "that many days ago".
 
-The result's `total` is how many rows match in all, not just this page: show "12 of 312" and page with `offset`. For a count, a sum or an average, use `useDatastoreFigure(tableId, { aggregate, column, filter })` instead of reading rows.
+The result's `total` is how many rows match in all, not just this page. **A list that grows reads its rows with `usePagedDatastoreQuery(tableId, { pageSize, ...query })`**, which takes the same options bar `limit` / `offset`, sets those itself, and appends the next page on `loadMore()`. Declare `pageSize: PAGE_SIZE_PROPERTY` in the `propertySchema` so the maker sets the rows per page. For a count, a sum or an average, use `useDatastoreFigure(tableId, { aggregate, column, filter })` instead of reading rows.
 
 **Narrow on the server, never over a fetched batch.** A widget that fetches `limit: 1000` and then filters or searches the rows in JavaScript only ever sees the first 1000; once the table grows past that, it misses rows without saying so. Send the search box's text as `q`, a chip's condition as `filter`, and page with `offset`. The checker warns about the batch pattern.
 
 ```js
 import { useEffect, useState } from "react";
-import { Pressable, Text, TextInput, View, useDatastoreQuery, useStableQuery } from "@colixsystems/widget-sdk";
+import { Button, Pressable, Text, TextInput, View, usePagedDatastoreQuery, useStableQuery } from "@colixsystems/widget-sdk";
 
-const PAGE = 50;
-
-export default function ContactList({ tableId }) {
+// manifest.propertySchema: { tableId: { type: "tableRef", … }, pageSize: PAGE_SIZE_PROPERTY }
+export default function ContactList({ tableId, pageSize }) {
   const [draft, setDraft] = useState("");
   const [search, setSearch] = useState("");
   const [status, setStatus] = useState("");
-  const [page, setPage] = useState(0);
   useEffect(() => {
-    const wait = setTimeout(() => { setSearch(draft.trim()); setPage(0); }, 250);
+    const wait = setTimeout(() => setSearch(draft.trim()), 250);
     return () => clearTimeout(wait);
   }, [draft]);
+  // A new search or status starts again from the first page.
   const query = useStableQuery(() => ({
     q: search,
     filter: status ? { status: `eq:${status}` } : undefined,
     sort: { field: "last_contacted", dir: "desc" },
-    limit: PAGE,
-    offset: page * PAGE,
+    pageSize,
   }));
-  const { data, total, loading, error } = useDatastoreQuery(tableId, query);
-  const pick = (next) => { setStatus(next); setPage(0); };
+  const { data, total, loading, error, hasMore, loadingMore, loadMore, retry } = usePagedDatastoreQuery(tableId, query);
   return (
     <View>
       <TextInput value={draft} onChangeText={setDraft} placeholder="Search" />
-      <Pressable onPress={() => pick(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
-      {error ? <Text>{error.message}</Text> : null}
+      <Pressable onPress={() => setStatus(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
       {loading ? <Text>Loading…</Text> : data.map((row) => <Text key={row.id}>{row.name}</Text>)}
+      {error ? <Button variant="ghost" title="Retry" onPress={retry} /> : null}
       <Text>{total ?? 0} contacts</Text>
-      {(page + 1) * PAGE < (total ?? 0) ? (
-        <Pressable onPress={() => setPage(page + 1)}><Text>Next page</Text></Pressable>
-      ) : null}
+      {hasMore ? <Button variant="ghost" title="Load more" busy={loadingMore} onPress={loadMore} /> : null}
     </View>
   );
 }

package/dist/contract.cjs

@@ -422,6 +422,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1992,6 +2002,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -6667,7 +6713,11 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  version: "1.232.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6693,6 +6743,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/contract.js

@@ -418,6 +418,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1988,6 +1998,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -6663,7 +6709,11 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  version: "1.232.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6689,6 +6739,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/index.d.ts

@@ -1160,6 +1160,48 @@ export function useDatastoreQuery<T = unknown>(
   query?: Query,
 ): QueryResult<T>;
 
+export interface PagedQueryOptions extends Omit<Query, "limit" | "offset"> {
+  /** Rows per page: default 25, clamped to 1-500. Pass the `pageSize` prop. */
+  pageSize?: number;
+}
+
+export interface PagedQueryResult<T> {
+  /** Every row loaded so far, first page first. */
+  data: T[];
+  /** How many rows the query matches in all; null until known. */
+  total: number | null;
+  /** False once every matching row is loaded. Hide Load more on it. */
+  hasMore: boolean;
+  /** True only until the first page lands. */
+  loading: boolean;
+  /** True while any page, or a re-read of them, is in flight. */
+  fetching: boolean;
+  /** True while `loadMore()` fetches the next page. */
+  loadingMore: boolean;
+  /** A failed page; the rows already loaded stay in `data`. */
+  error: Error | null;
+  /** Appends the next page. Does nothing when `hasMore` is false. */
+  loadMore(): void;
+  /** Fetches the failed page again (or re-reads the list). */
+  retry(): void;
+  refetch(): Promise<void>;
+}
+
+/**
+ * A table's rows a page at a time: the first `pageSize` at once, the next on
+ * each `loadMore()`. A changed sort, filter or page size starts again.
+ */
+export function usePagedDatastoreQuery<T = unknown>(
+  table: string | null | undefined,
+  options?: PagedQueryOptions,
+): PagedQueryResult<T>;
+
+/**
+ * The standard "Rows per page" property (number, default 25, 1-500), the one
+ * the stock Data List shows. Declare it as `pageSize` in a list's propertySchema.
+ */
+export const PAGE_SIZE_PROPERTY: Readonly<WidgetPropertyDef>;
+
 export interface FigureOptions {
   /** Default `"count"`. `"sum"` and `"average"` read the number `column`. */
   aggregate?: "count" | "sum" | "average";

package/dist/index.js

@@ -136,6 +136,7 @@ export {
 // sc-15163 — native-only in-app purchase; the web Player brokers none.
 export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export { usePagedDatastoreQuery, PAGE_SIZE_PROPERTY } from "./paged-query.js";
 export {
   useDatastoreAggregate,
   useUserStats,

package/dist/index.native.js

@@ -134,6 +134,7 @@ export {
 // sc-15163 — native-only in-app purchase; the web Player brokers none.
 export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export { usePagedDatastoreQuery, PAGE_SIZE_PROPERTY } from "./paged-query.js";
 export {
   useDatastoreAggregate,
   useUserStats,

package/dist/paged-query.js

@@ -0,0 +1,193 @@
+// sc-14120 — a list of records read a page at a time, shared by the stock Data
+// List and custom widgets on both hosts. The first page is useDatastoreQuery's,
+// so it keeps that hook's stale-while-revalidate, write re-reads, `live` and
+// pull-to-refresh; the pages after it are appended by offset. Platform-free,
+// so the web and native entries export this one module.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { CONTRACT } from "./contract.js";
+import { toDatastoreError, useDatastoreQuery, useWidgetContextOrThrow } from "./hooks.js";
+
+export const PAGE_SIZE_PROPERTY = CONTRACT.pageSizeProperty;
+
+// REQ-QUERY-02: the server returns at most this many rows per request.
+const MAX_ROWS_PER_READ = 1000;
+
+const NO_PAGES = Object.freeze({ key: null, rows: Object.freeze([]), pages: 0, total: null });
+
+/** A `pageSize` prop as the page size read: whole, within the property's bounds. */
+export function normalisePageSize(value) {
+  const { min, max } = PAGE_SIZE_PROPERTY.validation;
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n) || n < min) return PAGE_SIZE_PROPERTY.default;
+  return Math.min(n, max);
+}
+
+function windowKey(table, pageSize, query) {
+  try {
+    return JSON.stringify([table, pageSize, query]);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Rows `[offset, offset + count)`, in requests the server's row cap allows. */
+async function readRange(ns, query, offset, count) {
+  const reads = [];
+  for (let start = 0; start < count; start += MAX_ROWS_PER_READ) {
+    const limit = Math.min(MAX_ROWS_PER_READ, count - start);
+    reads.push(ns.list({ ...query, limit, offset: offset + start }));
+  }
+  const answers = await Promise.all(reads);
+  const rows = [];
+  let total = null;
+  for (const res of answers) {
+    if (res && Array.isArray(res.data)) rows.push(...res.data);
+    if (res && res.meta && Number.isFinite(res.meta.total)) total = res.meta.total;
+  }
+  return { rows, total };
+}
+
+// A row that moved into the next page between two reads shows once.
+function withoutRepeats(first, more) {
+  if (more.length === 0) return first;
+  const seen = new Set();
+  const out = [];
+  for (const row of [...first, ...more]) {
+    const id = row && row.id;
+    if (id !== undefined && id !== null) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+/**
+ * A table's rows, `pageSize` at a time, with `loadMore()` appending the next
+ * page. See the usePagedDatastoreQuery CONTRACT entry.
+ */
+export function usePagedDatastoreQuery(table, options) {
+  const ctx = useWidgetContextOrThrow("usePagedDatastoreQuery");
+  // `limit` and `offset` are the hook's to set, so a caller's are dropped.
+  // eslint-disable-next-line no-unused-vars
+  const { pageSize: requestedPageSize, limit, offset, ...query } = options || {};
+  const pageSize = normalisePageSize(requestedPageSize);
+  const boundTable = table || null;
+  const first = useDatastoreQuery(boundTable, { ...query, limit: pageSize });
+
+  const key = boundTable ? windowKey(boundTable, pageSize, query) : null;
+  const [more, setMore] = useState(NO_PAGES);
+  // The page read in flight or failed: { key, seq, pages, appending, error }.
+  const [op, setOp] = useState(null);
+  // A new query drops the old one's pages and reads before they can return.
+  const [windowOf, setWindowOf] = useState(key);
+  if (windowOf !== key) {
+    setWindowOf(key);
+    setMore(NO_PAGES);
+    setOp(null);
+  }
+
+  // Live inputs held in refs so loadMore / retry stay stable callbacks.
+  const live = useRef({});
+  live.current = {
+    key,
+    table: boundTable,
+    pageSize,
+    query,
+    records: ctx.datastore && ctx.datastore.records,
+    firstFetching: first.fetching,
+    more: more.key === key ? more : NO_PAGES,
+    op: op && op.key === key ? op : null,
+  };
+  const seqRef = useRef(0);
+  useEffect(() => {
+    seqRef.current += 1;
+  }, [key]);
+
+  // Reads pages 1..`pages` after the first one; `appending` reads only the last.
+  const readPages = useCallback(async (pages, appending) => {
+    const { key: k, table: t, pageSize: size, query: q, records, more: m } = live.current;
+    if (!k || !records) return;
+    const seq = ++seqRef.current;
+    setOp({ key: k, seq, pages, appending, error: null });
+    const from = appending ? pages : 1;
+    try {
+      const { rows, total } = await readRange(records(t), q, from * size, (pages - from + 1) * size);
+      if (seqRef.current !== seq || live.current.key !== k) return;
+      setMore({ key: k, rows: appending ? [...m.rows, ...rows] : rows, pages, total });
+      setOp(null);
+    } catch (err) {
+      if (seqRef.current !== seq || live.current.key !== k) return;
+      setOp({ key: k, seq, pages, appending, error: toDatastoreError(err) });
+    }
+  }, []);
+
+  const current = live.current.more;
+  const pending = live.current.op;
+  const total = first.total !== null ? first.total : current.total;
+  const loaded = current.pages === 0 ? first.data.length : pageSize + current.rows.length;
+  const lastPageFull = current.pages === 0 ? first.data.length >= pageSize : current.rows.length >= current.pages * pageSize;
+  const hasMore = Boolean(key) && !first.loading && !first.error && (total !== null ? loaded < total : lastPageFull);
+  live.current.hasMore = hasMore;
+
+  const loadMore = useCallback(() => {
+    const { key: k, more: m, op: o, hasMore: canLoad, firstFetching } = live.current;
+    if (!canLoad) return;
+    if (m.pages === 0 && firstFetching && !o) {
+      // The first page may still be the previous query's: wait for it.
+      setOp({ key: k, seq: ++seqRef.current, pages: 1, appending: true, queued: true, error: null });
+      return;
+    }
+    if (o && !o.error) {
+      // A page is already on its way; a re-read in flight takes one page more.
+      if (!o.appending) readPages(o.pages + 1, false);
+      return;
+    }
+    readPages(m.pages + 1, true);
+  }, [readPages]);
+
+  // A re-read of the first page (a write, `live`, refetch, pull-to-refresh)
+  // re-reads the pages after it, so the whole list shown stays current.
+  const firstRows = useRef(first.data);
+  useEffect(() => {
+    if (firstRows.current === first.data) return;
+    firstRows.current = first.data;
+    const { more: m, op: o } = live.current;
+    if (o && o.queued && m.pages === 0) {
+      readPages(1, true);
+      return;
+    }
+    const pages = Math.max(m.pages, o && !o.error ? o.pages : 0);
+    if (pages > 0) readPages(pages, false);
+  }, [first.data, readPages]);
+
+  const refetch = first.refetch;
+  const firstFailed = Boolean(first.error);
+  const firstFailedRef = useRef(firstFailed);
+  firstFailedRef.current = firstFailed;
+  const retry = useCallback(() => {
+    const o = live.current.op;
+    if (o && o.error) readPages(o.pages, o.appending);
+    if (firstFailedRef.current || !(o && o.error)) refetch();
+  }, [readPages, refetch]);
+
+  const data = useMemo(
+    () => withoutRepeats(first.data, current.rows),
+    [first.data, current.rows],
+  );
+  const waiting = Boolean(pending && !pending.error && !(pending.queued && firstFailed));
+  const loadingMore = waiting && pending.appending;
+  return {
+    data,
+    total,
+    hasMore,
+    loading: first.loading,
+    fetching: first.fetching || waiting,
+    loadingMore,
+    error: first.error || (pending && pending.error) || null,
+    loadMore,
+    retry,
+    refetch,
+  };
+}

package/dist/source-mask.cjs

@@ -28,8 +28,10 @@ function stripNonCode(
   source,
   { keepStrings = false, keepTemplates = keepStrings } = {},
 ) {
-  let out = "";
   const n = source.length;
+  // Code units, not `out += ch`: a per-character rope costs superlinear GC.
+  const out = new Uint16Array(n);
+  let written = 0;
   let mode = "code"; // code | line | block | sq | dq | tmpl
   // Brace depth, plus a stack of the depths at which an enclosing template
   // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
@@ -37,10 +39,10 @@ function stripNonCode(
   let braceDepth = 0;
   const tmplStack = [];
   const keep = (ch) => {
-    out += ch;
+    out[written++] = ch.charCodeAt(0);
   };
   const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
+    out[written++] = ch === "\n" || ch === "\r" ? ch.charCodeAt(0) : SPACE;
   };
   // String / template CONTENT: blanked for the banned-identifier scan
   // (prose must not trip `no-window`), kept for the host-API-URL scan,
@@ -162,7 +164,19 @@ function stripNonCode(
       }
     }
   }
-  return out;
+  return decodeCodeUnits(out.subarray(0, written));
+}
+
+const SPACE = 0x20;
+// fromCharCode spreads its arguments, so decode in stack-safe chunks.
+const DECODE_CHUNK = 8192;
+
+function decodeCodeUnits(units) {
+  const parts = [];
+  for (let at = 0; at < units.length; at += DECODE_CHUNK) {
+    parts.push(String.fromCharCode.apply(null, units.subarray(at, at + DECODE_CHUNK)));
+  }
+  return parts.join("");
 }
 module.exports = {
   stripNonCode,

package/dist/source-mask.js

@@ -24,8 +24,10 @@ export function stripNonCode(
   source,
   { keepStrings = false, keepTemplates = keepStrings } = {},
 ) {
-  let out = "";
   const n = source.length;
+  // Code units, not `out += ch`: a per-character rope costs superlinear GC.
+  const out = new Uint16Array(n);
+  let written = 0;
   let mode = "code"; // code | line | block | sq | dq | tmpl
   // Brace depth, plus a stack of the depths at which an enclosing template
   // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
@@ -33,10 +35,10 @@ export function stripNonCode(
   let braceDepth = 0;
   const tmplStack = [];
   const keep = (ch) => {
-    out += ch;
+    out[written++] = ch.charCodeAt(0);
   };
   const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
+    out[written++] = ch === "\n" || ch === "\r" ? ch.charCodeAt(0) : SPACE;
   };
   // String / template CONTENT: blanked for the banned-identifier scan
   // (prose must not trip `no-window`), kept for the host-API-URL scan,
@@ -158,5 +160,17 @@ export function stripNonCode(
       }
     }
   }
-  return out;
+  return decodeCodeUnits(out.subarray(0, written));
+}
+
+const SPACE = 0x20;
+// fromCharCode spreads its arguments, so decode in stack-safe chunks.
+const DECODE_CHUNK = 8192;
+
+function decodeCodeUnits(units) {
+  const parts = [];
+  for (let at = 0; at < units.length; at += DECODE_CHUNK) {
+    parts.push(String.fromCharCode.apply(null, units.subarray(at, at + DECODE_CHUNK)));
+  }
+  return parts.join("");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.281.0",
+  "version": "0.283.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -418,6 +418,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1988,6 +1998,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -6663,7 +6709,11 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  version: "1.232.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6689,6 +6739,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.