@lotics/ui 32.0.0 → 33.0.0

package/MIGRATION.md

@@ -4,6 +4,47 @@ 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.
 
+## 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

@@ -1157,9 +1157,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:
 

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": "33.0.0",
   "type": "module",
   "exports": {
     "./vite": {

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,
+  },
 });