@vvedantb/native-ui 0.2.0 → 0.3.12

package/README.md

@@ -1,8 +1,8 @@
 # `@vvedantb/native-ui`
 
-React Native + Expo primitives extracted from a React Native app. Floating pill chrome, Android-safe shadows, forms, list rows, and settings sections.
+React Native + Expo primitives extracted from a React Native app. Floating pill chrome, Android-safe shadows, forms, overlays, toasts, list rows, settings sections and the family app marks.
 
-Web apps should keep using `@vvedantb/ui`. This package is native-only.
+Web apps should keep using `@vvedantb/ui`. This package is native-only. Components that exist on both sides use the web names and, where they make sense on touch, the web props. `docs/native-ui-parity.md` at the repository root lists every `@vvedantb/ui` export and its native status.
 
 ## Install
 
@@ -14,7 +14,6 @@ Peers the app must already have (Expo SDK 57 / RN 0.76+):
 
 - `react`, `react-native`
 - `nativewind` `>=4`
-- `expo-blur`, `expo-haptics`, `expo-linear-gradient`
 - `react-native-reanimated`, `react-native-safe-area-context`, `react-native-screens`
 - `@rn-primitives/slot`, `@rn-primitives/switch`, `@rn-primitives/select`
 - `@expo/vector-icons`, `@tabler/icons-react-native`, `lucide-react-native`
@@ -22,9 +21,67 @@ Peers the app must already have (Expo SDK 57 / RN 0.76+):
 
 Optional, only if you import those components:
 
-- `expo-router` — `FloatingTabBar`
 - `@gorhom/bottom-sheet` — `BottomSheetContainer`
 - `@react-native-community/datetimepicker` and `dayjs` — `DateTimeField`
+- `react-native-svg` — the app marks (`APP_ICONS`, `Icon*`, `AppMark`, `AppWordmark`) and `PricingModal`. Apps with the icon peers above already have it: `lucide-react-native` and `@tabler/icons-react-native` both require it.
+
+Optional and loaded only when installed, so the package imports and runs without them:
+
+- `expo-blur` — glass blur on `FloatingSurface` and the chrome built on it. Without it, those surfaces draw a solid fill.
+- `expo-haptics` — the selection haptic on `FloatingTabBar`, `Tabs` and `Checkbox` presses. Without it, presses are silent.
+- `expo-linear-gradient` — the gradient in `AmbientBackground`. Without it, the background is the solid `tokens.color.background`.
+
+The package loads these three with a `require` inside `try`. Metro treats that as an optional dependency when `transformer.allowOptionalDependencies` is on, which is the default in the Expo and React Native Metro configs. `@vvedantb/native-ui/blur` exports the loader (`loadBlur`) and `@vvedantb/native-ui/haptics` exports `loadHaptics` and `selectionHaptic`. TypeScript still resolves their types: an app that type-checks without them reports a missing module in `src/blur.ts`, `src/haptics.ts` or `src/gradient.ts`. Declare the missing ones in a `.d.ts` file in the app:
+
+```ts
+declare module "expo-blur";
+declare module "expo-haptics";
+declare module "expo-linear-gradient";
+```
+
+`expo-router` stays an optional peer, but the package does not import it. `FloatingTabBar` declares the props it reads (`FloatingTabBarProps`) and fits the `tabBar` prop of Expo Router's `Tabs` on Expo SDK 57. Expo SDK 58 passes `emitter` and `navigateToTab` to `tabBar` in place of `navigation`, so the bar does not fit it yet.
+
+To hide a tab, give its screen Expo Router's `href: null`. From 0.3.9 `FloatingTabBar` draws no tab for that route. It also hides a route whose `tabBarItemStyle` resolves to `display: "none"`, because Expo Router's `Tabs` can pass `href: null` on in that form. The other tabs keep their focus and navigation, as `state.index` still counts every route:
+
+```tsx
+<Tabs tabBar={(props) => <FloatingTabBar {...props} />}>
+  <Tabs.Screen name="index" options={{ title: "Home" }} />
+  <Tabs.Screen name="details" options={{ href: null }} />
+</Tabs>
+```
+
+## Entry points
+
+The root entry exports everything. It still imports `BottomSheetContainer` and `DateTimeField`, so Metro resolves `@gorhom/bottom-sheet`, `@react-native-community/datetimepicker` and `dayjs` for any import from it. Apps without those peers, such as V Store, should import from the smaller entries below. Between them, they export every name the root exports.
+
+| Entry | Exports | Optional peers it reaches |
+| --- | --- | --- |
+| `@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`, `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`, `Tabs`, `PillTabs`, `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet`, `toast`, `Toaster` | `expo-blur`, `expo-haptics` (loaders) |
+| `@vvedantb/native-ui/search-input` | `SearchInput`, `SearchInputProps` | 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`, `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) |
+
+"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.
+
+```tsx
+import { FloatingTabBar } from "@vvedantb/native-ui/tab-bar";
+import { AppMark } from "@vvedantb/native-ui/brand";
+import { NativeUiProvider } from "@vvedantb/native-ui/theme";
+import { SearchInput } from "@vvedantb/native-ui/search-input";
+import { toast, Toaster } from "@vvedantb/native-ui/toast";
+```
+
+The entries re-export the same source files, so they can be mixed: `NativeUiProvider` from `/theme` sets the context that `FloatingTabBar` from `/tab-bar` reads. `tests/subpaths.test.ts` walks the imports from each entry and fails if one of the basic entries reaches a heavy peer other than through its loader.
 
 ## Expo / NativeWind
 
@@ -50,7 +107,9 @@ config.resolver.nodeModulesPaths = [
 ];
 ```
 
-The app must define NativeWind tokens (`bg-surface`, `bg-secondary`, `text-foreground`, pink utilities) and Instrument Sans font classes (`font-instrument-sans-*`). Accent pink stays in the app stylesheet.
+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.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.
 
 ## Theme
 
@@ -66,17 +125,109 @@ import { NativeUiProvider, Button, Card } from "@vvedantb/native-ui";
 </NativeUiProvider>
 ```
 
-`useLargerText()` steps type and tap targets up. `accentColor` tints FABs and card icons. Surfaces use the tokens in `src/tokens.ts` for fill, radius (card 24, row 20, pill 999) and spacing (16).
+`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` |
+| Overlays | `Dialog`, `AlertDialog`, `ConfirmDialog`, `Sheet` (RN `Modal`, each with the web part names), `BottomSheetContainer` (`@gorhom/bottom-sheet`) |
+| Feedback | `toast()` and `<Toaster />` |
+| Brand and upgrade | `APP_ICONS`, `IconVibot` and the other `Icon*`, `AppMark`, `AppWordmark`, `FAMILY_APPS`, `V_PRO_APP_BENEFITS`, `UpgradeToProCard`, `PricingModal` |
+| Settings and layout | `SettingsSection`, `SettingsField`, `SettingsToggleRow`, `SettingsStack`, `ScreenContainer`, `SafeAreaContainer`, `FloatingSurface`, `AmbientBackground` |
+
+Overlays hold their own open state, or take `open` and `onOpenChange`:
+
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Delete this list?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction variant="destructive" onPress={remove}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+As on the web, `AlertDialogAction` does not close the dialog; `ConfirmDialog` closes on either button. `DialogFooter` and `AlertDialogFooter` lay their buttons out in a row at the end, as the web does from `sm` up. Pass `fullWidth={false}` to a plain `Button` there (`AlertDialogAction` and `AlertDialogCancel` already default to it). `SheetFooter` stacks full width.
+
+From 0.3.7, in a compact window (639 wide or less, or 500 high or less: the web `COMPACT_OVERLAY_QUERY`) `DialogContent`, and so `AlertDialogContent` and `ConfirmDialog`, is the web phone bottom sheet: full width, top corners 16, a handle, the bottom safe-area inset. Its footer stacks the buttons full width and at least 44 high, the last child on top, whatever `fullWidth` says. Pass `viewportAware={false}` to keep the centred dialog at every size.
+
+From 0.3.8 `UpgradeToProCard` has the web `SidebarUpgradeCard` sizes: a 14 / 600 title, a 32-high pill with a 12 / 500 label (the web `Button` `sm`), `px-3 py-2.5` padding and radius 16. With larger text the title and pill keep their larger sizes.
+
+From 0.3.9 `SearchInput` is the web search field: a search icon, and a clear button while there is text. It is controlled with `value` and `onChange(text)`; `onClear` runs whenever the value becomes empty. `size="sm"` (default) is 32 high and `md` 40, border included, as on the web. From 0.3.12 that height is locked, so the line height of the text class cannot grow the field; it still grows with the system font size. The clear button is painted at 24 and reaches 44 with its hit slop. Inside a `ScrollView`, set `keyboardShouldPersistTaps="handled"` so the first tap on it clears while the keyboard is up. The web `shortcut` hint and `toolbar` variant are not ported.
+
+```tsx
+const [query, setQuery] = useState("");
+<SearchInput value={query} onChange={setQuery} label="Search apps" />
+```
+
+Toasts need one `<Toaster />` inside `SafeAreaProvider`, after the navigator. Then call `toast("Saved")`, `toast.error("Failed")` or `toast.loading("Syncing")` from anywhere. Pass the returned id to replace a toast (`toast.success("Synced", { id })`). On iOS toasts show over modals; on Android a `Modal` covers them.
+
+From 0.3.12 a toast looks like the web `SonnerToaster` at its default density with `toastIcons="filled24"`: the filled 24 success, info, warning and error icons (the web paths, in `palette` colours), a `text-sm` medium title, `px-4 py-3`, radius 16, and the flat overlay fill with a 1 px ring and a light shadow (`smooth-shadow-ring-md`). Toasts no longer blur.
+
+`Tabs` shares its name with Expo Router's `Tabs` layout. In a file that needs both, import one under another name.
+
+`@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.
+
+## 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`.
+
+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` and `Skeleton` 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.
 
 ## Floating UI / Android shadows
 
-Do not put `elevation` or NativeWind `shadow-*` on nested or translucent chrome. `floatingShadow` is iOS `shadow*` and Android/web `boxShadow`. `FloatingSurface` paints an opaque fill on Android and clips on an inner view. Blur is iOS-only.
+Do not put `elevation` or NativeWind `shadow-*` on nested or translucent chrome. `floatingShadow` is iOS `shadow*` and Android/web `boxShadow`. `FloatingSurface` clips on an inner view.
+
+Only chrome that floats on the web too has a shadow: dialogs, sheets and toasts, plus the native `FloatingTabBar` and `FloatingFAB`. From 0.3.5 `Card` and `SettingsSection` are flat (`cardStyle`: the web `rounded-lg bg-surface-card`), and `Button` is flat unless you pass `shadowType="shadow"`.
+
+## Glass blur (iOS and Android)
+
+With `expo-blur` installed, `FloatingSurface` blurs on iOS and Android. So do the components built on it: `FloatingTabBar`, the `Select` popover and `GlassSheetBackground`. `Card` and `SettingsSection` do not blur from 0.3.5, nor toasts from 0.3.12. Web uses a CSS backdrop blur. A surface draws the solid fill when `expo-blur` is not installed, with `blur={false}`, or when Reduce Transparency is on.
+
+Since expo-blur 55, Android blur needs a target: the content to blur. Wrap the screen content in `GlassBlurTarget` and render the floating chrome outside it, with both inside one `GlassBlurProvider`:
+
+```tsx
+import { GlassBlurProvider, GlassBlurTarget } from "@vvedantb/native-ui";
+
+<GlassBlurProvider>
+  <GlassBlurTarget>
+    <Stack />
+  </GlassBlurTarget>
+  <Toaster />
+</GlassBlurProvider>
+```
+
+With `FloatingTabBar`, put `GlassBlurProvider` around `Tabs` and wrap each tab screen's content in `GlassBlurTarget`. Pass `active={isFocused}` (for example from React Navigation's `useIsFocused()`) so the bar blurs the visible tab. The last active target wins.
+
+`GlassBlurTarget` is a view with `flex: 1`; pass `style` to change that. A blur view must not sit inside its own target, so surfaces inside a target (such as cards on the screen) get none. Without a target, expo-blur logs a warning on Android and draws only its tint, which under the glass fill looks almost solid.
+
+On Android the `BlurView` uses the dimezis method (`experimentalBlurMethod` and `blurMethod` set to `"dimezisBlurView"`) with `blurReductionFactor={3}`, and the same `tint` and `intensity` as iOS. The translucent glass fill is laid over the Android blur, because on iOS the blur samples that fill and dimezis does not. expo-blur 55 and later log a deprecation warning for `experimentalBlurMethod` when each Android `BlurView` mounts.
 
 ## Tokens
 
-The JS tokens (colours, radii, spacing) live in `src/tokens.ts`. It is a copy of `@vvedantb/ui/tokens/native`, kept inside this package so React Native apps do not install `@vvedantb/ui` (Radix, react-dom and the rest of the web stack) for colour values. A test in `@vvedantb/ui` fails when the two files differ, so change both together.
+The JS tokens (colours, radii, spacing) live in `src/tokens.ts`. It is a copy of `packages/ui/tokens/src/native.ts` (the `tokens` export of `@vvedantb/ui`), kept inside this package so React Native apps do not install `@vvedantb/ui` (Radix, react-dom and the rest of the web stack) for colour values. A test in each package fails when the two files differ, so change both together. From 0.3.3 the neutrals and radii match the web `tokens.css` (oklch converted to sRGB hex), and a test converts `tokens.css` and fails when they drift. `fill`, `hairline` and `radius.card` are native-only.
+
+`palette` holds the web semantic colours that `tokens` lacks (`primary`, `danger`, `success`, `warning`, `default`, `overlay`, `segment` and others), each `{ light, dark }`. A test converts `tokens.css` and fails when a value drifts. `withAlpha("#rrggbb", 0.12)` gives tints such as the web `bg-danger/12`.
+
+The brand files `src/brand/svg.ts`, `familyApps.ts` and `vProAppBenefits.ts` are byte-identical copies of `packages/ui/src/brand/`. A test fails when they differ.
+
+`fontClass` lists the Instrument Sans classes. `AppWordmark` uses `font-instrument-sans-medium` (weight 500) with -0.02em letter spacing, as on the web.
+
+## Type checking
 
-Apps that already depend on `@vvedantb/ui` can import the same values from `@vvedantb/ui/tokens/native`.
+`pnpm --filter @vvedantb/native-ui typecheck` runs `tsc` against `types/peers.d.ts`, local declarations of the React Native peers, because they are not installed in this repository. The declarations are looser than the real types. Apps type-check the source against the real packages.
 
 ## Publish
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.2.0",
+  "version": "0.3.12",
   "license": "MIT",
-  "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, settings chrome, and tab bar.",
+  "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar and the family app marks.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -16,7 +16,72 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./tab-bar": {
+      "types": "./src/entries/tab-bar.ts",
+      "default": "./src/entries/tab-bar.ts"
+    },
+    "./brand": {
+      "types": "./src/entries/brand.ts",
+      "default": "./src/entries/brand.ts"
+    },
+    "./button": {
+      "types": "./src/entries/button.ts",
+      "default": "./src/entries/button.ts"
+    },
+    "./primitives": {
+      "types": "./src/entries/primitives.ts",
+      "default": "./src/entries/primitives.ts"
+    },
+    "./search-input": {
+      "types": "./src/entries/search-input.ts",
+      "default": "./src/entries/search-input.ts"
+    },
+    "./toast": {
+      "types": "./src/entries/toast.ts",
+      "default": "./src/entries/toast.ts"
+    },
+    "./theme": {
+      "types": "./src/entries/theme.ts",
+      "default": "./src/entries/theme.ts"
+    },
+    "./floating": {
+      "types": "./src/entries/floating.ts",
+      "default": "./src/entries/floating.ts"
+    },
+    "./layout": {
+      "types": "./src/entries/layout.ts",
+      "default": "./src/entries/layout.ts"
+    },
+    "./marketing": {
+      "types": "./src/entries/marketing.ts",
+      "default": "./src/entries/marketing.ts"
+    },
+    "./ambient": {
+      "types": "./src/entries/ambient.ts",
+      "default": "./src/entries/ambient.ts"
+    },
+    "./bottom-sheet": {
+      "types": "./src/entries/bottom-sheet.ts",
+      "default": "./src/entries/bottom-sheet.ts"
+    },
+    "./date-time": {
+      "types": "./src/entries/date-time.ts",
+      "default": "./src/entries/date-time.ts"
+    },
+    "./gallery": {
+      "types": "./src/examples/ParityGallery.tsx",
+      "default": "./src/examples/ParityGallery.tsx"
+    },
+    "./blur": {
+      "types": "./src/blur.ts",
+      "default": "./src/blur.ts"
+    },
+    "./haptics": {
+      "types": "./src/haptics.ts",
+      "default": "./src/haptics.ts"
+    },
+    "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
   "files": [
@@ -24,6 +89,12 @@
     "LICENSE"
   ],
   "sideEffects": false,
+  "scripts": {
+    "build": "node -e \"require('node:fs').accessSync('src/index.ts')\"",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "prepack": "node -e \"require('node:fs').accessSync('src/index.ts')\""
+  },
   "peerDependencies": {
     "@expo/vector-icons": "*",
     "@gorhom/bottom-sheet": ">=5",
@@ -46,6 +117,7 @@
     "react-native-reanimated": "*",
     "react-native-safe-area-context": "*",
     "react-native-screens": "*",
+    "react-native-svg": "*",
     "tailwind-merge": ">=2.0.0"
   },
   "peerDependenciesMeta": {
@@ -58,8 +130,20 @@
     "dayjs": {
       "optional": true
     },
+    "expo-blur": {
+      "optional": true
+    },
+    "expo-haptics": {
+      "optional": true
+    },
+    "expo-linear-gradient": {
+      "optional": true
+    },
     "expo-router": {
       "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -67,9 +151,5 @@
     "react": "^19.1.0",
     "typescript": "^5.9.0",
     "vitest": "^3.2.0"
-  },
-  "scripts": {
-    "build": "node -e \"require('node:fs').accessSync('src/index.ts')\"",
-    "test": "vitest run"
   }
-}
+}

package/src/AlertDialog.tsx

@@ -0,0 +1,73 @@
+import { Button, type ButtonProps } from "./Button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  type DialogContentProps,
+  type DialogProps,
+} from "./Dialog";
+import { useOverlay } from "./primitives/overlay";
+
+export type AlertDialogProps = DialogProps;
+
+/** A `Dialog` whose content blocks backdrop taps. Android back still closes it, as Escape does on the web. */
+export function AlertDialog(props: AlertDialogProps) {
+  return <Dialog {...props} />;
+}
+
+export const AlertDialogTrigger = DialogTrigger;
+
+export type AlertDialogContentProps = Omit<DialogContentProps, "dismissible">;
+
+/** `DialogContent` with no backdrop dismiss and, by default, no close button. */
+export function AlertDialogContent({
+  hideCloseButton = true,
+  ...props
+}: AlertDialogContentProps) {
+  return (
+    <DialogContent hideCloseButton={hideCloseButton} dismissible={false} {...props} />
+  );
+}
+
+export const AlertDialogHeader = DialogHeader;
+export const AlertDialogFooter = DialogFooter;
+export const AlertDialogTitle = DialogTitle;
+export const AlertDialogDescription = DialogDescription;
+
+/**
+ * Confirm button. As on the web it does not close the dialog: close it in
+ * `onPress` (set `open` to false). Not full width by default, for the row
+ * footer; full width in the stacked footer of the compact sheet.
+ */
+export function AlertDialogAction(props: ButtonProps) {
+  return <Button shadowType="flat" fullWidth={false} {...props} />;
+}
+
+/**
+ * Cancel button: runs `onPress`, then closes the dialog. Default variant
+ * `outline`, as on the web. Not full width, except in the stacked footer of
+ * the compact sheet.
+ */
+export function AlertDialogCancel({
+  variant = "outline",
+  onPress,
+  ...props
+}: ButtonProps) {
+  const { setOpen } = useOverlay("AlertDialogCancel");
+  return (
+    <Button
+      variant={variant}
+      shadowType="flat"
+      fullWidth={false}
+      {...props}
+      onPress={() => {
+        onPress?.();
+        setOpen(false);
+      }}
+    />
+  );
+}

package/src/AmbientBackground.tsx

@@ -1,28 +1,43 @@
 import { StyleSheet, View, type ViewProps } from "react-native";
-import { LinearGradient } from "expo-linear-gradient";
-import { useColorScheme } from "nativewind";
 import { cn } from "./cn";
+import { loadLinearGradient } from "./gradient";
+import { tokens } from "./tokens";
+import { useScheme } from "./useScheme";
 
 const LIGHT = ["#f6f6f7", "#fde8f0", "#f4f5f7"] as const;
 const DARK = ["#1c1c1e", "#2a1820", "#1a1a1c"] as const;
 
+/**
+ * A soft gradient behind the screen. Without the optional
+ * `expo-linear-gradient` peer it draws the solid `tokens.color.background`.
+ */
 export function AmbientBackground({
   children,
   className,
   ...props
 }: ViewProps & { className?: string }) {
-  const { colorScheme } = useColorScheme();
-  const colors = colorScheme === "dark" ? DARK : LIGHT;
+  const scheme = useScheme();
+  const LinearGradient = loadLinearGradient()?.LinearGradient;
 
   return (
     <View className={cn("flex-1", className)} {...props}>
-      <LinearGradient
-        pointerEvents="none"
-        colors={[...colors]}
-        start={{ x: 0.05, y: 0 }}
-        end={{ x: 0.95, y: 1 }}
-        style={StyleSheet.absoluteFill}
-      />
+      {LinearGradient ? (
+        <LinearGradient
+          pointerEvents="none"
+          colors={[...(scheme === "dark" ? DARK : LIGHT)]}
+          start={{ x: 0.05, y: 0 }}
+          end={{ x: 0.95, y: 1 }}
+          style={StyleSheet.absoluteFill}
+        />
+      ) : (
+        <View
+          pointerEvents="none"
+          style={{
+            ...StyleSheet.absoluteFillObject,
+            backgroundColor: tokens.color.background[scheme],
+          }}
+        />
+      )}
       {children}
     </View>
   );

package/src/Avatar.tsx

@@ -0,0 +1,141 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import {
+  Image,
+  StyleSheet,
+  Text,
+  View,
+  type ImageProps,
+  type ViewProps,
+} from "react-native";
+import { cn } from "./cn";
+import { typeStyle } from "./controlStyles";
+import { palette } from "./palette";
+import { tokens } from "./tokens";
+import { useScheme } from "./useScheme";
+
+type ImageStatus = "idle" | "loaded" | "error";
+
+const AvatarContext = createContext<{
+  size: number;
+  status: ImageStatus;
+  setStatus: (status: ImageStatus) => void;
+} | null>(null);
+
+function useAvatar(part: string) {
+  const context = useContext(AvatarContext);
+  if (!context) throw new Error(`${part} must be inside an Avatar.`);
+  return context;
+}
+
+export type AvatarProps = ViewProps & {
+  /** Diameter in points. Default 40 (the web `h-10 w-10`). */
+  size?: number;
+  className?: string;
+};
+
+/** Round frame for `AvatarImage` and `AvatarFallback`, as the web `Avatar`. The fallback shows until the image loads, and stays if it fails. */
+export function Avatar({ size = 40, className, style, children, ...props }: AvatarProps) {
+  const scheme = useScheme();
+  const [status, setStatus] = useState<ImageStatus>("idle");
+  return (
+    <AvatarContext.Provider value={{ size, status, setStatus }}>
+      <View
+        className={cn("relative shrink-0 overflow-hidden border", className)}
+        style={[
+          {
+            width: size,
+            height: size,
+            borderRadius: size / 2,
+            borderColor: tokens.color.border[scheme],
+            backgroundColor: tokens.color.surfaceSecondary[scheme],
+          },
+          style,
+        ]}
+        {...props}
+      >
+        {children}
+      </View>
+    </AvatarContext.Provider>
+  );
+}
+
+export type AvatarImageProps = Omit<ImageProps, "style"> & {
+  className?: string;
+};
+
+export function AvatarImage({ onLoad, onError, className, ...props }: AvatarImageProps) {
+  const { status, setStatus } = useAvatar("AvatarImage");
+  // A new source gets a fresh try: back to the fallback until it loads.
+  const sourceKey = JSON.stringify(props.source);
+  const previousSource = useRef(sourceKey);
+  useEffect(() => {
+    if (previousSource.current === sourceKey) return;
+    previousSource.current = sourceKey;
+    setStatus("idle");
+  }, [sourceKey, setStatus]);
+  if (status === "error") return null;
+  return (
+    <Image
+      resizeMode="cover"
+      className={className}
+      style={StyleSheet.absoluteFill}
+      onLoad={(event) => {
+        setStatus("loaded");
+        onLoad?.(event);
+      }}
+      onError={(event) => {
+        setStatus("error");
+        onError?.(event);
+      }}
+      {...props}
+    />
+  );
+}
+
+export type AvatarFallbackProps = ViewProps & {
+  /** Usually initials (see `initials()`). A string is centred in Instrument Sans at 40% of the avatar size. */
+  children?: ReactNode;
+  className?: string;
+  textClassName?: string;
+};
+
+export function AvatarFallback({
+  children,
+  className,
+  textClassName,
+  style,
+  ...props
+}: AvatarFallbackProps) {
+  const { size, status } = useAvatar("AvatarFallback");
+  const scheme = useScheme();
+  if (status === "loaded") return null;
+  return (
+    <View
+      className={cn("absolute inset-0 items-center justify-center", className)}
+      style={[{ backgroundColor: palette.default[scheme] }, style]}
+      {...props}
+    >
+      {typeof children === "string" ? (
+        <Text
+          numberOfLines={1}
+          className={cn("font-instrument-sans-semibold", textClassName)}
+          style={[
+            { fontSize: Math.round(size * 0.4), color: palette.defaultForeground[scheme] },
+            typeStyle("semibold"),
+          ]}
+        >
+          {children}
+        </Text>
+      ) : (
+        children
+      )}
+    </View>
+  );
+}