@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/portal.mdx

@@ -0,0 +1,63 @@
+---
+title: Portal
+description: Rendering somewhere else in the tree — and why the provider and outlet are native-only.
+order: 38
+---
+
+# Portal
+
+`Portal` renders its children at an outlet instead of where they were written.
+It is what lets a menu escape a parent's `overflow: hidden`, a clipping
+scroll view, or a stacking context that would otherwise trap it.
+
+```tsx
+import { Portal } from '@oxyhq/bloom/portal';
+
+<View style={{ overflow: 'hidden' }}>
+  <Trigger />
+  {open ? (
+    <Portal>
+      <OverlayRoot>
+        <Panel />
+      </OverlayRoot>
+    </Portal>
+  ) : null}
+</View>
+```
+
+## `PortalProvider` and `PortalOutlet` are NATIVE-ONLY
+
+On web the fork portals directly to `document.body`, so both are explicit no-op
+exports there. You still render them — the API is the same on both platforms —
+they simply do nothing in a browser.
+
+This matters because "this app doesn't mount a Portal Outlet" is **never** a
+valid reason to fork a web-facing component. That reasoning once produced a
+742-line fork that diverged for two months and shipped strictly worse than the
+thing it replaced.
+
+## Where the outlet goes
+
+Near the app root, after the content it must paint over. Mounting it too early
+puts every portaled surface behind the app; mounting two duplicates every
+surface.
+
+Outlets deliberately stay **out** of `BloomProvider`: their tree position is an
+app decision, and a second mount is silent — you get two of everything, which
+reads as a render loop rather than as a duplicated outlet.
+
+## Portal is not enough on its own
+
+A portaled surface still needs:
+
+- an [`OverlayRoot`](/docs/bloom/main/overlay) for its stack position and its
+  interactive root — the web portal root is `pointer-events: none` and that
+  **inherits**, so a surface without one is entirely click-through;
+- a `Backdrop` if it should dismiss on an outside press.
+
+## Several portals coexist
+
+Each portal is tracked by its own id, so opening a second does not replace the
+first, and unmounting one removes only that one. Order at the outlet follows
+mount order — which is also why the overlay stack, not the outlet, decides what
+paints on top.

package/docs/pressable-scale.mdx

@@ -0,0 +1,51 @@
+---
+title: PressableScale
+description: A press that shrinks slightly — the feedback for something that is not already a button.
+order: 63
+---
+
+# PressableScale
+
+A `Pressable` that scales down while held.
+
+```tsx
+import { PressableScale } from '@oxyhq/bloom/pressable-scale';
+
+<PressableScale onPress={open} targetScale={0.97} accessibilityLabel="Open photo">
+  <Image source={photo} style={{ width: 120, height: 120, borderRadius: 12 }} />
+</PressableScale>
+```
+
+## Which prop decides what
+
+| prop          | decides                                                     |
+| ------------- | ------------------------------------------------------------ |
+| `targetScale` | how far it shrinks while held — smaller is more emphatic      |
+
+Everything else is `Pressable`'s.
+
+## What it is for
+
+Feedback on things that are not shaped like buttons: a photo, a card, a tile, a
+row that opens something. Those have no border or fill to darken, so without
+motion a press produces no acknowledgement at all and the user presses again.
+
+`Button`, `Fab` and `FrostedIconButton` already have their own press feedback —
+wrapping one adds a second animation on top of the first.
+
+## Keep the scale small
+
+Around 0.96–0.98 for anything sizeable. A large element shrinking to 0.9 moves
+its edges a long way, which reads as the layout jumping rather than as a press.
+Small targets can take more, because the absolute movement is smaller.
+
+## It is a Pressable, so it still needs a name
+
+An image inside a `PressableScale` announces as a button with no label.
+`accessibilityLabel` is not optional here.
+
+## Native vs web
+
+The press animation runs on the native driver, and jest can see the structure
+but never whether the animation ran. A device build is the only place it is
+actually verified.

package/docs/profile-card.mdx

@@ -0,0 +1,66 @@
+---
+title: ProfileCard
+description: A profile widget with one headline number and one metric — four flavours, one shape.
+order: 62
+---
+
+# ProfileCard
+
+A compact profile widget: an avatar with an optional ring and badge, a headline
+value, and one metric underneath.
+
+```tsx
+import { ProfileCard } from '@oxyhq/bloom/profile-card';
+
+<ProfileCard
+  variant="wallet"
+  avatar={{ source: user.avatar, name: user.displayName }}
+  value="$167,395"
+  subtitle="*5bF5"
+  metric={{ kind: 'dots', label: 'Token diversity', filled: 34, total: 50 }}
+  footer={{ label: 'Top tokens', items: topTokens }}
+/>
+```
+
+## Which prop decides what
+
+| prop       | decides                                                        |
+| ---------- | --------------------------------------------------------------- |
+| `variant`  | `wallet` · `social` · `shopping` · `stat` — the flavour           |
+| `layout`   | `widget` (a fixed-width card) or `wide` (fills its container)     |
+| `avatar`   | the image, its ring, a badge, and the fallback name               |
+| `value`    | the headline number                                              |
+| `metric`   | the thing underneath — a discriminated union, see below           |
+| `footer`   | a labelled row of avatars                                        |
+
+## `metric` is a discriminated union
+
+`kind` picks both the widget and the fields it needs, so a `dots` metric cannot
+be given a `max` and a `progress` metric cannot be given a `total`:
+
+```tsx
+metric={{ kind: 'dots', filled: 34, total: 50 }}
+metric={{ kind: 'progress', label: 'Level 4', value: 620, max: 1000 }}
+```
+
+That is deliberate: the alternative — a flat prop bag with everything optional
+— makes an incomplete metric a runtime surprise rather than a type error.
+
+## `avatar.source`, not a URL
+
+The avatar goes through [`ImageResolver`](/docs/bloom/main/image-resolver), so
+pass the bare Oxy file id. `name` is the fallback used to draw an initial when
+there is no image — give it even when you have one, since that is exactly the
+state you get when the image fails.
+
+## One headline number
+
+`value` is the number the card exists to show. If a card needs two, it is two
+cards — a widget with competing headlines has no headline, and the eye has
+nowhere to land.
+
+## The background is deliberately not the `card` role
+
+This widget sits **on** a card surface in its reference design, so it takes the
+page background and reads as a cut-out rather than as a stacked card. If you
+place it on the page background instead, give it a surface of its own.

package/docs/progressive-blur.mdx

@@ -0,0 +1,54 @@
+---
+title: ProgressiveBlur
+description: A blur that fades out, so content dissolves into the chrome instead of meeting a line.
+order: 72
+---
+
+# ProgressiveBlur
+
+A blur that is strongest at one edge and fades to nothing. Put it behind a
+floating tab bar or a transparent header so scrolling content dissolves rather
+than hitting a hard blur boundary halfway up a word.
+
+```tsx
+import { ProgressiveBlur } from '@oxyhq/bloom/progressive-blur';
+
+<ProgressiveBlur
+  direction="bottom"
+  intensity={5}
+  style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: 96 }}
+/>
+```
+
+## Which prop decides what
+
+| prop        | decides                                              |
+| ----------- | ----------------------------------------------------- |
+| `direction` | which edge the blur is anchored to — `top` or `bottom` |
+| `intensity` | the strength at that edge, on `expo-blur`'s 0–100 scale |
+
+It takes no size of its own: position and size it with `style`.
+
+## Two implementations, one call site
+
+iOS has no public variable-blur API, so the **native** fork stacks ten thin
+blur layers with a small per-layer intensity — each layer's edge adds an
+imperceptible step, so the falloff reads as continuous. The **web** fork
+replaces the whole stack with one masked `backdrop-filter`, because ten stacked
+backdrop passes would cost far more than the single pass a browser can do
+natively.
+
+Nothing at the call site changes, and `intensity` means the same thing in both
+— per layer on native, mapped onto the equivalent CSS radius on web.
+
+## Be conservative with `intensity`
+
+The blur exists so text stays legible while passing under the chrome. A high
+value turns the strip into an opaque band, which reads as a rendering bug
+rather than as a design.
+
+## It needs something behind it
+
+A backdrop blur with nothing scrolling under it is a slightly grey rectangle
+that costs a compositing pass. If the area behind is a flat background, use a
+gradient — or nothing.

package/docs/prompt-input.mdx

@@ -0,0 +1,183 @@
+---
+title: PromptInput
+description: AI chat input — textarea, actions, attachments, submit, stop, fullscreen.
+order: 17
+---
+
+# PromptInput
+
+The AI chat input component. Auto-resizing textarea, send / stop button, optional attachments, optional fullscreen toggle, configurable left-side actions, image paste on web, and a controlled or simple mode.
+
+## Simple mode
+
+The fastest path to a working prompt input:
+
+```tsx
+import { PromptInput } from '@oxyhq/bloom';
+
+const [value, setValue] = useState('');
+const [busy, setBusy] = useState(false);
+
+<PromptInput
+  value={value}
+  onValueChange={setValue}
+  placeholder="Ask anything…"
+  isLoading={busy}
+  onSubmit={async () => {
+    setBusy(true);
+    try { await ask(value); setValue(''); } finally { setBusy(false); }
+  }}
+  onStop={() => abortController.abort()}
+/>
+```
+
+That's it — textarea, submit button, stop button, all wired.
+
+## Compound mode
+
+For full control over layout, opt into the compound API:
+
+```tsx
+import * as Prompt from '@oxyhq/bloom/prompt-input';
+
+<Prompt.Root value={value} onValueChange={setValue} isLoading={busy} onSubmit={ask}>
+  <Prompt.Textarea placeholder="Ask anything…" />
+  <Prompt.Actions>
+    <Prompt.AttachmentButton onPress={pickFile} />
+    <View style={{ flex: 1 }} />
+    <Prompt.SubmitButton />
+  </Prompt.Actions>
+  <Prompt.Attachments />
+</Prompt.Root>
+```
+
+Compound mode lets you reorder actions, render extra buttons, swap icons, or render attachments somewhere else entirely.
+
+## Attachments
+
+```tsx
+const [attachments, setAttachments] = useState<Attachment[]>([]);
+
+<PromptInput
+  value={value}
+  onValueChange={setValue}
+  attachments={attachments}
+  onAddAttachment={(a) => setAttachments((prev) => [...prev, a])}
+  onRemoveAttachment={(id) => setAttachments((prev) => prev.filter((p) => p.id !== id))}
+  onUpdateAttachment={(id, u) => setAttachments((prev) => prev.map((p) => p.id === id ? { ...p, ...u } : p))}
+  onImagePaste={(files) => {
+    /* turn each File into an Attachment and call onAddAttachment */
+  }}
+/>
+```
+
+`onImagePaste` is web-only — the textarea swallows `paste` events and forwards image clipboard content.
+
+## Loading and stop
+
+`isLoading` toggles the right-side button between "submit" and "stop". Wire `onStop` to abort the in-flight request:
+
+```tsx
+const controllerRef = useRef<AbortController | null>(null);
+
+<PromptInput
+  isLoading={busy}
+  onSubmit={async () => {
+    controllerRef.current = new AbortController();
+    setBusy(true);
+    try {
+      await ask(value, { signal: controllerRef.current.signal });
+    } catch (err) {
+      if ((err as Error).name === 'AbortError') return; // user pressed stop
+      throw err;
+    } finally {
+      setBusy(false);
+    }
+  }}
+  onStop={() => controllerRef.current?.abort()}
+/>
+```
+
+## Empty action
+
+The right-side button defaults to the submit/stop pair. When the textarea is empty and not loading, you can render an alternate action (e.g. a mic for voice input):
+
+```tsx
+<PromptInput
+  value={value}
+  onValueChange={setValue}
+  emptyAction={<MicButton onPress={() => startListening()} />}
+/>
+```
+
+`emptyAction` only renders when `value` is empty and `isLoading` is false.
+
+## Fullscreen
+
+Tap the expand icon to swap the input into a fullscreen modal. Override the icons:
+
+```tsx
+<PromptInput
+  value={value}
+  onValueChange={setValue}
+  expandIcon={<MaximizeIcon />}
+  collapseIcon={<MinimizeIcon />}
+/>
+```
+
+## Props (simple mode)
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value?` | `string` | Controlled text value. |
+| `onValueChange?` | `(value: string) => void` | |
+| `isLoading?` | `boolean` | Show stop button instead of submit. |
+| `onSubmit?` | `() => void` | Submit handler. |
+| `onStop?` | `() => void` | Abort handler. |
+| `placeholder?` | `string` | Placeholder text. |
+| `maxHeight?` | `number` | Max textarea height before it scrolls. Default `240`. |
+| `disabled?` | `boolean` | |
+| `actionsLeft?` | `React.ReactNode` | Render extra buttons on the left of the actions bar. |
+| `emptyAction?` | `React.ReactNode` | Replaces the right-side button when empty + idle. |
+| `attachments?` | `Attachment[]` | Controlled attachments. |
+| `onAddAttachment?` | `(a: Attachment) => void` | |
+| `onRemoveAttachment?` | `(id: string) => void` | |
+| `onUpdateAttachment?` | `(id, updates) => void` | |
+| `onImagePaste?` | `(files: File[]) => void` | Web-only image paste. |
+| `disableKeyboardAvoidance?` | `boolean` | Skip the inner `KeyboardAvoidingView`. |
+| `expandIcon?` | `React.ReactNode` | Custom expand icon. |
+| `collapseIcon?` | `React.ReactNode` | Custom collapse icon. |
+| `testID?` | `string` | |
+
+## Recipes
+
+### Send on Enter, newline on Shift+Enter
+
+The textarea handles this on web automatically. On native, Enter inserts a newline (no software keyboard convention for "send" exists across iOS/Android). Drive submission via the submit button or an explicit toolbar action.
+
+### Disable submit while empty
+
+The submit button is disabled automatically when `value.trim()` is empty. No extra wiring required.
+
+### Custom left action (model picker)
+
+```tsx
+<PromptInput
+  value={value}
+  onValueChange={setValue}
+  actionsLeft={
+    <Select.Root value={model} onValueChange={setModel}>
+      <Select.Trigger label="Model">{({ props }) => <Button {...props}>{model}</Button>}</Select.Trigger>
+      <Select.Content
+        items={['gpt-4', 'gpt-3.5']}
+        renderItem={(m, _i, selected) => (
+          <Select.Item value={m} label={m}>
+            <Select.ItemText>{m}</Select.ItemText>
+            {selected === m ? <Select.ItemIndicator /> : null}
+          </Select.Item>
+        )}
+      />
+    </Select.Root>
+  }
+/>
+```

package/docs/provider.mdx

@@ -0,0 +1,64 @@
+---
+title: BloomProvider
+description: The one root a consuming app mounts — and why the outlets are deliberately not in it.
+order: 56
+---
+
+# BloomProvider
+
+The single root that composes Bloom's app-wide **state** providers, so none of
+them lands at the wrong depth.
+
+```tsx
+import { BloomProvider } from '@oxyhq/bloom/provider';
+
+export default function RootLayout() {
+  return (
+    <BloomProvider>
+      <Stack />
+    </BloomProvider>
+  );
+}
+```
+
+## Why one root rather than several
+
+Depth is not a detail for these. Mounted too low:
+
+- `useScrollRestoration()` **throws** for anything rendered beside it;
+- `useMinimizeState()` silently hands out a private fallback, so two parts of
+  the app disagree about the same state and neither errors.
+
+One root removes the chance to get that wrong.
+
+## Expo/expo-router apps only
+
+`BloomProvider` binds the scroll store to `expoRouterScrollAdapter`, so it is
+expo-router-only **by construction** — which is also why the family is not on
+the root barrel: importing it would drag `expo-router` into every consumer's
+graph, and Metro does not tree-shake, so an unmet peer is a build failure
+rather than a degradation.
+
+A Vite/SPA consumer mounts the pieces instead: `BloomThemeProvider` plus
+`<ScrollRestorationProvider adapter={…}>` with its own router adapter.
+
+## The OUTLETS are deliberately not in it
+
+`ToastOutlet`, `PortalProvider`/`PortalOutlet`, `SurfaceHost` and the dialog
+hosts stay out. Where an outlet sits in the tree is an app decision — it has to
+paint over the app's own chrome — and **a second mount duplicates every
+surface**. Adding one here would silently double the toasts of any app that
+already mounts its own.
+
+That failure is quiet: two identical toasts read as a double-fire in your own
+code, not as two outlets.
+
+## Where the theme provider goes
+
+Above **every** render branch, including the splash/loading one.
+
+`useTheme()` throws outside `BloomThemeProvider`, and the classic way to hit
+that is an `appIsReady` early-return in `app/_layout.tsx` that renders a splash
+screen *before* the providers mount. It fails at runtime only — `tsc` and the
+build stay green — and only on a cold start. Verify in a real browser after any
+theming migration.

package/docs/radio-indicator.mdx

@@ -0,0 +1,60 @@
+---
+title: RadioIndicator
+description: The radio dot on its own — presentational, for rows that are already controls.
+order: 69
+---
+
+# RadioIndicator
+
+The ring-and-dot glyph, with no label, no press target and no group.
+
+```tsx
+import { RadioIndicator } from '@oxyhq/bloom/radio-indicator';
+
+<Item
+  title={plan.name}
+  subtitle={plan.price}
+  leading={<RadioIndicator selected={plan.id === chosen} />}
+  role="radio"
+  onPress={() => setChosen(plan.id)}
+/>
+```
+
+## Which prop decides what
+
+| prop            | decides                                        |
+| --------------- | ----------------------------------------------- |
+| `selected`      | filled or hollow                                |
+| `size`          | the diameter; the dot scales with it            |
+| `selectedColor` | the fill when selected                          |
+| `borderColor`   | the ring when not                               |
+
+## Use it only where the row is already the control
+
+`RadioIndicator` is **presentational**. It has no press handler and contributes
+no role or state, so a group built out of these announces as decoration unless
+the surrounding row supplies both — `role="radio"` and the selected state.
+
+If you are building a plain list of options, use
+[`Radio` / `RadioGroup`](/docs/bloom/main/radio) instead: they render the label,
+make the whole row the target, and name the group. Reaching for the indicator
+where you meant the control is the usual way a "radio group" ends up
+unreachable by keyboard and silent to a screen reader.
+
+The legitimate cases are rows that are already something else: a card selector,
+a table row, a settings row with its own affordances.
+
+## The dot colour is derived, not white
+
+When `selectedColor` is the theme primary, the dot uses the preset's readable
+foreground — dark on a yellow primary, light on a blue one. A hardcoded white
+dot disappears on a light accent, which is the same class of failure as
+appending alpha to a token: correct markup, invisible control.
+
+A caller-supplied `selectedColor` falls back to white, because Bloom cannot
+know the right contrast for an arbitrary colour. If you pass one, check it.
+
+## Selected drops the border
+
+A filled circle with a ring around it reads as two states at once. When
+`selected` is true the border goes to zero and the fill carries the state.

package/docs/radio.mdx

@@ -0,0 +1,65 @@
+---
+title: Radio
+description: One choice from a small set — the control, not just the dot.
+order: 30
+---
+
+# Radio
+
+A radio is a **control**: the label is part of the target, the group announces
+itself as a group, and exactly one option is selected. `RadioGroup` is the form
+you almost always want; `Radio` is the single row, for when the options are not
+a flat list.
+
+```tsx
+import { RadioGroup } from '@oxyhq/bloom/radio';
+
+<RadioGroup
+  label="Delivery speed"
+  value={speed}
+  onValueChange={setSpeed}
+  options={[
+    { value: 'standard', label: 'Standard', description: 'Two to four days' },
+    { value: 'express', label: 'Express', description: 'Next working day' },
+    { value: 'pickup', label: 'Collect in store', disabled: !storeNearby },
+  ]}
+/>
+```
+
+## Which prop decides what
+
+| prop                      | decides                                            |
+| ------------------------- | --------------------------------------------------- |
+| `label` (group)           | the accessible name of the whole group — required    |
+| `value` / `onValueChange` | the selection; the group is fully controlled         |
+| `options`                 | the choices, each with its own `label`/`description` |
+| `size`                    | `small` · `medium` · `large`                         |
+| `disabled`                | the whole group, or one option via its `disabled`    |
+
+## The label belongs to the radio, not next to it
+
+`Radio` renders its own `label` and `description` and makes the whole row the
+press target. A dot with a separate `<Text>` beside it is a smaller target, and
+tapping the words does nothing — which reads as an unresponsive control.
+
+If you need the dot alone — inside a custom row, a card selector, a table cell —
+that is [`RadioIndicator`](/docs/bloom/main/radio-indicator), which is
+presentational and takes `selected`. Using the indicator where you meant the
+control is how a "radio group" ends up announcing as decoration.
+
+## Radio, Switch or Checkbox
+
+- **Radio** — one of several named options, all visible, mutually exclusive.
+- **[Switch](/docs/bloom/main/switch)** — a single thing that is on or off,
+  taking effect immediately.
+- **Checkbox** — several independent options, or an intent confirmed later.
+
+Two radios is usually a sign the choice is really a switch — unless both
+options need naming ("Metric" / "Imperial"), which is exactly when radios are
+right.
+
+## A group with nothing selected
+
+`value` may be `undefined`. Prefer that over pre-selecting an option the user
+did not choose: a default that happens to be first is indistinguishable from an
+answer, and it silently becomes the submitted value.

package/docs/scroll.mdx

@@ -0,0 +1,66 @@
+---
+title: Scroll restoration
+description: Returning to content where the user left it — and the decisions that make it feel right.
+order: 55
+---
+
+# Scroll restoration
+
+`@oxyhq/bloom/scroll` remembers where the user was and puts them back. The core
+is router-agnostic; one adapter binds it to a router.
+
+```tsx
+import { ScrollRestorationProvider } from '@oxyhq/bloom/scroll';
+import { expoRouterScrollAdapter } from '@oxyhq/bloom/scroll/expo-router';
+
+<ScrollRestorationProvider adapter={expoRouterScrollAdapter}>
+  <App />
+</ScrollRestorationProvider>
+```
+
+An expo-router app gets this from [`BloomProvider`](/docs/bloom/main/provider)
+already. A Vite/SPA consumer mounts it directly with its own adapter.
+
+**The adapter must be a module-level constant** — the core calls its members as
+hooks, so a value built inside a component changes the hook identity every
+render.
+
+## The key is CONTENT, not the navigation entry
+
+An offset is stored against the content's identity (route name plus sorted
+params) and the caller's optional `key` — deliberately **not** against the
+history entry.
+
+So content the user has already seen restores however they arrived at it, and
+only unseen content opens at the top. The accepted trade-off: the same content
+open in two live entries shares one offset.
+
+`contentId` comes from the adapter via `useRoute()`, never `usePathname()` —
+`usePathname` reads the globally focused route, so a background screen would
+adopt the foreground one's path and restore to a stranger's offset.
+
+## A miss RESETS to 0; it is not a no-op
+
+On a document-scrolled web app, one window scroller serves every route. If
+arriving at unseen content did nothing, it would inherit the previous screen's
+offset — you would open a new page halfway down.
+
+## Native is deliberately narrower
+
+The native hook is keyed on the storage key, never on focus, and it **returns**
+`{ onScroll, restorePending }` for the caller to wire up rather than attaching
+itself.
+
+`enabled` is how the caller says *its rows exist yet* — restoring to an offset a
+list cannot reach yet lands at the bottom of a short list. It is not a feature
+flag.
+
+## What to expect on web
+
+- The restore re-applies across a bounded run of frames, because a re-shown
+  virtualized list reaches full height over several.
+- It **aborts on user input** (`wheel`, `touchstart`, `pointerdown`, `keydown`).
+  If the user starts scrolling, they have taken over.
+- `history.scrollRestoration` is set to `'manual'` only while the provider is
+  mounted, and handed back on `pagehide` — so an app that unmounts it does not
+  leave the browser's own restoration disabled.