@lotics/ui 26.0.0 → 26.1.0

package/docs/catalog.md

@@ -879,7 +879,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

package/package.json

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

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,25 @@ 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. */}
+      <PopoverContent style={{ width: 320, 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 +324,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,15 +364,20 @@ 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} />
               {/* Disabled until something DIFFERS: with nothing to send, a save
                   is a write that fires the record's hooks and bumps its
@@ -358,52 +388,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>
   );