@lovett/ui 0.0.11 → 0.2.0

package/src/gauge-ring.tsx

@@ -0,0 +1,435 @@
+/**
+ * GaugeRing — a single-arc radial gauge: track, value arc, centre readout.
+ *
+ * Promoted in ADR-146 D5 (chart layer). This is `CompletionRing`
+ * generalised, and it absorbs the hand-rolled 88px fit-score ring at
+ * `lenses/discovery/geo/analysis-panel.tsx:176-198` — the duplicate ADR-146's
+ * Context calls out by name, and the one carrying an
+ * `eslint-disable no-restricted-syntax` for the charts exception. Moving it
+ * here is what lets that disable come out (ADR-146 D4, follow-up
+ * `geo-chart-primitives.md`).
+ *
+ * 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 (0 — gate NOT MET). The absorption described above has NOT
+ *   happened yet: `lenses/discovery/geo/analysis-panel.tsx:177` still draws
+ *   its own 88px ring and still carries the `eslint-disable`.
+ *   PLANNED: that panel (banded fit score, 88px, 270° gauge) and the
+ *   brand-profile / dashboard completion rail (plain 0-100 percentage, small
+ *   full circle, `CompletionRing` today) — the two shapes this generalises.
+ *   Tracked in `docs/follow-ups/_pending/adr-146-consumer-gate.md` and
+ *   `docs/follow-ups/_pending/geo-chart-primitives.md`.
+ *
+ *   <GaugeRing value={80} unit="%" />
+ *   <GaugeRing value={pct} size={38} strokeWidth={3} />
+ *   <GaugeRing value={pct} showLabel={false} />
+ *   <GaugeRing value={pct} label={<Check className="h-3 w-3" />} />
+ *   <GaugeRing value={83} size={88} strokeWidth={7}
+ *              startAngle={225} sweep={270} bands={FIT_BANDS} />
+ *
+ * WHAT IT ADDS OVER `CompletionRing`
+ * ----------------------------------
+ *   • **Bands.** `bands` maps value ranges onto semantic tones, so a fit
+ *     score paints destructive / warning / success by where it lands. The
+ *     matched band's `label` renders as TEXT beside the hue — never the hue
+ *     alone (ADR-146 D10.1) — and goes into the `aria-label`.
+ *   • **A partial arc.** `startAngle` + `sweep` give the 270° gauge shape.
+ *     `CompletionRing` could only draw a full turn.
+ *   • **A structural track**, `--border-strong`, which reads against every
+ *     surface a gauge can land on — card, frame AND the recessed inset well
+ *     — rather than a translucent overlay tint. See `trackColor` for the
+ *     measured numbers and for why it is NOT `--muted`.
+ *   • **A structured centre readout** — value, optional `unit` suffix,
+ *     optional `caption` beneath — instead of one opaque `label` node.
+ *
+ * `CompletionRing` is NOT deleted here. Migration is ADR-146 D13.
+ *
+ * WHY THE ARITHMETIC IS IMPORTED, NOT REWRITTEN
+ * ---------------------------------------------
+ * The circumference / dash accumulator was written three times before
+ * ADR-146 D6 (`completion-ring.tsx:58-64`, `shell-charts.tsx:63-91`, and the
+ * geo fork), each with its own answer for a zero radius and an all-zero
+ * series. This file derives none of it: `arcGeometry`, `arcSegments` and
+ * `clampPct` come from `./lib/chart`, whose output contract guarantees no
+ * `NaN` ever reaches an SVG attribute. A `NaN` in `stroke-dasharray` does not
+ * look broken — it drops the element silently, with every gate green.
+ *
+ * SVG is the right tool for ring geometry. CLAUDE.md §6's "no inline SVG"
+ * is about ICONS (use Lucide); it explicitly sanctions chart and ring
+ * geometry inside `packages/ui/`.
+ *
+ * Token discipline: every colour is a whole `rgb(var(--token))` string from a
+ * frozen literal map — no colour literal, and no custom-property name is ever
+ * composed at runtime (ADR-146 D8: a constructed name that misses yields
+ * invalid CSS the browser silently discards). The track is `--border-strong`,
+ * chart STRUCTURE inside a panel, which the data-display recipe requires — and
+ * pointedly NOT `--muted`, which aliases the recessed `--surface-inset` and
+ * therefore vanished at 1.00:1 whenever a gauge sat in a well (see
+ * `trackColor`). Band text wears the theme-tuned `*-ink` companions, because
+ * `--success` / `--warning` / `--accent` are sized as fills and are too light
+ * to read as ink on a light card. Size and stroke are numbers, applied
+ * through inline `style` and SVG attributes: a Tailwind arbitrary value built
+ * from a template literal (`` h-[${n}px] ``) is statically unscannable and
+ * silently produces nothing.
+ */
+
+import type { CSSProperties, ReactNode } from 'react'
+
+import { arcGeometry, arcSegments, clampPct } from './lib/chart'
+import { cn } from './lib/utils'
+
+/** Semantic tones a gauge arc may take. Identity is never tone alone (D10.1). */
+export type GaugeTone = 'accent' | 'neutral' | 'success' | 'warning' | 'destructive' | 'info'
+
+/**
+ * The arc colour per tone. A frozen literal map, the same shape as
+ * `metric-card.tsx`'s `TONE_COLOR` — never `` `--${tone}` ``.
+ */
+const TONE_ARC: Record<GaugeTone, string> = {
+  accent: 'rgb(var(--accent))',
+  neutral: 'rgb(var(--foreground))',
+  success: 'rgb(var(--success))',
+  warning: 'rgb(var(--warning))',
+  destructive: 'rgb(var(--destructive))',
+  info: 'rgb(var(--info))',
+}
+
+/**
+ * The band-label colour per tone — the `*-ink` companion, not the fill.
+ *
+ * `--accent` as text is 5.64:1 on a light card but only 3.05:1 on a dark one,
+ * and `--success` / `--warning` are sized to work as fills and icon strokes.
+ * The `-ink` tokens are the theme-tuned answer (CLAUDE.md §2, `tokens.css`
+ * "SEMANTIC INK"). `--info` has no `-ink` companion today and does not need
+ * one — it clears AA as text in both themes — so it maps to itself.
+ */
+const TONE_INK: Record<GaugeTone, string> = {
+  accent: 'rgb(var(--accent-ink))',
+  neutral: 'rgb(var(--foreground))',
+  success: 'rgb(var(--success-ink))',
+  warning: 'rgb(var(--warning-ink))',
+  destructive: 'rgb(var(--destructive-ink))',
+  info: 'rgb(var(--info))',
+}
+
+/** One threshold band. Bands partition `0..max` by their lower bounds. */
+export interface GaugeBand {
+  /**
+   * Inclusive lower bound, in the same units as `value`. The matched band is
+   * the last one whose `from` is at or below the value; a value below every
+   * bound takes the lowest band.
+   */
+  from: number
+  /** Tone the arc takes inside this band. */
+  tone: GaugeTone
+  /**
+   * The band's name — "Weak", "Fair", "Strong". REQUIRED, because a banded
+   * ring must expose its band as text, not only as a hue (ADR-146 D10.1).
+   * It renders under the value and goes into the `aria-label`.
+   */
+  label: string
+  /**
+   * Optional Lucide icon rendered before the band label — the third,
+   * redundant channel. Colour it with `currentColor`; the label row already
+   * carries the band's ink.
+   */
+  icon?: ReactNode
+}
+
+export interface GaugeRingProps {
+  /** The measured value. Clamped into `0..max` for the arc. */
+  value: number
+  /** Top of the scale. Default `100`. A `max` at or below zero draws empty. */
+  max?: number
+  /** Outer dimension in px. Default `30`. */
+  size?: number
+  /** Ring stroke width in px. Default scales with size (`size / 12`, min 2). */
+  strokeWidth?: number
+  /**
+   * Where the arc starts, in degrees clockwise from twelve o'clock.
+   * Default `0`.
+   *
+   * The arc runs CLOCKWISE from there, so the gap of a partial sweep sits
+   * *before* the start: a 270° gauge with its gap centred at the BOTTOM is
+   * `startAngle={225} sweep={270}` (arc 225° → 135°, gap 135° → 225°).
+   * `startAngle={135}` is the same gauge rotated a quarter turn, with its
+   * gap on the right — pinned by the rotation test, because the two are
+   * indistinguishable in a green build and obvious in a browser.
+   */
+  startAngle?: number
+  /** How far the arc sweeps, in degrees. Default `360` (a full ring). */
+  sweep?: number
+  /**
+   * Threshold bands. When present they choose the tone, and the matched
+   * band's `label` renders as text and enters the `aria-label`. Order does
+   * not matter — they are sorted by `from`.
+   */
+  bands?: readonly GaugeBand[]
+  /** Tone when there are no `bands`. Default `'accent'`. */
+  tone?: GaugeTone
+  /**
+   * Suffix printed immediately after the value, at a smaller size —
+   * `"%"`, `"pts"`. Not a caption; it sits on the value's baseline.
+   */
+  unit?: string
+  /**
+   * Small line beneath the value — `"/ 100"`, `"of target"`. Defaults to the
+   * matched band's label when `bands` are given. Pass `false` to suppress
+   * that default.
+   *
+   * **Passing a caption alongside `bands` REPLACES the band label**, which
+   * leaves the band carried by hue alone on screen (the `aria-label` still
+   * names it). That is the shape ADR-146 D10.1 forbids, so do it only when
+   * the band name is already rendered beside the gauge. When in doubt, let
+   * the band label stand and put "/ 100" in the surrounding copy.
+   */
+  caption?: ReactNode | false
+  /** Render the value as something other than a rounded integer. */
+  formatValue?: (value: number) => string
+  /**
+   * Replace the whole centre readout. A node wins over `unit` / `caption`;
+   * `false` / `null` hides the readout entirely.
+   */
+  label?: ReactNode | false
+  /** Convenience: `false` hides the default readout. Same as `label={false}`. */
+  showLabel?: boolean
+  /**
+   * Track colour. Default `rgb(var(--border-strong))`.
+   *
+   * NOT `--muted`. `--muted` aliases `--surface-inset`, which IS the recessed
+   * well surface, so a gauge dropped into a well painted its track in exactly
+   * the colour behind it: measured 242,242,244 on 242,242,244 in light and
+   * 45,45,48 on 45,45,48 in dark — **1.00:1, both themes**, i.e. a 0% gauge
+   * rendered as bare text with no ring. `--muted` is for small genuinely-muted
+   * FILLS (CLAUDE.md §2); a mark that must read against a surface which may
+   * itself be `--muted` needs a structural token, not a fill token.
+   *
+   * `--border-strong` is the structural choice, measured against every surface
+   * a gauge can land on (composited, WCAG ratio vs. its own ground):
+   *
+   * |               | card   | frame  | inset  |
+   * |---------------|--------|--------|--------|
+   * | light         | 1.61:1 | 1.60:1 | 1.60:1 |
+   * | dark          | 1.54:1 | 1.51:1 | 1.56:1 |
+   *
+   * `--border` was the other candidate and clears a thinner margin (1.23–1.32
+   * across the same six), and `--muted` bottoms out at 1.00. `--border-strong`
+   * is the only one of the three that never drops below 1.5.
+   *
+   * Pass a WHOLE `rgb(var(--token))` string — never a literal, never a
+   * composed name (ADR-146 D8).
+   */
+  trackColor?: string
+  /**
+   * Arc colour, overriding `tone` / `bands`. Same rule as `trackColor`:
+   * a whole token string. Exists so `CompletionRing`'s callers migrate
+   * without losing the escape hatch.
+   */
+  fillColor?: string
+  /**
+   * Screen-reader text. Defaults to the value, the scale, and — when banded
+   * — the band name, which is the contract ADR-146 D10.1 asks for.
+   */
+  ariaLabel?: string
+  /** Extra classes / inline style on the wrapper. */
+  className?: string
+  style?: CSSProperties
+}
+
+/** The band a value falls into: the last bound at or below it, else the lowest. */
+function matchBand(
+  bands: readonly GaugeBand[],
+  value: number,
+): GaugeBand | undefined {
+  if (bands.length === 0) return undefined
+  const ordered = [...bands].sort((a, b) => a.from - b.from)
+  let matched = ordered[0]
+  for (const band of ordered) {
+    if (value >= band.from) matched = band
+  }
+  return matched
+}
+
+export function GaugeRing({
+  value,
+  max = 100,
+  size = 30,
+  strokeWidth,
+  startAngle = 0,
+  sweep = 360,
+  bands,
+  tone = 'accent',
+  unit,
+  caption,
+  formatValue,
+  label,
+  showLabel = true,
+  trackColor = 'rgb(var(--border-strong))',
+  fillColor,
+  ariaLabel,
+  className,
+  style,
+}: GaugeRingProps) {
+  const safeMax = Number.isFinite(max) && max > 0 ? max : 0
+  const safeValue = Number.isFinite(value) ? value : 0
+  // `clampPct` absorbs NaN / Infinity / a zero denominator to 0 — the whole
+  // reason the ratio is routed through it rather than divided inline.
+  const percent = clampPct(safeMax > 0 ? (safeValue / safeMax) * 100 : 0)
+  const fill = percent / 100
+
+  // Geometry inputs are absorbed here, before anything reaches an SVG
+  // attribute. `width`, `height`, `viewBox` and `stroke-width` are ours to
+  // guard — `lib/chart` only guarantees the values it returns.
+  const safeSize = Number.isFinite(size) && size > 0 ? size : 0
+  const requested = strokeWidth ?? Math.max(2, Math.round(safeSize / 12))
+  const sw = Number.isFinite(requested) && requested > 0 ? requested : 0
+  const { radius } = arcGeometry(safeSize / 2, sw)
+  const centre = safeSize / 2
+  const spin = -90 + (Number.isFinite(startAngle) ? startAngle : 0)
+
+  // Fraction of a full turn the gauge occupies. A 270° gauge is 0.75.
+  const sweepFraction = clampPct((Number.isFinite(sweep) ? sweep : 360) / 3.6) / 100
+
+  // Both arcs come out of the shared accumulator rather than a local
+  // circumference expression: the second element is the unpainted remainder,
+  // so each `[0]` is the arc we want and both start at offset 0.
+  const [trackArc] = arcSegments([sweepFraction, 1 - sweepFraction], safeSize / 2, sw)
+  const painted = sweepFraction * fill
+  const [valueArc] = arcSegments([painted, 1 - painted], safeSize / 2, sw)
+
+  const band = bands ? matchBand(bands, safeValue) : undefined
+  const activeTone: GaugeTone = band?.tone ?? tone
+  const arcColor = fillColor ?? TONE_ARC[activeTone]
+
+  const valueText = formatValue ? formatValue(safeValue) : String(Math.round(safeValue))
+
+  // Reserve the readout's width for the largest plausible reading so the ring
+  // never resizes as the value ticks. `ch` is stable under tabular-nums.
+  const widestReading = (formatValue ? formatValue(safeMax) : String(Math.round(safeMax))).length
+  const readoutCh = Math.max(valueText.length, widestReading) + (unit ? unit.length : 0)
+
+  const valueSize = Math.max(9, Math.round(safeSize * 0.28))
+  const unitSize = Math.max(8, Math.round(valueSize * 0.55))
+  const captionSize = Math.max(8, Math.round(safeSize * 0.11))
+
+  const resolvedCaption = caption === undefined ? band?.label : caption
+  const showBandIcon = caption === undefined && band?.icon !== undefined
+
+  // A non-finite or non-positive `max` collapses to 0, and "10 of 0" is a
+  // worse accessible name than "10". Announce the value alone instead.
+  const spokenScale =
+    safeMax > 0
+      ? ` of ${formatValue ? formatValue(safeMax) : String(Math.round(safeMax))}${unit ?? ''}`
+      : ''
+  const spokenValue = `${valueText}${unit ?? ''}${spokenScale}`
+  const resolvedAriaLabel =
+    ariaLabel ?? (band ? `${spokenValue} — ${band.label}` : spokenValue)
+
+  // `label` (when provided) wins over `showLabel` — the same precedence
+  // CompletionRing established, so a migrating caller keeps its behaviour.
+  const overrideLabel = label !== undefined && label !== false && label !== null
+  const hasReadout = overrideLabel || (label === undefined && showLabel)
+
+  return (
+    <div
+      role="img"
+      aria-label={resolvedAriaLabel}
+      className={cn('relative shrink-0', className)}
+      style={{ width: safeSize, height: safeSize, ...style }}
+    >
+      <svg
+        width={safeSize}
+        height={safeSize}
+        viewBox={`0 0 ${safeSize} ${safeSize}`}
+        aria-hidden="true"
+        focusable="false"
+      >
+        <g transform={`rotate(${spin} ${centre} ${centre})`}>
+          <circle
+            cx={centre}
+            cy={centre}
+            r={radius}
+            fill="none"
+            stroke={trackColor}
+            strokeWidth={sw}
+            strokeLinecap={trackArc && trackArc.fraction > 0 && sweepFraction < 1 ? 'round' : 'butt'}
+            strokeDasharray={trackArc?.dasharray}
+          />
+          <circle
+            cx={centre}
+            cy={centre}
+            r={radius}
+            fill="none"
+            stroke={arcColor}
+            strokeWidth={sw}
+            // A round cap on a zero-length dash paints a stray dot, so an
+            // empty gauge butts instead. This is the "all-zero series" case
+            // ADR-146 names as a required test.
+            strokeLinecap={valueArc && valueArc.fraction > 0 ? 'round' : 'butt'}
+            strokeDasharray={valueArc?.dasharray}
+            // Data changes tween with --dur-base / --ease-out, never
+            // --ease-spring: overshoot on a measurement reads as imprecise
+            // (ADR-146 D9).
+            //
+            // `motion-reduce:transition-none` is load-bearing, not belt and
+            // braces. The duration and easing below are inline and therefore
+            // unconditional; `transition-property`'s INITIAL value is `all`,
+            // so under prefers-reduced-motion — where the motion-safe class
+            // does not apply — the element would inherit `transition: all
+            // var(--dur-base)` and tween the stroke colour, radius and
+            // opacity too. A reduce user would get MORE motion than everyone
+            // else. Declaring `transition-property: none` there is what
+            // actually makes the arc jump to its final state.
+            className="motion-safe:transition-[stroke-dasharray] motion-reduce:transition-none"
+            style={{
+              transitionDuration: 'var(--dur-base)',
+              transitionTimingFunction: 'var(--ease-out)',
+            }}
+          />
+        </g>
+      </svg>
+
+      {hasReadout && (
+        <div
+          className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center leading-none"
+          aria-hidden="true"
+        >
+          {overrideLabel ? (
+            label
+          ) : (
+            <>
+              <div
+                className="flex items-baseline justify-center font-bold tabular-nums leading-none"
+                style={{
+                  color: 'rgb(var(--foreground))',
+                  fontSize: valueSize,
+                  minWidth: `${readoutCh}ch`,
+                }}
+              >
+                {valueText}
+                {unit && (
+                  <span className="font-semibold" style={{ fontSize: unitSize }}>
+                    {unit}
+                  </span>
+                )}
+              </div>
+              {resolvedCaption !== undefined && resolvedCaption !== false && (
+                <div
+                  className="mt-1 flex items-center gap-1 font-semibold leading-none"
+                  style={{
+                    color: band ? TONE_INK[activeTone] : 'rgb(var(--text-tertiary))',
+                    fontSize: captionSize,
+                  }}
+                >
+                  {showBandIcon && band?.icon}
+                  {resolvedCaption}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/hue.ts

@@ -0,0 +1,52 @@
+/**
+ * Board hue keys + the class helper for the derived tint ladder.
+ *
+ * ADR-146 D7 / `docs/design-briefs/tasks-board-design-language.md` §6.
+ *
+ * The ladder itself lives in `styles.css` (`.hue` + one rule per hue). This
+ * file is the typed door into it: lens code names a KEY, never a colour, and
+ * never a class string it composed itself.
+ *
+ * `red` is excluded on purpose — `--folder-red` is byte-identical to
+ * `--accent` in light mode, so a red lane would spend the view's single
+ * accent moment on a whole column of cards.
+ */
+
+import type { FolderColorKey } from './folder-card'
+import { FOLDER_COLOR_KEYS } from './folder-card'
+
+/** The hues a board column may take. Every `--folder-*` key except `red`. */
+export type BoardHueKey = Exclude<FolderColorKey, 'red'>
+
+/** All board hue keys, in palette order — for swatch pickers. */
+export const BOARD_HUE_KEYS: readonly BoardHueKey[] = FOLDER_COLOR_KEYS.filter(
+  (key): key is BoardHueKey => key !== 'red',
+)
+
+/**
+ * The class pair that arms the tint ladder on an element.
+ *
+ * `.hue` declares the six rungs against `--h`; `.hue-<key>` sets `--h`. Both
+ * are required, which is why this returns a pair rather than one class — the
+ * single most likely way to use the ladder wrong is to write `hue-blue` alone
+ * and get a slate card.
+ */
+export function hueClass(key: BoardHueKey): string {
+  return `hue hue-${key}`
+}
+
+/**
+ * A stable hue for an arbitrary identity string (a person, an author, a lens).
+ *
+ * Deterministic so the same name is the same colour on every render and every
+ * machine — an avatar that changes colour between renders reads as a different
+ * person. Not a security or distribution primitive; a display hash.
+ */
+export function hueForKey(seed: string): BoardHueKey {
+  let hash = 0
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0
+  }
+  const index = Math.abs(hash) % BOARD_HUE_KEYS.length
+  return BOARD_HUE_KEYS[index] ?? 'slate'
+}