chati-dev 4.3.1 → 4.4.0

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

@@ -0,0 +1,393 @@
+/**
+ * components/data/StatCard.tsx
+ * ============================================================
+ * WHY THIS COMPONENT EXISTS
+ * -------------------------
+ * The KPI stat card is the single most-viewed element on any
+ * dashboard. It sets the visual tone for the entire product.
+ * A well-crafted StatCard communicates:
+ *   1. The metric name (label)
+ *   2. The current value (large, high-contrast, legible at a glance)
+ *   3. The direction of change (trend badge with semantic color)
+ *   4. The recent trajectory (sparkline)
+ *
+ * Building this as a shared primitive ensures every metric in the
+ * product uses identical visual weight, consistent delta semantics
+ * (green up / red down vs. red up / green down for different
+ * metric types), and the same loading skeleton.
+ *
+ * TYPOGRAPHY DECISIONS
+ * --------------------
+ * Value: --type-h1 (clamp 1.5rem -> 2.25rem), font-weight bold,
+ * letter-spacing --type-h1-ls (-0.025em). At dashboard scale,
+ * the value competes with chart axes and table numbers for
+ * attention, so it needs display weight, not just size.
+ *
+ * Label: --type-caption, font-weight semibold, letter-spacing
+ * 0.04em, uppercase. The micro-label treatment creates clear
+ * visual hierarchy without needing a divider.
+ *
+ * DELTA BADGE DESIGN
+ * ------------------
+ * The delta is rendered as an inline badge (pill shape, --radius-pill)
+ * using the semantic status token pairs:
+ *   success: --color-success / --color-success-subtle
+ *   danger:  --color-danger  / --color-danger-subtle
+ *   neutral: --color-text-muted / --color-bg-sunken
+ *
+ * The `trend` prop is separate from the delta calculation because
+ * some metrics are inverse (a lower bounce rate is good -- trend
+ * is 'up' for improvement even though the number went down). The
+ * parent computes trend from business semantics; StatCard only
+ * renders it.
+ *
+ * SPARKLINE DESIGN
+ * ----------------
+ * The sparkline is a 60x24 SVG path with no axes, no labels, and
+ * no interaction. Its sole purpose is to show the shape of the
+ * recent time series so the viewer can assess trend direction
+ * in a peripheral glance. The area fill uses the accent color at
+ * 15% opacity to tie it to the brand without overpowering the value.
+ *
+ * The SVG path is computed by normalizing the data array to the
+ * 0-24px height range, then constructing a smooth polyline using
+ * simple lineTo commands. A smooth cubic Bezier would look nicer
+ * but adds complexity without meaningful quality gain at 60x24px.
+ *
+ * MOTION
+ * ------
+ * No entry animation on StatCard itself -- the StatCardGrid handles
+ * stagger via CSS animation-delay on nth-child.
+ * The loading skeleton uses SkeletonBlock shimmer.
+ * ============================================================
+ */
+
+'use client';
+
+import React from 'react';
+import { TrendingUp, TrendingDown, Minus } from 'lucide-react';
+import { SkeletonBlock } from './SkeletonBlock';
+
+export interface StatCardProps {
+  /** The metric name displayed above the value. Always visible. */
+  label: string;
+
+  /**
+   * The current metric value as a formatted string.
+   * Pre-format before passing: '$12,400', '94.2%', '1.2k'
+   */
+  value: string;
+
+  /**
+   * The previous period value as a formatted string.
+   * When provided alongside `delta`, both are shown in the badge.
+   */
+  previousValue?: string;
+
+  /**
+   * Pre-formatted delta string: '+12.4%', '-$200', '+0.8pp'.
+   * When omitted, no delta badge is rendered.
+   */
+  delta?: string;
+
+  /** Unit suffix shown after the value at reduced size: 'users', 'MRR', '/mo'. */
+  unit?: string;
+
+  /** Lucide icon displayed in the card header corner. */
+  icon?: React.ReactNode;
+
+  /**
+   * Semantic trend direction. Controls badge color, not computed from delta.
+   * Use 'up' for positive outcomes (revenue up = good).
+   * Use 'down' for inverse metrics (churn down = good -- pass trend='up').
+   * Defaults to 'neutral'.
+   */
+  trend?: 'up' | 'down' | 'neutral';
+
+  /** When true, renders skeleton shimmer in place of all content. */
+  loading?: boolean;
+
+  /**
+   * Array of data points for the sparkline (last N values, any scale).
+   * The component normalizes them to the SVG viewport.
+   * Min 2 points required; otherwise sparkline is omitted.
+   */
+  sparklineData?: number[];
+
+  /** Additional className on the outer card wrapper. */
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sparkline SVG
+// ---------------------------------------------------------------------------
+
+interface SparklineProps {
+  data: number[];
+  width?: number;
+  height?: number;
+  color?: string;
+}
+
+function Sparkline({ data, width = 80, height = 28, color = 'var(--color-accent)' }: SparklineProps) {
+  if (data.length < 2) return null;
+
+  const min = Math.min(...data);
+  const max = Math.max(...data);
+  const range = max - min || 1; // avoid divide-by-zero for flat lines
+
+  // Normalize y values: flip because SVG y=0 is top
+  const normalize = (v: number) => height - ((v - min) / range) * (height - 4) - 2;
+
+  const step = width / (data.length - 1);
+
+  // Build path string: M x0 y0 L x1 y1 L x2 y2 ...
+  const linePath = data
+    .map((v, i) => `${i === 0 ? 'M' : 'L'} ${(i * step).toFixed(1)} ${normalize(v).toFixed(1)}`)
+    .join(' ');
+
+  // Area fill: close the path along the bottom
+  const lastX = ((data.length - 1) * step).toFixed(1);
+  const areaPath = `${linePath} L ${lastX} ${height} L 0 ${height} Z`;
+
+  // Stable across SSR and CSR (a per-render random id would mismatch on
+  // hydration). Colons from useId are stripped so the id is safe inside an
+  // inline SVG on all browsers.
+  const gradientId = `sparkline-gradient-${React.useId().replace(/:/g, '')}`;
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      fill="none"
+      aria-hidden="true"
+      style={{ display: 'block', flexShrink: 0 }}
+    >
+      <defs>
+        <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor={color} stopOpacity={0.22} />
+          <stop offset="100%" stopColor={color} stopOpacity={0} />
+        </linearGradient>
+      </defs>
+      {/* Area fill */}
+      <path d={areaPath} fill={`url(#${gradientId})`} />
+      {/* Line */}
+      <path
+        d={linePath}
+        stroke={color}
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+      />
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Delta badge
+// ---------------------------------------------------------------------------
+
+interface DeltaBadgeProps {
+  delta: string;
+  trend: 'up' | 'down' | 'neutral';
+}
+
+function DeltaBadge({ delta, trend }: DeltaBadgeProps) {
+  const colors = {
+    up: {
+      bg: 'var(--color-success-subtle)',
+      text: 'var(--color-success)',
+    },
+    down: {
+      bg: 'var(--color-danger-subtle)',
+      text: 'var(--color-danger)',
+    },
+    neutral: {
+      bg: 'var(--color-bg-sunken)',
+      text: 'var(--color-text-muted)',
+    },
+  };
+
+  const TrendIcon = trend === 'up' ? TrendingUp : trend === 'down' ? TrendingDown : Minus;
+
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 'var(--space-1)',
+        padding: '2px var(--space-2)',
+        borderRadius: 'var(--radius-pill)',
+        backgroundColor: colors[trend].bg,
+        color: colors[trend].text,
+        fontSize: 'var(--type-caption)',
+        fontWeight: 'var(--font-weight-medium)' as React.CSSProperties['fontWeight'],
+        lineHeight: 'var(--type-caption-lh)',
+        letterSpacing: '0.01em',
+        transition: `opacity var(--duration-fast) var(--ease-out)`,
+        flexShrink: 0,
+      }}
+    >
+      <TrendIcon size={11} aria-hidden="true" />
+      {delta}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// StatCard
+// ---------------------------------------------------------------------------
+
+export function StatCard({
+  label,
+  value,
+  previousValue,
+  delta,
+  unit,
+  icon,
+  trend = 'neutral',
+  loading = false,
+  sparklineData,
+  className,
+}: StatCardProps) {
+  return (
+    <article
+      className={className}
+      style={{
+        backgroundColor: 'var(--color-bg-raised)',
+        border: '1px solid var(--color-border-default)',
+        borderRadius: 'var(--radius-lg)',
+        padding: 'var(--space-6)',
+        boxShadow: 'var(--shadow-1)',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 'var(--space-4)',
+        // Reserve space to prevent layout shift when sparkline loads
+        minHeight: 'var(--space-14)',
+        position: 'relative',
+        overflow: 'hidden',
+      }}
+    >
+      {/* Header row: label + icon */}
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'flex-start',
+          justifyContent: 'space-between',
+          gap: 'var(--space-3)',
+        }}
+      >
+        <span
+          style={{
+            fontSize: 'var(--type-caption)',
+            fontWeight: 'var(--font-weight-semibold)' as React.CSSProperties['fontWeight'],
+            letterSpacing: '0.04em',
+            textTransform: 'uppercase',
+            color: 'var(--color-text-secondary)',
+            lineHeight: 'var(--type-caption-lh)',
+          }}
+        >
+          {loading ? <SkeletonBlock width="60%" height={12} /> : label}
+        </span>
+
+        {icon && !loading && (
+          <span
+            style={{
+              color: 'var(--color-text-muted)',
+              flexShrink: 0,
+              display: 'flex',
+              alignItems: 'center',
+            }}
+            aria-hidden="true"
+          >
+            {icon}
+          </span>
+        )}
+      </div>
+
+      {/* Value row */}
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'flex-end',
+          justifyContent: 'space-between',
+          gap: 'var(--space-3)',
+        }}
+      >
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-2)' }}>
+          {loading ? (
+            <SkeletonBlock width={120} height={32} />
+          ) : (
+            <span
+              style={{
+                fontSize: 'var(--type-h1)',
+                fontWeight: 'var(--font-weight-bold)' as React.CSSProperties['fontWeight'],
+                letterSpacing: 'var(--type-h1-ls)',
+                lineHeight: 'var(--type-h1-lh)',
+                color: 'var(--color-text-primary)',
+                fontFamily: 'var(--font-mono)', // tabular numerals
+                fontVariantNumeric: 'tabular-nums',
+              }}
+            >
+              {value}
+              {unit && (
+                <span
+                  style={{
+                    fontSize: 'var(--type-small)',
+                    fontWeight: 'var(--font-weight-regular)' as React.CSSProperties['fontWeight'],
+                    color: 'var(--color-text-muted)',
+                    marginLeft: 'var(--space-1)',
+                    fontFamily: 'var(--font-sans)',
+                  }}
+                >
+                  {unit}
+                </span>
+              )}
+            </span>
+          )}
+
+          {/* Delta badge */}
+          {!loading && delta && (
+            <div
+              style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)', flexWrap: 'wrap' }}
+            >
+              <DeltaBadge delta={delta} trend={trend} />
+              {previousValue && (
+                <span
+                  style={{
+                    fontSize: 'var(--type-caption)',
+                    color: 'var(--color-text-muted)',
+                  }}
+                >
+                  vs {previousValue}
+                </span>
+              )}
+            </div>
+          )}
+
+          {loading && <SkeletonBlock width={64} height={18} borderRadius="var(--radius-pill)" />}
+        </div>
+
+        {/* Sparkline */}
+        {!loading && sparklineData && sparklineData.length >= 2 && (
+          <Sparkline
+            data={sparklineData}
+            color={
+              trend === 'up'
+                ? 'var(--color-success)'
+                : trend === 'down'
+                ? 'var(--color-danger)'
+                : 'var(--color-accent)'
+            }
+          />
+        )}
+
+        {loading && (
+          <SkeletonBlock width={80} height={28} borderRadius="var(--radius-sharp)" />
+        )}
+      </div>
+    </article>
+  );
+}

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

@@ -0,0 +1,121 @@
+/**
+ * components/data/StatCardGrid.tsx
+ * ============================================================
+ * WHY THIS COMPONENT EXISTS
+ * -------------------------
+ * StatCards are almost always rendered in a row. This grid wrapper
+ * provides three things that would otherwise be repeated at every
+ * call site:
+ *
+ * 1. Responsive auto-fit columns: cards reflow from 4-column to
+ *    2-column to 1-column automatically based on viewport width,
+ *    without media query breakpoints that need to be kept in sync
+ *    across multiple files.
+ *
+ * 2. Consistent gap between cards (--spacing-card-gap, 20px) that
+ *    matches the card-to-section spacing rhythm.
+ *
+ * 3. Entry stagger: each card fades and slides up on mount with a
+ *    CSS animation-delay calculated from --stagger-base (40ms).
+ *    CSS-only stagger scales to any number of children and requires
+ *    zero JavaScript. nth-child selectors set the delay variable;
+ *    the animation reads it.
+ *
+ * STAGGER IMPLEMENTATION
+ * ----------------------
+ * The stagger is implemented via a CSS custom property --stagger-i
+ * on each child, set by :nth-child(n) selectors. The StatCard
+ * animation uses calc(var(--stagger-i, 0) * var(--stagger-base))
+ * as its animation-delay.
+ *
+ * Why nth-child instead of framer-motion staggerChildren:
+ * nth-child requires zero JavaScript and works during SSR, which
+ * is critical for a Next.js App Router preset where the first
+ * paint should not require hydration. framer-motion stagger would
+ * add client-side JS overhead and an invisible-then-visible flash
+ * before hydration.
+ *
+ * Why not inline style stagger from React:
+ * The component accepts `children` as ReactNode, so it cannot
+ * clone elements to inject style props without casting, which
+ * loses type safety and complicates custom child components.
+ *
+ * REDUCED-MOTION
+ * --------------
+ * The global globals.css reduced-motion rule collapses all
+ * animation-duration to 0.01ms, which effectively makes the
+ * stagger instantaneous without removing the visual end state.
+ * ============================================================
+ */
+
+import React from 'react';
+
+export interface StatCardGridProps {
+  children: React.ReactNode;
+  /** Additional className for vertical margin overrides. */
+  className?: string;
+}
+
+export function StatCardGrid({ children, className }: StatCardGridProps) {
+  return (
+    <>
+      {/* Scoped stagger keyframe + nth-child delay rules */}
+      <style>{STAGGER_STYLES}</style>
+      <div
+        className={[GRID_CLASS, className].filter(Boolean).join(' ')}
+        style={gridStyle}
+      >
+        {children}
+      </div>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CSS class name (for global :nth-child selectors to target)
+// ---------------------------------------------------------------------------
+const GRID_CLASS = 'stat-card-grid';
+
+// ---------------------------------------------------------------------------
+// Grid layout
+// ---------------------------------------------------------------------------
+const gridStyle: React.CSSProperties = {
+  display: 'grid',
+  // auto-fit: fills the row, then wraps. minmax(240px, 1fr) means
+  // 4 columns on 1280px, 2 on 640px, 1 on mobile.
+  gridTemplateColumns: 'repeat(auto-fit, minmax(240px, 1fr))',
+  gap: 'var(--spacing-card-gap, 20px)',
+};
+
+// ---------------------------------------------------------------------------
+// Stagger styles injected once via <style> tag
+// ---------------------------------------------------------------------------
+const STAGGER_STYLES = `
+  @keyframes stat-card-enter {
+    from {
+      opacity: 0;
+      transform: translateY(8px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  /* Each card gets a stagger delay based on its position.
+     The animation is 300ms (component duration) with ease-out
+     (decelerate on enter -- the card arrives and settles).
+     8px translateY: subtle enough not to distract, enough to
+     communicate top-down sequential reveal. */
+  .stat-card-grid > * {
+    animation: stat-card-enter 300ms cubic-bezier(0.16, 1, 0.3, 1) both;
+  }
+  .stat-card-grid > *:nth-child(1)  { animation-delay: calc(0 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(2)  { animation-delay: calc(1 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(3)  { animation-delay: calc(2 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(4)  { animation-delay: calc(3 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(5)  { animation-delay: calc(4 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(6)  { animation-delay: calc(5 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(7)  { animation-delay: calc(6 * var(--stagger-base, 40ms)); }
+  .stat-card-grid > *:nth-child(8)  { animation-delay: calc(7 * var(--stagger-base, 40ms)); }
+`;