@lotics/ui 47.6.0 → 47.7.0

package/src/cell_stack.tsx

@@ -0,0 +1,140 @@
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { type ReactNode } from "react";
+import { Text, type TextSize } from "./text";
+import { type TextColor } from "./text_ink";
+
+export interface CellStackProps {
+  /** The subject — what this cell is ABOUT. */
+  title: ReactNode;
+  /**
+   * The ONE line that qualifies the subject. Omit for a lone value.
+   *
+   * One, not several: a stack of three is no longer a value and its annotation,
+   * it is a row that wants to be a row.
+   */
+  caption?: ReactNode;
+  /**
+   * Subject weight. `medium` is itself a channel of demotion between the two
+   * lines, so it decides the caption's rung — see the class doc.
+   */
+  weight?: "regular" | "medium" | "semibold";
+  /**
+   * Set when the cell opens with an identity mark the CALLER draws (an avatar, a
+   * status dot, a file badge). A mark separates the pair exactly as `medium`
+   * does, so the caption keeps body size beside one.
+   */
+  marked?: boolean;
+  /** The subject's rung. The pair takes ONE rung, so the caption follows it. */
+  size?: TextSize;
+  /** The subject's ink. The caption is always `muted` — it is supporting text. */
+  color?: TextColor;
+  /** Fixed-width numerals on BOTH lines, so a column of figures lines up. */
+  tabular?: boolean;
+  align?: "left" | "right" | "center";
+  /** Clamp each line. A register cell almost always wants 1. */
+  numberOfLines?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/**
+ * A SUBJECT over one qualifying line — the commonest cell in any register, and
+ * the one shape the kit stated as a law and never shipped as a part.
+ *
+ * The rule lives in `docs/composition.md` §Typography and it has three moving
+ * pieces that have to agree; every hand-roll got at least one wrong, and the
+ * failure is invisible to every spacing probe because the excess height comes
+ * from the LINE BOX, so no margin and no gap appears anywhere to explain it.
+ * One app carried nine copies drifted three ways — 44px of stack around 26px of
+ * type, a ratio of 1.69, across three different gaps.
+ *
+ * **1. The caption's rung is decided by what ELSE separates the pair**, never by
+ * what the line carries. `color="muted"` is already one channel of demotion, so
+ * a size step is a second, and a second is only worth its cost where nothing
+ * else is doing the job. A `medium` subject or a leading identity mark separates
+ * the pair on its own, so the caption stays at body size — which matters most
+ * where that line is the DISAMBIGUATOR (which person, at which company), since
+ * `xs` demotes content the reader needs and 12px is where stacked diacritics
+ * crowd. With both lines regular and colour the only thing between them, the
+ * caption drops to `xs` or the two read as peers.
+ *
+ * **2. Both body-rung lines take `leading="tight"`.** The ramp's body rungs
+ * carry PROSE leading, right for a paragraph and wrong for two lines that are
+ * one object: it leaves ~10px of empty box between them. Where the caption is
+ * already `xs` it is already tight, so only the subject carries the prop.
+ *
+ * **3. The stack's `gap` is 0.** Each tight line box contributes 3px above and
+ * below, which is the 6px the pair wants; a `gap` on top is a third source of
+ * space between lines meant to read as one.
+ *
+ * A LONE line is deliberately NOT tightened. Tight leading is what closes a
+ * PAIR up; applied to a single line it just sits oddly against the prose around
+ * it, and there is no second line for it to be close to.
+ *
+ * A caption passed as a NODE keeps its own leading and ink — forcing either on
+ * somebody else's subtree would silently re-space something that is not a line
+ * of text at all.
+ */
+export function CellStack(props: CellStackProps) {
+  const {
+    title,
+    caption,
+    weight = "regular",
+    marked = false,
+    size = "sm",
+    color,
+    tabular,
+    align = "left",
+    numberOfLines,
+    style,
+    testID,
+  } = props;
+
+  const hasCaption = caption !== undefined && caption !== null && caption !== false;
+  // Rule 1 — the caption's rung, from what else is already separating the pair.
+  const captionSize: TextSize = weight !== "regular" || marked ? size : "xs";
+  // Rule 2 — tight closes a PAIR; `xs` is tight by construction, and a lone line
+  // has nothing to close up to.
+  const subjectTight = hasCaption ? "tight" : undefined;
+  const captionTight = captionSize === "xs" ? undefined : "tight";
+
+  return (
+    <View style={[{ gap: 0, alignItems: ALIGN[align] }, style]} testID={testID}>
+      {typeof title === "string" || typeof title === "number" ? (
+        <Text
+          size={size}
+          weight={weight}
+          color={color}
+          leading={subjectTight}
+          tabular={tabular}
+          numberOfLines={numberOfLines}
+        >
+          {title}
+        </Text>
+      ) : (
+        title
+      )}
+      {hasCaption
+        ? typeof caption === "string" || typeof caption === "number"
+          ? (
+            <Text
+              size={captionSize}
+              color="muted"
+              leading={captionTight}
+              tabular={tabular}
+              numberOfLines={numberOfLines}
+            >
+              {caption}
+            </Text>
+          )
+          : caption
+        : null}
+    </View>
+  );
+}
+
+const ALIGN = {
+  left: "flex-start",
+  right: "flex-end",
+  center: "center",
+} as const satisfies Record<"left" | "right" | "center", ViewStyle["alignItems"]>;

package/src/column_filter.tsx

@@ -137,7 +137,7 @@ export function ColumnFilter(props: ColumnFilterProps) {
                 onChange({ kind: "number", min, max: value?.kind === "number" ? value.max : null })
               }
             />
-            <Text size="sm" color="zinc-500">
+            <Text size="sm" color="muted">
               –
             </Text>
             <NumberInput

package/src/combobox.tsx

@@ -483,7 +483,7 @@ export function ComboboxContent(props: ComboboxContentProps) {
         <View style={styles.menu}>
           {showRecentsHeader ? (
             <View style={styles.sectionHeader}>
-              <Text size="xs" weight="medium" color="zinc-500">
+              <Text size="xs" weight="medium" color="muted">
                 {recentsLabel}
               </Text>
             </View>
@@ -506,7 +506,7 @@ export function ComboboxContent(props: ComboboxContentProps) {
               list.searching ? (
                 emptyEl ?? (
                   <View style={styles.statusRow}>
-                    <Text size="sm" color="zinc-500">
+                    <Text size="sm" color="muted">
                       {emptyText}
                     </Text>
                   </View>

package/src/comments_thread.tsx

@@ -211,7 +211,7 @@ function CommentRow(props: CommentRowProps) {
         </View>
         <View style={{ flex: 1 }}>
           <Text weight="medium">{displayName}</Text>
-          <Text size="sm" color="zinc-500">
+          <Text size="sm" color="muted">
             {formatTimestamp(comment.created_at)}
             {comment.updated_at !== comment.created_at ? ` (${labels.edited})` : ""}
           </Text>
@@ -292,7 +292,7 @@ export function CommentList(props: CommentListProps) {
   );
 
   if (sorted.length === 0) {
-    return <>{props.emptyState ?? <Text color="zinc-500">{labels.empty}</Text>}</>;
+    return <>{props.emptyState ?? <Text color="muted">{labels.empty}</Text>}</>;
   }
 
   return (

package/src/count.tsx

@@ -34,7 +34,7 @@ export function Count(props: CountProps) {
         size="xs"
         weight="medium"
         tabular
-        color={color === "muted" ? "zinc-500" : "inverted"}
+        color={color === "muted" ? "muted" : "onInverse"}
         userSelect="none"
       >
         {count}

package/src/date_calendar.tsx

@@ -74,7 +74,7 @@ function DayCell(props: {
         >
           <Text
             size="sm"
-            color={props.isActive ? "inverted" : "default"}
+            color={props.isActive ? "onInverse" : "default"}
             userSelect="none"
             weight={props.isToday ? "semibold" : "regular"}
           >
@@ -436,7 +436,7 @@ function CalendarMonth(props: CalendarMonthProps) {
       <View style={styles.weekHeader}>
         {daysOfWeekLabels.map((day) => (
           <View key={day} style={styles.dayHeaderCell}>
-            <Text size="xs" color="zinc-500">
+            <Text size="xs" color="muted">
               {day}
             </Text>
           </View>

package/src/date_filter.tsx

@@ -96,7 +96,7 @@ function RangeBound(props: {
   const { label, placeholder, bound, includeTime, localeTag, onTimeChange } = props;
   return (
     <View style={styles.rangeItem}>
-      <Text size="xs" color="zinc-500">
+      <Text size="xs" color="muted">
         {label}
       </Text>
       <Text size="sm" weight="medium" color={bound.date ? "default" : "muted"}>

package/src/diff_value.tsx

@@ -2,7 +2,7 @@ import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
 import { type ReactNode } from "react";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { type TextColor } from "./text_utils";
+import { type TextColor } from "./text_ink";
 
 /**
  * A VALUE THAT CHANGED — the atom of every review surface.
@@ -172,7 +172,7 @@ export function DiffValue(props: DiffValueProps) {
       // zinc-600 — pixel-identical to the field LABEL beside it, so the one word
       // saying a value is being deleted read as chrome. It describes an absence,
       // so it sits below the label rather than level with it.
-      color={hasAfter ? TONE[tone] : "zinc-400"}
+      color={hasAfter ? TONE[tone] : "inactive"}
       weight={hasAfter ? "medium" : "regular"}
       tabular={tabular}
       numberOfLines={1}

package/src/eyebrow.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import { Text } from "./text";
-import type { TextColor } from "./text_utils";
+import type { TextColor } from "./text_ink";
 
 export interface EyebrowProps {
   children?: React.ReactNode;

package/src/file_thumbnail.tsx

@@ -420,7 +420,7 @@ export function DocumentCard(props: DocumentCardProps) {
       {...focusProps}
     >
       <FileBadge mimeType={mimeType} size={badgeSize} isTemplate={isTemplate} />
-      <Text size="xs" numberOfLines={1} color="zinc-500" style={styles.documentTileName} userSelect="none">
+      <Text size="xs" numberOfLines={1} color="muted" style={styles.documentTileName} userSelect="none">
         {filename}
       </Text>
       {overlay}
@@ -491,7 +491,7 @@ export function MediaCard(props: MediaCardProps) {
             </View>
           </View>
           <View style={styles.documentCardFooter}>
-            <Text size="xs" numberOfLines={1} color="zinc-500" userSelect="none">
+            <Text size="xs" numberOfLines={1} color="muted" userSelect="none">
               {filename}
             </Text>
             <View style={[styles.typeLabel, { backgroundColor: color }]}>

package/src/file_thumbnail_grid.tsx

@@ -219,7 +219,7 @@ function OverflowTile({ size, count, onPress }: { size: number; count: number; o
   const box = { width: size, height: size, borderRadius: compact ? 7 : 10 };
   const { focusVisible, focusProps } = useFocusRing();
   const label = (
-    <Text size={compact ? "xs" : "sm"} weight="medium" color="zinc-700" userSelect="none">
+    <Text size={compact ? "xs" : "sm"} weight="medium" color="muted" userSelect="none">
       +{count}
     </Text>
   );

package/src/filter_band.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, useState, type ReactNode } from "react";
+import { Children, createContext, useContext, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { Button } from "./button";
 import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea } from "./dialog";
@@ -58,6 +58,14 @@ export function FilterBand(props: FilterBandProps) {
   const t = useLoticsLocale().filterBand;
   const { small } = useScreenSize();
   const [open, setOpen] = useState(false);
+  // WHETHER THERE IS ANYTHING TO COLLAPSE. `Children.toArray` drops the nulls a
+  // caller renders for a facet that has nothing to offer — a status filter whose
+  // options are all in view, a round picker before any round is recorded — so a
+  // band that draws no chips wide must not draw a button narrow. It did: the wide
+  // branch renders `children` and gets nothing, the narrow one rendered the
+  // trigger unconditionally, and the two presentations stopped agreeing at exactly
+  // the width where a control that opens an empty sheet costs the most.
+  const hasFilters = Children.toArray(children).length > 0;
 
   if (!small) {
     return (
@@ -77,14 +85,16 @@ export function FilterBand(props: FilterBandProps) {
   return (
     <View testID={testID} style={{ flexDirection: "row", alignItems: "center", gap: SPACE.sm }}>
       {search != null && <View style={{ flexGrow: 1, flexShrink: 1, minWidth: 0 }}>{search}</View>}
-      <Button
-        color="secondary"
-        title={activeCount > 0 ? `${t.filters} (${activeCount})` : t.filters}
-        onPress={() => setOpen(true)}
-        testID={testID ? `${testID}-filters` : undefined}
-      />
+      {hasFilters && (
+        <Button
+          color="secondary"
+          title={activeCount > 0 ? `${t.filters} (${activeCount})` : t.filters}
+          onPress={() => setOpen(true)}
+          testID={testID ? `${testID}-filters` : undefined}
+        />
+      )}
       {action}
-      <Dialog open={open} onOpenChange={setOpen} width="92%" maxWidth={520}>
+      <Dialog open={open && hasFilters} onOpenChange={setOpen} width="92%" maxWidth={520}>
         <DialogHeader>
           <DialogHeaderTitle>{t.filters}</DialogHeaderTitle>
         </DialogHeader>

package/src/filter_chip.tsx

@@ -127,7 +127,10 @@ export function FilterChip(props: FilterChipProps) {
           aria-expanded={isOpen}
           style={styles.rowHeader}
         >
-          <Text size="sm" weight="medium" color="zinc-700">{label}</Text>
+          {/* `muted`, not the retired `zinc-700`. This row's LABEL names the facet and
+              the summary beside it carries the accent — a label at full ink would
+              compete with the value it introduces. */}
+          <Text size="sm" weight="medium" color="muted">{label}</Text>
           <View style={styles.rowRight}>
             {active ? (
               typeof summary === "string" ? (
@@ -171,7 +174,7 @@ export function FilterChip(props: FilterChipProps) {
               // to answer "is anything on?" from across the screen, and ink is the
               // only channel that carries at that distance. It is a state, not
               // decoration, which is what makes it a legitimate place for brand.
-              color={active ? undefined : "zinc-700"}
+              color={active ? undefined : "muted"}
               style={active ? { color: colors.accent } : undefined}
               numberOfLines={1}
             >

package/src/finding.tsx

@@ -4,6 +4,7 @@ import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { useLoticsLocale } from "./locale";
 import { solid, type ColorName } from "./colors";
+import { useContainerSize } from "./size_boundary";
 
 export type FindingSeverity = "critical" | "warning" | "info" | "positive";
 
@@ -111,6 +112,15 @@ export interface FindingProps {
 export function Finding(props: FindingProps) {
   const words = useLoticsLocale().finding;
   const readings = props.readings ?? [];
+  // The headline STACKS where the row is narrow. Side by side, a title long
+  // enough to wrap breaks AROUND the figure and the sentence reads as two
+  // fragments with a number interposed. It never overflows — it only wraps
+  // mid-sentence — so every clipping probe passes, and at desk width the title
+  // does not wrap at all, which is why the defect is invisible at the width most
+  // reviews measure. The trade recorded below (a clipped delta is worse than a
+  // wrapped title) is about CLIPPING and still holds; stacking honours it, since
+  // a stacked figure is never clipped either.
+  const stacked = useContainerSize().small;
 
   return (
     <View style={[styles.root, props.style]}>
@@ -120,8 +130,8 @@ export function Finding(props: FindingProps) {
       />
 
       <View style={styles.body}>
-        <View style={styles.headline}>
-          <Text size="sm" weight="medium" style={styles.title}>
+        <View style={stacked ? styles.headlineStacked : styles.headline}>
+          <Text size="sm" weight="medium" style={stacked ? styles.titleStacked : styles.title}>
             {props.title}
           </Text>
           {props.delta ? (
@@ -207,7 +217,14 @@ const styles = StyleSheet.create({
   dot: { width: DOT, height: DOT, borderRadius: DOT / 2, marginTop: TITLE_INSET + (TITLE_LINE - DOT) / 2 },
   body: { flex: 1, gap: 3, minWidth: 0 },
   headline: { flexDirection: "row", alignItems: "baseline", gap: 12 },
+  // The narrow fork: the title owns its own lines, the figure sits under them on
+  // the same left edge as the dot's row — the scan becomes top-to-bottom, which
+  // is what a phone reads anyway.
+  headlineStacked: { flexDirection: "column", alignItems: "flex-start", gap: 3 },
   title: { flex: 1, minWidth: 0 },
+  // `flex: 1` in a COLUMN grows the box vertically, not horizontally, so the
+  // stacked title takes width the other way.
+  titleStacked: { alignSelf: "stretch", minWidth: 0 },
   // Never shrinks: the figure is the point of the row, and a clipped delta is
   // worse than a title that wraps. Its COLOUR is the severity's, set on the
   // instance — the dot marks the left edge and the figure the right, so a

package/src/form_field.tsx

@@ -84,7 +84,7 @@ export function FormField(props: FormFieldProps & { children: React.ReactNode })
             </Text>
           )}
           {!!optional && (
-            <Text numberOfLines={1} size="sm" color="zinc-500">
+            <Text numberOfLines={1} size="sm" color="muted">
               {resolvedOptionalLabel}
             </Text>
           )}

package/src/inline_date_picker.tsx

@@ -10,7 +10,7 @@ import { isoHasTime, resolveDateCommit } from "./date_picker_value";
 import { formatDate } from "./format_date";
 import { ActivityIndicator } from "./activity_indicator";
 import { type InlineEditVariant, InlineEditView } from "./inline_edit";
-import { type TextColor } from "./text_utils";
+import { type TextColor } from "./text_ink";
 import { useLoticsLocale, useLocaleTag } from "./locale";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";

package/src/inline_edit.tsx

@@ -7,7 +7,8 @@ import { ActivityIndicator } from "./activity_indicator";
 import { FocusRingPressable } from "./focus_ring_pressable";
 import { colors } from "./colors";
 import { FOCUS_RING, CONTROL_RADIUS, CONTROL_PADDING_V, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
-import { fontFamilyRegular, getInputTextStyle, INPUT_LETTER_SPACING, getMultilineInputHeight, getTextColor, type TextColor } from "./text_utils";
+import { fontFamilyRegular, getInputTextStyle, INPUT_LETTER_SPACING, getMultilineInputHeight } from "./text_utils";
+import { getTextColor, type TextColor } from "./text_ink";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
 import { trackCommit } from "./pending_commits";

package/src/line_chart.tsx

@@ -208,8 +208,10 @@ export function LineChart(props: LineChartProps) {
 }
 
 const styles = StyleSheet.create({
+  // Content-sized, for the reason written out on `BarChart.chartContainer`: a
+  // `flex: 1` root resolves to a zero basis inside the vertical stack a card body
+  // is, and the chart then paints outside it.
   chartContainer: {
-    flex: 1,
     justifyContent: "center",
     paddingVertical: 8,
   },

package/src/list_item.tsx

@@ -79,7 +79,7 @@ export function ListItem(props: ListItemProps) {
         )}
         {!!description &&
           (typeof description === "string" ? (
-            <Text size="sm" color="zinc-500" leading="tight" numberOfLines={1} userSelect="none">
+            <Text size="sm" color="muted" leading="tight" numberOfLines={1} userSelect="none">
               {description}
             </Text>
           ) : (

package/src/loading.tsx

@@ -1,6 +1,6 @@
 import { Container } from "./container";
 import { DotsIndicator } from "./dots_indicator";
-import { getTextColor } from "./text_utils";
+import { getTextColor } from "./text_ink";
 import { View } from "react-native";
 
 export function Loading() {

package/src/matrix.tsx

@@ -213,7 +213,7 @@ function MatrixCell({ ctx, display, row, col, value }: MatrixCellProps) {
   const label = `${row.label}, ${col.label}: ${formatValue(value)}`;
 
   const content = showNumber ? (
-    <Text size="sm" weight="medium" tabular align="right" color={value === 0 ? "zinc-500" : "default"}>
+    <Text size="sm" weight="medium" tabular align="right" color={value === 0 ? "muted" : "default"}>
       {value === 0 ? "" : formatValue(value)}
     </Text>
   ) : null;

package/src/member_chip.tsx

@@ -129,7 +129,7 @@ export function MemberChip({
           // supporting line except by colour.
           weight="medium"
           leading={pairLeading}
-          color={inactive ? "zinc-500" : undefined}
+          color={inactive ? "muted" : undefined}
           numberOfLines={1}
         >
           {displayName}

package/src/member_profile_card.tsx

@@ -174,7 +174,7 @@ export function MemberProfileCard(props: MemberProfileCardProps) {
               size it was separated from its own identity line by WEIGHT alone,
               which is a separate font file rather than a step, and the surface
               measured 1.17x — flatter than a register with no page band. */}
-          <Text {...SUBJECT} color={inactive ? "zinc-500" : undefined} numberOfLines={2}>
+          <Text {...SUBJECT} color={inactive ? "muted" : undefined} numberOfLines={2}>
             {displayName}
           </Text>
           {identityText ? (

package/src/menu_list_item.tsx

@@ -5,7 +5,7 @@ import { colors } from "./colors";
 import { CONTROL_RADIUS } from "./control_surface";
 import { Icon, IconName } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
-import type { TextColor } from "./text_utils";
+import type { TextColor } from "./text_ink";
 
 export interface MenuListItemProps {
   ref?: Ref<View>;
@@ -77,7 +77,7 @@ export function MenuListItem(props: MenuListItemProps) {
           title
         )}
         {!!description && (
-          <Text size="xs" color="zinc-500" numberOfLines={1} userSelect="none">
+          <Text size="xs" color="muted" numberOfLines={1} userSelect="none">
             {description}
           </Text>
         )}

package/src/metric.tsx

@@ -1,7 +1,7 @@
 import { View, StyleSheet, type TextStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { getTextColor } from "./text_utils";
+import { getTextColor } from "./text_ink";
 import { formatCompactNumber, formatMoney } from "./format_money";
 import { useMemo } from "react";
 

package/src/option_list.tsx

@@ -141,7 +141,7 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
           </View>
         ) : list.rows.length === 0 ? (
           <View style={styles.statusRow}>
-            <Text color="zinc-500" size="sm">
+            <Text color="muted" size="sm">
               {emptyText}
             </Text>
           </View>

package/src/page_header.tsx

@@ -1,6 +1,5 @@
 import { View } from "react-native";
 import { Text } from "@lotics/ui/text";
-import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
 
 interface PageHeaderProps {
@@ -62,28 +61,36 @@ export function PageHeader(props: PageHeaderProps) {
     <View
       style={{
         flexDirection: "row",
-        alignItems: "center",
+        // Top-aligned once a description makes the title block taller than the
+        // verbs; centring would hang them off the middle of a two-line column.
+        alignItems: description ? "flex-start" : "center",
         flexWrap: "wrap",
         gap: 12,
       }}
     >
-      <View
-        style={{
-          flexDirection: "row",
-          alignItems: "center",
-          gap: 8,
-          flexShrink: 1,
-          minWidth: 0,
-        }}
-      >
-        {!!title && (
-          <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
-            {title}
-          </Text>
-        )}
-        {/* Never shrinks: the title is what gives way, and a control squeezed
-            below its own icon is not a smaller control, it is a broken one. */}
-        {trailing !== undefined && <View style={{ flexShrink: 0 }}>{trailing}</View>}
+      {/* THE DESCRIPTION RIDES THE TITLE, because it explains the title.
+          It used to render after the whole title row — and that row wraps, so at
+          a narrow width `actions` dropped to their own line and the reading order
+          became title → verbs → the sentence explaining them. That made `actions`
+          unusable on any header carrying a description, and the caller's only
+          recourse was to hand-roll a second toolbar row and pay for it in
+          vertical space at every width.
+
+          The title is OPTIONAL here: the shell delegates to this component for a
+          band that carries only a description, so an absent title must render
+          nothing rather than an empty heading line. */}
+      <View style={{ flexShrink: 1, minWidth: 0, gap: 4 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          {!!title && (
+            <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
+              {title}
+            </Text>
+          )}
+          {/* Never shrinks: the title is what gives way, and a control squeezed
+              below its own icon is not a smaller control, it is a broken one. */}
+          {trailing !== undefined && <View style={{ flexShrink: 0 }}>{trailing}</View>}
+        </View>
+        {!!description && <Text color="muted">{description}</Text>}
       </View>
       {/* Wrapped so which side gives way is STATED rather than left to whatever
           the caller happened to pass. A bare `{actions}` inherited its own
@@ -148,12 +155,6 @@ export function PageHeader(props: PageHeaderProps) {
       ) : (
         titleRow
       )}
-      {!!description && (
-        <>
-          {!!title && <Spacer size={8} />}
-          <Text color="zinc-500">{description}</Text>
-        </>
-      )}
     </View>
   );
 }

package/src/pagination.tsx

@@ -87,7 +87,7 @@ export function Pagination(props: PaginationProps): React.ReactNode {
   return (
     <View style={styles.container}>
       <View style={styles.summary}>
-        <Text size="sm" color="zinc-500">
+        <Text size="sm" color="muted">
           {summary}
         </Text>
       </View>

package/src/pie_chart.tsx

@@ -149,7 +149,7 @@ export function PieChart(props: PieChartProps) {
                     {item.label}
                   </Text>
                   <Text size="sm" tabular style={styles.legendValue}>{formatNumber(item.value)}</Text>
-                  <Text size="sm" color="zinc-500" tabular style={styles.legendPercentage}>
+                  <Text size="sm" color="muted" tabular style={styles.legendPercentage}>
                     {percentage.toFixed(0)}%
                   </Text>
                 </View>
@@ -163,8 +163,10 @@ export function PieChart(props: PieChartProps) {
 }
 
 const styles = StyleSheet.create({
+  // Content-sized, for the reason written out on `BarChart.chartContainer`: a
+  // `flex: 1` root resolves to a zero basis inside the vertical stack a card body
+  // is, and the chart then paints outside it.
   chartContainer: {
-    flex: 1,
     justifyContent: "center",
   },
   chartWrapper: {