@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/message-bubble.mdx

@@ -0,0 +1,279 @@
+---
+title: Message Bubble
+description: The transcript — bubbles, runs, reactions, replies, separators and the service rows a person-to-person chat repeats on every screen.
+order: 64
+---
+
+# Message Bubble
+
+```tsx
+import {
+  CallSummaryRow,
+  DateSeparator,
+  MessageBubble,
+  MessageGroup,
+  MessageList,
+  SystemMessage,
+  TypingBubble,
+  UnreadSeparator,
+  bubblePositions,
+  groupMessages,
+  senderNameColor,
+} from '@oxy.so/bloom/message-bubble';
+```
+
+The bubble SHELL, its text and its metadata. Rich media — images, voice notes,
+files, polls — is a slot (`media`), not this family's job: pass whatever draws
+it and the bubble clips it to its own radius.
+
+Everything is a prop. No component here reads the clock: `"12:41"`,
+`"Yesterday"`, `"4 min"` and `"12.4K"` arrive already formatted, because what
+counts as "today" depends on a timezone and a locale the component cannot see.
+
+## `MessageBubble`
+
+```tsx
+<MessageBubble direction="incoming" text="Doors open at half six." time="18:02" />
+<MessageBubble direction="outgoing" text="On my way." time="18:04" status="read" />
+```
+
+| prop                      | decides                                                                      |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| `direction`               | `'incoming'` a neutral surface · `'outgoing'` the theme accent fill           |
+| `position`                | `'single' \| 'first' \| 'middle' \| 'last'` — which corner is cut             |
+| `text` / `children`       | the body; `children` wins                                                     |
+| `media`                   | the rich-media slot, edge to edge inside the radius                           |
+| `metaOverlay`             | float the meta over the media on a translucent pill (default on media-only)   |
+| `tail`                    | the SVG notch on the cut corner — OFF by default                              |
+| `senderName`              | the coloured name line (a group; `MessageGroup` normally draws it instead)    |
+| `senderColorSeed`         | what `senderNameColor` hashes; defaults to `senderName`                       |
+| `replyTo` / `onPressReply`| the quote block, and what pressing it does                                    |
+| `forwardedFrom`           | the "Forwarded from …" line                                                   |
+| `editedLabel`             | the "edited" mark in the meta row                                             |
+| `time` / `status`         | the meta row: a pre-formatted time and the delivery ticks                      |
+| `channelViews` / `authorSignature` | a channel post's view count and signature                           |
+| `reactions`               | the pills under the bubble; `onToggleReaction`, `onAddReaction`               |
+| `pending` `failed` `deleted` `selected` `highlighted` | the five states                            |
+| `onPress` `onLongPress` `onContextMenu` `onDoublePress` `onSwipeReply` | the gestures              |
+| `maxWidth`                | default `'78%'`                                                               |
+| `labels`                  | every English string this family draws                                        |
+
+### Colour
+
+`outgoing` is the theme accent. The text on it is chosen by CONTRAST rather
+than assumed: `primaryForeground`, white or near-black, whichever clears AA over
+the accent this preset resolved to. The meta row inside it is the most
+transparent mix of that on-colour that STILL clears AA — quiet, but never the
+2.8:1 a flat 60% opacity gives you on a mid-blue.
+
+`incoming` is the card in light mode and neutral-800 in dark, with a hairline in
+light mode only: a card on a near-white page has no edge of its own, a
+neutral-800 bubble on a neutral-950 page already does.
+
+### Grouping geometry
+
+Radius 18 on every corner, except ONE: the last bubble of a run cuts its own
+side to 4. `'first'` and `'middle'` stay fully round, which is what makes a run
+read as one block with a single spout instead of a column of identical
+lozenges. `MessageGroup` and `MessageList` compute `position` for you;
+`bubblePositions(count)` is exported for a list that renders its own rows.
+
+`tail` draws the notch on that corner. It is off by default and drawn OUTSIDE
+the bubble box, so turning it on re-lays out nothing.
+
+### The meta row tucks
+
+Time, "edited", views and the ticks sit bottom-right INSIDE the bubble, on the
+same line as the last words when they fit and on a line of their own when they
+do not. It is a wrapping flex row with an `auto` left margin on the meta — the
+one spelling of "float after the text" that Yoga and the browser agree on. On a
+media-only bubble it becomes a translucent pill over the media (`metaOverlay`).
+
+### States
+
+```tsx
+<MessageBubble direction="outgoing" text="Queued." status="sending" pending />
+<MessageBubble direction="outgoing" text="Did not send." failed onRetry={retry} />
+<MessageBubble direction="incoming" deleted />
+<MessageBubble direction="incoming" text="…" selected onPress={toggle} />
+<MessageBubble direction="incoming" text="…" highlighted />
+```
+
+`pending` dims. `failed` washes the fill towards the error colour and offers
+`onRetry` beside the bubble. `deleted` replaces everything with one italic line
+and no meta. `selected` bands the whole ROW — selection is a property of the
+message and the band has to reach the avatar gutter — and `highlighted` flashes
+that same band once, which is what a jump-to-message lands on. Under reduced
+motion the flash appears without animating.
+
+### Interaction
+
+`onPress`, `onLongPress` and `onDoublePress` work on both platforms;
+`onContextMenu` is web only (right-click, defaulted for you) and `onSwipeReply`
+is native only. That last split is deliberate: on web the same horizontal drag
+is text selection, and a pan handler that won that race would take away the one
+thing people do with a transcript in a browser.
+
+`onDoublePress` suppresses the second `onPress` of a pair, so "double-press to
+react" does not also toggle selection twice.
+
+### Entities
+
+`text` is scanned for links, `@mentions` and `#hashtags`. Without
+`renderEntity` they are simply painted in the accent; with it you decide:
+
+```tsx
+<MessageBubble
+  direction="incoming"
+  text="Ping @marcel about #gear"
+  renderEntity={(entity) =>
+    entity.type === 'mention' ? <Mention handle={entity.text} /> : undefined
+  }
+/>
+```
+
+Return `undefined` for a span you want the default paint for. `messageEntities`
+and `splitMessageText` are exported and pure if you want the ranges yourself.
+
+## `MessageGroup`
+
+```tsx
+<MessageGroup direction="incoming" senderName="Ana Restrepo" avatarSource={ana}>
+  <MessageBubble direction="incoming" text="First." />
+  <MessageBubble direction="incoming" text="Second." time="12:41" />
+</MessageGroup>
+```
+
+A run of consecutive messages from one sender. It computes each child's
+`position`, puts the avatar at the run's BOTTOM edge (beside the last bubble,
+the one the tail hangs off) and draws the sender name once above the first.
+Spacing is 2px inside a run and 8px between runs, so the block reads as one
+utterance and the gap reads as a turn.
+
+`showAvatar={false}` in a 1:1 chat — an avatar repeated beside every message of
+a two-person conversation is noise.
+
+### `senderNameColor(seed, theme)`
+
+The per-sender hue, exported. It hashes the seed onto the eight chart hues,
+which rotate with the theme preset, then walks that hue's ramp (600 → 900 in
+light, 400 → 100 in dark) to the first stop that clears AA over the incoming
+bubble. A single stop per mode is not enough: the hues are not equally light,
+and the yellow at 400 lands at 2.8:1 on a neutral-800 bubble where the indigo
+clears comfortably.
+
+Deterministic: same seed, same theme, same colour. Seed on a stable id
+(`senderId`), not on a display name someone can change.
+
+**Eight hues means collisions.** Two seeds in a group land on the same hue
+roughly one time in eight — the `Group conversation` story shows exactly that,
+with two of its three speakers in the same green. If a chat has to guarantee
+distinct colours, assign them yourself and pass `senderColor`.
+
+## `MessageList`
+
+```tsx
+<MessageList items={messages} showAvatars={false} showSenderNames={false} />
+```
+
+A plain vertical stack — date separators, the unread rule, service rows and runs
+— from one array. **Not virtualised**, and that is the contract: right for a
+thread you have just opened, wrong for a year of history.
+
+For a long history, render the parts yourself:
+
+```tsx
+const entries = useMemo(() => groupMessages(items), [items]);
+
+<FlatList
+  data={entries}
+  keyExtractor={(entry) => entry.key}
+  renderItem={({ item: entry }) =>
+    entry.kind === 'date' ? <DateSeparator label={entry.label} />
+    : entry.kind === 'unread' ? <UnreadSeparator />
+    : entry.kind === 'system' ? <SystemMessage text={entry.item.system} />
+    : <MessageGroup direction={entry.direction} senderName={entry.messages[0]?.item.senderName}>
+        {entry.messages.map(({ item, position }) => (
+          <MessageBubble key={item.id} {...item} position={position} />
+        ))}
+      </MessageGroup>
+  }
+/>
+```
+
+Every one of those is a standalone export that takes props and holds no list
+state.
+
+### `groupMessages(items)`
+
+Pure, exported. It inserts a `DateSeparator` when `dateKey` changes, an
+`UnreadSeparator` above an item with `unreadBefore`, and breaks a run on a
+change of `senderId`, a change of `direction`, or anything BETWEEN two messages
+— a day, the read marker, a service line. That last one matters: "Ana joined the
+group" between two of Ana's messages is a break, and a grouper that ignored it
+would round the corners of a run that no longer looks like one.
+
+## Separators and service rows
+
+```tsx
+<DateSeparator label="Today" />
+<UnreadSeparator />
+<SystemMessage text="Ana Restrepo joined the group" />
+<SystemMessage text="You pinned a message" icon={<RiPushpinLine width={12} height={12} fill={color} />} />
+<CallSummaryRow direction="incoming" outcome="missed" title="Missed voice call" time="09:41" />
+<TypingBubble senderName="Ana Restrepo" avatarSource={ana} label="Ana is typing…" />
+```
+
+`CallSummaryRow` splits direction from outcome on purpose: the ARROW says which
+way the call went and the COLOUR says whether it connected, because a missed
+incoming call and a missed outgoing call are different events and one red glyph
+for both would lose that.
+
+`TypingBubble` draws no text, so nothing can name it by contents — `label`
+(default "Typing…") is its accessible name, and an empty string is not one.
+
+## Accessibility
+
+The bubble is ONE node with a composed name: sender, text, time, then what a
+sighted reader gets from colour and a tick glyph — "Read", "Not sent",
+"Selected". The ticks inside it are hidden (`label=""`), because announcing the
+delivery state twice per message is the price of announcing it in words at all.
+
+With `selected` defined the bubble becomes a TOGGLE and carries both spellings —
+`aria-pressed` for web and `accessibilityState.selected` for native — and so
+does every reaction pill. React Native has no pressed state and react-native-web
+ignores `accessibilityState`; missing either half is silent on one platform.
+
+Pass your own `accessibilityLabel` to replace the composed one entirely.
+
+## Reaction pills
+
+```tsx
+<MessageBubble
+  direction="outgoing"
+  text="Booked it."
+  reactions={[{ emoji: '🎸', count: 2, mine: true }]}
+  onToggleReaction={(emoji) => toggle(emoji)}
+  onAddReaction={openPicker}
+/>
+```
+
+They overlap the bubble's bottom edge by 8px, which is what makes them read as
+attached to the message rather than as a row of their own, and they wrap. `mine`
+paints the pill in the accent and flips its pressed state. `onAddReaction` adds
+the `+` pill at the end; leave it out and there is none.
+
+## Localisation
+
+Every English string is in `labels`:
+
+```tsx
+<MessageList
+  items={items}
+  labels={{ deleted: 'Se eliminó este mensaje', forwardedFrom: 'Reenviado de' }}
+/>
+```
+
+`DateSeparator`, `UnreadSeparator`, `SystemMessage`, `CallSummaryRow` and
+`TypingBubble` take their text directly, since every string they draw is one
+the app already had to format.

package/docs/message-media.mdx

@@ -0,0 +1,330 @@
+---
+title: Message Media
+description: Everything that goes inside a chat bubble besides text — photos, albums, video, voice notes, files, locations, contacts, polls, stickers, GIFs, link previews — plus the info panel's media and file grids.
+order: 64
+---
+
+# Message Media
+
+```tsx
+import {
+  ContactMessage,
+  DocumentGrid,
+  FileMessage,
+  GifMessage,
+  ImageMessage,
+  LinkPreviewMessage,
+  LocationMessage,
+  MediaAlbum,
+  PollMessage,
+  SharedMediaGrid,
+  StickerMessage,
+  VideoMessage,
+  VoiceMessage,
+} from '@oxy.so/bloom/message-media';
+```
+
+Thirteen blocks that go INSIDE a bubble, and none of them draw one. The shell —
+grouping, the tail, the meta row, reactions — is `message-bubble`'s job; these
+fill its `media` slot, or stand on their own in a panel.
+
+## The two things every block has
+
+**`tone`.** `'incoming'` (default) is the neutral bubble, `'outgoing'` the accent
+one. It is not styling: half of these surfaces sit on a saturated fill where
+`colors.textSecondary` lands anywhere between 1.1:1 and 3:1 depending on the
+preset, so a block that reads page colours is illegible on one of the two
+bubbles and nobody notices until a preset changes. `resolveMessageMediaPaint()`
+takes the bubble fill and MIXES the bubble's own on-colour up from it until the
+result clears 4.5:1 — so the muted label is muted by the same amount on every
+preset, in both modes, and is never unreadable.
+
+```tsx
+<ImageMessage tone="outgoing" source={photo} />
+<FileMessage tone="incoming" name="Lease.pdf" sizeBytes={2_560_000} />
+```
+
+`onColor` and `bubbleColor` override the two ends for an app painting its own
+bubble; everything between them is re-derived, so the contrast guarantee holds.
+
+**`radius`.** The BUBBLE owns the corners. A photo flush with the bubble's edge
+has to take the bubble's radius on the side it touches, or the two draw two arcs
+a pixel apart. Default 16; `message-bubble` passes its own.
+
+## `ImageMessage`
+
+```tsx
+<ImageMessage
+  source={photo}                    // URL, {uri}, require(), or an Oxy file ID
+  aspectRatio={4 / 3}
+  placeholderColor="#5b6f7a"        // the flat colour a blurhash resolves to
+  spoiler
+  onPress={(index) => open(index)}  // index is always 0, so one handler serves a photo and an album
+/>
+```
+
+| prop                              | decides                                                             |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `aspectRatio` / `maxWidth` / `maxHeight` | the frame; the photo is fitted inside both caps, never cropped |
+| `placeholderColor`                | the fill shown until the photo paints. Bloom decodes no blurhash — that needs a decoder dependency; pass the average colour the decoder gives you |
+| `spoiler` / `spoilerLabel` / `onReveal` | hides the photo until pressed. Revealing LATCHES               |
+| `state` / `progress` / `onCancel` / `onRetry` | `'sending'` draws the ring, `'failed'` the retry row     |
+
+**The spoiler is opaque on native.** On web it is a translucent wash with a
+`backdrop-filter` blur, which is the look. A real blur on native needs
+`expo-blur`, an optional peer this family does not take, and a translucent cover
+with no blur behind it shows the photo it exists to hide — so native covers it
+completely. A spoiler that half-works is not a spoiler.
+
+## `MediaAlbum`
+
+```tsx
+<MediaAlbum
+  items={photos}          // 2–10 cells; past `maxTiles` the last takes a "+N"
+  width={260}
+  onPress={(index) => open(index)}
+/>
+```
+
+The packed grid, laid out by `albumLayout(count, width, { gap, radius, maxTiles })`,
+which is exported so an app (or a test) can read the geometry without rendering:
+
+| items | rows      | shape                                      |
+| ----- | --------- | ------------------------------------------- |
+| 2     | `[2]`     | two squares                                 |
+| 3     | `[1, 2]`  | one banner over two halves                  |
+| 4     | `[2, 2]`  | 2 × 2                                       |
+| 5     | `[2, 3]`  |                                             |
+| 6     | `[3, 3]`  |                                             |
+| 7     | `[2, 2, 3]` |                                           |
+| 8     | `[2, 3, 3]` |                                           |
+| 9     | `[3, 3, 3]` |                                           |
+| 10    | `[3, 3, 4]` |                                           |
+
+Cells are ABSOLUTE rectangles with integer widths that sum to the frame exactly.
+A flex row rounds each child independently, and the last cell in a row of three
+ends up a pixel short of a ROUNDED outer corner — which reads as a rendering
+fault rather than as a gap. Only the group's four outer corners are rounded; a
+cell in the middle is square on every side.
+
+A `video` cell draws a play glyph and a duration pill; `spoiler` works per cell.
+
+## `VideoMessage`
+
+```tsx
+<VideoMessage source={poster} duration={187} sizeBytes={25_800_000} onPress={play} />
+<VideoMessage source={poster} variant="videoNote" duration={31} position={19} />
+```
+
+`thumbnail` is a poster with the shared `PlayButton` (`media-controls`,
+`inverse`) centred on it and a duration pill. `watched` dims the pill and adds a
+tick rather than removing anything — a watched video is still a video.
+
+`videoNote` is the round short note: the circle is a mask and the ring around it
+is `position / duration`.
+
+**The play disc is drawn, not pressed.** The whole poster is the button; the
+`PlayButton` inside it carries no handler and is hidden from the pointer and
+from assistive tech. A second `role="button"` nested in the first swallows the
+press on web and is read twice by a screen reader.
+
+## `VoiceMessage`
+
+```tsx
+<VoiceMessage
+  samples={amplitudes}          // any length — resampled to `barCount`
+  duration={14}
+  position={position}
+  playing={playing}
+  onPlayPress={toggle}
+  onSeek={setPosition}
+  rate={rate} onRateChange={setRate}   // 1 → 1.5 → 2 → 1
+  unplayed={position === 0}
+  transcript="Left the keys with the neighbour."
+/>
+```
+
+`samples` are amplitudes 0..1, oldest first. Down-sampling takes the PEAK of
+each bucket, not the mean: a voice note is silence with peaks in it, and
+averaging flattens every recording into the same grey slab. Every bar has an 18%
+floor, so real silence is a short bar rather than a hole in the waveform.
+
+Played bars take the accent, unplayed ones the rail — two colours, NOT one at
+two opacities. An opacity composites against what is behind it, and behind it is
+the accent bubble half the time.
+
+The waveform is a `slider` (`accessibilityRole="adjustable"`) with flat
+`aria-value*` props, focusable on web, answering arrows / Home / End and the
+native `increment` / `decrement` actions. `seekPositionAt(x, width, duration)`
+is exported and clamps at BOTH ends — hit slop reports a negative `locationX`.
+
+The clock shows the LENGTH before playback starts and the ELAPSED position
+after. Two numbers side by side is a player's idiom; in a bubble the second one
+is chrome.
+
+## `FileMessage`
+
+```tsx
+<FileMessage name="Tenancy agreement.pdf" sizeBytes={2_560_000} onDownload={save} />
+<FileMessage variant="compact" name="Rents.xlsx" sizeBytes={831_488} transfer="downloading" progress={0.4} onCancel={stop} />
+```
+
+The kind comes from `fileKindFor(name, mimeType)` — the NAME first, because a
+`.csv` served as `text/plain` is still a spreadsheet to its sender. Ten kinds:
+`pdf doc sheet slides zip audio video image code other`, each with its own glyph
+and hue from the theme's status / accent roles.
+
+**The kind colour survives BOTH tones.** On the neutral bubble the disc is a
+light tint of the hue. On the accent bubble a tint of the hue would be a tint of
+a saturated fill, so the disc becomes a near-white plate and the hue is darkened
+onto it — rather than the colour being dropped because the bubble is coloured.
+
+The meta line is `"2.4 MB · PDF"`, formatted with `formatFileSize` from
+`file-upload` — the SAME formatter the uploader uses, extended with a gigabyte
+branch, so a size cannot read two ways in one app.
+
+The ring IS the button: the thing you press to cancel is the thing showing you
+how far it got.
+
+## `LocationMessage`
+
+```tsx
+<LocationMessage
+  title="Casa del Puerto"
+  address="Carrer de la Marina 118"
+  renderMap={({ width, height }) => <YourMapView width={width} height={height} />}
+/>
+<LocationMessage live liveUntilLabel="Live until 18:30" onStopSharing={stop} />
+```
+
+Bloom ships no map engine — a tile provider is a dependency, a key and a licence
+— so `renderMap` is the slot. Without it the frame draws a neutral grid, which
+is deliberately abstract: a fake coastline would be a map of somewhere.
+
+`live` swaps the pin for a pulsing dot (still under reduced motion — it reports
+"sharing", not "working", and the label already says so) and puts "Stop sharing"
+BELOW the frame rather than on it: it is destructive and must not be one mis-tap
+from "open the map". `liveUntilLabel` arrives pre-formatted; a component that
+reads the clock renders differently in every test and every timezone.
+
+## `ContactMessage`
+
+```tsx
+<ContactMessage name="Marta Ferreira" detail="+34 600 11 22 33" onMessage={chat} onAdd={save} />
+```
+
+Avatar, name, handle, and two EQUAL actions. "Message" and "Add" are the same
+size of decision, and ranking one with a filled button puts a second accent
+surface inside an accent surface. Only the actions are pressable.
+
+## `PollMessage`
+
+```tsx
+<PollMessage question="When should we do the handover?" options={options} onVote={vote} />
+<PollMessage question="…" multiple anonymous onVote={vote} />
+<PollMessage question="…" quiz voted options={[{ id: 'a', label: '…', votes: 3, correct: true }]} />
+```
+
+| prop                        | decides                                                          |
+| --------------------------- | ---------------------------------------------------------------- |
+| `multiple`                  | checkboxes, picks held locally until "Vote"                      |
+| `anonymous` / `quiz`        | labels on the question — they change what voting MEANS            |
+| `voted` / `showResults`     | bars and percentages replace the marks                            |
+| `totalVotes`                | defaults to the sum of `votes`                                    |
+
+Percentages come from `pollPercentages(votes, total?)`, which distributes the
+rounding remainder by largest fraction so the column sums to exactly 100.
+Rounding each share on its own gives three equal options 33/33/33 and two equal
+ones 51/51 — a poll that visibly cannot add up is a poll nobody believes. No
+votes at all is all zeroes, not an even split: "nobody voted" and "everyone
+agrees" are different facts. An explicit `total` LARGER than the votes cast is
+not inflated back to 100.
+
+Before the results an option is a `radio` / `checkbox` with `aria-checked`;
+after them it is a `progressbar` with its own name and the three `aria-value*`
+attributes, because pressing it no longer does anything. A quiz marks the right
+answer AND the viewer's wrong pick — hiding the right answer teaches nobody.
+
+## `StickerMessage` and `GifMessage`
+
+```tsx
+<StickerMessage source={sticker} accessibilityLabel="Sticker: grinning sun" />
+<GifMessage source={gif} aspectRatio={1.6} />
+```
+
+**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
+`contain`; cropping one cuts the drawing. The NAME matters more here than
+anywhere else — a sticker IS its meaning and there is no caption beside it, so
+pass the emotion rather than letting it announce "Sticker".
+
+A GIF is capped narrower than a photo (220 rather than 260) because they are
+usually low-resolution. The pill is the only thing that says the frame moves,
+which matters when it has not started — Android's `Image` decodes an animated
+GIF as a still unless the app enables the animated decoders in its Fresco
+config, so `playing={false}` plus the play glyph is the honest state there.
+
+## `LinkPreviewMessage`
+
+```tsx
+<LinkPreviewMessage
+  url="https://example.invalid/guides/moving-in"
+  siteName="Vila Nova Guide"
+  title="What to check before you sign a lease"
+  description="Damp, meters, deposits…"
+  image={cover}
+  layout="large"        // or "inline": a 56px thumb beside the text
+/>
+```
+
+**Why this is not `link-preview`'s `LinkPreviewCard`.** That card was read first
+and is the right component everywhere else; it is a `Card variant="outlined"` at
+`radius-20` painting `colors.text` / `colors.textSecondary` on `colors.card`.
+All three are PAGE colours. Dropped into an outgoing bubble it draws a
+page-coloured card on the accent fill — a second surface inside the message,
+with its own border and background, and a body colour that is a grey on a
+saturated fill. Giving it a tone, a palette and a no-chrome mode would be a
+different component wearing the same name. So the bubble's preview is its own
+block: no surface, an accent RULE down the left edge instead of a border, every
+colour from the tone's palette. Use `LinkPreviewCard` outside a bubble and this
+inside one.
+
+## `SharedMediaGrid` and `DocumentGrid`
+
+The two tabs of a chat's info panel.
+
+```tsx
+<SharedMediaGrid items={media} width={340} maxItems={9} onPressItem={open} onPressOverflow={seeAll} />
+<DocumentGrid items={files} onPressItem={open} onDownloadItem={save} />
+```
+
+`SharedMediaGrid` is the tight 3-column grid: square tiles, 2px gaps, radius 4 —
+a grid, not a row of cards. At three columns a 16px radius on every tile turns
+it into a pattern of gaps, and the outer corners belong to the panel. Column
+widths are integers summing to the width, the same arithmetic the album uses.
+"+N more" REPLACES the last tile so the grid stays rectangular.
+
+`DocumentGrid` is the files tab: a list of `FileMessage variant="compact"` rows,
+so the icons, colours, meta line and download ring are the ones the bubble draws.
+A second file-row implementation is a second place for the size format to drift.
+
+**The row's press target is the identity half only.** The download / cancel
+control beside it is its own button, laid out as a sibling — nesting it inside
+the row's `Pressable` would be a button inside a button (invalid HTML, and one
+action announced twice). `testID`-wise that is `<id>-open` for the row's press
+target and `<id>-row` for the box around both.
+
+## Exports
+
+Components aside, the family publishes the maths so an app can lay out against
+it: `albumLayout`, `albumRows`, `pollPercentages`, `formatVoteCount`,
+`resampleWaveform`, `seekPositionAt`, `nextPlaybackRate`, `fileKindFor`,
+`fileTypeLabel`, `resolveMessageMediaPaint`, `resolveBubbleColor`.
+
+## Images
+
+Every `source` accepts a full URL, an RN source object, a `require()` result, or
+a bare Oxy file ID resolved through the registered `ImageResolver` — the same
+rule `Avatar` uses, so one registration covers the whole family. A file ID with
+no resolver renders the placeholder rather than requesting a broken URL.