@colixsystems/widget-sdk 0.201.0 → 0.204.0

package/README.md

@@ -83,7 +83,51 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.201.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.204.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.204.0 (contract 1.163.0)
+
+**One loading look: `Spinner`, `Skeleton`, and the `loading` theme scope.** Widgets each drew their own loading state — a platform spinner in its default colour, hand-built placeholder bars, or a line of text. Draw these instead:
+
+```jsx
+// You know the shape of what is coming: draw its outline.
+if (loading) return <Skeleton shape="listRow" count={4} />;
+
+// You do not: a pending action.
+{saving ? <Spinner size="sm" color={theme.colors.onPrimary} /> : <Text>Save</Text>}
+```
+
+`<Spinner size label color>` takes `size` `"sm"` | `"md"` (default) | `"lg"` or a number, and an optional `label` drawn under the ring. `<Skeleton shape>` takes `"text"` (`width`, `lines`), `"block"` (`width`, `height`), `"circle"` (`size`) or the `"listRow"` preset (`count`, `leading`), whose rows share the frame of the theme's list rows. To mirror any other layout, wrap bones in one outer `<Skeleton>` and lay them out yourself:
+
+```jsx
+<Skeleton style={{ flexDirection: "row", gap: 12 }}>
+  <Skeleton shape="circle" />
+  <Skeleton shape="text" lines={2} style={{ flex: 1 }} />
+</Skeleton>
+```
+
+A spinner wears `theme.colors.loader`, the app's one spinner colour: set under **Design → Loading Indicator**, and re-derived for whatever surface the widget sits on, so it stays visible in a dark section. Pass `color` only inside a control you fill yourself. A skeleton's colour and corners come from **Design → Components → Loading** (`themeConfig.components.loading`: `skeletonColor`, `skeletonRadius`), defaulting to the theme's muted surface; `color` and `radius` override one skeleton.
+
+Both stop moving when the device asks for reduced motion; the outermost skeleton pulses as a whole, so a long list costs one animation. A spinner is a labelled `progressbar` in the busy state; a string `label` is its name, and a label that is a node stays exposed as content. The outermost skeleton is the one loading region: on the web a `status` region with a label and `aria-busy`, on native one labelled accessible element in the busy state (`accessibilityLabel` overrides the app's own "Loading…"). The bones inside it are hidden from assistive technology.
+
+The `loading` scope styles an SDK component rather than a widget's style fields, so its `targets` is empty and it names `Skeleton` in the new optional scope key **`sdkComponents`**.
+
+### What's new in 0.202.0 (contract 1.161.0)
+
+**Themed collapsible sections: `Accordion` and `AccordionItem`.** Widgets each built their own expand/collapse section, with their own header, chevron and spacing, and none told a screen reader whether the section was open. The SDK now draws one, from the app's existing look: the surface from **Theme Settings > Cards** (background, border, corner radius) and the headers and dividers from **Theme Settings > Lists** (row padding, row height, divider). No new theme scope.
+
+```jsx
+<Accordion defaultValue="shipping">
+  <AccordionItem value="shipping" title="Shipping" subtitle="2-4 days">
+    <Text>…</Text>
+  </AccordionItem>
+  <AccordionItem value="returns" title="Returns" trailing={<Badge label="New" tone="info" />}>
+    <Text>…</Text>
+  </AccordionItem>
+</Accordion>
+```
+
+By default one section is open at a time and pressing the open one closes it; `multiple` lets several stay open. Pass `value` + `onChange` to control it (a key, or an array of keys when `multiple`), or `defaultValue` to leave it uncontrolled. Each header is a 44px button with a chevron that works from the keyboard and reports `aria-expanded`. `trailing` sits outside the header's toggle, so a button there runs its own action. A section's body mounts only while it is open, so fetch its data inside it. One view renders on both the web Player and the exported app. Additive.
 
 ### What's new in 0.201.0 (contract 1.160.0)
 
@@ -2393,6 +2437,8 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
 - `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
 - `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
+- `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/accordion-tokens.js

@@ -0,0 +1,54 @@
+// The values `<Accordion>` paints with, and its open-state rules. The surface
+// comes from the theme's `card` scope and the rows from its `list` scope, so a
+// look restyles every collapsible section without a scope of its own.
+// Platform-free, so both hosts draw from the same numbers and tests can pin
+// them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { mixHex, isHexColor } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+import { resolveListTokens, LIST_ROW_MIN_HEIGHT } from "./list-tokens.js";
+
+/**
+ * Resolve one accordion: the `card` scope's surface, the `list` scope's row
+ * padding, height and divider, then the theme tokens.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function resolveAccordionTokens(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const card = normaliseThemeComponents(base.components).card || {};
+  const list = resolveListTokens(base);
+
+  const background = card.background ?? colors.surface;
+  return {
+    background,
+    borderColor: card.borderColor ?? colors.border,
+    radius: card.radius ?? radii.md,
+    headerPadding: list.rowPadding,
+    // A dense look may shrink a row, never the header's tap target.
+    headerMinHeight: Math.max(list.rowMinHeight, LIST_ROW_MIN_HEIGHT),
+    dividerColor: list.dividerColor,
+    dividerWidth: list.dividerWidth,
+    // The mix needs hex; a translucent surface tints the theme's own instead.
+    pressedBackground: mixHex(colors.onSurface, isHexColor(background) ? background : colors.surface, 0.94),
+    chevronColor: colors.onSurfaceMuted,
+  };
+}
+
+/** The open sections as an array, from a single key or a list of keys. */
+export function openKeysOf(value) {
+  if (Array.isArray(value)) return value.filter((key) => key !== null && key !== undefined);
+  return value === null || value === undefined ? [] : [value];
+}
+
+/**
+ * The open sections after one header is pressed. Single mode keeps at most one
+ * open, and pressing the open one closes it.
+ */
+export function toggleOpenKey(open, key, multiple) {
+  if (open.includes(key)) return open.filter((k) => k !== key);
+  return multiple ? [...open, key] : [key];
+}

package/dist/accordion-view.js

@@ -0,0 +1,210 @@
+// The ONE implementation behind the `<Accordion>` and `<AccordionItem>` SDK
+// primitives. The platform bindings (`accordion.js` / `accordion.native.js`)
+// differ only in where the primitives come from, so the hosts cannot drift.
+//
+// Widgets each built their own collapsible section, with their own header,
+// chevron and spacing, and none announced whether it was open. This one reads
+// the theme's `card` and `list` scopes, so every section in an app matches.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { textRoleStyle } from "./text-roles.js";
+import { resolveAccordionTokens, openKeysOf, toggleOpenKey } from "./accordion-tokens.js";
+
+/**
+ * Bind the shared accordion to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeAccordion(rn) {
+  const { View, Text, Pressable } = rn;
+  const AccordionContext = React.createContext(null);
+
+  /**
+   * @param {boolean} [props.multiple] — several sections may be open at once.
+   * @param {string|string[]|null} [props.value] — the open section(s); makes
+   *   the accordion controlled. A key in single mode, an array in multiple.
+   * @param {string|string[]|null} [props.defaultValue] — the initially open
+   *   section(s) when uncontrolled.
+   * @param {(next: string|string[]|null) => void} [props.onChange] — the open
+   *   section(s) after a header press, in the same shape as `value`.
+   */
+  function Accordion({
+    multiple = false,
+    value,
+    defaultValue,
+    onChange,
+    children,
+    accessibilityLabel,
+    style,
+    testID,
+  }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const tokens = resolveAccordionTokens(theme);
+    const controlled = value !== undefined;
+    const [ownOpen, setOwnOpen] = React.useState(() => openKeysOf(defaultValue));
+    const open = controlled ? openKeysOf(value) : ownOpen;
+
+    const toggle = (key) => {
+      if (key === null || key === undefined) return;
+      const next = toggleOpenKey(open, key, multiple);
+      if (!controlled) setOwnOpen(next);
+      if (typeof onChange === "function") onChange(multiple ? next : (next[0] ?? null));
+    };
+
+    return React.createElement(
+      AccordionContext.Provider,
+      { value: { open, toggle, tokens, theme } },
+      React.createElement(
+        View,
+        {
+          style: [
+            {
+              backgroundColor: tokens.background,
+              borderColor: tokens.borderColor,
+              borderWidth: 1,
+              borderRadius: tokens.radius,
+              overflow: "hidden",
+            },
+            style,
+          ],
+          // A label names the group only when it has a role to hang on.
+          role: accessibilityLabel ? "group" : undefined,
+          accessibilityLabel,
+          testID,
+        },
+        // The last section's divider slides under the clipped edge, so it
+        // ends on the surface wherever it sits in the tree.
+        React.createElement(
+          View,
+          { style: { marginBottom: -tokens.dividerWidth } },
+          children,
+        ),
+      ),
+    );
+  }
+  Accordion.displayName = "Accordion";
+
+  function AccordionItem(props) {
+    const context = React.useContext(AccordionContext);
+    // Stable per section, so a wrapped or conditional one keeps its own key.
+    const ownKey = React.useId();
+    // A lone section is an accordion of one, so it still opens and closes.
+    if (!context) return React.createElement(Accordion, null, React.createElement(AccordionItem, props));
+
+    const {
+      value = ownKey,
+      title,
+      subtitle,
+      trailing,
+      disabled = false,
+      divider = true,
+      children,
+      accessibilityLabel,
+      style,
+      testID,
+    } = props;
+    const { open: openKeys, toggle, tokens, theme } = context;
+    const open = openKeys.includes(value);
+    const { colors, typography } = theme;
+
+    const header = React.createElement(
+      View,
+      {
+        style: {
+          flexDirection: "row",
+          alignItems: "center",
+          paddingRight: trailing ? tokens.headerPadding : 0,
+        },
+      },
+      React.createElement(
+        Pressable,
+        {
+          onPress: () => toggle(value),
+          disabled,
+          // accessibilityRole + aria-*: the pair that announces on both hosts.
+          accessibilityRole: "button",
+          accessibilityLabel: accessibilityLabel ?? headerLabel(title, subtitle),
+          "aria-expanded": open,
+          "aria-disabled": disabled,
+          testID: testID ? `${testID}-header` : undefined,
+          style: ({ pressed }) => [
+            {
+              flex: 1,
+              minWidth: 0,
+              flexDirection: "row",
+              alignItems: "center",
+              gap: theme.spacing.sm,
+              minHeight: tokens.headerMinHeight,
+              padding: tokens.headerPadding,
+            },
+            pressed ? { backgroundColor: tokens.pressedBackground } : null,
+            disabled ? { opacity: 0.5 } : null,
+          ],
+        },
+        React.createElement(Icon, {
+          name: open ? "chevron-down" : "chevron-right",
+          size: 18,
+          color: tokens.chevronColor,
+        }),
+        React.createElement(
+          View,
+          { style: { flex: 1, minWidth: 0, gap: 2 } },
+          title !== undefined && title !== null
+            ? React.createElement(
+                Text,
+                { style: textRoleStyle("subtitle", typography, colors), numberOfLines: 1 },
+                title,
+              )
+            : null,
+          subtitle !== undefined && subtitle !== null
+            ? React.createElement(
+                Text,
+                { style: textRoleStyle("caption", typography, colors), numberOfLines: 2 },
+                subtitle,
+              )
+            : null,
+        ),
+      ),
+      // Outside the toggle, so a button here never opens the section.
+      trailing || null,
+    );
+
+    return React.createElement(
+      View,
+      {
+        style: [
+          divider && tokens.dividerWidth > 0
+            ? { borderBottomWidth: tokens.dividerWidth, borderColor: tokens.dividerColor }
+            : null,
+          style,
+        ],
+        testID,
+      },
+      header,
+      // Mounted only while open, so a closed section costs nothing.
+      open
+        ? React.createElement(
+            View,
+            {
+              style: { padding: tokens.headerPadding, paddingTop: 0 },
+              testID: testID ? `${testID}-panel` : undefined,
+            },
+            // A section nested in this body is not one of this accordion's.
+            React.createElement(AccordionContext.Provider, { value: null }, children),
+          )
+        : null,
+    );
+  }
+  AccordionItem.displayName = "AccordionItem";
+
+  // The label replaces the visible text, so it must carry the subtitle too.
+  function headerLabel(title, subtitle) {
+    const parts = [title, subtitle].filter((part) => typeof part === "string" && part !== "");
+    return parts.length ? parts.join(", ") : undefined;
+  }
+
+  return { Accordion, AccordionItem };
+}

package/dist/accordion.js

@@ -0,0 +1,7 @@
+// `<Accordion>` / `<AccordionItem>` (web). Binds ./accordion-view.js to
+// react-native-web; see ./primitives.js for why not the bare specifier.
+
+import { View, Text, Pressable } from "react-native-web";
+import { makeAccordion } from "./accordion-view.js";
+
+export const { Accordion, AccordionItem } = makeAccordion({ View, Text, Pressable });

package/dist/accordion.native.js

@@ -0,0 +1,7 @@
+// `<Accordion>` / `<AccordionItem>` (native). Binds ./accordion-view.js to
+// React Native's own primitives; only the import differs from ./accordion.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeAccordion } from "./accordion-view.js";
+
+export const { Accordion, AccordionItem } = makeAccordion({ View, Text, Pressable });

package/dist/contract.cjs

@@ -692,6 +692,18 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.user-management": TABS_FIELDS,
     }),
   }),
+  // Loading placeholders: `<Skeleton>` reads this scope directly, so it names
+  // the SDK component it styles and binds no widget field. `<Spinner>` is not
+  // here: it wears `colors.loader`, the app's one spinner colour.
+  loading: Object.freeze({
+    label: "Loading",
+    sdkComponents: Object.freeze(["Skeleton"]),
+    tokens: Object.freeze({
+      skeletonColor: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      skeletonRadius: Object.freeze({ type: "size", min: 0, max: 24, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -717,7 +729,8 @@ const HOOKS = [
         "page: a container painting its own background re-derives them for its " +
         "subtree. Read them and your text is readable wherever the widget lands; " +
         "there is nothing to opt into. `loader` is that surface's spinner colour " +
-        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
+        "(sc-6095) — `<Spinner>` wears it by default; paint your own loading " +
+        "state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -1450,7 +1463,7 @@ const HOOKS = [
       message: "string | null",
       signerName: "string | null",
       signedAt: "string | null",
-      verdict: "{ valid, checks, content_status, ... } | null",
+      verdict: "{ valid, checks, content_status, signed_by_others_since, seal, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
@@ -2608,7 +2621,7 @@ const PRIMITIVES = [
   {
     name: "ActivityIndicator",
     description:
-      "Loading spinner. See https://reactnative.dev/docs/activityindicator.",
+      "The raw platform spinner. Do NOT use it for a loading state — draw `<Spinner>` (below), which wears the app's spinner colour and follows the reduced-motion setting. See https://reactnative.dev/docs/activityindicator.",
     rnComponent: "ActivityIndicator",
     docsUrl: "https://reactnative.dev/docs/activityindicator",
   },
@@ -2804,6 +2817,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Accordion",
+    description:
+      'Themed collapsible sections. `<Accordion defaultValue="shipping"><AccordionItem value="shipping" title="Shipping" subtitle="2-4 days">…</AccordionItem><AccordionItem value="returns" title="Returns">…</AccordionItem></Accordion>`. THE way to build a section that expands and collapses (an FAQ, a settings group, a record\'s details, a group whose members show on demand): the surface takes the app\'s card look (Theme Settings > Cards: background, border, corner radius) and the headers and dividers its list look (Theme Settings > Lists: row padding, row height, divider), so every collapsible section in the app matches. Each header has a chevron, a 44px touch target, works from the keyboard and tells assistive technology whether its section is open, so never hand-roll a collapsible from `Pressable` + a chevron + a `useState`. By default one section is open at a time and pressing the open one closes it; `multiple` lets several stay open. Props: `multiple`, `value` (the open key, or an array of keys when `multiple`; makes it controlled), `defaultValue` (the same shape, uncontrolled), `onChange(next)` (the open key(s) after a press, in the same shape), `accessibilityLabel`, `style`, `testID`. Its children are `<AccordionItem>`s.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "AccordionItem",
+    description:
+      'One section of an `<Accordion>`. `<AccordionItem value={group.id} title={group.name} subtitle={`${group.count} members`} trailing={<Button title="Delete" variant="danger" onPress={remove} />}>…</AccordionItem>`. Props: `value` (the key `value` / `defaultValue` / `onChange` name it by — give one whenever you name sections; an item may sit inside your own component or a fragment), `title`, `subtitle` (the subtitle / caption text tiers), `trailing` (a node beside the header and OUTSIDE its toggle, so a button there runs its own action without opening the section), `disabled`, `divider` (default true; the surface edge hides the rule under the last section), `children` (the body: it mounts only while the section is open, so fetch its data inside it; an `<AccordionItem>` placed in a body is its own section, never part of the outer accordion), `accessibilityLabel` (defaults to the string `title` and `subtitle`), `style`, `testID` (also tags the header `<testID>-header` and the open body `<testID>-panel`). On its own, outside an `<Accordion>`, it is an accordion of one.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Tabs",
     description:
@@ -2832,6 +2859,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Spinner",
+    description:
+      'Themed loading spinner. `<Spinner />`, `<Spinner size="lg" label="Loading orders" />` — THE way to show that something is in progress when you cannot know its shape: a button\'s pending action, a save, a refresh, "load more", a full-widget first load with no layout yet. `size` is "sm" | "md" (default) | "lg" or a number; `label` draws a caption under the ring and is its accessibility label (unset, the app\'s own "Loading…"). Its colour is the app\'s one spinner colour (`theme.colors.loader`, set under Design → Loading Indicator and re-derived for whatever surface the widget sits on), so pass `color` ONLY inside a control you fill yourself, e.g. `color={theme.colors.onPrimary}` inside a primary button. It stops turning when the device asks for reduced motion and is a labelled element in the busy state. Never use `ActivityIndicator` or a hand-drawn spinner.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Skeleton",
+    description:
+      'Themed loading placeholder. `<Skeleton shape="text" width="60%" />`, `<Skeleton shape="text" lines={3} />`, `<Skeleton shape="block" height={160} />`, `<Skeleton shape="circle" size={40} />`, and the list preset `<Skeleton shape="listRow" count={4} />` (pass `leading={false}` for rows with no avatar or icon). THE loading state for content whose layout you already know — a list, a card, a profile, an article: draw the shape of what is coming so nothing jumps when it arrives. To mirror a custom layout, wrap bones in one group and lay them out yourself: `<Skeleton style={{ flexDirection: "row", gap: 12 }}><Skeleton shape="circle" /><Skeleton shape="text" lines={2} style={{ flex: 1 }} /></Skeleton>` — the outermost Skeleton is the ONE loading region (a `status` region with `aria-busy` on the web, one labelled accessible element in the busy state on native) and every bone inside is hidden from assistive technology. Its colour and corner radius come from the theme (Design → Components → Loading); `color` and `radius` override one skeleton. The outermost Skeleton pulses as a whole, and stops under reduced motion. Never hand-build placeholder bars from `View`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -5322,7 +5363,14 @@ const CONTRACT = deepFreeze({
   //    `usePageBadge(null)` now means "not known yet" and keeps the current
   //    badge; `undefined` still clears it. Linter rules `badge-counter-export-missing`
   //    (error) and `badge-counter-undeclared` (warning).
-  version: "1.160.0",
+  // 1.161.0: additive (sc-10930) — `Accordion` / `AccordionItem`, themed
+  //    collapsible sections drawn from the `card` and `list` scopes: single
+  //    or multiple open, controlled or uncontrolled, `aria-expanded` headers.
+  // 1.163.0: additive (sc-10928) — the `Spinner` and `Skeleton` primitives.
+  //    `Spinner` wears `colors.loader`; `Skeleton` reads the new `loading`
+  //    component scope (colour, radius). A scope may now name `sdkComponents`
+  //    and bind no widget field. Both stop under reduced motion.
+  version: "1.163.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -692,6 +692,18 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.user-management": TABS_FIELDS,
     }),
   }),
+  // Loading placeholders: `<Skeleton>` reads this scope directly, so it names
+  // the SDK component it styles and binds no widget field. `<Spinner>` is not
+  // here: it wears `colors.loader`, the app's one spinner colour.
+  loading: Object.freeze({
+    label: "Loading",
+    sdkComponents: Object.freeze(["Skeleton"]),
+    tokens: Object.freeze({
+      skeletonColor: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      skeletonRadius: Object.freeze({ type: "size", min: 0, max: 24, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -717,7 +729,8 @@ const HOOKS = [
         "page: a container painting its own background re-derives them for its " +
         "subtree. Read them and your text is readable wherever the widget lands; " +
         "there is nothing to opt into. `loader` is that surface's spinner colour " +
-        "(sc-6095) — paint your own loading state with it rather than a literal grey.",
+        "(sc-6095) — `<Spinner>` wears it by default; paint your own loading " +
+        "state with it rather than a literal grey.",
       spacing: "{ xs, sm, md, lg, xl }",
       spacingScale:
         "number — the app-wide spacing multiplier (REQ-THEME-LOOK, default 1). " +
@@ -1450,7 +1463,7 @@ const HOOKS = [
       message: "string | null",
       signerName: "string | null",
       signedAt: "string | null",
-      verdict: "{ valid, checks, content_status, ... } | null",
+      verdict: "{ valid, checks, content_status, signed_by_others_since, seal, ... } | null",
       loading: "boolean",
       error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
@@ -2608,7 +2621,7 @@ const PRIMITIVES = [
   {
     name: "ActivityIndicator",
     description:
-      "Loading spinner. See https://reactnative.dev/docs/activityindicator.",
+      "The raw platform spinner. Do NOT use it for a loading state — draw `<Spinner>` (below), which wears the app's spinner colour and follows the reduced-motion setting. See https://reactnative.dev/docs/activityindicator.",
     rnComponent: "ActivityIndicator",
     docsUrl: "https://reactnative.dev/docs/activityindicator",
   },
@@ -2804,6 +2817,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Accordion",
+    description:
+      'Themed collapsible sections. `<Accordion defaultValue="shipping"><AccordionItem value="shipping" title="Shipping" subtitle="2-4 days">…</AccordionItem><AccordionItem value="returns" title="Returns">…</AccordionItem></Accordion>`. THE way to build a section that expands and collapses (an FAQ, a settings group, a record\'s details, a group whose members show on demand): the surface takes the app\'s card look (Theme Settings > Cards: background, border, corner radius) and the headers and dividers its list look (Theme Settings > Lists: row padding, row height, divider), so every collapsible section in the app matches. Each header has a chevron, a 44px touch target, works from the keyboard and tells assistive technology whether its section is open, so never hand-roll a collapsible from `Pressable` + a chevron + a `useState`. By default one section is open at a time and pressing the open one closes it; `multiple` lets several stay open. Props: `multiple`, `value` (the open key, or an array of keys when `multiple`; makes it controlled), `defaultValue` (the same shape, uncontrolled), `onChange(next)` (the open key(s) after a press, in the same shape), `accessibilityLabel`, `style`, `testID`. Its children are `<AccordionItem>`s.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "AccordionItem",
+    description:
+      'One section of an `<Accordion>`. `<AccordionItem value={group.id} title={group.name} subtitle={`${group.count} members`} trailing={<Button title="Delete" variant="danger" onPress={remove} />}>…</AccordionItem>`. Props: `value` (the key `value` / `defaultValue` / `onChange` name it by — give one whenever you name sections; an item may sit inside your own component or a fragment), `title`, `subtitle` (the subtitle / caption text tiers), `trailing` (a node beside the header and OUTSIDE its toggle, so a button there runs its own action without opening the section), `disabled`, `divider` (default true; the surface edge hides the rule under the last section), `children` (the body: it mounts only while the section is open, so fetch its data inside it; an `<AccordionItem>` placed in a body is its own section, never part of the outer accordion), `accessibilityLabel` (defaults to the string `title` and `subtitle`), `style`, `testID` (also tags the header `<testID>-header` and the open body `<testID>-panel`). On its own, outside an `<Accordion>`, it is an accordion of one.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Tabs",
     description:
@@ -2832,6 +2859,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Spinner",
+    description:
+      'Themed loading spinner. `<Spinner />`, `<Spinner size="lg" label="Loading orders" />` — THE way to show that something is in progress when you cannot know its shape: a button\'s pending action, a save, a refresh, "load more", a full-widget first load with no layout yet. `size` is "sm" | "md" (default) | "lg" or a number; `label` draws a caption under the ring and is its accessibility label (unset, the app\'s own "Loading…"). Its colour is the app\'s one spinner colour (`theme.colors.loader`, set under Design → Loading Indicator and re-derived for whatever surface the widget sits on), so pass `color` ONLY inside a control you fill yourself, e.g. `color={theme.colors.onPrimary}` inside a primary button. It stops turning when the device asks for reduced motion and is a labelled element in the busy state. Never use `ActivityIndicator` or a hand-drawn spinner.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Skeleton",
+    description:
+      'Themed loading placeholder. `<Skeleton shape="text" width="60%" />`, `<Skeleton shape="text" lines={3} />`, `<Skeleton shape="block" height={160} />`, `<Skeleton shape="circle" size={40} />`, and the list preset `<Skeleton shape="listRow" count={4} />` (pass `leading={false}` for rows with no avatar or icon). THE loading state for content whose layout you already know — a list, a card, a profile, an article: draw the shape of what is coming so nothing jumps when it arrives. To mirror a custom layout, wrap bones in one group and lay them out yourself: `<Skeleton style={{ flexDirection: "row", gap: 12 }}><Skeleton shape="circle" /><Skeleton shape="text" lines={2} style={{ flex: 1 }} /></Skeleton>` — the outermost Skeleton is the ONE loading region (a `status` region with `aria-busy` on the web, one labelled accessible element in the busy state on native) and every bone inside is hidden from assistive technology. Its colour and corner radius come from the theme (Design → Components → Loading); `color` and `radius` override one skeleton. The outermost Skeleton pulses as a whole, and stops under reduced motion. Never hand-build placeholder bars from `View`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -5318,7 +5359,14 @@ const CONTRACT = deepFreeze({
   //    `usePageBadge(null)` now means "not known yet" and keeps the current
   //    badge; `undefined` still clears it. Linter rules `badge-counter-export-missing`
   //    (error) and `badge-counter-undeclared` (warning).
-  version: "1.160.0",
+  // 1.161.0: additive (sc-10930) — `Accordion` / `AccordionItem`, themed
+  //    collapsible sections drawn from the `card` and `list` scopes: single
+  //    or multiple open, controlled or uncontrolled, `aria-expanded` headers.
+  // 1.163.0: additive (sc-10928) — the `Spinner` and `Skeleton` primitives.
+  //    `Spinner` wears `colors.loader`; `Skeleton` reads the new `loading`
+  //    component scope (colour, radius). A scope may now name `sdkComponents`
+  //    and bind no widget field. Both stop under reduced motion.
+  version: "1.163.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -221,6 +221,23 @@ export function useHostNavigation() {
   return ctx ? ctx.navigation : undefined;
 }
 
+// A host translation, or null on a miss: both hosts answer a miss with the
+// key itself or a `{{t:…}}` placeholder.
+function hostTranslation(hostT, key) {
+  const text = hostT(key);
+  const hit =
+    typeof text === "string" && text.length > 0 && text !== key && !text.startsWith("{{t:");
+  return hit ? text : null;
+}
+
+// @internal — a predefined shared string in the host's language, or
+// `fallback` outside a widget context. Not re-exported from index.js.
+export function useHostSharedText(key, fallback) {
+  const ctx = useContext(HostWidgetContext);
+  const hostT = ctx && ctx.i18n && typeof ctx.i18n.t === "function" ? ctx.i18n.t : null;
+  return (hostT && hostTranslation(hostT, sharedTranslationKey(key))) || fallback;
+}
+
 /**
  * REQ-THEME-13 — returns the author-set per-widget style values: the object the
  * host delivers under `props.style`, keyed by the style-field names the widget
@@ -863,16 +880,8 @@ export function useI18n() {
         //    miss form both hosts emit). No fallback is passed here so a miss
         //    is unambiguous and we can fall through to the raw key.
         if (widgetId) {
-          const namespaced = widgetTranslationKey(widgetId, key);
-          const scoped = hostT(namespaced);
-          if (
-            typeof scoped === "string" &&
-            scoped.length > 0 &&
-            scoped !== namespaced &&
-            !scoped.startsWith("{{t:")
-          ) {
-            return scoped;
-          }
+          const scoped = hostTranslation(hostT, widgetTranslationKey(widgetId, key));
+          if (scoped !== null) return scoped;
         }
         // 2) REQ-L10N-SHARED: for a predefined SHARED key, try the tenant-wide
         //    `shared.<key>` namespace next. This is what lets identical
@@ -883,16 +892,8 @@ export function useI18n() {
         //    instance. Only the predefined keys are tried here — an
         //    author-invented bare key is never silently shared.
         if (isSharedTranslationKey(key)) {
-          const shared = sharedTranslationKey(key);
-          const scoped = hostT(shared);
-          if (
-            typeof scoped === "string" &&
-            scoped.length > 0 &&
-            scoped !== shared &&
-            !scoped.startsWith("{{t:")
-          ) {
-            return scoped;
-          }
+          const scoped = hostTranslation(hostT, sharedTranslationKey(key));
+          if (scoped !== null) return scoped;
         }
         // 3) Fall back to the raw key (shared app keys + widgets with no
         //    manifest translations — unchanged from pre-1.10 behaviour).