@colixsystems/widget-sdk 0.202.0 → 0.204.0

package/README.md

@@ -83,7 +83,34 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.202.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)
 
@@ -2411,6 +2438,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `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/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). " +
@@ -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",
   },
@@ -2846,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 = [
@@ -5339,7 +5366,11 @@ const CONTRACT = deepFreeze({
   // 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.
-  version: "1.161.0",
+  // 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). " +
@@ -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",
   },
@@ -2846,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 = [
@@ -5335,7 +5362,11 @@ const CONTRACT = deepFreeze({
   // 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.
-  version: "1.161.0",
+  // 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).

package/dist/index.d.ts

@@ -3487,6 +3487,74 @@ export const AccordionItem: (props: {
   testID?: string;
 }) => any;
 
+export type SpinnerSize = "sm" | "md" | "lg";
+
+/**
+ * Themed loading spinner. It wears the theme's `colors.loader`, stops turning
+ * under reduced motion, and is a labelled element in the busy state.
+ *
+ * @example
+ *   <Spinner />
+ *   <Spinner size="lg" label="Loading orders" />
+ */
+export const Spinner: (props: {
+  /** A named size, or a diameter in px. Defaults to "md". */
+  size?: SpinnerSize | number;
+  /** Overrides `colors.loader`, for contrast inside a control you fill yourself. */
+  color?: string;
+  /** Drawn under the ring. A string is also the accessibility label; a node stays exposed as content. */
+  label?: ReactNode;
+  /** The accessibility label, instead of `label` / the app's own "Loading…". */
+  accessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  testID?: string;
+}) => any;
+
+export type SkeletonShape = "text" | "block" | "circle" | "listRow";
+
+/**
+ * Themed loading placeholder. Its colour and corners come from the theme's
+ * `loading` scope. The outermost Skeleton pulses as a whole (still under
+ * reduced motion), is the one loading region (`role="status"` + `aria-busy`
+ * on the web; a labelled accessible element in the busy state on native), and
+ * hides every bone inside it from assistive technology — pass children to
+ * group bones.
+ *
+ * @example
+ *   <Skeleton shape="listRow" count={4} />
+ *   <Skeleton style={{ flexDirection: "row", gap: 12 }}>
+ *     <Skeleton shape="circle" />
+ *     <Skeleton shape="text" lines={2} style={{ flex: 1 }} />
+ *   </Skeleton>
+ */
+export const Skeleton: (props: {
+  /** Defaults to "text". Ignored when children are passed. */
+  shape?: SkeletonShape;
+  /** `text` / `block`. Defaults to "100%". */
+  width?: number | string;
+  /** `text` / `block`. */
+  height?: number;
+  /** `circle` diameter. */
+  size?: number;
+  /** `text`: how many lines; the last one stops short. */
+  lines?: number;
+  /** `listRow`: how many rows. Defaults to 3. */
+  count?: number;
+  /** `listRow`: draw the leading avatar. Defaults to true. */
+  leading?: boolean;
+  radius?: number;
+  color?: string;
+  /** The region's accessibility label, instead of the app's own "Loading…". */
+  accessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
 export type TextRole = "display" | "title" | "subtitle" | "body" | "caption" | "overline";
 export const TEXT_ROLES: readonly TextRole[];
 export const TEXT_TRANSFORMS: readonly string[];

package/dist/index.js

@@ -261,6 +261,8 @@ export { TextField } from "./text-field.js";
 export { Accordion, AccordionItem } from "./accordion.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.js";
+// Themed loading states; follow the theme's `loading` scope.
+export { Spinner, Skeleton } from "./loading.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -254,6 +254,8 @@ export { TextField } from "./text-field.native.js";
 export { Accordion, AccordionItem } from "./accordion.native.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.native.js";
+// Themed loading states; follow the theme's `loading` scope.
+export { Spinner, Skeleton } from "./loading.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/loading-tokens.js

@@ -0,0 +1,122 @@
+// The values `<Spinner>` and `<Skeleton>` paint with. Platform-free, like
+// tabs-tokens.js, so both hosts draw one loading look and tests can pin it.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+// `md` and `lg` are the platform spinner's small and large.
+export const SPINNER_SIZES = Object.freeze({ sm: 16, md: 20, lg: 36 });
+export const DEFAULT_SPINNER_SIZE = "md";
+export const SPINNER_TURN_MS = 750;
+
+export const SKELETON_SHAPES = Object.freeze(["text", "block", "circle", "listRow"]);
+export const DEFAULT_SKELETON_SHAPE = "text";
+// One way of the pulse; a full breath is twice this.
+export const SKELETON_PULSE_MS = 900;
+export const SKELETON_PULSE_MIN_OPACITY = 0.5;
+export const SKELETON_TEXT_HEIGHT = 12;
+export const SKELETON_TEXT_GAP = 8;
+export const SKELETON_BLOCK_HEIGHT = 96;
+export const SKELETON_CIRCLE_SIZE = 40;
+export const SKELETON_LIST_ROWS = 3;
+
+// A paragraph's last line stops short, as real text does.
+const LAST_LINE_WIDTH = "60%";
+// A list row's title and subtitle.
+export const SKELETON_LIST_ROW_LINE_WIDTHS = Object.freeze(["45%", "30%"]);
+
+// Per-instance overrides a widget may pass, named as the theme tokens are.
+export const LOADING_TOKEN_NAMES = Object.freeze(["skeletonColor", "skeletonRadius"]);
+
+function isSet(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pick(overrides, scope, name) {
+  if (overrides && isSet(overrides[name])) return overrides[name];
+  if (scope && isSet(scope[name])) return scope[name];
+  return undefined;
+}
+
+/**
+ * Resolve a skeleton's look: explicit override, then the theme's `loading`
+ * scope, then the theme tokens. The scope passes the contract's own bounds, so
+ * a hand-edited theme cannot reach a native style unvalidated.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-instance values keyed by LOADING_TOKEN_NAMES.
+ */
+export function resolveLoadingTokens(theme, overrides) {
+  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 scope = normaliseThemeComponents({
+    loading: base.components && base.components.loading,
+  }).loading;
+  return {
+    skeletonColor: pick(overrides, scope, "skeletonColor") ?? colors.surfaceMuted,
+    skeletonRadius: pick(overrides, scope, "skeletonRadius") ?? radii.sm,
+  };
+}
+
+/**
+ * A spinner's colour: the one a widget passed, else the theme's `loader`, the
+ * app's Loading Indicator colour, which each painted surface re-derives.
+ */
+export function resolveSpinnerColor(theme, color) {
+  if (isSet(color)) return color;
+  const colors = (theme && theme.colors) || DEFAULT_THEME_TOKENS.colors;
+  return colors.loader || DEFAULT_THEME_TOKENS.colors.loader;
+}
+
+/** A spinner's diameter: a named size, or the number a widget passed. */
+export function spinnerDiameter(size) {
+  if (typeof size === "number" && Number.isFinite(size) && size > 0) return size;
+  return SPINNER_SIZES[size] || SPINNER_SIZES[DEFAULT_SPINNER_SIZE];
+}
+
+export function spinnerStrokeWidth(diameter) {
+  return Math.max(2, Math.round(diameter / 8));
+}
+
+export function normaliseSkeletonShape(shape) {
+  return SKELETON_SHAPES.includes(shape) ? shape : DEFAULT_SKELETON_SHAPE;
+}
+
+/**
+ * The box one bone is drawn in.
+ *
+ * @param {"text"|"block"|"circle"} shape
+ * @param {{ width?: number|string, height?: number, size?: number }} dims
+ * @param {number} radius — the resolved `skeletonRadius`.
+ */
+export function skeletonBox(shape, dims, radius) {
+  const { width, height, size } = dims || {};
+  if (shape === "circle") {
+    const diameter = isSet(size) ? size : SKELETON_CIRCLE_SIZE;
+    return { width: diameter, height: diameter, borderRadius: diameter / 2 };
+  }
+  return {
+    width: isSet(width) ? width : "100%",
+    height: isSet(height)
+      ? height
+      : shape === "block"
+        ? SKELETON_BLOCK_HEIGHT
+        : SKELETON_TEXT_HEIGHT,
+    borderRadius: radius,
+  };
+}
+
+/** The width of each line of a `text` skeleton, top to bottom. */
+export function skeletonLineWidths(lines, width) {
+  const count = Math.max(1, Math.floor(Number(lines) || 1));
+  const full = isSet(width) ? width : "100%";
+  return Array.from({ length: count }, (_, i) =>
+    count > 1 && i === count - 1 ? LAST_LINE_WIDTH : full,
+  );
+}
+
+export function skeletonListRowCount(count) {
+  const n = Math.floor(Number(count));
+  return Number.isFinite(n) && n > 0 ? n : SKELETON_LIST_ROWS;
+}

package/dist/loading-view.js

@@ -0,0 +1,330 @@
+// The ONE implementation behind `<Spinner>` and `<Skeleton>`. The bindings
+// (`loading.js` / `loading.native.js`) differ only in their primitives.
+
+import React from "react";
+import { useHostTheme, useHostSharedText } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { resolveListTokens, listRowFrame } from "./list-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+import { flattenStyle } from "./flatten-style.js";
+import {
+  resolveLoadingTokens,
+  resolveSpinnerColor,
+  spinnerDiameter,
+  spinnerStrokeWidth,
+  normaliseSkeletonShape,
+  skeletonBox,
+  skeletonLineWidths,
+  skeletonListRowCount,
+  SPINNER_TURN_MS,
+  SKELETON_PULSE_MS,
+  SKELETON_PULSE_MIN_OPACITY,
+  SKELETON_TEXT_GAP,
+  SKELETON_LIST_ROW_LINE_WIDTHS,
+} from "./loading-tokens.js";
+
+const LOADING_FALLBACK = CONTRACT.sharedTranslationKeys.loading.en;
+const FILL = { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 };
+const TRACK_OPACITY = 0.2;
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+
+// A labelled element in the busy state, on both hosts.
+function busyRegion(label) {
+  return { accessible: true, accessibilityLabel: label, "aria-busy": true };
+}
+
+// The web needs a role to expose the label; native has none for `status`.
+const LOADING_REGION = { role: "status" };
+
+/**
+ * Bind the shared loading components to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Animated: any, Easing: any, AccessibilityInfo: any}} rn
+ * @param {{ useNativeDriver: boolean }} options — false where no native driver exists.
+ */
+export function makeLoading(rn, { useNativeDriver }) {
+  const { View, Text, Animated, Easing, AccessibilityInfo } = rn;
+
+  // One listener for every loading state on screen. Reduced until the host
+  // answers, so nothing moves for a user who asked it not to.
+  const motion = (() => {
+    let reduced = true;
+    let subscription = null;
+    const listeners = new Set();
+    const set = (value) => {
+      if (reduced === !!value) return;
+      reduced = !!value;
+      listeners.forEach((notify) => notify());
+    };
+    const subscribe = (notify) => {
+      listeners.add(notify);
+      if (listeners.size === 1) {
+        AccessibilityInfo.isReduceMotionEnabled().then(set, () => {});
+        subscription = AccessibilityInfo.addEventListener("reduceMotionChanged", set);
+      }
+      return () => {
+        listeners.delete(notify);
+        if (listeners.size > 0) return;
+        if (subscription && typeof subscription.remove === "function") subscription.remove();
+        subscription = null;
+      };
+    };
+    return { subscribe, isReduced: () => reduced };
+  })();
+
+  function useReducedMotion() {
+    return React.useSyncExternalStore(motion.subscribe, motion.isReduced, motion.isReduced);
+  }
+
+  // One running animation however many components draw from it. Nothing is
+  // allocated until the first loading state asks for it.
+  function sharedLoop(build, project) {
+    let value = null;
+    let output = null;
+    let users = 0;
+    let loop = null;
+    const animated = () => {
+      if (!value) {
+        value = new Animated.Value(0);
+        output = project(value);
+      }
+      return output;
+    };
+    const retain = () => {
+      animated();
+      users += 1;
+      if (users === 1) {
+        loop = Animated.loop(build(value));
+        loop.start();
+      }
+      return () => {
+        users -= 1;
+        if (users > 0) return;
+        loop.stop();
+        loop = null;
+        value.setValue(0);
+      };
+    };
+    return { animated, retain };
+  }
+
+  const turn = sharedLoop(
+    (value) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: SPINNER_TURN_MS,
+        easing: Easing.linear,
+        useNativeDriver,
+      }),
+    (value) => value.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] }),
+  );
+
+  const breathe = (value, toValue) =>
+    Animated.timing(value, {
+      toValue,
+      duration: SKELETON_PULSE_MS,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver,
+    });
+  const pulse = sharedLoop(
+    (value) => Animated.sequence([breathe(value, 1), breathe(value, 0)]),
+    (value) =>
+      value.interpolate({ inputRange: [0, 1], outputRange: [1, SKELETON_PULSE_MIN_OPACITY] }),
+  );
+
+  function useSharedLoop(loop, moving) {
+    React.useEffect(() => (moving ? loop.retain() : undefined), [loop, moving]);
+  }
+
+  function useLoadingTheme(explicitTheme) {
+    const hostTheme = useHostTheme();
+    // A host drawing outside a widget context passes its own theme.
+    return explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+  }
+
+  function Spinner({
+    size,
+    color,
+    label,
+    accessibilityLabel,
+    theme: explicitTheme,
+    style,
+    testID,
+  }) {
+    const theme = useLoadingTheme(explicitTheme);
+    const loadingText = useHostSharedText("loading", LOADING_FALLBACK);
+    const moving = !useReducedMotion();
+    useSharedLoop(turn, moving);
+
+    const ink = resolveSpinnerColor(theme, color);
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const diameter = spinnerDiameter(size);
+    const ring = {
+      ...FILL,
+      borderRadius: diameter / 2,
+      borderWidth: spinnerStrokeWidth(diameter),
+    };
+    const hasLabel = label !== undefined && label !== null && label !== "";
+    // A string caption is already the spinner's name; a node speaks for itself.
+    const named = typeof label === "string" && label !== "";
+
+    return React.createElement(
+      View,
+      {
+        ...busyRegion(accessibilityLabel || (named && label) || loadingText),
+        accessibilityRole: "progressbar",
+        style: [{ alignItems: "center", justifyContent: "center", gap: spacing.sm }, style],
+        testID,
+      },
+      React.createElement(
+        Animated.View,
+        {
+          ...HIDDEN,
+          style: [
+            { width: diameter, height: diameter },
+            moving ? { transform: [{ rotate: turn.animated() }] } : null,
+          ],
+        },
+        React.createElement(View, {
+          style: [ring, { borderColor: ink, opacity: TRACK_OPACITY }],
+        }),
+        React.createElement(View, {
+          style: [ring, { borderColor: "transparent", borderTopColor: ink }],
+        }),
+      ),
+      hasLabel
+        ? React.createElement(
+            Text,
+            {
+              ...(named ? HIDDEN : null),
+              style: textRoleStyle(
+                "caption",
+                theme.typography || DEFAULT_THEME_TOKENS.typography,
+                theme.colors || DEFAULT_THEME_TOKENS.colors,
+              ),
+            },
+            label,
+          )
+        : null,
+    );
+  }
+  Spinner.displayName = "Spinner";
+
+  // True inside a `<Skeleton>` that already is the loading region.
+  const RegionContext = React.createContext(false);
+
+  // A bone the widget sizes by aspect ratio must not keep the default height.
+  function boneBox(box, style) {
+    if (flattenStyle(style).aspectRatio === undefined) return box;
+    const { height: _defaultHeight, ...rest } = box;
+    return rest;
+  }
+
+  function boneStyle(box, tokens, style) {
+    return [boneBox(box, style), { backgroundColor: tokens.skeletonColor }, style];
+  }
+
+  function bone(shape, dims, tokens, key) {
+    return React.createElement(View, {
+      ...HIDDEN,
+      key,
+      style: boneStyle(skeletonBox(shape, dims, tokens.skeletonRadius), tokens),
+    });
+  }
+
+  function listRows(theme, tokens, { count, leading = true }) {
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    // The real rows' own frame, so nothing shifts when they arrive.
+    const list = resolveListTokens(theme);
+    const rows = skeletonListRowCount(count);
+    return Array.from({ length: rows }, (_, row) =>
+      React.createElement(
+        View,
+        {
+          key: row,
+          style: {
+            ...listRowFrame(list, spacing),
+            paddingVertical: list.rowPadding,
+            minHeight: list.rowMinHeight,
+            ...(!list.separated && row < rows - 1 && list.dividerWidth > 0
+              ? { borderBottomWidth: list.dividerWidth, borderColor: list.dividerColor }
+              : null),
+          },
+        },
+        leading ? bone("circle", null, tokens, "leading") : null,
+        React.createElement(
+          View,
+          { style: { flex: 1, gap: SKELETON_TEXT_GAP } },
+          ...SKELETON_LIST_ROW_LINE_WIDTHS.map((width) => bone("text", { width }, tokens, width)),
+        ),
+      ),
+    );
+  }
+
+  // What a skeleton of several bones holds; null when it is a single bone.
+  function composite(kind, props, theme, tokens) {
+    if (props.children !== undefined && props.children !== null) {
+      return { content: props.children, layout: null };
+    }
+    if (kind === "listRow") {
+      return {
+        content: listRows(theme, tokens, props),
+        layout: { gap: resolveListTokens(theme).gap },
+      };
+    }
+    if (kind !== "text" || !(props.lines > 1)) return null;
+    const { lines, width, height } = props;
+    return {
+      content: skeletonLineWidths(lines, width).map((lineWidth, i) =>
+        bone("text", { width: lineWidth, height }, tokens, i),
+      ),
+      layout: { gap: SKELETON_TEXT_GAP },
+    };
+  }
+
+  function Skeleton(props) {
+    const { shape, accessibilityLabel, theme: explicitTheme, style, testID } = props;
+    const theme = useLoadingTheme(explicitTheme);
+    const loadingText = useHostSharedText("loading", LOADING_FALLBACK);
+    const nested = React.useContext(RegionContext);
+    // The outermost skeleton pulses as one; the bones inside it never animate.
+    const moving = !useReducedMotion() && !nested;
+    useSharedLoop(pulse, moving);
+
+    const tokens = resolveLoadingTokens(theme, {
+      skeletonColor: props.color,
+      skeletonRadius: props.radius,
+    });
+    const kind = normaliseSkeletonShape(shape);
+    const group = composite(kind, props, theme, tokens);
+    const own = group
+      ? [group.layout, style]
+      : boneStyle(skeletonBox(kind, props, tokens.skeletonRadius), tokens, style);
+
+    if (nested) {
+      return React.createElement(
+        View,
+        { ...(group ? null : HIDDEN), style: own, testID },
+        group && group.content,
+      );
+    }
+    return React.createElement(
+      RegionContext.Provider,
+      { value: true },
+      React.createElement(
+        Animated.View,
+        {
+          ...busyRegion(accessibilityLabel || loadingText),
+          ...LOADING_REGION,
+          style: [own, moving ? { opacity: pulse.animated() } : null],
+          testID,
+        },
+        group && group.content,
+      ),
+    );
+  }
+  Skeleton.displayName = "Skeleton";
+
+  return { Spinner, Skeleton };
+}

package/dist/loading.js

@@ -0,0 +1,7 @@
+// `<Spinner>` and `<Skeleton>` (web). Binds ./loading-view.js to
+// react-native-web; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeLoading } from "./loading-view.js";
+
+export const { Spinner, Skeleton } = makeLoading(ReactNative, { useNativeDriver: false });

package/dist/loading.native.js

@@ -0,0 +1,10 @@
+// `<Spinner>` and `<Skeleton>` (native). Binds ./loading-view.js to React
+// Native's own primitives; only the import differs from ./loading.js.
+
+import { View, Text, Animated, Easing, AccessibilityInfo } from "react-native";
+import { makeLoading } from "./loading-view.js";
+
+export const { Spinner, Skeleton } = makeLoading(
+  { View, Text, Animated, Easing, AccessibilityInfo },
+  { useNativeDriver: true },
+);

package/package.json

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

@@ -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). " +
@@ -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",
   },
@@ -2846,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 = [
@@ -5335,7 +5362,11 @@ const CONTRACT = deepFreeze({
   // 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.
-  version: "1.161.0",
+  // 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,