@lotics/ui 28.2.0 → 28.3.0

package/docs/catalog.md

@@ -922,6 +922,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS
   never live in the header: compose them as `DetailTable`s in the sections below. Replaces
   hand-rolled record headers (mixed scales, several competing figures, color noise).
+  `metric.value` also takes a NODE, for the one case of a figure that has not loaded yet — pass
+  a `Skeleton` and it renders in place of the styled figure, in a slot holding that figure's own
+  line box, so the band is the same height either way and a loading record's header does not
+  move when the number lands. Still ONE number: a node is a stand-in for it, not a licence to
+  put a control in the slot.
 - **`ledger`** — `Ledger` + `LedgerGroup` + `LedgerBasis` + `LedgerRow` + `LedgerTotal` — the
   record-level money list: every figure on ONE right-aligned tabular column, `peek` turns a row
   into a pressable door floating its particulars in an anchored popover (put links INSIDE the

package/docs/composition.md

@@ -46,7 +46,10 @@ restyle a heading level per-page.
   (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
   at the column edge; `SectionHeadingMeta`, any VIEW control, and the section's own ADD ride the
   heading row's right edge (the title's `flex: 1` pushes them) — see the add-placement law
-  below. The page column is a **`SectionStack`** — it owns the
+  below. A COUNT earns that slot only when what it counts is not fully on screen — collapsed,
+  paged, or long enough that the reader would have to scan to know. Over a list or thread
+  rendered whole directly beneath its own heading it restates what is already in view, and the
+  heading reads busier for it. The page column is a **`SectionStack`** — it owns the
   between-section law (a fixed 56px beat + a bare hairline separating one section from the NEXT;
   null/false children are skipped so a conditional section never leaves a stray hairline). The
   `Divider` NEVER goes directly under a heading — that orphans the title from its own content.

package/examples/tpl_record.tsx

@@ -12,7 +12,7 @@ import type { PickerOption } from "@lotics/ui/picker";
 import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { DetailRow, DetailTable } from "@lotics/ui/detail_row";
 import { Callout, CalloutText } from "@lotics/ui/callout";
-import { Section, SectionHeading, SectionHeadingMeta, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
+import { Section, SectionHeading, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
 import { SectionStack, SubsectionStack } from "@lotics/ui/section_stack";
 import { Checklist, ChecklistActions, ChecklistGroup, ChecklistItem, ChecklistNote } from "@lotics/ui/checklist";
 import { DateStamp } from "@lotics/ui/date_stamp";
@@ -2381,9 +2381,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         {!wide ? (
           <View onLayout={nav.register("comments")}>
           <Section>
+            {/* No count. The thread is RIGHT THERE — the number restates what
+                the reader is already looking at, and it is the kind of meta that
+                earns its place only when the thing it counts is collapsed, or
+                off-screen, or expensive to scan. None of those hold for a
+                discussion rendered in full directly beneath its own heading. */}
             <SectionHeading>
               <SectionHeadingTitle description="Notes on this record — everyone with access sees them.">Comments</SectionHeadingTitle>
-              <SectionHeadingMeta>{`${comments.length} ${comments.length === 1 ? "comment" : "comments"}`}</SectionHeadingMeta>
             </SectionHeading>
             {commentsThread}
           </Section>
@@ -2626,9 +2630,9 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                 the verb is off-screen entirely, and on an empty list there is no
                 last row to sit under, so it had to be a SECOND button inside the
                 `EmptyState`. One verb, two renderings, neither findable without
-                scanning. The heading row is the section's control line — it
-                already carries `SectionHeadingMeta` and the title grows to push
-                its siblings right — so the add belongs on it, in the same spot
+                scanning. The heading row is the section's control line — where a
+                section's meta and verbs sit, with the title growing to push its
+                siblings right — so the add belongs on it, in the same spot
                 whether the list holds nought or forty. */}
             <Button title="Add fee" color="primary" onPress={addFee} />
           </SectionHeading>
@@ -3632,13 +3636,12 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         {/* The panel is a PEER of the sections beside it, not a widget, so its
             title takes the ramp's section rung rather than a hand-picked size —
             and it takes the WHOLE construct. `SectionHeadingTitle` carries
-            `flex: 1` so it can push meta to a heading row's right edge; dropped
-            straight into this column it grows VERTICALLY instead and starves the
-            thread beneath it. The row wrapper is what makes that flex mean what
-            it was written to mean. */}
+            `flex: 1` so it can push a heading row's trailing content to the right
+            edge; dropped straight into this column it grows VERTICALLY instead
+            and starves the thread beneath it. The row wrapper is what makes that
+            flex mean what it was written to mean. */}
         <SectionHeading>
           <SectionHeadingTitle>Comments</SectionHeadingTitle>
-          <SectionHeadingMeta>{`${comments.length} ${comments.length === 1 ? "comment" : "comments"}`}</SectionHeadingMeta>
         </SectionHeading>
         {/* The panel's OWN scroller, so a long thread scrolls inside itself and
             never lengthens the record. The thread inside it is the same one the

package/package.json

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

package/src/record_summary.tsx

@@ -5,8 +5,20 @@ import { Text } from "./text";
 export interface RecordSummaryMetric {
   /** Caption above the number ("Outstanding", "Total value"). */
   label: string;
-  /** The headline figure — rendered lg semibold tabular. */
-  value: string;
+  /**
+   * The headline figure — rendered lg semibold tabular.
+   *
+   * A NODE is accepted for one reason: the figure is not known yet, and the
+   * surface wants a placeholder (a `Skeleton`) in its place while the record
+   * loads. It is rendered INSTEAD of the styled `Text`, not inside it — a `View`
+   * nested in a `Text` is not a thing React Native supports — into a slot that
+   * reserves the figure's own line box, so a placeholder cannot change the
+   * band's height and the caller never has to know what that height is.
+   *
+   * It is still ONE headline number. A node here is a stand-in for the number,
+   * never a licence to put a control or a second figure in the slot.
+   */
+  value: ReactNode;
   /** Valence of the figure (and its note) — the summary's ONE permitted accent. */
   tone?: "default" | "danger" | "warning" | "success";
   /** One short qualifier under the number ("Overdue 25 days"). */
@@ -65,9 +77,13 @@ export function RecordSummary(props: RecordSummaryProps) {
             <Text size="xs" color="muted" weight="medium" align="right">
               {metric.label}
             </Text>
-            <Text size="lg" weight="semibold" tabular align="right" color={metric.tone === "default" ? undefined : metric.tone}>
-              {metric.value}
-            </Text>
+            {typeof metric.value === "string" ? (
+              <Text size="lg" weight="semibold" tabular align="right" color={metric.tone === "default" ? undefined : metric.tone}>
+                {metric.value}
+              </Text>
+            ) : (
+              <View style={styles.metricSlot}>{metric.value}</View>
+            )}
             {metric.note ? (
               <Text size="xs" align="right" weight={metric.tone && metric.tone !== "default" ? "medium" : "regular"} color={metric.tone && metric.tone !== "default" ? metric.tone : "muted"}>
                 {metric.note}
@@ -100,4 +116,12 @@ const styles = StyleSheet.create({
     alignItems: "flex-end",
     gap: 1,
   },
+  // The figure's line box, held open for a non-string value so the band is the
+  // same height whether it holds the number or a placeholder. 30 is `Text` size
+  // `lg`'s lineHeight (src/text.tsx) — the height the styled figure occupies.
+  metricSlot: {
+    height: 30,
+    justifyContent: "center",
+    alignItems: "flex-end",
+  },
 });