@colixsystems/widget-sdk 0.246.0 → 0.248.0

package/dist/index.d.ts

@@ -2406,6 +2406,160 @@ 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;
+
+/**
+ * `required` on a control that frames its own label (`<TextField>`,
+ * `<Select>`, `<RadioGroup>`, `<PeoplePicker>`, `<FileUpload>`, `<FormField>`).
+ */
+export interface FieldRequiredProps {
+  /**
+   * Draws a mark after a text label and adds the app's "Required" to the
+   * control's spoken name. It does not validate: pass `error` yourself.
+   */
+  required?: boolean;
+}
+
+/**
+ * A form laid out in width tiers from its own measured width, capped near
+ * 1000px and centred: its fields one to a line when narrow, two at medium and
+ * `columns` (three for `"auto"`) when wide. A `<FormField>` or a control that
+ * frames its own label (`<TextField>`, `<Select>`, `<RadioGroup>`,
+ * `<PeoplePicker>`, `<FileUpload>`) is one field; a multiline field, a `<FormField span="full">`,
+ * a `<FieldRow>`, a `<FormSection>`, a `<FormActions>` and anything else take
+ * the whole line. Children are read directly, not through a fragment.
+ *
+ * @example
+ *   <Form>
+ *     <FormSection title="Your details">
+ *       <FieldRow>
+ *         <TextField label="First name" value={first} onChangeText={setFirst} />
+ *         <TextField label="Last name" value={last} onChangeText={setLast} />
+ *       </FieldRow>
+ *       <TextField label="Email" required value={email} onChangeText={setEmail} />
+ *       <FormField label="Colour"><SwatchPicker value={colour} onChange={setColour} /></FormField>
+ *       <TextField label="Notes" multiline value={notes} onChangeText={setNotes} />
+ *     </FormSection>
+ *     <FormActions>
+ *       <Button variant="secondary" title="Cancel" onPress={cancel} />
+ *       <Button title="Save" onPress={save} />
+ *     </FormActions>
+ *   </Form>
+ */
+export const Form: (props: {
+  children?: ReactNode;
+  /** The most fields to a line when wide, 1–3. Default "auto" (three). */
+  columns?: "auto" | 1 | 2 | 3;
+  /** The cap the form centres within. Default 1000; `null` for none. */
+  maxWidth?: number | null;
+  /** Between fields and lines; `"md"` when unset. */
+  gap?: GridGap;
+  /** The form's outer box; padding here stays out of the measured width. */
+  style?: any;
+  testID?: string;
+  /** Names the form as one group to a screen reader. */
+  accessibilityLabel?: string;
+}) => any;
+
+/** Short related fields on one line (up to three); stacked when narrow. */
+export const FieldRow: (props: {
+  children?: ReactNode;
+  gap?: GridGap;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/** A titled group of fields, laid out in the same columns as its form. */
+export const FormSection: (props: {
+  /** A heading for screen readers too. */
+  title?: ReactNode;
+  description?: ReactNode;
+  children?: ReactNode;
+  gap?: GridGap;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/**
+ * The form's buttons in normal flow after its fields: the secondary first,
+ * the primary last. A row at the trailing edge at medium and wide; a
+ * full-width stack in the same order when narrow.
+ */
+export const FormActions: (props: {
+  children?: ReactNode;
+  style?: any;
+  testID?: string;
+}) => any;
+
+/**
+ * A label, required mark, helper and error round any control. A control that
+ * frames its own label is handed them instead (a prop it sets itself wins,
+ * `disabled={false}` included), so one label is drawn; `testID` goes to that
+ * control, or to a wrapper round it when it has its own. Any other child is
+ * framed here: on the web it is named as a group described by the note; on a
+ * device the one child takes the label (with "Required") as its name and the
+ * note as its hint, unless it names itself.
+ */
+export const FormField: (props: FormControlProps & FieldRequiredProps & {
+  children?: ReactNode;
+  /** Take the form's whole line. */
+  span?: "full";
+  /** The frame round the control. */
+  style?: any;
+}) => any;
+
 /** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
 export interface GeolocationOptions {
   enableHighAccuracy?: boolean;
@@ -3140,6 +3294,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;
 }
@@ -3843,6 +3999,97 @@ export const EmptyState: (props: {
   children?: ReactNode;
 }) => any;
 
+/** One column of a `<DataTable>`. */
+export interface DataTableColumn<Row = Record<string, any>> {
+  /** The record field the column shows, and the key its sort names. */
+  key: string;
+  /** The header label, and the label beside the value in the card layouts. Defaults to `key`. */
+  label?: ReactNode;
+  /** The column's share of the row width; the header uses the same. Defaults to 1. */
+  flex?: number;
+  align?: "left" | "center" | "right";
+  /** The narrowest the column may get, in pixels. Defaults to 0. */
+  minWidth?: number;
+  /** Makes the header a sort button. */
+  sortable?: boolean;
+  /** The cell's content; a string or number is drawn as the cell's text. Return `undefined` for the default. */
+  render?: (row: Row, column: DataTableColumn<Row>) => ReactNode;
+}
+
+/** The order a `<DataTable>` shows: one column, ascending or descending. */
+export interface DataTableSort {
+  key: string;
+  direction: "asc" | "desc";
+}
+
+/**
+ * A list of records laid out for its own measured width, on the web Player and
+ * the native export alike: stacked label/value cards when narrow, one card per
+ * row at medium (the first column as the title, the rest on one line), and
+ * aligned columns under a sticky header when wide. Its rows are `<List>` /
+ * `<ListRow>` and its header `<ListHeader>`, styled by the theme's Lists
+ * settings (and Cards for the card layouts); it adds no theme scope.
+ *
+ * Sorting: a sortable header is a 44px button named by its column and
+ * described by its sort, and a change of sort is announced once, on both
+ * hosts. With `onSortChange` the widget orders the rows itself (a server
+ * sort: re-query with the new sort) and the table draws `rows` as given;
+ * without it the table sorts them, a `Date` value as a date. `sort` makes the
+ * order controlled, `defaultSort` sets where an uncontrolled table starts; a
+ * controlled `sort` without `onSortChange` is display-only, its headers plain
+ * labels. The card layouts offer the same sort from a menu above the cards.
+ * The sticky header is filled with the rows' Lists background, else the
+ * theme surface.
+ *
+ * @example
+ *   const [sort, setSort] = useState({ key: "name", direction: "asc" });
+ *   const query = useStableQuery(() => ({ sort: { field: sort.key, dir: sort.direction } }));
+ *   const { data, loading } = useDatastoreQuery(tableId, query);
+ *   <DataTable
+ *     columns={[
+ *       { key: "name", label: "Name", flex: 2, sortable: true },
+ *       { key: "status", label: "Status", render: (row) => <Badge label={row.status} /> },
+ *       { key: "total", label: "Total", align: "right", sortable: true },
+ *     ]}
+ *     rows={data}
+ *     loading={loading}
+ *     sort={sort}
+ *     onSortChange={setSort}
+ *     onRowPress={(row) => open(row.id)}
+ *   />
+ */
+export const DataTable: <Row = Record<string, any>>(
+  props: ListRowTokens & {
+    columns: Array<DataTableColumn<Row> | string>;
+    rows: Row[];
+    /** The field that keys each row. Defaults to "id". */
+    keyField?: string;
+    /** Every cell's content where its column has no `render`; return `undefined` for the default. */
+    renderCell?: (row: Row, column: DataTableColumn<Row>) => ReactNode;
+    /** Makes every row a button. */
+    onRowPress?: (row: Row) => void;
+    /** The order shown, controlled. */
+    sort?: DataTableSort | null;
+    /** Where an uncontrolled table's order starts. */
+    defaultSort?: DataTableSort;
+    /** Called with the new order; the widget then orders `rows` itself. */
+    onSortChange?: (sort: DataTableSort) => void;
+    /** The rows' scroll box height, in pixels. Defaults to 480. */
+    maxHeight?: number;
+    /** Placeholder rows while `rows` is still empty. */
+    loading?: boolean;
+    /** The empty state's title and message; the message defaults to "No results". */
+    emptyTitle?: ReactNode;
+    emptyMessage?: ReactNode;
+    /** The words a sort is spoken with, in the widget's language. */
+    sortLabels?: { sort?: string; ascending?: string; descending?: string };
+    /** The table's outer box; padding here stays out of the measured width. */
+    style?: any;
+    testID?: string;
+    accessibilityLabel?: string;
+  },
+) => any;
+
 /**
  * Themed status pill: a record's state (Active, Paid, Overdue) beside the
  * thing it describes. The label always renders; the tone only tints it.
@@ -4136,7 +4383,7 @@ export interface FormFieldOverrides {
  * @example
  *   <TextField label="Name" value={name} onChangeText={setName} placeholder="Your name" />
  */
-export const TextField: (props: FormControlProps & FormFieldOverrides & {
+export const TextField: (props: FormControlProps & FieldRequiredProps & FormFieldOverrides & {
   multiline?: boolean;
   style?: any;
   /** The box around a labelled field. */
@@ -4187,12 +4434,54 @@ 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>>;
+  FieldRequiredProps &
+  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 +4509,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 +4540,136 @@ 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;
+
+/** One `<FilterBar>` facet: a dropdown of `options` under `key` in the value. */
+export interface FilterBarFacet<V extends string | number = string | number> {
+  key: string;
+  label: string;
+  options: Array<SelectOption<V>>;
+  /** Several values at once; the facet's value is then a list. */
+  multiple?: boolean;
+  /** Type to narrow the options, as `<Select searchable>`. */
+  searchable?: boolean;
+}
+
+/** The applied filters: each facet's value, or a list for a `multiple` one. */
+export type FilterBarValue = Record<string, string | number | Array<string | number>>;
+
+/**
+ * Search plus facet filters that lay themselves out for their own measured
+ * width. Medium and wide: one toolbar row of a `<SearchField>`, a compact
+ * `<Select>` per facet ("Status: Any") and the sort. Narrow, or a row whose
+ * dropdowns do not fit: the search field and one "Filters · n" button opening
+ * the facets in a `<Modal>` sheet, where nothing applies until Apply. At every
+ * width each applied facet is a removable `<Chip>` beneath, with a "Clear all".
+ *
+ * `onChange` gets the whole next value once per edit, with a cleared facet's
+ * key removed; `onQueryChange` gets the trimmed query once typing pauses
+ * (`queryDebounceMs`, default 250) and at once on clear or submit. Both are
+ * controlled, so seed `query` and `value` from route params or
+ * `useWidgetRoute`. "Clear all" resets the facets and the query. The search
+ * field shows only with `onQueryChange`. Copy props default to English.
+ *
+ * @example
+ *   <FilterBar query={q} onQueryChange={setQ} value={filters} onChange={setFilters}
+ *     facets={[{ key: "status", label: "Status", options: [{ value: "open", label: "Open" }] }]}
+ *     sort={{ options: [{ value: "new", label: "Newest" }], value: sortBy, onChange: setSortBy }} />
+ */
+export const FilterBar: (props: {
+  query?: string;
+  onQueryChange?: (query: string) => void;
+  /** The pause, in ms, before typed text is reported. Default 250. */
+  queryDebounceMs?: number;
+  facets: FilterBarFacet[];
+  value?: FilterBarValue | null;
+  onChange?: (next: FilterBarValue) => void;
+  /** One more dropdown; sorting is never shown as a chip. */
+  sort?: {
+    options: Array<SelectOption>;
+    value?: string | number | null;
+    onChange: (value: string | number) => void;
+    /** Default "Sort". */
+    label?: string;
+  };
+  /** Default "Search". */
+  searchPlaceholder?: string;
+  /** A facet with nothing picked. Default "Any". */
+  anyText?: string;
+  /** The narrow button and the sheet's title. Default "Filters". */
+  filtersText?: string;
+  /** Spoken after the button's name; `{count}` is the number applied. Default "{count} active". */
+  activeCountText?: string | ((count: number) => string);
+  /** Default "Clear all". */
+  clearAllText?: string;
+  /** Default "Apply". */
+  applyText?: string;
+  /** Empties the sheet's facets and puts its sort on the first option. Default "Clear". */
+  clearText?: string;
+  /** Names the chip group. Default "Active filters". */
+  activeFiltersText?: string;
+  /** A chip's remove control; `{label}` is the chip. Default "Remove {label}". */
+  removeText?: string | ((label: string) => string);
+  closeAccessibilityLabel?: string;
+  /** The outer box; its padding is not counted into the measured width. */
+  style?: any;
+  testID?: 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`.
@@ -4318,7 +4742,7 @@ export interface RadioOption<V extends string | number = string | number> {
  *     options={[{ value: "standard", label: "Standard" }, { value: "express", label: "Express" }]} />
  */
 export const RadioGroup: <V extends string | number = string | number>(
-  props: FormControlProps & {
+  props: FormControlProps & FieldRequiredProps & {
     options: Array<RadioOption<V>>;
     value?: V | null;
     /** Called when a different option is picked. */
@@ -4462,6 +4886,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
@@ -4499,8 +4997,8 @@ export const FilePicker: ((props: {
 /**
  * Themed file chooser on `<FilePicker>`: a button (the `button` scope) in the
  * input field (the `muted` scope), the chosen files with their size and a
- * remove control, and the form controls' `label` / `helper` / `error` /
- * `disabled`. On the web a file can also be dropped onto the field; native
+ * remove control, and the form controls' `label` / `required` / `helper` /
+ * `error` / `disabled`. On the web a file can also be dropped onto the field; native
  * has no file drop, so the button is the control there. A file `accept` rules
  * out is not added and shows an error. It uploads nothing: upload in
  * `onPick` with `useFilestoreUpload` and pass `uploading` while it runs, which
@@ -4513,7 +5011,7 @@ export const FilePicker: ((props: {
  *     files={photos} onFilesChange={setPhotos}
  *     onPick={(picked) => Promise.all(picked.map((f) => upload(f))).then(() => setPhotos([]))} />
  */
-export const FileUpload: (props: FormControlProps & {
+export const FileUpload: (props: FormControlProps & FieldRequiredProps & {
   accept?: string;
   /** A new pick joins the list instead of replacing the file. Default false. */
   multiple?: boolean;
@@ -4658,6 +5156,107 @@ export const Tooltip: (props: {
   children: ReactNode;
 }) => any;
 
+/**
+ * The words `<SortableList>` and `<Board>` show and announce. `{item}`,
+ * `{position}`, `{total}` and `{column}` are filled in; a blank entry keeps
+ * the English default.
+ */
+export interface SortableLabels {
+  /** The handle's name and its options' title. Default "Move {item}". */
+  handle?: string;
+  hint?: string;
+  moveUp?: string;
+  moveDown?: string;
+  moveToTop?: string;
+  moveToBottom?: string;
+  /** Default "Move to {column}". */
+  moveToColumn?: string;
+  /** Default "{item} moved to position {position} of {total}". */
+  moved?: string;
+  /** Default "{item} moved to {column}, position {position}". */
+  movedToColumn?: string;
+}
+
+/**
+ * A list the user reorders by dragging a row's grip handle, on both hosts.
+ * The rows are `<ListRow>`s in the theme's `list` scope. A tap or Enter on
+ * the handle opens its move options, the arrow keys move a focused handle on
+ * the web, and a screen reader is offered the same moves as actions.
+ * `onReorder` runs once per real change; a drag that changes nothing springs
+ * back and calls nothing.
+ *
+ * @example
+ *   <SortableList
+ *     items={steps}
+ *     onReorder={(next) => setSteps(next)}
+ *     renderItem={({ item }) => <Text>{item.title}</Text>}
+ *   />
+ */
+export function SortableList<T>(props: {
+  items: T[];
+  onReorder?: (nextItems: T[], move: { from: number; to: number; item: T }) => void;
+  /** A row's content; with none the item's title, name or label shows. */
+  renderItem?: (row: { item: T; index: number; dragging: boolean }) => ReactNode;
+  /** Default: the item's `id`, then `key`, then its position. */
+  keyExtractor?: (item: T, index: number) => string | number;
+  /** The name a move announces. Default: its `title`, `name` or `label`. */
+  getItemLabel?: (item: T) => string;
+  /** Read on every render; a row it refuses shows no handle. Default true. */
+  canDrag?: boolean | ((item: T) => boolean);
+  /** "card" draws each row as the app's card. Default "plain". */
+  variant?: "plain" | "card";
+  labels?: SortableLabels;
+  style?: any;
+  testID?: string;
+  accessibilityLabel?: string;
+}): any;
+
+/** One `<Board>` column: the key `getColumn` returns, and its heading. */
+export interface BoardColumn {
+  key: string | number;
+  title: string;
+}
+
+/**
+ * Cards the user moves between columns (a kanban, a pipeline) by dragging a
+ * card's grip handle, on both hosts. Each card is the app's `<Card>`. The one
+ * column a held card is over takes the theme's soft primary, with a line
+ * where it will land; a narrow board scrolls its columns sideways, and by
+ * itself while a card is held at its edge. Move options, arrow keys and
+ * screen-reader actions move a card without dragging.
+ *
+ * @example
+ *   <Board
+ *     columns={[{ key: "todo", title: "To do" }, { key: "done", title: "Done" }]}
+ *     items={rows}
+ *     getColumn={(row) => row.status}
+ *     onMove={(row, { toColumn }) => move(row, toColumn)}
+ *     renderCard={({ item }) => <Text>{item.title}</Text>}
+ *   />
+ */
+export function Board<T>(props: {
+  columns: BoardColumn[];
+  items: T[];
+  /** The key of the column an item belongs in; an unknown key hides it. */
+  getColumn: (item: T) => string | number;
+  /** `index` is its place in the target column. */
+  onMove?: (item: T, move: { fromColumn: string | number; toColumn: string | number; index: number }) => void;
+  /** A card's content; with none the item's title, name or label shows. */
+  renderCard?: (card: { item: T; index: number; column: string | number; dragging: boolean }) => ReactNode;
+  keyExtractor?: (item: T, index: number) => string | number;
+  getItemLabel?: (item: T) => string;
+  /** Read on every render; a card it refuses shows no handle. Default true. */
+  canDrag?: boolean | ((item: T) => boolean);
+  /** False when cards keep no order of their own. Default true. */
+  reorderInColumn?: boolean;
+  /** A column's width when a narrow board scrolls sideways. Default 280. */
+  columnWidth?: number;
+  labels?: SortableLabels;
+  style?: any;
+  testID?: string;
+  accessibilityLabel?: string;
+}): any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every