@vvedantb/native-ui 0.4.0 → 0.5.0

package/README.md

@@ -61,18 +61,18 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@vvedantb/native-ui/tab-bar` | `FloatingTabBar`, `FloatingTabBarProps`, `FLOATING_INSET`, `FLOATING_TAB_BAR_HEIGHT`, `FLOATING_TAB_BAR_HEIGHT_LARGE`, `tabBarReserve` | `expo-blur`, `expo-haptics` (loaders) |
 | `@vvedantb/native-ui/brand` | `AppMark`, `AppWordmark`, `GoogleMark` (from 0.3.15), `APP_ICONS`, `IconVibot` and the other `Icon*`, the SVG helpers (`APP_MARKS`, `appMarkSvg`, `appTileSvg` and the rest), `FAMILY_APPS`, `familyApp`, `V_PRO_APP_BENEFITS` | none |
 | `@vvedantb/native-ui/button` | `Button`, `ButtonProps`, `ButtonSize`, `ButtonVariant` | none |
-| `@vvedantb/native-ui/primitives` | `Button`, `Input`, `SearchInput`, `Textarea`, `Label`, `Select`, `Switch`, `LabeledSwitchRow`, `Checkbox`, `Card` and its parts, `Badge`, `StatusDot`, `Avatar`, `Separator`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`, `ListRow`, `Chip`, `HeaderIconButton`, `ThemeToggle` (from 0.3.16), `Tabs`, `PillTabs`, `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet`, `toast`, `Toaster` | `expo-blur`, `expo-haptics` (loaders) |
+| `@vvedantb/native-ui/primitives` | `Button`, `Input`, `SearchInput`, `Textarea`, `Label`, `Select`, `Switch`, `LabeledSwitchRow`, `Checkbox`, `Card` and its parts, `Badge`, `StatusDot`, `Avatar`, `Separator`, `Progress`, `Spinner`, `Skeleton`, `EmptyState`, `ListRow`, `Chip`, `HeaderIconButton`, `ThemeToggle` (from 0.3.16), `Tabs`, `PillTabs`, `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet`, `toast`, `Toaster`. From 0.5.0: `Text` and `TextClassContext` (only here, not on the root), `ColorSwatches`, `StatGrid`, `SectionLabel`, `SheetRow`, `PageIndicator`, `IconButton`, `CaptureButton`, and the `ListRowProps` and `CardProps` types | `expo-blur`, `expo-haptics` (loaders) |
 | `@vvedantb/native-ui/search-input` | `SearchInput`, `SearchInputProps` | none |
-| `@vvedantb/native-ui/page-title` | `PageTitle`, `PageHeader`, `PageTitleProps`, `PageHeaderProps` (from 0.3.13) | none |
+| `@vvedantb/native-ui/page-title` | `PageTitle`, `PageHeader`, `PageTitleProps`, `PageHeaderProps` (from 0.3.13), `StackPageHeader`, `StackPageHeaderProps` (from 0.5.0; it brings the Tabler package for its chevron) | none |
 | `@vvedantb/native-ui/toast` | `toast`, `Toaster`, `ToastOptions`, `ToastVariant` | none (from 0.3.12) |
 | `@vvedantb/native-ui/theme` | `NativeUiProvider`, `useNativeUi`, `useLargerText`, `useAccentColor`, `DEFAULT_ACCENT`, `tokens`, `palette`, `withAlpha`, `fontClass`, `cn`, `Colors` and the colour constants | none |
 | `@vvedantb/native-ui/floating` | `FloatingSurface`, `GlassSheetBackground`, `LiquidGlass`, `GlassBlurProvider`, `GlassBlurTarget`, `FloatingFAB`, `useReduceTransparency`, the floating metrics and styles | `expo-blur` (loader) |
-| `@vvedantb/native-ui/layout` | `ScreenContainer`, `SafeAreaContainer`, `PageTitle`, `PageHeader` and their props types, `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack` | `expo-blur` (loader) |
+| `@vvedantb/native-ui/layout` | `ScreenContainer`, `SafeAreaContainer`, `PageTitle`, `PageHeader`, `StackPageHeader` (0.5.0) and their props types, `SectionLabel` (0.5.0), `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack` | `expo-blur` (loader) |
 | `@vvedantb/native-ui/marketing` | `UpgradeToProCard`, `PricingModal` and the pricing types | none |
 | `@vvedantb/native-ui/ambient` | `AmbientBackground` | `expo-linear-gradient` (loader) |
 | `@vvedantb/native-ui/blur`, `/haptics` | the loaders | `expo-blur`, `expo-haptics` (loaders) |
 | `@vvedantb/native-ui/bottom-sheet` | `BottomSheetContainer` | `@gorhom/bottom-sheet` (import), `expo-blur` (loader) |
-| `@vvedantb/native-ui/date-time` | `DateTimeField` | `@react-native-community/datetimepicker`, `dayjs` (import) |
+| `@vvedantb/native-ui/date-time` | `DateTimeField`, `DateTimeFieldProps` (0.5.0) | `@react-native-community/datetimepicker`, `dayjs` (import) |
 | `@vvedantb/native-ui/ai` | The AI chat parts (from 0.4.0): `Conversation`, `Message`, `Reasoning`, `AgentTrace`, `ChainOfThought`, `ActivityStep`, `PromptInput`, `Suggestions`, `Sources`, `FileChip`, `Attachments`, `CodeBlock`, `ResponseText`, `Shimmer`, `Collapsible`, `useStreamingDisclosure` and their parts. See [AI chat](#ai-chat-040). Not on the root entry. | none |
 | `@vvedantb/native-ui/ai-gallery` | `AiChatGallery`, `AiChatSamples` (from 0.4.0) | none |
 
@@ -93,10 +93,11 @@ The entries re-export the same source files, so they can be mixed: `NativeUiProv
 
 ## Expo / NativeWind
 
-Source-exported. Point Tailwind at the package so class names are generated:
+Source-exported. Point Tailwind at the package so class names are generated, and set `darkMode: "class"` (see [Theme](#theme)):
 
 ```js
 // tailwind.config.js
+darkMode: "class",
 content: [
   "./app/**/*.{js,ts,tsx}",
   "./components/**/*.{js,ts,tsx}",
@@ -115,10 +116,26 @@ config.resolver.nodeModulesPaths = [
 ];
 ```
 
-The app must define NativeWind tokens (`bg-surface`, `bg-secondary`, pink utilities) and Instrument Sans font classes (`font-instrument-sans-*`). Accent pink stays in the app stylesheet. `Button`, `Input`, `Textarea`, the `Select` trigger, `Switch`, `Checkbox`, `Badge`, `Tabs` and `PillTabs` take their colours from `tokens` and `palette`, so they do not need `primary`, `input` or other theme keys. From 0.3.3 so does component text (titles, descriptions, labels, rows, toasts): it no longer uses `text-foreground` or `text-muted-foreground`, which stay light-mode colours in dark mode when an app defines `foreground` with a nested `dark` key. Override those colours with `style`, not `className`. App text needs the same care: `tokens.color.foreground[scheme]` reads in both schemes.
+The app must define NativeWind tokens (`bg-surface`, `bg-secondary`, pink utilities) and Instrument Sans font classes (`font-instrument-sans-*`). Accent pink stays in the app stylesheet. `Button`, `Input`, `Textarea`, the `Select` trigger, `Switch`, `Checkbox`, `Badge`, `Tabs` and `PillTabs` take their colours from `tokens` and `palette`, so they do not need `primary`, `input` or other theme keys. From 0.3.3 so does component text (titles, descriptions, labels, rows, toasts): it no longer uses `text-foreground` or `text-muted-foreground`, which stay light-mode colours in dark mode when an app defines `foreground` with a nested `dark` key. Override those colours with `style`, not `className`. App text needs the same care: `tokens.color.foreground[scheme]` reads in both schemes. From 0.5.0 the `ListRow`, `DateTimeField` and `HeaderIconButton` fills are styles too, so `ThemeToggle` and the `StackPageHeader` back button follow the scheme.
 
 From 0.3.5 text that uses `font-instrument-sans-medium` or `-semibold` also sets `fontWeight` as a style (`typeStyle` in `src/controlStyles.ts`). Where an app maps every `font-instrument-sans-*` class to one family with no weight, as Expo web does, the class alone draws Regular. A weight without the face class does not pick the Instrument Sans Medium or Semibold file, so set both. From 0.3.13 every title in the package pairs the two, the internal primitives included, and `tests/fontWeight.test.ts` fails on a face class without its weight, a weight without its face class, or a bare Tailwind `font-medium`, `font-semibold` or `font-bold`.
 
+The app loads the font; the package does not. On Expo web, one variable family covers every weight. `@vvedantb/ui` ships the woff2 files (400–700, latin and latin-ext) in `fonts/`. Expo web CSS does not bundle relative `url()`s, so copy the files to the app's `public/fonts/` and copy the `@font-face` rules from `@vvedantb/ui/fonts/instrument-sans.css` with `url("/fonts/…")`. Then map all four classes to that family with a sans-serif fallback, as the components set the weight:
+
+```js
+// tailwind.config.js (Expo web)
+const instrumentSans = ["Instrument Sans", "system-ui", "sans-serif"];
+// theme.extend.fontFamily:
+fontFamily: {
+  "instrument-sans": instrumentSans,
+  "instrument-sans-medium": instrumentSans,
+  "instrument-sans-semibold": instrumentSans,
+  "instrument-sans-bold": instrumentSans,
+},
+```
+
+A class mapped to a family the browser does not have, such as `["System"]`, with no generic fallback draws in the browser default, often a serif.
+
 ## Theme
 
 Wrap the tree (inside your colour-scheme provider):
@@ -133,16 +150,20 @@ import { NativeUiProvider, Button, Card } from "@vvedantb/native-ui";
 </NativeUiProvider>
 ```
 
+**Dark mode needs `darkMode: "class"`.** Every component reads the scheme with NativeWind's `useColorScheme()` (`useScheme` in `src/useScheme.ts`) and takes its colours from `tokens` and `palette` for it; the AI composer and code block do too. `ThemeToggle`, and any `setColorScheme` call in the app, need `darkMode: "class"` in `tailwind.config.js`. Under Tailwind's default, `media`, NativeWind's `setColorScheme` throws ("Unable to manually set color scheme without using darkMode: class"), on web and native. The scheme then stays on the system setting, and the components keep the light colours, even where the app paints its own page dark.
+
+**Switch the scheme through NativeWind only.** Call `useColorScheme().setColorScheme("dark"|"light")` (or use `ThemeToggle`). That updates `useScheme` and, with `darkMode: "class"`, the `<html>` class together. Do **not** toggle `document.documentElement.classList` (or a page-level CSS `.dark` rule) by hand while leaving NativeWind on light: the page background can go dark while every token-styled part stays on the light set. That dual-owner fault is an app bug, not a native-ui colour bug.
+
 `useLargerText()` steps type and tap targets up. Without it, `Button`, `Input`, `Textarea` and the `Select` trigger have the web sizes (`Button` 32 / 40 / 44 high, fields 40); with it they keep the larger 0.3.2 sizes. `accentColor` tints FABs, card icons and progress bars (checked checkboxes use the palette primary, as on the web). Surfaces use the tokens in `src/tokens.ts` for fill, radius (card 24, button 16, field 10, pill 999; rows 20) and spacing (16).
 
 ## Components (0.3.0)
 
 | Area | Exports |
 | --- | --- |
-| Actions and fields | `Button` (`default`/`primary`, `secondary`, `outline`, `destructive`, `ghost`, `link`, `tinted`; `sm`/`small`, `default`/`medium`, `lg`/`large`, `icon`), `Input`, `SearchInput` (0.3.9), `Textarea`, `Label`, `Select`, `Switch`, `Checkbox`, `LabeledSwitchRow`, `DateTimeField` |
-| Display | `Card` (+ `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`), `Badge`, `StatusDot`, `Avatar` (+ `AvatarImage`, `AvatarFallback`, `initials()`), `Separator`, `Progress`, `Spinner`, `CenteredSpinner`, `Skeleton`, `EmptyState` (+ `EmptyState.Root` and parts), `ListRow`, `Chip` |
-| Navigation | `Tabs` (+ `TabsList`, `TabsTrigger`, `TabsContent`), `PillTabs`, `FloatingTabBar`, `FloatingFAB`, `HeaderIconButton`, `ThemeToggle` (0.3.16) |
-| Overlays | `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet` (RN `Modal`, each with the web part names), `BottomSheetContainer` (`@gorhom/bottom-sheet`) |
+| Actions and fields | `Button` (`default`/`primary`, `secondary`, `outline`, `destructive`, `ghost`, `link`, `tinted`; `sm`/`small`, `default`/`medium`, `lg`/`large`, `icon`), `IconButton` (0.5.0), `CaptureButton` (0.5.0), `Input`, `SearchInput` (0.3.9), `Textarea`, `Label`, `Select`, `Switch`, `Checkbox`, `LabeledSwitchRow`, `ColorSwatches` (0.5.0), `DateTimeField` (date-only, empty and clearable from 0.5.0) |
+| Display | `Card` (+ `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`; `onPress` from 0.5.0), `Badge`, `StatusDot` (`info` from 0.5.0), `Avatar` (+ `AvatarImage`, `AvatarFallback`, `initials()`), `Separator`, `Progress`, `Spinner`, `CenteredSpinner`, `Skeleton`, `EmptyState` (+ `EmptyState.Root` and parts), `ListRow` (`leading`, `titleEnd`, `control`, `onLongPress` from 0.5.0), `StatGrid` (0.5.0), `SectionLabel` (0.5.0), `Chip`, `Text` (0.5.0, `/primitives` only) |
+| Navigation | `Tabs` (+ `TabsList`, `TabsTrigger`, `TabsContent`), `PillTabs`, `PageIndicator` (0.5.0), `FloatingTabBar`, `FloatingFAB`, `HeaderIconButton`, `ThemeToggle` (0.3.16), `StackPageHeader` (0.5.0) |
+| Overlays | `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet` (RN `Modal`, each with the web part names), `SheetRow` (0.5.0), `BottomSheetContainer` (`@gorhom/bottom-sheet`) |
 | Feedback | `toast()` and `<Toaster />` |
 | Brand and upgrade | `APP_ICONS`, `IconVibot` and the other `Icon*`, `AppMark`, `AppWordmark`, `GoogleMark` (0.3.15), `FAMILY_APPS`, `V_PRO_APP_BENEFITS`, `UpgradeToProCard`, `PricingModal` |
 | Settings and layout | `PageTitle`, `PageHeader` (0.3.13), `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack`, `ScreenContainer`, `SafeAreaContainer`, `FloatingSurface`, `AmbientBackground` |
@@ -197,6 +218,44 @@ From 0.3.12 a toast looks like the web `SonnerToaster` at its default density wi
 
 `@vvedantb/native-ui/gallery` exports `ParityGallery`, a screen that renders these components. Put it in a dev-only route to check them on a device.
 
+## App pieces (0.5.0)
+
+Components and props that the Verve, vibot and Velth apps need. They follow the rest of the package: Instrument Sans with its weight as a style, `tokens` and `palette` colours as styles in light and dark, a step up with larger text, 44 pt targets, and roles, names and states for VoiceOver and TalkBack.
+
+| Part | Notes |
+| --- | --- |
+| `ListRow` `leading`, `titleEnd`, `control`, `onLongPress`, `accessibilityLabel` | `leading` (any node, such as an avatar with an unread dot) replaces `icon`. `titleEnd` sits at the end of the title line. `control` sits outside the pressable area, so a `Switch` there does not fire `onPress`; `right` stays inside it. With a `control`, `testID` is on the pressable body. |
+| `Card` `onPress` | The whole card is a button that fades while pressed, named by `title` or `accessibilityLabel`. It is one element for assistive tech, so put no other control in it. |
+| `DateTimeField` | `mode="date"` for the date button only. `value` may be `null`: the buttons show `placeholder`, and the picker opens on today (or an earlier `maximumDate`). `onClear` adds a 44 clear button while there is a value. |
+| `ColorSwatches` | A radio group of round swatches (`sm` 24, `md` 32, `lg` 40) with a foreground ring and a black or white check on the selected one. `labels` names each swatch. |
+| `StatGrid` | Label and value tiles on the flat card, in rows of 2 or 3. |
+| `SectionLabel` | The muted `text-xs` medium label above a group of rows; `uppercase` for capitals. Add `className="px-4"` to line it up with rows. |
+| `SheetRow` | An action row for a `Sheet`: icon, title, detail; `active` adds a check, `danger` uses the danger colour, `disabled` dims it. |
+| `PageIndicator` | The web carousel dots. With `onChange` each dot is a 44 button named "Page 2 of 5", so the dots sit 44 apart. |
+| `StatusDot` `info` | A blue dot (`#3b82f6`, `#60a5fa` in dark), native only. |
+| `StackPageHeader` | A see-through stack header for screens over `AmbientBackground`: back chevron, centred `PageTitle` with an optional description, and `headerRight`. Pads the top inset unless `safeTop={false}`. |
+| `IconButton`, `CaptureButton` | A round icon button (`default` bordered surface, or `overlay` translucent black for camera chrome) and a 76 white camera shutter. `IconButton` is not the AI chat button. |
+
+```tsx
+<ListRow
+  title="Ada Lovelace"
+  meta="See you at nine"
+  leading={<Avatar><AvatarFallback>AL</AvatarFallback></Avatar>}
+  titleEnd={<Badge variant="secondary">09:41</Badge>}
+  onPress={openThread}
+  onLongPress={showActions}
+  control={<Switch checked={pinned} onCheckedChange={setPinned} accessibilityLabel="Pin" />}
+/>
+
+<DateTimeField mode="date" value={due} onChange={setDue} placeholder="No due date" onClear={() => setDue(null)} />
+
+<AmbientBackground>
+  <StackPageHeader title="Details" onBack={router.back} headerRight={<ThemeToggle />} />
+</AmbientBackground>
+```
+
+`Text` from `@vvedantb/native-ui/primitives` is the variant text (`h1`–`h4`, `p`, `lead`, `large`, `small`, `muted`, `code`, `blockquote`). It is not on the root entry. Unlike the components, it takes its colour from NativeWind classes (`text-foreground`, `text-muted-foreground`); where the app defines `foreground` with a nested `dark` key, give it `style={{ color: tokens.color.foreground[scheme] }}` in dark mode.
+
 ## AI chat (0.4.0)
 
 `@vvedantb/native-ui/ai` ports the `@vvedantb/ui` AI elements for touch: the thread, messages, reasoning and agent trace folds, the composer, suggestions, sources, attachments and code. They are generic (no model names, no app logic) and say "the AI", "Thinking…", "Thought for 12s" and "Worked for 12s". They add no package.
@@ -269,13 +328,13 @@ Every control has a role, an accessible name and a 44 pt target. Folds report `e
 
 ## Phones and accessibility
 
-The components keep the web sizes on screen and reach a 44 pt touch target with `hitSlop` (`touchSlop` in `src/controlStyles.ts`): `Checkbox` (16), `Switch` (36 × 20), tab triggers (30 high), the `Select` trigger (40 high), the `SearchInput` clear button (24), the `UpgradeToProCard` pill (32 high, slop 8) and `Button` (the slop brings each size to at least 48). Controls set their role and state for VoiceOver and TalkBack: `Button` (`disabled`, `busy` while loading), `Checkbox` (`checked`, `mixed`), `Switch` (`checked`), `Tabs` and `PillTabs` (`tablist`, `tab`, `selected`) and the `Select` trigger (`combobox`, with an `accessibilityLabel` prop). Give a `Button` with no text child an `accessibilityLabel`.
+The components keep the web sizes on screen and reach a 44 pt touch target with `hitSlop` (`touchSlop` in `src/controlStyles.ts`): `Checkbox` (16), `Switch` (36 × 20), tab triggers (30 high), the `Select` trigger (40 high), the `SearchInput` clear button (24), the `UpgradeToProCard` pill (32 high, slop 8) and `Button` (the slop brings each size to at least 48). From 0.5.0 so do `ColorSwatches` swatches and `IconButton` (32 and 40); the `DateTimeField` clear button and the pressable `PageIndicator` dots are 44 squares. Controls set their role and state for VoiceOver and TalkBack: `Button` (`disabled`, `busy` while loading), `Checkbox` (`checked`, `mixed`), `Switch` (`checked`), `Tabs` and `PillTabs` (`tablist`, `tab`, `selected`) and the `Select` trigger (`combobox`, with an `accessibilityLabel` prop). Give a `Button` with no text child an `accessibilityLabel`.
 
 Text scales with the system font size. Labelled controls have minimum heights, so a large Dynamic Type size grows them instead of clipping the label (the `SearchInput` lock grows with the font scale); only the `FloatingTabBar` labels are capped (1.5×), to fit the fixed bar. With Reduce Motion on, dialogs, sheets, toasts, the `Select` popover, `PricingModal`, `Progress`, `Skeleton` and the `FloatingTabBar` pill do not animate. Dialogs, sheets, toasts, `FloatingTabBar` and `FloatingFAB` stay inside the safe-area insets, and dialog and sheet fields stay above the keyboard on iOS and Android.
 
 The brand marks (`APP_ICONS`, the `Icon*` exports, `AppMark` and `GoogleMark`) are images named by `title`, and hidden from assistive tech without one. From 0.3.14 they set the props each platform reads: `accessibilityRole="image"` and `accessibilityLabel` on iOS and Android, `role="img"` and `aria-label` on web. Without a title they set `accessibilityElementsHidden` and `importantForAccessibility="no-hide-descendants"` on native and `aria-hidden` on web. `testID` is `data-testid` on web. On web `react-native-svg` passes its props straight to the DOM `<svg>`, and React Native Web does not map `accessible`, the `accessibility*` props or `testID` there. So do not put them on an `Svg` or on a Tabler icon: put them on the parent `View` or `Pressable`. The package draws no Lucide icon, as a Lucide icon always sets `testID` on its `Svg`. On web the `Select` options are Radix DOM nodes, so from 0.3.14 they take their name and test id as `aria-label` and `data-testid` there, and as `accessibilityLabel` and `testID` on iOS and Android.
 
-`ThemeToggle` (from 0.3.16) is a `HeaderIconButton` that switches between light and dark with NativeWind's `setColorScheme`, the scheme every component reads through `useColorScheme`. It shows and names the scheme it switches to: a moon and "Switch to dark mode" in light, a sun and "Switch to light mode" in dark. It stores nothing: to restore the choice on the next launch, store `useColorScheme().colorScheme` in the app. It takes `testID`.
+`ThemeToggle` (from 0.3.16) is a `HeaderIconButton` that switches between light and dark with NativeWind's `setColorScheme`, the scheme every component reads through `useColorScheme`. It shows and names the scheme it switches to: a moon and "Switch to dark mode" in light, a sun and "Switch to light mode" in dark. It stores nothing: to restore the choice on the next launch, store `useColorScheme().colorScheme` in the app. It takes `testID`. It needs `darkMode: "class"` (see [Theme](#theme)). Without it, from 0.5.0, a press logs that fix with `console.error` and leaves the scheme as it is, instead of throwing from the press handler.
 
 `GoogleMark` (from 0.3.15) is the four-colour Google "G", 18 by default, for a "Continue with Google" button: `<Button variant="outline" leftIcon={<GoogleMark />}>Continue with Google</Button>`. Its colours are fixed, so it takes no `color`. Leave it without a `title` there, as the label names the button.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts and the family app marks.",
   "type": "module",

package/src/CaptureButton.tsx

@@ -0,0 +1,62 @@
+import { Pressable, View } from "react-native";
+import { cn } from "./cn";
+import { withAlpha } from "./palette";
+import { tokens } from "./tokens";
+
+export type CaptureButtonProps = {
+  onPress?: () => void;
+  disabled?: boolean;
+  testID?: string;
+  /** Default "Take photo". */
+  accessibilityLabel?: string;
+};
+
+/** Shutter metrics: outer diameter, ring width and the gap inside the ring. */
+export const CAPTURE_BUTTON = { size: 76, ring: 4, gap: 4 } as const;
+
+/**
+ * A camera shutter: a 76 white ring around a white disc, for a live preview in
+ * light and dark alike. The disc shrinks to 90% while pressed. Larger than the
+ * 44 target, so it needs no hit slop. A labelled button, dimmed and ignoring
+ * presses when `disabled`.
+ */
+export function CaptureButton({
+  onPress,
+  disabled = false,
+  testID,
+  accessibilityLabel = "Take photo",
+}: CaptureButtonProps) {
+  const { size, ring, gap } = CAPTURE_BUTTON;
+  const inner = size - 2 * (ring + gap);
+  return (
+    <Pressable
+      testID={testID}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={{ disabled }}
+      disabled={disabled}
+      onPress={onPress}
+      className={cn("items-center justify-center", disabled && "opacity-50")}
+      style={{
+        width: size,
+        height: size,
+        borderRadius: size / 2,
+        borderWidth: ring,
+        borderColor: tokens.color.white,
+        backgroundColor: withAlpha(tokens.color.black, 0.15),
+      }}
+    >
+      {({ pressed }) => (
+        <View
+          style={{
+            width: inner,
+            height: inner,
+            borderRadius: inner / 2,
+            backgroundColor: tokens.color.white,
+            transform: [{ scale: pressed && !disabled ? 0.9 : 1 }],
+          }}
+        />
+      )}
+    </Pressable>
+  );
+}

package/src/Card.tsx

@@ -1,6 +1,6 @@
 import type { ComponentType, ReactNode } from "react";
 import type { IconProps } from "@tabler/icons-react-native";
-import { Text, View, type TextProps, type ViewProps } from "react-native";
+import { Pressable, Text, View, type TextProps, type ViewProps } from "react-native";
 import {
   Card as PrimitiveCard,
   CardContent as PrimitiveCardContent,
@@ -12,15 +12,7 @@ import { cardStyle, sizeStyle, textStyle, typeStyle } from "./controlStyles";
 import { useAccentColor, useLargerText } from "./theme";
 import { useScheme } from "./useScheme";
 
-export function Card({
-  children,
-  title,
-  description,
-  action,
-  leftIcon: Icon,
-  className,
-  testID,
-}: {
+export type CardProps = {
   children: ReactNode;
   title?: string;
   /** Muted line under the title (the web `CardDescription`). */
@@ -29,8 +21,28 @@ export function Card({
   leftIcon?: ComponentType<IconProps>;
   /** Classes on the card surface. */
   className?: string;
+  /**
+   * Makes the whole card a button that fades while pressed (from 0.5.0). It is
+   * then one element for VoiceOver and TalkBack, so put no other control in it.
+   */
+  onPress?: () => void;
+  /** Names the pressable card. Default `title`; pass one when there is no title. */
+  accessibilityLabel?: string;
+  /** On the button when there is `onPress`, otherwise on the card surface. */
   testID?: string;
-}) {
+};
+
+export function Card({
+  children,
+  title,
+  description,
+  action,
+  leftIcon: Icon,
+  className,
+  onPress,
+  accessibilityLabel,
+  testID,
+}: CardProps) {
   const largerText = useLargerText();
   const accentColor = useAccentColor();
   const scheme = useScheme();
@@ -38,9 +50,9 @@ export function Card({
   const titleSize = largerText ? "text-2xl" : "text-base";
   // The web card: a flat `surfaceCard` fill at radius 16, with no border, no
   // shadow and no blur. Dialogs, sheets and toasts float, as on the web.
-  return (
+  const card = (
     <PrimitiveCard
-      testID={testID}
+      testID={onPress ? undefined : testID}
       className={cn("gap-4 overflow-hidden border-0 py-4", className)}
       style={cardStyle(scheme)}
     >
@@ -74,6 +86,18 @@ export function Card({
       </PrimitiveCardContent>
     </PrimitiveCard>
   );
+  if (!onPress) return card;
+  return (
+    <Pressable
+      testID={testID}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? title}
+      onPress={onPress}
+      className="active:opacity-70"
+    >
+      {card}
+    </Pressable>
+  );
 }
 
 // Parts for composing a card body with the web part names. They sit inside

package/src/ColorSwatches.tsx

@@ -0,0 +1,133 @@
+import { Pressable, View } from "react-native";
+import { IconCheck } from "@tabler/icons-react-native";
+import { cn } from "./cn";
+import { touchSlop } from "./controlStyles";
+import { selectionHaptic } from "./haptics";
+import { withAlpha } from "./palette";
+import { useLargerText } from "./theme";
+import { tokens } from "./tokens";
+import { useScheme } from "./useScheme";
+
+export type ColorSwatchesSize = "sm" | "md" | "lg";
+
+export type ColorSwatchesProps = {
+  /** The selected colour: one of `colors`, compared without case. */
+  value: string;
+  onChange: (color: string) => void;
+  /** `#rgb` or `#rrggbb` colours. */
+  colors: string[];
+  /** Swatch diameter: `sm` 24, `md` 32, `lg` 40. Default `md`. */
+  size?: ColorSwatchesSize;
+  /** Per-swatch accessibility labels; falls back to the colour string */
+  labels?: string[];
+  /** Names the group, such as "Accent colour". */
+  accessibilityLabel?: string;
+  testID?: string;
+  disabled?: boolean;
+};
+
+/** Swatch diameters, one step up with larger text. */
+const DIAMETER = {
+  regular: { sm: 24, md: 32, lg: 40 },
+  larger: { sm: 32, md: 40, lg: 48 },
+} as const;
+
+/** Selection ring width and the gap between the ring and the swatch. */
+const RING = 2;
+const RING_GAP = 2;
+
+/**
+ * The check colour on a swatch: black or white, whichever has the higher WCAG
+ * contrast with it. `null` when the colour is not `#rgb` or `#rrggbb`, and the
+ * ring alone marks the selection.
+ */
+export function swatchCheckColor(color: string): string | null {
+  const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i.exec(color);
+  const hex = short ? `#${short[1]}${short[1]}${short[2]}${short[2]}${short[3]}${short[3]}` : color;
+  if (!/^#[0-9a-f]{6}$/i.test(hex)) return null;
+  const n = Number.parseInt(hex.slice(1), 16);
+  const linear = (channel: number) => {
+    const c = channel / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const luminance =
+    0.2126 * linear((n >> 16) & 255) + 0.7152 * linear((n >> 8) & 255) + 0.0722 * linear(n & 255);
+  // Contrast with white is 1.05 / (L + 0.05); with black, (L + 0.05) / 0.05.
+  return 1.05 / (luminance + 0.05) >= (luminance + 0.05) / 0.05 ? tokens.color.white : tokens.color.black;
+}
+
+/**
+ * Pick one colour from a row of round swatches that wraps. The selected swatch
+ * has a ring in the foreground colour and a check in black or white, whichever
+ * reads on it. Each swatch has a faint outline, so white shows on a white
+ * surface. A radio group for VoiceOver and TalkBack: each swatch is a radio
+ * named by `labels` (or its colour string). A `md` swatch is 32 across and 40
+ * with its ring, and reaches 44 with its hit slop; the 12 gap keeps the slops
+ * of neighbouring swatches apart.
+ */
+export function ColorSwatches({
+  value,
+  onChange,
+  colors,
+  size = "md",
+  labels,
+  accessibilityLabel,
+  testID,
+  disabled = false,
+}: ColorSwatchesProps) {
+  const scheme = useScheme();
+  const largerText = useLargerText();
+  const diameter = DIAMETER[largerText ? "larger" : "regular"][size];
+  const outer = diameter + 2 * (RING + RING_GAP);
+  const selected = value.toLowerCase();
+  return (
+    <View
+      testID={testID}
+      accessibilityRole="radiogroup"
+      accessibilityLabel={accessibilityLabel}
+      className={cn("flex-row flex-wrap gap-3", disabled && "opacity-50")}
+    >
+      {colors.map((color, index) => {
+        const isSelected = color.toLowerCase() === selected;
+        const check = isSelected ? swatchCheckColor(color) : null;
+        return (
+          <Pressable
+            key={`${color}-${index}`}
+            testID={testID ? `${testID}-${index}` : undefined}
+            accessibilityRole="radio"
+            accessibilityLabel={labels?.[index] ?? color}
+            accessibilityState={{ checked: isSelected, disabled }}
+            hitSlop={touchSlop(outer)}
+            disabled={disabled}
+            onPress={() => {
+              selectionHaptic();
+              onChange(color);
+            }}
+            className="items-center justify-center active:opacity-70"
+            style={{
+              width: outer,
+              height: outer,
+              borderRadius: outer / 2,
+              borderWidth: RING,
+              borderColor: isSelected ? tokens.color.foreground[scheme] : "transparent",
+            }}
+          >
+            <View
+              className="items-center justify-center"
+              style={{
+                width: diameter,
+                height: diameter,
+                borderRadius: diameter / 2,
+                backgroundColor: color,
+                borderWidth: 1,
+                borderColor: withAlpha(tokens.color.foreground[scheme], 0.12),
+              }}
+            >
+              {check ? <IconCheck size={Math.round(diameter / 2)} color={check} strokeWidth={2} /> : null}
+            </View>
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}

package/src/DateTimeField.tsx

@@ -4,26 +4,65 @@ import DateTimePicker, {
   type DateTimePickerEvent,
 } from "@react-native-community/datetimepicker";
 import dayjs from "dayjs";
-import { textStyle, typeStyle } from "./controlStyles";
+import { IconX } from "@tabler/icons-react-native";
+import { MIN_TOUCH_TARGET, textStyle, typeStyle } from "./controlStyles";
+import { palette } from "./palette";
 import { useLargerText } from "./theme";
+import { tokens } from "./tokens";
 import { useScheme } from "./useScheme";
 
 type PickerMode = "date" | "time";
 type PickerButton = { mode: PickerMode; label: string };
 
+export type DateTimeFieldProps = {
+  /** `null` shows `placeholder` until a date is picked (from 0.5.0). */
+  value: Date | null;
+  onChange: (value: Date) => void;
+  /** Date and time buttons (default), the time button only, or the date button only. */
+  mode?: "datetime" | "time" | "date";
+  maximumDate?: Date;
+  /** Shown on each button while `value` is `null`. Default "Select date" or "Select time". */
+  placeholder?: string;
+  /** Shows a clear button while `value` is set. It calls this; `onChange` is not called. */
+  onClear?: () => void;
+  /** Names the clear button. Default "Clear time" in `time` mode, "Clear date" otherwise. */
+  clearLabel?: string;
+  testID?: string;
+};
+
+const DEFAULT_PLACEHOLDER: Record<PickerMode, string> = {
+  date: "Select date",
+  time: "Select time",
+};
+
+/**
+ * The date the picker opens on: `value`, or with no value `now`, held back to
+ * `maximumDate` when that is earlier.
+ */
+export function pickerSeed(value: Date | null, maximumDate?: Date, now: Date = new Date()): Date {
+  if (value) return value;
+  return maximumDate && maximumDate.getTime() < now.getTime() ? maximumDate : now;
+}
+
+/**
+ * Date and time buttons that open the system picker below them. `mode="date"`
+ * shows the date button only. A `null` value shows `placeholder` in the field
+ * placeholder colour, and the picker opens on today (or `maximumDate`, if
+ * earlier); picking calls `onChange`. With `onClear`, a 44 clear button
+ * follows the buttons while there is a value. On iOS the spinner sets the
+ * value when it is turned. The buttons have the web `bg-secondary` fill
+ * (`palette.default`) as a style, so it follows the scheme.
+ */
 export function DateTimeField({
   value,
   onChange,
   mode = "datetime",
   maximumDate,
+  placeholder,
+  onClear,
+  clearLabel,
   testID,
-}: {
-  value: Date;
-  onChange: (value: Date) => void;
-  mode?: "datetime" | "time";
-  maximumDate?: Date;
-  testID?: string;
-}) {
+}: DateTimeFieldProps) {
   const largerText = useLargerText();
   const scheme = useScheme();
   const [picker, setPicker] = useState<PickerMode | null>(null);
@@ -33,18 +72,19 @@ export function DateTimeField({
     if (event.type === "set" && next) onChange(next);
   };
 
-  const timeButton: PickerButton = {
-    mode: "time",
-    label: dayjs(value).format("HH:mm"),
-  };
+  const label = (button: PickerMode, format: string) =>
+    value ? dayjs(value).format(format) : (placeholder ?? DEFAULT_PLACEHOLDER[button]);
+  const dateButton: PickerButton = { mode: "date", label: label("date", "D MMM YYYY") };
+  const timeButton: PickerButton = { mode: "time", label: label("time", "HH:mm") };
   const buttons: PickerButton[] =
-    mode === "datetime"
-      ? [{ mode: "date", label: dayjs(value).format("D MMM YYYY") }, timeButton]
-      : [timeButton];
+    mode === "datetime" ? [dateButton, timeButton] : mode === "date" ? [dateButton] : [timeButton];
+  const textColor = value
+    ? textStyle("foreground", scheme)
+    : { color: palette.fieldPlaceholder[scheme] };
 
   return (
     <View className="gap-2">
-      <View className="flex-row gap-3">
+      <View className="flex-row items-center gap-3">
         {buttons.map((button) => (
           <Pressable
             key={button.mode}
@@ -56,20 +96,36 @@ export function DateTimeField({
                 current === button.mode ? null : button.mode,
               )
             }
-            className={`${largerText ? "min-h-16" : "min-h-14"} flex-1 justify-center rounded-lg bg-secondary px-4 py-2 active:opacity-70`}
+            className={`${largerText ? "min-h-16" : "min-h-14"} flex-1 justify-center rounded-lg px-4 py-2 active:opacity-70`}
+            style={{ backgroundColor: palette.default[scheme] }}
           >
             <Text
               className={`${largerText ? "text-xl" : "text-lg"} font-instrument-sans-semibold`}
-              style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+              style={[textColor, typeStyle("semibold")]}
             >
               {button.label}
             </Text>
           </Pressable>
         ))}
+        {onClear && value ? (
+          <Pressable
+            testID={testID ? `${testID}-clear` : undefined}
+            accessibilityRole="button"
+            accessibilityLabel={clearLabel ?? (mode === "time" ? "Clear time" : "Clear date")}
+            onPress={() => {
+              setPicker(null);
+              onClear();
+            }}
+            className="items-center justify-center rounded-full active:opacity-70"
+            style={{ width: MIN_TOUCH_TARGET, height: MIN_TOUCH_TARGET }}
+          >
+            <IconX size={largerText ? 24 : 20} color={tokens.color.muted[scheme]} />
+          </Pressable>
+        ) : null}
       </View>
       {picker ? (
         <DateTimePicker
-          value={value}
+          value={pickerSeed(value, maximumDate)}
           mode={picker}
           is24Hour
           maximumDate={picker === "date" ? maximumDate : undefined}

package/src/HeaderIconButton.tsx

@@ -1,5 +1,20 @@
 import { TouchableOpacity } from "react-native";
+import { withAlpha } from "./palette";
 import { useLargerText } from "./theme";
+import { tokens } from "./tokens";
+import { useScheme } from "./useScheme";
+
+/**
+ * Fill and border of `HeaderIconButton`: the surface with a white hairline
+ * (40% in light, 10% in dark). Styles, not `bg-surface`, which an app theme
+ * that nests `dark` under `surface` keeps white in dark mode.
+ */
+export function headerIconButtonColors(scheme: "light" | "dark") {
+  return {
+    backgroundColor: tokens.color.surface[scheme],
+    borderColor: withAlpha(tokens.color.white, scheme === "dark" ? 0.1 : 0.4),
+  };
+}
 
 export function HeaderIconButton({
   onPress,
@@ -13,10 +28,12 @@ export function HeaderIconButton({
   children: React.ReactNode;
 }) {
   const largerText = useLargerText();
+  const scheme = useScheme();
   return (
     <TouchableOpacity
       testID={testID}
-      className={`${largerText ? "h-14 w-14" : "h-12 w-12"} items-center justify-center rounded-full border border-white/40 bg-surface dark:border-white/10`}
+      className={`${largerText ? "h-14 w-14" : "h-12 w-12"} items-center justify-center rounded-full border`}
+      style={headerIconButtonColors(scheme)}
       onPress={onPress}
       accessibilityRole="button"
       accessibilityLabel={label}