@vvedantb/native-ui 0.11.2 → 0.12.0

package/README.md

@@ -72,16 +72,17 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@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`, `configureTheme` (with the `ThemeConfig`, `ThemeColors` and `ThemePalette` types), `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`, `StackPageHeader` (0.5.0) and their props types, `SectionLabel` (0.5.0), `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack`, `MoreFromProjectV` and `FromProjectV` (0.8.0) | `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`, `MoreFromProjectV` and `FromProjectV` (0.8.0), `ScreenContainerProps`, `SettingsEmptyState`, `PinnedBotTile`, `BotPinGrid`, `ArtifactList` (0.12.0). `ScreenContainer` takes `refreshing`, `onRefresh` and `refreshControl` (0.12.0). `StackPageHeader` takes `centre` (0.12.0) | `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/push` | `useExpoPushRegistration`, `getExpoPushToken`, `showPushesInForeground`, the three loaders and the types (0.9.0). Pass `register` from your backend (for `@vvedantb/server`: `useMutation(api.push.register)`) and route taps in `onNotificationTap` | `expo-notifications`, `expo-constants`, `expo-device` (loaders) |
 | `@vvedantb/native-ui/bottom-sheet` | `BottomSheetContainer` | `@gorhom/bottom-sheet` (import), `expo-blur` (loader) |
 | `@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` | 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.. From 0.12.0: `ChatThread`, `UIMessage`, `ChatJumpRail` and the `Attachment` props `onPress` and `accessibilityLabel` | none |
 | `@vvedantb/native-ui/ai-gallery` | `AiChatGallery`, `AiChatSamples` (from 0.4.0) | none |
 | `@vvedantb/native-ui/auth` | From 0.7.0: `AuthProviders`, `SignInScreen`, `SignUpScreen`, `GoogleSignInButton`, `useGoogleSignIn`, `AuthScreen`, `OrDivider`, `FieldError`, `authErrorMessage`, `SecondFactorScreen`, `useSecondFactor`, `submitTotpSecondFactor`, `submitSecondFactor`, `prepareSecondFactorIfNeeded`, `prepareFirstFactorIfNeeded`, `submitFirstFactor`, `pickFirstFactorStrategy`, `TOTP_MESSAGES` and their props types. See [Auth](#auth-070). Not on the root entry. | `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser`, `expo-router` (import) |
+| `@vvedantb/native-ui/expo-router` | From 0.12.0: `RouterStackPageHeader`, `RouterStackPageHeaderProps`, `goBackOrReplace`. Not on the root, `/layout` or `/page-title` entries. | `expo-router` (import) |
 | `@vvedantb/native-ui/expo-web-root` | From 0.7.0: `ExpoWebRoot`, `ExpoWebRootProps`, `ExpoWebRootViewport`, `EXPO_WEB_VIEWPORT`, `expoWebBackgroundCss`. Not on the root entry. | `expo-router` (import of `expo-router/html`) |
 | `@vvedantb/native-ui/tailwind-preset` | From 0.7.0, CommonJS for `tailwind.config.js`: `nativeUiPreset`, `nativeUiContent`, `cssVar`, `hslVar`, `rgbAlpha`, `cssVariables`, `schemeColors` and a default preset. See [Expo / NativeWind](#expo--nativewind). | `nativewind` (`require`, when installed) |
 
@@ -426,6 +427,41 @@ Components and props that the Verve, vibot and Velth apps need. They follow the
 </AmbientBackground>
 ```
 
+### 0.12.0 additions
+
+```tsx
+// Typed routes: `afterAuthHref`, `signUpHref` and `signInHref` take expo-router's `Href`,
+// and `replaceOptions` takes `Parameters<Router["replace"]>[1]`.
+<SignInScreen scheme="app" afterAuthHref="/(app)/bots" signUpHref="/sign-up" replaceOptions={{ withAnchor: true }} />
+
+// Router-aware back: router.canGoBack() ? router.back() : router.replace(fallbackHref).
+import { RouterStackPageHeader } from "@vvedantb/native-ui/expo-router";
+<RouterStackPageHeader title="Bot" fallbackHref="/bots" backTestID="screen-back" centre={<BotTitle />} />
+
+// An attachment chip that opens its file. The remove button stays separate.
+<Attachment data={file} onPress={() => open(file.url)} onRemove={() => remove(file.id)} />
+
+// The chat column as one piece.
+<ChatThread
+  messages={messages}
+  working={status === "streaming"}
+  renderMessage={(message, isStreaming) => <MessageItem message={message} streaming={isStreaming} />}
+  thinking={<Shimmer>Thinking</Shimmer>}
+  footer={<PromptInput onSubmit={send} status={status} />}
+  contentContainerClassName="px-4 py-4"
+/>
+
+// A two-across grid of pinned bots.
+<BotPinGrid>
+  <PinnedBotTile title="Research" leading={<Avatar />} unread onPress={open} onLongPress={showActions} />
+</BotPinGrid>
+
+// Pull to refresh. `refreshing` is controlled. No control without `onRefresh` or `refreshControl`.
+<ScreenContainer refreshing={refreshing} onRefresh={reload}>{children}</ScreenContainer>
+```
+
+`StackPageHeader` `centre` replaces the centre `PageTitle` (for example a 20 px avatar beside a name). `title` stays the accessible name and the fallback; `description` still shows under it. The two sides keep the same width and the centre shrinks and truncates. `RouterStackPageHeader` takes the `StackPageHeader` props without `onBack`, plus `fallbackHref` (default `"/"`). `ChatThread` shows `thinking` right after the last user message while `working` and marks the last assistant message as streaming. A `PromptInput` footer keeps its own keyboard lift; the outer `KeyboardAvoidingView` moves it clear first, so the lift is not doubled. `SettingsEmptyState` is a compact empty note for the inside of a `SettingsSection`; `ArtifactList` lists artifacts as pressable rows; `ChatJumpRail` is a horizontal rail of chips that jump between messages.
+
 `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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "license": "MIT",
   "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts, the family app marks, a NativeWind preset, the Expo web root and Clerk + Convex auth screens.",
   "type": "module",
@@ -109,6 +109,10 @@
       "types": "./src/entries/markdown.ts",
       "default": "./src/entries/markdown.ts"
     },
+    "./expo-router": {
+      "types": "./src/entries/expo-router.ts",
+      "default": "./src/entries/expo-router.ts"
+    },
     "./expo-web-root": {
       "types": "./src/entries/expo-web-root.ts",
       "default": "./src/entries/expo-web-root.ts"

package/src/ArtifactList.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import { View } from "react-native";
+import { DividedList } from "./DividedList";
+import { ListRow } from "./ListRow";
+
+export type ArtifactRow = { id: string; title: string; description?: string };
+
+export type ArtifactListProps = {
+  rows: ArtifactRow[];
+  /** Called with the `id` of the pressed row. */
+  onOpen: (id: string) => void;
+  /** Shown when `rows` is empty, such as an `EmptyState`. Nothing without it. */
+  empty?: ReactNode;
+  className?: string;
+  testID?: string;
+};
+
+/**
+ * Artifacts as pressable `ListRow`s under hairlines (`DividedList`): the title
+ * and an optional description line. A row is a button named by its title.
+ * `empty` stands in for an empty list.
+ */
+export function ArtifactList({ rows, onOpen, empty, className, testID }: ArtifactListProps) {
+  if (rows.length === 0) return empty != null ? <View testID={testID}>{empty}</View> : null;
+  return (
+    <DividedList className={className} testID={testID}>
+      {rows.map((row) => (
+        <ListRow
+          key={row.id}
+          testID={`artifact-${row.id}`}
+          title={row.title}
+          meta={row.description}
+          onPress={() => onOpen(row.id)}
+        />
+      ))}
+    </DividedList>
+  );
+}

package/src/PinnedBotTile.tsx

@@ -0,0 +1,88 @@
+import { Children, type ReactNode } from "react";
+import { Pressable, Text, View, type ViewProps } from "react-native";
+import { cn } from "./cn";
+import { cardStyle, textStyle, typeStyle } from "./controlStyles";
+import { StatusDot } from "./StatusDot";
+import { Spinner } from "./Spinner";
+import { useLargerText } from "./theme";
+import { useScheme } from "./useScheme";
+
+export type PinnedBotTileProps = {
+  /** The bot name, under the avatar. Up to two lines. */
+  title: string;
+  /** The avatar, above the name. */
+  leading: ReactNode;
+  /** Shows an unread dot at the top start and adds "unread" to the label. */
+  unread?: boolean;
+  /** Shows a spinner at the top end and adds "generating" to the label. It can show with the unread dot. */
+  generating?: boolean;
+  onPress: () => void;
+  /** Opens actions on a long press. */
+  onLongPress?: () => void;
+  testID?: string;
+};
+
+/**
+ * A large pinned-bot tile: the avatar above the name on a `Card` fill, an
+ * unread dot or a generating spinner at the top end. At least 112 high, so it
+ * is a comfortable touch target in a `BotPinGrid`. The tile is one button named
+ * by the title, plus "unread" or "generating".
+ */
+export function PinnedBotTile({ title, leading, unread = false, generating = false, onPress, onLongPress, testID }: PinnedBotTileProps) {
+  const scheme = useScheme();
+  const largerText = useLargerText();
+  const state = [unread ? "unread" : null, generating ? "generating" : null].filter(Boolean).join(", ");
+  return (
+    <Pressable
+      testID={testID}
+      accessibilityRole="button"
+      accessibilityLabel={state ? `${title}, ${state}` : title}
+      onPress={onPress}
+      onLongPress={onLongPress}
+      className={cn("min-w-0 items-center justify-center gap-2 px-3 py-4 active:opacity-70", largerText ? "min-h-36" : "min-h-28")}
+      style={cardStyle(scheme)}
+    >
+      {leading}
+      <Text
+        numberOfLines={2}
+        className={cn("text-center font-instrument-sans-semibold", largerText ? "text-lg" : "text-base")}
+        style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+      >
+        {title}
+      </Text>
+      {unread ? (
+        <View className="absolute left-3 top-3" testID={testID ? `${testID}-unread` : undefined}>
+          <StatusDot tone="active" size="md" />
+        </View>
+      ) : null}
+      {generating ? (
+        <View className="absolute right-3 top-3" testID={testID ? `${testID}-generating` : undefined}>
+          <Spinner size="sm" decorative />
+        </View>
+      ) : null}
+    </Pressable>
+  );
+}
+
+export type BotPinGridProps = ViewProps & {
+  /** `PinnedBotTile`s. */
+  children?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Lays `PinnedBotTile`s out two across, wrapping to new rows, with a 12 gap. A
+ * lone last tile keeps half the width. Each child gets a half-width cell.
+ */
+export function BotPinGrid({ children, className, ...props }: BotPinGridProps) {
+  const cells = Children.toArray(children);
+  return (
+    <View className={cn("flex-row flex-wrap gap-3", className)} {...props}>
+      {cells.map((child, index) => (
+        <View key={(child as { key?: string | null }).key ?? index} className="min-w-0" style={{ flexBasis: "47%", flexGrow: 1, maxWidth: "50%" }}>
+          {child}
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/ScreenContainer.tsx

@@ -1,25 +1,52 @@
-import { ScrollView, View, type ViewProps } from "react-native";
+import {
+  RefreshControl,
+  ScrollView,
+  View,
+  type RefreshControlProps,
+  type ViewProps,
+} from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { useLargerText } from "./theme";
+import { useAccentColor, useLargerText } from "./theme";
 import { tabBarReserve } from "./floating";
 
-interface ScreenContainerProps extends ViewProps {
+export interface ScreenContainerProps extends ViewProps {
   children: React.ReactNode;
   reserveTabBar?: boolean;
   footer?: React.ReactNode;
+  /** Shows the pull-to-refresh spinner while true. Controlled: no timer, no minimum duration. */
+  refreshing?: boolean;
+  /** Called on pull. May return a promise. Adds a `RefreshControl` tinted with the accent colour. */
+  onRefresh?: () => void | Promise<void>;
+  /** Full control. Takes precedence over `refreshing` and `onRefresh`. */
+  refreshControl?: React.ReactElement<RefreshControlProps>;
 }
 
 export function ScreenContainer({
   children,
   reserveTabBar = false,
   footer,
+  refreshing = false,
+  onRefresh,
+  refreshControl,
   ...props
 }: ScreenContainerProps) {
   const insets = useSafeAreaInsets();
   const largerText = useLargerText();
+  const accent = useAccentColor();
   const bottomPad = reserveTabBar
     ? tabBarReserve(largerText, insets.bottom)
     : 40;
+  // No control unless the app asks for one.
+  const control =
+    refreshControl ??
+    (onRefresh ? (
+      <RefreshControl
+        refreshing={refreshing}
+        onRefresh={() => void onRefresh()}
+        tintColor={accent}
+        colors={[accent]}
+      />
+    ) : undefined);
 
   return (
     <View className="flex-1 bg-transparent" {...props}>
@@ -27,6 +54,7 @@ export function ScreenContainer({
         showsVerticalScrollIndicator={false}
         className="flex-1"
         contentContainerStyle={{ paddingBottom: bottomPad }}
+        refreshControl={control}
       >
         <View className="flex-col gap-4 p-4">{children}</View>
         {footer ? <View className="pt-4">{footer}</View> : null}

package/src/StackPageHeader.tsx

@@ -11,7 +11,15 @@ import { tokens } from "./tokens";
 import { useScheme } from "./useScheme";
 
 export type StackPageHeaderProps = {
+  /** The accessible name of the header, and the centre text when `centre` is not set. */
   title: string;
+  /**
+   * Custom content for the centre, such as a 20 px avatar beside a name. It
+   * replaces the `PageTitle`. `title` stays the accessible name. Wrap long
+   * text in a `PageTitle` (or `Text` with `numberOfLines`) so it can truncate:
+   * the centre shrinks (`min-w-0`) and clips what does not fit.
+   */
+  centre?: ReactNode;
   /** Muted line under the title, up to two lines. */
   description?: string;
   /** Shows a back `HeaderIconButton` at the start that calls this. No button without it. */
@@ -36,11 +44,14 @@ export type StackPageHeaderProps = {
  * a centred `PageTitle` (Instrument Sans 600 at 20 / 25) with an optional
  * muted description. The two sides are the same width, the wider of the back
  * button and `headerRight`, so the title stays centred on the screen and a
- * long one is cut off before it reaches them. The row is at least 56 high
+ * long one is cut off before it reaches them. `centre` (0.12.0) replaces the
+ * `PageTitle` with custom content; `title` then names the header for
+ * VoiceOver and TalkBack. The row is at least 56 high
  * below the top inset, as `PageHeader`, with the `px-4` screen padding.
  */
 export function StackPageHeader({
   title,
+  centre,
   description,
   onBack,
   backLabel = "Back",
@@ -74,7 +85,18 @@ export function StackPageHeader({
         ) : null}
       </View>
       <View className="min-w-0 shrink items-center py-2">
-        <PageTitle className="text-center">{title}</PageTitle>
+        {centre != null ? (
+          <View
+            accessible
+            accessibilityRole="header"
+            accessibilityLabel={title}
+            className="min-w-0 max-w-full shrink flex-row items-center justify-center"
+          >
+            {centre}
+          </View>
+        ) : (
+          <PageTitle className="text-center">{title}</PageTitle>
+        )}
         {description ? (
           <Text
             numberOfLines={2}

package/src/ai/attachments.tsx

@@ -88,18 +88,31 @@ export type AttachmentProps = {
   data: AttachmentData;
   /** Shows a remove button, labelled "Remove" and the attachment name. */
   onRemove?: () => void;
+  /**
+   * Makes the chip a button, such as to open the file. The remove button stays a
+   * separate target and does not call this. Without it the chip is not pressable.
+   */
+  onPress?: () => void;
+  /** Names the chip button, with `onPress`. Default the attachment name (`getAttachmentLabel`). */
+  accessibilityLabel?: string;
   testID?: string;
 };
 
+/** The hit target of a pressable chip, in points, on each axis. */
+export const ATTACHMENT_PRESS_TARGET = 48;
+
 /** A remove cross of 20 in a 32 row: the slop brings it to 44. */
 const REMOVE_SIZE = 20;
 
 /**
  * One attachment as a chip: a 20 thumbnail for an image with a `url`, else
  * its media icon, then the name and an optional remove button. Flat, on the
- * web `flatPanelSubtle` fill (`bg-surface-secondary`). No hover card.
+ * web `flatPanelSubtle` fill (`bg-surface-secondary`). No hover card. With
+ * `onPress` the thumbnail or icon and the name are one button with a 48 point
+ * hit target (the chip stays 32, or 44 with larger text, and `hitSlop` does the
+ * rest); the remove button is a separate target that never calls `onPress`.
  */
-export function Attachment({ data, onRemove, testID }: AttachmentProps) {
+export function Attachment({ data, onRemove, onPress, accessibilityLabel, testID }: AttachmentProps) {
   const variant = useContext(AttachmentsContext);
   const scheme = useScheme();
   const largerText = useLargerText();
@@ -108,16 +121,8 @@ export function Attachment({ data, onRemove, testID }: AttachmentProps) {
   const Icon = MEDIA_ICONS[category];
   const iconSize = largerText ? 20 : 16;
   const muted = tokens.color.muted[scheme];
-  return (
-    <View
-      testID={testID}
-      className={cn(
-        "min-w-0 flex-row items-center gap-1.5 px-2",
-        largerText ? "min-h-11" : "min-h-8",
-        variant === "list" ? "w-full" : "max-w-full",
-      )}
-      style={{ borderRadius: tokens.radius.sm, backgroundColor: tokens.color.surfaceSecondary[scheme] }}
-    >
+  const content = (
+    <>
       {category === "image" && data.url ? (
         <Image
           source={{ uri: data.url }}
@@ -136,6 +141,36 @@ export function Attachment({ data, onRemove, testID }: AttachmentProps) {
       >
         {label}
       </ResponseText>
+    </>
+  );
+  const chipHeight = largerText ? 44 : 32;
+  const slop = Math.max(0, Math.ceil((ATTACHMENT_PRESS_TARGET - chipHeight) / 2));
+  return (
+    <View
+      testID={testID}
+      className={cn(
+        "min-w-0 flex-row items-center gap-1.5 px-2",
+        largerText ? "min-h-11" : "min-h-8",
+        variant === "list" ? "w-full" : "max-w-full",
+      )}
+      style={{ borderRadius: tokens.radius.sm, backgroundColor: tokens.color.surfaceSecondary[scheme] }}
+    >
+      {onPress ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={accessibilityLabel ?? label}
+          hitSlop={{ top: slop, bottom: slop, left: 0, right: 0 }}
+          onPress={onPress}
+          className={cn(
+            "min-w-0 flex-row items-center gap-1.5 self-stretch active:opacity-70",
+            variant === "list" ? "flex-1" : "shrink",
+          )}
+        >
+          {content}
+        </Pressable>
+      ) : (
+        content
+      )}
       {onRemove ? (
         <Pressable
           accessibilityRole="button"

package/src/ai/chat-jump-rail.tsx

@@ -0,0 +1,38 @@
+import { ScrollView } from "react-native";
+import { Chip } from "../Chip";
+import { cn } from "../cn";
+
+export type ChatJumpRailItem = { id: string; label: string };
+
+export type ChatJumpRailProps = {
+  /** The messages to jump between, such as the user messages of a long thread. */
+  items: ChatJumpRailItem[];
+  /** Called with the `id` of the pressed item. */
+  onJump: (id: string) => void;
+  className?: string;
+  testID?: string;
+};
+
+/**
+ * A rail to jump between messages (web `chat-jump-rail`): a horizontal row of
+ * chips, one per item. Each chip is a 48 high button named by its label. Draws
+ * nothing for an empty list.
+ */
+export function ChatJumpRail({ items, onJump, className, testID }: ChatJumpRailProps) {
+  if (items.length === 0) return null;
+  return (
+    <ScrollView
+      testID={testID}
+      horizontal
+      showsHorizontalScrollIndicator={false}
+      keyboardShouldPersistTaps="handled"
+      accessibilityRole="toolbar"
+      className={cn("grow-0", className)}
+      contentContainerClassName="gap-2 px-3 py-2"
+    >
+      {items.map((item) => (
+        <Chip key={item.id} label={item.label} selected={false} onPress={() => onJump(item.id)} testID={`jump-${item.id}`} />
+      ))}
+    </ScrollView>
+  );
+}

package/src/ai/chat-thread.tsx

@@ -0,0 +1,96 @@
+import type { ReactNode } from "react";
+import { KeyboardAvoidingView, View } from "react-native";
+import { cn } from "../cn";
+import {
+  Conversation,
+  ConversationContent,
+  ConversationScrollButton,
+} from "./conversation";
+
+/**
+ * The least `ChatThread` reads from a message: an id and a role. The `ai` SDK
+ * `UIMessage` fits it, so the package takes no `ai` dependency.
+ */
+export type UIMessage = {
+  id: string;
+  role: "system" | "user" | "assistant";
+};
+
+export type ChatThreadProps<M extends UIMessage = UIMessage> = {
+  messages: M[];
+  /** True while a reply is on its way. Marks the last assistant message as streaming and shows `thinking`. */
+  working: boolean;
+  /** Draws one message. `isStreaming` is true for the last assistant message while `working`. */
+  renderMessage: (message: M, isStreaming: boolean) => ReactNode;
+  /** A row after the last user message while `working`, such as a `Shimmer` "Thinking". */
+  thinking?: ReactNode;
+  /** Shown in place of the list when there are no messages. */
+  emptyState?: ReactNode;
+  /** Last in the column, lifted over the keyboard. A `PromptInput`. */
+  footer: ReactNode;
+  /** Merged into the `ConversationContent` column classes (`gap-4 px-3 py-3`), such as `px-4 py-4`. */
+  contentContainerClassName?: string;
+  /** Height of anything above the thread, such as a navigation header, for the keyboard lift. Default 0. */
+  keyboardVerticalOffset?: number;
+  className?: string;
+  testID?: string;
+};
+
+/** Index of the last message with `role`, or -1. A loop, not `findLastIndex` (Hermes). */
+function lastIndexOfRole(messages: UIMessage[], role: UIMessage["role"]) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]!.role === role) return index;
+  }
+  return -1;
+}
+
+/**
+ * The chat column as one piece: `Conversation`, `ConversationContent`, the
+ * messages, a `thinking` row right after the last user message while
+ * `working`, `ConversationScrollButton` and the `footer` last. The whole
+ * column sits in a `KeyboardAvoidingView` (`padding`, as `PromptInput`), which
+ * also lifts the footer on Android edge-to-edge, where the window does not
+ * resize. A `PromptInput` footer has its own `KeyboardAvoidingView`; the outer
+ * lift moves it clear of the keyboard, so it adds no second lift.
+ */
+export function ChatThread<M extends UIMessage = UIMessage>({
+  messages,
+  working,
+  renderMessage,
+  thinking,
+  emptyState,
+  footer,
+  contentContainerClassName,
+  keyboardVerticalOffset = 0,
+  className,
+  testID,
+}: ChatThreadProps<M>) {
+  const lastUser = working ? lastIndexOfRole(messages, "user") : -1;
+  const streaming = working ? lastIndexOfRole(messages, "assistant") : -1;
+
+  return (
+    <KeyboardAvoidingView
+      testID={testID}
+      behavior="padding"
+      keyboardVerticalOffset={keyboardVerticalOffset}
+      className={cn("flex-1", className)}
+    >
+      <Conversation>
+        <ConversationContent contentContainerClassName={contentContainerClassName}>
+          {messages.length === 0
+            ? emptyState
+            : messages.map((message, index) => (
+                <View key={message.id}>
+                  {renderMessage(message, index === streaming)}
+                  {index === lastUser && thinking != null ? (
+                    <View className="mt-4">{thinking}</View>
+                  ) : null}
+                </View>
+              ))}
+        </ConversationContent>
+        <ConversationScrollButton testID="chat-thread-scroll-bottom" />
+      </Conversation>
+      {footer}
+    </KeyboardAvoidingView>
+  );
+}

package/src/ai/index.ts

@@ -115,6 +115,7 @@ export {
   Attachment,
   getMediaCategory,
   getAttachmentLabel,
+  ATTACHMENT_PRESS_TARGET,
 } from "./attachments";
 export type {
   AttachmentData,
@@ -123,6 +124,10 @@ export type {
   AttachmentsProps,
   AttachmentProps,
 } from "./attachments";
+export { ChatThread } from "./chat-thread";
+export type { ChatThreadProps, UIMessage } from "./chat-thread";
+export { ChatJumpRail } from "./chat-jump-rail";
+export type { ChatJumpRailProps, ChatJumpRailItem } from "./chat-jump-rail";
 export { CodeBlock, CodeBlockCopyButton } from "./code-block";
 export type { CodeBlockProps, CodeBlockCopyButtonProps } from "./code-block";
 export { ResponseText, ChatTextColorContext } from "./response-text";

package/src/auth/GoogleSignInButton.tsx

@@ -3,7 +3,7 @@ import { Platform } from "react-native";
 import { useSSO } from "@clerk/clerk-expo";
 import * as AuthSession from "expo-auth-session";
 import * as WebBrowser from "expo-web-browser";
-import { useRouter } from "expo-router";
+import { useRouter, type Href, type Router } from "expo-router";
 import { GoogleMark } from "../brand/GoogleMark";
 import { Button, type ButtonProps } from "../Button";
 import { toast } from "../toastStore";
@@ -16,9 +16,9 @@ export const GOOGLE_ERROR_MESSAGE = "Could not continue with Google";
 
 export type AuthNavigationOptions = {
   /** Where to go after a session starts. Default `"/"`. */
-  afterAuthHref?: string;
+  afterAuthHref?: Href;
   /** Passed to `router.replace`, such as `{ withAnchor: true }`. */
-  replaceOptions?: object;
+  replaceOptions?: Parameters<Router["replace"]>[1];
   /** Called after a session starts, in place of `router.replace`. */
   onSuccess?: () => void;
 };

package/src/auth/SignInScreen.tsx

@@ -1,7 +1,7 @@
 import { useState, type ReactNode } from "react";
 import { Text, View } from "react-native";
 import { useSignIn, useSignUp } from "@clerk/clerk-expo";
-import { useRouter } from "expo-router";
+import { useRouter, type Href } from "expo-router";
 import { Button } from "../Button";
 import { textStyle } from "../controlStyles";
 import { Input } from "../Input";
@@ -119,9 +119,9 @@ export type SignInScreenProps = AuthNavigationOptions & {
   /** Default "Continue with Google". */
   googleLabel?: string;
   /** In `sign-in`: the "Sign up" link in the footer. No link without it. */
-  signUpHref?: string;
+  signUpHref?: Href;
   /** In `sign-up`: the "Sign in" link in the footer. No link without it. */
-  signInHref?: string;
+  signInHref?: Href;
   /** Sign-up rejects a shorter password before sending it. Default: no check. */
   minPasswordLength?: number;
   /** Default `"toast"`. `"inline"` shows errors under the fields. */

package/src/entries/expo-router.ts

@@ -0,0 +1,5 @@
+// `@vvedantb/native-ui/expo-router`: components that need `expo-router`, an
+// optional peer. Not on the root, `/layout` or `/page-title` entries: they
+// never import it.
+export { RouterStackPageHeader, goBackOrReplace } from "../router/RouterStackPageHeader";
+export type { RouterStackPageHeaderProps } from "../router/RouterStackPageHeader";

package/src/entries/layout.ts

@@ -2,6 +2,7 @@
 // labels and settings chrome.
 export { SafeAreaContainer } from "../SafeAreaContainer";
 export { ScreenContainer } from "../ScreenContainer";
+export type { ScreenContainerProps } from "../ScreenContainer";
 export { PageTitle, PageHeader } from "../PageTitle";
 export type { PageTitleProps, PageHeaderProps } from "../PageTitle";
 export { StackPageHeader } from "../StackPageHeader";
@@ -12,6 +13,12 @@ export { SettingsSection } from "../settings/SettingsSection";
 export { SettingsField } from "../settings/SettingsField";
 export { SettingsToggleRow } from "../settings/SettingsToggleRow";
 export { SettingsStack } from "../settings/SettingsStack";
+export { SettingsEmptyState } from "../settings/SettingsEmptyState";
+export type { SettingsEmptyStateProps } from "../settings/SettingsEmptyState";
+export { PinnedBotTile, BotPinGrid } from "../PinnedBotTile";
+export type { PinnedBotTileProps, BotPinGridProps } from "../PinnedBotTile";
+export { ArtifactList } from "../ArtifactList";
+export type { ArtifactListProps, ArtifactRow } from "../ArtifactList";
 export { MoreFromProjectV, FromProjectV } from "../settings/MoreFromProjectV";
 export type { MoreFromProjectVProps, FromProjectVProps } from "../settings/MoreFromProjectV";
 export {

package/src/index.ts

@@ -182,6 +182,7 @@ export type { DateTimeFieldProps } from "./DateTimeField";
 export { BottomSheetContainer } from "./BottomSheetContainer";
 export { SafeAreaContainer } from "./SafeAreaContainer";
 export { ScreenContainer } from "./ScreenContainer";
+export type { ScreenContainerProps } from "./ScreenContainer";
 export { PageTitle, PageHeader } from "./PageTitle";
 export type { PageTitleProps, PageHeaderProps } from "./PageTitle";
 export { StackPageHeader } from "./StackPageHeader";
@@ -190,6 +191,12 @@ export { SettingsSection } from "./settings/SettingsSection";
 export { SettingsField } from "./settings/SettingsField";
 export { SettingsToggleRow } from "./settings/SettingsToggleRow";
 export { SettingsStack } from "./settings/SettingsStack";
+export { SettingsEmptyState } from "./settings/SettingsEmptyState";
+export type { SettingsEmptyStateProps } from "./settings/SettingsEmptyState";
+export { PinnedBotTile, BotPinGrid } from "./PinnedBotTile";
+export type { PinnedBotTileProps, BotPinGridProps } from "./PinnedBotTile";
+export { ArtifactList } from "./ArtifactList";
+export type { ArtifactListProps, ArtifactRow } from "./ArtifactList";
 export { MoreFromProjectV, FromProjectV } from "./settings/MoreFromProjectV";
 export type { MoreFromProjectVProps, FromProjectVProps } from "./settings/MoreFromProjectV";
 export {

package/src/router/RouterStackPageHeader.tsx

@@ -0,0 +1,25 @@
+import { useRouter, type Href, type Router } from "expo-router";
+import { StackPageHeader, type StackPageHeaderProps } from "../StackPageHeader";
+
+export type RouterStackPageHeaderProps = Omit<StackPageHeaderProps, "onBack"> & {
+  /** Where the back button goes when there is nothing to go back to, such as after a deep link. Default `"/"`. */
+  fallbackHref?: Href;
+};
+
+/** Goes back when the stack has a screen below, else replaces the route with `fallbackHref`. */
+export function goBackOrReplace(router: Pick<Router, "canGoBack" | "back" | "replace">, fallbackHref: Href = "/") {
+  if (router.canGoBack()) router.back();
+  else router.replace(fallbackHref);
+}
+
+/**
+ * `StackPageHeader` with a router-aware back button: `router.canGoBack() ?
+ * router.back() : router.replace(fallbackHref)`. Same props as
+ * `StackPageHeader` without `onBack`, and `fallbackHref` (default `"/"`).
+ * On `@vvedantb/native-ui/expo-router` only, so the other entries never import
+ * `expo-router`.
+ */
+export function RouterStackPageHeader({ fallbackHref = "/", ...props }: RouterStackPageHeaderProps) {
+  const router = useRouter();
+  return <StackPageHeader {...props} onBack={() => goBackOrReplace(router, fallbackHref)} />;
+}

package/src/settings/SettingsEmptyState.tsx

@@ -0,0 +1,44 @@
+import type { ComponentType, ReactNode } from "react";
+import { Text, View } from "react-native";
+import type { IconProps } from "@tabler/icons-react-native";
+import { textStyle, typeStyle } from "../controlStyles";
+import { useLargerText } from "../theme";
+import { tokens } from "../tokens";
+import { useScheme } from "../useScheme";
+
+export type SettingsEmptyStateProps = {
+  title: string;
+  description?: string;
+  /** Optional icon above the title, as on the web. */
+  icon?: ComponentType<IconProps>;
+  /** Below the text, such as a `Button`. */
+  action?: ReactNode;
+  testID?: string;
+};
+
+/**
+ * A compact empty note for the inside of a `SettingsSection` (web
+ * `SettingsEmptyState`): centred title, muted description and an optional
+ * action, with no large icon. Use `EmptyState` for a whole screen.
+ */
+export function SettingsEmptyState({ title, description, icon: Icon, action, testID }: SettingsEmptyStateProps) {
+  const scheme = useScheme();
+  const largerText = useLargerText();
+  return (
+    <View testID={testID} className="items-center gap-1 px-2 py-4">
+      {Icon ? <Icon size={largerText ? 24 : 20} color={tokens.color.muted[scheme]} /> : null}
+      <Text
+        className="text-center font-instrument-sans-semibold text-base"
+        style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+      >
+        {title}
+      </Text>
+      {description ? (
+        <Text className="text-center font-instrument-sans text-sm" style={textStyle("muted", scheme)}>
+          {description}
+        </Text>
+      ) : null}
+      {action ? <View className="mt-2">{action}</View> : null}
+    </View>
+  );
+}