@colixsystems/widget-sdk 0.201.0 → 0.204.0

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). " +
@@ -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,