@colixsystems/widget-sdk 0.176.0 → 0.180.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 }`. |
@@ -56,7 +57,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
@@ -73,7 +74,39 @@ 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.180.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.180.0 (contract 1.141.0)
+
+**`<Button>` stays readable on a coloured section.** A section that paints its own fill (a card or band on the theme's colours, or a gradient wash) already gave its text a colour that reads there. Its buttons kept the page's paint, so an `outlined` button drew its label and border in the primary colour on a band washed in that same colour, and a `secondary` fill disappeared into it. A button there is now measured against the section by the same rule as its text: a colour that already reads is kept, and one the section makes unreadable takes the section's text colour, but only when that reads better. "The section makes it unreadable" is measured against the surface the look was designed for: a colour moves only when the section costs it at least a third of the contrast it had there, so a white or lightly tinted panel changes nothing.
+
+- `outlined`: a label under 4.5:1 and a border under 3:1 against the section are re-inked.
+- `secondary`: a fill under 3:1 against the section becomes the section's outlined button.
+- `primary` and `danger`: a fill under 3:1 turns inverse, with the section's text colour as its fill and its own colour as its label, so it still leads the quieter buttons. Where that label would not reach 4.5:1, or you set the label colour, the fill is kept and gains an edge in the section's text colour instead.
+
+A colour you pass in `fields`, `style` (`backgroundColor`, `borderColor`) or `labelStyle` (`color`), or that the app's button look sets, is never changed. A `<Card>` inside such a section becomes the surface its content reads: it re-derives `surface`, `onSurface`, `border` and the rest from its own fill, as a layout container does, and its buttons are measured against it. Inside a section `useTheme().colors.backdrop` is the fill your widget sits on and `colors.backdropBase` the surface the look was designed for; on the page itself both are absent.
+
+### 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 +193,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/button-style.js

@@ -2,6 +2,8 @@
 // the built-in widgets (frontend `_shared/buttonStyle.js` re-exports these).
 // Platform-free, so both hosts resolve a button identically.
 
+import { INK_CONTRAST, contrastRatio, inkForBackdrop, isHexColor } from "./contract.js";
+
 export const BUTTON_PADDING_MAX = 64;
 export const BUTTON_BORDER_WIDTH_MAX = 8;
 
@@ -58,3 +60,95 @@ export function selfAlignStyle(style) {
   const alignSelf = SELF_ALIGNMENTS[style && style.align];
   return alignSelf ? { alignSelf } : null;
 }
+
+// How much of its page contrast a section must cost a colour before it moves:
+// a tint or neutral panel never does, a coloured band always does.
+const SECTION_LOSS = 1.5;
+
+/**
+ * A variant's own paint, measured against the painted section it sits on
+ * (`colors.backdrop`) by the rule that section's text follows. A colour moves
+ * only where it is unreadable there AND the section is what broke it, measured
+ * against the surface the look was designed for (`colors.backdropBase`). Only
+ * what the look painted moves; `owned` names what the maker set.
+ *
+ * A transparent button re-inks its label and border separately. A fill the
+ * section swallows is replaced: a quiet `secondary` becomes the section's
+ * outlined button, and an emphatic fill turns inverse (the section's ink as
+ * fill, its own colour as label), so it still outranks the quiet ones. Where
+ * that label would not read, or the maker chose it, the fill gains an edge.
+ *
+ * @param {string} variant
+ * @param {{container: object, ink: string}} paint
+ * @param {object} colors - the surface-aware theme colours.
+ * @param {{fill?: boolean, label?: boolean, border?: boolean}} [owned]
+ * @returns {{container: object, ink: string}} `paint` itself when nothing moves.
+ */
+export function paintOnBackdrop(variant, paint, colors, owned = {}) {
+  const { backdrop, backdropBase, onSurface: ink } = colors || {};
+  if (owned.fill || ![backdrop, backdropBase, ink].every(isHexColor)) return paint;
+  const reink = (colour, minimum) =>
+    isHexColor(colour) && brokenBySection(colour, backdrop, backdropBase, minimum)
+      ? inkForBackdrop(colour, ink, backdrop, minimum)
+      : colour;
+  const { container } = paint;
+  const fill = container.backgroundColor;
+  if (fill === "transparent") return reinkOutline(paint, reink, owned);
+  if (reink(fill, INK_CONTRAST.boundary) === fill) return paint;
+  if (!owned.label && variant === "secondary") {
+    return {
+      container: { backgroundColor: "transparent", borderWidth: 1, borderColor: ink },
+      ink,
+    };
+  }
+  if (!owned.label && contrastRatio(fill, ink) >= INK_CONTRAST.text) {
+    const edge = container.borderColor ? { borderColor: ink } : null;
+    return { container: { ...container, backgroundColor: ink, ...edge }, ink: fill };
+  }
+  if (owned.border) return paint;
+  return { container: { ...container, borderWidth: 1, borderColor: ink }, ink: paint.ink };
+}
+
+function brokenBySection(colour, backdrop, base, minimum) {
+  const here = contrastRatio(colour, backdrop);
+  return here < minimum && here * SECTION_LOSS <= contrastRatio(colour, base);
+}
+
+function reinkOutline(paint, reink, owned) {
+  const { borderColor } = paint.container;
+  const label = owned.label ? paint.ink : reink(paint.ink, INK_CONTRAST.text);
+  const border = owned.border ? borderColor : reink(borderColor, INK_CONTRAST.boundary);
+  if (label === paint.ink && border === borderColor) return paint;
+  return { container: { ...paint.container, borderColor: border }, ink: label };
+}
+
+const SIDE_BORDER_COLORS = [
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+];
+
+/**
+ * Which of a button's fill, label and border its caller set, so
+ * `paintOnBackdrop` never replaces them: the surface `fields`, and colours in
+ * the flattened container `style` and `labelStyle`.
+ */
+export function ownedButtonPaint(variant, fields, style, labelStyle) {
+  const f = fields || {};
+  const s = style || {};
+  const danger = variant === "danger";
+  return {
+    fill: Boolean(
+      f.background || f.gradient || s.backgroundColor || (danger && f.dangerBackground),
+    ),
+    label: Boolean(f.textColor || (labelStyle && labelStyle.color) || (danger && f.dangerTextColor)),
+    border: Boolean(
+      f.borderColor ||
+        f.ringColor ||
+        SIDE_BORDER_COLORS.some((key) => s[key]) ||
+        (danger && f.dangerBorderColor),
+    ),
+  };
+}

package/dist/button-view.js

@@ -8,7 +8,12 @@ import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { lucideGlyph } from "./icon.js";
 import { applyThemeComponentStyle } from "./theme-components.js";
 import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
-import { buttonSurfaceOverlay, buttonSurfaceTextOverlay } from "./button-style.js";
+import {
+  buttonSurfaceOverlay,
+  buttonSurfaceTextOverlay,
+  ownedButtonPaint,
+  paintOnBackdrop,
+} from "./button-style.js";
 
 export const BUTTON_VARIANTS = Object.freeze(["primary", "secondary", "outlined", "danger"]);
 
@@ -39,8 +44,8 @@ function variantPaint(variant, colors) {
 }
 
 // Precedence, weakest first: variant, danger scope, ring, then the fields.
-function containerLayers(variant, f, colors) {
-  const paint = variantPaint(variant, colors);
+function containerLayers(variant, f, colors, owned) {
+  const paint = paintOnBackdrop(variant, variantPaint(variant, colors), colors, owned);
   let ink = paint.ink;
   const layers = [paint.container];
   if (variant === "danger") {
@@ -115,7 +120,13 @@ export function makeButton(rn) {
       ? fields || {}
       : applyThemeComponentStyle(THEMED_AS, theme, { style: fields }).style || {};
     const resolvedVariant = BUTTON_VARIANTS.includes(variant) ? variant : "primary";
-    const { layers, ink } = containerLayers(resolvedVariant, f, colors);
+    const owned = ownedButtonPaint(
+      resolvedVariant,
+      f,
+      StyleSheet.flatten(style),
+      StyleSheet.flatten(labelStyle),
+    );
+    const { layers, ink } = containerLayers(resolvedVariant, f, colors, owned);
 
     const fontSize =
       typeof f.fontSize === "number" && Number.isFinite(f.fontSize)

package/dist/card-style.js

@@ -5,7 +5,7 @@
 // Every resolver emits ONLY the fields that are set, so a widget's own base
 // style keeps whatever the author left alone.
 
-import { CONTRACT, normaliseComponentGradient } from "./contract.js";
+import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.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
@@ -74,6 +118,35 @@ export function gradientProps(value) {
     : null;
 }
 
+/**
+ * The colour a card's buttons are measured against: its opaque flat fill, or
+ * a gradient's midpoint, as a layout container's ink basis is read. `null`
+ * (a translucent or unknown fill) keeps the backdrop the card inherited.
+ *
+ * @param {object|Array} styles - the card's container style, as composed.
+ * @param {{colors: string[]}|null} gradient - its `gradientProps`.
+ */
+export function cardBackdrop(styles, gradient) {
+  if (gradient) {
+    const [from, to] = gradient.colors;
+    return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
+  }
+  let fill = null;
+  for (const style of [styles].flat(Infinity)) {
+    if (style && typeof style === "object" && style.backgroundColor !== undefined) {
+      fill = style.backgroundColor;
+    }
+  }
+  return isOpaqueHex(fill) ? fill : null;
+}
+
+// The colour maths ignores alpha, so a see-through fill cannot be judged.
+function isOpaqueHex(value) {
+  if (!isHexColor(value)) return false;
+  const hex = value.slice(1);
+  return hex.length !== 8 || hex.slice(6).toLowerCase() === "ff";
+}
+
 /** The card-surface gradient (`cardGradient`). */
 export function cardGradientProps(style) {
   return gradientProps(style && style.cardGradient);

package/dist/card-view.js

@@ -6,10 +6,16 @@
 // swap lives here once rather than in each widget.
 
 import React from "react";
-import { useHostTheme } from "./hooks.js";
+import { useHostTheme, BackdropScope } 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,
+  cardBackdrop,
+} from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 
 // A wrapped scroller stays transparent and fits inside the gradient.
@@ -75,9 +81,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,15 +130,22 @@ 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);
+    const basis = cardBackdrop(
+      [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
+      gradient,
+    );
+    const scoped = React.createElement(BackdropScope, { basis }, children);
 
     if (!gradient) {
       return React.createElement(
         Container,
-        { style: composeStyle([base, overlay], containerStyle), ...rest },
-        children,
+        { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
+        scoped,
       );
     }
 
@@ -139,10 +159,10 @@ export function makeCard(rn) {
         {
           colors: gradient.colors,
           angle: gradient.angle,
-          style: composeStyle([base, paint], containerStyle),
+          style: composeStyle([base, paint, layout], containerStyle),
           ...rest,
         },
-        children,
+        scoped,
       );
     }
 
@@ -153,7 +173,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,
@@ -164,7 +185,7 @@ export function makeCard(rn) {
           ),
           ...rest,
         },
-        children,
+        scoped,
       ),
     );
   }

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,14 +2473,14 @@ 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,
   },
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + 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,17 @@ 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.
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4989,6 +5040,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5071,6 +5141,8 @@ module.exports = {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

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,14 +2473,14 @@ 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,
   },
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + 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,17 @@ 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.
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4985,6 +5036,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5067,6 +5137,8 @@ export {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

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

@@ -46,6 +46,7 @@ import {
   // sc-5717 — "is this key still at its declared default", shared with the
   // host codec so the hook and the encoder can never disagree about it.
   sameWidgetRouteValue,
+  deriveSurfaceTokens,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -67,6 +68,27 @@ export function WidgetContextProvider({ value, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — a surface painting its own fill inside a coloured section
+ * becomes the surface its content reads and its buttons are measured against
+ * (`<Card>` uses it), by the derivation a layout container applies.
+ * Outside such a section there is no backdrop and nothing changes.
+ */
+export function BackdropScope({ basis, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const theme = ctx && ctx.workspace ? ctx.workspace.theme : null;
+  const colors = theme && theme.colors;
+  const scoped = Boolean(basis && colors && colors.backdrop && colors.backdrop !== basis);
+  const value = useMemo(
+    () =>
+      scoped
+        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis } } } }
+        : ctx,
+    [scoped, ctx, theme, colors, basis],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {
@@ -2173,7 +2195,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 +2211,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 +2229,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 +2299,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 +2311,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 +2366,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/host.d.ts

@@ -39,6 +39,21 @@ export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
+export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
+
+/**
+ * The measured re-ink rule a painted section applies to its text and buttons:
+ * `current` while it reaches `minimum` against `backdrop`, else `candidate`
+ * when that reads better there, else `current`.
+ */
+export function inkForBackdrop(
+  current: string,
+  candidate: string,
+  backdrop: string,
+  minimum: number,
+): string;
+
 /**
  * REQ-THEME-ELEMENT host helper: validates a raw `themeConfig.widgetStyles` blob.
  * Structural only — the key space is the workspace's widget catalog, not the

package/dist/host.js

@@ -41,7 +41,7 @@ export {
 // surface — the page background and every container that carries its own fill.
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
-export { deriveSurfaceTokens } from "./contract.js";
+export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The

package/dist/index.d.ts

@@ -393,6 +393,11 @@ export interface ThemeTokens {
     onSurface: string;
     danger: string;
     [k: string]: string;
+  } & {
+    /** Inside a section painting its own fill: that fill. Absent on the page. */
+    backdrop?: string;
+    /** The surface the look was designed for, which `backdrop` is judged against. */
+    backdropBase?: string;
   };
   /** sc-3696: the shared elevation vocabulary. Spread a level into a style. */
   elevation: {
@@ -843,6 +848,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 +873,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 +2810,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.180.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",