@lotics/ui 26.1.0 → 26.4.1

package/docs/catalog.md

@@ -649,7 +649,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`use_form`** — `useForm`: THE batch draft-form state hook — `values` = `initialValues` +
   an edits overlay (a revalidation refreshes untouched fields, no sync effect), `validate`
   (sync/async, gates submit, editing clears the field's error), `onSubmit(values, helpers)`
-  with a re-entry-guarded `submitting`, and `changes`/`changed` — the touched-fields diff
+  with a re-entry-guarded `submitting` — an error `onSubmit` reports itself via
+  `setFieldError` (a rejected write, say) SURVIVES, because each attempt clears the previous
+  attempt's errors on the way IN, not on the way out — and `changes`/`changed` — the touched-fields diff
   that feeds DIFF-writes (send only edited fields); `setFieldValue` (curried or direct) +
   `setValues`/`setFieldError`/`reset`. Pairs with the Form\* family for dialog/settings
   forms — the draft-validate-COMMIT-together twin of the self-persisting Inline\* editors.
@@ -830,7 +832,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 +856,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
@@ -1085,7 +1088,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.1.0",
+  "version": "26.4.1",
   "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

@@ -274,7 +274,11 @@ export function ReferenceField(props: ReferenceFieldProps) {
           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 }}>
+      {/* `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>
@@ -378,7 +382,11 @@ export function ReferenceField(props: ReferenceFieldProps) {
         <PopoverFooter align={editing ? "end" : "space-between"}>
           {editing ? (
             <>
-              <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. */}

package/src/use_form.ts

@@ -116,9 +116,14 @@ function reducer<T>(prevState: FormState<T>, action: Action<T>): FormState<T> {
       if (prevState.submitting === action.submitting) return prevState;
       return { ...prevState, submitting: action.submitting };
     case "SUBMIT":
+      // Deliberately does NOT clear errors. This fires after `onSubmit` returns,
+      // and a handler that caught a server rejection and called `setFieldError`
+      // returns normally — so wiping here erased the only report of the failure
+      // and the press looked like it did nothing. Nothing needs the wipe:
+      // editing a field clears that field's error, and a `validate` pass
+      // replaces the whole set.
       return {
         ...prevState,
-        errors: {},
         submitting: false,
         submitCount: prevState.submitCount + 1,
       };
@@ -228,14 +233,14 @@ export function useForm<T>(props: UseFormProps<T>): FormHandler<T> {
     if (!onSubmit) return;
     if (submittingRef.current) return;
 
-    if (validate !== undefined) {
-      const nextErrors = await validate(values);
-
-      if (nextErrors && Object.keys(nextErrors).length) {
-        setErrors(nextErrors);
-        return;
-      }
-    }
+    // The previous attempt's errors are cleared HERE, before this one runs —
+    // not after `onSubmit` returns. Clearing afterwards erased the very error a
+    // handler had just set from a rejected write, so the press looked like it
+    // did nothing; never clearing left that error on screen after a later
+    // attempt succeeded. Clearing up front does both jobs.
+    const nextErrors = validate ? ((await validate(values)) ?? {}) : {};
+    setErrors(nextErrors);
+    if (Object.keys(nextErrors).length) return;
 
     submittingRef.current = true;
     dispatch({ type: "SET_SUBMITTING", submitting: true });