@leavepulse/ui 0.68.0 → 0.70.0

package/src/components/format.ts

@@ -0,0 +1,136 @@
+/*
+ * Numbers as the kit prints them: byte sizes (a file tree's size column, a
+ * quota's "4.2 GB of 5 GB") and compact figures (a chart's axis ticks, a
+ * counter's "1.2k"). One module so the size column and the quota bar agree on
+ * units and rounding, and so the axis and the counter cross a million the same
+ * way. Pure, so the edge cases are tested without a DOM.
+ */
+
+/*
+ * Building an Intl formatter costs far more than using one, and a file tree
+ * formats a size on every row, so each distinct setup is built once.
+ */
+const numberFormats = new Map<string, Intl.NumberFormat>()
+
+function numberFormat(locale: string | undefined, options: Intl.NumberFormatOptions): Intl.NumberFormat {
+  const key = `${locale ?? ""}|${JSON.stringify(options)}`
+  let format = numberFormats.get(key)
+  if (!format) {
+    format = new Intl.NumberFormat(locale, options)
+    numberFormats.set(key, format)
+  }
+  return format
+}
+
+const BYTE_UNITS = ["byte", "kilobyte", "megabyte", "gigabyte", "terabyte", "petabyte"] as const
+
+export interface FormatBytesOptions {
+  /**
+   * Keep the decimal place a value under 10 gets even when it is zero
+   * ("1.0 MB" rather than "1 MB"), so a column of sizes keeps one shape.
+   */
+  fixed?: boolean
+}
+
+/**
+ * A byte count in the largest unit that keeps it readable: 1 536 → "1.5 kB".
+ * Binary steps, the way file managers and storage limits show sizes. Unit
+ * names come from Intl, so a Russian app reads "1,5 МБ" without a table of
+ * its own. One decimal under 10 (2.4 MB), none above (240 MB). Negative or
+ * non-finite input is "—": there is no size to show.
+ */
+export function formatBytes(bytes: number, locale?: string, options: FormatBytesOptions = {}): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "—"
+  let scaled = bytes
+  let step = 0
+  // Compared as it will print, so 1 048 575 B is "1.0 MB", not "1024 kB".
+  while (Math.round(scaled) >= 1024 && step < BYTE_UNITS.length - 1) {
+    scaled /= 1024
+    step += 1
+  }
+  // Decided on the rounded value: 9.96 kB prints as "10 kB", not "10.0 kB".
+  const places = step > 0 && Number(scaled.toFixed(1)) < 10 ? 1 : 0
+  // The number and the unit symbol are assembled here rather than taken whole:
+  // Intl's "short" form spells the smallest unit out ("1023 byte", "1023 Byte")
+  // while every other unit is a symbol, and its "narrow" form glues English
+  // symbols to the figure ("1023B"). Narrow symbols with one no-break space
+  // read the same in every locale: "1023 B", "1.5 kB", "1,5 МБ".
+  const parts = numberFormat(locale, {
+    style: "unit",
+    unit: BYTE_UNITS[step],
+    unitDisplay: "narrow",
+    // A figure here never passes 1023 below petabytes, and "1,023 kB" reads as
+    // a decimal in half the world.
+    useGrouping: false,
+    minimumFractionDigits: options.fixed ? places : 0,
+    maximumFractionDigits: places,
+  }).formatToParts(scaled)
+  const unit = parts.filter((p) => p.type === "unit").map((p) => p.value).join("")
+  const figure = parts.filter((p) => p.type !== "unit" && p.type !== "literal").map((p) => p.value).join("")
+  return unit ? `${figure}\u00a0${unit}` : figure
+}
+
+const COMPACT_UNITS: readonly (readonly [number, string])[] = [
+  [1, ""],
+  [1e3, "k"],
+  [1e6, "M"],
+  [1e9, "B"],
+  [1e12, "T"],
+]
+
+export interface CompactNumberOptions {
+  /**
+   * Writes the decimal separator the locale's way ("1,2k" in Russian). The
+   * k/M/B/T suffixes stay: Intl's own compact notation changes the shape of
+   * the figure per locale ("1,2 тыс."), which a tick label or a rolling
+   * counter cannot absorb. Unset keeps a plain "." whatever the browser says.
+   */
+  locale?: string
+  /** Places for a figure below a thousand (12.25). Default 2. */
+  plainDecimals?: number
+  /** Places once a unit is in play (1.2k). Default 1. */
+  decimals?: number
+  /**
+   * Keep trailing zeros ("5.0M", "1.0k") so the figure's shape only changes
+   * at a rollover. Off, they are dropped ("5M"), the way a label is written.
+   */
+  fixed?: boolean
+}
+
+/**
+ * A figure shortened with k/M/B/T: 1 200 → "1.2k", 3 400 000 → "3.4M".
+ *
+ * The unit is picked by what will PRINT, not by the raw size: 999 950 at one
+ * place rounds to "1000k", which reads as the next unit up, so it becomes
+ * "1M"; 999.999 with two places would be "1000", so it becomes "1k".
+ */
+export function compactNumber(value: number, options: CompactNumberOptions = {}): string {
+  if (!Number.isFinite(value)) return String(value)
+  const { locale, plainDecimals = 2, decimals = 1, fixed = false } = options
+  const abs = Math.abs(value)
+  let i = COMPACT_UNITS.length - 1
+  while (i > 0 && abs < COMPACT_UNITS[i][0]) i--
+
+  const placesAt = (at: number) => (at === 0 ? plainDecimals : decimals)
+  const roundAt = (at: number) => Number((value / COMPACT_UNITS[at][0]).toFixed(placesAt(at)))
+  let scaled = roundAt(i)
+  if (Math.abs(scaled) >= 1000 && i < COMPACT_UNITS.length - 1) {
+    i++
+    scaled = roundAt(i)
+  }
+
+  const places = placesAt(i)
+  // -0.001 rounds to -0, which would print as "-0".
+  if (scaled === 0) scaled = 0
+  const number =
+    locale === undefined
+      ? fixed
+        ? scaled.toFixed(places)
+        : String(scaled)
+      : numberFormat(locale, {
+          minimumFractionDigits: fixed ? places : 0,
+          maximumFractionDigits: places,
+          useGrouping: false,
+        }).format(scaled)
+  return `${number}${COMPACT_UNITS[i][1]}`
+}

package/src/components/identicon.ts

@@ -0,0 +1,160 @@
+/*
+ * Identicons: a picture derived from a string, so something with no avatar
+ * of its own (a new account, a server, an API key, a commit) still gets a
+ * face that is the same every time and different from its neighbours.
+ *
+ * The pattern is a small pixel grid mirrored left to right, the way faces
+ * and logos are: symmetry is what makes a random grid read as a shape rather
+ * than noise, and it halves the bits each picture needs.
+ *
+ * The colour comes from the same hash, but only the HUE is free. Saturation
+ * and lightness are held to a middle band so every identicon reads on a dark
+ * surface and on a light one alike; a free lightness would hand some seeds a
+ * near-black shape that vanishes in a dark theme and others a pale one that
+ * vanishes in a light theme.
+ *
+ * Pure and deterministic: no randomness beyond the seed, no DOM. The same
+ * seed gives the same picture on the server, in the client and across
+ * releases, which is what lets a user recognise it.
+ */
+
+export interface IdenticonOptions {
+  /** Cells per side. 5 is the familiar look; more cells, busier shapes. */
+  grid?: number
+  /** Saturation range, percent. Kept in the middle so the colour holds on any theme. */
+  saturation?: readonly [number, number]
+  /** Lightness range, percent: dark enough for a light theme, light enough for a dark one. */
+  lightness?: readonly [number, number]
+}
+
+export interface Identicon {
+  /** Rows of cells, `true` filled. Mirrored left to right. */
+  cells: boolean[][]
+  /** The hue the seed picked, 0–360. */
+  hue: number
+  /** The shape's colour as a CSS `hsl()`. */
+  color: string
+}
+
+/*
+ * FNV-1a over the string's UTF-16 units. Not a secure hash and not meant to
+ * be: it only has to spread similar ids ("user-1", "user-2") far apart, which
+ * it does, in a few lines that give the same answer on every engine.
+ */
+export function hashString(seed: string): number {
+  let h = 0x811c9dc5
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return h >>> 0
+}
+
+/*
+ * A small seeded generator (mulberry32). The hash alone has 32 bits, and a
+ * 7×7 grid wants more than that; drawing from a generator seeded with it
+ * keeps every bit dependent on the whole string.
+ */
+function generator(seed: number): () => number {
+  let a = seed
+  return () => {
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+/** The grid and colour for a seed. */
+export function identicon(seed: string, options: IdenticonOptions = {}): Identicon {
+  const size = Math.max(3, Math.min(12, Math.round(options.grid ?? 5)))
+  const [sMin, sMax] = options.saturation ?? [55, 72]
+  const [lMin, lMax] = options.lightness ?? [48, 60]
+  const next = generator(hashString(seed))
+
+  const hue = Math.floor(next() * 360)
+  const saturation = Math.round(sMin + next() * (sMax - sMin))
+  const lightness = Math.round(lMin + next() * (lMax - lMin))
+
+  const half = Math.ceil(size / 2)
+  const cells: boolean[][] = []
+  let filled = 0
+  for (let y = 0; y < size; y++) {
+    const row: boolean[] = new Array(size).fill(false)
+    for (let x = 0; x < half; x++) {
+      const on = next() < 0.5
+      row[x] = on
+      row[size - 1 - x] = on
+      if (on) filled++
+    }
+    cells.push(row)
+  }
+
+  /*
+   * A grid that came out nearly empty or nearly full is not a shape, just a
+   * dot or a block. Flip cells in a seed-driven order until the half holds
+   * between a third and two thirds of its cells.
+   */
+  const total = half * size
+  const low = Math.ceil(total / 3)
+  const high = Math.floor((total * 2) / 3)
+  while (filled < low || filled > high) {
+    const y = Math.floor(next() * size)
+    const x = Math.floor(next() * half)
+    const on = cells[y][x]
+    if ((filled < low && on) || (filled > high && !on)) continue
+    cells[y][x] = !on
+    cells[y][size - 1 - x] = !on
+    filled += on ? -1 : 1
+  }
+
+  return { cells, hue, color: `hsl(${hue} ${saturation}% ${lightness}%)` }
+}
+
+/** The filled cells as rectangles, merged along each row: fewer nodes than one per cell. */
+export function identiconRects(cells: boolean[][]): { x: number; y: number; w: number }[] {
+  const rects: { x: number; y: number; w: number }[] = []
+  cells.forEach((row, y) => {
+    let x = 0
+    while (x < row.length) {
+      if (!row[x]) {
+        x++
+        continue
+      }
+      let w = 1
+      while (x + w < row.length && row[x + w]) w++
+      rects.push({ x, y, w })
+      x += w
+    }
+  })
+  return rects
+}
+
+export interface IdenticonSvgOptions extends IdenticonOptions {
+  /** Pixel size of the square image. */
+  size?: number
+  /** Fill behind the pattern, any CSS colour; transparent when unset. */
+  background?: string
+  /** Empty margin around the grid, as a share of the side. */
+  padding?: number
+}
+
+/**
+ * The identicon as standalone SVG markup, for places a component cannot go:
+ * a favicon, a canvas, a notification icon (`data:image/svg+xml,…`).
+ */
+export function identiconSvg(seed: string, options: IdenticonSvgOptions = {}): string {
+  const { cells, color } = identicon(seed, options)
+  const n = cells.length
+  const pad = n * Math.max(0, Math.min(0.4, options.padding ?? 0.12))
+  const view = n + pad * 2
+  const px = options.size ?? 64
+  const bg = options.background ? `<rect width="${view}" height="${view}" fill="${options.background}"/>` : ""
+  const shapes = identiconRects(cells)
+    .map((r) => `<rect x="${r.x + pad}" y="${r.y + pad}" width="${r.w}" height="1"/>`)
+    .join("")
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${px}" height="${px}" viewBox="0 0 ${view} ${view}" shape-rendering="crispEdges">` +
+    `${bg}<g fill="${color}">${shapes}</g></svg>`
+  )
+}

package/src/components/masonry.ts

@@ -0,0 +1,73 @@
+/*
+ * Column maths for LpMasonry, kept free of the DOM so it can be tested.
+ */
+
+export interface MasonryColumns {
+  /**
+   * Fixed count, or a table of minimum container widths to counts
+   * (`{ 0: 1, 480: 2, 900: 3 }`). Omit to derive the count from `minColumnWidth`.
+   */
+  columns?: number | Record<number, number>
+  /** Narrowest a column may get when the count is derived. */
+  minColumnWidth: number
+  /** Upper bound for a derived count, so a wide screen does not shred cards into slivers. */
+  maxColumns?: number
+  gap: number
+}
+
+/** How many columns fit a container `width` px wide. Always at least one. */
+export function masonryColumnCount(width: number, options: MasonryColumns): number {
+  const { columns, minColumnWidth, maxColumns, gap } = options
+  if (typeof columns === "number") return Math.max(1, Math.floor(columns))
+  if (columns) {
+    let picked = 1
+    let best = -Infinity
+    for (const [min, count] of Object.entries(columns)) {
+      const at = Number(min)
+      if (width >= at && at > best) {
+        best = at
+        picked = count
+      }
+    }
+    return Math.max(1, Math.floor(picked))
+  }
+  const fit = Math.floor((width + gap) / (Math.max(1, minColumnWidth) + gap))
+  return Math.max(1, Math.min(fit, maxColumns ?? Infinity))
+}
+
+export interface MasonryPlacement {
+  /** Left edge of each item, in px, in input order. */
+  x: number[]
+  /** Top edge of each item, in px, in input order. */
+  y: number[]
+  /** Column each item went to. */
+  column: number[]
+  /** Width every item is laid out at. */
+  columnWidth: number
+  /** Height of the tallest column: the container's height. */
+  height: number
+}
+
+/**
+ * Places items in order, each into the column that is currently shortest
+ * (leftmost on a tie). In order, so the first items stay at the top and an
+ * item added at the end never reshuffles the ones before it.
+ */
+export function placeMasonry(heights: number[], count: number, width: number, gap: number): MasonryPlacement {
+  const columns = Math.max(1, count)
+  const columnWidth = Math.max(0, (width - gap * (columns - 1)) / columns)
+  const bottoms = new Array<number>(columns).fill(0)
+  const x: number[] = []
+  const y: number[] = []
+  const column: number[] = []
+  for (const height of heights) {
+    let shortest = 0
+    for (let c = 1; c < columns; c += 1) if (bottoms[c]! < bottoms[shortest]! - 0.5) shortest = c
+    x.push(shortest * (columnWidth + gap))
+    y.push(bottoms[shortest]!)
+    column.push(shortest)
+    bottoms[shortest] = bottoms[shortest]! + Math.max(0, height) + gap
+  }
+  const tallest = Math.max(0, ...bottoms)
+  return { x, y, column, columnWidth, height: heights.length ? tallest - gap : 0 }
+}

package/src/components/meter.ts

@@ -0,0 +1,122 @@
+/*
+ * The arithmetic shared by the kit's meters: LpGauge, LpQuota, LpStatus and
+ * LpActivityLine. A reading against a range, the tone it earns, and the colour
+ * that tone paints in. Kept in one place so a gauge and a quota showing the same
+ * disk agree on when it turns amber, instead of each picking its own breakpoints.
+ * The colours themselves are tone.ts's: a meter tone is one of its aliases.
+ */
+import { TONE_ALIASES, TONES, type ToneLook } from "./tone"
+
+/**
+ * The semantic tones a meter speaks in. They name what the reading MEANS, not
+ * which colour it is: a theme decides the colour, and `ok` stays the "fine"
+ * colour whatever that happens to be.
+ */
+export type MeterTone = "ok" | "warning" | "danger" | "brand" | "neutral"
+
+/** One step of a scale: from `at` (in the meter's own units) upward, `tone`. */
+export interface MeterThreshold {
+  at: number
+  tone: MeterTone
+}
+
+const METER_TONES: readonly MeterTone[] = ["ok", "warning", "danger", "brand", "neutral"]
+const byMeterTone = (pick: (look: ToneLook) => string) =>
+  Object.fromEntries(METER_TONES.map((t) => [t, pick(TONES[TONE_ALIASES[t]])])) as Record<MeterTone, string>
+
+/** The solid colour of a tone, as a CSS value a style or an SVG stroke takes. */
+export const TONE_COLOR: Record<MeterTone, string> = byMeterTone((look) => look.color)
+
+/** The tinted background of a tone, for pills and highlighted rows. */
+export const TONE_SOFT: Record<MeterTone, string> = byMeterTone((look) => look.soft)
+
+/**
+ * Where `value` sits between `min` and `max`, as 0–1. An empty or inverted
+ * range (no limit known yet) reads as empty rather than as NaN or Infinity,
+ * which would otherwise reach an SVG attribute and draw nothing at all.
+ */
+export function meterFraction(value: number, min: number, max: number): number {
+  const span = max - min
+  if (!(span > 0) || !Number.isFinite(value)) return 0
+  return Math.max(0, Math.min(1, (value - min) / span))
+}
+
+/**
+ * The capacity scale every finite resource is read against: comfortable well
+ * past half, uncomfortable in the last fifth, urgent in the last tenth. The
+ * same breakpoints LpProgress's `auto` tone uses, so the two never disagree
+ * about one disk.
+ */
+export function capacityThresholds(
+  min: number,
+  max: number,
+  warnAt = 0.8,
+  dangerAt = 0.9,
+): MeterThreshold[] {
+  const span = max - min
+  return [
+    { at: min + span * warnAt, tone: "warning" },
+    { at: min + span * dangerAt, tone: "danger" },
+  ]
+}
+
+/**
+ * The tone a reading earns on a scale. Thresholds are steps, not bands: each
+ * one holds from its `at` until the next, and below the first the reading is
+ * `base`. Sorted here, so a caller can list them in whatever order reads best.
+ *
+ * Steps go either way, which is what lets one shape describe both "higher is
+ * worse" (load: ok → warning → danger) and "higher is better" (a score:
+ * danger from 0, warning from 50, ok from 80).
+ */
+export function toneAt(value: number, thresholds: readonly MeterThreshold[], base: MeterTone = "ok"): MeterTone {
+  let tone = base
+  for (const step of [...thresholds].sort((a, b) => a.at - b.at)) {
+    if (value >= step.at) tone = step.tone
+  }
+  return tone
+}
+
+/* ── Bar (LpProgress, LpQuota) ──────────────────────────────────────────── */
+
+/**
+ * The track a bar meter fills, shared so LpProgress's bar and LpQuota's read as
+ * one family. Each adds its own clipping: a progress bar clips its fill, a
+ * quota lets its limit mark stand out past the track.
+ */
+export const METER_TRACK = "h-1.5 w-full rounded-pill bg-surface-soft"
+
+/** The row above a bar: what is measured at the start, the reading at the end. Each sets its own size and gap. */
+export const METER_HEADER = "flex items-baseline justify-between"
+
+/* ── Arc geometry (LpGauge) ─────────────────────────────────────────────── */
+
+/**
+ * A point on a circle, with the angle in degrees clockwise from twelve
+ * o'clock — the way a dial is read, so -90 is nine o'clock and 90 is three.
+ */
+export function polar(cx: number, cy: number, r: number, deg: number): { x: number; y: number } {
+  const rad = (deg * Math.PI) / 180
+  return { x: cx + r * Math.sin(rad), y: cy - r * Math.cos(rad) }
+}
+
+/** An SVG path along a circle from one angle to another, clockwise. */
+export function arcPath(cx: number, cy: number, r: number, from: number, to: number): string {
+  const a = polar(cx, cy, r, from)
+  const b = polar(cx, cy, r, to)
+  const large = to - from > 180 ? 1 : 0
+  const f = (n: number) => Number(n.toFixed(3))
+  return `M ${f(a.x)} ${f(a.y)} A ${f(r)} ${f(r)} 0 ${large} 1 ${f(b.x)} ${f(b.y)}`
+}
+
+/**
+ * The sweep of each gauge shape, as [start, end] angles. A semicircle reads
+ * left to right across the top; the full dial opens at the bottom, a 270°
+ * sweep, because a closed circle has no visible start or end and that is
+ * LpProgress's ring, a different thing (progress toward done, not a reading
+ * within a range).
+ */
+export const GAUGE_SWEEP: Record<"semi" | "full", readonly [number, number]> = {
+  semi: [-90, 90],
+  full: [-135, 135],
+}

package/src/components/otp.ts

@@ -3,6 +3,8 @@
  * model. reka empties a cell by deleting its slot (numeric mode) or setting it
  * to "", so the array can have holes in the middle.
  */
+import { groupCode } from "./fieldText"
+
 export type OtpCells = (string | number | undefined)[]
 
 /** The code typed so far: the filled cells in order. */
@@ -36,10 +38,19 @@ export function upperCells<T extends OtpCells>(cells: T): T {
  * The cell indexes a group separator follows: after every `group` cells, never
  * after the last. Eight characters are read and copied as two blocks of four,
  * which is how such codes are printed, far more easily than as one row.
+ *
+ * The blocks are LpCodeDisplay's (`groupCode`), so a code shown by one and
+ * typed into the other breaks in the same places; exact sizes (`[4, 6, 5]`)
+ * work here too. Unlike there, no `group` means no breaks: an input does not
+ * guess a grouping the printed code may not have.
  */
-export function groupBreaks(length: number, group: number | undefined): Set<number> {
+export function groupBreaks(length: number, group: number | number[] | undefined): Set<number> {
   const breaks = new Set<number>()
-  if (!group || group < 1 || group >= length) return breaks
-  for (let i = group; i < length; i += group) breaks.add(i - 1)
+  if (Array.isArray(group) ? !group.some((n) => n > 0) : !group || group < 1) return breaks
+  let at = 0
+  for (const block of groupCode("x".repeat(Math.max(0, length)), group)) {
+    at += block.length
+    if (at < length) breaks.add(at - 1)
+  }
   return breaks
 }

package/src/components/pipeline.ts

@@ -0,0 +1,101 @@
+/*
+ * The state of a run of jobs, read off the jobs themselves. Pure, so the
+ * rules LpPipeline draws by (which connector is filled, which step is
+ * "current", what a run as a whole amounts to) are testable without a DOM.
+ */
+import { toEpoch } from "./timeSpan"
+
+export type StepStatus = "pending" | "running" | "success" | "failed" | "skipped" | "cancelled"
+
+export interface PipelineStep {
+  label: string
+  /** Stable id: what `expanded` and the `step` slot address. Defaults to the index. */
+  key?: string
+  status: StepStatus
+  /** A line under the label: the command, the host, the reason it was skipped. */
+  description?: string
+  /** Replaces the glyph while the step is pending (a step that is "deploy" more than "3"). */
+  icon?: string
+  /**
+   * Time the step took, in ms. When it is not known yet, `startedAt` (and
+   * `finishedAt`) let the pipeline work it out — and keep a running step's
+   * clock ticking without the app re-sending it every second.
+   */
+  duration?: number
+  startedAt?: Date | string | number
+  finishedAt?: Date | string | number
+  /** Jobs inside this one, shown when the step is expanded (vertical layout). */
+  steps?: PipelineStep[]
+}
+
+/** Done, one way or another: nothing more will happen to the step. */
+export function isSettled(status: StepStatus): boolean {
+  return status !== "pending" && status !== "running"
+}
+
+/**
+ * Whether the line leaving a step is drawn as travelled. A step that passed
+ * or was skipped hands over to the next; one that failed or was cancelled is
+ * where the run stopped, so the line after it stays empty — the break in the
+ * line is the place to look.
+ */
+export function connectorFilled(status: StepStatus): boolean {
+  return status === "success" || status === "skipped"
+}
+
+/**
+ * The step a viewer is following: the running one, else the first that has
+ * not run yet after something has, else the last failure. -1 when the run has
+ * not started or is cleanly over.
+ */
+export function currentStepIndex(steps: readonly Pick<PipelineStep, "status">[]): number {
+  const running = steps.findIndex((s) => s.status === "running")
+  if (running !== -1) return running
+  const failed = steps.findIndex((s) => s.status === "failed")
+  if (failed !== -1) return failed
+  const started = steps.some((s) => isSettled(s.status))
+  if (!started) return -1
+  return steps.findIndex((s) => s.status === "pending")
+}
+
+/**
+ * What the run amounts to. A failure anywhere outranks everything (one red
+ * job fails the build), then work in progress, then a cancellation; a run of
+ * passes and skips is a pass. Nothing started is pending.
+ */
+export function overallStatus(steps: readonly Pick<PipelineStep, "status">[]): StepStatus {
+  if (steps.length === 0) return "pending"
+  const has = (s: StepStatus) => steps.some((step) => step.status === s)
+  if (has("failed")) return "failed"
+  if (has("running")) return "running"
+  if (has("cancelled")) return "cancelled"
+  if (steps.every((s) => s.status === "skipped")) return "skipped"
+  if (steps.every((s) => s.status === "success" || s.status === "skipped")) return "success"
+  if (steps.some((s) => isSettled(s.status))) return "running"
+  return "pending"
+}
+
+/**
+ * Ms a step has taken, as of `now`. An explicit `duration` wins; otherwise
+ * from `startedAt` to `finishedAt`, or to `now` while it is still running.
+ * null when there is nothing to say (pending, or no times given).
+ */
+export function stepElapsed(step: PipelineStep, now: number): number | null {
+  if (typeof step.duration === "number" && Number.isFinite(step.duration)) return Math.max(0, step.duration)
+  const start = toEpoch(step.startedAt)
+  if (Number.isNaN(start)) return null
+  const end = toEpoch(step.finishedAt)
+  if (!Number.isNaN(end)) return Math.max(0, end - start)
+  return step.status === "running" ? Math.max(0, now - start) : null
+}
+
+/** "2/5": finished children out of all, for a step whose inside is folded away. */
+export function childProgress(step: PipelineStep): { done: number; total: number } | null {
+  if (!step.steps?.length) return null
+  return { done: step.steps.filter((s) => isSettled(s.status)).length, total: step.steps.length }
+}
+
+/** The key a step is addressed by. */
+export function stepKey(step: Pick<PipelineStep, "key">, index: number): string {
+  return step.key ?? String(index)
+}