@oxyhq/bloom 0.89.0 → 1.0.1

package/docs/context-menu.mdx

@@ -0,0 +1,65 @@
+---
+title: ContextMenu
+description: The menu a right-click opens on web and a long press opens on native.
+order: 16
+---
+
+# ContextMenu
+
+The secondary menu for an object on screen. Right-click on web, long press on native.
+
+Its parts are shadcn's, and its rows are the SAME rows `DropdownMenu` and `Menubar` publish — one implementation under three prefixes, so a row behaves identically wherever it is.
+
+## Basic
+
+```tsx
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@oxyhq/bloom/context-menu';
+
+<ContextMenu>
+  <ContextMenuTrigger label="Photo actions">
+    <Image source={photo.source} style={styles.thumb} />
+  </ContextMenuTrigger>
+
+  <ContextMenuContent>
+    <ContextMenuItem
+      onPress={() => share(photo)}
+      trailing={<ContextMenuShortcut>⌘S</ContextMenuShortcut>}>
+      Share
+    </ContextMenuItem>
+    <ContextMenuItem onPress={() => save(photo)}>Save to library</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem variant="destructive" onPress={() => remove(photo)}>
+      Delete
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+`asChild` composes the trigger onto your own element instead of wrapping it, exactly as it does on `DropdownMenu`.
+
+## It opens where the pointer is
+
+On web the menu anchors to the CLICK POINT, not to the trigger's box: right-clicking the bottom-right corner of a large card opens the menu there, not under the card's top-left. A click point is a zero-area anchor, which the same fit / flip / clamp arithmetic every other Bloom surface uses already handles.
+
+On native there is no cursor to anchor to, so a long press presents the same bottom sheet `DropdownMenu` uses.
+
+## No `open` prop, on purpose
+
+`ContextMenu` is uncontrolled by construction. Its open POSITION comes from the pointer event that opened it, so there is no `open` a caller could set that would mean anything — Radix's `ContextMenu.Root` takes the same view. What you get instead is `onOpenChange`:
+
+```tsx
+<ContextMenu onOpenChange={(open) => setDimmed(open)}>
+```
+
+## Rows
+
+Everything `DropdownMenu` documents applies, under the `ContextMenu` prefix: `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup` / `ContextMenuRadioItem`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuGroup`, and `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent`.
+
+Sub-menus fly out beside their trigger row on web and render as an inline disclosure on native — see [DropdownMenu](/docs/bloom/main/dropdown-menu) for the hover, keyboard and placement behaviour, which is shared.

package/docs/design-tokens.mdx

@@ -0,0 +1,254 @@
+---
+title: Design Tokens
+description: The centralized semantic Tailwind / NativeWind vocabulary shared by every Oxy app.
+---
+
+# Design Tokens
+
+`@oxyhq/bloom/design-tokens` ships the **Oxy Unified Design Language**: a
+namespaced, semantic set of utility classes (`bg-fill`, `text-text-tertiary`,
+`p-space-8`, `rounded-radius-20`, `text-body`, `font-body`, `shadow-s`) that
+resolve to the SAME class names on **web (Tailwind)** and **native (NativeWind)**.
+
+Color roles are aliases onto Bloom's existing resolved theme tokens
+(`--background`, `--surface`, `--primary`, …), so they follow the active
+light/dark mode and color preset automatically. The vocabulary is **additive** —
+existing utilities (`bg-background`, `text-muted-foreground`, `rounded-lg`) keep
+working.
+
+## Preset recipes and runtime colour
+
+Bloom ships **34 named recipes**, authored once in the type-checked
+`COLOR_PRESET_REGISTRY`. A recipe is not a frozen light/dark token table: it is
+an identity seed, a scheme variant and optionally explicit secondary/tertiary
+seeds. `BloomThemeProvider`, `getResolvedTokens()` and `BloomColorScope` run
+those seeds through the same colour policy for the active mode and scope.
+Arbitrary consumer seeds remain supported through `buildThemeFromSeed()` and
+`BloomSeedScope`; the named catalog is a set of useful starting points, not the
+limit of the dynamic engine.
+
+```ts
+import {
+  COLOR_PRESET_REGISTRY,
+  COLOR_PRESET_FAMILY_REGISTRY,
+  COLOR_PRESET_GROUPS,
+} from '@oxyhq/bloom';
+
+const cobalt = COLOR_PRESET_REGISTRY.find((recipe) => recipe.name === 'cobalt');
+cobalt?.displayName;   // 'Cobalt + Signal Yellow'
+cobalt?.family;        // 'ocean'
+cobalt?.tertiaryHex;   // '#ffd000'
+
+COLOR_PRESET_FAMILY_REGISTRY[0].displayName; // stable family copy and order
+COLOR_PRESET_GROUPS.ocean.presets;            // ordered recipes for a picker
+```
+
+The 16 `pairing: 'curated'` recipes pin a complementary `tertiaryHex`. The
+identity remains `--primary`; the standout action is `--tertiary`, which is the
+role used by FABs and compose actions. The other 18 recipes derive their accent
+families dynamically. Every recipe exposes `displayName`, `description`,
+`family`, `pairing` and `featured` metadata, so consumer pickers do not need a
+second name/category map. Historical `APP_COLOR_PRESETS`, name arrays, hex
+lookup and access-gate arrays are derived from this registry and retain their
+existing public shapes.
+
+For visual review, run Storybook and open **Theme / Color System Playground**
+(`src/theme/ColorSystemLab.stories.tsx`). It keeps signed-in and public Mention
+views, renders both modes from `getResolvedTokens()`, and filters the complete
+registry by family or curated/derived pairing.
+
+## Opt in
+
+### Native (NativeWind) and Tailwind v3 web
+
+Add the Bloom preset to your `tailwind.config.js`:
+
+```js
+const { bloomTailwindPreset } = require('@oxyhq/bloom/tailwind-preset');
+
+module.exports = {
+  presets: [bloomTailwindPreset],
+  content: [/* your existing globs */],
+  theme: { extend: {/* your existing app overrides */} },
+};
+```
+
+That single line adds every semantic utility. Your `BloomThemeProvider` already
+populates the underlying `--x` color tokens at runtime.
+
+### Tailwind v4 web (auth, console, website) and CSS-first NativeWind (Homiio)
+
+Tailwind v4 apps configure tokens in CSS. **Import Bloom's shipped theme CSS —
+never paste the tokens into your own `global.css`.** Bloom ships a static
+`theme.css` (generated from the same source as `bloomThemeCss()`, so JS and CSS
+cannot drift) at a dedicated export:
+
+```css
+/* your global.css — after the Tailwind import */
+@import "tailwindcss";
+@import "@oxyhq/bloom/design-tokens/theme.css";
+```
+
+That single `@import` registers the full Bloom `@theme` vocabulary (color-role
+aliases, spacing, radius, border-width, typography, shadow), so utilities like
+`rounded-radius-28`, `p-space-8`, and `text-body` resolve without hand-copying
+any `--radius-radius-*` / `--spacing-*` block. The aliases are
+`--color-<role>: var(--canonical)` — direct `var(--x)` references (never
+`hsl(var(--x))`, per Bloom's web CSS-var contract).
+
+Keep only your **app-local** color seeds / `:root` overrides in `global.css`.
+Do NOT re-declare Bloom's radius or spacing scales locally — the imported CSS is
+the single authority.
+
+If you need the block inline (e.g. an app that assembles its stylesheet at build
+time) rather than via `@import`, `bloomThemeBlock()` / `bloomThemeCss()` return
+the exact same content programmatically:
+
+```ts
+import { bloomThemeBlock } from '@oxyhq/bloom/design-tokens';
+// write `bloomThemeBlock()` into your generated global.css
+```
+
+### The pre-JS palette (prerendered apps)
+
+`theme.css` is the **alias** layer: `--color-background: var(--background)`. It
+says nothing about what `--background` *is* — `BloomThemeProvider` writes that at
+startup. So between first paint and hydration, a prerendered page shows whatever
+palette its own stylesheet declares, and a hand-written one is a second source of
+truth that drifts from the preset it claims to mirror.
+
+Generate it instead, at build time:
+
+```ts
+import { getPresetVars, buildSeedScopeVars } from '@oxyhq/bloom/design-tokens';
+
+// Document root: canonical tokens are all it needs.
+getPresetVars('oxy', 'dark'); // { '--background': 'rgb(16 13 16)', … }
+
+// A scoped block — a brand section, a forced-dark region — needs the
+// `--color-x` aliases too, because an alias substitutes where it is DECLARED:
+// overriding `--background` on a subtree does not move a `--color-background`
+// declared at `:root`. That is why hand-written brand themes write every colour
+// twice. `buildSeedScopeVars` returns both namespaces from one seed.
+buildSeedScopeVars({ seed: '#7c5aed', mode: 'dark' });
+```
+
+`buildSeedScopeVars` also writes the ROLE vocabulary (`withScopeAliases`)
+alongside the colour aliases — omitting it is what makes a scoped block paint
+near-black text over a dark photo in forced-dark mode, since the role that
+resolves foreground-over-fill never got scoped with everything else.
+
+A preset's own `hex` + `variant` reproduces `getPresetVars` token-for-token, so
+the document root and a brand scope go through the same code path. Both
+functions are pure — no react, no react-native — so a plain node/bun script can
+import them.
+
+### Consumers that are not browsers
+
+A consumer that cannot run a stylesheet — native UI code, a design tool, a
+codegen step — reads the resolved tokens as data instead. Bloom ships them in
+W3C Design Tokens (DTCG) format, generated from the same colour engine, so the
+JSON and the CSS cannot disagree:
+
+```ts
+import tokens from '@oxyhq/bloom/design-tokens/tokens.json';
+
+tokens.color.oxy.dark.card.$value;    // '#3b323c' — the value of --card
+tokens.color.teal.light.primary.$value; // '#1d6a75'
+tokens.spacing['space-8'].$value;     // '8px'
+tokens.typography.body.fontWeight.$value; // 400
+```
+
+The JSON is an interoperability artifact generated by `generate:tokens-json`,
+not an editable source. Each preset group also carries a `so.oxy.bloom`
+extension with its seed recipe and picker metadata (family, description,
+pairing, featured and optional secondary/tertiary seeds). Keeping the authored
+registry in TypeScript gives duplicate/shape checks and inferred identifier
+types; generating JSON from it gives non-TypeScript tools the same data without
+introducing a second catalog.
+
+`color.<preset>.<scheme>.<token>` covers every preset Bloom ships and both
+schemes. Token names are the CSS custom properties with the leading `--`
+removed, so the mapping to `getPresetVars` output is mechanical. Values are
+sRGB hex — `#rrggbb`, or `#rrggbbaa` for the translucent `-subtle` family.
+Font families and shadows are deliberately absent: families resolve to
+`var(--bloom-font-*)`, which is meaningless off the web, and shadows ship as a
+platform-forked style object (`bloomShadowStyle`). If you need the same data in
+memory rather than from the file, `bloomDesignTokens()` from
+`@oxyhq/bloom/design-tokens` returns it.
+
+## Color roles
+
+| Utility | Role | Canonical token |
+| --- | --- | --- |
+| `bg-bg` | page background | `--background` |
+| `bg-fill` | default surface | `--card` |
+| `bg-fill-secondary` | muted fill | `--muted` |
+| `bg-fill-hover` | secondary hover | `--accent` |
+| `bg-fill-brand` | brand fill | `--primary` |
+| `bg-fill-brand-hover` | brand hover | `--ring` |
+| `bg-fill-inverse` | inverse fill | `--foreground` |
+| `bg-fill-inverse-hover` | inverse hover | `--muted-foreground` |
+| `bg-fill-placeholder` | disabled surface | `--muted` |
+| `text-text` | primary text | `--foreground` |
+| `text-text-secondary` | secondary text | `--muted-foreground` |
+| `text-text-tertiary` | tertiary text | `--muted-foreground` |
+| `text-text-inverse` | text on brand | `--primary-foreground` |
+| `text-text-fixed-light` | always-light text | `--primary-foreground` |
+| `text-text-placeholder` | placeholder text | `--muted-foreground` |
+| `border-border` | default border | `--border` |
+| `border-border-image` | hairline color | `--border` |
+| `border-border-secondary` | softer border | `--input` |
+| `border-border-input` | input border | `--input` |
+| `border-border-input-active` | focused input | `--ring` |
+
+## The neutral surface ramp
+
+`--background`, `--surface`, `--popover`, `--muted`/`--accent` and `--card` are a
+stack: several components carry meaning **only** in the step between two of them —
+an `ActivityHeatmap` empty cell, `Card variant="filled"`, a `Code` block, the
+`StatBar` and `CompositionBar` tracks, `DotGridMeter`'s off dots, a filled `Tabs`
+track, a selected `Item`, the solid `TabBar`, a plain `Card` on a panel, the
+`Toast` action, and the `Avatar`/`BenefitList`/`LinkPreviewCard` placeholders.
+
+Those tones are owned by `SURFACE_RAMP` in `theme/color-policy.ts` rather than
+taken from Material 3's container roles. M3's ramp steps by 2 tones, which at
+these lightnesses is about **1.2 ΔE00** — below the just-noticeable difference for
+two large flat patches. Measured across all 34 presets, **4 tones (~2.4 ΔE00)** is
+the first spacing at which every pair separates.
+
+`--background` is deliberately not part of the ramp: the page tone is every
+consuming app's page colour, so the rungs below it carry the spacing instead.
+`--card` is not either — it sits on the far side of the page in light (tone 100,
+white) and at the top of the ramp in dark, so it is expressed as the engine role
+that means exactly that in each mode.
+
+If you move any of these, measure **every** pair rather than the one you are
+fixing: the light tones 92/94/96/98/100 are exactly `--muted`, `--popover`,
+`--surface`, `--content-area` and `--card`, so any new value for one lands on
+another unless you check.
+
+## Scales
+
+- **Spacing** (px): `space-2/4/8/12/16/20/24/32` + `screen-margin` (20).
+  `p-space-8`, `gap-space-20`, `px-screen-margin`.
+- **Radius** (px): `radius-8/12/20/28/max`. `rounded-radius-20`.
+- **Hairline border**: `border-hairline` (0.5px), pair with `border-border-image`.
+- **Typography**: `text-<role>` (size/line-height) + `font-<role>`
+  (family/weight) for `caption, bodySmall, bodyTitleSmall, body, subtitle,
+  sectionTitle, headerBold, buttonLarge`.
+- **Shadow**: `shadow-s`, `shadow-m` (web box-shadow). On native surfaces apply
+  `bloomShadowStyle('s' | 'm')` (returns RN elevation/shadow props).
+
+### Type scale
+
+| Role | Size / line | Weight | Family |
+| --- | --- | --- | --- |
+| `caption` | 11 / 14 | 400 | sans |
+| `bodySmall` | 13 / 18 | 400 | sans |
+| `bodyTitleSmall` | 13 / 18 | 600 | sans |
+| `body` | 15 / 22 | 400 | sans |
+| `subtitle` | 17 / 24 | 500 | sans |
+| `sectionTitle` | 20 / 26 | 600 | sans |
+| `headerBold` | 28 / 34 | 700 | display |
+| `buttonLarge` | 17 / 22 | 600 | sans |

package/docs/dialog.mdx

@@ -0,0 +1,277 @@
+---
+title: Dialog
+description: A single <Dialog> for every overlay surface — centered modal, side-sheet, or bottom-sheet.
+order: 3
+---
+
+# Dialog
+
+A single `<Dialog>` component for every overlay surface — centered modal, side-sheet (left/right drawer), or bottom-sheet — controlled by the `placement` prop. Same component, same props on every platform.
+
+<Callout variant="warning" title="Required providers (native)">
+Your app root **must** be wrapped with `GestureHandlerRootView` from `react-native-gesture-handler` for the bottom-sheet pan gestures to work. See [Getting started](/docs/bloom/main/getting-started).
+</Callout>
+
+## Declarative (the 90% case)
+
+```tsx
+import { Dialog, useDialogControl, Button } 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
+
+<Callout variant="warning" title="Prefer useDialogControl">
+The controlled path fires `onClose` synchronously on `open` flipping to `false` — ahead of the exit animation. If your `onClose` handler unmounts the consumer (navigates away, removes the dialog from the tree), it races the animation still in flight. `useDialogControl()` doesn't have this footgun: it closes imperatively and only resolves once the exit finishes.
+</Callout>
+
+Pass `open` + `onClose` to drive the dialog from external state instead of `useDialogControl`:
+
+```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>
+```
+
+## Pure custom
+
+Drop the declarative props entirely — `children` owns every pixel.
+
+```tsx
+<Dialog control={control}>
+  <YourEntirelyCustomLayout />
+</Dialog>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `control?` | `DialogControl` | — | From `useDialogControl()`. Omit when using controlled `open`. |
+| `open?` | `boolean` | — | Controlled open state. When provided, wins over `control`. |
+| `placement?` | `DialogPlacement \| ResponsiveDialogPlacement` | `'center'` | Surface anchor. See [Placement](#placement). |
+| `title?` | `string` | — | Header text. |
+| `description?` | `string` | — | Supporting copy below the title. |
+| `actions?` | `DialogAction[]` | — | Confirmation buttons. See [DialogAction](#dialogaction). |
+| `children?` | `React.ReactNode` | — | Custom content rendered after the description. |
+| `onClose?` | `() => void` | — | Fires after the dialog finishes closing. In controlled mode, the host flips `open` to `false`. |
+| `contentPadding?` | `number` | `20` | Inner padding of the dialog body (px). Set `0` for custom children that own their insets. |
+| `width?` | `number` | `460` | Side-sheet width (px) on `left`/`right` placements. |
+| `maxWidth?` | `number` | `480` | Centered-card max width (px). |
+| `maxHeightRatio?` | `number` | `0.9` | Bottom-sheet max height as a fraction of the viewport height. |
+| `inset?` | `{ top?; bottom?; left?; right? }` | — | Side-sheet inset (px) from the overlay container edges. |
+| `showHandle?` | `boolean` | `true` | Show drag handle in bottom-sheet mode. |
+| `dismissOnBackdrop?` | `boolean` | `true` | Tap backdrop to dismiss. |
+| `panelStyle?` | `StyleProp<ViewStyle>` | — | Style for the panel surface. |
+| `panelClassName?` | `string` | — | NativeWind class for the panel surface. |
+| `containerStyle?` | `StyleProp<ViewStyle>` | — | Style for the root overlay (e.g. rail offset, theme-var scope). |
+| `containerClassName?` | `string` | — | NativeWind class for the root overlay. |
+| `label?` | `string` | — | Accessibility label. |
+| `testID?` | `string` | — | RN testing ID. |
+
+## Placement
+
+`placement` accepts a single value or a **responsive map** resolved by `useWindowDimensions()`:
+
+```ts
+type DialogPlacement = 'center' | 'left' | 'right' | 'bottom';
+
+type ResponsiveDialogPlacement =
+  | DialogPlacement
+  | { base: DialogPlacement; sm?: DialogPlacement; md?: DialogPlacement; lg?: DialogPlacement; xl?: DialogPlacement };
+```
+
+Breakpoints (px): `sm` 640 / `md` 768 / `lg` 1024 / `xl` 1280. The largest breakpoint whose min-width is `<=` the viewport wins; falls back to `base` below all breakpoints.
+
+Per-placement behavior:
+- `center` — DOM-portal modal (web) / detached floating card (native).
+- `left` / `right` — animated side-sheet anchored to the viewport edge.
+- `bottom` — reuses the cross-platform `BottomSheet` on BOTH web and native (drag-to-dismiss + internal scroll work everywhere). Custom `children` on bottom placement are rendered in a NON-scrollable body — children own scrolling.
+
+### `DialogAction`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Button text. |
+| `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` | |
+
+## Blurring the backdrop on Android
+
+A backdrop blurs its content on iOS and web with no setup. **On Android it needs
+the app content wrapped in a blur target**, which `BloomProvider` composes — so
+if you mount it, there is nothing to do:
+
+```tsx
+import { BloomProvider } from '@oxyhq/bloom/provider';
+
+<BloomProvider>{children}</BloomProvider>
+```
+
+An app that does not mount `BloomProvider` keeps the tint-only backdrop. That is
+a supported state, not a missing step — see below.
+
+Two things are worth knowing rather than discovering:
+
+- **It applies to the bottom-sheet path only.** `expo-blur` on Android blurs a
+  target view, and a blur view that is a DESCENDANT of its own target crashes
+  the app — `SIGSEGV`, an unbounded render-tree recursion. Only a surface in a
+  separate native window is safe, which means a real RN `<Modal>`: that is
+  `BottomSheet`, and `Dialog`'s bottom placement through it. `Dialog`'s centre
+  and side placements portal into the same window and keep the tint-only
+  backdrop. Bloom enforces this structurally — the target is simply not
+  reachable from a surface that has not crossed a window boundary — so there is
+  no wiring you can get wrong.
+- **Not mounting it is a supported state**, not a broken one. The backdrop still
+  paints its tint at full intensity; you lose the blur and nothing else, with no
+  warning and no crash.
+
+## Web setup
+
+Inject the CSS animations into your global styles once:
+
+```tsx
+import { BLOOM_DIALOG_CSS } from '@oxyhq/bloom/dialog';
+
+// In your HTML head or global CSS file:
+<style>{BLOOM_DIALOG_CSS}</style>
+```
+
+## Examples
+
+### Three-action confirmation
+
+```tsx
+<Dialog
+  control={control}
+  title="Delete project?"
+  description="This will permanently delete the project and all of its files."
+  actions={[
+    { label: 'Delete', color: 'destructive', onPress: handleDelete },
+    { label: 'Archive', onPress: handleArchive },
+    { label: 'Cancel', color: 'cancel' },
+  ]}
+/>
+```
+
+### Async confirm with loading state
+
+```tsx
+const [busy, setBusy] = useState(false);
+
+<Dialog
+  control={control}
+  title="Submit?"
+  actions={[
+    {
+      label: busy ? 'Submitting…' : 'Submit',
+      disabled: busy,
+      shouldCloseOnPress: false, // keep dialog open while we work
+      onPress: async () => {
+        setBusy(true);
+        try {
+          await submit();
+          control.close();
+        } finally {
+          setBusy(false);
+        }
+      },
+    },
+    { label: 'Cancel', color: 'cancel' },
+  ]}
+/>
+```
+
+### Form inside a dialog
+
+```tsx
+<Dialog control={control} title="Add tag">
+  <TextFieldInput label="Tag name" value={name} onChangeText={setName} />
+  <Button onPress={() => { save(name); control.close(); }}>Save</Button>
+</Dialog>
+```
+
+### Responsive drawer→sheet
+
+Bottom-sheet on small screens, left drawer on `md` and wider:
+
+```tsx
+<Dialog
+  placement={{ base: 'bottom', md: 'left' }}
+  control={control}
+  title="Store settings"
+  containerClassName="md:left-[4.75rem]"
+>
+  <SettingsPanel />
+</Dialog>
+```
+
+## Migration from CenteredDialog / ResponsiveSheet
+
+`CenteredDialog` and `ResponsiveSheet` were removed in 0.16.x.
+
+```tsx
+// Before
+<CenteredDialog visible={v} onClose={c}>…</CenteredDialog>
+// After
+<Dialog placement="center" open={v} onClose={c}>…</Dialog>
+
+// Before
+<ResponsiveSheet side="left" open={o} onClose={c}>…</ResponsiveSheet>
+// After
+<Dialog placement={{ base: 'bottom', md: 'left' }} open={o} onClose={c}>…</Dialog>
+```
+
+Removed exports: `CenteredDialog`, `CenteredDialogProps`, `BLOOM_CENTERED_DIALOG_CSS`, `CENTERED_DIALOG_BACKDROP_TESTID`, `ResponsiveSheet`, `@oxyhq/bloom/responsive-sheet` subpath.

package/docs/divider.mdx

@@ -0,0 +1,56 @@
+---
+title: Divider
+description: The one separator. Nothing else in the library draws a rule by hand.
+order: 27
+---
+
+# Divider
+
+A hairline in the `border` role. Three families used to draw their own 1px
+separator and each had a slightly different colour — that is the whole reason
+this component exists.
+
+```tsx
+import { Divider } from '@oxyhq/bloom/divider';
+
+<Divider />
+<Divider spacing={12} />
+<Divider vertical spacing={12} />
+```
+
+## Which prop decides what
+
+| prop        | decides                                                     |
+| ----------- | ------------------------------------------------------------ |
+| `vertical`  | the axis                                                     |
+| `spacing`   | margin on the axis it separates — the prop you usually want   |
+| `thickness` | the weight; defaults to the platform hairline                 |
+| `color`     | an override; defaults to the `border` role                    |
+
+Reach for `spacing` first. Most "the divider looks wrong" cases are margin, not
+weight — a rule pressed against the text above it reads as heavier than it is.
+
+## A vertical divider needs a parent with a height
+
+It fills the cross axis (`alignSelf: 'stretch'`); it does not invent a height.
+In a row with no height it is invisible rather than broken — which is the usual
+reason a toolbar rule "doesn't render".
+
+```tsx
+<View style={{ flexDirection: 'row', alignItems: 'center', height: 40 }}>
+  <Text>Drafts</Text>
+  <Divider vertical spacing={12} />
+  <Text>Sent</Text>
+</View>
+```
+
+## When not to use one
+
+A divider between every row of a list is usually noise: a settings group already
+separates itself with its card, and rows separated by space read as a group
+without a rule. Use one where a boundary is *meaningful* — between sections,
+not between items.
+
+`SettingsListDivider` is the inset variant for grouped rows; prefer it inside a
+settings group so the rule starts after the icon column instead of cutting the
+card in half.