@oxyhq/bloom 1.0.0 → 1.0.2

package/README.md

@@ -76,6 +76,16 @@ On native, wrap the app root in `GestureHandlerRootView` from `react-native-gest
 
 </details>
 
+## Upgrading from 0.x
+
+Bloom follows the clean cut rule, so there are no `@deprecated` aliases and no old name shims anywhere in 1.0.0. If a symbol you import was renamed, nothing re-exports it under the old spelling and the build fails. **[`docs/migrating-to-1.0.mdx`](./docs/migrating-to-1.0.mdx) is the only bridge** — every removed subpath, every rename, every prop change, derived from the published 0.89.0 and 1.0.0 tarballs rather than from commit messages.
+
+That file ships inside the package, so the copy you read is the one that describes the version you installed:
+
+```bash
+$EDITOR node_modules/@oxyhq/bloom/docs/migrating-to-1.0.mdx
+```
+
 ## Getting started
 
 Mount `BloomProvider` once, at the very top of the app. It composes every piece of app wide Bloom state, theme, haptics, image resolution, scroll restoration and tab bar minimise progress, so none of them can end up at the wrong depth.
@@ -144,10 +154,10 @@ Bloom publishes 88 subpath exports. Importing from the subpath rather than the r
 | Group | Exports |
 |---|---|
 | Providers and theme | `provider`, `theme`, `color-presets`, `preset-vars`, `design-tokens`, `tailwind-preset`, `styles`, `hooks` |
-| Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `menu`, `tooltip`, `overlay`, `portal`, `surfaces` |
+| Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `dropdown-menu`, `menubar`, `tooltip`, `overlay`, `portal`, `surfaces` |
 | Actions | `button`, `fab`, `frosted-icon-button`, `pressable-scale`, `subtle-hover` |
-| Forms | `text-field`, `field`, `input-group`, `label`, `select`, `combobox`, `command`, `checkbox`, `switch`, `slider`, `segmented-control`, `search`, `prompt-input` |
-| Layout and lists | `grid`, `list`, `scroll`, `tabs`, `tab-bar`, `settings-list`, `content-panel`, `card`, `accordion`, `divider`, `item` |
+| Forms | `text-field`, `field`, `input-group`, `label`, `select`, `combobox`, `command`, `checkbox`, `radio`, `switch`, `slider`, `segmented-control`, `search`, `prompt-input` |
+| Layout and lists | `grid`, `list`, `scroll`, `tabs`, `tab-bar`, `settings-list`, `content-panel`, `card`, `accordion`, `aspect-ratio`, `divider`, `item` |
 | Identity and media | `avatar`, `avatar-group`, `user-hover-card`, `profile-card`, `image-resolver`, `image-aspect-ratio-cache`, `zoomable-image-gallery`, `media-inset-border`, `progressive-blur`, `fill` |
 | Feedback and data | `toast`, `admonition`, `loading`, `skeleton`, `error-boundary`, `badge`, `chip`, `kbd`, `code`, `link-preview`, `connection-status`, `connection-dots` |
 | Charts and motion | `composition-bar`, `dot-grid-meter`, `stat-bar`, `activity-heatmap`, `motion`, `animated-check`, `icon-circle`, `radio-indicator` |
@@ -157,7 +167,9 @@ Bloom publishes 88 subpath exports. Importing from the subpath rather than the r
 
 ## Documentation
 
-Component guides live in [`docs/`](./docs): [getting started](./docs/getting-started.mdx), [theme](./docs/theme.mdx), [design tokens](./docs/design-tokens.mdx), [dialog](./docs/dialog.mdx), [bottom sheet](./docs/bottom-sheet.mdx), [toast](./docs/toast.mdx), [alert](./docs/alert.mdx), [menu](./docs/menu.mdx), [select](./docs/select.mdx), [context menu](./docs/context-menu.mdx), [button](./docs/button.mdx), [avatar](./docs/avatar.mdx), [text field](./docs/text-field.mdx), [settings list](./docs/settings-list.mdx), [tab bar](./docs/tab-bar.mdx), [prompt input](./docs/prompt-input.mdx) and [loading](./docs/loading.mdx).
+Component guides live in [`docs/`](./docs), one `.mdx` per family, and **they ship inside the package** at `node_modules/@oxyhq/bloom/docs/`. The copy you read there always describes the version you installed, which matters most for [migrating to 1.0](./docs/migrating-to-1.0.mdx).
+
+Start with [getting started](./docs/getting-started.mdx), [theme](./docs/theme.mdx) and [design tokens](./docs/design-tokens.mdx). Then per surface: [dialog](./docs/dialog.mdx), [bottom sheet](./docs/bottom-sheet.mdx), [toast](./docs/toast.mdx), [alert](./docs/alert.mdx), [dropdown menu](./docs/dropdown-menu.mdx), [select](./docs/select.mdx), [context menu](./docs/context-menu.mdx), [button](./docs/button.mdx), [avatar](./docs/avatar.mdx), [text field](./docs/text-field.mdx), [settings list](./docs/settings-list.mdx), [tab bar](./docs/tab-bar.mdx), [prompt input](./docs/prompt-input.mdx) and [loading](./docs/loading.mdx).
 
 The theme reference is in [README.theme.md](./README.theme.md).
 

package/docs/accordion.mdx

@@ -0,0 +1,69 @@
+---
+title: Accordion
+description: Collapsible sections — fully controlled, and when a disclosure is the wrong shape.
+order: 28
+---
+
+# Accordion
+
+Sections that expand and collapse. Use it when a page holds more than a reader
+needs at once and the sections are *independent* — an FAQ, a set of advanced
+options, a long form split into stages.
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@oxyhq/bloom/accordion';
+
+const [open, setOpen] = useState<string | string[] | undefined>('shipping');
+
+<Accordion type="single" value={open} onValueChange={setOpen}>
+  <AccordionItem value="shipping">
+    <AccordionTrigger>When will it arrive?</AccordionTrigger>
+    <AccordionContent>Two to four working days.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="returns">
+    <AccordionTrigger>Can I return it?</AccordionTrigger>
+    <AccordionContent>Within 30 days, unopened.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Which prop decides what
+
+| prop            | decides                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `type`          | `single` — one open section — or `multiple`                           |
+| `value`         | which section(s) are open: a string for `single`, an array for `multiple` |
+| `onValueChange` | receives the next value, or `undefined` when everything closes         |
+| `disabled`      | per `AccordionItem`, a section that cannot be opened                   |
+| `icon`          | per `AccordionTrigger`, replaces the default chevron                   |
+
+**It is fully controlled — `value` and `onValueChange` are required.** There is
+no uncontrolled mode and no `collapsible` flag: closing the last open section
+means `onValueChange` hands you `undefined`, and whether you accept that or
+re-open something is your decision, not the component's. That is what a wizard
+(always something open) and an FAQ (nothing open is fine) actually differ by.
+
+```tsx
+// FAQ: allow everything closed.
+onValueChange={setOpen}
+
+// Wizard: never let the current step close.
+onValueChange={(next) => setOpen(next ?? open)}
+```
+
+## When an accordion is the wrong shape
+
+- **The user needs to compare sections.** Collapsing hides exactly what they are
+  comparing.
+- **The content is two lines.** More interaction than reading it would have been.
+- **Something inside must be findable.** Browser find-in-page and screen-reader
+  search do not see collapsed content, so an accordion is a bad home for
+  anything a user might arrive looking for.
+
+## Animation
+
+The height transition is driven imperatively from a measured content height
+rather than by a layout animation. On web that distinction is load-bearing:
+an animation started from a Reanimated mapper never ticks, so the obvious
+"animate the content in" silently does nothing. If you nest something that
+animates its own height, let one of the two own the measurement.

package/docs/activity-heatmap.mdx

@@ -0,0 +1,71 @@
+---
+title: ActivityHeatmap
+description: A calendar grid coloured by count — when something happened, over months.
+order: 65
+---
+
+# ActivityHeatmap
+
+Days as cells, coloured by how much happened. Contributions, posts, sessions,
+streaks.
+
+```tsx
+import { ActivityHeatmap } from '@oxyhq/bloom/activity-heatmap';
+
+<ActivityHeatmap
+  data={days}
+  numDays={182}
+  weekStartsOn={1}
+  onPressDay={(day) => showDay(day.date)}
+/>
+```
+
+`data` is `{ date, count }[]`; `date` is an ISO day string.
+
+## Which prop decides what
+
+| prop                       | decides                                            |
+| -------------------------- | --------------------------------------------------- |
+| `data`                     | the counts                                          |
+| `numDays` / `endDate`      | the window shown                                    |
+| `levels`                   | the count thresholds between colour steps           |
+| `colorScale` / `emptyColor`| the colours per level, and for zero                 |
+| `weekStartsOn`             | `0` Sunday or `1` Monday                            |
+| `cellSize` / `gap`         | the geometry                                        |
+| `monthLabels` / `weekdayLabels` | the axis text, for localisation                |
+| `onPressDay`               | makes a cell pressable                              |
+
+## `levels` is the prop to think about
+
+The default buckets suit a roughly uniform distribution. Real activity data is
+usually skewed — a handful of enormous days and a long tail of ones — and with
+default thresholds almost everything paints at the lowest level, so the chart
+says "nothing much happened" about a year of work.
+
+Set thresholds that match your distribution. Quantiles of the non-zero counts
+are a better starting point than evenly spaced values.
+
+Pass one more colour than you pass thresholds. A level is the number of
+thresholds a count meets, so N thresholds address `colorScale[0..N]`; index 0 is
+"positive, but below the first threshold". That index only exists while the
+first threshold is 2 or more — start it at 1 and every positive count meets it,
+so the faintest colour in your scale can never paint.
+
+## Zero is not the lowest level
+
+`emptyColor` is separate from the scale on purpose. "Nothing happened" and "the
+least that ever happens" are different facts, and collapsing them hides exactly
+the streaks the chart is usually read for.
+
+## `weekStartsOn` is a locale decision
+
+Not a style one. Getting it wrong shifts every column by a day, so the chart
+disagrees with the user's calendar — which reads as bad data rather than as a
+wrong setting. `monthLabels` and `weekdayLabels` exist for the same reason:
+they must come from the app's locale, not from English defaults.
+
+## Give the window a reason
+
+`numDays` should match a period the user thinks in — a year, six months, a
+quarter. An arbitrary window invites the reader to work out what they are
+looking at, and the label above the chart should say it outright.

package/docs/admonition.mdx

@@ -0,0 +1,77 @@
+---
+title: Admonition
+description: A bordered callout inside the content — for information the reader must not scroll past.
+order: 49
+---
+
+# Admonition
+
+A bordered block that interrupts the reading flow: a warning about a setting, a
+note about a limitation, an apology for something that went wrong.
+
+```tsx
+import { Admonition } from '@oxyhq/bloom/admonition';
+
+<Admonition type="warning">
+  Turning this off signs you out of every other device.
+</Admonition>
+```
+
+For a callout with an action, compose the parts:
+
+```tsx
+import {
+  AdmonitionRoot,
+  AdmonitionRow,
+  AdmonitionIcon,
+  AdmonitionContent,
+  AdmonitionText,
+  AdmonitionButton,
+} from '@oxyhq/bloom/admonition';
+
+<AdmonitionRoot type="error">
+  <AdmonitionRow>
+    <AdmonitionIcon />
+    <AdmonitionContent>
+      <AdmonitionText>We couldn't reach the server.</AdmonitionText>
+      <AdmonitionButton onPress={retry}>Try again</AdmonitionButton>
+    </AdmonitionContent>
+  </AdmonitionRow>
+</AdmonitionRoot>
+```
+
+## `type` picks the icon and the border together
+
+| `type`    | for                                                    |
+| --------- | ------------------------------------------------------- |
+| `info`    | a neutral note                                          |
+| `tip`     | a suggestion — painted in the brand colour               |
+| `warning` | something that could go wrong if they continue          |
+| `error`   | something that has gone wrong                           |
+| `apology` | a limitation on our side, not the reader's mistake      |
+
+`AdmonitionIcon` reads the type from context, so the icon and the border cannot
+disagree — which is how an `error` callout ends up with a warning icon when the
+two are set by hand.
+
+## Admonition or toast
+
+- **Admonition** — stays. It is *about* the content it sits next to, and the
+  reader can return to it.
+- **[Toast](/docs/bloom/main/toast)** — passes. It is about something that just
+  happened.
+
+Anything the user might need to read twice belongs in an admonition. A toast is
+gone in four seconds and cannot be recovered.
+
+## `apology` exists because the wording differs
+
+"Something went wrong" and "we couldn't do this, and it is our fault" are
+different messages, and the second reads badly in an `error` box that looks
+like the user broke something. Use it where the limitation is ours.
+
+## Do not stack them
+
+Three callouts in a row is a page that has given up prioritising. If everything
+is important, nothing reads as important — and a reader who learns to scroll
+past one will scroll past the one that mattered.

package/docs/alert-dialog.mdx

@@ -0,0 +1,75 @@
+---
+title: AlertDialog
+description: The declarative confirm dialog — and when to use `confirm()` instead.
+order: 40
+---
+
+# AlertDialog
+
+A confirm dialog you render: a title, a description, and a confirm/cancel pair.
+
+```tsx
+import { AlertDialog } from '@oxyhq/bloom/alert-dialog';
+
+<AlertDialog
+  visible={confirmingDelete}
+  onClose={() => setConfirmingDelete(false)}
+  title="Delete this draft?"
+  description="This cannot be undone."
+  confirmLabel="Delete"
+  destructive
+  onConfirm={remove}
+/>
+```
+
+## Which prop decides what
+
+| prop            | decides                                                     |
+| --------------- | ------------------------------------------------------------ |
+| `visible`       | whether it is open — the dialog is controlled                 |
+| `onClose`       | called whenever it closes, however it closed                  |
+| `title`         | the question                                                  |
+| `description`   | the consequence                                               |
+| `confirmLabel` / `cancelLabel` | the button text                                |
+| `onConfirm` / `onCancel` | what each button does                                |
+| `destructive`   | paints the confirm button in the error role                   |
+| `hideCancel`    | one button only — an acknowledgement, not a choice            |
+| `dismissible`   | whether a backdrop press or Escape closes it                  |
+
+There is no free-form action array: the shape is confirm-and-cancel, and that
+constraint is the point. A dialog with three or four actions is a menu wearing
+a dialog's clothes, and the user has to read all of them before deciding.
+
+## AlertDialog or `confirm()`
+
+Both ask the same question; they differ in where the answer goes.
+
+- **`AlertDialog`** — declarative and controlled. Right when the open state is
+  already part of the screen's state.
+- **[`confirm()`](/docs/bloom/main/surfaces)** — imperative, returns a promise.
+  Right inside an event handler or a mutation callback, where you want to
+  `await` the answer and there is no natural place to hang a `visible` flag.
+
+The family owns no queue and no host: it bridges onto `Dialog`'s imperative
+control internally, so it stacks with every other overlay and its exit
+animation is not raced by a consumer unmounting in `onClose`.
+
+## `destructive` is a colour
+
+It does not add a second confirmation and it does not make the action
+reversible. If the action destroys something the user cannot get back, the
+recovery path — an undo, a trash — is the real safeguard; the red button is
+only a signal.
+
+## Write the question, not "Are you sure?"
+
+The title says what will happen, and `confirmLabel` says what the button does —
+"Delete" rather than "OK". Anyone dismissing dialogs quickly reads only the
+button, and should still know what they agreed to.
+
+## `hideCancel` is for an acknowledgement
+
+One button means there is no choice to make — something already happened and
+the user is being told. Consider whether that needs a dialog at all: if nothing
+is required of the reader, a [`toast`](/docs/bloom/main/toast) says it without
+interrupting.

package/docs/alert.mdx

@@ -0,0 +1,93 @@
+---
+title: alert()
+description: Imperative one-shot confirmation dialogs, matching React Native's Alert.alert signature.
+order: 6
+---
+
+# alert()
+
+Imperative one-shot confirmation dialogs, matching React Native's `Alert.alert(title, message?, buttons?)` signature. You can call `alert()` from anywhere — an event handler, an async callback, a top-level helper — without threading a provider through the call site.
+
+It presents onto Bloom's shared **surface stack**, the same one `confirm()`, `prompt()` and `surfaces.present()` use, so an alert layers correctly above whatever is already open. Two `alert()` calls in a row STACK; they do not queue.
+
+## Setup
+
+Mount the surface host once near your app root:
+
+```tsx
+import { SurfaceProvider } from '@oxyhq/bloom';
+
+<SurfaceProvider>
+  <App />
+</SurfaceProvider>
+```
+
+`<SurfaceHost />` on its own does the same job without wrapping `children`, if you'd rather place it yourself.
+
+See [Getting started](/docs/bloom/main/getting-started) for the full provider stack.
+
+## Usage
+
+```tsx
+import { alert } from '@oxyhq/bloom';
+
+alert('Sign out?', 'Are you sure you want to sign out of this device?', [
+  { text: 'Cancel', style: 'cancel' },
+  { text: 'Sign out', style: 'destructive', onPress: doSignOut },
+]);
+
+// Single OK button (default when no buttons passed):
+alert('Saved');
+```
+
+## Signature
+
+```ts
+function alert(
+  title: string,
+  message?: string,
+  buttons?: AlertButton[],
+): void
+```
+
+### `AlertButton`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | Required label. |
+| `style?` | `'default' \| 'cancel' \| 'destructive'` | Defaults to `'default'`. |
+| `onPress?` | `() => void` | Fires on the press, as the surface animates out. |
+
+## Patterns
+
+### Drop-in replacement for `Alert.alert`
+
+If you're migrating from React Native's built-in `Alert`, you can swap the import:
+
+```diff
+-import { Alert } from 'react-native';
++import { alert } from '@oxyhq/bloom';
+
+-Alert.alert('Title', 'Message');
++alert('Title', 'Message');
+```
+
+`alert()` matches the same call signature, so existing call sites work unchanged.
+
+<Callout variant="warning" title="alert vs Dialog">
+`alert()` is for **imperative one-shot prompts** (e.g. confirming destructive actions from a deeply nested callback). When you need state-driven control over a dialog (open/close timing, busy states), use the declarative [`<Dialog>`](/docs/bloom/main/dialog) component instead.
+</Callout>
+
+## Related
+
+`alert()` answers nothing. Its two siblings on the same stack do:
+
+```tsx
+import { confirm, prompt } from '@oxyhq/bloom/surfaces';
+
+const ok = await confirm({ title: 'Delete app?', destructive: true });
+const name = await prompt({ title: 'Name this list' }); // string | null
+```
+
+`confirm` resolves `false` and `prompt` resolves `null` on a backdrop / Escape /
+Android-back dismissal, so neither can hang.

package/docs/animated-check.mdx

@@ -0,0 +1,53 @@
+---
+title: AnimatedCheck
+description: A checkmark that draws itself — confirmation for something that just finished.
+order: 67
+---
+
+# AnimatedCheck
+
+A checkmark that strokes itself in when told to.
+
+```tsx
+import { AnimatedCheck, type AnimatedCheckRef } from '@oxyhq/bloom/animated-check';
+
+const check = useRef<AnimatedCheckRef>(null);
+
+<AnimatedCheck ref={check} size={48} />
+
+// when the thing succeeds
+check.current?.play();
+```
+
+## Which prop decides what
+
+| prop    | decides                     |
+| ------- | ---------------------------- |
+| `size`  | the glyph size               |
+| `color` | the stroke colour            |
+
+The animation itself is imperative: `ref.play()`. There is no `visible` or
+`animate` prop, because the interesting moment is a **transition** — the check
+should draw when the operation finishes, not whenever the component happens to
+mount or a prop happens to flip.
+
+## Where it belongs
+
+The end of something the user waited for: a payment confirmed, a file uploaded,
+a form submitted. It replaces the spinner that was there.
+
+Not as a static tick in a list — that is an icon
+(`Check_Stroke2_Corner0_Rounded`) and drawing it with an animation component
+costs an animation and a ref for a glyph. And not for every save: a check
+animation on an autosave is motion for something the user did not ask about.
+
+## Say it in words too
+
+An animation is not announced. Whatever the check confirms should also be
+readable — a line of text beside it, or a [toast](/docs/bloom/main/toast) — or a
+screen reader user gets no confirmation at all.
+
+## Reduced motion
+
+If the user has asked for reduced motion, show the check rather than drawing
+it. The information is the checkmark; the stroke is decoration.

package/docs/aspect-ratio.mdx

@@ -0,0 +1,45 @@
+---
+title: AspectRatio
+description: A box that keeps a fixed width-to-height ratio.
+order: 25
+---
+
+# AspectRatio
+
+A box that keeps a fixed width-to-height ratio while the layout around it decides its width. The usual job: a media well that must not jump as an image loads, because its height was known before the image was.
+
+```tsx
+import { AspectRatio } from '@oxyhq/bloom/aspect-ratio';
+
+<AspectRatio ratio={16 / 9}>
+  <Image source={{ uri: cover }} style={{ width: '100%', height: '100%' }} />
+</AspectRatio>
+```
+
+`ratio` is width divided by height and defaults to `1`. A number rather than a preset name, for the same reason shadcn's web `AspectRatio` takes one: a ratio is arithmetic the call site already has, and naming presets needs a new name for every ratio anyone wants.
+
+## A ratio it cannot use takes the default
+
+`0`, `NaN`, `Infinity` and negatives are not ratios — a box has positive finite lengths on both axes — and every one of them comes out of the arithmetic above when the image has not loaded yet: `0 / 0` is `NaN`, `w / 0` is `Infinity`, `0 / h` is `0`. Passed through, they leave the well with no usable height, which is the layout jump this component exists to prevent. So they fall back to `1` rather than reaching the style.
+
+You still want a real number here. The fallback keeps the well a well; it does not know your media's shape, so a component that can be told the ratio ahead of the load should be told it.
+
+## It fills its parent's width
+
+An aspect box with no width is zero-sized, and "fill the parent, derive the height" is what every call site wants. So the width is `100%` and the height follows from `ratio`. A caller who needs a fixed width passes one through `style`, which lands last:
+
+```tsx
+<AspectRatio ratio={1} style={{ width: 96, borderRadius: 12, overflow: 'hidden' }}>
+  <Avatar source={user.avatar} />
+</AspectRatio>
+```
+
+## It takes no `className`
+
+`aspectRatio` is the ONE property this component exists to set, and react-native-css merges utilities into `style` before inline style — so a caller writing `className="aspect-video"` would have it silently overwritten by the `ratio` prop, with no error anywhere.
+
+One owner per property: use this component with `ratio`, or a plain `View` with the class, never both. Wrap it for the surrounding layout classes.
+
+## Not a port
+
+react-native-reusables' `aspect-ratio.tsx` is four lines re-exporting `@rn-primitives/aspect-ratio`'s Root — a primitive that exists on the web because CSS needed `padding-bottom` tricks before `aspect-ratio` landed. React Native has had `aspectRatio` as an ordinary style property the whole time, so there was nothing to copy. What earns the name here is the shadcn spelling and the two decisions above.

package/docs/avatar-group.mdx

@@ -0,0 +1,91 @@
+---
+title: AvatarGroup
+description: The one stacked-avatar component. Apps must not keep a local avatar stack.
+order: 22
+---
+
+# AvatarGroup
+
+Overlapping avatars with an overflow count — "3 people are typing", "12 members",
+a facepile on a post. **Every grouped or stacked avatar UI in the ecosystem uses
+this.** App-local avatar-stack components are not a variation to be tolerated;
+they drift on overlap, ring colour and overflow rules, and they miss the avatar
+resolution rules below.
+
+```tsx
+import { AvatarGroup } from '@oxyhq/bloom/avatar-group';
+
+<AvatarGroup
+  items={members}
+  max={5}
+  total={members.length}
+  size={32}
+  onPressItem={(item) => router.push(`/@${item.username}`)}
+/>
+```
+
+## Which prop decides what
+
+| prop               | decides                                                       |
+| ------------------ | -------------------------------------------------------------- |
+| `items`            | who is shown, in order                                          |
+| `max`              | how many faces before the overflow chip                         |
+| `total`            | the number the overflow chip counts to                          |
+| `size` / `overlap` | the geometry                                                    |
+| `ringColor`        | the colour of the gap between overlapping faces                 |
+| `onPressItem`      | makes each face a link to that profile                          |
+| `hoverCard`        | a hover card on web; a no-op on native, where there is no hover |
+| `renderItemAction` | a slot on each face                                             |
+
+`total` is separate from `items.length` on purpose: a list endpoint usually
+returns a page of members plus a full count, and the overflow chip should say
+`+248` rather than `+3`.
+
+## The avatar prop that goes wrong silently
+
+Pass an Oxy avatar to `source`, **not** `uri`.
+
+```tsx
+items={users.map((u) => ({ id: u.id, source: u.avatar, name: u.displayName }))}  // ✅
+items={users.map((u) => ({ id: u.id, uri: u.avatar }))}                          // ✗
+```
+
+`source` sends a non-URL string — an Oxy file id — through the consumer's
+registered `ImageResolver`. `uri` is taken as a raw URL, so a file id resolves
+to nothing, the image 404s, and every face falls back to its initial. Nothing
+throws. The symptom is "all avatars show a placeholder character", which reads
+as missing data rather than as a wiring mistake.
+
+## `ringColor` is the surface behind, not a decoration
+
+The gap between overlapping faces is drawn in `ringColor`, so it must match
+whatever the group sits **on** — the page background on a screen, the `card`
+role inside a card. A ring left at the default over a coloured surface is the
+usual reason a facepile looks like it has white halos.
+
+## `hoverCard`
+
+Web-only by construction: hover does not exist on touch, so the prop is a no-op
+on native rather than a different interaction. The card itself is
+[`UserHoverCard`](/docs/bloom/main/user-hover-card), which holds no follow
+state — the consumer passes the SDK's `FollowButton` into its `action` slot.
+
+`renderItemAction` is the only slot the hover card exposes per item.
+`UserHoverCard`'s `footer` is not forwarded: a facepile hover card is a glance at
+who these people are, and an app that wants a fuller preview renders
+`UserHoverCard` behind its own trigger.
+
+The card floats via `Portal`, imported from `'../portal/index.web'` rather than
+the bare `'../portal'` — export conditions don't apply to relative specifiers,
+so a bare import here resolves to the NATIVE barrel off Metro (Vite, webpack,
+SSR), and the card renders nothing, silently, because the native `Portal`
+needs a `PortalOutlet` no web app mounts. If you touch this import, verify
+against the BUILT artefact, not just the source.
+
+The card floats under a `View` with `onPointerEnter`/`onPointerLeave`, and that
+must not become a `Pressable`. react-native-web's `Pressable` dispatches a
+bubbling `react-gui:hover:lock` event on hover, and an ancestor `Pressable` that
+is currently hovered ends its own hover for any lock it did not send — so a
+`Pressable` bridge dismissed the card the moment the cursor reached the injected
+FollowButton or the identity area. Nothing was logged; the card just went away
+about 120ms later.