{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "stat-card", "title": "Stat Card", "author": "ilinxa", "description": "Single-metric dashboard card — value, label, delta, and a dependency-free SVG sparkline with polarity-aware coloring.", "dependencies": [], "registryDependencies": [ "skeleton" ], "files": [ { "path": "src/registry/components/data/stat-card/stat-card.tsx", "content": "import type { ElementType, MouseEvent } from \"react\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { cn } from \"@/lib/utils\";\nimport { defaultDeltaFormat } from \"./lib/format-default\";\nimport { StatCardSparkline } from \"./parts/sparkline\";\nimport {\n DEFAULT_STAT_CARD_LABELS,\n type StatCardDelta,\n type StatCardLabels,\n type StatCardProps,\n type StatCardVariant,\n} from \"./types\";\n\ntype DeltaTone = \"good\" | \"bad\" | \"neutral\";\ntype DeltaDirection = \"up\" | \"down\" | \"neutral\";\n\nfunction deltaDirection(value: number): DeltaDirection {\n if (value > 0) return \"up\";\n if (value < 0) return \"down\";\n return \"neutral\";\n}\n\nfunction deltaTone(direction: DeltaDirection, betterIsHigher: boolean): DeltaTone {\n if (direction === \"neutral\") return \"neutral\";\n if (direction === \"up\") return betterIsHigher ? \"good\" : \"bad\";\n return betterIsHigher ? \"bad\" : \"good\";\n}\n\n// pro-ui doesn't ship a dedicated `--success` token; using `text-chart-2`\n// (calibrated green-leaning hue from the existing chart palette) for the\n// \"good\" tone keeps the component themable via existing tokens. Consumers\n// who want a custom green pass `deltaClassName`.\nconst TONE_CLASSES: Record = {\n good: \"text-chart-2\",\n bad: \"text-destructive\",\n neutral: \"text-muted-foreground\",\n};\n\ninterface DeltaRowProps {\n delta: StatCardDelta;\n labels: Required;\n className?: string;\n}\n\nfunction DeltaRow({ delta, labels, className }: DeltaRowProps) {\n const dir = deltaDirection(delta.value);\n const tone = deltaTone(dir, delta.betterIsHigher ?? true);\n const formatted = (delta.format ?? defaultDeltaFormat)(delta.value);\n const period = delta.period ?? labels.deltaPeriod;\n const srLabel =\n dir === \"up\"\n ? labels.increaseLabel\n : dir === \"down\"\n ? labels.decreaseLabel\n : null;\n\n return (\n \n \n {dir === \"up\" ? \"↑\" : dir === \"down\" ? \"↓\" : \"→\"}\n \n {formatted}\n {srLabel ? {srLabel} : null}\n \n {labels.deltaPrefix} {period}\n \n \n );\n}\n\ninterface VariantSpec {\n /** Outer card padding + min-height (skeleton match). */\n padding: string;\n minHeight: string;\n /** Value text size. */\n valueSize: string;\n labelSize: string;\n /** Whether sparkline renders for this variant. */\n showSparkline: boolean;\n /** Default sparkline height in px (only used when sparkline renders). */\n sparklineHeight: number;\n /** Icon container size. */\n iconBoxSize: string;\n iconSize: string;\n}\n\nconst VARIANT_SPEC: Record = {\n default: {\n padding: \"p-5\",\n minHeight: \"min-h-[7.5rem]\",\n valueSize: \"text-2xl font-bold\",\n labelSize: \"text-sm\",\n showSparkline: true,\n sparklineHeight: 28,\n iconBoxSize: \"h-9 w-9 rounded-md bg-muted\",\n iconSize: \"h-4 w-4\",\n },\n compact: {\n padding: \"p-4\",\n minHeight: \"min-h-[5rem]\",\n valueSize: \"text-xl font-semibold\",\n labelSize: \"text-xs\",\n showSparkline: false,\n sparklineHeight: 0,\n iconBoxSize: \"h-8 w-8 rounded-md bg-muted\",\n iconSize: \"h-4 w-4\",\n },\n detailed: {\n padding: \"p-6\",\n minHeight: \"min-h-[10rem]\",\n valueSize: \"text-3xl font-bold\",\n labelSize: \"text-sm\",\n showSparkline: true,\n sparklineHeight: 36,\n iconBoxSize: \"h-11 w-11 rounded-lg bg-primary/10\",\n iconSize: \"h-5 w-5 text-primary\",\n },\n};\n\n// Per-variant skeleton block sizes — hardcoded rather than derived from\n// VARIANT_SPEC to avoid string-replace surgery on iconBoxSize (which contained\n// `bg-primary/10` in the detailed variant, conflicting with Skeleton's own\n// pulse-animation styling). See v0.1.0 review F-02.\nconst SKELETON_SIZES: Record<\n StatCardVariant,\n { iconBox: string; value: string; sparkline: string }\n> = {\n default: { iconBox: \"h-9 w-9 rounded-md\", value: \"h-7 w-24\", sparkline: \"h-7 w-full\" },\n compact: { iconBox: \"h-8 w-8 rounded-md\", value: \"h-6 w-20\", sparkline: \"h-7 w-full\" },\n detailed: { iconBox: \"h-11 w-11 rounded-lg\", value: \"h-9 w-32\", sparkline: \"h-9 w-full\" },\n};\n\nfunction StatCardSkeleton({\n variant,\n labels,\n className,\n}: {\n variant: StatCardVariant;\n labels: Required;\n className?: string;\n}) {\n const spec = VARIANT_SPEC[variant];\n const sk = SKELETON_SIZES[variant];\n return (\n // aria-busy on a generic div is sufficient — no role=\"region\" (which\n // would require an accessible name we can't supply when loadingLabel\n // is a ReactNode). The sr-only span provides the spoken announcement.\n // See v0.1.0 review F-01.\n \n {labels.loadingLabel}\n
\n
\n \n \n
\n \n \n {spec.showSparkline ? : null}\n
\n \n );\n}\n\ninterface IconBlockProps {\n spec: VariantSpec;\n Icon: NonNullable;\n}\n\nfunction IconBlock({ spec, Icon }: IconBlockProps) {\n return (\n \n \n \n );\n}\n\nexport function StatCard(props: StatCardProps) {\n const {\n value,\n label,\n variant = \"default\",\n delta,\n trend,\n renderTrend,\n icon: Icon,\n iconPosition = \"leading\",\n formatValue,\n renderValue,\n href,\n linkComponent,\n onClick,\n loading = false,\n labels: labelsProp,\n className,\n valueClassName,\n labelClassName,\n deltaClassName,\n ariaLabel,\n } = props;\n\n const labels: Required = {\n ...DEFAULT_STAT_CARD_LABELS,\n ...labelsProp,\n };\n\n if (loading) {\n return (\n \n );\n }\n\n const spec = VARIANT_SPEC[variant];\n\n // Resolve the value cell's content. Priority: renderValue > formatValue > raw.\n // value === undefined renders the empty-state placeholder.\n const isEmpty = value === undefined;\n const valueNode = isEmpty\n ? labels.emptyValueLabel\n : renderValue\n ? renderValue({ value, loading: false })\n : formatValue\n ? formatValue(value)\n : String(value);\n\n // Trend rendering — only when the variant shows it AND data exists.\n let trendNode: React.ReactNode = null;\n if (spec.showSparkline) {\n if (renderTrend && trend) {\n trendNode = renderTrend({ data: trend, variant });\n } else if (trend && trend.length >= 2) {\n trendNode = (\n \n );\n }\n }\n\n const showIconLeading = Icon && iconPosition === \"leading\";\n const showIconTrailing = Icon && iconPosition === \"trailing\";\n\n // Body — same shape across variants; spacing differs via spec.\n const body = (\n <>\n {/* Top row: label + (trailing icon) */}\n
\n \n {label}\n \n {showIconTrailing && Icon ? : null}\n
\n\n {/* Middle row: leading icon + big value */}\n
\n {showIconLeading && Icon ? : null}\n \n {valueNode}\n \n
\n\n {/* Delta row */}\n {delta ? (\n
\n \n
\n ) : null}\n\n {/* Trend / sparkline */}\n {trendNode ? (\n \n {trendNode}\n \n ) : null}\n \n );\n\n // Linked variant — overlay-link pattern.
is the semantic root; the\n // covers it for click capture and gets the focus ring.\n if (href) {\n const LinkComponent: ElementType = linkComponent ?? \"a\";\n const handleClick = onClick\n ? (event: MouseEvent) => onClick({ event })\n : undefined;\n // Resolve the link's accessible name. Priority:\n // 1. Consumer-supplied `ariaLabel` — wins absolutely.\n // 2. `${label}: ${value}` — when both are stringifiable.\n // 3. `${label}` only — when label is stringifiable but value isn't\n // (notably value === undefined). v0.1.1 fix per review F-03 — the\n // v0.1.0 implementation fell through to undefined here, leaving\n // a linked card with no accessible name.\n // 4. undefined — when the label itself is a ReactNode and not a\n // string. Consumer should supply ariaLabel explicitly in that case.\n const computedAriaLabel =\n ariaLabel ??\n (typeof label === \"string\"\n ? typeof value === \"string\" || typeof value === \"number\"\n ? `${label}: ${value}`\n : label\n : undefined);\n\n return (\n \n
{body}
\n \n \n );\n }\n\n // Pure-display variant — no link wrapper, no focus ring.\n return (\n \n {body}\n
\n );\n}\n\nexport default StatCard;\n", "type": "registry:component", "target": "components/stat-card/stat-card.tsx" }, { "path": "src/registry/components/data/stat-card/index.ts", "content": "export { StatCard, default } from \"./stat-card\";\nexport { StatCardSparkline } from \"./parts/sparkline\";\nexport type { StatCardSparklineProps } from \"./parts/sparkline\";\nexport { defaultDeltaFormat } from \"./lib/format-default\";\nexport { DEFAULT_STAT_CARD_LABELS } from \"./types\";\nexport type {\n StatCardDelta,\n StatCardIcon,\n StatCardIconPosition,\n StatCardLabels,\n StatCardProps,\n StatCardTrendContext,\n StatCardValueContext,\n StatCardVariant,\n} from \"./types\";\n// NOTE: `meta` is intentionally NOT re-exported — it's docs-site only,\n// excluded from registry shipments per the post-Phase-7 cleanup\n// (see .claude/decisions/ for the barrel-meta-export removal).\n", "type": "registry:component", "target": "components/stat-card/index.ts" }, { "path": "src/registry/components/data/stat-card/types.ts", "content": "import type { ComponentType, ElementType, MouseEvent, ReactNode } from \"react\";\n\n/** Visual variant. Default: 'default'. */\nexport type StatCardVariant = \"default\" | \"compact\" | \"detailed\";\n\n/** Lucide-style icon prop. */\nexport type StatCardIcon = ComponentType<{ className?: string }>;\n\n/** Position for the optional icon. Default: 'leading'. */\nexport type StatCardIconPosition = \"leading\" | \"trailing\";\n\n/**\n * Delta payload — change since some prior period. Object-shape;\n * F-cross-12 lessons applied at construction.\n */\nexport interface StatCardDelta {\n /**\n * Signed number representing the change. **Convention: a fraction in 0–1\n * range representing a percentage** (`0.124` = +12.4%, `-0.08` = −8.0%).\n * The default `format` callback assumes this convention and renders via\n * `Intl.NumberFormat` with `style: \"percent\"`. For absolute counts\n * (\"+1,240 users\") or other units, override `format`.\n */\n value: number;\n /**\n * Custom formatter. Default: locale-aware\n * `Intl.NumberFormat(undefined, { style: \"percent\", maximumFractionDigits: 1, signDisplay: \"exceptZero\" })`\n * → produces `+12.4%` / `−8.0%` / `0%`. Override for non-percentage units.\n */\n format?: (value: number) => string;\n /**\n * \"Is up good?\" — default `true`. Set `false` for cost / error metrics\n * where ↑ is bad (colors the upward delta red instead of green).\n */\n betterIsHigher?: boolean;\n /**\n * Optional period label rendered after the formatted delta value\n * (e.g. \"vs last 30 days\", \"since Tuesday\", \"from peak\"). ReactNode —\n * consumer owns the copy. Default: `labels.deltaPeriod` (\"last period\").\n */\n period?: ReactNode;\n}\n\n/** Localized labels — defaults English. */\nexport interface StatCardLabels {\n /** Default: 'vs'. Rendered between formatted delta value and period text. */\n deltaPrefix?: ReactNode;\n /** Default: 'last period'. Used as `delta.period` fallback when none supplied. */\n deltaPeriod?: ReactNode;\n /** Default: 'Loading metric…'. Visually-hidden announcement on the loading skeleton. */\n loadingLabel?: ReactNode;\n /** Default: 'increase'. Visually-hidden screen-reader text for positive deltas. */\n increaseLabel?: ReactNode;\n /** Default: 'decrease'. Visually-hidden screen-reader text for negative deltas. */\n decreaseLabel?: ReactNode;\n /** Default: '—'. Rendered at value position when `value === undefined`. */\n emptyValueLabel?: ReactNode;\n}\n\n/** Render-slot context for `renderValue`. */\nexport interface StatCardValueContext {\n value: number | string;\n /** True when this is the value rendered inside the loading skeleton (consumer-side rare). */\n loading: boolean;\n}\n\n/** Render-slot context for `renderTrend` (escape hatch for non-default chart shapes). */\nexport interface StatCardTrendContext {\n data: ReadonlyArray;\n variant: StatCardVariant;\n}\n\nexport interface StatCardProps {\n // ─── Required ────────────────────────────────────────────────────\n /** Big number. Pass primitive (formatted via `formatValue`) or any ReactNode via `renderValue`. */\n value: number | string | undefined;\n /** What this number is. Required. */\n label: ReactNode;\n\n // ─── Variant ─────────────────────────────────────────────────────\n /** Visual variant. Default: 'default'. */\n variant?: StatCardVariant;\n\n // ─── Delta ───────────────────────────────────────────────────────\n /** Optional delta payload. Absent → delta row not rendered. */\n delta?: StatCardDelta;\n\n // ─── Trend / sparkline ───────────────────────────────────────────\n /**\n * Sparkline data — equal-spaced numeric values. Default rendering: pure-SVG\n * single-line chart (no charting peer dep). Empty array or single point → no\n * chart (graceful skip). Cap at 100 points (sampled if more).\n */\n trend?: ReadonlyArray;\n /** Full-takeover render slot for trend visualization (e.g., bars, dual-axis). Receives raw data. */\n renderTrend?: (ctx: StatCardTrendContext) => ReactNode;\n\n // ─── Icon ────────────────────────────────────────────────────────\n /** Optional decorative icon. Lucide-style component. */\n icon?: StatCardIcon;\n /** Position for the icon. Default: 'leading'. */\n iconPosition?: StatCardIconPosition;\n\n // ─── Formatters / slots ──────────────────────────────────────────\n /** Format the big value for display. Default: `String(value)` (no formatting). */\n formatValue?: (value: number | string) => ReactNode;\n /** Full-takeover slot for the value cell (overrides `formatValue`). */\n renderValue?: (ctx: StatCardValueContext) => ReactNode;\n\n // ─── Linking (overlay-link pattern) ──────────────────────────────\n /** URL the card links to. Pairs with `linkComponent`. */\n href?: string;\n /** Element used for the link wrapper. Default: 'a'. */\n linkComponent?: ElementType;\n /**\n * Click handler — F-cross-12-shape (object). Fired before navigation if\n * `href` is also set.\n */\n onClick?: (args: { event: MouseEvent }) => void;\n\n // ─── Loading / empty states ──────────────────────────────────────\n /** When true, renders a skeleton at the same shape as the loaded card. */\n loading?: boolean;\n\n // ─── i18n ────────────────────────────────────────────────────────\n labels?: StatCardLabels;\n\n // ─── Theming / overrides ─────────────────────────────────────────\n /** Override classes for the root
/ . */\n className?: string;\n /** Override classes for the value cell. */\n valueClassName?: string;\n /** Override classes for the label cell. */\n labelClassName?: string;\n /** Override classes for the delta row. */\n deltaClassName?: string;\n\n // ─── Accessibility ───────────────────────────────────────────────\n /**\n * Override the link's accessible name. Default: derived from\n * `${label}: ${formatted-value}`. Only used when `href` is set.\n */\n ariaLabel?: string;\n}\n\n/** Default English labels — exported for consumer composition. */\nexport const DEFAULT_STAT_CARD_LABELS: Required = {\n deltaPrefix: \"vs\",\n deltaPeriod: \"last period\",\n loadingLabel: \"Loading metric…\",\n increaseLabel: \"increase\",\n decreaseLabel: \"decrease\",\n emptyValueLabel: \"—\",\n};\n", "type": "registry:component", "target": "components/stat-card/types.ts" }, { "path": "src/registry/components/data/stat-card/parts/sparkline.tsx", "content": "/**\n * Pure-SVG single-line sparkline. Sibling export of stat-card; consumers can\n * use it standalone via ``.\n *\n * Server-renderable (no state, no client). aria-hidden — the meaningful\n * summary belongs to the surrounding label/value/delta context.\n */\n\nimport { cn } from \"@/lib/utils\";\n\nexport interface StatCardSparklineProps {\n /** Equal-spaced numeric values. */\n data: ReadonlyArray;\n /** Default: 32. SVG viewBox height; visual height controlled by className. */\n height?: number;\n /** Default: 96. SVG viewBox width; visual width controlled by className. */\n width?: number;\n /** Default: `currentColor` (inherits parent text color). */\n strokeColor?: string;\n /** Default: 1.5. */\n strokeWidth?: number;\n /** Tailwind classes for the wrapping ; size/color overrides land here. */\n className?: string;\n}\n\nconst MAX_POINTS = 100;\n\nfunction downsample(data: ReadonlyArray): ReadonlyArray {\n if (data.length <= MAX_POINTS) return data;\n // Uniform sampling — pick every Nth point so the trend shape is preserved.\n const step = data.length / MAX_POINTS;\n const out: number[] = [];\n for (let i = 0; i < MAX_POINTS; i++) out.push(data[Math.floor(i * step)]);\n // Always include the last point so the rightmost edge reflects the latest value.\n out[MAX_POINTS - 1] = data[data.length - 1];\n return out;\n}\n\nexport function StatCardSparkline({\n data,\n height = 32,\n width = 96,\n strokeColor = \"currentColor\",\n strokeWidth = 1.5,\n className,\n}: StatCardSparklineProps) {\n // Skip render for empty / single-point datasets.\n if (data.length < 2) return null;\n\n const points = downsample(data);\n const min = Math.min(...points);\n const max = Math.max(...points);\n const range = max - min;\n\n // Constant data → render a flat line at vertical center.\n const yFor = (v: number) =>\n range === 0 ? height / 2 : height - ((v - min) / range) * height;\n\n const xStep = width / (points.length - 1);\n const path = points\n .map((v, i) => `${i === 0 ? \"M\" : \"L\"} ${(i * xStep).toFixed(2)} ${yFor(v).toFixed(2)}`)\n .join(\" \");\n\n return (\n \n \n \n );\n}\n", "type": "registry:component", "target": "components/stat-card/parts/sparkline.tsx" }, { "path": "src/registry/components/data/stat-card/lib/format-default.ts", "content": "// Locale-aware default delta formatter. Convention: `delta.value` is a\n// fraction (0.124 = +12.4%); the percent style multiplies by 100 internally.\n// `signDisplay: \"exceptZero\"` produces \"+12.4%\" / \"−8.0%\" / \"0%\" — the sign\n// communicates direction; the visual arrow + sr-only label add semantics.\nconst enPercentFormatter = new Intl.NumberFormat(undefined, {\n style: \"percent\",\n maximumFractionDigits: 1,\n signDisplay: \"exceptZero\",\n});\n\n/** Default delta formatter — convention: value is a fraction (0.124 = 12.4%). */\nexport function defaultDeltaFormat(value: number): string {\n return enPercentFormatter.format(value);\n}\n", "type": "registry:component", "target": "components/stat-card/lib/format-default.ts" } ], "categories": [ "data" ], "type": "registry:block" }