@oxy.so/bloom 2.10.0 → 2.12.0

package/docs/chat-composer.mdx

@@ -0,0 +1,233 @@
+---
+title: Chat Composer
+description: The message bar of a person-to-person chat — attach, autosizing field, emoji, the mic that becomes send — with its banners, suggestions, voice recorder and the emoji, reaction and message menus.
+order: 64
+---
+
+# Chat Composer
+
+```tsx
+import {
+  ChatComposer,
+  ComposerBanner,
+} from '@oxy.so/bloom/chat-composer';
+
+<ChatComposer
+  value={draft}
+  onValueChange={setDraft}
+  onSend={send}
+  banner={replyTo ? <ComposerBanner kind="reply" title={replyTo.author} preview={replyTo.text} onClose={clearReply} /> : null}
+  attachments={pending}
+  onRemoveAttachment={remove}
+  onAttachPress={openAttachMenu}
+  onEmojiPress={openEmojiPicker}
+  onMicPress={startRecording}
+/>
+```
+
+A radius-24 pill: an attach button, an autosizing field that grows one 20px line at a time up to `maxLines` and then scrolls, an emoji button, and a right control that cross-fades between a mic (nothing to send) and an accent send disc (there is). Everything above the bar — reply and edit previews, the attachment strip, a slow-mode line, the suggestion list — is a separate part that composes into it.
+
+## Why this is not `composer-panel`
+
+`composer-panel` is Bloom's AI-prompt composer and stays that. It is two rows tall and its second row is a control strip: a permission mode, a model picker, an effort slider. Its state is about *how the model will answer*.
+
+This one is one row, and its state lives **above** the bar — who you are replying to, which message you are editing, what is uploading, whether the channel is in slow mode. Its right control swaps between two different actions rather than staying a send button, and its keyboard has to choose between Enter-sends and Enter-newlines because a chat message is usually one line and a prompt usually is not.
+
+What genuinely transfers is reused rather than retyped: the 56px attachment tile and the rounded-rect progress path come from `composer-panel/shared` (`ringPath`), and the 36px round control, the pill geometry and the `bg-button-primary` send gradient are the same recipe. What did **not** transfer is the two-row card, the model/permission/effort surface and the status tab.
+
+## Exports
+
+| Export | What it is |
+|---|---|
+| `ChatComposer` | The bar. |
+| `ComposerBanner` | One reply / edit / forward preview, or a one-line `note`. |
+| `ComposerAttachmentStrip` | The pending-attachment tiles. `ChatComposer` draws one from `attachments`; export it for a standalone strip. |
+| `ComposerIconButton` | The 36px round control, for a slot that has to match. |
+| `SuggestionList` | `@mention`, `/command` and `:shortcode` rows — one part, three `kind`s. |
+| `VoiceRecorder` | Recording, locked and preview. |
+| `AttachmentMenu` | The plus menu, as a `Popover`. |
+| `EmojiPicker` | The controlled emoji grid. |
+| `ReactionPicker` | The quick reaction bar. |
+| `MessageContextMenu` | The per-message menu, as a `DropdownMenu`. |
+| `formatRecordingTime`, `filterEmojiGroups`, `applySkinTone`, `emojiChar` | The pure helpers, so an app can format and search the same way. |
+| `ATTACHMENT_MENU_ITEMS`, `REACTION_PICKER_EMOJIS`, `EMOJI_CATEGORY_ICONS`, `SKIN_TONE_MODIFIERS` | Defaults, for extending rather than retyping. |
+
+## Anatomy
+
+| Part | Geometry |
+|---|---|
+| bar | radius 24, 1px border, padding 6, min height 48 |
+| controls | 36 round; the send disc paints the `bg-button-primary` gradient, the rest paint only on hover/press/focus |
+| field | `body-regular`, one 20px line, up to `maxLines` (6) then scrolls |
+| banner | radius 12, accent wash, a 3px accent rail, padding 6 / left 8 / right 4 |
+| note banner | no rail, no wash — a `caption-1-regular` line |
+| attachment tile | 56, radius 12, 1px border; the ring is a 2px accent stroke over that border |
+| suggestion row | min 44, radius 10, in a radius-16 panel |
+| emoji cell | 36; category tabs 32; the grid body is 288 tall by default |
+| reaction cell | 36 (`small` 30), in a full-pill bar |
+
+Full pill radius only on the button-like parts — the controls, the reaction bar, the emoji category tabs. The banner, the tiles and the panels keep normal radii.
+
+## Keyboard (web)
+
+| Key | What happens |
+|---|---|
+| Enter | Sends (`sendOn="enter"`, the default). With `sendOn="mod-enter"` it breaks the line. |
+| Shift + Enter | Breaks the line. |
+| ⌘ / Ctrl + Enter | Sends when `sendOn="mod-enter"`. |
+| Escape | `onEscape` — cancel the reply or the edit. |
+| ↑ on an empty draft | `onEditLast`. |
+| ↑ / ↓ with `suggestions` open | Moves `activeIndex` (wrapping) through `onActiveIndexChange`. |
+| Enter with a highlighted suggestion | Takes it instead of sending. |
+
+An open IME composition is respected: committing a candidate with Enter never sends the half-written word behind it. Native has no key events to read here — the send button is the only way to submit, and `showKeyboardHint` draws nothing off web.
+
+## State
+
+`value` / `defaultValue` / `onValueChange` — the draft, controlled or not; an uncontrolled draft clears after a send and a controlled one is left to its owner. **Everything else is a prop**, deliberately: the app owns a draft per conversation, which banner is up, what is uploading and which suggestion is highlighted. A composer that kept its own would lose all of it on the first navigation, and a highlight it owned would fight the pointer for it.
+
+Times ("12:41", "Yesterday") never appear here. `VoiceRecorder` takes `seconds` and `duration` as numbers and formats them with `formatRecordingTime`; nothing in this family reads the clock.
+
+## Slots
+
+`leading` replaces the attach button, `emojiSlot` the emoji button and `recorder` the entire bar. That is how a menu gets anchored to a control that lives inside the composer:
+
+```tsx
+<ChatComposer
+  leading={
+    <AttachmentMenu onSelect={handleAttachment}>
+      <ComposerIconButton icon={RiAddLine} accessibilityLabel="Attach" iconSize={22} />
+    </AttachmentMenu>
+  }
+  recorder={recording ? <VoiceRecorder state="recording" seconds={elapsed} amplitudes={levels} onCancel={cancel} onLock={lock} /> : undefined}
+/>
+```
+
+`AttachmentMenu` renders its child through `PopoverTrigger asChild`, which merges the open handler, `aria-expanded` and `aria-haspopup` onto it — `ComposerIconButton` accepts and forwards all three, so any other trigger you write must too.
+
+## Banners
+
+```tsx
+<ComposerBanner kind="reply" title="Ana Restrepo" preview="Still on for Thursday?" onClose={clear} />
+<ComposerBanner kind="edit" title="Edit message" preview="See you at six" onClose={clear} />
+<ComposerBanner kind="forward" title="Forward to Harbour crew" preview="1 photo" thumbnail={uri} onClose={clear} />
+<ComposerBanner kind="note" title="Slow mode: 12s" icon={RiTimerLine} />
+```
+
+`reply`, `edit` and `forward` are one row — rail, glyph, optional thumbnail, two lines, close — because they are the same affordance: *the next message is about this, and here is how to get out of it*. `note` drops the rail and the wash, which is the difference between "you are in a mode" and "here is a fact about sending". Stack several by passing a `View` of them as `banner`.
+
+`accentColor` paints the rail and the title; pass a per-sender colour to match the quoted bubble. The banner names itself from both lines, so assistive tech announces it as one thing rather than two.
+
+## Suggestions
+
+```tsx
+<ChatComposer
+  suggestions={people}
+  suggestionKind="mention"
+  activeIndex={active}
+  onActiveIndexChange={setActive}
+  onSelectSuggestion={(suggestion) => insert(suggestion.handle)}
+/>
+```
+
+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.
+
+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
+
+```tsx
+<VoiceRecorder state="recording" seconds={7} amplitudes={levels} onCancel={cancel} onLock={lock} />
+<VoiceRecorder state="locked" seconds={64} amplitudes={levels} onCancel={cancel} onSend={send} />
+<VoiceRecorder state="preview" seconds={position} duration={41} amplitudes={levels} playing={playing} onPlayToggle={toggle} onDelete={discard} onSend={send} />
+```
+
+`amplitudes` is `0`–`1`, oldest first. The bar count is derived from the MEASURED width, so the same recorder reads correctly in a 390px column and a 900px one, and `waveformBars` drops the overflow from the **front** — a growing array scrolls left like a live meter. Silence is floored at `0.06` so a quiet passage is a row of ticks rather than an invisible gap that reads as a dropped recording.
+
+`slideToCancel` defaults to `true` off web: a pointer has no slide gesture, so on web the hint is replaced with an explicit cancel button. The gesture itself belongs to the app — this part draws the affordance and takes `onCancel`.
+
+## Attachment menu
+
+`Popover`, not a surface of its own. Bloom's popover is already an anchored panel on a pointer and a bottom sheet on a phone, so this family ships **no platform fork**: it inherits the dismissal, stacking and focus behaviour those surfaces were gated for. `layout="grid"` (default, `columns` 4) draws 48px tinted discs with captions; `layout="list"` draws rows. `recent` is a slot above the items for a recent-gallery strip.
+
+## Emoji picker
+
+**Bloom ships no emoji dataset**, and that is the design. A full set with names and keywords is tens of kilobytes that every app with its own would still pay for, and emoji names are localised.
+
+```ts
+interface EmojiGroup {
+  key: string;      // 'smileys' | 'people' | … keys the built-in category glyph
+  label: string;
+  emojis: (string | { char: string; name?: string; keywords?: string[] })[];
+  icon?: ChatComposerIcon;
+}
+```
+
+The object form is what the built-in search matches on. A dataset of **bare glyphs still renders** — it just only matches a pasted glyph, which is the honest behaviour rather than a silent one. Pass `filter={false}` to hand searching to the app entirely and supply pre-filtered `groups`.
+
+The grid is a `FlatList` on **both** platforms, over pre-chunked rows rather than single emoji, with exact `getItemLayout` offsets. A few thousand entries is the normal case: at eight columns that is a few hundred rows of which a dozen are mounted, and the exact offsets are what let a category tab jump straight to its header instead of estimating. The active category follows a TAP, not the scroll position — tracking the scroll would need viewability callbacks whose thresholds differ per platform.
+
+`skinTone` (0–5) applies a Fitzpatrick modifier through `applySkinTone`, which only modifies an emoji whose base accepts one and never splices a modifier into a ZWJ sequence — that renders a stray colour square beside the glyph. `tabs` adds top-level siblings to "Emoji" (stickers, GIFs) whose `content` replaces the body.
+
+## Reactions and the message menu
+
+```tsx
+<ReactionPicker selected={mine} onSelectEmoji={react} onMorePress={openPicker} />
+
+<MessageContextMenu items={items} onSelect={run} selectedReaction={mine} onSelectReaction={react} onMoreReactions={openPicker}>
+  <MessageBubble … />
+</MessageContextMenu>
+```
+
+The viewer's own reaction is marked with **both** `aria-pressed` and `accessibilityState` — React Native has no concept of `aria-pressed` and react-native-web reads nothing else, so a toggle that sets one of the two is stateless on one platform.
+
+`MessageContextMenu` is a `DropdownMenu`: an anchored panel on a pointer, a bottom sheet on a phone, with Bloom's own row vocabulary (destructive colour, disabled, shortcuts). `items` is a prop and not a fixed list — which actions exist depends on who sent the message, how old it is and what the channel allows, and a menu that hid its own rows would be deciding policy the app owns. Drive it from a long-press or a right-click with the controlled `open`.
+
+## Accessibility
+
+Every control is named (`Attach`, `Emoji`, `Camera`, `Record a voice message`, `Send`), and `labels` translates all of them — a glyph-only button has no other name.
+
+**The mic and the send disc both stay mounted for the cross-fade**, so the hidden one leaves the accessibility tree: `aria-hidden` for react-native-web and `importantForAccessibility="no-hide-descendants"` for React Native. Setting one of the two hides it on one platform only, and the symptom is a composer that announces "Send" and "Record a voice message" side by side while only one of them does anything.
+
+`pointerEvents` on those layers is a **prop**, never a style entry — react-native-web drops it from a style object silently, and a hidden layer that still takes the press is a send button that fires on an empty draft.
+
+## Motion
+
+State colours 150ms; the mic ↔ send cross-fade 220ms; the recording dot pulses on a 1s clock (CSS keyframes on web, a reanimated loop on native). Everything snaps under reduced motion. No press or scale feedback on any control.
+
+## Props
+
+### `ChatComposer`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` / `defaultValue` / `onValueChange` | `string` | `''` | The draft. |
+| `onSend` | `(value) => void` | — | Send button and the keyboard. |
+| `sendOn` | `'enter' \| 'mod-enter'` | `'enter'` | Which keystroke sends on web. |
+| `maxLines` / `minLines` | `number` | `6` / `1` | The field's growth range. |
+| `placeholder` | `string` | `'Message'` | |
+| `disabled` | `boolean` | `false` | Greys the bar; no callback fires. |
+| `notice` / `noticeIcon` | `ReactNode` / icon | — | Replaces the input row. |
+| `banner` | `ReactNode` | — | Usually one or more `ComposerBanner`. |
+| `attachments` / `onRemoveAttachment` | `ChatComposerAttachment[]` / `(id) => void` | — | |
+| `leading` / `emojiSlot` / `recorder` | `ReactNode` | — | Slots. |
+| `onAttachPress` / `onEmojiPress` / `onCameraPress` | `() => void` | — | Draw the matching default control. |
+| `onMicPress` / `onMicPressIn` / `onMicPressOut` | `() => void` | — | Press-and-hold lives here. |
+| `canSend` | `boolean` | derived | Forces the send disc. |
+| `suggestions` / `suggestionKind` / `activeIndex` / `onActiveIndexChange` / `onSelectSuggestion` | | | The list above the bar. |
+| `onEscape` / `onEditLast` | `() => void` | — | Escape, and ↑ on an empty draft. |
+| `showKeyboardHint` | `boolean` | `false` | The hint line under the bar (web). |
+| `inputRef`, `onFocus`, `onBlur`, `labels`, `style`, `testID`, `accessibilityLabel` | | | |
+
+### The other parts
+
+`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).
+`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`.
+`ReactionPicker` — `emojis`, `selected`, `onSelectEmoji`, `onMorePress`, `moreLabel`, `size`, `surface`, `emojiLabel`.
+`MessageContextMenu` — `items`, `onSelect`, `reactions`, `selectedReaction`, `onSelectReaction`, `onMoreReactions`, `open`/`defaultOpen`/`onOpenChange`, `label`.
+
+All of them take `style` and `testID`.

package/docs/chat-list.mdx

@@ -0,0 +1,332 @@
+---
+title: Chat List
+description: The conversations screen — rows with previews and unread state, folders, stories, search and the swipe actions behind each row.
+order: 64
+---
+
+# Chat List
+
+```tsx
+import {
+  ArchivedRow,
+  ChatFolderTabs,
+  ChatList,
+  ChatListItem,
+  ChatListItemSkeleton,
+  ChatSearchField,
+  ChatSearchResults,
+  GroupAvatar,
+  HighlightedText,
+  NewChatButton,
+  StoriesRow,
+} from '@oxy.so/bloom/chat-list';
+```
+
+Everything a messaging app's first screen needs. It builds on
+[`chat-indicators`](./chat-indicators.mdx) — the presence dot, the delivery
+ticks, the unread badge, the typing dots and the story ring are all from there,
+and nothing is reimplemented here.
+
+Every string is a PROP. No component in this family reads the clock, formats a
+duration, pluralises a count or decides what "recently" means: `time` arrives as
+`"12:41"` or `"Yesterday"`, an attachment arrives as `"Voice message 0:12"`, and
+a typing line arrives as `"Ana is typing…"`. The app owns the locale.
+
+## `ChatListItem`
+
+```tsx
+<ChatListItem
+  name="Mirela Antunes"
+  avatar="https://…/mirela.jpg"
+  status="online"
+  verified
+  time="12:41"
+  preview={{ sender: 'You', text: 'Sent the floor plan over' }}
+  outgoingStatus="read"
+  onPress={() => router.push('/chats/mirela')}
+/>
+```
+
+Two densities:
+
+| `density` | height | avatar | padding | name / preview |
+| --- | --- | --- | --- | --- |
+| `comfortable` (default) | 72 | 48 | 16 | `headline` / `body` |
+| `compact` | 56 | 36 | 12 | `body` / `body-2` |
+
+`comfortable` is the phone conversations screen; `compact` is the narrow pane of
+a desktop split view and the search results. A one-line row (no `preview`) keeps
+the same height, so a list never develops a ragged rhythm.
+
+### The preview line
+
+Exactly one shape wins, in this order:
+
+```tsx
+<ChatListItem preview={{ draft: true, text: 'about the deposit — can we' }} />
+<ChatListItem preview={{ attachment: { kind: 'voice', label: 'Voice message 0:12' } }} />
+<ChatListItem preview={{ sender: 'You', text: 'on my way' }} />
+<ChatListItem preview={{ sender: 'Pau', text: 'Meeting at the car park at seven' }} />
+```
+
+- **A draft** turns the line into an italic `Draft:` in the negative colour
+  followed by what was typed. It beats everything, including an attachment —
+  a half-written reply is the thing you came back for.
+- **An attachment** draws its glyph beside the label. The glyph comes from
+  `kind` (`photo`, `video`, `voice`, `audio`, `file`, `sticker`, `gif`,
+  `location`, `contact`, `poll`); the WORDS come from `label`, always, because
+  "Photo" is a translation and a duration is a format.
+- **A sender prefix** (`sender`) is the muted `"You: "` or a member's name in a
+  group, and is dropped on a draft (two lead-ins compete).
+
+`typingLabel` replaces the whole line with bouncing dots and that text:
+
+```tsx
+<ChatListItem name="Inés Bordoy" typingLabel="typing…" unreadCount={3} />
+```
+
+### The right column
+
+The time sits over the states: the mute bell, the pin, then EITHER the unread
+badge OR the delivery ticks of your own last message.
+
+**Those two are mutually exclusive, and the badge wins.** If their message is
+the last one in the conversation, yours is not in this row and has no status to
+report — so `unreadCount={3}` with `outgoingStatus="read"` draws the badge and
+no ticks. `unreadDot` counts as unread for the same rule. The time turns accent
+while there is something unread, except on a muted chat.
+
+### Groups
+
+```tsx
+<ChatListItem
+  name="Tramuntana Hikers"
+  kind="group"
+  faces={[{ source: a, name: 'Nuria' }, { source: b, name: 'Pau' }, { name: 'Ivet' }]}
+/>
+```
+
+`faces` draws a `GroupAvatar` cluster instead of one avatar. A group has no
+presence dot: "online" is a property of a person, and a dot on a cluster of four
+claims it about whichever face it lands on.
+
+`kind` also picks the marker beside the name — `channel` a megaphone, `bot` a
+robot, `group` a pair of figures — and `verified` beats all three. Pass `marker`
+for your own node.
+
+### Actions
+
+```tsx
+const actions = {
+  left: [{ key: 'read', label: 'Read', icon: RiCheckDoubleLine, tone: 'accent' }],
+  right: [
+    { key: 'mute', label: 'Mute', icon: RiNotificationOffLine },
+    { key: 'archive', label: 'Archive', icon: RiArchiveLine, tone: 'accent' },
+    { key: 'delete', label: 'Delete', icon: RiDeleteBinLine, tone: 'negative' },
+  ],
+};
+
+<ChatListItem name="Ana" swipeActions={actions} onAction={(key) => run(key)} />
+```
+
+One list, two affordances:
+
+- **Touch** — dragging right uncovers `left`, dragging left uncovers `right`. The
+  row travels with the finger and snaps open past 40% of the pane, closed below;
+  while a pane is open, pressing the row closes it rather than opening the chat.
+  The gesture fails on vertical travel, so a list scroll never becomes a swipe.
+- **Web** — the same actions appear as icon buttons over the right column on
+  hover and on keyboard focus, because a drag is undiscoverable with a mouse.
+  They are hidden entirely under `@media (hover: none)`.
+
+`swipeEnabled` defaults to "on wherever the platform is not web"; set it to
+`false` to keep the hover buttons and drop the gesture.
+
+`tone` paints the pane: `accent`, `negative` (delete), or the default neutral.
+
+### Accessibility
+
+The row is ONE target with ONE name, and its content is hidden from assistive
+technology. A pin, a bell, a badge and a pair of ticks are four states no text on
+the row carries, so the name says all of them:
+
+> Ana Ferrer, Verified, Draft: see you at eight, 12:41, 3 unread messages, Muted, Pinned
+
+Pass `accessibilityLabel` to replace it whole (a translated row), or `labels` to
+translate just the words this family supplies (`draft`, `pinned`, `muted`,
+`verified`, `channel`, `bot`, `group`).
+
+With `href` the row is a `link`; with `onPress` alone it is a `button`; with
+neither it is not a control at all. `selected` is `aria-current` on web and
+`accessibilityState.selected` on native.
+
+## `ChatList`
+
+```tsx
+<ChatList
+  sections={[
+    { key: 'pinned', title: 'Pinned', chats: pinned },
+    { key: 'all', title: 'All', chats: all },
+  ]}
+  selectedId={openChatId}
+  onChatPress={openChat}
+  onChatAction={(key, id) => run(key, id)}
+  archived={{ count: 6, onPress: openArchive }}
+  header={<ScreenHeader />}
+/>
+```
+
+`chats` is the shorthand for one unlabelled section. `archived` pins the archive
+row above the first section — it is a destination, not a conversation, so it
+never sorts in among them.
+
+`header` and `footer` are where the search field, the stories row and the folder
+tabs go; putting them inside the list is what makes the whole screen scroll as
+one.
+
+It MAPS every chat, which is right for the few hundred a phone shows. For a
+longer list render `ChatListItem` yourself inside a virtualised list — every row
+prop is on `ChatSummary` and `ChatList` holds no list state of its own.
+
+`loading` draws `ChatListItemSkeleton` rows at the same geometry and marks the
+region `aria-busy`, so "loading" is announced once rather than eight times.
+`empty` replaces the built-in empty state; `labels.emptyTitle` /
+`labels.emptyDescription` just reword it.
+
+## `ChatFolderTabs`
+
+```tsx
+<ChatFolderTabs
+  folders={[
+    { key: 'all', label: 'All', unreadCount: 15 },
+    { key: 'unread', label: 'Unread', unreadCount: 4 },
+    { key: 'groups', label: 'Groups', unreadCount: 12 },
+    { key: 'channels', label: 'Channels', unreadCount: 148, muted: true },
+    { key: 'bots', label: 'Bots' },
+  ]}
+  value={folder}
+  onValueChange={setFolder}
+  accessibilityLabel="Chat folders"
+/>
+```
+
+A horizontally scrolling tablist with a 2px accent underline under the selected
+tab, flush with the strip's hairline. Controlled with `value`, uncontrolled with
+`defaultValue` (or neither, which selects the first folder).
+
+**Why not `CategoryBar`.** The two look adjacent and are not: `CategoryBar` is an
+ICON over a label — its `icon` is required and it sizes and tints it — it carries
+no per-item count, and it marks the selection with a heavier label rather than an
+underline. Adding a badge slot and an icon-less mode would make one component
+answer two shapes. Both are `role="tablist"`, so an app that wants icon
+categories still has one.
+
+The count goes into the tab's NAME ("Unread, 4 unread"), because the badge is a
+bare number with no label of its own, and the badge itself is hidden from the
+reader so the tab does not announce it twice.
+
+## `StoriesRow`
+
+```tsx
+<StoriesRow
+  stories={stories}
+  own={{ avatar: me.avatar }}
+  onStoryPress={openStory}
+  onOwnPress={addStory}
+/>
+```
+
+"Your story" first with a `+` badge, then the rest with the UNSEEN ones before
+the seen (`seenLast`, on by default) — the point of the row is what is new, and a
+seen ring holding its place pushes the new ones off the right edge. The reorder
+is a STABLE sort, so two unseen stories keep the order you gave them; `state:
+'none'` counts as seen.
+
+Names sit under the rings, one line, clipped to the ring's footprint. Each ring
+is named `"<name>'s story"`, and the caption under it is hidden so the name is
+announced once.
+
+## `ChatSearchField` and `ChatSearchResults`
+
+```tsx
+<ChatSearchField value={query} onChangeText={setQuery} onClear={() => setQuery('')} />
+<ChatSearchResults query={query} results={results} onResultPress={open} />
+```
+
+A 40-tall pill: search glyph, input, and a clear button once there is text.
+Pressing anywhere on the pill focuses the input; focus takes the border, with no
+size change, so nothing reflows.
+
+**Why not `Search` or the music library's field.** [`Search`](./search.mdx) is a
+`TextField` with a floating LABEL — taller, and a label above a one-word search
+box is chrome a chat header has no room for.
+[`music-library`](./music-library.mdx)'s field is the right geometry but it is 48
+tall with a Browse toggle and a divider baked in, and reusing it would make a
+messaging screen import the music library's whole module graph for a pill.
+
+`ChatSearchResults` groups hits by `kind` in a fixed order — Chats, Messages,
+Contacts — keeping your order inside each group, and DROPS an empty group rather
+than printing a heading over nothing. Each row is the compact chat row with the
+matched run of the name and of the detail marked.
+
+### `HighlightedText`
+
+```tsx
+<HighlightedText text="José Ferrer" query="jose" />
+```
+
+Matching folds case AND accents, so `jose` finds `José` — but the runs are sliced
+out of the ORIGINAL string, never the folded one, so what is drawn is exactly
+what was passed in. (Folding is not length-preserving: a combining mark
+disappears, which is why the offsets are mapped back through a per-character
+index instead of assuming the two strings line up.) `highlightRuns(text, query)`
+is exported for the same logic without the rendering.
+
+The match is marked with COLOUR, not a band: inside a one-line result a tinted
+background reads as a second badge beside the unread pill. Pass
+`highlightBackground` where the text has room.
+
+## `GroupAvatar`
+
+```tsx
+<GroupAvatar size={48} faces={[{ source: a }, { source: b }, { name: 'Rut' }]} />
+```
+
+Two to four faces packed into one avatar-sized cluster: diagonal at 62% for two,
+one-above-two at 55% for three, a 2×2 rosette at 48% for four. A longer array is
+truncated; ONE face renders as a plain avatar at the full size, so a group that
+lost a member does not suddenly draw a lone disc in the corner.
+
+Every face carries a hairline ring in the surface colour, which is what makes the
+overlap read as two discs rather than one silhouette — pass `ringColor` when the
+cluster sits on a card rather than the page.
+
+It is decorative by default. Inside a `ChatListItem` the row's own name already
+says which group this is; pass `accessibilityLabel` when it stands alone.
+
+## `NewChatButton`
+
+```tsx
+<NewChatButton onPress={startChat} />
+<NewChatButton extended onPress={startChat} accessibilityLabel="New chat" />
+```
+
+It IS Bloom's [`Fab`](./fab.mdx) — placement, sizing, the minimize behaviour that
+follows a tab bar and the web/native fork all come from there. This only fixes
+the glyph and the name, so every messaging screen spells the action the same way
+instead of each one picking an icon. Every `Fab` prop passes through.
+
+`extended` promotes it to the pill with `accessibilityLabel` as its text, which
+is the one place the name is also the label.
+
+## Exported helpers
+
+| | |
+| --- | --- |
+| `highlightRuns(text, query)` | the matched/unmatched runs, accent-folded |
+| `groupSearchResults(results)` | hits bucketed by kind, empty groups dropped |
+| `sortStories(stories)` | unseen first, stable |
+| `hasUnread(count, dot)` | the rule the badge-vs-ticks precedence is built on |
+| `CHAT_ROW_GEOMETRY` | the two density rungs, as numbers |
+| `CHAT_ATTACHMENT_ICONS` | the glyph per attachment kind |
+| `CHAT_SEARCH_KINDS` | the group order |