@lotics/ui 11.3.0 → 11.4.0

package/AGENTS.md

@@ -1076,7 +1076,7 @@ check_circle (CheckCircle — the completion ring: an empty ring that springs to
 floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Example: `tpl_task_board`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · 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 to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover (Popover + PopoverTrigger + PopoverContent — **PopoverContent already insets its body 12px; put content directly in it, NEVER add your own padding View (that double-pads). Title/actions via PopoverHeader / PopoverFooter**) · popover_nav (usePopoverNav + PopoverScreen + PopoverNavHeader — the popover's built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes, `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the root and screens render conditionally (unmounted when inactive — no scroll preservation), `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack` (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover (an avatar/settings menu drilling into a sub-panel); route PATTERNS, `params`, and stacked-alive screens are `screen_router`'s job. Distinct from `Popover`'s plain `PopoverHeader` children container) · tooltip ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · 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 to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · screen_router (ScreenRouter + Screen + useScreenRouter — the SCREENS compound: a flat navigation stack (`navigate("/case/:id")` pushes, `goBack` pops, `canGoBack`, route `params`; stacked screens stay mounted `display:none` so scroll survives the round trip). Dialog BAKES a router in (`<Dialog><Screen route="">…`); ANY other container hosts the standalone `<ScreenRouter>` — and it wraps AROUND the container so the CHROME can read the stack: a Drawer drilling into a LINKED record swaps its header to a BACK IconButton + the pushed record's id while `canGoBack` (sequence ◀ ▶ hides — stepping the root from inside a linked record disorients), and the pushed `<Screen route="/case/:id">` is a REAL editable workspace with its own footer CTAs. Key the router by record id so stepping ◀ ▶ resets the stack. Worked example: `tpl_item_list` drawer) · popover (Popover + PopoverTrigger + PopoverContent — **NON-MODAL: the anchored popover has NO blocking overlay, so the rest of the page stays interactive; clicking another control both dismisses this popover AND activates that control in one click; clicking outside, scrolling an ancestor, or Escape dismisses. Only `small` (bottom sheet) is modal (scrim). PopoverContent already insets its body 12px; put content directly in it, NEVER add your own padding View (that double-pads). Title/actions via PopoverHeader / PopoverFooter**) · popover_nav (usePopoverNav + PopoverScreen + PopoverNavHeader — the popover's built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes, `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the root and screens render conditionally (unmounted when inactive — no scroll preservation), `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack` (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover (an avatar/settings menu drilling into a sub-panel); route PATTERNS, `params`, and stacked-alive screens are `screen_router`'s job. Distinct from `Popover`'s plain `PopoverHeader` children container) · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · summary_line (SummaryLine — the light inline summary of a register/list's FILTERED view, sits below the toolbar; NOT the boxed dashboard `kpi_strip` band) · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "11.3.0",
+  "version": "11.4.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

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}