@lotics/ui 26.4.1 → 27.7.0

package/examples/tpl_record.tsx

@@ -35,6 +35,7 @@ import { FileRows } from "@lotics/ui/file_rows";
 import { FileGrid } from "@lotics/ui/file_grid";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { InlineStatic } from "@lotics/ui/inline_static";
+import { Ledger, LedgerGroup, LedgerRow, LedgerTotal } from "@lotics/ui/ledger";
 import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { InlineNumberInput } from "@lotics/ui/inline_number_input";
 import { InlineSelect } from "@lotics/ui/inline_select";
@@ -59,7 +60,6 @@ import { CheckboxInput } from "@lotics/ui/checkbox_input";
 import { ChipGroup, type ChipOption } from "@lotics/ui/chip_group";
 import { Sequence, SequenceItem, SEQUENCE_INSET } from "@lotics/ui/sequence";
 import { ReferenceField } from "@lotics/ui/reference_field";
-import { TextButton } from "@lotics/ui/text_button";
 import { InlineButton } from "@lotics/ui/inline_button";
 import { useSelection } from "@lotics/ui/use_selection";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
@@ -136,7 +136,11 @@ interface Customer {
 // inline Tax ID fix-up in the Customer section.
 const KNOWN_CUSTOMERS: Customer[] = [
   { id: "cus_01", name: "Northwind Traders", code: "KH-0148", taxId: "0312456780", contact: "Mara Lindqvist", city: "Gothenburg", address: "Ringvägen 118, 4 tr, 116 61 Stockholm, Sweden", since: "2019-03-14" },
-  { id: "cus_02", name: "Harbor Freight Lines", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam", address: "Waalhaven Oostzijde 81, 3087 BM Rotterdam, Netherlands", since: "2021-11-02" },
+  // DELIBERATELY too long for one line. A register of tidy two-word names cannot
+  // show what a reference does when it does not fit — which is truncate in the
+  // field and wrap in the peek — so the one fixture the template opens with is the
+  // realistic worst case. Real customer names look like this.
+  { id: "cus_02", name: "Harbor Freight Lines & Coastal Forwarding Group", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam", address: "Waalhaven Oostzijde 81, 3087 BM Rotterdam, Netherlands", since: "2021-11-02" },
   { id: "cus_03", name: "Summit Packaging Co.", code: "KH-0231", taxId: "0301557742", contact: "Priya Nair", city: "Singapore", address: "9 Tuas Bay Walk, #03-14, Singapore 637803", since: "2023-06-19" },
   { id: "cus_04", name: "Atlas Distribution", code: "KH-0117", taxId: "", contact: "Tom Becker", city: "Hamburg", address: "Grosser Grasbrook 9, 20457 Hamburg, Germany", since: "2018-01-30" },
   { id: "cus_05", name: "Bluewater Logistics", code: "KH-0294", taxId: "0312004455", contact: "Lena Fischer", city: "Antwerp", address: "Noorderlaan 127, 2030 Antwerpen, Belgium", since: "2022-09-08" },
@@ -278,9 +282,12 @@ interface Invoice {
 
 const BILLING_INITIAL: Invoice[] = [
   {
+    // Issued AND multi-line, which is the row that exercises the precedence: `peek` wins,
+    // so its lookup link renders INSIDE the popover and the flat `reference` is ignored.
+    // Storage is the mirror case (one charge, issued) and takes the flat link instead.
     key: "delivery",
     title: "Delivery",
-    ref: "",
+    ref: "INV-0029",
     charges: [
       { key: "freight", label: "Freight", standard: 1_200_000, amount: 1_200_000, method: "cash" },
       { key: "insurance", label: "Insurance", standard: 250_000, amount: 0, method: "" },
@@ -293,13 +300,19 @@ const BILLING_INITIAL: Invoice[] = [
     charges: [{ key: "handling", label: "Handling fee", standard: 150_000, amount: 150_000, method: "" }],
   },
   {
+    // Seeded ISSUED, so the section renders both states at rest: the Re-issue path, the
+    // band's lookup link, and the ledger's trailing `reference`. A fixture where nothing
+    // has happened yet only ever exercises the first half of a flow.
     key: "storage",
     title: "Storage",
-    ref: "",
+    ref: "INV-0031",
     charges: [{ key: "storage", label: "Storage fee", standard: 80_000, amount: 80_000, method: "transfer" }],
   },
 ];
 
+/** A settled credit against the record — the statement's third side, and its only line. */
+const CREDIT = { key: "cn-0031", label: "Credit note CN-0031", amount: 120_000, meta: "Storage waived, 3 days" };
+
 const invoiceTotal = (inv: Invoice) => inv.charges.reduce((s, c) => s + c.amount, 0);
 const missingMethods = (inv: Invoice) => inv.charges.filter((c) => c.amount > 0 && !c.method);
 
@@ -640,6 +653,38 @@ interface Stop {
  * The kit draws the rail, the reorder/remove controls and the spacing; the
  * template supplies what a stop CONTAINS and what its position MEANS.
  */
+/**
+ * What sits behind ONE invoice figure in the closing statement — the charges that add up
+ * to it, and the lookup link once it is issued.
+ *
+ * The link belongs in HERE rather than beside the row: a `peek` row is already a button,
+ * and a button inside a button is invalid markup. That is also why the flat `reference`
+ * link and `peek` are alternatives, never companions — the component renders `reference`
+ * only on a row that is not a door.
+ *
+ * Unpriced charges are listed too, as "—" rather than 0: a charge nobody has priced is
+ * not a charge of nothing, and this is the popover that explains why the figure above is
+ * smaller than the invoice's line count suggests.
+ */
+function InvoiceParticulars({ inv }: { inv: Invoice }) {
+  return (
+    <View style={{ gap: 8, padding: 12, minWidth: 240 }}>
+      <Text size="xs" color="muted">{inv.title}</Text>
+      {inv.charges.map((c) => (
+        <View key={c.key} style={{ flexDirection: "row", alignItems: "baseline", gap: 12 }}>
+          <Text size="sm" style={{ flexGrow: 1, flexShrink: 1 }}>{c.label}</Text>
+          <Text size="sm" tabular color={c.amount > 0 ? undefined : "muted"}>
+            {c.amount > 0 ? formatMoney(c.amount) : "—"}
+          </Text>
+        </View>
+      ))}
+      {inv.ref ? (
+        <Link size="xs" onPress={() => {}} accessibilityLabel={`Open invoice ${inv.ref}`}>{inv.ref}</Link>
+      ) : null}
+    </View>
+  );
+}
+
 function RouteStops({ stops, onChange }: { stops: Stop[]; onChange: (next: Stop[]) => void }) {
   const patch = (id: string, next: Partial<Stop>) =>
     onChange(stops.map((s) => (s.id === id ? { ...s, ...next } : s)));
@@ -691,7 +736,9 @@ function RouteStops({ stops, onChange }: { stops: Stop[]; onChange: (next: Stop[
       <View style={{ flexDirection: "row", paddingLeft: SEQUENCE_INSET }}>
         {/* A stop is added BEFORE the destination — a new leg is always in the
             middle of a journey; nobody adds one past the end. */}
-        <TextButton
+        <Button
+          title="Add stop"
+          color="secondary"
           onPress={() =>
             onChange([
               ...stops.slice(0, -1),
@@ -699,9 +746,7 @@ function RouteStops({ stops, onChange }: { stops: Stop[]; onChange: (next: Stop[
               stops[stops.length - 1],
             ])
           }
-        >
-          Add stop
-        </TextButton>
+        />
       </View>
     </View>
   );
@@ -1282,6 +1327,22 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   // total that will actually be billed, including a charge that landed after the press.
   const confirmIssue = invoices.find((i) => i.key === confirmIssueKey) ?? null;
   const grandTotal = invoices.reduce((sum, inv) => sum + invoiceTotal(inv), 0);
+  // A charge carrying a METHOD has been paid — the statement below is derived from
+  // that, not from a second "paid" flag somebody has to keep in step with it. The
+  // record already knows; asking again is how the two answers start disagreeing.
+  //
+  // ONE list, and both the rows and the subtotal read it. Deriving them from two
+  // separate predicates is how a ledger comes to disagree with itself: filter the
+  // rows on `method && amount > 0` while summing on `method` alone and any charge
+  // that fails only the second test lands in the total with no line to explain it.
+  // The component cannot catch that — it renders the `total` it is handed.
+  const receipts = invoices.flatMap((inv) =>
+    inv.charges.filter((c) => c.method !== "" && c.amount > 0).map((c) => ({ inv, charge: c })),
+  );
+  const received = receipts.reduce((sum, r) => sum + r.charge.amount, 0);
+  // Three sides now, so the total states the arithmetic rather than a difference of two:
+  // what was billed, less what was credited, less what arrived.
+  const outstanding = grandTotal - CREDIT.amount - received;
   const allMissing = invoices.flatMap(missingMethods);
 
   const issue = (inv: Invoice) => {
@@ -2441,12 +2502,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                             convention, which is the kit's. It replaces the
                             DrawerFooter that used to pin it.
 
-                            `TextButton`, same as the peek's detach: a text-weight
-                            destructive act aligned to a column of text. It lands its
-                            ink ON the label column by construction, keeps a 40px
-                            target via hitSlop, and drops the trash glyph — "Remove
-                            fee" already names the object, which is the safeguard the
-                            icon was only decorating.
+                            Solid `danger`, which is the destructive convention
+                            page-wide (composition rule 9) — not a text-weight act.
+                            A quiet destructive verb had been tried here and the
+                            surface-less rung is gone: an act now always carries a
+                            control, and only NAVIGATION is underlined text. The trash
+                            glyph stays off — "Remove fee" already names the object,
+                            which is the safeguard the icon was only decorating.
 
                             NO Divider. Every hairline a `Table` draws is
                             full-bleed (the row `Divider`s carry no padding, the
@@ -2457,7 +2519,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                             wrapper is required, not decoration: a `Button` alone
                             in a column View stretches to full width. */}
                         <View style={{ flexDirection: "row" }}>
-                          <TextButton color="danger" onPress={() => deleteFee(f)}>Remove fee</TextButton>
+                          <Button title="Remove fee" color="danger" onPress={() => deleteFee(f)} />
                         </View>
                       </View>
                     }
@@ -2591,6 +2653,88 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
             })}
           </SubsectionStack>
 
+          {/* THE CLOSING STATEMENT — `Ledger`, the money grammar, and the answer to
+              the one question the bands above cannot give: what does this record come
+              to, and how much of it has arrived. Each invoice states its own total on
+              its lead line, but three totals down the page are three facts the reader
+              has to add up, and "is anything still owed" was nowhere on the section.
+
+              It is a STATEMENT, not another band: no `Subsection`, no heading rung. It
+              closes the invoices, so it sits directly under them and above the record's
+              own fields — a conclusion goes after what it concludes.
+
+              THREE sides, which is what makes the total state arithmetic rather than a
+              difference: billed, less credited, less received. Money coming back is
+              NEGATIVE (the component renders "− ") and `success`-toned, because a
+              receipt and a credit are both the good outcome; `zeroLabel` gives a settled
+              record "Paid in full" instead of a proud zero.
+
+              The DEPOSIT is deliberately absent. It is refundable — never part of the
+              total to collect — so folding it in would make the closing figure answer a
+              different question than the one it is labelled with. A ledger earns trust
+              by summing exactly what its label claims.
+
+              A row opens where there is something to open, and the two ways are not
+              interchangeable. `peek` floats an invoice's PARTICULARS — the charges behind
+              its one figure — and the lookup link lives INSIDE that popover, never beside
+              the trigger, because a button inside a button is invalid. `reference` is the
+              flat alternative for a row with nothing to expand: one charge IS its own
+              particulars, so Storage carries a trailing link instead of a door.
+
+              The `Adjustments` group holds ONE row and therefore no `total`: a sum over a
+              single line states the same fact twice, at two weights. That is the honest
+              fixture rather than a tidy one — real groups are built from data, so some
+              arrive with one row — and it puts the grammar's open question on screen: an
+              unsummed group captions from ABOVE while a summed one closes from below, so
+              this statement names its groups in two places. */}
+          <Ledger formatValue={money}>
+            <LedgerGroup label="Invoiced" total={grandTotal}>
+              {invoices.map((inv) => {
+                /* NO meta on this side. It briefly carried "awaiting payment method",
+                   and that was `meta` doing two jobs: on the Received rows it holds a
+                   neutral QUALIFIER (how the money arrived), here it held a PROBLEM.
+                   Two unlike things in one treatment is what makes a caption read as
+                   inconsistent — the size was never the fault.
+                   The problem also had a home already: the charge row above carries
+                   `warning="Choose how this was paid"`, on the line with the editor that
+                   fixes it. A statement's job is the arithmetic, and the arithmetic
+                   already says it — `Outstanding` IS the unpaid money. Saying it again in
+                   weaker words adds a second voice for one fact. */
+                /* A door where there are PARTICULARS, and the count that decides it is the
+                   charges, not the priced ones. An invoice whose second line is unpriced is
+                   exactly the row whose figure looks too small for it, which is the question
+                   the popover answers — gating on `amount > 0` would hide the door precisely
+                   when it is most useful. */
+                return (
+                  <LedgerRow
+                    key={inv.key}
+                    label={inv.title}
+                    value={invoiceTotal(inv)}
+                    peek={inv.charges.length > 1 ? <InvoiceParticulars inv={inv} /> : undefined}
+                    reference={inv.ref ? { label: inv.ref, onPress: () => {} } : undefined}
+                  />
+                );
+              })}
+            </LedgerGroup>
+            <LedgerGroup label="Adjustments">
+              <LedgerRow label={CREDIT.label} meta={CREDIT.meta} value={-CREDIT.amount} tone="success" />
+            </LedgerGroup>
+            {received > 0 ? (
+              <LedgerGroup label="Received" total={-received}>
+                {receipts.map(({ inv, charge }) => (
+                  <LedgerRow
+                    key={`${inv.key}-${charge.key}`}
+                    label={charge.label}
+                    meta={METHODS.find((m) => m.value === charge.method)?.label}
+                    value={-charge.amount}
+                    tone="success"
+                  />
+                ))}
+              </LedgerGroup>
+            ) : null}
+            <LedgerTotal label="Outstanding" value={outstanding} tone={outstanding > 0 ? "danger" : "default"} zeroLabel="Paid in full" />
+          </Ledger>
+
           {/* ONE action row for the section, on the control column. The deposit
               is a field of the record, not a band of its own — its receipt is a
               second act on the same row. */}

package/examples/tpl_task_board.tsx

@@ -1,7 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { Pressable, ScrollView, StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "@lotics/ui/text";
-import { TextButton } from "@lotics/ui/text_button";
 import { colors, solid, asColorName } from "@lotics/ui/colors";
 import { Icon } from "@lotics/ui/icon";
 import { CheckCircle } from "@lotics/ui/check_circle";
@@ -527,7 +526,7 @@ function RowActionCell({ task, result, onAttach, onApprove }: { task: Task; resu
   const onPress = a.kind === "attach" ? () => onAttach(task.id) : a.kind === "approve" ? () => onApprove(task.id) : () => {};
   return (
     <View style={styles.action}>
-      <TextButton numberOfLines={1} onPress={onPress}>{a.label}</TextButton>
+      <Button title={a.label} color="muted" onPress={onPress} />
     </View>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "26.4.1",
+  "version": "27.7.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -179,7 +179,6 @@
     "./counter": "./src/counter.tsx",
     "./link": "./src/link.tsx",
     "./reference_field": "./src/reference_field.tsx",
-    "./text_button": "./src/text_button.tsx",
     "./text_link": "./src/text_link.tsx",
     "./sort_header": "./src/sort_header.tsx",
     "./skeleton": "./src/skeleton.tsx",

package/src/filter_chip.tsx

@@ -3,11 +3,11 @@ import { StyleSheet, View } from "react-native";
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { colors } from "./colors";
-import { TextButton } from "./text_button";
 import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { useLoticsLocale } from "./locale";
+import { Button } from "./button";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -110,7 +110,7 @@ export function FilterChip(props: FilterChipProps) {
           <PopoverFooter>{footer}</PopoverFooter>
         ) : showClear ? (
           <PopoverFooter align="start">
-            <TextButton onPress={onClear}>{clearLabel}</TextButton>
+            <Button title={clearLabel} color="muted" onPress={onClear} />
           </PopoverFooter>
         ) : null}
       </PopoverContent>

package/src/ledger.tsx

@@ -9,9 +9,12 @@ import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 
 // The record-level money list — a compact financial STATEMENT for one record's
-// drawer/section: charge/receipt GROUPS with their sums in the group headers,
-// every figure on ONE right-aligned tabular column, closed by a divider-set
-// emphasized total. A row with `peek` is a door: pressing it floats the fee's
+// drawer/section: charge/receipt GROUPS each closed by their own sum, every
+// figure on ONE right-aligned tabular column, closed by a divider-set
+// emphasized total. Three ascending rungs and no more — a row, a group's
+// subtotal, the total — so the reader's eye lands on the conclusion.
+//
+// A row with `peek` is a door: pressing it floats the fee's
 // PARTICULARS (basis, who charged it, the invoice it landed on) in an anchored
 // popover — the list stays flat and scannable, the depth is on demand. A row
 // with `reference` carries a trailing link instead (an issued invoice, a
@@ -63,31 +66,125 @@ export function Ledger(props: LedgerProps) {
 }
 
 export interface LedgerGroupProps {
-  /** The group name ("Charges", "Received") — xs muted, with the sum opposite. */
+  /** The group name ("Charges", "Received", a category). It travels WITH the sum when
+   *  there is one, and captions the rows from above when there is not. */
   label: string;
-  /** The group's sum, shown right-aligned in the header. Sign renders as
-   *  "−" (pass receipts negative). Omit to leave the header sumless. */
+  /** The group's sum, closing the rows BELOW it. Sign renders as "−" (pass receipts
+   *  negative). It must EQUAL the rows it closes — derive the rows and the sum from one
+   *  list, never from two predicates that can drift apart.
+   *
+   *  Omit it for a group that only NAMES its rows: a sum earns its place by adding
+   *  something the rows do not already say, which a one-row group's sum does not. */
   total?: number;
   children: ReactNode;
 }
 
-/** One side of the ledger — a labelled run of rows with its sum in the header. */
+/**
+ * One side of the ledger — a run of rows, closed by its sum.
+ *
+ * **The sum FOLLOWS its rows.** It sat in the header for a version, which is how a
+ * caption behaves, not how a subtotal does: every invoice, statement and receipt puts
+ * a subtotal after the lines it sums, and above them the reader either trusts a figure
+ * before seeing its parts or reads down and jumps back up to find it.
+ *
+ * It also sat at the LABEL's weight — xs muted — so the number summarising three rows
+ * came out smaller and greyer than the rows themselves. A subtotal is of the same
+ * magnitude class as its lines, so it takes their SIZE and one step of weight above
+ * them: `sm/medium` against rows at `sm/regular`, under a total at `md/semibold`. Three
+ * rungs, each one step, and the eye can rank them without reading a word.
+ *
+ * The LABEL travels with the sum rather than being repeated: a group that closes with
+ * "Invoiced  1.430.000 ₫" does not also need to announce "INVOICED" before its rows —
+ * that is the same word twice for one group. A group with no `total` therefore keeps the
+ * caption ABOVE its rows, because there is nothing for its label to travel with — and a
+ * group can legitimately have no sum: naming a category is one job, summing it is
+ * another, and a one-row group's sum only restates the row.
+ *
+ * **Do not mix the two inside one `Ledger`.** The label sits above an unsummed group and
+ * below a summed one, so a statement holding both moves its own group names around and
+ * reads as though the placement were an accident. Pick one shape per statement: if any
+ * group earns a sum, give every group one (grouping a single row is then the thing to
+ * avoid — let that row stand bare, or fold it into a neighbouring group).
+ *
+ * Naming a side at the BOTTOM means the reader meets its rows before its name, so the
+ * rows must say which side they are on by themselves — which they do when the sides
+ * carry opposite SIGNS (charges positive, receipts "−" and `tone="success"`). Two
+ * same-signed groups are not two sides of one statement; they are two statements, and
+ * they want two `Ledger`s under their own headings.
+ */
 export function LedgerGroup(props: LedgerGroupProps) {
   const { label, total, children } = props;
   const { format } = useLedger();
+  const closed = total != null;
   return (
     <View style={styles.group}>
-      <View style={styles.groupHead}>
-        <Text size="xs" weight="medium" color="muted" style={styles.grow}>
-          {label}
-        </Text>
-        {total != null ? (
-          <Text size="xs" color="muted" tabular>
+      {!closed ? (
+        <View style={styles.groupHead}>
+          <Text size="xs" weight="medium" color="muted" style={styles.grow}>
+            {label}
+          </Text>
+        </View>
+      ) : null}
+      {children}
+      {closed ? (
+        <View style={styles.row}>
+          <Text size="sm" weight="medium" style={styles.grow}>
+            {label}
+          </Text>
+          <Text size="sm" weight="medium" tabular>
             {signed(format, total)}
           </Text>
-        ) : null}
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+export interface LedgerBasisProps {
+  /** What the figure IS ("Customs value (CIF)", "Gross revenue", "Principal"). */
+  label: string;
+  value: number;
+  /** How the figure was arrived at — the FX rate it was converted at, the period
+   *  it covers. Not a second label: it qualifies the number, it does not name it. */
+  meta?: string;
+}
+
+/**
+ * The figure the rows below are computed FROM — a statement's premise, not one of
+ * its lines.
+ *
+ * Some statements are not `charges → total`. Duty is `customs value → levies →
+ * payable`; commission is `gross → rates → owed`; interest is `principal → accrual
+ * → balance`. In all of them one number is the BASE and the rest are derived from
+ * it, and a ledger that can only say "row" has to lie about which is which.
+ *
+ * Rendering the base as a `LedgerRow` claims it is a peer of the levies — that you
+ * could add it to them. Putting it in a one-row `LedgerGroup` is worse: a group's
+ * sum earns its place only when it sums more than one visible row, so a single-row
+ * group states the same fact twice, at two weights, and the reader has to work out
+ * that the repetition means nothing.
+ *
+ * So it takes the THIRD treatment on the ledger's one money column — between a
+ * plain row and the total — and its `Divider` sits BELOW it, because a premise
+ * separates itself from what it feeds. (`LedgerTotal`'s rule sits above, closing
+ * what came before.) Order is the caller's: a basis first reads as "from this",
+ * which is the only order that makes the levies beneath it legible.
+ */
+export function LedgerBasis(props: LedgerBasisProps) {
+  const { label, value, meta } = props;
+  const { format } = useLedger();
+  return (
+    <View style={styles.basis}>
+      <View style={[styles.row, styles.baselineRow]}>
+        <View style={styles.grow}>
+          <Text size="sm" weight="medium">{label}</Text>
+          {meta != null ? <Text size="xs" color="muted">{meta}</Text> : null}
+        </View>
+        <Text size="sm" weight="medium" tabular>
+          {signed(format, value)}
+        </Text>
       </View>
-      {children}
+      <Divider />
     </View>
   );
 }
@@ -95,7 +192,18 @@ export function LedgerGroup(props: LedgerGroupProps) {
 export interface LedgerRowProps {
   /** The line's name — what was charged / received. */
   label: string;
-  /** Inline context after the label — a date, method, a basis, a period. */
+  /**
+   * Inline context after the label — a date, a method, a basis, a period. A neutral
+   * QUALIFIER on the figure, rendered as a caption (xs, muted) because it is
+   * subordinate to the thing it qualifies.
+   *
+   * Never a PROBLEM or a state ("awaiting approval", "missing method"). It reads
+   * inconsistent the moment one row's meta is a fact and another's is a complaint —
+   * two unlike things in one treatment — and a caption is the wrong weight for
+   * something that wants acting on. A problem belongs on the row that can FIX it (a
+   * `DetailRow`'s `warning` beside its editor), and in a statement the arithmetic has
+   * usually said it already: an unpaid line is what the outstanding total IS.
+   */
   meta?: string;
   /** The amount. Negative renders "− <abs>" (a receipt). */
   value: number;
@@ -174,7 +282,23 @@ export interface LedgerTotalProps {
   zeroLabel?: string;
 }
 
-/** The divider-set closing line — the ledger's ONE emphasized number. */
+/**
+ * The divider-set closing line — the ledger's ONE emphasized number.
+ *
+ * **Both sides take the same size.** The figure spent a version at `lg` against an
+ * `sm` label, which on web is 20px beside 14px (the scale steps `lg` up past 768px) —
+ * a 1.4× mismatch between two texts that are PEERS on one line, and a mismatch on one
+ * line reads as a slip however principled its reason. Raising the label to match is
+ * worse: `lg` puts it within a few px of the section heading above it and the record's
+ * conclusion starts competing with the record's structure.
+ *
+ * So the line is `md/semibold` throughout, and the emphasis comes from everything
+ * except size: it is the only line above a `Divider`, the only one at semibold, and
+ * the only one allowed a tone. Against rows at `sm/regular` and subtotals at
+ * `sm/medium` that is still a clear third rung — 2px and a weight step, plus a rule
+ * and a colour — and the ledger ends up using exactly two type sizes for its money
+ * and one for its captions.
+ */
 export function LedgerTotal(props: LedgerTotalProps) {
   const { label, value, tone = "default", zeroLabel } = props;
   const { format } = useLedger();
@@ -183,10 +307,10 @@ export function LedgerTotal(props: LedgerTotalProps) {
     <View style={styles.total}>
       <Divider />
       <View style={styles.row}>
-        <Text size="sm" weight="semibold" style={styles.grow}>
+        <Text size="md" weight="semibold" style={styles.grow}>
           {label}
         </Text>
-        <Text size="lg" weight="semibold" tabular color={settled ? "success" : tone === "default" ? undefined : tone}>
+        <Text size="md" weight="semibold" tabular color={settled ? "success" : tone === "default" ? undefined : tone}>
           {settled ? zeroLabel : signed(format, value)}
         </Text>
       </View>
@@ -199,13 +323,15 @@ const styles = StyleSheet.create({
   // the money column align with the section heading and the container edges;
   // the pressable door's wash bleeds into the gutter instead of squeezing text.
   // Grouping reads by PROXIMITY: the gap between groups must be decisively larger
-  // than the gap inside one, or the eyebrow floats midway and belongs to neither
-  // the group above nor the rows below. 18 between, 2 within.
+  // than the gap inside one, or a line floats midway and belongs to neither the
+  // group above nor the rows below. 16 between, 0 within — a row's own 28px
+  // minHeight already sets the beat inside a group, so adding a gap on top of it
+  // would loosen the group toward the between-group distance and undo the ranking.
   ledger: { gap: 16, marginHorizontal: -8 },
   group: { gap: 0 },
-  // EVERY line (group header, rows, the total) shares the 8px text inset, so
-  // labels and the money column sit on one edge whether a row peeks or not —
-  // the pressable door's wash simply fills the same padded box.
+  // EVERY line (rows, a group's caption or sum, the basis, the total) shares the 8px
+  // text inset, so labels and the money column sit on one edge whether a row peeks or
+  // not — the pressable door's wash simply fills the same padded box.
   row: {
     flexDirection: "row",
     alignItems: "center",
@@ -213,9 +339,8 @@ const styles = StyleSheet.create({
     minHeight: 28,
     paddingHorizontal: 8,
   },
-  // The group eyebrow is a CAPTION on the rows beneath it, not a line of its own —
-  // it takes only the height its xs text needs, so it hugs what it labels instead
-  // of sitting in a full 28px row box.
+  // An unsummed group's caption labels the rows beneath it, so it takes only the height
+  // its xs text needs — hugging what it labels instead of sitting in a full 28px row.
   groupHead: {
     flexDirection: "row",
     alignItems: "center",
@@ -230,4 +355,16 @@ const styles = StyleSheet.create({
   grow: { flexGrow: 1, flexShrink: 1 },
   shrink: { flexShrink: 1 },
   total: { gap: 6 },
+  // The BASIS row, the only one whose two sides can differ in height: its label may
+  // carry a stacked `meta` while the figure stays one line. Centring then measures the
+  // figure against the whole block and lands it in the gap between the label and its
+  // caption instead of level with the label it belongs to. On a shared baseline the
+  // figure sits on the label's FIRST line — the law `DetailRow` already follows for a
+  // wrapped label, and the alignment `KPICard`, `RemainderMeter`, `ProgressBar` and
+  // `Funnel` already use wherever a figure meets smaller text on one row. Every other
+  // line here is same-size on both sides, where centring and baseline agree.
+  baselineRow: { alignItems: "baseline" },
+  // Mirrors `total`'s gap so the premise and the conclusion frame the levies with
+  // the same air — the rule just sits on the other side.
+  basis: { gap: 6 },
 });

package/src/option_list.tsx

@@ -7,7 +7,6 @@ import { Checkbox } from "./checkbox";
 import { MenuButton } from "./menu_button";
 import { MenuListItem } from "./menu_list_item";
 import { Button } from "./button";
-import { TextButton } from "./text_button";
 import { ActivityIndicator } from "./activity_indicator";
 import { TextInputField } from "./text_input_field";
 import { useScreenSize } from "./use_screen_size";
@@ -176,9 +175,9 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
 
       {list.showSelectAll || list.showDeselectAll ? (
         <View style={styles.selectAllContainer}>
-          {list.showSelectAll ? <TextButton onPress={list.selectAll}>{selectAllLabel}</TextButton> : null}
+          {list.showSelectAll ? <Button title={selectAllLabel} color="muted" onPress={list.selectAll} /> : null}
           {list.showDeselectAll ? (
-            <TextButton onPress={list.deselectAll}>{deselectAllLabel}</TextButton>
+            <Button title={deselectAllLabel} color="muted" onPress={list.deselectAll} />
           ) : null}
         </View>
       ) : null}
@@ -200,8 +199,12 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 16,
     paddingVertical: 4,
-    // Matches a MenuButton option's 8px text inset so the select-all / deselect-all
-    // links line up under the option labels above.
+    // Matches a MenuButton option's 8px inset, so the Button's SURFACE starts on the
+    // same edge as the option rows above it. Not its ink: a Button's ink sits 10px
+    // further in (measured 458 against option labels at 480, which begin after the
+    // checkbox), and no inset here makes text-to-text alignment possible in a list
+    // whose rows lead with a control. The surface is the edge a surfaced control
+    // aligns on.
     paddingHorizontal: 8,
     borderTopWidth: 1,
     borderTopColor: colors.border,