@oxy.so/bloom 5.3.0 → 5.4.1

package/docs/adoption-matrix.mdx

@@ -187,7 +187,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 10 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 4 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
-| `floating` | internal | universal | — | — | 17 | n/a¹ |  | reads | reads |
+| `floating` | internal | universal | — | — | 18 | n/a¹ |  | reads | reads |
 | `fonts` | `@oxy.so/bloom/fonts` + barrel | web fork | `fonts.mdx` | yes | 2 |  |  |  |  |
 | `frosted-icon-button` | `@oxy.so/bloom/frosted-icon-button` + barrel | web fork | `frosted-icon-button.mdx` | yes | 4 |  |  |  |  |
 | `glass` | internal | universal | `glass.mdx` | — | 2 |  | reads |  |  |
@@ -196,7 +196,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 12 |  |  |  | reads |
 | `hover-card` | `@oxy.so/bloom/hover-card` + barrel | web fork | `hover-card.mdx` | yes | 4 |  |  | reads | reads |
 | `icon-circle` | `@oxy.so/bloom/icon-circle` + barrel | universal | `icon-circle.mdx` | yes | 1 |  |  |  |  |
-| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 58 |  |  |  |  |
+| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 59 |  |  |  |  |
 | `image-aspect-ratio-cache` | `@oxy.so/bloom/image-aspect-ratio-cache` + barrel | universal | `image-aspect-ratio-cache.mdx` | yes | 1 |  |  |  |  |
 | `image-resolver` | `@oxy.so/bloom/image-resolver` + barrel | universal | `image-resolver.mdx` | yes | 8 |  |  |  |  |
 | `important-alerts-card` | `@oxy.so/bloom/important-alerts-card` + barrel | universal | `important-alerts-card.mdx` | yes | 1 |  |  |  |  |
@@ -206,7 +206,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `job-board` | `@oxy.so/bloom/job-board` + barrel | universal | `job-board.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  |  |  |  |
 | `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 2 |  |  |  |  |
-| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 8 |  |  |  |  |
+| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 9 |  |  |  |  |
 | `lead-score` | `@oxy.so/bloom/lead-score` + barrel | universal | `lead-score.mdx` | yes | 1 |  |  |  |  |
 | `link-preview` | `@oxy.so/bloom/link-preview` + barrel | universal | `link-preview.mdx` | yes | 3 |  |  |  |  |
 | `list` | `@oxy.so/bloom/list` + barrel | web fork | `list.mdx` | yes | 2 |  |  |  |  |
@@ -246,7 +246,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `order-confirmation` | `@oxy.so/bloom/order-confirmation` + barrel | universal | `order-confirmation.mdx` | yes | 1 |  |  |  |  |
 | `order-status` | `@oxy.so/bloom/order-status` + barrel | universal | `order-status.mdx` | yes | 1 |  |  |  |  |
 | `outline-nav` | `@oxy.so/bloom/outline-nav` + barrel | universal | `outline-nav.mdx` | yes | 2 |  |  |  |  |
-| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 14 |  |  |  |  |
+| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 15 |  |  |  |  |
 | `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 4 |  | reads |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 2 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
@@ -265,7 +265,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
 | `proof-of-delivery` | `@oxy.so/bloom/proof-of-delivery` + barrel | universal | `proof-of-delivery.mdx` | yes | 1 |  |  |  | reads |
 | `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 5 |  |  |  | reads |
-| `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 2 |  |  |  |  |
+| `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 3 |  |  |  |  |
 | `questionnaire` | `@oxy.so/bloom/questionnaire` + barrel | universal | `questionnaire.mdx` | yes | 1 | **adaptation** |  |  | **adaptation** |
 | `queue-panel` | `@oxy.so/bloom/queue-panel` + barrel | universal | `queue-panel.mdx` | yes | 3 |  |  |  | **adaptation** |
 | `radio` | `@oxy.so/bloom/radio` + barrel | universal | `radio.mdx` | yes | 3 | reads |  |  |  |
@@ -280,7 +280,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 4 | reads |  |  |  |
 | `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 9 | reads |  | reads |  |
 | `settings-list` | `@oxy.so/bloom/settings-list` + barrel | universal | `settings-list.mdx` | yes | 5 |  |  |  |  |
-| `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 9 |  |  |  | reads |
+| `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 10 |  |  |  | reads |
 | `shapes` | `@oxy.so/bloom/shapes` + barrel | universal | `shapes.mdx` | yes | 4 |  |  |  |  |
 | `shipment-request` | `@oxy.so/bloom/shipment-request` + barrel | universal | `shipment-request.mdx` | yes | 1 | **adaptation** |  |  |  |
 | `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 10 | n/a¹ |  |  | reads |
@@ -308,7 +308,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 5 |  | n/a¹ |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 16 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 341 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 343 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |

package/docs/ai-chat.mdx

@@ -69,6 +69,8 @@ Give the shell a sized parent — it fills it.
 - **A collapsible rail** — `sidebarCollapsed` publishes the state while the sidebar owns its width and transition. `sidebarWidth` and `collapsedSidebarWidth` are explicit column overrides only; omit them for a Bloom `Sidebar` so its FAB, insets and collapse animation determine the actual width. The shell does not clip that sidebar into a fixed 56px lane.
 - **`background` and `surface`** — `background` is any node, drawn above the shell's own background-full and below the sidebar, workspace and drawers; it is never interactive. The workspace paints background-full too, so pass `surface={false}` with it (that drops both) or the layer is covered exactly where the chat sits. When the layer belongs to the chat rather than the page, put it on `AiChatContainer` instead, which is the nearer slot and needs no opt-out.
 - **`scroll`** — what scrolls the page, `AppShell`'s contract. `container` (the default) fills the parent and the conversation scrolls inside the card. **`document`** (web) grows the page and lets the browser scroll it — the page's scrollbar, scroll restoration, the mobile address bar collapsing and `window.scrollTo` behave as on any page. See [Document scroll](#document-scroll). Native has no document and treats it as `container`.
+- **Native safe area** — Opt in with `<AiChatShell safeArea>` to add all four device insets to the shell frame and drawer content. The default remains off, and web geometry is unchanged. Inner `PageHeader` components use `safeArea={false}`; `BottomBar` automatically excludes the bottom inset already supplied by the shell. Device insets remain available to portaled dialogs. Screens do not need their own safe-area padding.
+
 - **What the shell publishes** — `useAiChatShell()` returns the shell's state to any descendant: `compact`, `navCollapsed`, `sidebarCollapsed`, `hasNav` / `hasPanel`, `documentScroll`, `openNav` / `closeNav` / `openPanel`, and **`navPresented`**.
 
   Below `lg` a closed drawer stays **mounted** — it is translated offscreen, not removed. The shell takes it out of reach itself: while closed, the nav drawer and the panel drawer are `aria-hidden` and `pointerEvents="none"`, `inert` on web (so their controls leave the tab order too) and hidden from VoiceOver/TalkBack on native. The veil over the workspace is inside the same gate, and it is never a Tab stop — react-native-web's `Pressable` writes `tabIndex` 0 over `focusable={false}`, so the veil takes `tabIndex={-1}`. A host does not wrap `mobileSidebar` in a gate of its own; `navPresented` is there for anything else that has to know whether the nav is on screen.
@@ -81,6 +83,8 @@ Radius 24 on background-secondary: the breadcrumb header (px 16 / pt 16, share a
 
 `project` is **optional**: a chat that belongs to nothing draws its own crumb alone, with no folder glyph and no empty crumb.
 
+The container publishes its painted surface through Bloom’s surface context, so nested sheet composers and sticky controls follow the panel fill. A transparent container inherits its parent’s fill.
+
 `background` is a layer filling the container, drawn **above its own surface and below every turn, header and composer**, clipped to the radius and never interactive — a host's wallpaper, gradient or animated field goes here rather than behind the container, and nothing has to reach into it. An opaque node needs nothing else; add `surface={false}` when the node is translucent and should show what the container is sitting on instead of background-secondary.
 
 The thread scrolls with a thin scrollbar, px 16 / pt 16, turns 12 apart, and is **bottom-anchored**: a short exchange sits just above the composer. It follows the newest content with a smooth scroll whenever it grows — that is the default, and every prop below is off unless asked for.

package/docs/app-shell.mdx

@@ -648,3 +648,20 @@ through the shared edge registry; document/container content receives no duplica
 `scroll="fixed"` always leaves scrolling and clearance to the child navigator or list.
 
 ProOfferCard retains its animated complementary host and decorative artwork, with shared SurfacePaint beneath it and contextual backing published for descendant controls. Explicit background overrides remain supported.
+
+### Split panes inside another Bloom shell
+
+`AppShellSplitPanes` is also exported from `@oxy.so/bloom/app-shell` and the root barrel. It owns only the bounded pane layout and divider, not navigation, surfaces or a second shell context. Compose it inside `AiChatShell` + `AiChatContainer` to use that template's reveal navigation and surfaces.
+
+```tsx
+<AppShellSplitPanes
+  list={<MailboxList />}
+  showList={desktop}
+  detail={<Slot />}
+  paneScroll={false}
+/>
+```
+
+The detail remains mounted while `showList` changes; hiding a pane explicitly unmounts that pane. Defaults match AppShell's split layout: list width 360 (range 280–520), info width 320, scrolling and resizing enabled. `showDetail` defaults to true; list/info visibility follows the supplied content. Set `paneScroll={false}` when routes or virtualized lists own their scrolling. The surrounding Bloom container must provide a bounded height.
+
+Use `variant="separated"` when each pane supplies its own `AiChatContainer`. Bloom inserts 12px transparent gutters and centers the existing resize handle in the list gutter; there is no extra surface around the panels. A single visible pane has no gutter. The default `joined` variant retains hairline dividers for panes inside one shared surface.

package/docs/mail-list.mdx

@@ -1,6 +1,6 @@
 ---
 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.
+description: The inbox — one row at three densities, day sections, the markers a message carries, and the bulk-selection bar the list mounts itself.
 order: 64
 ---
 
@@ -26,34 +26,30 @@ import { MailList, groupMailByDay } from '@oxy.so/bloom';
 />;
 ```
 
-## Two densities, one component
+## Three 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 |
+| | `compact` | `comfortable` | `cozy` |
+| --- | --- | --- | --- |
+| height | 40, exact | 64 (a floor) | 80 (a floor) |
+| padding (horizontal / vertical) | 12 / 0 | 14 / 12 | 16 / 16 |
+| avatar | 24 | 40 | 48 |
+| lines | one | sender, then subject + snippet | sender, then subject + snippet |
 
-`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.
+`comfortable` remains the default. `cozy` gives the same two-line layout more
+space without changing content, actions, theme colours or accessibility names.
+`compact` uses a sender column with a 180px basis, an 88px floor and a 34% width
+ceiling, leaving room for the subject in a narrow pane.
 
-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.
+The shared geometry table drives rows, skeletons and the selection bar; use the
+same `density` on all three when composing a virtualized list yourself.
 
-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.
+Set `showAvatar={false}` on `MailRow` or `MailList` to hide sender avatars.
+Selection checkboxes remain available; each `MailSummary` can override the list
+setting. The text uses the freed space instead of leaving an empty avatar slot.
 
 ## The subject and the snippet are one `Text`
 
-At BOTH densities the subject and the snippet are a single string with a nested
+At all 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
@@ -225,3 +221,7 @@ 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.
+
+## Pointer targets
+
+The row link is an absolute sibling below the foreground content. Layout wrappers use `pointerEvents="box-none"`, and inert text/marks use `pointerEvents="none"`; controls retain their own targets. A synthetic `element.click()` bypasses those layers, so run `scripts/verify-mail-row-pointer.mjs` against the Pointer Targets story to validate actual browser hit testing.

package/docs/settings-modal.mdx

@@ -83,7 +83,7 @@ Every layout uses `PageHeader` with its floating islands. A `ButtonGroupItem` su
 
 This shell differs from `Dialog`'s centered card in every load-bearing way: black 70% backdrop with no blur, 24px radius on `background/full`, a fixed 871×614 size, a fade + scale-from-0.85 + 4px blur on `cubic-bezier(0.32, 0.72, 0, 1)`, and a **Saved toast that straddles the panel's bottom edge** — outside the panel's clip, which `Dialog`'s card owns. So the shell is built from the same authorities `Dialog` uses — `Portal`, `OverlayRoot` (the one stacking rank) and `Backdrop` (the pointer-events contract) — and accepts `Dialog`'s `control`.
 
-Menus, selects, tooltips and the date popover opened inside a page stack above it through the overlay stack. **Escape closes the innermost surface first:** the modal listens on `window`, and the floating surfaces stop the key on `document`.
+Menus, selects, tooltips and the date popover opened inside a page stack above it through the overlay stack. **Escape closes the innermost surface first:** shared `ModalKeyboard` checks overlay and floating-surface ownership before claiming the key. Its capture/deferred handling also hears Escape from React Native Web text fields. Focus moves into the panel on open, Tab remains inside, and closing restores the opener.
 
 ## The saved toast