@oxy.so/bloom 3.6.0 → 4.0.0

package/docs/lead-score.mdx

@@ -0,0 +1,153 @@
+---
+title: LeadScoreCard
+description: How good a lead is and why — the verdict and the score on a tinted panel, and the factors that make it up on a neutral one.
+order: 126
+---
+
+# LeadScoreCard
+
+```tsx
+import { LeadScoreCard } from '@oxy.so/bloom';
+
+<LeadScoreCard
+  score={82}
+  accessibilityLabel="Lead score for Larkspur Freight"
+  valueText="82 of 100, hot"
+  factors={[
+    { label: 'Fits the ideal profile', contribution: 24, detail: 'Logistics, 200–500 people' },
+    { label: 'No decision-maker', contribution: -9, detail: 'One contact, no budget owner' },
+  ]}
+  trend={{ label: '+8 against last week', direction: 'up' }}
+/>
+```
+
+## Two panels in one card
+
+It is drawn the way Bloom draws a SCORE — `chart-cards`' `SleepScoreCard` is the
+register, and the `BesideTheReference` story puts the two in one shot at the
+same width:
+
+| panel | what it holds |
+| --- | --- |
+| header | washed in the band's tone: the quiet `body-medium` label over the `title-1-medium` verdict with the band's glyph, the trend as a quiet icon-and-label line, and the ring — 132 across, CENTRED, the score at `display-4-medium` inside it |
+| factors | neutral, padded on the LEFT only so the rules run to its right edge: one row per factor — a 10 mark, the label and its detail as one reading line, and the signed contribution right-aligned and tabular |
+
+The card itself is 10 padding and a 10 gap; both panels take `radius-16` inside
+its `radius-20`.
+
+## There are no bars
+
+Every factor used to be a `Meter`. Five bars stacked down a card is a chart
+pretending to be a measurement — a CHART colours by WHICH datum it is, and these
+are all the same datum at different sizes — and it was the single thing that
+made this card read as a dashboard from another product rather than as Bloom.
+
+A contribution is a NUMBER. It is printed (`+24`, `-9`), it is tabular so the
+column lines up, and the MARK beside the label says which way it pulls: the
+accent for a factor that pushes the score up, the quiet graphical neutral for
+one that pulls it down. Five bars also announced `progressbar` five more times;
+`LeadScore.test.tsx` now asserts that the card emits exactly ONE, and that it is
+the ring.
+
+The one measurement on the card is the score, and it is a ring, because there is
+one of it.
+
+## The ring
+
+`MeterRing` from `stat-bar` owns the geometry and the FLAT `aria-value*` props.
+The arc is the meter's own accent fill whatever band the score falls in: that is
+what a meter means in Bloom — how much of one thing there is. A green ring
+claims "healthy", which is not the claim "82 of 100" makes.
+
+**The TRACK is read off the header wash, not from `stat-bar`'s default rail.**
+That rail is a neutral computed for the page; on a tinted panel it reads as a
+foreign grey ring rather than as the empty part of this one. `resolveLeadScorePaint`
+takes it from `hairlineOn(theme, header)`.
+
+It is 132 across, centred, with the number at `display-4-medium` — larger than
+the verdict word beside it. At 72 in a corner it was a widget, and the one fact
+the card exists to state was smaller than the label.
+
+## The tint is FLATTENED before anything is derived from it
+
+The header is `resolveAccentColors(colors, tone, 'subtle').background` —
+composited over the card, not painted raw.
+
+The `*Subtle` members are `rgba()` on purpose, and painting one renders
+correctly. What does not work is DERIVING off it: every reader in
+`styles/color-contrast.ts` treats a colour as opaque, so a text rung or a
+hairline read from `rgba(16 185 129 / 0.24)` is computed against solid emerald
+and lands on a panel that is nothing like it. Measured here before the flatten:
+the header's secondary label came back at **1.96:1** against its own panel in
+dark mode, and the card rendered perfectly.
+
+So `flattenOver` composites the tint ONCE (parse-and-re-emit, the same move
+`chip/hue-colors.ts` makes for a translucent hue), the panel paints the
+flattened colour, and every rung is read off that — the two can then never
+disagree. Flattened, the worst secondary label over the whole
+`preset × mode × band` sweep measures 6.1:1.
+
+Both panels publish themselves with `SurfaceLevelProvider` and
+`surfaceFillVars`, so anything nested inside either one steps off the right
+parent.
+
+## The band is the VERDICT, and it is the tint
+
+`cold` / `warm` / `hot` map to the `info` / `warning` / `success` tones in
+`LEAD_SCORE_BAND`. The tone paints the header wash and the band's glyph; the
+word beside it is the reading colour of that wash. A pill saying the same word
+would say it twice.
+
+**`hot` is the SUCCESS tone, not the error one.** A hot lead is the good
+outcome; reading temperature as danger is exactly the confusion a tone
+vocabulary exists to prevent.
+
+The band is DERIVED from the score as a fraction of `max`
+(`LEAD_SCORE_THRESHOLDS`: warm at 0.4, hot at 0.7), so a 0–100 score and a 0–5
+one land in the same places. Boundaries are inclusive upward — exactly 0.4 is
+warm — because a score sitting on a threshold has reached it. An app with its
+own thresholds passes `band`, which moves the WASH with it; `bandLabel` renames
+the verdict without changing the tone.
+
+A non-positive `max` has no scale to divide, so the band is `cold` rather than
+`NaN`: the card renders data it did not choose instead of throwing over it.
+
+## The name is a required prop
+
+`accessibilityLabel` is required at the type level. ARIA computes no name for a
+`progressbar` from its contents, and the ring draws a bare number — so without
+it the card announces "progress bar, 82%" and never says whose lead it is. A
+heading beside the ring does not name it either; that is a SIBLING.
+
+`valueText` is what a screen reader says instead of the raw number: without it
+`82` of `100` is announced as a percentage, which is right by accident here and
+wrong the moment `max` is 5.
+
+react-native-web reads `aria-*` and never `accessibilityValue`, so a ring that
+set only the object announces its role and no value — in a screenshot, in a
+browser and in a prop-level test it looks perfect. `LeadScore.test.tsx` reads
+the emitted attributes instead.
+
+## The factors
+
+Each factor is a signed contribution. `factorLine` joins the label and its
+`detail` into ONE string, because the row truncates as a sentence: two
+independently shrinking texts drop the label to "Fits the ide…" while the detail
+beside it still has room.
+
+A zero factor draws a row with `0` in it rather than being hidden: "this counted
+for nothing" is a fact about the lead. The signed number is printed in the
+READING colour, not a status one — the sign is what says which way it went, and
+a red `-9` beside a grey mark would be two spellings of one fact.
+
+`factorsLabel` is the panel's header row, above the first factor and sharing its
+rule.
+
+## The trend
+
+`trend` is a pre-formatted label plus a direction. The card does no arithmetic
+and does not know what "last period" means — a week, a quarter, since the deal
+opened — so it draws what it is handed with the direction's arrow, as a quiet
+line on the wash. `LEAD_SCORE_TREND` carries the glyph and nothing else: the
+arrow is the direction, and the card keeps one tinted thing rather than three
+competing ones.

package/docs/loading.mdx

@@ -23,7 +23,7 @@ so the variant is gone.
 import { Loading } from '@oxy.so/bloom';
 
 <Loading variant="spinner" />
-<Loading variant="spinner" size="large" />
+<Loading variant="spinner" size="lg" />
 <Loading variant="spinner" text="Loading…" />
 <Loading variant="spinner" text="Saving…" iconSize={32} />
 ```
@@ -59,7 +59,7 @@ For native-tailwind users, `className` overrides `color`:
 | Prop | Type | Description |
 |------|------|-------------|
 | `variant?` | `'spinner' \| 'top' \| 'inline'` | Default: `'spinner'`. |
-| `size?` | `'small' \| 'medium' \| 'large'` | Default: `'medium'`. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | Default: `'md'`. |
 | `color?` | `string` | Spinner color. Defaults to theme primary. |
 | `className?` | `string` | NativeWind class. Overrides `color`. |
 | `style?` | `ViewStyle` | Container style. |

package/docs/mail-compose.mdx

@@ -0,0 +1,123 @@
+---
+title: Mail Compose
+description: Writing a message — recipients as chips inside a Field contract, the cc/bcc reveal, and a frame that is a sheet on a phone and a docked panel on a desktop.
+order: 66
+---
+
+# Mail Compose
+
+`MailRecipientField` is one addressing row, `MailComposeHeader` is the block of
+them plus the subject, and `MailComposeSurface` is the frame around the whole
+thing.
+
+```tsx
+import { MailComposeHeader, MailComposeSurface } from '@oxy.so/bloom';
+
+<MailComposeSurface
+  variant="docked"
+  header={<MailComposeHeader to={to} onToChange={setTo} subject={subject} onSubjectChange={setSubject} />}
+  attachments={pending}
+  onAttachmentRemove={remove}
+  toolbar={<NoteEditorToolbar {...editor} />}
+  onSend={send}
+  onAttach={pick}
+  onDiscard={discard}
+  onClose={close}
+>
+  <YourEditor />
+</MailComposeSurface>;
+```
+
+## What this family does NOT write
+
+- **A rich-text engine.** `children` is a slot. The body is your editor.
+- **A formatting toolbar.** `toolbar` is a slot, and the toolbar Bloom ships is
+  `note-editor`'s `NoteEditorToolbar`. A second one grown here would be a second
+  one to keep in step with the first, in a library where the whole point is that
+  there is one of each thing.
+- **An attachment strip.** `attachments` goes to `chat-composer`'s
+  `ComposerAttachmentStrip`, imported rather than rebuilt. A pending attachment
+  is a pending attachment: a thumbnail, an upload ring and a remove, with the
+  ring drawn from ONE rounded-rect path helper. Two strips mean two rings that
+  close at different angles.
+- **An overlay.** There is no `position: fixed` here and no portal. See below.
+- **An address parser.** `onSubmit` hands you the typed string. Only the app
+  knows its directory and its address grammar.
+
+## The surface positions nothing
+
+`variant="sheet"` draws no frame at all — no surface, no border, no radius —
+because whatever presented it already did. Mount it as a `Dialog`'s child in its
+sheet placement, or inside a `BottomSheet`, or as a full-screen route.
+
+`variant="docked"` is the desktop panel: it paints the card rung, its own
+hairline and its own radius, and it publishes that fill with
+`SurfaceLevelProvider` so the chips, hairlines and quiet text inside it step off
+what is really behind them. WHERE it sits is your shell's decision.
+
+A compose window that placed itself would fight the app's layout in one app out
+of three, and Bloom already owns exactly one overlay stack — this is not a
+second one.
+
+`minimized` collapses a docked panel to its title bar. It is ignored by `sheet`,
+where there is nothing to minimise into.
+
+## `MailRecipientField` is a `Field` member
+
+It calls `useFieldMembership()`, which is the only supported way to join a
+`Field` — the four decisions it resolves each have a direction that is silently
+wrong the other way round (`composition.mdx` §Field).
+
+The choice this family makes is `labelPlacement: 'adjacent'`. The "To" in the
+gutter is the words the reader reads AS the control, so it keeps its own name
+and an enclosing `Field` only fills a gap. A `stacked` control would announce
+the field's label while the eye reads "To", which is exactly the disagreement
+that rule exists to prevent.
+
+Invalidity COMBINES, it does not replace: `recipientsInvalid(recipients, own)`
+is `own || any recipient invalid`. A field told it is invalid stays invalid
+however good its recipients look, and a good field holding one rejected address
+is not a good field. The chip that is wrong paints the error tone through
+`resolveAccentColors`, so the `Field`'s error text and the chip that caused it
+say the same thing.
+
+## Why this is not the generic tag input
+
+A recipient is a PERSON: a face, a name, an address and a verdict on whether
+that address will deliver. A tag has none of those four, and a tag field that
+grew them would be a contact picker wearing a tag field's name.
+
+What the two share is the part worth sharing — they are both built on `Chip` and
+they both answer the `Field` contract the same way — so if they ever converge,
+unifying them is a rename rather than a rewrite. Until then they are two things.
+
+## The cc/bcc reveal is not a plain toggle
+
+`copiesOpen(visible, cc, bcc)` forces the rows open whenever a cc or a bcc
+arrives non-empty, whatever the reveal last said. A reply-all whose copies were
+hidden is a message going to people the writer cannot see, and that is not a
+state `MailComposeHeader` will render.
+
+## Every row is a gutter, not a box
+
+The four rows — `To`, `Cc`, `Bcc`, `Subject` — share one label column
+(`MAIL_COMPOSE_GEOMETRY.gutter`) and one hairline, so the chips and the subject
+sit on a single left margin.
+
+This is deliberately not four `TextField`s. A stack of bordered boxes draws five
+rectangles where the writer is filling in one form, and the recipient chips
+would then be a control inside a box inside a box. `TextField`'s chrome is right
+for a field in a form and wrong for a mail header, which is the only place in
+this family where a base-layer control was passed over on purpose.
+
+## Known gaps
+
+- `Chip`'s remove button is named "Remove" and takes no per-chip name, so a
+  recipient chip's remove announces "Remove" rather than "Remove Mireia Solans".
+  Closing it means a `closeLabel` prop on `Chip`, which is a base-layer change
+  this family did not make. `MailComposeStrings.removeRecipient` is here and
+  ready for it.
+- The suggestion list renders inline under the row, not in a floating surface.
+  Anchoring it would make the field a `Popover` owner, and a popover inside a
+  docked panel inside a dialog is a stacking question worth answering once, on
+  purpose, rather than in passing here.

package/docs/mail-list.mdx

@@ -0,0 +1,220 @@
+---
+title: Mail List
+description: The inbox — one row at two densities, day sections, the markers a message carries, and the bulk-selection bar the list mounts itself.
+order: 64
+---
+
+# Mail List
+
+The list half of a mail client: `MailRow` is one thread in the inbox, `MailList`
+is the screen around it, and `MailSelectionBar` is what appears when rows are
+checked.
+
+```tsx
+import { MailList, groupMailByDay } from '@oxy.so/bloom';
+
+<MailList
+  sections={groupMailByDay(mail, { now: Date.now() })}
+  selectedId={openId}
+  onMailPress={setOpenId}
+  rowActions={[{ key: 'archive', label: 'Archive', icon: RiArchiveLine }]}
+  checkedIds={checked}
+  onCheckedIdsChange={setChecked}
+  bulkActions={bulk}
+/>;
+```
+
+## Two densities, one component
+
+| | `comfortable` | `compact` |
+| --- | --- | --- |
+| height | 72 (a floor) | 40, exact |
+| padding | 16 / 12 vertical | 12 / 0 |
+| avatar | 48 | 24 |
+| lines | sender + time, then subject + snippet | one |
+
+`comfortable` is the phone inbox; `compact` is a desktop list, where the sender
+takes a 180px column that shrinks (never grows) down to 88 so a narrow pane
+gives the subject the space rather than clipping it.
+
+The phone rung is the same 72 tall with the same 48 avatar as a `chat-list` row,
+deliberately. A mail row and a conversation row are the same kind of object, and
+an inbox standing 16px taller per row than the messages screen reads as a
+different library. Two lines is what pays for it: the sender and the time share
+the first, the subject and the snippet the second, and everything that used to
+need a third line is either a mark or is said only in the row's name.
+
+There is no second row component for the desktop. Everything a compact row
+draws, a comfortable row draws too, and the whole difference is one geometry
+table in `shared.ts` — a density that forked into two files is a density that
+drifts, and the two then disagree about what a starred draft looks like.
+
+## The subject and the snippet are one `Text`
+
+At BOTH densities the subject and the snippet are a single string with a nested
+span, not two flex children. Two neighbouring flex children each want to be as
+wide as their content, and with a long one the result is either a row that
+pushes the list sideways or a subject clipped to nothing while the snippet keeps
+its full width. One string truncates where the line ends, which is the only
+behaviour that is right at every width.
+
+## Unread is the whole row
+
+`unread` moves the sender and the subject to semibold and moves every rung of
+text up one step — sender and subject to the primary colour, the snippet to the
+secondary one, the time to the accent. A read row sits on the quiet rungs.
+
+There is no dot. A dot is 8px of colour that survives neither truncation nor a
+colour-blind reader, and it has to be placed somewhere, which is how a row ends
+up with a dot, a bold name and a coloured time all saying the same thing once
+each. The weight change IS the state.
+
+Every colour comes from the fill the list was handed: the hovered row is
+`surfaceFillOn(theme, surface)`, the selected row is one step further, and the
+text rungs are `surfaceTextOn` floored against the same fill. So a list inside a
+card and a list on the page each step off their own background, and neither
+picks a ramp stop that only matches one page colour.
+
+## Labels are data, so `labels` is the data prop
+
+In this domain a "label" is a mailbox label, which is a thing the message
+carries — so `labels` is that array and the i18n strings prop is `strings`. It
+is the one place this family departs from the library's usual spelling, and it
+departs deliberately: `labels={['Work']}` reading as translation strings would
+be worse than the inconsistency.
+
+A label's colour is an `AccentTone`, never a hex. The chip resolves it through
+`resolveAccentColors`, so a label reads the way a status badge reads and
+survives a preset change.
+
+`maxLabels` counts MARKS, and what a mark is depends on how much line there is:
+
+- **One-line row** (`compact`): every mark is a chip, and the overflow chip is
+  one of them (`visibleLabels`). At 2 with four labels the row draws one label
+  and a `+3`, never two labels and a `+2` in the space of three.
+- **Two-line row** (`comfortable`): the first label keeps its name as a chip and
+  the rest become 8px dots of their own tone (`labelMarks`). A second chip costs
+  more of the subject's width than a second label is worth, and the dot still
+  says "there is another one of these". Labels past `maxLabels` are drawn
+  nowhere at all.
+
+Either way `composeMailRowName` reads every label aloud, which is what makes
+dropping the names on screen a layout decision rather than a loss.
+
+## The star is drawn only where it is a control
+
+No `onStarredChange`, no star. A star that looks like a button and does nothing
+is worse than no button, and on a two-line row it is also the widest thing
+competing with the subject. The state is not lost: the row's name says "Starred"
+either way, which is the reading an 18px marker was ever going to give.
+
+## Two affordances, and neither is an icon at rest
+
+A pointer hovers; a thumb drags. Nothing is drawn inside a phone row at rest.
+
+```tsx
+<MailList
+  rowActions={[archive, snooze, remove]}            // the pointer's rail
+  rowSwipeActions={{ left: [archive], right: [snooze, remove] }}  // the thumb's
+  onMailAction={(key, id) => run(key, id)}
+/>
+```
+
+`actions` + `actionsPlacement` is the rail:
+
+- `hover` — over the right column, revealed on hover and on keyboard focus, and
+  hidden outright under `@media (hover: none)`. The default on web.
+- `inline` — always drawn. A kiosk or a tablet list with no pointer and no
+  gesture; never a phone.
+- `none` — drawn nowhere. The default on NATIVE.
+
+`swipeActions` is the drag, through `SwipeRow` — the library's one
+implementation of that gesture, shared with `chat-list` (see
+[Swipe Row](/docs/swipe-row) for the thresholds and the pane geometry). It is on
+wherever the pointer is coarse (`useSwipeAvailable()`); `swipeEnabled` forces it
+either way.
+
+The two props are separate because they answer different questions. `actions` is
+the whole menu a pointer gets at once; a pane is ONE action a thumb reaches in
+one direction. Archive right, delete left is a convention your app owns, not one
+this family should guess from an array's order.
+
+The rail's buttons are SIBLINGS of the row's link, never children. A button
+inside an anchor is invalid HTML, and every "Archive" click would open the
+message.
+
+### Reaching the actions without a swipe
+
+A drag has no tab stop and no announced name. Three paths, and the row carries
+all of them:
+
+- **A pointer** — the rail, which appears on `:focus-within` as well as on
+  hover, so a keyboard reaches it.
+- **A touch reader** — every rail and pane action is on the row's
+  `accessibilityActions`, once per key, which is the rotor. react-native-web
+  drops that prop and rightly: there the rail is already in the tab order.
+- **A closed pane is hidden from assistive technology entirely**, rather than
+  leaving invisible buttons for the focus ring to disappear into.
+
+## The selection bar is not a component you place
+
+Give `MailList` an `onCheckedIdsChange` and three things happen at once: the
+rows grow checkboxes in place of their avatars, the bar mounts the moment
+something is checked, and select-all / clear / per-row toggles all resolve
+inside the list.
+
+It is one decision because they are one feature. A bar the app had to place by
+hand is a bar the app can forget, and a selection mode with no bar is a
+selection with no way out of it — the rows stay checked and nothing on screen
+says so or offers to undo it.
+
+The bar paints the accent's SUBTLE pair, which is the one fill in the palette
+that says "a mode is on" without competing with the selected row's own fill.
+Its checkbox is `indeterminate` while some but not all rows are checked, so one
+control answers both "how many" and "press me to take the rest".
+
+## Day sections
+
+`groupMailByDay` is a pure function, not a prop.
+
+```tsx
+import { groupMailByDay } from '@oxy.so/bloom';
+
+const sections = groupMailByDay(mail, {
+  now: Date.now(),
+  formatDate: (date) => intl.format(date),
+});
+```
+
+"Today" and "Yesterday" are CALENDAR days in the reader's own time zone, not
+24-hour windows: a message from 23:50 last night is yesterday's at 00:10, which
+is what a person means by it. Mail with no `date` falls into one trailing
+untitled bucket rather than being dropped.
+
+It takes `now` and the formatter as parameters because a component that read the
+clock is a component whose sections cannot be pinned by a test — the same call
+has to be the same sections in June and in December.
+
+## What this family does not do
+
+- **It does not virtualise.** It maps every row, which is right for the few
+  hundred a mailbox screen shows. For more, render `MailRow` yourself inside
+  your own virtualised list: every row prop is on `MailSummary` and nothing here
+  holds list state.
+- **It does not format a clock or a date.** `time` arrives formatted.
+- **It does not own the mailbox tree.** That is `Sidebar`'s `tree` prop and
+  `SidebarFolder`; the `WithMailboxTree` story shows the pairing.
+
+## Accessibility
+
+The row is ONE target with ONE composed name, and its content is hidden from
+assistive technology. A star, a paperclip, a thread count and four labels are
+states no text on the row carries, so `composeMailRowName` says all of them in
+reading order — "Mireia Solans, Roof survey, The surveyor came back…, 14:02,
+Unread, Has attachment, 4 messages, Work". It says every label and every state
+the row decided not to draw, which is what lets the row draw fewer of them.
+
+The open row is `aria-current` on web and `accessibilityState.selected` on
+native — `aria-selected` belongs to a tab or an option, and a message row is
+neither. While `loading` the region is `aria-busy` and the placeholders are
+hidden, so "loading" is announced once rather than eight times.

package/docs/mail-thread.mdx

@@ -0,0 +1,118 @@
+---
+title: Mail Thread
+description: One conversation — a collapsible message with a real header, the middle of a long thread folded behind one control, and the trimmed-content toggle.
+order: 65
+---
+
+# Mail Thread
+
+The reading half of a mail client. `MailMessage` is one message, collapsed or
+open; `MailThread` is the stack; `MailAddressLine` is a `to`/`cc` line with its
+overflow; `MailQuoteToggle` is the "show trimmed content" control.
+
+```tsx
+import { MailThread } from '@oxy.so/bloom';
+
+<MailThread
+  subject="Roof survey"
+  messages={messages}
+  quickReply={<ReplyBox />}
+/>;
+```
+
+## The body is a slot, and stays one
+
+`MailMessage` takes `children`. It renders no HTML, no rich text and no
+sanitizer, because a mail body is markup from a stranger: what is safe to render
+depends on the app's threat model, its CSP, its image proxy and whether it is on
+a device or in a browser. A component that answered that would be answering it
+wrong for two apps out of three.
+
+What Bloom owns around the slot is the frame: the header, the indent (the body
+starts under the sender's NAME, not under the avatar — `MAIL_BODY_INSET`), the
+attachment row, the three replies, and the trimmed-content toggle.
+
+## Collapsed and open share one header row
+
+Both states draw the same avatar in the same leading column at the same
+`paddingVertical`. The only thing that changes is what the text column holds and
+whether a body is drawn under it.
+
+That is the whole reason the transition does not leave a gap. A collapsed state
+written as its own compact row — its own padding, its own avatar size — jumps by
+a few pixels every time it opens, and the eye reads that as the list resettling
+rather than as the message opening. One geometry table, two states.
+
+Collapsed shows the sender, a one-line preview, a paperclip if there are
+attachments, and the time. Open shows the sender, the `to`/`cc` lines, the full
+date, the body, the toggle, the attachments and the replies.
+
+## The middle folds, not the tail
+
+A thread longer than `collapseAfter` (default 4) hides everything between the
+FIRST message and the LAST TWO behind one "N earlier messages" control.
+
+The first message is what the thread is about and the last two are what it is
+about now, so those three are the ones a reader needs. Folding from the top
+instead would hide the first, which is the one that sets the subject up.
+`collapseAfter={0}` turns folding off. The arithmetic is `collapseThread`, a
+pure function, so a test can pin which entries survive without rendering
+anything.
+
+## The newest message is open
+
+Uncontrolled, `MailThread` opens the last message and closes the rest —
+`defaultExpandedIds`. That is the arrangement a reader arriving at a thread
+wants every time, so it is the default rather than a prop the app has to
+remember. A thread that opened everything would make the reader scroll past what
+they have already read to reach what they have not; one that opened nothing
+would make every arrival a press.
+
+`expandedIds` takes it over for a deep link to one message, or an "expand all".
+
+## An address line's overflow is a control, not an ellipsis
+
+A `to` line truncated with "…" tells the reader there are more recipients and
+gives them no way to find out who. On a message they are about to reply-all to,
+that is the one fact that changes what they write. So `MailAddressLine` collapses
+the surplus into a `+3` button that reveals the rest IN PLACE, and the names
+stay selectable text either way. `maxVisible` counts names; the button is beside
+them, not one of them.
+
+It is reusable on its own — a reading pane's summary, a send confirmation — and
+it owns no state it does not have to: pass `expanded` and it is controlled.
+
+## The trimmed-content toggle
+
+The quoted tail of a message is the app's: where the quote starts, what counts
+as trimmed, and how that markup renders are questions only your parser can
+answer. Pass it as `trimmed` and this family owns the presentation.
+
+It draws as a short dotted lozenge rather than as a labelled button, because it
+sits at the end of the message's own words where a fourth labelled control would
+read as a fourth action beside Reply and Forward. Its accessible name FLIPS with
+the state — "Show trimmed content" / "Hide trimmed content" — because a toggle
+whose name does not change is a toggle a screen-reader user cannot read the
+state of.
+
+## Attachments here are not the composer's attachments
+
+A received attachment has a name, a size and a download. A pending one has a
+thumbnail, an upload ring and a remove. They are different objects with
+different affordances, so the thread draws its attachments as `Chip`s (pressable,
+outlined, a file glyph, "name · 248 KB") and `mail-compose` reuses
+`chat-composer`'s `ComposerAttachmentStrip` for the pending kind. Sharing one
+component between them would mean a strip that draws a progress ring for a file
+that finished arriving last Tuesday.
+
+## Accessibility
+
+The disclosure is a `button` carrying `aria-expanded` AND the native
+`accessibilityState.expanded` — react-native-web reads only the first and React
+Native folds the first back into the second, so both spellings are written. Its
+name is "Expand message: Mireia Solans", not "Expand": a thread of eight
+identically-named buttons is a thread a screen-reader user cannot navigate.
+
+The star, the `menu` slot and the three replies are SIBLINGS of the disclosure,
+never children. A button inside a button is invalid, and the press target would
+be ambiguous.

package/docs/menubar.mdx

@@ -32,7 +32,7 @@ import {
       </MenubarItem>
       <MenubarItem onPress={open}>Open…</MenubarItem>
       <MenubarSeparator />
-      <MenubarItem variant="destructive" onPress={closeWindow}>
+      <MenubarItem tone="danger" onPress={closeWindow}>
         Close window
       </MenubarItem>
     </MenubarContent>

package/docs/motion.mdx

@@ -81,3 +81,25 @@ Jest and `tsc` catch none of these. Verify in a real **foregrounded** tab — a
 hidden tab freezes plain CSS transitions too, which mimics "the class didn't
 apply". Read the class attribute, or set `transitionProperty: 'none'` before
 reading computed styles.
+
+### Static Storybook and Reanimated's CommonJS bridge
+
+A live Vite preview can animate correctly while its static build crashes in
+Reanimated's DOM updater at `Object.keys(node.props)`. Measured here: the static
+bundle left the optional `require('react-native-web/dist/exports/StyleSheet/compiler/createReactDOMStyle')`
+in Reanimated's ESM `webUtils.web` module. The browser's missing `require` was
+swallowed by its `try/catch`, leaving the DOM compiler undefined; a DOM element
+then reached the legacy component-props branch. Dev `optimizeDeps` had converted
+the same call successfully. Storybook's `build.commonjsOptions` now enables
+`transformMixedEsModules` and converts `try/catch` requires only for installed
+`react-native-web/dist/*` modules. Other optional-peer boundaries remain intact.
+The source gate guards that wiring; emitted bundle inspection and a real static
+open-overlay check are required to verify it. Reanimated remains the real package.
+
+The same static audit exposed a separate Expo bootstrap omission: `expo-image`
+read `globalThis.expo.NativeModule` after tree shaking discarded the empty web
+`ensureNativeModulesAreInstalled` bridge and its polyfill import. Expo marks the
+polyfill as side-effectful but not that bridge. Storybook narrowly marks the real
+`expo-modules-core/src/ensureNativeModulesAreInstalled.ts` module as side-effectful;
+it neither mocks Expo nor creates a replacement global. A minimal production
+bundle confirmed the installer precedes the first NativeModule read.