@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/card.mdx

@@ -0,0 +1,106 @@
+---
+title: Card
+description: The one card-shaped surface — background, border, elevation and corner decided in a single place.
+order: 20
+---
+
+# Card
+
+`Card` is the answer to "what is a card made of". One component owns the `card`
+background role, the border colour and width, the elevation and the corner
+rung — and the platform split those imply, since a shadow is a `box-shadow` on
+web and `elevation` on Android.
+
+Five families used to draw that chrome by hand, with five different radii and
+three different elevations. That is what `Card` removes. It does **not** remove
+the variety: a settings group, a hover card and a link preview are legitimately
+different surfaces, and the radius scale has rungs precisely so they can differ.
+
+```tsx
+import { Card, CardHeader, CardBody, CardFooter, CardTitle, CardDescription } from '@oxyhq/bloom/card';
+
+<Card variant="outlined" radius="radius-16">
+  <CardHeader>
+    <CardTitle>Weekly digest</CardTitle>
+    <CardDescription>Sent every Monday at 09:00.</CardDescription>
+  </CardHeader>
+  <CardBody>…</CardBody>
+</Card>
+```
+
+## Which prop decides what
+
+| prop        | decides                                                          |
+| ----------- | ---------------------------------------------------------------- |
+| `variant`   | the preset combination of background, border and elevation        |
+| `radius`    | the corner, as a **rung of the `RADIUS` scale** — never a number  |
+| `border`    | `none` · `hairline` (0.5px) · `thin` (1px)                        |
+| `elevation` | `none` · `s` (a subtle raise) · `m` (the overlay role)            |
+
+`variant` is only a named default for the other three. An explicit `border` or
+`elevation` wins, in both directions — you can add a shadow to `plain` and take
+one away from `elevated`. That is deliberate: a surface that is "an outlined
+card but flatter" should refine the axes rather than earn a fifth variant name.
+
+```tsx
+<Card variant="plain" border="hairline" elevation="m" radius="radius-20" />
+```
+
+## Variants
+
+- `plain` — the bare `card` surface: no border, no shadow.
+- `elevated` — `shadow-s`. The default.
+- `outlined` — a 1px border in the `border` role.
+- `filled` — paints from `backgroundSecondary` instead of `card`, for a surface
+  that sits **on** a card rather than being one.
+
+## `radius` is a rung, not a number
+
+```tsx
+<Card radius="radius-20" />   // ✅
+<Card radius={20} />          // ✗ does not type-check
+```
+
+The scale has 2 / 4 / 12 / 16 / 20 / 24 / 28 / max. Taking a rung rather than a
+number is what keeps "this surface is a bit rounder" to eight values instead of
+eight hundred, and it is why a design change to a rung moves every surface that
+uses it.
+
+## The mistake it prevents
+
+Hand-rolling the chrome means hand-rolling the platform split too, and the
+usual result is a `Platform.OS` branch with slightly different numbers from the
+one next to it. Worse, on web it is tempting to reach for classes —
+`border border-border bg-card` — which are **inert until the consumer wires the
+Tailwind pipeline**. That failure is silent: the card renders as an unbordered
+transparent block, nothing throws, and it looks like a spacing bug.
+
+`Card` applies background, border, radius and shadow as resolved inline tokens,
+so the surface paints with or without a consumer's CSS pipeline.
+
+## Pressable cards
+
+Passing `onPress` makes the card a `Pressable` with a press dip. Say what it
+is: a card that opens a URL is a `link`, a card that performs an in-app action
+is a `button` (the default).
+
+```tsx
+<Card onPress={open} accessibilityRole="link" accessibilityLabel="Read the post" />
+```
+
+## Clipping
+
+`Card` sets `overflow: 'hidden'` so a cover image cannot paint over the corner.
+A surface that must *not* clip — because it has an Android elevation, or
+because a child deliberately overflows — opts out through `style`:
+
+```tsx
+<Card style={{ overflow: 'visible' }} />
+```
+
+## Parts
+
+`CardHeader`, `CardBody`, `CardFooter`, `CardTitle` and `CardDescription` are
+spacing and type conventions, not requirements. A card with entirely custom
+content is a normal thing; use the parts when you want the same rhythm as every
+other card.

package/docs/checkbox.mdx

@@ -0,0 +1,59 @@
+---
+title: Checkbox
+description: A tri-state checkbox with an optional label and description.
+order: 24
+---
+
+# Checkbox
+
+A checkbox. Controlled, with an optional label and description, three sizes and a mixed state.
+
+## Basic
+
+```tsx
+import { Checkbox } from '@oxyhq/bloom/checkbox';
+
+const [checked, setChecked] = useState(false);
+
+<Checkbox checked={checked} onCheckedChange={setChecked} label="Remember me" />
+```
+
+`label` also becomes the accessible name, so a labelled checkbox needs nothing else. A checkbox with no label needs `accessibilityLabel`.
+
+```tsx
+<Checkbox
+  checked={notify}
+  onCheckedChange={setNotify}
+  label="Email notifications"
+  description="Get a message when someone replies to you."
+/>
+```
+
+## The mixed state
+
+```tsx
+<Checkbox
+  checked={allChecked}
+  indeterminate={!allChecked && someChecked}
+  onCheckedChange={(next) => setAll(next)}
+  label="Select all"
+/>
+```
+
+`indeterminate` announces as `aria-checked="mixed"` and draws a rounded bar rather than a second glyph — the icon set has no minus, and a rule is what the state means.
+
+## Sizes and colour
+
+`size` is `small`, `medium` (default) or `large`. `color` overrides the checked fill; it defaults to the theme primary, and the mark on top of it resolves to that preset's readable foreground rather than a hardcoded white.
+
+## Touch target
+
+The box is 22dp at the default size, which is half of what a finger needs. The pressable is grown to 44dp with `hitSlop` — the target grows, the drawing does not — and the slack is derived per size, so `large` does not overshoot into a neighbouring row.
+
+For a labelled checkbox the pressable already spans the label, so the whole row is the target.
+
+## Keyboard focus on web
+
+The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. It rings the element the browser actually focuses — the box AND its label — because ringing anything else would point at something that does not have focus.
+
+`:focus-visible`, not `:focus`: a mouse click never leaves a ring behind.

package/docs/chip.mdx

@@ -0,0 +1,53 @@
+---
+title: Chip
+description: A labelled pill — a filter, a tag, a removable token.
+order: 23
+---
+
+# Chip
+
+A labelled pill. A filter you can toggle, a tag you can remove, or a static token.
+
+`Chip` is what shadcn calls `Badge`. Bloom's own [`Badge`](/docs/bloom/main/design-tokens) is a different component — a counter or a dot that rides on another control — so if you are porting a `<Badge>Draft</Badge>` from shadcn, this is the one you want.
+
+## Basic
+
+```tsx
+import { Chip } from '@oxyhq/bloom/chip';
+
+<Chip>Draft</Chip>
+<Chip variant="solid" color="success">Published</Chip>
+<Chip variant="subtle" color="warning">Needs review</Chip>
+```
+
+## Tone and fill
+
+`color` picks the tone (`default`, `primary`, `success`, `warning`, `error`, `info`) and `variant` picks how loudly it is painted (`solid`, `subtle`, `outlined` — default `outlined`). shadcn's four badge variants map onto that pair: `default` is `solid` + `primary`, `secondary` is `subtle` + `default`, `destructive` is `solid` + `error`, and `outline` is `outlined` + `default`.
+
+Both come from `theme/accent-colors.ts`, the one resolver `Chip` and `Badge` share. Never derive a tint yourself by appending alpha to a token — an accent resolves to `rgb(...)`, so the appended-hex form parses back fully opaque and paints the label on its own colour at contrast 1.00.
+
+## Filter pills
+
+```tsx
+<Chip variant="subtle" selected={active} onPress={toggle}>
+  Music
+</Chip>
+```
+
+`selected` promotes the chip to the brand tone rather than to a colour system of its own, and announces as `aria-pressed`. On web a keyboard user gets a `:focus-visible` ring — keyboard-only, so a mouse click does not leave one behind.
+
+## Removable
+
+```tsx
+<Chip onClose={() => removeTag(tag)}>{tag}</Chip>
+```
+
+The close affordance is its own control inside the pill, with its own label and its own hit slop.
+
+## Sizes and icons
+
+`size` is `small`, `medium` (default) or `large`. `startIcon` and `endIcon` take any node, and both are sized to the pill rather than to whatever was passed — an icon in a `small` chip and the same icon in a `large` one come out proportional.
+
+## A pill does not shrink
+
+In a flex row of chips — a filter bar, a tag list — each pill keeps its size and the row overflows, rather than every label squeezing into an ellipsis to make room. Inside one pill, the label yields first: a chip narrower than its own text ellipsises rather than spilling past its radius.

package/docs/code.mdx

@@ -0,0 +1,50 @@
+---
+title: Code
+description: Inline monospace and code blocks, as real elements rather than styled text.
+order: 53
+---
+
+# Code
+
+`Code` is **inline** — an identifier, a flag, a token inside a sentence.
+`Pre` is a **block** — a command, a snippet, a config file.
+
+```tsx
+import { Code, Pre } from '@oxyhq/bloom/code';
+
+<Text>
+  Pass <Code>variant="outlined"</Code> to draw the border.
+</Text>
+
+<Pre>{`bun add @oxyhq/bloom
+bun run build`}</Pre>
+```
+
+## They are elements, not fonts
+
+On web `Code` renders a real `<code>`. That matters for more than styling:
+find-in-page, copy behaviour, and assistive technology all treat it as code
+rather than as decoration. On native it is a `Text` in the monospace family.
+
+## `Pre` keeps its whitespace and scrolls
+
+A block preserves line breaks and indentation and scrolls horizontally rather
+than wrapping. Wrapping is the wrong default for a command: a wrapped command
+is a command someone will copy wrong, and the break is invisible once pasted.
+
+Write the content as a template literal so the source's own indentation does
+not leak into the block.
+
+## Use `Code` for things that are typed, not for emphasis
+
+`Code` means *this is a literal you would type or paste*: a prop name, a flag,
+a file path, an env var. It is not a way to make a word stand out — monospace
+in the middle of a sentence tells the reader "this is exact", and using it for
+emphasis makes the real literals unfindable.
+
+## No syntax highlighting
+
+`Pre` renders text. Highlighting means shipping a grammar for every language a
+consumer might use, and getting it wrong is worse than not having it —
+mis-tokenised code reads as broken code. If a surface genuinely needs
+highlighting, it belongs to that surface.

package/docs/combobox.mdx

@@ -0,0 +1,64 @@
+---
+title: Combobox
+description: A select you can type into — for when the option list is too long to scan.
+order: 42
+---
+
+# Combobox
+
+A picker with a search field. Reach for it when there are more options than a
+user can scan — a country, a repository, a person.
+
+```tsx
+import { Combobox } from '@oxyhq/bloom/combobox';
+
+<Combobox
+  options={apps.map((a) => ({ value: a.id, label: a.name, description: a.tagline }))}
+  value={appId}
+  onValueChange={setAppId}
+  placeholder="Pick an app"
+  emptyText="No apps match that"
+/>
+```
+
+## Which prop decides what
+
+| prop                      | decides                                             |
+| ------------------------- | ---------------------------------------------------- |
+| `options`                 | the choices — `value`, `label`, optional `description` |
+| `value` / `onValueChange` | the selection; `null` means nothing chosen            |
+| `placeholder`             | the trigger text while nothing is selected            |
+| `emptyText`               | what an empty result says                             |
+| `filter`                  | replaces the default match                            |
+| `query` / `onQueryChange` | the search text, if you want to control it            |
+| `maxListHeight`           | how tall the list may grow                            |
+
+## The trigger shows the LABEL
+
+`value` is an opaque id to the user. A combobox that renders the value into the
+field shows `usr_8f21c` where the user chose "Ada Lovelace" — which reads as a
+bug rather than as a raw id.
+
+## Controlled `query` is for search that leaves the component
+
+By default the combobox owns the query. Take control of it when the *filtering*
+happens elsewhere — a debounced server search, a query mirrored into the URL:
+
+```tsx
+<Combobox query={q} onQueryChange={setQ} options={serverResults} filter={() => true} />
+```
+
+Note the `filter={() => true}`: if the server already filtered, filtering again
+locally throws away results that matched for reasons the client cannot see.
+
+## `emptyText` earns its place
+
+An empty popover reads as broken. Saying "No apps match that" tells the user
+the search worked and there is nothing — a different message from silence.
+
+## Combobox, Select or Command
+
+- **Combobox** — many values, typing needed to find one, selection persists.
+- **[Select](/docs/bloom/main/select)** — few enough values to scan.
+- **[Command](/docs/bloom/main/command)** — **actions**, not values; runs one
+  and closes.

package/docs/command.mdx

@@ -0,0 +1,85 @@
+---
+title: Command
+description: A command palette — search across everything the user could do from here.
+order: 41
+---
+
+# Command
+
+A searchable list of actions, opened over the page. Type to filter, press to run.
+
+```tsx
+import { Command } from '@oxyhq/bloom/command';
+
+<Command
+  visible={paletteOpen}
+  onClose={() => setPaletteOpen(false)}
+  placeholder="Type a command…"
+  items={[
+    {
+      id: 'new-post',
+      label: 'New post',
+      group: 'Create',
+      shortcut: '⌘N',
+      icon: PencilIcon,
+      onSelect: newPost,
+    },
+    {
+      id: 'settings',
+      label: 'Open settings',
+      description: 'Account, appearance, notifications',
+      keywords: ['preferences', 'account'],
+      group: 'Navigate',
+      onSelect: () => router.push('/settings'),
+    },
+  ]}
+/>
+```
+
+## Which prop decides what
+
+| prop            | decides                                                    |
+| --------------- | ----------------------------------------------------------- |
+| `visible` / `onClose` | whether it is open — controlled                        |
+| `items`         | everything that can be run                                   |
+| `query` / `onQueryChange` | the search text, if you want to control it         |
+| `filter`        | replaces the default match                                   |
+| `emptyText`     | what an empty result says                                    |
+| `maxListHeight` | how tall the list may grow                                   |
+
+## `keywords` is what makes a palette usable
+
+A palette is only as good as its synonyms. A user looking for "preferences"
+will not type "settings", and a user looking for "dark mode" will not type
+"appearance". `keywords` are matched alongside the label and description and
+are never shown, so they cost nothing on screen.
+
+```tsx
+{ id: 'theme', label: 'Appearance', keywords: ['dark mode', 'light', 'theme'] }
+```
+
+## `group` is a heading, not a filter
+
+Items are grouped under their `group` label in the order the groups first
+appear. Grouping helps a user *scan* a list they did not search; once they type,
+what matters is the match, not the category.
+
+## `shortcut` is a reminder, not a binding
+
+Setting it draws the key hint on the row. It does **not** register a keyboard
+shortcut — the app owns its key handling, and a palette that silently bound
+keys would collide with the page underneath.
+
+## An item that cannot run should not be listed
+
+Prefer omitting an inapplicable action to showing it `disabled`. A palette is
+searched, not browsed: a disabled row is a match that answers the query and
+then refuses, which is worse than no match at all. Keep `disabled` for the case
+where the user needs to know the action *exists* here but is unavailable right
+now.
+
+## Command or Combobox
+
+- **Command** — a list of **actions**, opened over the page, closed after one.
+- **[Combobox](/docs/bloom/main/combobox)** — a list of **values**, inside a
+  form, producing a selection that stays.

package/docs/composition-bar.mdx

@@ -0,0 +1,63 @@
+---
+title: CompositionBar
+description: What a total is made of — a segmented bar with a readout you can interrogate.
+order: 62
+---
+
+# CompositionBar
+
+A single bar split into coloured segments, with a readout for the selected one.
+Use it when the question is *what is this total made of* — a portfolio by
+asset, spending by category, storage by file type.
+
+```tsx
+import { CompositionBar } from '@oxyhq/bloom/composition-bar';
+
+<CompositionBar
+  categories={[
+    { key: 'eth', name: 'Ethereum', amount: 4200, color: '#627EEA' },
+    { key: 'btc', name: 'Bitcoin', amount: 3100, color: '#F7931A' },
+    { key: 'other', name: 'Other', amount: 900, color: '#9CA3AF' },
+  ]}
+  selectedKey={selected}
+  onSelect={setSelected}
+  hintLabel="Tap a segment"
+/>
+```
+
+## Which prop decides what
+
+| prop             | decides                                                  |
+| ---------------- | --------------------------------------------------------- |
+| `categories`     | the segments — `key`, `name`, `amount`, `color`            |
+| `selectedKey`    | which segment's readout is shown; `null` for none          |
+| `onSelect`       | the press                                                  |
+| `hintLabel`      | the prompt shown while nothing is selected                 |
+| `formatReadout`  | how the selected amount and percentage are worded          |
+
+## The readout is the point
+
+`selectedKey` and `onSelect` are required. A segmented bar with no way to ask
+"which slice is that?" is decoration: the colours are unlabelled and the widths
+are unreadable below about 5%.
+
+`null` is a real state — nothing selected — and not the same as selecting the
+first category on the user's behalf. `hintLabel` is what fills that space.
+
+## Amounts, not percentages
+
+Pass raw `amount`s and let the component compute the shares. Pre-computing
+percentages is how the segments stop summing to 100 after rounding, which shows
+up as a sliver of background at the end of the bar.
+
+## Keep the category count low
+
+Five or six. Beyond that the small segments are too thin to press and the
+colours stop being distinguishable — group the tail into an "Other" category
+with its own neutral colour, as above.
+
+## `formatReadout`
+
+The default states the amount and its share. Override it when the unit needs
+saying (`$4,200`, `4.2 GB`) — a bare number in a readout is the same problem as
+a bare number anywhere else.

package/docs/connection-dots.mdx

@@ -0,0 +1,50 @@
+---
+title: ConnectionDots
+description: An animated link between two things — an OAuth consent shape, not a loading state.
+order: 68
+---
+
+# ConnectionDots
+
+Two elements with a run of animated dots travelling between them. It is the
+"this app is connecting to your account" illustration on a consent screen.
+
+```tsx
+import { ConnectionDots } from '@oxyhq/bloom/connection-dots';
+
+<ConnectionDots
+  left={<AppLogo />}
+  right={<Avatar source={user.avatar} size={48} />}
+  accessibilityLabel="Notion is connecting to your Oxy account"
+/>
+```
+
+## Which prop decides what
+
+| prop                 | decides                                            |
+| -------------------- | --------------------------------------------------- |
+| `left` / `right`     | the two endpoints — required                        |
+| `dotCount` / `dotSize` | the run between them                              |
+| `accessibilityLabel` | what the whole illustration means                   |
+| `reducedMotion`      | render the dots static instead of animating         |
+
+## It illustrates a relationship, not progress
+
+The dots move continuously; they do not fill up. Nothing here says how far
+along anything is, and using it while an operation runs implies a progress bar
+that never advances. For work in flight use [`Loading`](/docs/bloom/main/loading).
+
+## Give it a label
+
+The whole point is carried by the picture: two parties and a link between them.
+Without `accessibilityLabel` a screen reader gets an app logo, an avatar, and
+nothing about the relationship — which is exactly the thing the user is being
+asked to consent to.
+
+Name both sides in the label, in the direction the consent runs.
+
+## `reducedMotion`
+
+Honour the OS setting. Perpetual motion is one of the more uncomfortable
+patterns for motion-sensitive users, and this one runs for as long as the
+screen is open. The static form still communicates the link.

package/docs/connection-status.mdx

@@ -0,0 +1,56 @@
+---
+title: ConnectionStatusToasts
+description: Offline and reconnected, announced once — with a delay that hides the flap.
+order: 70
+---
+
+# ConnectionStatusToasts
+
+Mount it once and the app announces losing and regaining its connection.
+
+```tsx
+import { ConnectionStatusToasts } from '@oxyhq/bloom/connection-status';
+
+<ConnectionStatusToasts />
+```
+
+## Which prop decides what
+
+| prop                   | decides                                              |
+| ---------------------- | ----------------------------------------------------- |
+| `offlineMessage`       | shown while there is no connection                    |
+| `reconnectingMessage`  | shown after `reconnectingDelayMs` offline             |
+| `restoredMessage`      | shown when the connection comes back                  |
+| `reconnectingDelayMs`  | how long to wait before escalating                    |
+| `restoredDurationMs`   | how long the restored toast stays                     |
+
+## "Back online" is only shown to someone who saw the outage
+
+The restored toast is suppressed unless an outage toast was actually up. A
+"Back online" that appears on its own is confusing — the user never knew
+anything was wrong, and the message implies they missed something.
+
+## The delay is the point
+
+Connectivity flaps. Announcing every dropped packet produces a toast that
+appears and disappears while the user is reading, which is worse than silence.
+The offline toast is shown immediately because the user is about to hit a
+failure; the *reconnecting* escalation waits, so a two-second blip never
+escalates at all.
+
+## Optional peer
+
+Connectivity comes from `@react-native-community/netinfo`, loaded through
+Bloom's optional-require boundary. Without the package installed the component
+mounts and does nothing rather than failing the build.
+
+That is why the require is written the way it is — a literal specifier, as a
+direct statement of a `try` block. Metro's optionality walk returns at the
+first enclosing block, so one `if` of nesting inside the `try` would lose
+optionality and turn a missing optional peer into a build failure.
+
+## Mount it once
+
+It presents through the shared [toast](/docs/bloom/main/toast) engine with a
+fixed id, so a second mount does not duplicate the toast — but it does double
+the listeners and the timers. One per app.

package/docs/content-panel.mdx

@@ -0,0 +1,62 @@
+---
+title: ContentPanel
+description: The reading column — a width constraint that optionally becomes a framed surface.
+order: 50
+---
+
+# ContentPanel
+
+The column a screen's content lives in. It caps the reading width and, above a
+breakpoint, decides whether that column reads as a framed surface or as the
+page itself.
+
+```tsx
+import { ContentPanel } from '@oxyhq/bloom/content-panel';
+
+<ContentPanel framed framedFrom={640}>
+  <SettingsScreen />
+</ContentPanel>
+```
+
+## Which prop decides what
+
+| prop               | decides                                                  |
+| ------------------ | --------------------------------------------------------- |
+| `framed`           | whether the panel draws a surface at all                   |
+| `framedFrom`       | the breakpoint it starts framing at — `500` `640` `768` `1024` |
+| `showStickyFrame`  | whether the frame persists behind sticky content           |
+| `surfaceStyle` / `surfaceClassName` | the surface itself                        |
+| `contentStyle` / `contentClassName` | the column inside it                      |
+| `maskColor`        | the colour the gutter mask fades to                        |
+
+## `framedFrom` is why the branch is not in your screen
+
+A phone wants a plain column: a frame a few pixels from the screen edge reads
+as a rendering bug, not as a card. A desktop wants the framed surface. Handling
+that in the screen means every screen re-derives the same breakpoint, and they
+drift.
+
+## Panels are siblings, never nested
+
+`ContentPanel` **throws** if you nest one inside another. That is deliberate: a
+panel in a panel would frame inside a frame and inset the reading column twice,
+which looks merely "a bit padded" and would survive review indefinitely. A loud
+failure in development is the cheaper outcome.
+
+Two columns side by side are two panels as **siblings**:
+
+```tsx
+<View style={{ flexDirection: 'row', gap: 16 }}>
+  <View style={{ flex: 2 }}><ContentPanel framed>…</ContentPanel></View>
+  <View style={{ flex: 1 }}><ContentPanel framed>…</ContentPanel></View>
+</View>
+```
+
+A screen picks one panel per column; the sections inside it are plain views.
+
+## Do not put a Card immediately inside a framed panel
+
+They are both surfaces. A card filling a framed panel is two borders with a few
+pixels between them. Use the panel's frame, and reach for
+[`Card`](/docs/bloom/main/card) for things *within* the column that are
+genuinely separate objects.