@oxy.so/bloom 2.10.0 → 2.12.0

package/docs/button.mdx

@@ -40,6 +40,33 @@ import { Button } from '@oxy.so/bloom';
 | `text` | Borderless `primary` label on a compact 4/8 padding with a hover wash (Bloom-only). |
 | `link` | No container at all — label only, `accent-600` (`linkTone="secondary"`: secondary text), underline (offset 3) on hover, `accent-800` while held. |
 
+### Which variant for which job
+
+The variants overlap, and five families answered the overlap with their own
+component rather than with this list. So, explicitly:
+
+| You want | Use |
+|---|---|
+| The action of the screen | `primary` |
+| A second action beside it | `secondary` |
+| A THIRD, still accent-coloured, action | `ghost` |
+| A destructive action | `destructive` |
+| A neutral ⋯ / × / clear / toggle GLYPH | **`GlyphButton`** (below) |
+| A neutral icon button WITH a surface | `icon` |
+| A transparent LABELLED button | `text` |
+| An action inside running copy | `link` + `linkTone` + `underline` |
+
+**`ghost` is not the transparent one.** It paints an accent WASH at rest
+(`accent-100`, dark `accent-900`) with an accent label, and that is the whole
+point of it: it is the low-emphasis member of the ACCENT family. A neutral ⋯ or
+× in it lands tinted, and a destructive action in it draws a RED label on a BLUE
+fill — which is what `track-list`'s selection bar shipped before this was
+written down.
+
+**The neutral transparent icon button is `GlyphButton`**, not a `Button`
+variant: it takes an arbitrary diameter, where `Button iconOnly` is pinned to
+the four heights in the size table.
+
 The accent and neutral ramps are rebuilt around the theme colours in OKLCH (`button/shared.ts`), since Bloom presets carry one `primary` rather than a Tailwind ramp. There is NO press scale — a press is the active paint alone — and disabled buttons take their own paint instead of an opacity dip (`icon` excepted).
 
 On web the state colours arrive as `--bloom-btn-*` custom properties and are declared only in the adopted stylesheet — an inline `background-color` would silence the `:hover` rule. The gradient variants cross-fade their hover gradient in through `::before`, because `background-image` does not transition. On native the gradient is a `react-native-svg` layer; every gradient stop is an opaque composite, since react-native-svg drops alpha in `stopColor`.
@@ -101,7 +128,8 @@ Use Remix icons (`RiAddLine`, `RiArrowRightLine`, `RiDeleteBinLine`…). `iconOn
 
 ## IconButton, LinkButton, CloseButton
 
-Three companions to `Button`, exported from the same family:
+Three more companions to `Button` (a fourth, `GlyphButton`, has its own section
+below), exported from the same family:
 
 ```tsx
 <IconButton icon={RiMore2Line} accessibilityLabel="More" />          // 36, glyph 20
@@ -118,6 +146,99 @@ Three companions to `Button`, exported from the same family:
 - `href` (any `Button`) renders a real `<a href>` on web and drops the `href` while disabled; on native a press opens the URL unless `onPress` is set.
 - `CloseButton` is a round `background/tertiary` disc (16 / 20 / 24 / 32) with a two-stroke X drawn per size in its own viewBox, so the stroke is a literal pixel value (1.6 / 2 / 2 / 2.5); the glyph turns `text/primary` on hover (held press on native). The control draws no text, so `accessibilityLabel` is required.
 
+## Inline text actions
+
+```tsx
+// The underline IS the affordance, at the reading colour: a "Clear all",
+// a "Show more", a price row's label, a listing's "128 reviews".
+<Button variant="link" linkTone="text" underline="rest" textVariant="body-semibold">
+  Clear all
+</Button>
+
+// The underline as the pointer cue, in the accent (the `link` default).
+<Button variant="link">Learn more</Button>
+```
+
+| Prop | Values | Default |
+|---|---|---|
+| `underline` | `rest` · `hover` · `none` | `hover` for `link`, `none` otherwise |
+| `linkTone` | `primary` (accent-600) · `secondary` (neutral-500) · `text` (the reading colour) | `primary` |
+| `textVariant` | any `TYPE_SCALE` step | the size's own step |
+
+`linkTone="text"` is `colors.text` at rest, `colors.textSecondary` under a
+pointer or a press, `colors.textTertiary` disabled — the tone for an action that
+sits inside a sentence and must not read as the accent. It is the only tone
+whose HOVER changes the label colour; on web that arrives as
+`--bloom-btn-fg-hover` and the hover rule falls back to the rest colour for
+every other variant.
+
+`underline="hover"` is web-only by nature: native dispatches no hover, so the
+underline never appears there. Reach for `rest` when the underline has to be
+visible on a phone.
+
+`textVariant` replaces the four TYPE fields the size picked (size, line height,
+weight, tracking) and nothing else — the height, padding, gap and icon size stay
+the size's. Use it rather than `textStyle`: a `lineHeight` NUMBER in a style
+object is CSS's unitless multiplier on web, so a ramp step passed that way
+renders at twenty times its size.
+
+`numberOfLines={1}` truncates a label with an ellipsis instead of clipping it
+(`.bloom-btn` is `white-space: nowrap; overflow: hidden`, so a long label was
+cut with nothing to say so). Native honours any count; web honours `1`.
+
+`accessibilityRole` overrides the announced role — `link` with no `href`, for a
+control that navigates through the app's own router. Prefer `href`, which
+renders a real anchor and is the only spelling middle-click and copy-link
+understand.
+
+## GlyphButton
+
+The round glyph-only control at an ARBITRARY size — the neutral, transparent
+⋯ / × / shuffle / clear affordance.
+
+```tsx
+import { GlyphButton } from '@oxy.so/bloom/button';
+
+<GlyphButton icon={RiMoreFill} accessibilityLabel="More options" onPress={open} />
+<GlyphButton size={40} icon={RiShuffleLine} accessibilityLabel="Shuffle"
+             pressed={shuffle} onPress={() => setShuffle(!shuffle)} />
+```
+
+|  | off | on (`pressed`) |
+|---|---|---|
+| rest | `color` — `textSecondary` | `activeColor` — the accent |
+| hover / press | `hoverColor` — `text` | `activeHoverColor` — `activeColor` |
+| fill | `fill` — none | the same |
+| fill, hover / press | `hoverFill` — the neutral wash (neutral-100, dark 800) | the same |
+
+All four corners are spellable because the on-state and the hover state are
+independent: a player's lit shuffle still brightens under the cursor.
+
+- **`size`** is the diameter (default 36); the glyph is **0.6 × the box**
+  (`GLYPH_BUTTON_GLYPH_RATIO`), and **`glyphSize`** overrides it. Across the five
+  family-local copies this replaced the ratio ran 0.50 to 0.75; 0.6 is the middle
+  of that range, and every call site that measured differently passes its own.
+- **`pressed`** makes it a TOGGLE and emits `aria-pressed` AND
+  `accessibilityState.selected` — react-native-web drops `accessibilityState`,
+  React Native has no `aria-pressed`. Leave it undefined for a plain button:
+  `aria-pressed="false"` on one announces a state nobody set.
+- **`accessibilityLabel` is required** — the control draws no text, so nothing
+  else can name it.
+- **`ring`** is the focus ring's colour (default the accent). Pass a light one on
+  a surface Bloom does not own — artwork, a player bar — or the ring disappears
+  exactly where a keyboard user needs it.
+- **`disabled`** blocks the press, sets `aria-disabled` and
+  `accessibilityState.disabled`, and dims the control to `disabledOpacity`
+  (0.5).
+- **`children`** replaces `icon` with a node you paint yourself; as a FUNCTION it
+  is handed the resolved foreground, so a text glyph still follows hover and the
+  toggle. **`grow`** turns the box into a minimum width for exactly that case.
+- **`decoration`** is an extra absolutely-positioned layer over the box — the
+  media player's 4px active dot. The family owns its geometry.
+
+Colour change only, 150ms, no scale. Focus is a 2px ring at a 2px offset, on
+`:focus-visible` so a mouse press leaves none behind.
+
 ## Disabled
 
 ```tsx
@@ -135,11 +256,15 @@ Three companions to `Button`, exported from the same family:
 | `disabled?` | `boolean` | `false` | Blocks presses, disabled paint. |
 | `variant?` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'outline' \| 'inverse' \| 'icon' \| 'text' \| 'link'` | `'primary'` | Visual style. |
 | `size?` | `'xs' \| 'small' \| 'medium' \| 'large'` (+ `sm \| md \| lg \| icon`) | `'medium'` | Height, radius, padding, type and icon size. |
-| `leadingIcon?` | `ComponentType<{ width, height, fill }>` | — | Icon component before the label, sized by the button. |
-| `trailingIcon?` | `ComponentType<{ width, height, fill }>` | — | Icon component after the label. |
+| `leadingIcon?` | `BloomIconComponent` | — | Icon component before the label, sized by the button. |
+| `trailingIcon?` | `BloomIconComponent` | — | Icon component after the label. |
 | `iconOnly?` | `boolean` | `false` | Square icon-only button. |
 | `icon?` | `React.ReactNode \| ComponentType` | — | Icon component (sized) or pre-rendered node next to the label. |
-| `linkTone?` | `'primary' \| 'secondary'` | `'primary'` | Colour of the `link` variant. |
+| `linkTone?` | `'primary' \| 'secondary' \| 'text'` | `'primary'` | Colour of the `link` variant; `text` is the reading colour. |
+| `underline?` | `'rest' \| 'hover' \| 'none'` | `hover` for `link`, else `none` | When the label carries its underline. |
+| `textVariant?` | `TypeScaleVariant` | the size's step | Override the label's type-ramp step. |
+| `numberOfLines?` | `number` | — | Truncate the label. Web honours `1`. |
+| `accessibilityRole?` | `'button' \| 'link'` | derived from `href` | Override the announced role. |
 | `href?` | `string` | — | Renders an anchor on web; opens the URL on native. `target` / `rel` pass through on web. |
 | `iconPosition?` | `'left' \| 'right'` | `'left'` | Which side of the label `icon` goes. |
 | `loading?` | `boolean` | `false` | Show centered spinner, block presses. |

package/docs/call-ui.mdx

@@ -0,0 +1,297 @@
+---
+title: Call UI
+description: Voice and video calls — the stage, the controls, the incoming banner and screen, the group grid and the call log. Presentational only.
+order: 64
+---
+
+# Call UI
+
+```tsx
+import {
+  CallScreen,
+  CallControls,
+  CallControlButton,
+  CallMinimisedPill,
+  IncomingCallBanner,
+  IncomingCallScreen,
+  GroupCallGrid,
+  GroupCallTile,
+  GroupCallBar,
+  CallHistoryRow,
+  CallHistoryList,
+} from '@oxy.so/bloom/call-ui';
+```
+
+**Nothing here knows what WebRTC is.** A video frame arrives as a `ReactNode`
+slot, the elapsed time arrives as the string your app already formatted
+(`"00:42"`), and `speaking` arrives from whatever audio-level meter you run. The
+family draws a call; it does not place one.
+
+## The stage is dark in both modes
+
+A `CallScreen` backs a video frame Bloom does not own. White chrome over an
+unknown frame is the only thing that survives a bright kitchen and a dark
+bedroom in the same call, so the stage stays a deep neutral and the MODE picks
+the depth only — `neutral-900` in light, `neutral-950` in dark. The preset's hue
+still tints both, and the accent still comes from your theme.
+
+The surfaces that sit IN the app — `IncomingCallBanner`, `GroupCallBar`,
+`CallHistoryRow`/`List` — take the ordinary theme surface and flip with the mode
+like every other card in Bloom.
+
+## `CallScreen`
+
+```tsx
+<CallScreen
+  mode="voice"
+  name="Ana Restrepo"
+  subtitle="Mobile"
+  avatar={avatarUrl}
+  status="active"
+  duration="00:42"
+  encryption="End-to-end encrypted"
+  onMinimise={minimise}
+  onOpenChat={openChat}
+  controls={{
+    muted,
+    onMutedChange: setMuted,
+    speaker,
+    onSpeakerChange: setSpeaker,
+    onEndCall: hangUp,
+  }}
+/>
+```
+
+| prop                  | decides                                                                  |
+| --------------------- | ------------------------------------------------------------------------ |
+| `mode`                | `'voice'` (avatar over an accent wash) or `'video'`                       |
+| `status`              | `calling · ringing · connecting · active · reconnecting · onHold · ended` |
+| `duration`            | the elapsed time, PRE-FORMATTED. Only drawn while `active`                |
+| `statusText`          | replaces the status line entirely                                         |
+| `accentColor`         | the hue the voice stage is washed with — derive it from artwork yourself  |
+| `encryption`          | a string beside a padlock, or your own node                               |
+| `remoteVideo`         | fills the stage                                                          |
+| `localVideo`          | the picture-in-picture                                                   |
+| `localVideoCorner`    | `'top-right'` by default; CONTROLLED                                      |
+| `onMoveLocal(corner)` | called with the NEXT corner when the PiP is pressed                       |
+| `controls`            | `CallControlsProps` — the bar at the foot                                 |
+| `controlsSlot`        | replaces the bar entirely                                                 |
+| `minimised`           | collapses the whole screen to `CallMinimisedPill`                         |
+
+### The status line has a precedence, and it is a function
+
+`resolveCallStatusLine({ status, duration, statusText, labels })` is exported,
+and `CallScreen` calls it rather than branching in JSX:
+
+1. `statusText` — you said exactly what to show
+2. `ended` — **never** a timer; a frozen last tick reads as a live call
+3. `reconnecting` — the timer keeps counting underneath, but saying so while
+   the media is down is a lie the user can see
+4. `active` — `duration`, or "Connected" until the first tick arrives
+5. anything else — that status's own label
+
+Every label is overridable through `labels` for translation.
+
+### The PiP moves by PRESS
+
+A drag has no keyboard and no screen-reader equivalent, so pressing the local
+frame cycles the corners clockwise and reports the new one through
+`onMoveLocal`. The whole 96×140 frame is the target. If you want a real drag
+gesture, wrap the screen and report the corner it landed in — `localVideoCorner`
+is a controlled prop, so both paths drive the same state.
+
+## `CallControls`
+
+**A control appears when you hand it a HANDLER.** `onMutedChange` draws the mic,
+`onVideoChange` the camera, `onFlipCamera` the flip, `onEndCall` the red button.
+There is no `mode` prop and no `show*` booleans, because a list of what to show
+kept in sync with a list of what to do is two sources of truth for one row — and
+the failure is a button that does nothing.
+
+```tsx
+<CallControls
+  muted={muted}
+  onMutedChange={setMuted}
+  videoOn={cameraOn}
+  onVideoChange={setCameraOn}
+  onFlipCamera={flip}
+  onScreenShareChange={setSharing}
+  onEndCall={hangUp}
+  size="large"
+  showLabels
+/>
+```
+
+`controls` reorders and narrows the set; a key in it with no handler is still
+skipped, so it can never put a dead button back. The end button is last, always.
+
+| size     | button | glyph |
+| -------- | ------ | ----- |
+| `small`  | 40     | 20    |
+| `medium` | 48     | 22    |
+| `large`  | 56     | 26    |
+
+### Toggle accessibility
+
+`CallControlButton`'s `active` prop decides the accessibility SHAPE. Passing it
+makes the button a toggle: it emits `aria-pressed` for web **and**
+`accessibilityState.selected` for native, because react-native-web reads only
+the first and React Native has no concept of the second. Leaving `active`
+undefined makes a plain action button — "flip camera" is not a state, and a
+button reporting `aria-pressed="false"` forever announces one it does not have.
+
+The name flips with the state and says what pressing DOES: "Mute" → "Unmute".
+
+## `CallMinimisedPill`
+
+```tsx
+<CallMinimisedPill
+  name="Ana Restrepo"
+  duration="00:42"
+  muted
+  onMutedChange={setMuted}
+  onExpand={reopen}
+  onEndCall={hangUp}
+  style={{ position: 'absolute', left: x, top: y }}
+/>
+```
+
+The timer is in tabular figures, so a running clock does not jitter sideways.
+
+**It does not drag itself.** Your app knows the safe areas, the keyboard and
+what is underneath; a component that moves itself inside a layout it cannot see
+ends up under a tab bar. Pass `style` with the offsets — an animated one is
+fine.
+
+`<CallScreen minimised />` renders exactly this, reading `name`, `duration`,
+`mode`, `accentColor` and `controls.muted` from the screen's own props, with
+`onMinimise` becoming the pill's EXPAND press.
+
+## `IncomingCallBanner` and `IncomingCallScreen`
+
+The banner is a card for a call arriving while the app is open. Its two round
+buttons are SIBLINGS of the banner's own press target, never nested inside it: a
+button inside a button is one hit area on web and two announcements on native.
+
+```tsx
+<IncomingCallBanner
+  name="Marcel Dubé"
+  mode="video"            // "Incoming video call"
+  status="online"
+  onAccept={answer}
+  onDecline={decline}
+  onPress={openFullScreen}
+/>
+```
+
+The screen is the full-bleed version, with two answer modes:
+
+```tsx
+<IncomingCallScreen
+  name="Lucía Ferrer"
+  answerMode="slide"      // or "buttons" (the default)
+  onAccept={answer}
+  onDecline={decline}
+  onMessage={reply}
+  onRemind={snooze}
+/>
+```
+
+**The slide track answers a PRESS as well as a drag**, and that is not a
+convenience: the press is the same control's accessible path, so the knob
+carries `role="button"` and the accept name whichever way it is used. A release
+past 60% of the track answers (`SLIDE_ANSWER_THRESHOLD`); an unmeasured track
+never does, because `dx >= 0` is true for every stray touch.
+
+The chevrons behind the knob breathe on a 1.4s loop and stand still under
+reduced motion — the hint is the arrows, not the movement.
+
+## `GroupCallGrid`
+
+```tsx
+<GroupCallGrid
+  participants={people}          // { id, name, avatar?, video?, muted?, speaking?, presenting? }
+  maxTiles={9}
+  onParticipantPress={focus}
+/>
+```
+
+Columns are `ceil(sqrt(n))` — 2 side by side, 4 a square, 6 as 3×2, 9 as 3×3,
+12 as 4×3. `callGridColumns(n)` and `callGridLayout(count, maxTiles, columns?)`
+are exported and pure, so the arithmetic is testable without rendering.
+
+**Past `maxTiles` the last CELL becomes `+N`**, rather than a cell being added
+beside the grid: a 9-up that quietly becomes a 10-cell 4×3 the moment a tenth
+person joins is the failure that shape exists to stop. With `maxTiles={9}` and
+12 people you get 8 faces and a `+4`.
+
+`layout="spotlight"` draws one big tile over a strip of the rest. The big one is
+`spotlightId`, else whoever is `presenting`, else whoever is `speaking`, else the
+first — `callSpotlightIndex` is exported too.
+
+The grid MEASURES itself unless you pass `width`, and draws nothing until it has
+one: a first paint at zero stacks every tile on top of itself, and on native
+that frame is visible.
+
+### The speaking ring
+
+`GroupCallTile` draws it as an OVERLAY, never as the tile's own border — a
+border that appears changes the content box, so every tile would shift by 3px
+each time somebody started talking. It pulses by opacity on a 900ms loop and
+holds still at full opacity under reduced motion.
+
+## `GroupCallBar`
+
+```tsx
+<GroupCallBar
+  title="Saturday planning"
+  speakingName="Marcel"        // wins over statusText, with a live dot
+  statusText="4 on the call"
+  participants={people}
+  joined={joined}
+  onJoin={join}
+  onLeave={leave}
+  muted={muted}
+  onMutedChange={setMuted}
+  onPress={openCall}
+/>
+```
+
+The speaking line REPLACES the status line rather than sitting beside it: two
+lines in a 56px strip is a strip that scrolls, and "who is talking" is the only
+thing on it that changes second to second. Avatars overlap by 10px and the tail
+becomes a `+N` mark.
+
+## `CallHistoryRow` and `CallHistoryList`
+
+```tsx
+<CallHistoryList
+  sections={[
+    { title: 'Today', items: [{ id: '1', name: 'Ana Restrepo', direction: 'missed', meta: '09:14', count: 2 }] },
+    { title: 'Yesterday', items: [...] },
+  ]}
+  onItemPress={open}
+  onCallBack={ring}
+/>
+```
+
+**Direction is two signals, not one.** The arrow says which way the call went
+(down-left arrived, up-right left) and the COLOUR says whether it connected —
+`missed` and `declined` are drawn in the negative colour. A missed call told
+apart from a received one by hue alone is a distinction one reader in twelve
+cannot make, so the second line names it in words ("Missed · Yesterday, 18:40")
+and the row's accessible name carries it too.
+
+`meta` and every section `title` arrive PRE-FORMATTED. Deciding what
+"yesterday" means needs a locale and a timezone your app has and a component
+does not. An empty section is dropped rather than drawn with a heading and
+nothing under it; `emptyState` covers the case where every section is empty.
+
+## What jest cannot see here
+
+The suite (`src/__tests__/CallUi.test.tsx`) reads the emitted DOM through the
+real react-native-web, so it pins every accessible name, both toggle spellings
+and the grid's geometry. It cannot see whether the stage's scrim actually keeps
+the controls legible over a bright frame, whether the PiP overlaps the top bar
+on a short screen, or whether the speaking ring reads as a ring at all. Those
+are browser and device checks.

package/docs/card.mdx

@@ -104,3 +104,34 @@ because a child deliberately overflows — opts out through `style`:
 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.
+
+## `Card` does not publish a surface
+
+A `ContentPanel` tells its children what they are sitting on — level 1 of the
+ladder in [Styles](/docs/bloom/main/styles), plus the colour it actually painted
+— and a `Card` deliberately does not, even though it paints the same colour. The
+difference is ownership: a panel is a surface Bloom paints and keeps painting,
+while a `Card` is a box a consumer routinely repaints through `style` /
+`className`, and a fill Bloom cannot guarantee is worse than none — every
+`TextField`, `Tabs` rail, hovered row and `SettingsListGroup` inside it would
+then step off a colour that is not there. (`ContentPanel` hits the same wall when
+it IS repainted, and answers it with an explicit `surfaceColor` prop rather than
+a guess.)
+
+So a component that needs to know what is behind it inside a card is still told:
+pass `SettingsListGroup`'s `variant`, or publish the surface yourself for a card
+you know you have not repainted. `SurfaceLevelProvider` ships on the `styles`
+subpath, not the root barrel:
+
+```tsx
+import { SurfaceLevelProvider } from '@oxy.so/bloom/styles';
+
+<Card>
+  <SurfaceLevelProvider level={1} fill={colors.card}>
+    <SettingsListGroup title="Account">…</SettingsListGroup>
+  </SurfaceLevelProvider>
+</Card>
+```
+
+Pass `fill` as well as `level`: the level says how deep the subtree is, the fill
+says what you actually painted, and it is the fill everything inside steps off.

package/docs/chart-cards.mdx

@@ -165,3 +165,14 @@ Series tones follow the `CHART_TONES` order — `chart-2` lime, `chart-6` blue,
 # Building a chart card
 
 The chrome is published for composing your own card: `ChartCardSurface`, `ChartHeader` / `ChartHeadline`, `ChartRangePill` / `ChartRangeSelect` + `useChartRange`, `ChartLegend`, `ChartStatTiles`, `ChartCenterReadout` and `CartesianPlot`. `src/chart-cards/README.md` documents each one and how a card is assembled from them.
+
+## Axis labels and captions are floored on the card
+
+`textSecondary` and `textTertiary` are read off the card's own fill (and the
+stat tiles', which are a second fill they land on) with `quietTextOver` — see
+[Styles → Quiet text](/docs/bloom/main/styles). As ramp stops they measured
+4.38:1 light / 3.78:1 dark for the label and **2.42:1 / 2.29:1** for the axis
+ticks, because `neutral-400` was chosen against the page and a chart card is not
+the page. They now clear 7:1 and 4.5:1 on every preset in both modes; the delta
+chips' labels clear 4.5:1 on their own chips. Gate:
+`surface-level-adoption.test.ts`.