@colixsystems/widget-sdk 0.267.0 → 0.267.1

package/README.md

@@ -50,7 +50,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **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:*` |
+| **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 }`, applied on the server: 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>` |
@@ -86,7 +86,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.267.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.267.1` — 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.267.1 (contract 1.217.0)
+
+**The record query options are documented where an author reads them.** A new *Querying records* section lists everything `useDatastoreQuery` sends to the server — `filter` and its operators, `filterMode`, `q`, `sort`, `limit` (50 by default, at most 1000) and `offset` — with `total` for paging and a searchable, paged list to start from. The `Query` type now declares `q`, `offset`, `filterMode` and both filter and sort shapes, and marks `cursor`, which the datastore never read, deprecated. No runtime change.
 
 ### What's new in 0.267.0 (contract 1.217.0)
 
@@ -3543,6 +3547,64 @@ export default function OpenTasks({ tableId, titleField, statusField }) {
 
 `useCanWrite(tableId)` answers "may I create a row here". It says nothing about changing an EXISTING row: gate a list's Edit / Delete on each row's `_capabilities` (read with `includeCapabilities: true`, see *What's new in 0.174.0*), and a single-record page on `useCanWrite(tableId, { recordId })` or `useDatastoreRecord(…, { includeCapabilities: true })`. Never call `useCanWrite` with a `recordId` per list row — that is one request per row. Either answer is a FLOOR, not the whole rule: a widget whose own logic is more specific ("only the assignee may edit this row") still hand-checks that in addition (`user.id === record[assigneeField]`).
 
+## Querying records
+
+`useDatastoreQuery(tableId, query)` hands `query` to the datastore, which filters, searches, sorts and pages the table before a row reaches the widget. Every key is optional. Build the object with `useStableQuery` so it does not refetch every render.
+
+| Option | What the server does with it |
+| --- | --- |
+| `filter` | Keeps the rows that match. A map `{ column: "op:value" }` (an array of expressions puts a range on one column), or an array `[{ column, operator, value }]`. |
+| `filterMode` | `"and"` (the default) keeps rows matching every condition; `"or"` keeps rows matching any. |
+| `q` | Free-text search: a case-insensitive substring match across every text column of the table (encrypted columns excepted). |
+| `sort` | `{ field, dir }` with `dir` `"asc"` or `"desc"`, or the string `"field:desc"`. One column; `created_at` and `updated_at` work too. |
+| `limit` | Rows per page: 50 when left out, at most 1000. |
+| `offset` | Rows to skip, for the next page. |
+| `includeCapabilities` | `true` stamps each row with `_capabilities`, what the signed-in user may do to it. |
+
+The filter operators are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (a case-insensitive substring), `empty` and `nempty` (no value). 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.
+
+**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";
+
+const PAGE = 50;
+
+export default function ContactList({ tableId }) {
+  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);
+    return () => clearTimeout(wait);
+  }, [draft]);
+  const query = useStableQuery(() => ({
+    q: search,
+    filter: status ? { status: `eq:${status}` } : undefined,
+    sort: { field: "last_contacted", dir: "desc" },
+    limit: PAGE,
+    offset: page * PAGE,
+  }));
+  const { data, total, loading } = useDatastoreQuery(tableId, query);
+  const pick = (next) => { setStatus(next); setPage(0); };
+  return (
+    <View>
+      <TextInput value={draft} onChangeText={setDraft} placeholder="Search" />
+      <Pressable onPress={() => pick(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
+      {loading ? <Text>Loading…</Text> : data.map((row) => <Text key={row.id}>{row.name}</Text>)}
+      <Text>{total ?? 0} contacts</Text>
+      {(page + 1) * PAGE < (total ?? 0) ? (
+        <Pressable onPress={() => setPage(page + 1)}><Text>Next page</Text></Pressable>
+      ) : null}
+    </View>
+  );
+}
+```
+
 ## Cross-platform widgets (single-file vs split)
 
 Every widget runs in **both** the web Player and the exported native (Expo) app.

package/dist/index.d.ts

@@ -1074,10 +1074,23 @@ export function hasCornerRadius(
   radius: ResolvedCornerRadius | null | undefined,
 ): boolean;
 
+/** A record query the datastore applies on the server; see the README's "Querying records". */
 export interface Query {
-  filter?: Record<string, unknown>;
-  sort?: Array<{ field: string; dir: "asc" | "desc" }>;
+  /** `{ column: "op:value" }` (an array of expressions for a range), or `[{ column, operator, value, valueMode }]`. */
+  filter?:
+    | Record<string, string | string[]>
+    | Array<{ column: string; operator?: string; value?: unknown; valueMode?: string }>;
+  /** `"and"` (the default) keeps rows matching every condition, `"or"` rows matching any. */
+  filterMode?: "and" | "or";
+  /** A case-insensitive substring search across the table's text columns. */
+  q?: string;
+  /** `{ field, dir }` or `"field:desc"`; one column, so an array uses its first entry. */
+  sort?: string | { field: string; dir?: "asc" | "desc" } | Array<{ field: string; dir?: "asc" | "desc" }>;
+  /** Rows per page: 50 when omitted, at most 1000. */
   limit?: number;
+  /** Rows to skip, for the next page. */
+  offset?: number;
+  /** @deprecated The datastore ignores it; page with `offset`. */
   cursor?: string;
   /**
    * Stamp each row with `_capabilities` — what the signed-in user may do to

package/package.json

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