@lotics/ui 46.2.0 → 46.3.0

package/AGENTS.md

@@ -75,6 +75,30 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **The kit's fonts/colors/icons ARE the design system** — never a custom font, icon set, or
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
   → [composition.md §"Color discipline"](./docs/composition.md).
+- **An overlay paints in the order it was OPENED, and a scroller that swaps content opens the new
+  content at the top.** Compose overlays wherever you like — a `Dialog` written beside the
+  `Drawer` whose row opens it works, both ways round, and a `Dialog` opened from an open `Popover`
+  paints over its panel. An overlay of your OWN gets that for free by rendering its react-native
+  `Modal` **only while open** (`{open && <Modal visible …>}`); mounted while closed it takes its
+  body-level slot on the app's first paint and is then covered by anything opened later —
+  rendering and announcing perfectly, dead to every press. The z-index rungs beside the overlays
+  are published in `overlay_layer`, so never hand-pick a number to clear a Lotics overlay.
+  `DrawerScrollArea` / `DialogScrollArea` / `ModalBody` take a `scrollKey` and the routed
+  `Popover` takes the same seam off its route, so a swapped-in record opens at the top and the
+  reader returns to their place on the way back.
+  → [composition.md §"Canvas & content column"](./docs/composition.md)
+  → [catalog.md §"Overlays & navigation"](./docs/catalog.md)
+- **ONE VALUE, ONE RENDERING, inside one card — the chart draws the entity its table draws.**
+  A value's filter renders it the way its cell does, and the same rule reaches the chart beside
+  the table: `StackedBarRow` and `BarChartItem` take a `leading` slot for the entity's own mark.
+  A LEGEND row is the exception — its subject is a category, and the swatch is that identity.
+  → [composition.md §"A register that TRIAGES"](./docs/composition.md).
+- **A row says which side HOLDS; `numberOfLines` handles the side that gives way.** The clamp
+  brings its own `minWidth: 0` + `flexShrink: 1` (a clamp that cannot shrink cannot clamp), so
+  what a call site still has to state is `flexShrink: 0` on the figure or control that must stay
+  whole. Same law on a categorical axis: the LABELS thin to fit, the bars never do.
+  → [composition.md §"Typography"](./docs/composition.md),
+  [catalog.md §"Numbers & charts"](./docs/catalog.md).
 - **Hand-typed type is off-system — and it always lands too small.** Every run of language is
   `<Text size= weight= color=>` on the fixed rungs. **Grep the diff: `fontSize:` / `lineHeight:` /
   `letterSpacing:` outside `src/` is a bug.** → [composition.md §"Typography"](./docs/composition.md).

package/MIGRATION.md

@@ -4,6 +4,93 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 46.3.0
+
+**A `Text` with `numberOfLines` now declares `flexShrink: 1` + `minWidth: 0` for you.**
+A clamp that cannot shrink cannot clamp: on web a clamped `Text` is `white-space: nowrap`, so
+`min-width: auto` floors it at the WHOLE string; on native a `Text` is `flexShrink: 0`. Either way
+two clamped values on one row laid out at intrinsic width and ran off the frame. Both declarations
+now come with the clamp, and both are no-ops until a row actually overflows.
+
+Nothing's API changed, but **a layout default moved under every clamped `Text` in your app** — this
+is the one 46.3.0 change to re-check by looking. Two shapes are worth a pass:
+
+- A flex ROW where a clamped `Text` was the side that HELD and an unclamped sibling gave way. Both
+  can shrink now, so the wrong one may truncate.
+- A flex COLUMN with a bounded height (a fixed-height card, a `maxHeight` panel). `flexShrink` acts
+  on the MAIN axis, so a clamped `Text` that used to hold its height can now be compressed.
+
+The pair sits BEFORE your own `style`, so the site that must stay whole says so:
+
+```diff
+-<Text numberOfLines={1}>{amount}</Text>
++<Text numberOfLines={1} style={{ flexShrink: 0 }}>{amount}</Text>
+```
+
+That is how a figure keeps winning over its label. `minWidth` is overridden the same way
+(`style={{ minWidth: "auto" }}`) on the rare surface that wants the old min-content floor back.
+
+**An overlay of your OWN must render its react-native `Modal` only while it is OPEN.**
+`Dialog`, `Drawer`, `Modal` and `FileGalleryModal` now do — nothing in their API changed — and a
+hand-rolled overlay outside the kit has to do the same, or it loses to them:
+
+```diff
+-<Modal visible={open} onRequestClose={close} transparent>
+-  …
+-</Modal>
++{open && (
++  <Modal visible onRequestClose={close} transparent>
++    …
++  </Modal>
++)}
+```
+
+react-native-web appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders
+it, so an overlay mounted while closed takes its slot on the app's first paint and is then covered
+by any overlay opened later — while rendering, reading and announcing perfectly, with only its
+presses dead. Nothing is lost by the change: react-native-web renders a closed `Modal`'s children
+as `null` already, so only the empty portal div was being held. A takeover with
+`animationType="fade"` keeps its fade IN and now closes immediately, as `FileGalleryModal` always
+has; state that must survive a close belongs outside the `Modal` element either way.
+
+**The overlay z-index rungs are now published constants.** The numbers are unchanged for `Tooltip`
+and `Alert` (`10000`) and for a toast (`10001`); **the skip link moved `10001` → `10002`**, off the
+rung it was sharing with a toast. Read the rung instead of naming a number:
+
+```diff
+-import { View } from "react-native";
++import { NOTIFICATION_Z } from "@lotics/ui/overlay_layer";
+ …
+-  zIndex: 10001,
++  zIndex: NOTIFICATION_Z,
+```
+
+The full table is in `docs/catalog.md` § Overlays & navigation: `OVERLAY_Z` (every overlay, and
+`Popover`), `OVERLAY_Z_ABOVE` (tooltip/alert), `NOTIFICATION_Z` (a toast), `SKIP_LINK_Z`.
+
+**`PageContent`'s title band is now a `PageHeader`**, so the two stop drifting. `title`,
+`titleRight` and `description` are unchanged, and `PageHeader`'s `title` became optional — but the
+band's rhythm is now `PageHeader`'s everywhere: a description sits **8px** under the title (it was
+flush in `PageHeader`) and the band clears **16px** before the content (it was 24 in
+`PageContent`). Nothing to change; worth one look at a page shell you care about.
+
+**`useChangeSet`'s per-proposal default is a MAP, not a predicate.** `initial: "accepted"` /
+`"pending"` are unchanged.
+
+```diff
+-useChangeSet(ids, { initial: (id) => (overwrites.has(id) ? "rejected" : "accepted") })
++const initial = useMemo(
++  () => new Map(rows.filter((r) => r.overwrites).map((r) => [r.id, "rejected" as const])),
++  [rows],
++);
++useChangeSet(ids, { initial })
+```
+
+An id the map does not name arrives `accepted`, as before. A value rather than a function is what
+lets the default be an ordinary dependency: `status` and the group arrays derive from it together,
+so `status` changes identity whenever a decision does — which a screen that memoizes its rows on
+`review.status` needs, and which a predicate held out of the dependency lists could not give.
+
 ## 46.0.0
 
 **`AgentRun` / `AgentProgress` drop `stepsLabel`, and the `agentRun` locale slice drops `steps`.**

package/docs/ai_patterns.md

@@ -379,6 +379,17 @@ alignment and rhythm.
   `keptCount`/`total`/`settled`. `initial` defaults to **`accepted`** so an operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change
   genuinely deserves its own verdict, and gate the commit on `settled`.
+  - **A set that mixes KINDS defaults per kind: `initial` also takes a `Map<id, decision>`.** A
+    review usually holds both — filling a blank should arrive `accepted`, overwriting a value a
+    human already set should arrive `rejected`, so the destructive half is opt-in — and one
+    global default puts one of the two on the wrong footing. An id the map does not name arrives
+    `accepted`. Build it with a `useMemo` over the proposals your screen already holds, which is
+    what keeps the hook ignorant of what a proposal IS; a VALUE (rather than a predicate written
+    inline) is what lets `status` and the group arrays derive from it together, so `status`
+    changes identity the moment a decision moves and a screen memoizing its rows on it re-runs.
+    Deciding those rows by calling `reject()` from the result handler instead writes overrides
+    nobody made, and `undo` then hands the row back **accepted** — the destructive change
+    silently in, from the control that means "undo".
 
 ### The shapes, and what each one is
 

package/docs/catalog.md

@@ -443,6 +443,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   numbers), `weight`, `color`, alignment, tabular numerals. **`leading="tight"`** sets the line
   box for a STACKED PAIR rather than for prose — a subject over its supporting line, a value over
   its annotation; see composition.md, which also covers the `gap` that goes with it.
+  **`numberOfLines`** clamps, and brings the `minWidth: 0` + `flexShrink: 1` that makes clamping
+  possible on a flex row — a clamp that cannot shrink cannot clamp. Both are no-ops until the row
+  overflows, and a `style` on the call site still wins, so a value that must never give way says
+  `flexShrink: 0` and keeps holding over its own label.
 - **`eyebrow`** — `Eyebrow`: the small quiet label above or beside a VALUE (`xs` muted medium) —
   a metric caption, a field name in a cell, an artifact tag. Takes `color` (for a VERDICT word
   like "Mismatch") and `align`, and deliberately takes no `size`, `weight` or `transform`:
@@ -702,16 +706,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band. `actions` puts page-level CTAs on
+- **`page_header`** — `PageHeader`: the page's title band, and the ONE place that band is
+  defined — `PageContent`'s `title`/`titleRight`/`description` render one of these rather than a
+  second copy of the row. `actions` puts page-level CTAs on
   the title row (right-aligned) and `trailing` puts a control immediately AFTER the title;
   `left`/`right` form a separate nav row above. Split `trailing` from `actions` by what the
   control acts on: `actions` do something to the page's CONTENT (create, sort, export),
   `trailing` changes what is AROUND it (a side-panel toggle, a view switch). A panel toggle
   filed under `actions` reads as a peer of "create one of these". Under a title too long for
   the row the TITLE gives way and wraps while `trailing`
-  and `actions` keep their width.
+  and `actions` keep their width. **The band owns the space under itself** — 16px, whether it
+  is rendered on a hand-rolled screen or by `PageContent`; a shell adds nothing after it, or
+  the same band closes on two different rhythms depending on which shell a screen picked.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
+  region — a centred column with optional `title`/`titleRight`/`description` (which render a
+  `PageHeader`, so the band's row law and rhythm have one home), `header`/`footer`
   slots and `fullscreen`. **Reach for it before hand-rolling a screen shell.** Its side
   padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
   genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
@@ -1586,15 +1595,56 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Overlays & navigation
 
+**Every overlay paints in the order it was OPENED**, so mount them wherever composition wants — a
+`Dialog` written beside the `Drawer` whose row opens it is the ordinary shape and it works; a
+drawer opened from a dialog covers the dialog, which is the same rule the other way round. There
+is no layer prop and nothing at the call site has to know the tree order. It covers every
+body-level surface the kit has, `Popover` included: a `Dialog` or a file-preview `Modal` opened
+from an open popover paints OVER the panel that opened it. `Alert` and `Tooltip` stay above every
+overlay at any depth.
+
+**The one rule an overlay of your OWN has to follow: render the react-native `Modal` element only
+while it is open** (`{open && <Modal visible …>}`, or an early `return null`). react-native-web
+appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders it, so an overlay
+mounted while closed has already taken its slot before anything opened — and once two overlays tie
+at the same z-index, that slot is what decides. The symptom is nasty precisely because it is not
+visual: the covered surface renders, reads and announces perfectly, and only its presses do
+nothing. Nothing is lost by not mounting it — react-native-web renders a closed `Modal`'s children
+as `null` anyway, so only the empty portal div was ever being held, and anything that must survive
+a close (a router, a context, form state) belongs outside the `Modal` element regardless.
+
+**The rungs beside the overlays are a published contract** (`overlay_layer`), because a surface
+OUTSIDE the kit that has to clear a Lotics overlay cannot do it with a hand-picked literal:
+
+| z-index | what sits there |
+|---|---|
+| `9999` | every overlay, and `Popover` — `OVERLAY_Z` |
+| `10000` | `Tooltip`, `Alert` — `OVERLAY_Z_ABOVE` |
+| `10001` | a transient notification / toast — `NOTIFICATION_Z` |
+| `10002` | the skip link — `SKIP_LINK_Z` |
+
+Overlays all share one rung on purpose: DOM order settles the tie and DOM order is open order.
+`Popover` is on it too — it is no `Modal`, but it portals into the nearest `PortalHost`, so one
+opened inside an overlay is already inside that overlay's stacking context and a page-level one is
+a child of the app root, which every overlay's body-level box follows.
+
 - **`portal`** — `PortalHost` + `Portal`: the floating-content mount point; the app root
   needs ONE `PortalHost` or `Dialog`/`Popover`/`Tooltip`/`Alert`/`OptionList` cannot render.
 - **`dialog`** — `Dialog` (+ `DialogHeader`/`DialogHeaderTitle`/`DialogFooter`, `useDialog`,
   `useDialogNavigation`): the centered card over a scrim; BAKES a screen router in
-  (`<Dialog><Screen route="">…` — see `screen_router`).
+  (`<Dialog><Screen route="">…` — see `screen_router`). `DialogScrollArea` takes the same
+  **`scrollKey`** seam as `DrawerScrollArea` for a pane that swaps its body in place; a dialog
+  navigating between `Screen`s does not need it, because a stacked screen stays mounted and keeps
+  its own offset.
 - **`drawer`** — `Drawer` + `DrawerScrollArea` + `DrawerFooter`: the docked side panel with scrim; the
   register row's edit surface. ONE standard width (600px) — pass `width` only for a genuinely
   exceptional panel; full-width on small screens. `DrawerScrollArea` is the guttered content
-  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. It always
+  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. Give it a
+  **`scrollKey`** (the open content's identity — `scrollKey={openChild?.id}`, where the undefined
+  leg names the root content rather than opting out) on a drawer that SWAPS its body in place, so
+  the new content opens at the top and the previous one's offset returns on the way back — the seam
+  `DialogScrollArea` and `ModalBody` take too, and the one thing a React `key` on the scroller
+  cannot buy, since that resets the parent's place along with the child's. It always
   scrolls: a padded box around a `flex:1` scroller insets that scroller's viewport, ending the
   list short of the panel with the last row clipped. Two bodies skip it and take the `Drawer`'s
   bare slot: a FULL-BLEED one (a band spanning the panel, a record screen with its own gutters),
@@ -1605,7 +1655,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog
   (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it
   to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader
-  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned
+  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody (which takes the
+  **`scrollKey`** seam — a wizard stepping between steps swaps its body in place), a pinned
   ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a
   focused capture / multi-step wizard / a console the user steps INTO; pick Dialog when the
   surface is a card the user can see context around.
@@ -1631,11 +1682,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   The built-in scroller is **full-bleed horizontally** and re-insets its content by the same
   amount, so a scrolling body reaches the panel's real edges while the text stays on the
   same column the header and footer use. Nothing to opt into; `disableBodyScroll` consumers
-  (which own their scroll) are untouched.
+  (which own their scroll) are untouched. It also carries the **scroll seam** every scroller
+  that swaps its body in place takes — keyed on the routed popover's current route, with no prop
+  at call site, and inert in a popover that has no sub-screens.
 - **`popover_nav`** — `usePopoverNav` + `PopoverScreen` + `PopoverNavHeader` — the popover's
   built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes,
   `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the
-  root and screens render conditionally (unmounted when inactive — no scroll preservation),
+  root and screens render conditionally (unmounted when inactive, so a screen's own state does
+  not survive the round trip — the panel's SCROLL does: the screens share `PopoverContent`'s one
+  scroller, which takes the ROUTE as its seam key, so a sub-screen opens at the top with its
+  `PopoverNavHeader` in view and the root list's offset returns on the way back),
   `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack`
   (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover; route PATTERNS,
   `params`, and stacked-alive screens are `screen_router`'s job.
@@ -1661,6 +1717,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   content) — it is what `SectionHeadingTitle.info`/`CardHeaderTitle.info` render.
 - **`alert`** — `Alert` (+ `AlertButton`/`AlertOptions`): the blocking confirm —
   `Alert.alert(title, message, [{cancel}, {destructive}])`.
+- **`overlay_layer`** — `OVERLAY_Z` / `OVERLAY_Z_ABOVE` / `NOTIFICATION_Z` / `SKIP_LINK_Z`: the
+  ONE paint-order table for everything that reaches `document.body` (the rungs are in the table
+  above), and the file that states why open order works. Constants only — there is no layer to
+  render and nothing to claim; an overlay of your own gets its place by mounting its react-native
+  `Modal` only while it is open. Never write one of these numbers as a literal.
 - **`overlay_scope`** — `isOverlayScopeActive` / `pushOverlayScope` / `useOverlayScope`: the
   module-level open-overlay counter every overlay primitive reports into; the host's
   shortcut registry reads it synchronously to floor page-level shortcuts while any overlay
@@ -1715,11 +1776,24 @@ component rather than showing it at zero.
   it carries SHAPE (rising, spiky, flat) and no readable values, which is exactly what a
   register wants. Reach for a real chart the moment someone needs to read a value off it.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
-  `PieChart`: the canonical SVG chart set (no recharts). `LineChart` prints as many x labels
-  as the track fits and thins the rest, anchored on the LAST point — the newest reading is the
-  one a reader looks up, and anchoring there is what keeps the spacing uniform. The first
-  point is labelled only when it clears the same distance, so a series whose length does not
-  divide evenly drops its opening label rather than crowding the one beside it.
+  `PieChart`: the canonical SVG chart set (no recharts). **A categorical axis prints as many
+  labels as the track fits and thins the rest** — `LineChart` and `BarChart`'s vertical
+  orientation both, because it is the axis's rule and not one chart's. It is anchored on the LAST
+  position: the newest reading is the one a reader looks up, and anchoring there is what keeps the
+  spacing uniform; the first position is labelled only when it clears the same distance, so a
+  series whose length does not divide evenly drops its opening label rather than crowding the one
+  beside it. **The BARS never thin** — how many bars a card carries is a question about the data,
+  never about how wide a label happens to be, and an unlabelled bar keeps its slot so the row
+  above stays in line. **What thins is the whole annotation, label AND value together**, because a
+  bar's name and its figure are one reading: a number under an unnamed bar is a quantity of nothing
+  a reader can name, and the surviving annotation is widened across the room its dropped neighbours
+  vacated — room the figure needs as much as the name does. So a DENSE vertical `BarChart` (more
+  bars than `track ÷ 50px`: a 30-day daily series in a 600px card keeps roughly ten) shows the
+  figures only for the bars it labels. When every bar's number has to be readable, that is a
+  `Table` or the horizontal orientation, which gives each entity its own row and its own value
+  column. `BarChart`'s horizontal orientation is one row per entity: **`labelWidth`**
+  sizes the fixed label column (default 80, which fits a date and not a company name), and each
+  item's **`leading`** slot carries that entity's own mark ahead of its name.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it.
 - **`progress_ring`** — `ProgressRing`: the same meter in a circle, and the ONLY circular one. Same API shape as the bar — a real `value`/`max` rather than a
@@ -1741,7 +1815,10 @@ component rather than showing it at zero.
   cost make-up per product line. `series` (key/label/colour, one hue family per dimension)
   drives a legend that is on by default; each `StackedBarRow` takes `label` + optional `meta`,
   a pre-formatted headline `value` with its `valueTone`, and a `caption` sentence, so colour is
-  never the only channel. Between `stacked_progress_bar` (one whole, own track) and `breakdown`
+  never the only channel. **`leading`** is the entity's own mark (`BrandMark`, `Avatar`, a status
+  dot), centred on the label's line box — a row's segment colours belong to the MEASURE, so unlike
+  a legend row this one carries no identity until you give it one, and a chart beside a table over
+  the same entities has to draw them the same way (composition.md § the register's own craft). Between `stacked_progress_bar` (one whole, own track) and `breakdown`
   (one whole + ranked share rows beneath it): reach here the moment there are SEVERAL wholes to
   compare.
 - **`waterfall_chart`** — `WaterfallChart`: the BRIDGE — an opening level, the signed steps
@@ -2205,7 +2282,14 @@ component rather than showing it at zero.
   `ids` is normally a memo over query rows — a new array every render, which is the
   `Maximum update depth exceeded` loop). `initial` defaults to `accepted` so the operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change deserves
-  its own verdict and gate the commit on `settled`.
+  its own verdict and gate the commit on `settled`. **`initial` also takes a
+  `ReadonlyMap<id, decision>`**, for a set that mixes kinds with different safe defaults —
+  filling a blank arrives `accepted`, overwriting a value a human already set arrives `rejected`,
+  so the destructive half is opt-in; an id the map does not name arrives `accepted`. Build it in a
+  `useMemo` over your own rows: it is a VALUE, so `status` and the groups derive from it together
+  and `status` changes identity whenever a decision does — which is what a screen memoizing its
+  rows on `status` needs. Do not reach for `reject()` in the result handler instead: that writes
+  overrides the operator never made, so `undo` hands the row back `accepted`.
 - **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
   (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
   the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires

package/docs/composition.md

@@ -69,6 +69,28 @@ the subject into rows.
   the same left edge as the title above it and the actions below it. Never hand-pad inside one,
   and never hand-roll one: the three surfaces disagree on the number (24 / responsive / 20) and
   only the surface knows which it is.
+  - **ANY scroller whose body is SWAPPED opens the new content at the top.** Stated as a rule and
+    not as a count of the surfaces that happen to have one today: `ModalBody`,
+    `DialogScrollArea` and `DrawerScrollArea` each take a `scrollKey` — the content's identity (a
+    record id, a step name) — and the kit's routed `Popover` takes the same seam with no prop at
+    all, because its ROUTE already is that identity. A scroller you add that swaps its body joins
+    the rule rather than being added to a list. `scrollKey={openChild?.id}` is the right shape:
+    an ABSENT key names the root content, not an opt-out, so the offset comes back when the child
+    closes. Opting out needs no signal — a surface whose key never changes never scrolls. Without it the container keeps the offset it
+    was holding for content that no longer exists, so a swapped-in record opens part-way down
+    itself with its heading off-screen above — invisible until the first list long enough to
+    scroll, which is the same list that made the swap worth having. The key opens unseen content
+    at the top and restores the offset when it comes BACK, which is what a React `key` on the
+    scroll area cannot do: that rebuilds the container, resetting the parent's place along with
+    the child's. Omit it where the body is one thing, and inside a `Screen`-routed dialog, where
+    a stacked screen stays mounted and already keeps its own offset.
+- **Overlays paint in the order they were OPENED, and no call site has to know it.** Mount them
+  wherever composition wants — a `Dialog` sitting always-mounted beside the `Drawer` whose row
+  opens it is the ordinary shape, and it is the one that used to fail: the dialog claimed its DOM
+  slot on the app's first paint, the drawer landed after it, and the dialog then rendered
+  perfectly and read correctly with every control under the panel DEAD. Whatever opens last is on
+  top, both ways round, so a drawer opened from a dialog covers it too. `Alert` and `Tooltip` sit
+  above every overlay at any depth — they are ABOUT the surface under them.
   - **The responsive one is READ, never re-derived — `useDialogGutter()`, no argument.** Inside
     a `Dialog` that is what the header, the scroll area, the footer and any pane a caller drops
     in all call. The `Dialog` resolves `small ? 16 : 24` ONCE, off the SCREEN, and publishes it.
@@ -829,7 +851,11 @@ unconditionally and let an empty `value` disable it, rather than revealing it on
 
 Pressing a PRIMARY entity row opens the record workspace in a `Drawer` with `onPrev`/`onNext`/
 `position` ("3/24") over the visible ordering (←/→ arrow keys are built in). Key the drawer body by
-record id so per-record state resets on step. Facts are `DetailRow`s; the commit bar is a
+record id so per-record state resets on step. A drawer that instead REPLACES its body with a child
+record — the shape where a row inside the panel opens a second record rather than stacking a
+second drawer — passes that id as `DrawerScrollArea`'s `scrollKey` (`scrollKey={openChild?.id}` —
+the undefined leg is the list's own identity), so the child opens at the top and the list keeps its
+place on the way back. Facts are `DetailRow`s; the commit bar is a
 `DrawerFooter` (a hairline-topped band pinned to the panel bottom — render it as the LAST child,
 after the scroll body; actions sit right, a leading `<Text style={{ flex: 1 }}>` hint pushes them
 there). The open row shows a `selected` highlight (and `marked` for a bulk-ticked row). `Peek` is
@@ -1318,6 +1344,15 @@ colours, same shapes. Re-rendering it as plain text makes the reader translate b
 presentations of one field, and the two drift the first time either side gains a value. This holds
 for every custom-rendered value, not just status.
 
+**The same rule reaches the CHART beside the table.** One entity, one rendering, everywhere inside
+one card: if the table's first cell carries the entity's mark (`BrandMark`, `Avatar`, a status
+dot), the chart's rows carry it too — `StackedBarRow` and `BarChartItem` each take a `leading`
+slot for exactly that, laid out on the label's own line box. It is worst where the mark carries
+most (a channel, a platform, a person), and the two ways out that are not the slot are both
+losses: dropping the mark from the table to match makes *both* halves anonymous, and hand-drawing
+the chart to get one slot loses the component. A LEGEND row is the exception and needs no slot —
+its subject is a category, and the colour swatch already is that category's identity.
+
 **Group by what implies a different ACTION, never by a category the reader can already see.**
 Bands like *Waiting on you* / *Gone quiet* / *Open* / *Closed* each name a different response, so
 the grouping tells the reader something no column does. Grouping by a value that is already a
@@ -1780,13 +1815,20 @@ complaint it was meant to fix, because a reader who cannot read a label reports
 cluttered rather than as small. Recede with INK, at the same rung. `xs` is for genuine meta (a
 timestamp, a count), not for a label that a person actually has to read.
 
-**A LABEL sharing a row with a flexible VALUE must be told which one gives way.** Two items in one
+**A LABEL sharing a row with a flexible VALUE must be told which one HOLDS.** Two items in one
 flex row, and whichever cannot shrink forces the other to. It is invisible wherever the values
 happen to fit, which is usually the width it was built at, and it appears the first time a real
-record carries a long one. Decide deliberately: `flexShrink: 0` on the one that must stay
-whole (a fixed-length key, a label), `flexShrink: 1` + `numberOfLines` on the one that may clip,
-and pick by which is still USEFUL truncated — `RC-2026-0…` is unusable, `(555) 384-7…` is still
-recognisably a phone number.
+record carries a long one. Say which one stays whole — `flexShrink: 0` on a fixed-length key, on a
+figure, on a control — and pick by which is still USEFUL truncated: `RC-2026-0…` is unusable,
+`(555) 384-7…` is still recognisably a phone number.
+
+The clipping half needs only **`numberOfLines`**, which now brings its own `minWidth: 0` +
+`flexShrink: 1`: a clamp that cannot shrink cannot clamp, so the prop that says "cut this to fit"
+is what makes it possible. (Neither platform gave it for free — on web a clamped `Text` is
+`white-space: nowrap`, so `min-width: auto` floors it at the WHOLE string; on native a `Text` is
+`flexShrink: 0`. A row of two clamped values laid out at intrinsic width and ran off the frame.)
+Both are no-ops until a row actually overflows, and a `style` on the call site still wins — which
+is how a figure keeps holding over its own label.
 
 
 

package/docs/templates.md

@@ -450,7 +450,9 @@ The corollaries, each of which a register is routinely missing:
     DRAFTS; it does not write. Every drafted record then renders in full — all four fields as
     they will be stored, each editable in place, a `DiffMark` per card, Keep/Drop via
     `useChangeSet` (`initial: "accepted"` — the operator drops the exceptions rather than
-    approving six identical records) — and ONE commit named for its outcome creates them. The
+    approving six identical records; a set that also OVERWRITES values a human set passes a
+    `Map<id, decision>` instead, so that half arrives dropped) — and ONE commit named for its outcome
+    creates them. The
     manual form beside it skips all of that and saves direct. Only the DOCUMENT path needs the
     gate. The receipt still follows the write — it states the outcome, ROUTES, and carries the
     deterministic checks (a checksum, a count reconciliation).

package/docs/testing.md

@@ -46,6 +46,12 @@ Assert two things, not one: that the content appeared, and that it **dismisses**
 backdrop, so clicking the trigger a second time is often intercepted; click the
 backdrop or press `Escape`.
 
+Two overlays open at once stack by the order they were OPENED, so the newest one
+takes the press. If a driver reports `subtree intercepts pointer events` on a
+control of the overlay you just opened, that is a real defect and not this
+anatomy: check with `document.elementFromPoint` at the control's centre, which
+names whatever is actually on top.
+
 ## Custom pointer drag is not `dragTo`
 
 The calendar and gantt drags are built on `use_pointer_drag`, which listens for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.2.0",
+  "version": "46.3.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -150,6 +150,7 @@
     "./popover_nav": "./src/popover_nav.tsx",
     "./popover": "./src/popover.tsx",
     "./overlay_scope": "./src/overlay_scope.ts",
+    "./overlay_layer": "./src/overlay_layer.ts",
     "./switcher": "./src/switcher.tsx",
     "./menu_button": "./src/menu_button.tsx",
     "./menu_list_item": "./src/menu_list_item.tsx",
@@ -334,7 +335,7 @@
   "dependencies": {
     "@lotics/docx": "^0.3.0",
     "@lotics/markdown-editor": "^0.1.0",
-    "@lotics/xlsx": "^0.2.0",
+    "@lotics/xlsx": "^0.3.0",
     "ai": "^7.0.30",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm-footnote": "^2.1.0",

package/src/alert.css

@@ -9,7 +9,6 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  z-index: 10000;
   animation: lotics-alert-fade-in 0.2s ease-out;
   padding: 16px;
 }

package/src/alert.tsx

@@ -4,6 +4,7 @@ import "./alert.css";
 import { Text } from "./text";
 import { Button, ButtonColor } from "./button";
 import { useOverlayScope } from "./overlay_scope";
+import { OVERLAY_Z_ABOVE } from "./overlay_layer";
 
 export type AlertButtonStyle = "default" | "cancel" | "destructive";
 
@@ -27,6 +28,13 @@ class Alert {
     if (!this.container) {
       this.container = document.createElement("div");
       this.container.id = "alert-container";
+      // The rung lives here rather than on the overlay's CSS class, because it
+      // is a fact about where an alert sits among the OTHER body-level layers —
+      // one table answers that (`overlay_layer.tsx`), and a stylesheet cannot
+      // read it. The box is zero-height, so making it a stacking context is
+      // free; the fixed overlay inside paints in it.
+      this.container.style.position = "relative";
+      this.container.style.zIndex = String(OVERLAY_Z_ABOVE);
       document.body.appendChild(this.container);
     }
     if (!this.root) {

package/src/axis_label_indices.ts

@@ -0,0 +1,84 @@
+/**
+ * Which of a CATEGORICAL AXIS's positions get a printed label.
+ *
+ * The rule belongs to the axis, not to one chart: a line's x labels and a bar
+ * chart's per-bar labels have the same failure — a label is roughly
+ * `minLabelWidth` wide, so only so many fit across the track, and past that the
+ * axis either overlaps or ellipsises its own labels. Neither is a typography
+ * problem to solve by shortening the data; the labels are what thin out.
+ *
+ * ONE model serves both geometries. How many labels fit is a function of the
+ * TRACK and the label width — `floor(track / minLabelWidth)` — and that is the
+ * same question whether the labels are points on the track (a line's, at
+ * `i/(count-1)`) or slot centres (a bar's, at `(i+0.5)·track/count`). The two
+ * geometries differ only in the distance from position 0 to the first kept
+ * index, and by less than one slot; the count and the step are shared.
+ *
+ * What the caller must NOT assume is that thinning alone widens a label. On a
+ * SLOT geometry the survivor still sits in its own slot, so the space the
+ * dropped neighbours freed has to be handed to it explicitly — see
+ * {@link axisLabelStep} and `BarChart`'s label box.
+ *
+ * The rule that matters is WHERE the thinning is anchored: stepping forwards
+ * from the first position and then forcing the last one in collides whenever the
+ * count minus one is not a multiple of the step — the newest label lands a few
+ * pixels from the one before it while every other pair is a full step apart.
+ * Anchoring on the LAST position makes the spacing uniform by construction, and
+ * the last position is the one a reader looks up first. The first position is
+ * then kept only when it clears the same distance.
+ */
+/**
+ * How many positions the axis skips between printed labels — 1 when every label
+ * fits, `count` when the track has room for only one. Exported because a SLOT
+ * geometry needs it twice: once to pick the labels, and once to give a survivor
+ * the width of the span its dropped neighbours vacated. Deriving it a second
+ * time at the call site is how the two drift.
+ *
+ * The floor is ONE label, not two. Forcing a second onto a track that fits one
+ * breaks this module's own rule — the two then land closer together than a label
+ * is wide, which is the overlap the thinning exists to prevent — and it is the
+ * narrow end that needs the rule most, because that is where a track can go to
+ * zero or below.
+ */
+export function axisLabelStep(count: number, chartWidth: number, minLabelWidth = 50): number {
+  if (count <= 1) return 1;
+  const maxLabels = Math.max(1, Math.floor(chartWidth / minLabelWidth));
+  return Math.max(1, Math.ceil(count / maxLabels));
+}
+
+/**
+ * The positions to print, thinned to what the track fits.
+ *
+ * THE CONTRACT: the result is empty ONLY when there is nothing to label
+ * (`count <= 0`). An axis that HAS positions always prints at least one of them
+ * — the last, the one a reader looks up — however little room it has, so a card
+ * too narrow to fit a second label shows one rather than none.
+ *
+ * Whether the track has been MEASURED yet is the caller's fact, not this
+ * function's: a host with no layout pass reports 0 exactly as a 0px track does,
+ * and only the caller knows which it is holding. It answers that itself (show
+ * every label until measured) before asking here. Returning `[]` for both a
+ * zero width and a zero count made one value mean two things, and the two call
+ * sites duly read it two ways — the line chart as "not measured", the bar chart
+ * as "kept nothing", which is how a narrow card came to erase its whole label
+ * row.
+ */
+export function axisLabelIndices(
+  count: number,
+  chartWidth: number,
+  minLabelWidth = 50,
+): number[] {
+  if (count <= 0) return [];
+  if (count === 1) return [0];
+
+  const last = count - 1;
+  const step = axisLabelStep(count, chartWidth, minLabelWidth);
+
+  const kept: number[] = [];
+  for (let i = last; i >= 0; i -= step) kept.unshift(i);
+
+  const firstKept = kept[0] ?? 0;
+  if (firstKept > 0 && (firstKept / last) * chartWidth >= minLabelWidth) kept.unshift(0);
+
+  return kept;
+}