@colixsystems/widget-sdk 0.176.0 → 0.179.0

package/README.md

@@ -43,7 +43,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
 | **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** | `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, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching` | `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:*` |
+| **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>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
@@ -73,7 +74,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.176.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.179.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.179.0 (contract 1.140.0)
+
+**`<Card>` no longer discards the layout in its `style` (sc-9200).** `style` was read for the `card*` design fields alone, so `<Card style={{ width: "100%" }}>` sized nothing and every layout key vanished without a warning — a widget could not lay its cards out by its measured width, because the `widthTier()` branch set exactly that. A card that brings no `baseStyle` now also takes the box's **layout** from `style`: width, height, the flex properties, `alignSelf`, `gap` and position (`CARD_LAYOUT_STYLE_FIELDS`). The app's card look is kept:
+
+```jsx
+<Card style={{ width: "100%", maxWidth: 480, alignSelf: "center" }}>…</Card>
+```
+
+Layout only, deliberately: a widget is told to hand `<Card>` its whole declared style bag, so forwarding everything that is not a `card*` field would put design fields (`background`, `fontSize`, `titleColor`) on the box — and react-native-web renders an unknown key as real CSS where React Native drops it, which is one widget rendering two different cards. The paint stays the card's own vocabulary (`cardBackground`, `cardRadius`, `padding`, `shadow`); anything else about the container goes on `containerStyle`.
+
+A card given a `baseStyle` is unchanged: that caller owns the container's layout, so its `style` is still read for the `card*` fields only — the contract the built-in widgets pass their per-instance style on.
+
+### What's new in 0.178.0 (contract 1.139.0)
+
+**New optional manifest field `drawsFigures` (sc-9150).** A boolean (default `false`) that declares your widget draws a strip of live figures, such as "12 pending" or "€4,200 this month", about the records it shows, or is itself a strip of figures. Set it `true` when your widget draws them (for example with `useDatastoreFigure` and `<Stat>`). The AppStudio app-builder then counts the widget as the page's figures when it reuses it on a page, and does not plan a second strip of figures beside it. Leave it `false` or omit it when the widget draws no figures. Additive: existing manifests omit it and read `false`, so no widget needs changing.
+
+### What's new in 0.177.0 (contract 1.138.0)
+
+**`useDatastoreFigure(tableId, { aggregate, column, filter })` — one live figure over a table, for a `<Stat>`.** A custom widget showing "12 pending" above its list had to reduce `useDatastoreQuery` rows by hand, and nothing told it to skip blank cells, apply a filter, or admit the 1000-row query ceiling. The built-in Stat widget's figure logic is now this hook, and the Stat widget computes through it. `aggregate` is `"count"` (the default), `"sum"` or `"average"` of the number `column`, and `filter` takes the same shapes as `useDatastoreQuery`. It returns `{ value, text, truncated, loading, fetching, error, refetch }`: pass `text` to `<Stat value>`. It is null while loading or when there is no figure, so the tile prints its empty value, never a fake 0. A count is exact: it reads the server's total and fetches a single row. A sum or average reads up to 1000 rows and, when the table holds more, reads "≈ n" with `truncated: true`. Filter on a bound column only once `useBoundColumns` has resolved (pass `null` as the table until then), or the first read is unfiltered.
+
+**`useDatastoreQuery` returns `total`**: how many rows the query matches in all (the envelope's `meta.total`), not only the page in `data`.
 
 ### What's new in 0.176.0 (contract 1.137.0)
 
@@ -160,7 +183,7 @@ Installed widgets pick up the row fix with no rebuild on the web: the Player han
 - **`<Badge>`** is a record's state (Active, Paid, Overdue) beside the thing it describes. `tone` is `neutral` | `info` | `success` | `warning` | `danger`, tinted from the app's theme; the label always shows.
 - **`<Avatar>`** is a person: a picture, else the name's initials, else a person glyph. `size` is `sm` | `md` | `lg` | `xl` or a number of px.
 - **`<Progress>`** is real progress toward a goal, as a `bar` or a `ring`; the percent is clamped to 0-100 and printed.
-- **`<Stat>`** displays a headline figure you computed, with an optional caption, icon and delta. An empty value prints `emptyValue` (default "—"), never a fake 0.
+- **`<Stat>`** displays a headline figure (compute a live one with `useDatastoreFigure`), with an optional caption, icon and delta. An empty value prints `emptyValue` (default "—"), never a fake 0.
 - **`<Divider>`** splits two groups inside one surface, optionally captioned. A `<List>` and a `<Card>` already draw their own edges.
 
 `initialsFor(name)` is exported too. Additive: the built-in widgets render as before.

package/dist/card-style.js

@@ -62,6 +62,50 @@ export function cardOverlay(style) {
   return { ...cardSurfaceStyle(style), ...marginStyle(style || {}) };
 }
 
+/**
+ * The React Native layout properties a card may be given through `style` —
+ * how big the box is and where it sits, nothing about how it is painted.
+ *
+ * An ALLOWLIST, because a widget is told to hand `<Card>` its whole declared
+ * style bag: forwarding whatever is not a `card*` field would put design
+ * fields (`background`, `fontSize`, `titleColor`) on the box, and
+ * react-native-web renders an unknown key as real CSS where native drops it —
+ * two hosts, one widget, different cards (CLAUDE.md §8). Paint stays the
+ * card's own vocabulary (`cardBackground`, `cardRadius`, `padding`, `shadow`);
+ * anything else on the container goes through `containerStyle`.
+ */
+export const CARD_LAYOUT_STYLE_FIELDS = Object.freeze([
+  "width", "minWidth", "maxWidth",
+  "height", "minHeight", "maxHeight",
+  "aspectRatio",
+  "flex", "flexBasis", "flexGrow", "flexShrink", "alignSelf",
+  "flexDirection", "flexWrap", "justifyContent", "alignItems", "alignContent",
+  "gap", "rowGap", "columnGap",
+  "position", "top", "right", "bottom", "left", "start", "end", "zIndex",
+  "display", "overflow",
+]);
+
+/**
+ * The layout a card's `style` declares. Returning it is what keeps
+ * `<Card style={{ width: "100%" }}>` from being silently dropped; a card
+ * declaring none yields null, so it emits no extra style object.
+ *
+ * An `undefined` value is skipped rather than copied: react-native-web's
+ * styleq ignores it while React Native's flattenStyle assigns it, so copying
+ * one would clear the theme's value on native alone.
+ */
+export function cardLayoutStyle(style) {
+  if (!style || typeof style !== "object" || Array.isArray(style)) return null;
+  const out = {};
+  let any = false;
+  for (const key of CARD_LAYOUT_STYLE_FIELDS) {
+    if (style[key] === undefined) continue;
+    out[key] = style[key];
+    any = true;
+  }
+  return any ? out : null;
+}
+
 /**
  * A gradient value as `<Gradient>` props, or null when unpaintable. A
  * per-instance value runs through the same normaliser the theme uses, so the

package/dist/card-view.js

@@ -9,7 +9,12 @@ import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { CONTRACT } from "./contract.js";
-import { cardOverlay, cardSurfaceStyle, cardGradientProps } from "./card-style.js";
+import {
+  cardOverlay,
+  cardSurfaceStyle,
+  cardGradientProps,
+  cardLayoutStyle,
+} from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 
 // A wrapped scroller stays transparent and fits inside the gradient.
@@ -75,9 +80,16 @@ export function makeCard(rn) {
 
   /**
    * @param {object} [props.style] — `card*` fields, `shadow`, `margin`
-   *   (a widget's per-instance style, theme tokens already folded in).
+   *   (a widget's per-instance style, theme tokens already folded in). On a
+   *   card with no `baseStyle` it also carries the box's LAYOUT
+   *   (`CARD_LAYOUT_STYLE_FIELDS`), so `style={{ width: "100%" }}` sizes the
+   *   card rather than vanishing. Under `as` + a gradient the layout rides the
+   *   gradient — the card's real box — so the content keys there
+   *   (`flexDirection`, `gap`, …) arrange the wrapper, not the inner children.
    * @param {object|Array} [props.baseStyle] — the caller's own base style. A
-   *   card given none starts from the theme's surface and `card` scope.
+   *   card given none starts from the theme's surface and `card` scope. A
+   *   caller that supplies one owns the container's layout, so its `style` is
+   *   read for `card*` fields only — that is the built-in widgets' contract.
    * @param {React.ElementType} [props.as] — container; anything but `View`
    *   renders INSIDE the gradient, never as it. Other props land on it.
    * @param {boolean} [props.fillInGradient] — the inner container stretches to
@@ -117,6 +129,8 @@ export function makeCard(rn) {
       ...explicit,
     };
     const base = standalone ? themedBase(theme) : baseStyle;
+    // Last, so an author's own declaration beats the theme's surface.
+    const layout = standalone ? cardLayoutStyle(style) : null;
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
     const gradient = cardGradientProps(fields);
@@ -124,7 +138,7 @@ export function makeCard(rn) {
     if (!gradient) {
       return React.createElement(
         Container,
-        { style: composeStyle([base, overlay], containerStyle), ...rest },
+        { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
         children,
       );
     }
@@ -139,7 +153,7 @@ export function makeCard(rn) {
         {
           colors: gradient.colors,
           angle: gradient.angle,
-          style: composeStyle([base, paint], containerStyle),
+          style: composeStyle([base, paint, layout], containerStyle),
           ...rest,
         },
         children,
@@ -153,7 +167,8 @@ export function makeCard(rn) {
       {
         colors: gradient.colors,
         angle: gradient.angle,
-        style: [base, paint, CLIP_TO_RADIUS],
+        // Before the clip: it keeps the gradient inside the corners, not a default.
+        style: [base, paint, layout, CLIP_TO_RADIUS],
       },
       React.createElement(
         Container,

package/dist/contract.cjs

@@ -1395,9 +1395,43 @@ const HOOKS = [
       "`_capabilities` { can_read, can_write, can_delete, can_grant } — what " +
       "the signed-in user may do to THAT row, the answer update/delete " +
       "enforce, computed for the whole page in one lookup. Gate a row's " +
-      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`.",
+      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
+      "`total` is how many rows the query matches in all (the envelope's " +
+      "meta.total), not just the page in `data`; null until known.",
     returnShape: {
       data: "Record[]",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
+  {
+    name: "useDatastoreFigure",
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
+    optionalArgs: ["aggregate", "column", "filter"],
+    description:
+      "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
+      "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
+      "or \"average\" (of the NUMBER `column`). `filter` takes the same shapes " +
+      "as useDatastoreQuery's; name a bound column through useBoundColumns and " +
+      "pass null as the table until its `loading` is false, or the first read " +
+      "runs unfiltered: useDatastoreFigure(columnsLoading ? null : tableId, " +
+      "{ filter: [{ column: bound.statusField, operator: \"eq\", value: \"Pending\" }] }). " +
+      "Render `<Stat value={figure.text} label=\"Pending\" />`: `text` is null " +
+      "while loading or when there is no figure, so the tile prints its empty " +
+      "value, never a fake 0. A count is exact, from the server's total. A sum " +
+      "or average reads up to 1000 rows, skips blank cells rather than counting " +
+      "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
+      "Stat widget computes its figure through this hook, so use it rather than " +
+      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+    returnShape: {
+      value: "number | null",
+      text: "string | null  // the formatted figure for <Stat value>",
+      truncated: "boolean",
       loading: "boolean",
       fetching: "boolean",
       error: "DatastoreError | null",
@@ -2418,7 +2452,7 @@ const PRIMITIVES = [
   {
     name: "Stat",
     description:
-      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure, so compute it yourself (e.g. from `useDatastoreQuery` rows). An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2439,7 +2473,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2655,6 +2689,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
     default: false,
   },
+  drawsFigures: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget draws a strip of live figures (counts, totals, averages) about the records it shows, or is itself a strip of figures. The AppStudio app-builder reads this when it places an already-installed widget: it counts the widget as the page's figures, so it does not plan a second strip of figures beside it. Set it to match what the component actually renders; leave it false (or omit) when the widget draws no figures.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -4716,7 +4757,14 @@ const CONTRACT = deepFreeze({
   //    without saving it, through the new `device.pdfViewer` host slice. And
   //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
   //    "print version" as a plain-text blob that never worked on native.
-  version: "1.137.0",
+  // 1.137.0: additive (sc-9142) — `manifest.description` is optional.
+  // 1.138.0: additive (sc-9150) — `useDatastoreFigure`, and
+  //    `useDatastoreQuery` returns the envelope's `total`.
+  // 1.139.0: additive (sc-9150) — new OPTIONAL manifest field `drawsFigures`
+  //    (boolean, default false): the widget draws live figures about its
+  //    records, so the app-builder counts it as the page's figures when it
+  //    reuses it. Existing manifests omit it and read false.
+  version: "1.140.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1395,9 +1395,43 @@ const HOOKS = [
       "`_capabilities` { can_read, can_write, can_delete, can_grant } — what " +
       "the signed-in user may do to THAT row, the answer update/delete " +
       "enforce, computed for the whole page in one lookup. Gate a row's " +
-      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`.",
+      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
+      "`total` is how many rows the query matches in all (the envelope's " +
+      "meta.total), not just the page in `data`; null until known.",
     returnShape: {
       data: "Record[]",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
+  {
+    name: "useDatastoreFigure",
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
+    optionalArgs: ["aggregate", "column", "filter"],
+    description:
+      "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
+      "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
+      "or \"average\" (of the NUMBER `column`). `filter` takes the same shapes " +
+      "as useDatastoreQuery's; name a bound column through useBoundColumns and " +
+      "pass null as the table until its `loading` is false, or the first read " +
+      "runs unfiltered: useDatastoreFigure(columnsLoading ? null : tableId, " +
+      "{ filter: [{ column: bound.statusField, operator: \"eq\", value: \"Pending\" }] }). " +
+      "Render `<Stat value={figure.text} label=\"Pending\" />`: `text` is null " +
+      "while loading or when there is no figure, so the tile prints its empty " +
+      "value, never a fake 0. A count is exact, from the server's total. A sum " +
+      "or average reads up to 1000 rows, skips blank cells rather than counting " +
+      "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
+      "Stat widget computes its figure through this hook, so use it rather than " +
+      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+    returnShape: {
+      value: "number | null",
+      text: "string | null  // the formatted figure for <Stat value>",
+      truncated: "boolean",
       loading: "boolean",
       fetching: "boolean",
       error: "DatastoreError | null",
@@ -2418,7 +2452,7 @@ const PRIMITIVES = [
   {
     name: "Stat",
     description:
-      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure, so compute it yourself (e.g. from `useDatastoreQuery` rows). An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
+      'Themed headline figure. `<Stat value={openCount} label="Open orders" delta="+3 this week" deltaTone="positive" icon="package" />`. THE way to show one headline number in a summary tile; put peer tiles side by side in a row. It only DISPLAYS a figure: compute a count, sum or average over a table with `useDatastoreFigure` and pass its `text`. An empty value (null, undefined, blank text, NaN) prints `emptyValue` (default "—") in the muted tier, never a fake 0. Props: `value` (string or number), `label`, `icon` (lucide name), `delta`, `deltaTone` ("neutral" | "positive" | "negative"), `emptyValue`, `color` and `fontSize` (12-96) for the figure, `style`, `testID`.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2439,7 +2473,7 @@ const PRIMITIVES = [
   {
     name: "Card",
     description:
-      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A card that brings no `baseStyle` also takes the box\'s LAYOUT from `style` — width, height, the flex properties, `alignSelf`, `gap`, position — so `style={{ width: \'100%\', maxWidth: 480, alignSelf: \'center\' }}` sizes the card and still keeps the app\'s card look; put anything else about the container on `containerStyle`. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2651,6 +2685,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
     default: false,
   },
+  drawsFigures: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget draws a strip of live figures (counts, totals, averages) about the records it shows, or is itself a strip of figures. The AppStudio app-builder reads this when it places an already-installed widget: it counts the widget as the page's figures, so it does not plan a second strip of figures beside it. Set it to match what the component actually renders; leave it false (or omit) when the widget draws no figures.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -4712,7 +4753,14 @@ const CONTRACT = deepFreeze({
   //    without saving it, through the new `device.pdfViewer` host slice. And
   //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
   //    "print version" as a plain-text blob that never worked on native.
-  version: "1.137.0",
+  // 1.137.0: additive (sc-9142) — `manifest.description` is optional.
+  // 1.138.0: additive (sc-9150) — `useDatastoreFigure`, and
+  //    `useDatastoreQuery` returns the envelope's `total`.
+  // 1.139.0: additive (sc-9150) — new OPTIONAL manifest field `drawsFigures`
+  //    (boolean, default false): the widget draws live figures about its
+  //    records, so the app-builder counts it as the page's figures when it
+  //    reuses it. Existing manifests omit it and read false.
+  version: "1.140.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datastore-figure.js

@@ -0,0 +1,27 @@
+// The hook half of ./figure.js: one live figure over a table, shared by the
+// stock Stat widget and custom widgets on both hosts.
+import { useDatastoreQuery } from "./hooks.js";
+import { figureQuery, reduceFigure } from "./figure.js";
+
+/**
+ * sc-9150 — one live count, sum or average over a table; see the
+ * useDatastoreFigure CONTRACT entry. Built on useDatastoreQuery, so a changed
+ * `filter` keeps the previous figure on screen while `fetching`.
+ */
+export function useDatastoreFigure(table, options) {
+  const { aggregate, column, filter } = options || {};
+  const rows = useDatastoreQuery(table || null, figureQuery(filter, aggregate));
+  const figure =
+    table && !rows.loading && !rows.error
+      ? reduceFigure(rows.data, { aggregate, column }, rows.total)
+      : null;
+  return {
+    value: figure ? figure.value : null,
+    text: figure ? figure.text : null,
+    truncated: figure ? figure.truncated : false,
+    loading: rows.loading,
+    fetching: rows.fetching,
+    error: rows.error,
+    refetch: rows.refetch,
+  };
+}

package/dist/figure.js

@@ -0,0 +1,59 @@
+// The pure rules behind `useDatastoreFigure`: which rows a figure reads and how
+// they reduce to the one number a `<Stat>` shows. Plain JS, no React, so the
+// stock Stat and every custom widget count the same way on both hosts.
+
+export const FIGURE_AGGREGATES = Object.freeze(["count", "sum", "average"]);
+
+// REQ-QUERY-02 clamps every datastore query to 1000 rows, so a sum or average
+// over a bigger table is reduced from a truncated page and must say so.
+export const FIGURE_ROW_CEILING = 1000;
+
+/** The aggregate to run: an unknown or missing one counts rows. */
+export function figureAggregate(aggregate) {
+  return FIGURE_AGGREGATES.includes(aggregate) ? aggregate : "count";
+}
+
+function hasFilter(filter) {
+  return Array.isArray(filter)
+    ? filter.length > 0
+    : Boolean(filter) && typeof filter === "object" && Object.keys(filter).length > 0;
+}
+
+/**
+ * The rows query a figure reads. A count needs only the envelope's exact
+ * `meta.total`, so it fetches one row; a sum or average reads up to the ceiling.
+ */
+export function figureQuery(filter, aggregate) {
+  const limit = figureAggregate(aggregate) === "count" ? 1 : FIGURE_ROW_CEILING;
+  return hasFilter(filter) ? { limit, filter } : { limit };
+}
+
+// Whole numbers stay whole; an average keeps two decimals at most.
+function formatNumber(n) {
+  return Number.isInteger(n) ? String(n) : String(Math.round(n * 100) / 100);
+}
+
+/**
+ * Reduce a figure query's result to `{ value, text, truncated }`, or null when
+ * there is nothing honest to show. `total` is how many rows the query matched;
+ * a sum or average over fewer rows than that is prefixed "≈ ".
+ */
+export function reduceFigure(rows, { aggregate, column } = {}, total = null) {
+  if (!Array.isArray(rows)) return null;
+  const known = Number.isFinite(total);
+  if (figureAggregate(aggregate) === "count") {
+    return known ? { value: total, text: String(total), truncated: false } : null;
+  }
+  if (!column) return null;
+  // Number(null) and Number("") are 0: coercing would count a blank or
+  // permission-hidden cell as a real zero. A NUMBER cell arrives as a number.
+  const numbers = rows
+    .map((row) => (row ? row[column] : undefined))
+    .filter((cell) => typeof cell === "number" && Number.isFinite(cell));
+  if (numbers.length === 0) return null;
+  const sum = numbers.reduce((acc, n) => acc + n, 0);
+  const value = aggregate === "average" ? sum / numbers.length : sum;
+  if (!Number.isFinite(value)) return null;
+  const truncated = known ? total > rows.length : rows.length >= FIGURE_ROW_CEILING;
+  return { value, text: `${truncated ? "≈ " : ""}${formatNumber(value)}`, truncated };
+}

package/dist/hooks.js

@@ -2173,7 +2173,7 @@ function toDatastoreError(err) {
 // on a genuine loop.
 const VOLATILE_QUERY_RENDER_LIMIT = 10;
 
-const NO_QUERY_RESULT = { key: null, table: null, data: null, error: null, loaded: false };
+const NO_QUERY_RESULT = { key: null, table: null, data: null, total: null, error: null, loaded: false };
 const NO_RECORD_RESULT = { key: null, data: null, error: null, loaded: false };
 
 function serializeQuery(query) {
@@ -2189,8 +2189,8 @@ const recordResultKey = (table, recordId, includeCapabilities = false) =>
   JSON.stringify([table, recordId, includeCapabilities]);
 
 /**
- * Stateful datastore query hook. Returns { data, loading, fetching, error,
- * refetch }.
+ * Stateful datastore query hook. Returns { data, total, loading, fetching,
+ * error, refetch }.
  *
  * The host injects a `@colixsystems/datastore-client` instance at
  * `ctx.datastore`. We call `ctx.datastore.records(table).list(query)`, which
@@ -2207,6 +2207,9 @@ const recordResultKey = (table, recordId, includeCapabilities = false) =>
  * `_capabilities` ({ can_read, can_write, can_delete, can_grant }), computed
  * for the whole page in one server lookup. Gate a row's Edit / Delete on it.
  *
+ * sc-9150 — `total` is the envelope's `meta.total`: how many rows the query
+ * matches, beyond the page in `data`. null until known.
+ *
  * sc-8595 — stale-while-revalidate. `loading` is true only until the first
  * result for the bound TABLE lands. A changed query on that table, `refetch()`
  * and a page pull-to-refresh keep the rows already in `data` on screen with
@@ -2274,9 +2277,10 @@ export function useDatastoreQuery(table, query) {
       // The datastore-client returns the { data, meta } list envelope
       // verbatim — unwrap to the rows array (default []).
       const rows = res && Array.isArray(res.data) ? res.data : [];
+      const total = res && res.meta && Number.isFinite(res.meta.total) ? res.meta.total : null;
       // Discard the result if a newer fetch has started since we kicked off.
       if (runRef.current !== myRun) return;
-      setSettled({ key, table: t, data: rows, error: null, loaded: true });
+      setSettled({ key, table: t, data: rows, total, error: null, loaded: true });
       setInFlight(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
@@ -2285,7 +2289,7 @@ export function useDatastoreQuery(table, query) {
       setSettled((prev) =>
         prev.table === t && prev.loaded
           ? { ...prev, key, error }
-          : { key, table: t, data: emptyRows, error, loaded: false },
+          : { key, table: t, data: emptyRows, total: null, error, loaded: false },
       );
       setInFlight(false);
     }
@@ -2340,6 +2344,7 @@ export function useDatastoreQuery(table, query) {
   const hasRows = Boolean(table) && settled.table === table && settled.loaded;
   return {
     data: hasRows ? settled.data : emptyRows,
+    total: hasRows ? settled.total : null,
     loading: !hasRows && busy,
     fetching: busy,
     error: table && !busy && settled.table === table ? settled.error : null,

package/dist/index.d.ts

@@ -843,6 +843,8 @@ export interface RecordCapabilities {
 
 export interface QueryResult<T> {
   data: T[];
+  /** How many rows the query matches in all, not just this page; null until known. */
+  total: number | null;
   /**
    * True only until the first result for the bound table lands. A changed
    * query on the same table, `refetch()` and pull-to-refresh keep the rows
@@ -866,6 +868,34 @@ export function useDatastoreQuery<T = unknown>(
   query?: Query,
 ): QueryResult<T>;
 
+export interface FigureOptions {
+  /** Default `"count"`. `"sum"` and `"average"` read the number `column`. */
+  aggregate?: "count" | "sum" | "average";
+  column?: string;
+  /** The rows the figure covers, in any shape `Query.filter` accepts. */
+  filter?:
+    | Query["filter"]
+    | Array<{ column: string; operator: string; value?: unknown; valueMode?: string }>;
+}
+
+export interface FigureResult {
+  value: number | null;
+  /** The formatted figure for `<Stat value>`; null while loading or when there is none. */
+  text: string | null;
+  /** A sum or average read fewer rows than the table holds, so `text` reads "≈ n". */
+  truncated: boolean;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+}
+
+/** One live count, sum or average over a table, as the stock Stat computes it. */
+export function useDatastoreFigure(
+  table: string | null | undefined,
+  options?: FigureOptions,
+): FigureResult;
+
 export function useDatastoreMutation<T = unknown>(
   table: string,
 ): MutationApi<T>;
@@ -2775,7 +2805,14 @@ export const Card: (props: {
   padding?: number | { top?: number; right?: number; bottom?: number; left?: number };
   shadow?: "none" | "sm" | "md" | "lg";
   gradient?: { from: string; to: string; angle?: number };
-  /** `card*` style fields, `shadow`, `margin` — a widget's per-instance style. */
+  /**
+   * `card*` style fields, `shadow`, `margin` — a widget's per-instance style.
+   * With no `baseStyle` it also carries the box's layout (width, height, the
+   * flex properties, `alignSelf`, `gap`, position), so `{ width: "100%" }`
+   * sizes the card; anything else about the container goes on
+   * `containerStyle`. Read for the `card*` fields alone when `baseStyle` is
+   * given — the contract the built-in widgets pass their whole style bag on.
+   */
   style?: Record<string, any>;
   /** The caller's own base style; a card given none starts from the theme. */
   baseStyle?: any;

package/dist/index.js

@@ -104,6 +104,7 @@ export {
 // the web variant and index.native.js picks the native variant.
 export { useClipboard, ClipboardError } from "./clipboard.js";
 export { useToast } from "./toast.js";
+export { useDatastoreFigure } from "./datastore-figure.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box
 // identically on the Player and the Expo export.

package/dist/index.native.js

@@ -102,6 +102,7 @@ export {
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";
+export { useDatastoreFigure } from "./datastore-figure.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";
 // sc-8104 — see the note on the web mirror in ./index.js.

package/package.json

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