@colixsystems/widget-sdk 0.255.0 → 0.258.0

package/README.md

@@ -85,7 +85,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.255.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.258.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.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)
+
+**A page's top navigation bar can centre its tabs again.** `resolveTopBarTokens().tabAlignment` is `"left"` | `"center"` | `"right"`. A `theme_config.topBar.tabAlignment` of `"center"` places the tabs between two flexible spacers, never by centring the row, so a row with more tabs than fit still scrolls from its first tab. Unset or unknown still resolves to `"left"`, so an app that never chose is unchanged. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed.
 
 ### What's new in 0.255.0
 
@@ -211,7 +219,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,
   },
@@ -6372,7 +6372,12 @@ const CONTRACT = deepFreeze({
   //    showing, the app's appearance preference, `canSwitch` and
   //    `setPreference`, backed by the optional `appearance` host slice. Hosts
   //    without it read light / false.
-  version: "1.206.0",
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  version: "1.209.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,
   },
@@ -6368,7 +6368,12 @@ const CONTRACT = deepFreeze({
   //    showing, the app's appearance preference, `canSwitch` and
   //    `setPreference`, backed by the optional `appearance` host slice. Hosts
   //    without it read light / false.
-  version: "1.206.0",
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  version: "1.209.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -409,7 +409,7 @@ export interface TopBarTokens {
    *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
   /** Where the row's tabs sit across its width; `left` unless authored. */
-  tabAlignment: "left" | "right";
+  tabAlignment: "left" | "center" | "right";
   /** The column the tabs sit in: the whole bar, or the page content's. The
    *  bar's surface spans the full width either way. */
   tabRowWidth: "full" | "content";

package/dist/index.d.ts

@@ -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/navigation.cjs

@@ -566,11 +566,8 @@ function resolveTopStripeLayout(theme) {
     // reading the bar; so does the SITE header, which is shown instead of this
     // row rather than beside it.
     //
-    // The notification bell is the one member of `slots` this does not reach.
-    // It keeps its own resting colour on both hosts — web reads the authored
-    // `topBar.textColor` and the export tints it not at all — and moving it
-    // here would widen that difference rather than close it. Whoever closes it
-    // should move both hosts at once.
+    // The notification bell is one of the row's icons and takes this tint on
+    // both hosts; the bells outside the row keep the bar's.
     tintColor: hexOr(stripe.textColor, barTokens.tintColor),
     titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
@@ -617,7 +614,7 @@ function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
   return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
 }
 
-const TAB_ALIGNMENTS = ["left", "right"];
+const TAB_ALIGNMENTS = ["left", "center", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 function resolveTopBarTokens(theme) {

package/dist/navigation.js

@@ -557,11 +557,8 @@ export function resolveTopStripeLayout(theme) {
     // reading the bar; so does the SITE header, which is shown instead of this
     // row rather than beside it.
     //
-    // The notification bell is the one member of `slots` this does not reach.
-    // It keeps its own resting colour on both hosts — web reads the authored
-    // `topBar.textColor` and the export tints it not at all — and moving it
-    // here would widen that difference rather than close it. Whoever closes it
-    // should move both hosts at once.
+    // The notification bell is one of the row's icons and takes this tint on
+    // both hosts; the bells outside the row keep the bar's.
     tintColor: hexOr(stripe.textColor, barTokens.tintColor),
     titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
@@ -608,7 +605,7 @@ export function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
   return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
 }
 
-const TAB_ALIGNMENTS = ["left", "right"];
+const TAB_ALIGNMENTS = ["left", "center", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 export function resolveTopBarTokens(theme) {

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.255.0",
+  "version": "0.258.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,
   },
@@ -6368,7 +6368,12 @@ const CONTRACT = deepFreeze({
   //    showing, the app's appearance preference, `canSwitch` and
   //    `setPreference`, backed by the optional `appearance` host slice. Hosts
   //    without it read light / false.
-  version: "1.206.0",
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  // 1.209.0: additive (sc-12242) — `<PeoplePicker>` takes `activeOnly`
+  //    (users), a function `loadErrorText(error)`, and gives each option a
+  //    `<testID>-option-<id>`.
+  version: "1.209.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,