@lotics/ui 46.2.0 → 46.3.0

package/src/bar_chart.tsx

@@ -1,11 +1,23 @@
-import { View, StyleSheet, type ViewStyle } from "react-native";
-import { useMemo } from "react";
+import { View, StyleSheet, type LayoutChangeEvent, type ViewStyle } from "react-native";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { Text } from "./text";
 import { colors } from "./colors";
+import { axisLabelIndices } from "./axis_label_indices";
 import { useLoticsLocale } from "./locale";
 
 const DEFAULT_BAR_COLOR = colors.blue[500];
 
+/** The horizontal orientation's label column, in px, when the caller names none. */
+const DEFAULT_LABEL_WIDTH = 80;
+
+/** The value axis's own column — the gutter the vertical bars start after. */
+const AXIS_LABEL_WIDTH = 56;
+
+/** The gap between bar slots, and therefore between label slots. Named because
+ *  the label box's width is computed from the slot PITCH (slot + gap), and a
+ *  second literal there would silently stop matching the row it measures. */
+const LABEL_GAP = 8;
+
 const defaultFormatNumber = (n: number): string =>
   new Intl.NumberFormat(undefined, { maximumFractionDigits: 1 }).format(n);
 
@@ -13,6 +25,17 @@ export interface BarChartItem {
   label: string;
   value: number;
   color?: string;
+  /**
+   * The entity's own mark, before its name — a `BrandMark`, an `Avatar`, a
+   * status dot. A bar is one entity, and a chart beside a table over the same
+   * entities has to draw them the same way; the bar's COLOUR belongs to the
+   * measure, so it cannot carry identity as a legend swatch does.
+   *
+   * Horizontal: in the label column, ahead of the name. Vertical: above it,
+   * where the axis label sits — and thinned out with that label when the axis
+   * cannot fit them all.
+   */
+  leading?: ReactNode;
 }
 
 export interface BarChartProps {
@@ -20,6 +43,13 @@ export interface BarChartProps {
   orientation?: "vertical" | "horizontal";
   formatNumber?: (n: number) => string;
   emptyLabel?: string;
+  /**
+   * The horizontal orientation's fixed label column, in px (default 80). It is
+   * fixed because every row's bar has to start on one left edge; it is a prop
+   * because 80 fits a date and not a company name, and how long an entity's
+   * name runs is the caller's fact, not the chart's.
+   */
+  labelWidth?: number;
 }
 
 function useAxisTicks(maxValue: number) {
@@ -62,9 +92,13 @@ function useAxisTicks(maxValue: number) {
 }
 
 /**
- * The canonical SVG bar chart over `data: { label, value, color? }[]` — `orientation`
- * vertical|horizontal, nice auto axis ticks, `formatNumber` for value labels. (No recharts.) For
- * one inline trend use `Sparkline`; for parts-of-a-whole, `PieChart` / `Breakdown`.
+ * The canonical SVG bar chart over `data: { label, value, color?, leading? }[]` —
+ * `orientation` vertical|horizontal, nice auto axis ticks, `formatNumber` for value labels,
+ * `labelWidth` for the horizontal label column. (No recharts.) For one inline trend use
+ * `Sparkline`; for parts-of-a-whole, `PieChart` / `Breakdown`.
+ *
+ * The vertical axis prints as many labels as it fits and thins the rest, so the number of
+ * bars is never decided by how wide a label happens to be.
  */
 export function BarChart(props: BarChartProps) {
   const locale = useLoticsLocale();
@@ -73,12 +107,73 @@ export function BarChart(props: BarChartProps) {
     orientation = "vertical",
     formatNumber = defaultFormatNumber,
     emptyLabel = locale.chart.noData,
+    labelWidth = DEFAULT_LABEL_WIDTH,
   } = props;
   const maxValue = Math.max(...data.map((d) => d.value), 1);
   const axisTicks = useAxisTicks(maxValue);
   const axisMax = axisTicks[axisTicks.length - 1] || maxValue;
   const barAreaHeight = 200;
 
+  // The vertical axis prints as many labels as the row fits and thins the rest —
+  // the same rule `LineChart` runs, because it is the axis's rule and not one
+  // chart's. Without it the label box IS the bar slot: 13 bars in a 1000px card
+  // give each label 38px, so a `dd/MM` ellipsises and the axis stops being
+  // readable at exactly the density that makes a bar chart worth drawing. The
+  // BARS never thin — dropping data to fit typography is the wrong trade.
+  const [labelsWidth, setLabelsWidth] = useState(0);
+  const handleLabelsLayout = useCallback((event: LayoutChangeEvent) => {
+    setLabelsWidth(event.nativeEvent.layout.width);
+  }, []);
+  // ONE derivation from the ONE measurement — which labels survive AND how wide
+  // the box each survivor gets. They are two answers about the same row, and a
+  // second pass over the same numbers is exactly how they came to disagree about
+  // it.
+  //
+  // THE SPACE THE THINNING FREED, HANDED TO THE LABEL THAT SURVIVED.
+  //
+  // Dropping a neighbour is only half the fix: the survivor still sits in its
+  // own bar slot, and a one-line `Text` is capped at that slot's width and
+  // ellipsises inside it — so the axis kept fewer labels and clipped them just
+  // the same, with a blank slot beside each one. The label box therefore spans
+  // the STEP: `step` slots and the gaps between them, centred on its bar, which
+  // is exactly the room the dropped labels vacated. The bar slots themselves
+  // never move, so an unlabelled bar stays a blank slot rather than a narrower
+  // one — the box overflows the slot instead of resizing it.
+  const axisLabels = useMemo(() => {
+    // Unmeasured (first paint, and any host with no layout pass) shows every
+    // label, which is where this started — thinning is what measurement BUYS,
+    // never a precondition for rendering an axis at all.
+    if (labelsWidth <= 0 || data.length === 0) return null;
+    // `labelsRow` holds the axis spacer AND one slot per bar, so its N slots
+    // carry N gaps rather than N-1: `track` is already `sum(slots) + N·gap`, and
+    // the slot PITCH is therefore `track / N` — the gaps net out exactly. The
+    // survivor's box spans `step` slots and the `step - 1` gaps between them,
+    // which is `step · pitch - gap`.
+    const track = labelsWidth - AXIS_LABEL_WIDTH;
+    const pitch = track / data.length;
+    const keptIndices = axisLabelIndices(data.length, track);
+    // The span comes from the KEPT SET, never from `axisLabelStep`. The two are
+    // allowed to disagree — `axisLabelIndices` re-adds index 0 when there is
+    // room for it, so a step of `count` can still yield two survivors — and
+    // sizing off the step then hands EACH of them a box spanning the whole
+    // track, so the two labels overlap. Reading one source of truth cannot
+    // drift, whatever the thinning rule becomes later.
+    const gaps = keptIndices.slice(1).map((v, i) => v - keptIndices[i]);
+    const span = gaps.length > 0 ? Math.min(...gaps) : data.length;
+    const boxWidth = span > 1 ? span * pitch - LABEL_GAP : 0;
+    return {
+      kept: new Set(keptIndices),
+      // Undefined when nothing was dropped (`step === 1`): the slot IS the box,
+      // and an explicit width there would only re-state it. Undefined too when
+      // the span is not a positive number of pixels — a card narrower than the
+      // value axis's own gutter leaves a track of zero or less, and a `width: 0`
+      // box would ERASE the label the thinning just chose to keep. Letting it
+      // overflow its slot is the same trade the row makes everywhere else: the
+      // axis thins labels, it never deletes them.
+      boxWidth: boxWidth > 0 ? boxWidth : undefined,
+    };
+  }, [data.length, labelsWidth]);
+
   if (data.length === 0) {
     return (
       <View style={styles.chartContainer}>
@@ -97,7 +192,8 @@ export function BarChart(props: BarChartProps) {
 
             return (
               <View key={index} style={styles.horizontalBarContainer}>
-                <View style={styles.horizontalBarLabel}>
+                <View style={[styles.horizontalBarLabel, { width: labelWidth }]}>
+                  {item.leading !== undefined ? item.leading : null}
                   <Text size="sm" numberOfLines={1}>
                     {item.label}
                   </Text>
@@ -122,7 +218,7 @@ export function BarChart(props: BarChartProps) {
             );
           })}
           <View style={styles.horizontalAxisContainer}>
-            <View style={styles.horizontalBarLabel} />
+            <View style={{ width: labelWidth }} />
             <View style={styles.horizontalAxisTrack}>
               {axisTicks.map((tick, index) => (
                 <View
@@ -186,14 +282,27 @@ export function BarChart(props: BarChartProps) {
             })}
           </View>
         </View>
-        <View style={styles.labelsRow}>
+        <View style={styles.labelsRow} onLayout={handleLabelsLayout}>
           <View style={styles.axisLabelSpacer} />
           {data.map((item, index) => (
+            // The slot stays whatever the axis prints, so the bars above it keep
+            // their positions — an unlabelled bar is a blank slot, never a
+            // narrower one.
             <View key={index} style={styles.labelContainer}>
-              <Text numberOfLines={1} weight="medium">
-                {item.label}
-              </Text>
-              <Text color="muted">{formatNumber(item.value)}</Text>
+              {axisLabels === null || axisLabels.kept.has(index) ? (
+                <View
+                  style={[
+                    styles.labelBox,
+                    axisLabels?.boxWidth !== undefined && { width: axisLabels.boxWidth },
+                  ]}
+                >
+                  {item.leading !== undefined ? item.leading : null}
+                  <Text numberOfLines={1} weight="medium">
+                    {item.label}
+                  </Text>
+                  <Text color="muted">{formatNumber(item.value)}</Text>
+                </View>
+              ) : null}
             </View>
           ))}
         </View>
@@ -215,7 +324,7 @@ const styles = StyleSheet.create({
     gap: 8,
   },
   verticalAxis: {
-    width: 56,
+    width: AXIS_LABEL_WIDTH,
     position: "relative",
   },
   verticalAxisTick: {
@@ -243,15 +352,23 @@ const styles = StyleSheet.create({
   },
   labelsRow: {
     flexDirection: "row",
-    gap: 8,
+    gap: LABEL_GAP,
   },
   labelContainer: {
     flex: 1,
     alignItems: "center",
     gap: 2,
   },
+  // Wider than its slot when the axis thinned, and centred on the bar by the
+  // slot's own `alignItems` — a flex item wider than its cross-axis space
+  // overflows both edges equally, which is what puts the label over the blank
+  // slots beside it rather than clipping it inside its own.
+  labelBox: {
+    alignItems: "center",
+    gap: 2,
+  },
   axisLabelSpacer: {
-    width: 56,
+    width: AXIS_LABEL_WIDTH,
   },
   horizontalChart: {
     gap: 8,
@@ -264,8 +381,12 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 8,
   },
+  // The width is the instance's `labelWidth`; what lives here is the row shape —
+  // the entity's mark, then its name, on one line.
   horizontalBarLabel: {
-    width: 80,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
   },
   horizontalBarTrack: {
     flex: 1,

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/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>