@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/frosted-icon-button.mdx

@@ -0,0 +1,60 @@
+---
+title: FrostedIconButton
+description: A translucent icon button for use over media, where a normal button has nothing to sit on.
+order: 65
+---
+
+# FrostedIconButton
+
+A circular icon button with a blurred, translucent background. It is for
+controls that float **over content** — a close button on a photo viewer, a
+mute toggle on a video, a back button over a hero image.
+
+```tsx
+import { FrostedIconButton } from '@oxyhq/bloom/frosted-icon-button';
+
+<FrostedIconButton
+  icon={<CloseIcon />}
+  accessibilityLabel="Close"
+  onPress={close}
+/>
+```
+
+## Which prop decides what
+
+| prop       | decides                                             |
+| ---------- | ---------------------------------------------------- |
+| `icon`     | the glyph                                            |
+| `size`     | `sm` · `md`, or a number                             |
+| `active`   | a persistent on state, for a toggle                  |
+| `disabled` | dims and disables                                    |
+| `hitSlop`  | the touch target beyond the drawn circle             |
+
+## Why it exists rather than a `Button` variant
+
+Over arbitrary media there is no background to be legible against: a photo can
+be white here and black there. The frosted fill blurs whatever is behind it so
+the glyph keeps its contrast wherever the button lands, which is not something
+a solid or ghost button can do.
+
+That also means it is the wrong choice **on** a surface. Over a card or a page
+background, frosting blurs a flat colour — it costs a blur pass to look like a
+slightly muddy circle. Use `Button`'s icon form there.
+
+## Always give it a label
+
+An icon-only button announces as "button" and nothing else. `accessibilityLabel`
+is not decoration here; it is the entire accessible name.
+
+## `hitSlop` for small buttons
+
+A 32px circle over media is usually near a screen edge and pressed with a
+thumb. `hitSlop` grows the target without growing the drawn button, which is
+preferable to drawing something bigger than the design calls for.
+
+## Web-only props
+
+`onClick`, `title`, `id`, `type` and `aria-label` are on the shared type so one
+call site type-checks on both platforms. They are consumed by the web fork,
+which renders a real DOM `<button>`, and are no-ops on native. Prefer
+`onPress` and `accessibilityLabel`, which work on both.

package/docs/getting-started.mdx

@@ -0,0 +1,75 @@
+---
+title: Getting started
+description: Install Bloom and wrap your app with the theme and dialog providers.
+order: 1
+---
+
+# Getting started
+
+## 1. Install
+
+```sh
+bun add @oxyhq/bloom
+```
+
+Install the peer dependencies. The same set covers native and web — Bloom's
+overlays and its toast engine run on react-native-web:
+
+```sh
+bun add react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg
+```
+
+## 2. Wrap your app root
+
+```tsx
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { BloomThemeProvider, SurfaceProvider } from '@oxyhq/bloom';
+
+export default function Root() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <BloomThemeProvider mode="system" colorPreset="teal">
+        <SurfaceProvider>
+          <App />
+        </SurfaceProvider>
+      </BloomThemeProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+- `BloomThemeProvider` is required — every Bloom component reads from it.
+- `SurfaceProvider` (or a bare `<SurfaceHost />`) is required only if you use the imperative surfaces — `alert()`, `confirm()`, `prompt()`, `surfaces.present()`. Without it, `<Dialog>` still works on its own.
+- `GestureHandlerRootView` is required on native for any sheet-based component.
+
+<Callout variant="warning" title="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>
+```
+</Callout>
+
+## 3. Use a component
+
+```tsx
+import { Button } from '@oxyhq/bloom/button';
+import { toast } from '@oxyhq/bloom';
+
+export function Hello() {
+  return <Button onPress={() => toast.success('Hello, Bloom!')}>Greet</Button>;
+}
+```
+
+## Recommended layout
+
+If your app supports both light and dark themes:
+
+```tsx
+<BloomThemeProvider mode="system" colorPreset="teal">
+```
+
+`mode="system"` follows the OS preference. `colorPreset` picks one of the 10 named palettes — see [Theme](/docs/bloom/main/theme) for the full list.

package/docs/grid.mdx

@@ -0,0 +1,64 @@
+---
+title: Grid
+description: Row and Col — a gutter that keeps the grid's outer edges flush with everything else.
+order: 45
+---
+
+# Grid
+
+`Row` and `Col` are a twelfth-free fractional grid. A row holds columns; each
+column takes a fraction of the width.
+
+```tsx
+import { Row, Col } from '@oxyhq/bloom/grid';
+
+<Row gap={16}>
+  <Col width={2 / 3}>
+    <Article />
+  </Col>
+  <Col width={1 / 3}>
+    <Sidebar />
+  </Col>
+</Row>
+```
+
+## Which prop decides what
+
+| prop    | decides                                                    |
+| ------- | ----------------------------------------------------------- |
+| `gap`   | on `Row`, the space between columns                          |
+| `width` | on `Col`, its fraction of the row — `0.5`, `1 / 3`, `0.25`   |
+
+## How the gutter works, and why it matters
+
+The row pulls itself out by **half** the gap on each side, and each column pads
+in by half. The result is that the outer edges of the grid line up with the
+content above and below it, while the columns are still separated.
+
+A grid that only padded its columns would be inset by half a gutter on both
+sides — a few pixels of misalignment against every other block on the page,
+which is the kind of thing that looks like nothing and reads as sloppy.
+
+That is also why a `Col` outside any `Row` gets no gutter at all rather than a
+default one: without a row there is no negative margin to compensate for it.
+
+## `width` is a fraction, not a column count
+
+`width={1 / 3}` rather than `width={4}` out of twelve. Fractions compose with
+any number of columns and do not require the reader to remember the divisor.
+`1 / 3` is exactly what it says; `4` is only meaningful once you know the grid
+is twelve wide.
+
+## Grid or flexbox
+
+`Row`/`Col` is for a **proportional split** — two thirds and one third,
+regardless of content. Ordinary flexbox is better when the split follows the
+content (a label that hugs its text beside a field that takes the rest), and a
+`gap` on a plain `View` is better when everything is the same size.
+
+## Wrapping
+
+`Row` does not wrap. A responsive layout switches between one column and two by
+rendering different structures at the breakpoint, rather than by letting a row
+reflow — a wrapped grid loses the alignment the gutter maths exists to
+preserve.

package/docs/hooks.mdx

@@ -0,0 +1,81 @@
+---
+title: Hooks
+description: The shared behaviours Bloom's own components are built on.
+order: 73
+---
+
+# Hooks
+
+`@oxyhq/bloom/hooks` is the set of behaviours Bloom's components share. They
+are exported because apps hit the same problems, and because a second copy of
+any of them drifts.
+
+```tsx
+import { useInteractionState, useDelayedLoading, useGutters } from '@oxyhq/bloom/hooks';
+```
+
+## `useInteractionState`
+
+Press and hover state as plain booleans, with the handlers to wire up.
+
+```tsx
+const { state: pressed, onIn, onOut } = useInteractionState();
+
+<Pressable onPressIn={onIn} onPressOut={onOut} style={[base, pressed && dim]}>
+```
+
+Bloom uses this rather than `Pressable`'s function-form `style`, which
+NativeWind's css-interop swallows — taking the base container style (background,
+radius, border, shadow) with it. That failure is silent and total: the component
+renders unstyled and nothing errors.
+
+## `useDelayedLoading`
+
+Holds a flag true for a fixed delay, then flips it false.
+
+```tsx
+const settling = useDelayedLoading(300);        // true for 300ms, then false
+const showContent = !settling && !isFetching;
+```
+
+It takes the DELAY, not the loading flag: `useDelayedLoading(delay, initialState?)`.
+Use it to guarantee a minimum on-screen time. A spinner that appears for 80ms
+and vanishes is worse than no spinner — the flash reads as a glitch, and the
+user cannot tell what happened.
+
+## `useThrottledValue`
+
+A value that updates at most every N ms. For anything that re-renders a
+expensive tree on a continuous input — a drag, a scroll position, a typed
+query.
+
+## `usePressAnimation`
+
+The shared press transform, so a press dip is the same everywhere.
+
+## `useGutters`
+
+The screen's horizontal insets, from one place, so a header and the content
+below it agree about where the margin is.
+
+## `useHaptics`
+
+Haptic feedback through Bloom's optional-peer boundary — a no-op when
+`expo-haptics` is not installed, rather than a build failure.
+
+Mount `BloomHapticsProvider` if the app needs to turn haptics off globally
+(a user setting, or a platform where they are inappropriate).
+
+## `useImagePreload` / `preloadImage`
+
+Fetch an image before it is rendered — the transition into a full-screen viewer,
+the next page of a carousel.
+
+## `mergeRefs`
+
+Combines several refs into one callback.
+
+Note the return type: `(instance: T | null) => void`, **not**
+`React.RefCallback<T>`. That is deliberate — the plain function type stays
+assignable across duplicate copies of `@types/react` in a consumer's tree,
+which the branded type does not.

package/docs/icon-circle.mdx

@@ -0,0 +1,66 @@
+---
+title: IconCircle
+description: An icon on a tinted disc — the reference for how Bloom tints anything.
+order: 47
+---
+
+# IconCircle
+
+An icon centred on a coloured disc. Empty states, consent steps, the header of
+a settings section — anywhere an icon needs presence rather than sitting beside
+text.
+
+```tsx
+import { IconCircle } from '@oxyhq/bloom/icon-circle';
+import { Shield_Stroke2_Corner0_Rounded as ShieldIcon } from '@oxyhq/bloom/icons';
+
+<IconCircle icon={ShieldIcon} />
+<IconCircle icon={ShieldIcon} size="lg" />
+```
+
+## Which prop decides what
+
+| prop        | decides                                       |
+| ----------- | ---------------------------------------------- |
+| `icon`      | the glyph component — passed, not rendered      |
+| `size`      | `lg` (52px) or `xl` (64px, the default)         |
+| `style`     | the disc                                       |
+| `iconStyle` | the glyph                                      |
+
+`icon` takes the component itself (`icon={ShieldIcon}`), not an element
+(`icon={<ShieldIcon />}`), so the circle can size and colour it.
+
+## The tinting rule this component is the reference for
+
+The disc is `primarySubtle` and the glyph is `primary` — a **pair** of resolved
+tokens, not one token with alpha appended.
+
+That distinction is the whole point. A Bloom accent token resolves to a full
+`rgb(...)`, so `` `${colors.primary}1A` `` is a malformed string that
+react-native-web parses back as fully **opaque**. A disc tinted that way ends
+up the same colour as the glyph on it — contrast 1.00, an invisible icon, and
+markup that reads as correct.
+
+## Override both or neither
+
+`style` moves the disc, `iconStyle` moves the glyph. Changing one is exactly
+how a tinted disc ends up with an invisible icon:
+
+```tsx
+<IconCircle
+  icon={BellIcon}
+  style={{ backgroundColor: 'rgb(255 237 213)' }}
+  iconStyle={{ color: 'rgb(154 52 18)' }}
+/>
+```
+
+If you find yourself doing this often for the same tone, that is a signal the
+tone belongs in the theme — `resolveAccentColors(colors, tone, fill)` reads the
+`*Subtle` / `*SubtleForeground` pairs the design tokens already gate together.
+
+## Not a button
+
+`IconCircle` draws; it does not press. Wrap it in a `Pressable` with an
+`accessibilityLabel` if it should do something — and consider
+[`FrostedIconButton`](/docs/bloom/main/frosted-icon-button) or `Button`'s icon
+form first, which are already controls.

package/docs/icons.mdx

@@ -0,0 +1,69 @@
+---
+title: Icons
+description: 250-odd glyphs with full names — and why a shortened one is invisible to the compiler.
+order: 66
+---
+
+# Icons
+
+Bloom's icon set. Every glyph is a named export carrying its style and corner
+suffix.
+
+```tsx
+import { Bell_Stroke2_Corner0_Rounded as BellIcon } from '@oxyhq/bloom/icons';
+
+<BellIcon size="lg" fill={colors.text} />
+```
+
+## The naming is `<Subject>_<Style>_Corner0_Rounded`
+
+The suffix is not decoration — it is *which drawing you get*. `Stroke2` and
+`Filled` are separate exports rather than a prop on one component, because they
+are different artwork: filled reads as "on"/selected, stroke as the resting
+state. A tab bar uses both for the same subject.
+
+Import the exact identifier and alias it locally, as above.
+
+## `fill` and `size`, not inheritance
+
+Colour travels on `fill` and size on `size`. Neither is inherited from a
+surrounding `Text`, so an icon beside a label has to be told both — an icon
+that "looks black in dark mode" is almost always one that was never given a
+`fill`.
+
+## A shortened name is invisible to `tsc`
+
+Dropping the suffix — writing the bare subject where the full identifier
+belongs — is not a compile error anywhere such a reference usually appears: in
+a **doc comment** or an `.mdx` example, TypeScript never sees it. A reader
+copies it, gets `undefined`, and React reports "Element type is invalid … but
+got: undefined" against *their* file — which is how a phantom release blocker
+once got filed against the tab bar.
+
+`src/__tests__/icon-references.test.ts` scans `src/`, `docs/`, `README.md` and
+`AGENTS.md` for references that do not resolve against the real export union.
+It is the only gate on this class of bug, and it deliberately does **not** strip
+comments, because the comments are the surface under test.
+
+## Two import shapes are correct, one is not
+
+```tsx
+import * as Icons from '@oxyhq/bloom/icons';   // ✅ the subpath, as a namespace
+import { Icons } from '@oxyhq/bloom';          // ✅ the root barrel's namespace
+```
+
+The third shape — importing `Icons` as a *named* export from the **subpath** —
+is `undefined` at runtime. The subpath exports the components flat; the `Icons`
+name is assembled by the root barrel (`export * as Icons from './icons'`), so
+there is no such named export to destructure.
+
+The gate below flags that shape too, which is why this page describes it rather
+than showing it: a counter-example spelled as a literal is indistinguishable
+from the mistake it warns about, and the scan is right to flag both.
+
+## Adding an icon
+
+One file per subject under `src/icons/`, exporting the full identifiers, and
+re-exported from the barrel. Keep the stroke and filled variants together in
+the same file — they are the same subject, and separating them is how one gets
+updated without the other.

package/docs/image-aspect-ratio-cache.mdx

@@ -0,0 +1,63 @@
+---
+title: Image aspect-ratio cache
+description: Remembering an image's shape so a list stops jumping when it loads.
+order: 67
+---
+
+# Image aspect-ratio cache
+
+A process-wide cache of image intrinsic sizes, keyed by URL.
+
+```tsx
+import {
+  getAspectRatio,
+  hasAspectRatio,
+  fetchAspectRatio,
+  setAspectRatio,
+  DEFAULT_ASPECT_RATIO,
+} from '@oxyhq/bloom/image-aspect-ratio-cache';
+
+const ratio = hasAspectRatio(url) ? getAspectRatio(url) : DEFAULT_ASPECT_RATIO;
+```
+
+## The problem it solves
+
+An image's shape is not known until it loads. A list that reserves no space
+reflows every time one arrives, which throws the reading position down the page
+— the classic feed that jumps while you are reading it.
+
+Reserving a *fixed* box instead is not a fix: it letterboxes portrait images and
+crops landscape ones. What you want is the real ratio, remembered, so the second
+time the same image appears there is no jump at all.
+
+## The functions
+
+| function                | for                                                  |
+| ----------------------- | ----------------------------------------------------- |
+| `hasAspectRatio(url)`   | whether the shape is known **without** guessing        |
+| `getAspectRatio(url)`   | the ratio, if known                                    |
+| `getIntrinsicSize(url)` | the width and height, if known                         |
+| `fetchAspectRatio(url)` | measure it and cache the result                        |
+| `setAspectRatio(url, …)`| record one you already know — from a DTO, say          |
+| `DEFAULT_ASPECT_RATIO`  | what to reserve while it is unknown                    |
+
+## `hasAspectRatio` is not the same as `getAspectRatio() !== undefined`
+
+Keep the distinction. "Not measured yet" and "measured, and it happens to be
+the default" want different behaviour: the first should reserve the default and
+then settle, the second is already correct and must not animate.
+
+## Prefer `setAspectRatio` over measuring
+
+If the API already returns the dimensions — most media DTOs do — record them
+and skip the measurement entirely. A ratio known before first paint means the
+layout is right on frame one, which no amount of caching after the fact
+achieves.
+
+## It is a cache, not state
+
+Module-level and process-wide, so it survives navigation and re-renders. Do not
+read it in a memoized position: it is external mutable state, and under the
+React Compiler that is exactly the shape that produces a stale read. Read it
+during render for the initial reservation, and drive updates from the load
+event.

package/docs/image-resolver.mdx

@@ -0,0 +1,66 @@
+---
+title: ImageResolver
+description: The one chokepoint that turns an Oxy file id into a URL.
+order: 54
+---
+
+# ImageResolver
+
+Bloom components take a **file id** and ask the app how to turn it into a URL.
+The app registers that function once, at the root.
+
+```tsx
+import { ImageResolverProvider } from '@oxyhq/bloom/image-resolver';
+import { oxyServices } from '@oxyhq/services';
+
+<ImageResolverProvider value={(id, variant) => oxyServices.getFileDownloadUrl(id, variant)}>
+  <App />
+</ImageResolverProvider>
+```
+
+```ts
+type ImageResolver = (id: string, variant?: string) => string | undefined;
+```
+
+## Why Bloom does not build the URL itself
+
+A URL builder in Bloom would hardcode a host, a path shape and a variant
+vocabulary that belong to the platform, not to a component library — and every
+consumer would then need Bloom released to change any of them. One function,
+registered by the app, keeps the media contract in `@oxyhq/services` where it
+already lives.
+
+That is also why there is no `avatarUrl` field on any DTO and no per-app URL
+helper: **one chokepoint**, `getFileDownloadUrl(id, variant)`, plus this
+resolver.
+
+## `source` versus `uri` — the failure that is total and silent
+
+`Avatar` invokes the resolver only for a **non-URL string** passed as `source`.
+
+```tsx
+<Avatar source={user.avatar} />        // ✅ file id → resolver → URL
+<Avatar uri={user.avatar} />           // ✗ file id used as a raw URL → 404
+```
+
+A full URL or an `{ uri }` object passes through untouched, so both props
+"work" in a test with a real URL and only one of them works with a file id.
+Nothing throws — the image 404s and the avatar falls back to its initial. The
+symptom is *every avatar shows a placeholder character*, which reads as missing
+data rather than as a wiring mistake.
+
+The same applies to every Bloom component that wraps `Avatar`:
+[`AvatarGroup`](/docs/bloom/main/avatar-group) items and
+[`UserHoverCard`](/docs/bloom/main/user-hover-card).
+
+## `variant`
+
+The second argument asks for a size. `Avatar` defaults it to `thumb` rather
+than requesting the full-size original for a 32px circle — a detail worth
+keeping if you write a resolver that ignores the argument.
+
+## Register it once
+
+One provider at the app root. A second one deeper in the tree silently shadows
+the first for that subtree, which produces images that work on some screens and
+not others.

package/docs/index.mdx

@@ -0,0 +1,44 @@
+---
+title: Bloom
+description: Shared UI component library for the Oxy ecosystem. React Native + Expo + Web.
+order: 0
+---
+
+# Bloom
+
+Shared UI component library for the Oxy ecosystem. Built for React Native + Expo + Web.
+
+<Badge>Apache-2.0</Badge>
+
+## 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
+- `react-native-gesture-handler >= 2.16.1` (`Dialog`, `BottomSheet`, toast swipe-to-dismiss) — native also needs the app root wrapped in `GestureHandlerRootView`
+- `react-native-svg >= 13` (Bloom icons, Avatar `squircle` shape)
+
+## What's inside
+
+Bloom ships modal primitives, form controls, layout helpers, typography, theming, and a portal system that works on both native and web. Everything is exported under a sub-path (`@oxyhq/bloom/dialog`, `@oxyhq/bloom/button`, etc.) so tree-shaking stays effective.
+
+## Next steps
+
+- [Getting started](/docs/bloom/main/getting-started) — wire up `BloomThemeProvider` and `SurfaceProvider`.
+- [Theme](/docs/bloom/main/theme) — color presets, modes, design tokens.
+- [Dialog](/docs/bloom/main/dialog) — the unified Dialog API.
+- [BottomSheet](/docs/bloom/main/bottom-sheet) — gesture-driven sheet primitive.
+- [Toast](/docs/bloom/main/toast) — passive notifications.
+- [alert()](/docs/bloom/main/alert) — imperative one-shot confirmations.

package/docs/input-group.mdx

@@ -0,0 +1,58 @@
+---
+title: InputGroup
+description: A control with things attached to it — one bordered box, not several.
+order: 34
+---
+
+# InputGroup
+
+An input with prefixes, suffixes or buttons attached, drawn as **one** bordered
+box so the whole thing reads as a single control.
+
+```tsx
+import { InputGroup, InputGroupAddon } from '@oxyhq/bloom/input-group';
+
+<InputGroup>
+  <InputGroupAddon>oxy.so/</InputGroupAddon>
+  <TextFieldInput label="Handle" value={handle} onChangeText={setHandle} />
+</InputGroup>
+
+<InputGroup>
+  <TextFieldInput label="Search" value={query} onChangeText={setQuery} />
+  <InputGroupAddon divider>
+    <Button size="small" onPress={run}>Search</Button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## Which prop decides what
+
+| prop        | decides                                                       |
+| ----------- | -------------------------------------------------------------- |
+| `size`      | `sm` · `md` · `lg` — applied to the group, so parts agree       |
+| `isInvalid` | the error border on the whole box                              |
+| `disabled`  | dims and disables the group                                    |
+| `divider`   | per addon, a rule between it and the input                     |
+| `noPadding` | per addon, for an addon that supplies its own (a button)        |
+
+## Why the state lives on the group
+
+`isInvalid` and `disabled` are properties of the **control**, not of the input
+element inside it. Setting them per part is how a box ends up with a red border
+and a normal-coloured button, or an enabled button beside a disabled input.
+
+## A prefix is not a placeholder and not a label
+
+`oxy.so/` as an addon is part of the value's shape: it is always visible, it
+does not disappear on typing, and it is not editable. That is different from a
+placeholder (an example, which vanishes) and from a label (the name of the
+field, which belongs to [`Field`](/docs/bloom/main/field) or
+[`Label`](/docs/bloom/main/label)).
+
+`InputGroup` goes *inside* a `Field` — the group is the control, the field is
+its label, hint and error.
+
+## `divider`
+
+Use it when the addon is a distinct target — a button, a dropdown. Skip it for
+a static prefix or an icon, where a rule makes one control look like two.