Metrics Grid Glass

1// ========================================
2// METRICS GRID GLASS - COMPOSITE COMPONENT
3// Responsive grid of metric cards
4// Level 3: Composite (extracted from TrustScoreCardGlass)
5// ========================================
6 
7import { forwardRef, type HTMLAttributes } from 'react';
8import { cn } from '@/lib/utils';
9import { MetricCardGlass, type MetricVariant } from './metric-card-glass';
10import '@/glass-theme.css';
11 
12/**
13 * Metric data structure for MetricsGridGlass.
14 *
15 * Defines a single metric to be displayed in the grid.
16 *
17 * @example
18 * ```tsx
19 * const metric: MetricData = {
20 *   title: 'Total Repositories',
21 *   value: 42,
22 *   variant: 'default',
23 * };
24 * ```
25 */
26export interface MetricData {
27  /** Metric title/label */
28  readonly title: string;
29  /** Metric value (number or string) */
30  readonly value: string | number;
31  /** Visual variant (default, success, warning, destructive) */
32  readonly variant: MetricVariant;
33}
34 
35/**
36 * Props for MetricsGridGlass component.
37 *
38 * Extends standard div attributes for maximum flexibility.
39 * All props are readonly to ensure immutability.
40 *
41 * @example
42 * ```tsx
43 * const props: MetricsGridGlassProps = {
44 *   metrics: [
45 *     { title: 'Total Repos', value: 42, variant: 'default' },
46 *     { title: 'Stars', value: '1.2k', variant: 'success' },
47 *   ],
48 *   columns: 4,
49 *   gap: 'md',
50 * };
51 * ```
52 */
53export interface MetricsGridGlassProps extends HTMLAttributes<HTMLDivElement> {
54  /**
55   * Array of metrics to display in the grid.
56   *
57   * Each metric requires title, value, and variant.
58   * Returns null if array is empty.
59   *
60   * @example
61   * ```tsx
62   * const metrics = [
63   *   { title: 'Commits', value: 1234, variant: 'default' },
64   *   { title: 'Stars', value: '2.5k', variant: 'success' },
65   *   { title: 'Issues', value: 8, variant: 'warning' },
66   *   { title: 'Forks', value: 156, variant: 'default' },
67   * ];
68   * <MetricsGridGlass metrics={metrics} />
69   * ```
70   */
71  readonly metrics: readonly MetricData[];
72 
73  /**
74   * Number of columns on desktop breakpoint (1-6).
75   *
76   * Automatically responsive:
77   * - 1: Single column (all breakpoints)
78   * - 2: 1 col mobile, 2 cols sm+
79   * - 3: 1 col mobile, 2 cols sm+, 3 cols md+
80   * - 4: 2 cols mobile, 3 cols sm+, 4 cols md+
81   * - 5: 2 cols mobile, 3 cols sm+, 5 cols md+
82   * - 6: 2 cols mobile, 3 cols sm+, 6 cols md+
83   *
84   * @default 4
85   */
86  readonly columns?: 1 | 2 | 3 | 4 | 5 | 6;
87 
88  /**
89   * Gap size between metric cards.
90   *
91// … truncated