@lotics/ui 11.3.0 → 11.5.0

package/docs/templates.md

@@ -0,0 +1,357 @@
+# Templates — the worked example screens
+
+The package ships full worked-example screens in `examples/tpl_*.tsx` — each a complete,
+runnable recipe for one screen **job**, built purely from `@lotics/ui` components plus mock
+data. This doc is the map: what shape each template solves, what it owns versus what its
+primitives own, and which one to start from. Read it when starting any new screen, then read
+the chosen template's source before writing code. Component contracts live in
+[the catalog](./catalog.md), the layout/color laws in [the composition grammar](./composition.md);
+the package index is [../AGENTS.md](../AGENTS.md).
+
+## How to use an example
+
+- **Read the source** at `node_modules/@lotics/ui/examples/<name>.tsx`. Each file is
+  self-contained: `react` + `react-native` + `@lotics/ui/<module>` imports only, mock data
+  constants at the top, one exported screen component.
+- **Copy and adapt — never import.** The `examples/` directory ships as `.tsx` source and is
+  **not** in the package's `exports` map: `import … from "@lotics/ui/examples/…"` fails module
+  resolution by design. Copy the bands you need into your app, keep the component imports,
+  and replace the mock constants with real reads.
+- **Pick by the job, not the domain.** Templates are scenario-flavoured (a pick run, cash
+  application, a delivery week) but generic-purpose — they teach the shape. Your orders /
+  items / customers screen starts from the template whose *job* matches, whatever the domain.
+- The templates encode the composition grammar (band order, toolbar law, color discipline,
+  status weight) as working code — when a template and your instinct disagree, the template
+  wins.
+
+## Picking by the job
+
+| You are building | Start from |
+| --- | --- |
+| Executive overview — KPIs, trends, an attention list | `tpl_dashboard` |
+| Monitoring a population too large to browse (drill-down → faceted register) | `tpl_stock` |
+| A live wallboard of hundreds of unit states | `tpl_tower` |
+| One dimension crossed against another, with drill | `tpl_pivot` |
+| Hierarchical totals chased down a tree | `tpl_rollup` |
+| A register / consolidated work-list (browse, per-row action, bulk action) | `tpl_item_list` |
+| A guided sequence of physical tasks (scan, confirm, next) | `tpl_pick` |
+| Splitting one source amount across many targets | `tpl_allocate` |
+| A record's create/edit surface — also the settings shape | `tpl_record` |
+| A personal to-do list | `tpl_tasks` |
+| A team task board (inline-managed grouped table) | `tpl_task_board` |
+| Financial statements | `tpl_statements` |
+| A scoped lookup report with export | `tpl_report` |
+| A week calendar + agenda | `tpl_calendar` |
+| An attendance desk | `tpl_attendance` |
+| Shift signup + staffing | `tpl_shifts` |
+| AI produces a visual artifact on a canvas | `tpl_dieline` |
+| AI ranks answers — look-up-and-explain | `tpl_lookup` |
+| AI over a record's documents (extract / cross-check / generate) | `tpl_documents` |
+
+## Analytics
+
+Read-mostly screens that answer a question about a population, then open doors into the
+records behind each number.
+
+### `tpl_dashboard` — the executive overview
+
+One screen answering "how is this period going, where is it stuck, who pays the bills".
+Bands: header + period · `KPIStrip` · a revenue chart (`BarChart`, emerald = money) beside
+the pipeline (`StackedProgressBar`, blue = pipeline) · a **Needs attention** `Accordion`
+(icon + label + count `Badge`; expanding opens the records behind the count, each row
+carrying its domain `⋯ ActionMenu`) · top customers (`Avatar` + revenue + margin badge; the
+name `Peek`s the dossier). Also exercises the wider chart family (`LineChart`, `PieChart`,
+`RingGauge`, `Sparkline`, `TrendFooter`, `Funnel`) and `DateRangeFilterField` — the date
+filter actually filters the KPI datasets. Start here for any "state of the operation"
+landing screen.
+
+### `tpl_stock` — the drill-down overview (large populations)
+
+Monitoring a population too large to browse (10,000+ units). The funnel: `KPIStrip`
+(population health) → `Breakdown` cards (composition by dimension; **pressing a segment IS
+the drill-down**) → dismissible facet chips + search → a **paginated** register (the data
+volume is the reason `Pagination` exists) → row press opens the sequenced unit `Drawer`, `⋯`
+carries quick operations. Facets combine across dimensions and each `Breakdown`'s counts
+respect the *other* dimensions' selections — true faceted search. Also the reference for
+color discipline: coherent dimensions take one hue family shaded by `ramp`; status colors
+carry meaning, one `ColorName` per state, no hand-picked hex.
+
+### `tpl_tower` — the status-grid wallboard
+
+Continuous monitoring of hundreds of live units (machines, gates, sensors). Three bands
+answer the three ops questions in order: `KPIStrip` + `StatusGrid` = "is everything OK right
+now?" (scan for red; the `StatusLegend` drills a state) · an exceptions rail = "where do I
+look first?" (severity, then longest unresolved) · a `Heatmap` = "when/where does it
+cluster?" (pressing a cell explains the day). Cells and exception rows open the SAME
+sequenced unit `Drawer` (with a `Timeline` of the unit's events). One semantic color
+reference per state — every weight (grid cell, legend dot, drawer badge) derives from that
+family name.
+
+### `tpl_pivot` — the cross-tab desk
+
+One dimension crossed against another, then drill. The `Matrix` is the hero: the number IN
+each cell plus a heat wash behind it so concentration reads at a glance, row/column/grand
+totals down the edges. **Pressing a cell is a door** — the register below filters to exactly
+that intersection; a row there opens the item drawer. The pattern for "how does X distribute
+across Y, and what's behind each bucket?".
+
+### `tpl_rollup` — hierarchical totals
+
+Totals with drill: three levels (e.g. region → site → lane), every level carrying the SAME
+aligned metric columns so a bad number can be chased down the tree ("which branch drags the
+total?"). Pure composition: nested `Accordion`s + a fixed-width column map; under-target
+branches are flagged at every level so the drill path is visible before expanding. Leaf rows
+open a sequenced `Drawer`.
+
+## Work
+
+Screens where the user executes: browse → act. **Every work screen is FLAT (no `Card`) and
+ONE of two shapes**: a register/list you WORK EACH of (press a row → workspace `Drawer`) or
+a list you ACT ON MANY of (tick rows → `FloatingActionBar`) — never a side-by-side
+master-detail panel.
+
+### `tpl_item_list` — THE canonical register
+
+The one work-execution list shape; it subsumes approvals, dispatch, batch-building, and run
+screens — register, per-row action, gated selection, and act-on-many in one. The page:
+
+- **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
+  RIGHT; a light `SummaryLine` of the filtered view below.
+- **A sortable, `Divider`-separated `Table`** where every row carries a leading checkbox; a
+  row that can't take the bulk action gets a **disabled** checkbox (the same gating as any
+  blocked line). A per-row action `Button` (here Print) is the row's primary action in the
+  trailing column, `⋯` its overflow. A select-all band, footer totals + `Pagination`, and a
+  `FloatingActionBar` carrying the bulk action while rows are ticked.
+- **A row press opens the PRODUCTION workspace `Drawer`**, which demonstrates the full
+  record-workspace anatomy section by section:
+  - **Details `DetailTable`** showing every inline field type — text, `InlineMemberSelect`,
+    dates incl. optional time, dot-select, money number, the `InlineTagSelect` tag field,
+    and `InlineStatic` + a System badge for read-only values. Detail rows earn trailing CTAs
+    where deserved (Phone → Call, Due → Today) — the case where `trailingWidth` IS set.
+  - **Linked records** — the customer's other records as `ListItem`s (title + description at
+    the column edge, badge · amount · chevron); pressing one PUSHES an **editable** workspace
+    for that record inside the drawer via the hosted `ScreenRouter` — while `canGoBack` the
+    drawer header swaps to a back button + the pushed id and the ◀ ▶ sequencer hides; back
+    pops with scroll preserved.
+  - **Files** with its own Add CTA — `FileRows` CRUD via `pickFiles`, plus an EXPECTED
+    document as a ghost `FileRow placeholder` with a Request action.
+  - **Payment** — the `Ledger` (charge/received groups with sums, peekable fee rows,
+    `LedgerTotal`) + a Record-payment popover that appends a receipt.
+  - **Activity** — the CRM touch-log shape: optional outcome pills (`ChipGroup`,
+    tap-to-deselect) over a MULTILINE note (the note IS the record and the one requirement),
+    an always-visible optional follow-up `InlineDatePicker`, an "Attach files" secondary
+    (`pickFiles` → removable `FileThumbnailGrid` in the composer), and the primary Log button
+    saying WHY when disabled. Below, a labelled History `Timeline` of outcome-typed entries,
+    newest first — an entry's attachments ride its expandable details as a thumbnail grid
+    whose press opens the shared `FileGalleryModal`.
+  - A closing `DangerZone`.
+
+### `tpl_pick` — the guided queue
+
+Work that is a SEQUENCE of physical tasks, not a list to browse: the run hands the operator
+the next location, they scan to verify (`ScanField`), confirm the count (`Counter`), and the
+next task takes its place. A single-focus column — the CURRENT task is the only thing in view;
+the whole path is a collapsible `Accordion` below, collapsed by default, so position is one
+tap away and never competes with the task. Can't-skip ordering, `Stepper` + `ProgressBar`
+progress, and a short-pick exception that flags-and-advances without stalling, ending in a
+`CompletionState`.
+
+### `tpl_allocate` — the split
+
+Apply ONE source across MANY targets until the remainder is zero (cash application,
+stock-to-orders, budget distribution). The inverse of a batch builder: batch SUMS parts up to
+a total; allocation SPLITS a fixed total DOWN with a remainder that must hit zero. The
+`RemainderMeter` is the spine — under (left on account) · exact (apply) · over (blocked).
+Oldest-first auto-allocates; each `AllocationRow` can be filled or typed.
+
+### `tpl_record` — THE record surface
+
+Create-then-refine taken all the way: **"New" is ONE CLICK** (no dialog, no form) — it
+creates a fresh Draft and the surface IS the editor; everything refines in place. It absorbed
+the old order-form, inline-record, intake, settings, billing, and quick-capture templates.
+Top → bottom:
+
+- A `RecordSummary` header (identity · status · the one metric) over its key-fact
+  `DetailTable`, then a Details `DetailTable` — one shared column grid, auto-stacking when
+  narrow.
+- **The customer section — TWO states, no swap mode.** Attached = the read-only-first card:
+  Edit/Done live in the SECTION HEADING and swap the fields to inline chips, where a trailing
+  Fetch fills contact + city from a registry lookup keyed by tax ID, un-gating billing;
+  Remove (danger) sits low and detaches the link (the customer stays in the book) → the
+  find-or-create search, whose custom row opens the create `Dialog` rendering the SAME
+  inline-chip table + Fetch.
+- **Files** — `FileDropzone` add, gallery preview, delete.
+- **Billing, owned by a later desk** (gated until the record reaches that stage), in the
+  inline vocabulary: each invoice is a hairline-set band; charge amounts are chips with the
+  list price as ghost placeholder + a one-tap "Standard …" suggestion pill while unset;
+  "How paid…" select chips; NO per-band totals — the collect band owns the number. The band's
+  action row sits BOTTOM-RIGHT as *hint → status dot → Issue*, the hint naming exactly what
+  blocks (fees → method → the customer gate). An ISSUED invoice keeps its lines editable and
+  offers Re-issue — a new lookup code replaces the old, confirmed in the same `Dialog`. Plus
+  a validated receipt and a separate refundable deposit.
+- **The lifecycle is a HANDOFF CHAIN** (e.g. Sales → Operations → Accounting → Closed): a
+  Tasks section speaking the full task-list grammar — a clearable Group-by `FilterChip`
+  (Desk/Assignee/Status) plus assignee/status filter chips derive the groups (empty groups
+  drop, EXCEPT desk groups — the journey stays visible; desk heads keep their owner dots,
+  assignee heads are `MemberChip`s), the add-a-task `CaptureRow` at the TOP landing on the
+  current desk, rows riding the `Checklist`/`ChecklistRow` compound with per-task
+  `InlineMemberSelect` assignees and a per-row `menu` (move to next desk · danger Delete),
+  and suggested tasks as `SuggestionChip`s. EVERY desk's rows edit — the stage gates the
+  handoff and Billing, never task editing (planning ahead on a later desk is normal work).
+  **Per-stage handoff CTAs are NEVER blocked** — open tasks warn and carry over.
+- Also the settings shape: Preferences switch rows + a `DangerZone`.
+- A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) jumps between the sections and
+  scroll-spies the active one; on narrow containers it becomes the pinned current-section
+  bar opening a section-picker `Modal`.
+
+### `tpl_tasks` — the quick list
+
+The personal to-do shape: quiet `CheckCircle` rows you tick to finish and tap to **expand in
+place** to edit (`Inline*` editors; the row is stable — the meta summary never shifts on
+expand), colour-dot tags (`OptionBadge`), an attachments field (`FilesEditor` — thumbnail
+grid, tap a tile for the gallery with download + confirmed remove, plus its Add button),
+search + a clearable group-by (✕ → ungrouped) + tag filter chips, and a primary
+Draft-from-notes CTA (`Composer` → `AgentRun` → `ChangeReview`). No assignee — the list is
+yours.
+
+**Warning — never a button in a button.** There is deliberately NO `Task` component: a task
+row varies too much to bake into one, so rows compose `CheckCircle` + `InlineTextInput` +
+inline-editor cells as **sibling** controls in a plain `View`. NEVER wrap the whole row in a
+`Pressable accessibilityRole="button"` (for tap-to-expand) with those controls nested inside:
+React Native Web renders the row AND each control as a `<button>`, so you get `<button>`s
+inside a `<button>` — invalid DOM, and the inner controls drop out of the keyboard tab order.
+Give "expand" its own affordance (a trailing `Pressable` over the meta/chevron), as
+`tpl_tasks` does.
+
+### `tpl_task_board` — the columns shape
+
+The manager's board: a search · group-by · filter toolbar over a grouped, sortable grid of
+LIVE inline-editable cells — assignee/due/status/tags set directly in the cell. It builds on
+the `DataGrid` primitive (the inline-managed grouped-table shape) and **owns only its data,
+toolbar, columns, and per-group add**; `DataGrid` owns the sortable header, the collapsible
+grouped sections, and the aligned rows. It demonstrates:
+
+- A **files cell** — thumbnail glance in the cell → a `Popover` hosting the full
+  `FilesEditor` → gallery.
+- A **dynamic action column** — a per-row underlined action link (`TextLink`) driven by each
+  row's `action` descriptor (attach / approve / open…), each wired in a real app to its OWN
+  workflow: one board, a different action per row; the link's pressable fills the cell to
+  match the inline editors.
+- A trailing `ActionMenu` (the `⋯` overflow — a `danger` Remove behind a confirm `Alert`).
+- CUSTOM pressable cells (files, the action link) hover with the control-surface BORDER
+  reveal (`HOVER_BORDER` from `@lotics/ui/control_surface`) — the same language as the
+  inline-editor cells beside them, never their own background wash.
+- Per-group add rows that pre-set the group's field (align with the exported `gridRowStyle`),
+  and the same Draft-from-notes CTA as `tpl_tasks`.
+
+Both `tpl_tasks` and `tpl_task_board`: filters/search left, primary CTA right, one toolbar
+row; group-by holds only real dimensions, ✕ clears to ungrouped (no "Nothing" option).
+
+**Altitude rule**: `tpl_task_board` is the inline-managed grouped table — MODERATE data you
+manage in view (group/sort/filter/edit-in-place; it renders ALL rows). For thousands+ you
+BROWSE — that's `tpl_item_list`'s paginated register, not this.
+
+## Finance
+
+### `tpl_statements` — the statement grammar
+
+The income statement, balance sheet, and cash flow statement in ONE statement grammar:
+right-aligned column captions over fixed money columns, items indented under group headers, a
+hairline rule above every subtotal, the grand total DOUBLE-RULED (the accounting convention),
+negatives in accounting parentheses, per-cell currency-free (the meta line names the currency
+once), no bars, no charts — the numbers are the interface. Composed from `Text` + `Divider`
+alone: it teaches a grammar, not a component. The three statements TIE — net income flows
+into retained earnings, closing cash IS the balance sheet's cash, the loan repayment moves
+the debt line. Keep your books reconciled when adapting the data, or the screen teaches the
+wrong thing.
+
+### `tpl_report` — the scope-first lookup report
+
+Answer a question by SCOPING a dataset, not by browsing it. The scope bar leads: a header
+period (`DateRangeFilterField`) + ONE search key chosen from several mutually-exclusive
+dimensions (`SegmentedControl` swaps the matching picker; switching the key resets the
+value). That scope drives everything below — KPI totals → a row of pressable `Breakdown`
+facets (the long-tail one folds behind `maxRows`) → the paginated register of matching lines
+→ an Export button. Leave the search empty and the period alone gives the whole-period
+report. The fee / transaction / usage lookup desk.
+
+## Scheduling
+
+### `tpl_calendar` — the week desk
+
+One real `CalendarView` week grid over the current week's events, then a "Today" agenda card
+of pressable rows. Every slot is a door: pressing a grid event or an agenda row opens the
+sequenced workspace `Drawer`; agenda rows also carry the `⋯` quick-actions menu. Event colors
+carry meaning (one `ColorName` per event kind). The mock data anchors to the real current
+week so the copied screen is evergreen.
+
+### `tpl_attendance` — the attendance desk
+
+Who is in, who is late, who is out, plus the weekly per-person grid. Header + month `Picker`
+· `KPIStrip` (the four counts) · `Tabs` Today / This week. "Today" = one banded roster
+`Card` — each row press-opens the person's workspace `Drawer` (◀ ▶ sequencing) and carries a
+`⋯ ActionMenu` with the day's quick fixes. "This week" = per-person `Accordion` rows: day
+markers expanding to the day-by-day detail in place. Presence is one accent; badge colors
+carry the status meaning.
+
+### `tpl_shifts` — two-sided staffing
+
+Members SIGN UP, the manager DECIDES and FILLS. Three bands reuse the execution grammar: the
+coverage board is the overview (shifts × days, each cell its filled/required state — press to
+open the slot), the signup rail is the APPROVALS pattern (in-hours = one-click Accept;
+overtime = a consequence `Dialog`; decline behind `⋯`), and the slot drawer fills gaps with
+the DISPATCH fit-gate (every candidate names their hours; same-slot members are excluded,
+double-shift days flagged). Accepting and assigning move the board live.
+
+## Agents
+
+Screens where AI does the work and the human reviews. `tpl_dieline` *produces* an artifact;
+`tpl_lookup` and `tpl_documents` *structure* information for a decision. The AI component
+contracts and the propose→review→apply loop live in [ai_patterns.md](./ai_patterns.md).
+
+### `tpl_dieline` — the design canvas
+
+The page IS the design: a parametric drawing fills the centre of a pannable/zoomable surface,
+a FLOATING `Composer` sits at the bottom, and a pinned PARAMS PANEL (a hand-composed
+label/value field card in live-edit mode) floats centre-right. Empty → drop a photo in the
+composer → the centre processes while the composer MORPHS into a progress pill
+(`AgentProgress`) → the drawing reveals, the params panel appears, the composer returns. Two
+ways to change it: prompt the agent ("5 mm taller") or edit a param directly — either
+re-flows the design in place. The geometry is deterministic (the app owns it); the agent only
+proposes parameters. The panel carries the single Download.
+
+### `tpl_lookup` — the answer desk
+
+Look-up-and-explain (classification, tariff/fee lookup, policy Q&A, a spec/compliance desk).
+Describe the subject on the LEFT (`Composer` + `AgentRun`), the agent RANKS the matching
+candidates (nearest matches, the top one wearing a Recommended `Badge`), you pick one and its
+structured ANSWER pins on the RIGHT — the code, the exact breakdown as hand-composed spec
+rows, policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matches → pick, not
+a single confident verdict: classification is ambiguous, so the alternatives are first-class.
+Refine the description in a follow-up and the ranking updates.
+
+### `tpl_documents` — the document desk
+
+THE worked example for everything document-driven on a record. A record's files block feeds
+ONE **"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
+menu holds only Rename/Download). Inside its dialog the run FORKS into three tasks as
+`CardSelectItem`s (select → a confirming footer CTA, never one-click):
+
+- **Extract** (read the documents, fill the record) — the open `ChangeFields` review: ONE
+  `Change` section per record whose body stacks a `ChangeField` per proposed value (label ·
+  the − band when replacing · the editable + value). **Editing IS the review**; an add has no
+  before, a removal is the − band alone, and a conflict shows the read-only outcome band over
+  candidate rows + a type-another-value third option. Proposed line items arrive as
+  `ChangeRecord` cards; Keep-all + one outcome-named Apply commit.
+- **Cross-check** (compare the documents against the record and each other) — ranked,
+  display-only `Finding`s the human acts on, closing in a recorded verdict.
+- **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the
+  platform chat (the documents attached to a fresh thread), not in the app.
+
+Separately, a **Create documents** action opens its own dialog: a readiness checklist
+(hand-composed rows — per-document missing inputs open a fill screen, saved values recompute
+readiness) → generation runs as a visible `AgentRun`, never a teleport → generated files stay
+PENDING (previewable) until the user commits them onto the record.
+
+All mock — `useState` plus a timer streams the `AgentRun`; a real app drives the same
+components from its live agent run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.3.0",
+  "version": "11.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -223,7 +223,8 @@
   "files": [
     "src",
     "examples",
-    "AGENTS.md"
+    "AGENTS.md",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"

package/src/popover.tsx

@@ -188,7 +188,7 @@ export interface PopoverContentProps {
    *  restores it on close. Set false for an anchored panel whose trigger must
    *  keep focus — e.g. a search-as-you-type combobox whose input lives outside
    *  the popover and drives the list via `aria-activedescendant`. Focus then
-   *  stays on the trigger; keyboard still reaches it through the overlay. */
+   *  stays on the trigger; keyboard still reaches the content. */
   manageFocus?: boolean;
 }
 
@@ -212,9 +212,9 @@ export function PopoverContent(props: PopoverContentProps) {
   const [isBottomSheetShown, setIsBottomSheetShown] = useState(false);
   const returnFocusRef = useRef<HTMLElement | null>(null);
   // Last known trigger geometry. The trigger can unmount while the popover is
-  // open — a hover-revealed menu button stops being rendered the moment our
-  // overlay covers its row and the hover ends — so positioning cannot rely on
-  // `triggerRef.current` still being live when it runs.
+  // open — a hover-revealed menu button stops being rendered once its row loses
+  // hover/focus — so positioning cannot rely on `triggerRef.current` still being
+  // live when it runs.
   const triggerRectRef = useRef<DOMRect | null>(null);
 
   const handleClose = useCallback(() => {
@@ -224,9 +224,9 @@ export function PopoverContent(props: PopoverContentProps) {
 
   // Snapshot the trigger geometry synchronously the moment we open, while it is
   // guaranteed to still be mounted. `calculatePosition` runs later in a rAF, by
-  // which point a hover-revealed trigger may already be gone (our overlay covers
-  // its row, hover ends, the button unmounts). Capturing here keeps the popover
-  // anchored to where the trigger was instead of stranding it off-screen.
+  // which point a hover-revealed trigger may already be gone (a hover-revealed row
+  // button can unmount once hover/focus leaves the row). Capturing here keeps the
+  // popover anchored to where the trigger was instead of stranding it off-screen.
   useLayoutEffect(() => {
     if (!open || small) return;
     if (triggerRef.current) {
@@ -249,7 +249,10 @@ export function PopoverContent(props: PopoverContentProps) {
       const firstFocusable = content.querySelector<HTMLElement>(
         'input, select, textarea, button, [role="button"], [role="menuitem"], [role="option"], [tabindex]:not([tabindex="-1"])',
       );
-      (firstFocusable ?? content).focus();
+      // preventScroll: focusing the content must never scroll an ancestor into
+      // view — that scroll would trip the scroll-to-dismiss listener and close the
+      // popover the instant it opens.
+      (firstFocusable ?? content).focus({ preventScroll: true });
     });
 
     return () => {
@@ -262,11 +265,11 @@ export function PopoverContent(props: PopoverContentProps) {
       // popover (a Picker/InlineSelect/menu) it is <body>; restoring there strands
       // focus and the next Tab jumps to the page's first focusable. Fall back to
       // the prior element only if the trigger is gone (e.g. a hover-revealed menu
-      // button that unmounted under the overlay).
+      // button that unmounted once its row lost hover).
       const trigger = triggerRef.current;
       const target = trigger && trigger.isConnected ? trigger : prior;
       if (target && typeof target.focus === "function") {
-        target.focus();
+        target.focus({ preventScroll: true });
       }
     };
   }, [open, manageFocus]);
@@ -313,6 +316,34 @@ export function PopoverContent(props: PopoverContentProps) {
     };
   }, [open, small, onOpenChange]);
 
+  // Outside-dismiss (NON-MODAL anchored popover): with no blocking overlay, the
+  // rest of the page stays interactive, so we close on a click that lands outside
+  // this popover's content AND its trigger. We listen on `click` (not pointerdown)
+  // in the CAPTURE phase so that clicking ANOTHER field's trigger completes that
+  // trigger's own press — the old popover dismisses AND the new one opens in a
+  // single click, instead of the press being cancelled mid-gesture. A click INSIDE
+  // a deeper (nested) popover keeps this one open — a Select opened inside a filter
+  // popover must not dismiss the filter. The bottom sheet (`small`) is modal and
+  // dismisses via its scrim, so it opts out here.
+  useEffect(() => {
+    if (!open || small) return;
+    const onOutsideClick = (e: MouseEvent) => {
+      const node = e.target instanceof Node ? e.target : null;
+      if (!node) return;
+      if (popoverRef.current?.contains(node)) return; // inside my content
+      if (triggerRef.current?.contains(node)) return; // on my trigger — its own press toggles
+      // Keep open when the click is inside a DEEPER popover (e.g. a Select opened
+      // inside this one). `data-popover-level` is the same nesting depth as z-index.
+      const myLevel = Number(popoverRef.current?.getAttribute("data-popover-level") ?? "0");
+      const el = node instanceof Element ? node : node.parentElement;
+      const hit = el?.closest("[data-popover]");
+      if (hit && Number(hit.getAttribute("data-popover-level") ?? "0") > myLevel) return; // deeper popover
+      onOpenChange(false);
+    };
+    document.addEventListener("click", onOutsideClick, true);
+    return () => document.removeEventListener("click", onOutsideClick, true);
+  }, [open, small, onOpenChange, triggerRef]);
+
   const calculatePosition = useCallback(() => {
     if (!popoverRef.current) return;
     if (small) return;
@@ -476,11 +507,26 @@ export function PopoverContent(props: PopoverContentProps) {
       }
     });
 
+    // Non-modal: the page can now scroll UNDER an open popover. A scroll of the
+    // page or any ancestor is a "moved on" signal, so we DISMISS (as native
+    // <select> and most menu systems do) rather than chase the trigger and risk a
+    // panel detached from an off-screen anchor. Scrolling the popover's OWN content
+    // (a long option list) must NOT close it. Capture catches nested scrollers.
+    const onScroll = (e: Event) => {
+      if (e.target instanceof Node && popoverRef.current?.contains(e.target)) return;
+      onOpenChange(false);
+    };
+    window.addEventListener("scroll", onScroll, true);
+    // A window resize just re-anchors (the layout moved, the intent didn't).
+    window.addEventListener("resize", calculatePosition);
+
     return () => {
       cancelAnimationFrame(frame);
       resizeObserver?.disconnect();
+      window.removeEventListener("scroll", onScroll, true);
+      window.removeEventListener("resize", calculatePosition);
     };
-  }, [open, calculatePosition, small]);
+  }, [open, calculatePosition, small, onOpenChange]);
 
   const handleOverlayClick = useCallback(
     (e: React.MouseEvent) => {
@@ -501,27 +547,32 @@ export function PopoverContent(props: PopoverContentProps) {
 
   return (
     <Portal>
-      {/* Overlay */}
-      <div
-        style={{
-          position: "fixed",
-          top: 0,
-          left: 0,
-          right: 0,
-          bottom: 0,
-          backgroundColor: small ? "rgba(0, 0, 0, 0.5)" : "transparent",
-          opacity: small ? (isBottomSheetShown ? 1 : 0) : 1,
-          transition: small ? "opacity 0.3s ease" : undefined,
-          zIndex: overlayZIndex,
-          pointerEvents: "auto",
-        }}
-        onClick={handleOverlayClick}
-        onMouseDown={(e) => e.stopPropagation()}
-      />
+      {/* Modal scrim — ONLY for the bottom-sheet (`small`) mode, which IS modal.
+          The anchored popover is NON-MODAL: no overlay, so the rest of the page
+          stays interactive; outside-dismiss is the click listener above. */}
+      {small && (
+        <div
+          style={{
+            position: "fixed",
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            backgroundColor: "rgba(0, 0, 0, 0.5)",
+            opacity: isBottomSheetShown ? 1 : 0,
+            transition: "opacity 0.3s ease",
+            zIndex: overlayZIndex,
+            pointerEvents: "auto",
+          }}
+          onClick={handleOverlayClick}
+          onMouseDown={(e) => e.stopPropagation()}
+        />
+      )}
       {/* Popover */}
       <div
         ref={popoverRef}
         data-popover="true"
+        data-popover-level={nestingLevel}
         data-testid={testID}
         role="dialog"
         aria-modal={small ? true : undefined}