@lotics/ui 26.0.0 → 26.4.0

package/docs/catalog.md

@@ -830,7 +830,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   grammar); raise `minValueWidth` (default 160) when a cell holds
   MORE than one editor so the table stacks earlier. Two tables on one page share one grid by
   repeating the same labelWidth. Worked example:
-  [`tpl_record`](../examples/tpl_record.tsx).
+  [`tpl_record`](../examples/tpl_record.tsx). A label's FIRST line centres on the control line, not the label block: a wrapped label grows DOWNWARD past the value's first line rather than dragging its own first line above it, so "Registered address" over two lines still starts level with the value it names.
 - **`record_summary`** — `RecordSummary`: the identity band of a record detail/drawer — ONE
   row: `title` xxl semibold tabular, `subtitle` sm muted, `status` Badge slot, optional
   `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS
@@ -854,7 +854,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   seam: **left, the LINK** — `Change` (`onChange`, `secondary`) points the field at a different
   record, named for the intent and deliberately not `danger` since a recoverable correction must
   not wear the colour reserved for destruction; `Clear` (`onClear`, NO fill — the least-reached
-  verb of the four) leaves it empty. **Both are REQUIRED**, so the footer has one shape
+  verb of the four) leaves it empty. The draft's footer follows the same rule: `Cancel` carries
+  no fill beside a filled `Save`, so the only filled button in either mode is the one that acts. **Both are REQUIRED**, so the footer has one shape
   everywhere; a reference the record cannot do without gains nothing from hiding Clear, because
   Change and then declining to pick reaches the same empty state. **Right, the RECORD it points at** — `Edit` (`primary`, the one filled-dark rung,
   handed to `Save` when the draft opens) and `Open` (`secondary`, rightmost, OPTIONAL, the
@@ -879,7 +880,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   derived value that rides along read-only); `multiline` for an address or an account block;
   `type: "date"` swaps the draft's text input for a `DatePicker` and formats the read value —
   the fact's `value` stays the canonical ISO string on both sides, so a date is never edited as
-  free text and the format ambiguity never reaches the record.
+  free text and the format ambiguity never reaches the record; `action` hangs a verb ABOUT the
+  value on it (an `InlineButton` — "look this tax id up"), rendered AT REST only, because an
+  action writes the RECORD while a draft holds values seeded before it ran — fire one mid-draft
+  and Save writes the pre-action values back over what it just fetched.
+  The peek uses the popover's OWN anatomy: `PopoverHeader` for the identity, a scrolling body,
+  and a **pinned `PopoverFooter`** for the verbs. A long block therefore scrolls with its actions
+  still reachable — the earlier hand-rolled footer was a body child and scrolled away, hiding its
+  own Save.
   `Edit` swaps the SAME grid's value cells for inputs — a DRAFT, so nothing commits until `Save`,
   which fires `onSave` with **only the facts that CHANGED** (never a snapshot, so a lock or
   `before_update` sees the real edit). This is what lets a peek hold editors at all: a
@@ -1078,7 +1086,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. Only the
   `small` (bottom-sheet) presentation 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 go in `PopoverHeader` / `PopoverFooter`.
+  title/actions go in `PopoverHeader` / `PopoverFooter`. **A fixed width is the `width` PROP,
+  never `style`**: `style` reaches only the BODY, and the panel is `max-content`, so a width set
+  there governs the scroller while the header and footer sit outside it — the first long title
+  then stretches the panel and leaves the content adrift in a box wider than itself. A popover
+  with no bands never sees this, which is why `width` had to exist before one had both.
+  The built-in scroller is **full-bleed horizontally** and re-insets its content by the same
+  amount, so a scrolling body reaches the panel's real edges — its content slides under the
+  panel edge rather than under an invisible margin 12px inside it — while the text stays on the
+  same column the header and footer use. Nothing to opt into; `disableBodyScroll` consumers
+  (which own their scroll) are untouched.
 - **`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

package/examples/tpl_record.tsx

@@ -738,7 +738,7 @@ function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onUnset, on
             { label: "Contact", value: rec.contact, name: "contact" },
             { label: "City", value: rec.city, name: "city" },
             { label: "Tax ID", value: rec.taxId, name: "taxId" },
-            { label: "Address", value: rec.address, name: "address", multiline: true },
+            { label: "Registered address", value: rec.address, name: "address", multiline: true },
             { label: "Customer since", value: rec.since, name: "since", type: "date" },
           ]}
           accessibilityLabel={`${rec.name} — details`}
@@ -1719,7 +1719,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                         { label: "Tax ID", value: customer.taxId, name: "taxId" },
                         { label: "Contact", value: customer.contact, name: "contact" },
                         { label: "City", value: customer.city, name: "city" },
-                        { label: "Address", value: customer.address, name: "address", multiline: true },
+                        { label: "Registered address", value: customer.address, name: "address", multiline: true },
                         { label: "Customer since", value: customer.since, name: "since", type: "date" },
                       ]}
                       accessibilityLabel={`${customer.name} — details`}

package/package.json

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

package/src/detail_row.tsx

@@ -136,8 +136,17 @@ export function DetailRow(props: DetailRowProps) {
   // so the perceived gap matches a chip row's. Horizontal mode only (stacked
   // mode has no band; it mirrors FormField's order).
   const flatTuck = flat && annotated ? -Math.max(0, Math.round((minHeight - getInputLineHeight(false)) / 2)) : 0;
+  // A label CENTERS in the control line — but only its FIRST line does. Centring
+  // the whole block is identical while the label fits on one line and wrong the
+  // moment it wraps: a two-line label fills the band, so its first line starts at
+  // the band's top while the value's still sits at the control's own text inset,
+  // and the pair reads nine pixels out of step. Pad down by what centring a
+  // single line would have cost, then top-align: one line lands exactly where it
+  // always did, and every extra line grows downward past the value's first line
+  // instead of dragging it upward.
+  const labelLead = Math.max(0, Math.round((minHeight - getInputLineHeight(false)) / 2));
   const labelCell = (cellStyle: StyleProp<ViewStyle>) => (
-    <View style={[styles.labelCell, { minHeight }, cellStyle]}>
+    <View style={[styles.labelCell, { minHeight, paddingTop: labelLead }, cellStyle]}>
       {/* The label WRAPS inside its column — it is NEVER clipped. A field name
           the reader can't finish is worse than a taller row, and a fixed
           `labelWidth` guarantees the clip on every long name ("Registered
@@ -237,7 +246,9 @@ const styles = StyleSheet.create({
   // tall as the band or taller, so it fills it and its FIRST line tops out
   // level with the value's first control line. Do not "fix" this to
   // `flex-start` — that drops every single-line label to the band's top edge.
-  labelCell: { justifyContent: "center" },
+  // Top-aligned, with `labelLead` doing the single-line centring — see the
+  // note at its definition for why centring the BLOCK breaks a wrapped label.
+  labelCell: { justifyContent: "flex-start" },
   // The first line of the value cell — the control centers in it exactly like
   // the label cell does.
   controlLine: { justifyContent: "center" },

package/src/popover.tsx

@@ -51,6 +51,16 @@ function usePopoverContext() {
 }
 
 // Root Popover component
+/**
+ * The panel's own inset. The footer bleeds out by it to span its divider full
+ * width, and the scroll body does the same to reach the panel's real edges —
+ * three places that must agree, so they read it from here rather than each
+ * spelling `12`.
+ */
+const PANEL_INSET = 12;
+const SCROLL_BODY = { marginHorizontal: -PANEL_INSET } as const;
+const SCROLL_BODY_CONTENT = { paddingHorizontal: PANEL_INSET } as const;
+
 export interface PopoverProps {
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -187,6 +197,17 @@ export interface PopoverContentProps {
   contentContainerStyle?: StyleProp<ViewStyle>;
   /** When true, body renders in a plain View instead of ScrollView (use when children manage their own scroll) */
   disableBodyScroll?: boolean;
+  /**
+   * A fixed panel width, in px, covering ALL THREE BANDS.
+   *
+   * `style` reaches only the BODY, so a width set there governs the scroller and
+   * leaves `PopoverHeader`/`PopoverFooter` outside it — and the panel is
+   * `max-content`, so the first long title stretches the panel while the body
+   * stays put, leaving the content adrift in a box wider than itself. A popover
+   * with no bands never sees this, which is why it went unnoticed until one had
+   * both.
+   */
+  width?: number;
   /** When true, renders as bottom sheet on small screens (close button, slide-up animation) */
   small?: boolean;
   /** Accessible name for the bottom-sheet close button. Defaults to the locale's `overlay.close` ("Close" / "Đóng"). */
@@ -207,6 +228,7 @@ export function PopoverContent(props: PopoverContentProps) {
     style,
     contentContainerStyle,
     disableBodyScroll,
+    width,
     small = false,
     closeLabel = locale.overlay.close,
     manageFocus = true,
@@ -602,7 +624,7 @@ export function PopoverContent(props: PopoverContentProps) {
         tabIndex={small ? undefined : -1}
         style={{
           position: "fixed",
-          padding: 12,
+          padding: PANEL_INSET,
           borderTopLeftRadius: 16,
           borderTopRightRadius: 16,
           borderBottomLeftRadius: small ? 0 : 16,
@@ -664,6 +686,8 @@ export function PopoverContent(props: PopoverContentProps) {
               width: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
               maxWidth: Math.max(triggerWidth, MIN_CONTROL_WIDTH),
             }),
+          // Last, so it beats the `max-content` every branch above sets.
+          ...(width != null && !small ? { width, maxWidth: width } : null),
         }}
         onClick={(e) => e.stopPropagation()}
         // React synthetic events bubble through portals via the REACT tree, so a
@@ -692,7 +716,21 @@ export function PopoverContent(props: PopoverContentProps) {
         {disableBodyScroll ? (
           <View style={style}>{bodyChildren}</View>
         ) : (
-          <ScrollView style={style} contentContainerStyle={contentContainerStyle}>
+          // FULL-BLEED HORIZONTALLY, then re-inset by the same 12. The panel
+          // pads all four sides, so a scroller sitting inside that padding
+          // clips its content 12px short of the edge and parks the scrollbar
+          // there too — content slides under an invisible margin instead of
+          // under the panel's own edge. Pulling out and padding back keeps the
+          // text on the exact column the header and footer use while giving the
+          // scroll its real edges. `PopoverFooter` already does this dance for
+          // its divider; the body needed it for the same reason.
+          //
+          // Horizontal only: the vertical padding is the gap to the header and
+          // footer, which is a gap the reader wants.
+          <ScrollView
+            style={[SCROLL_BODY, style]}
+            contentContainerStyle={[SCROLL_BODY_CONTENT, contentContainerStyle]}
+          >
             {bodyChildren}
           </ScrollView>
         )}
@@ -719,9 +757,9 @@ export function PopoverFooter(props: PopoverFooterProps) {
   return (
     // Pull out to the popover's edges (counteract its 12px inset) so the divider
     // spans full width; the action row then re-insets to align with the body.
-    <View style={{ marginHorizontal: -12, marginTop: 12 }}>
+    <View style={{ marginHorizontal: -PANEL_INSET, marginTop: PANEL_INSET }}>
       {showDivider && <Divider />}
-      <View style={{ paddingHorizontal: 12, paddingTop: 12, flexDirection: "row", alignItems: "center", gap: 8, justifyContent }}>
+      <View style={{ paddingHorizontal: PANEL_INSET, paddingTop: PANEL_INSET, flexDirection: "row", alignItems: "center", gap: 8, justifyContent }}>
         {children}
       </View>
     </View>

package/src/reference_field.tsx

@@ -1,13 +1,12 @@
-import { useRef, useState } from "react";
+import { useRef, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { Button } from "./button";
 import { DatePicker } from "./date_picker";
 import { DetailRow, DetailTable } from "./detail_row";
 import { formatDate } from "./format_date";
-import { Divider } from "./divider";
 import { InlineEditView } from "./inline_edit";
 import { InlineStatic } from "./inline_static";
-import { Popover, PopoverContent } from "./popover";
+import { Popover, PopoverContent, PopoverFooter, PopoverHeader } from "./popover";
 import { DialogSectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
 import { TextInputField } from "./text_input_field";
@@ -86,6 +85,17 @@ export interface ReferenceFact {
    * the input.
    */
   type?: "text" | "date";
+  /**
+   * A verb ABOUT this value — an `InlineButton`, per the kit's rule that such a
+   * verb travels with what it acts on. "Look this tax id up in the business
+   * register", "call this number".
+   *
+   * Rendered at REST, never inside the draft, and that is a correctness bound
+   * rather than a layout choice: an action here acts on the RECORD, while a
+   * draft holds values seeded before it ran. Fire one mid-draft and Save would
+   * write the pre-action values straight back over whatever it just fetched.
+   */
+  action?: ReactNode;
 }
 
 export interface ReferenceFieldProps {
@@ -250,16 +260,29 @@ export function ReferenceField(props: ReferenceFieldProps) {
           (`DialogSectionHeadingTitle`, ####) with the code as its description
           rather than a hand-picked font weight; the facts are `DetailRow`s, which
           is what label-beside-value IS everywhere else on this page; and the
-          destructive verb is fenced off by a `Divider` instead of floating after
+          verbs sit in the popover's own pinned footer rather than floating after
           the last fact. Width matches `Peek`'s own content width so every peek in
           an app is the same object.
           `labelWidth` is the one override, and it is not arbitrary: a `DetailTable`
           STACKS its columns below `labelWidth + MIN_CONTROL_WIDTH + 24`, so the
           page's 150 would flip a 320 popover into stacked form grammar. 88 keeps
           the summary side-by-side, which is the whole point of a glance. */}
-      <PopoverContent style={{ width: 320 }} disableBodyScroll>
-        <View style={{ gap: 12 }}>
+      {/* `PopoverContent` PARTITIONS its children: a `PopoverHeader` sits above
+          the scroller, a `PopoverFooter` is pinned below it, and everything else
+          scrolls between them. This component used none of that — it disabled
+          the body scroll and hand-rolled both bands as ordinary children, which
+          is invisible at three facts and fatal at eleven: the panel ran past the
+          viewport with no way to scroll, carrying its own Save button off-screen
+          with it. The three-fact fixture is what hid it. */}
+      {/* `width` on the PANEL, not `style` — `style` reaches only the body, so a
+          long referenced name in the header stretched the panel past it and the
+          facts sat in a box wider than themselves. `maxHeight` stays on the
+          body: that is the band that scrolls. */}
+      <PopoverContent width={320} style={{ maxHeight: 420 }}>
+        <PopoverHeader>
           <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
+        </PopoverHeader>
+        <View style={{ gap: 12 }}>
           {/* ONE geometry for both modes — the table's own 40px band, which is
               `CONTROL_HEIGHT` and exactly what `TextInputField` renders at. The
               read row therefore RESERVES the space its editor will need, and
@@ -305,15 +328,21 @@ export function ReferenceField(props: ReferenceFieldProps) {
                       editors, border and all, and reaching for it means the
                       alignment survives the control geometry changing. Copying
                       the box here instead would drift the first time it does. */}
-                  <InlineStatic
-                    /* A date's canonical value is its ISO string — that is what
-                       the picker reads and what Save sends — so the FORMATTING
-                       happens here, where the type is known. Handing the caller
-                       that job would make `value` mean two things (display in
-                       read, ISO in the draft) and the two would drift. */
-                    value={f.type === "date" ? formatDate(f.value, { locale: localeTag }) : f.value}
-                    multiline={f.multiline}
-                  />
+                  <View style={{ flex: 1, minWidth: 0, flexDirection: "row", alignItems: "center", gap: 6 }}>
+                    <View style={{ flex: 1, minWidth: 0 }}>
+                      <InlineStatic
+                        /* A date's canonical value is its ISO string — that is
+                           what the picker reads and what Save sends — so the
+                           FORMATTING happens here, where the type is known.
+                           Handing the caller that job would make `value` mean
+                           two things (display in read, ISO in the draft) and the
+                           two would drift. */
+                        value={f.type === "date" ? formatDate(f.value, { locale: localeTag }) : f.value}
+                        multiline={f.multiline}
+                      />
+                    </View>
+                    {f.action}
+                  </View>
                 </DetailRow>
               ),
             )}
@@ -339,16 +368,25 @@ export function ReferenceField(props: ReferenceFieldProps) {
               edit-only reference would otherwise draw a rule under the facts and
               fence off an empty band, which is chrome asserting a structure that
               is not there. */}
-          <Divider />
-          {/* THE DRAFT'S FOOTER REPLACES the peek's, it does not join it. Change
-              and Open are moves AWAY from an unsaved draft — one detaches the
-              record being edited, one navigates off it — so offering either here
-              would be offering to lose the typing. Cancel and Save are the only
-              two exits, which is also what the pinned popover promised. */}
+        </View>
+        {/* `PopoverFooter` — PINNED outside the scroller, and it owns the rule,
+            the full-bleed inset and the action-layout alignment this component
+            used to hand-roll. Hand-rolled, the verbs were a body child: they
+            scrolled away with the facts, so a long block hid its own Save.
+
+            THE DRAFT'S FOOTER REPLACES the peek's, it does not join it. Change
+            and Open are moves AWAY from an unsaved draft — one detaches the
+            record being edited, one navigates off it — so offering either here
+            would be offering to lose the typing. Cancel and Save are the only
+            two exits, which is also what the pinned popover promised. */}
+        <PopoverFooter align={editing ? "end" : "space-between"}>
           {editing ? (
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-              <View style={{ flex: 1 }} />
-              <Button title={t.cancel} color="secondary" disabled={saving} onPress={closeDraft} />
+            <>
+              {/* No fill, the same as `Clear` in the resting footer: in a pair of
+                  one quiet exit and one commit, the exit carries no box. Save is
+                  the only filled button in this mode, so nothing competes with
+                  the act that writes. */}
+              <Button title={t.cancel} disabled={saving} onPress={closeDraft} />
               {/* Disabled until something DIFFERS: with nothing to send, a save
                   is a write that fires the record's hooks and bumps its
                   modified stamp to record that nobody changed anything. */}
@@ -358,52 +396,46 @@ export function ReferenceField(props: ReferenceFieldProps) {
                 disabled={!dirty || saving}
                 onPress={() => void save()}
               />
-            </View>
+            </>
           ) : (
-          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-            {/* LEFT PAIR acts on the LINK — which record this points at. Both
-                are unconditional: the peek always offers "point it elsewhere"
-                and "leave it empty", so its footer has ONE shape everywhere
-                instead of four depending on which callbacks a call site
-                remembered. */}
-            <Button
-              title={t.change}
-              color="secondary"
-              accessibilityLabel={`${t.change} — ${name}`}
-              onPress={() => { setPeekOpen(false); onChange(); }}
-            />
-            {/* No fill — Clear is the least-reached verb here, and the one whose
-                result the reader is least likely to want by accident, so it
-                carries the least weight of the four. */}
-            <Button
-              title={t.clear}
-              accessibilityLabel={`${t.clear} — ${name}`}
-              onPress={() => { setPeekOpen(false); onClear(); }}
-            />
-            {/* The spacer is the SEAM between what the two pairs touch: left the
-                link, right the record it points at. Without that split, Open's
-                position is just "pushed over". */}
-            <View style={{ flex: 1 }} />
-            {/* RIGHT PAIR acts on the RECORD the link points at — correct its
-                data, or go to it. Edit takes the ONE filled-dark rung because it
-                is the only verb here that leads to a commit, and it hands that
-                rung straight to Save when the draft opens: one primary per mode,
-                never two. Every other verb stays `secondary` and FILLED — a
-                fill-less Button shows no box, so its ink sits a padding inside
-                its own edge, and one boxless label in a row of boxes reads as
-                indented (the geometry that made `TextButton` exist). */}
-            {editable ? (
-              <Button title={t.edit} color="primary" accessibilityLabel={`${t.edit} — ${name}`} onPress={openDraft} />
-            ) : null}
-            {/* `openLabel` names the DESTINATION ("Open customer"): a page carries
-                four of these peeks, and four buttons announcing a bare "Open"
-                are four controls a screen reader cannot tell apart. */}
-            {onOpen ? (
-              <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
-            ) : null}
-          </View>
+            <>
+              {/* LEFT acts on the LINK — which record this points at. Both are
+                  unconditional: the peek always offers "point it elsewhere" and
+                  "leave it empty", so its footer has ONE shape everywhere. */}
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                <Button
+                  title={t.change}
+                  color="secondary"
+                  accessibilityLabel={`${t.change} — ${name}`}
+                  onPress={() => { setPeekOpen(false); onChange(); }}
+                />
+                {/* No fill — the least-reached verb here, and the one whose
+                    result the reader is least likely to want by accident. */}
+                <Button
+                  title={t.clear}
+                  accessibilityLabel={`${t.clear} — ${name}`}
+                  onPress={() => { setPeekOpen(false); onClear(); }}
+                />
+              </View>
+              {/* RIGHT acts on the RECORD the link points at. Edit takes the ONE
+                  filled-dark rung because it is the only verb here that leads to
+                  a commit, and it hands that rung straight to Save when the
+                  draft opens: one primary per mode, never two. */}
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                {editable ? (
+                  <Button title={t.edit} color="primary" accessibilityLabel={`${t.edit} — ${name}`} onPress={openDraft} />
+                ) : null}
+                {/* `openLabel` names the DESTINATION ("Open customer"): a page
+                    carries four of these peeks, and four buttons announcing a
+                    bare "Open" are four controls a screen reader cannot tell
+                    apart. */}
+                {onOpen ? (
+                  <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
+                ) : null}
+              </View>
+            </>
           )}
-        </View>
+        </PopoverFooter>
       </PopoverContent>
     </Popover>
   );