@oxy.so/bloom 6.0.0 → 6.2.0

package/README.md

@@ -162,7 +162,7 @@ Icons go one step further: every glyph is its own subpath, `@oxy.so/bloom/icons/
 | Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `dropdown-menu`, `menubar`, `tooltip`, `overlay`, `portal`, `teleport`, `surfaces`, `settings-modal` |
 | Actions | `button`, `button-group`, `social-button`, `fab`, `frosted-icon-button`, `pressable-scale`, `subtle-hover` |
 | Forms | `text-field`, `textarea`, `phone-input`, `input-otp`, `field`, `input-group`, `label`, `select`, `command`, `checkbox`, `radio`, `switch`, `slider`, `segmented-control`, `search`, `date-picker`, `file-upload`, `auth-card`, `stepper`, `rating`, `wizard` |
-| Layout and lists | `grid`, `list`, `scroll`, `settings-list`, `card`, `accordion`, `aspect-ratio`, `divider`, `item`, `carousel` |
+| Layout and lists | `grid`, `list`, `scroll`, `settings-list`, `card`, `cover-header`, `accordion`, `aspect-ratio`, `divider`, `item`, `carousel` |
 | Data and charts | `table`, `data-table`, `chart-cards`, `stat-cards`, `calendar`, `composition-bar`, `dot-grid-meter`, `stat-bar`, `activity-heatmap`, `recent-hires-card`, `patient-info-card`, `important-alerts-card`, `agent-limits-card`, `ai-profile-card` |
 | Music and media | `media-card`, `media-controls`, `media-header`, `media-player`, `media-shelf`, `track-list`, `queue-panel`, `lyrics`, `music-library`, `creator-studio`, `sortable-media` |
 | Housing | `home-search`, `listing-actions`, `listing-editor`, `offering-badge`, `place-reviews`, `property-insights`, `tenancy`, `eviction` |

package/docs/adoption-matrix.mdx

@@ -32,7 +32,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **206 families** in `src/`, **204** published (a subpath, the root barrel, or both). **40** carry a web fork.
+- **208 families** in `src/`, **206** published (a subpath, the root barrel, or both). **41** carry a web fork.
 - Docs, stories and suites are gated as a standard by `src/__tests__/family-coverage.test.ts`; the per-family counts are in the table below.
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
@@ -163,6 +163,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 2 |  |  |  |  |
 | `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 8 |  |  |  |  |
 | `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 5 |  |  | reads |  |
+| `cover-header` | `@oxy.so/bloom/cover-header` + barrel | universal | `cover-header.mdx` | yes | 1 |  |  |  |  |
 | `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 4 |  | n/a¹ |  | **adaptation** |
 | `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 4 |  | reads |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 5 | reads | reads |  | reads |
@@ -228,7 +229,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `menu-item` | `@oxy.so/bloom/menu-item` + barrel | universal | `menu-item.mdx` | yes | 1 |  |  |  |  |
 | `menubar` | `@oxy.so/bloom/menubar` + barrel | web fork | `menubar.mdx` | yes | 5 |  |  | reads | reads |
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 2 |  |  |  |  |
-| `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 2 | n/a¹ |  |  |  |
+| `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 4 |  |  |  |  |
 | `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `navigation-banner` | `@oxy.so/bloom/navigation-banner` + barrel | universal | `navigation-banner.mdx` | yes | 2 |  |  |  |  |
@@ -287,6 +288,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 5 | n/a¹ | reads |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 5 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 4 | reads | reads |  |  |
+| `sticker` | `@oxy.so/bloom/sticker` + barrel | web fork | `sticker.mdx` | yes | 1 |  |  |  |  |
 | `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 83 | n/a¹ |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
 | `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 37 |  |  |  |  |
@@ -302,7 +304,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 5 |  | reads |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 16 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 343 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 345 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |

package/docs/chat-composer.mdx

@@ -136,6 +136,10 @@ Times ("12:41", "Yesterday") never appear here. `VoiceRecorder` takes `seconds`
 
 One `SuggestionList` serves all three kinds; only the leading slot differs (an avatar, a glyph disc, the emoji). Rows are `role="option"` inside a `role="listbox"` with `aria-selected` — the spelling react-native-web reads; `accessibilityState` alone would render a list with no state on web. Each row is named by its label **and** handle, because "Ana" alone is ambiguous in a group.
 
+A person marked `verified` gets the accent verified badge after the name, and the row's name says so ("Ana Restrepo, Verified, @ana"); the marker belongs to `kind="mention"` only.
+
+The list also answers the two states a search passes through. `loading` replaces the rows with a named, busy "Searching…" line, so a list with nothing *yet* is not read as one that found nothing. An empty list still draws nothing by default — right for a composer that shows the list only while it has rows — and `showEmpty` draws the localized "No people found" line instead (`emptyLabel` replaces it), for a picker the user opened on purpose.
+
 The list renders **in flow** above the bar rather than in a portal. Anchoring it over the conversation is a layout decision an app makes with its own container (`position: absolute` on a wrapper); a portal here would have to guess the scroll parent.
 
 ## Voice recorder
@@ -227,7 +231,7 @@ State colours 150ms; the mic ↔ send cross-fade 220ms; the recording dot pulses
 
 `ComposerBanner` — `kind`, `title`, `preview`, `thumbnail`, `icon`, `accentColor`, `onClose`, `closeLabel`, `trailing`.
 `ComposerAttachmentStrip` — `attachments`, `onRemove`, `size` (56), `removeLabel`.
-`SuggestionList` — `kind`, `suggestions`, `activeIndex`, `onSelectSuggestion`, `onActiveIndexChange`, `header`, `maxHeight` (232).
+`SuggestionList` — `kind`, `suggestions` (each may carry `verified`), `activeIndex`, `onSelectSuggestion`, `onActiveIndexChange`, `header`, `maxHeight` (232), `loading`, `showEmpty`, `emptyLabel`.
 `VoiceRecorder` — `state`, `seconds`, `duration`, `amplitudes`, `playing`, `onPlayToggle`, `onCancel`, `onDelete`, `onSend`, `onLock`, `slideToCancel`, `labels`.
 `AttachmentMenu` — `open`/`defaultOpen`/`onOpenChange`, `items`, `layout`, `columns`, `onSelect`, `recent`, `label`.
 `EmojiPicker` — `groups`, `onSelectEmoji`, `activeGroup`, `query`, `filter`, `frequentlyUsed`, `skinTone`, `columns` (8), `height` (288), `tabs`, `activeTab`, `labels`.

package/docs/cover-header.mdx

@@ -0,0 +1,56 @@
+---
+title: CoverHeader
+description: A cover band with content rising into its bottom edge — a profile's banner and the avatar that overlaps it.
+order: 106
+---
+
+# CoverHeader
+
+A cover band (a photo, or anything you draw) and a content column whose top
+rises `overlap` points into the band's bottom edge. It is the geometry of a
+profile page's banner-plus-avatar, and of `AiProfileCard`, which is built on it.
+
+```tsx
+import { CoverHeader } from '@oxy.so/bloom/cover-header';
+
+<CoverHeader coverSource={bannerUrl} coverHeight={170} overlap={45}
+  contentStyle={{ paddingHorizontal: 16 }}>
+  <Avatar size={90} source={avatarUrl} />
+  <Text variant="title-2-medium">Maya Collins</Text>
+</CoverHeader>
+```
+
+## Props
+
+| Prop | Default | |
+|---|---|---|
+| `coverSource` | — | photo across the band; without one the band is `background-tertiary` |
+| `coverPosition` | `{ x: 0.5, y: 0.5 }` | where the crop sits, as `object-position` fractions |
+| `cover` | — | drawn in the band instead of the photo |
+| `coverHeight` | `170` | height of the band |
+| `overlap` | `45` | how far the content rises into the band, clamped to `0..coverHeight` |
+| `coverStyle` | — | the band's style (corner radii, another fill) |
+| `contentStyle` | — | the content column's style; its `paddingTop` is the component's |
+| `testID` | — | also names `-cover`, `-cover-image` and `-content` |
+
+## How the overlap is made
+
+By layout. Nothing is moved.
+
+- The band is the **first** child, positioned absolutely over the top `coverHeight`.
+- The content is the **last** child, in flow, with `paddingTop: coverHeight - overlap`.
+
+There is no negative margin, no transform and no `zIndex`, and each of those
+has broken a profile before:
+
+- A **transform** keeps the layout box where it was. The content paints 45pt higher,
+  but whatever comes next (a tab strip, a list's next row) still starts after the
+  un-moved box, which leaves a 45pt hole.
+- A **negative margin** on the content leaves the paint order to whichever
+  view happens to create a stacking context first. Inside a native
+  virtualized cell, that has put the avatar under the banner.
+- **`zIndex`** belongs to the overlay stack (`docs/overlay.mdx`), never to a component.
+
+Because the content is the later sibling, it paints over the band on iOS,
+Android and web. The measured height is the real one. A list header or
+sticky section placed after a `CoverHeader` starts exactly where its content ends.

package/docs/message-media.mdx

@@ -258,9 +258,14 @@ answer AND the viewer's wrong pick — hiding the right answer teaches nobody.
 
 ```tsx
 <StickerMessage source={sticker} accessibilityLabel="Sticker: grinning sun" />
+<StickerMessage source={still} animation={lottieUrl} accessibilityLabel="Sticker: waving" />
 <GifMessage source={gif} aspectRatio={1.6} />
 ```
 
+Given `animation`, the sticker plays its Lottie file through
+[`Sticker`](./sticker.mdx), over `source` as the still — which is also what shows
+under reduced motion or when no Lottie player is installed.
+
 **A sticker draws NO surface** — no background, no radius, no padding. Render it
 with `message-bubble`'s `variant="bare"`: a bubble behind a sticker is a picture
 of a sticker, and its scrim turns a cut-out into a square. `resizeMode` is

package/docs/sticker.mdx

@@ -0,0 +1,64 @@
+---
+title: Sticker
+description: A Lottie sticker that animates where it can and stays a clean still where it cannot.
+order: 140
+---
+
+# Sticker
+
+A sticker, animated when it can be and still when it cannot.
+
+```tsx
+import { Sticker } from '@oxy.so/bloom/sticker';
+
+<Sticker
+  animation={sticker.animation.url}   // Lottie JSON or .lottie
+  fallback={sticker.fallback.url}     // the still image of the same sticker
+  size={160}
+  accessibilityLabel="Sticker: sad bear"
+/>
+```
+
+Oxy's sticker catalogue (`@oxy.so/stickers`) hands out both URLs for every
+sticker, which is exactly this component's pair of props.
+
+## What a person sees
+
+| situation | shown |
+| --- | --- |
+| the animation is still loading | the still |
+| the animation loaded | the animation |
+| the animation failed to load | the still, for good |
+| the person asked for reduced motion | the still — the player is never mounted |
+| no Lottie player is installed on this platform | the still, with one dev warning naming the package |
+
+The still is always drawn first, so a sticker never flashes blank while its
+animation arrives, and every failure mode still looks like a sticker.
+
+## Players are optional peers
+
+Bloom ships no native code, so each platform's player is an OPTIONAL peer,
+loaded only when a `Sticker` with an `animation` renders:
+
+- native: `lottie-react-native` (`npx expo install lottie-react-native`)
+- web: `@lottiefiles/dotlottie-react`
+
+An app that shows no animated sticker installs neither. An app with its own
+build of a player hands it in with `provideLottiePlayer(Component)`, adapted to
+`LottiePlayerProps` (`uri`, `loop`, `paused`, `onLoad`, `onError`, `style`).
+
+## Props
+
+| prop | decides |
+| --- | --- |
+| `animation` | the Lottie file; omit it for a still sticker |
+| `fallback` | the still image — required |
+| `size` | square edge, default 128 |
+| `loop` | default true |
+| `paused` | hold the frame, e.g. while scrolled out of view |
+| `accessibilityLabel` | the name; a sticker IS its meaning, so pass its emotion |
+| `decorative` | hide it from assistive technology when its container already names it |
+
+Like `StickerMessage`, it draws **no surface** — no background, radius or
+padding. In a chat use `StickerMessage` with `animation`, which is this plus the
+press, sending and failed affordances.