@lotics/ui 44.7.1 → 44.9.0

package/src/date_range_filter_field.tsx

@@ -2,7 +2,7 @@ import React, { useMemo, useState } from "react";
 import { View } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { CONTROL_HEIGHT, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { Icon } from "./icon";
 import { Button } from "./button";
 import { FocusRingPressable } from "./focus_ring_pressable";
@@ -129,7 +129,14 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
             flexDirection: "row",
             alignItems: "center",
             gap: 8,
-            paddingVertical: 9,
+            // The height comes from the shared constant, never from padding
+            // tuned against a particular leading. This was `paddingVertical: 9`,
+            // which was exactly 40 against the OLD `sm` 14/20 — then 43.5.0 made
+            // running text 14/24 and the same padding silently became 44, one
+            // control standing 4px proud of every sibling in its band. A ramp is
+            // allowed to move; a control's height is not derived from it.
+            height: CONTROL_HEIGHT,
+            justifyContent: "center",
             paddingHorizontal: 12,
             borderWidth: 1,
             // `colors.border` like every other control — this rested a step

package/src/date_stamp.tsx

@@ -15,6 +15,12 @@ export interface DateStampProps {
   onChange?: (iso: string) => void;
   /** Locale tag for the rendered date. Defaults to the kit's locale. */
   locale?: string;
+  /** Drop the year (`08/09` rather than `08/09/2026`). The stamp sits in
+   *  columns beside dates a caller formats itself, and a year on one side of a
+   *  row and not the other is the kind of mismatch nobody reports and everyone
+   *  notices. Same option `formatDate` takes — the format itself stays there,
+   *  so there is one place that decides what a date looks like. */
+  compact?: boolean;
   accessibilityLabel: string;
 }
 
@@ -44,7 +50,7 @@ export interface DateStampProps {
  * value therefore renders nothing at all.
  */
 export function DateStamp(props: DateStampProps) {
-  const { value, onChange, locale, accessibilityLabel } = props;
+  const { value, onChange, locale, compact = false, accessibilityLabel } = props;
   const localeTag = useLocaleTag();
   const tag = locale ?? localeTag;
   const [hovered, setHovered] = useState(false);
@@ -55,7 +61,7 @@ export function DateStamp(props: DateStampProps) {
   // replaced. This is what the close path reads instead.
   const picked = useRef<string | null>(value);
 
-  const shown = value ? formatDate(value, { locale: tag }) : "";
+  const shown = value ? formatDate(value, { locale: tag, compact }) : "";
 
   // Read-only, or nothing to show and no way to add one: render the text alone
   // so a caller can drop this into a column without a conditional.

package/src/detail_row.tsx

@@ -1,6 +1,6 @@
 import { createContext, ReactNode, useContext, useState } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
-import { MIN_CONTROL_WIDTH } from "./control_surface";
+import { MIN_VALUE_WIDTH } from "./control_surface";
 import { SPACE } from "./spacing";
 import { FieldAnnotationProps, FieldAnnotations, hasFieldAnnotation } from "./field_annotations";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
@@ -32,9 +32,9 @@ export interface DetailTableProps {
    *  and custom rows all sit on the inline-control baseline grid. */
   minHeight?: number;
   /** The usable width the value cell must keep before the table STACKS
-   *  (default 160). Raise it when a cell holds MORE than one editor (an
-   *  amount + method pair) — side-by-side columns that technically fit can
-   *  still crush a multi-editor cell. */
+   *  (default {@link MIN_VALUE_WIDTH}). Raise it when a cell holds MORE than one
+   *  editor (an amount + method pair) — side-by-side columns that technically
+   *  fit can still crush a multi-editor cell. */
   minValueWidth?: number;
   /** `DetailRow`s (each inherits the table's columns; row props override). */
   children: ReactNode;
@@ -68,7 +68,7 @@ export interface DetailTableProps {
  * above a full-width value. No prop — the switch is automatic.
  */
 export function DetailTable(props: DetailTableProps) {
-  const { labelWidth = DETAIL_LABEL_WIDTH, minHeight = INLINE_CONTROL_HEIGHT, minValueWidth = MIN_CONTROL_WIDTH, children, style } = props;
+  const { labelWidth = DETAIL_LABEL_WIDTH, minHeight = INLINE_CONTROL_HEIGHT, minValueWidth = MIN_VALUE_WIDTH, children, style } = props;
   const [width, setWidth] = useState<number | null>(null);
   const stacked = width != null && width < labelWidth + minValueWidth + 24;
   return (
@@ -100,12 +100,17 @@ export interface DetailRowProps extends FieldAnnotationProps {
   labelSize?: "xs" | "sm";
   /** Min row height. Default 28 (or the `DetailTable`'s `minHeight`). */
   minHeight?: number;
-  /** The value renders as FLAT text (an `InlineStatic`, a plain `Text`) rather
-   *  than a control-height chip. Annotations then tuck up by the control
-   *  band's slack, so the perceived gap under the TEXT equals the gap under a
-   *  chip — without it, the band's invisible bottom half reads as a hole
-   *  between a static value and its description. Row height and label
-   *  centering are unchanged. */
+  /** The value is a RAW node — a plain `Text`, a figure, a pair — sitting off the
+   *  inline-control grid. NOT `InlineStatic` or `InlineSlot`: those compose the
+   *  grid's own box, so their words already start at the control text inset and
+   *  centre in the band, and `flat` there re-introduces both offsets it exists
+   *  to remove. Annotations then align to the value on BOTH axes,
+   *  because a control's box is what they were offset from and there is no box:
+   *  they tuck up by the control band's slack, so the perceived gap under the
+   *  TEXT equals the gap under a chip rather than leaving the band's invisible
+   *  bottom half reading as a hole; and they drop the control's text inset, so
+   *  the description starts on the value's own left edge instead of nine pixels
+   *  inside it. Row height and label centering are unchanged. */
   flat?: boolean;
 }
 
@@ -160,7 +165,7 @@ export function DetailRow(props: DetailRowProps) {
   // text inset, defined once in `field_annotations` and rendered identically by
   // a checklist row's field. A record's field and a checklist's are the same
   // thing on two surfaces; they may not say a fault two different ways.
-  const annotations = <FieldAnnotations description={description} warning={warning} error={error} />;
+  const annotations = <FieldAnnotations description={description} warning={warning} error={error} flat={flat} />;
   if (table?.stacked) {
     // Stacked mode wears the FORM grammar: the label renders exactly like a
     // `FormField` label (medium, default ink), so a narrow record surface

package/src/empty_state.tsx

@@ -42,11 +42,11 @@ export function EmptyState(props: EmptyStateProps) {
           <Icon name={props.icon} size={28} color={colors.zinc[400]} />
         </View>
       ) : null}
-      <Text size="sm" color="muted">
+      <Text size="sm" color="muted" style={styles.line}>
         {props.message}
       </Text>
       {props.hint ? (
-        <Text size="xs" color="muted">
+        <Text size="xs" color="muted" style={styles.line}>
           {props.hint}
         </Text>
       ) : null}
@@ -63,4 +63,11 @@ const styles = StyleSheet.create({
   icon: {
     marginBottom: 4,
   },
+  // The container centres the BOX; without this the text inside it still sets
+  // left. Invisible while every line is short enough not to wrap — which is
+  // exactly the case a narrow container breaks, leaving a wrapped message
+  // reading left-aligned beside a one-line hint reading centred.
+  line: {
+    textAlign: "center",
+  },
 });

package/src/error_state.tsx

@@ -41,11 +41,11 @@ export function ErrorState(props: ErrorStateProps) {
       <View style={styles.icon}>
         <Icon name="triangle-alert" size={28} color={solid("red")} />
       </View>
-      <Text size="sm" color="muted">
+      <Text size="sm" color="muted" style={styles.line}>
         {props.message}
       </Text>
       {props.detail ? (
-        <Text size="xs" color="muted">
+        <Text size="xs" color="muted" style={styles.line}>
           {props.detail}
         </Text>
       ) : null}
@@ -66,6 +66,13 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 4,
   },
+  // Centred like `EmptyState`'s, and for the same reason: the container centres
+  // the BOX, not the text inside it. These two swap into one another as a read
+  // settles, so a difference here would show up as the copy jumping alignment at
+  // the moment a region fails.
+  line: {
+    textAlign: "center",
+  },
   icon: {
     marginBottom: 4,
   },

package/src/field_annotations.tsx

@@ -45,10 +45,31 @@ export function hasFieldAnnotation(props: FieldAnnotationProps): boolean {
  * they answer different questions ("this is broken" / "this will cost you" / "this is what the
  * field is for"), and hiding the rule that explains the failure is exactly the wrong economy.
  */
-export function FieldAnnotations(props: FieldAnnotationProps) {
+export interface FieldAnnotationsProps extends FieldAnnotationProps {
+  /**
+   * The value above is FLAT text, not a painted control — so drop the control's
+   * text inset and sit on the value's own left edge.
+   *
+   * The inset exists to clear a control's border and padding, which is what puts
+   * an annotation under the value's WORDS instead of under the editor's
+   * invisible box. Under plain text there is no border and no padding to clear,
+   * so the same number becomes pure indent: label, value and description end up
+   * on THREE left edges where the screen only has two things to say. Nine pixels
+   * is small enough to read as sloppiness rather than as structure, and it
+   * appears only on the rows whose value happens not to be a control, so a
+   * column of fields drifts in and out of alignment down its own length.
+   *
+   * Hosts already know which kind of value they hold: `DetailRow` passes its
+   * `flat`, the same flag that tucks the block up by the control band's slack.
+   * One fact about the value, both corrections.
+   */
+  flat?: boolean;
+}
+
+export function FieldAnnotations(props: FieldAnnotationsProps) {
   if (!hasFieldAnnotation(props)) return null;
   return (
-    <View style={styles.stack}>
+    <View style={[styles.stack, props.flat === true && styles.stackFlat]}>
       {props.error != null ? (
         <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite">
           {props.error}
@@ -73,4 +94,6 @@ const styles = StyleSheet.create({
   // with the editor's invisible box — and the 2px that separates the lines from each other,
   // which is the same rhythm the host puts between the control and this block.
   stack: { gap: 2, paddingLeft: CONTROL_TEXT_INSET },
+  // ...and nothing to clear when the value is flat text — see `flat`.
+  stackFlat: { paddingLeft: 0 },
 });

package/src/finding.tsx

@@ -45,8 +45,8 @@ export interface FindingProps {
   /** What was found, in one line, in the reader's own nouns. */
   title: string;
   /**
-   * The readings that disagree, in source order. Rendered inline beneath the
-   * title as `source value · source value`.
+   * The readings that disagree, in source order. Rendered ONE PER LINE beneath
+   * the title, each as `source value` — never joined by a separator.
    *
    * NEITHER is marked as the wrong one. A finding reports that two sources
    * disagree; which one is right is the reader's call, and a struck-through or
@@ -77,8 +77,15 @@ export interface FindingProps {
 }
 
 /**
- * ONE RANKED INSIGHT from an AI check — a cross-check discrepancy, an audit
- * observation, a briefing item.
+ * ONE RANKED DISCREPANCY from a cross-check — a contradiction between two
+ * readings, an audit observation, a briefing item.
+ *
+ * WHOEVER performed the check. Nothing here is AI-specific — the labels are
+ * four severity words and "difference" — but this opened "from an AI check",
+ * and a rules-derived contradiction (two papers disagreeing, a carrier moving
+ * an ETA) reads as out of scope on that wording. It is not: the next author who
+ * believes it hand-rolls a Callout and loses the ranking, the delta and the
+ * readings line.
  *
  * The readings sit at `sm`, the same size as the title. They were `xs` — a
  * miniature that said "secondary" by being hard to read, which is the wrong
@@ -134,11 +141,6 @@ export function Finding(props: FindingProps) {
           <View style={styles.readings}>
             {readings.map((reading, index) => (
               <View key={`${reading.source}-${index}`} style={styles.reading}>
-                {index > 0 ? (
-                  <Text size="sm" color="muted">
-                    ·
-                  </Text>
-                ) : null}
                 <SourceName label={reading.source} onOpen={props.onOpenSource} />
                 <Text size="sm" weight="medium" tabular numberOfLines={1}>
                   {reading.value}
@@ -189,6 +191,13 @@ const styles = StyleSheet.create({
   // instance — the dot marks the left edge and the figure the right, so a
   // reader scanning a stack gets rank and magnitude in one pass.
   delta: { flexShrink: 0 },
-  readings: { flexDirection: "row", flexWrap: "wrap", alignItems: "baseline", gap: 6 },
+  // ONE READING PER LINE. They were joined inline by a ` · `, which fails twice:
+  // a middot claims a relation while refusing to name it (the templated-metadata
+  // tell `docs/reviewing.md` bans outright), and it is the one mark a screen
+  // reader drops — so the separator carrying "these two disagree" never survived
+  // being read aloud, the same defect `CommentsButton` was fixed for. It also
+  // wrapped: at phone width a line could BEGIN with the separator. Stacking pairs
+  // each source with its own value at every width and needs no separator at all.
+  readings: { flexDirection: "column", alignItems: "flex-start", gap: 4 },
   reading: { flexDirection: "row", alignItems: "baseline", gap: 5, minWidth: 0 },
 });

package/src/format_money.ts

@@ -5,6 +5,12 @@ export interface FormatMoneyOptions {
    * "486 tr ₫". For stat strips/cards where the full figure lives in the
    * table below — never for the table itself. */
   compact?: boolean;
+  /** Significant digits below the currency's minor unit. `Intl`'s currency
+   *  style floors at that unit — 2 for USD — so a genuine per-unit price like
+   *  an LCL rate of 0,019 US$/kg renders as `0,02`: a 5% error, printed as
+   *  fact, with nothing on screen saying it was rounded. Set this on a UNIT
+   *  price; leave it off for a total, where two decimals is the contract. */
+  maxFractionDigits?: number;
 }
 
 /**
@@ -29,10 +35,18 @@ export function formatCompactNumber(value: number, locale = "vi-VN"): string {
  * or the ₫ suffix.
  */
 export function formatMoney(value: number, options: FormatMoneyOptions = {}): string {
-  const { locale = "vi-VN", currency = "VND", compact = false } = options;
+  const { locale = "vi-VN", currency = "VND", compact = false, maxFractionDigits } = options;
   if (compact && Math.abs(value) >= 1_000_000) {
     const suffixed = formatCompactNumber(value, locale);
     return currency === "VND" ? `${suffixed} ₫` : `${suffixed} ${currency}`;
   }
-  return value.toLocaleString(locale, { style: "currency", currency });
+  return value.toLocaleString(locale, {
+    style: "currency",
+    currency,
+    // Raising the MAXIMUM alone is enough, and is what keeps a total looking
+    // like money: Intl holds its own minimum (2 for USD, 0 for VND), so 0,019
+    // gains its digits while 2750 still renders 2.750,00. Unset, both stay at
+    // the currency's own contract.
+    ...(maxFractionDigits != null ? { maximumFractionDigits: maxFractionDigits } : {}),
+  });
 }

package/src/inline_edit.tsx

@@ -259,6 +259,7 @@ function fieldSurface(o: { variant: InlineEditVariant; disabled?: boolean; activ
   return (hovered: boolean): StyleProp<ViewStyle>[] => [
     styles.view,
     (o.variant === "bare" || o.disabled) && styles.viewBare,
+    o.disabled === true && styles.viewInert,
     // Keyed on the VARIANT alone, never on `disabled` — a disabled `framed`
     // field shares the line above (it must not promise a press) but stays in its
     // column with the enabled fields beside it. Bleeding that one would pull a
@@ -396,9 +397,9 @@ interface InlineEditViewProps {
 /**
  * The view-mode box of an inline-editable field: the value as plain text on the
  * shared control surface — white with a 1px border when `framed`, frameless
- * until hover when `bare`. It hovers via its BORDER, never a grey wash, and the
- * cursor stays the default arrow: the surface itself is the affordance, and a
- * pointer would read as a button. The border is present at every state (merely
+ * until hover when `bare`. It hovers via its BORDER, never a grey wash, and it
+ * takes the pointer cursor every other control takes. The border is present at
+ * every state (merely
  * transparent when `bare` rests), so swapping to an input, or floating a
  * dropdown above it, never shifts the layout. Used by `InlineEditFrame`, and as
  * the overlay trigger for the select/date inline editors (it forwards ref +
@@ -459,7 +460,7 @@ export function InlineEditView(props: InlineEditViewProps) {
           onFocus={onFocus}
           accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
-          style={[styles.viewInner, multilineBox(numberOfLines)]}
+          style={[styles.viewInner, disabled === true && styles.viewInert, multilineBox(numberOfLines)]}
         >
           {content}
         </Pressable>
@@ -678,14 +679,33 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
     gap: 6,
-    // An inline editor is an INPUT, not a button — keep the default arrow
-    // cursor (the chip + hover-border carry the affordance; a pointer reads
-    // as a button press). Overrides the Pressable's pointer default.
-    cursor: "auto",
+    // THE POINTER, like every other control in the kit.
+    //
+    // This box used to force the arrow back, on the reasoning that an inline
+    // editor is an input rather than a button and the chip plus hover-border
+    // already carried the affordance. Both halves fail. `bare` HAS no chip —
+    // nothing at rest by design — so the whole affordance was a 1px edge that
+    // appears on hover, which is invisible to touch and to anyone who never
+    // happens to sweep the value; a member's actual question was "how am I
+    // supposed to edit this?". And the arrow does not read as "input", it
+    // reads as INERT: it is what the page's own prose gets, so the one thing
+    // on the row that is theirs to change looked like the one thing that
+    // wasn't.
+    //
+    // The I-beam is not the alternative. It promises a caret and a selection,
+    // and `userSelect: "none"` below deliberately denies both so a drag edits
+    // instead of selecting — a false promise in the same family as the arrow.
+    // What is true of every variant is that pressing DOES something, which is
+    // exactly what the pointer says.
+    cursor: "pointer",
   },
   // Nothing at rest — the frame arrives on hover. Also how a DISABLED field
   // rests, whatever its variant: an inert value must not promise a press.
   viewBare: { backgroundColor: "transparent", borderColor: "transparent" },
+  // ...and the cursor is half of that promise, so it goes back to the arrow
+  // for a disabled field only. `viewBare` cannot carry it: a `bare` field is
+  // enabled and wears the same style.
+  viewInert: { cursor: "auto" },
   // A bare field at rest looks like TEXT, so it aligns like text: its glyphs sit
   // on the column, not its invisible box. The frame's 8px inset is real padding
   // the eye cannot see at rest, and it put every bare value 8px right of the
@@ -716,7 +736,7 @@ const styles = StyleSheet.create({
   // The value region inside a verb-hosting resting field: carries the row layout
   // the surface would otherwise own. `userSelect` here rather than via the
   // `FocusRingPressable` prop — a drag across a value must edit, not select text.
-  viewInner: { flex: 1, minWidth: 0, alignSelf: "stretch", flexDirection: "row", alignItems: "center", gap: 6, ...({ userSelect: "none", cursor: "auto" } as ViewStyle) },
+  viewInner: { flex: 1, minWidth: 0, alignSelf: "stretch", flexDirection: "row", alignItems: "center", gap: 6, ...({ userSelect: "none" } as ViewStyle) },
   // Open (popover showing): the resting surface plus the 2px active ring — the
   // one thing that separates open from at-rest, and identical to a focused input.
   viewActive: {

package/src/inline_select.tsx

@@ -26,6 +26,11 @@ interface InlineSelectBaseProps<T extends string, D = unknown> {
   /** Custom option content in the dropdown (icon + label, two-line, a badge…).
    *  Omit for a plain label list — both render through the same `OptionList`. */
   renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
+  /** A second line under an option's label in the dropdown — a driver's phone
+   *  under their name, a code under a description. `OptionList` has always
+   *  rendered this two-line `MenuListItem`; this only forwards it, which is why
+   *  callers were hand-rebuilding the anatomy through `renderOptionContent`. */
+  getOptionDescription?: (option: PickerOption<T, D>) => string | undefined;
   /** Render ONE selected option as its resting chip — single: the value; multi:
    *  each tag. Falls back to `renderOptionContent`, then the plain label (single) /
    *  a zinc `Badge` (multi). The one seam for "how the selection looks". */
@@ -135,7 +140,7 @@ function InlineSelectShell(props: {
 }
 
 export function InlineSelect<T extends string, D = unknown>(props: InlineSelectProps<T, D>) {
-  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, customOptionPlacement, variant, actions, autoFocus = false } = props;
+  const { options, renderOptionContent, getOptionDescription, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, customOptionPlacement, variant, actions, autoFocus = false } = props;
   const labels = useLoticsLocale().inline;
   const [open, setOpen] = useState(autoFocus);
   const [saving, setSaving] = useState(false);
@@ -191,6 +196,7 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
       >
         <OptionList<T, true, D>
           multi
+          getOptionDescription={getOptionDescription}
           search={{ mode: searchMode }}
           options={options}
           value={draft}
@@ -237,6 +243,7 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
       error={error}
     >
       <OptionList<T, false, D>
+        getOptionDescription={getOptionDescription}
         search={{ mode: searchMode }}
         options={options}
         value={value}

package/src/inline_text_input.tsx

@@ -184,19 +184,18 @@ export function InlineTextInput(props: InlineTextInputProps) {
         // Everything the resting VIEW used to draw, the input now draws, because
         // there is no resting view left to draw it. Both of these were its job:
         //
-        // `bare` — the transparent resting edge. Hover and the focus ring are
-        // applied after `style` inside `TextInputField`, so it still darkens on
-        // hover and still rings on focus, from the element that now owns it.
+        // `variant` — the resting frame, or none. It goes over as the PROP, not
+        // as a `style` override: the two are not equivalent, because `style` is
+        // applied after the hover rule and so erased the hover edge that is a
+        // bare field's only affordance. The field owns its own variants.
         //
         // `struck` — a completed item's value, line-through and muted. This was
         // applied in `fieldContent`, which only ever runs in the resting view, so
         // moving to one element silently dropped it: a done task on the board kept
         // its title upright. Anything else the view used to render has to move the
         // same way, or it goes the same way — quietly.
-        style={[
-          variant === "bare" ? { borderColor: "transparent", backgroundColor: "transparent" } : null,
-          struck ? { textDecorationLine: "line-through" as const, color: colors.zinc[500] } : null,
-        ]}
+        variant={variant}
+        style={struck ? { textDecorationLine: "line-through" as const, color: colors.zinc[500] } : null}
         // With verbs on the field, the FRAME owns the surface and the ring.
         seamless={actions != null}
       />

package/src/ledger.tsx

@@ -44,8 +44,11 @@ function useLedger(): LedgerContextValue {
 }
 
 /** Signed display: negatives render as "− <abs>" (a receipt against charges).
- *  `n + 0` normalizes -0 (a zero receipts sum passed negated) to plain 0. */
-function signed(format: (n: number) => string, n: number) {
+ *  `n + 0` normalizes -0 (a zero receipts sum passed negated) to plain 0.
+ *  Exported for `RunningLedger`, which shares this exact glyph rule for every
+ *  money/quantity figure it renders — one definition, so the two components'
+ *  output can never drift into two different negative-number conventions. */
+export function signed(format: (n: number) => string, n: number) {
   return n < 0 ? `− ${format(-n)}` : format(n + 0);
 }
 

package/src/locale.tsx

@@ -74,11 +74,23 @@ export interface LoticsLocale {
   clarify: { otherPlaceholder: string; back: string; next: string; cancel: string; submit: string };
   /** `Ledger`: the screen-reader name of a peekable row. */
   ledger: { rowDetails: (label: string) => string };
-  /** `SectionHeadingTitle`: the info-popover trigger's screen-reader name. */
+  /** `RunningLedger`: the closing line's label ("Số dư hiện tại", "Tồn kho
+   *  hiện tại") — the ledger's one derived, always-current figure. */
+  runningLedger: { currentBalance: string };
   /** `Step`/`ChecklistItem`'s toggleable MARKER, when the caller names no
    *  label of its own. A pipeline stage always passes its title, so this is the
    *  bare-`Step` fallback. */
   stepper: { complete: string; progress: string };
+  /** `StepProgress`: the built-in caption over NAMED stages, and the
+   *  screen-reader position when there is no caption to borrow. The counts are
+   *  interpolated by the pack rather than concatenated at the call site, because
+   *  where the number sits in the sentence is a property of the language. */
+  stepProgress: {
+    complete: (total: number) => string;
+    stage: (name: string, index: number, total: number) => string;
+    none: (total: number) => string;
+    position: (index: number, total: number) => string;
+  };
   /** `ChecklistGroup`'s disclosure — the small pressable text that shows or hides
    *  a phase's rows. The kit owns the wording so one app does not say "Show" while
    *  the next says "Expand" for the same gesture. */
@@ -89,6 +101,8 @@ export interface LoticsLocale {
    *  because word order is not shared: English puts the verb first, and a
    *  language that does not would otherwise be stuck with a prefix. */
   textDisclosure: { show: (label: string) => string; hide: (label: string) => string };
+  /** The info-popover trigger's screen-reader name on a heading — every level of
+   *  `SectionHeading*`, and `CardHeaderTitle`, which names the same altitude. */
   sectionHeading: { info: string };
   /** `ErrorState`'s retry button. The kit owns the wording so "try again" is
    *  phrased identically everywhere instead of hand-written per app. */
@@ -196,6 +210,10 @@ export interface LoticsLocale {
    *  a SOURCE with different words. */
   fileRow: { open: (name: string) => string };
   sources: { open: (label: string) => string; heading: string };
+  /** `RelatedRecordRow`: the accessible name for its press target, when the
+   *  caller has not overridden it — "<kind> <code>", e.g. "Kế hoạch sản xuất
+   *  KH-2026-0001". */
+  relatedRecordRow: { open: (kind: string, code: string) => string };
   /** `Counter`: the two steppers, named for the value they move. */
   counter: { decrease: (label: string) => string; increase: (label: string) => string };
   /** `AllocationRow`: the a11y name of the amount input (naming its destination),
@@ -292,7 +310,14 @@ export const en: LoticsLocale = {
   inline: { saveError: "Couldn't save. Try again.", save: "Save", cancel: "Cancel" },
   clarify: { otherPlaceholder: "Or type your own answer…", back: "Back", next: "Next", cancel: "Cancel", submit: "Submit" },
   ledger: { rowDetails: (label) => `${label} details` },
+  runningLedger: { currentBalance: "Current balance" },
   stepper: { complete: "Complete step", progress: "Progress" },
+  stepProgress: {
+    complete: (total) => `Complete (${total}/${total})`,
+    stage: (name, index, total) => `${name} (${index}/${total})`,
+    none: (total) => `0/${total}`,
+    position: (index, total) => `${index} of ${total}`,
+  },
   checklist: { expand: "Show", collapse: "Hide" },
   textDisclosure: { show: (label) => `Show ${label}`, hide: (label) => `Hide ${label}` },
   sectionHeading: { info: "About this data" },
@@ -392,6 +417,7 @@ export const en: LoticsLocale = {
   infoPopover: { more: "More information", about: (label) => `About ${label}` },
   fileRow: { open: (name) => `Open ${name}` },
   sources: { open: (label) => `Open ${label}`, heading: "Sources" },
+  relatedRecordRow: { open: (kind, code) => `Open ${kind} ${code}` },
   counter: { decrease: (label) => `Decrease ${label}`, increase: (label) => `Increase ${label}` },
   allocationRow: {
     allocateTo: (label) => `Allocate to ${label}`,
@@ -471,7 +497,14 @@ export const vi: LoticsLocale = {
   inline: { saveError: "Không lưu được. Thử lại.", save: "Lưu", cancel: "Hủy" },
   clarify: { otherPlaceholder: "Hoặc nhập câu trả lời khác…", back: "Quay lại", next: "Tiếp", cancel: "Hủy", submit: "Gửi" },
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
+  runningLedger: { currentBalance: "Số dư hiện tại" },
   stepper: { complete: "Hoàn thành bước", progress: "Tiến trình" },
+  stepProgress: {
+    complete: (total) => `Hoàn tất (${total}/${total})`,
+    stage: (name, index, total) => `${name} (${index}/${total})`,
+    none: (total) => `0/${total}`,
+    position: (index, total) => `${index} trên ${total}`,
+  },
   checklist: { expand: "Mở", collapse: "Thu gọn" },
   textDisclosure: { show: (label) => `Xem ${label}`, hide: (label) => `Ẩn ${label}` },
   sectionHeading: { info: "Giải thích dữ liệu" },
@@ -571,6 +604,7 @@ export const vi: LoticsLocale = {
   infoPopover: { more: "Thông tin thêm", about: (label) => `Thông tin về ${label}` },
   fileRow: { open: (name) => `Mở ${name}` },
   sources: { open: (label) => `Mở ${label}`, heading: "Nguồn" },
+  relatedRecordRow: { open: (kind, code) => `Mở ${kind} ${code}` },
   counter: { decrease: (label) => `Giảm ${label}`, increase: (label) => `Tăng ${label}` },
   allocationRow: {
     allocateTo: (label) => `Phân bổ vào ${label}`,

package/src/number_input.tsx

@@ -18,6 +18,12 @@ export interface NumberInputProps {
   disabled?: boolean;
   testID?: string;
   accessibilityLabel?: string;
+  /** Hint text shown while the field is empty — a unit, a shape, an example
+   *  ("0,00", "kg"). `InlineNumberInput` has always had one; without it here the
+   *  only hint slot left on a `FormField` is `description`, which renders
+   *  BETWEEN label and input and so drops this field's input a line below its
+   *  neighbour's in a two-column form grid. */
+  placeholder?: string;
   /** The HOST paints the surface — drop this input's own border, fill, focus ring
    *  AND horizontal padding, so the page draws one box and the text lands on the
    *  host's inset rather than 8px further in. Set by an inline editor whose field
@@ -37,7 +43,7 @@ export interface NumberInputProps {
  * number in place on a record use `InlineNumberInput`.
  */
 export function NumberInput(props: NumberInputProps) {
-  const { value, onValueChange, min, max, disabled, onBlur, onKeyDown, autoFocus, testID, accessibilityLabel, seamless } = props;
+  const { value, onValueChange, min, max, disabled, onBlur, onKeyDown, autoFocus, testID, accessibilityLabel, placeholder, seamless } = props;
   const binding = useFormField();
   const describedBy = [binding?.descriptionId, binding?.warningId, binding?.errorId].filter(Boolean).join(" ") || undefined;
   const { focusVisible, focusProps } = useFocusRing({ always: true });
@@ -52,6 +58,7 @@ export function NumberInput(props: NumberInputProps) {
       aria-describedby={describedBy}
       aria-invalid={binding?.invalid || undefined}
       value={value ?? ""}
+      placeholder={placeholder}
       onChange={(e) =>
         e.target.value !== "" ? onValueChange(Number(e.target.value)) : onValueChange(null)
       }

package/src/reference_field.tsx

@@ -423,10 +423,17 @@ export function ReferenceField(props: ReferenceFieldProps) {
                   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. */}
+                {/* Same resting surface as `change` beside it. It had NO
+                    color — which renders transparent, borderless and
+                    undecorated, i.e. the hover-only affordance composition.md
+                    bans: invisible to keyboard and touch, and a singleton
+                    no-ground among grounded siblings, which a reader parses
+                    before they read any label. Being the least-reached verb is
+                    said by PLACEMENT — second in the left group, far from the
+                    primary — not by drawing nothing. */}
                 <Button
                   title={t.clear}
+                  color="secondary"
                   accessibilityLabel={`${t.clear} — ${name}`}
                   onPress={() => { setPeekOpen(false); onClear(); }}
                 />