@colixsystems/widget-sdk 0.256.0 → 0.259.0

package/README.md

@@ -85,7 +85,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.256.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.259.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.259.0 (contract 1.210.0)
+
+**`<Avatar url>` falls back to the initials** when its picture fails to load, instead of showing a broken image (as `<Avatar fileId>` already did). The built-in form fields for users, groups and related records now use `<PeoplePicker>`, and the User widget's photo uses `<Avatar>`.
+
+### What's new in 0.258.0 (contract 1.209.0)
+
+**`<PeoplePicker>` options for admin flows.** `activeOnly` keeps deactivated people out of a users picker; `loadErrorText` may be a function of the error, so a picker can say why a read was refused; each option carries `<testID>-option-<id>`. The built-in User Management now uses `<PeoplePicker>` for adding members and choosing invite groups, a `<Menu>` for row actions, and `<ConfirmDialog>` before removing a user or deleting a group.
 
 ### What's new in 0.256.0 (contract 1.207.0)
 
@@ -215,7 +223,7 @@ const { groups, loading } = useDatastoreAggregate(tableId, { groupBy: "city", su
   data={groups.map((g) => ({ label: String(g.group), value: Number(g.sum) || 0 }))} />
 ```
 
-**Searchable pickers: `<Select searchable>` and `<PeoplePicker>`.** A long `Select` can be searched: pass `searchable` to filter the options you hold, `onSearch` to fetch each query yourself (called with "" when the sheet opens and again once typing pauses), or an async `options` function and Select fetches, keeping only the latest answer. `<PeoplePicker source="users" | "groups" | "records">` does this for the workspace's people, groups or a table's records with avatar rows, server-side search and `excludeIds`, and names a saved choice that is not on the first page instead of showing its id (a malformed saved id reads "Unknown" without failing the rest). `useGroups({ ids })` names groups by id.
+**Searchable pickers: `<Select searchable>` and `<PeoplePicker>`.** A long `Select` can be searched: pass `searchable` to filter the options you hold, `onSearch` to fetch each query yourself (called with "" when the sheet opens and again once typing pauses), or an async `options` function and Select fetches, keeping only the latest answer. `<PeoplePicker source="users" | "groups" | "records">` does this for the workspace's people, groups or a table's records with avatar rows, server-side search, `excludeIds` and (for users) `activeOnly`, and names a saved choice that is not on the first page instead of showing its id (a malformed saved id reads "Unknown" without failing the rest). `useGroups({ ids })` names groups by id.
 
 ```jsx
 <PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />

package/dist/contract.cjs

@@ -3577,7 +3577,7 @@ const PRIMITIVES = [
   {
     name: "PeoplePicker",
     description:
-      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
+      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `activeOnly` leaves deactivated users out, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. `loadErrorText` may be a function of the failed search\'s error (`error.code === "FORBIDDEN"` for a refused read). Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6374,7 +6374,12 @@ const CONTRACT = deepFreeze({
   //    without it read light / false.
   // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
   //    "left" | "center" | "right" again; "center" centres the tabs.
-  version: "1.207.0",
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  // 1.210.0: behaviour (sc-12245) — `<Avatar url>` falls back to the
+  //    initials when its picture fails to load. No API change.
+  version: "1.210.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3577,7 +3577,7 @@ const PRIMITIVES = [
   {
     name: "PeoplePicker",
     description:
-      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
+      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `activeOnly` leaves deactivated users out, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. `loadErrorText` may be a function of the failed search\'s error (`error.code === "FORBIDDEN"` for a refused read). Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6370,7 +6370,12 @@ const CONTRACT = deepFreeze({
   //    without it read light / false.
   // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
   //    "left" | "center" | "right" again; "center" centres the tabs.
-  version: "1.207.0",
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  // 1.210.0: behaviour (sc-12245) — `<Avatar url>` falls back to the
+  //    initials when its picture fails to load. No API change.
+  version: "1.210.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/detail-parts-view.js

@@ -111,6 +111,13 @@ export function makeDetailParts(rn) {
     );
   }
 
+  // A photo that cannot load gives way to the initials.
+  function UrlAvatar({ photo, monogram }) {
+    const [failed, setFailed] = React.useState(false);
+    if (failed) return monogram;
+    return h(Image, { ...photo, onError: () => setFailed(true) });
+  }
+
   function Avatar({ name, url, fileId, seed, size = "md", shape = "circle", accessibilityLabel, style, testID }) {
     const { colors, radii, typography } = useDetailTheme();
     const px = avatarPixelSize(size);
@@ -127,15 +134,6 @@ export function makeDetailParts(rn) {
     const stored = typeof fileId === "string" && fileId !== "";
     const source = typeof url === "string" ? url.trim() : "";
     const label = accessibilityLabel || captionText(name) || "Avatar";
-    if (source && !stored) {
-      return h(Image, {
-        source: { uri: source },
-        accessibilityLabel: label,
-        resizeMode: "cover",
-        style: [box, style],
-        testID,
-      });
-    }
     const initials = initialsFor(name);
     const fallback = { alignItems: "center", justifyContent: "center" };
     const content = initials
@@ -152,11 +150,16 @@ export function makeDetailParts(rn) {
           initials,
         )
       : h(Icon, { name: "user", size: Math.round(px * 0.55), color: ink });
+    const monogram = h(View, { style: [box, fallback, style], accessibilityLabel: label, testID }, content);
+    if (source && !stored) {
+      const photo = { source: { uri: source }, accessibilityLabel: label, resizeMode: "cover", style: [box, style], testID };
+      return h(UrlAvatar, { key: source, photo, monogram });
+    }
     if (stored) {
       const frame = { style: [box, fallback, { overflow: "hidden" }, style], accessibilityLabel: label, testID };
       return h(FileAvatar, { key: fileId, fileId, px, frame, monogram: content });
     }
-    return h(View, { style: [box, fallback, style], accessibilityLabel: label, testID }, content);
+    return monogram;
   }
   Avatar.displayName = "Avatar";
 

package/dist/index.d.ts

@@ -4151,7 +4151,7 @@ export const Avatar: (props: {
   name?: string;
   /** A stable id (a user id): tints the monogram with that person's colour. */
   seed?: string;
-  /** An absolute image URL. */
+  /** An absolute image URL; the initials show if it cannot load. */
   url?: string;
   /**
    * A filestore file id (a FILE column's value). Takes precedence over `url`;
@@ -4613,7 +4613,8 @@ export type PeoplePickerSource = "users" | "groups" | "records";
  * Nothing loads until the sheet opens; each pause in typing searches on the
  * server. A saved value the page does not hold is looked up once by id, so the
  * trigger shows its name, `loadingText` meanwhile, or `unknownText` when it is
- * gone, never the id. Every other `<Select>` prop works.
+ * gone, never the id. Every other `<Select>` prop works; with a `testID`
+ * each option takes `<testID>-option-<id>`.
  *
  * @example
  *   <PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />
@@ -4622,7 +4623,7 @@ export type PeoplePickerSource = "users" | "groups" | "records";
  *     onValueChange={setCustomerId} />
  */
 export const PeoplePicker: (
-  props: Omit<SelectBaseProps<string>, "options" | "onSearch" | "selectedOptions" | "searchable"> & {
+  props: Omit<SelectBaseProps<string>, "options" | "onSearch" | "selectedOptions" | "searchable" | "loadErrorText"> & {
     /** Default "users". */
     source?: PeoplePickerSource;
     /** `source="records"`: the table id. */
@@ -4633,6 +4634,10 @@ export const PeoplePicker: (
     avatarColumn?: string;
     /** `source="users"`: only members of this group (a `useGroups()` row id). */
     groupId?: string;
+    /** `source="users"`: leave deactivated users out. */
+    activeOnly?: boolean;
+    /** Shown when a search fails; a function names the failure, e.g. a refused read. */
+    loadErrorText?: string | ((error: { code?: string; message?: string }) => string);
     /** `source="records"`: narrows the rows, as `useDatastoreQuery`'s `filter`. */
     filter?: Query["filter"];
     /** Ids never offered (already members, the signed-in user). */

package/dist/markdown.js

@@ -29,6 +29,9 @@ const ORDERED_RE = /^\s*(\d+)[.)]\s+(.*)$/;
 const TABLE_ROW_RE = /^\s*\|(.*)\|\s*$/;
 const TABLE_DIVIDER_RE = /^\s*\|(?:\s*:?-+:?\s*\|)+\s*$/;
 
+const FENCE_OPEN_RE = /^\s*```+\s*([^`]*)$/;
+const FENCE_CLOSE_RE = /^\s*```+\s*$/;
+
 // An image is its own block, written on one line with the size in the title
 // slot. Keeping blocks in the SAME markdown column as the prose is what lets
 // content written before images existed keep rendering with no migration.
@@ -322,6 +325,60 @@ export function formatMarkdownTable(columns = 3, rows = 2) {
   return out.join("\n");
 }
 
+// Any `[label](target)` as written, a label wrapped over lines included.
+const RAW_LINK_RE = /(!?)\[((?:[^\]\\]|\\.)*)\]\(\s*(\S+?)\s*\)/g;
+
+function collectHrefs(spans, into) {
+  for (const span of spans || []) if (span.href) into.add(span.href);
+}
+
+/**
+ * sc-12618 — `text` with each link to a target `keepLink` refuses turned back
+ * into its label, everything else byte for byte.
+ *
+ * `keepLink` is asked only about the targets `<RichText>` draws as links. A
+ * refused target is then unlinked wherever it is written outside a fenced
+ * block, so no reading of the text (a label wrapped over two lines, a link
+ * only a table cell or a joined paragraph exposes) leaves one live. An
+ * occurrence the renderer would not have drawn loses only its brackets.
+ */
+export function unlinkMarkdownLinks(text, keepLink) {
+  if (typeof text !== "string" || !text.includes("](")) return text;
+  const hrefs = new Set();
+  for (const block of parseMarkdown(text, { stripLegacyHtml: false })) {
+    collectHrefs(block.spans, hrefs);
+    for (const row of block.rows || []) for (const cell of row.cells) collectHrefs(cell, hrefs);
+  }
+  const refused = new Set([...hrefs].filter((href) => !keepLink(href)));
+  if (refused.size === 0) return text;
+
+  const unlink = (chunk) =>
+    chunk.replace(RAW_LINK_RE, (whole, bang, label, target) =>
+      bang || !refused.has(target) ? whole : label,
+    );
+  const out = [];
+  let prose = [];
+  let inFence = false;
+  const flushProse = () => {
+    if (prose.length > 0) out.push(unlink(prose.join("\n")));
+    prose = [];
+  };
+  for (const line of text.split("\n")) {
+    if (inFence) {
+      out.push(line);
+      if (FENCE_CLOSE_RE.test(line)) inFence = false;
+    } else if (FENCE_OPEN_RE.test(line.trimEnd())) {
+      flushProse();
+      out.push(line);
+      inFence = true;
+    } else {
+      prose.push(line);
+    }
+  }
+  flushProse();
+  return out.join("\n");
+}
+
 /**
  * Parses markdown text into renderable blocks:
  * `{ type: "heading"|"paragraph"|"bullet"|"ordered", level?, marker?, spans }`,
@@ -360,12 +417,12 @@ export function parseMarkdown(text, options) {
 
     // A fenced block is verbatim: its newlines and indentation ARE the content,
     // and joining them into a paragraph made a code sample unreadable.
-    const fence = /^\s*```+\s*([^`]*)$/.exec(line);
+    const fence = FENCE_OPEN_RE.exec(line);
     if (fence) {
       flushParagraph();
       const body = [];
       let j = i + 1;
-      while (j < lines.length && !/^\s*```+\s*$/.test(lines[j])) {
+      while (j < lines.length && !FENCE_CLOSE_RE.test(lines[j])) {
         body.push(lines[j]);
         j += 1;
       }

package/dist/people-picker-logic.js

@@ -27,14 +27,16 @@ function text(value) {
  * server, never filtered from one page here.
  *
  * @param {"users"|"groups"|"records"} source
- * @param {{query?: string, pageSize?: number, groupId?: string, filter?: object}} own
+ * @param {{query?: string, pageSize?: number, groupId?: string, filter?: object,
+ *   activeOnly?: boolean}} own
  */
-export function pageQuery(source, { query, pageSize, groupId, filter } = {}) {
+export function pageQuery(source, { query, pageSize, groupId, filter, activeOnly } = {}) {
   const q = text(query);
   const limit =
     Number.isInteger(pageSize) && pageSize > 0 ? Math.min(pageSize, 200) : DEFAULT_PEOPLE_PAGE_SIZE;
   const out = { ...(q ? { q } : null), limit };
   if (source === "users" && isId(groupId)) out.group_id = groupId;
+  if (source === "users" && activeOnly === true) out.is_active = true;
   if (source === "records" && filter && typeof filter === "object") out.filter = filter;
   return out;
 }
@@ -86,6 +88,19 @@ export function rowLabel(row, { source, labelColumn, unknownText }) {
   return text(row.name) || unknownText;
 }
 
+/**
+ * What `<Select>` is told when a page fails: a `loadErrorText` function
+ * names that failure, a string replaces the default, anything else keeps it.
+ *
+ * @param {string|((error: object) => string)|undefined} loadErrorText
+ * @param {object|null} error
+ */
+export function pageErrorText(loadErrorText, error) {
+  if (!error) return false;
+  if (typeof loadErrorText === "function") return text(loadErrorText(error)) || true;
+  return typeof loadErrorText === "string" && loadErrorText ? loadErrorText : true;
+}
+
 /** The rows a page offers: each with an id, none of `excludeIds`. */
 export function offeredRows(rows, excludeIds) {
   const excluded = new Set(Array.isArray(excludeIds) ? excludeIds.map(String) : []);

package/dist/people-picker-view.js

@@ -20,6 +20,7 @@ import {
   answersQuery,
   lookupableIds,
   offeredRows,
+  pageErrorText,
   pageQuery,
   pickedIds,
   pickedLabels,
@@ -148,12 +149,14 @@ export function makePeoplePicker(rn) {
       labelColumn,
       avatarColumn,
       groupId,
+      activeOnly,
       filter,
       excludeIds,
       pageSize,
       showAvatars = true,
       unknownText = "Unknown",
       loadingText = "Loading…",
+      loadErrorText,
       multiple = false,
       value,
       values,
@@ -173,6 +176,7 @@ export function makePeoplePicker(rn) {
       return {
         value: row.id,
         label,
+        testID: rest.testID ? `${rest.testID}-option-${row.id}` : undefined,
         ...(showAvatars ? { leading: decoration(avatarFor(source, row, label, avatarColumn)) } : null),
       };
     };
@@ -193,7 +197,7 @@ export function makePeoplePicker(rn) {
     const missing = readable ? unresolvedIds(ids, knownRows, attempted) : [];
     const { lookup, unknown } = lookupableIds(missing, source);
     const named = unknown.length ? new Set([...attempted, ...unknown.map(String)]) : attempted;
-    const query = sent === null || !readable ? null : pageQuery(source, { query: sent, pageSize, groupId, filter });
+    const query = sent === null || !readable ? null : pageQuery(source, { query: sent, pageSize, groupId, filter, activeOnly });
     const options = offeredRows(page.rows, excludeIds).map(toOption);
     const selectedOptions = pickedLabels(ids, { knownRows, attempted: named, nameOf, loadingText, unknownText }).map(
       (own) => (own.row ? toOption(own.row) : own),
@@ -221,7 +225,7 @@ export function makePeoplePicker(rn) {
         selectedOptions,
         onSearch: setSent,
         loading: sent !== null && (page.query !== sent || page.loading),
-        optionsError: !!page.error,
+        optionsError: pageErrorText(loadErrorText, page.error),
         loadingText,
       }),
       query ? h(pages[source], { table, query, sent, onReport }) : null,

package/package.json

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

@@ -3577,7 +3577,7 @@ const PRIMITIVES = [
   {
     name: "PeoplePicker",
     description:
-      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
+      'Searchable picker of people, groups or records. `<PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />` — use it by default whenever the user picks a workspace user (an assignee, a reviewer, a recipient), a group (`source="groups"`), or a related record of a table they should search (`source="records" table={tableId}`, named by the table\'s identification column or `labelColumn`). It is a searchable `<Select>`: the same field, sheet, `label` / `helper` / `error` / `disabled`, and `multiple` with `values` / `onValuesChange`. Nothing loads until the sheet opens, each pause in typing searches on the server (never one page filtered in the widget), each user or group row leads with an `<Avatar>` (`avatarColumn` names a record\'s photo column; `showAvatars={false}` hides them), `excludeIds` leaves ids out (the current members), `groupId` limits users to one group, `activeOnly` leaves deactivated users out, `filter` narrows records, and `pageSize` (default 50) sets the page. A saved value outside the first page is looked up once by id, so the trigger shows its name — `loadingText` meanwhile, `unknownText` (default "Unknown") when it is gone — never the raw id. `loadErrorText` may be a function of the failed search\'s error (`error.code === "FORBIDDEN"` for a refused read). Values are the row ids, exactly what a USER, USER_GROUP or RELATION column stores. Scopes: `directory.read:users` for users, `groups.read:*` for groups, the table\'s `datastore.read` scope for records. When the request needs what it cannot do — a people list that stays on screen with an action per row, a picker of users with presence dots or a role column — build your own with `useDirectory` / `useGroups` and the app\'s look.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6370,7 +6370,12 @@ const CONTRACT = deepFreeze({
   //    without it read light / false.
   // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
   //    "left" | "center" | "right" again; "center" centres the tabs.
-  version: "1.207.0",
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  // 1.210.0: behaviour (sc-12245) — `<Avatar url>` falls back to the
+  //    initials when its picture fails to load. No API change.
+  version: "1.210.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,