@colixsystems/widget-sdk 0.246.0 → 0.247.0

package/dist/chart-tokens.js

@@ -0,0 +1,131 @@
+// The colours and corners `<Chart>` paints with, resolved from the theme's
+// `chart` scope and falling back to the theme's own colours. Platform-free,
+// so both hosts draw one chart from the same values.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT, isHexColor, mixHex } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+export const CHART_SERIES_TOKENS = Object.freeze(["series1", "series2", "series3", "series4", "series5", "series6"]);
+
+// Distinct hues first, so two series rarely share a family.
+const PALETTE_ROLES = Object.freeze(["primary", "warning", "secondary", "danger", "info", "success"]);
+// How far a seventh-and-later series is lightened toward the surface.
+const REPEAT_TINT = 0.45;
+
+function themeColors(theme) {
+  return { ...DEFAULT_THEME_TOKENS.colors, ...((theme && theme.colors) || {}) };
+}
+
+/** The six series colours an unthemed chart uses: the theme's own, deduplicated. */
+function defaultPalette(colors) {
+  const seen = new Set();
+  const palette = [];
+  for (const role of PALETTE_ROLES) {
+    const colour = colors[role];
+    const key = typeof colour === "string" ? colour.toLowerCase() : "";
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    palette.push(colour);
+  }
+  for (let i = 0; palette.length < CHART_SERIES_TOKENS.length; i += 1) {
+    palette.push(mixHex(colors.primary, i % 2 ? colors.surface : colors.onSurface, 0.3 + 0.15 * Math.floor(i / 2)));
+  }
+  return palette;
+}
+
+/**
+ * Resolve one chart's look: the `chart` scope first, then the theme.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @returns {{ palette: string[], axisColor: string, gridColor: string, barRadius: number, surface: string, fontFamily: string, fontSize: number }}
+ */
+export function resolveChartTokens(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = themeColors(base);
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const typography = base.typography || DEFAULT_THEME_TOKENS.typography;
+  const sizes = typography.sizes || DEFAULT_THEME_TOKENS.typography.sizes;
+  const scope = normaliseThemeComponents(base.components).chart || {};
+  const fallback = defaultPalette(colors);
+  return {
+    palette: CHART_SERIES_TOKENS.map((token, i) => scope[token] ?? fallback[i]),
+    axisColor: scope.axisColor ?? colors.onSurfaceMuted,
+    gridColor: scope.gridColor ?? colors.border,
+    barRadius: scope.barRadius ?? radii.sm,
+    surface: colors.surface,
+    fontFamily: typography.fontFamily || DEFAULT_THEME_TOKENS.typography.fontFamily,
+    fontSize: sizes.xs || DEFAULT_THEME_TOKENS.typography.sizes.xs,
+  };
+}
+
+const RGB = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*[\d.]+%?\s*)?\)$/i;
+
+// A `#rrggbb` for a hex or rgb() colour, so it can be mixed; else null.
+function mixable(colour) {
+  if (isHexColor(colour)) return colour;
+  const rgb = typeof colour === "string" ? RGB.exec(colour.trim()) : null;
+  if (!rgb) return null;
+  return `#${rgb.slice(1, 4).map((n) => Math.min(255, Number(n)).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/**
+ * How series (or donut slice) `index` is painted: its palette colour, a
+ * seventh and later one lighter. A colour that cannot be mixed (a named or
+ * hsl() colour) repeats at a lower opacity instead.
+ *
+ * @returns {{ color: string, opacity: number }}
+ */
+export function chartSeriesPaint(tokens, index) {
+  const palette = tokens.palette;
+  const colour = palette[index % palette.length];
+  const round = Math.floor(index / palette.length);
+  if (round === 0) return { color: colour, opacity: 1 };
+  const tint = Math.min(0.8, REPEAT_TINT * round);
+  const hex = mixable(colour);
+  return hex ? { color: mixHex(hex, tokens.surface, tint), opacity: 1 } : { color: colour, opacity: 1 - tint };
+}
+
+/** The colour of series (or donut slice) `index`; see `chartSeriesPaint`. */
+export function chartSeriesColor(tokens, index) {
+  return chartSeriesPaint(tokens, index).color;
+}
+
+/**
+ * The colours `<Chart>` paints with, for a chart a widget draws itself (a
+ * scatter plot, a timeline): `series(i)` and `seriesOpacity(i)` for the i-th
+ * series' marks, `axis` for labels and the axis line, `grid` for gridlines.
+ * Pass it `useTheme()`, so a hand-drawn chart follows Design > Components >
+ * Charts exactly as `<Chart>` does.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function chartColors(theme) {
+  const tokens = resolveChartTokens(theme);
+  return {
+    palette: tokens.palette.slice(),
+    axis: tokens.axisColor,
+    grid: tokens.gridColor,
+    series: (index) => chartSeriesPaint(tokens, index).color,
+    seriesOpacity: (index) => chartSeriesPaint(tokens, index).opacity,
+  };
+}
+
+/**
+ * What each `chart` token resolves to while unset, keyed by token name, so
+ * the Studio previews the colour each control would replace.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ */
+export function chartScopeDefaults(theme) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const components = { ...(base.components || {}) };
+  delete components.chart;
+  const unset = resolveChartTokens({ ...base, components });
+  const out = {};
+  for (const token of Object.keys(CONTRACT.themeComponents.chart.tokens)) {
+    const series = CHART_SERIES_TOKENS.indexOf(token);
+    out[token] = series === -1 ? unset[token] : unset.palette[series];
+  }
+  return out;
+}

package/dist/chart-view.js

@@ -0,0 +1,262 @@
+// The ONE implementation behind the `<Chart>` SDK primitive. The platform
+// bindings (`chart.js` / `chart.native.js`) differ only in where the
+// primitives and the SVG elements come from, so the hosts cannot drift.
+//
+// Every dashboard widget drew its own chart, each with its own colours, axes
+// and empty state. This one reads the theme's `chart` scope.
+
+import React from "react";
+import { useHostLocale, useHostTheme, useHostSharedText } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { textRoleStyle } from "./text-roles.js";
+import { resolveChartTokens, chartSeriesPaint } from "./chart-tokens.js";
+import {
+  normaliseChartType,
+  chartHeight,
+  normaliseChartData,
+  isChartEmpty,
+  cartesianLayout,
+  donutLayout,
+  barPath,
+  chartSummary,
+  formatChartValue,
+} from "./chart-logic.js";
+
+const h = React.createElement;
+const NO_RESULTS_FALLBACK = CONTRACT.sharedTranslationKeys.no_results.en;
+const AREA_OPACITY = 0.18;
+const LINE_WIDTH = 2;
+const DOT_RADIUS = 3;
+const SWATCH_SIZE = 10;
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+
+/**
+ * Bind the shared chart to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Svg: any, G: any, Path: any, Line: any, Circle: any, SvgText: any, Skeleton: any, EmptyState: any}} rn
+ */
+export function makeChart(rn) {
+  const { View, Text, Svg, G, Path, Line, Circle, SvgText, Skeleton, EmptyState } = rn;
+
+  function Legend({ items, theme, testID }) {
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const colors = theme.colors || DEFAULT_THEME_TOKENS.colors;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const label = textRoleStyle("caption", typography, colors);
+    return h(
+      View,
+      {
+        style: { flexDirection: "row", flexWrap: "wrap", columnGap: spacing.md, rowGap: spacing.xs, marginTop: spacing.sm },
+        testID: testID ? `${testID}-legend` : undefined,
+      },
+      items.map((item) =>
+        h(
+          View,
+          { key: item.key, style: { flexDirection: "row", alignItems: "center", gap: spacing.xs, minWidth: 0 } },
+          h(View, {
+            style: {
+              width: SWATCH_SIZE,
+              height: SWATCH_SIZE,
+              borderRadius: SWATCH_SIZE / 2,
+              backgroundColor: item.paint.color,
+              opacity: item.paint.opacity,
+            },
+          }),
+          h(Text, { style: label, numberOfLines: 1 }, item.text),
+        ),
+      ),
+    );
+  }
+
+  function axisText(label, i, tokens, prefix) {
+    return h(
+      SvgText,
+      {
+        key: `${prefix}-${i}`,
+        x: label.x,
+        y: label.y,
+        fill: tokens.axisColor,
+        fontSize: tokens.fontSize,
+        fontFamily: tokens.fontFamily,
+        textAnchor: label.anchor,
+      },
+      label.text,
+    );
+  }
+
+  function CartesianMarks({ kind, width, height, model, tokens, valueFormat, locale, paintOf }) {
+    const layout = cartesianLayout({ type: kind, width, height, model, fontSize: tokens.fontSize, valueFormat, locale });
+    const grid = layout.gridLines.map((line, i) =>
+      line.y === undefined
+        ? h(Line, { key: `grid-${i}`, x1: line.x, x2: line.x, y1: line.y1, y2: line.y2, stroke: tokens.gridColor, strokeWidth: 1 })
+        : h(Line, { key: `grid-${i}`, x1: line.x1, x2: line.x2, y1: line.y, y2: line.y, stroke: tokens.gridColor, strokeWidth: 1 }),
+    );
+    const base = layout.baseline;
+    const axis = !base
+      ? null
+      : base.y === undefined
+        ? h(Line, { x1: base.x, x2: base.x, y1: base.y1, y2: base.y2, stroke: tokens.axisColor, strokeWidth: 1 })
+        : h(Line, { x1: base.x1, x2: base.x2, y1: base.y, y2: base.y, stroke: tokens.axisColor, strokeWidth: 1 });
+    return h(
+      G,
+      null,
+      kind === "sparkline" ? null : grid,
+      layout.areas.map((area) =>
+        h(Path, {
+          key: `area-${area.seriesIndex}`,
+          d: area.d,
+          fill: paintOf(area.seriesIndex).color,
+          fillOpacity: AREA_OPACITY * paintOf(area.seriesIndex).opacity,
+        }),
+      ),
+      layout.bars.map((bar) =>
+        h(Path, {
+          key: `bar-${bar.seriesIndex}-${bar.index}`,
+          d: barPath(bar.rect, tokens.barRadius, bar.edge),
+          fill: paintOf(bar.seriesIndex).color,
+          fillOpacity: paintOf(bar.seriesIndex).opacity,
+        }),
+      ),
+      axis,
+      layout.lines.map((line) =>
+        h(Path, {
+          key: `line-${line.seriesIndex}`,
+          d: line.d,
+          fill: "none",
+          stroke: paintOf(line.seriesIndex).color,
+          strokeOpacity: paintOf(line.seriesIndex).opacity,
+          strokeWidth: LINE_WIDTH,
+          strokeLinejoin: "round",
+          strokeLinecap: "round",
+        }),
+      ),
+      layout.dots.map((dot, i) =>
+        h(Circle, {
+          key: `dot-${i}`,
+          cx: dot.cx,
+          cy: dot.cy,
+          r: DOT_RADIUS,
+          fill: paintOf(dot.seriesIndex).color,
+          fillOpacity: paintOf(dot.seriesIndex).opacity,
+        }),
+      ),
+      layout.tickLabels.map((label, i) => axisText(label, i, tokens, "tick")),
+      layout.categoryLabels.map((label, i) => axisText(label, i, tokens, "label")),
+    );
+  }
+
+  function DonutMarks({ width, height, model, tokens, valueFormat, locale, paintOf }) {
+    const layout = donutLayout({ width, height, model });
+    return h(
+      G,
+      null,
+      layout.slices.map((slice) =>
+        h(Path, {
+          key: `slice-${slice.index}`,
+          d: slice.d,
+          fill: paintOf(slice.index).color,
+          fillOpacity: paintOf(slice.index).opacity,
+          fillRule: "evenodd",
+        }),
+      ),
+      h(
+        SvgText,
+        {
+          x: layout.cx,
+          y: layout.cy + tokens.fontSize / 3,
+          fill: tokens.axisColor,
+          fontSize: tokens.fontSize + 2,
+          fontWeight: "600",
+          fontFamily: tokens.fontFamily,
+          textAnchor: "middle",
+        },
+        formatChartValue(layout.total, valueFormat, locale),
+      ),
+    );
+  }
+
+  function Chart(props) {
+    const {
+      type,
+      data,
+      series,
+      valueFormat,
+      height,
+      loading,
+      emptyTitle,
+      emptyMessage,
+      accessibilityLabel,
+      moreText,
+      theme: explicitTheme,
+      style,
+      testID,
+    } = props;
+    const hostTheme = useHostTheme();
+    // A host drawing outside a widget context passes its own theme.
+    const theme = explicitTheme || hostTheme || DEFAULT_THEME_TOKENS;
+    const noResults = useHostSharedText("no_results", NO_RESULTS_FALLBACK);
+    const locale = useHostLocale();
+    const [width, setWidth] = React.useState(0);
+    const kind = normaliseChartType(type);
+    const plotHeight = chartHeight(kind, height);
+    const model = React.useMemo(() => normaliseChartData(data, series), [data, series]);
+
+    if (loading) {
+      return h(Skeleton, { shape: "block", height: plotHeight, theme: explicitTheme, style, testID });
+    }
+    if (isChartEmpty(model, kind)) {
+      return h(EmptyState, { title: emptyTitle || noResults, message: emptyMessage, style, testID });
+    }
+
+    const tokens = resolveChartTokens(theme);
+    const paintOf = (index) => {
+      const own = kind === "donut" ? undefined : model.series[index] && model.series[index].color;
+      return own ? { color: own, opacity: 1 } : chartSeriesPaint(tokens, index);
+    };
+    const onLayout = (event) => {
+      const next = Math.floor(event.nativeEvent.layout.width);
+      if (next !== width) setWidth(next);
+    };
+    const marks =
+      width <= 0
+        ? null
+        : h(
+            Svg,
+            { width, height: plotHeight },
+            kind === "donut"
+              ? h(DonutMarks, { width, height: plotHeight, model, tokens, valueFormat, locale, paintOf })
+              : h(CartesianMarks, { kind, width, height: plotHeight, model, tokens, valueFormat, locale, paintOf }),
+          );
+    const legendItems =
+      kind === "donut"
+        ? donutLayout({ width: 1, height: 1, model }).slices.map((slice) => ({
+            key: `slice-${slice.index}`,
+            paint: paintOf(slice.index),
+            text: `${model.labels[slice.index]} ${formatChartValue(model.series[0].values[slice.index], valueFormat, locale)}`,
+          }))
+        : model.series.length > 1 && kind !== "sparkline"
+          ? model.series.map((s, i) => ({ key: s.key, paint: paintOf(i), text: s.label }))
+          : null;
+
+    return h(
+      View,
+      {
+        accessible: true,
+        accessibilityRole: "image",
+        accessibilityLabel: chartSummary({ type: kind, model, valueFormat, lead: accessibilityLabel, locale, moreText }),
+        style: [{ width: "100%" }, style],
+        testID,
+      },
+      h(
+        View,
+        { ...HIDDEN, onLayout, style: { width: "100%", height: plotHeight }, testID: testID ? `${testID}-plot` : undefined },
+        marks,
+      ),
+      legendItems ? h(Legend, { items: legendItems, theme, testID }) : null,
+    );
+  }
+  Chart.displayName = "Chart";
+
+  return { Chart };
+}

package/dist/chart.js

@@ -0,0 +1,21 @@
+// `<Chart>` (web). Binds ./chart-view.js to react-native-web and the host's
+// react-native-svg; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import Svg, { G, Path, Line, Circle, Text as SvgText } from "react-native-svg";
+import { Skeleton } from "./loading.js";
+import { EmptyState } from "./list.js";
+import { makeChart } from "./chart-view.js";
+
+export const { Chart } = makeChart({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Svg,
+  G,
+  Path,
+  Line,
+  Circle,
+  SvgText,
+  Skeleton,
+  EmptyState,
+});

package/dist/chart.native.js

@@ -0,0 +1,10 @@
+// `<Chart>` (native). Binds ./chart-view.js to React Native and
+// react-native-svg; only the imports differ from ./chart.js.
+
+import { View, Text } from "react-native";
+import Svg, { G, Path, Line, Circle, Text as SvgText } from "react-native-svg";
+import { Skeleton } from "./loading.native.js";
+import { EmptyState } from "./list.native.js";
+import { makeChart } from "./chart-view.js";
+
+export const { Chart } = makeChart({ View, Text, Svg, G, Path, Line, Circle, SvgText, Skeleton, EmptyState });

package/dist/contract.cjs

@@ -622,7 +622,7 @@ const THEME_COMPONENTS = Object.freeze({
   muted: Object.freeze({
     label: "Inputs",
     // The SDK's form controls read this scope directly, in every widget.
-    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField", "FileUpload", "RadioGroup"]),
+    sdkComponents: Object.freeze(["TextField", "Checkbox", "Switch", "Select", "SearchField", "FileUpload", "RadioGroup", "PeoplePicker"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
@@ -641,7 +641,7 @@ const THEME_COMPONENTS = Object.freeze({
   // radius and shadow keep the `<Overlay>` panel's own.
   popover: Object.freeze({
     label: "Dropdown menus",
-    sdkComponents: Object.freeze(["Select", "Menu", "Popover", "Tooltip"]),
+    sdkComponents: Object.freeze(["Select", "Menu", "Popover", "Tooltip", "PeoplePicker"]),
     tokens: Object.freeze({
       background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
@@ -784,6 +784,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Charts: `<Chart>` reads this scope directly, so it names the SDK
+  // component it styles and binds no widget field. Unset series colours
+  // follow the theme's own colours, so their defaults are derived.
+  chart: Object.freeze({
+    label: "Charts",
+    sdkComponents: Object.freeze(["Chart"]),
+    tokens: Object.freeze({
+      series1: Object.freeze({ type: "color" }),
+      series2: Object.freeze({ type: "color" }),
+      series3: Object.freeze({ type: "color" }),
+      series4: Object.freeze({ type: "color" }),
+      series5: Object.freeze({ type: "color" }),
+      series6: Object.freeze({ type: "color" }),
+      axisColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      gridColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      barRadius: Object.freeze({ type: "size", min: 0, max: 24, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2536,7 +2555,8 @@ const HOOKS = [
       "Returns { groups, loading, error, refetch, create, remove, addMember, " +
       "removeMember }. list returns the { data, meta } envelope verbatim — the " +
       "hook unwraps res.data; rows are snake_case. Reads need groups.read:*; " +
-      "mutations need groups.write:*.",
+      "mutations need groups.write:*. query { q?, ids?, limit?, offset? }: " +
+      "`ids` (1 to 100) names the groups behind ids you already hold.",
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -3377,6 +3397,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Chart",
+    description:
+      'Themed chart. `<Chart type="bar" data={groups.map((g) => ({ label: String(g.group), value: Number(g.sum) || 0 }))} loading={loading} valueFormat="compact" />`. Use it by default to plot a table\'s figures: feed it ONE `useDatastoreAggregate` call (`groups` for a breakdown by a column, `buckets` for a series over time) mapped to `[{ label, value }]`. `type` is "bar" (default), "hbar" (horizontal bars, for long category names), "line", "area", "donut" (the parts of a whole) or "sparkline" (a small line inside a tile, with no axes). It measures its own width and redraws when its container resizes, shows a `<Skeleton>` while `loading` and an `<EmptyState>` when there is nothing to plot, draws a legend for a donut and for several series, and gives a screen reader a one-line summary followed by the values. Its series colours, axis and label colour, gridline colour and bar corners come from the app\'s chart look (Design > Components > Charts), falling back to the theme\'s colours, so pass no colours of your own. Props: `data` (`[{ label, value }]`, or one number per series key), `series` (`[{ key, label, color? }]` for several series sharing one `data`: bars stand side by side, lines and areas overlay; a donut and a sparkline draw the first), `type`, `valueFormat` ("number" default | "compact", 1.2k | "percent", which appends % to a value already in percent, 42 reads 42% | a function of the number; used for the axis, the legend and the spoken values, grouped for the app\'s language), `height` (px, default 220; 48 for a sparkline), `loading`, `emptyTitle` (default the shared "No results" text) and `emptyMessage`, `accessibilityLabel` (replaces the spoken summary sentence; pass your translated title), `moreText` (`(count) => string`, the tail of a long spoken value list, default "and N more"; pass it translated), `style`, `testID`. When the request needs a chart it cannot draw (a scatter plot, a gantt or timeline, brushing or tapping a bar to filter), build your own with react-native-svg in the app\'s look (see DRAWING A CHART), painting it with `chartColors(useTheme())`: `series(i)` and `seriesOpacity(i)` for the i-th series, `axis` and `grid`, the colours `<Chart>` uses.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Divider",
     description:
@@ -3384,6 +3411,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Grid",
+    description:
+      'Balanced lines of cells sized from the grid\'s own measured width. `<Grid minCellWidth={240}>{items.map((item) => <Card key={item.id} style={{ flex: 1 }}>…</Card>)}</Grid>` — use it by default for a card grid, a tile or stat row, and a grid of definite-size cells (calendar days, seats, swatches); when the layout needs what it cannot express (masonry, a bento layout whose cells span lines), lay it out yourself with `useContainerWidth()`. It measures an inner box with no padding, so padding in its `style` is never counted into the width. `balance` "cards" (default): as many cells per line as fit at `minCellWidth` (240 when unset), every line but the last full and the last padded with empty cells so its cards keep the width above (6 that fit 5 are 3 + 3). "tiles": the remainder spreads over every line and each line stretches (5 at 4 per line are 3 + 2, never 4 + 1); the per-line ceiling is `maxColumns`, or what fits at `minCellWidth`, or else 4 / 3 / 2 for the wide / medium / narrow width tier. `columns` fixes the count per line. `cell={{ min, max }}` makes definite-size cells as large as fit up to `max` (never below `min`, 32 when unset) in a block centred in the grid (a block whose `min` cells cannot fit starts at the leading edge, so only its far end is cut off), `square` makes them as tall as wide: `<Grid columns={7} cell={{ min: 32, max: 64 }} square gap="xs">`. Props: `children` (one cell each; each keeps its own look and theme scope, and a child with `flex: 1` fills its cell\'s height so a line of cards ends level), `balance`, `minCellWidth`, `maxColumns`, `columns`, `cell`, `square`, `gap` (a theme spacing name, default "md", or a number), `style` (the outer box), `testID`, `accessibilityLabel`. A layout that depends on the width draws nothing until it is measured. In a row, give it `style={{ flex: 1, minWidth: 0 }}` so it has a width to measure.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Banner",
     description:
@@ -3464,7 +3498,7 @@ const PRIMITIVES = [
   {
     name: "Select",
     description:
-      'Themed picker for ONE value of a known list, or several with `multiple`. `<Select label="Status" value={status} onValueChange={setStatus} options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} placeholder="Choose a status" />` — the default way to let the user pick ONE of a known list. The trigger is the app\'s input field (Design > Components > Inputs) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Dropdown menus, so no card or scroll container can clip them, and a long list scrolls inside the sheet. The trigger is a button that opens a dialog (expanded state included) and each option carries the option role and its selected state on both hosts; the list around them is a listbox on the web only. On the web Enter, Space or an arrow key opens it, the arrow keys, Home and End move between options, Enter or Space chooses, Escape closes, and focus returns to the trigger; on Android the back button closes it. Props: `options` (`[{ value, label, disabled?, testID? }]`, `value` a string or number, unique), `value`, `onValueChange(value, option)`, `placeholder` (default "Select"), `title` (the sheet\'s heading; defaults to a text `label`), `emptyText` (default "No options"), `label`, `helper`, `error`, `disabled`, `accessibilityLabel`, `closeAccessibilityLabel`, `background` / `textColor` / `borderColor` / `radius` / `height` to override one field, `style` (the trigger), `containerStyle`, `testID`; any other prop lands on the trigger. Use it rather than a dropdown of your own; when the request needs options it cannot show (colour swatches, photos with two-line captions), put a small swatch or photo picker in a `<Popover>` at its button, or a long or full-screen option list in a `<Modal>` (an emoji choice is `<EmojiPicker>`) — never an absolutely positioned list, which the widget\'s container clips on both hosts. MULTIPLE: `<Select multiple label="Tags" values={tags} onValuesChange={setTags} options={tagOptions} />` — the default way to let the user pick SEVERAL of a known list. The same trigger and sheet; each option shows a tick box and toggles, the listbox is multiselectable on the web, and the sheet\'s Done button commits the choice through `onValuesChange(values, options)` (values in listed order, called only when they changed); closing the sheet any other way (backdrop, Escape, Android back) keeps the previous choice. Space toggles the focused option on the web. The trigger shows the picked labels as small chips while they fit on its one line, otherwise "N selected" (`selectedCountText(count)` to translate it), and `placeholder` while nothing is picked; `doneText` (default "Done") names the button. In this mode `value` / `onValueChange` are ignored. A handful of options always shown inline is a `<ChipGroup selection="multiple">` of `<Chip>`s instead.',
+      'Themed picker for ONE value of a known list, or several with `multiple`. `<Select label="Status" value={status} onValueChange={setStatus} options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} placeholder="Choose a status" />` — the default way to let the user pick ONE of a known list. The trigger is the app\'s input field (Design > Components > Inputs) showing the chosen label; pressing it opens the options at SCREEN level, in a sheet painted from Design > Components > Dropdown menus, so no card or scroll container can clip them, and a long list scrolls inside the sheet. The trigger is a button that opens a dialog (expanded state included) and each option carries the option role and its selected state on both hosts; the list around them is a listbox on the web only. On the web Enter, Space or an arrow key opens it, the arrow keys, Home and End move between options, Enter or Space chooses, Escape closes, and focus returns to the trigger; on Android the back button closes it. Props: `options` (`[{ value, label, disabled?, testID? }]`, `value` a string or number, unique), `value`, `onValueChange(value, option)`, `placeholder` (default "Select"), `title` (the sheet\'s heading; defaults to a text `label`), `emptyText` (default "No options"), `label`, `helper`, `error`, `disabled`, `accessibilityLabel`, `closeAccessibilityLabel`, `background` / `textColor` / `borderColor` / `radius` / `height` to override one field, `style` (the trigger), `containerStyle`, `testID`; any other prop lands on the trigger. Use it rather than a dropdown of your own; when the request needs options it cannot show (colour swatches, photos with two-line captions), put a small swatch or photo picker in a `<Popover>` at its button, or a long or full-screen option list in a `<Modal>` (an emoji choice is `<EmojiPicker>`) — never an absolutely positioned list, which the widget\'s container clips on both hosts. MULTIPLE: `<Select multiple label="Tags" values={tags} onValuesChange={setTags} options={tagOptions} />` — the default way to let the user pick SEVERAL of a known list. The same trigger and sheet; each option shows a tick box and toggles, the listbox is multiselectable on the web, and the sheet\'s Done button commits the choice through `onValuesChange(values, options)` (values in listed order, called only when they changed); closing the sheet any other way (backdrop, Escape, Android back) keeps the previous choice. Space toggles the focused option on the web. The trigger shows the picked labels as small chips while they fit on its one line, otherwise "N selected" (`selectedCountText(count)` to translate it), and `placeholder` while nothing is picked; `doneText` (default "Done") names the button. In this mode `value` / `onValueChange` are ignored. A handful of options always shown inline is a `<ChipGroup selection="multiple">` of `<Chip>`s instead. SEARCHABLE: a long list the user should type to narrow. `searchable` filters the given `options` by label as they type; `onSearch(query)` hands you the trimmed query when the sheet opens (\"\") and once typing pauses (`searchDebounceMs`, default 250), and you answer with new `options` and `loading` meanwhile (`optionsError` when it failed); or pass `options` as an async function of the query and Select fetches, keeping only the latest answer. The sheet then leads with the app\'s search field (Design > Components > Search fields), shows a spinner while loading, `noResultsText` (default \"No results\") when a query finds nothing and `loadErrorText` on failure, and its rows take the Lists row height and padding when the theme sets them. It remembers the label of every option it has shown; pass `selectedOptions` for a saved value the first page may not hold, or the trigger shows the placeholder. An option may carry `leading` (an `<Avatar>`, an icon) drawn before its label. Picking people, groups or a table\'s records is `<PeoplePicker>`, which does all of this for you.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3475,6 +3509,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    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.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "RadioGroup",
     description:
@@ -4544,7 +4585,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a bespoke line/area/donut chart renders identically in the Player and the Expo export from ONE source file. Pure JS.",
+      "SVG path generators — `line`, `area`, `arc`, `pie`, `curve*`. Each returns a path string you hand to the vetted react-native-svg's `<Path d={…} />`, so a chart `<Chart>` does not draw renders identically in the Player and the Expo export from ONE source file. Pure JS.",
   },
   {
     specifier: "d3-array",
@@ -6214,7 +6255,10 @@ const CONTRACT = deepFreeze({
   //    `<Menu>`, `<Popover>`, `<Tooltip>` (popover scope gains radius,
   //    shadow), `<IconButton>`, Button ghost/link/size/busy/selected and
   //    trigger pass-through, `<FileImage>`, `Avatar fileId`, `<RadioGroup>`.
-  version: "1.200.0",
+  // 1.201.0: additive (sc-12070, sc-12071, sc-12072) — new `<Grid>`,
+  //    `<Chart>` + `chart` theme scope + `chartColors`, `<PeoplePicker>`,
+  //    searchable `<Select>`; `useGroups` takes `ids`.
+  version: "1.201.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,