@colixsystems/widget-sdk 0.210.0 → 0.213.0

package/README.md

@@ -83,8 +83,104 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.210.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.213.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.213.0 (contract 1.172.0)
+
+**New component `<ConfirmDialog>` — the standard "are you sure?".** Widgets asked for confirmation each in their own way (a button that re-labels itself to be pressed twice, a hand-laid Yes / No row), so a delete looked and behaved differently from one widget to the next. `<ConfirmDialog>` is that prompt, built once as a preset of `<Modal>` and `<Button>`:
+
+```jsx
+import { useState } from "react";
+import { ConfirmDialog, Button, useToast } from "@colixsystems/widget-sdk";
+
+function DeleteOrder({ order, onDelete }) {
+  const [asking, setAsking] = useState(false);
+  const { showToast } = useToast();
+  return (
+    <>
+      <Button variant="danger" title="Delete" onPress={() => setAsking(true)} />
+      <ConfirmDialog
+        visible={asking}
+        tone="destructive"
+        title="Delete this order?"
+        message="This cannot be undone."
+        confirmLabel="Delete"
+        onCancel={() => setAsking(false)}
+        onConfirm={async () => {
+          try {
+            await onDelete(order.id);
+          } catch (err) {
+            showToast({ kind: "error", message: err.message });
+          }
+          setAsking(false);
+        }}
+      />
+    </>
+  );
+}
+```
+
+Props: `visible`, `title` (the question), `message` (what confirming does; text is drawn in the theme's body style, any other node as it is), `confirmLabel` and `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel` and `testID` (the parts take `-message`, `-cancel`, `-confirm` and `-busy`, plus the Modal's own).
+
+- **Cancelling is the safe default.** The Cancel button, the close button, a backdrop press, Escape on web and the Android back button all fire `onCancel`, never `onConfirm`.
+- **`tone="destructive"`** draws the confirm button as the danger `<Button>`, so it takes its colours from the theme's `destructive` scope (Design > Components > Destructive), and on web opens with focus on Cancel. `default` draws the primary button and opens with focus on Confirm. Focus placement is web only.
+- **Busy.** Return the action's promise from `onConfirm` and the dialog stays busy until it settles: both buttons are disabled, a `<Spinner>` shows, nothing dismisses the dialog, and a second press is ignored. Pass `busy` yourself when the action runs elsewhere; the two combine. A rejected promise is **not** caught: handle the failure inside `onConfirm`, otherwise it is reported as an unhandled rejection. Either way the dialog becomes usable again.
+- **It never closes itself.** Set `visible` to false from `onCancel` and once the action is done.
+- **Labels follow the app's language.** Unset, the buttons read the app's shared `confirm`, `cancel` and `close` translations (the same ones `useI18n().t("cancel")` resolves), falling back to English. Prefer a `confirmLabel` that names the action: "Delete", "Remove", "Send".
+
+It adds no theme scope: the panel follows `modal`, the actions `button`, a destructive confirm `destructive`. `<Button>` now forwards a `ref` to its pressable, which is how the dialog places focus. Additive.
+
+### What's new in 0.212.0 (contract 1.171.0)
+
+**Standard form controls: `Checkbox`, `Switch`, `Select` and `SearchField`.** Only text entry had a themed component, so every widget drew its own tick boxes, toggles, dropdowns and search boxes. Four controls now sit beside `TextField`, each one view bound to both hosts, and all five share one frame: `label` draws the control's label and names it for a screen reader (pressing a field's label focuses it), `helper` a hint below, `error` a message in the hint's place that also marks the control (`true` marks it without a message), and `disabled` stops input.
+
+```jsx
+<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />
+<Select
+  label="Status"
+  value={status}
+  onValueChange={setStatus}
+  options={[{ value: "open", label: "Open" }, { value: "done", label: "Done" }]}
+/>
+<Checkbox label="Urgent only" value={urgent} onValueChange={setUrgent} />
+<Switch label="Notify me" value={notify} onValueChange={setNotify} />
+```
+
+**What existing widgets will look different.** `Switch` was already exported, as React Native's switch with the platform's default colours. It is now themed, so every existing `<Switch>` that passes no colours is repainted when this ships, in published and generated widgets alike:
+
+| | Before | Now |
+| --- | --- | --- |
+| Web, off track | `#939393` | the theme's border colour |
+| Web, on track | `#A3D3CF` | the theme's primary colour |
+| Web, on thumb | teal `#009688` | white |
+| Web, off thumb | `#FAFAFA` | unchanged |
+| Web, disabled | the host's grey track and thumb | the themed colours at half opacity |
+| iOS and Android, tracks | the platform's defaults | the theme's border (off) and primary (on) |
+| iOS and Android, thumb | the platform's default | unchanged |
+| iOS and Android, disabled | the platform's greyed switch | unchanged |
+
+Three smaller changes reach switches that do pass something:
+
+- **Web, `thumbColor` without `activeThumbColor`:** the "on" thumb was the host's teal and is now the `thumbColor` you passed.
+- **Web, a partial `trackColor`** (`{ true: "#0a0" }`, a string, or `activeTrackColor` alone): the state you did not name was the host's default and is now the theme's.
+- **iOS and Android, a truthy non-boolean `value`** (`value={1}`): it was off, because React Native's switch is on only for `true`, and is now on, as it already was on the web.
+
+A switch that passes its own colours keeps them, disabled or not: a `trackColor` overrides the theme for the states it names (`{ true: "#0a0" }` still gets the themed off track), the web's `activeTrackColor` and string `trackColor` are still read, and iOS's off colour follows `trackColor.false` unless `ios_backgroundColor` is passed. A disabled switch that brings its own colours is drawn exactly as before on the web, at full strength; only one that left its colours to the theme is dimmed there. Layout does not change: a switch with no `label`, `helper` or `error` renders the bare control. Nothing else that existed before changes appearance; a `TextField` with none of the new props renders exactly what it did.
+
+- **`Checkbox`**: `value` / `onValueChange(next)`. One 44px row with the checkbox role and checked state on both hosts; Space toggles it on the web. The box is the input surface and fills with the primary colour when checked. `style` is the row, `containerStyle` the box around a row that shows a helper or error; other props and the ref land on the row.
+- **`Switch`**: the platform's own switch (React Native's `Switch`), so each host keeps its role, state and keys. A device greys a disabled switch itself; on the web a disabled switch is drawn at half strength unless it brings its own colours. With a `label`, `helper` or `error` it draws a row whose label toggles it too.
+- **`Select`**: `options` (`[{ value, label, disabled?, testID? }]`), `value`, `onValueChange(value, option)`, `placeholder`, `title`, `emptyText`. The trigger is the input field, exposed as a button that opens a dialog (`aria-haspopup`, `aria-expanded`). Its options open through `Overlay`, at screen level, each with the option role and a selected state on both hosts (the list around them is a `listbox` on the web only; React Native has no such role), so a card or scroll container cannot clip them, and a long list scrolls inside the sheet. On the web Enter, Space or an arrow key opens it, the arrow keys, Home and End move between options, Enter or Space chooses, Escape closes, and focus returns to the trigger; on Android the back button closes it. Other props and the ref land on the trigger.
+- **`SearchField`**: a `TextField` with a search glyph, the search key on the on-screen keyboard (`enterKeyHint="search"`, overridable) and a clear control that appears once there is text. Clearing calls `onChangeText("")`, then `onClear`, and keeps focus in the field. `style` styles the input and `containerStyle` the box around it.
+- **`TextField`** gains `label`, `helper`, `error`, `disabled` and `containerStyle`. An invalid field keeps its danger border while focused.
+- **`spaceActivates(onPress)`**: the `onKeyDown` handler the controls use to answer Space on the web, for a control you build yourself whose role is not a button. It fires once per key press and is ignored on native.
+
+**Theming.** No new scope. All five read **Design > Components > Muted** for the field (background, text colour, border, corner radius, height) and show focus in the primary colour, as `TextField` always has: a field and a Select trigger in their own border, a checkbox and a labelled switch as a 2px ring around the control whose width is always reserved, so focusing moves nothing. A bare switch keeps the host's own focus indication. The Select's option sheet reads **Popover** (background, text colour, border). In the contract, `muted` and `popover` now list these components under `sdkComponents` next to the form widgets they already targeted. The `ring` scope is the Button widget's emphasis border and is not read by these controls.
+
+**Known limits.** On a device a long option list does not scroll to the current choice when it opens (the web does, through focus). A helper or error is linked to its control with `aria-describedby` on the web, for all five controls; a device's screen reader reads it in place, and Android announces an error when it appears.
+
+The built-in Data List, Files and User Management widgets and the form widgets' user and group pickers now draw their search boxes with `SearchField`.
+
+- **`CONTRACT.version` → `1.171.0`** (`Checkbox`, `Select`, `SearchField`, `spaceActivates`; the `TextField` frame props; `sdkComponents` on `muted` and `popover`; and the visible change to `Switch` described above).
 ### What's new in 0.210.0 (contract 1.169.0)
 
 **New component `<Modal>` — the standard dialog.** Widgets that opened a dialog each built their own header, close button and action row inside a bare `<Overlay>`, so no two dialogs in an app matched and none could be restyled from the theme. `<Modal>` is that dialog, built once on `<Overlay>`:
@@ -2499,6 +2595,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.
+- `ConfirmDialog` — the standard confirmation prompt, a preset of `Modal` and `Button`. `<ConfirmDialog visible={asking} tone="destructive" title="Delete this order?" message="This cannot be undone." confirmLabel="Delete" onCancel={() => setAsking(false)} onConfirm={removeOrder} />` asks before a delete or any other action that cannot be undone. Cancel, the close button, the backdrop, Escape and the Android back button fire `onCancel`; a promise returned from `onConfirm` keeps it busy (buttons disabled, a second press ignored) until it settles. Props: `visible`, `title`, `message`, `confirmLabel`, `cancelLabel`, `tone` (`default` | `destructive`), `busy`, `onConfirm`, `onCancel`, `closeAccessibilityLabel`, `testID`. Use it instead of building a confirmation from `Modal` yourself.
 - `Modal` — the standard dialog, built on `Overlay`. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<Button title="Save" onPress={save} />}>…</Modal>` draws a title, a close button, a body that scrolls when it is long and a footer action row laid out below it. Its background, corner radius, padding, scrim, shadow and title colour come from the theme's `modal` scope (Design > Components > Dialogs), so every dialog in an app matches. Props: `visible`, `onRequestClose`, `dismissible`, `title`, `footer`, `presentation` (`dialog` | `sheet`), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `role`, `initialFocusRef`, `closeAccessibilityLabel`, `accessibilityLabel`, `testID`. Use it for every dialog instead of hand-building a header and an action row inside `Overlay`.
 - `RichText` — the formatted-content renderer (sc-6970). `<RichText value={post.body} />` parses the markdown subset (`**bold**`, `*italic*` / `_italic_`, `` `code` ``, `#`/`##`/`###` headings, `-`/`*` bullets, `1.` ordered items, one-line `![alt](src "large")` images) and renders it with SDK primitives, so formatted content reads the same in the web Player and the exported Expo app. `value` is markdown, NOT HTML — widgets have no `dangerouslySetInnerHTML` on either host, so tags in a content string render as literal tag soup; stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. Props: `value`, `renderImage` (`({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving one needs the scopes your own widget holds; without it only absolute `http(s)` URLs render), `style`, `testID`. Colour, type scale and leading come from the workspace theme — never re-style them.
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.
@@ -2510,6 +2607,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
+- `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, single-choice picker and search box. Like `TextField` they follow the theme's `muted` scope (and `popover` for the Select's option sheet) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level. Never hand-roll one from `Pressable` and `View`.
 - `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
@@ -2541,7 +2639,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
-- **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
+- **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Put any other icon or unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

package/dist/button-view.js

@@ -100,8 +100,9 @@ export function makeButton(rn) {
    * @param {boolean} [props.hostThemed] — `fields` already carry the theme
    *   (a built-in the host folded); skip the second fold, which would add the
    *   Button widget's own scopes to a form submit or a Link action.
+   * @param {object} ref — forwarded to the pressable, so a caller can focus it.
    */
-  function Button({
+  const Button = React.forwardRef(function Button({
     title,
     variant = "primary",
     icon,
@@ -114,7 +115,7 @@ export function makeButton(rn) {
     hostThemed = false,
     accessibilityLabel,
     testID,
-  }) {
+  }, ref) {
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const { colors, spacing, radii, typography } = theme;
     const f = hostThemed
@@ -192,6 +193,7 @@ export function makeButton(rn) {
     return React.createElement(
       Pressable,
       {
+        ref,
         onPress,
         disabled,
         accessibilityRole: "button",
@@ -202,7 +204,7 @@ export function makeButton(rn) {
       },
       children,
     );
-  }
+  });
 
   Button.displayName = "Button";
   return Button;

package/dist/checkbox-view.js

@@ -0,0 +1,150 @@
+// The ONE implementation behind the `<Checkbox>` SDK primitive. The platform
+// bindings (`checkbox.js` / `checkbox.native.js`) differ only in where the
+// primitives come from, so the hosts cannot drift.
+//
+// Widgets each drew their own tick box, so one control looked different per
+// widget. This one follows the theme's `muted` scope.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
+import {
+  CHECKBOX_MAX_RADIUS,
+  CHECKBOX_SIZE,
+  CONTROL_MIN_TARGET,
+  focusHaloStyle,
+  resolveFormControlTokens,
+} from "./form-control-tokens.js";
+import {
+  errorMessage,
+  hasNote,
+  isShown,
+  isText,
+  spaceActivates,
+  spokenLabel,
+} from "./form-control-logic.js";
+import { makeFieldFrame } from "./form-control-view.js";
+
+const h = React.createElement;
+
+/**
+ * Bind the shared checkbox to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any}} rn
+ */
+export function makeCheckbox(rn) {
+  const { View, Text, Pressable } = rn;
+  const FieldFrame = makeFieldFrame(rn);
+
+  const Checkbox = React.forwardRef(function Checkbox(props, ref) {
+    const {
+      value = false,
+      onValueChange,
+      label,
+      helper,
+      error,
+      disabled = false,
+      accessibilityLabel,
+      style,
+      containerStyle,
+      onFocus,
+      onBlur,
+      ...rest
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const t = resolveFormControlTokens(theme);
+    const [focused, setFocused] = React.useState(false);
+    const noteId = React.useId();
+    const checked = Boolean(value);
+    const invalid = isShown(error);
+    const noted = hasNote({ helper, error });
+    const radius = Math.min(t.radius, CHECKBOX_MAX_RADIUS);
+    const toggle = () => {
+      if (!disabled && typeof onValueChange === "function") onValueChange(!checked);
+    };
+
+    const row = h(
+      Pressable,
+      {
+        ...rest,
+        ref,
+        onPress: toggle,
+        onKeyDown: spaceActivates(toggle),
+        onFocus: (event) => {
+          setFocused(true);
+          if (typeof onFocus === "function") onFocus(event);
+        },
+        onBlur: (event) => {
+          setFocused(false);
+          if (typeof onBlur === "function") onBlur(event);
+        },
+        disabled,
+        // accessibilityRole + aria-*: the pair that announces on both hosts.
+        accessibilityRole: "checkbox",
+        "aria-checked": checked,
+        "aria-disabled": disabled,
+        ...(invalid ? { "aria-invalid": true } : null),
+        ...(noted ? { "aria-describedby": noteId } : null),
+        accessibilityLabel: spokenLabel(accessibilityLabel, label),
+        style: [
+          {
+            flexDirection: "row",
+            alignItems: "center",
+            gap: t.rowGap,
+            minHeight: CONTROL_MIN_TARGET,
+            minWidth: CONTROL_MIN_TARGET,
+          },
+          // The frame dims a noted checkbox as a whole.
+          disabled && !noted ? { opacity: t.disabledOpacity } : null,
+          style,
+        ],
+      },
+      h(
+        View,
+        { style: focusHaloStyle(t, focused, radius) },
+        h(
+          View,
+          {
+            style: {
+              width: CHECKBOX_SIZE,
+              height: CHECKBOX_SIZE,
+              alignItems: "center",
+              justifyContent: "center",
+              borderWidth: 1,
+              borderRadius: radius,
+              borderColor: checked ? t.accent : invalid ? t.errorColor : t.borderColor,
+              backgroundColor: checked ? t.accent : t.background,
+            },
+          },
+          checked ? h(Icon, { name: "check", size: 16, color: t.onAccent }) : null,
+        ),
+      ),
+      isText(label)
+        ? h(
+            Text,
+            {
+              style: {
+                flexShrink: 1,
+                color: t.labelColor,
+                fontFamily: t.fontFamily,
+                fontSize: t.fontSize,
+              },
+            },
+            label,
+          )
+        : isShown(label)
+          ? label
+          : null,
+    );
+    if (!noted) return row;
+    return h(
+      FieldFrame,
+      { t, helper, error: errorMessage(error), disabled, noteId, style: containerStyle },
+      row,
+    );
+  });
+
+  Checkbox.displayName = "Checkbox";
+  return Checkbox;
+}

package/dist/checkbox.js

@@ -0,0 +1,11 @@
+// `<Checkbox>` (web). Binds ./checkbox-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeCheckbox } from "./checkbox-view.js";
+
+export const Checkbox = makeCheckbox({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+});

package/dist/checkbox.native.js

@@ -0,0 +1,7 @@
+// `<Checkbox>` (native). Binds ./checkbox-view.js to React Native's own
+// primitives; only the import differs from ./checkbox.js.
+
+import { View, Text, Pressable } from "react-native";
+import { makeCheckbox } from "./checkbox-view.js";
+
+export const Checkbox = makeCheckbox({ View, Text, Pressable });

package/dist/confirm-dialog-view.js

@@ -0,0 +1,158 @@
+// The ONE implementation behind the `<ConfirmDialog>` SDK component: a preset
+// of `<Modal>` holding a message, a Cancel and a Confirm `<Button>`.
+//
+// Bound per host by confirm-dialog.js / confirm-dialog.native.js, which differ
+// only in where the primitives come from, so the two hosts cannot drift.
+
+import React from "react";
+import { useHostSharedText, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+
+function isThenable(value) {
+  return value != null && typeof value.then === "function";
+}
+
+function isText(value) {
+  return typeof value === "string" || typeof value === "number";
+}
+
+/**
+ * Bind the shared confirmation to one platform's primitives and to that
+ * host's `<Modal>`, `<Button>` and `<Spinner>`.
+ *
+ * @param {{Text: any}} rn
+ * @param {any} Modal — the host's bound `<Modal>`.
+ * @param {any} Button — the host's bound `<Button>`.
+ * @param {any} Spinner — the host's bound `<Spinner>`.
+ */
+export function makeConfirmDialog(rn, Modal, Button, Spinner) {
+  const { Text } = rn;
+
+  // Rendered inside the Modal, so it reads the theme the Modal re-inks.
+  function Message({ testID, children }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    return React.createElement(
+      Text,
+      { testID, style: textRoleStyle("body", theme.typography, theme.colors) },
+      children,
+    );
+  }
+
+  /**
+   * The standard "are you sure?" prompt. Cancelling is the safe default: the
+   * close button, the backdrop, Escape (web) and the Android back button all
+   * fire `onCancel`, never `onConfirm`.
+   *
+   * @param {object} props
+   * @param {boolean} [props.visible] — nothing is mounted while false.
+   * @param {string} props.title — the question, e.g. "Delete this order?".
+   * @param {any} [props.message] — what confirming does; text is drawn in the
+   *   theme's body style, any other node is rendered as it is.
+   * @param {string} [props.confirmLabel] — default the app's "Confirm".
+   * @param {string} [props.cancelLabel] — default the app's "Cancel".
+   * @param {"default"|"destructive"} [props.tone] — `destructive` draws the
+   *   confirm button from the theme's Destructive colours and, on web, opens
+   *   with focus on Cancel; `default` opens with focus on Confirm.
+   * @param {boolean} [props.busy] — the confirmed action is running: both
+   *   buttons are disabled, a loading indicator shows, nothing closes it.
+   * @param {() => void|Promise<any>} [props.onConfirm] — a returned promise
+   *   keeps the dialog busy until it settles. A rejection is not caught.
+   * @param {() => void} [props.onCancel]
+   * @param {string} [props.closeAccessibilityLabel] — default the app's "Close".
+   * @param {string} [props.testID] — on the panel; the parts take `-message`,
+   *   `-cancel`, `-confirm` and `-busy`, plus the Modal's own.
+   */
+  function ConfirmDialog({
+    visible = false,
+    title,
+    message,
+    confirmLabel,
+    cancelLabel,
+    tone = "default",
+    busy = false,
+    onConfirm,
+    onCancel,
+    closeAccessibilityLabel,
+    testID,
+  }) {
+    const sharedConfirm = useHostSharedText("confirm", "Confirm");
+    const sharedCancel = useHostSharedText("cancel", "Cancel");
+    const sharedClose = useHostSharedText("close", "Close");
+    const [pending, setPending] = React.useState(false);
+    // Set before the re-render, so a second press in the same frame is ignored.
+    const inFlight = React.useRef(false);
+    const cancelRef = React.useRef(null);
+    const confirmRef = React.useRef(null);
+
+    const working = busy || pending;
+    const destructive = tone === "destructive";
+    const part = (name) => (testID ? `${testID}-${name}` : undefined);
+
+    const confirm = () => {
+      if (working || inFlight.current || typeof onConfirm !== "function") return;
+      const result = onConfirm();
+      if (!isThenable(result)) return;
+      inFlight.current = true;
+      setPending(true);
+      const settle = () => {
+        inFlight.current = false;
+        setPending(false);
+      };
+      result.then(settle, (error) => {
+        settle();
+        // Rethrown so a failure the caller did not handle is still reported.
+        throw error;
+      });
+    };
+
+    const cancel = () => {
+      if (working || inFlight.current) return;
+      if (typeof onCancel === "function") onCancel();
+    };
+
+    const footer = React.createElement(
+      React.Fragment,
+      null,
+      working ? React.createElement(Spinner, { testID: part("busy") }) : null,
+      React.createElement(Button, {
+        ref: cancelRef,
+        variant: "secondary",
+        title: cancelLabel ?? sharedCancel,
+        onPress: cancel,
+        disabled: working,
+        testID: part("cancel"),
+      }),
+      React.createElement(Button, {
+        ref: confirmRef,
+        variant: destructive ? "danger" : "primary",
+        title: confirmLabel ?? sharedConfirm,
+        onPress: confirm,
+        disabled: working,
+        testID: part("confirm"),
+      }),
+    );
+
+    return React.createElement(
+      Modal,
+      {
+        visible,
+        title,
+        footer,
+        role: "alertdialog",
+        size: "sm",
+        dismissible: !working,
+        onRequestClose: cancel,
+        initialFocusRef: destructive ? cancelRef : confirmRef,
+        closeAccessibilityLabel: closeAccessibilityLabel ?? sharedClose,
+        testID,
+      },
+      isText(message)
+        ? React.createElement(Message, { testID: part("message") }, message)
+        : message,
+    );
+  }
+
+  ConfirmDialog.displayName = "ConfirmDialog";
+  return ConfirmDialog;
+}

package/dist/confirm-dialog.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (web). Binds ./confirm-dialog-view.js to react-native-web
+// and the web `<Modal>`, `<Button>` and `<Spinner>`; see ./primitives.js for
+// why not the bare specifier.
+
+import { Text } from "react-native-web";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.js";
+import { Button } from "./button.js";
+import { Spinner } from "./loading.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);

package/dist/confirm-dialog.native.js

@@ -0,0 +1,11 @@
+// `<ConfirmDialog>` (native). Binds ./confirm-dialog-view.js to React Native's
+// own primitives and the native `<Modal>`, `<Button>` and `<Spinner>`; only the
+// imports differ from ./confirm-dialog.js.
+
+import { Text } from "react-native";
+import { makeConfirmDialog } from "./confirm-dialog-view.js";
+import { Modal } from "./modal.native.js";
+import { Button } from "./button.native.js";
+import { Spinner } from "./loading.native.js";
+
+export const ConfirmDialog = makeConfirmDialog({ Text }, Modal, Button, Spinner);