@lotics/ui 44.14.0 → 45.3.0

package/src/reference_field.tsx

@@ -7,7 +7,7 @@ import { formatDate } from "./format_date";
 import { InlineEditView } from "./inline_edit";
 import { InlineStatic } from "./inline_static";
 import { Popover, PopoverContent, PopoverFooter, PopoverHeader } from "./popover";
-import { DialogSectionHeadingTitle } from "./section_heading";
+import { SectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
 import { TextInputField } from "./text_input_field";
 import { TextLink } from "./text_link";
@@ -256,19 +256,21 @@ export function ReferenceField(props: ReferenceFieldProps) {
           </View>
         }
       />
-      {/* THE PEEK'S FORMAT — the kit's own grammar, not a bespoke one. A popover
-          is dialog-scale, so the identity takes the ramp's dialog rung
-          (`DialogSectionHeadingTitle`, ####) with the code as its description
-          rather than a hand-picked font weight; the facts are `DetailRow`s, which
+      {/* THE PEEK'S FORMAT — the kit's own grammar, not a bespoke one. The
+          identity is a plain `SectionHeadingTitle` with the code as its
+          description rather than a hand-picked font weight — a popover is
+          dialog-scale, so the ramp puts it on the `####` rung by itself, and
+          this call site no longer names the surface it is standing
+          on; the facts are `DetailRow`s, which
           is what label-beside-value IS everywhere else on this page; and the
           verbs sit in the popover's own pinned footer rather than floating after
           the last fact.
 
           WIDTH COMES FROM THE FIELD (`inheritTriggerWidth`), not a constant. A
           fixed 320 was "every peek in an app is the same object", and the object
-          it was actually the same as was nothing on screen: measured on a record
-          page, a 558px field opened a 320px panel left-aligned under it, stopping
-          238px short of the edge the reader's eye had just travelled to. A
+          it was actually the same as was nothing on screen: a wide field opened a
+          narrow panel left-aligned under it, stopping short of the edge the
+          reader's eye had just travelled to. A
           popover narrower than the control that opened it reads as belonging to
           something else. `InlineSelect` — the same shape, an inline field opening
           a `triggerRef` popover — already inherits its field's width, so the two
@@ -294,7 +296,7 @@ export function ReferenceField(props: ReferenceFieldProps) {
           is never what scrolls out of view. */}
       <PopoverContent style={{ maxHeight: 420 }}>
         <PopoverHeader>
-          <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
+          <SectionHeadingTitle description={code}>{name}</SectionHeadingTitle>
         </PopoverHeader>
         <View style={{ gap: 12 }}>
           {/* ONE geometry for both modes — the table's own 40px band, which is

package/src/section_heading.tsx

@@ -1,8 +1,9 @@
 import { View, type StyleProp, type ViewStyle } from "react-native";
-import { Text, type HeadingLevel } from "./text";
+import { Text, type HeadingLevel, type TextSize } from "./text";
 import { Icon, type IconName } from "./icon";
 import { InfoPopover } from "./info_popover";
 import { useLoticsLocale } from "./locale";
+import { useHeadingAltitude, type HeadingAltitude } from "./heading_altitude";
 
 // The card-less section header — the bare-canvas sibling of `CardHeader`, built
 // the same compound way. A title (+ optional leading icon / description) on one
@@ -117,9 +118,15 @@ export interface SubsectionHeadingTitleProps {
   info?: string;
 }
 
-/** The subsection title — ALWAYS `###` (lg semibold), the fixed step under the
- * xl section title and above the md/sm body. Grows to push siblings (a
- * `SectionHeadingMeta`, a `Badge`, an action) to the right edge. */
+/** The subsection title — ALWAYS `###` (lg semibold), the fixed step under a
+ * PAGE's xl section title and above the md/sm body. Grows to push siblings (a
+ * `SectionHeadingMeta`, a `Badge`, an action) to the right edge.
+ *
+ * It has one altitude, not two: inside a PANEL the section rung is already
+ * the ramp's floor (`####` md), so a subsection there would out-rank its own
+ * section. A named group inside a panel's section is `Text size="sm"
+ * weight="semibold"` — a panel is one surface, and a second heading level in it
+ * is a document the reader is not reading. */
 export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   const { children, description, level = 3, info } = props;
   const words = useLoticsLocale();
@@ -144,64 +151,6 @@ export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
   );
 }
 
-export interface DialogSectionHeadingTitleProps {
-  children: React.ReactNode;
-  /** Optional muted line under the title, as on `SectionHeadingTitle`. */
-  description?: string;
-  /** Leading glyph, as on `SectionHeadingTitle`. */
-  icon?: IconName;
-  /** Heading rank. Defaults to 4 — one level under `SubsectionHeadingTitle`'s 3. */
-  level?: HeadingLevel;
-  /** An ⓘ popover after the title, as on the two rungs above. */
-  info?: string;
-}
-
-/**
- * The section title for a surface hosted in a DIALOG — ALWAYS `####` (md semibold), the fourth
- * rung of the same fixed ladder.
- *
- * It exists because `DialogHeaderTitle` is `lg`, which is the rung `SubsectionHeadingTitle`
- * occupies: a dialog holding a multi-section surface has its own title tying with, or being
- * outranked by, its content. The ladder stays ABSOLUTE — this is one more fixed size, never a
- * knob on an existing rung. Do not reach for a `size`/`compact` prop on the titles above; the same
- * rank rendering at two sizes is exactly what the fixed ramp prevents.
- *
- * Compose it with the SUBSECTION layout — `Subsection` › `SubsectionHeading` › this, inside a
- * `SubsectionStack`. Only the type size steps down; the 12px body gap and the 32px between-group
- * beat are already right for a dialog, so duplicating them under a `Dialog*` name would add three
- * exports that differ from their siblings in nothing.
- *
- *   <SubsectionStack divided>
- *     <Subsection>
- *       <SubsectionHeading>
- *         <DialogSectionHeadingTitle info="…">Usage</DialogSectionHeadingTitle>
- *         <SectionHeadingMeta>Aug 2 – Sep 2</SectionHeadingMeta>
- *       </SubsectionHeading>
- *       {body}
- *     </Subsection>
- *   </SubsectionStack>
- */
-export function DialogSectionHeadingTitle(props: DialogSectionHeadingTitleProps) {
-  const { children, description, icon, level = 4, info } = props;
-  const words = useLoticsLocale();
-  return (
-    <View style={{ flex: 1, minWidth: HEADING_TITLE_MIN_WIDTH, gap: 2 }}>
-      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-        {icon ? <Icon name={icon} size={16} /> : null}
-        <Text level={level} size="md" weight="semibold">
-          {children}
-        </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
-      </View>
-      {description ? (
-        <Text color="zinc-500" size="sm">
-          {description}
-        </Text>
-      ) : null}
-    </View>
-  );
-}
-
 export interface SectionHeadingProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
@@ -219,7 +168,15 @@ export interface SectionHeadingTitleProps {
   children: React.ReactNode;
   description?: string;
   icon?: IconName;
-  /** Heading rank. Defaults to 2 — typical for page-level section titles. */
+  /**
+   * Heading rank, when the surface's own outline needs one the altitude does not
+   * give it. Leave it unset: the default is the rank of whichever rung the
+   * altitude selected (`2` on a page, `4` in a panel), so an outline is
+   * correct without anyone thinking about it.
+   *
+   * It does NOT move the type size — the ramp is absolute, and a rank rendering
+   * at two sizes is exactly what a fixed ladder exists to prevent.
+   */
   level?: HeadingLevel;
   /** Title weight. Defaults to `semibold` — a section title must separate from
    * the body rows at a glance (medium blends in; it remains as an opt-down for
@@ -230,21 +187,50 @@ export interface SectionHeadingTitleProps {
   info?: string;
 }
 
-/** The title block — ALWAYS `##` (xl semibold): the heading ramp is the fixed
- * markdown ladder `#` xxl (`RecordSummary`/`PageHeader`) → `##` xl (section) →
- * `###` lg (`SubsectionHeadingTitle`) over the sm body — no per-surface size
- * knobs, one outline everywhere. Optional muted `description` line; grows to
- * push any sibling actions to the right edge. */
+/**
+ * THE SECTION RUNG, per altitude — the two fixed points of one ladder, written
+ * down once.
+ *
+ * On a PAGE the section title is `##` (xl), under the `#` xxl identity band.
+ * Inside a PANEL it is `####` (md), under the container's `lg` chrome title —
+ * the ladder does not gain a knob, it gains a second fixed point, chosen by
+ * where the heading IS rather than by what the caller remembered to pass.
+ *
+ * The glyph steps with the type: a 20px icon beside 16px text is a mark that
+ * outweighs the words it introduces.
+ */
+const SECTION_RUNG = {
+  page: { size: "xl", level: 2, icon: 20 },
+  panel: { size: "md", level: 4, icon: 16 },
+} as const satisfies Record<HeadingAltitude, { size: TextSize; level: HeadingLevel; icon: number }>;
+
+/** The title block — the heading ramp's SECTION rung, on the fixed markdown
+ * ladder `#` xxl (`RecordSummary`/`PageHeader`) → `##` xl (section) → `###` lg
+ * (`SubsectionHeadingTitle`) over the sm body. No size knob: which rung it
+ * renders is decided by the SURFACE, not the call site — `##` xl on a page,
+ * `####` md inside a panel's content region, where the container's own title
+ * is already `lg`. A caller never says which; the container publishes it (see
+ * `heading_altitude.ts`), so the same heading is correct on a page and in a
+ * drawer without being written twice.
+ *
+ * Inside a panel this rung is the ramp's FLOOR — a pane is one surface,
+ * not a document. A named group inside a section there is `Text size="sm"
+ * weight="semibold"`, not a `SubsectionHeadingTitle`, which is `lg` at every
+ * altitude and would out-rank the section holding it.
+ *
+ * Optional muted `description` line; grows to push any sibling actions to the
+ * right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level = 2, weight = "semibold", info } = props;
+  const { children, description, icon, level, weight = "semibold", info } = props;
   // Hoisted — a hook inside the `info ?` ternary breaks hook ordering the
   // render `info` appears or disappears.
   const words = useLoticsLocale();
+  const rung = SECTION_RUNG[useHeadingAltitude()];
   return (
     <View style={{ flex: 1, minWidth: HEADING_TITLE_MIN_WIDTH, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
-        {icon ? <Icon name={icon} size={20} /> : null}
-        <Text level={level} weight={weight} size="xl">
+        {icon ? <Icon name={icon} size={rung.icon} /> : null}
+        <Text level={level ?? rung.level} weight={weight} size={rung.size}>
           {children}
         </Text>
         {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}

package/src/stepper.tsx

@@ -288,9 +288,8 @@ export function Step(props: StepProps) {
                 on the first content row, so there is a `markerTopOffset` band of
                 empty column above it. A single below-the-marker segment cannot
                 reach into the NEXT step's band, so the line broke at every joint
-                — ~4px under each marker (this segment's old top margin) plus the
-                next one's offset above it. Measured on the record template: 4px
-                and 3px, at every stage, which reads as dashes rather than a spine.
+                — a gap under each marker (this segment's old top margin) plus the
+                next one's offset above it, which reads as dashes rather than a spine.
                 The upper segment fills that band, so the line is continuous from
                 the first marker to the last. It also replaces the column's old
                 `paddingTop`, which is why the marker lands in the same place. */}

package/src/summary.tsx

@@ -231,9 +231,9 @@ const styles = StyleSheet.create({
   // 12, and it is half of what a page must put BETWEEN this band and its
   // neighbours. The band's parts are one group — a figure, the shape of what it
   // counts, and that shape's key — so they have to sit closer to each other than
-  // the band sits to the register below it. Measured at 14 against a 16px page
-  // gap, the ratio was 1.14: every block on the screen an equal peer, nothing
-  // grouped, which is what "no rhythm" is when you measure it.
+  // the band sits to the register below it. At near-parity with the page gap
+  // every block on the screen is an equal peer, nothing
+  // grouped, which is what "no rhythm" means.
   root: { gap: 12 },
   header: {
     flexDirection: "row",

package/src/table.tsx

@@ -612,7 +612,10 @@ const styles = StyleSheet.create({
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
   headerBandFilled: {
-    backgroundColor: colors.accent_wash,
+    // The literal neutral, not `accent_wash`: this band is a lid on the columns,
+    // never a "you are here", and reading it through the brand token made a
+    // themed app tint a piece of pure furniture.
+    backgroundColor: colors.zinc[100],
     // The band bleeds to the row wash's width so its edges line up with a hovered
     // row beneath it; without this the lid is narrower than the rows it caps.
     marginHorizontal: -ROW_WASH_BLEED,

package/src/text_utils.ts

@@ -103,10 +103,9 @@ export const inputTextStyleWeb = {
   // THE INK IS PART OF THE CONTRACT, because leaving it out does not mean
   // "inherit" — a native <input> ignores inherited colour and falls to the UA
   // default, PURE BLACK, while every resting value beside it renders `zinc-900`.
-  // So a field's own text changed colour the instant it was focused: measured
-  // rgb(24,24,27) at rest against rgb(0,0,0) editing, on an unremarkable text
-  // field. Nothing moved — which is why box geometry, insets, line boxes, fonts
-  // and five widths all measured identical — but at 14px a darkness change
+  // So a field's own text changed colour the instant it was focused — the
+  // resting ink against the UA's black. Nothing MOVED, which is why every
+  // geometry check came back identical, but at body size a darkness change
   // re-weights the antialiasing of every stroke, and the eye reads that as the
   // text shifting on focus. An EMPTY field hid it completely, since a placeholder
   // sets its own colour and therefore never changed.

package/src/timeline.tsx

@@ -17,10 +17,9 @@ export interface TimelineItem {
   /**
    * The row's identity line — CLAMPED TO TWO LINES, because it is a scan target
    * before it is a sentence. A feed is the one place user-authored prose lands in
-   * a row primitive, and unclamped it eats the section: measured on a real
-   * interaction log, one 700-character summary drew a 180px label — nine lines
-   * for one entry, and the disc, which centres on the label row, ended up 80px
-   * below the first line it was meant to sit beside.
+   * a row primitive, and unclamped it eats the section: one long summary can
+   * draw a label many lines deep, and the disc — which centres on the label row —
+   * ends up far below the first line it was meant to sit beside.
    *
    * The clamp holds while the row is COLLAPSED and lifts when it opens, so a
    * long label is readable in full without being copied anywhere. **Never repeat