@colixsystems/widget-sdk 0.267.0 → 0.268.0

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,15 @@ 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.268.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.268.0 (contract 1.218.0)
+
+**`useAction().available` tells the truth about the Action.** It used to be true whenever an Action was bound, so a widget offered a run that could never happen. It now turns false once the server says a run would not reach the script: the Action is switched off or paused, not allowed from the app, gone, or the viewer is not a signed-in app user (signed-out visitors and anonymous accounts can't run Actions). It is asked again when the binding or the signed-in user changes, and stays true while no answer has come. The actions client (`@colixsystems/actions-client` 0.2.0) gains `status(actionId)` for it.
+
+### 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 +3551,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/contract.cjs

@@ -2184,7 +2184,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2195,7 +2200,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4150,13 +4155,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6472,7 +6478,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -3893,18 +3893,46 @@ function toActionError(err) {
  * `available` is false and `run` rejects UNAVAILABLE rather than throwing at
  * render — the widget must render a visible unbound state (CLAUDE.md §8).
  *
+ * sc-14224 — `available` also turns false once the server says a run would
+ * not reach the script: the Action is switched off, paused, not allowed from
+ * the app, gone, or the viewer is not a signed-in app user. It is asked again
+ * when the binding or the signed-in user changes. With no answer (offline, an
+ * older host) it stays true and `run` reports the refusal.
+ *
  * Routes through the injected `@colixsystems/actions-client` at `ctx.actions`,
  * so the Player and the Expo export resolve against the identical client.
  */
 export function useAction(actionRef) {
   const ctx = useWidgetContextOrThrow("useAction");
-  const available =
+  const bound =
     Boolean(actionRef) &&
     Boolean(ctx.actions) &&
     typeof ctx.actions.run === "function";
+  const canAsk = bound && typeof ctx.actions.status === "function";
+  const askedAs = `${actionRef}|${(ctx.user && ctx.user.id) || ""}`;
 
   const clientRef = useRef(null);
-  clientRef.current = available ? ctx.actions : null;
+  clientRef.current = bound ? ctx.actions : null;
+
+  // The binding and viewer the server last refused, so a rebind starts fresh.
+  const [refusedAs, setRefusedAs] = useState(null);
+  useEffect(() => {
+    const client = clientRef.current;
+    if (!canAsk || !client) return undefined;
+    let live = true;
+    client.status(actionRef).then(
+      (answer) => {
+        if (live) setRefusedAs(answer && answer.available === false ? askedAs : null);
+      },
+      // No answer is not a refusal: keep offering the run.
+      () => {},
+    );
+    return () => {
+      live = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [askedAs, canAsk]);
+  const available = bound && refusedAs !== askedAs;
   const actionIdRef = useRef(actionRef);
   actionIdRef.current = actionRef;
 

package/dist/index.d.ts

@@ -890,6 +890,8 @@ export interface WidgetContext<TProps = unknown> {
   /** sc-13843 — injected @colixsystems/actions-client backing useAction(). */
   actions?: {
     run(actionId: string, input?: Record<string, unknown> | null): Promise<{ ok: boolean; result: unknown }>;
+    /** sc-14224 — whether a run would reach the script; optional on older hosts. */
+    status?(actionId: string): Promise<{ available: boolean; reason: string | null }>;
   };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
@@ -1074,10 +1076,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
@@ -1880,7 +1895,11 @@ export interface AgentApi {
 export function useAgent(agentRef: string | null | undefined): AgentApi;
 
 export interface ActionApi {
-  /** False when no Action is bound, or the host brokers no actions client. */
+  /**
+   * False when no Action is bound, the host brokers no actions client, or the
+   * server says a run would not reach the script (switched off, not allowed
+   * from the app, or the viewer is not a signed-in app user).
+   */
   available: boolean;
   /**
    * Imperative — call from an event handler, never on mount. Resolves with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.267.0",
+  "version": "0.268.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

@@ -2181,7 +2181,12 @@ const HOOKS = [
       "`actionRef` is an Action id an author bound through an `actionRef` " +
       "property — when it is missing, or the host brokers no actions client, " +
       "`available` is false and run() rejects UNAVAILABLE; render a visible " +
-      "'pick an action' state, NEVER a blank box. A changed binding clears " +
+      "'pick an action' state, NEVER a blank box. sc-14224: `available` also " +
+      "turns false once the server says a run would not reach the script — " +
+      "the Action is switched off or paused, not allowed from the app, gone, " +
+      "or the viewer is not a signed-in app user (signed-out visitors and " +
+      "anonymous accounts can't run Actions) — so render an 'isn't available' " +
+      "state then too. It stays true while no answer has come. A changed binding clears " +
       "`result` and `error`, and a run that settles after the binding changed " +
       "(or after unmount) writes nothing. ActionError.code: " +
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
@@ -2192,7 +2197,7 @@ const HOOKS = [
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
       "Reads ctx.actions.",
     returnShape: {
-      available: "boolean  // false when no Action is bound, or the host brokers none",
+      available: "boolean  // false when no Action is bound, the host brokers none, or the server says a run would not reach the script",
       run: "(input) => Promise<unknown>  // input is optional; resolves with the Action's respond() value, or null; rejects with ActionError",
       running: "boolean  // true while any run is in flight",
       result: "unknown  // the last successful run's result; null before the first run",
@@ -4147,13 +4152,14 @@ const WIDGET_CONTEXT_SHAPE = {
   actions: {
     description:
       "sc-13843 — injected @colixsystems/actions-client instance. " +
-      "{ run(actionId, input?) -> Promise<{ ok, result }> }. Backs useAction(). " +
+      "{ run(actionId, input?) -> Promise<{ ok, result }>, status(actionId) -> " +
+      "Promise<{ available, reason }> }. Backs useAction(). " +
       "Runs one Action as the signed-in caller; the server refuses an Action " +
       "without the app trigger. Errors carry the server's `code` and `status`. " +
       "Absent on a host that brokers no actions client, where useAction() " +
       "degrades to available: false rather than throwing.",
     required: false,
-    fields: { run: "function" },
+    fields: { run: "function", status: "function" },
   },
   linkPreviews: {
     description:
@@ -6469,7 +6475,10 @@ const CONTRACT = deepFreeze({
   // 1.217.0: additive (sc-4747) — `TextInput` documents `keyboardType`,
   //    `autoCapitalize`, `autoCorrect`, `autoComplete`, `secureTextEntry`;
   //    `useDatastoreSchema` columns document `text_format` (snake_case wire).
-  version: "1.217.0",
+  // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
+  //    `useAction().available` turns false when the server says a run would
+  //    not reach the script.
+  version: "1.218.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,