@oxy.so/bloom 2.10.0 → 2.11.0

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 |

package/docs/chat-people.mdx

@@ -0,0 +1,277 @@
+---
+title: Chat People
+description: Contacts with an A–Z rail, picked-people chips, group creation, member roles, channel posts and the story viewer.
+order: 65
+---
+
+# Chat People
+
+```tsx
+import {
+  ContactRow,
+  ContactList,
+  SelectedChipsRow,
+  NewGroupForm,
+  MemberRow,
+  MemberList,
+  ChannelPostCard,
+  StoryViewer,
+  StoryProgressBars,
+} from '@oxy.so/bloom/chat-people';
+```
+
+The surfaces a messaging app has BESIDE the conversation: who you can talk to,
+who is in a group, what a channel broadcast looks like, and the story viewer.
+
+**Every time here is a pre-formatted string** — `"last seen recently"`,
+`"12:41"`, `"2 h"`. Your app owns the locale, the timezone and what "recently"
+means; a component that reads the clock is wrong for every user who is not in
+the timezone the data came from.
+
+## `ContactRow`
+
+```tsx
+<ContactRow id="ana" name="Ana Restrepo" subtitle="online" status="online" onPress={open} />
+<ContactRow id="ana" name="Ana Restrepo" selected={picked} onSelectedChange={pick} />
+<ContactRow id="ana" name="Ana Restrepo" actionLabel="Invite" onAction={invite} />
+```
+
+The trailing affordance is DERIVED from the handlers by default — a checkbox
+with `onSelectedChange`, an action button with `onAction`, nothing otherwise.
+`trailing` (`'none' | 'chevron' | 'checkbox' | 'action'`) overrides it, and
+`trailingSlot` replaces it with your own node.
+
+| prop                    | decides                                                 |
+| ----------------------- | -------------------------------------------------------- |
+| `status`                | the presence dot on the avatar (`chat-indicators`)        |
+| `subtitle`              | the quiet second line — a handle, a last-seen string      |
+| `actionDone`            | swaps the button for a quiet "Added" mark                 |
+| `size`                  | `'medium'` 44px avatar (default), `'small'` 36 for a picker |
+
+### Selection is ONE target
+
+When the row is a checkbox row, the **row itself** carries `role="checkbox"` and
+`aria-checked`, and the mark inside it is drawn, not a Bloom `Checkbox`. Nesting
+one would put a second `role="checkbox"` inside the first — two hit areas that
+disagree about which the user meant, and a screen reader announcing the same
+control twice. The mark is a circle, not a square, so it is not mistaken for the
+settings checkbox it is not.
+
+## `ContactList`
+
+```tsx
+<ContactList
+  sections={[{ letter: 'A', contacts: [...] }, { letter: 'K', contacts: [...] }]}
+  activeLetter="A"
+  height={480}
+  onContactPress={open}
+  onJumpToLetter={(letter) => track(letter)}
+/>
+```
+
+Section headings PIN while their own rows scroll under them, through
+`stickyHeaderIndices` — react-native-web implements the same prop the native
+`ScrollView` does, so one spelling works on both platforms. `position: sticky`
+would pin on web and do nothing at all on native, which is the shape of bug
+nothing in jest can see.
+
+The rail down the right edge scrolls the list itself when it can (it measures
+each section with `onLayout`) and always reports the letter through
+`onJumpToLetter`, so an app driving a virtualised list gets what it needs. **A
+letter with no section does nothing** — a rail showing the whole alphabet over
+six sections must not jump to whatever happens to be nearest. It appears
+automatically for 2+ sections; `showIndex` forces it either way.
+
+`indexLetters` replaces the rail's contents; `CONTACT_ALPHABET` is A–Z plus `#`,
+with `#` LAST — it is the least-used target and the bottom of the rail is where
+the thumb naturally lands.
+
+Empty sections are dropped from the list and from the rail.
+
+## `SelectedChipsRow`
+
+```tsx
+<SelectedChipsRow people={picked} onRemove={unpick} />
+<SelectedChipsRow people={picked} layout="wrap" onRemove={unpick} />
+```
+
+`layout="scroll"` (the default) is one row that scrolls sideways: a picker whose
+chip row grows downwards pushes the field and the list it is filtering off the
+screen as you type. `layout="wrap"` is for a sheet with the room.
+
+The × is its own button named "Remove Ana Restrepo". The chip is not pressable —
+there is nothing else it could do, and a chip that removes on any press removes
+people who were only being read.
+
+## `NewGroupForm`
+
+```tsx
+<NewGroupForm
+  name={name}
+  onNameChange={setName}
+  nameMaxLength={64}
+  description={about}
+  onDescriptionChange={setAbout}
+  onPickPhoto={pickPhoto}
+  members={picked}
+  onRemoveMember={unpick}
+  onAddMembers={openPicker}
+/>
+```
+
+**The counter and the limit are one number.** `nameMaxLength` is both the
+denominator drawn under the field and the input's own `maxLength`; setting them
+from two constants is how a counter ends up saying 64 while the field stops at
+50, and nothing catches it, because both halves look right on their own.
+
+The counter goes amber at 90%, not at 100%: the input has already stopped
+accepting characters by then, so a warning that arrives at the limit is telling
+the user about something that has already happened. `nameCounterTone(length,
+max)` is exported.
+
+## `MemberRow` and `MemberList`
+
+```tsx
+<MemberList
+  members={members}                 // { id, name, role?: 'owner' | 'admin' | 'member', subtitle? }
+  title="412 members"
+  search={query}
+  onSearchChange={setQuery}
+  onAddMembers={openPicker}
+  onPromote={promote}
+  onRestrict={restrict}
+  onRemove={remove}
+/>
+```
+
+**The badge is a word, not a colour.** `owner` is amber and `admin` is the
+accent, but each also carries a glyph and its own text — a role told apart by
+hue alone is a role one reader in twelve cannot read at all, and "who can remove
+me from this group" is not a detail to encode in a tint. `roleLabel` overrides
+the text ("Creator").
+
+The per-member menu appears only when at least one of `onPromote` / `onRestrict`
+/ `onRemove` is given, and lists only the actions that exist. `trailingSlot`
+replaces it with your own.
+
+**The search field filters nothing.** Which members match "an" depends on how
+you normalise accents, whether you search handles and phone numbers, and whether
+the list is paged from a server — none of which a component can guess, and all
+of which it would get wrong silently. Pass the filtered `members`; `emptyState`
+covers the search that found nobody.
+
+## `ChannelPostCard`
+
+```tsx
+<ChannelPostCard
+  channelName="Coast Weather Watch"
+  channelAvatar={avatarUrl}
+  verified
+  pinned
+  time="12:41"
+  media={<Image source={{ uri }} style={{ width: '100%', height: 180 }} />}
+  views="12.4K"
+  forwards="318"
+  comments="128 comments"
+  onComments={openComments}
+  onShare={share}
+  reactions={<ReactionChips />}
+>
+  Swell picks up after midnight along the whole north shore.
+</ChannelPostCard>
+```
+
+**Counts are strings.** "12.4K" is a locale decision and an abbreviation policy
+your feed already made; a card that formats numbers itself would disagree with
+the list it sits in, in the one place a reader compares them side by side.
+
+The eye and forward glyphs are decorative — the counts beside them are text, so
+the glyph would announce a second time. The names for both pairs live in
+`labels`, on the row that holds each pair.
+
+The footer buttons sit OUTSIDE the card's own press target, so opening a post
+and opening its comments are two targets rather than a race.
+
+## `StoryViewer`
+
+```tsx
+const [index, setIndex] = useState(0);
+
+<StoryViewer
+  stories={stories}                        // { id, media?, duration? }
+  index={index}
+  onNext={() => setIndex((i) => i + 1)}
+  onPrevious={() => setIndex((i) => Math.max(0, i - 1))}
+  onClose={close}
+  paused={held}
+  name="Saoirse Byrne"
+  avatar={avatarUrl}
+  time="2 h"
+  muted={muted}
+  onMutedChange={setMuted}
+  replyValue={reply}
+  onReplyChange={setReply}
+  onReplySend={send}
+  reactions={['❤️', '🔥', '😂']}
+  onReact={react}
+/>
+```
+
+`index` is CONTROLLED. The viewer never advances itself: `onNext` fires from the
+forward tap zone and from the progress strip running out, and you decide whether
+that means the next story, the next person, or closing.
+
+### The tap zones are not symmetric
+
+Forward is what a reader means nine times out of ten and must not require aim,
+so it gets two thirds of the width; back is a correction and gets one.
+`storyTapZone(x, width)` is exported for a surface measuring the gesture itself.
+Both zones are real `button`s with names, because a tap zone that is only a
+gesture is a story set a keyboard user cannot get through.
+
+### Hold-to-pause is yours
+
+A long press has to compete with whatever scrolling, swiping and dismissing the
+surface around the viewer does, and a component that claims it in isolation
+fights its own host. Bind the gesture and pass `paused`:
+
+```tsx
+<Pressable onLongPress={() => setHeld(true)} onPressOut={() => setHeld(false)}>
+  <StoryViewer paused={held} … />
+</Pressable>
+```
+
+## `StoryProgressBars`
+
+Exported on its own, for a viewer you are building yourself:
+
+```tsx
+<StoryProgressBars count={5} index={1} duration={5000} paused={held} onComplete={next} />
+<StoryProgressBars count={5} index={1} progress={0.4} />   // controlled
+```
+
+Everything before the current bar is full, everything after it is empty, and
+only the current one moves — `storyProgressFill(bar, index, progress)`, a pure
+function of three numbers, exported and tested as one. Writing that per-segment
+inside the map is how a viewer ends up drawing an empty bar for a story the user
+has already watched: a segment knows its own position and nothing about the
+sequence.
+
+Two modes, and the difference is who owns the clock. Pass `progress` and the
+strip draws what it is told and runs no timer (use this when a video already
+drives playback). Omit it and the strip animates 0→1 over `duration` and calls
+`onComplete`; `paused` freezes it where it is.
+
+**Reduced motion stops the ANIMATION, not the story.** The bar jumps to full and
+the `onComplete` timer still runs, so a story set still advances — a viewer that
+stops advancing under reduced motion strands the reader on story one with
+nothing to say anything was meant to happen.
+
+## What jest cannot see here
+
+`src/__tests__/ChatPeople.test.tsx` reads the emitted DOM through the real
+react-native-web, so it pins the checkbox row's role and state, the rail's names
+and its refusal to jump to an absent letter, the role badges, and both pure
+functions. It cannot see whether the sticky headings actually stick, whether the
+rail is reachable with a thumb, or whether the story chrome stays legible over a
+bright photo. Those are browser and device checks.