@colixsystems/widget-sdk 0.202.0 → 0.205.0

package/dist/stats-hooks.js

@@ -0,0 +1,144 @@
+// sc-10691 — read-only hooks for an app's user totals and user activity. Each
+// is one keyed read, stale-while-revalidate like useDatastoreQuery, and each
+// re-runs on the page's pull-to-refresh.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toDirectoryError, useRefresh, useWidgetContextOrThrow } from "./hooks.js";
+
+const EMPTY = { identity: null, key: null, data: null, error: null };
+
+function serialize(value) {
+  try {
+    return JSON.stringify(value === undefined ? null : value);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Runs `read()` whenever `key` changes. A changed key on the same `identity`
+ * keeps the previous data on screen (`fetching`); a new identity starts over
+ * (`loading`). A null key is "nothing to read" and settles empty.
+ */
+function useKeyedRead(read, identity, key, mapError) {
+  const readRef = useRef(read);
+  readRef.current = read;
+  const runRef = useRef(0);
+  const [settled, setSettled] = useState(EMPTY);
+  const [fetching, setFetching] = useState(key !== null);
+
+  const run = useCallback(async () => {
+    const myRun = ++runRef.current;
+    if (key === null) {
+      setSettled(EMPTY);
+      setFetching(false);
+      return;
+    }
+    setFetching(true);
+    try {
+      const data = await readRef.current();
+      if (runRef.current === myRun) setSettled({ identity, key, data, error: null });
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setSettled((prev) => ({
+        identity,
+        key,
+        data: prev.identity === identity ? prev.data : null,
+        error: mapError(err),
+      }));
+    } finally {
+      if (runRef.current === myRun) setFetching(false);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [identity, key]);
+
+  useEffect(() => {
+    run();
+  }, [run]);
+  useRefresh(run);
+
+  const sameIdentity = settled.identity === identity;
+  return {
+    data: sameIdentity ? settled.data : null,
+    loading: key !== null && !sameIdentity,
+    fetching,
+    error: sameIdentity ? settled.error : null,
+    refetch: run,
+  };
+}
+
+/**
+ * The app's user totals for its own admins — never a list of people.
+ * `query`: `{ days?: 7 | 30 | 90, group_id? }`. Returns `{ stats, loading,
+ * fetching, error, refetch }`; `stats.invites` is null unless the viewer may
+ * list invites. A viewer without the admin user view gets a FORBIDDEN error.
+ */
+export function useUserStats(query) {
+  const ctx = useWidgetContextOrThrow("useUserStats");
+  if (!ctx.directory || !ctx.directory.users || typeof ctx.directory.users.stats !== "function") {
+    throw new Error("useUserStats: host did not inject a directory client (ctx.directory.users.stats)");
+  }
+  const users = ctx.directory.users;
+  const key = serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.stats(query), "stats", key, toDirectoryError);
+  return { ...state, stats: data };
+}
+
+function useUsersNamespace(hookName, method) {
+  const ctx = useWidgetContextOrThrow(hookName);
+  const users = ctx.directory && ctx.directory.users;
+  if (!users || typeof users[method] !== "function") {
+    throw new Error(`${hookName}: host did not inject a directory client (ctx.directory.users.${method})`);
+  }
+  return users;
+}
+
+/**
+ * sc-10691 — user activity for an app's admins: who is online now, active
+ * in the last day / week / month, never active, active users per bucket,
+ * the platform split and the active share per group. `query`: `{ days?: 7 |
+ * 30 | 90, group_id? }`. `error.reason` is "ACTIVITY_DISABLED" when the
+ * workspace does not record activity, "ACTIVITY_UNAVAILABLE" before it is
+ * offered to the workspace, and `error.code` FORBIDDEN without the
+ * users.activity permission. Pass `null` to read nothing.
+ */
+export function useUserActivity(query) {
+  const users = useUsersNamespace("useUserActivity", "activity");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.activity(query), "activity", key, toDirectoryError);
+  return { ...state, activity: data };
+}
+
+/**
+ * sc-10691 — one page of users not seen for `inactive_days` (default 30),
+ * never-seen first. `query`: `{ inactive_days?, group_id?, limit?, offset? }`.
+ * Returns `{ users, total, loading, fetching, error, refetch, remind }`; each
+ * user is `{ id, name, last_active_at, last_reminded_at }` (last_active_at
+ * null when never seen). `remind(id, { title, body })` notifies one and
+ * re-reads the page. Same gate as useUserActivity.
+ */
+export function useInactiveUsers(query) {
+  const users = useUsersNamespace("useInactiveUsers", "inactive");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.inactive(query), "inactive", key, toDirectoryError);
+  const { refetch } = state;
+  const remind = useCallback(
+    async (id, message) => {
+      if (typeof users.remind !== "function") {
+        throw new Error("useInactiveUsers: host did not inject ctx.directory.users.remind");
+      }
+      try {
+        await users.remind(id, message);
+      } catch (err) {
+        throw toDirectoryError(err);
+      }
+      await refetch();
+    },
+    [users, refetch],
+  );
+  return {
+    ...state,
+    remind,
+    users: data && Array.isArray(data.data) ? data.data : [],
+    total: data && data.meta && Number.isFinite(data.meta.total) ? data.meta.total : null,
+  };
+}

package/package.json

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