@lovett/ui 0.0.11 → 0.2.0

package/src/sparkline.tsx

@@ -0,0 +1,416 @@
+/**
+ * Sparkline — an inline trend at cell size. No axes, no gridlines, no frame,
+ * no legend, no tooltip. Line or bar.
+ *
+ * Promoted in ADR-146 D5 (chart layer). It supersedes the **chart half** of
+ * `allocation-sparkbar.tsx`, whose labels-under-bars affordance stays with
+ * that primitive until the staged migration in ADR-146 D13.
+ *
+ * CONSUMERS — measured 2026-09-06 (real `from '@lovett/ui'` imports under
+ * `apps/workspace/src`; the design-system gallery is a demo harness and does
+ * NOT count toward the ADR-008 D3 gate).
+ *   TODAY (1 — gate NOT MET):
+ *     • `lenses/budget-flighting/components/cards/LineItemCard.tsx` — the
+ *       monthly allocation strip
+ *   PLANNED second consumer: a trend cell per row in the Keywords term table
+ *   (`lenses/keywords/results-table.tsx`). Not written. Tracked in
+ *   `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * That one migration also COST something: the budget-flighting strip lost its
+ * per-month flight-group tint, because a chart primitive takes a palette slot
+ * and never a token name (D8). Logged as DEV-2 in
+ * `docs/phases/_completed/adr-146-analytics-primitives.md` and open as
+ * ADR-146 OQ-2 (`docs/follow-ups/_pending/adr-146-sparkline-per-bar-colour.md`).
+ *
+ * WHAT IT INHERITS FROM `AllocationSparkbar`, DELIBERATELY
+ * -------------------------------------------------------
+ * The bar variant keeps that primitive's three load-bearing behaviours so a
+ * migration is a swap and not a redesign:
+ *
+ *   • **Max-normalisation** (`allocation-sparkbar.tsx:40`) — heights are a
+ *     fraction of the largest value, via `normalizeToMax`. That helper drops
+ *     the old `Math.max(...values, 1)` fudge, which silently rescaled any
+ *     series whose max was below 1 (a set of ratios) against a phantom
+ *     maximum and flattened the whole strip.
+ *   • **A floor under every bar** (`:48`, `8 + (v/max) * (h - 12)`) — the
+ *     smallest bar is still a visible mark, not a hairline. At that file's
+ *     36px default height this one reproduces the arithmetic exactly (floor
+ *     8, headroom 4, span 8..32); below it the floor and headroom scale with
+ *     the box, because an 8px floor inside a 20px strip is 40% of the chart.
+ *   • **Paused reads as paused, not as empty** (`:44`) — a value of exactly
+ *     `0` renders short and dashed in a muted tone, so "we spent nothing that
+ *     month" is distinguishable from "we have no data". Turn it off with
+ *     `zeroAsPaused={false}` when zero is a real measurement.
+ *
+ * WHY THE BAR VARIANT IS DIVS AND THE LINE VARIANT IS SVG
+ * ------------------------------------------------------
+ * A bar strip is rectangles, and a `<div>` takes `border-radius`,
+ * `background` and `border` straight from tokens. An SVG `<rect>` cannot: its
+ * `rx` is a geometry attribute, `var()` substitution inside presentation
+ * attributes is not reliably implemented, and a radius that fails to parse
+ * fails **silently** — the exact class of defect ADR-146 D8 exists to prevent.
+ * So bars stay divs, as they were in the primitive this supersedes, and only
+ * the line — which genuinely needs path arithmetic — is SVG, where every
+ * colour is a plain `fill`/`stroke` value and no token has to survive an
+ * attribute parser.
+ *
+ * THE POINT TREATMENT INVERTS AT SMALL SIZE
+ * -----------------------------------------
+ * The extracted anatomy (`METORIC-ANALYTICS-SPEC.md` 6.2) draws the large
+ * chart's point as a **filled** dot with a 2px surface ring, and the 450×56
+ * sparkline's as the **opposite** — a surface fill with a 3px coloured
+ * stroke. That inversion is right and we keep it. At sparkline size the mark
+ * is a large fraction of the plot, so a filled dot reads as a blob and hides
+ * the very inflection it is marking; a hollow ring keeps the line's own path
+ * visible through it. The dot and its stroke scale with `height`, so the
+ * treatment holds at 60×20 and at 300×60.
+ *
+ * The hollow dot is filled with `--surface-card` — it is drawn to sit on a
+ * `Card`, which is where an inline trend lives. On a tray or a zebra band it
+ * reads as a very slightly lighter ring; pass `emphasizeLast={false}` there
+ * rather than introducing a fill-colour prop.
+ *
+ * NO MOTION, ON PURPOSE
+ * ---------------------
+ * SVG path geometry does not tween under a CSS transition, and animating it
+ * properly would mean a per-frame interpolator inside a primitive whose whole
+ * job is to be cheap enough to render once per table row. A sparkline
+ * redraws; it does not settle. That is reduced-motion-correct by
+ * construction. `RankedBars` and the full-size chart layer carry the
+ * `--dur-base` / `--ease-out` data tween.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`; the series hue
+ * resolves through the frozen `SERIES` lookup in `lib/series.ts` (ADR-146 D8
+ * — never a constructed `--series-${i}`), and defaults to `rgb(var(--accent))`
+ * because a lone trend is one series and D7's monochrome default applies.
+ * Tints are applied with `opacity` / SVG `fill-opacity` rather than by
+ * editing the token string, so no call site can stack a second alpha onto a
+ * token that already carries one. Sizes are props applied through inline
+ * `style` and SVG attributes, never a template-literal Tailwind class
+ * (`h-[${n}px]` is statically unscannable and silently produces nothing).
+ */
+
+import { cn } from './lib/utils'
+import { areaPath, bandScale, linePath, linearScale, normalizeToMax } from './lib/chart'
+import { slotColor, type ChartSlot, type SeriesPalette } from './lib/series'
+
+/** Which mark the sparkline draws. */
+export type SparklineVariant = 'line' | 'bar'
+
+export interface SparklineProps {
+  /**
+   * The series, oldest first. Non-finite entries are dropped from the line
+   * (it closes over the gap) and read as `0` in the bar variant. Negative
+   * values plot normally on the line and clamp to the height floor on bars —
+   * a bar cannot be shorter than nothing.
+   */
+  values: readonly number[]
+  /** `'line'` (default) or `'bar'`. */
+  variant?: SparklineVariant
+  /** Plot width in px. Default `120`. Renders sensibly from about 60. */
+  width?: number
+  /** Plot height in px. Default `32`. Renders sensibly from about 20. */
+  height?: number
+  /**
+   * Optional palette slot. Omit for the monochrome accent default (ADR-146
+   * D7). Pass a slot only when this trend is one of several colour-identified
+   * entities, and derive the slot from the entity's stable key — never from
+   * an array index after sorting or filtering.
+   */
+  slot?: ChartSlot | undefined
+  /** Which palette `slot` indexes into. Default `'default'`. */
+  palette?: SeriesPalette
+  /** Line stroke width in px. Default `2`. Ignored by the bar variant. */
+  strokeWidth?: number
+  /**
+   * Fill the area under the line at a 12% tint. Default `false` — at cell
+   * size the line alone is usually clearer. Ignored by the bar variant.
+   */
+  area?: boolean
+  /**
+   * Emphasize one mark: the line gets its hollow end dot, the bar variant
+   * draws that bar at full strength and tints the rest. Default `true`.
+   */
+  emphasizeLast?: boolean
+  /**
+   * Which mark is emphasized. Default: the last one. Pass the peak's or the
+   * selected period's index when "now" is not the interesting mark. Clamped
+   * into range, so a stale selection still points at a real mark.
+   */
+  emphasisIndex?: number
+  /**
+   * Render a value of exactly `0` as a short dashed stub rather than as a
+   * floor-height bar — the `AllocationSparkbar` paused treatment. Default
+   * `true`. Bar variant only.
+   */
+  zeroAsPaused?: boolean
+  /**
+   * Optional pre-formatted value shown after the plot, in `tabular-nums`.
+   * Format through `@lovett/ui/format` — this primitive never formats a
+   * number.
+   */
+  valueLabel?: string
+  /**
+   * Reserved width for `valueLabel`, so a value growing from "9" to "11,227"
+   * cannot resize the row. Pass a token-derived length.
+   * Default `var(--space-10)`.
+   */
+  valueMinWidth?: string
+  /**
+   * Accessible name — e.g. `'Impressions, last 12 weeks'`. With it the plot
+   * is `role="img"`; without it the plot is `aria-hidden`, which is correct
+   * only when a neighbouring cell already states the number and the
+   * sparkline is decorative. Never leave a meaning-carrying trend unlabelled.
+   */
+  label?: string
+  /** Optional className on the outer container. */
+  className?: string
+}
+
+/** Clamp without ever returning a non-finite number. */
+function clamp(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min
+  if (value < min) return min
+  return value > max ? max : value
+}
+
+export function Sparkline({
+  values,
+  variant = 'line',
+  width = 120,
+  height = 32,
+  slot,
+  palette = 'default',
+  strokeWidth = 2,
+  area = false,
+  emphasizeLast = true,
+  emphasisIndex,
+  zeroAsPaused = true,
+  valueLabel,
+  valueMinWidth = 'var(--space-10)',
+  label,
+  className,
+}: SparklineProps) {
+  const w = Math.max(0, Number.isFinite(width) ? width : 0)
+  const h = Math.max(0, Number.isFinite(height) ? height : 0)
+  const count = values.length
+  const color = slot === undefined ? 'rgb(var(--accent))' : slotColor(slot, palette)
+
+  // Default emphasis is the newest mark.
+  const emphasis =
+    count === 0
+      ? -1
+      : emphasisIndex === undefined
+        ? count - 1
+        : Math.round(clamp(emphasisIndex, 0, count - 1))
+
+  // The plot reserves its exact box, so async data cannot reflow the row it
+  // sits in — the layout-stability rule, at cell scale.
+  const plot = (
+    <div
+      role={label === undefined ? undefined : 'img'}
+      aria-label={label}
+      aria-hidden={label === undefined ? true : undefined}
+      className="relative shrink-0"
+      style={{ width: w, height: h }}
+    >
+      {variant === 'bar'
+        ? renderBars({ values, w, h, color, emphasis, emphasizeLast, zeroAsPaused })
+        : renderLine({ values, w, h, color, emphasis, emphasizeLast, strokeWidth, area })}
+    </div>
+  )
+
+  if (valueLabel === undefined) {
+    return <div className={cn('inline-flex', className)}>{plot}</div>
+  }
+
+  return (
+    <div className={cn('inline-flex items-center gap-2', className)}>
+      {plot}
+      <span
+        className="shrink-0 text-right text-[12px] font-semibold tabular-nums"
+        style={{ color: 'rgb(var(--foreground))', minWidth: valueMinWidth }}
+      >
+        {valueLabel}
+      </span>
+    </div>
+  )
+}
+
+/* ── line ────────────────────────────────────────────────────────────── */
+
+interface LineArgs {
+  values: readonly number[]
+  w: number
+  h: number
+  color: string
+  emphasis: number
+  emphasizeLast: boolean
+  strokeWidth: number
+  area: boolean
+}
+
+function renderLine({
+  values,
+  w,
+  h,
+  color,
+  emphasis,
+  emphasizeLast,
+  strokeWidth,
+  area,
+}: LineArgs) {
+  if (w === 0 || h === 0) return null
+
+  // The dot and its ring scale with the box: the extracted 450×56 sparkline
+  // uses a 12px dot with a 3px stroke (r ≈ h/9), which at 20px tall would be
+  // a 2px dot with a hairline — below the visibility floor. The clamps hold
+  // both ends of the range.
+  const dotRadius = clamp(h * 0.11, 2.5, 6)
+  const dotStroke = clamp(dotRadius * 0.5, 1.5, 3)
+  const stroke = Math.max(0.5, Number.isFinite(strokeWidth) ? strokeWidth : 2)
+
+  // Inset so neither the stroke nor the end dot is clipped by the viewBox.
+  // `Math.max` rather than a ternary: with the dot on, a caller-raised
+  // `strokeWidth` can exceed the dot's own inset (strokeWidth 8 at h=20 needs
+  // 4 of inset, the dot only reserves 3.25), and the line would be shaved
+  // against the viewBox edge with every gate green.
+  const pad = Math.max(stroke / 2, emphasizeLast ? dotRadius + dotStroke / 2 : 0)
+  const plotW = Math.max(0, w - pad * 2)
+  const plotH = Math.max(0, h - pad * 2)
+
+  const finiteValues = values.filter((value) => Number.isFinite(value))
+  const first = finiteValues[0]
+  if (first === undefined) return null
+
+  let min = first
+  let max = first
+  for (const value of finiteValues) {
+    if (value < min) min = value
+    if (value > max) max = value
+  }
+
+  // A flat or single-datum series maps to the midpoint of the range — see
+  // `linearScale`'s contract. Nothing divides by zero.
+  const y = linearScale([min, max], [pad + plotH, pad])
+  const xAt = (index: number): number =>
+    values.length > 1 ? pad + (index / (values.length - 1)) * plotW : pad + plotW / 2
+
+  // Non-finite entries are dropped rather than pinned to the floor: a missing
+  // datum has no honest position, and plotting it at zero invents a dip. A
+  // single plottable point still paints, as a round dot.
+  const points = values
+    .map((value, index) => ({ value, x: xAt(index), y: y(value) }))
+    .filter((point) => Number.isFinite(point.value))
+    .map((point) => ({ x: point.x, y: point.y }))
+
+  const emphasized = values[emphasis]
+  const showDot =
+    emphasizeLast && emphasis >= 0 && emphasized !== undefined && Number.isFinite(emphasized)
+
+  return (
+    <svg
+      width={w}
+      height={h}
+      viewBox={`0 0 ${w} ${h}`}
+      aria-hidden="true"
+      focusable="false"
+      style={{ display: 'block' }}
+    >
+      {area && (
+        <path d={areaPath(points, pad + plotH)} fill={color} fillOpacity={0.12} stroke="none" />
+      )}
+      <path
+        d={linePath(points)}
+        fill="none"
+        stroke={color}
+        strokeWidth={stroke}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      {showDot && (
+        <circle
+          cx={xAt(emphasis)}
+          cy={y(emphasized)}
+          r={dotRadius}
+          fill="rgb(var(--surface-card))"
+          stroke={color}
+          strokeWidth={dotStroke}
+        />
+      )}
+    </svg>
+  )
+}
+
+/* ── bars ────────────────────────────────────────────────────────────── */
+
+interface BarArgs {
+  values: readonly number[]
+  w: number
+  h: number
+  color: string
+  emphasis: number
+  emphasizeLast: boolean
+  zeroAsPaused: boolean
+}
+
+function renderBars({
+  values,
+  w,
+  h,
+  color,
+  emphasis,
+  emphasizeLast,
+  zeroAsPaused,
+}: BarArgs) {
+  if (values.length === 0 || w === 0 || h === 0) return null
+
+  const band = bandScale(values.length, w, 0.28)
+  const fractions = normalizeToMax(values)
+
+  // At h = 36 — `allocation-sparkbar.tsx`'s own default — the ratios resolve
+  // to exactly its arithmetic: floor 8, headroom 4, a bar spanning 8..32,
+  // i.e. `8 + f * (36 - 12)`. Below that height both scale with the box, so
+  // the floor never swallows the chart (an 8px floor in a 20px strip is 40%
+  // of the plot). The fractions are 2/9 and 1/9 rather than 0.22 and 0.11
+  // precisely so the 36px case lands on the integers and not on 7.92.
+  const floor = Math.min(8, (h * 2) / 9)
+  const headroom = Math.min(4, h / 9)
+  const cap = Math.max(floor, h - headroom)
+
+  return (
+    <>
+      {values.map((value, index) => {
+        const paused = zeroAsPaused && value === 0
+        const fraction = fractions[index] ?? 0
+        const barHeight = paused ? headroom : floor + fraction * (cap - floor)
+
+        // D7's scarcity rule, sized for this box: the emphasized bar is full
+        // strength and the rest are a tint. The tint is 0.55 rather than the
+        // full-size chart's 0.14 because at 60×20 a 14% fill is below the
+        // visibility floor — the same reason the point treatment inverts.
+        const tinted = emphasizeLast && index !== emphasis
+
+        return (
+          <div
+            key={index}
+            style={{
+              position: 'absolute',
+              left: band.at(index),
+              bottom: 0,
+              width: band.band,
+              height: barHeight,
+              // A lightly-rounded BAR, not a pill: --radius-xs on a 5px-wide
+              // bar clamps to a full capsule, so it is halved — the same
+              // correction ChartLegend makes on its 12px swatch.
+              borderRadius: 'calc(var(--radius-xs) / 2)',
+              background: paused ? 'rgb(var(--text-muted) / 0.18)' : color,
+              border: paused ? '1px dashed rgb(var(--text-muted) / 0.4)' : undefined,
+              opacity: !paused && tinted ? 0.55 : 1,
+            }}
+          />
+        )
+      })}
+    </>
+  )
+}