@oxyhq/bloom 0.86.0 → 0.87.0

package/NOTICE

@@ -1,5 +1,8 @@
 @oxyhq/bloom
-Copyright (c) Oxy HQ
+Copyright (c) 2026-present The Oxy Collective Inc
+
+This product is licensed under the Apache License, Version 2.0. See the LICENSE
+file.
 
 This product includes software derived from third-party open-source projects.
 

package/README.md

@@ -1,515 +1,187 @@
-# Bloom
+<p align="center">
+  <b>Bloom is the UI library every Oxy app is built with.</b><br>
+  One component set for React Native, Expo and the web, with the same props on every platform.
+</p>
 
-Shared UI component library for the Oxy ecosystem. Built for React Native + Expo + Web.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@oxyhq/bloom"><img alt="npm" src="https://img.shields.io/npm/v/@oxyhq/bloom?style=flat-square&color=440151&label=%40oxyhq%2Fbloom"></a>
+  <a href="./LICENSE"><img alt="License Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-informational?style=flat-square"></a>
+  <img alt="React Native" src="https://img.shields.io/badge/React%20Native-0.73%2B-61DAFB?style=flat-square&logo=react&logoColor=black">
+  <img alt="Expo" src="https://img.shields.io/badge/Expo-supported-000020?style=flat-square&logo=expo&logoColor=white">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white">
+  <img alt="Bun" src="https://img.shields.io/badge/Bun-1.3.14-000000?style=flat-square&logo=bun&logoColor=white">
+</p>
 
-## Install
-
-```sh
-bun add @oxyhq/bloom
-```
-
-### Peer dependencies
-
-Required:
-
-- `react >= 18`
-- `react-native >= 0.73`
-- `react-native-safe-area-context >= 5`
-
-Also required:
-
-- `react-native-reanimated >= 3.13` (`Dialog`, `BottomSheet`, `toast`, `Loading`) — on web too: the toast engine runs on react-native-web.
-- `react-native-gesture-handler >= 2.16.1` (`Dialog`, `BottomSheet`, toast swipe-to-dismiss) — **native** also needs the app root wrapped in `GestureHandlerRootView`, see [Dialog](#dialog); on web the toast host provides its own.
-- `react-native-svg >= 13` (Bloom icons, Avatar `squircle` shape)
-
-## Usage
-
-### App root
-
-Mount `BloomProvider` once, at the very top of the app. It composes every piece of
-app-wide Bloom state — theme, haptics, image resolution, scroll restoration and the
-tab-bar minimize progress — so none of them can end up at the wrong depth. It takes
-all of `BloomThemeProvider`'s props plus `imageResolver` and `haptics`.
-
-```tsx
-import { BloomProvider } from '@oxyhq/bloom/provider';
-
-<BloomProvider
-  defaultMode="system"
-  defaultColorPreset="blue"
-  persistKey="app.theme"
-  storage={storage}
-  imageResolver={(id, variant) => oxyServices.getFileDownloadUrl(id, variant)}
->
-  <App />
-</BloomProvider>
-```
-
-Everything scrollable must be **under** it: `useScrollRestoration()` throws outside
-its provider, so a list rendered beside the root (a right rail, an overlay) crashes
-the screen.
-
-Outlets are **not** included — their position in the tree is a real app decision, and
-a second mount duplicates every surface they render. Mount these yourself, under
-`BloomProvider`: `<ToastOutlet>`, `<Portal.Provider>`/`<Portal.Outlet>`,
-`<SurfaceHost>`, `<BloomDialogProvider>`, `<AlertDialogHost>`.
-
-### Theme
-
-`BloomProvider` already mounts `BloomThemeProvider`; mount it directly only when you
-need a nested/scoped theme. It accepts controlled `mode` and `colorPreset` props — persist them however you like (AsyncStorage, Zustand, etc.).
-
-```tsx
-import { BloomThemeProvider } from '@oxyhq/bloom/theme';
-
-<BloomThemeProvider mode="system" colorPreset="teal">
-  <App />
-</BloomThemeProvider>
-```
-
-Access theme values in any component:
-
-```tsx
-import { useTheme } from '@oxyhq/bloom/theme';
-
-const theme = useTheme();
-// theme.colors.primary, theme.colors.text, theme.isDark, etc.
-```
-
-10 color presets: `teal`, `blue`, `green`, `amber`, `red`, `purple`, `pink`, `sky`, `orange`, `mint`.
-
-4 modes: `light`, `dark`, `system`, `adaptive` (uses iOS/Android native dynamic colors when available).
-
-### Overlay components: Dialog, BottomSheet, toast / alert
-
-Bloom ships **two** overlay surface components plus feedback helpers:
-
-| Component | Use when |
-|-----------|----------|
-| `Dialog` | All modal surfaces — centered card, side-sheet (left/right), or bottom-sheet — via the `placement` prop. Confirmation flows AND custom content. |
-| `BottomSheet` | You need direct control over snap points, scroll handoff, gesture coordination, or detached presentation. |
-| `toast` / `alert` | Passive feedback (`toast`) or one-shot confirmations (`alert`) called imperatively from anywhere. |
-
-> **Removed in 0.16.x:** `CenteredDialog` and `ResponsiveSheet` no longer exist. Migrate: `<CenteredDialog visible={v} onClose={c}>…</CenteredDialog>` → `<Dialog placement="center" open={v} onClose={c}>…</Dialog>`; `<ResponsiveSheet side="left" open={o} onClose={c}>…</ResponsiveSheet>` → `<Dialog placement={{ base:'bottom', md:'left' }} open={o} onClose={c}>…</Dialog>`.
-
-### Dialog
-
-A single `<Dialog>` component for every overlay surface — centered modal, side-sheet, or bottom-sheet — selected by the `placement` prop. Same component and same props on every platform.
-
-> **Required providers (native).** Your app root **must** be wrapped with `GestureHandlerRootView` from `react-native-gesture-handler` for the bottom-sheet pan gestures to work.
-
-```tsx
-import { GestureHandlerRootView } from 'react-native-gesture-handler';
-import { BloomThemeProvider, BloomDialogProvider } from '@oxyhq/bloom';
-
-export default function Root() {
-  return (
-    <GestureHandlerRootView style={{ flex: 1 }}>
-      <BloomThemeProvider mode="system" colorPreset="oxy">
-        <BloomDialogProvider>
-          <App />
-        </BloomDialogProvider>
-      </BloomThemeProvider>
-    </GestureHandlerRootView>
-  );
-}
-```
-
-`BloomDialogProvider` powers the imperative `alert()` helper — mount it once near the app root.
-
-#### Declarative (the 90% case)
-
-```tsx
-import { Dialog, useDialogControl } from '@oxyhq/bloom';
-
-function SignOutButton() {
-  const control = useDialogControl();
-  return (
-    <>
-      <Button onPress={() => control.open()}>Sign out</Button>
-
-      <Dialog
-        control={control}
-        title="Sign out?"
-        description="You'll need to enter your password to sign in again."
-        actions={[
-          { label: 'Sign out', color: 'destructive', onPress: doSignOut },
-          { label: 'Cancel', color: 'cancel' },
-        ]}
-      />
-    </>
-  );
-}
-```
-
-#### Controlled open state
-
-```tsx
-<Dialog
-  placement="center"
-  open={isOpen}
-  onClose={() => setIsOpen(false)}
-  title="Confirm?"
-  actions={[{ label: 'OK', onPress: handleOk }, { label: 'Cancel', color: 'cancel' }]}
-/>
-```
-
-#### Side-sheet (drawer)
-
-```tsx
-// Fixed left side-sheet
-<Dialog placement="left" control={control} title="Filters">
-  <FilterPanel />
-</Dialog>
-
-// Responsive: bottom-sheet on mobile, left drawer on desktop
-<Dialog placement={{ base: 'bottom', md: 'left' }} control={control} title="Filters">
-  <FilterPanel />
-</Dialog>
-```
-
-#### Custom content
-
-Provide any JSX as `children`. Combine with `title` to keep a consistent header. Set `contentPadding={0}` when the children own their own insets.
+---
 
-```tsx
-<Dialog control={control} title="Pick a tag" contentPadding={0}>
-  <YourCustomBody />
-</Dialog>
-```
+<table>
+<tr>
+<td valign="top" width="50%">
 
-#### Pure custom
+### What it is
 
-Drop the declarative props entirely — `children` owns every pixel.
+Components, hooks and design tokens published as `@oxyhq/bloom` across 88 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
 
-```tsx
-<Dialog control={control}>
-  <YourEntirelyCustomLayout />
-</Dialog>
-```
+Styling is NativeWind classes throughout. There are no colour props and no wrapper components to theme a button, because a second way to set a colour is a second thing that can disagree.
 
-#### Props
-
-- `control?` — from `useDialogControl()`. Omit when using controlled `open` instead.
-- `open?` — controlled open state. When provided, wins over `control`.
-- `placement?` — `'center' | 'left' | 'right' | 'bottom'` or a responsive map `{ base; sm?; md?; lg?; xl? }`. Default: `'center'`. Breakpoints: sm 640 / md 768 / lg 1024 / xl 1280 px.
-- `title?: string` — header text.
-- `description?: string` — supporting copy rendered below the title.
-- `actions?: DialogAction[]` — confirmation buttons. Each action:
-  - `label: string`
-  - `color?: 'default' | 'cancel' | 'destructive'` — defaults to `'default'`.
-  - `onPress?: (e) => void` — invoked after the dialog finishes closing.
-  - `disabled?: boolean`
-  - `shouldCloseOnPress?: boolean` — defaults to `true`. Set `false` while an async action is in flight.
-  - `testID?: string`
-- `children?: React.ReactNode` — custom content rendered after the description.
-- `onClose?: () => void` — fires after the dialog has finished closing. In controlled mode, the host must flip `open` to `false`.
-- `contentPadding?: number` — inner padding of the dialog body. Default `20`. Set `0` for custom children that own their own insets.
-- `width?: number` — side-sheet width (px). Default `460`.
-- `maxWidth?: number` — centered-card max width (px). Default `480`.
-- `maxHeightRatio?: number` — bottom-sheet height as a fraction of viewport height. Default `0.9`.
-- `inset?: { top?; bottom?; left?; right? }` — side-sheet inset (px) from the overlay container edges.
-- `showHandle?: boolean` — show drag handle in bottom-sheet mode. Default `true`.
-- `dismissOnBackdrop?: boolean` — tap backdrop to dismiss. Default `true`.
-- `panelStyle? / panelClassName?` — style/class for the panel surface.
-- `containerStyle? / containerClassName?` — style/class for the root overlay (e.g. rail offset, theme-var scope).
-- `label?: string` — accessibility label.
-- `testID?: string`
-
-#### Web setup
-
-Inject the CSS animations into your global styles once:
+</td>
+<td valign="top" width="50%">
 
-```tsx
-import { BLOOM_DIALOG_CSS } from '@oxyhq/bloom/dialog';
+### How it fits the Oxy platform
 
-// In your HTML head or global CSS file:
-<style>{BLOOM_DIALOG_CSS}</style>
-```
-
-### toast
+Bloom is the presentation layer of [**oxy**](https://github.com/OxyHQ/oxy). It knows nothing about identity or the network, so it has no dependency on the Oxy SDK and can be used on its own.
 
-Passive notifications. Bloom's own universal engine — one implementation on native and web, no `sonner` / `sonner-native` to install.
-
-```tsx
-import { toast } from '@oxyhq/bloom';
-import { ToastOutlet } from '@oxyhq/bloom/toast';
+Where an app does use the SDK, the two meet at one seam: register `imageResolver` once at the root, usually `oxyServices.getFileDownloadUrl` from `@oxyhq/core`, and every `Avatar` and image in the tree resolves bare file ids for free.
 
-// Mount once near the app root, inside BloomThemeProvider:
-<ToastOutlet />
+</td>
+</tr>
+</table>
 
-// Anywhere in your app:
-toast('Saved');
-toast.success('Profile updated');
-toast.error('Network error', { duration: 5000 });
-toast.warning('Please verify your email');
-toast.info('A new version is available');
+## Install
 
-const id = toast.loading('Uploading…');
-toast.dismiss(id);
+```bash
+bun add @oxyhq/bloom
 ```
 
-`toast(content, options?)` accepts strings or React elements, and every method
-returns the toast's id. `options.type` (`'default' | 'success' | 'error' |
-'warning' | 'info' | 'loading'`) is overridden by the typed helpers above; the
-full surface (`promise`, `custom`, `wiggle`, `action`/`description`, stacking,
-positions) is documented in [docs/toast.mdx](docs/toast.mdx).
+<details>
+<summary><b>Peer dependencies</b></summary>
 
-### alert()
+<br>
 
-Imperative one-shot confirmation dialogs, matching React Native's `Alert.alert(title, message?, buttons?)` signature. Calls are queued and rendered through `BloomDialogProvider` — you can call `alert()` from anywhere, including before the provider mounts (alerts queue and drain on subscribe).
+Always required:
 
-```tsx
-import { alert } from '@oxyhq/bloom';
+| Package | Range |
+|---|---|
+| `react` | `>=18.0.0` |
+| `react-dom` | `>=18.0.0` |
+| `react-native` | `>=0.73.0` |
+| `react-native-safe-area-context` | `>=5.0.0` |
+| `react-native-screens` | `>=3.16.0` |
+| `nativewind` | `>=5.0.0` |
 
-alert('Sign out?', 'Are you sure you want to sign out of this device?', [
-  { text: 'Cancel', style: 'cancel' },
-  { text: 'Sign out', style: 'destructive', onPress: doSignOut },
-]);
+Required by specific surfaces, and by more of them than you would guess:
 
-// Single OK button (default when no buttons passed):
-alert('Saved');
-```
+| Package | Range | Needed by |
+|---|---|---|
+| `react-native-reanimated` | `>=3.13.0` | `Dialog`, `BottomSheet`, `toast`, `Loading`, on the web too |
+| `react-native-gesture-handler` | `>=2.16.1` | `Dialog`, `BottomSheet`, swipe to dismiss on toasts |
+| `react-native-svg` | `>=13.0.0` | icons, `Avatar` in `squircle` shape |
+| `react-native-keyboard-controller` | `>=1.11.4` | keyboard aware surfaces |
+| `expo`, `expo-blur`, `expo-font`, `expo-haptics`, `expo-image`, `expo-symbols` | see `package.json` | native effects, fonts, haptics, images and SF Symbols |
+| `expo-glass-effect` | `>=0.1.9` | glass surfaces |
+| `expo-router` | `>=3.0.0` | the `expo-router` variants of `tabs`, `scroll` and `tab-bar` |
+| `@react-native-community/netinfo` | `>=11.1.0` | `connection-status` |
 
-Each button:
+On native, wrap the app root in `GestureHandlerRootView` from `react-native-gesture-handler`, or the bottom sheet pan gestures will not fire.
 
-- `text: string` — required label.
-- `style?: 'default' | 'cancel' | 'destructive'` — defaults to `'default'`.
-- `onPress?: () => void` — fires after the dialog finishes closing.
+</details>
 
-### BottomSheet
+## Getting started
 
-A standalone, draggable bottom sheet built on React Native `Modal` + `react-native-reanimated` + `react-native-gesture-handler`. **Not** based on `@gorhom/bottom-sheet`, so it does not require `BottomSheetModalProvider`. Use it when the compound `Dialog` API doesn't fit, when you want to avoid the Gorhom dependency, or when you need direct control over scroll, keyboard handling, or detached presentation.
+Mount `BloomProvider` once, at the very top of the app. It composes every piece of app wide Bloom state, theme, haptics, image resolution, scroll restoration and tab bar minimise progress, so none of them can end up at the wrong depth.
 
 ```tsx
-import { useRef } from 'react';
-import { BottomSheet, type BottomSheetRef } from '@oxyhq/bloom/bottom-sheet';
-
-function Example() {
-  const sheetRef = useRef<BottomSheetRef>(null);
-
-  return (
-    <>
-      <Button onPress={() => sheetRef.current?.present()}>Open</Button>
-
-      <BottomSheet ref={sheetRef} onDismiss={() => console.log('dismissed')}>
-        <Text>Sheet content</Text>
-      </BottomSheet>
-    </>
-  );
-}
-```
-
-`BottomSheetRef` methods: `present()`, `dismiss()`, `close()`, `expand()`, `collapse()`, `scrollTo(y, animated?)`.
-
-`BottomSheetProps`:
-
-- `children`
-- `onDismiss?: () => void`
-- `enablePanDownToClose?: boolean` — defaults to `true`.
-- `enableHandlePanningGesture?: boolean` — defaults to `true`.
-- `onDismissAttempt?: () => boolean` — return `false` to veto a dismiss attempt.
-- `detached?: boolean` — when `true`, the sheet floats with horizontal margins and rounded corners on all sides; when `false`, it's flush to the bottom edges with rounded top corners only.
-- `showHandle?: boolean` — defaults to `true`. Toggles the drag handle pill at the top of the sheet.
-- `backdropOpacity?: number` — opacity (0–1) of the dimming backdrop once fully visible. Defaults to `0.5`. Use a higher value (e.g. `0.7`) when stacking a sheet over another sheet.
-- `backgroundComponent?` — custom background renderer.
-- `backdropComponent?` — custom backdrop renderer.
-- `style?`
-- `scrollable?: boolean` — defaults to `true`. When `false`, renders `children` directly without the internal `Animated.ScrollView` wrapper. **Required when the sheet's content owns its own scrolling primitive** (e.g. `FlatList`, `SectionList`, or any `VirtualizedList`) — nesting a virtualized list inside the internal ScrollView breaks windowing and triggers a React Native warning. Combine with `manualActivation` so the handle stays draggable while the inner list owns the scroll.
-- `manualActivation?: boolean` — defaults to `false`. When `true`, the body pan uses RNGH's `manualActivation` and only activates when (a) the inner ScrollView is at the top AND (b) the user has moved their finger downward by > 8dp. This is the `@gorhom/bottom-sheet` coordination model — recommended for sheets that contain a scrolling region on Android (the legacy always-active pan can steal vertical events from the inner scroller). Enabling this also gives the drag handle its own dedicated, unconditionally-active gesture so users can always grab the handle even mid-scroll.
-- `dynamicBackdrop?: boolean` — defaults to `false`. When `true`, the backdrop dims proportionally to drag distance — fades from full `backdropOpacity` (sheet at rest) to 30% as the sheet is pulled down 40% of the screen height. This is the iOS Photos / iMessage drag-to-dismiss look. The base `backdropOpacity` still controls the resting dim.
-- `handleComponent?: () => React.ReactNode` — custom drag-handle renderer. When provided (and `showHandle` is `true`), replaces the default 36×5 pill. In `manualActivation` mode the rendered handle sits inside the dedicated handle hit-area and gesture detector so it remains unconditionally draggable.
-
-**Pattern: sheet with a `FlatList` inside.** Use `scrollable={false}` so the BottomSheet doesn't wrap the list in its own ScrollView, plus `manualActivation` so the drag handle remains the dedicated drag-to-dismiss surface while the list owns vertical scroll:
-
-```tsx
-<BottomSheet ref={sheetRef} scrollable={false} manualActivation>
-  <FlatList data={items} renderItem={renderItem} />
-</BottomSheet>
-```
-
-**Pattern: iOS Photos-style backdrop dim.** Combine `manualActivation` (so the inner photo grid keeps scroll ownership) with `dynamicBackdrop` (so the overlay fades as the user pulls down):
+import { BloomProvider } from '@oxyhq/bloom/provider';
 
-```tsx
-<BottomSheet
-  ref={sheetRef}
-  scrollable={false}
-  manualActivation
-  dynamicBackdrop
-  backdropOpacity={0.85}
+<BloomProvider
+  defaultMode="system"
+  defaultColorPreset="blue"
+  persistKey="app.theme"
+  storage={storage}
+  imageResolver={(id, variant) => oxyServices.getFileDownloadUrl(id, variant)}
 >
-  <PhotoGrid />
-</BottomSheet>
-```
-
-### Button
-
-```tsx
-import { Button, PrimaryButton, SecondaryButton, IconButton, GhostButton, TextButton } from '@oxyhq/bloom/button';
-
-<Button variant="primary" size="large" onPress={handlePress}>
-  Save
-</Button>
-
-<IconButton icon={<TrashIcon />} onPress={handleDelete} />
-
-<SecondaryButton disabled>Cancel</SecondaryButton>
+  <App />
+</BloomProvider>
 ```
 
-Variants: `primary`, `secondary`, `icon`, `ghost`, `text`. Sizes: `small`, `medium`, `large`.
-
-### GroupedButtons
+Everything scrollable must sit under it. `useScrollRestoration()` throws outside its provider, so a list rendered beside the root, a right rail or an overlay, crashes that screen.
 
-iOS-settings-style grouped action list.
+Outlets are deliberately not included, because where they sit in the tree is a real application decision and a second mount duplicates every surface they render. Mount these yourself, under `BloomProvider`: `ToastOutlet`, the `Provider` and `Outlet` pair from `@oxyhq/bloom/portal`, `SurfaceHost`, `BloomDialogProvider` and `AlertDialogHost`.
 
 ```tsx
-import { GroupedButtons } from '@oxyhq/bloom/grouped-buttons';
+import { Button } from '@oxyhq/bloom/button';
+import { toast } from '@oxyhq/bloom/toast';
 
-<GroupedButtons>
-  <GroupedButtons.Item label="Edit Profile" icon={<EditIcon />} onPress={handleEdit} />
-  <GroupedButtons.Item label="Settings" onPress={handleSettings} />
-  <GroupedButtons.Item label="Delete Account" destructive onPress={handleDelete} />
-</GroupedButtons>
+<Button onPress={() => toast.success('Saved')}>Save</Button>
 ```
 
-### Divider
+## Theming
 
-```tsx
-import { Divider } from '@oxyhq/bloom/divider';
+<table>
+<tr>
+<td valign="top" width="50%">
 
-<Divider />
-<Divider spacing={16} color="#ccc" />
-<Divider vertical />
-```
+**Four modes**
 
-### RadioIndicator
+`light`, `dark`, `system`, and `adaptive`, which follows the iOS and Android dynamic colours when the platform offers them.
 
 ```tsx
-import { RadioIndicator } from '@oxyhq/bloom/radio-indicator';
-
-<RadioIndicator selected={isSelected} />
-<RadioIndicator selected={true} size={24} selectedColor="#007AFF" />
-```
-
-### Avatar
-
-Supports circle and squircle shapes. Squircle requires `react-native-svg`.
-
-```tsx
-import { Avatar } from '@oxyhq/bloom/avatar';
+import { useTheme } from '@oxyhq/bloom/theme';
 
-<Avatar uri="https://example.com/photo.jpg" size={48} />
-<Avatar uri={userPhoto} shape="squircle" verified verifiedIcon={<BadgeIcon />} />
-<Avatar fallbackSource={require('./default.png')} />
+const theme = useTheme();
+// theme.colors.primary, theme.colors.text, theme.isDark
 ```
 
-### Loading
-
-4 variants: `spinner`, `top` (animated collapse/expand), `skeleton`, `inline`.
-
-```tsx
-import { Loading } from '@oxyhq/bloom/loading';
+`useTheme()` throws outside a provider, so hoist `BloomProvider` above the splash and loading branches, not just above the main tree.
 
-<Loading />
-<Loading variant="spinner" text="Loading..." />
-<Loading variant="top" showLoading={isRefreshing} />
-<Loading variant="skeleton" lines={4} />
-<Loading variant="inline" text="Saving..." />
-```
+</td>
+<td valign="top" width="50%">
 
-Animation is platform-specific but the API and visuals are identical. On native, the spinner (used by `spinner`/`inline`) and the `top` collapse/expand are driven by `react-native-reanimated` (with `react-native-svg` for the spinner blades when available). On web, `Loading` resolves to a CSS-animated fork — a `@keyframes` rotation for the spinner and CSS transitions for the `top` variant — so it imports neither reanimated nor SVG and works in any web bundler (Vite, webpack, Metro-web) with no extra peers.
+**Eighteen colour presets**
 
-### Collapsible
+`teal`, `blue`, `green`, `yellow`, `red`, `purple`, `pink`, `sky`, `orange`, `mint`, `pumpkin`, `gray`, `brown`, `peach`, `rose`, plus `oxy` and `faircoin`, which are reserved for the accounts whose brands they are, and `mono`, which ships with a subscription.
 
-```tsx
-import { Collapsible } from '@oxyhq/bloom/collapsible';
+Every palette is generated from a single seed colour by a dependency free colour engine, into the full Material 3 role set for light and dark. A colour a user picks themselves runs through exactly the same path, so a preset is only a fixed seed.
 
-<Collapsible title="Advanced Options" defaultOpen={false}>
-  <Text>Hidden content here</Text>
-</Collapsible>
-```
+</td>
+</tr>
+</table>
 
-### ErrorBoundary
+## Components
 
-```tsx
-import { ErrorBoundary } from '@oxyhq/bloom/error-boundary';
+Bloom publishes 88 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
 
-<ErrorBoundary onError={(error) => logError(error)}>
-  <App />
-</ErrorBoundary>
+| Group | Exports |
+|---|---|
+| Providers and theme | `provider`, `theme`, `color-presets`, `preset-vars`, `design-tokens`, `tailwind-preset`, `styles`, `hooks` |
+| Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `menu`, `tooltip`, `overlay`, `portal`, `surfaces` |
+| Actions | `button`, `fab`, `frosted-icon-button`, `grouped-buttons`, `pressable-scale`, `pressable-with-hover`, `subtle-hover` |
+| Forms | `text-field`, `field`, `input-group`, `label`, `select`, `combobox`, `command`, `checkbox`, `switch`, `slider`, `segmented-control`, `search`, `prompt-input` |
+| Layout and lists | `grid`, `list`, `scroll`, `tabs`, `tab-bar`, `settings-list`, `content-panel`, `card`, `accordion`, `collapsible`, `divider`, `item` |
+| Identity and media | `avatar`, `avatar-group`, `user-hover-card`, `profile-card`, `image-resolver`, `image-aspect-ratio-cache`, `zoomable-image-gallery`, `media-inset-border`, `progressive-blur`, `fill` |
+| Feedback and data | `toast`, `admonition`, `loading`, `skeleton`, `error-boundary`, `badge`, `chip`, `kbd`, `code`, `link-preview`, `connection-status`, `connection-dots` |
+| Charts and motion | `composition-bar`, `dot-grid-meter`, `stat-bar`, `activity-heatmap`, `motion`, `animated-check`, `icon-circle`, `radio-indicator` |
+| Assets | `icons`, `typography`, `fonts`, `benefit-list` |
 
-<ErrorBoundary
-  title="Oops!"
-  message="Something broke."
-  retryLabel="Retry"
-  fallback={<CustomFallback />}
->
-  <RiskyComponent />
-</ErrorBoundary>
-```
+`tabs`, `scroll` and `tab-bar` each ship an `/expo-router` variant for apps on Expo Router.
 
-### PromptInput
+## Documentation
 
-AI chat input with attachments, fullscreen expand, and submit/stop control.
+Component guides live in [`docs/`](./docs): [getting started](./docs/getting-started.mdx), [theme](./docs/theme.mdx), [design tokens](./docs/design-tokens.mdx), [dialog](./docs/dialog.mdx), [bottom sheet](./docs/bottom-sheet.mdx), [toast](./docs/toast.mdx), [alert](./docs/alert.mdx), [menu](./docs/menu.mdx), [select](./docs/select.mdx), [context menu](./docs/context-menu.mdx), [button](./docs/button.mdx), [avatar](./docs/avatar.mdx), [text field](./docs/text-field.mdx), [settings list](./docs/settings-list.mdx), [tab bar](./docs/tab-bar.mdx), [prompt input](./docs/prompt-input.mdx) and [loading](./docs/loading.mdx).
 
-```tsx
-import {
-  PromptInput,
-  PromptInputTextarea,
-  PromptInputActions,
-  PromptInputAttachments,
-  PromptInputSubmitButton,
-} from '@oxyhq/bloom/prompt-input';
-
-// Simple mode — renders built-in layout
-<PromptInput
-  value={text}
-  onValueChange={setText}
-  onSubmit={handleSend}
-  isLoading={isGenerating}
-  onStop={handleStop}
-  placeholder="Ask anything..."
-/>
-
-// Compound mode — full control over layout
-<PromptInput value={text} onValueChange={setText} onSubmit={handleSend}>
-  <PromptInputAttachments />
-  <PromptInputTextarea placeholder="Type a message..." />
-  <PromptInputActions>
-    <MyAddButton />
-    <PromptInputSubmitButton isLoading={isGenerating} onStop={handleStop} />
-  </PromptInputActions>
-</PromptInput>
-```
-
-## Sub-path exports
-
-```ts
-import { BloomThemeProvider, useTheme } from '@oxyhq/bloom/theme';
-import { Dialog, BloomDialogProvider, alert, useDialogControl } from '@oxyhq/bloom/dialog';
-import { BottomSheet, type BottomSheetRef } from '@oxyhq/bloom/bottom-sheet';
-import { toast, ToastOutlet } from '@oxyhq/bloom/toast';
-import { Button, IconButton } from '@oxyhq/bloom/button';
-import { GroupedButtons } from '@oxyhq/bloom/grouped-buttons';
-import { Divider } from '@oxyhq/bloom/divider';
-import { RadioIndicator } from '@oxyhq/bloom/radio-indicator';
-import { Avatar } from '@oxyhq/bloom/avatar';
-import { Loading } from '@oxyhq/bloom/loading';
-import { Collapsible } from '@oxyhq/bloom/collapsible';
-import { ErrorBoundary } from '@oxyhq/bloom/error-boundary';
-import { PromptInput, PromptInputTextarea } from '@oxyhq/bloom/prompt-input';
-```
+Upgrade notes are in [MIGRATION.md](./MIGRATION.md), and the theme reference is in [README.theme.md](./README.theme.md).
 
 ## Development
 
-```sh
+```bash
 bun install
-bun run build        # react-native-builder-bob
-bun run typescript   # type-check
+bun run build        # react-native-builder-bob, then verify the published shape
+bun run typescript   # type check
 bun run test         # jest
+bun run storybook    # component workshop on port 6006
 bun run clean        # remove lib/
 ```
 
+`build` regenerates the platform export map and the theme CSS first, then verifies the package it just produced. If that verification fails, the package is wrong, not the check.
+
+## Contributing
+
+Issues and pull requests are welcome. Please run `bun run typescript` and `bun run test` first. Org wide [contributing notes](https://github.com/OxyHQ/.github/blob/main/CONTRIBUTING.md), the [security policy](https://github.com/OxyHQ/.github/blob/main/SECURITY.md) and the [code of conduct](https://github.com/OxyHQ/.github/blob/main/CODE_OF_CONDUCT.md) live in the organisation profile.
+
 ## License
 
-AGPL-3.0-only -- The Oxy Foundation, Inc. See the [LICENSE](LICENSE) file for details.
+Apache-2.0, The Oxy Collective Inc. See [LICENSE](./LICENSE).
+
+Bloom moved from AGPL-3.0-only to Apache-2.0 at `0.87.0`. Versions published before that keep AGPL-3.0-only permanently; a licence change binds future versions only.
+
+Third party code Bloom derives from, principally the universal toast engine, is credited in [NOTICE](./NOTICE).