{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "stat-row-baseline-spark",
  "title": "Stat Row Baseline Spark",
  "description": "A KPI row implementing the stat-tile figure contract (value, delta, sparkline) honestly: the sparkline behind each number is the same series the delta is computed from, hovering or focusing surfaces exactly which point that delta is measured against, and color only ever means 'this is good news for this metric', never 'the number went up'.",
  "dependencies": [],
  "files": [
    {
      "path": "registry/core/stat-row-baseline-spark/component.tsx",
      "content": "\"use client\";\n\nexport type StatPolarity = \"higherIsBetter\" | \"lowerIsBetter\" | \"neutral\";\n\nexport interface StatTileData {\n  /** Stable id, used as the React key and in the aria-label. */\n  id: string;\n  label: string;\n  value: number;\n  /** Suffix (\"%\", \"ms\") or \"$\" for a prefix — anything else renders as a suffix. */\n  unit?: string;\n  /** Chronological, oldest first, NOT including `value` — value is the implicit latest point. */\n  history: number[];\n  /** Index into `history` the delta is measured against. Defaults to 0 (the oldest point). */\n  baselineIndex?: number;\n  /** States what the delta is against, e.g. \"30d ago\" — the delta is never shown without it. */\n  baselineLabel: string;\n  /** Which direction is actually good. Omit (or \"neutral\") to render the delta with no emphasis. */\n  polarity?: StatPolarity;\n  precision?: number;\n}\n\nexport interface StatTileRowProps {\n  /** the stat tiles, in order */\n  tiles: StatTileData[];\n  /** extra classes merged onto the rendered root element */\n  className?: string;\n}\n\nconst W = 100;\nconst H = 34;\nconst PAD = 3;\n\nfunction formatValue(v: number, unit: string | undefined, precision: number): string {\n  const n = v.toLocaleString(undefined, { minimumFractionDigits: precision, maximumFractionDigits: precision });\n  if (!unit) return n;\n  return unit === \"$\" ? `$${n}` : `${n}${unit}`;\n}\n\nfunction Sparkline({\n  points,\n  baselineIndex,\n  favorable,\n}: {\n  points: number[];\n  baselineIndex: number;\n  favorable: boolean | null;\n}) {\n  const min = Math.min(...points);\n  const max = Math.max(...points);\n  const span = max - min || 1;\n  const x = (i: number) => (points.length === 1 ? W / 2 : (i / (points.length - 1)) * W);\n  const y = (v: number) => H - PAD - ((v - min) / span) * (H - PAD * 2);\n\n  const lineD = points.map((v, i) => `${i === 0 ? \"M\" : \"L\"}${x(i)},${y(v)}`).join(\" \");\n  const areaD = `${lineD} L${x(points.length - 1)},${H} L${x(0)},${H} Z`;\n  const lastIdx = points.length - 1;\n  const baselineY = y(points[baselineIndex] ?? points[0]);\n  const baselineX = x(baselineIndex);\n\n  return (\n    <svg\n      aria-hidden\n      className=\"pointer-events-none absolute inset-x-0 bottom-0 h-9 w-full overflow-visible\"\n      viewBox={`0 0 ${W} ${H}`}\n      preserveAspectRatio=\"none\"\n    >\n      <path d={areaD} className=\"fill-ns-muted/10\" />\n      <path d={lineD} className=\"fill-none stroke-ns-muted\" strokeWidth={1} vectorEffect=\"non-scaling-stroke\" />\n      {/* baseline guide — only surfaces on hover/focus, alongside the reference dot below */}\n      <line\n        x1={baselineX}\n        x2={baselineX}\n        y1={baselineY}\n        y2={H}\n        className=\"stroke-border opacity-0 transition-opacity duration-150 group-hover:opacity-100 group-focus-visible:opacity-100\"\n        strokeWidth={1}\n        strokeDasharray=\"2 2\"\n        vectorEffect=\"non-scaling-stroke\"\n      />\n      <circle\n        cx={baselineX}\n        cy={baselineY}\n        r={2}\n        className=\"fill-background stroke-ns-muted opacity-0 transition-opacity duration-150 group-hover:opacity-100 group-focus-visible:opacity-100\"\n        strokeWidth={1}\n        vectorEffect=\"non-scaling-stroke\"\n      />\n      <circle cx={x(lastIdx)} cy={y(points[lastIdx])} r={2.25} className={favorable ? \"fill-ns-accent\" : \"fill-foreground\"} />\n    </svg>\n  );\n}\n\nfunction Tile({ tile }: { tile: StatTileData }) {\n  const precision = tile.precision ?? 0;\n  const baselineIndex = Math.min(Math.max(tile.baselineIndex ?? 0, 0), Math.max(tile.history.length - 1, 0));\n  const baseline = tile.history[baselineIndex] ?? tile.value;\n  const delta = tile.value - baseline;\n  const direction: \"up\" | \"down\" | \"flat\" = delta > 0 ? \"up\" : delta < 0 ? \"down\" : \"flat\";\n  const polarity = tile.polarity ?? \"neutral\";\n  const favorable =\n    polarity === \"neutral\" ? null : polarity === \"higherIsBetter\" ? delta > 0 : delta < 0;\n  const arrow = direction === \"up\" ? \"▲\" : direction === \"down\" ? \"▼\" : \"–\";\n  const deltaText = formatValue(Math.abs(delta), tile.unit, precision);\n  const points = [...tile.history, tile.value];\n\n  const directionWord = direction === \"up\" ? \"up\" : direction === \"down\" ? \"down\" : \"unchanged\";\n  const goodnessWord = favorable === null ? \"\" : favorable ? \", favorable\" : \", unfavorable\";\n  const ariaLabel = `${tile.label}: ${formatValue(tile.value, tile.unit, precision)}, ${directionWord} ${deltaText} vs ${tile.baselineLabel}${goodnessWord}`;\n\n  return (\n    <button\n      type=\"button\"\n      aria-label={ariaLabel}\n      className=\"group relative flex min-h-[128px] w-full flex-col justify-between overflow-hidden rounded-md border border-border bg-surface p-4 text-left transition-colors duration-150 hover:border-ns-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ns-accent\"\n    >\n      <div className=\"relative z-10\">\n        <p className=\"mb-2 font-mono text-[10px] uppercase tracking-widest text-ns-muted\">{tile.label}</p>\n        <p className=\"font-mono text-2xl tabular-nums text-foreground\">{formatValue(tile.value, tile.unit, precision)}</p>\n        <p className={`mt-1 font-mono text-xs tabular-nums ${favorable ? \"font-semibold text-ns-accent\" : \"text-ns-muted\"}`}>\n          <span aria-hidden>{arrow}</span> {deltaText}\n          <span className=\"ml-1 text-ns-muted/80\">vs {tile.baselineLabel}</span>\n        </p>\n      </div>\n      <Sparkline points={points} baselineIndex={baselineIndex} favorable={favorable} />\n    </button>\n  );\n}\n\n/**\n * A KPI row where every number arrives with its receipts: the sparkline\n * behind the figure is the same history the delta is computed from, and the\n * delta always states what it's measured against rather than assuming\n * \"vs last point\" silently. See each tile's instruction section for the\n * honesty rules governing color and direction.\n */\nexport function StatTileRow({ tiles, className = \"\" }: StatTileRowProps) {\n  return (\n    <div\n      role=\"group\"\n      aria-label=\"Stat tiles\"\n      className={`grid gap-3 ${className}`}\n      // Container-width responsive rather than viewport-media-query\n      // responsive: a row dropped into a narrow sidebar wraps to fewer\n      // columns on its own, the same as inside a full-width dashboard body —\n      // no breakpoint prop to get wrong.\n      style={{ gridTemplateColumns: \"repeat(auto-fit, minmax(11rem, 1fr))\" }}\n    >\n      {tiles.map((tile) => (\n        <Tile key={tile.id} tile={tile} />\n      ))}\n    </div>\n  );\n}\n",
      "type": "registry:ui",
      "target": "components/ui/stat-row-baseline-spark.tsx"
    }
  ],
  "cssVars": {
    "theme": {
      "color-ns-muted": "var(--ns-muted)",
      "color-ns-accent": "var(--ns-accent)",
      "color-surface": "var(--surface)"
    },
    "light": {
      "ns-muted": "#4d4d4d",
      "ns-accent": "#006bff",
      "surface": "#fafafa"
    },
    "dark": {
      "ns-muted": "#8f8f8f",
      "surface": "#171717"
    }
  },
  "meta": {
    "collection": "core",
    "tags": [
      "stat-tile",
      "kpi",
      "data-viz",
      "sparkline",
      "delta",
      "dashboard",
      "accessibility"
    ],
    "instruction": "A stat tile row built to the dataviz skill's figure contract — value, delta, optional sparkline — with the two parts most implementations get dishonest: what the delta is measured against, and what its color is allowed to mean. Each tile takes `value` plus `history` (chronological, oldest first, NOT including `value` — `value` is the implicit newest point) and a required `baselineLabel` string stating what the delta compares to in words ('30d ago', 'vs target'); there is no silent 'vs previous point' default with nothing said about it. `baselineIndex` (default 0, the oldest history point) selects which history entry that comparison is against, and the SAME index drives a marker drawn directly on the sparkline — a dashed guide line and a hollow ring at that exact point — so the number and the chart are never two disconnected claims about the same series. That marker, like the sparkline's own resting state, is nearly invisible until the tile is hovered or keyboard-focused, at which point it fades in over 150ms; the resting sparkline still reads as a shape (10% muted-fill area, thin muted line) but the specific comparison point is something you have to ask for, the same way a tooltip is. COLOR: every tile ships an optional `polarity` — 'higherIsBetter' | 'lowerIsBetter' | 'neutral' (default) — and it is the ONLY thing allowed to trigger the tile's one accent moment: the delta text and the sparkline's current-value dot switch from --ns-muted to --ns-accent when the change is favorable BY THAT POLARITY, never by raw sign. A falling error rate (lowerIsBetter, value < baseline) gets the accent precisely because a fall is what 'better' means for that metric; a falling revenue number does not, and a 'neutral' tile never gets it regardless of direction — this is deliberate, since the registry's token rule leaves no red/green to fall back on anyway, so the arrow glyph (▲/▼/–) is what carries literal direction, unconditionally and honestly, while accent-vs-muted separately carries 'is this good'. Each tile is a real `<button>` (not a div faking one) with a single computed `aria-label` stating the value, the literal direction word, the delta, the baseline label and, if polarity is set, whether the change is favorable — so a screen reader user gets the exact same honesty a sighted user gets from color, rather than the color-only version most stat tiles ship. The row itself is `role=group`. Sparkline geometry is one small pure function per tile: points are `[...history, value]` scaled into a fixed 100x34 viewBox with `preserveAspectRatio=none` so it stretches to the tile's real width, no canvas, no ResizeObserver needed. All ink is Tailwind utility classes resolving to --background/--foreground/--ns-muted/--border/--ns-accent (fill-ns-muted, stroke-ns-muted, stroke-border, fill-ns-accent, fill-foreground) — no raw color anywhere, so both themes render from the same markup with zero JS color derivation. Reduced motion is inherent rather than stripped: the only animated properties are opacity/color transitions on hover and focus, which stay because they are what exposes the baseline marker at all — there is no motion to remove, only a state to reach non-visually via Tab, which every tile already supports."
  },
  "type": "registry:ui"
}