@lovett/ui 0.0.11 → 0.2.0

package/src/stat-card.tsx

@@ -0,0 +1,376 @@
+/**
+ * StatCard — the KPI card: label, value, delta, optional icon tile, optional
+ * footer.
+ *
+ * Promoted in ADR-146 D5 (stat layer).
+ *
+ * CONSUMERS — measured 2026-09-06 by grepping real `from '@lovett/ui'`
+ * imports under `apps/workspace/src`. The design-system gallery
+ * (`design-system/registry/demos/analytics.tsx`) is a demo harness and does
+ * NOT count toward the ADR-008 D3 gate.
+ *   TODAY (2 — ADR-008 D3 gate MET, the only primitive in this set that
+ *   clears it):
+ *     • `components/ui/admin/stat-tile.tsx`   — the analytics KPI grid
+ *     • `lenses/keywords/keyword-stats.tsx`   — volume / CPC / competition
+ *   PLANNED, not written: creative-checker (spec pass rate), sem-spec
+ *   (output stats). Tracked in `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * `MetricCard`, `ShellStat` and `StatRow` are NOT deleted by this file —
+ * `StatCard` is the superset and migration of the ~26 forked tiles is
+ * ADR-146 D13 (`converge-stat-forks.md`).
+ *
+ * WHY THIS EXISTS AT ALL
+ * ----------------------
+ * The inventory behind ADR-146 found three shipped KPI primitives and ~26
+ * lens-local re-implementations of the same label+value tile. The cause is
+ * one missing slot: **not one shipped primitive can express "value + how it
+ * changed"**, which is the entire job of a KPI card. So every lens that
+ * needed a delta forked the tile. The delta slot is the point of this
+ * primitive; everything else is anatomy.
+ *
+ * ANATOMY (METORIC-ANALYTICS-SPEC §2, §4; ADR-146 D1)
+ * ---------------------------------------------------
+ *   frame   `.ds-card-surface[data-framed]`  --surface-frame, r16, pad 4
+ *     panel `.ds-card-tray`                  --surface-card,  r12, pad 16
+ *     footer                                 on the frame, below the panel
+ *
+ * The radii are concentric by construction: 16 - 4 = 12. Both classes are
+ * the ones `Card`, `Modal` and `ProfileSection` already use, so this is the
+ * house frame, not a forked `<div>`.
+ *
+ * THE TRAY IS CONDITIONAL — this is the source kit's own rule and it is
+ * load-bearing. A stat card with nothing but a value has ONE panel, so it is
+ * a plain `.ds-card-surface` with no frame; wrapping it anyway gives every
+ * card in a KPI grid a redundant 4px border-in-a-border. The frame appears
+ * only when there is a second thing to separate — here, a footer.
+ *
+ * LINE-HEIGHT 1 ON THE VALUE
+ * --------------------------
+ * Everything else in the card is 1.5. The metric is set solid (spec §4), and
+ * that single difference is what stops a KPI card reading loose. Do not
+ * "fix" it to match its siblings.
+ *
+ * RESERVED SPACE (design principles → Layout stability)
+ * -----------------------------------------------------
+ * A KPI is the most likely thing on a page to tick. The value gets a `ch`
+ * min-width plus `tabular-nums` so digits cannot change the card's width,
+ * and BOTH branches — the value row and the pending well — render into ONE
+ * `--space-6` slot, so adding a delta chip or swapping in the well cannot
+ * change the card's height. That is why the well is padded to the chip's
+ * own 2px rhythm rather than a control's 8px: at 8px it stood 10px taller
+ * than the row it replaces, and a pending card grew its whole grid row.
+ * The one exception is `pendingHint`, which adds a deliberate second line.
+ * A stat card whose box breathes with its contents is the cheap-UI tell.
+ *
+ * PENDING IS NOT ZERO
+ * -------------------
+ * `pending` renders an explicit "Not available" well instead of a number.
+ * This behaviour is carried over from `admin/stat-tile.tsx` where it is
+ * load-bearing (ADR-088 D6): an analytics tile with no data must never
+ * fabricate a figure, and `0` is a fabricated figure.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`; no colour literals,
+ * no constructed token names. Sizes come from `--space-*`, `--radius-*` and
+ * `--ctrl-md` (the 40px icon tile). The two value sizes are frozen static
+ * Tailwind classes — never interpolated, because an interpolated arbitrary
+ * value is statically unscannable and generates nothing.
+ */
+
+import type { ReactNode } from 'react'
+import { ArrowRight } from 'lucide-react'
+import { cn } from './lib/utils'
+import { DeltaChip, type DeltaChipProps } from './delta-chip'
+
+/** `md` = 18px value (dense grids), `lg` = 24px (a hero KPI). Spec §4. */
+export type StatCardSize = 'md' | 'lg'
+
+/**
+ * Frozen static class strings. `text-[${n}px]` would type-check, lint and
+ * build while generating no CSS at all — Tailwind scans source statically.
+ */
+const VALUE_CLASS: Record<StatCardSize, string> = {
+  md: 'text-[18px]',
+  lg: 'text-[24px]',
+}
+
+/**
+ * Default `ch` reserve per size. 6 fits "482.5K" / "12,480" — the compact
+ * and 5-digit forms a KPI actually ticks through. A caller whose figure runs
+ * longer raises `valueChars`; the value grows past the reserve rather than
+ * clipping, so the default is a floor, not a cap.
+ */
+const VALUE_RESERVE: Record<StatCardSize, number> = {
+  md: 6,
+  lg: 6,
+}
+
+export interface StatCardFooterLink {
+  /** Visible text. Carries the accessible name — no bare icon link. */
+  label: string
+  /** Renders an `<a>`. Mutually exclusive with `onClick` in practice. */
+  href?: string
+  /** Renders a `<button>` when there is no `href`. */
+  onClick?: () => void
+}
+
+export interface StatCardProps {
+  /** Small muted caption above the value. 12px semibold (spec §4). */
+  label: string
+  /**
+   * The headline figure. Pass a PRE-FORMATTED string from
+   * `@lovett/ui/format` — the card does not format, so a caller can pick
+   * currency, compact or ratio without a prop explosion.
+   */
+  value: ReactNode
+  /**
+   * Period-over-period change, rendered as a `<DeltaChip>`. Typed as the
+   * chip's own props so a caller cannot fork the chip — passing a `ReactNode`
+   * here is exactly how the ~26 forks started.
+   */
+  delta?: DeltaChipProps
+  /** `md` (18px value) or `lg` (24px). Default `md`. */
+  size?: StatCardSize
+  /**
+   * Optional 20px Lucide icon, rendered in a 40x40 raised tile at the
+   * card's trailing edge. Pass the element (`<TrendingUp size={20} />`) so
+   * the caller owns the glyph; the tile owns the surface.
+   */
+  icon?: ReactNode
+  /**
+   * Secondary text below the panel. Its presence is what promotes the card
+   * to the framed tray anatomy — see the header.
+   */
+  footer?: ReactNode
+  /** Optional trailing link/arrow in the footer row. Also promotes the tray. */
+  footerLink?: StatCardFooterLink
+  /**
+   * No data for this metric. Renders the "Not available" well instead of a
+   * number, and suppresses the delta. Never render `0` for missing data.
+   */
+  pending?: boolean
+  /** Headline shown in the pending well. Default "Not available". */
+  pendingLabel?: string
+  /** Optional second line in the pending well — why, or what unit is missing. */
+  pendingHint?: string
+  /**
+   * Character slot reserved for the value so a ticking number cannot resize
+   * the card. Defaults to 6; raise it for figures that will exceed it.
+   */
+  valueChars?: number
+  /** Optional class override for the outermost element. */
+  className?: string
+}
+
+export function StatCard({
+  label,
+  value,
+  delta,
+  size = 'md',
+  icon,
+  footer,
+  footerLink,
+  pending = false,
+  pendingLabel = 'Not available',
+  pendingHint,
+  valueChars,
+  className,
+}: StatCardProps) {
+  // The tray exists only when there is a second thing inside the frame.
+  const framed = Boolean(footer || footerLink)
+  const reserve = valueChars ?? VALUE_RESERVE[size]
+
+  const panel = (
+    <div
+      className="flex items-start justify-between"
+      style={{ gap: 'var(--space-4)' }}
+    >
+      <div
+        className="flex min-w-0 flex-col"
+        style={{ gap: 'var(--space-2)' }}
+      >
+        <span
+          className="text-[12px] font-semibold leading-[1.5]"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          {label}
+        </span>
+
+        {/* ONE slot for both branches — see the header. --space-6 clears
+            the 24px `lg` value, the 22px chip and a single-line well, so
+            pending → loaded is not a layout shift. */}
+        <div
+          // `flex-wrap`: when the value plus the chip genuinely cannot fit the
+          // column (a 3-up KPI grid at desktop width is already that narrow),
+          // the chip drops to a second line. Without it the row keeps
+          // shrinking and the two paint ON TOP of each other — measured 12px
+          // of "6,140,000" under its own delta chip in the gallery's KPI row.
+          // A card that grows by one line in the overflow case is strictly
+          // better than a card that renders illegible text.
+          className="flex flex-wrap items-center"
+          style={{ gap: 'var(--space-2)', minHeight: 'var(--space-6)' }}
+        >
+          {pending ? (
+            <div
+              className="flex flex-col"
+              style={{
+                gap: 'calc(var(--space-1) / 2)',
+                // The chip's own 2/8 rhythm, so the well fits the reserved
+                // row instead of growing it.
+                padding: 'calc(var(--space-1) / 2) var(--space-2)',
+                borderRadius: 'var(--radius-xs)',
+                background: 'rgb(var(--muted))',
+                boxShadow: 'inset 0 0 0 1px rgb(var(--border))',
+              }}
+            >
+              <span
+                className="text-[12px] font-semibold leading-[1.5]"
+                style={{ color: 'rgb(var(--text-secondary))' }}
+              >
+                {pendingLabel}
+              </span>
+              {pendingHint && (
+                <span
+                  className="text-[12px] leading-[1.5]"
+                  // --text-tertiary, NOT --text-muted: tokens.css documents
+                  // --text-muted as non-text/disabled chrome only (3.47:1 on
+                  // a white card, under the 4.5:1 text floor). The hint is
+                  // real prose a user has to read.
+                  style={{ color: 'rgb(var(--text-tertiary))' }}
+                >
+                  {pendingHint}
+                </span>
+              )}
+            </div>
+          ) : (
+            <>
+              <span
+                className={cn(
+                  // Size FIRST: tailwind-merge treats font-size as conflicting
+                  // with line-height (a Tailwind text-* utility sets both), so
+                  // a size class placed after `leading-none` deletes it — and
+                  // the value silently reverts to 1.5, which is the exact
+                  // "looks loose" defect the solid setting exists to prevent.
+                  VALUE_CLASS[size],
+                  // Line-height 1: the metric is set solid. See the header.
+                  'font-semibold leading-none tabular-nums',
+                  // `shrink-0` is what makes the documented contract true. An
+                  // explicit `min-width` REPLACES flexbox's default
+                  // `min-width: auto` (min-content) protection, so without
+                  // this the span shrinks to exactly the reserve and the
+                  // longer figure overflows its own box — painting under the
+                  // delta chip rather than "growing past the reserve".
+                  'shrink-0',
+                )}
+                style={{
+                  color: 'rgb(var(--foreground))',
+                  minWidth: `${reserve}ch`,
+                }}
+              >
+                {value}
+              </span>
+              {delta && <DeltaChip {...delta} />}
+            </>
+          )}
+        </div>
+      </div>
+
+      {icon && (
+        <span
+          className="inline-flex shrink-0 items-center justify-center"
+          style={{
+            width: 'var(--ctrl-md)',
+            height: 'var(--ctrl-md)',
+            borderRadius: 'var(--radius-sm)',
+            // --surface-raised, NOT --surface-card: in dark the card IS
+            // --surface-card, so a card-coloured tile is the same colour as
+            // the thing it sits on and only an 8%-alpha border separates
+            // them. --surface-raised (ADR-063) is white in light — identical
+            // to today — and a real step up in dark.
+            background: 'rgb(var(--surface-raised))',
+            border: '1px solid rgb(var(--border-card))',
+            boxShadow: 'var(--shadow-sm)',
+            color: 'rgb(var(--text-tertiary))',
+          }}
+        >
+          {icon}
+        </span>
+      )}
+    </div>
+  )
+
+  if (!framed) {
+    // One panel, so no frame: a plain card at --radius-lg.
+    return (
+      <div
+        data-pending={pending ? 'true' : undefined}
+        className={cn('ds-card-surface', className)}
+        style={{ padding: 'var(--space-4)' }}
+      >
+        {panel}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-framed="true"
+      data-pending={pending ? 'true' : undefined}
+      className={cn('ds-card-surface flex flex-col', className)}
+    >
+      <div className="ds-card-tray" style={{ padding: 'var(--space-4)' }}>
+        {panel}
+      </div>
+      <div
+        className="flex items-center justify-between text-[12px] leading-[1.5]"
+        style={{
+          gap: 'var(--space-3)',
+          // Left pad = tray margin (4) + tray padding (16), so the footer
+          // text sits on the same column as the label above it.
+          padding: 'var(--space-2) var(--space-5) var(--space-3)',
+          color: 'rgb(var(--text-tertiary))',
+        }}
+      >
+        <span className="min-w-0 truncate">{footer}</span>
+        {footerLink && <FooterLink {...footerLink} />}
+      </div>
+    </div>
+  )
+}
+
+function FooterLink({ label, href, onClick }: StatCardFooterLink) {
+  const className = cn(
+    'inline-flex shrink-0 items-center text-[12px] font-semibold leading-[1.5]',
+    'transition-colors duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+    'motion-reduce:transition-none',
+    // Colour lives in a class, not the style object: an inline `color`
+    // outranks any class, so a hover rule beside it would never paint.
+    '[color:rgb(var(--text-secondary))] hover:[color:rgb(var(--foreground))]',
+    'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+  )
+  const style = {
+    gap: 'var(--space-1)',
+    padding: 'calc(var(--space-1) / 2) var(--space-1)',
+    borderRadius: 'var(--radius-xs)',
+  }
+  const body = (
+    <>
+      {label}
+      <ArrowRight size={14} strokeWidth={2} aria-hidden="true" />
+    </>
+  )
+
+  if (href) {
+    // onClick is wired here too — an <a href> that silently dropped a
+    // handler the caller passed is a bug that only shows up in analytics.
+    return (
+      <a href={href} onClick={onClick} className={className} style={style}>
+        {body}
+      </a>
+    )
+  }
+  return (
+    <button type="button" onClick={onClick} className={className} style={style}>
+      {body}
+    </button>
+  )
+}