@lovett/ui 0.0.11 → 0.2.0

package/src/stat-strip.tsx

@@ -0,0 +1,327 @@
+/**
+ * StatStrip — one card divided into equal columns by hairline borders.
+ *
+ * Promoted in ADR-146 D5 (stat layer); it is the Metoric kit's `Full Stats`
+ * anatomy (spec §7).
+ *
+ * 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):
+ *     • none. `lenses/budget-flighting/components/GlobalHeader.tsx` was
+ *       migrated onto this primitive during ADR-146 and then REVERTED at the
+ *       phase audit: measured in the gallery, this strip renders 116px tall in
+ *       its most compact form (230px with deltas), against the ~29px inline
+ *       chip row it replaced — and that row sits in a `flex items-center`
+ *       header beside a ~28px select. A dashboard header strip (the Metoric
+ *       "Full Stats" anatomy: label ABOVE value, 24px figure, --space-4
+ *       padding) is simply a different object from a compact toolbar chip
+ *       strip, and forcing one into the other was the wrong fit rather than a
+ *       tuning problem. See the ADR-146 completion report, DEV-8.
+ *   PLANNED second consumer: `lenses/sem-spec/output/output-stats-bar.tsx`,
+ *   which hand-rolls this exact anatomy today ("one bordered card ... five
+ *   hairline-divided stat cells", its own docstring). Not migrated. Tracked
+ *   in `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * WHY THIS IS NOT A GRID OF `StatCard`s
+ * -------------------------------------
+ * A dashboard header wants ONE object, not N. `GlobalHeader.tsx:32` forked a
+ * local strip for exactly this reason — its own comment says "a stat group,
+ * not four floating bordered pills (which read as form fields)" — and that
+ * fork is the evidence this shape is a primitive. So: one border, one radius,
+ * one surface, **no per-cell shadow and no gaps between cells**. The kit is
+ * explicit that `Full Stats` carries no tray either (ADR-146 D1 — a tray
+ * appears only when a widget holds more than one internal panel).
+ *
+ * ANATOMY (spec §7, real measurements mapped onto our tokens)
+ * -----------------------------------------------------------
+ *   card    opaque `--surface-card`, `--radius-lg`, 1px `--border`, no shadow
+ *   cell    pad `--space-4`, gap `--space-2`
+ *   label   12px SemiBold, `--text-tertiary`, + optional 16px info icon
+ *   value   24px SemiBold, **line-height 1**, tabular-nums, `--foreground`
+ *           (the kit sets a metric solid while everything else is 1.5 — that
+ *           is what stops a KPI reading loose, and it is worth keeping)
+ *   footer  `DeltaChip` + 14px `--text-secondary` context
+ *
+ * The card is styled here rather than composed from `Card` for the same
+ * reason `ChartFrame` is: `Card` brings a resting shadow, `h-full`, and the
+ * tray auto-wrap, none of which a flat divided strip wants. Same tokens,
+ * same surface — this is not a forked look, it is the same panel without the
+ * lift the kit explicitly does not draw here.
+ *
+ * THE DIVIDERS ACROSS A WRAP — the hard part of this component
+ * ------------------------------------------------------------
+ * Cells must be separated by a 1px rule with **none on the outside**: a
+ * vertical rule between cells in a row, a horizontal rule between wrapped
+ * rows, and nothing on the first row's top or the first column's start edge.
+ * No CSS selector can express "first item of each wrapped row", so the naive
+ * `:not(:last-child)` approach draws a stray vertical rule at the start of
+ * every row after the first.
+ *
+ * The generic answer, and the one used here: give EVERY cell a
+ * `border-inline-start` and a `border-block-start`, then shift the whole row
+ * container back by exactly one hairline (`margin-block-start:-1px`,
+ * `margin-inline-start:-1px`) inside an `overflow:hidden` card. The outermost
+ * borders land outside the padding box and are clipped; every interior one
+ * survives. It is correct for any cell count, at any wrap point, and it is
+ * why a single cell needs no special case — both of its borders are clipped,
+ * so it renders with no dividers at all, for free.
+ *
+ * Logical properties (`inline-start` / `block-start`) rather than left/top, so
+ * the strip is correct under RTL.
+ *
+ * RESPONSIVE — intrinsic, not device presets
+ * -------------------------------------------
+ * The row is `flex-wrap` with every cell at `flex: 1 1 <minCellWidth>`, so it
+ * holds its structure until the content stops fitting and then breaks — 4-up
+ * to 3-up to 2-up to 1-up — against **the strip's own width**, never the
+ * viewport. Two properties of flex earn it over a grid here:
+ *
+ *   1. **The last row fills.** `repeat(auto-fit, minmax(…, 1fr))` leaves an
+ *      empty track when the count does not divide evenly (4 cells in 3
+ *      columns = a visible hole beside the orphan). Flex grows the last row
+ *      to full width instead, so the strip always reads as a finished object.
+ *   2. **Cells in a row stay equal.** Identical basis + identical grow means
+ *      identical width, so a value that changes length cannot resize its own
+ *      column (the D9 reserved-space rule holds structurally, without a
+ *      per-cell `min-width` guess).
+ *
+ * Long localized labels wrap rather than truncate, and never widen a cell:
+ * every cell is `min-width: 0` with `overflow-wrap: anywhere`.
+ *
+ * The footer row (delta + context) is **reserved for every cell whenever any
+ * cell has one**, at a fixed `--space-6` min-height, so a cell WITHOUT a delta
+ * does not sit shorter than its neighbours (D9).
+ *
+ * That derivation cannot cover the case it most needs to: while the deltas are
+ * still in flight NO cell has one, so nothing is reserved, and the slot appears
+ * — growing the strip and shifting the page — the moment the fetch lands. The
+ * data cannot reserve space for itself before it exists. So `reserveFooter`
+ * overrides the derivation: a caller that KNOWS deltas are coming passes
+ * `reserveFooter` and the slot is there from the first paint.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`; every padding, gap
+ * and radius is a token. The only bare number is the hairline (1px — the
+ * border width it cancels) and `minCellWidth`, which is a wrap threshold, not
+ * spacing. No motion: nothing here is interactive, and a stat that animates
+ * on hover advertises an interaction it does not have.
+ */
+
+import { Info } from 'lucide-react'
+import type { ReactNode } from 'react'
+
+import { cn } from './lib/utils'
+import { DeltaChip, type DeltaChipProps } from './delta-chip'
+
+/**
+ * The divider width, and the offset that cancels the outermost ones.
+ * Not spacing — this is the border's own geometry, so it does not come off
+ * the `--space-*` scale. Kept as one constant so the two can never drift.
+ */
+const HAIRLINE = '1px'
+const HAIRLINE_OFFSET = '-1px'
+
+/** Default wrap threshold: the narrowest a cell may get before the row breaks. */
+const DEFAULT_MIN_CELL_WIDTH = 180
+
+/**
+ * Default `ch` slot reserved for every value, matching `StatCard`'s `lg`
+ * reserve — "1,234,567" fits in 9. Strip-level rather than per-cell, because
+ * a strip's whole job is to read as one object with one rhythm.
+ */
+const DEFAULT_VALUE_CHARS = 9
+
+export interface StatStripCell {
+  /**
+   * Stable identity key — also the React key. Use the stat's own id, never
+   * the array index: a strip whose cells are filtered must not re-key.
+   */
+  key: string
+  /** The stat name. 12px semibold, muted. Wraps; never truncated. */
+  label: string
+  /**
+   * The headline value. Pre-format through `@lovett/ui/format` — the strip
+   * only sets it 24px semibold, solid, in `tabular-nums`.
+   */
+  value: ReactNode
+  /**
+   * Optional hint. Renders the 16px info icon beside the label, carrying this
+   * text as both its accessible name and its hover title.
+   */
+  info?: string
+  /**
+   * Optional change indicator. Props are handed straight to `DeltaChip` —
+   * the strip never re-implements the arrow/tone ternary that ADR-146 D5
+   * exists to delete.
+   */
+  delta?: DeltaChipProps
+  /**
+   * Optional 14px context beside the delta ("vs last month"). Wears
+   * `--text-secondary`; it is prose, not a number.
+   */
+  context?: ReactNode
+}
+
+export interface StatStripProps {
+  /** The stats, in reading order. Renders nothing when empty. */
+  cells: readonly StatStripCell[]
+  /**
+   * Narrowest a cell may get before the row wraps, in px. This is a layout
+   * threshold measured against the strip's own width — raise it for cells
+   * with long values, lower it for a dense strip of short counts.
+   */
+  minCellWidth?: number
+  /**
+   * Character slot reserved for every value so a ticking number cannot resize
+   * anything (D9). Sized for the largest plausible value; a longer one still
+   * grows past it rather than clipping.
+   */
+  valueChars?: number
+  /**
+   * Force the delta/context footer slot on (or off) instead of deriving it
+   * from the data. Pass `true` when the deltas arrive from a later fetch than
+   * the values: the derived default reserves nothing while every `delta` is
+   * still `undefined`, so the slot would pop in and grow the strip exactly
+   * when the numbers land (D9). Defaults to "reserve it if any cell has one".
+   */
+  reserveFooter?: boolean
+  /**
+   * Accessible name for the group, e.g. "Plan totals". Recommended whenever
+   * more than one strip is on a page.
+   */
+  ariaLabel?: string
+  /** Optional className on the outer card. */
+  className?: string
+}
+
+export function StatStrip({
+  cells,
+  minCellWidth = DEFAULT_MIN_CELL_WIDTH,
+  valueChars = DEFAULT_VALUE_CHARS,
+  reserveFooter,
+  ariaLabel,
+  className,
+}: StatStripProps) {
+  // An empty strip is an empty bordered box — worse than nothing. A caller
+  // with a genuinely empty data set shows its own empty state.
+  if (cells.length === 0) return null
+
+  // Reserve the footer for every cell as soon as ANY cell owns one, so the
+  // strip's height is decided by its shape and not by which cell has a delta.
+  // An explicit `reserveFooter` wins, because the derivation is blind to the
+  // one case that matters: deltas that have not arrived yet.
+  const showFooter =
+    reserveFooter ??
+    cells.some(
+      (cell) => cell.delta !== undefined || cell.context !== undefined,
+    )
+
+  return (
+    <div
+      className={cn('overflow-hidden', className)}
+      style={{
+        background: 'rgb(var(--surface-card))',
+        border: `${HAIRLINE} solid rgb(var(--border))`,
+        borderRadius: 'var(--radius-lg)',
+      }}
+    >
+      <dl
+        aria-label={ariaLabel}
+        className="flex flex-wrap"
+        style={{
+          // Pulled back by one hairline in both axes so the first row's top
+          // borders and the first column's start borders fall outside the
+          // padding box and are clipped by `overflow:hidden` above. Every
+          // interior divider survives, at any wrap point. See the header.
+          margin: 0,
+          marginBlockStart: HAIRLINE_OFFSET,
+          marginInlineStart: HAIRLINE_OFFSET,
+        }}
+      >
+        {cells.map((cell) => (
+          <div
+            key={cell.key}
+            className="flex min-w-0 flex-col"
+            style={{
+              flex: `1 1 ${minCellWidth}px`,
+              padding: 'var(--space-4)',
+              gap: 'var(--space-2)',
+              borderBlockStart: `${HAIRLINE} solid rgb(var(--border))`,
+              borderInlineStart: `${HAIRLINE} solid rgb(var(--border))`,
+            }}
+          >
+            <dt
+              className="flex items-start text-[12px] font-semibold leading-[1.5]"
+              style={{
+                gap: 'var(--space-1)',
+                color: 'rgb(var(--text-tertiary))',
+              }}
+            >
+              <span className="min-w-0 [overflow-wrap:anywhere]">
+                {cell.label}
+              </span>
+              {cell.info !== undefined && (
+                // `sr-only` text rather than `role="img" aria-label`, which
+                // is the same pattern `DeltaChip` uses for its direction word.
+                // An aria-label names the icon and `title` then DESCRIBES it,
+                // so an accname-correct reader announces the same sentence
+                // twice. Here the hint is read once, as part of the <dt>, and
+                // `title` stays for the sighted hover.
+                <span
+                  title={cell.info}
+                  className="inline-flex shrink-0"
+                  style={{ color: 'rgb(var(--text-muted))' }}
+                >
+                  <Info size={16} aria-hidden="true" />
+                  <span className="sr-only">{cell.info}</span>
+                </span>
+              )}
+            </dt>
+
+            <dd
+              className="text-[24px] font-semibold leading-none tabular-nums [overflow-wrap:anywhere]"
+              style={{
+                margin: 0,
+                color: 'rgb(var(--foreground))',
+                minWidth: `${valueChars}ch`,
+              }}
+            >
+              {cell.value}
+            </dd>
+
+            {showFooter && (
+              <dd
+                // A reserved-but-empty slot is a blank <dd>, which AT reads as
+                // an empty description of the stat above it. It is spacing, so
+                // it is hidden rather than announced.
+                aria-hidden={
+                  cell.delta === undefined && cell.context === undefined
+                    ? true
+                    : undefined
+                }
+                className="flex flex-wrap items-center"
+                style={{
+                  margin: 0,
+                  gap: 'var(--space-2)',
+                  // Reserved, not conditional: the slot exists in every cell
+                  // so a late-arriving delta cannot grow the strip (D9).
+                  minHeight: 'var(--space-6)',
+                }}
+              >
+                {cell.delta !== undefined && <DeltaChip {...cell.delta} />}
+                {cell.context !== undefined && (
+                  <span
+                    className="text-[14px] leading-[1.5] [overflow-wrap:anywhere]"
+                    style={{ color: 'rgb(var(--text-secondary))' }}
+                  >
+                    {cell.context}
+                  </span>
+                )}
+              </dd>
+            )}
+          </div>
+        ))}
+      </dl>
+    </div>
+  )
+}

package/src/status.tsx

@@ -0,0 +1,215 @@
+/**
+ * The status vocabulary — `StatusRing` (degree of completion) and
+ * `StatusGlyph` (discrete state).
+ *
+ * `docs/design-briefs/tasks-board-header-primitives.md` §2. The source app
+ * (continuity-control) hand-wrote six inline-SVG glyphs that take no props at
+ * all, and filled them from a HARDCODED constant per status — a control that
+ * looks like a meter and measures nothing, rendered next to a real `62%` from
+ * a different source. Two adjacent sources of truth, and neither one is the
+ * ledger's.
+ *
+ * So this file draws the line the source never did:
+ *
+ *   - **A real number gets a ring.** `StatusRing` takes a percent and renders
+ *     that percent. It is fed by `ledgerProgress()` (progress-ledger.tsx) —
+ *     the SAME function that computes the number the ledger prints as text, so
+ *     a ring and its ledger cannot disagree.
+ *   - **A discrete state gets a lucide glyph**, sized and coloured by props
+ *     like every other icon in the system (CLAUDE.md §6). Five of the six
+ *     shapes the source hand-rolled already ship in lucide; the partial ring
+ *     was the only real gap, and that is exactly what `StatusRing` is.
+ *
+ * Colour comes from the `--folder-*` hue via the tint ladder (`hue.ts`), and
+ * NOTHING here is legible by colour alone: a glyph carries its state in its
+ * accessible name (or in an adjacent visible label), and a ring carries its
+ * percent in its accessible name (or is marked decorative when the number
+ * already sits beside it as text). Never both — a ring announced next to a
+ * printed percentage says the number twice.
+ */
+
+import type { CSSProperties } from 'react'
+import {
+  Circle,
+  CircleCheck,
+  CircleDashed,
+  CircleDotDashed,
+  CircleSlash,
+  CircleX,
+  type LucideIcon,
+} from 'lucide-react'
+import { cn } from './lib/utils'
+import CompletionRing from './completion-ring'
+import { hueClass, type BoardHueKey } from './hue'
+
+/**
+ * The six discrete states.
+ *
+ * `blocked` has no signal behind it in the Tasks board yet — an item carries
+ * no blocked flag — so it is vocabulary, not a rendered state, until one
+ * exists. It is declared here rather than added later because the map is what
+ * makes the set consistent across a column, a rail row and a card.
+ */
+export type BoardStatusKey =
+  | 'empty'
+  | 'todo'
+  | 'in-progress'
+  | 'blocked'
+  | 'done'
+  | 'cancelled'
+
+export const BOARD_STATUS_KEYS: readonly BoardStatusKey[] = [
+  'empty',
+  'todo',
+  'in-progress',
+  'blocked',
+  'done',
+  'cancelled',
+]
+
+/**
+ * Lucide, never a hand-rolled `<svg>`. The shapes match the source's own queue
+ * view, which is the better half of its codebase — its comment says the icon
+ * must carry the meaning so state never reads by colour alone, and this map is
+ * how that stays true in one place instead of six call sites.
+ */
+export const STATUS_GLYPHS: Readonly<Record<BoardStatusKey, LucideIcon>> = {
+  empty: CircleDashed,
+  todo: Circle,
+  'in-progress': CircleDotDashed,
+  blocked: CircleSlash,
+  done: CircleCheck,
+  cancelled: CircleX,
+}
+
+/** Operator language, sentence case (interface-standards §7). No schema words. */
+export const STATUS_LABELS: Readonly<Record<BoardStatusKey, string>> = {
+  empty: 'Nothing here yet',
+  todo: 'Not started',
+  'in-progress': 'In progress',
+  blocked: 'Blocked',
+  done: 'Done',
+  cancelled: 'Cancelled',
+}
+
+export interface StatusGlyphProps {
+  status: BoardStatusKey
+  /** Optical size in px. Default 14 — the board header's marker size. */
+  size?: number
+  /**
+   * Default 2, matching a 600-weight label (interface-standards §5). Pass 1.5
+   * beside 400-weight meta text.
+   */
+  strokeWidth?: number
+  /** Overrides the accessible name. Defaults to the state's own label. */
+  label?: string
+  /**
+   * True when the state is ALREADY spelled out in adjacent visible text — the
+   * glyph then adds nothing to the accessible name and only repeats it.
+   */
+  decorative?: boolean
+  className?: string
+}
+
+export function StatusGlyph({
+  status,
+  size = 14,
+  strokeWidth = 2,
+  label,
+  decorative = false,
+  className,
+}: StatusGlyphProps) {
+  const Glyph = STATUS_GLYPHS[status]
+  return (
+    <Glyph
+      size={size}
+      strokeWidth={strokeWidth}
+      className={cn('shrink-0', className)}
+      // The INK rung, not the raw hue: `--h` on a frame surface measures under
+      // 3:1 in light mode for half the ladder. `--tint-ink` mixes toward
+      // --foreground, so it is readable in BOTH themes. Falls back to a
+      // neutral when no `.hue` ancestor has armed the ladder.
+      style={{ color: 'var(--tint-ink, rgb(var(--text-tertiary)))' }}
+      {...(decorative
+        ? { 'aria-hidden': true }
+        : { role: 'img', 'aria-label': label ?? STATUS_LABELS[status] })}
+    />
+  )
+}
+
+export interface StatusRingProps {
+  /** 0–100. Values outside the range are clamped, never wrapped. */
+  percent: number
+  /** Outer dimension in px. Default 14. */
+  size?: number
+  /** Ring stroke in px. Default 2. */
+  strokeWidth?: number
+  /**
+   * Arms the tint ladder locally. Omit when an ancestor already carries
+   * `hueClass(...)` — the board column and the card both do.
+   */
+  hue?: BoardHueKey
+  /** Overrides the accessible name. Defaults to `{n}% complete`. */
+  label?: string
+  /**
+   * True when a text percentage sits beside it. The ring is then `aria-hidden`
+   * so the number is announced once, not twice.
+   */
+  decorative?: boolean
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * The arc-stroke ring (header-primitives §2):
+ *
+ *   circumference    = 2πr
+ *   strokeDashoffset = circumference · (1 − clamp(percent, 0, 100) / 100)
+ *   transform="rotate(-90 c c)"   strokeLinecap="round"
+ *
+ * That geometry already exists once in this package, in `CompletionRing`, so
+ * this composes it rather than pasting a second copy of the maths — a second
+ * copy is precisely the defect the brief indicts. What `StatusRing` adds is
+ * the board's contract on top of it: the hue ladder instead of the accent, a
+ * `--border` track, no centre label (the ledger prints the number), and an
+ * explicit announced-or-decorative choice.
+ */
+export function StatusRing({
+  percent,
+  size = 14,
+  strokeWidth = 2,
+  hue,
+  label,
+  decorative = false,
+  className,
+  style,
+}: StatusRingProps) {
+  const clamped = Math.max(0, Math.min(100, percent))
+  const name = label ?? `${Math.round(clamped)}% complete`
+
+  return (
+    <span
+      className={cn(
+        'ds-status-ring inline-flex shrink-0',
+        hue ? hueClass(hue) : undefined,
+        className,
+      )}
+      style={style}
+      {...(decorative ? { 'aria-hidden': true } : { role: 'img', 'aria-label': name })}
+    >
+      <CompletionRing
+        percent={clamped}
+        size={size}
+        strokeWidth={strokeWidth}
+        label={false}
+        // Grey structure, per the data-display recipe — the track is the
+        // unfilled remainder, not a surface.
+        trackColor="rgb(var(--border))"
+        // The hue ladder's raw hue. The fallback is the ladder's own default,
+        // so a ring outside a `.hue` ancestor renders slate rather than
+        // nothing.
+        fillColor="var(--h, rgb(var(--folder-slate)))"
+      />
+    </span>
+  )
+}