@oxyhq/bloom 0.89.0 → 1.0.1

package/docs/tabs.mdx

@@ -0,0 +1,75 @@
+---
+title: Tabs
+description: Switching which panel is shown, controlled from the outside.
+order: 26
+---
+
+# Tabs
+
+`Tabs` is the **strip**, and only the strip: the triggers, the sliding
+indicator and the horizontal scroll. It is controlled — `value` is the open tab
+and `onValueChange` reports a press — and the caller renders the panel for
+whatever `value` currently is.
+
+```tsx
+import { Tabs, TabsTrigger } from '@oxyhq/bloom/tabs';
+
+<Tabs value={tab} onValueChange={setTab}>
+  <TabsTrigger value="posts" label="Posts" />
+  <TabsTrigger value="replies" label="Replies" />
+  <TabsTrigger value="media" label="Media" count={12} />
+</Tabs>
+
+{tab === 'posts' ? <Posts /> : null}
+{tab === 'replies' ? <Replies /> : null}
+{tab === 'media' ? <Media /> : null}
+```
+
+Keeping the panels outside is what lets a screen put the strip in a sticky
+header, in a navigator, or beside the content — the strip does not have to be
+an ancestor of what it switches.
+
+## Which prop decides what
+
+| prop            | decides                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `value`         | the open tab                                                   |
+| `onValueChange` | receives the pressed trigger's `value`                         |
+| `hasSelection`  | whether **any** tab is selected — see below                    |
+| `variant`       | `underline` · `filled` · `outlined`                            |
+| `fullWidth`     | spread the triggers across the container instead of hugging    |
+| `count`         | a number beside a trigger's label                              |
+
+## `hasSelection` exists for a state a tab strip usually cannot express
+
+A filter row where nothing is chosen yet. Without it, the first tab looks
+selected before the user has selected anything, and "All" and "no filter" are
+indistinguishable.
+
+```tsx
+<Tabs value={filter} hasSelection={filter != null} onValueChange={setFilter}>
+```
+
+## `count` is a quantity you are choosing between
+
+3 drafts versus 41 sent — a number that helps you decide which tab to open. It
+is not an unread badge; unread belongs on the thing that is unread, through
+[`Badge`](/docs/bloom/main/badge), where `invisible` keeps the layout still as
+the count reaches zero.
+
+## Tabs, SegmentedControl or a Select
+
+- **Tabs** — several views of one subject, with real content underneath.
+- **[SegmentedControl](/docs/bloom/main/segmented-control)** — the choice *is*
+  the value (a setting). Announces as a radio group.
+- **[Select](/docs/bloom/main/select)** — too many options to show at once, or
+  the options are data rather than fixed sections.
+
+The first two look similar enough that the decision is worth making explicitly:
+after the user picks, has something been *set*, or is the same thing now shown
+differently?
+
+## expo-router
+
+`@oxyhq/bloom/tabs/expo-router` binds the strip to the router so `value` comes
+from the current route and a press navigates, instead of a local `useState`.

package/docs/text-field.mdx

@@ -0,0 +1,187 @@
+---
+title: TextField
+description: Composable text input — the field, its input, label, icon, suffix and ghost.
+order: 11
+---
+
+# TextField
+
+A composable text input. `TextField` is the field itself; put a `TextFieldInput` inside it, plus any of `TextFieldIcon`, `TextFieldSuffix` and `TextFieldGhost`. The field tracks focus, hover and invalid state and hands it to those parts, so the whole chrome reacts as one.
+
+## Basic
+
+```tsx
+import { TextField, TextFieldInput } from '@oxyhq/bloom/text-field';
+
+<TextField>
+  <TextFieldInput
+    label="Email"
+    value={value}
+    onChangeText={setValue}
+    keyboardType="email-address"
+  />
+</TextField>
+```
+
+`label` is required and is the input's accessible name. Without an explicit `placeholder` it doubles as the placeholder; pass `placeholder={null}` for none.
+
+## One input needs no wrapper
+
+```tsx
+<TextFieldInput label="Email" value={value} onChangeText={setValue} />
+```
+
+`TextFieldInput` on its own wraps itself in a `TextField`, so the common case is one element. Reach for the explicit `TextField` when you have more than one part to put in it, or when you need `isInvalid` or `radius` on the field.
+
+## With an icon
+
+```tsx
+<TextField>
+  <TextFieldIcon icon={Envelope_Stroke2_Corner0_Rounded} />
+  <TextFieldInput label="Email" value={email} onChangeText={setEmail} />
+</TextField>
+```
+
+The field lays its children out in a row and focuses the input when you click anywhere in it (web).
+
+## Which parts need the field
+
+`TextFieldIcon` and `TextFieldSuffix` read the field's focus, hover and invalid state, and **throw** when rendered outside a `TextField` — they have nothing to colour themselves against, and a part that renders anyway would look finished while never reacting to anything. The message names what is missing:
+
+```
+TextField parts must be rendered inside a <TextField>.
+```
+
+`TextFieldInput` does not throw: a missing field is how it knows to wrap itself. `TextFieldLabel` sits above the field by design, and `TextFieldGhost` reads no state — both render anywhere.
+
+## Validation
+
+```tsx
+const [value, setValue] = useState('');
+const [touched, setTouched] = useState(false);
+const isInvalid = touched && !value.includes('@');
+
+<TextField isInvalid={isInvalid}>
+  <TextFieldInput
+    label="Email"
+    value={value}
+    onChangeText={setValue}
+    onBlur={() => setTouched(true)}
+  />
+</TextField>
+{isInvalid ? <Text style={{ color: theme.colors.negative }}>Enter a valid email</Text> : null}
+```
+
+`isInvalid` paints the field in the negative palette and reaches every part through context. `TextFieldInput` takes its own `isInvalid` too, for the wrapper-less spelling.
+
+## Floating label
+
+```tsx
+<TextField>
+  <TextFieldInput floatingLabel label="Email" value={email} onChangeText={setEmail} />
+</TextField>
+```
+
+The label starts inside the field and animates to a caption at the top on focus or once there is a value. State drives it, not CSS, so web and native behave identically; reduced motion snaps instead of animating.
+
+## Multiline
+
+```tsx
+<TextField style={{ minHeight: 96, alignItems: 'flex-start' }}>
+  <TextFieldInput label="Bio" value={bio} onChangeText={setBio} multiline />
+</TextField>
+```
+
+## Suffix
+
+```tsx
+<TextField>
+  <TextFieldInput label="Workspace" value={url} onChangeText={setUrl} />
+  <TextFieldSuffix label="domain">.oxy.so</TextFieldSuffix>
+</TextField>
+```
+
+## Components
+
+### `TextField`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isInvalid?` | `boolean` | Paints the field in the negative palette and exposes it via context. |
+| `radius?` | `number` | Corner radius of the chrome, default `10`. A large value (999) reads as a pill. |
+| `style?` | `StyleProp<ViewStyle>` | Override the container style. |
+| `children?` | `React.ReactNode` | The input, plus any icon / suffix / ghost. |
+
+### `TextFieldInput`
+
+Accepts React Native's `TextInputProps`, plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Required. The accessible name, and the default placeholder. |
+| `value?` / `onChangeText?` | `string` / `(v: string) => void` | The controlled value. |
+| `placeholder?` | `string \| null` | Overrides the label as placeholder; `null` for none. |
+| `isInvalid?` | `boolean` | For the wrapper-less spelling. |
+| `floatingLabel?` | `boolean` | Material-style animated label. Default `false`. |
+| `inputRef?` | `RefObject<TextInput \| null>` | Merged with the field's own ref. |
+
+### `TextFieldIcon`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `React.ComponentType<SVGIconProps>` | A Bloom icon component. Takes the field's hover / focus / error colour. |
+
+Renders before the input, so put it first.
+
+### `TextFieldLabel`
+
+A visible label rendered ABOVE the field, outside it:
+
+```tsx
+<TextFieldLabel>Workspace</TextFieldLabel>
+<TextField>
+  <TextFieldInput label="Workspace" value={name} onChangeText={setName} />
+</TextField>
+```
+
+### `TextFieldSuffix`
+
+Inline trailing text — domain suffixes, units. `label` is its accessible name; `accessibilityHint` and `style` are optional.
+
+### `TextFieldGhost`
+
+Greyed completion text drawn behind the input, for "type `acme`, see `acme.oxy.so`". Takes the typed prefix as `children` and the suggested remainder as `value`; it is `aria-hidden`.
+
+## Accessibility
+
+- Clicking anywhere in the field focuses the input (web).
+- `label` is the input's `accessibilityLabel`; the floating label itself is hidden from assistive tech so it is not announced twice.
+- On web the browser's own focus ring is stripped, because it follows the input's box rather than the field's and pokes out of a pill's corners. The animated border IS the focus signal.
+- Invalid state paints the chrome. Surface the reason as text under the field — colour alone is not an announcement.
+
+## Recipes
+
+### Password with visibility toggle
+
+```tsx
+const [show, setShow] = useState(false);
+
+<TextField>
+  <TextFieldInput
+    label="Password"
+    value={password}
+    onChangeText={setPassword}
+    secureTextEntry={!show}
+  />
+  <Button
+    variant="icon"
+    icon={show ? <EyeSlash_Stroke2_Corner0_Rounded /> : <Eye_Stroke2_Corner0_Rounded />}
+    accessibilityLabel={show ? 'Hide password' : 'Show password'}
+    onPress={() => setShow(!show)}
+  />
+</TextField>
+```
+
+### Search
+
+Reach for `Search` rather than rebuilding it: it is a `TextField` at the pill radius with the magnifier, the clear button and the keyboard settings a query field wants.

package/docs/theme.mdx

@@ -0,0 +1,67 @@
+---
+title: Theme
+description: Color presets, light/dark modes, and design tokens used by every Bloom component.
+order: 2
+---
+
+# Theme
+
+Wrap your app with `BloomThemeProvider`. 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>
+```
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| `light` | Force light theme. |
+| `dark` | Force dark theme. |
+| `system` | Follow OS preference (`useColorScheme`). |
+| `adaptive` | iOS/Android native dynamic colors when available, falls back to `system`. |
+
+## Color presets
+
+10 named palettes:
+
+`teal` · `blue` · `green` · `amber` · `red` · `purple` · `pink` · `sky` · `orange` · `mint`
+
+Each preset has a tuned light + dark variant and a contrast-checked primary color.
+
+## Reading theme values
+
+```tsx
+import { useTheme } from '@oxyhq/bloom/theme';
+
+function MyComponent() {
+  const theme = useTheme();
+  return (
+    <View style={{ backgroundColor: theme.colors.surface }}>
+      <Text style={{ color: theme.colors.text }}>{theme.isDark ? 'Dark' : 'Light'}</Text>
+    </View>
+  );
+}
+```
+
+### Tokens
+
+Every preset exposes:
+
+- `colors.primary` — brand color.
+- `colors.background` — page background.
+- `colors.surface` — elevated surface (cards, sheets).
+- `colors.text` — body text.
+- `colors.muted` — secondary text.
+- `colors.border` — divider lines.
+- `colors.success` / `colors.warning` / `colors.danger` — semantic colors.
+- `isDark` — boolean.
+- `mode` — resolved mode (`'light' | 'dark'`).
+
+<Callout variant="info" title="Web CSS variables">
+On web, Bloom also writes the active palette to CSS variables on `:root`, so non-React surfaces (e.g. raw HTML pages) can theme themselves with `var(--bloom-primary)`.
+</Callout>

package/docs/toast.mdx

@@ -0,0 +1,285 @@
+---
+title: Toast
+description: Passive notifications, powered by Bloom's own universal toast engine.
+order: 5
+---
+
+# Toast
+
+Passive notifications. Bloom ships its own engine — **one** implementation that runs
+on native and on web (through react-native-web), so there is nothing extra to
+install and the API is identical everywhere.
+
+The engine is derived from [sonner-native](https://github.com/gunnartorfis/sonner-native)
+v0.26.4 (MIT), itself a React Native port of [sonner](https://github.com/emilkowalski/sonner).
+
+## Setup
+
+Mount the outlet once near the app root, inside `BloomThemeProvider`:
+
+```tsx
+import { ToastOutlet } from '@oxyhq/bloom/toast';
+
+<BloomThemeProvider>
+  <App />
+  <ToastOutlet />
+</BloomThemeProvider>
+```
+
+Apps that mount `OxyProvider` from `@oxyhq/services` already get an outlet and
+should **not** mount a second one — two outlets render every toast twice.
+
+Native apps must wrap the root in `GestureHandlerRootView` (as they already do for
+`Dialog` / `BottomSheet`) for swipe-to-dismiss. On web the toast host provides its
+own, so no setup is needed.
+
+## API
+
+```tsx
+import { toast } from '@oxyhq/bloom';
+
+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');
+toast.loading('Uploading…');
+
+const id = toast('Uploading…');
+toast.dismiss(id);   // one toast
+toast.dismiss();     // all of them
+```
+
+Every method returns the toast's id (`string | number`), so `const id = toast(…)`
+followed by `toast.dismiss(id)` works. Passing your own `id` updates that toast in
+place instead of adding another:
+
+```tsx
+toast.loading('Uploading…', { id: 'upload' });
+toast.success('Uploaded', { id: 'upload' }); // replaces the row, keeps its position
+```
+
+`toast(content, options?)` takes a string or a React element; anything else throws.
+`options.type` is the public variant knob and the typed helpers above are shorthands
+for it. `type: 'default'` (the default) renders a neutral toast — no icon, no tint.
+
+### The variant colours the icon, not the surface
+
+Every toast renders the SAME neutral surface — `backgroundSecondary` with the
+`border`, `text` and `textSecondary` roles — whatever its `type`, and with
+`richColors` on or off. The variant shows up only in the leading icon, which uses
+the theme's first-class status tokens: `success`, `error`, `warning`, `info`. A
+`loading` or variant-less toast gets `textSecondary`.
+
+That is deliberate, and matches sonner. `toast.success('Saved')` should read as a
+normal toast with a green check, not as a full brand-coloured card.
+
+`richColors` lifts the status colour from the icon alone to the **border and
+title** as well. That is all it does: the surface stays `backgroundSecondary`, and
+the description, close button and action colours stay neutral, so a rich-coloured
+row still reads as a toast rather than a status banner. All four status variants
+behave identically under it — `warning` and `info` are not special-cased and get
+exactly the same border+title treatment as `success` and `error`, because the
+lift is the only tinting mechanism there is. `loading` and a variant-less toast
+have no status colour, so `richColors` has nothing to make more prominent and
+they stay fully neutral either way.
+
+<Callout variant="info" title="Tinted status surfaces need new tokens">
+There is no `warningSubtle` / `infoSubtle` (or `successSubtle` / `errorSubtle`)
+pair to tint a surface with, which is why every variant gets the same border+title
+lift instead. Bloom has `*Subtle` / `*SubtleForeground` pairs for the **brand**
+roles (`primarySubtle`, `negativeSubtle`) only — those are not status colours, and
+reaching for them here is what once made a success toast render brand-purple.
+Genuinely tinted status surfaces would need that missing status token family: a
+theme addition affecting every app, not something to fake from a brand pair or a
+derived alpha.
+</Callout>
+
+### Recolouring toasts with `BloomColorScope`
+
+`BloomColorScope` is a React context override, and React context flows through a
+portal — so a scope **does** reach the toast even though the row renders into
+`#bloom-portal-root` at the end of `<body>`. The catch is which side of the scope
+the OUTLET is on, not which side the `toast()` call is on:
+
+```tsx
+// ✅ tints toasts — the scope is an ancestor of the outlet
+<BloomColorScope colorPreset="green">
+  <App />
+  <ToastOutlet />
+</BloomColorScope>
+
+// ❌ does NOT tint toasts — the outlet is outside the scope
+<BloomColorScope colorPreset="green">
+  <SomeScreen />   {/* toast() called from in here */}
+</BloomColorScope>
+<ToastOutlet />
+```
+
+**Apps that mount `OxyProvider` are in the second shape.** It renders
+`<ToastOutlet />` at app root, so a `BloomColorScope` wrapped around a screen deep
+in the tree will not tint toasts fired from that screen — they follow the root
+preset. To recolour toasts, move the scope up so it wraps the provider.
+
+What a scope changes is the **preset-derived** roles: the surface, text and
+border. Status colours are fixed theme tokens, so a `success` icon (and, under
+`richColors`, the border and title) is the same green whichever preset is in
+scope — only the neutral card around it moves.
+
+### Width
+
+A toast is a card, not a banner. The row is `width: 100%` up to a **388px cap**,
+centred — which puts the visible card on 356px, sonner's reference width, plus its
+two 16px gutters. Below a 388px viewport the cap never binds and the card stays
+screen-width-minus-32, so phone portrait is unaffected; above it (desktop, tablet,
+phone landscape) the card caps and centres instead of spanning the viewport.
+
+Widen it per outlet through the existing style slot:
+
+```tsx
+<ToastOutlet toastOptions={{ toastContainerStyle: { maxWidth: 600 } }} />
+```
+
+That moves the card only. The swipe-to-dismiss threshold and the stacking depth
+cue are fractions of the **default** cap, so a widened card keeps the default
+gesture distances.
+
+### Stacking
+
+Toasts **stack** by default, the way sonner's do: the newest row sits in front at
+full size, older ones sit behind it scaled down and offset by `gap` (8px), and
+pressing the stack expands it into a readable column. Pressing outside collapses
+it again, and timers pause for as long as it is expanded.
+
+Measured on a 1280px viewport with three rows, front to back: `scaleX` 1 / 0.959 /
+0.918 at 0 / -8 / -16px, expanding to 1 / 1 / 1 at 0 / -54 / -108px.
+
+This is a deliberate deviation from sonner-**native**, which defaults it off —
+that default is right for a phone and wrong for the desktop consumers Bloom also
+serves. Two consequences to know about:
+
+- Only the front row's action button is reachable while the stack is collapsed.
+  Expand it (a press) to reach the others.
+- While more than one toast is live, a press on the row toggles the stack **and**
+  still calls the toast's own `onPress`.
+- No press on a stacked row is inert: it dismisses if it lands on a ✕ that is
+  actually rendered (`closeButton` and `dismissible` both on), and otherwise
+  expands or collapses like the rest of the row.
+
+Opt out per outlet for a surface that must show several toasts at once with no
+interaction:
+
+```tsx
+<ToastOutlet enableStacking={false} />
+```
+
+### Hover (web)
+
+On web a **mouse** over the stack expands it and moving away collapses it again,
+the way sonner does — no prop, no setup. Press keeps working everywhere and is the
+only trigger on native and on touch: the handlers ignore any pointer that is not a
+mouse, so a tap cannot expand-then-collapse the stack from its own
+`pointerenter`/`pointerleave` pair. While a mouse is over the stack, a press does
+not toggle the expansion (hover owns it there) but still runs the toast's `onPress`.
+
+**The pointer pauses the auto-close timers for as long as it is over a toast**, so
+hovering to read one cannot let it expire under the cursor. Measured: three rows
+with the default 3000ms duration survive 5s of hover, then resume when the pointer
+leaves. This holds with `enableStacking={false}` too — there the pointer pauses
+without expanding anything, since a flat column has nothing to open.
+
+Dismissing a row **out of** a hovered stack leaves the rest expanded and still
+paused, rather than collapsing under the cursor and resuming. Without a pointer
+holding it — on native, or once the mouse leaves — a stack still collapses itself
+once one row is left, which is invisible (a lone row sits at the same offset and
+scale either way) and is what stops that last toast's paused timer hanging forever.
+
+## Options
+
+Per-toast options (`ToastOptions`):
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id?` | `string \| number` | Stable id. Reusing one updates that toast in place. |
+| `type?` | `'default' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'loading'` | Visual variant. `'default'` is neutral. |
+| `duration?` | `number` | Milliseconds before auto-dismiss. Defaults to `3000`. `Infinity` never auto-closes. |
+| `description?` | `string` | Secondary text under the title. |
+| `action?` | `{ label, onClick }` \| `ReactNode` | Primary button, or your own node. |
+| `cancel?` | `{ label, onClick }` \| `ReactNode` | Secondary button; the object form also dismisses. |
+| `closeButton?` | `boolean` | Show the ✕ affordance. |
+| `dismissible?` | `boolean` | Allow swipe / close. Defaults to `true`. |
+| `position?` | `'top-center' \| 'bottom-center' \| 'center'` | Override the outlet's position for this toast. |
+| `icon?` | `ReactNode` | Replaces the variant icon. |
+| `richColors?` | `boolean` | Show the status colour more prominently: it moves from the icon alone to the border and title as well. The surface stays neutral, as do the description, close button and action colours. No effect on `loading` or a variant-less toast, which have no status colour. |
+| `important?` | `boolean` | Announce assertively to screen readers. |
+| `onDismiss?` / `onAutoClose?` | `(id) => void` | Called when the toast goes away. |
+| `onPress?` | `() => void` | Press anywhere on the row. |
+| `style?` / `styles?` / `unstyled?` | — | Escape hatches for the row's own styling. |
+| `animation?` | `{ enter?, exit? }` | A predefined Reanimated builder, a `Keyframe`, or `'default'`. On web, prefer a **predefined** builder for `enter`: a custom `Keyframe` handed to Reanimated's `entering` gets frozen in place by its web layout-animation cleanup, which breaks the stack. Bloom's own default enter avoids that path entirely. |
+
+Outlet options (`ToasterProps`) cover `position`, `offset`, `gap`, `visibleToasts`,
+`duration`, `swipeToDismissDirection`, `closeButton`, `richColors`,
+`enableStacking`, `autoWiggleOnUpdate`, `pauseWhenPageIsHidden`, `icons`,
+`toastOptions` and `positionerStyle`. Their defaults all come from the exported
+`toastDefaults`, so `<ToastOutlet position="top-center" />` changes only that one.
+
+<Callout variant="info" title="Documented no-ops">
+`theme` and `invert` are accepted but do nothing: light/dark and per-subtree
+recolouring belong to `BloomThemeProvider` / `BloomColorScope`.
+</Callout>
+
+## Patterns
+
+### Promise toast
+
+The pending row shows a spinner; the promise's result is formatted into the final
+title. `success` is a formatter, `error` is a formatter **or** a plain string:
+
+```tsx
+toast.promise(saveProfile(), {
+  loading: 'Saving…',
+  success: (profile) => `Saved ${profile.name}`,
+  error: (err) => `Failed: ${err instanceof Error ? err.message : 'unknown'}`,
+});
+```
+
+A promise toast cannot be swiped away while it is pending, and its auto-close timer
+only starts once it settles.
+
+### Action toast
+
+```tsx
+toast('Item moved to trash', {
+  action: {
+    label: 'Undo',
+    onClick: () => restore(item.id),
+  },
+});
+```
+
+### Fully custom row
+
+`toast.custom` hands the whole row to your element — Bloom renders no surface,
+icon or buttons around it, but still animates, stacks and swipes it:
+
+```tsx
+toast.custom(<MyRow />, { duration: 8000 });
+```
+
+### Above a native iOS modal
+
+Bloom does not depend on `react-native-screens`. Inject the overlay host yourself
+when a toast has to appear above a native modal:
+
+```tsx
+import { FullWindowOverlay } from 'react-native-screens';
+
+<ToastOutlet ToasterOverlayWrapper={FullWindowOverlay} />
+```
+
+<Callout variant="info" title="Toast vs alert()">
+Reach for `toast()` for passive feedback (the user doesn't have to react). Use [`alert()`](/docs/bloom/main/alert) when you need a one-shot confirmation that blocks the rest of the UI.
+</Callout>
+
+Upgrading from 0.50.x? `show`, `api`, `DURATION`, `type Toast` and the composition
+exports were removed, and the default position moved to `bottom-center`.

package/docs/tooltip.mdx

@@ -0,0 +1,67 @@
+---
+title: Tooltip
+description: A hint about an already-labelled control — controlled, because what opens it differs by platform.
+order: 39
+---
+
+# Tooltip
+
+A short hint attached to a control.
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipTextBubble } from '@oxyhq/bloom/tooltip';
+
+const [visible, setVisible] = useState(false);
+
+<Tooltip visible={visible} onVisibleChange={setVisible} position="top">
+  <TooltipTrigger>
+    <Pressable
+      onHoverIn={() => setVisible(true)}
+      onHoverOut={() => setVisible(false)}
+      onPress={copy}
+      accessibilityLabel="Copy link"
+    >
+      <LinkIcon />
+    </Pressable>
+  </TooltipTrigger>
+  <TooltipTextBubble>Copies the link to your clipboard</TooltipTextBubble>
+</Tooltip>
+```
+
+## Why it is controlled
+
+What should open a tooltip differs by platform and by trigger — hover for a
+desktop pointer, long-press on touch, focus for a keyboard — and the right
+answer depends on what the trigger already does with a press. `Tooltip` takes
+`visible` and leaves that decision at the call site rather than guessing.
+
+`TooltipTextBubble` renders its own content surface, so it is a **sibling** of
+the trigger inside `Tooltip`, not something you wrap in a `TooltipContent`.
+
+## A tooltip is never the only place the information appears
+
+It cannot be reached by touch without an interaction that also does something
+else, and it dismisses on the next tap. So:
+
+- The control still needs its own `accessibilityLabel`. A tooltip is a hint
+  about a labelled control, not a substitute for the label.
+- Nothing required to complete a task goes in one. If the user must know it,
+  put it on the page.
+
+## `position` is a preference
+
+A bubble near a screen edge is nudged back into view, so `position="top"` on an
+element at the top of the viewport still renders somewhere readable rather than
+off screen.
+
+## Two platform notes
+
+The **web** tooltip is not portaled and takes no rank in the overlay stack; the
+**native** one is portaled and does. So on native it participates in overlay
+ordering and on web it does not — check for a `Portal` before reasoning about
+what paints above what.
+
+**Known gap on native:** `TooltipTrigger` measures in page coordinates while
+the content renders into the root portal group, so a tooltip inside a
+`BottomSheet` portals *outside* that window and lands in the wrong place.
+Fixing it needs a real device — jest cannot see a native window boundary.