@lotics/ui 46.1.0 → 46.3.0

package/src/dialog.tsx

@@ -17,6 +17,7 @@ import {
   useNavigationStack,
 } from "./screen_router";
 import { HeadingAltitudeContext } from "./heading_altitude";
+import { useScrollSeam } from "./use_scroll_seam";
 
 // ============================================================================
 // Shared Navigation Context (used by both Dialog and MasterDetailDialog)
@@ -191,29 +192,39 @@ export function Dialog(props: DialogProps) {
       <ScreenRouterInternalContext.Provider value={internalValue}>
         <DialogContext.Provider value={dialogValue}>
           <DialogNavigationProvider value={navigationContextValue}>
-            <Modal visible={open} onRequestClose={handleClose} transparent>
-              <View style={styles.base}>
-                <View style={styles.background} />
-                <Animated.View
-                  style={{
-                    top: effectiveOffsetTop,
-                    width: screenSize.small ? "100%" : width,
-                    height: screenSize.small ? "100%" : height,
-                    maxHeight: screenSize.small ? undefined : maxHeight,
-                    maxWidth: screenSize.small ? undefined : maxWidth,
-                  }}
-                >
-                  <PortalHost>
-                    <View testID={testID} style={[styles.dialogContainer, { borderRadius }]}>
-                      <View style={[styles.closeButtonContainer, { paddingHorizontal: gutter }]}>
-                        <IconButton icon="x" size="lg" accessibilityLabel={locale.overlay.close} onPress={handleClose} />
+            {/* Mounted only while OPEN. react-native-web appends a `Modal`'s
+                body-level div on first render and never re-orders it, so an
+                always-mounted dialog claims its DOM slot before a drawer that
+                opens later and is then covered by it — readable, announced, and
+                dead to every press. Mounting on open makes DOM order open order.
+                Nothing is lost: a closed `Modal` renders its children as `null`
+                already, and everything that must survive a close (the router,
+                the contexts) lives outside this element. */}
+            {open && (
+              <Modal visible onRequestClose={handleClose} transparent>
+                <View style={styles.base}>
+                  <View style={styles.background} />
+                  <Animated.View
+                    style={{
+                      top: effectiveOffsetTop,
+                      width: screenSize.small ? "100%" : width,
+                      height: screenSize.small ? "100%" : height,
+                      maxHeight: screenSize.small ? undefined : maxHeight,
+                      maxWidth: screenSize.small ? undefined : maxWidth,
+                    }}
+                  >
+                    <PortalHost>
+                      <View testID={testID} style={[styles.dialogContainer, { borderRadius }]}>
+                        <View style={[styles.closeButtonContainer, { paddingHorizontal: gutter }]}>
+                          <IconButton icon="x" size="lg" accessibilityLabel={locale.overlay.close} onPress={handleClose} />
+                        </View>
+                        <SizeBoundary style={styles.container}>{children}</SizeBoundary>
                       </View>
-                      <SizeBoundary style={styles.container}>{children}</SizeBoundary>
-                    </View>
-                  </PortalHost>
-                </Animated.View>
-              </View>
-            </Modal>
+                    </PortalHost>
+                  </Animated.View>
+                </View>
+              </Modal>
+            )}
           </DialogNavigationProvider>
         </DialogContext.Provider>
       </ScreenRouterInternalContext.Provider>
@@ -280,11 +291,19 @@ export function DialogHeaderActions(props: DialogHeaderActionsProps) {
 
 export interface DialogScrollAreaProps {
   children: React.ReactNode;
+  /**
+   * The IDENTITY of the content in the scroller, for a pane that SWAPS its body
+   * in place — see `DrawerScrollArea`. A dialog that navigates between `Screen`s
+   * does not need it: a stacked screen stays mounted, so each screen keeps its
+   * own scroll area and its own offset already.
+   */
+  scrollKey?: string;
 }
 
 export function DialogScrollArea(props: DialogScrollAreaProps) {
-  const { children } = props;
+  const { children, scrollKey } = props;
   const gutter = useDialogGutter();
+  const seam = useScrollSeam(scrollKey);
 
   // The gutter and the heading altitude are the same kind of fact — both belong
   // to the panel, and both were being answered by callers who could only guess.
@@ -292,7 +311,10 @@ export function DialogScrollArea(props: DialogScrollAreaProps) {
   // `lg` `DialogHeaderTitle` above it. See `heading_altitude.ts`.
   return (
     <HeadingAltitudeContext.Provider value="panel">
-      <ScrollView contentContainerStyle={[styles.scrollAreaContent, { paddingHorizontal: gutter }]}>
+      <ScrollView
+        {...seam}
+        contentContainerStyle={[styles.scrollAreaContent, { paddingHorizontal: gutter }]}
+      >
         {children}
       </ScrollView>
     </HeadingAltitudeContext.Provider>

package/src/drawer.tsx

@@ -9,6 +9,7 @@ import { Text } from "@lotics/ui/text";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
 import { useLoticsLocale } from "@lotics/ui/locale";
 import { HeadingAltitudeContext } from "./heading_altitude";
+import { useScrollSeam } from "./use_scroll_seam";
 
 /**
  * The panel's inset — the ONE left edge the header, `DrawerScrollArea` and the footer
@@ -103,8 +104,14 @@ export function Drawer(props: DrawerProps) {
     return () => document.removeEventListener("keydown", handler);
   }, [open, onPrev, onNext]);
 
+  // Mounted only while OPEN — see `overlay_layer.ts`. react-native-web appends a
+  // `Modal`'s body-level div on first render and never re-orders it, so an
+  // always-mounted overlay claims its slot ahead of one opened later and covers
+  // it. Mounting on open makes DOM order open order.
+  if (!open) return null;
+
   return (
-    <Modal visible={open} onRequestClose={handleClose} transparent>
+    <Modal visible onRequestClose={handleClose} transparent>
       <View style={styles.base}>
         {/* Scrim is a sibling of the panel, so tapping the panel never closes. */}
         <Pressable style={styles.scrim} onPress={handleClose} accessibilityLabel={loc.close} tabIndex={-1} />
@@ -153,6 +160,17 @@ export function Drawer(props: DrawerProps) {
 
 export interface DrawerScrollAreaProps {
   children: ReactNode;
+  /**
+   * The IDENTITY of the content in the scroller — a record id, a step name.
+   *
+   * Set it on a drawer that SWAPS its body in place (the master-detail shape: a
+   * child row replaces the record rather than stacking a second drawer).
+   * Changing it opens the new content at the top and restores the previous
+   * content's offset when the key comes back, so the way forward starts where a
+   * reader expects and the way back keeps their place in the list they came
+   * from. Omit it on a drawer whose body is one thing.
+   */
+  scrollKey?: string;
 }
 
 /**
@@ -192,9 +210,10 @@ export function DrawerScrollArea(props: DrawerScrollAreaProps) {
   // Not on `Drawer` itself: the drawer's BARE slot is where a whole record
   // screen goes, and that surface brings its own `#` identity band, so its
   // sections are page sections and must stay `##`. See `heading_altitude.ts`.
+  const seam = useScrollSeam(props.scrollKey);
   return (
     <HeadingAltitudeContext.Provider value="panel">
-      <ScrollView style={styles.body} contentContainerStyle={styles.bodyContent}>{props.children}</ScrollView>
+      <ScrollView {...seam} style={styles.body} contentContainerStyle={styles.bodyContent}>{props.children}</ScrollView>
     </HeadingAltitudeContext.Provider>
   );
 }

package/src/file_gallery_modal.tsx

@@ -211,6 +211,9 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
   ];
 
   return (
+    // Rendered only while a file is open (`activeIndex !== null` returns null
+    // above), which is what puts this overlay's body-level div in open order —
+    // see `overlay_layer.ts`.
     <Modal visible transparent onRequestClose={close} animationType="fade">
       {/* PortalHost so the ⋯ menu's popover portals INSIDE the modal's stacking
           context (on top) instead of to the app-root host behind the overlay —

package/src/line_chart.tsx

@@ -4,7 +4,7 @@ import { colors } from "./colors";
 import { useMemo, useState, useCallback } from "react";
 import Svg, { Circle, Defs, Line, LinearGradient, Polygon, Polyline, Stop } from "react-native-svg";
 import { useLoticsLocale } from "./locale";
-import { lineChartLabelIndices } from "./line_chart_labels";
+import { axisLabelIndices } from "./axis_label_indices";
 
 export interface LineChartPoint {
   x: string | number;
@@ -97,7 +97,7 @@ export function LineChart(props: LineChartProps) {
   const visibleLabels = useMemo(() => {
     if (data.length === 0 || chartWidth === 0) return [];
 
-    return lineChartLabelIndices(data.length, chartWidth).map((index) => ({
+    return axisLabelIndices(data.length, chartWidth).map((index) => ({
       index,
       label: formatXLabel(data[index].x),
     }));

package/src/locale.tsx

@@ -460,9 +460,9 @@ export const en: LoticsLocale = {
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
   agentRun: {
-    starting: "Starting…",
+    starting: "Starting",
     thinking: "Thinking",
-    thinkingStreaming: "Thinking…",
+    thinkingStreaming: "Thinking",
     input: "Input",
     error: "Error",
     output: "Output",
@@ -667,9 +667,9 @@ export const vi: LoticsLocale = {
   scrollToBottom: { tooltip: "Cuộn xuống cuối" },
   textInputField: { clear: "Xóa" },
   agentRun: {
-    starting: "Đang bắt đầu…",
+    starting: "Đang bắt đầu",
     thinking: "Suy nghĩ",
-    thinkingStreaming: "Đang suy nghĩ…",
+    thinkingStreaming: "Đang suy nghĩ",
     input: "Đầu vào",
     error: "Lỗi",
     output: "Kết quả",

package/src/modal.tsx

@@ -7,6 +7,7 @@ import { PortalHost } from "@lotics/ui/portal";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
 import { useLoticsLocale } from "@lotics/ui/locale";
 import { HeadingAltitudeContext } from "./heading_altitude";
+import { useScrollSeam } from "./use_scroll_seam";
 
 export interface ModalProps {
   open: boolean;
@@ -34,8 +35,17 @@ export function Modal(props: ModalProps) {
   const { open, onClose, children, testID } = props;
   useOverlayScope(open);
 
+  // Mounted only while OPEN — see `overlay_layer.ts`. react-native-web appends a
+  // `Modal`'s body-level div on first render and never re-orders it, so an
+  // always-mounted overlay claims its slot ahead of one opened later and covers
+  // it. Mounting on open makes DOM order open order. `animationType` still
+  // FADES IN (the element mounts already visible and the animation runs on the
+  // first paint); the exit is immediate, exactly as `FileGalleryModal`'s
+  // full-screen takeover has always closed.
+  if (!open) return null;
+
   return (
-    <RNModal visible={open} onRequestClose={onClose} animationType="fade">
+    <RNModal visible onRequestClose={onClose} animationType="fade">
       <View testID={testID} style={styles.surface}>
         <PortalHost>{children}</PortalHost>
       </View>
@@ -93,6 +103,13 @@ export function ModalHeader(props: ModalHeaderProps) {
 
 export interface ModalBodyProps {
   children: ReactNode;
+  /**
+   * The IDENTITY of the content in the scroller, for a takeover that SWAPS its
+   * body in place — a wizard stepping between steps, a console changing subject.
+   * Changing it opens the new content at the top and restores the previous
+   * content's offset when the key comes back. See `DrawerScrollArea`.
+   */
+  scrollKey?: string;
 }
 
 /**
@@ -100,14 +117,17 @@ export interface ModalBodyProps {
  * footer. Fills the remaining height; its content scrolls.
  */
 export function ModalBody(props: ModalBodyProps) {
-  const { children } = props;
+  const { children, scrollKey } = props;
+  const seam = useScrollSeam(scrollKey);
   // A takeover is still a panel: `ModalHeader`'s title is `lg`, so a section
   // heading inside the body takes the ramp's `####` rung. Same rule as the
   // drawer and the dialog, published from the same kind of region — the one
   // that owns the surface's padding. See `heading_altitude.ts`.
   return (
     <HeadingAltitudeContext.Provider value="panel">
-      <ScrollView contentContainerStyle={styles.bodyContent}>{children}</ScrollView>
+      <ScrollView {...seam} contentContainerStyle={styles.bodyContent}>
+        {children}
+      </ScrollView>
     </HeadingAltitudeContext.Provider>
   );
 }

package/src/overlay_layer.ts

@@ -0,0 +1,65 @@
+/**
+ * THE PAINT ORDER OF EVERYTHING THE KIT PUTS AT THE TOP OF THE DOCUMENT.
+ *
+ * Every overlay in the kit (`Dialog`, `Drawer`, `Modal`, `FileGalleryModal`) is
+ * a react-native `Modal`, and on web that mounts a bare `<div>` on
+ * `document.body`, at the END of it, and removes it again when it unmounts. The
+ * layer inside sits at one fixed z-index, the same one for every overlay, so two
+ * open overlays tie and the tie is broken by DOM order.
+ *
+ * So the rule is one line of composition, not a mechanism: **the react-native
+ * `Modal` element is rendered only while the overlay is OPEN**. Its body-level
+ * div is then appended when it opens and removed when it closes, DOM order is
+ * open order, and paint order follows for free — a drawer opened from a dialog
+ * covers the dialog, a dialog opened from a drawer covers the drawer, and
+ * neither composition has to be picked in advance.
+ *
+ * Mounting the `Modal` while CLOSED is what breaks this, and it breaks it
+ * silently: `ModalPortal` appends its div on FIRST RENDER and never re-orders
+ * it, so an always-mounted dialog claims its slot on the app's first paint and a
+ * drawer opened later lands after it and covers it. The dialog then renders
+ * perfectly — centred, readable, correctly announced — and every control of it
+ * under the drawer panel is dead, because `elementFromPoint` there answers the
+ * drawer. Nothing is lost by not mounting it: react-native-web renders a closed
+ * `Modal`'s children as `null` anyway, so the subtree is already unmounted; only
+ * the empty portal div was being held.
+ *
+ * The rungs BESIDE the overlays are what needs naming, and they are a PUBLISHED
+ * CONTRACT — anything outside the kit that must clear a Lotics overlay reads one
+ * from here rather than picking a literal:
+ *
+ *   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`)
+ */
+
+/**
+ * Where every overlay sits — react-native-web's own number for a `Modal`, and
+ * the one `Popover` writes into its panel.
+ *
+ * They all share it on purpose. A popover is not an RN `Modal`: it portals into
+ * the nearest `PortalHost`, so a popover 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 modal's body-level div follows. One number plus DOM
+ * order therefore says the same thing for a popover as for a modal: whatever was
+ * opened last is on top.
+ */
+export const OVERLAY_Z = 9999;
+
+/**
+ * ABOVE EVERY OVERLAY — a tooltip and an alert are ABOUT the surface under them,
+ * so neither can ever be covered by it.
+ */
+export const OVERLAY_Z_ABOVE = OVERLAY_Z + 1;
+
+/**
+ * A transient notification (a toast) reporting the outcome of an action — over
+ * the alert on the rung below, because the action that raised it is often the
+ * one that alert confirmed, and a report nobody can read is not a report.
+ */
+export const NOTIFICATION_Z = OVERLAY_Z_ABOVE + 1;
+
+/** The skip link outranks everything: it is the first thing a keyboard reaches.
+ *  It shared a rung with the toast until this table gave each one a name. */
+export const SKIP_LINK_Z = NOTIFICATION_Z + 1;

package/src/page_content.tsx

@@ -1,7 +1,6 @@
 import { ScrollView, View } from "react-native";
-import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
-import { Spacer } from "@lotics/ui/spacer";
+import { PageHeader } from "@lotics/ui/page_header";
 import { ReactNode } from "react";
 import { useContainerSize } from "@lotics/ui/size_boundary";
 import { pagePad } from "@lotics/ui/spacing";
@@ -81,27 +80,14 @@ export function PageContent(props: PageContentProps) {
             paddingHorizontal: pad,
           }}
         >
-          <View
-            style={{
-              flexDirection: "row",
-              alignItems: "center",
-              justifyContent: "space-between",
-            }}
-          >
-            {!!title && (
-              <Text size="xxl" weight="semibold">
-                {title}
-              </Text>
-            )}
-            {titleRight && <View>{titleRight}</View>}
-          </View>
-          {!!description && (
-            <>
-              {title && <Spacer size={8} />}
-              <Text color="zinc-500">{description}</Text>
-            </>
+          {/* The title band IS a `PageHeader` — the same optional xxl title, the
+              same right-hand slot, the same zinc-500 description, so it is that
+              component and not a second copy of it. Written out here it drifted
+              immediately: two spellings of one row law and two rhythms around
+              it, with `titleRight` and `actions` naming the same slot. */}
+          {(!!title || !!description || !!titleRight) && (
+            <PageHeader title={title} description={description} actions={titleRight} />
           )}
-          {(title || description) && <Spacer size={24} />}
           <View style={{ flex: 1 }}>{children}</View>
         </View>
       </ScrollView>

package/src/page_header.tsx

@@ -1,9 +1,12 @@
 import { View } from "react-native";
 import { Text } from "@lotics/ui/text";
+import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
 
 interface PageHeaderProps {
-  title: string;
+  /** The page's name. Optional only so the SHELL can delegate to this component
+   *  for a band that is description-only; a page header normally has one. */
+  title?: string;
   description?: string | null;
   /** The nav row ABOVE the title — breadcrumbs, a back control, row-level status. */
   left?: ReactNode;
@@ -60,7 +63,6 @@ export function PageHeader(props: PageHeaderProps) {
       style={{
         flexDirection: "row",
         alignItems: "center",
-        justifyContent: "space-between",
         flexWrap: "wrap",
         gap: 12,
       }}
@@ -74,9 +76,11 @@ export function PageHeader(props: PageHeaderProps) {
           minWidth: 0,
         }}
       >
-        <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
-          {title}
-        </Text>
+        {!!title && (
+          <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
+            {title}
+          </Text>
+        )}
         {/* Never shrinks: the title is what gives way, and a control squeezed
             below its own icon is not a smaller control, it is a broken one. */}
         {trailing !== undefined && <View style={{ flexShrink: 0 }}>{trailing}</View>}
@@ -84,8 +88,14 @@ export function PageHeader(props: PageHeaderProps) {
       {/* Wrapped so which side gives way is STATED rather than left to whatever
           the caller happened to pass. A bare `{actions}` inherited its own
           shrink behaviour, so the row's bargain held or broke depending on the
-          CTA — and a bargain that depends on the other party is not one. */}
-      {actions !== undefined && <View style={{ flexShrink: 0 }}>{actions}</View>}
+          CTA — and a bargain that depends on the other party is not one.
+          `marginLeft: auto` rather than the row's `justifyContent`, because
+          justification is applied PER LINE: once the row wraps, the second line
+          holds only the actions and `space-between` packs that one item at the
+          START, dropping the CTA to the left edge under the title on exactly the
+          narrow frame the wrap exists for. An auto margin right-aligns it on the
+          shared line and on a line of its own alike. */}
+      {actions !== undefined && <View style={{ flexShrink: 0, marginLeft: "auto" }}>{actions}</View>}
     </View>
   );
 
@@ -93,9 +103,45 @@ export function PageHeader(props: PageHeaderProps) {
     <View style={{ paddingBottom: 16 }}>
       {hasNav ? (
         <>
-          <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", height: 64, paddingBottom: 16 }}>
-            {left}
-            {right}
+          {/* The SAME three facts as the title row, for the same reason — this
+              row is a pair of intrinsically-sized children too, and a
+              breadcrumb trail is exactly the kind of thing that outgrows a
+              narrow frame. `minHeight` rather than `height`: a fixed height
+              cannot absorb a wrap, so the row that most needs to grow was the
+              one forbidden to. */}
+          <View
+            style={{
+              flexDirection: "row",
+              alignItems: "center",
+              flexWrap: "wrap",
+              gap: 12,
+              minHeight: 64,
+              paddingBottom: 16,
+            }}
+          >
+            {/* `flexDirection: "row"` is not decoration: these wrappers RE-PARENT
+                what used to be a direct child of the row, and a react-native
+                `View` defaults to `column`. Both props are documented as taking
+                a nav row's worth of content — "breadcrumbs, a back control,
+                row-level status" — so a fragment of several nodes is the shape
+                they invite, and without the axis restated it lays out
+                top-to-bottom. A wrapper added to state a shrink rule must not
+                also silently state a direction. */}
+            <View style={{ flexDirection: "row", alignItems: "center", flexShrink: 1, minWidth: 0 }}>
+              {left}
+            </View>
+            {right !== undefined && (
+              <View
+                style={{
+                  flexDirection: "row",
+                  alignItems: "center",
+                  flexShrink: 0,
+                  marginLeft: "auto",
+                }}
+              >
+                {right}
+              </View>
+            )}
           </View>
           {titleRow}
         </>
@@ -103,7 +149,10 @@ export function PageHeader(props: PageHeaderProps) {
         titleRow
       )}
       {!!description && (
-        <Text color="zinc-500">{description}</Text>
+        <>
+          {!!title && <Spacer size={8} />}
+          <Text color="zinc-500">{description}</Text>
+        </>
       )}
     </View>
   );

package/src/popover.tsx

@@ -23,6 +23,8 @@ import {
 } from "./popover_layers";
 import { PopoverNavContext, type PopoverNavContextValue } from "./popover_nav";
 import { useLoticsLocale } from "./locale";
+import { OVERLAY_Z } from "./overlay_layer";
+import { useScrollSeam } from "./use_scroll_seam";
 import { HeadingAltitudeContext } from "./heading_altitude";
 
 export type PopoverSide = "top" | "right" | "bottom" | "left";
@@ -269,6 +271,22 @@ export function PopoverContent(props: PopoverContentProps) {
   // inside it must not dismiss this popover. See popover_layers.ts.
   const modalsAtOpenRef = useRef<ReadonlySet<Element> | null>(null);
 
+  // THE SEAM EVERY SCROLLER THAT SWAPS ITS BODY IN PLACE TAKES.
+  //
+  // A routed popover is one: `PopoverScreen` renders `null` for every route but
+  // the active one, and the screens are children of THIS scroller — so
+  // navigating from a long root list to a sub-screen leaves the container at the
+  // list's offset and opens the sub-screen part-way down itself, its
+  // `PopoverNavHeader` and back chevron scrolled off the top. Same failure as a
+  // master-detail drawer's, in the kit's own navigation primitive.
+  //
+  // The route IS the content's identity, so it is read here rather than asked
+  // for: a popover with no sub-screens sits on the root route forever, its key
+  // never changes, and the seam is inert — which is exactly the opt-out
+  // `use_scroll_seam` defines.
+  const currentRoute = useContext(PopoverNavContext)?.currentRoute;
+  const bodySeam = useScrollSeam(currentRoute);
+
   const handleClose = useCallback(() => {
     if (!open) return;
     onOpenChange(false);
@@ -603,9 +621,6 @@ export function PopoverContent(props: PopoverContentProps) {
   if (!open) return null;
 
   const nestingLevel = getNestingLevel();
-  const baseZIndex = 9999;
-  const overlayZIndex = baseZIndex + nestingLevel * 2;
-  const contentZIndex = baseZIndex + nestingLevel * 2 + 1;
 
   return (
     // A popover is dialog-scale — a few hundred px with its own chrome — so a
@@ -630,7 +645,7 @@ export function PopoverContent(props: PopoverContentProps) {
               backgroundColor: "rgba(0, 0, 0, 0.5)",
               opacity: isBottomSheetShown ? 1 : 0,
               transition: "opacity 0.3s ease",
-              zIndex: overlayZIndex,
+              zIndex: OVERLAY_Z,
               pointerEvents: "auto",
             }}
             onClick={handleOverlayClick}
@@ -656,7 +671,15 @@ export function PopoverContent(props: PopoverContentProps) {
             backgroundColor: colors.background,
             boxShadow: colors.shadow,
             boxSizing: "border-box",
-            zIndex: contentZIndex,
+            // The kit's ONE overlay rung (`overlay_layer.ts`), shared with every
+            // react-native `Modal` — DOM order settles the tie, and DOM order is
+            // open order for all of them. A nested popover portals into the same
+            // host AFTER its parent; a page-level one is inside the app root,
+            // which every modal's body-level div follows; and one opened INSIDE
+            // an overlay portals into that overlay's own host. The scrim and the
+            // panel share the rung too: siblings in one container, panel written
+            // second.
+            zIndex: OVERLAY_Z,
             transition: small ? "transform 0.3s ease" : undefined,
             ...(small
               ? {
@@ -752,6 +775,7 @@ export function PopoverContent(props: PopoverContentProps) {
             // Horizontal only: the vertical padding is the gap to the header and
             // footer, which is a gap the reader wants.
             <ScrollView
+              {...bodySeam}
               style={[SCROLL_BODY, style]}
               contentContainerStyle={[SCROLL_BODY_CONTENT, contentContainerStyle]}
             >

package/src/skip_link.tsx

@@ -1,5 +1,6 @@
 import { Platform } from "react-native";
 import { colors } from "./colors";
+import { SKIP_LINK_Z } from "./overlay_layer";
 
 export interface SkipLinkProps {
   /** DOM id of the main region to jump to, e.g. `"main-content"`. */
@@ -29,7 +30,7 @@ export function SkipLink(props: SkipLinkProps) {
         color: colors.white,
         textDecoration: "none",
         borderRadius: 4,
-        zIndex: 10001,
+        zIndex: SKIP_LINK_Z,
         transform: "translateY(-200%)",
         transition: "transform 0.15s ease",
       }}

package/src/stacked_bar_chart.tsx

@@ -1,10 +1,11 @@
-import { useMemo } from "react";
+import { useMemo, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
 import { LegendItem } from "./legend_item";
 import { useLoticsLocale } from "./locale";
 import { SPACE } from "./spacing";
 import { Text } from "./text";
+import { TYPE_LEADING_TIGHT_DESKTOP, TYPE_LEADING_TIGHT_MOBILE } from "./type_ramp";
 import type { TextColor } from "./text_utils";
 
 export interface StackedBarSeries {
@@ -17,6 +18,20 @@ export interface StackedBarRow {
   key: string;
   /** The entity this row is about — a campaign, a depot, a month. */
   label: string;
+  /**
+   * That entity's own mark, before its name — a `BrandMark`, an `Avatar`, a
+   * status dot. A chart and a table over the SAME entities inside one card have
+   * to draw them the same way; without a slot the chart can only say the name in
+   * text, and one value ends up with two renderings a few hundred pixels apart.
+   *
+   * A slot rather than a widened `label`, following `Table`/`FileRow`: `label`
+   * is also this row's accessible name and the target of the two-line clamp, and
+   * a `ReactNode` there would lose both.
+   *
+   * The row's SERIES colours belong to the measure, so unlike a legend row this
+   * one carries no identity of its own until you give it one.
+   */
+  leading?: ReactNode;
   /** A neutral qualifier beside the label ("Đang chạy", "12 đơn"). */
   meta?: string;
   /** Per-series magnitudes, keyed by `StackedBarSeries.key`. Negatives are dropped. */
@@ -110,6 +125,9 @@ export function StackedBarChart(props: StackedBarChartProps) {
                   that also has to fit a status and a figure spends a narrow
                   container's width truncating exactly that. */}
               <View style={styles.head}>
+                {row.leading !== undefined ? (
+                  <View style={styles.leading}>{row.leading}</View>
+                ) : null}
                 <View style={styles.headText}>
                   <Text size="sm" weight="medium" numberOfLines={2} leading="tight">
                     {row.label}
@@ -181,6 +199,18 @@ const styles = StyleSheet.create({
     minWidth: 0,
     gap: 1,
   },
+  // The mark centres on the LABEL'S OWN LINE BOX, not on the head — a row that
+  // also carries `meta` is two lines tall, and centring on the head would drift
+  // the mark down between them for that row only. Giving the slot the line box's
+  // height and centring inside it lands any mark on the first line whatever the
+  // mark's size, so a dot and a 24px avatar both sit right without either being
+  // measured. `sm` is the same box at both breakpoints; the max is what keeps
+  // that from being an assumption.
+  leading: {
+    height: Math.max(TYPE_LEADING_TIGHT_MOBILE.sm, TYPE_LEADING_TIGHT_DESKTOP.sm),
+    justifyContent: "center",
+    flexShrink: 0,
+  },
   // The track is the SHARED ruler; the fill is this row's share of it, and the
   // segments split the fill. Three boxes, because collapsing the middle one is
   // exactly how a stacked bar loses its scale.