@colixsystems/widget-sdk 0.221.0 → 0.222.0

package/README.md

@@ -84,7 +84,37 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.221.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.222.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.222.0 (contract 1.178.0)
+
+**A card can carry its picture as its background — `<Card image>`.** A small image with its title in a box underneath reads as a caption under a thumbnail. The same content with the picture filling the card and the title on it reads as designed, and until now a widget could only build that by hand: an absolutely positioned `Image`, its own translucent overlay, hand-picked light text. `<Card>` now does it.
+
+```jsx
+<Card
+  as={Pressable}
+  onPress={open}
+  image={urls ? urls.card : null}
+  scrim="bottom"
+  style={{ aspectRatio: 1, justifyContent: "flex-end" }}
+>
+  {({ colors }) => <Text style={{ color: colors.onSurface }}>{record.name}</Text>}
+</Card>
+```
+
+- **`image`** takes a URL or `{ uri }`. The picture fills the card to every edge, inside the card's own corner radius; the card's padding insets the content, not the picture.
+- **`scrim`** names the edge the text sits on: `"bottom"` (default), `"top"`, `"left"`, `"right"`, `"full"` for centred text, or `"none"`. It is a light gradient that is clear over most of the picture.
+- **`imagePosition`** (`"center"` default, `"top"`, `"bottom"`, `"left"`, `"right"`) keeps that part of the picture in frame when the crop is tight.
+- **Children may be a function.** It receives `{ colors, onImage }`: the theme colours as they read where the content sits. Over a picture `colors.onSurface` and `colors.onSurfaceMuted` are light; on a card with no image they are the theme's own. A `<Button>` inside the card reads its backdrop without help.
+- **No image, no change.** `image={null}` renders the ordinary card, so a record with an empty file cell needs no branch.
+- **A photo card is a `View` or a `Pressable`.** Put a scroller inside it, never as it (`as={ScrollView}`): the picture would scroll away with the content.
+- **Give it a size.** Nothing picture-shaped sizes a photo card, so `style` carries an `aspectRatio` or a `minHeight`. The keys that arrange content (`justifyContent`, `alignItems`, `gap`, `flexDirection`) apply to the content laid over the picture, also under `as={Pressable}`.
+
+Both hosts paint it: the web Player with a CSS background, the exported app with `expo-image`, which every export already bundles. Additive: a card given no `image` renders exactly as before.
+
+### What's new in 0.221.1 (contract 1.177.1)
+
+**`useFileSignature`: one failed poll no longer outlives the next answer.** `error` is the last call that failed, and a `refresh()` or `verify()` that succeeds now clears it. While `status` is `'pending'` an `error` means a poll failed: keep polling and keep showing the order. Fix only; nothing was added or removed.
 
 ### What's new in 0.221.0 (contract 1.177.0)
 
@@ -2775,7 +2805,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
-- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a `16 / 9` card cover, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame.
+- **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead. The frame is your decision, never the picture's: size it for the role (a 40–56 square avatar, a 72–96 square row thumbnail, a square photo tile, a `16 / 9` photo card, a 160–240 tall band) and let `resizeMode="cover"` crop the photo into it — photos arrive at every size and ratio, so one left to its own proportions breaks the layout. Keep `contain` for art whose whole subject must stay visible (a logo, a diagram), inside a fixed frame. When an item has a photograph, make it the card's background with the title on it — `<Card image={url} scrim="bottom">` with a function child for the colours — rather than a small picture with its text in a box underneath; keep the stacked form for a card whose text is long or dense.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 
 **Honest ceilings:** the styling surface is React Native style objects, not full CSS. Gradients come from the `<Gradient>` primitive (not a CSS `linear-gradient` string), depth comes from `theme.elevation` (not arbitrary `box-shadow` stacks), and there are no custom CSS keyframe animations or `transition` strings (the hover/press lift comes built into `pressableLift` — never write your own), no `filter` / `backdrop-filter` / `clip-path` / `mask` / blend modes, and no opacity-faked tints (that's what `primarySoft` is for). Aim for clean, confident, professional polish within those bounds — lifted surfaces, generous corners, one accent moment.

package/dist/card-photo.js

@@ -0,0 +1,26 @@
+// The picture behind a photo-backed `<Card>` (web). A CSS background, because
+// `background-position` is what keeps the chosen part of a crop in frame.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+
+// A quote, backslash or newline would end the CSS `url("…")` early.
+function cssUrl(uri) {
+  const safe = uri.replace(/[\n\r\f]/g, "").replace(/\\/g, "%5C").replace(/"/g, "%22");
+  return `url("${safe}")`;
+}
+
+export function Photo({ uri, position, style }) {
+  return React.createElement(ReactNative.View, {
+    "aria-hidden": true,
+    style: [
+      style,
+      {
+        backgroundImage: cssUrl(uri),
+        backgroundSize: "cover",
+        backgroundPosition: position,
+        backgroundRepeat: "no-repeat",
+      },
+    ],
+  });
+}

package/dist/card-photo.native.js

@@ -0,0 +1,32 @@
+// The picture behind a photo-backed `<Card>` (native). expo-image, because
+// `contentPosition` is the only native equivalent of CSS background-position;
+// React Native's own Image can only centre a `cover` crop.
+
+import React from "react";
+import { Image } from "react-native";
+
+// Pinned in every export; only a dev client older than the pin lacks it.
+let ExpoImage = null;
+try {
+  ExpoImage = require("expo-image").Image;
+} catch (_) {
+  ExpoImage = null;
+}
+
+export function Photo({ uri, position, style }) {
+  if (!ExpoImage) {
+    return React.createElement(Image, {
+      source: { uri },
+      resizeMode: "cover",
+      style,
+      accessible: false,
+    });
+  }
+  return React.createElement(ExpoImage, {
+    source: { uri },
+    contentFit: "cover",
+    contentPosition: position,
+    style,
+    accessible: false,
+  });
+}

package/dist/card-style.js

@@ -11,6 +11,7 @@ import {
   normaliseComponentGradient,
   componentGradientColors,
   componentGradientMidpoint,
+  deriveSurfaceTokens,
 } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
@@ -160,3 +161,74 @@ function isOpaqueHex(value) {
 export function cardGradientProps(style) {
   return gradientProps(style && style.cardGradient);
 }
+
+// ---- The photo-backed card: a picture edge to edge, content laid over it ----
+
+export const CARD_SCRIMS = Object.freeze(["bottom", "top", "left", "right", "full", "none"]);
+export const DEFAULT_CARD_SCRIM = "bottom";
+
+export const CARD_IMAGE_POSITIONS = Object.freeze(["center", "top", "bottom", "left", "right"]);
+
+// What content over a photo is inked against, and what shows while it loads.
+export const CARD_PHOTO_BACKDROP = "#111827";
+
+// The dark end sits on the named edge, where the text is.
+const SCRIM_ANGLES = Object.freeze({ bottom: 180, top: 0, left: 270, right: 90 });
+// Clear over most of the picture, so the photo stays a photo.
+const SCRIM_EDGE = Object.freeze(["#00000000", "#00000026", "#000000b8"]);
+const SCRIM_FULL = Object.freeze(["#00000066", "#00000066"]);
+
+/** The picture's address from a URL or an RN `{ uri }` source, else null. */
+export function cardPhotoUri(image) {
+  const raw = image && typeof image === "object" ? image.uri : image;
+  if (typeof raw !== "string") return null;
+  const uri = raw.trim();
+  return uri ? uri : null;
+}
+
+/** The `<Gradient>` props that keep text readable on a photo; null for none. */
+export function cardScrimProps(scrim) {
+  const name = CARD_SCRIMS.includes(scrim) ? scrim : DEFAULT_CARD_SCRIM;
+  if (name === "none") return null;
+  if (name === "full") return { colors: [...SCRIM_FULL], angle: 180 };
+  return { colors: [...SCRIM_EDGE], angle: SCRIM_ANGLES[name] };
+}
+
+/** Which part of the picture a cropped card keeps in frame. */
+export function cardImagePosition(value) {
+  return CARD_IMAGE_POSITIONS.includes(value) ? value : "center";
+}
+
+/** Theme colours as content over a photo reads them, for a card with no host. */
+export function cardPhotoColors(colors) {
+  return {
+    ...colors,
+    ...deriveSurfaceTokens(CARD_PHOTO_BACKDROP),
+    backdrop: CARD_PHOTO_BACKDROP,
+  };
+}
+
+const RADIUS_FIELDS = Object.freeze([
+  "borderRadius", "borderTopLeftRadius", "borderTopRightRadius",
+  "borderBottomRightRadius", "borderBottomLeftRadius",
+]);
+
+/**
+ * The layer that holds a photo card's picture: it fills the card behind the
+ * content and rounds the picture to the card's corners. Its own layer, since
+ * iOS drops the shadow of a view that clips.
+ *
+ * @param {object|Array} styles - the card's composed container style.
+ */
+export function cardPhotoClip(styles) {
+  const flat = flattenStyle(styles);
+  const clip = {
+    position: "absolute", top: 0, right: 0, bottom: 0, left: 0,
+    overflow: "hidden",
+    pointerEvents: "none",
+  };
+  for (const key of RADIUS_FIELDS) {
+    if (flat[key] !== undefined) clip[key] = flat[key];
+  }
+  return clip;
+}

package/dist/card-view.js

@@ -4,6 +4,9 @@
 //
 // A gradient is a COMPONENT on both hosts, never a style value, so the element
 // swap lives here once rather than in each widget.
+//
+// A card given an `image` is a PHOTO card: the same element, with the picture
+// and a readability scrim on a layer behind its content.
 
 import React from "react";
 import { useHostTheme, BackdropScope } from "./hooks.js";
@@ -15,6 +18,12 @@ import {
   cardGradientProps,
   cardLayoutStyle,
   cardBackdrop,
+  cardPhotoUri,
+  cardScrimProps,
+  cardImagePosition,
+  cardPhotoClip,
+  cardPhotoColors,
+  CARD_PHOTO_BACKDROP,
 } from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 import { flattenStyle } from "./flatten-style.js";
@@ -31,6 +40,12 @@ const FILL_IN_GRADIENT = {
 
 const CLIP_TO_RADIUS = { overflow: "hidden" };
 
+// The fill shows while the picture loads, so light text never sits on white.
+const PHOTO_BOX = { backgroundColor: CARD_PHOTO_BACKDROP };
+const PHOTO_LAYER = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 };
+// The theme's hairline reads as a stray outline around a photograph.
+const NO_BORDER = { borderWidth: 0 };
+
 const CARD_FIELDS = CONTRACT.themeComponents.card.universalFields;
 
 // The convenience props, each named for the `card*` field it sets.
@@ -61,6 +76,19 @@ function themedFields(theme) {
   return out;
 }
 
+// Inside the card's scope, so a function child reads the card's own inks.
+function CardContent({ onImage, children }) {
+  const hosted = useHostTheme();
+  if (typeof children !== "function") return children;
+  // No host means no scope to re-ink through; the photo is dark regardless.
+  const colors = hosted
+    ? hosted.colors
+    : onImage
+      ? cardPhotoColors(DEFAULT_THEME_TOKENS.colors)
+      : DEFAULT_THEME_TOKENS.colors;
+  return children({ colors, onImage });
+}
+
 function themedBase(theme) {
   const { colors, radii, spacing } = theme;
   return {
@@ -75,10 +103,10 @@ function themedBase(theme) {
 /**
  * Bind the shared card to one platform's primitives.
  *
- * @param {{View: any, Gradient: any}} rn
+ * @param {{View: any, Gradient: any, Photo: any}} rn
  */
 export function makeCard(rn) {
-  const { View, Gradient } = rn;
+  const { View, Gradient, Photo } = rn;
 
   /**
    * @param {object|Array} [props.style] — `card*` fields, `shadow`, `margin`
@@ -101,6 +129,16 @@ export function makeCard(rn) {
    *   element receiving the other props, so a Pressable's feedback lands.
    * @param {boolean} [props.withoutMargin] — leave the margin off this surface
    *   for a widget that rides it on an outer root.
+   * @param {string|{uri: string}} [props.image] — a picture painted edge to
+   *   edge BEHIND the content. With none (a record without a photo) the card
+   *   is an ordinary card, so one widget serves both.
+   * @param {string} [props.imagePosition] — the part kept in frame when
+   *   cropped (`CARD_IMAGE_POSITIONS`).
+   * @param {string} [props.scrim] — the edge the readability gradient darkens
+   *   (`CARD_SCRIMS`); the edge the text sits on.
+   * @param {React.ReactNode|Function} [props.children] — a function is called
+   *   with `{ colors, onImage }`: the theme colours as they read where the
+   *   content sits, light over a photo and the theme's own without one.
    */
   function Card(props) {
     const {
@@ -110,6 +148,9 @@ export function makeCard(rn) {
       fillInGradient = false,
       containerStyle,
       withoutMargin = false,
+      image,
+      imagePosition,
+      scrim,
       children,
       ...others
     } = props;
@@ -118,6 +159,7 @@ export function makeCard(rn) {
       if (!(key in PROP_FIELDS)) rest[key] = value;
     }
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const uri = cardPhotoUri(image);
 
     const explicit = {};
     for (const [prop, field] of Object.entries(PROP_FIELDS)) {
@@ -137,17 +179,49 @@ export function makeCard(rn) {
     const layout = standalone ? cardLayoutStyle(own) : null;
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
-    const gradient = cardGradientProps(fields);
-    const basis = cardBackdrop(
-      [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
-      gradient,
+
+    const gradient = uri ? null : cardGradientProps(fields);
+    const basis = uri
+      ? CARD_PHOTO_BACKDROP
+      : cardBackdrop(
+          [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
+          gradient,
+        );
+    const scoped = React.createElement(
+      BackdropScope,
+      { basis, always: Boolean(uri) },
+      React.createElement(CardContent, { onImage: Boolean(uri) }, children),
     );
-    const scoped = React.createElement(BackdropScope, { basis }, children);
 
     if (!gradient) {
+      const box = [
+        base,
+        overlay,
+        layout,
+        uri ? PHOTO_BOX : null,
+        uri && !fields.cardBorderColor ? NO_BORDER : null,
+      ];
+      const scrimProps = uri ? cardScrimProps(scrim) : null;
+      const ownStyle = typeof containerStyle === "function" ? null : containerStyle;
+      // The layer keeps its slot with no photo, so content survives one arriving.
+      const layer = uri
+        ? React.createElement(
+            View,
+            { style: cardPhotoClip([box, ownStyle]) },
+            React.createElement(Photo, {
+              uri,
+              position: cardImagePosition(imagePosition),
+              style: PHOTO_LAYER,
+            }),
+            scrimProps
+              ? React.createElement(Gradient, { ...scrimProps, style: PHOTO_LAYER })
+              : null,
+          )
+        : null;
       return React.createElement(
         Container,
-        { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
+        { style: composeStyle(box, containerStyle), ...rest },
+        layer,
         scoped,
       );
     }

package/dist/card.js

@@ -3,6 +3,7 @@
 
 import * as ReactNative from "react-native-web";
 import { Gradient } from "./gradient.js";
+import { Photo } from "./card-photo.js";
 import { makeCard } from "./card-view.js";
 
-export const Card = makeCard({ View: ReactNative.View, Gradient });
+export const Card = makeCard({ View: ReactNative.View, Gradient, Photo });

package/dist/card.native.js

@@ -3,6 +3,7 @@
 
 import { View } from "react-native";
 import { Gradient } from "./gradient.native.js";
+import { Photo } from "./card-photo.native.js";
 import { makeCard } from "./card-view.js";
 
-export const Card = makeCard({ View, Gradient });
+export const Card = makeCard({ View, Gradient, Photo });

package/dist/contract.cjs

@@ -1559,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -3242,7 +3245,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 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `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,
   },
@@ -5868,7 +5871,14 @@ const CONTRACT = deepFreeze({
   //    and attach to it in one handler. A FILE column's file goes in its
   //    row's record space; useCamera / useImageEditor point at
   //    useFilestoreUpload, since widget code cannot reach ctx.assets.
-  version: "1.177.0",
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  version: "1.178.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1559,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -3242,7 +3245,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 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `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,
   },
@@ -5864,7 +5867,14 @@ const CONTRACT = deepFreeze({
   //    and attach to it in one handler. A FILE column's file goes in its
   //    row's record space; useCamera / useImageEditor point at
   //    useFilestoreUpload, since widget code cannot reach ctx.assets.
-  version: "1.177.0",
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  version: "1.178.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -72,17 +72,20 @@ export function WidgetContextProvider({ 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.
+ * Outside such a section there is no backdrop and nothing changes, unless
+ * `always`: a surface whose fill is fixed (a photograph) re-inks everywhere.
  */
-export function BackdropScope({ basis, children }) {
+export function BackdropScope({ basis, always = false, 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 scoped = Boolean(
+    basis && colors && (always || (colors.backdrop && colors.backdrop !== basis)),
+  );
   const value = useMemo(
     () =>
       scoped
-        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis } } } }
+        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis, backdropBase: colors.backdropBase || colors.surface } } } }
         : ctx,
     [scoped, ctx, theme, colors, basis],
   );

package/dist/index.d.ts

@@ -3697,6 +3697,9 @@ export function initialsFor(name: unknown): string;
  * @example
  *   <Card><Text>…</Text></Card>
  *   <Card as={Pressable} onPress={open} radius={12} shadow="md">…</Card>
+ *   <Card image={url} scrim="bottom" style={{ aspectRatio: 1, justifyContent: "flex-end" }}>
+ *     {({ colors }) => <Text style={{ color: colors.onSurface }}>…</Text>}
+ *   </Card>
  */
 export const Card: (props: {
   background?: string;
@@ -3705,6 +3708,15 @@ 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 };
+  /**
+   * A picture painted edge to edge behind the content. With none the card is
+   * an ordinary card, so a record without a photo needs no branch.
+   */
+  image?: string | { uri: string } | null;
+  /** The part of the picture kept in frame when cropped. Default "center". */
+  imagePosition?: CardImagePosition;
+  /** The edge the readability gradient darkens. Default "bottom". */
+  scrim?: CardScrim;
   /**
    * `card*` style fields, `shadow`, `margin` — a widget's per-instance style.
    * With no `baseStyle` it also carries the box's layout (width, height, the
@@ -3721,10 +3733,17 @@ export const Card: (props: {
   fillInGradient?: boolean;
   containerStyle?: any;
   withoutMargin?: boolean;
-  children?: ReactNode;
+  /**
+   * A function is called with the theme colours as they read where the
+   * content sits: light over a picture, the theme's own without one.
+   */
+  children?: ReactNode | ((ink: { colors: Record<string, string>; onImage: boolean }) => ReactNode);
   [prop: string]: any;
 }) => any;
 
+export type CardScrim = "bottom" | "top" | "left" | "right" | "full" | "none";
+export type CardImagePosition = "center" | "top" | "bottom" | "left" | "right";
+
 export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger";
 export const BUTTON_VARIANTS: readonly ButtonVariant[];
 

package/dist/signing-hooks.js

@@ -40,7 +40,9 @@ const userIdOf = (ctx) => (ctx.user && ctx.user.id) || "";
  * with `hintCode: "sealing"`. `hintCode` is where the order stands;
  * `nameRefusal` (`{ reason, characters }`) is set when it failed because the
  * signer's name cannot be shown. `autoStartToken` is set only while opening
- * BankID can still help. Reads
+ * BankID can still help. `error` is the last call that failed; a `refresh()`
+ * or `verify()` that succeeds clears it, so one failed poll does not outlive
+ * the next answer. Reads
  * `ctx.filestore.signatures.{initiate,status,cancel,verify}`. When `fileId` is
  * null/empty the hook collapses to a no-op.
  *
@@ -128,7 +130,8 @@ export function useFileSignature(fileId, existingSignatureId = null) {
       const res = await sigRef.current.status(id);
       // A cancel or a new order since this poll was sent: its answer is old news.
       if (answersRef.current !== asked) return;
-      apply(forScope, (base) => ({ order: signOrderStateAfterAnswer(base.order, res) }));
+      // An answer means the order can be reached again: an earlier failure is over.
+      apply(forScope, (base) => ({ order: signOrderStateAfterAnswer(base.order, res), error: null }));
     } catch (err) {
       if (answersRef.current !== asked) return;
       apply(forScope, () => ({ error: toPermissionError(err) }));
@@ -156,7 +159,7 @@ export function useFileSignature(fileId, existingSignatureId = null) {
     if (!id) return null;
     try {
       const v = await sigRef.current.verify(id);
-      apply(forScope, () => ({ verdict: v }));
+      apply(forScope, () => ({ verdict: v, error: null }));
       return v;
     } catch (err) {
       const refusal = toPermissionError(err);

package/package.json

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

package/src/contract.js

@@ -1559,7 +1559,10 @@ const HOOKS = [
       "be cancelled. cancel() resolves to what became of the order, which is " +
       "then still pending or already complete: read status after it, never " +
       "assume 'cancelled'. nameRefusal is set when the order failed because " +
-      "the signer's name cannot be shown on the document. Reads " +
+      "the signer's name cannot be shown on the document. error is the last " +
+      "call that failed, and a refresh() or verify() that succeeds clears it: " +
+      "while status is 'pending' an error means one poll failed, so keep " +
+      "polling and keep showing the order. Reads " +
       "ctx.filestore.signatures.{initiate,status,cancel,verify}.",
     returnShape: {
       status: "'pending' | 'complete' | 'failed' | 'cancelled' | null",
@@ -3242,7 +3245,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 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. 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`. `style` may be an object or a React Native style array (`style={[{ flex: 1, minWidth: 0 }, align && { alignItems: align }]}`), read as the host flattens it: nested arrays and falsy entries are fine and a later entry wins. A gradient paints on both hosts. `image` (a URL or `{ uri }`) makes it a PHOTO card: the picture fills the card edge to edge BEHIND the content, under a light gradient on the edge named by `scrim` ("bottom" default | "top" | "left" | "right" | "full" | "none") — the edge the text sits on — and cropped around `imagePosition` ("center" default | "top" | "bottom" | "left" | "right"). A photo card has no picture-shaped content to size it, so give it an `aspectRatio` or `minHeight` in `style`, and pass the children as a function — `{({ colors, onImage }) => …}` — to receive the theme colours as they read where the content sits (`colors.onSurface` for a title, `colors.onSurfaceMuted` for a supporting line): light over a picture, the theme\'s own on a card without one. `image={null}` renders an ordinary card, so a record with no photo needs no branch. A photo card is a `View` or, with `as`, a `Pressable`; put a scroller inside it, never as it. Use it whenever an item has a photograph, instead of a small `Image` with its text in a box underneath. `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,
   },
@@ -5864,7 +5867,14 @@ const CONTRACT = deepFreeze({
   //    and attach to it in one handler. A FILE column's file goes in its
   //    row's record space; useCamera / useImageEditor point at
   //    useFilestoreUpload, since widget code cannot reach ctx.assets.
-  version: "1.177.0",
+  // 1.177.1: fix (sc-10410) — a `refresh()` or `verify()` that succeeds
+  //    clears `useFileSignature`'s `error`; it used to keep one failed poll's
+  //    error for the rest of the order.
+  // 1.178.0: additive (sc-11272) — `<Card image>` paints a picture edge to
+  //    edge behind the card's content, with a `scrim` on the text's edge and
+  //    an `imagePosition` for the crop. Children may be a function taking
+  //    `{ colors, onImage }`: the theme colours as they read over the picture.
+  version: "1.178.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,