@colixsystems/widget-sdk 0.202.0 → 0.205.0

package/README.md

@@ -83,7 +83,42 @@ 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.205.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.205.0 (contract 1.164.0)
+
+**An app's user totals for its own admins — `useUserStats({ days, group_id })`.** Active and deactivated users, new users per day (7 / 30 days) or week (90 days) with the previous period's total beside them, users in no group, empty groups, and invite figures. Totals only — never a list of people. Needs `users.read:*` and the viewer's admin user access (else `error.code === "FORBIDDEN"`); `stats.invites` is null unless the widget also declares `users.write:*` and the viewer holds it.
+
+**User activity — `useUserActivity({ days, group_id })` and `useInactiveUsers({ inactive_days, group_id, limit, offset })`.** For a workspace that records user activity: who is online now, active in the last day / week / month, never active, active users per day or week, the web / iOS / Android split and the active share per group — and a page of the users not seen recently, never-seen first. Needs `users.activity:*` and the viewer's "View user activity" permission (else `error.code === "FORBIDDEN"`); when the workspace does not record activity, `error.reason === "ACTIVITY_DISABLED"` — show that, not zeros. Before user activity is offered to the workspace at all, `error.reason` is `"ACTIVITY_UNAVAILABLE"`: hide the section, as for `FORBIDDEN`. `useInactiveUsers` also returns `remind(userId, { title, body })`, which notifies one of them and records when (each row carries `last_reminded_at`). Days follow the workspace's time zone (`period.time_zone`).
+
+**Linter fix.** A widget that uses `useGroups` or `useUsers` is no longer refused for a write it never makes: `StyleSheet.create(...)` and an event subscription's bare `remove()` (an `AppState` listener, say) are not user or group writes.
+
+### 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 +2446,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). " +
@@ -1962,6 +1975,95 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
+  // sc-10691 / REQ-USERMGMT-10 — an app's user totals for its own admins.
+  {
+    name: "useUserStats",
+    signature: "useUserStats({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "Workspace user TOTALS for an app's own administrators — never a list " +
+      "of people. `days` is 7 or 30 (charted per day) or 90 (per ISO week), in " +
+      "the workspace's time zone (`stats.period.time_zone`); " +
+      "`group_id` (a useGroups() row id) narrows the user and invite " +
+      "figures to that group. `stats.users` = { active, deactivated, " +
+      "without_group }; `stats.new_users` = { total, previous_total, buckets: " +
+      "[{ date, count }] } with every bucket present and previous_total the " +
+      "equal-length window before the period; `stats.groups` and " +
+      "`stats.empty_groups`; `stats.invites` = { " +
+      "pending, expiring_soon, expired, accepted }. `without_group`, `groups` " +
+      "and `empty_groups` are null on a group-scoped read. `invites` is null unless " +
+      "the widget also declares users.write:* AND the viewer holds users.write " +
+      "— render \"no access\" for that section rather than zeros. A viewer " +
+      "without the admin user view gets error.code FORBIDDEN; show an " +
+      "explicit no-access state.",
+    returnShape: {
+      stats:
+        "{ period, group_id, users, new_users, groups, empty_groups, invites } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN without the admin user view, NOT_FOUND for a foreign group",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.read:*"],
+  },
+  // sc-10691 / REQ-USERMGMT-12 — user activity, behind users.activity.
+  {
+    name: "useUserActivity",
+    signature: "useUserActivity({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "User ACTIVITY for an app's administrators, for a workspace that " +
+      "records it: `activity.online_now` (app open in the last two minutes), " +
+      "`activity.active` = { day (since midnight), week, month (last 7/30 " +
+      "days), period (distinct users active in the period) }, " +
+      "`activity.never_active`, " +
+      "`activity.daily_active` = [{ date, count }] distinct active users per " +
+      "day (7/30 days) or week (90) in the workspace's time zone, `activity.platforms` = { web, ios, " +
+      "android, unknown } users active in the period, `activity.by_group` = " +
+      "[{ group_id, name, users, active }] (null on a group-scoped read), " +
+      "`activity.users` and `activity.recording_since` (activity before it " +
+      "is unknown — say \"since <date>\" next to never-active figures). Needs " +
+      "users.activity:* AND the viewer's \"View user activity\" permission " +
+      "(else error.code FORBIDDEN). error.reason \"ACTIVITY_UNAVAILABLE\" means " +
+      "user activity is not offered to this workspace yet: hide the section, " +
+      "like FORBIDDEN. When the workspace does not record activity, " +
+      "error.reason is \"ACTIVITY_DISABLED\": show that state, not zeros. " +
+      "Pass null instead of a query to read nothing (a section switched off).",
+    returnShape: {
+      activity:
+        "{ period, group_id, recording_since, users, online_now, active, never_active, daily_active, platforms, by_group } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN; reason ACTIVITY_UNAVAILABLE (hide) or ACTIVITY_DISABLED (not recorded)",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
+  {
+    name: "useInactiveUsers",
+    signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
+    optionalArgs: ["inactive_days", "group_id", "limit", "offset"],
+    description:
+      "One page of users not seen for `inactive_days` (1-365, default 30), " +
+      "never-seen first, then least recently seen: `users` = [{ id, name, " +
+      "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
+      "since recording began), `total` for paging. `remind(id, { title, body })` " +
+      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "Same gate and errors as useUserActivity; null reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_reminded_at }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      remind: "(id, { title, body }) => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -2608,7 +2710,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 +2948,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 +5455,16 @@ 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.
+  // 1.164.0: additive (sc-10691) — `useUserStats(query)` reads an app's user
+  //    totals through the new `ctx.directory.users.stats`; `useUserActivity`
+  //    and `useInactiveUsers` read user activity through the new
+  //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
+  //    new `users.activity:*` scope.
+  version: "1.164.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). " +
@@ -1962,6 +1975,95 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
+  // sc-10691 / REQ-USERMGMT-10 — an app's user totals for its own admins.
+  {
+    name: "useUserStats",
+    signature: "useUserStats({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "Workspace user TOTALS for an app's own administrators — never a list " +
+      "of people. `days` is 7 or 30 (charted per day) or 90 (per ISO week), in " +
+      "the workspace's time zone (`stats.period.time_zone`); " +
+      "`group_id` (a useGroups() row id) narrows the user and invite " +
+      "figures to that group. `stats.users` = { active, deactivated, " +
+      "without_group }; `stats.new_users` = { total, previous_total, buckets: " +
+      "[{ date, count }] } with every bucket present and previous_total the " +
+      "equal-length window before the period; `stats.groups` and " +
+      "`stats.empty_groups`; `stats.invites` = { " +
+      "pending, expiring_soon, expired, accepted }. `without_group`, `groups` " +
+      "and `empty_groups` are null on a group-scoped read. `invites` is null unless " +
+      "the widget also declares users.write:* AND the viewer holds users.write " +
+      "— render \"no access\" for that section rather than zeros. A viewer " +
+      "without the admin user view gets error.code FORBIDDEN; show an " +
+      "explicit no-access state.",
+    returnShape: {
+      stats:
+        "{ period, group_id, users, new_users, groups, empty_groups, invites } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN without the admin user view, NOT_FOUND for a foreign group",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.read:*"],
+  },
+  // sc-10691 / REQ-USERMGMT-12 — user activity, behind users.activity.
+  {
+    name: "useUserActivity",
+    signature: "useUserActivity({ days, group_id })",
+    optionalArgs: ["days", "group_id"],
+    description:
+      "User ACTIVITY for an app's administrators, for a workspace that " +
+      "records it: `activity.online_now` (app open in the last two minutes), " +
+      "`activity.active` = { day (since midnight), week, month (last 7/30 " +
+      "days), period (distinct users active in the period) }, " +
+      "`activity.never_active`, " +
+      "`activity.daily_active` = [{ date, count }] distinct active users per " +
+      "day (7/30 days) or week (90) in the workspace's time zone, `activity.platforms` = { web, ios, " +
+      "android, unknown } users active in the period, `activity.by_group` = " +
+      "[{ group_id, name, users, active }] (null on a group-scoped read), " +
+      "`activity.users` and `activity.recording_since` (activity before it " +
+      "is unknown — say \"since <date>\" next to never-active figures). Needs " +
+      "users.activity:* AND the viewer's \"View user activity\" permission " +
+      "(else error.code FORBIDDEN). error.reason \"ACTIVITY_UNAVAILABLE\" means " +
+      "user activity is not offered to this workspace yet: hide the section, " +
+      "like FORBIDDEN. When the workspace does not record activity, " +
+      "error.reason is \"ACTIVITY_DISABLED\": show that state, not zeros. " +
+      "Pass null instead of a query to read nothing (a section switched off).",
+    returnShape: {
+      activity:
+        "{ period, group_id, recording_since, users, online_now, active, never_active, daily_active, platforms, by_group } | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null  // FORBIDDEN; reason ACTIVITY_UNAVAILABLE (hide) or ACTIVITY_DISABLED (not recorded)",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
+  {
+    name: "useInactiveUsers",
+    signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
+    optionalArgs: ["inactive_days", "group_id", "limit", "offset"],
+    description:
+      "One page of users not seen for `inactive_days` (1-365, default 30), " +
+      "never-seen first, then least recently seen: `users` = [{ id, name, " +
+      "last_active_at, last_reminded_at }] (last_active_at null = never seen " +
+      "since recording began), `total` for paging. `remind(id, { title, body })` " +
+      "notifies one of them, records when (last_reminded_at) and re-reads. " +
+      "Same gate and errors as useUserActivity; null reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_reminded_at }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+      remind: "(id, { title, body }) => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -2608,7 +2710,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 +2948,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 +5451,16 @@ 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.
+  // 1.164.0: additive (sc-10691) — `useUserStats(query)` reads an app's user
+  //    totals through the new `ctx.directory.users.stats`; `useUserActivity`
+  //    and `useInactiveUsers` read user activity through the new
+  //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
+  //    new `users.activity:*` scope.
+  version: "1.164.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).
@@ -5612,7 +5613,8 @@ export class DirectoryError extends Error {
   }
 }
 
-function toDirectoryError(err) {
+// Internal: shared with stats-hooks.js, not re-exported by the index.
+export function toDirectoryError(err) {
   // See the note in toDatastoreError: the directory CLIENT has a same-named
   // class, so a client rejection is read from the envelope below, not here.
   if (err instanceof DirectoryError) return err;

package/dist/index.d.ts

@@ -1037,6 +1037,87 @@ export function useDatastoreFigure(
   options?: FigureOptions,
 ): FigureResult;
 
+export interface UserStatsQuery {
+  days?: 7 | 30 | 90;
+  /** A `useGroups()` row id: narrows user and invite figures to that group. */
+  group_id?: string;
+}
+
+export interface UserStats {
+  /** Days follow the workspace's `time_zone` (IANA; "UTC" when unset). */
+  period: { days: 7 | 30 | 90; bucket: "day" | "week"; from: string; to: string; time_zone: string };
+  group_id: string | null;
+  users: { active: number; deactivated: number; without_group: number | null };
+  /** `previous_total`: the equal-length window just before the period. */
+  new_users: {
+    total: number;
+    previous_total: number;
+    buckets: Array<{ date: string; count: number }>;
+  };
+  /** The workspace's groups; null on a group-scoped read. */
+  groups: number | null;
+  empty_groups: number | null;
+  /** Null unless the viewer may list invites (`users.write`). */
+  invites: { pending: number; expiring_soon: number; expired: number; accepted: number } | null;
+}
+
+/** An app's user totals for its own admins — never a list of people. */
+export function useUserStats(query?: UserStatsQuery): {
+  stats: UserStats | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+export interface UserActivity {
+  /** Days follow the workspace's `time_zone` (IANA; "UTC" when unset). */
+  period: { days: 7 | 30 | 90; bucket: "day" | "week"; from: string; to: string; time_zone: string };
+  group_id: string | null;
+  /** When the workspace started recording. */
+  recording_since: string | null;
+  users: number;
+  /** Seen with the app open in the last two minutes. */
+  online_now: number;
+  /** `day`: since midnight; `week`/`month`: last 7/30 days; `period`: distinct over the period. */
+  active: { day: number; week: number; month: number; period: number };
+  never_active: number;
+  daily_active: Array<{ date: string; count: number }>;
+  platforms: { web: number; ios: number; android: number; unknown: number };
+  by_group: Array<{ group_id: string; name: string; users: number; active: number }> | null;
+}
+
+/**
+ * User activity for an app's admins. Needs `users.activity:*` and the
+ * viewer's "View user activity" permission; `error.reason` is
+ * "ACTIVITY_DISABLED" when the workspace does not record activity, and
+ * "ACTIVITY_UNAVAILABLE" (hide the section) before it is offered at all.
+ */
+export function useUserActivity(query?: { days?: 7 | 30 | 90; group_id?: string }): {
+  activity: UserActivity | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+};
+
+/** Users not seen for `inactive_days` (default 30), never-seen first. */
+export function useInactiveUsers(query?: {
+  inactive_days?: number;
+  group_id?: string;
+  limit?: number;
+  offset?: number;
+} | null): {
+  users: Array<{ id: string; name: string; last_active_at: string | null; last_reminded_at: string | null }>;
+  total: number | null;
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+  /** Notify one user, record when, then re-read the page. */
+  remind(id: string, message: { title: string; body: string }): Promise<void>;
+};
+
 export function useDatastoreMutation<T = unknown>(
   table: string,
 ): MutationApi<T>;
@@ -3487,6 +3568,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[];