learning_ai_common_plat/packages/data-viz/src/KpiCard.tsx

import type { CSSProperties, ReactNode } from 'react';
import { Sparkline } from './Sparkline.js';

export interface KpiCardProps {
  /** Metric label (e.g. 'Active users'). */
  label: string;
  /** Pre-formatted display value (e.g. '12.4k', '$8,421'). */
  value: ReactNode;
  /** Delta percentage (e.g. 6.6 for +6.6%). */
  deltaPercent?: number;
  /** Override the delta label (e.g. 'vs last 7d'). */
  deltaLabel?: string;
  /** Inline trend data. Optional. */
  trend?: number[];
  /** Icon rendered top-right. */
  icon?: ReactNode;
  /** Sparkline stroke override. */
  trendColor?: string;
  /** Hide the up/down arrow next to delta. Default false. */
  hideDeltaArrow?: boolean;
  /** Override the threshold below which a delta is rendered as 'good'.
   *  Useful for cost / latency KPIs where lower is better. Default `>=0`. */
  goodWhen?: 'higher' | 'lower';
  className?: string;
  style?: CSSProperties;
}

/**
 * `<KpiCard>` — token-themed key-performance-indicator tile.
 *
 *   ┌────────────────────────┐
 *   │ Active users        ✦  │
 *   │ 8,421                  │
 *   │ ▲ +6.6% vs last 7d ╱╲╱ │
 *   └────────────────────────┘
 *
 * Renders the headline number prominently, an optional delta with
 * color-coded arrow, and an inline `<Sparkline>` for context.
 */
export function KpiCard({
  label,
  value,
  deltaPercent,
  deltaLabel = 'vs previous',
  trend,
  icon,
  trendColor,
  hideDeltaArrow,
  goodWhen = 'higher',
  className,
  style,
}: KpiCardProps) {
  const hasDelta = typeof deltaPercent === 'number';
  const up = hasDelta && deltaPercent! >= 0;
  const good =
    !hasDelta ||
    (goodWhen === 'higher' ? up : !up && Math.abs(deltaPercent!) > 0.0001);
  const deltaColor = good
    ? 'var(--bl-success, #22c55e)'
    : 'var(--bl-danger, #ef4444)';

  return (
    <article
      data-testid="bl-kpi-card"
      className={className}
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 'var(--bl-space-2, 8px)',
        padding: 'var(--bl-space-4, 16px)',
        border: '1px solid var(--bl-border, rgba(0,0,0,0.08))',
        borderRadius: 'var(--bl-radius-card, 12px)',
        background: 'var(--bl-surface-card, #fff)',
        color: 'var(--bl-text-primary, inherit)',
        minWidth: 180,
        ...style,
      }}
    >
      <header
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'space-between',
          gap: 'var(--bl-space-2, 8px)',
        }}
      >
        <span
          style={{
            fontSize: '0.75rem',
            fontWeight: 600,
            textTransform: 'uppercase',
            letterSpacing: '0.04em',
            color: 'var(--bl-text-tertiary, #888)',
          }}
        >
          {label}
        </span>
        {icon && (
          <span
            aria-hidden
            style={{
              display: 'inline-flex',
              alignItems: 'center',
              justifyContent: 'center',
              width: 28,
              height: 28,
              borderRadius: 'var(--bl-radius-pill, 999px)',
              background: 'var(--bl-accent-muted, rgba(99,102,241,0.12))',
              color: 'var(--bl-accent, #6366f1)',
            }}
          >
            {icon}
          </span>
        )}
      </header>

      <div
        data-testid="bl-kpi-value"
        style={{
          fontSize: '2.1rem',
          fontWeight: 700,
          lineHeight: 1.05,
          fontVariantNumeric: 'tabular-nums',
        }}
      >
        {value}
      </div>

      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: 'var(--bl-space-2, 8px)',
          fontSize: '0.78rem',
        }}
      >
        {hasDelta && (
          <span
            data-testid="bl-kpi-delta"
            data-good={good ? 'true' : 'false'}
            style={{
              display: 'inline-flex',
              alignItems: 'center',
              gap: 2,
              color: deltaColor,
              fontWeight: 600,
            }}
          >
            {!hideDeltaArrow && <span aria-hidden>{up ? '▲' : '▼'}</span>}
            {(up ? '+' : '') + deltaPercent!.toFixed(1)}%
          </span>
        )}
        {hasDelta && (
          <span style={{ color: 'var(--bl-text-tertiary, #888)' }}>{deltaLabel}</span>
        )}
        {trend && trend.length > 1 && (
          <div style={{ marginLeft: 'auto' }}>
            <Sparkline
              data={trend}
              width={88}
              height={28}
              stroke={trendColor ?? (good ? 'var(--bl-success, #22c55e)' : 'var(--bl-danger, #ef4444)')}
            />
          </div>
        )}
      </div>
    </article>
  );
}