@vvedantb/native-ui 0.3.17 → 0.5.0

package/README.md

@@ -61,20 +61,24 @@ 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 |
 
-"Loader" means the `require` inside `try` described above, so the entry bundles and runs without that peer. `@vvedantb/native-ui/gallery` imports the root entry.
+"Loader" means the `require` inside `try` described above, so the entry bundles and runs without that peer. `@vvedantb/native-ui/gallery` imports the root entry; `@vvedantb/native-ui/ai-gallery` imports `/ai` only.
+
+The AI chat parts are only on `/ai`. Metro does not tree-shake by default, so on the root entry they would bundle into every app, with or without a chat.
 
 ```tsx
 import { FloatingTabBar } from "@vvedantb/native-ui/tab-bar";
@@ -89,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}",
@@ -111,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):
@@ -129,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` |
@@ -193,15 +218,123 @@ 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.
+
+```tsx
+import {
+  Conversation,
+  ConversationContent,
+  ConversationScrollButton,
+  Message,
+  MessageAction,
+  MessageActionsBar,
+  MessageContent,
+  PromptInput,
+  Reasoning,
+  ReasoningContent,
+  ReasoningTrigger,
+  ResponseText,
+} from "@vvedantb/native-ui/ai";
+
+<View className="flex-1">
+  <Conversation>
+    <ConversationContent>
+      <Message from="user">
+        <MessageContent>{question}</MessageContent>
+      </Message>
+      <Message from="assistant">
+        <MessageContent>
+          <Reasoning isStreaming={status === "streaming"}>
+            <ReasoningTrigger />
+            <ReasoningContent>{reasoning}</ReasoningContent>
+          </Reasoning>
+          <ResponseText>{answer}</ResponseText>
+        </MessageContent>
+        <MessageActionsBar>
+          <MessageAction kind="copy" onPress={() => copy(answer)} />
+          <MessageAction kind="retry" onPress={retry} />
+        </MessageActionsBar>
+      </Message>
+    </ConversationContent>
+    <ConversationScrollButton />
+  </Conversation>
+  <PromptInput onSubmit={send} status={status} onStop={stop} />
+</View>
+```
+
+| Part | Notes |
+| --- | --- |
+| `Conversation`, `ConversationContent`, `ConversationEmptyState`, `ConversationScrollButton`, `useConversation` | A `ScrollView` that sticks to the bottom: while the reader is within 70 of the end, new and growing messages stay in view. Once they drag up it stops following, and the scroll button shows: a round outline arrow (40, slop to 48), 16 above the bottom, with an opaque fill and no shadow. Pressing it scrolls down (a jump with Reduce Motion). For very long threads, drive a `FlatList` with `useConversation`. |
+| `Message`, `MessageContent`, `MessageActionsBar`, `MessageAction` | A user message is the web primary bubble (radius 16, bottom-right 14, `px-4 py-3`) at the end of the row; an assistant message has no fill. `MessageAction` is a ghost icon button at the web `icon-sm` size (32, slop to 44). `kind` gives the icon and label: "Copy", "Retry", "Good response", "Bad response". `selected` marks chosen feedback. |
+| `Reasoning`, `ReasoningTrigger`, `ReasoningContent`, `useReasoning` | Opens when streaming starts, times the stream and closes once, a second after it stops. The trigger shows a brain, the shimmering "Thinking…", then "Thought for 12s", and a chevron. The content is muted monospace text on the web `bg-surface-secondary/40` panel. Unlike the web, a reader can close it while it streams. |
+| `AgentTrace`, `AgentTraceLine`, `AgentTraceIcon`, `AgentTraceTitle`, `AgentTraceDescription`, `AgentTraceCollapsible*` | One step per line, with an optional fold behind a rail. `AgentTraceTitle shimmer` pulses a running step. Spread `useStreamingDisclosure(isStreaming)` on `AgentTraceCollapsible` to open it while a step streams. |
+| `ActivityStep` | One tool step as a trace line: icon, label, a spinner while `running`, a check when `complete`, a warning on `error`, and a description such as `` `Worked for ${formatElapsed(12)}` ``. |
+| `ChainOfThought` and its parts | Simplified: header, steps with a rail, search-result chips. |
+| `PromptInput`, `PromptInputButton`, `PromptInputSubmit` | The web field surface with a `header` slot (attachments), a field, a `toolbar` slot and the send button. The field grows from one line to 160 high (about 6 lines), then scrolls. Send is primary with text and disabled without. While `status` is `submitted` or `streaming` it is a "Stop" square that calls `onStop`. It sits in a `KeyboardAvoidingView` (padding, on iOS and Android) and pads the safe-area insets: put it last in a full-height column. Under a navigation header, pass the header height as `keyboardVerticalOffset`; above a tab bar, pass `safeBottom={false}`. |
+| `Suggestions`, `Suggestion` | A horizontal row of round chips (or `orientation="vertical"`). `onPress` gets the suggestion text. |
+| `Sources`, `SourcesTrigger`, `SourcesContent`, `Source` | A fold of link rows. A row opens its address with `Linking.openURL`, or hands it to `onPress`. |
+| `FileChip`, `Attachments`, `Attachment` | A monospace file chip (a button with `onOpenFile`), and attachment chips with a media icon or image thumbnail and a labelled remove button. No hover cards and no grid previews. |
+| `CodeBlock`, `CodeBlockCopyButton` | Plain monospace code on the flat panel, scrolling sideways, with the language and a copy button in a header. No highlighting. |
+| `ResponseText` | Plain, selectable reply text with newlines kept. It takes the colour of the `MessageContent` it is in. |
+| `Shimmer` | "Live" text: the foreground fades to 0.45 and back on the UI thread. With Reduce Motion it holds still, muted. |
+
+**Markdown.** There is no markdown renderer: `ResponseText` draws the text as it is. To render markdown, an app can add one of these and use it in place of `ResponseText`: `react-native-markdown-display`, `@ronradtke/react-native-markdown-display` (a maintained fork) or `react-native-marked`.
+
+**Clipboard.** React Native's own `Clipboard` is deprecated (moved out of core), and the package adds no clipboard package. `MessageAction kind="copy"` calls your `onPress`, and `CodeBlock` shows its copy button when given `onCopy(code)`. Pass your own clipboard call, for example `expo-clipboard`'s `setStringAsync`.
+
+Every control has a role, an accessible name and a 44 pt target. Folds report `expanded`, feedback actions `selected`, and the send button `disabled`. Type and icons step up with larger text. Colours come from `palette` and `tokens` as styles, in light and dark.
+
+`@vvedantb/native-ui/ai-gallery` exports `AiChatGallery`, a full chat screen with a sample thread: a user message, a finished assistant message with folded reasoning and trace, code, sources and actions, and a second answer that streams with its reasoning open until you press Stop. It also has suggestions and the composer with sample attachments. Put it in a dev-only route with a `SafeAreaProvider` above it. `ParityGallery` shows the same thread (`AiChatSamples`) in its "AI chat" section.
+
 ## 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,8 +1,8 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.3.17",
+  "version": "0.5.0",
   "license": "MIT",
-  "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar and the family app marks.",
+  "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",
   "publishConfig": {
     "access": "public"
@@ -73,10 +73,18 @@
       "types": "./src/entries/date-time.ts",
       "default": "./src/entries/date-time.ts"
     },
+    "./ai": {
+      "types": "./src/entries/ai.ts",
+      "default": "./src/entries/ai.ts"
+    },
     "./gallery": {
       "types": "./src/examples/ParityGallery.tsx",
       "default": "./src/examples/ParityGallery.tsx"
     },
+    "./ai-gallery": {
+      "types": "./src/examples/AiChatGallery.tsx",
+      "default": "./src/examples/AiChatGallery.tsx"
+    },
     "./blur": {
       "types": "./src/blur.ts",
       "default": "./src/blur.ts"

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>
+  );
+}