@colixsystems/widget-sdk 0.245.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;
 }
@@ -3870,6 +3926,11 @@ export const Avatar: (props: {
   seed?: string;
   /** An absolute image URL. */
   url?: string;
+  /**
+   * A filestore file id (a FILE column's value). Takes precedence over `url`;
+   * the initials show while it loads and stay if it cannot load.
+   */
+  fileId?: string | null;
   /** A size token, or a number of px (clamped to 16-160). */
   size?: "sm" | "md" | "lg" | "xl" | number;
   shape?: "circle" | "rounded";
@@ -3878,6 +3939,36 @@ export const Avatar: (props: {
   testID?: string;
 }) => any;
 
+/**
+ * A stored file's picture, or one at a URL: a themed `<Skeleton>` while it
+ * loads and a fallback, never a broken image, when it cannot. A `fileId` is
+ * resolved through `useFilestoreFile`, and an expired signed URL is fetched
+ * again once before the fallback shows.
+ *
+ * @example
+ *   <FileImage fileId={record.Photo} variant="card" aspectRatio={4 / 3} />
+ */
+export const FileImage: (props: {
+  /** A filestore file id (a FILE column's value). Wins over `uri`. */
+  fileId?: string | null;
+  /** A URL you already have, e.g. a `useFilestoreFiles()` row's `urls.card`. */
+  uri?: string | null;
+  /** The size-ladder rung to load. Default "large". */
+  variant?: "thumbnail" | "card" | "large" | "hero" | "original";
+  /** Width / height. Unset, the box takes the picture's own shape once loaded. */
+  aspectRatio?: number;
+  /** Corner radius: px, a theme radius name, or "none". Default the theme's `md`. */
+  radius?: number | "none" | "sm" | "md" | "lg" | "pill";
+  resizeMode?: "cover" | "contain" | "stretch" | "center";
+  /** What shows when the picture cannot load. Default "icon". */
+  fallback?: "icon" | "blank";
+  /** Unset, the picture is decorative and hidden from assistive technology. */
+  accessibilityLabel?: string;
+  style?: any;
+  /** Also tags `<testID>-image`, `<testID>-loading` and `<testID>-fallback`. */
+  testID?: string;
+}) => any;
+
 /** Themed completion bar or ring for real progress toward a known goal. */
 export const Progress: (props: {
   /** Percent complete; clamped to 0-100. */
@@ -3979,38 +4070,61 @@ export const Card: (props: {
 export type CardScrim = "bottom" | "top" | "left" | "right" | "full" | "none";
 export type CardImagePosition = "center" | "top" | "bottom" | "left" | "right";
 
-export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger";
+export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger" | "ghost" | "link";
+export type ButtonSize = "sm" | "md" | "lg";
 export const BUTTON_VARIANTS: readonly ButtonVariant[];
 
+/** Per-button surface fields; unset ones follow the theme. */
+export interface ButtonFields {
+  background?: string;
+  textColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  paddingX?: number;
+  paddingY?: number;
+  radius?: number;
+  fontWeight?: string;
+  fontSize?: number;
+  shadow?: "none" | "sm" | "md" | "lg";
+  gradient?: { from: string; to: string; angle?: number };
+}
+
 /**
  * Themed button (Design > Components > Buttons, Danger buttons, Button outline). Omit
- * `onPress` for a purely visual button inside something pressable.
+ * `onPress` for a purely visual button inside something pressable. `ghost` and
+ * `link` draw no fill or border and take only the look's shape and type.
  *
  * @example
- *   <Button title="Save" onPress={save} />
+ *   <Button title="Save" onPress={save} busy={saving} />
  *   <Button title="Delete" variant="danger" icon="trash-2" onPress={remove} />
+ *   <Button title="Load more" variant="ghost" size="sm" onPress={next} />
  */
-export const Button: (props: {
+/**
+ * What a `<Menu>`, `<Popover>` or `<Tooltip>` puts on the button it wraps, so
+ * a button can open one and expose whether it is open.
+ */
+export interface ButtonTriggerProps {
+  /** A `<Tooltip>` shows on a long press. */
+  onLongPress?: () => void;
+  "aria-haspopup"?: "menu" | "dialog" | boolean;
+  "aria-expanded"?: boolean;
+  "aria-describedby"?: string;
+}
+
+export const Button: (props: ButtonTriggerProps & {
   title: ReactNode;
   variant?: ButtonVariant;
+  /** sm (36 high) | md (44, default) | lg (52). */
+  size?: ButtonSize;
   icon?: string;
   iconPosition?: "leading" | "trailing";
   onPress?: () => void;
   disabled?: boolean;
-  /** Per-button surface fields; unset ones follow the theme. */
-  fields?: {
-    background?: string;
-    textColor?: string;
-    borderColor?: string;
-    borderWidth?: number;
-    paddingX?: number;
-    paddingY?: number;
-    radius?: number;
-    fontWeight?: string;
-    fontSize?: number;
-    shadow?: "none" | "sm" | "md" | "lg";
-    gradient?: { from: string; to: string; angle?: number };
-  };
+  /** A pending action: a spinner over the kept label; it cannot be pressed. */
+  busy?: boolean;
+  /** A toggle's on/off state; omit for a plain button. */
+  selected?: boolean;
+  fields?: ButtonFields;
   style?: any;
   labelStyle?: any;
   accessibilityLabel?: string;
@@ -4019,6 +4133,34 @@ export const Button: (props: {
   ref?: { current: any } | ((node: any) => void);
 }) => any;
 
+/**
+ * A square themed button that shows only an icon, at least 36px on both hosts.
+ * `accessibilityLabel` is its only name, so it is required.
+ *
+ * @example
+ *   <IconButton icon="pencil" accessibilityLabel="Edit order" onPress={edit} />
+ *   <IconButton icon="bold" accessibilityLabel="Bold" selected={bold} onPress={toggleBold} />
+ */
+export const IconButton: (props: ButtonTriggerProps & {
+  /** A lucide icon name, drawn with `<Icon>`. */
+  icon: string;
+  accessibilityLabel: string;
+  /** ghost (default) | primary | secondary | outlined | danger. */
+  variant?: Exclude<ButtonVariant, "link">;
+  /** sm (36) | md (44, default) | lg (52). */
+  size?: ButtonSize;
+  /** The glyph's colour, over the variant's. */
+  color?: string;
+  onPress?: () => void;
+  disabled?: boolean;
+  busy?: boolean;
+  selected?: boolean;
+  fields?: ButtonFields;
+  style?: any;
+  testID?: string;
+  ref?: { current: any } | ((node: any) => void);
+}) => any;
+
 /**
  * What every form control shares: the label drawn with it (and read by a
  * screen reader), a hint below it, and an error that replaces the hint and
@@ -4101,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`. */
@@ -4134,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" }]} />
@@ -4160,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`.
@@ -4204,6 +4448,48 @@ export const SearchField: (props: FormControlProps & {
   [prop: string]: any;
 }) => any;
 
+export type RadioGroupVariant = "list" | "card" | "segmented";
+
+export interface RadioOption<V extends string | number = string | number> {
+  value: V;
+  label: ReactNode;
+  /** A second line under the label; not drawn by the segmented variant. */
+  description?: ReactNode;
+  /** A lucide icon name drawn before the label. */
+  icon?: string;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/**
+ * Themed pick-ONE of a short list that stays on screen. `list` (default) is
+ * the app's input panel with one row per option, `card` one bordered card per
+ * option (with its `description`), both from Design > Components > Inputs;
+ * `segmented` is the segmented tab strip from Design > Components > Tabs,
+ * its options sharing the row evenly. Radio role and checked state on both
+ * hosts; on the web the group is one tab stop, the arrow keys move the
+ * choice and Space picks the focused option. Other props land on the group.
+ *
+ * @example
+ *   <RadioGroup label="Delivery" value={speed} onValueChange={setSpeed}
+ *     options={[{ value: "standard", label: "Standard" }, { value: "express", label: "Express" }]} />
+ */
+export const RadioGroup: <V extends string | number = string | number>(
+  props: FormControlProps & {
+    options: Array<RadioOption<V>>;
+    value?: V | null;
+    /** Called when a different option is picked. */
+    onValueChange?: (value: V, option: RadioOption<V>) => void;
+    variant?: RadioGroupVariant;
+    /** The group. */
+    style?: any;
+    /** The box around a group that shows a label, helper or error. */
+    containerStyle?: any;
+    [prop: string]: any;
+  },
+) => any;
+
 export type TabStyle = "segmented" | "pill" | "underline";
 
 /**
@@ -4334,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
@@ -4429,6 +4789,107 @@ export const FileUpload: (props: FormControlProps & {
   containerStyle?: any;
 }) => any;
 
+export type PopoverPlacement = "bottom" | "top";
+
+/** One `<Menu>` item. */
+export interface MenuItem {
+  label: string;
+  /** Runs after the menu closes. */
+  onPress?: () => void;
+  /** A Lucide icon name, or an element drawn before the label. */
+  icon?: string | ReactNode;
+  /** Drawn in the theme's danger colour. */
+  danger?: boolean;
+  /** Dimmed, skipped by the arrow keys, and cannot be picked. */
+  disabled?: boolean;
+  accessibilityLabel?: string;
+  testID?: string;
+  key?: string;
+}
+
+/**
+ * A list of actions opened from a trigger: a row's "…" button, a toolbar's
+ * overflow. Beside the trigger on a wide screen, a bottom sheet on a phone;
+ * drawn over the screen, so no card or list clips it. The backdrop, Escape
+ * (web) and the Android back button close it, and focus returns to the
+ * trigger. On the web it is a `menu` of `menuitem`s: the arrow keys, Home and
+ * End move between enabled items and Space or Enter picks one. A picked
+ * item's `onPress` runs once the menu has left the screen, so it can open a
+ * `<ConfirmDialog>`. Follows the theme's `popover` scope (Design > Components
+ * > Dropdown menus).
+ *
+ * @example
+ *   <Menu
+ *     trigger={<IconButton icon="more-horizontal" accessibilityLabel="More actions" />}
+ *     accessibilityLabel="Order actions"
+ *     items={[
+ *       { label: "Edit", icon: "pencil", onPress: edit },
+ *       canDelete && { label: "Delete", icon: "trash-2", danger: true, onPress: askDelete },
+ *     ]}
+ *   />
+ */
+export const Menu: (props: {
+  /** ONE pressable element; the menu adds the press that opens it. */
+  trigger: ReactNode;
+  /** Falsy entries are skipped, so `cond && { … }` works. */
+  items: Array<MenuItem | null | false | undefined>;
+  accessibilityLabel?: string;
+  /** Default "bottom"; it flips at the screen edge. */
+  placement?: PopoverPlacement;
+  /** The sheet backdrop's name. Default "Close". */
+  closeAccessibilityLabel?: string;
+  /** On the panel; the item list takes `-items`. */
+  testID?: string;
+}) => any;
+
+/**
+ * Free content beside a trigger: quick filters, a swatch picker, a short
+ * detail card. Placed like `<Menu>`, closed the same ways. Components inside
+ * read a theme inked for the panel. Follows the theme's `popover` scope.
+ *
+ * @example
+ *   <Popover trigger={<Button variant="secondary" title="Filters" />} accessibilityLabel="Filters">
+ *     {({ close }) => <Button title="Apply" onPress={() => { apply(); close(); }} />}
+ *   </Popover>
+ */
+export const Popover: (props: {
+  /** ONE pressable element; the popover adds the press that opens it. */
+  trigger: ReactNode;
+  children?: ReactNode | ((api: { close: () => void }) => ReactNode);
+  /** Pass with `onVisibleChange` to open and close it from your own code. */
+  visible?: boolean;
+  onVisibleChange?: (visible: boolean) => void;
+  /** Default "bottom"; it flips at the screen edge. */
+  placement?: PopoverPlacement;
+  accessibilityLabel?: string;
+  /** The sheet backdrop's name. Default "Close". */
+  closeAccessibilityLabel?: string;
+  /** On the panel. */
+  testID?: string;
+}) => any;
+
+/**
+ * A short label for the one pressable element it wraps, usually an
+ * icon-only button that keeps its own `accessibilityLabel`. On the web it
+ * shows on hover and keyboard focus; a touch screen has no hover, so there a
+ * long press shows it (a bottom sheet on a phone). A child with its own
+ * `onLongPress` keeps it and gets no long-press tooltip. The tooltip wraps
+ * the child in a `View`. Follows the theme's `popover` scope.
+ *
+ * @example
+ *   <Tooltip label="Delete">
+ *     <IconButton icon="trash-2" accessibilityLabel="Delete" onPress={remove} />
+ *   </Tooltip>
+ */
+export const Tooltip: (props: {
+  label: string;
+  /** Default "top"; it flips at the screen edge. */
+  placement?: PopoverPlacement;
+  /** On the label. */
+  testID?: string;
+  children: ReactNode;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

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.
@@ -241,6 +243,8 @@ export { List, ListRow, ListHeader, EmptyState } from "./list.js";
 export { Badge, Avatar, Progress, Stat, Divider } from "./detail-parts.js";
 export { initialsFor } from "./initials.js";
 export { avatarColorFor } from "./avatar-color.js";
+// A stored file's picture: a themed placeholder, then a fallback on failure.
+export { FileImage } from "./file-image.js";
 // The one card surface: the theme's `card` scope, a gradient fill, margin.
 export { Card } from "./card.js";
 export {
@@ -258,7 +262,7 @@ export {
   cardGradientProps,
 } from "./card-style.js";
 // The themed button; follows the theme's button, destructive and ring scopes.
-export { Button, BUTTON_VARIANTS } from "./button.js";
+export { Button, IconButton, BUTTON_VARIANTS } from "./button.js";
 export {
   BUTTON_PADDING_MAX,
   BUTTON_BORDER_WIDTH_MAX,
@@ -278,6 +282,10 @@ 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.
 export { spaceActivates } from "./form-control-logic.js";
 // A themed tab strip; follows the theme's `tabs` scope.
@@ -292,8 +300,13 @@ 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.
+export { Menu, Popover, Tooltip } from "./popover.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,