@colixsystems/widget-sdk 0.247.0 → 0.249.0

package/dist/contract.cjs

@@ -3361,6 +3361,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "DataTable",
+    description:
+      'A list of records laid out for its own width. `<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" }]} rows={data} loading={loading} onRowPress={(row) => open(row.id)} />` — use it by default for a list or table of records (datastore rows): it is 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, from its own measured width, so it needs no tier code of yours. When the table needs what it cannot do (editable cells, grouped or collapsible rows, resizable columns, a pivot), build your own from `<ListHeader>` over a `<List>` of `<ListRow>`s with the same `flex` per column. Columns: `key`, `label`, `flex` (default 1, the same in the header and the rows), `align` ("left" / "center" / "right"), `minWidth`, `sortable`, `render(row, column)` (a string or number becomes the cell\'s text). Props: `columns`, `rows`, `keyField` (default "id"), `renderCell(row, column)` (every cell without its own `render`; return `undefined` for the default), `onRowPress(row)`, `sort` / `defaultSort` (`{ key, direction: "asc" | "desc" }`), `onSortChange(sort)`, `maxHeight` (the rows\' scroll box, default 480), `loading` (placeholder rows while `rows` is empty), `emptyTitle`, `emptyMessage` (an empty state, "No results" by default), `sortLabels` (`{ sort, ascending, descending }` in the widget\'s language), the Lists overrides (`rowPadding`, `gap`, …), `style`, `testID`, `accessibilityLabel`. A sortable header is a 44px button named by its column and described by its sort, and a change of sort is announced once; the card layouts offer the same sort from a menu. With `onSortChange` you order the rows (re-query with the new sort) and the table draws `rows` as given; without it the table sorts them itself (a `Date` value sorts as a date). A controlled `sort` without `onSortChange` is display-only: the rows follow it and the headers are plain labels. The sticky header is filled with the rows\' Lists background, else the theme surface. It is styled by Design > Components > Lists (and Cards for the card layouts).',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Badge",
     description:
@@ -3418,6 +3425,41 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Form",
+    description:
+      'A form laid out in width tiers from its own measured width. `<Form><FieldRow><TextField label="First name" … /><TextField label="Last name" … /></FieldRow><TextField label="Email" required … /><FormActions><Button variant="secondary" title="Cancel" … /><Button title="Save" … /></FormActions></Form>` — use it by default for a widget that captures or edits data: its fields sit one to a line when narrow, two at medium and up to three when wide, and the form is capped near 1000px and centred, so it is never flush left, a narrow strip in an empty page, or a wall of giant inputs. 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 (a `<Banner>`, a paragraph) take the whole line. Its direct children are read, so do not wrap them in a fragment. Props: `children`, `columns` ("auto" — three when wide — or 1–3, the most fields to a line), `maxWidth` (1000 by default, `null` for none, for a form in a side panel), `gap` (a theme spacing name, default "md", or a number), `style` (the outer box), `testID`, `accessibilityLabel`. When the form needs what it cannot do (a multi-step wizard, a form beside a live preview, fields laid over a picture), lay it out yourself in the app\'s look with `useContainerWidth()` and `widthTier()`, keeping the three tiers.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FieldRow",
+    description:
+      'Short related fields on one line inside a `<Form>`: first + last name, city + postal code, expiry + CVC. `<FieldRow><TextField label="City" … /><TextField label="Postal code" … /></FieldRow>`. Up to three fields share the line; when narrow they stack. Props: `children`, `gap`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormSection",
+    description:
+      'A titled group of fields inside a `<Form>`, laid out in the form\'s own columns. `<FormSection title="Payment" description="Charged when the order ships">…</FormSection>`. Group a form past about six fields into sections. The title is a heading for screen readers too, in the subtitle text role; the description is in the helper colour. Props: `title`, `description`, `children`, `gap`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormActions",
+    description:
+      'A form\'s buttons in normal flow after its fields, never over them. `<FormActions><Button variant="secondary" title="Cancel" onPress={cancel} /><Button title="Save" onPress={save} busy={saving} /></FormActions>`. Pass the secondary first and the primary last: at medium and wide they sit in a row at the trailing edge, the primary last; when narrow they stack full-width in the same order, the primary nearest the thumb. Props: `children`, `style`, `testID`. In a `<Modal>`, pass the buttons to its `footer` instead.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormField",
+    description:
+      'The label, required mark, helper and error of the form controls, round any control. `<FormField label="Colour" required helper="Shown on the card" error={colourError}><SwatchPicker … /></FormField>`. A control that frames its own label (`<TextField>`, `<Select>`, `<RadioGroup>`, `<PeoplePicker>`, `<FileUpload>`) is handed them instead, so one label is drawn (a prop the control sets itself wins, `disabled={false}` included; the field\'s `testID` goes to the control, or to a wrapper round it when the control has its own); those five also take `required` directly. Any other child is framed here and named to a screen reader: on the web as a group, with the helper or error as its description; on a device the one child itself takes the label (with "Required") as its name and the helper or error as its hint, unless it names itself, when the label speaks the required word. Give that child no label of its own. `required` draws the mark and adds the app\'s "Required" to the spoken name; it does not validate, so pass `error` yourself. Props: `label`, `required`, `helper`, `error`, `disabled`, `span` ("full" takes the form\'s whole line), `style`, `testID`, `children`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Banner",
     description:
@@ -3484,7 +3526,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3505,7 +3547,7 @@ const PRIMITIVES = [
   {
     name: "SearchField",
     description:
-      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it; its glyph and clear control fill the icon slots of `TextField`, so it takes no `leadingIcon` / `trailingIcon`. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3516,6 +3558,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "FilterBar",
+    description:
+      'Search plus facet filters that lay themselves out for their own width. `<FilterBar query={query} onQueryChange={setQuery} facets={[{ key: "status", label: t("status", "Status"), options: [{ value: "open", label: t("open", "Open") }] }]} value={filters} onChange={setFilters} sort={{ options: sortOptions, value: sortBy, onChange: setSortBy }} />` — use it by default for a list\'s search and filters; when the filters need what it cannot do (a date-range facet, a price slider, a map-area filter, saved filter presets), build your own toolbar from `<SearchField>`, `<Select>`, `<Chip>` and `<Modal>` in the same shape. It measures its own unpadded box: medium and wide are ONE toolbar row (the search field taking the free width, one compact `<Select>` per facet whose placeholder reads "Status: Any", then the sort) with each applied facet beneath as a removable chip ("Status: Open") and a "Clear all" that resets the facets and the query; narrow, or a row whose dropdowns would not fit, is the search field plus ONE "Filters · 2" button opening the facets as full-width Selects in a `<Modal>` sheet, applied on Apply (Clear empties the sheet\'s facets and puts its sort back on the first option). The applied chips and "Clear all" show beneath at every width, so a narrow user can drop one filter without the sheet. A facet is `{ key, label, options, multiple?, searchable? }`; `value` is `{ [key]: value }`, a list for a `multiple` facet, and `onChange(next)` fires once per edit with a cleared facet\'s key removed. `onQueryChange(query)` gets the trimmed query once typing pauses (`queryDebounceMs`, default 250) and at once on clear or submit; the search field shows only with it. Both are controlled, so seed `query` and `value` from route params or `useWidgetRoute`. Its parts keep their own looks (Design > Components > Search fields, Inputs, Dropdown menus, Chips, Dialogs); it adds no theme scope. Translate the copy with `t()`: `searchPlaceholder`, `anyText` ("Any"), `filtersText` ("Filters"), `activeCountText` ("{count} active"), `clearAllText`, `applyText`, `clearText`, `activeFiltersText`, `removeText` ("Remove {label}"). Other props: `style` (the outer box), `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "RadioGroup",
     description:
@@ -3548,7 +3597,7 @@ const PRIMITIVES = [
   {
     name: "FileUpload",
     description:
-      'Themed file chooser. `<FileUpload label="Attachments" accept="image/*,.pdf" multiple files={files} onFilesChange={setFiles} />` — the default way to let the user pick files to upload, whether they upload at once or with a form. It is built on `<FilePicker>`: a button (Design > Components > Buttons) inside the app\'s input field (Design > Components > Inputs), the chosen files listed under it with their name, size and a remove control, and the same `label` / `helper` / `error` / `disabled` as every form control. The button opens the system file picker on both hosts and is the only way in on a device; on the web a file can also be dropped onto the field. A picked or dropped file that `accept` rules out is not added and the field shows an error. It uploads nothing itself: call `upload(file)` from `useFilestoreUpload` in `onPick` (or when the form is submitted) and pass `uploading` while it runs; the field then shows a `<Spinner>` with "Uploading…" and locks (no percentage is reported). Props: `accept` (an HTML accept value: "image/*", ".pdf", "application/pdf"), `multiple` (default false: a new pick replaces the file), `files` + `onFilesChange(files)` to own the list (omit both and it keeps its own; pass `files={[]}` to list nothing), `onPick(file)` (an array when `multiple`) once per pick or drop with only the new files, `onRemove(file, index)`, `onReject(files, reason)` (reason "type" for a file `accept` rules out, "count" for the files beyond the first when not `multiple`), `uploading`, `label`, `helper`, `error` (a message, or `true`), `disabled`, `buttonLabel` (default "Choose file" / "Choose files"), `buttonVariant` ("primary" | "secondary" | "outlined", the default), `uploadingLabel`, `emptyLabel`, `dropLabel`, `rejectedMessage`, `singleFileMessage`, `unsupportedMessage`, `removeAccessibilityLabel`, `accessibilityLabel`, `style` (the field), `containerStyle`, `testID` (also tags `<testID>-button`, `<testID>-file-<i>` and `<testID>-remove-<i>`). Pass translated copy for every label. Use it rather than a `<FilePicker>` round your own button, file list or "Uploading…" text; when the request needs what it cannot do (a grid of photo thumbnails, a cover image replaced on tap), wrap `<FilePicker>` round your own trigger in the app\'s look and still upload with `useFilestoreUpload`.',
+      'Themed file chooser. `<FileUpload label="Attachments" accept="image/*,.pdf" multiple files={files} onFilesChange={setFiles} />` — the default way to let the user pick files to upload, whether they upload at once or with a form. It is built on `<FilePicker>`: a button (Design > Components > Buttons) inside the app\'s input field (Design > Components > Inputs), the chosen files listed under it with their name, size and a remove control, and the same `label` / `required` / `helper` / `error` / `disabled` as every form control. The button opens the system file picker on both hosts and is the only way in on a device; on the web a file can also be dropped onto the field. A picked or dropped file that `accept` rules out is not added and the field shows an error. It uploads nothing itself: call `upload(file)` from `useFilestoreUpload` in `onPick` (or when the form is submitted) and pass `uploading` while it runs; the field then shows a `<Spinner>` with "Uploading…" and locks (no percentage is reported). Props: `accept` (an HTML accept value: "image/*", ".pdf", "application/pdf"), `multiple` (default false: a new pick replaces the file), `files` + `onFilesChange(files)` to own the list (omit both and it keeps its own; pass `files={[]}` to list nothing), `onPick(file)` (an array when `multiple`) once per pick or drop with only the new files, `onRemove(file, index)`, `onReject(files, reason)` (reason "type" for a file `accept` rules out, "count" for the files beyond the first when not `multiple`), `uploading`, `label`, `required` (a mark after the label and "Required" in the picker\'s spoken name; it does not validate), `helper`, `error` (a message, or `true`), `disabled`, `buttonLabel` (default "Choose file" / "Choose files"), `buttonVariant` ("primary" | "secondary" | "outlined", the default), `uploadingLabel`, `emptyLabel`, `dropLabel`, `rejectedMessage`, `singleFileMessage`, `unsupportedMessage`, `removeAccessibilityLabel`, `accessibilityLabel`, `style` (the field), `containerStyle`, `testID` (also tags `<testID>-button`, `<testID>-file-<i>` and `<testID>-remove-<i>`). Pass translated copy for every label. Use it rather than a `<FilePicker>` round your own button, file list or "Uploading…" text; when the request needs what it cannot do (a grid of photo thumbnails, a cover image replaced on tap), wrap `<FilePicker>` round your own trigger in the app\'s look and still upload with `useFilestoreUpload`.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3574,6 +3623,21 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // Drag-and-drop: rows reordered and cards moved between columns.
+  {
+    name: "SortableList",
+    description:
+      'A list the user reorders by dragging. `<SortableList items={steps} onReorder={(next) => setSteps(next)} renderItem={({ item }) => <Text>{item.title}</Text>} />` — use it by default for a list the user reorders (a ranking, a playlist, the steps of a routine, priorities); when the request needs what it cannot do (free-form positioning on a canvas, a drag between two widgets, a drop onto a calendar slot, dragging several rows at once), build your own with `Animated` + `PanResponder` from react-native. Each row is a `<ListRow>` (the theme\'s `list` scope; `variant="card"` draws card rows) led by a grip handle that owns the drag on both hosts: the row lifts and follows the finger, the other rows step aside, the gap where it will land shows in the soft primary, and a release settles it there, or springs it back and calls nothing when nothing changed. A tap or Enter on the handle opens its move options (Move up, Move down, Move to top, Move to bottom), so dragging is never the only way; on the web the arrow keys move a focused handle, a screen reader is offered the same moves as actions, and every move is announced. `onReorder(nextItems, { from, to, item })` runs once per real change: show `nextItems` at once and save the new order yourself. Props: `items`, `onReorder`, `renderItem({ item, index, dragging })` (a row\'s content; with none the item\'s title shows), `keyExtractor` (default `item.id`), `getItemLabel` (the name a move announces; default its title, name or label), `canDrag` (a boolean or `(item) => boolean`; a row it refuses has no handle; it is read on every render, so pass `useCanWrite`\'s flag as it is), `variant` "plain" (default) | "card", `labels` (translated words: `handle` "Move {item}", `moveUp`, `moveDown`, `moveToTop`, `moveToBottom`, `moved` "{item} moved to position {position} of {total}", `hint`), `style`, `testID`, `accessibilityLabel`. In a list taller than the screen a drag reaches the rows in view; the move options reach any place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Board",
+    description:
+      'Cards the user moves between columns: a kanban, a pipeline, a status board. `<Board columns={[{ key: "todo", title: t("todo", "To do") }, { key: "done", title: t("done", "Done") }]} items={rows} getColumn={(row) => row[props.statusField]} onMove={(row, { toColumn }) => move(row, toColumn)} renderCard={({ item }) => <Text>{item[props.titleField]}</Text>} canDrag={canWrite} />` — use it by default for cards the user moves between columns; when the request needs what it cannot do (free-form positioning on a canvas, a drag between two widgets, a drop onto a calendar slot, swimlanes in two directions), build your own with `Animated` + `PanResponder` from react-native. Each card is a `<Card>` (the theme\'s `card` scope) with a grip handle. The board hit-tests the drop itself, highlights the one column the card is over in the soft primary with a line where it will land, and on a narrow box lays fixed-width columns in a sideways scroll that scrolls by itself while a card is held at its edge. A tap or Enter on the handle opens its move options (Move up, Move down, Move to <column>), so dragging is never the only way; on the web the arrow keys move a focused card (left and right to the end of the next column), a screen reader is offered the same moves as actions, and every move is announced. `onMove(item, { fromColumn, toColumn, index })` runs once per real change (`index` is its place in the target column); a drag released over no column, or where it started, springs back and calls nothing. The board draws `items` as you pass them, so show a moved card in its new column at once: keep an optimistic map until your write lands and you refetch, and on failure drop it with a toast so the card returns. Props: `columns` (`[{ key, title }]`), `items`, `getColumn(item)` (its column key), `onMove`, `renderCard({ item, index, column, dragging })` (a card\'s content), `keyExtractor`, `getItemLabel`, `canDrag` (a boolean or per item, read on every render), `reorderInColumn` (default true; false when cards keep no order of their own, and a drop in its own column then changes nothing), `columnWidth` (the narrow width of a column, default 280), `labels` (as SortableList, plus `moveToColumn` "Move to {column}" and `movedToColumn` "{item} moved to {column}, position {position}"), `style`, `testID`, `accessibilityLabel`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -6258,7 +6322,15 @@ const CONTRACT = deepFreeze({
   // 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",
+  // 1.202.0: additive (sc-12073, sc-12074, sc-12075, sc-12076) — new
+  //    `<DataTable>`, `<FilterBar>`, `<Form>` / `<FieldRow>` / `<FormSection>`
+  //    / `<FormActions>` / `<FormField>`, `<SortableList>`, `<Board>`;
+  //    `required` on TextField, Select, RadioGroup, PeoplePicker, FileUpload.
+  // 1.203.0: additive (sc-12232) — `<TextField>` takes `leadingIcon`,
+  //    `trailingIcon`, `onTrailingPress`, `trailingAccessibilityLabel` and the
+  //    slots' testIDs; `<SearchField>` draws through them. New warnings
+  //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
+  version: "1.203.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3361,6 +3361,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "DataTable",
+    description:
+      'A list of records laid out for its own width. `<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" }]} rows={data} loading={loading} onRowPress={(row) => open(row.id)} />` — use it by default for a list or table of records (datastore rows): it is 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, from its own measured width, so it needs no tier code of yours. When the table needs what it cannot do (editable cells, grouped or collapsible rows, resizable columns, a pivot), build your own from `<ListHeader>` over a `<List>` of `<ListRow>`s with the same `flex` per column. Columns: `key`, `label`, `flex` (default 1, the same in the header and the rows), `align` ("left" / "center" / "right"), `minWidth`, `sortable`, `render(row, column)` (a string or number becomes the cell\'s text). Props: `columns`, `rows`, `keyField` (default "id"), `renderCell(row, column)` (every cell without its own `render`; return `undefined` for the default), `onRowPress(row)`, `sort` / `defaultSort` (`{ key, direction: "asc" | "desc" }`), `onSortChange(sort)`, `maxHeight` (the rows\' scroll box, default 480), `loading` (placeholder rows while `rows` is empty), `emptyTitle`, `emptyMessage` (an empty state, "No results" by default), `sortLabels` (`{ sort, ascending, descending }` in the widget\'s language), the Lists overrides (`rowPadding`, `gap`, …), `style`, `testID`, `accessibilityLabel`. A sortable header is a 44px button named by its column and described by its sort, and a change of sort is announced once; the card layouts offer the same sort from a menu. With `onSortChange` you order the rows (re-query with the new sort) and the table draws `rows` as given; without it the table sorts them itself (a `Date` value sorts as a date). A controlled `sort` without `onSortChange` is display-only: the rows follow it and the headers are plain labels. The sticky header is filled with the rows\' Lists background, else the theme surface. It is styled by Design > Components > Lists (and Cards for the card layouts).',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Badge",
     description:
@@ -3418,6 +3425,41 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Form",
+    description:
+      'A form laid out in width tiers from its own measured width. `<Form><FieldRow><TextField label="First name" … /><TextField label="Last name" … /></FieldRow><TextField label="Email" required … /><FormActions><Button variant="secondary" title="Cancel" … /><Button title="Save" … /></FormActions></Form>` — use it by default for a widget that captures or edits data: its fields sit one to a line when narrow, two at medium and up to three when wide, and the form is capped near 1000px and centred, so it is never flush left, a narrow strip in an empty page, or a wall of giant inputs. 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 (a `<Banner>`, a paragraph) take the whole line. Its direct children are read, so do not wrap them in a fragment. Props: `children`, `columns` ("auto" — three when wide — or 1–3, the most fields to a line), `maxWidth` (1000 by default, `null` for none, for a form in a side panel), `gap` (a theme spacing name, default "md", or a number), `style` (the outer box), `testID`, `accessibilityLabel`. When the form needs what it cannot do (a multi-step wizard, a form beside a live preview, fields laid over a picture), lay it out yourself in the app\'s look with `useContainerWidth()` and `widthTier()`, keeping the three tiers.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FieldRow",
+    description:
+      'Short related fields on one line inside a `<Form>`: first + last name, city + postal code, expiry + CVC. `<FieldRow><TextField label="City" … /><TextField label="Postal code" … /></FieldRow>`. Up to three fields share the line; when narrow they stack. Props: `children`, `gap`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormSection",
+    description:
+      'A titled group of fields inside a `<Form>`, laid out in the form\'s own columns. `<FormSection title="Payment" description="Charged when the order ships">…</FormSection>`. Group a form past about six fields into sections. The title is a heading for screen readers too, in the subtitle text role; the description is in the helper colour. Props: `title`, `description`, `children`, `gap`, `style`, `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormActions",
+    description:
+      'A form\'s buttons in normal flow after its fields, never over them. `<FormActions><Button variant="secondary" title="Cancel" onPress={cancel} /><Button title="Save" onPress={save} busy={saving} /></FormActions>`. Pass the secondary first and the primary last: at medium and wide they sit in a row at the trailing edge, the primary last; when narrow they stack full-width in the same order, the primary nearest the thumb. Props: `children`, `style`, `testID`. In a `<Modal>`, pass the buttons to its `footer` instead.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "FormField",
+    description:
+      'The label, required mark, helper and error of the form controls, round any control. `<FormField label="Colour" required helper="Shown on the card" error={colourError}><SwatchPicker … /></FormField>`. A control that frames its own label (`<TextField>`, `<Select>`, `<RadioGroup>`, `<PeoplePicker>`, `<FileUpload>`) is handed them instead, so one label is drawn (a prop the control sets itself wins, `disabled={false}` included; the field\'s `testID` goes to the control, or to a wrapper round it when the control has its own); those five also take `required` directly. Any other child is framed here and named to a screen reader: on the web as a group, with the helper or error as its description; on a device the one child itself takes the label (with "Required") as its name and the helper or error as its hint, unless it names itself, when the label speaks the required word. Give that child no label of its own. `required` draws the mark and adds the app\'s "Required" to the spoken name; it does not validate, so pass `error` yourself. Props: `label`, `required`, `helper`, `error`, `disabled`, `span` ("full" takes the form\'s whole line), `style`, `testID`, `children`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Banner",
     description:
@@ -3484,7 +3526,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3505,7 +3547,7 @@ const PRIMITIVES = [
   {
     name: "SearchField",
     description:
-      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it; its glyph and clear control fill the icon slots of `TextField`, so it takes no `leadingIcon` / `trailingIcon`. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3516,6 +3558,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "FilterBar",
+    description:
+      'Search plus facet filters that lay themselves out for their own width. `<FilterBar query={query} onQueryChange={setQuery} facets={[{ key: "status", label: t("status", "Status"), options: [{ value: "open", label: t("open", "Open") }] }]} value={filters} onChange={setFilters} sort={{ options: sortOptions, value: sortBy, onChange: setSortBy }} />` — use it by default for a list\'s search and filters; when the filters need what it cannot do (a date-range facet, a price slider, a map-area filter, saved filter presets), build your own toolbar from `<SearchField>`, `<Select>`, `<Chip>` and `<Modal>` in the same shape. It measures its own unpadded box: medium and wide are ONE toolbar row (the search field taking the free width, one compact `<Select>` per facet whose placeholder reads "Status: Any", then the sort) with each applied facet beneath as a removable chip ("Status: Open") and a "Clear all" that resets the facets and the query; narrow, or a row whose dropdowns would not fit, is the search field plus ONE "Filters · 2" button opening the facets as full-width Selects in a `<Modal>` sheet, applied on Apply (Clear empties the sheet\'s facets and puts its sort back on the first option). The applied chips and "Clear all" show beneath at every width, so a narrow user can drop one filter without the sheet. A facet is `{ key, label, options, multiple?, searchable? }`; `value` is `{ [key]: value }`, a list for a `multiple` facet, and `onChange(next)` fires once per edit with a cleared facet\'s key removed. `onQueryChange(query)` gets the trimmed query once typing pauses (`queryDebounceMs`, default 250) and at once on clear or submit; the search field shows only with it. Both are controlled, so seed `query` and `value` from route params or `useWidgetRoute`. Its parts keep their own looks (Design > Components > Search fields, Inputs, Dropdown menus, Chips, Dialogs); it adds no theme scope. Translate the copy with `t()`: `searchPlaceholder`, `anyText` ("Any"), `filtersText` ("Filters"), `activeCountText` ("{count} active"), `clearAllText`, `applyText`, `clearText`, `activeFiltersText`, `removeText` ("Remove {label}"). Other props: `style` (the outer box), `testID`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "RadioGroup",
     description:
@@ -3548,7 +3597,7 @@ const PRIMITIVES = [
   {
     name: "FileUpload",
     description:
-      'Themed file chooser. `<FileUpload label="Attachments" accept="image/*,.pdf" multiple files={files} onFilesChange={setFiles} />` — the default way to let the user pick files to upload, whether they upload at once or with a form. It is built on `<FilePicker>`: a button (Design > Components > Buttons) inside the app\'s input field (Design > Components > Inputs), the chosen files listed under it with their name, size and a remove control, and the same `label` / `helper` / `error` / `disabled` as every form control. The button opens the system file picker on both hosts and is the only way in on a device; on the web a file can also be dropped onto the field. A picked or dropped file that `accept` rules out is not added and the field shows an error. It uploads nothing itself: call `upload(file)` from `useFilestoreUpload` in `onPick` (or when the form is submitted) and pass `uploading` while it runs; the field then shows a `<Spinner>` with "Uploading…" and locks (no percentage is reported). Props: `accept` (an HTML accept value: "image/*", ".pdf", "application/pdf"), `multiple` (default false: a new pick replaces the file), `files` + `onFilesChange(files)` to own the list (omit both and it keeps its own; pass `files={[]}` to list nothing), `onPick(file)` (an array when `multiple`) once per pick or drop with only the new files, `onRemove(file, index)`, `onReject(files, reason)` (reason "type" for a file `accept` rules out, "count" for the files beyond the first when not `multiple`), `uploading`, `label`, `helper`, `error` (a message, or `true`), `disabled`, `buttonLabel` (default "Choose file" / "Choose files"), `buttonVariant` ("primary" | "secondary" | "outlined", the default), `uploadingLabel`, `emptyLabel`, `dropLabel`, `rejectedMessage`, `singleFileMessage`, `unsupportedMessage`, `removeAccessibilityLabel`, `accessibilityLabel`, `style` (the field), `containerStyle`, `testID` (also tags `<testID>-button`, `<testID>-file-<i>` and `<testID>-remove-<i>`). Pass translated copy for every label. Use it rather than a `<FilePicker>` round your own button, file list or "Uploading…" text; when the request needs what it cannot do (a grid of photo thumbnails, a cover image replaced on tap), wrap `<FilePicker>` round your own trigger in the app\'s look and still upload with `useFilestoreUpload`.',
+      'Themed file chooser. `<FileUpload label="Attachments" accept="image/*,.pdf" multiple files={files} onFilesChange={setFiles} />` — the default way to let the user pick files to upload, whether they upload at once or with a form. It is built on `<FilePicker>`: a button (Design > Components > Buttons) inside the app\'s input field (Design > Components > Inputs), the chosen files listed under it with their name, size and a remove control, and the same `label` / `required` / `helper` / `error` / `disabled` as every form control. The button opens the system file picker on both hosts and is the only way in on a device; on the web a file can also be dropped onto the field. A picked or dropped file that `accept` rules out is not added and the field shows an error. It uploads nothing itself: call `upload(file)` from `useFilestoreUpload` in `onPick` (or when the form is submitted) and pass `uploading` while it runs; the field then shows a `<Spinner>` with "Uploading…" and locks (no percentage is reported). Props: `accept` (an HTML accept value: "image/*", ".pdf", "application/pdf"), `multiple` (default false: a new pick replaces the file), `files` + `onFilesChange(files)` to own the list (omit both and it keeps its own; pass `files={[]}` to list nothing), `onPick(file)` (an array when `multiple`) once per pick or drop with only the new files, `onRemove(file, index)`, `onReject(files, reason)` (reason "type" for a file `accept` rules out, "count" for the files beyond the first when not `multiple`), `uploading`, `label`, `required` (a mark after the label and "Required" in the picker\'s spoken name; it does not validate), `helper`, `error` (a message, or `true`), `disabled`, `buttonLabel` (default "Choose file" / "Choose files"), `buttonVariant` ("primary" | "secondary" | "outlined", the default), `uploadingLabel`, `emptyLabel`, `dropLabel`, `rejectedMessage`, `singleFileMessage`, `unsupportedMessage`, `removeAccessibilityLabel`, `accessibilityLabel`, `style` (the field), `containerStyle`, `testID` (also tags `<testID>-button`, `<testID>-file-<i>` and `<testID>-remove-<i>`). Pass translated copy for every label. Use it rather than a `<FilePicker>` round your own button, file list or "Uploading…" text; when the request needs what it cannot do (a grid of photo thumbnails, a cover image replaced on tap), wrap `<FilePicker>` round your own trigger in the app\'s look and still upload with `useFilestoreUpload`.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3574,6 +3623,21 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // Drag-and-drop: rows reordered and cards moved between columns.
+  {
+    name: "SortableList",
+    description:
+      'A list the user reorders by dragging. `<SortableList items={steps} onReorder={(next) => setSteps(next)} renderItem={({ item }) => <Text>{item.title}</Text>} />` — use it by default for a list the user reorders (a ranking, a playlist, the steps of a routine, priorities); when the request needs what it cannot do (free-form positioning on a canvas, a drag between two widgets, a drop onto a calendar slot, dragging several rows at once), build your own with `Animated` + `PanResponder` from react-native. Each row is a `<ListRow>` (the theme\'s `list` scope; `variant="card"` draws card rows) led by a grip handle that owns the drag on both hosts: the row lifts and follows the finger, the other rows step aside, the gap where it will land shows in the soft primary, and a release settles it there, or springs it back and calls nothing when nothing changed. A tap or Enter on the handle opens its move options (Move up, Move down, Move to top, Move to bottom), so dragging is never the only way; on the web the arrow keys move a focused handle, a screen reader is offered the same moves as actions, and every move is announced. `onReorder(nextItems, { from, to, item })` runs once per real change: show `nextItems` at once and save the new order yourself. Props: `items`, `onReorder`, `renderItem({ item, index, dragging })` (a row\'s content; with none the item\'s title shows), `keyExtractor` (default `item.id`), `getItemLabel` (the name a move announces; default its title, name or label), `canDrag` (a boolean or `(item) => boolean`; a row it refuses has no handle; it is read on every render, so pass `useCanWrite`\'s flag as it is), `variant` "plain" (default) | "card", `labels` (translated words: `handle` "Move {item}", `moveUp`, `moveDown`, `moveToTop`, `moveToBottom`, `moved` "{item} moved to position {position} of {total}", `hint`), `style`, `testID`, `accessibilityLabel`. In a list taller than the screen a drag reaches the rows in view; the move options reach any place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Board",
+    description:
+      'Cards the user moves between columns: a kanban, a pipeline, a status board. `<Board columns={[{ key: "todo", title: t("todo", "To do") }, { key: "done", title: t("done", "Done") }]} items={rows} getColumn={(row) => row[props.statusField]} onMove={(row, { toColumn }) => move(row, toColumn)} renderCard={({ item }) => <Text>{item[props.titleField]}</Text>} canDrag={canWrite} />` — use it by default for cards the user moves between columns; when the request needs what it cannot do (free-form positioning on a canvas, a drag between two widgets, a drop onto a calendar slot, swimlanes in two directions), build your own with `Animated` + `PanResponder` from react-native. Each card is a `<Card>` (the theme\'s `card` scope) with a grip handle. The board hit-tests the drop itself, highlights the one column the card is over in the soft primary with a line where it will land, and on a narrow box lays fixed-width columns in a sideways scroll that scrolls by itself while a card is held at its edge. A tap or Enter on the handle opens its move options (Move up, Move down, Move to <column>), so dragging is never the only way; on the web the arrow keys move a focused card (left and right to the end of the next column), a screen reader is offered the same moves as actions, and every move is announced. `onMove(item, { fromColumn, toColumn, index })` runs once per real change (`index` is its place in the target column); a drag released over no column, or where it started, springs back and calls nothing. The board draws `items` as you pass them, so show a moved card in its new column at once: keep an optimistic map until your write lands and you refetch, and on failure drop it with a toast so the card returns. Props: `columns` (`[{ key, title }]`), `items`, `getColumn(item)` (its column key), `onMove`, `renderCard({ item, index, column, dragging })` (a card\'s content), `keyExtractor`, `getItemLabel`, `canDrag` (a boolean or per item, read on every render), `reorderInColumn` (default true; false when cards keep no order of their own, and a drop in its own column then changes nothing), `columnWidth` (the narrow width of a column, default 280), `labels` (as SortableList, plus `moveToColumn` "Move to {column}" and `movedToColumn` "{item} moved to {column}, position {position}"), `style`, `testID`, `accessibilityLabel`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -6254,7 +6318,15 @@ const CONTRACT = deepFreeze({
   // 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",
+  // 1.202.0: additive (sc-12073, sc-12074, sc-12075, sc-12076) — new
+  //    `<DataTable>`, `<FilterBar>`, `<Form>` / `<FieldRow>` / `<FormSection>`
+  //    / `<FormActions>` / `<FormField>`, `<SortableList>`, `<Board>`;
+  //    `required` on TextField, Select, RadioGroup, PeoplePicker, FileUpload.
+  // 1.203.0: additive (sc-12232) — `<TextField>` takes `leadingIcon`,
+  //    `trailingIcon`, `onTrailingPress`, `trailingAccessibilityLabel` and the
+  //    slots' testIDs; `<SearchField>` draws through them. New warnings
+  //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
+  version: "1.203.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/data-table-logic.js

@@ -0,0 +1,179 @@
+// The `<DataTable>` rules without a renderer: which layout a width gets, how
+// its columns read, and how rows sort. React-free, so both hosts and the SDK's
+// own tests share one answer.
+
+import { widthTier } from "./container-width.js";
+
+/** The rows' scroll box stops here unless `maxHeight` says otherwise. */
+export const DATA_TABLE_DEFAULT_MAX_HEIGHT = 480;
+/** Placeholder rows while the first page loads. */
+export const DATA_TABLE_SKELETON_ROWS = 3;
+/** A sortable header is a button, so it keeps the touch-target floor. */
+export const DATA_TABLE_HEADER_TARGET = 44;
+export const DATA_TABLE_ALIGNS = Object.freeze(["left", "center", "right"]);
+export const DATA_TABLE_LAYOUTS = Object.freeze({
+  narrow: "stacked",
+  medium: "cards",
+  wide: "columns",
+});
+/** The English words a sort is spoken with; a widget passes its own language. */
+export const DEFAULT_SORT_LABELS = Object.freeze({
+  sort: "Sort",
+  ascending: "sorted ascending",
+  descending: "sorted descending",
+});
+
+const JUSTIFY = Object.freeze({ left: "flex-start", center: "center", right: "flex-end" });
+
+function isText(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+function positive(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * The layout a MEASURED width calls for: stacked label/value cards when
+ * narrow, one card per row at medium, aligned columns when wide. An
+ * unmeasured width is "columns", as `widthTier(0)` is "wide".
+ */
+export function dataTableLayout(width) {
+  return DATA_TABLE_LAYOUTS[widthTier(width)];
+}
+
+function normaliseColumn(entry) {
+  const column = typeof entry === "string" ? { key: entry } : entry;
+  if (!column || typeof column !== "object" || !isText(column.key)) return null;
+  return {
+    key: column.key,
+    label: column.label !== undefined && column.label !== null ? column.label : column.key,
+    flex: positive(column.flex, 1),
+    align: DATA_TABLE_ALIGNS.includes(column.align) ? column.align : "left",
+    minWidth: positive(column.minWidth, 0),
+    sortable: column.sortable === true,
+    render: typeof column.render === "function" ? column.render : null,
+  };
+}
+
+/**
+ * The columns as the table draws them. A bare string is a column of that
+ * key; an entry without a key is dropped; a repeated key keeps its first.
+ */
+export function normaliseColumns(columns) {
+  if (!Array.isArray(columns)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of columns) {
+    const column = normaliseColumn(entry);
+    if (!column || seen.has(column.key)) continue;
+    seen.add(column.key);
+    out.push(column);
+  }
+  return out;
+}
+
+/** A `{ key, direction }` sort, or null when it names no column. */
+export function normaliseSort(sort) {
+  if (!sort || typeof sort !== "object" || !isText(sort.key)) return null;
+  return { key: sort.key, direction: sort.direction === "desc" ? "desc" : "asc" };
+}
+
+/** A header tap: a new column sorts ascending, the sorted one flips. */
+export function nextSort(current, key) {
+  const now = normaliseSort(current);
+  const flip = now && now.key === key && now.direction === "asc";
+  return { key, direction: flip ? "desc" : "asc" };
+}
+
+/** The text a cell shows for a record value; nothing for an empty one. */
+export function cellText(value) {
+  if (value === null || value === undefined) return "";
+  if (Array.isArray(value)) return value.map(cellText).filter(Boolean).join(", ");
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    for (const name of ["label", "name", "id"]) {
+      if (typeof value[name] === "string") return value[name];
+    }
+  }
+  return "";
+}
+
+function sortKey(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.getTime();
+  if (typeof value === "boolean") return value ? 1 : 0;
+  const text = cellText(value);
+  return text === "" ? null : text;
+}
+
+function compareKeys(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/**
+ * The rows in `sort` order, as a new array; stable, with empty values last
+ * in either direction. Without a sort, the rows as given.
+ */
+export function sortRows(rows, sort) {
+  const list = Array.isArray(rows) ? rows : [];
+  const by = normaliseSort(sort);
+  if (!by) return list;
+  const sign = by.direction === "desc" ? -1 : 1;
+  return list
+    .map((row, index) => ({ row, index, key: sortKey(row && row[by.key]) }))
+    .sort((a, b) => {
+      if (a.key === null || b.key === null) {
+        return a.key === b.key ? a.index - b.index : a.key === null ? 1 : -1;
+      }
+      return sign * compareKeys(a.key, b.key) || a.index - b.index;
+    })
+    .map((entry) => entry.row);
+}
+
+/** A row's React key: its `keyField` value, else its position. */
+export function rowKey(row, keyField, index) {
+  const value = row && typeof row === "object" ? row[keyField] : undefined;
+  return value !== undefined && value !== null && value !== "" ? String(value) : `row-${index}`;
+}
+
+/** A sortable column's sort state: "none", "ascending" or "descending". */
+export function ariaSortFor(column, sort) {
+  const by = normaliseSort(sort);
+  if (!by || by.key !== column.key) return "none";
+  return by.direction === "desc" ? "descending" : "ascending";
+}
+
+/** A header's spoken name: its label, and the sort when it is the sorted one. */
+export function sortSpokenLabel(label, column, sort, labels = DEFAULT_SORT_LABELS) {
+  const words = sortStateWords(column, sort, labels);
+  return words ? `${label}, ${words}` : label;
+}
+
+/** The words a sorted column's state is spoken with; "" when it is not sorted. */
+export function sortStateWords(column, sort, labels = DEFAULT_SORT_LABELS) {
+  const state = ariaSortFor(column, sort);
+  if (state === "none") return "";
+  return state === "descending" ? labels.descending : labels.ascending;
+}
+
+/** The rows' scroll-box height: a positive number, else the default. */
+export function resolveMaxHeight(maxHeight) {
+  return positive(maxHeight, DATA_TABLE_DEFAULT_MAX_HEIGHT);
+}
+
+/** How a column's content sits across its cell. */
+export function justifyFor(align) {
+  return JUSTIFY[align] || JUSTIFY.left;
+}
+
+/**
+ * Who orders the rows. With `onSortChange` the widget re-queries (server
+ * sort) and the table draws the rows as given; without it the table sorts.
+ */
+export function sortsClientSide(onSortChange) {
+  return typeof onSortChange !== "function";
+}