@colixsystems/widget-sdk 0.202.0 → 0.205.0

package/dist/index.js

@@ -124,6 +124,11 @@ export {
   AudioPlayerError,
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export {
+  useUserStats,
+  useUserActivity,
+  useInactiveUsers,
+} from "./stats-hooks.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box
 // identically on the Player and the Expo export.
@@ -261,6 +266,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

@@ -122,6 +122,11 @@ export {
   AudioPlayerError,
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export {
+  useUserStats,
+  useUserActivity,
+  useInactiveUsers,
+} from "./stats-hooks.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";
 // sc-8104 — see the note on the web mirror in ./index.js.
@@ -254,6 +259,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/linter.cjs

@@ -771,7 +771,8 @@ function _scopeRules(source, manifest) {
     // the edit-style write scope above.
     if (usesUsersHook && !firedUsersDelete) {
       for (const m of USER_DELETE_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // remove(userId) takes an id; an event subscription's remove() does not.
+        const re = new RegExp(`\\.${m}\\s*\\(\\s*[^)\\s]`);
         if (re.test(line)) {
           if (
             !declared.has("users.delete:*") &&
@@ -791,7 +792,10 @@ function _scopeRules(source, manifest) {
     }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // Not group writes: `StyleSheet.create(`, and a subscription's bare remove().
+        const lookbehind = m === "create" ? "(?<!StyleSheet)" : "";
+        const needsArgs = m === "remove" ? "\\s*[^)\\s]" : "";
+        const re = new RegExp(`${lookbehind}\\.${m}\\s*\\(${needsArgs}`);
         if (re.test(line)) {
           if (m === "remove" && usesUsersHook) continue;
           if (

package/dist/linter.js

@@ -723,7 +723,8 @@ function _scopeRules(source, manifest) {
     // the edit-style write scope above.
     if (usesUsersHook && !firedUsersDelete) {
       for (const m of USER_DELETE_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // remove(userId) takes an id; an event subscription's remove() does not.
+        const re = new RegExp(`\\.${m}\\s*\\(\\s*[^)\\s]`);
         if (re.test(line)) {
           if (
             !declared.has("users.delete:*") &&
@@ -743,7 +744,10 @@ function _scopeRules(source, manifest) {
     }
     if (usesGroupsHook && !firedGroupsWrite) {
       for (const m of GROUP_MUTATION_METHODS) {
-        const re = new RegExp(`\\.${m}\\s*\\(`);
+        // Not group writes: `StyleSheet.create(`, and a subscription's bare remove().
+        const lookbehind = m === "create" ? "(?<!StyleSheet)" : "";
+        const needsArgs = m === "remove" ? "\\s*[^)\\s]" : "";
+        const re = new RegExp(`${lookbehind}\\.${m}\\s*\\(${needsArgs}`);
         if (re.test(line)) {
           // `.remove(` is also a useUsers method; only blame groups
           // when the source also uses the groups hook AND the source

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 },
+);