@colixsystems/widget-sdk 0.246.0 → 0.247.0

package/dist/index.d.ts

@@ -2406,6 +2406,60 @@ export const WIDE_WIDTH_PX: number;
  */
 export function widthTier(width: number): "narrow" | "medium" | "wide";
 
+/** How a `<Grid>` splits its cells into lines. */
+export type GridBalance = "cards" | "tiles";
+
+/** A theme spacing name, or a number of pixels. */
+export type GridGap = "xs" | "sm" | "md" | "lg" | "xl" | number;
+
+/**
+ * Lays its children out in balanced lines of cells, sized from the grid's own
+ * measured width, on the web Player and the native export alike. It measures
+ * an inner box with no padding, so a `style` padding is not counted twice.
+ *
+ * - `balance="cards"` (default): as many cells per line as fit at
+ *   `minCellWidth` (240 when unset); every line but the last is full, and the
+ *   last is padded with empty cells so its cards keep the width of the lines
+ *   above. 6 that fit 5 are 3 + 3.
+ * - `balance="tiles"`: the remainder spreads over every line and each line
+ *   stretches, so 5 tiles 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`: exactly that many cells per line, the last line padded.
+ * - `cell={{ min, max }}`: definite-size cells (calendar days, seats,
+ *   swatches) 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); with
+ *   `columns` a fixed count per line. `square` makes each cell as tall as it
+ *   is wide.
+ *
+ * Each child is one cell and keeps its own look; a child with `flex: 1` fills
+ * its cell's height, so a line of cards ends level. Nothing is drawn until the
+ * width is measured when the layout depends on it. In a row, give the grid
+ * `style={{ flex: 1, minWidth: 0 }}` so it has a width to measure.
+ *
+ * @example
+ *   <Grid minCellWidth={240}>{items.map((item) => <Card key={item.id}>…</Card>)}</Grid>
+ *   <Grid columns={7} cell={{ min: 32, max: 64 }} square gap="xs">{days}</Grid>
+ */
+export const Grid: (props: {
+  children?: ReactNode;
+  balance?: GridBalance;
+  /** The narrowest a cell may be; the per-line count is derived from it. */
+  minCellWidth?: number;
+  maxColumns?: number;
+  columns?: number;
+  cell?: { min?: number; max: number };
+  square?: boolean;
+  /** Space between cells and lines; `"md"` when unset. */
+  gap?: GridGap;
+  /** The grid's outer box; padding here stays out of the measured width. */
+  style?: any;
+  testID?: string;
+  /** Names the grid as one group to a screen reader. */
+  accessibilityLabel?: string;
+}) => any;
+
 /** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
 export interface GeolocationOptions {
   enableHighAccuracy?: boolean;
@@ -3140,6 +3194,8 @@ export interface AppUserGroupRow {
 
 export interface GroupsQuery {
   q?: string;
+  /** Only these groups (1 to 100 ids): name the groups behind ids you hold. */
+  ids?: string[];
   limit?: number;
   offset?: number;
 }
@@ -4187,12 +4243,53 @@ export interface SelectOption<V extends string | number = string | number> {
   label: string;
   disabled?: boolean;
   testID?: string;
+  /** Drawn before the label in the sheet: an `<Avatar>`, an icon. */
+  leading?: ReactNode;
+}
+
+/**
+ * The searchable mode of `<Select>`: a `<SearchField>` heads the sheet. Turn
+ * it on with `searchable` (the options are filtered where they are held),
+ * `onSearch` (you fetch per query) or async `options` (Select fetches).
+ */
+export interface SelectSearchProps<V extends string | number = string | number> {
+  /** Filter the given `options` by label as the person types. */
+  searchable?: boolean;
+  /**
+   * Called with the trimmed query when the sheet opens ("") and once typing
+   * pauses; answer by passing new `options` (and `loading` meanwhile).
+   */
+  onSearch?: (query: string) => void;
+  /** The pause, in ms, before a typed query is sent. Default 250. */
+  searchDebounceMs?: number;
+  /** The options for the last query are on their way. */
+  loading?: boolean;
+  /** The last query failed; a string replaces `loadErrorText`. */
+  optionsError?: boolean | string;
+  /**
+   * The options behind picked values the current `options` may not hold (a
+   * saved choice outside the first page), so the trigger names them.
+   */
+  selectedOptions?: Array<SelectOption<V>>;
+  /** Default "Search". */
+  searchPlaceholder?: string;
+  /** Shown when a query finds nothing. Default "No results". */
+  noResultsText?: string;
+  /** Default "Loading…". */
+  loadingText?: string;
+  /** Default "Could not load the options". */
+  loadErrorText?: string;
 }
 
 /** What every `<Select>` takes, in either mode. */
 export type SelectBaseProps<V extends string | number = string | number> = FormControlProps &
-  FormFieldOverrides & {
-    options: Array<SelectOption<V>>;
+  FormFieldOverrides &
+  SelectSearchProps<V> & {
+    /**
+     * The options, or a function Select calls with each query (searchable
+     * mode) that resolves to them; only its latest answer is shown.
+     */
+    options: Array<SelectOption<V>> | ((query: string) => Promise<Array<SelectOption<V>>>);
     /** Shown while nothing is chosen. Default "Select". */
     placeholder?: string;
     /** The sheet's heading. Defaults to a text `label`. */
@@ -4220,6 +4317,11 @@ export type SelectBaseProps<V extends string | number = string | number> = FormC
  * trigger shows the picked labels as small chips while they fit on its line,
  * else "N selected".
  *
+ * Searchable (`searchable`, `onSearch` or async `options`), the sheet leads
+ * with a `<SearchField>`, says when it is loading and when nothing matches,
+ * and keeps the label of every option it has shown; its rows take the theme's
+ * Lists row height and padding when they are set.
+ *
  * @example
  *   <Select label="Status" value={status} onValueChange={setStatus}
  *     options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]} />
@@ -4246,6 +4348,62 @@ export const Select: <V extends string | number = string | number>(
       }),
 ) => any;
 
+/** Where `<PeoplePicker>` reads its options. */
+export type PeoplePickerSource = "users" | "groups" | "records";
+
+/**
+ * A searchable `<Select>` of the workspace's users (`useDirectory`, scope
+ * `directory.read:users`), its groups (`useGroups`, `groups.read:*`) or one
+ * table's records (`useDatastoreQuery`, the table's `datastore.read` scope).
+ * 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.
+ *
+ * @example
+ *   <PeoplePicker label="Assignee" value={assignee} onValueChange={setAssignee} />
+ *   <PeoplePicker source="groups" multiple label="Teams" values={teams} onValuesChange={setTeams} />
+ *   <PeoplePicker source="records" table={tableId} label="Customer" value={customerId}
+ *     onValueChange={setCustomerId} />
+ */
+export const PeoplePicker: (
+  props: Omit<SelectBaseProps<string>, "options" | "onSearch" | "selectedOptions" | "searchable"> & {
+    /** Default "users". */
+    source?: PeoplePickerSource;
+    /** `source="records"`: the table id. */
+    table?: string;
+    /** `source="records"`: the column that names a record. Default the identification column. */
+    labelColumn?: string;
+    /** `source="records"`: a FILE column drawn as each row's avatar. */
+    avatarColumn?: string;
+    /** `source="users"`: only members of this group (a `useGroups()` row id). */
+    groupId?: string;
+    /** `source="records"`: narrows the rows, as `useDatastoreQuery`'s `filter`. */
+    filter?: Query["filter"];
+    /** Ids never offered (already members, the signed-in user). */
+    excludeIds?: string[];
+    /** Rows per search. Default 50, at most 200. */
+    pageSize?: number;
+    /** Draw an avatar before each user or group. Default true. */
+    showAvatars?: boolean;
+    /** A saved value whose row is gone, or a row with no name. Default "Unknown". */
+    unknownText?: string;
+  } & (
+      | {
+          multiple?: false;
+          value?: string | null;
+          onValueChange?: (value: string, option: SelectOption<string>) => void;
+        }
+      | {
+          multiple: true;
+          values?: string[] | null;
+          onValuesChange?: (values: string[], options: Array<SelectOption<string>>) => void;
+          selectedCountText?: (count: number) => string;
+          doneText?: string;
+        }
+    ),
+) => any;
+
 /**
  * Space-key activation for a control whose role is not a button: on the web a
  * `Pressable` answers Space only for a button. Native ignores `onKeyDown`.
@@ -4462,6 +4620,80 @@ export const ChipGroup: (props: {
   testID?: string;
 }) => any;
 
+export type ChartType = "bar" | "hbar" | "line" | "area" | "donut" | "sparkline";
+export type ChartValueFormat = "number" | "compact" | "percent" | ((value: number) => string);
+
+/** One series of a multi-series `<Chart>`: the key each `data` item carries its value under. */
+export interface ChartSeries {
+  key: string;
+  label: string;
+  /** A colour of the series' own; leave unset so the theme's chart look applies. */
+  color?: string;
+}
+
+/**
+ * Themed chart drawn with react-native-svg. Its series colours, axis and label
+ * colour, gridline colour and bar corners come from the theme's `chart` scope
+ * (falling back to the theme's colours), so every chart in the app matches. It
+ * measures its own width, 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 summary and the values.
+ *
+ * @example
+ *   const { groups, loading } = useDatastoreAggregate(tableId, { groupBy: "city", sumColumn: "visits" });
+ *   <Chart type="bar" loading={loading}
+ *     data={groups.map((g) => ({ label: String(g.group), value: Number(g.sum) || 0 }))} />
+ */
+export const Chart: (props: {
+  /** Default "bar". "hbar" is horizontal bars; "sparkline" a small line with no axes. */
+  type?: ChartType;
+  /** `[{ label, value }]`, or with `series` one number per series key. */
+  data: Array<{ label: string | number | { label: string }; [key: string]: unknown }>;
+  /** Several series sharing `data`. A donut and a sparkline draw the first. */
+  series?: ChartSeries[];
+  /**
+   * How values read on the axis, the legend and to a screen reader, grouped
+   * for the app's language. Default "number". "percent" appends "%" to values
+   * already in percent (42 reads "42%"); it does not multiply by 100.
+   */
+  valueFormat?: ChartValueFormat;
+  /** The plot's height in px. Default 220, or 48 for a sparkline. */
+  height?: number;
+  loading?: boolean;
+  /** Defaults to the shared "No results" text. */
+  emptyTitle?: string;
+  emptyMessage?: string;
+  /** Replaces the spoken summary sentence; the values are still read after it. */
+  accessibilityLabel?: string;
+  /** The tail of a spoken value list cut short; default `(count) => \`and ${count} more\``. */
+  moreText?: (count: number) => string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/**
+ * The colours `<Chart>` paints with, for a chart a widget draws itself (a
+ * scatter plot, a timeline) so it matches Design > Components > Charts.
+ *
+ * @example
+ *   const colors = chartColors(useTheme());
+ *   <Circle fill={colors.series(0)} fillOpacity={colors.seriesOpacity(0)} />
+ */
+export function chartColors(theme: any): {
+  /** The six series colours, in order. */
+  palette: string[];
+  /** Axis line and label colour. */
+  axis: string;
+  /** Gridline colour. */
+  grid: string;
+  /** Series `index`'s colour; a seventh and later one is lighter. */
+  series(index: number): string;
+  /** Series `index`'s opacity: 1, below 1 for a repeat of a colour that cannot be lightened. */
+  seriesOpacity(index: number): number;
+};
+
 /**
  * A file as `<FilePicker>` and `<FileUpload>` hand it over: the browser's
  * `File` on the web, expo-file-system's `File` on the Expo export. Pass it to

package/dist/index.js

@@ -112,6 +112,8 @@ export {
   widthTier,
   WIDE_WIDTH_PX,
 } from "./container-width.js";
+// Balanced lines of cells sized from the grid's own measured width.
+export { Grid } from "./grid.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file
 // (./clipboard.js / .native.js, ./toast.js / .native.js); index.js picks
 // the web variant and index.native.js picks the native variant.
@@ -280,6 +282,8 @@ export { Checkbox } from "./checkbox.js";
 export { Switch } from "./switch.js";
 export { Select } from "./select.js";
 export { SearchField } from "./search-field.js";
+// A searchable `<Select>` of users, groups or one table's records.
+export { PeoplePicker } from "./people-picker.js";
 // Pick one of a short visible list; `muted` scope, or `tabs` when segmented.
 export { RadioGroup } from "./radio-group.js";
 // Space for a control whose role is not a button; a no-op on native.
@@ -296,6 +300,9 @@ export { Modal } from "./modal.js";
 export { ConfirmDialog } from "./confirm-dialog.js";
 // Themed filter chips, tags and pills; follow the theme's `chip` scope.
 export { Chip, ChipGroup } from "./chip.js";
+// Themed bar, line, area and donut charts; follow the theme's `chart` scope.
+export { Chart } from "./chart.js";
+export { chartColors } from "./chart-tokens.js";
 // A themed file chooser on `<FilePicker>`; follows the theme's `muted` scope.
 export { FileUpload } from "./file-upload.js";
 // Anchored actions, content and labels; follow the theme's `popover` scope.

package/dist/index.native.js

@@ -112,6 +112,8 @@ export {
   widthTier,
   WIDE_WIDTH_PX,
 } from "./container-width.js";
+// Balanced lines of cells sized from the grid's own measured width.
+export { Grid } from "./grid.native.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";
@@ -273,6 +275,8 @@ export { Checkbox } from "./checkbox.native.js";
 export { Switch } from "./switch.native.js";
 export { Select } from "./select.native.js";
 export { SearchField } from "./search-field.native.js";
+// A searchable `<Select>` of users, groups or one table's records.
+export { PeoplePicker } from "./people-picker.native.js";
 // Pick one of a short visible list; `muted` scope, or `tabs` when segmented.
 export { RadioGroup } from "./radio-group.native.js";
 // Space for a control whose role is not a button; a no-op on native.
@@ -289,6 +293,9 @@ export { Modal } from "./modal.native.js";
 export { ConfirmDialog } from "./confirm-dialog.native.js";
 // Themed filter chips, tags and pills; follow the theme's `chip` scope.
 export { Chip, ChipGroup } from "./chip.native.js";
+// Themed bar, line, area and donut charts; follow the theme's `chart` scope.
+export { Chart } from "./chart.native.js";
+export { chartColors } from "./chart-tokens.js";
 // A themed file chooser on `<FilePicker>`; follows the theme's `muted` scope.
 export { FileUpload } from "./file-upload.native.js";
 // Anchored actions, content and labels; follow the theme's `popover` scope.

package/dist/people-picker-logic.js

@@ -0,0 +1,203 @@
+// The `<PeoplePicker>` rules that need no renderer: which source it reads,
+// the query each source is asked, how a row is named, and which saved values
+// still need a name. Both hosts share them, and the node suite tests them.
+
+export const PEOPLE_PICKER_SOURCES = Object.freeze(["users", "groups", "records"]);
+export const DEFAULT_PEOPLE_PAGE_SIZE = 50;
+// The directory resolves at most this many ids per request.
+export const MAX_RESOLVE_IDS = 100;
+
+/** A `source` prop as the picker reads it; anything unknown is "users". */
+export function pickerSource(source) {
+  return PEOPLE_PICKER_SOURCES.includes(source) ? source : "users";
+}
+
+function isId(value) {
+  return (typeof value === "string" && value !== "") || typeof value === "number";
+}
+
+function text(value) {
+  if (typeof value === "number") return String(value);
+  if (typeof value !== "string") return "";
+  return value.trim();
+}
+
+/**
+ * The page query a source's hook is asked: the typed search sent to the
+ * server, never filtered from one page here.
+ *
+ * @param {"users"|"groups"|"records"} source
+ * @param {{query?: string, pageSize?: number, groupId?: string, filter?: object}} own
+ */
+export function pageQuery(source, { query, pageSize, groupId, filter } = {}) {
+  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 === "records" && filter && typeof filter === "object") out.filter = filter;
+  return out;
+}
+
+// Schema columns arrive as wire `data_type` / `is_identification`; a
+// manifest-derived column carries `dataType` / `isIdentification`, and a
+// column being written names the flag `is_identification_column`.
+function columnType(column) {
+  return column.data_type ?? column.dataType;
+}
+
+function isIdentificationColumn(column) {
+  return Boolean(column.is_identification ?? column.isIdentification ?? column.is_identification_column);
+}
+
+/**
+ * The column a record is named by: the one given, else the table's
+ * identification column, else its first text column, else none.
+ *
+ * @param {{columns?: Array<{name: string, data_type?: string, dataType?: string,
+ *   is_identification?: boolean, isIdentification?: boolean}>}|null} schema
+ * @param {string} [own]
+ */
+export function recordLabelColumn(schema, own) {
+  if (typeof own === "string" && own !== "") return own;
+  const columns = (schema && Array.isArray(schema.columns) ? schema.columns : []).filter(Boolean);
+  const named = columns.find(isIdentificationColumn);
+  if (named) return named.name;
+  const textual = columns.find((column) => ["STRING", "TEXT"].includes(columnType(column)));
+  return textual ? textual.name : null;
+}
+
+/**
+ * A row's name: a user's name or email, a group's name, a record's label
+ * column. A row with none is `unknownText`, never its id.
+ *
+ * @param {object} row
+ * @param {{source: string, labelColumn?: string|null, unknownText: string}} how
+ */
+export function rowLabel(row, { source, labelColumn, unknownText }) {
+  if (!row || typeof row !== "object") return unknownText;
+  if (source === "records") {
+    const cell = labelColumn ? row[labelColumn] : undefined;
+    // A relation cell is hydrated as `{ id, label }`.
+    const shown = cell && typeof cell === "object" ? text(cell.label) : text(cell);
+    return shown || unknownText;
+  }
+  if (source === "users") return text(row.name) || text(row.email) || unknownText;
+  return text(row.name) || unknownText;
+}
+
+/** 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) : []);
+  return (Array.isArray(rows) ? rows : []).filter(
+    (row) => row && isId(row.id) && !excluded.has(String(row.id)),
+  );
+}
+
+/** A `value` or `values` prop as the list of picked ids. */
+export function pickedIds({ multiple, value, values }) {
+  if (multiple) return (Array.isArray(values) ? values : []).filter(isId);
+  return isId(value) ? [value] : [];
+}
+
+/**
+ * The picked ids no row has named and no lookup has tried yet: each is asked
+ * for once, so a deleted person is not looked up on every render.
+ *
+ * @param {Array<string|number>} ids
+ * @param {Map<string, object>} knownRows — id → row.
+ * @param {Set<string>} attempted — ids already looked up.
+ */
+export function unresolvedIds(ids, knownRows, attempted) {
+  return (Array.isArray(ids) ? ids : []).filter(
+    (id) => !knownRows.has(String(id)) && !attempted.has(String(id)),
+  );
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Split saved ids into those a users or groups lookup can ask for and those
+ * it cannot: the directory refuses a whole batch over one id that is not a
+ * UUID, so such an id is named unknown at once instead. Record ids are each
+ * read alone, so every one is asked for.
+ *
+ * @param {Array<string|number>} ids
+ * @param {"users"|"groups"|"records"} source
+ */
+export function lookupableIds(ids, source) {
+  const list = Array.isArray(ids) ? ids : [];
+  if (source === "records") return { lookup: list, unknown: [] };
+  const lookup = [];
+  const unknown = [];
+  for (const id of list) (typeof id === "string" && UUID.test(id) ? lookup : unknown).push(id);
+  return { lookup, unknown };
+}
+
+/**
+ * The lookups in flight, with `ids` that none of them holds yet added as new
+ * batches. A batch keeps the key it was given, so an id resolving elsewhere
+ * never restarts a lookup still out. Returns `queue` itself when nothing is new.
+ *
+ * @param {{pending: Array<{key: number, ids: Array<string|number>}>, next: number}} queue
+ * @param {Array<string|number>} ids
+ * @param {number} [size]
+ */
+export function queueLookups(queue, ids, size = MAX_RESOLVE_IDS) {
+  const out = new Set(queue.pending.flatMap((batch) => batch.ids.map(String)));
+  const fresh = (Array.isArray(ids) ? ids : []).filter((id) => !out.has(String(id)));
+  if (fresh.length === 0) return queue;
+  const added = batches(fresh, size).map((batch, i) => ({ key: queue.next + i, ids: batch }));
+  return { pending: [...queue.pending, ...added], next: queue.next + added.length };
+}
+
+/** `queue` without the lookup `key`. */
+export function settleLookup(queue, key) {
+  return { ...queue, pending: queue.pending.filter((batch) => batch.key !== key) };
+}
+
+/**
+ * Whether a page hook's result answers the query it was last asked. After the
+ * query changes, the hook still holds the previous answer until it starts
+ * loading or returns new rows, so that answer is not reported as this one.
+ *
+ * @param {{queryKey: string|null, rows: unknown, error: unknown}|null} last — what was last reported.
+ * @param {{queryKey: string|null, rows: unknown, error: unknown, loading: boolean}} now
+ */
+export function answersQuery(last, now) {
+  if (!last || last.queryKey === now.queryKey) return true;
+  return now.loading || now.rows !== last.rows || now.error !== last.error;
+}
+
+/** `ids` in batches of at most `size`. */
+export function batches(ids, size = MAX_RESOLVE_IDS) {
+  const list = Array.isArray(ids) ? ids : [];
+  const out = [];
+  for (let start = 0; start < list.length; start += size) out.push(list.slice(start, start + size));
+  return out;
+}
+
+/**
+ * What the trigger shows for each picked id: its row's name, "loading" while
+ * the lookup is out, `unknownText` once it found nothing. Never the raw id.
+ *
+ * @param {Array<string|number>} ids
+ * @param {{knownRows: Map<string, object>, attempted: Set<string>,
+ *   nameOf: (row: object) => string, loadingText: string, unknownText: string}} how
+ */
+export function pickedLabels(ids, { knownRows, attempted, nameOf, loadingText, unknownText }) {
+  return (Array.isArray(ids) ? ids : []).map((id) => {
+    const row = knownRows.get(String(id));
+    if (row) return { value: id, label: nameOf(row), row };
+    return { value: id, label: attempted.has(String(id)) ? unknownText : loadingText };
+  });
+}
+
+/** `knownRows` with every row in `rows` added by id. */
+export function rememberRows(knownRows, rows) {
+  const next = new Map(knownRows);
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (row && isId(row.id)) next.set(String(row.id), row);
+  }
+  return next;
+}