Metric Card Glass

1/**
2 * MetricCardGlass Component
3 *
4 * Rich metric display card with progress bars, sparklines, and trend indicators.
5 * Follows shadcn/ui variant system with Glass UI extensions for data visualization.
6 *
7 * ## Features
8 * - 5 semantic variants (default, secondary, success, warning, destructive)
9 * - Trend indicators with directional arrows (up/down/neutral)
10 * - Optional progress bar with gradient colors matched to variant
11 * - Optional sparkline chart for trend visualization
12 * - Flexible change display (string, number, or detailed MetricChange object)
13 * - Score ratio display (e.g., "85/100") via maxScore prop
14 * - Optional explain button with HelpCircle icon
15 * - Hover lift effect via InteractiveCard primitive
16 * - Responsive sizing (sm, md, lg text scales)
17 * - Theme-aware with per-variant CSS variables
18 *
19 * ## CSS Variables
20 * Per-variant variables (5 variants × 4 properties = 20 variables):
21 * - `--metric-default-bg`, `--metric-default-text`, `--metric-default-border`, `--metric-default-glow`
22 * - `--metric-secondary-bg`, `--metric-secondary-text`, `--metric-secondary-border`, `--metric-secondary-glow`
23 * - `--metric-success-bg`, `--metric-success-text`, `--metric-success-border`, `--metric-success-glow`
24 * - `--metric-warning-bg`, `--metric-warning-text`, `--metric-warning-border`, `--metric-warning-glow`
25 * - `--metric-destructive-bg`, `--metric-destructive-text`, `--metric-destructive-border`, `--metric-destructive-glow`
26 *
27 * @example Basic metric card (shadcn/ui style)
28 * ```tsx
29 * import { MetricCardGlass } from 'shadcn-glass-ui'
30 * import { DollarSign } from 'lucide-react'
31 *
32 * function Dashboard() {
33 *   return (
34 *     <MetricCardGlass
35 *       title="Total Revenue"
36 *       value="$45,231"
37 *       change="+12.5%"
38 *       variant="success"
39 *       icon={<DollarSign className="w-4 h-4" />}
40 *     />
41 *   )
42 * }
43 * ```
44 *
45 * @example With progress bar and sparkline
46 * ```tsx
47 * <MetricCardGlass
48 *   title="Completion Rate"
49 *   value="85%"
50 *   description="Project milestones"
51 *   change={{ value: 5.2, direction: 'up', period: 'vs last month' }}
52 *   variant="success"
53 *   progress={85}
54 *   sparklineData={[70, 75, 78, 80, 82, 84, 85]}
55 *   showProgress
56 *   showSparkline
57 * />
58 * ```
59 *
60 * @example Score ratio display
61 * ```tsx
62 * <MetricCardGlass
63 *   title="Test Coverage"
64 *   value={92}
65 *   maxScore={100}
66 *   description="Unit tests"
67 *   variant="success"
68 *   progress={92}
69 *   showProgress
70 * />
71 * // Displays: "92/100"
72// … truncated