@colixsystems/widget-sdk 0.213.0 → 0.215.0

package/README.md

@@ -83,7 +83,33 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.213.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.215.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.215.0 (contract 1.174.0)
+
+**A themed chip: `Chip`, `ChipGroup`, and the `chip` theme scope.** `<Chip label selected onPress />` draws a filter chip, tag or pill whose fill, text colour, border, corner radius and selected colours come from **Theme Settings > Chips** (`themeConfig.components.chip`), so every chip in an app matches on the web Player and in the exported app. Pass `selected` with `onPress` for a chip that toggles (keep the selection in your own state), `onRemove` for a trailing remove button, `icon` for a lucide glyph before the label, and `disabled` to switch it off. A long label truncates on one line. `label` is a string or a number; pass `numberOfLines={0}` to let it wrap instead. `<ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen.
+
+```jsx
+const [status, setStatus] = useState("open");
+<ChipGroup selection="single" accessibilityLabel="Status">
+  {["open", "done"].map((s) => (
+    <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />
+  ))}
+</ChipGroup>
+<Chip label="Design" icon="tag" onRemove={() => removeTag("Design")} />
+```
+
+Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state. Outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web, Space and Enter press a chip, and a single-choice group is one tab stop whose arrow keys move the choice. The remove control is its own button labelled `Remove <label>`; pass `removeAccessibilityLabel` with your translated text. `size` is `"md"` (default, a 44px touch target) or `"sm"` (a compact 28px chip for a dense toolbar); `variant` is `"filled"` (default) or `"outlined"`. Pass `background`, `textColor`, `borderColor`, `radius`, `selectedBackground` or `selectedTextColor` (hex colours) to override one chip; a fill set without its text colour gets the dark or light label that reads on it. Unthemed, a chip is a muted pill with no border, and the selected one takes the primary colour. A status nobody taps stays a `<Badge>`.
+
+A component scope can now name the SDK components that read it directly (`sdkComponents`) instead of binding widget style fields; `chip` is the first.
+
+### What's new in 0.214.0 (contract 1.173.0)
+
+**Who is behind a figure — `useActiveUsers({ within, group_id, limit, offset })`.** One page of the users seen within `within` — `"online"` (default; the app open in the last two minutes), `"day"` (since midnight in the workspace's time zone), `"week"` or `"month"` (the last 7 / 30 days) — most recently seen first, as `[{ id, name, last_active_at, last_platform }]` with `total` for paging. Same gate as `useUserActivity` (`users.activity:*` plus the "View user activity" permission); pass `null` to read nothing.
+
+**"Who joined" — `useUsers({ joined_since, sort: "newest" })`.** The admin user list narrows to users created since `joined_since` (a `YYYY-MM-DD` date read in the workspace's time zone, or an ISO instant) and lists them newest first. Join dates are admin data, so a caller with only the directory view gets the plain list.
+
+**Reminding several — `remind(id, message, { refetch: false })`.** `useInactiveUsers`' `remind` re-reads the page after each reminder; pass `{ refetch: false }` while sending a batch and call `refetch()` once at the end.
 
 ### What's new in 0.213.0 (contract 1.172.0)
 
@@ -246,7 +272,7 @@ Like the `loading` scope, `alert` styles an SDK component rather than a widget's
 
 **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`).
+**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`); pass `{ refetch: false }` as a third argument when reminding several, then call `refetch()` once. 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.
 
@@ -2609,6 +2635,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `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.
 - `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, single-choice picker and search box. Like `TextField` they follow the theme's `muted` scope (and `popover` for the Select's option sheet) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level. Never hand-roll one from `Pressable` and `View`.
 - `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.
+- `Chip`, `ChipGroup` — the themed filter chip, tag or pill. `<Chip label selected onPress onRemove disabled>` follows the theme's `chip` scope; `<ChipGroup>` spaces and wraps its chips and, with `selection="single"`, announces them as one choice. Never hand-roll a chip from `Pressable` + a pill radius.
 - `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/chip-roving.js

@@ -0,0 +1,63 @@
+// The single tab stop of a single-choice `<ChipGroup>`, for the web. The chips
+// register with their group, and the group names the one that holds the tab
+// stop: the picked chip, else the first enabled one. Native never runs this:
+// React Native maps `tabIndex` to focusability, with no arrow keys to match.
+
+import React from "react";
+
+function inDocumentOrder([, a], [, b]) {
+  const before = a.node.compareDocumentPosition(b.node) & 4;
+  return before ? -1 : 1;
+}
+
+function tabStopHolder(members) {
+  const live = [...members.entries()]
+    .filter(([, m]) => !m.disabled && m.node && typeof m.node.compareDocumentPosition === "function")
+    .sort(inDocumentOrder);
+  const holder = live.find(([, m]) => m.selected) || live[0];
+  return holder ? holder[0] : null;
+}
+
+/**
+ * The group's half: a registry of its choices and the id that holds the tab
+ * stop. Inactive (both values null) unless `active`.
+ *
+ * @returns {{ register: Function|null, holder: string|null }}
+ */
+export function useTabStopRegistry(active) {
+  const members = React.useRef(new Map());
+  const [holder, setHolder] = React.useState(null);
+  const recompute = React.useCallback(() => setHolder(tabStopHolder(members.current)), []);
+  const register = React.useCallback(
+    (id, member) => {
+      if (member) members.current.set(id, member);
+      else members.current.delete(id);
+      recompute();
+    },
+    [recompute],
+  );
+  // After every render of the group: a reorder changes which chip is first.
+  React.useEffect(() => {
+    if (active) recompute();
+  });
+  return active ? { register, holder } : { register: null, holder: null };
+}
+
+/**
+ * A choice's half: registers it and returns its `tabIndex`, or undefined when
+ * its group keeps no single tab stop. Until the group has answered, the picked
+ * chip holds the stop so the first paint already has one.
+ */
+export function useTabStop(group, { node, disabled, selected, enrolled }) {
+  const id = React.useId();
+  const register = enrolled && group ? group.register : null;
+  React.useEffect(() => {
+    if (!register) return undefined;
+    register(id, { node: node.current, disabled: !!disabled, selected });
+    return () => register(id, null);
+  }, [register, id, node, disabled, selected]);
+  if (!register) return undefined;
+  if (disabled) return -1;
+  const holds = group.holder === null ? selected : group.holder === id;
+  return holds ? 0 : -1;
+}

package/dist/chip-tokens.js

@@ -0,0 +1,141 @@
+// The values `<Chip>` paints with, resolved from the theme's `chip` component
+// scope. Platform-free, like tabs-tokens.js, so both hosts draw one chip from
+// the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { readableInk } from "./readable-ink.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+export const CHIP_VARIANTS = Object.freeze(["filled", "outlined"]);
+export const DEFAULT_CHIP_VARIANT = "filled";
+
+// `md` is a full touch target; `sm` is the compact chip of a dense toolbar.
+export const CHIP_SIZES = Object.freeze({
+  sm: Object.freeze({ minHeight: 28, fontSize: "xs", iconSize: 12 }),
+  md: Object.freeze({ minHeight: 44, fontSize: "sm", iconSize: 16 }),
+});
+export const DEFAULT_CHIP_SIZE = "md";
+
+// How a group of chips announces: one choice, several, or plain actions.
+export const CHIP_SELECTIONS = Object.freeze(["none", "single", "multiple"]);
+
+// Per-chip overrides a widget may pass, named as the theme tokens are.
+export const CHIP_TOKEN_NAMES = Object.freeze([
+  "background",
+  "textColor",
+  "borderColor",
+  "radius",
+  "selectedBackground",
+  "selectedTextColor",
+]);
+
+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;
+}
+
+export function chipVariant(variant) {
+  return CHIP_VARIANTS.includes(variant) ? variant : DEFAULT_CHIP_VARIANT;
+}
+
+/** Object.hasOwn, because an inherited key ("constructor") is truthy. */
+export function chipSize(size) {
+  return CHIP_SIZES[Object.hasOwn(CHIP_SIZES, size) ? size : DEFAULT_CHIP_SIZE];
+}
+
+/**
+ * The role a chip announces with. A chip told whether it is `selected` is a
+ * choice: a radio in a single-choice group, otherwise a checkbox. Both carry
+ * `aria-checked`, the one selected state web and native each announce.
+ *
+ * @param {{ selectable: boolean, pressable: boolean, selection?: string }} chip
+ * @returns {"radio"|"checkbox"|"button"|undefined}
+ */
+export function chipRole({ selectable, pressable, selection }) {
+  if (selectable) return selection === "single" ? "radio" : "checkbox";
+  return pressable ? "button" : undefined;
+}
+
+/** The role a group announces with; only a single-choice group has one. */
+export function chipGroupRole(selection) {
+  return selection === "single" ? "radiogroup" : undefined;
+}
+
+/**
+ * Resolve one chip: explicit override, then the theme's `chip` scope, then the
+ * variant's own defaults. Overrides pass the contract's bounds, so a bad prop
+ * cannot reach a native style unvalidated. A border is drawn only when a
+ * colour for it resolves, so an unthemed filled chip keeps its exact size.
+ * A fill chosen without its text colour gets the label that reads on it.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — CHIP_TOKEN_NAMES values, plus `variant`.
+ */
+export function resolveChipTokens(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 = base.components && base.components.chip;
+  const own = normaliseThemeComponents({ chip: overrides }).chip;
+  const outlined = chipVariant(overrides && overrides.variant) === "outlined";
+
+  const ownFill = pick(own, scope, "background");
+  const ownSelectedFill = pick(own, scope, "selectedBackground");
+  const idleInk = outlined ? colors.onSurface : colors.onSurfaceMuted;
+  return {
+    background: ownFill ?? (outlined ? colors.surface : colors.surfaceMuted),
+    textColor:
+      pick(own, scope, "textColor") ?? (ownFill ? readableInk(ownFill, colors.surface) : idleInk),
+    borderColor: pick(own, scope, "borderColor") ?? (outlined ? colors.border : undefined),
+    radius: pick(own, scope, "radius") ?? radii.pill ?? DEFAULT_THEME_TOKENS.radii.pill,
+    selectedBackground: ownSelectedFill ?? colors.primary,
+    selectedTextColor:
+      pick(own, scope, "selectedTextColor") ??
+      (ownSelectedFill ? readableInk(ownSelectedFill, colors.surface) : colors.onPrimary),
+  };
+}
+
+/** The fill, ink and edge of one chip in its current state. */
+export function chipPaint(tokens, selected) {
+  const paint = {
+    backgroundColor: selected ? tokens.selectedBackground : tokens.background,
+    color: selected ? tokens.selectedTextColor : tokens.textColor,
+    borderRadius: tokens.radius,
+  };
+  if (tokens.borderColor === undefined) return paint;
+  // A selected chip's edge is clear, so the fill beneath shows through it: a
+  // translucent fill painted again as the border would draw a darker ring.
+  return {
+    ...paint,
+    borderWidth: 1,
+    borderColor: selected ? "transparent" : tokens.borderColor,
+  };
+}
+
+/**
+ * What each `chip` token resolves to while unset, keyed by token name, so the
+ * Studio can preview the default each control would replace. Each is resolved
+ * with only that token removed, since a text colour follows the fill beside
+ * it. No border colour: a chip with none set draws no border.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ */
+export function chipScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const scope = (base.components && base.components.chip) || {};
+  const out = {};
+  for (const name of CHIP_TOKEN_NAMES) {
+    const without = { ...scope, [name]: undefined };
+    const value = resolveChipTokens({ ...base, components: { ...base.components, chip: without } })[name];
+    if (value !== undefined) out[name] = value;
+  }
+  // A pill radius is past the token's range; its ceiling draws the same pill.
+  out.radius = Math.min(out.radius, CONTRACT.themeComponents.chip.tokens.radius.max);
+  return out;
+}

package/dist/chip-view.js

@@ -0,0 +1,324 @@
+// The ONE implementation behind the `<Chip>` and `<ChipGroup>` SDK components.
+// The platform bindings (`chip.js` / `chip.native.js`) differ only in where
+// the primitives come from, so the hosts cannot drift.
+//
+// Filter chips, tags and pills were hand-built per widget, each with its own
+// radius, padding and selected colour. This one reads the theme's `chip` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import {
+  CHIP_SELECTIONS,
+  chipGroupRole,
+  chipPaint,
+  chipRole,
+  chipSize,
+  resolveChipTokens,
+} from "./chip-tokens.js";
+import { useTabStop, useTabStopRegistry } from "./chip-roving.js";
+
+const h = React.createElement;
+const DISABLED_OPACITY = 0.5;
+// react-native-web ignores hitSlop, so the remove target has real width;
+// native honours it, so there the target also reaches a full touch size.
+const REMOVE_TARGET_MIN_WIDTH = 32;
+const TOUCH_TARGET = 44;
+const ARROW_STEP = Object.freeze({ ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 });
+// Outside a group nothing says how close the next row is, so stay small.
+const UNGROUPED_ROW_GAP = 4;
+
+function plainLabel(label) {
+  if (typeof label === "number" && Number.isFinite(label)) return String(label);
+  return typeof label === "string" ? label : "";
+}
+
+function shapeStyle({ dims, surface, grouped, disabled }) {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    // A long label truncates inside its row instead of pushing past it.
+    flexShrink: 1,
+    minWidth: 0,
+    maxWidth: "100%",
+    minHeight: dims.minHeight,
+    ...surface,
+    // Alone in a column it hugs its label; a group aligns its own chips.
+    ...(grouped ? null : { alignSelf: "flex-start" }),
+    ...(disabled ? { opacity: DISABLED_OPACITY } : null),
+  };
+}
+
+function bodyStyle(spacing, removable) {
+  return {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: spacing.xs,
+    flexShrink: 1,
+    minWidth: 0,
+    paddingVertical: spacing.xs,
+    paddingStart: spacing.sm,
+    // The remove button owns the trailing inset when there is one.
+    paddingEnd: removable ? 0 : spacing.sm,
+  };
+}
+
+// Read when a key is pressed, so the arrows follow the order on screen.
+function enabledRadios(node) {
+  return Array.from(node.querySelectorAll('[role="radio"]')).filter(
+    (el) => el.getAttribute("aria-disabled") !== "true",
+  );
+}
+
+// The radiogroup pattern: an arrow moves focus to the next choice and picks it.
+function moveChoice(event, step) {
+  const group = event.currentTarget.closest('[role="radiogroup"]');
+  const radios = group ? enabledRadios(group) : [];
+  const at = radios.indexOf(event.currentTarget);
+  if (at < 0 || radios.length < 2) return;
+  event.preventDefault();
+  const next = radios[(at + step + radios.length) % radios.length];
+  next.focus();
+  next.click();
+}
+
+// Web only; native fires no key events. react-native-web presses on Enter for
+// every role but on Space for buttons alone, so a choice handles Space itself.
+function choiceKeyHandler(onPress, roving) {
+  return (event) => {
+    // A held key must not toggle at repeat rate, nor Alt+Arrow lose its meaning.
+    if (event.repeat || event.altKey || event.ctrlKey || event.metaKey) return;
+    if (event.key === " " || event.key === "Spacebar") {
+      event.preventDefault();
+      onPress();
+    } else if (roving && ARROW_STEP[event.key]) {
+      moveChoice(event, ARROW_STEP[event.key]);
+    }
+  };
+}
+
+// accessibilityRole + aria-*: the pair that announces on both hosts.
+function pressProps({ onPress, disabled, role, name }) {
+  return {
+    onPress,
+    disabled: !!disabled,
+    accessibilityRole: role,
+    accessibilityLabel: name,
+    "aria-disabled": !!disabled,
+  };
+}
+
+function choiceProps({ onPress, disabled, selected, roving, tabIndex }) {
+  return {
+    "aria-checked": selected,
+    ...(disabled ? null : { onKeyDown: choiceKeyHandler(onPress, roving) }),
+    ...(tabIndex === undefined ? null : { tabIndex }),
+  };
+}
+
+// Never past half the gap to the next row: a tap there belongs to that row.
+function removeHitSlop(dims, rowGap) {
+  const wanted = Math.max(0, (TOUCH_TARGET - dims.minHeight) / 2);
+  const vertical = Math.min(wanted, rowGap / 2);
+  return { top: vertical, bottom: vertical, right: (TOUCH_TARGET - REMOVE_TARGET_MIN_WIDTH) / 2 };
+}
+
+// With no clip on the chip, each half rounds its own outer corners so a focus
+// outline follows the pill.
+function startCorners(radius) {
+  return { borderTopStartRadius: radius, borderBottomStartRadius: radius };
+}
+
+function endCorners(radius) {
+  return { borderTopEndRadius: radius, borderBottomEndRadius: radius };
+}
+
+function labelStyle({ typography, dims, selected, ink }) {
+  return {
+    flexShrink: 1,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.sizes[dims.fontSize],
+    fontWeight: selected ? "600" : "500",
+    color: ink,
+  };
+}
+
+/**
+ * Bind the shared chip to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ * @param {{ web?: boolean }} [host] — `web` turns on the single tab stop.
+ */
+export function makeChip(rn, host) {
+  const { View, Text, Pressable } = rn;
+  const rovingTabStop = !!(host && host.web);
+  const GroupContext = React.createContext(null);
+
+  function RemoveButton({ onRemove, disabled, label, spacing, dims, ink, radius, rowGap, testID }) {
+    return h(
+      Pressable,
+      {
+        ...pressProps({ onPress: onRemove, disabled, role: "button", name: label }),
+        testID,
+        hitSlop: removeHitSlop(dims, rowGap),
+        style: {
+          ...endCorners(radius),
+          alignSelf: "stretch",
+          alignItems: "center",
+          justifyContent: "center",
+          minWidth: REMOVE_TARGET_MIN_WIDTH,
+          paddingStart: spacing.xs,
+          paddingEnd: spacing.sm,
+        },
+      },
+      h(Icon, { name: "x", size: dims.iconSize, color: ink }),
+    );
+  }
+
+  function Chip({
+    label,
+    icon,
+    selected,
+    onPress,
+    onRemove,
+    disabled,
+    variant,
+    size,
+    numberOfLines = 1,
+    theme: explicitTheme,
+    accessibilityLabel,
+    removeAccessibilityLabel,
+    style,
+    testID,
+    ...overrides
+  }) {
+    const group = React.useContext(GroupContext);
+    const hostTheme = useHostTheme();
+    // A Studio preview renders outside a widget context, so it passes its own.
+    const theme = explicitTheme || (group && group.theme) || hostTheme || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const dims = chipSize(size);
+    const isSelected = selected === true;
+    const tokens = resolveChipTokens(theme, { ...overrides, variant });
+    const { color: ink, ...surface } = chipPaint(tokens, isSelected);
+    const pressable = typeof onPress === "function";
+    const removable = typeof onRemove === "function";
+    const selection = group ? group.selection : "none";
+    // In a choice group every pressable chip is a choice, picked or not.
+    const selectable = pressable && (typeof selected === "boolean" || selection !== "none");
+    const roving = selectable && selection === "single";
+    const body = React.useRef(null);
+    const tabIndex = useTabStop(group, {
+      node: body,
+      disabled,
+      selected: isSelected,
+      enrolled: roving,
+    });
+
+    const shape = shapeStyle({ dims, surface, grouped: !!group, disabled });
+    const bodyLayout = bodyStyle(spacing, removable);
+    const content = [
+      icon ? h(Icon, { key: "icon", name: icon, size: dims.iconSize, color: ink }) : null,
+      h(
+        Text,
+        {
+          key: "label",
+          // Zero lifts the limit, so a long label wraps instead.
+          numberOfLines:
+            Number.isInteger(numberOfLines) && numberOfLines > 0 ? numberOfLines : undefined,
+          style: labelStyle({ typography, dims, selected: isSelected, ink }),
+        },
+        label,
+      ),
+    ];
+    const interaction = pressable
+      ? {
+          ...pressProps({
+            onPress,
+            disabled,
+            role: chipRole({ selectable, pressable, selection }),
+            name: accessibilityLabel || plainLabel(label) || undefined,
+          }),
+          ...(selectable
+            ? choiceProps({ onPress, disabled, selected: isSelected, roving, tabIndex })
+            : null),
+          ref: body,
+        }
+      : null;
+    const Body = pressable ? Pressable : View;
+
+    if (!removable) {
+      return h(Body, { ...interaction, style: [shape, bodyLayout, style], testID }, ...content);
+    }
+    return h(
+      View,
+      { style: [shape, style], testID },
+      h(
+        Body,
+        {
+          ...interaction,
+          style: [bodyLayout, startCorners(tokens.radius), { minHeight: dims.minHeight }],
+          testID: testID ? `${testID}-body` : undefined,
+        },
+        ...content,
+      ),
+      h(RemoveButton, {
+        onRemove,
+        disabled,
+        label: removeAccessibilityLabel || `Remove ${plainLabel(label)}`.trim(),
+        spacing,
+        dims,
+        ink,
+        radius: tokens.radius,
+        rowGap: group ? group.rowGap : UNGROUPED_ROW_GAP,
+        testID: testID ? `${testID}-remove` : undefined,
+      }),
+    );
+  }
+  Chip.displayName = "Chip";
+
+  function ChipGroup({
+    children,
+    selection,
+    gap,
+    theme: explicitTheme,
+    accessibilityLabel,
+    style,
+    testID,
+  }) {
+    const hostTheme = useHostTheme();
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const mode = CHIP_SELECTIONS.includes(selection) ? selection : "none";
+    const rowGap = typeof gap === "number" && Number.isFinite(gap) && gap >= 0 ? gap : spacing.xs;
+    const { register, holder } = useTabStopRegistry(rovingTabStop && mode === "single");
+    const context = React.useMemo(
+      () => ({ selection: mode, theme: explicitTheme, rowGap, register, holder }),
+      [mode, explicitTheme, rowGap, register, holder],
+    );
+    return h(
+      GroupContext.Provider,
+      { value: context },
+      h(
+        View,
+        {
+          accessibilityRole: chipGroupRole(mode),
+          accessibilityLabel,
+          testID,
+          style: [
+            { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: rowGap },
+            style,
+          ],
+        },
+        children,
+      ),
+    );
+  }
+  ChipGroup.displayName = "ChipGroup";
+
+  return { Chip, ChipGroup };
+}

package/dist/chip.js

@@ -0,0 +1,8 @@
+// `<Chip>` / `<ChipGroup>` (web). Binds ./chip-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier. Only the web keeps a single
+// tab stop per single-choice group.
+
+import * as ReactNative from "react-native-web";
+import { makeChip } from "./chip-view.js";
+
+export const { Chip, ChipGroup } = makeChip(ReactNative, { web: true });

package/dist/chip.native.js

@@ -0,0 +1,7 @@
+// `<Chip>` / `<ChipGroup>` (native). Binds ./chip-view.js to React Native's own
+// primitives; only the import differs from ./chip.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeChip } from "./chip-view.js";
+
+export const { Chip, ChipGroup } = makeChip({ View, Text, Pressable });

package/dist/contract.cjs

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -1960,7 +1976,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2100,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2133,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2143,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -3046,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5640,7 +5697,17 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -1960,7 +1976,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2100,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2133,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2143,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -3046,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5636,7 +5693,17 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -45,6 +45,12 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  */
 export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * What each token of the `chip` component scope resolves to while unset,
+ * keyed by token name: the values `<Chip>` paints an unthemed app with.
+ */
+export function chipScopeDefaults(theme: unknown): Record<string, string | number>;
+
 /**
  * The theme a surface painting `backgroundColor` hands its subtree: surface
  * tokens derived for that fill, and any type tier whose own ink cannot be read

package/dist/host.js

@@ -51,6 +51,9 @@ export { surfaceAwareTheme } from "./surface-theme.js";
 // the Expo export rendering the same notification (CLAUDE.md §8).
 // The dialog's resolved look, for the Studio's Design > Components > Dialogs preview.
 export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
+// What each `chip` scope token resolves to while unset, for the Studio's
+// Design page to preview beside its controls.
+export { chipScopeDefaults } from "./chip-tokens.js";
 
 export {
   createToastController,

package/dist/index.d.ts

@@ -1107,6 +1107,21 @@ export function useUserActivity(query?: { days?: 7 | 30 | 90; group_id?: string
   refetch(): Promise<void>;
 };
 
+/** Users seen within `within` (default "online"), most recently seen first. */
+export function useActiveUsers(query?: {
+  within?: "online" | "day" | "week" | "month";
+  group_id?: string;
+  limit?: number;
+  offset?: number;
+} | null): {
+  users: Array<{ id: string; name: string; last_active_at: string; last_platform: "web" | "ios" | "android" | "unknown" }>;
+  total: number | 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;
@@ -1121,7 +1136,8 @@ export function useInactiveUsers(query?: {
   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>;
+  /** `{ refetch: false }` skips re-reading the page, for a batch that reads once. */
+  remind(id: string, message: { title: string; body: string }, options?: { refetch?: boolean }): Promise<void>;
 };
 
 /** One record's online members, as `useOnlineMembers` reports them. */
@@ -2743,6 +2759,12 @@ export interface UsersQuery {
   is_active?: boolean;
   /** Restrict to members of one app-user group — the `id` of a `useGroups()` row. */
   group_id?: string;
+  /** Admin view only: users created since this date (workspace time zone) or instant. */
+  joined_since?: string;
+  /** Admin view only: "newest" lists the most recently created first. */
+  sort?: "name" | "newest";
+  /** "real" leaves out preview and store-review accounts; an in-app admin always gets "real". */
+  audience?: "all" | "real" | "preview";
   limit?: number;
   offset?: number;
 }
@@ -3895,6 +3917,73 @@ export const Banner: (props: {
   testID?: string;
 }) => any;
 
+export type ChipVariant = "filled" | "outlined";
+export type ChipSize = "sm" | "md";
+export type ChipSelection = "none" | "single" | "multiple";
+
+/**
+ * Themed filter chip, tag or pill. Its fill, text colour, border, corner radius
+ * and selected colours come from the theme's `chip` scope, so every chip in the
+ * app matches. Pass `selected` with `onPress` for a chip that toggles. Inside a
+ * `<ChipGroup>` with a `selection` every pressable chip is a choice (a radio
+ * when single, otherwise a checkbox); outside one, a boolean `selected` makes
+ * it a checkbox. `onRemove` adds a trailing remove button.
+ *
+ * @example
+ *   <Chip label="Open" selected={status === "open"} onPress={() => setStatus("open")} />
+ *   <Chip label="Design" onRemove={() => removeTag("Design")} />
+ */
+export const Chip: (props: {
+  label: string | number;
+  /** Lines the label may take before it truncates; 0 lets it wrap. Default 1. */
+  numberOfLines?: number;
+  /** A lucide icon name, drawn before the label. */
+  icon?: string;
+  selected?: boolean;
+  onPress?: () => void;
+  onRemove?: () => void;
+  disabled?: boolean;
+  /** `md` (default) is a 44px touch target; `sm` is a compact 28px chip. */
+  size?: ChipSize;
+  variant?: ChipVariant;
+  /**
+   * Hex colour overrides; leave unset so the theme's chip look applies. A fill
+   * set without its text colour gets the dark or light label that reads on it.
+   */
+  background?: string;
+  textColor?: string;
+  borderColor?: string;
+  radius?: number;
+  selectedBackground?: string;
+  selectedTextColor?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  accessibilityLabel?: string;
+  /** Defaults to "Remove <label>"; pass translated text. */
+  removeAccessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/**
+ * Wrapping row of `<Chip>`s: spaces them and wraps onto the next line when the
+ * row is full. `selection` sets how the chips announce and, on the web, how
+ * the keyboard reaches them (a single-choice group is one tab stop whose
+ * arrow keys move the choice). It holds no state: the selected
+ * value stays in your own state.
+ */
+export const ChipGroup: (props: {
+  children?: ReactNode;
+  selection?: ChipSelection;
+  /** Px between chips; defaults to the theme's `spacing.xs`. */
+  gap?: number;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  accessibilityLabel?: string;
+  style?: any;
+  testID?: string;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

package/dist/index.js

@@ -127,6 +127,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — one source, bound to how each platform says the app is in front.
@@ -284,6 +285,8 @@ export { Banner } from "./banner.js";
 export { Modal } from "./modal.js";
 // The standard confirmation, a preset of `<Modal>` and `<Button>`.
 export { ConfirmDialog } from "./confirm-dialog.js";
+// Themed filter chips, tags and pills; follow the theme's `chip` scope.
+export { Chip, ChipGroup } from "./chip.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -125,6 +125,7 @@ export { useDatastoreFigure } from "./datastore-figure.js";
 export {
   useUserStats,
   useUserActivity,
+  useActiveUsers,
   useInactiveUsers,
 } from "./stats-hooks.js";
 // sc-11025 — see the note on the web mirror in ./index.js.
@@ -277,6 +278,8 @@ export { Banner } from "./banner.native.js";
 export { Modal } from "./modal.native.js";
 // The standard confirmation, a preset of `<Modal>` and `<Button>`.
 export { ConfirmDialog } from "./confirm-dialog.native.js";
+// Themed filter chips, tags and pills; follow the theme's `chip` scope.
+export { Chip, ChipGroup } from "./chip.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/stats-hooks.js

@@ -108,13 +108,32 @@ export function useUserActivity(query) {
   return { ...state, activity: data };
 }
 
+/**
+ * sc-11066 — one page of users seen within `within` ("online" — the last two
+ * minutes — "day", "week" or "month"), most recently seen first. `query`:
+ * `{ within?, group_id?, limit?, offset? }`. Returns `{ users, total, loading,
+ * fetching, error, refetch }`; each user is `{ id, name, last_active_at,
+ * last_platform }`. Same gate as useUserActivity; null reads nothing.
+ */
+export function useActiveUsers(query) {
+  const users = useUsersNamespace("useActiveUsers", "active");
+  const key = query === null ? null : serialize(query);
+  const { data, ...state } = useKeyedRead(() => users.active(query), "active-users", key, toDirectoryError);
+  return {
+    ...state,
+    users: data && Array.isArray(data.data) ? data.data : [],
+    total: data && data.meta && Number.isFinite(data.meta.total) ? data.meta.total : null,
+  };
+}
+
 /**
  * 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.
+ * re-reads the page; `{ refetch: false }` as a third argument skips the
+ * re-read, so a batch reads once at the end. Same gate as useUserActivity.
  */
 export function useInactiveUsers(query) {
   const users = useUsersNamespace("useInactiveUsers", "inactive");
@@ -122,7 +141,7 @@ export function useInactiveUsers(query) {
   const { data, ...state } = useKeyedRead(() => users.inactive(query), "inactive", key, toDirectoryError);
   const { refetch } = state;
   const remind = useCallback(
-    async (id, message) => {
+    async (id, message, { refetch: reread = true } = {}) => {
       if (typeof users.remind !== "function") {
         throw new Error("useInactiveUsers: host did not inject ctx.directory.users.remind");
       }
@@ -131,7 +150,7 @@ export function useInactiveUsers(query) {
       } catch (err) {
         throw toDirectoryError(err);
       }
-      await refetch();
+      if (reread) await refetch();
     },
     [users, refetch],
   );

package/package.json

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

@@ -745,6 +745,22 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Filter chips, tags and pills: `<Chip>` reads this scope directly, so it
+  // names the SDK component it styles and binds no widget field. No uiDefault:
+  // an unset text colour follows its fill, so the default is derived.
+  chip: Object.freeze({
+    label: "Chips",
+    sdkComponents: Object.freeze(["Chip"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color" }),
+      textColor: Object.freeze({ type: "color" }),
+      borderColor: Object.freeze({ type: "color" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48 }),
+      selectedBackground: Object.freeze({ type: "color" }),
+      selectedTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -1960,7 +1976,9 @@ const HOOKS = [
       "Returns { users, loading, error, refetch, invite, deactivate, " +
       "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "res.data; rows are snake_case (is_active, created_at, …). For an admin, " +
+      "query { joined_since, sort: \"newest\" } lists who joined since a date " +
+      "(read in the workspace's time zone), newest first. Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
@@ -2082,6 +2100,30 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11066 — who was seen in a window, behind users.activity.
+  {
+    name: "useActiveUsers",
+    signature: "useActiveUsers({ within, group_id, limit, offset } | null)",
+    optionalArgs: ["within", "group_id", "limit", "offset"],
+    description:
+      "One page of users seen within `within`: \"online\" (default; the app " +
+      "open in the last two minutes), \"day\" (since midnight in the " +
+      "workspace's time zone), \"week\" or \"month\" (the last 7 / 30 days), " +
+      "most recently seen first: `users` = [{ id, name, last_active_at, " +
+      "last_platform }], `total` for paging. Use it to show WHO is behind an " +
+      "online or active figure. Same gate and errors as useUserActivity; null " +
+      "reads nothing.",
+    returnShape: {
+      users: "Array<{ id, name, last_active_at, last_platform }>",
+      total: "number | null",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DirectoryError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.users"],
+    scopes: ["users.activity:*"],
+  },
   {
     name: "useInactiveUsers",
     signature: "useInactiveUsers({ inactive_days, group_id, limit, offset } | null)",
@@ -2091,7 +2133,8 @@ const HOOKS = [
       "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. " +
+      "notifies one of them, records when (last_reminded_at) and re-reads; " +
+      "pass `{ refetch: false }` third to skip the re-read in a batch. " +
       "Same gate and errors as useUserActivity; null reads nothing.",
     returnShape: {
       users: "Array<{ id, name, last_active_at, last_reminded_at }>",
@@ -2100,7 +2143,7 @@ const HOOKS = [
       fetching: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
-      remind: "(id, { title, body }) => Promise<void>",
+      remind: "(id, { title, body }, { refetch? }) => Promise<void>",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
@@ -3046,6 +3089,20 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chip",
+    description:
+      'Themed chip. `<ChipGroup selection="single">{STATUSES.map((s) => <Chip key={s} label={s} selected={status === s} onPress={() => setStatus(s)} />)}</ChipGroup>`. THE way to build filter chips, tags and pills: anything small, rounded and tappable that selects, filters or can be removed. ONE facet with up to five options may be a single-choice `<ChipGroup>` of all its options; several facets, or a longer option list, go in the filter toolbar, where only the ACTIVE filters show as removable chips. Its fill, text colour, border, corner radius and selected colours come from the app\'s chip look (Theme Settings > Chips), so every chip in the app matches. Never hand-roll one from `Pressable` + `radii.pill` + a fill. A display-only STATE (Active, Paid, Overdue) is a `<Badge>`, not a chip. Props: `label` (a string or a number; it truncates on one line instead of breaking the row, or pass `numberOfLines={0}` to let it wrap), `icon` (optional lucide name before the label), `selected` (boolean; pass it together with `onPress` for a chip that toggles, and keep the selection in your own state), `onPress`, `onRemove` (adds a trailing x button, e.g. an active filter or a tag the user can drop; it is a separate button from `onPress`), `disabled`, `size` ("md" default, a full 44px touch target: use it on a narrow screen | "sm", a compact 28px chip for a medium or wide toolbar), `variant` ("filled" default | "outlined", a bordered chip on the surface), `accessibilityLabel`, `removeAccessibilityLabel` (default "Remove <label>"; pass your translated text), `style`, `testID`, and the overrides `background`, `textColor`, `borderColor`, `radius`, `selectedBackground`, `selectedTextColor` (hex colours; leave them unset so the app\'s chip look applies; a fill set without its text colour gets the dark or light label that reads on it). Inside a `<ChipGroup>` with a `selection`, every chip with `onPress` is a choice whether picked or not: a radio in a single-choice group, otherwise a checkbox, with its checked state; outside one, a chip given a boolean `selected` is a checkbox and a chip with only `onPress` is a button. On the web a single-choice group is one tab stop and the arrow keys move the choice.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "ChipGroup",
+    description:
+      'Wrapping row of `<Chip>`s. `<ChipGroup selection="multiple" accessibilityLabel="Tags">…</ChipGroup>` spaces its chips and wraps them onto the next line on a narrow screen, so never lay chips out in a hand-rolled `flexWrap` row. Props: `selection` ("none" default | "single", one choice at a time, so its chips are radios | "multiple", any number of choices), `gap` (px between chips; defaults to the theme\'s `spacing.xs`), `accessibilityLabel`, `style`, `testID`. It only lays out and announces: the selected value lives in your state and each chip gets its own `selected` and `onPress`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Card",
     description:
@@ -5636,7 +5693,17 @@ const CONTRACT = deepFreeze({
   //    and cancel labels, `tone` "default" | "destructive", `busy`). No new
   //    theme scope: the panel reads `modal`, the actions `button` and
   //    `destructive`. `Button` forwards a ref to its pressable.
-  version: "1.172.0",
+  // 1.173.0: additive (sc-11066) — `useActiveUsers(query)` lists who was
+  //    seen online / today / in 7 or 30 days through the new
+  //    `ctx.directory.users.active`; `useUsers` takes `joined_since` and
+  //    `sort: "newest"` for an admin's "who joined" list.
+  // 1.174.0: additive (sc-10926) — the `chip` component scope (background,
+  //    text colour, border colour, radius, selected background, selected text
+  //    colour) and the `Chip` / `ChipGroup` primitives that read it. The scope
+  //    binds no widget style fields: the component reads it on both hosts,
+  //    which a scope now states as `sdkComponents`.
+  //    Additive: an unthemed chip is the muted pill widgets drew by hand.
+  version: "1.174.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,