@lotics/ui 41.0.1 → 41.3.0

package/src/timeline.tsx

@@ -14,11 +14,55 @@ export interface TimelineItem {
    *  renders a tinted disc of this color; the icon takes the full color. */
   iconColor: string;
   isLoading?: boolean;
+  /**
+   * 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.
+   *
+   * So a label that can run long belongs in `details` as well, in full. The
+   * clamp is the contract rather than a prop: a prop would let the next caller
+   * re-open the same hole, and the whole point is that the row keeps its beat
+   * whatever the caller hands it.
+   */
   label: string;
-  /** An always-visible sub-line under the label (a note, a detail). When set, the
-   *  row top-aligns so `right` sits next to the label, not centred on the block. */
+  /**
+   * The label is a STAND-IN the surface supplied, not a value the record holds —
+   * render it in the placeholder tone the kit uses for an unfilled field.
+   *
+   * A feed fills up from more than one direction: a person writes an entry, but
+   * an automation also drops one the moment a recording lands, and an extraction
+   * files one from a screenshot. Those arrive with no words in them, and a row
+   * whose identity line is `string` forces the caller to invent some — which
+   * then renders in body ink, indistinguishable from a note somebody actually
+   * wrote. "Nobody has written this up" and "this is what happened" must not
+   * look alike; without this flag the type makes them.
+   */
+  placeholder?: boolean;
+  /** An always-visible sub-line under the label (a note, a detail) — clamped to
+   *  two lines, same reason. When set, the row top-aligns so `right` sits next to
+   *  the label, not centred on the block. */
   description?: string;
   error?: string;
+  /**
+   * Trailing content — a duration, a badge, a status. It renders BESIDE the press
+   * target rather than inside it, so an interactive one stays clickable on its
+   * own: nesting a control in the row's own button is invalid HTML (`<button>`
+   * cannot contain `<button>`) and hands one click to two handlers. The chevron
+   * closes the pressable region; `right` sits after it.
+   *
+   * **On a row that EXPANDS, prefer putting verbs in the body instead.** A
+   * control sharing the label row with the press target produced three separate
+   * defects here, and they are not independent: it nested a button in a button,
+   * it needed a fixed-height box of its own to stay on the label's first line,
+   * and it sat close enough to the chevron to read as one cluster with it. All
+   * three exist only because something interactive shares the row. In the body
+   * there is no press target to share with, and the verbs sit next to the
+   * content they act on — where an expansion the reader chose is also the look
+   * before a destructive act. Keep `right` for what it is good at: a fact.
+   */
   right?: ReactNode;
   details?: ReactNode;
 }
@@ -50,20 +94,44 @@ export function Timeline(props: TimelineProps) {
         const isFirst = index === 0;
         const isLast = index === items.length - 1;
 
-        // The label row: label + right + chevron only. Secondary lines
-        // (description/error) render BELOW in the spine band, so the disc can
-        // center against this row whatever its height (a plain 20px label or a
-        // 40px inline control in `right` both align label-on-disc).
+        // The label row: label + chevron only. Secondary lines
+        // (description/error) render BELOW in the spine band.
+        //
+        // Everything in this band aligns to the label's FIRST LINE, never to the
+        // label BLOCK — see FIRST_LINE_CENTRE. That is why the row tops its
+        // children and the chevron carries an offset instead of being centred:
+        // centring matches first-line alignment exactly until a label wraps, and
+        // then quietly stops.
         const row = (
           <View style={styles.row}>
-            <Text size="sm" style={{ flex: 1 }}>{item.label}</Text>
-            {item.right}
+            <Text
+              size="sm"
+              numberOfLines={2}
+              // The same ink an unfilled field draws (`Not set`, `No date set`),
+              // so an unwritten row reads as unwritten everywhere it appears.
+              color={item.placeholder ? "zinc-400" : undefined}
+              style={{ flex: 1 }}
+            >
+              {item.label}
+            </Text>
             {hasDetails ? (
-              <Icon name={expanded ? "chevron-up" : "chevron-down"} size={14} color={colors.zinc[400]} />
+              <View style={styles.onFirstLine}>
+                <Icon name={expanded ? "chevron-up" : "chevron-down"} size={14} color={colors.zinc[400]} />
+              </View>
             ) : null}
           </View>
         );
 
+        // `right` centres inside a first-line-tall box, so a duration, a badge
+        // and a row-action menu all land on the label's first line whatever
+        // their own height, and stay there when the label wraps. Which box
+        // depends on whether it sits inside the row's padding or beside it.
+        const trailing = item.right ? (
+          <View style={hasDetails ? styles.onFirstLineOutdented : styles.onFirstLine}>
+            {item.right}
+          </View>
+        ) : null;
+
         return (
           <View key={item.id}>
             {/* Band 1 — disc beside the label row, vertically CENTERED on it.
@@ -71,7 +139,7 @@ export function Timeline(props: TimelineProps) {
                 through tall rows. */}
             <View style={styles.labelBand}>
               <View style={styles.discColumn}>
-                <View style={styles.halfSpineSlot}>{!isFirst ? <View style={styles.spineFill} /> : null}</View>
+                <View style={styles.spineAbove}>{!isFirst ? <View style={styles.spineFill} /> : null}</View>
                 <AnimationFadeIn key={`${item.id}-${item.icon}`}>
                   {/* Tinted disc: a low-alpha wash of the accent behind a full-color icon. */}
                   <View style={[styles.node, { backgroundColor: withAlpha(item.iconColor, 0.1) }]}>
@@ -82,15 +150,23 @@ export function Timeline(props: TimelineProps) {
                     )}
                   </View>
                 </AnimationFadeIn>
-                <View style={styles.halfSpineSlot}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
+                <View style={styles.spineBelow}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
               </View>
               <View style={styles.rowColumn}>
                 {hasDetails ? (
-                  <PressableHighlight focusRing onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
-                    {row}
-                  </PressableHighlight>
+                  // `right` is a SIBLING of the press target, never a child of
+                  // it — see the prop's doc comment.
+                  <View style={styles.rowSplit}>
+                    <PressableHighlight focusRing onPress={() => toggleItem(item.id)} style={styles.pressableRow}>
+                      {row}
+                    </PressableHighlight>
+                    {trailing}
+                  </View>
                 ) : (
-                  <View style={styles.plainRow}>{row}</View>
+                  <View style={styles.plainRow}>
+                    {row}
+                    {trailing}
+                  </View>
                 )}
               </View>
             </View>
@@ -100,7 +176,7 @@ export function Timeline(props: TimelineProps) {
             <View style={styles.belowBand}>
               <View style={styles.spineColumn}>{!isLast ? <View style={styles.spineFill} /> : null}</View>
               <View style={[styles.belowColumn, isLast && !hasBelow ? styles.belowColumnLast : null]}>
-                {item.description ? <Text size="xs" color="muted">{item.description}</Text> : null}
+                {item.description ? <Text size="xs" color="muted" numberOfLines={2}>{item.description}</Text> : null}
                 {item.error ? (
                   <Text size="xs" color="danger" numberOfLines={1}>{item.error}</Text>
                 ) : null}
@@ -114,19 +190,55 @@ export function Timeline(props: TimelineProps) {
   );
 }
 
+/** Line box of the label (`Text size="sm"`). */
+const LINE_HEIGHT = 20;
+/** The row's vertical padding — also the press target's breathing room. */
+const ROW_PAD_Y = 10;
+/** The disc itself, and the air it keeps around it. */
+const NODE_SIZE = 32;
+const NODE_MARGIN_Y = 3;
+/** The disc's own box — DERIVED, because `spineAbove` is sized by the difference
+ *  between this and the first line. Hand-copied as `38` it drifted the moment
+ *  either number above changed, and the symptom would have been the disc sliding
+ *  off the very line FIRST_LINE_CENTRE exists to hold it on. */
+const NODE_BOX = NODE_SIZE + NODE_MARGIN_Y * 2;
+
+/**
+ * WHERE THE LABEL'S FIRST LINE SITS, measured from the top of the label band —
+ * and the single number every ornament in that band derives from.
+ *
+ * It exists because "centre it on the row" and "put it on the first line" are
+ * the same answer right up until a label wraps, and then they are 10px apart,
+ * silently: the disc slides to the middle of the pair while the one-line rows
+ * beside it stay put, and the column stops being a column. Only the wrapped rows
+ * are wrong, so nothing about the screen says which number is the mistake.
+ *
+ * Every ornament reads this instead of picking its own — the disc, the chevron,
+ * and whatever a caller puts in `right`.
+ */
+const FIRST_LINE_CENTRE = ROW_PAD_Y + LINE_HEIGHT / 2;
+
 const styles = StyleSheet.create({
   labelBand: {
     flexDirection: "row",
     gap: 12,
   },
-  // Stretches to the label row's height; the disc centers on it, half-spines
-  // fill the remainder so the line never breaks on a tall row.
+  // Stretches to the label row's height so the spine below the disc can fill it;
+  // the disc itself is PINNED to the first line rather than centred on the block
+  // (see FIRST_LINE_CENTRE).
   discColumn: {
     width: 32,
     alignSelf: "stretch",
     alignItems: "center",
   },
-  halfSpineSlot: {
+  // A fixed sliver above the disc puts its centre on the label's first line; the
+  // slot below flexes, so the spine still reaches the bottom of a tall row.
+  spineAbove: {
+    height: FIRST_LINE_CENTRE - NODE_BOX / 2,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  spineBelow: {
     flex: 1,
     alignItems: "center",
     justifyContent: "center",
@@ -138,12 +250,12 @@ const styles = StyleSheet.create({
     backgroundColor: colors.zinc[200],
   },
   node: {
-    width: 32,
-    height: 32,
-    borderRadius: 16,
+    width: NODE_SIZE,
+    height: NODE_SIZE,
+    borderRadius: NODE_SIZE / 2,
     justifyContent: "center",
     alignItems: "center",
-    marginVertical: 3,
+    marginVertical: NODE_MARGIN_Y,
   },
   rowColumn: {
     flex: 1,
@@ -167,31 +279,79 @@ const styles = StyleSheet.create({
   },
   row: {
     flexDirection: "row",
-    alignItems: "center",
+    // TOP, not centre — the whole band aligns to the first line.
+    alignItems: "flex-start",
     gap: 10,
     flex: 1,
   },
-  // The press target for expandable rows; pressable rows bleed the hover wash
-  // past the text column.
+  // Centres its content on the first line, for anything INSIDE the row's padding
+  // — the chevron, and `right` on a row that is not a press target.
+  //
+  // `height`, never `minHeight`. A floor lets the box GROW to whatever the
+  // caller passed, and a grown box centres its content on its own new middle
+  // rather than on the line: against these numbers a 28px `ActionMenu` in a
+  // plain row's `right` lands 4px low and a 40px control 10px low, while a 16px
+  // duration — the only `right` in the kit's own examples — sits perfectly,
+  // which is exactly how a defect like this survives review. A FIXED box
+  // overflows symmetrically instead (a View does not clip), so the content's
+  // centre stays pinned whatever its size.
+  onFirstLine: {
+    height: LINE_HEIGHT,
+    justifyContent: "center",
+  },
+  // The same job for `right` on an EXPANDABLE row, where it sits outside the
+  // press target and so does not inherit that padding. Two styles rather than
+  // one because the difference is real: same target line, different origin.
+  onFirstLineOutdented: {
+    height: FIRST_LINE_CENTRE * 2,
+    justifyContent: "center",
+  },
+  // Holds the press target and `right` side by side, so the wash marks exactly
+  // what a press acts on. The 8px BLEED lives here rather than on the pressable:
+  // owned by the child it would push `right` into the gap, and a wash sliding
+  // under a control is how a row action stops being visible at the moment the
+  // pointer reaches it.
+  rowSplit: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    // WIDER than the gap INSIDE the press target (10), because these are not
+    // peers: the chevron belongs to the row's own button, `right` does not. At 4
+    // the two sat 12px apart against the chevron's 10 — near enough to 1:1 that
+    // the eye read them as one cluster, with only a 4px break in the hover wash
+    // saying otherwise, which a reader who never hovers never sees. 20 against
+    // 10 is the ratio that makes them two things.
+    gap: 12,
+    marginHorizontal: -8,
+  },
+  // The press target for expandable rows; the horizontal padding puts the label
+  // back on the column's own left edge, which the bleed above moved off it.
+  //
+  // There is no `minHeight` any more, and none is missing: `ROW_PAD_Y` on both
+  // sides of one line IS the 40px touch target, so the two can no longer
+  // disagree. A floor above the content was also what made this row centre its
+  // children in slack it owned — the drift FIRST_LINE_CENTRE exists to remove.
   pressableRow: {
+    flex: 1,
     borderRadius: 8,
     paddingHorizontal: 8,
-    paddingVertical: 4,
-    marginHorizontal: -8,
-    minHeight: 40,
+    paddingVertical: ROW_PAD_Y,
     flexDirection: "row",
-    alignItems: "center",
+    alignItems: "flex-start",
   },
   plainRow: {
-    paddingVertical: 4,
-    minHeight: 40,
+    paddingVertical: ROW_PAD_Y,
     flexDirection: "row",
-    alignItems: "center",
+    alignItems: "flex-start",
+    gap: 10,
   },
+  // NO left padding. It was 2, which put a row's body 2px right of the
+  // description line directly above it — one column of text at two left edges,
+  // small enough to read as sloppiness rather than as a defect, and the reason a
+  // reader cannot say what is wrong with a screen that measures fine everywhere
+  // else. An indent is legitimate only when something VISIBLE occupies it.
   detailsContainer: {
     gap: 8,
     paddingTop: 8,
-    paddingLeft: 2,
   },
 });