@oxyhq/bloom 1.0.0 → 1.0.2

package/docs/search.mdx

@@ -0,0 +1,67 @@
+---
+title: Search
+description: A pill-shaped search field whose clear button appears only when there is something to clear.
+order: 48
+---
+
+# Search
+
+A search input: magnifier, rounded field, and a clear button that appears once
+there is a query.
+
+```tsx
+import { Search } from '@oxyhq/bloom/search';
+
+<Search
+  value={query}
+  onChangeText={setQuery}
+  onClearText={() => setQuery('')}
+  label="Search people"
+/>
+```
+
+## Which prop decides what
+
+| prop           | decides                                                    |
+| -------------- | ----------------------------------------------------------- |
+| `value`        | the query — the field is controlled                          |
+| `onChangeText` | typing                                                       |
+| `onClearText`  | the clear button's press                                     |
+| `label`        | the accessible name **and** the placeholder; defaults to `Search` |
+
+Everything else passes through to the underlying text input.
+
+## `onClearText` reports; it does not clear
+
+The field is controlled, so clearing itself would fight the caller's state and
+leave the list filtered by a query the field no longer shows. Handle it:
+
+```tsx
+onClearText={() => { setQuery(''); refetch(); }}
+```
+
+## The clear button is conditional on purpose
+
+It appears only when `value` is non-empty. A clear button on an empty field is
+a dead target that looks live, and a missing one on a full field strands the
+user with no way back to the unfiltered list except selecting and deleting.
+
+## Searching as you type, or on submit
+
+`Search` sets `returnKeyType="search"` but does not decide when the search
+runs. Both are legitimate:
+
+- **As you type** — cheap, local filtering. Debounce anything that leaves the
+  device.
+- **On submit** — expensive or paginated search. Say so, by leaving the results
+  alone until the key is pressed rather than showing stale ones.
+
+What is not legitimate is issuing a request per keystroke to a server. That is
+the same failure as a [`Slider`](/docs/bloom/main/slider) that saves in
+`onValueChange`.
+
+## Search or Combobox
+
+- **Search** — filters something already on the page.
+- **[Combobox](/docs/bloom/main/combobox)** — picks a value into a form, and
+  the picked value stays.

package/docs/segmented-control.mdx

@@ -0,0 +1,76 @@
+---
+title: SegmentedControl
+description: Two controls that look identical and announce differently — `type` is the decision.
+order: 25
+---
+
+# SegmentedControl
+
+A row of segments with a sliding indicator. Two to four options, all visible at
+once, one selected.
+
+```tsx
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+  SegmentedControlItemText,
+} from '@oxyhq/bloom/segmented-control';
+
+<SegmentedControl label="Appearance" type="radio" value={mode} onChange={setMode}>
+  <SegmentedControlItem value="light">
+    <SegmentedControlItemText>Light</SegmentedControlItemText>
+  </SegmentedControlItem>
+  <SegmentedControlItem value="dark">
+    <SegmentedControlItemText>Dark</SegmentedControlItemText>
+  </SegmentedControlItem>
+  <SegmentedControlItem value="system">
+    <SegmentedControlItemText>System</SegmentedControlItemText>
+  </SegmentedControlItem>
+</SegmentedControl>
+```
+
+## `type` is an accessibility decision wearing visual clothes
+
+| `type`  | means                                          | announces as              |
+| ------- | ---------------------------------------------- | ------------------------- |
+| `radio` | the segments **pick a value** — a setting       | radio group / radio       |
+| `tabs`  | the segments **switch the panel below**         | tab list / tab            |
+
+The two render identically. That is exactly why the wrong one is dangerous:
+there is nothing on screen to notice, and it is wrong in every screen reader.
+
+Ask what happens when the user picks: if something is now *set*, it is `radio`;
+if the same subject is now shown a different way, it is `tabs`.
+
+## The state spelling follows the role
+
+ARIA gives a `tab` a **selected** state and a `radio` a **checked** one, so a
+single spelling would be invalid in one of the two modes. `SegmentedControl`
+emits `aria-selected` for tabs and `aria-checked` for radios, and neither uses
+`accessibilityState` — react-native-web drops that entirely, so a control
+relying on it would announce no state at all on web.
+
+## `label` is required
+
+It names the group. "Light / Dark / System" without a group name announces as
+three unrelated radios; with `label="Appearance"` it announces as a choice
+about appearance.
+
+## Which prop decides what
+
+| prop       | decides                                        |
+| ---------- | ---------------------------------------------- |
+| `label`    | the accessible name of the whole group          |
+| `type`     | radio group vs tab list (see above)             |
+| `value`    | the selected segment — fully controlled         |
+| `onChange` | receives the pressed segment's `value`          |
+| `size`     | `small` (32px) for a toolbar, `large` (40px)    |
+
+`SegmentedControlItemText` takes no `value` — it reads whether its segment is
+active from context. Passing one is a type error.
+
+## When to reach for something else
+
+- More than about four options, or long labels: a [`Select`](/docs/bloom/main/select).
+- A view of the same subject with real panels underneath: [`Tabs`](/docs/bloom/main/tabs).
+- A single on/off: [`Switch`](/docs/bloom/main/switch).

package/docs/select.mdx

@@ -0,0 +1,93 @@
+---
+title: Select
+description: A single-choice picker — trigger, value, grouped options.
+order: 15
+---
+
+# Select
+
+A single-choice picker. A bottom sheet on native, an anchored dropdown on web. Controlled or uncontrolled.
+
+`Select` owns the value, `SelectTrigger` opens it, `SelectContent` renders the choices from an `items` array, and `SelectItem` is one row.
+
+## Basic
+
+```tsx
+import {
+  Select,
+  SelectContent,
+  SelectIcon,
+  SelectItem,
+  SelectItemIndicator,
+  SelectItemText,
+  SelectTrigger,
+  SelectValue,
+} from '@oxyhq/bloom/select';
+
+const [country, setCountry] = useState('us');
+
+<Select value={country} onValueChange={setCountry}>
+  <SelectTrigger label="Country">
+    <SelectValue placeholder="Pick a country" />
+    <SelectIcon />
+  </SelectTrigger>
+
+  <SelectContent
+    label="Country"
+    items={countries}
+    renderItem={(item) => (
+      <SelectItem value={item.code} label={item.name}>
+        <SelectItemIndicator />
+        <SelectItemText>{item.name}</SelectItemText>
+      </SelectItem>
+    )}
+  />
+</Select>
+```
+
+`SelectContent` takes the whole `items` array rather than children, so the native fork can hand it to a `FlatList` and the web fork can measure and scroll it. `renderItem` receives `(item, index, selectedValue)`.
+
+`SelectTrigger` renders a pressable around its children, or hands the open handler to your own control with `asChild` — the same escape hatch every anchored Bloom family offers:
+
+```tsx
+<SelectTrigger asChild label="Country">
+  <MyField>
+    <SelectValue placeholder="Pick a country" />
+    <SelectIcon />
+  </MyField>
+</SelectTrigger>
+```
+
+It used to take a render prop instead, which handed its child a `state` object whose `pressed` was a hardcoded `false` and whose `hovered` the native fork never computed. Press and hover styling on a select trigger was therefore dead while the API read as though it worked. Bring your own control through `asChild` and its own states are real.
+
+## Groups and labels
+
+```tsx
+<SelectGroup>
+  <SelectLabel>Europe</SelectLabel>
+  <SelectItem value="es" label="Spain">…</SelectItem>
+  <SelectItem value="fr" label="France">…</SelectItem>
+</SelectGroup>
+```
+
+`SelectGroup` renders `role="group"` so a screen reader announces the run as one; `SelectLabel` is its heading. Return them from `renderItem` on the first row of each run — `SelectContent`'s list stays flat.
+
+## Long lists
+
+The web dropdown grows to `maxHeight` (default 208, shadcn's `max-h-52`) and then scrolls. When it does, `SelectScrollUpButton` and `SelectScrollDownButton` appear at whichever end still has something to show, and disappear at the ends — a scroll affordance that is always visible tells the user a list scrolls when it does not.
+
+`SelectContent` renders both, so you get them by default. They are exported for a caller composing their own content, and on NATIVE they render nothing at all: the sheet's list already scrolls under the finger, and a chevron there is a target with no pointer to hit it.
+
+## Selection state
+
+Both forks render each option as `role="radio"` with `aria-checked` — the only spelling react-native-web reads, and one React Native folds back into `accessibilityState`. `SelectItemIndicator` draws the mark: the shared `RadioIndicator` on native, a check on web.
+
+`SelectSeparator` draws a rule between runs.
+
+## Why a row is not `Item`
+
+Every menu row in Bloom is an `Item`. A select row is not, and the reason is its layout.
+
+The web option reserves a 30px indicator gutter and paints the indicator into it ABSOLUTELY, so the label's left edge does not move between a selected row and an unselected one; `Item` has an in-flow leading slot and no absolute one. On top of that, `Item` couples `selected` — which select needs purely to emit `aria-checked` — to a selected BACKGROUND, and the web select deliberately paints none, because the check mark is its selection signal.
+
+Composing would mean flattening one of those two, and both are visible: the first as a label that jumps sideways on selection, the second as a highlighted row where there was none. So select keeps its own row, and `radio-indicator` stays the one indicator both it and `Radio` draw.

package/docs/settings-list.mdx

@@ -0,0 +1,186 @@
+---
+title: SettingsList
+description: iOS-style grouped settings list — items, groups, dividers.
+order: 18
+---
+
+# SettingsList
+
+iOS-style grouped settings list. Items, groups (with optional headers and footers), and dividers. Built for the dense, list-heavy screens common in account / preferences UIs.
+
+## Basic
+
+```tsx
+import {
+  SettingsListGroup,
+  SettingsListItem,
+  SettingsListDivider,
+} from '@oxyhq/bloom/settings-list';
+
+<SettingsListGroup title="General">
+  <SettingsListItem
+    icon={<PersonIcon />}
+    title="Account"
+    value="ada@oxy.so"
+    onPress={() => navigate('Account')}
+  />
+  <SettingsListDivider />
+  <SettingsListItem
+    icon={<GlobeIcon />}
+    title="Language"
+    value="English"
+    onPress={() => navigate('Language')}
+  />
+</SettingsListGroup>
+```
+
+The group renders a rounded card on iOS-style platforms and on web. The first item rounds top corners, the last item rounds bottom corners.
+
+## With description
+
+```tsx
+<SettingsListItem
+  icon={<ShieldIcon />}
+  title="Two-factor authentication"
+  description="Add a second sign-in step with an authenticator app."
+  value="On"
+  onPress={() => navigate('TwoFactor')}
+/>
+```
+
+`description` is multi-line and styled in muted text under the title.
+
+## Toggle row
+
+```tsx
+<SettingsListItem
+  icon={<MoonIcon />}
+  title="Dark mode"
+  rightElement={<Switch value={darkMode} onValueChange={setDarkMode} />}
+/>
+```
+
+When `rightElement` is set, the chevron is hidden automatically (you can override with `showChevron`).
+
+## Destructive
+
+```tsx
+<SettingsListGroup title="Danger zone">
+  <SettingsListItem
+    icon={<TrashIcon />}
+    title="Delete account"
+    destructive
+    onPress={confirmDelete}
+  />
+</SettingsListGroup>
+```
+
+`destructive` switches the title to the negative color and uses the destructive icon tint.
+
+## Disabled
+
+```tsx
+<SettingsListItem
+  icon={<KeyIcon />}
+  title="Reset password"
+  description="Coming soon"
+  disabled
+/>
+```
+
+## Footer / header text
+
+```tsx
+<SettingsListGroup
+  title="Notifications"
+  footer="Push notifications require an enabled device permission."
+>
+  <SettingsListItem title="Marketing emails" rightElement={<Switch value={mktg} onValueChange={setMktg} />} />
+  <SettingsListDivider />
+  <SettingsListItem title="Product updates" rightElement={<Switch value={prod} onValueChange={setProd} />} />
+</SettingsListGroup>
+```
+
+`title` is the group header (uppercase muted label on iOS-style platforms); `footer` is a soft explanatory line under the card.
+
+## Components
+
+### `SettingsListGroup`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title?` | `string` | Section header. |
+| `footer?` | `string` | Section footer. |
+| `children` | `React.ReactNode` | `Item`, `Divider`. |
+| `style?` | `StyleProp<ViewStyle>` | Override group container style. |
+
+### `SettingsListItem`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon?` | `React.ReactNode` | Leading icon. |
+| `title` | `string` | Primary label. |
+| `description?` | `string` | Multi-line secondary text. |
+| `value?` | `string` | Right-side value string. |
+| `rightElement?` | `React.ReactNode` | Replaces value / chevron with a custom node. |
+| `showChevron?` | `boolean` | Defaults to `true` when `onPress` is set. |
+| `destructive?` | `boolean` | Negative palette for title + icon. |
+| `onPress?` | `() => void` | Tap handler. |
+| `disabled?` | `boolean` | |
+| `accessibilityLabel?` | `string` | Override the derived label. |
+| `accessibilityHint?` | `string` | |
+| `accessibilityRole?` | `'button' \| 'link' \| 'none'` | Defaults to `'button'` when pressable. |
+| `leftInset?` | `number` | Left inset to align text when no icon is set. |
+
+### `SettingsListDivider`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `inset?` | `number` | Left inset to align with text (default `52`). |
+
+## Recipes
+
+### Mixed read / link rows
+
+```tsx
+<SettingsListGroup title="About">
+  <SettingsListItem title="Version" value="1.4.2" />
+  <SettingsListDivider />
+  <SettingsListItem title="Build" value="231" />
+  <SettingsListDivider />
+  <SettingsListItem title="Terms" onPress={() => navigate('Terms')} />
+  <SettingsListDivider />
+  <SettingsListItem title="Privacy" onPress={() => navigate('Privacy')} />
+</SettingsListGroup>
+```
+
+### Sign-out section
+
+```tsx
+<SettingsListGroup>
+  <SettingsListItem
+    title="Sign out"
+    onPress={signOut}
+    accessibilityRole="button"
+  />
+</SettingsListGroup>
+```
+
+### Account switcher
+
+```tsx
+<SettingsListGroup title="Accounts">
+  {accounts.map((a, i) => (
+    <Fragment key={a.id}>
+      {i > 0 ? <SettingsListDivider /> : null}
+      <SettingsListItem
+        icon={<Avatar uri={a.avatarUrl} size={28} />}
+        title={a.name}
+        description={a.handle}
+        rightElement={a.id === activeId ? <CheckIcon /> : null}
+        onPress={() => switchTo(a.id)}
+      />
+    </Fragment>
+  ))}
+</SettingsListGroup>
+```

package/docs/skeleton.mdx

@@ -0,0 +1,66 @@
+---
+title: Skeleton
+description: Shimmering placeholders shaped like the content that is coming.
+order: 32
+---
+
+# Skeleton
+
+Placeholders for content that has not arrived. `Skeleton` is a namespace of
+primitives you compose into the shape of the real thing.
+
+```tsx
+import * as Skeleton from '@oxyhq/bloom/skeleton';
+
+<Skeleton.Row style={{ gap: 12 }}>
+  <Skeleton.Circle size={40} />
+  <Skeleton.Col style={{ gap: 6 }}>
+    <Skeleton.Text style={{ width: 140 }} />
+    <Skeleton.Text style={{ width: 90 }} />
+  </Skeleton.Col>
+</Skeleton.Row>
+```
+
+## The parts
+
+| part               | takes                | for                                |
+| ------------------ | -------------------- | ---------------------------------- |
+| `Skeleton.Text`    | `style` (`width`, `lineHeight`) | a line of text          |
+| `Skeleton.Circle`  | `size`               | an avatar                          |
+| `Skeleton.Pill`    | `size`               | a chip, a badge, a button          |
+| `Skeleton.Box`     | `width` / `height`   | anything rectangular               |
+| `Skeleton.Row` / `Skeleton.Col` | `style`  | layout, so a placeholder needs no extra views |
+
+`Skeleton.Text` reads its width and line height out of `style` rather than
+taking props for them, so the same style object you would give the real `Text`
+produces a placeholder the right size — which is the point.
+
+It is a namespace rather than flat exports because the names are generic
+(`Text`, `Box`, `Row`) and would collide with everything. Each ships as a
+subpath, so `import * as` costs no tree-shaking.
+
+## Shape it like the content, not like a grey box
+
+The point of a skeleton is that nothing moves when the data arrives. A
+placeholder wider than the real text, or one line where there will be two,
+produces a jump that is more distracting than a spinner would have been. Match
+the line count and the rough widths; do not match them exactly, because
+identical widths on every row read as a pattern rather than as text.
+
+## Skeleton or Loading
+
+- **Skeleton** — you know the shape of what is coming and it fills the region.
+  A feed, a profile header, a table.
+- **[Loading](/docs/bloom/main/loading)** — you do not know the shape, or the
+  wait is short, or it is a small inline region. Also the right choice for an
+  action in progress, where a skeleton would imply content is arriving.
+
+Do not show a skeleton for longer than a couple of seconds. Past that it stops
+reading as "almost there" and starts reading as broken; show progress or an
+explanation instead.
+
+## Accessibility
+
+A skeleton is decorative — it must not be announced as text. Mark the region as
+busy on the container that will hold the content, so a screen reader user is
+told that something is loading rather than read a grid of empty boxes.

package/docs/slider.mdx

@@ -0,0 +1,73 @@
+---
+title: Slider
+description: A value on a continuum — and the difference between `onValueChange` and `onSlidingComplete`.
+order: 35
+---
+
+# Slider
+
+For a value where the *approximate* position matters more than the exact number:
+volume, brightness, a zoom level, a price ceiling.
+
+```tsx
+import { Slider } from '@oxyhq/bloom/slider';
+
+<Slider
+  value={volume}
+  onValueChange={setVolume}
+  onSlidingComplete={persistVolume}
+  min={0}
+  max={100}
+  step={1}
+  accessibilityLabel="Volume"
+/>
+```
+
+## Which prop decides what
+
+| prop                | decides                                                  |
+| ------------------- | --------------------------------------------------------- |
+| `value`             | the position — the slider is fully controlled              |
+| `onValueChange`     | fires **continuously** while dragging                      |
+| `onSlidingComplete` | fires **once**, when the finger lifts                      |
+| `min` / `max`       | the range                                                  |
+| `step`              | the granularity; omit for continuous                       |
+| `disabled`          | dims and ignores gestures                                  |
+
+## The two callbacks are the whole API
+
+`onValueChange` fires on every frame of a drag. Put the *preview* there — the
+number under the thumb, the live volume — and nothing else.
+
+`onSlidingComplete` fires once. Put anything expensive or persistent there: a
+network request, a write to storage, a re-render of a large list. A `PATCH` in
+`onValueChange` sends one request per frame, which is the classic way a slider
+takes a settings screen offline.
+
+```tsx
+onValueChange={setLocalValue}          // cheap, immediate
+onSlidingComplete={(v) => save(v)}     // once, at the end
+```
+
+## Give it a label and a unit
+
+A slider announces a number with no meaning attached. `accessibilityLabel`
+names it; if the number is not self-evident (a price, a duration), show the
+formatted value beside the track so it is readable without dragging.
+
+The label is not optional in practice, only in the type. ARIA computes no name
+from a `slider`'s contents — a track and a knob render no text — so a caption
+beside it names nothing, and the `aria-value*` props say how far along it is
+and never what it is. Omitting it warns once in development, dev-only and never
+throwing; an empty or whitespace-only string counts as missing, because
+`aria-label=""` is not a name.
+
+## When a slider is the wrong control
+
+- **The exact value matters.** Use a number input; a slider cannot be typed
+  into and is hard to land on a specific value.
+- **There are fewer than about five positions.** Use a
+  [`SegmentedControl`](/docs/bloom/main/segmented-control) or a
+  [`Radio`](/docs/bloom/main/radio) group — they name the options.
+- **The range is huge and non-linear.** A slider over 1–1,000,000 gives most of
+  its travel to values nobody wants.

package/docs/stat-bar.mdx

@@ -0,0 +1,59 @@
+---
+title: StatBar
+description: A labelled bar in two shapes — progress toward a maximum, or a split between two sides.
+order: 63
+---
+
+# StatBar
+
+One bar, two meanings.
+
+```tsx
+import { StatBar } from '@oxyhq/bloom/stat-bar';
+
+<StatBar label="Storage" value={62} max={100} minLabel="0 GB" maxLabel="100 GB" />
+
+<StatBar variant="split" label="Votes" percent={64} leftValue="Yes" rightValue="No" />
+```
+
+## Which prop decides what
+
+| prop                      | decides                                            |
+| ------------------------- | --------------------------------------------------- |
+| `variant`                 | `progress` (default) or `split`                     |
+| `value` / `max`           | progress: how far along                             |
+| `percent`                 | split: where the divide sits                        |
+| `leftValue` / `rightValue`| split: what each side is                            |
+| `minLabel` / `maxLabel`   | progress: the ends of the range                     |
+| `label`                   | what the bar is about — required                    |
+| `icon`                    | a glyph beside the label                            |
+| `fillColor` / `trackColor`| the colours                                         |
+
+The two variants are one component because they are the same object visually,
+and one prop rather than two components because a row often switches between
+them for the same subject.
+
+## `progress` and `split` are different claims
+
+`progress` says *how much of a maximum has been used* — there is a ceiling, and
+approaching it means something. `split` says *how a whole divides between two
+named sides* — there is no ceiling and neither side is "full".
+
+Using `progress` for a split reads as the left side filling up toward a limit,
+which is a claim you did not intend to make.
+
+## `minLabel` / `maxLabel` on a progress bar
+
+A bar with no scale is a proportion with no units. "62 of 100" is a different
+statement from "62%", and only one of them tells the user whether to act.
+
+## `percent` is a number, the values are strings
+
+`leftValue` and `rightValue` are strings because they are labels, not the
+maths: "Yes" / "No", "1,204" / "677", "You" / "Everyone else". The bar's
+geometry comes from `percent` alone.
+
+## `label` is required
+
+A bar in a stack of stats with no label is a colour. It is also the only thing
+a screen reader gets, since the bar itself conveys nothing.

package/docs/stat-widgets.mdx

@@ -0,0 +1,33 @@
+---
+title: Choosing a stat widget
+description: Four families, four different questions about a number.
+order: 61
+---
+
+# Choosing a stat widget
+
+Bloom has four small data-display families. They are separate because each
+answers a different question, and picking the wrong one makes a number harder
+to read rather than easier.
+
+| family                                                | answers                                  |
+| ----------------------------------------------------- | ---------------------------------------- |
+| [`CompositionBar`](/docs/bloom/main/composition-bar)  | what is this total **made of**?           |
+| [`StatBar`](/docs/bloom/main/stat-bar)                | how far along, or how is it split in two? |
+| [`DotGridMeter`](/docs/bloom/main/dot-grid-meter)     | how many out of a countable total?        |
+| [`ActivityHeatmap`](/docs/bloom/main/activity-heatmap) | when did this happen, over time?          |
+
+Two rules apply to all four.
+
+## Colours are the app's, not the theme's
+
+Each takes explicit colours, because the categories belong to the product — a
+token's brand colour is not a Bloom role. Whatever you pass, check it against
+the surface it sits on and in both modes: a colour chosen on a light card is
+routinely invisible in dark mode.
+
+## A chart still needs the number in text
+
+None of these announces anything useful on its own. Whatever the widget shows,
+the value should also be readable as text nearby — otherwise the information is
+available only to people who can see and interpret the shape.