@colixsystems/widget-sdk 0.205.1 → 0.207.0

package/README.md

@@ -83,7 +83,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.205.1` — 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.207.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.207.0 (contract 1.166.0)
+
+**A themed inline message: `Banner`, and the `alert` theme scope.** `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />` draws the box a widget shows when something needs saying in place: a list that failed to load, a form that cannot be submitted yet, a read-only notice. `tone` is `info` (default), `success`, `warning` or `error`; `title`, `icon`, `action` and `onDismiss` are all optional, and a long `message` wraps. `title` and `message` take text, which the banner themes, or an element you built, which it renders as given. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place. Its fill, text colour, border and corner radius come from **Design > Components > Alerts** (`themeConfig.components.alert`: `radius`, `borderWidth`, and `<tone>Background` / `<tone>TextColor` for each tone). Left unset, each tone is a soft tint of the theme's own status colour (`danger`, `success`, `warning`, `info`) with text that clears 4.5:1 on it, the same colours a toast of that kind is accented with, so the two agree. A background set without a text colour takes whichever of dark or light text has the higher contrast on it, measured as the fill appears over the surface when it is translucent.
+
+Use a banner for a message that belongs to a place and stays until it is resolved, and `useToast()` for a brief confirmation of something the user just did. The built-in Notifications and User Management widgets now render their error boxes through it.
+
+Like the `loading` scope, `alert` styles an SDK component rather than a widget's style field: it declares `sdkComponents: ["Banner"]` and an empty `targets`. `bannerScopeDefaults(theme)` on the `/host` entry returns what each token resolves to while unset.
+
+- **`CONTRACT.version` → `1.166.0`** (additive: the `Banner` primitive and the `alert` scope).
+- **Changed:** a pill tab's automatic active-label colour (a custom `activeColor` with no `activeTextColor`) is now chosen by contrast between a fixed dark ink (`#111827`) and white, measured over the surface when the accent is translucent. It was chosen between the theme's own text colour and white, which left the label unreadable on a dark theme. Apps whose theme text colour is not the default will see that label in the fixed ink instead of their text colour; an explicit `activeTextColor` still wins.
+
+### What's new in 0.206.0 (contract 1.165.0)
+
+**Who is online — `useOnlineMembers(tableId, recordIds)` and `useOnlineVisibility()`.** For the people who share a record (a conversation, a team, a case): which members of records you are a member of — users holding their own read grant on it, given by a person — have the app open now and show their online status. A table opts in: a template table declares `presence: true` (an upgrade that declares it turns it on), or a builder turns on the table's "Show members' online status" setting in the Studio. `online` is a `Set` of user ids across the records and `byRecord[recordId]` is `{ online_user_ids, online_count }` (ids capped at 100, so count with `online_count`); a record the viewer only reads (through a group or a grant to everyone) or cannot read answers with nobody, and there are never timestamps. It refreshes every minute while the app is in front, on return to it and on pull-to-refresh. `supported` is true only once the workspace answered: it is false while the workspace does not record user activity, when the table has not opted in, when the viewer hides their own status, or in a preview — then show no online state at all, never "offline". Declare `directory.read:users`; the publish checks do not require it for this hook, but it is the scope the hook belongs to. `useOnlineVisibility()` is the viewer's own "Show when I'm online" switch (`{ supported, showOnline, setShowOnline }`, on by default): hiding takes the viewer out of everyone's answers, and they then see nobody online either.
 
 ### What's new in 0.205.1
 
@@ -2449,6 +2464,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `List`, `ListRow`, `ListHeader`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<ListHeader>` labels a table's columns on the rows' own inset; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row or a header row from `View` + `Pressable`.
 - `Badge`, `Avatar`, `Progress`, `Stat`, `Divider` — the themed status pill, person picture, completion bar or ring, headline figure and rule the built-in widgets of the same names render through. Reach for them inside a record row instead of hand-rolling a pill or a circle from `View`.
 - `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.

package/dist/banner-tokens.js

@@ -0,0 +1,116 @@
+// The values `<Banner>` paints with, resolved from the theme's `alert`
+// component scope. Platform-free, like tabs-tokens.js, so both hosts draw one
+// banner from the same numbers and tests can pin them without a renderer.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT, deriveAccentTints, mixHex } from "./contract.js";
+import { compositeOver, readableInk } from "./readable-ink.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+import { KIND_COLOR_ROLE } from "./toast-host.js";
+
+export const BANNER_TONES = Object.freeze(["info", "success", "warning", "error"]);
+export const DEFAULT_BANNER_TONE = "info";
+export const DEFAULT_BANNER_BORDER_WIDTH = 1;
+
+// The glyph a tone carries when the caller names none.
+export const BANNER_TONE_ICONS = Object.freeze({
+  info: "info",
+  success: "circle-check",
+  warning: "triangle-alert",
+  error: "circle-alert",
+});
+
+// How far the outline sits from the text colour toward the fill.
+const BORDER_FILL_WEIGHT = 0.7;
+
+export function normaliseBannerTone(tone) {
+  return BANNER_TONES.includes(tone) ? tone : DEFAULT_BANNER_TONE;
+}
+
+/** The `alert` scope's token names for one tone's fill and text. */
+export function bannerToneTokenNames(tone) {
+  return { background: `${tone}Background`, textColor: `${tone}TextColor` };
+}
+
+// The soft fill + readable text of a tone, from the status colour a toast of
+// the same kind is accented with.
+function defaultTonePair(colors, tone) {
+  const fallback = DEFAULT_THEME_TOKENS.colors;
+  const role = KIND_COLOR_ROLE[tone];
+  const tints = deriveAccentTints(
+    colors[role] || fallback[role],
+    colors.surface || fallback.surface,
+    colors.onSurface || fallback.onSurface,
+  );
+  return tints
+    ? { background: tints.primarySoft, textColor: tints.onPrimarySoft }
+    : { background: colors.surfaceMuted, textColor: colors.onSurface };
+}
+
+/**
+ * Resolve one banner: the theme's `alert` scope, then the tone's status
+ * colour. A themed fill with no themed text takes whichever of dark or light
+ * text has the higher contrast on it, so the message stays legible.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {string} tone — `info` | `success` | `warning` | `error`.
+ */
+export function resolveBannerTokens(theme, tone) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const fallback = DEFAULT_THEME_TOKENS;
+  const colors = base.colors || fallback.colors;
+  const radii = base.radii || fallback.radii;
+  const safeTone = normaliseBannerTone(tone);
+  const scope = normaliseThemeComponents(base.components).alert || {};
+  const names = bannerToneTokenNames(safeTone);
+  const derived = defaultTonePair(colors, safeTone);
+
+  const background = scope[names.background] ?? derived.background;
+  const textColor =
+    scope[names.textColor] ??
+    (scope[names.background] === undefined
+      ? derived.textColor
+      : readableInk(background, colors.surface));
+  return {
+    tone: safeTone,
+    background,
+    textColor,
+    borderColor: mixHex(
+      textColor,
+      compositeOver(background, colors.surface),
+      BORDER_FILL_WEIGHT,
+    ),
+    borderWidth: scope.borderWidth ?? DEFAULT_BANNER_BORDER_WIDTH,
+    radius: scope.radius ?? radii.md,
+    icon: BANNER_TONE_ICONS[safeTone],
+  };
+}
+
+// The tone a token belongs to and the resolved value it sets.
+function tokenReading(token) {
+  for (const tone of BANNER_TONES) {
+    const names = bannerToneTokenNames(tone);
+    if (token === names.background) return { tone, value: "background" };
+    if (token === names.textColor) return { tone, value: "textColor" };
+  }
+  return { tone: DEFAULT_BANNER_TONE, value: token };
+}
+
+/**
+ * What each `alert` token resolves to once THAT token is unset, keyed by token
+ * name, so the Studio previews the value each control would replace. The rest
+ * of the scope stays: a tone's default text depends on its themed fill.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function bannerScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const scope = (base.components && base.components.alert) || {};
+  const out = {};
+  for (const token of Object.keys(CONTRACT.themeComponents.alert.tokens)) {
+    const { tone, value } = tokenReading(token);
+    const without = { ...base, components: { ...base.components, alert: { ...scope, [token]: undefined } } };
+    out[token] = resolveBannerTokens(without, tone)[value];
+  }
+  return out;
+}

package/dist/banner-view.js

@@ -0,0 +1,198 @@
+// The ONE implementation behind the `<Banner>` SDK primitive. The platform
+// bindings (`banner.js` / `banner.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// Widgets each drew their own error box, so the same kind of message looked
+// different in every widget. This one reads the theme's `alert` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import { resolveBannerTokens } from "./banner-tokens.js";
+
+const ICON_SIZE = 18;
+const DISMISS_ICON_SIZE = 16;
+const LINE_MIN_HEIGHT = 24;
+// A real 36px target: the web host ignores hitSlop, so size carries it.
+const CONTROL_MIN_SIZE = 36;
+const CONTROL_HIT_SLOP = 4;
+
+const h = React.createElement;
+
+function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+function isShown(value) {
+  return value !== undefined && value !== null && value !== false && value !== "";
+}
+
+// An error is an alert on both hosts. The other tones are a polite live
+// region on the web and Android; iOS has no equivalent and reads them in place.
+function announcement(tone) {
+  return tone === "error"
+    ? { accessibilityRole: "alert", accessibilityLiveRegion: "assertive" }
+    : { role: "status", accessibilityLiveRegion: "polite" };
+}
+
+/**
+ * Bind the shared banner to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeBanner(rn) {
+  const { View, Text, Pressable } = rn;
+
+  function BannerAction({ action, ink, typography, fallbackTestID }) {
+    return h(
+      Pressable,
+      {
+        onPress: action.onPress,
+        accessibilityRole: "button",
+        accessibilityLabel: action.accessibilityLabel || action.label,
+        hitSlop: CONTROL_HIT_SLOP,
+        testID: action.testID || fallbackTestID,
+        style: ({ pressed }) => [
+          {
+            minWidth: CONTROL_MIN_SIZE,
+            minHeight: CONTROL_MIN_SIZE,
+            paddingHorizontal: 4,
+            alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+          },
+          pressed ? { opacity: 0.6 } : null,
+        ],
+      },
+      h(
+        Text,
+        {
+          style: {
+            color: ink,
+            fontFamily: typography.fontFamily,
+            fontSize: typography.sizes.sm,
+            fontWeight: "600",
+            textDecorationLine: "underline",
+          },
+        },
+        action.label,
+      ),
+    );
+  }
+
+  function BannerDismiss({ onDismiss, label, ink, testID }) {
+    return h(
+      Pressable,
+      {
+        onPress: onDismiss,
+        accessibilityRole: "button",
+        accessibilityLabel: label,
+        hitSlop: CONTROL_HIT_SLOP,
+        testID,
+        style: ({ pressed }) => [
+          {
+            minWidth: CONTROL_MIN_SIZE,
+            minHeight: CONTROL_MIN_SIZE,
+            alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+          },
+          pressed ? { opacity: 0.6 } : null,
+        ],
+      },
+      h(Icon, { name: "x", size: DISMISS_ICON_SIZE, color: ink }),
+    );
+  }
+
+  function Banner({
+    tone,
+    title,
+    message,
+    icon,
+    action,
+    onDismiss,
+    dismissAccessibilityLabel = "Dismiss",
+    theme: explicitTheme,
+    style,
+    testID,
+  }) {
+    const hostTheme = useHostTheme();
+    // A Studio preview renders outside a widget context, so it passes its own.
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const t = resolveBannerTokens(theme, tone);
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const glyph = icon === false || icon === null ? null : icon || t.icon;
+    const hasAction =
+      action && isShown(action.label) && typeof action.onPress === "function";
+    const hasDismiss = typeof onDismiss === "function";
+    // Text sits level with a control when the row has one.
+    const lineMinHeight = hasAction || hasDismiss ? CONTROL_MIN_SIZE : LINE_MIN_HEIGHT;
+    const text = {
+      color: t.textColor,
+      fontFamily: typography.fontFamily,
+      fontSize: typography.sizes.sm,
+    };
+    // Text is wrapped and themed; an element the caller built renders as given.
+    const slot = (value, style) => {
+      if (!isShown(value)) return null;
+      return isText(value) ? h(Text, { style }, value) : value;
+    };
+
+    return h(
+      View,
+      {
+        ...announcement(t.tone),
+        testID,
+        style: [
+          {
+            flexDirection: "row",
+            alignItems: "flex-start",
+            gap: spacing.sm,
+            paddingVertical: spacing.sm,
+            paddingHorizontal: spacing.md,
+            borderRadius: t.radius,
+            borderWidth: t.borderWidth,
+            borderColor: t.borderColor,
+            backgroundColor: t.background,
+          },
+          style,
+        ],
+      },
+      glyph
+        ? h(
+            View,
+            { style: { minHeight: lineMinHeight, justifyContent: "center" } },
+            h(Icon, { name: glyph, size: ICON_SIZE, color: t.textColor }),
+          )
+        : null,
+      h(
+        View,
+        // minWidth 0 lets a long message wrap instead of pushing the row wide.
+        { style: { flex: 1, minWidth: 0, minHeight: lineMinHeight, justifyContent: "center", gap: 2 } },
+        slot(title, { ...text, fontWeight: "600" }),
+        slot(message, text),
+      ),
+      hasAction
+        ? h(BannerAction, {
+            action,
+            ink: t.textColor,
+            typography,
+            fallbackTestID: testID ? `${testID}-action` : undefined,
+          })
+        : null,
+      hasDismiss
+        ? h(BannerDismiss, {
+            onDismiss,
+            label: dismissAccessibilityLabel,
+            ink: t.textColor,
+            testID: testID ? `${testID}-dismiss` : undefined,
+          })
+        : null,
+    );
+  }
+
+  Banner.displayName = "Banner";
+  return Banner;
+}

package/dist/banner.js

@@ -0,0 +1,7 @@
+// `<Banner>` (web). Binds ./banner-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeBanner } from "./banner-view.js";
+
+export const Banner = makeBanner(ReactNative);

package/dist/banner.native.js

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

package/dist/contract.cjs

@@ -704,6 +704,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Inline messages: `<Banner>` reads this scope directly, so it names the
+  // SDK component it styles and binds no widget field.
+  alert: Object.freeze({
+    label: "Alerts",
+    sdkComponents: Object.freeze(["Banner"]),
+    tokens: Object.freeze({
+      radius: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "radii.md" }),
+      borderWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+      infoBackground: Object.freeze({ type: "color" }),
+      infoTextColor: Object.freeze({ type: "color" }),
+      successBackground: Object.freeze({ type: "color" }),
+      successTextColor: Object.freeze({ type: "color" }),
+      warningBackground: Object.freeze({ type: "color" }),
+      warningTextColor: Object.freeze({ type: "color" }),
+      errorBackground: Object.freeze({ type: "color" }),
+      errorTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2064,6 +2083,62 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11025 / REQ-USERMGMT-12 — online status for people who share a record.
+  {
+    name: "useOnlineMembers",
+    signature: "useOnlineMembers(tableId, recordIds)",
+    description:
+      "Who is online among the members of each record the viewer is a " +
+      "member of (a conversation, a team, a case), on a table that shows its " +
+      "members' online status (a template table's `presence: true`, or the " +
+      "table setting in the Studio). Members hold their OWN read grant on the " +
+      "record, given to them by a person (a grant from a template or one " +
+      "inherited from a parent row names no member). `online` is a Set of " +
+      "the user ids online across the records; `byRecord[recordId]` is " +
+      "{ online_user_ids, online_count } — the ids are capped at 100 per " +
+      "record, so count with `online_count`. A record the viewer only reads " +
+      "(through a group or a grant to everyone) or cannot read answers with " +
+      "nobody. Refreshes every minute while the app is in front, on return " +
+      "to it and on pull-to-refresh. `supported` is true only once the " +
+      "workspace answered: it is false while the workspace does not record " +
+      "user activity, when the table has not opted in, when the viewer hides " +
+      "their own status (useOnlineVisibility), and in a preview — then show " +
+      "NO online state at all, never \"offline\". The viewer's own id may be " +
+      "in `online`; leave it out when you mean \"someone else is here\". " +
+      "Never timestamps. Declare `directory.read:users`: the publish checks " +
+      "do not require it for this hook, but it is the scope the hook belongs to.",
+    returnShape: {
+      supported: "boolean  // false: render no online dots, no counts, no 'offline' state",
+      online: "Set<string>  // user ids online across the records",
+      byRecord: "{ [recordId]: { online_user_ids: string[], online_count: number } }",
+      loading: "boolean",
+      error: "DirectoryError | null  // reason ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN (not a live person) when refused",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: ["directory.read:users"],
+  },
+  {
+    name: "useOnlineVisibility",
+    signature: "useOnlineVisibility()",
+    description:
+      "The viewer's own \"Show when I'm online\" switch, on by default. " +
+      "`supported` is false where the workspace shows nobody online: offer " +
+      "the switch only when it is true. `setShowOnline(false)` hides the " +
+      "viewer from everyone, and they then see nobody online either; every " +
+      "useOnlineMembers on the page re-reads. No scope: it is the viewer's " +
+      "own setting.",
+    returnShape: {
+      supported: "boolean",
+      showOnline: "boolean | null  // null until known",
+      loading: "boolean",
+      saving: "boolean",
+      error: "DirectoryError | null",
+      setShowOnline: "(showOnline: boolean) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: null,
+  },
   // 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
@@ -2906,6 +2981,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Banner",
+    description:
+      'Themed inline message. `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />`. THE way to show an error, warning, success or notice that belongs to a place in the widget and stays until it is resolved: a list that failed to load, a form the user cannot submit yet, a "read-only" or "offline" notice. Render it where the problem is — above the list or form it concerns. Use `useToast()` instead for a brief confirmation of something the user just did ("Saved", "Deleted") that needs no decision and may disappear on its own; never both for one event. Its fill, text colour, border and corner radius come from the app\'s theme per tone (Design > Components > Alerts), so never hand-roll a tinted box from `View` + a border + a hex. Props: `tone` ("info" default | "success" | "warning" | "error"), `title` (optional, one short line) and `message` (wraps — never truncate it): text, or an element you built when part of it needs its own styling, `icon` (a lucide name replacing the tone\'s own glyph, or `false` for none), `action` (`{ label, onPress, accessibilityLabel?, testID? }`, ONE action such as Retry), `onDismiss` (pass it to show a close control; you hide the banner in the handler), `dismissAccessibilityLabel` (default "Dismiss" — pass a translated one), `style` (spacing around it), `testID`. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Accordion",
     description:
@@ -3218,7 +3300,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation).",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table.",
   },
   translations: {
     type: "object",
@@ -3369,10 +3451,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
-      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() }, " +
+      "presence: { online(tableId, recordIds) -> { data: [{ record_id, online_user_ids, online_count }] }, me() -> { show_online }, setShowOnline(bool) -> { show_online } } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope); presence backs useOnlineMembers() + useOnlineVisibility() (session-gated, no scope header). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
-    fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
+    fields: { users: "object", groups: "object", invites: "object", bankid: "object", presence: "object" },
   },
   assets: {
     description:
@@ -5464,7 +5547,14 @@ const CONTRACT = deepFreeze({
   //    and `useInactiveUsers` read user activity through the new
   //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
   //    new `users.activity:*` scope.
-  version: "1.164.0",
+  // 1.165.0: additive (sc-11025) — `useOnlineMembers(tableId, recordIds)`
+  //    and `useOnlineVisibility()` read who of a record's members is online
+  //    and the viewer's own switch, through the new `ctx.directory.presence`.
+  //    A `datastoreTemplate` table may declare `presence: true`.
+  // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
+  //    error, warning, success or notice) and the `alert` component scope it
+  //    reads.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,