@lotics/ui 46.2.0 → 46.8.0

package/src/charge_lines.tsx

@@ -0,0 +1,373 @@
+import { createContext, useCallback, useContext, useState, type ReactNode } from "react";
+import { StyleSheet, View, type LayoutChangeEvent } from "react-native";
+import { colors } from "./colors";
+import { CONTROL_TEXT_INSET } from "./control_surface";
+import { InlineNumberInput } from "./inline_number_input";
+import { useLoticsLocale } from "./locale";
+import { SPACE } from "./spacing";
+import { Text } from "./text";
+
+
+/**
+ * The editable money band — what a record charges, priced line by line, closed
+ * by its own total.
+ *
+ * `Ledger` is the READ side of the same subject: three sides and a statement,
+ * for a reader who is checking arithmetic somebody else did. This is the WRITE
+ * side, for the person doing the pricing, and the two are not interchangeable —
+ * a ledger has nothing to type into and this has no notion of adjustments.
+ *
+ * ## Why this exists as a component
+ *
+ * `data_entry.md` §Billing has always prescribed the shape in prose — "a FLAT
+ * hairline-set band that holds its own editable charge lines, its live total,
+ * and its issue action in its closing row" — with nothing to build it from, so
+ * every app hand-rolled it. Hand-rolled versions converge on the same defects,
+ * and they are the reason this file exists:
+ *
+ * - **The derived amount ends up on its own line.** Building the row as
+ *   `[qty] × [price]` and hanging `= amount` underneath doubles the height of
+ *   every charge and leaves the answer floating in the middle of the band,
+ *   aligned to nothing. A charge is ONE line: the arithmetic reads across it and
+ *   ends at the amount.
+ * - **Three money edges instead of two.** A typed price left-aligns inside its
+ *   editor while the derived amount right-aligns, so the two columns drift and
+ *   the total closes a column that only half the figures are in. Every money
+ *   column here is right-aligned and the total lands on the amount column, so
+ *   the band can be added up by eye.
+ * - **The total drifts from the lines.** Computed by the caller from a
+ *   different array, or rounded differently, it stops being the sum of what is
+ *   on screen. Here the total is derived from the lines themselves.
+ *
+ * ## Anatomy
+ *
+ * ```
+ * Gate movements         45  ×    4.000 ₫      180.000 ₫   ×
+ * Terminal cleaning       1  ×   30.000 ₫       30.000 ₫   ×
+ * ──────────────────────────────────────────────────────────
+ * Total                                        210.000 ₫
+ * ```
+ *
+ * Narrow containers fork deliberately: the name takes its own line and the
+ * arithmetic sits under it, RIGHT-ALIGNED to the band so it still ends on the
+ * amount column. That is a two-line row on purpose, which is a different thing
+ * from a derived value that fell off the end of a one-line row — and the tell is
+ * exactly that the amounts still share an edge with the total. The row's money
+ * verb moves up to the name line there, because the arithmetic line has no width
+ * to reserve for it and the name line has room to spare.
+ *
+ * ```
+ * Gate movements                                  4.200 ₫
+ *          45  ×   4.000 ₫       180.000 ₫   ×
+ * ```
+ */
+export interface ChargeLineProps {
+  /** What is being charged. */
+  label: string;
+  /** A neutral qualifier under the label — a basis, a period. Never a problem:
+   *  a problem belongs on the control that can fix it. */
+  meta?: string;
+  /** Priced line: `quantity × unitPrice` derives the amount, and the amount is
+   *  never typed. Leave BOTH out for a flat line whose amount IS the figure
+   *  someone states — a fee agreed as one number rather than computed. */
+  quantity?: number | null;
+  unitPrice?: number | null;
+  /** Flat line: the amount itself. Ignored when `quantity`/`unitPrice` are set,
+   *  because a derived figure and a typed one cannot both be the truth. */
+  amount?: number | null;
+  onAmountChange?: (next: number | null) => void | Promise<void>;
+  /** The same, for a FLAT line's amount. Unconditional and `disabled` when idle. */
+  amountActions?: ReactNode;
+  /** One more control on this line — how it was paid, which party owes it.
+   *  It belongs to the charge, so it rides the charge's own row. */
+  extra?: ReactNode;
+  /** A problem with THIS line, beside the control that fixes it. */
+  warning?: string;
+  /** Format a money figure. Comes from the band; a line never formats its own,
+   *  or two lines in one band disagree about a currency. */
+  formatMoney?: (n: number) => string;
+  onQuantityChange?: (next: number | null) => void | Promise<void>;
+  onUnitPriceChange?: (next: number | null) => void | Promise<void>;
+  /**
+   * A verb about the unit price — "apply the standard rate" — as an
+   * `InlineButton`, which rides the field it acts on rather than standing on
+   * its own beside it.
+   *
+   * **Pass it UNCONDITIONALLY and `disabled` it when there is nothing to act
+   * on.** Passing it only when it has work makes the field narrower on the rows
+   * that carry it, so a row with a one-tap rate and a row without stop sharing
+   * a price column — and a verb that appears and disappears as a value changes
+   * is furniture the reader cannot learn.
+   */
+  unitPriceActions?: ReactNode;
+  /** The row's own verb, usually removal. Rendered in a fixed slot so the money
+   *  column does not move between a row that has one and a row that does not. */
+  action?: ReactNode;
+  /** Read-only band: editors become values, and no action slot is drawn. */
+  locked?: boolean;
+}
+
+export interface ChargeLinesProps {
+  /** The lines. Absent is a real state — a record that has not been priced yet
+   *  — so this is optional and `empty` speaks for it. */
+  children?: ReactNode;
+  /** Label for the closing row. */
+  totalLabel: string;
+  /** The band's total. Pass the sum of the lines on screen — a total that is
+   *  not the sum of something visible is the one figure a reader cannot check. */
+  total: number;
+  formatMoney: (n: number) => string;
+  /** Sits in the closing row beside the total — the issue/collect action. */
+  action?: ReactNode;
+  /** Shown in place of the lines when there are none. */
+  empty?: ReactNode;
+}
+
+const QTY_W = 76;
+const OP_W = 14;
+const PRICE_W = 132;
+const QTY_W_NARROW = 48;
+const PRICE_W_NARROW = 92;
+const AMOUNT_W = 108;
+const ACTION_W = 32;
+/** Below this the row forks to two lines. Measured on the CONTAINER, never the
+ *  window: this band lives in drawers as often as on pages. */
+const FORK_AT = 520;
+
+export function ChargeLines(props: ChargeLinesProps) {
+  const { children, totalLabel, total, formatMoney, action, empty } = props;
+  const [width, setWidth] = useState(0);
+  const narrow = width > 0 && width < FORK_AT;
+  const onLayout = useCallback((e: LayoutChangeEvent) => setWidth(e.nativeEvent.layout.width), []);
+  const rows = Array.isArray(children) ? children.filter(Boolean) : children;
+  const isEmpty = Array.isArray(rows) ? rows.length === 0 : !rows;
+
+  return (
+    <ChargeLinesContext.Provider value={{ narrow, formatMoney }}>
+      <View onLayout={onLayout} style={styles.band}>
+        {isEmpty ? (
+          <View style={styles.empty}>{empty}</View>
+        ) : (
+          rows
+        )}
+        {/* The closing row mirrors a LINE's trailing geometry exactly — amount
+            slot, then the same verb gutter — or the total misses the column it
+            is closing: without the gutter it sits a verb's width too far right,
+            and with the commit beside it the button shoves it left. Neither is
+            a nudge to tune; the row has to be built from the line's parts. */}
+        <View style={styles.total}>
+          <Text size="sm" weight="medium" style={styles.grow}>
+            {totalLabel}
+          </Text>
+          <View style={styles.maths}>
+            <View style={styles.amountSlot}>
+              <Text size="sm" weight="semibold" tabular style={[styles.right, styles.inset]}>
+                {formatMoney(total)}
+              </Text>
+            </View>
+            <View style={styles.actionSlot} />
+          </View>
+        </View>
+        {/* The commit takes its OWN row at the band's end and sits on the left,
+            because a right-floated act aligns to nothing — and here it would be
+            aligning to the one column that must stay the reader's. */}
+        {action ? <View style={styles.commit}>{action}</View> : null}
+      </View>
+    </ChargeLinesContext.Provider>
+  );
+}
+
+export function ChargeLine(props: ChargeLineProps) {
+  const {
+    label, meta, quantity, unitPrice, onQuantityChange, onUnitPriceChange,
+    unitPriceActions, amountActions, action, locked,
+  } = props;
+  const band = useChargeLines();
+  const words = useLoticsLocale().chargeLines;
+  const money = props.formatMoney ?? band.formatMoney;
+  const priced = quantity !== undefined || unitPrice !== undefined;
+  const amount = priced ? (quantity ?? 0) * (unitPrice ?? 0) : (props.amount ?? 0);
+  /** The row's money verb — the unit price's on a priced line, the amount's on a
+   *  flat one. A locked band has nothing to act on, so it draws none. */
+  const warning = props.warning ? (
+    <Text size="xs" color="warning" style={styles.warn}>
+      {props.warning}
+    </Text>
+  ) : null;
+
+  const maths = (
+    /* RIGHT-ALIGNED, always. Wide, the row's growing label already pushes this
+       block to the band's edge; narrow it is a block in a COLUMN, so it stretches
+       and would lay its slots out from the LEFT — landing the amounts wherever
+       the fixed widths happen to end, which coincides with the closing row's
+       amount column only when the container is exactly as wide as this row. It
+       was 50px adrift in a 448 container and 33px in a 360 one. Justifying to the
+       end makes the amount slot the band's own trailing geometry, which is what
+       the total is built from. */
+    <View style={[styles.maths, band.narrow ? styles.mathsNarrow : null]}>
+      {!priced ? null : (
+      <View style={{ width: band.narrow ? QTY_W_NARROW : QTY_W }}>
+        {locked || !onQuantityChange ? (
+          <Text size="sm" tabular style={styles.inset}>
+            {quantity ?? "—"}
+          </Text>
+        ) : (
+          <InlineNumberInput
+            value={quantity ?? null}
+            onSave={onQuantityChange}
+            min={0}
+            placeholder="1"
+            align="right"
+            accessibilityLabel={words.quantity(label)}
+          />
+        )}
+      </View>
+      )}
+      {!priced ? null : (
+      <Text size="sm" color="muted" style={styles.op}>
+        ×
+      </Text>
+      )}
+      {!priced ? null : (
+      <View style={{ width: band.narrow ? PRICE_W_NARROW : PRICE_W }}>
+        {locked || !onUnitPriceChange ? (
+          <Text size="sm" tabular style={[styles.inset, styles.right]}>
+            {unitPrice == null ? "—" : money(unitPrice)}
+          </Text>
+        ) : (
+          <InlineNumberInput
+            value={unitPrice ?? null}
+            onSave={onUnitPriceChange}
+            min={0}
+            format={(v) => (v == null ? "" : money(v))}
+            placeholder="—"
+            align="right"
+            accessibilityLabel={words.unitPrice(label)}
+          />
+        )}
+      </View>
+      )}
+      {/* BESIDE the price field, never inside it: a verb inside eats the field's
+          width, so the figure slides left and a row carrying a one-tap rate stops
+          sharing this column with a row that has none. Width is the verb's own —
+          the contract is that a caller passes it on every row and DISABLES it
+          where it has nothing to do, which is what keeps the rows equal. */}
+      {!priced ? null : unitPriceActions}
+      {/* The amount ENDS the expression it derives from. Put it on a second
+          line and the reader parses left to right, then jumps back to find the
+          answer — and it lands in no column, so the total below closes nothing. */}
+      <View style={styles.amountSlot}>
+        {priced || locked || !props.onAmountChange ? (
+          <Text size="sm" tabular style={[styles.right, styles.inset]}>
+            {money(amount)}
+          </Text>
+        ) : (
+          <InlineNumberInput
+            value={props.amount ?? null}
+            onSave={props.onAmountChange}
+            min={0}
+            format={(v) => (v == null ? "" : money(v))}
+            placeholder="—"
+            align="right"
+            accessibilityLabel={words.amount(label)}
+          />
+        )}
+      </View>
+      {/* The flat line's twin of `unitPriceActions`, on the figure a flat line
+          actually edits — its amount. Same contract: pass it on every row and
+          disable it where it has nothing to do. */}
+      {priced ? null : amountActions}
+      {/* Held open whether or not this row has a verb, so the money column does
+          not shift between a row that can be removed and one that cannot. */}
+      <View style={styles.actionSlot}>{locked ? null : action}</View>
+    </View>
+  );
+
+  if (band.narrow) {
+    return (
+      <View style={styles.rowNarrow}>
+        {/* The NAME line carries the row's verb here, because the room it needs
+            is spare on this line and scarce on the next one. The arithmetic row
+            below then holds the same slots on every line whether or not a rate
+            is one tap away, which is the property the reserved slot bought in
+            the wide row — bought here without spending width the fork does not
+            have. */}
+        <View style={styles.narrowHead}>
+          <View style={styles.grow}>
+            <Text size="sm">{label}</Text>
+            {props.extra ? <View style={styles.extra}>{props.extra}</View> : null}
+            {meta ? (
+              <Text size="xs" color="muted">
+                {meta}
+              </Text>
+            ) : null}
+          </View>
+        </View>
+        {maths}
+        {/* The problem follows the row through the fork. It was rendered only in
+            the wide branch, so a line's warning vanished at exactly the width
+            where the reader has least room to work out what is wrong. */}
+        {warning}
+      </View>
+    );
+  }
+
+  return (
+    <View>
+    <View style={styles.row}>
+      <View style={styles.grow}>
+        <Text size="sm" numberOfLines={1}>
+          {label}
+        </Text>
+        {props.extra ? <View style={styles.extra}>{props.extra}</View> : null}
+        {meta ? (
+          <Text size="xs" color="muted" numberOfLines={1}>
+            {meta}
+          </Text>
+        ) : null}
+      </View>
+      {maths}
+    </View>
+    {warning}
+    </View>
+  );
+}
+
+const ChargeLinesContext = createContext<{ narrow: boolean; formatMoney: (n: number) => string }>({
+  narrow: false,
+  formatMoney: (n) => String(n),
+});
+
+function useChargeLines() {
+  return useContext(ChargeLinesContext);
+}
+
+const styles = StyleSheet.create({
+  band: { gap: SPACE.sm },
+  row: { flexDirection: "row", alignItems: "center", gap: SPACE.md },
+  rowNarrow: { gap: SPACE.xs },
+  grow: { flex: 1, minWidth: 0 },
+  maths: { flexDirection: "row", alignItems: "center", gap: SPACE.xs },
+  mathsNarrow: { justifyContent: "flex-end" },
+  narrowHead: { flexDirection: "row", alignItems: "flex-start", gap: SPACE.sm },
+  op: { width: OP_W, textAlign: "center" },
+  amountSlot: { width: AMOUNT_W },
+
+  extra: { maxWidth: 200, paddingTop: 4 },
+  actionSlot: { width: ACTION_W, alignItems: "flex-end" },
+  commit: { alignSelf: "flex-start", paddingTop: SPACE.xs },
+  right: { textAlign: "right" },
+  warn: { paddingTop: 2 },
+  /** A value standing where an editor stands lines up with it, rather than
+   *  sitting where the editor's frame would have been. */
+  inset: { paddingHorizontal: CONTROL_TEXT_INSET },
+  total: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: SPACE.md,
+    paddingTop: SPACE.sm,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: colors.zinc[200],
+  },
+  empty: { paddingVertical: SPACE.sm },
+});

package/src/chip_group.tsx

@@ -1,4 +1,7 @@
 import { StyleSheet, View, type ViewStyle } from "react-native";
+import { colors } from "./colors";
+import { Icon, type IconName } from "./icon";
+import { solid, type ColorName } from "./colors";
 import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { chipSurfaceStyle } from "./control_surface";
@@ -22,6 +25,41 @@ import { chipSurfaceStyle } from "./control_surface";
 export interface ChipOption<T extends string = string> {
   label: string;
   value: T;
+  /**
+   * A mark BEFORE the label, for a set whose members differ in KIND rather than
+   * in degree — payment methods, channels, document types.
+   *
+   * It earns its place when the distinction it draws is one the reader acts on
+   * faster than they read: a glyph plus `iconColor` separates "the money is
+   * here" from "it is not" before the words are parsed. It is decoration on a
+   * set whose labels already differ plainly (Low / Medium / High), and there it
+   * costs width every chip pays for nothing.
+   *
+   * Never icon-ONLY: the label stays, because a chip that is a bare glyph is a
+   * control whose value cannot be read aloud or guessed.
+   */
+  icon?: IconName;
+  /** Ink for `icon`. Defaults to the label's own colour, which is what a mark
+   *  that only says "which one" should take; give it a colour when the icon
+   *  carries a MEANING the label does not (settled vs pending, ok vs blocked). */
+  iconColor?: string;
+  /**
+   * How many rows this chip leads to, as a PROP — never formatted into `label`.
+   * A number inside the label is a second copy that goes stale the moment the
+   * set behind it changes, and it cannot be styled apart from the word it
+   * follows. A count is also a reason to PRESS: a chip that states how many
+   * rows sit behind it and does not filter to them states a fact it refuses to
+   * act on.
+   */
+  count?: number;
+  /**
+   * A status dot BEFORE the label, in the same vocabulary as `Badge
+   * variant="dot"` — so a chip and the rows it filters to cannot disagree about
+   * what colour a state is. STATUS only: a category, a type or a place is not a
+   * status and takes no dot. Mutually exclusive with `icon`, which marks a
+   * difference in KIND rather than in state.
+   */
+  status?: ColorName;
   testID?: string;
 }
 
@@ -77,6 +115,15 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
                 filter row selects the chip text instead of reading as a control —
                 `SegmentedControl` and `Button` already suppress it, and the chips
                 were the gap. */}
+            {option.status ? (
+              <View style={[styles.dot, { backgroundColor: solid(option.status) }]} />
+            ) : option.icon ? (
+              <Icon
+                name={option.icon}
+                size={14}
+                color={option.iconColor ?? (active ? colors.zinc[900] : colors.zinc[500])}
+              />
+            ) : null}
             <Text
               userSelect="none"
               size="sm"
@@ -85,6 +132,11 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
             >
               {option.label}
             </Text>
+            {option.count != null ? (
+              <Text userSelect="none" size="sm" color="muted" tabular>
+                {option.count}
+              </Text>
+            ) : null}
           </PressableHighlight>
         );
       })}
@@ -93,5 +145,9 @@ export function ChipGroup<T extends string = string>(props: ChipGroupProps<T>) {
 }
 
 const styles = StyleSheet.create({
-  chip: { paddingHorizontal: 14, ...({ cursor: "auto" } as ViewStyle) },
+  dot: { width: 6, height: 6, borderRadius: 3 },
+  chip: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6, paddingHorizontal: 14, ...({ cursor: "auto" } as ViewStyle) },
 });

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 —