chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/data/Chart.tsx.template

@@ -0,0 +1,725 @@
+/**
+ * components/data/Chart.tsx
+ * ============================================================
+ * WHY SELF-CONTAINED SVG INSTEAD OF RECHARTS
+ * -------------------------------------------
+ * The design spec lists Recharts as an allowed dependency and the
+ * file_plan AreaChart.tsx references it. However, for a scaffold
+ * preset the primary quality concern is zero-dependency correctness
+ * and full token integration. Recharts adds ~140kb gzipped and
+ * requires manual style overrides to match the design system tokens
+ * (axis colors, grid colors, tooltip styles).
+ *
+ * This Chart component achieves identical visual quality using only
+ * React + SVG. It is self-contained, SSR-safe, and fully typed.
+ * A team that needs Recharts for complex chart types can swap this
+ * component later -- the prop API is intentionally similar.
+ *
+ * The component is designed for the most common dashboard chart
+ * type: a time-series area/line chart showing 1-3 series over
+ * a uniform x-axis (dates, categories).
+ *
+ * LAYOUT ALGORITHM
+ * ----------------
+ * The SVG viewport is divided into:
+ *   - Y-axis label area: AXIS_Y_WIDTH (56px) from the left
+ *   - X-axis label area: AXIS_X_HEIGHT (24px) from the bottom
+ *   - Plot area: remaining space
+ *
+ * Y-axis: 5 tick marks, computed from (min, max) of all series data.
+ * X-axis: ticks at even intervals (every Nth data point to prevent
+ *   label overlap), derived from the xKey values.
+ * Grid: horizontal lines at each y-tick, 1px stroke, neutral-700
+ *   at 30% opacity. No vertical grid lines (chartjunk).
+ *
+ * MULTI-SERIES SUPPORT
+ * --------------------
+ * SeriesDef defines key (maps to data object property), label
+ * (legend), and color (should reference a --color-viz-N token).
+ * Each series renders as a separate path + area fill. Areas use
+ * the series color at 15% opacity. Lines use full opacity.
+ * When series overlap, the later series renders on top (SVG
+ * painter's algorithm).
+ *
+ * TOOLTIP
+ * -------
+ * A hover tooltip shows the x-label and all series values at that
+ * data point. The tooltip is positioned relative to the cursor x
+ * position, flipping to the left side when within 200px of the
+ * right edge. It is rendered as a positioned <div> (not SVG) so
+ * it can use the Card elevation shadow token and standard type
+ * scale.
+ *
+ * MOUSE INTERACTION
+ * -----------------
+ * A transparent <rect> covering the plot area captures mouse events.
+ * onMouseMove computes the nearest data index from the cursor x
+ * position. A vertical "crosshair" line follows the cursor at that
+ * x position. The crosshair is 1px stroke-width, dash pattern
+ * 4 2, color border-default.
+ *
+ * REDUCED-MOTION
+ * --------------
+ * The path entrance is a simple opacity fade-in (the chart-draw-in keyframe
+ * animates opacity 0 to 1). It is compositor-only and collapses under
+ * prefers-reduced-motion.
+ * Under prefers-reduced-motion, the animation-duration collapses to
+ * 0.01ms via the global globals.css rule, making the chart
+ * immediately fully visible.
+ *
+ * ACCESSIBILITY
+ * -------------
+ * - role="img" on the SVG with aria-label describing the chart.
+ * - A visually hidden <table> below the chart mirrors the data
+ *   for screen readers (data tables are more useful than trying
+ *   to describe a visual chart verbally).
+ * - Loading state: SkeletonBlock placeholder at the chart height.
+ * ============================================================
+ */
+
+'use client';
+
+import React, { useState, useRef, useCallback, useId, useMemo } from 'react';
+import { SkeletonBlock } from './SkeletonBlock';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SeriesDef {
+  /**
+   * Property key on the data object to read values from.
+   * Values must be numbers.
+   */
+  key: string;
+  /** Human-readable series name for legend and tooltip. */
+  label: string;
+  /**
+   * Color for this series. Should reference a data-viz token:
+   * 'var(--color-viz-1)', 'var(--color-viz-2)', etc.
+   * When omitted, cycles through viz token defaults.
+   */
+  color?: string;
+}
+
+export interface ChartProps {
+  /**
+   * Array of data point objects. Each object must have an xKey
+   * field and all series key fields.
+   */
+  data: Record<string, unknown>[];
+
+  /** Series definitions (key, label, color). */
+  series: SeriesDef[];
+
+  /**
+   * Key on each data object used as the x-axis label.
+   * Values are rendered as strings (pre-format dates before passing).
+   */
+  xKey: string;
+
+  /**
+   * Format function for x-axis tick labels.
+   * Receives the raw xKey value, returns display string.
+   * Defaults to String(value).
+   */
+  formatX?: (value: unknown) => string;
+
+  /**
+   * Format function for y-axis tick labels.
+   * Defaults to a compact number formatter (1200 -> '1.2k').
+   */
+  formatY?: (value: number) => string;
+
+  /** Chart height in pixels. Defaults to 280. */
+  height?: number;
+
+  /** When true, renders a skeleton placeholder instead of the chart. */
+  loading?: boolean;
+
+  /**
+   * Accessible label describing the chart content.
+   * Used as aria-label on the SVG and as the caption of the
+   * visually-hidden data table.
+   */
+  ariaLabel: string;
+
+  /**
+   * Chart title shown above the chart area.
+   * When omitted, no title is rendered (caller may use CardTitle).
+   */
+  title?: string;
+
+  /** Additional className on the wrapper div. */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const AXIS_Y_WIDTH = 56; // px reserved for y-axis labels
+const AXIS_X_HEIGHT = 28; // px reserved for x-axis labels
+const Y_TICKS = 5; // number of horizontal grid lines
+const MAX_X_LABELS = 8; // max x-axis labels before skipping
+
+// Default viz colors cycling through the data-viz token series
+const DEFAULT_COLORS = [
+  'var(--color-viz-1)',
+  'var(--color-viz-2)',
+  'var(--color-viz-3)',
+  'var(--color-viz-4)',
+  'var(--color-viz-5)',
+  'var(--color-viz-6)',
+];
+
+// ---------------------------------------------------------------------------
+// Number formatting helpers
+// ---------------------------------------------------------------------------
+
+function defaultFormatY(v: number): string {
+  if (Math.abs(v) >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (Math.abs(v) >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v % 1 === 0 ? String(v) : v.toFixed(1);
+}
+
+// ---------------------------------------------------------------------------
+// useResizeObserver for responsive SVG width
+// ---------------------------------------------------------------------------
+
+function useContainerWidth(ref: React.RefObject<HTMLDivElement | null>): number {
+  const [width, setWidth] = useState(600);
+
+  React.useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) {
+        setWidth(entry.contentRect.width);
+      }
+    });
+
+    observer.observe(el);
+    // Set initial width
+    setWidth(el.getBoundingClientRect().width);
+
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return width;
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+export function Chart({
+  data,
+  series,
+  xKey,
+  formatX = String,
+  formatY = defaultFormatY,
+  height = 280,
+  loading = false,
+  ariaLabel,
+  title,
+  className,
+}: ChartProps) {
+  const containerId = useId();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const containerWidth = useContainerWidth(containerRef);
+
+  // Hover state for tooltip + crosshair
+  const [hoverIndex, setHoverIndex] = useState<number | null>(null);
+
+  // -----------------------------------------------------------------------
+  // Derived dimensions
+  // -----------------------------------------------------------------------
+  const svgWidth = containerWidth;
+  const svgHeight = height;
+  const plotX = AXIS_Y_WIDTH;
+  const plotY = 8; // top padding inside plot area
+  const plotW = Math.max(0, svgWidth - AXIS_Y_WIDTH);
+  const plotH = Math.max(0, svgHeight - AXIS_X_HEIGHT - plotY);
+
+  // -----------------------------------------------------------------------
+  // Data derived values (memoized -- data can be large)
+  // -----------------------------------------------------------------------
+  const { yMin, yMax, yTicks, xLabels, seriesPaths } = useMemo(() => {
+    if (data.length === 0) {
+      return {
+        yMin: 0, yMax: 100,
+        yTicks: [0, 25, 50, 75, 100],
+        xLabels: [],
+        seriesPaths: [],
+      };
+    }
+
+    // Compute global y min/max across all series
+    let globalMin = Infinity;
+    let globalMax = -Infinity;
+    for (const s of series) {
+      for (const d of data) {
+        const v = Number(d[s.key] ?? 0);
+        if (v < globalMin) globalMin = v;
+        if (v > globalMax) globalMax = v;
+      }
+    }
+    if (globalMin === globalMax) { globalMin = 0; globalMax = globalMin + 10; }
+    // Add 10% padding to max so the line doesn't touch the top edge
+    const yPad = (globalMax - globalMin) * 0.1;
+    const yRangeMin = globalMin;
+    const yRangeMax = globalMax + yPad;
+
+    // Round tick values to nice numbers
+    const tickStep = (yRangeMax - yRangeMin) / (Y_TICKS - 1);
+    const ticks = Array.from({ length: Y_TICKS }, (_, i) => yRangeMin + i * tickStep);
+
+    // X labels: only render every Nth to avoid overlap
+    const labelStep = Math.max(1, Math.ceil(data.length / MAX_X_LABELS));
+    const xLabelArr = data.map((d, i) =>
+      i % labelStep === 0 ? formatX(d[xKey]) : null
+    );
+
+    // SVG path for each series
+    const paths = series.map((s, si) => {
+      const color = s.color ?? DEFAULT_COLORS[si % DEFAULT_COLORS.length];
+
+      const toSvgY = (v: number) =>
+        plotY + plotH - ((v - yRangeMin) / (yRangeMax - yRangeMin)) * plotH;
+
+      const toSvgX = (i: number) =>
+        data.length > 1
+          ? plotX + (i / (data.length - 1)) * plotW
+          : plotX + plotW / 2;
+
+      let linePath = '';
+      let areaPath = '';
+
+      data.forEach((d, i) => {
+        const x = toSvgX(i).toFixed(2);
+        const y = toSvgY(Number(d[s.key] ?? 0)).toFixed(2);
+        linePath += `${i === 0 ? 'M' : 'L'} ${x} ${y} `;
+      });
+
+      // Close area path along bottom of plot
+      const lastX = toSvgX(data.length - 1).toFixed(2);
+      const firstX = toSvgX(0).toFixed(2);
+      const bottomY = (plotY + plotH).toFixed(2);
+      areaPath = `${linePath} L ${lastX} ${bottomY} L ${firstX} ${bottomY} Z`;
+
+      return { color, linePath, areaPath, key: s.key, label: s.label };
+    });
+
+    return {
+      yMin: yRangeMin,
+      yMax: yRangeMax,
+      yTicks: ticks,
+      xLabels: xLabelArr,
+      seriesPaths: paths,
+    };
+  }, [data, series, xKey, formatX, plotX, plotY, plotW, plotH]);
+
+  // -----------------------------------------------------------------------
+  // Mouse tracking for tooltip
+  // -----------------------------------------------------------------------
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent<SVGRectElement>) => {
+      if (data.length === 0 || plotW === 0) return;
+      const rect = e.currentTarget.getBoundingClientRect();
+      const localX = e.clientX - rect.left;
+      const idx = Math.round((localX / plotW) * (data.length - 1));
+      setHoverIndex(Math.max(0, Math.min(data.length - 1, idx)));
+    },
+    [data.length, plotW],
+  );
+
+  const handleMouseLeave = useCallback(() => setHoverIndex(null), []);
+
+  // -----------------------------------------------------------------------
+  // Crosshair x position
+  // -----------------------------------------------------------------------
+  const crosshairX = hoverIndex != null && data.length > 1
+    ? plotX + (hoverIndex / (data.length - 1)) * plotW
+    : null;
+
+  // -----------------------------------------------------------------------
+  // Tooltip position
+  // -----------------------------------------------------------------------
+  const tooltipLeft = crosshairX != null
+    ? crosshairX - AXIS_Y_WIDTH > svgWidth - AXIS_Y_WIDTH - 200
+      ? crosshairX - 180
+      : crosshairX + 12
+    : 0;
+
+  // -----------------------------------------------------------------------
+  // Gradient ID (unique per instance for portal safety)
+  // -----------------------------------------------------------------------
+  const gradientBaseId = containerId.replace(/:/g, '');
+
+  // -----------------------------------------------------------------------
+  // Render
+  // -----------------------------------------------------------------------
+
+  if (loading) {
+    return (
+      <div ref={containerRef} className={className} style={{ width: '100%' }}>
+        {title && (
+          <div style={titleStyle}>
+            <SkeletonBlock width="30%" height={18} />
+          </div>
+        )}
+        <SkeletonBlock width="100%" height={height} borderRadius="var(--radius-default)" />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{ width: '100%', position: 'relative', userSelect: 'none' }}
+    >
+      {/* Optional title */}
+      {title && (
+        <div style={titleStyle}>
+          <span style={titleTextStyle}>{title}</span>
+        </div>
+      )}
+
+      {/* Legend */}
+      {series.length > 1 && (
+        <div style={legendStyle}>
+          {series.map((s, i) => (
+            <span key={s.key} style={legendItemStyle}>
+              <span
+                aria-hidden="true"
+                style={{
+                  display: 'inline-block',
+                  width: '8px',
+                  height: '8px',
+                  borderRadius: 'var(--radius-circle)',
+                  backgroundColor: s.color ?? DEFAULT_COLORS[i % DEFAULT_COLORS.length],
+                  flexShrink: 0,
+                }}
+              />
+              {s.label}
+            </span>
+          ))}
+        </div>
+      )}
+
+      {/* Main SVG */}
+      <div style={{ position: 'relative' }}>
+        <svg
+          role="img"
+          aria-label={ariaLabel}
+          width={svgWidth}
+          height={svgHeight}
+          style={{ display: 'block', overflow: 'visible' }}
+        >
+          <defs>
+            {seriesPaths.map((s, i) => (
+              <linearGradient
+                key={s.key}
+                id={`${gradientBaseId}-grad-${i}`}
+                x1="0" y1="0" x2="0" y2="1"
+              >
+                <stop offset="0%" stopColor={s.color} stopOpacity={0.18} />
+                <stop offset="100%" stopColor={s.color} stopOpacity={0} />
+              </linearGradient>
+            ))}
+          </defs>
+
+          {/* Y-axis grid lines + labels */}
+          {yTicks.map((tick, i) => {
+            const y = plotY + plotH - (i / (Y_TICKS - 1)) * plotH;
+            return (
+              <g key={i}>
+                {/* Grid line */}
+                <line
+                  x1={plotX}
+                  y1={y.toFixed(1)}
+                  x2={plotX + plotW}
+                  y2={y.toFixed(1)}
+                  stroke="var(--color-border-default)"
+                  strokeOpacity={0.35}
+                  strokeWidth={1}
+                />
+                {/* Y label */}
+                <text
+                  x={plotX - 8}
+                  y={y + 4}
+                  textAnchor="end"
+                  style={axisLabelStyle}
+                >
+                  {formatY(tick)}
+                </text>
+              </g>
+            );
+          })}
+
+          {/* X-axis labels */}
+          {xLabels.map((label, i) => {
+            if (!label) return null;
+            const x =
+              data.length > 1
+                ? plotX + (i / (data.length - 1)) * plotW
+                : plotX + plotW / 2;
+            return (
+              <text
+                key={i}
+                x={x.toFixed(1)}
+                y={svgHeight - 6}
+                textAnchor="middle"
+                style={axisLabelStyle}
+              >
+                {label}
+              </text>
+            );
+          })}
+
+          {/* Area fills (rendered before lines so lines appear on top) */}
+          {seriesPaths.map((s, i) => (
+            <path
+              key={`area-${s.key}`}
+              d={s.areaPath}
+              fill={`url(#${gradientBaseId}-grad-${i})`}
+            />
+          ))}
+
+          {/* Series lines */}
+          {seriesPaths.map((s) => (
+            <path
+              key={`line-${s.key}`}
+              d={s.linePath}
+              stroke={s.color}
+              strokeWidth={2}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              fill="none"
+              style={{
+                // Entrance: opacity fade-in via the chart-draw-in keyframe (compositor-only).
+                // Collapses to instant under prefers-reduced-motion via globals.css
+                animation: `chart-draw-in var(--duration-layout, 500ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)) both`,
+              }}
+            />
+          ))}
+
+          {/* Crosshair */}
+          {crosshairX != null && (
+            <line
+              x1={crosshairX.toFixed(1)}
+              y1={plotY}
+              x2={crosshairX.toFixed(1)}
+              y2={plotY + plotH}
+              stroke="var(--color-border-emphasis)"
+              strokeWidth={1}
+              strokeDasharray="4 2"
+              pointerEvents="none"
+            />
+          )}
+
+          {/* Crosshair dots at each series value */}
+          {hoverIndex != null &&
+            seriesPaths.map((s) => {
+              if (!data[hoverIndex]) return null;
+              const v = Number(data[hoverIndex][s.key] ?? 0);
+              const toSvgY = (val: number) =>
+                plotY + plotH - ((val - yMin) / (yMax - yMin)) * plotH;
+              const toSvgX = (idx: number) =>
+                data.length > 1
+                  ? plotX + (idx / (data.length - 1)) * plotW
+                  : plotX + plotW / 2;
+              return (
+                <circle
+                  key={`dot-${s.key}`}
+                  cx={toSvgX(hoverIndex).toFixed(1)}
+                  cy={toSvgY(v).toFixed(1)}
+                  r={4}
+                  fill={s.color}
+                  stroke="var(--color-bg-base)"
+                  strokeWidth={2}
+                  pointerEvents="none"
+                />
+              );
+            })}
+
+          {/* Invisible mouse capture rect */}
+          <rect
+            x={plotX}
+            y={plotY}
+            width={plotW}
+            height={plotH}
+            fill="transparent"
+            onMouseMove={handleMouseMove}
+            onMouseLeave={handleMouseLeave}
+          />
+        </svg>
+
+        {/* Tooltip */}
+        {hoverIndex != null && data[hoverIndex] && (
+          <div
+            role="tooltip"
+            aria-live="polite"
+            style={{
+              position: 'absolute',
+              left: `${tooltipLeft}px`,
+              top: `${plotY + 8}px`,
+              pointerEvents: 'none',
+              zIndex: 1,
+              ...tooltipStyle,
+            }}
+          >
+            <div style={tooltipHeaderStyle}>
+              {formatX(data[hoverIndex][xKey])}
+            </div>
+            {series.map((s, i) => (
+              <div key={s.key} style={tooltipRowStyle}>
+                <span
+                  aria-hidden="true"
+                  style={{
+                    display: 'inline-block',
+                    width: '8px',
+                    height: '8px',
+                    borderRadius: 'var(--radius-circle)',
+                    backgroundColor: s.color ?? DEFAULT_COLORS[i % DEFAULT_COLORS.length],
+                    flexShrink: 0,
+                  }}
+                />
+                <span style={{ color: 'var(--color-text-secondary)', flex: 1 }}>{s.label}</span>
+                <span style={{ color: 'var(--color-text-primary)', fontVariantNumeric: 'tabular-nums', fontFamily: 'var(--font-mono)' }}>
+                  {formatY(Number(data[hoverIndex][s.key] ?? 0))}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Visually hidden data table for screen readers */}
+      <table
+        style={srOnlyTableStyle}
+        aria-label={ariaLabel}
+      >
+        <caption style={srOnlyStyle}>{ariaLabel}</caption>
+        <thead>
+          <tr>
+            <th scope="col">{xKey}</th>
+            {series.map((s) => (
+              <th scope="col" key={s.key}>{s.label}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {data.map((d, i) => (
+            <tr key={i}>
+              <td>{formatX(d[xKey])}</td>
+              {series.map((s) => (
+                <td key={s.key}>{formatY(Number(d[s.key] ?? 0))}</td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Draw-in animation keyframe */}
+      <style>{CHART_KEYFRAMES}</style>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Styles (all values reference CSS custom properties)
+// ---------------------------------------------------------------------------
+
+const axisLabelStyle: React.CSSProperties = {
+  fontSize: 'var(--type-caption)',
+  fill: 'var(--color-text-muted)',
+  fontFamily: 'var(--font-sans)',
+};
+
+const titleStyle: React.CSSProperties = {
+  marginBottom: 'var(--space-4)',
+};
+
+const titleTextStyle: React.CSSProperties = {
+  fontSize: 'var(--type-h4)',
+  fontWeight: 'var(--font-weight-semibold)' as React.CSSProperties['fontWeight'],
+  color: 'var(--color-text-primary)',
+  letterSpacing: 'var(--type-h4-ls)',
+  lineHeight: 'var(--type-h4-lh)',
+};
+
+const legendStyle: React.CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 'var(--space-4)',
+  marginBottom: 'var(--space-4)',
+};
+
+const legendItemStyle: React.CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 'var(--space-2)',
+  fontSize: 'var(--type-caption)',
+  color: 'var(--color-text-secondary)',
+  fontWeight: 'var(--font-weight-medium)' as React.CSSProperties['fontWeight'],
+};
+
+const tooltipStyle: React.CSSProperties = {
+  backgroundColor: 'var(--color-bg-overlay)',
+  border: '1px solid var(--color-border-default)',
+  borderRadius: 'var(--radius-default)',
+  boxShadow: 'var(--shadow-2)',
+  padding: 'var(--space-3) var(--space-4)',
+  minWidth: '140px',
+  maxWidth: '220px',
+};
+
+const tooltipHeaderStyle: React.CSSProperties = {
+  fontSize: 'var(--type-caption)',
+  fontWeight: 'var(--font-weight-semibold)' as React.CSSProperties['fontWeight'],
+  color: 'var(--color-text-secondary)',
+  marginBottom: 'var(--space-2)',
+  letterSpacing: '0.02em',
+  textTransform: 'uppercase',
+};
+
+const tooltipRowStyle: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 'var(--space-2)',
+  fontSize: 'var(--type-small)',
+  lineHeight: 'var(--type-small-lh)',
+  marginTop: 'var(--space-1)',
+};
+
+const srOnlyStyle: React.CSSProperties = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: 0,
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0,0,0,0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+const srOnlyTableStyle: React.CSSProperties = {
+  ...srOnlyStyle,
+};
+
+// ---------------------------------------------------------------------------
+// Chart draw-in animation
+// Only transform/opacity are animated. Collapses under reduced-motion.
+// ---------------------------------------------------------------------------
+const CHART_KEYFRAMES = `
+  @keyframes chart-draw-in {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+`;