@lotics/ui 32.0.0 → 34.0.0

package/MIGRATION.md

@@ -4,6 +4,91 @@ 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.
 
+## 34.0.0 — one avatar rung fits a control band
+
+**`AVATAR_PX.md` is 28, not 36.** Nothing to change at a call site — `md` is still
+the default and still shows two initials — but every `Avatar`, `MemberChip` and
+`GroupAvatar` on that rung renders 8px smaller (its initials drop a type rung with
+it, to hold the same share of the circle), and the controls holding them get
+SHORTER, which is the point.
+
+`CONTROL_HEIGHT` is a promise: a toolbar row, a record's value column and a
+picker's option list read as one band because every control on them is 40. TEXT
+keeps that promise for free — a line is ~20, so `minHeight` governs and a
+surface's vertical padding never binds. That is exactly why each 40px surface had
+quietly picked its own inset (`Select`'s trigger 4, the inline editor 6,
+`InlineSlot` 8) with no number to pick it from, and nothing on a resting screen
+ever showed the disagreement.
+
+Putting a 36px avatar in one broke all three at once. The same member chip
+measured **46** in a `Select` trigger, **50** in an inline editor and **54** in an
+`InlineSlot` — a record whose value column is the only thing telling a reader
+these fields belong to one record, with the member row 10px off every other row
+in it.
+
+So the budget is stated once and the surfaces derive from it:
+
+- **`CONTROL_CONTENT_HEIGHT`** (28) — the tallest fixed-height node a 40px band
+  seats, 6 per side of air. Not a fresh number: it is what `InlineButton` and a
+  `md` `IconButton` had already settled on for sitting inside a field. An avatar
+  is not a special kind of child, so it gets the same height they do.
+- **`CONTROL_PADDING_V`** (5) — derived, and the 1px border counts inside the 6
+  per side. Reading the padding and forgetting the border is how the drift
+  started.
+
+Both from `@lotics/ui/control_surface`. **If you build your own 40px control, pad
+by `CONTROL_PADDING_V` and keep fixed-height children at or under
+`CONTROL_CONTENT_HEIGHT`** — anything taller belongs in a row that sets its own
+height, not in a control.
+
+Two knock-on effects worth looking at once:
+
+- A **multi-line control at rest** (a rich select showing title + description) is
+  ~2px shorter, since its padding came off the same constant.
+- An `InlineSlot`/`InlineStatic` value now actually matches the editor beside it.
+  It always claimed to; it was 2px more padded, invisible at one line.
+
+## 33.0.0 — `DrawerScrollArea`
+
+A `Drawer` gets the content primitive its siblings already had, named to match
+`DialogScrollArea`. **Wrap your drawer body in it and delete the padding you were
+applying:**
+
+```diff
+  <Drawer open onOpenChange={setOpen} title={name}>
+-   <View style={{ flex: 1, padding: 24, gap: 12 }}>
++   <DrawerScrollArea>
++     <View style={{ gap: 12 }}>
+      …
+    </View>
+  </Drawer>
+```
+
+**Why a component and not a default.** The gutter is a contract: content has to
+land on the same left edge as the header's title and the footer's actions, and
+only the panel knows that number. Left to callers it was answered three ways
+across the templates and the live apps — `24` six times (4px past the drawer's own
+title), `20` three times, and in one shipped app not at all, which put a comment
+thread flush against the panel edge while its title was inset 20.
+
+The `Drawer`'s own slot stays BARE, which is how `Modal` and `Dialog` already
+work. A drawer that padded its slot would be the one overlay of the three that
+does, and would force every full-bleed child to cancel it with a negative margin.
+
+**Two bodies do NOT wrap in it**, and both take the bare slot instead:
+
+- **Full-bleed** — a band spanning the panel, a record screen carrying its own
+  gutters. Nothing to do; the slot already reaches the edge.
+- **Pinned + scrolling** — a heading, count or summary held above a list that
+  scrolls under it. Put `DRAWER_GUTTER` on the pinned part and on the scroller's
+  `contentContainerStyle`. **Do not** wrap the pair in a padded box: a box with
+  padding insets the scroller's VIEWPORT, so the list ends short of the panel with
+  dead space beneath it and the last row clipped. Measured: a 400px panel ends its
+  scroll at 380.
+
+Import `DRAWER_GUTTER` in both cases; a hardcoded `20` stops matching the day it
+moves.
+
 ## 32.0.0 — `Table`'s `align` prop is gone; rows are centred
 
 `align?: "center" | "top"` and the `TableAlign` type are removed. `center` was the

package/docs/catalog.md

@@ -76,12 +76,20 @@ inline: a picker option, an assignee, a `select_member` value. Pure: resolve the
 your directory and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`MemberSelect`
 renders these per option.)
 
-**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 36 / 48 / 72
+**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 48 / 72
 (`@lotics/ui/avatar_size`, shared by `Avatar`, `MemberChip` and `GroupAvatar`). Default `md`.
 The number was removed because the same concept had drifted to eleven different values across
 the product and its apps, so one person looked different on every screen. Pick by density:
-`sm` for a dense row or inline cell, `md` for a register or list (the default), `lg` for a
-prominent row or the account menu, `xl` for a profile's own header.
+`sm` for a dense row or inline cell, `md` for a control band, register or list (the default),
+`lg` for a prominent row or the account menu, `xl` for a profile's own header.
+
+**`md` is `CONTROL_CONTENT_HEIGHT`** (28) — the largest rung a 40px control band seats without
+growing, and the height `InlineButton` and a `md` `IconButton` already used to sit inside a
+field. An avatar is the tallest thing in whatever row holds it, so a rung that overshoots
+doesn't look slightly big, it RESIZES the control: at the old 36 the same member chip measured
+46 in a `Select` trigger, 50 in an inline editor and 54 in an `InlineSlot`, because each
+surface had picked its own inset with no number to pick it from. Put nothing taller than `md`
+in a control — a bigger avatar belongs in a row that sets its own height.
 
 **`sm` shows ONE initial; every larger rung shows two** — two letters are not legible at 24px.
 That is the practical reason not to reach for `sm` by reflex: on a real roster a single letter
@@ -411,7 +419,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
 - **`spacing`** — the `SPACE` scale + `SpaceToken`.
-- **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
+- **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
+  FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
+  `IconButton` already used, now named so an avatar or any other child lands on it too. Text
+  never needs it because `minHeight` governs a single line, which is exactly why three surfaces
+  could each pick a different inset and only disagree once an avatar went in),
+  `CONTROL_PADDING_V` (5 — derived from the pair, BORDER INCLUDED in the 6 per side; every 40px
+  surface pads by it instead of a number of its own), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
   up with a control's WORDS rather than its box carries it — a caption under an inline editor,
   a note under a figure — rather than a hand-measured 8),
@@ -1157,9 +1171,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`dialog`** — `Dialog` (+ `DialogHeader`/`DialogHeaderTitle`/`DialogFooter`, `useDialog`,
   `useDialogNavigation`): the centered card over a scrim; BAKES a screen router in
   (`<Dialog><Screen route="">…` — see `screen_router`).
-- **`drawer`** — `Drawer` + `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.
+- **`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
+  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),
+  and a PINNED one (a heading or summary above a scrolling list), which puts the exported
+  `DRAWER_GUTTER` on the pinned part and on the scroller's `contentContainerStyle` rather than
+  copying `20`.
 - **`modal`** — `Modal` + `ModalHeader` + `ModalBody` + `ModalFooter` — the full-bleed,
   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

package/docs/composition.md

@@ -10,9 +10,18 @@ them produces off-system UI.
 
 ## Canvas & content column
 
-- **Canvas**: a full-bleed `colors.white` ScrollView with `padding: 28` (a `Drawer`'s scroll body
-  uses 24). Cards separate from the canvas by their own border + shadow, not by a tinted
-  background.
+- **Canvas**: a full-bleed `colors.white` ScrollView with `padding: 28`. Cards separate from the
+  canvas by their own border + shadow, not by a tinted background.
+- **An overlay's gutter belongs to a CONTENT primitive, never to the caller.** `ModalBody`,
+  `DialogScrollArea` and `DrawerScrollArea` each carry their surface's inset, so content lands on
+  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.
+- **Never wrap a scroller in a padded box.** The box insets the scroller's VIEWPORT, so the list
+  ends short of the surface with dead space beneath it and its last row clipped — measured, a
+  400px panel ends its scroll at 380. A pinned heading above a scrolling list therefore takes the
+  overlay's BARE slot and puts the gutter on the pinned part and on the scroller's
+  `contentContainerStyle`. Same for a full-bleed band, which wants no gutter at all.
 - **Content column**: one centered column — `{ width: "100%", maxWidth, alignSelf: "center" }` —
   sized to the job, with `gap: 16` between top-level bands/cards:
 
@@ -508,7 +517,19 @@ shape.
 
 ## One view-control vocabulary
 
-All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping band:
+All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping band.
+
+**A 40px band affords 28 (`CONTROL_CONTENT_HEIGHT`), and a surface pads by
+`CONTROL_PADDING_V` rather than a number of its own.** The height only holds for free when the
+content is TEXT: a line is ~20, so `minHeight` governs and the padding never binds — which is
+why a surface can pick any inset it likes and nothing on a resting screen ever contradicts it.
+The moment something with a FIXED height goes in — an avatar, a swatch, a thumbnail — that
+inset decides the control's whole height, and three surfaces that had each chosen their own
+(4, 6, 8) rendered one member chip at 46, 50 and 54. So: a fixed-height child is sized against
+the band's budget, never against how it looks alone, and a surface that needs more room than
+the budget is not a control. The budget is 28 because that is what `InlineButton` and a `md`
+`IconButton` were already using inside a field — a control's children must not differ in height
+by what KIND of thing they are, so an avatar takes the same number rather than a fourth one.
 
 - **`SearchInput`** is THE search box — a white `TextInputField` preset (the shared
   `CONTROL_RADIUS` like every other input, a thin border, the leading search glyph + a clear ✕).

package/examples/tpl_attendance.tsx

@@ -9,7 +9,7 @@ import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
 import { Card } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
@@ -205,38 +205,40 @@ function NhanVienWorkspace({ nv }: { nv: NhanVien }) {
   const tt = TRANG_THAI[nv.trangThai];
   return (
     <>
-      <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 24, gap: 20 }}>
-        <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-          <Avatar name={nv.ten} size="lg" />
-          <View style={{ flex: 1, gap: 2 }}>
-            <Text size="sm" color="muted">{nv.chucVu}</Text>
-          </View>
-          <Badge label={badgeLabel(nv)} color={tt.color} />
-        </View>
-        <View style={{ gap: 6 }}>
-          <KVRow label="Clock-in" value={nv.vao ?? "Not clocked"} />
-          <KVRow label="Clock-out" value={nv.ra ?? "Not clocked"} />
-          <KVRow label="Hours today" value={nv.tongGio ?? "—"} />
-        </View>
-        <Divider />
-        <View style={{ gap: 10 }}>
-          <View style={{ flexDirection: "row", alignItems: "center" }}>
-            <View style={{ flex: 1 }}>
-              <Text size="xs" color="muted" weight="medium">This week</Text>
+      <DrawerScrollArea>
+        <View style={{ gap: 20 }}>
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+            <Avatar name={nv.ten} size="lg" />
+            <View style={{ flex: 1, gap: 2 }}>
+              <Text size="sm" color="muted">{nv.chucVu}</Text>
             </View>
-            <Text size="sm" weight="medium" tabular>{nv.tongTuan}</Text>
+            <Badge label={badgeLabel(nv)} color={tt.color} />
           </View>
           <View style={{ gap: 6 }}>
-            {nv.tuan.map((ngay, i) => (
-              <View key={NGAY_TUAN[i]} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 24 }}>
-                <Text size="xs" color="muted" tabular style={{ width: 24 }}>{NGAY_TUAN[i]}</Text>
-                <DayCell ngay={ngay} />
-                <Text size="sm">{NGAY_CONG[ngay].label}</Text>
+            <KVRow label="Clock-in" value={nv.vao ?? "Not clocked"} />
+            <KVRow label="Clock-out" value={nv.ra ?? "Not clocked"} />
+            <KVRow label="Hours today" value={nv.tongGio ?? "—"} />
+          </View>
+          <Divider />
+          <View style={{ gap: 10 }}>
+            <View style={{ flexDirection: "row", alignItems: "center" }}>
+              <View style={{ flex: 1 }}>
+                <Text size="xs" color="muted" weight="medium">This week</Text>
               </View>
-            ))}
+              <Text size="sm" weight="medium" tabular>{nv.tongTuan}</Text>
+            </View>
+            <View style={{ gap: 6 }}>
+              {nv.tuan.map((ngay, i) => (
+                <View key={NGAY_TUAN[i]} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 24 }}>
+                  <Text size="xs" color="muted" tabular style={{ width: 24 }}>{NGAY_TUAN[i]}</Text>
+                  <DayCell ngay={ngay} />
+                  <Text size="sm">{NGAY_CONG[ngay].label}</Text>
+                </View>
+              ))}
+            </View>
           </View>
         </View>
-      </ScrollView>
+      </DrawerScrollArea>
       {/* pinned footer — the workspace's one primary fix action */}
       <View style={{ borderTopWidth: 1, borderTopColor: colors.border, paddingHorizontal: 20, paddingVertical: 14, flexDirection: "row", alignItems: "center", gap: 12 }}>
         <Text size="xs" color="muted" style={{ flex: 1 }}>Missed punches get fixed here — every change is audited.</Text>

package/examples/tpl_calendar.tsx

@@ -7,7 +7,7 @@ import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
 import { Card, CardHeader, CardHeaderTitle, CardHeaderMeta } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { ListItem } from "@lotics/ui/list_item";
 import {
   CalendarView,
@@ -154,17 +154,19 @@ function SlotWorkspace({ e }: { e: CalendarEvent<AgendaMeta> }) {
   ];
   return (
     <>
-      <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 24, gap: 10 }}>
-        {rows.map(([label, value], i) => (
-          <View key={label} style={{ gap: 10 }}>
-            {i > 0 ? <Divider /> : null}
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 24 }}>
-              <Text size="sm" color="muted" style={{ width: 104 }}>{label}</Text>
-              {value}
+      <DrawerScrollArea>
+        <View style={{ gap: 10 }}>
+          {rows.map(([label, value], i) => (
+            <View key={label} style={{ gap: 10 }}>
+              {i > 0 ? <Divider /> : null}
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: 24 }}>
+                <Text size="sm" color="muted" style={{ width: 104 }}>{label}</Text>
+                {value}
+              </View>
             </View>
-          </View>
-        ))}
-      </ScrollView>
+          ))}
+        </View>
+      </DrawerScrollArea>
       <View
         style={{
           borderTopWidth: 1,

package/examples/tpl_dashboard.tsx

@@ -26,7 +26,7 @@ import {
 } from "@lotics/ui/date_range_filter_field";
 import { type DateFilterValue } from "@lotics/ui/date_filter";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { PressableRow } from "@lotics/ui/pressable_row";
 import { type IconName } from "@lotics/ui/icon";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
@@ -530,25 +530,27 @@ export function TplDashboard() {
           onNext={openRec.idx < recAlert.records.length - 1 ? () => setOpenRec({ alertKey: openRec.alertKey, idx: openRec.idx + 1 }) : undefined}
           position={`${openRec.idx + 1}/${recAlert.records.length}`}
         >
-          <View key={rec.id} style={{ flex: 1, padding: 24, gap: 12 }}>
-            <Badge label={recAlert.label} color={recAlert.tone === "warning" ? "amber" : "red"} />
-            <View style={{ gap: 10, paddingTop: 4 }}>
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Text size="sm" color="muted" style={{ flex: 1 }}>Customer</Text>
-                <Text size="sm" weight="medium">{rec.name}</Text>
-              </View>
-              <Divider />
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Text size="sm" color="muted" style={{ flex: 1 }}>Amount / due</Text>
-                <Text size="sm" tabular>{rec.value}</Text>
-              </View>
-              <Divider />
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Text size="sm" color="muted" style={{ flex: 1 }}>Status</Text>
-                <Text size="sm" color={rec.noteTone} tabular>{rec.note}</Text>
+          <DrawerScrollArea key={rec.id}>
+            <View style={{ gap: 12 }}>
+              <Badge label={recAlert.label} color={recAlert.tone === "warning" ? "amber" : "red"} />
+              <View style={{ gap: 10, paddingTop: 4 }}>
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                  <Text size="sm" color="muted" style={{ flex: 1 }}>Customer</Text>
+                  <Text size="sm" weight="medium">{rec.name}</Text>
+                </View>
+                <Divider />
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                  <Text size="sm" color="muted" style={{ flex: 1 }}>Amount / due</Text>
+                  <Text size="sm" tabular>{rec.value}</Text>
+                </View>
+                <Divider />
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                  <Text size="sm" color="muted" style={{ flex: 1 }}>Status</Text>
+                  <Text size="sm" color={rec.noteTone} tabular>{rec.note}</Text>
+                </View>
               </View>
             </View>
-          </View>
+          </DrawerScrollArea>
           <View
             style={{
               borderTopWidth: 1,

package/examples/tpl_item_list.tsx

@@ -10,7 +10,7 @@ import { Button } from "@lotics/ui/button";
 import { CheckboxInput } from "@lotics/ui/checkbox_input";
 import { DetailRow, DetailTable } from "@lotics/ui/detail_row";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer, DrawerFooter } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea, DrawerFooter } from "@lotics/ui/drawer";
 import { EmptyState } from "@lotics/ui/empty_state";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { FormField } from "@lotics/ui/form_field";
@@ -350,37 +350,39 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
   if (!r) return null;
   return (
     <>
-      <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 24, gap: 16 }}>
-        <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
-          <Badge label={TRANG_THAI[r.trangThai].label} color={TRANG_THAI[r.trangThai].color} />
-          <Text size="sm" color="muted">{`Linked record: ${r.khach}`}</Text>
+      <DrawerScrollArea>
+        <View style={{ gap: 16 }}>
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+            <Badge label={TRANG_THAI[r.trangThai].label} color={TRANG_THAI[r.trangThai].color} />
+            <Text size="sm" color="muted">{`Linked record: ${r.khach}`}</Text>
+          </View>
+          <DetailTable labelWidth={120}>
+            <DetailRow label="Customer"><InlineTextInput value={khach} onSave={persist(setKhach)} accessibilityLabel="Customer" /></DetailRow>
+            <DetailRow label="Phone"><InlineTextInput value={dienThoai} onSave={persist(setDienThoai)} accessibilityLabel="Phone" /></DetailRow>
+            <DetailRow label="Assignee">
+              <InlineMemberSelect members={MEMBERS} value={assignee} onSave={persist(setAssignee)} placeholder="Assign…" accessibilityLabel="Assignee" />
+            </DetailRow>
+            <DetailRow label="Received"><InlineDatePicker value={ngayNhan} onSave={persist(setNgayNhan)} accessibilityLabel="Received date" /></DetailRow>
+            <DetailRow label="Fee">
+              <InlineNumberInput value={fee} onSave={persist(setFee)} min={0} format={(v) => (v == null ? "" : formatMoney(v))} accessibilityLabel="Fee" />
+            </DetailRow>
+            <DetailRow label="Collected">
+              <InlineSelect
+                value={collected}
+                onSave={persist(setCollected)}
+                options={[{ value: "yes", label: "Collected" }, { value: "no", label: "Outstanding" }]}
+                accessibilityLabel="Collected"
+                renderOptionContent={(o) => (
+                  <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                    <View style={{ width: 8, height: 8, borderRadius: 4, backgroundColor: o.value === "yes" ? colors.emerald[500] : colors.amber[500] }} />
+                    <Text size="sm">{o.label}</Text>
+                  </View>
+                )}
+              />
+            </DetailRow>
+          </DetailTable>
         </View>
-        <DetailTable labelWidth={120}>
-          <DetailRow label="Customer"><InlineTextInput value={khach} onSave={persist(setKhach)} accessibilityLabel="Customer" /></DetailRow>
-          <DetailRow label="Phone"><InlineTextInput value={dienThoai} onSave={persist(setDienThoai)} accessibilityLabel="Phone" /></DetailRow>
-          <DetailRow label="Assignee">
-            <InlineMemberSelect members={MEMBERS} value={assignee} onSave={persist(setAssignee)} placeholder="Assign…" accessibilityLabel="Assignee" />
-          </DetailRow>
-          <DetailRow label="Received"><InlineDatePicker value={ngayNhan} onSave={persist(setNgayNhan)} accessibilityLabel="Received date" /></DetailRow>
-          <DetailRow label="Fee">
-            <InlineNumberInput value={fee} onSave={persist(setFee)} min={0} format={(v) => (v == null ? "" : formatMoney(v))} accessibilityLabel="Fee" />
-          </DetailRow>
-          <DetailRow label="Collected">
-            <InlineSelect
-              value={collected}
-              onSave={persist(setCollected)}
-              options={[{ value: "yes", label: "Collected" }, { value: "no", label: "Outstanding" }]}
-              accessibilityLabel="Collected"
-              renderOptionContent={(o) => (
-                <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-                  <View style={{ width: 8, height: 8, borderRadius: 4, backgroundColor: o.value === "yes" ? colors.emerald[500] : colors.amber[500] }} />
-                  <Text size="sm">{o.label}</Text>
-                </View>
-              )}
-            />
-          </DetailRow>
-        </DetailTable>
-      </ScrollView>
+      </DrawerScrollArea>
       {/* the pushed record's OWN footer — different CTAs from the root case */}
       <DrawerFooter>
         <Text size="xs" color="muted" style={{ flex: 1 }}>Changes save in place on this linked record.</Text>

package/examples/tpl_pivot.tsx

@@ -5,7 +5,7 @@ import { colors } from "@lotics/ui/colors";
 import { Badge } from "@lotics/ui/badge";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { EmptyState } from "@lotics/ui/empty_state";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { Chip } from "@lotics/ui/chip";
@@ -230,18 +230,20 @@ export function TplPivot() {
           onNext={openIdx < Math.min(items.length, 10) - 1 ? () => setOpenIdx(openIdx + 1) : undefined}
           position={`${openIdx + 1}/${Math.min(items.length, 10)}`}
         >
-          <View key={open.code} style={{ flex: 1, padding: 24, gap: 12 }}>
-            <Badge variant="dot" label={STATUS[open.status].label} color={STATUS[open.status].color} />
-            <View style={{ gap: 6, paddingTop: 4 }}>
-              <KVRow label="Item"><Text size="sm">{open.name}</Text></KVRow>
-              <Divider />
-              <KVRow label="Warehouse"><Text size="sm">{whOf(open.warehouse).label}</Text></KVRow>
-              <Divider />
-              <KVRow label="Category"><Text size="sm">{catOf(open.category).label}</Text></KVRow>
-              <Divider />
-              <KVRow label="Units on hand"><Text size="sm" tabular>{count(open.units)}</Text></KVRow>
+          <DrawerScrollArea key={open.code}>
+            <View style={{ gap: 12 }}>
+              <Badge variant="dot" label={STATUS[open.status].label} color={STATUS[open.status].color} />
+              <View style={{ gap: 6, paddingTop: 4 }}>
+                <KVRow label="Item"><Text size="sm">{open.name}</Text></KVRow>
+                <Divider />
+                <KVRow label="Warehouse"><Text size="sm">{whOf(open.warehouse).label}</Text></KVRow>
+                <Divider />
+                <KVRow label="Category"><Text size="sm">{catOf(open.category).label}</Text></KVRow>
+                <Divider />
+                <KVRow label="Units on hand"><Text size="sm" tabular>{count(open.units)}</Text></KVRow>
+              </View>
             </View>
-          </View>
+          </DrawerScrollArea>
         </Drawer>
       ) : null}
     </ScrollView>

package/examples/tpl_record.tsx

@@ -2,6 +2,7 @@ import { Fragment, useEffect, useRef, useState, type ReactNode, useMemo } from "
 import { ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
+import { DRAWER_GUTTER } from "@lotics/ui/drawer";
 import { Button } from "@lotics/ui/button";
 import { BackButton } from "@lotics/ui/back_button";
 import { Divider } from "@lotics/ui/divider";
@@ -2011,7 +2012,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         // no box, so its ink is what the eye lines up — 18 + 10 = 28. Set the bar,
         // not a negative margin on the button: the gutter belongs to the bar, and
         // one number here cannot drift out of step with itself.
-        <View style={{ borderBottomWidth: 1, borderBottomColor: colors.zinc[200], paddingHorizontal: (isDrawer ? 20 : 28) - 10, paddingVertical: 6, flexDirection: "row", alignItems: "center", gap: 8 }}>
+        <View style={{ borderBottomWidth: 1, borderBottomColor: colors.zinc[200], paddingHorizontal: (isDrawer ? DRAWER_GUTTER : 28) - 10, paddingVertical: 6, flexDirection: "row", alignItems: "center", gap: 8 }}>
           {/* narrow keeps the standard too — the bare back glyph beside the
               section bar (the rail that would carry it is collapsed). A DRAWER
               already has one in its own header; two would be two exits. */}
@@ -2066,7 +2067,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
     {/* The gutter is CHROME's, not the record's: 28 is the page canvas, 20 is what
         a `Drawer` pads its header with — so in a drawer the content lines up with
         the record NAME in the header above it instead of sitting 8px inside it. */}
-    <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16} style={{ flex: 1 }} contentContainerStyle={{ padding: isDrawer ? 20 : 28, paddingBottom: 96 }}>
+    <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16} style={{ flex: 1 }} contentContainerStyle={{ padding: isDrawer ? DRAWER_GUTTER : 28, paddingBottom: 96 }}>
       {/* The centred group: a gutter RESERVED for the rail, the reading column,
           and an equal empty gutter that balances it — so the column's centre is
           the window's centre. Both gutters live INSIDE the scroller, so they

package/examples/tpl_rollup.tsx

@@ -6,7 +6,7 @@ import { Accordion, AccordionContent, AccordionHeader, AccordionTitle } from "@l
 import { Button } from "@lotics/ui/button";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { PressableHighlight } from "@lotics/ui/pressable_highlight";
 import { Sparkline } from "@lotics/ui/sparkline";
@@ -255,30 +255,32 @@ export function TplRollup() {
           onNext={open.idx < open.site.lanes.length - 1 ? () => setOpen({ site: open.site, idx: open.idx + 1 }) : undefined}
           position={`${open.idx + 1}/${open.site.lanes.length}`}
         >
-          <View key={openLane.id} style={{ flex: 1, padding: 24, gap: 16 }}>
-            <View style={{ gap: 6 }}>
-              <KVRow label="Route"><Text size="sm">{`${open.site.label} → ${openLane.dest}`}</Text></KVRow>
-              <Divider />
-              <KVRow label="Volume this month"><Text size="sm" tabular>{openLane.volume.toLocaleString("en-US")}</Text></KVRow>
-              <Divider />
-              <KVRow label="On-time">
-                <Text size="sm" tabular color={openLane.ontime < ONTIME_TARGET ? "danger" : "default"}>
-                  {`${openLane.ontime}% (target ${ONTIME_TARGET}%)`}
-                </Text>
-              </KVRow>
-              <Divider />
-              <KVRow label="Margin"><Text size="sm" tabular>{`${openLane.margin}%`}</Text></KVRow>
+          <DrawerScrollArea key={openLane.id}>
+            <View style={{ gap: 16 }}>
+              <View style={{ gap: 6 }}>
+                <KVRow label="Route"><Text size="sm">{`${open.site.label} → ${openLane.dest}`}</Text></KVRow>
+                <Divider />
+                <KVRow label="Volume this month"><Text size="sm" tabular>{openLane.volume.toLocaleString("en-US")}</Text></KVRow>
+                <Divider />
+                <KVRow label="On-time">
+                  <Text size="sm" tabular color={openLane.ontime < ONTIME_TARGET ? "danger" : "default"}>
+                    {`${openLane.ontime}% (target ${ONTIME_TARGET}%)`}
+                  </Text>
+                </KVRow>
+                <Divider />
+                <KVRow label="Margin"><Text size="sm" tabular>{`${openLane.margin}%`}</Text></KVRow>
+              </View>
+              <View style={{ gap: 8 }}>
+                <Text size="xs" color="muted" weight="medium">Volume (last 12 weeks)</Text>
+                <Sparkline
+                  data={Array.from({ length: 12 }, (_, w) => openLane.volume / 4 + (hash(w, openLane.volume) - 500) * (openLane.volume / 12000))}
+                  width={200}
+                  height={36}
+                  color={openLane.ontime < ONTIME_TARGET ? solid("amber") : solid("blue")}
+                />
+              </View>
             </View>
-            <View style={{ gap: 8 }}>
-              <Text size="xs" color="muted" weight="medium">Volume (last 12 weeks)</Text>
-              <Sparkline
-                data={Array.from({ length: 12 }, (_, w) => openLane.volume / 4 + (hash(w, openLane.volume) - 500) * (openLane.volume / 12000))}
-                width={200}
-                height={36}
-                color={openLane.ontime < ONTIME_TARGET ? solid("amber") : solid("blue")}
-              />
-            </View>
-          </View>
+          </DrawerScrollArea>
           <View
             style={{
               borderTopWidth: 1,

package/examples/tpl_shifts.tsx

@@ -9,7 +9,7 @@ import { Button } from "@lotics/ui/button";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle } from "@lotics/ui/dialog";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { EmptyState } from "@lotics/ui/empty_state";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { MenuListItem } from "@lotics/ui/menu_list_item";
@@ -328,58 +328,60 @@ export function TplShifts() {
           onNext={openIdx < allSlots.length - 1 ? () => setOpenSlot(slotId(allSlots[openIdx + 1].day, allSlots[openIdx + 1].shift)) : undefined}
           position={`${openIdx + 1}/${allSlots.length}`}
         >
-          <ScrollView key={openSlot} style={{ flex: 1 }} contentContainerStyle={{ padding: 24, gap: 16 }}>
-            <ProgressBar
-              title="Coverage"
-              value={openAssigned.length}
-              max={openRequired}
-              format="fraction"
-              color={solid("amber")}
-              completeColor={solid("emerald")}
-            />
-            <View style={{ gap: 8 }}>
-              <Text size="sm" weight="semibold">On this shift</Text>
-              {openAssigned.length === 0 ? (
-                <Text size="sm" color="muted">Nobody yet — accept a signup or add a member below.</Text>
-              ) : (
-                openAssigned.map((m) => (
-                  <View key={m} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
-                    <Avatar name={m} size="md" />
-                    <Text size="sm" style={{ flex: 1 }}>{m}</Text>
-                    <Text size="xs" color="muted" tabular>{`${hoursOf(m)}h this week`}</Text>
-                    <ActionMenu
-                      accessibilityLabel={`Actions for ${m}`}
-                      items={[{ key: "remove", label: "Remove from shift", icon: "ban", danger: true, onPress: () => unassign(openSlot, m) }]}
-                    />
-                  </View>
-                ))
-              )}
-            </View>
-            {openSignups.length > 0 ? (
+          <DrawerScrollArea key={openSlot}>
+            <View style={{ gap: 16 }}>
+              <ProgressBar
+                title="Coverage"
+                value={openAssigned.length}
+                max={openRequired}
+                format="fraction"
+                color={solid("amber")}
+                completeColor={solid("emerald")}
+              />
               <View style={{ gap: 8 }}>
-                <Text size="sm" weight="semibold">Asked for this shift</Text>
-                {openSignups.map((su) => {
-                  const hoursAfter = hoursOf(su.member) + SHIFT_HOURS;
-                  return (
-                    <View key={su.id} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
-                      <Avatar name={su.member} size="md" />
-                      <Text size="sm" style={{ flex: 1 }}>{su.member}</Text>
-                      <Text size="xs" color={hoursAfter > WEEK_LIMIT ? "danger" : "muted"} tabular>{`→ ${hoursAfter}h`}</Text>
-                      {hoursAfter > WEEK_LIMIT ? (
-                        <OvertimeGate label={su.member} hoursAfter={hoursAfter} onConfirm={() => accept(su)} />
-                      ) : (
-                        <Button title="Accept" color="secondary" onPress={() => accept(su)} />
-                      )}
+                <Text size="sm" weight="semibold">On this shift</Text>
+                {openAssigned.length === 0 ? (
+                  <Text size="sm" color="muted">Nobody yet — accept a signup or add a member below.</Text>
+                ) : (
+                  openAssigned.map((m) => (
+                    <View key={m} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
+                      <Avatar name={m} size="md" />
+                      <Text size="sm" style={{ flex: 1 }}>{m}</Text>
+                      <Text size="xs" color="muted" tabular>{`${hoursOf(m)}h this week`}</Text>
+                      <ActionMenu
+                        accessibilityLabel={`Actions for ${m}`}
+                        items={[{ key: "remove", label: "Remove from shift", icon: "ban", danger: true, onPress: () => unassign(openSlot, m) }]}
+                      />
                     </View>
-                  );
-                })}
+                  ))
+                )}
               </View>
-            ) : null}
-            <Divider />
-            <KVRow label="Required">
-              <Text size="sm" tabular>{`${openRequired} members`}</Text>
-            </KVRow>
-          </ScrollView>
+              {openSignups.length > 0 ? (
+                <View style={{ gap: 8 }}>
+                  <Text size="sm" weight="semibold">Asked for this shift</Text>
+                  {openSignups.map((su) => {
+                    const hoursAfter = hoursOf(su.member) + SHIFT_HOURS;
+                    return (
+                      <View key={su.id} style={{ flexDirection: "row", alignItems: "center", gap: 10, minHeight: 36 }}>
+                        <Avatar name={su.member} size="md" />
+                        <Text size="sm" style={{ flex: 1 }}>{su.member}</Text>
+                        <Text size="xs" color={hoursAfter > WEEK_LIMIT ? "danger" : "muted"} tabular>{`→ ${hoursAfter}h`}</Text>
+                        {hoursAfter > WEEK_LIMIT ? (
+                          <OvertimeGate label={su.member} hoursAfter={hoursAfter} onConfirm={() => accept(su)} />
+                        ) : (
+                          <Button title="Accept" color="secondary" onPress={() => accept(su)} />
+                        )}
+                      </View>
+                    );
+                  })}
+                </View>
+              ) : null}
+              <Divider />
+              <KVRow label="Required">
+                <Text size="sm" tabular>{`${openRequired} members`}</Text>
+              </KVRow>
+            </View>
+          </DrawerScrollArea>
           <View style={{ borderTopWidth: 1, borderTopColor: colors.border, paddingHorizontal: 20, paddingVertical: 14, flexDirection: "row", alignItems: "center", justifyContent: "flex-end", gap: 12 }}>
             {/* the dispatch fit-gate: every candidate names its week; the
                 slot's own members are excluded, overtime is visible */}

package/examples/tpl_stock.tsx

@@ -8,7 +8,7 @@ import { Breakdown } from "@lotics/ui/breakdown";
 import { Button } from "@lotics/ui/button";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { EmptyState } from "@lotics/ui/empty_state";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { Pagination } from "@lotics/ui/pagination";
@@ -358,21 +358,23 @@ export function TplStock() {
           onNext={openIdx < pageRows.length - 1 ? () => setOpenIdx(openIdx + 1) : undefined}
           position={`${page * PAGE_SIZE + openIdx + 1}/${filtered.length.toLocaleString("en-US")}`}
         >
-          <View key={open.id} style={{ flex: 1, padding: 24, gap: 12 }}>
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-              <Badge label={statusOf(open.status).label} color={statusOf(open.status).color} />
-              <Badge label={typeOf(open.type).label} />
-            </View>
-            <View style={{ gap: 6, paddingTop: 4 }}>
-              <KVRow label="Depot"><Text size="sm">{depotOf(open.depot).label}</Text></KVRow>
-              <Divider />
-              <KVRow label="Last movement"><Text size="sm" tabular>{open.lastMove}</Text></KVRow>
-              <Divider />
-              <KVRow label="Age"><Text size="sm" tabular>{`${open.ageYears} years`}</Text></KVRow>
-              <Divider />
-              <KVRow label="Book value"><Text size="sm" tabular>{formatMoney(open.value)}</Text></KVRow>
+          <DrawerScrollArea key={open.id}>
+            <View style={{ gap: 12 }}>
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                <Badge label={statusOf(open.status).label} color={statusOf(open.status).color} />
+                <Badge label={typeOf(open.type).label} />
+              </View>
+              <View style={{ gap: 6, paddingTop: 4 }}>
+                <KVRow label="Depot"><Text size="sm">{depotOf(open.depot).label}</Text></KVRow>
+                <Divider />
+                <KVRow label="Last movement"><Text size="sm" tabular>{open.lastMove}</Text></KVRow>
+                <Divider />
+                <KVRow label="Age"><Text size="sm" tabular>{`${open.ageYears} years`}</Text></KVRow>
+                <Divider />
+                <KVRow label="Book value"><Text size="sm" tabular>{formatMoney(open.value)}</Text></KVRow>
+              </View>
             </View>
-          </View>
+          </DrawerScrollArea>
           <View
             style={{
               borderTopWidth: 1,

package/examples/tpl_tower.tsx

@@ -7,7 +7,7 @@ import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
-import { Drawer } from "@lotics/ui/drawer";
+import { Drawer, DrawerScrollArea } from "@lotics/ui/drawer";
 import { Heatmap, type HeatmapCell } from "@lotics/ui/heatmap";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { PressableRow } from "@lotics/ui/pressable_row";
@@ -306,34 +306,36 @@ export function TplTower() {
           onNext={open.idx < walk.length - 1 ? () => setOpen({ ...open, idx: open.idx + 1 }) : undefined}
           position={`${open.idx + 1}/${walk.length}`}
         >
-          <View key={unit.key} style={{ flex: 1, padding: 24, gap: 16 }}>
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-              <Badge label={stateOf(unit.state).label} color={stateOf(unit.state).color} />
-              <Badge label={siteOf(unit.site).label} />
+          <DrawerScrollArea key={unit.key}>
+            <View style={{ gap: 16 }}>
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                <Badge label={stateOf(unit.state).label} color={stateOf(unit.state).color} />
+                <Badge label={siteOf(unit.site).label} />
+              </View>
+              {unit.message ? (
+                <Text size="sm" color="danger">{`${unit.message} (${formatAge(unit.ageMin ?? 0)} ago)`}</Text>
+              ) : null}
+              <View style={{ gap: 6 }}>
+                <KVRow label="Site"><Text size="sm">{siteOf(unit.site).label}</Text></KVRow>
+                <Divider />
+                <KVRow label="Model"><Text size="sm" tabular>{unit.model}</Text></KVRow>
+                <Divider />
+                <KVRow label="Hours since service"><Text size="sm" tabular>{unit.serviceHours.toLocaleString("en-US")}</Text></KVRow>
+              </View>
+              <View style={{ gap: 8, paddingTop: 4 }}>
+                <Text size="sm" weight="semibold">Recent events</Text>
+                <Timeline
+                  items={[
+                    ...(unit.message
+                      ? [{ id: "alarm", icon: "circle-alert" as const, iconColor: solid(stateOf(unit.state).color), label: unit.message, right: <Text size="xs" color="muted" tabular>{formatAge(unit.ageMin ?? 0)} ago</Text> }]
+                      : []),
+                    { id: "cycle", icon: "activity" as const, iconColor: solid("blue"), label: `Completed ${120 + hash(unit.serviceHours, 9) % 300} cycles today`, right: <Text size="xs" color="muted" tabular>today</Text> },
+                    { id: "service", icon: "settings" as const, iconColor: colors.zinc[500], label: "Scheduled service completed", right: <Text size="xs" color="muted" tabular>{`${1 + hash(unit.serviceHours, 10) % 20}d ago`}</Text> },
+                  ]}
+                />
+              </View>
             </View>
-            {unit.message ? (
-              <Text size="sm" color="danger">{`${unit.message} (${formatAge(unit.ageMin ?? 0)} ago)`}</Text>
-            ) : null}
-            <View style={{ gap: 6 }}>
-              <KVRow label="Site"><Text size="sm">{siteOf(unit.site).label}</Text></KVRow>
-              <Divider />
-              <KVRow label="Model"><Text size="sm" tabular>{unit.model}</Text></KVRow>
-              <Divider />
-              <KVRow label="Hours since service"><Text size="sm" tabular>{unit.serviceHours.toLocaleString("en-US")}</Text></KVRow>
-            </View>
-            <View style={{ gap: 8, paddingTop: 4 }}>
-              <Text size="sm" weight="semibold">Recent events</Text>
-              <Timeline
-                items={[
-                  ...(unit.message
-                    ? [{ id: "alarm", icon: "circle-alert" as const, iconColor: solid(stateOf(unit.state).color), label: unit.message, right: <Text size="xs" color="muted" tabular>{formatAge(unit.ageMin ?? 0)} ago</Text> }]
-                    : []),
-                  { id: "cycle", icon: "activity" as const, iconColor: solid("blue"), label: `Completed ${120 + hash(unit.serviceHours, 9) % 300} cycles today`, right: <Text size="xs" color="muted" tabular>today</Text> },
-                  { id: "service", icon: "settings" as const, iconColor: colors.zinc[500], label: "Scheduled service completed", right: <Text size="xs" color="muted" tabular>{`${1 + hash(unit.serviceHours, 10) % 20}d ago`}</Text> },
-                ]}
-              />
-            </View>
-          </View>
+          </DrawerScrollArea>
           <View
             style={{
               borderTopWidth: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "32.0.0",
+  "version": "34.0.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/avatar_size.ts

@@ -13,11 +13,28 @@ import type { TextSize } from "./text";
  */
 export type AvatarSize = "sm" | "md" | "lg" | "xl";
 
+/**
+ * THE RUNGS.
+ *
+ * `md` IS `CONTROL_CONTENT_HEIGHT`, and that is the whole design. An avatar is
+ * the tallest thing in any row that holds one, so a rung that overshoots its
+ * container does not look slightly big — it RESIZES the container. The default
+ * rung therefore has to be the largest a 40px control band can seat, and that
+ * number was already fixed elsewhere in the kit: 28, what `InlineButton` and a
+ * `md` `IconButton` use to sit inside a field. An avatar is not a special kind
+ * of child; it gets the same height they do.
+ *
+ * It was 36, which fits nothing. The same member chip measured 46 in a `Select`
+ * trigger, 50 in an inline editor and 54 in an `InlineSlot` — three heights for
+ * one control band, because each surface had picked its own inset and none of
+ * them had a number to pick it FROM.
+ */
 export const AVATAR_PX: Record<AvatarSize, number> = {
   /** Dense rows and inline chips — one initial, because two do not fit. */
   sm: 24,
-  /** The default: registers, lists, anywhere a person is a row. */
-  md: 36,
+  /** The default: a 40px control band, a register, a list — anywhere a person is
+   *  a row. Equals `CONTROL_CONTENT_HEIGHT` (`control_surface`). */
+  md: 28,
   /** Prominent rows, the account menu. */
   lg: 48,
   /** A profile's own header. */
@@ -32,19 +49,27 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
  * native, and `text.css` moves again at 768px, so these are the desktop numbers
  * and only a render can give them):
  *
- *   sm  12 on 24 = 50%   ·  md  14 on 36 = 39%
- *   lg  20 on 48 = 42%   ·  xl  32 on 72 = 44%
+ *   sm  12 on 24 = 50%
+ *   md  12 on 28 = 43%
+ *   lg  20 on 48 = 42%
+ *   xl  32 on 72 = 44%
  *
- * The two-letter rungs sit within 6 points of each other, so an avatar reads the
+ * The two-letter rungs sit within 2 points of each other, so an avatar reads the
  * same at every size rather than growing emptier as it grows — `lg` was on `md`
  * type (16 on 48 = 33%) and was visibly the thin one. `sm` runs richer by design:
  * one letter in a small circle needs the weight.
+ *
+ * `md` shares `sm`'s rung and is NOT the odd one out for it: the same 12px reads
+ * as 50% of a 24px circle holding one letter and 43% of a 28px circle holding
+ * two. Keeping it on `sm` type (14) would have put `md` at 50% — the fattest of
+ * the two-letter rungs, and the same defect in the other direction as the `lg`
+ * one this table was written to fix.
  */
 export const AVATAR_TEXT: Record<AvatarSize, TextSize> = {
   sm: "xs", // 12 on 24 — one letter, so it carries a larger share of the circle
-  md: "sm", // 14 on 36
-  lg: "lg", // 18 on 48
-  xl: "xxl", // 28 on 72
+  md: "xs", // 12 on 28
+  lg: "lg", // 20 on 48
+  xl: "xxl", // 32 on 72
 };
 
 const words = (name: string): string[] => name.trim().split(/\s+/).filter((w) => w !== "");

package/src/control_surface.ts

@@ -5,6 +5,38 @@ import { colors } from "./colors";
  *  buttons) aligns to it so a toolbar row reads as one band. */
 export const CONTROL_HEIGHT = 40;
 
+/**
+ * THE TALLEST FIXED-HEIGHT NODE A CONTROL BAND CAN SEAT — and so the inner height
+ * every 40px surface must afford. 6 per side of air, BORDER INCLUDED.
+ *
+ * `CONTROL_HEIGHT` is a promise — a toolbar row, a record's value column and a
+ * picker's option list read as one band because every control on them is 40. TEXT
+ * keeps that promise for free: a line is ~20, so `minHeight` governs and a
+ * surface's padding never binds. That is precisely why the promise broke the
+ * first time a control was handed something with a FIXED height. Each surface had
+ * quietly picked its own inset — 4, 6, 8 — with no number to pick it from, and
+ * nothing on a resting screen could reveal the disagreement; the moment a 36px
+ * avatar went in, the same member chip came out 46 in a `Select` trigger, 50 in
+ * an inline editor and 54 in an `InlineSlot`.
+ *
+ * 28 is not a fresh choice: it is what `InlineButton` and an `IconButton` at `md`
+ * had ALREADY settled on for sitting inside a field, air and all. Naming it once
+ * is what stops the next fixed-height child inventing a fourth number, and it is
+ * why an avatar on the default rung is 28 too — a control's children should not
+ * differ in height by what kind of thing they are.
+ *
+ * Anything taller does not belong in a control at all; it belongs in a row that
+ * sets its own height.
+ */
+export const CONTROL_CONTENT_HEIGHT = 28;
+
+/** A control's own vertical inset, derived so the band seats
+ *  {@link CONTROL_CONTENT_HEIGHT} at exactly {@link CONTROL_HEIGHT}. The 1px
+ *  border is part of the 6, so a bordered surface pads by this and an unbordered
+ *  one by this + 1 — reading the padding and forgetting the border is what let
+ *  three surfaces drift in the first place. */
+export const CONTROL_PADDING_V = (CONTROL_HEIGHT - CONTROL_CONTENT_HEIGHT) / 2 - 1;
+
 /** The narrowest a control may be and still be usable — below it, editors get
  *  crushed and option text has nowhere to go. It is the threshold at which a
  *  `DetailTable` gives up its side-by-side columns and stacks, and the floor

package/src/drawer.tsx

@@ -1,5 +1,5 @@
 import { ReactNode, useEffect } from "react";
-import { Modal, Pressable, StyleSheet, View } from "react-native";
+import { Modal, Pressable, ScrollView, StyleSheet, View } from "react-native";
 import { useScreenSize } from "@lotics/ui/use_screen_size";
 import { SizeBoundary } from "@lotics/ui/size_boundary";
 import { PortalHost } from "@lotics/ui/portal";
@@ -9,6 +9,19 @@ import { Text } from "@lotics/ui/text";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
 import { useLoticsLocale } from "@lotics/ui/locale";
 
+/**
+ * The panel's inset — the ONE left edge the header, `DrawerScrollArea` and the footer
+ * all sit on.
+ *
+ * `DrawerScrollArea` applies it, so an ordinary body never names this. It is
+ * exported for the surfaces that cannot use it: a MIXED body (a full-bleed ruled
+ * bar over guttered content) and a PINNED one (a heading or summary held above a
+ * scrolling list, which needs the gutter on both parts). A hardcoded `20` there
+ * silently stops matching the day this one moves — same reason `AVATAR_PX` is
+ * exported.
+ */
+export const DRAWER_GUTTER = 20;
+
 export interface DrawerProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -32,9 +45,12 @@ export interface DrawerProps {
   /** Position caption between the chevrons ("3/24"). */
   position?: string;
   /**
-   * Drawer body. Fills the panel below the header as a plain flex column — lay
-   * out your own scroll area and pinned footer (e.g. a thread that scrolls above
-   * a fixed composer).
+   * Drawer body — a BARE flex column filling the panel below the header, so a
+   * full-bleed child reaches the panel edge.
+   *
+   * Wrap content in `DrawerScrollArea` to get the panel's gutter; that is where
+   * the padding lives, and hand-rolling it is how a body ends up on a different
+   * left edge from the title above it. A `DrawerFooter` goes last, after it.
    */
   children: ReactNode;
   testID?: string;
@@ -134,6 +150,41 @@ export function Drawer(props: DrawerProps) {
   );
 }
 
+export interface DrawerScrollAreaProps {
+  children: ReactNode;
+}
+
+/**
+ * The scrolling, guttered content region of a `Drawer` — the exact counterpart of
+ * `DialogScrollArea`, and named to match it.
+ *
+ * It exists because the gutter is a CONTRACT, not a convenience: the content has
+ * to sit on the same left edge as the header's title and the footer's actions, and
+ * the panel is the only thing that knows that number. Left to callers, it was
+ * answered three different ways across the templates and the live apps — `24` six
+ * times (4px past the drawer's own title), `20` three times, and in one shipped
+ * app not at all, which put a comment thread flush against the panel edge while
+ * its title was inset 20.
+ *
+ * It ALWAYS scrolls, and there is deliberately no flag to stop it. A padded box
+ * holding a `flex:1` scroller insets that scroller's VIEWPORT — measured, a 400px
+ * panel ends its scroll at 380 — so the list clips short of the panel with dead
+ * space beneath it. A surface that genuinely needs a pinned region above a
+ * scrolling one is not this component: it goes in the `Drawer`'s bare slot and
+ * puts `DRAWER_GUTTER` on the pinned part's padding AND on its scroller's
+ * `contentContainerStyle`, which is the only arrangement where content still
+ * reaches the panel edge.
+ *
+ * A body that must reach the panel edge — a full-bleed band, a whole record screen
+ * carrying its own gutters — likewise does NOT wrap in this, which is why the
+ * `Drawer` leaves its slot bare. That is also how `Modal` and `Dialog` work; a
+ * `Drawer` that padded its own slot would be the one overlay of the three that
+ * does, and would force every full-bleed child to cancel it with a negative margin.
+ */
+export function DrawerScrollArea(props: DrawerScrollAreaProps) {
+  return <ScrollView style={styles.body} contentContainerStyle={styles.bodyContent}>{props.children}</ScrollView>;
+}
+
 export interface DrawerFooterProps {
   /** The action(s) — typically right-aligned `Button`s. Prepend a
    *  `<Text style={{ flex: 1 }}>` hint to push them right with a summary on the left. */
@@ -155,7 +206,7 @@ const styles = StyleSheet.create({
   footer: {
     borderTopWidth: 1,
     borderTopColor: colors.border,
-    paddingHorizontal: 20,
+    paddingHorizontal: DRAWER_GUTTER,
     paddingVertical: 14,
     flexDirection: "row",
     alignItems: "center",
@@ -183,7 +234,10 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
     gap: 8,
-    paddingLeft: 20,
+    paddingLeft: DRAWER_GUTTER,
+    // Short of the gutter by design: the close IconButton carries its own
+    // padding, so a full gutter here would push its GLYPH inside the edge the
+    // title sits on.
     paddingRight: 12,
     paddingTop: 16,
     paddingBottom: 8,
@@ -197,4 +251,7 @@ const styles = StyleSheet.create({
   body: {
     flex: 1,
   },
+  bodyContent: {
+    padding: DRAWER_GUTTER,
+  },
 });

package/src/inline_button.tsx

@@ -2,11 +2,14 @@ import { type GestureResponderEvent } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
-import { CONTROL_TRANSITION } from "./control_surface";
+import { CONTROL_CONTENT_HEIGHT, CONTROL_TRANSITION } from "./control_surface";
 
 /** The height that fits INSIDE the 40px inline control band with 6px of air
- *  above and below — the same air a `DetailRow`'s label gets against its value. */
-const INLINE_BUTTON_HEIGHT = 28;
+ *  above and below — the same air a `DetailRow`'s label gets against its value.
+ *  This file is where that number was FIRST worked out; it now lives in
+ *  `control_surface` so an avatar or any other fixed-height child of a control
+ *  lands on the same line rather than inventing its own. */
+const INLINE_BUTTON_HEIGHT = CONTROL_CONTENT_HEIGHT;
 
 interface InlineButtonProps {
   /** The verb, as a word. An inline button is never icon-only — it sits on a

package/src/inline_edit.tsx

@@ -6,7 +6,7 @@ import { useLoticsLocale } from "./locale";
 import { ActivityIndicator } from "./activity_indicator";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { colors } from "./colors";
-import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { FOCUS_RING, CONTROL_RADIUS, CONTROL_PADDING_V, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { fontFamilyRegular, getInputTextStyle, getMultilineInputHeight, getTextColor, type TextColor } from "./text_utils";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
@@ -653,11 +653,15 @@ const styles = StyleSheet.create({
     borderColor: colors.border,
     backgroundColor: colors.white,
     paddingHorizontal: 8,
-    // Vertical padding matters only when the display content is TALLER than
-    // one line (a rich select showing title + description at rest): minHeight
-    // still governs single-line rows, so those render pixel-identical, while
-    // multi-line content gets breathing room instead of touching the edges.
-    paddingVertical: 6,
+    // Vertical padding binds on two kinds of content, never on a single line
+    // (minHeight governs there, so those rows render pixel-identical whatever
+    // this is): content TALLER than one line, which gets breathing room instead
+    // of touching the edges, and content of FIXED height — an avatar, a swatch —
+    // which this decides the field's whole height for. Hence the shared
+    // constant: an editor seats a `CONTROL_CONTENT_HEIGHT` node at exactly 40,
+    // the same as every other 40px surface, rather than at a number this file
+    // happened to choose.
+    paddingVertical: CONTROL_PADDING_V,
     flexDirection: "row",
     alignItems: "center",
     gap: 6,

package/src/inline_slot.tsx

@@ -1,6 +1,6 @@
 import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
 import { type ReactNode } from "react";
-import { CONTROL_RADIUS } from "./control_surface";
+import { CONTROL_PADDING_V, CONTROL_RADIUS } from "./control_surface";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
 
 export interface InlineSlotProps {
@@ -46,13 +46,16 @@ const styles = StyleSheet.create({
     borderWidth: 1,
     borderColor: "transparent",
     paddingHorizontal: 8,
-    // The editors' vertical padding too, not just the horizontal. A single line
-    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
-    // sides land on 40 whether or not this exists — but an auto-growing input
-    // sizes itself to content PLUS its padding and border, so from the SECOND
-    // line on, a value without this sits ~14px shorter than the input that
-    // replaces it. Matching by coincidence at one line is not matching.
-    paddingVertical: 8,
+    // The editors' vertical padding too, not just the horizontal — and it comes
+    // from the shared constant, NOT from the 8 the horizontal happens to use. A
+    // single line hides both the absence and a mismatch: the box is `minHeight`
+    // 40 and the text is ~20, so any padding from 0 to 10 lands on 40. It bites
+    // from the SECOND line on (an auto-growing input sizes to content PLUS its
+    // padding and border, so a value without this sits shorter than the input
+    // that replaces it) and on any FIXED-height content, where this slot's old
+    // hand-picked 8 made it 4px taller than the editor beside it for the very
+    // same child. Matching by coincidence at one line is not matching.
+    paddingVertical: CONTROL_PADDING_V,
     justifyContent: "center",
   },
 });

package/src/member_chip.tsx

@@ -12,7 +12,8 @@ interface MemberChipProps {
   image?: string | null;
   /** Optional secondary line under the name — e.g. email, role, department. */
   secondary?: string | null;
-  /** A rung on the shared avatar scale. Default `md`. */
+  /** A rung on the shared avatar scale. Default `md`, which is sized to seat in a
+   *  40px control band; drop to `sm` for a dense cell. See `AVATAR_PX`. */
   size?: AvatarSize;
   style?: StyleProp<ViewStyle>;
 }
@@ -26,6 +27,12 @@ interface MemberChipProps {
  * Pure: pass the member's fields in (from `useMembers`, or a resolved
  * `select_member` cell joined against that roster); this component fetches
  * nothing and carries no domain types.
+ *
+ * A chip's usual home is a 40px CONTROL BAND — a picker option, a select's
+ * trigger, an inline editor at rest, a diff slot — and the default `md` is sized
+ * to seat in one (`CONTROL_CONTENT_HEIGHT`). That is not a coincidence to
+ * preserve by hand: it is why `md` is 28 rather than the 36 that used to grow
+ * those three surfaces to 46, 50 and 54 for the very same chip.
  */
 export function MemberChip({ name, image, secondary, size = "md", style }: MemberChipProps) {
   const displayName = name?.trim() || "Unknown";

package/src/select.tsx

@@ -1,7 +1,7 @@
 import { StyleSheet, View, type GestureResponderEvent, type StyleProp, type ViewStyle } from "react-native";
 import { useState, useCallback, useMemo, type ReactNode, type Ref } from "react";
 import { colors } from "./colors";
-import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { FOCUS_RING, CONTROL_RADIUS, CONTROL_HEIGHT, CONTROL_PADDING_V, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { Text } from "./text";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
@@ -293,11 +293,14 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
     paddingHorizontal: 6,
-    paddingVertical: 4,
+    // Shared, so a trigger seats a `CONTROL_CONTENT_HEIGHT` node at exactly
+    // `CONTROL_HEIGHT` — the hand-picked 4 here made this trigger 4px shorter
+    // than the inline editor holding the identical chip.
+    paddingVertical: CONTROL_PADDING_V,
     borderWidth: 1,
     borderColor: colors.border,
     borderRadius: CONTROL_RADIUS,
-    minHeight: 40,
+    minHeight: CONTROL_HEIGHT,
   },
   opened: {
     // Mouse-opened, so the trigger never takes keyboard focus — wear the same 2px