@wakastellar/ui 2.0.0 → 2.1.0

package/src/components/waka-compare-period/index.tsx

@@ -0,0 +1,1230 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import {
+  TrendingUp,
+  TrendingDown,
+  Minus,
+  Calendar,
+  ArrowRight,
+  ChevronDown,
+  BarChart3,
+  RefreshCw,
+  Check,
+} from "lucide-react"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type PeriodPreset = "last_week" | "last_month" | "last_quarter" | "last_year" | "custom"
+
+export type TrendDirection = "up" | "down" | "neutral"
+
+export interface PeriodRange {
+  /** Start date of the period */
+  start: Date
+  /** End date of the period */
+  end: Date
+  /** Optional label for display */
+  label?: string
+}
+
+export interface MetricValue {
+  /** Current period value */
+  current: number
+  /** Previous period value */
+  previous: number
+}
+
+export interface Metric {
+  /** Unique identifier for the metric */
+  id: string
+  /** Display name */
+  name: string
+  /** Metric values for current and previous periods */
+  value: MetricValue
+  /** Format function for displaying the value */
+  format?: (value: number) => string
+  /** Unit suffix (e.g., "%", "k", "ms") */
+  unit?: string
+  /** Invert trend colors (lower is better) */
+  invertTrend?: boolean
+  /** Custom icon */
+  icon?: React.ReactNode
+  /** Color theme for the metric */
+  color?: "default" | "blue" | "green" | "purple" | "orange" | "red"
+}
+
+export interface ComparePeriodSummary {
+  /** Total metrics improving */
+  improving: number
+  /** Total metrics declining */
+  declining: number
+  /** Total metrics unchanged */
+  unchanged: number
+  /** Average percentage change */
+  averageChange: number
+  /** Best performing metric ID */
+  bestMetricId?: string
+  /** Worst performing metric ID */
+  worstMetricId?: string
+}
+
+export interface WakaComparePeriodProps {
+  /** Array of metrics to compare */
+  metrics: Metric[]
+  /** Current period range */
+  currentPeriod: PeriodRange
+  /** Previous period range */
+  previousPeriod: PeriodRange
+  /** Selected period preset */
+  periodPreset?: PeriodPreset
+  /** Callback when period preset changes */
+  onPeriodChange?: (preset: PeriodPreset, current: PeriodRange, previous: PeriodRange) => void
+  /** Show period selector dropdown */
+  showPeriodSelector?: boolean
+  /** Show visual comparison bars */
+  showComparisonBars?: boolean
+  /** Show summary statistics */
+  showSummary?: boolean
+  /** Enable animated value transitions */
+  animated?: boolean
+  /** Layout variant */
+  variant?: "grid" | "list" | "compact"
+  /** Number of columns for grid layout */
+  columns?: 2 | 3 | 4
+  /** Additional CSS classes */
+  className?: string
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const colorConfig = {
+  default: {
+    bar: "bg-primary",
+    barBg: "bg-primary/20",
+    text: "text-primary",
+    icon: "text-primary",
+  },
+  blue: {
+    bar: "bg-blue-500",
+    barBg: "bg-blue-500/20",
+    text: "text-blue-600",
+    icon: "text-blue-500",
+  },
+  green: {
+    bar: "bg-green-500",
+    barBg: "bg-green-500/20",
+    text: "text-green-600",
+    icon: "text-green-500",
+  },
+  purple: {
+    bar: "bg-purple-500",
+    barBg: "bg-purple-500/20",
+    text: "text-purple-600",
+    icon: "text-purple-500",
+  },
+  orange: {
+    bar: "bg-orange-500",
+    barBg: "bg-orange-500/20",
+    text: "text-orange-600",
+    icon: "text-orange-500",
+  },
+  red: {
+    bar: "bg-red-500",
+    barBg: "bg-red-500/20",
+    text: "text-red-600",
+    icon: "text-red-500",
+  },
+}
+
+const periodPresetConfig: Record<PeriodPreset, { label: string; shortLabel: string }> = {
+  last_week: { label: "vs Last Week", shortLabel: "Week" },
+  last_month: { label: "vs Last Month", shortLabel: "Month" },
+  last_quarter: { label: "vs Last Quarter", shortLabel: "Quarter" },
+  last_year: { label: "vs Last Year", shortLabel: "Year" },
+  custom: { label: "Custom Range", shortLabel: "Custom" },
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function calculateChange(current: number, previous: number): {
+  percentage: number
+  absolute: number
+  direction: TrendDirection
+} {
+  if (previous === 0) {
+    return {
+      percentage: current > 0 ? 100 : 0,
+      absolute: current,
+      direction: current > 0 ? "up" : current < 0 ? "down" : "neutral",
+    }
+  }
+
+  const absolute = current - previous
+  const percentage = ((current - previous) / Math.abs(previous)) * 100
+
+  let direction: TrendDirection = "neutral"
+  if (percentage > 0.01) direction = "up"
+  else if (percentage < -0.01) direction = "down"
+
+  return { percentage, absolute, direction }
+}
+
+function formatPercentage(value: number): string {
+  const sign = value >= 0 ? "+" : ""
+  return `${sign}${value.toFixed(1)}%`
+}
+
+function formatAbsolute(value: number, format?: (v: number) => string, unit?: string): string {
+  const sign = value >= 0 ? "+" : ""
+  const formatted = format ? format(Math.abs(value)) : Math.abs(value).toLocaleString()
+  return `${sign}${value < 0 ? "-" : ""}${formatted}${unit || ""}`
+}
+
+function formatDate(date: Date): string {
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+  })
+}
+
+function calculatePeriodRanges(
+  preset: PeriodPreset,
+  referenceDate: Date = new Date()
+): { current: PeriodRange; previous: PeriodRange } {
+  const now = new Date(referenceDate)
+  now.setHours(23, 59, 59, 999)
+
+  let currentStart: Date
+  let currentEnd: Date = now
+  let previousStart: Date
+  let previousEnd: Date
+
+  switch (preset) {
+    case "last_week": {
+      currentStart = new Date(now)
+      currentStart.setDate(now.getDate() - 6)
+      currentStart.setHours(0, 0, 0, 0)
+
+      previousEnd = new Date(currentStart)
+      previousEnd.setDate(previousEnd.getDate() - 1)
+      previousEnd.setHours(23, 59, 59, 999)
+
+      previousStart = new Date(previousEnd)
+      previousStart.setDate(previousEnd.getDate() - 6)
+      previousStart.setHours(0, 0, 0, 0)
+      break
+    }
+    case "last_month": {
+      currentStart = new Date(now)
+      currentStart.setDate(now.getDate() - 29)
+      currentStart.setHours(0, 0, 0, 0)
+
+      previousEnd = new Date(currentStart)
+      previousEnd.setDate(previousEnd.getDate() - 1)
+      previousEnd.setHours(23, 59, 59, 999)
+
+      previousStart = new Date(previousEnd)
+      previousStart.setDate(previousEnd.getDate() - 29)
+      previousStart.setHours(0, 0, 0, 0)
+      break
+    }
+    case "last_quarter": {
+      currentStart = new Date(now)
+      currentStart.setDate(now.getDate() - 89)
+      currentStart.setHours(0, 0, 0, 0)
+
+      previousEnd = new Date(currentStart)
+      previousEnd.setDate(previousEnd.getDate() - 1)
+      previousEnd.setHours(23, 59, 59, 999)
+
+      previousStart = new Date(previousEnd)
+      previousStart.setDate(previousEnd.getDate() - 89)
+      previousStart.setHours(0, 0, 0, 0)
+      break
+    }
+    case "last_year": {
+      currentStart = new Date(now)
+      currentStart.setFullYear(now.getFullYear() - 1)
+      currentStart.setHours(0, 0, 0, 0)
+
+      previousEnd = new Date(currentStart)
+      previousEnd.setDate(previousEnd.getDate() - 1)
+      previousEnd.setHours(23, 59, 59, 999)
+
+      previousStart = new Date(previousEnd)
+      previousStart.setFullYear(previousEnd.getFullYear() - 1)
+      previousStart.setHours(0, 0, 0, 0)
+      break
+    }
+    default: {
+      // Custom - return current week as default
+      currentStart = new Date(now)
+      currentStart.setDate(now.getDate() - 6)
+      currentStart.setHours(0, 0, 0, 0)
+
+      previousEnd = new Date(currentStart)
+      previousEnd.setDate(previousEnd.getDate() - 1)
+      previousEnd.setHours(23, 59, 59, 999)
+
+      previousStart = new Date(previousEnd)
+      previousStart.setDate(previousEnd.getDate() - 6)
+      previousStart.setHours(0, 0, 0, 0)
+    }
+  }
+
+  return {
+    current: {
+      start: currentStart,
+      end: currentEnd,
+      label: `${formatDate(currentStart)} - ${formatDate(currentEnd)}`,
+    },
+    previous: {
+      start: previousStart,
+      end: previousEnd,
+      label: `${formatDate(previousStart)} - ${formatDate(previousEnd)}`,
+    },
+  }
+}
+
+// ============================================================================
+// Trend Arrow Component
+// ============================================================================
+
+interface TrendArrowProps {
+  direction: TrendDirection
+  invert?: boolean
+  size?: "sm" | "md" | "lg"
+  animated?: boolean
+}
+
+function TrendArrow({ direction, invert = false, size = "md", animated = true }: TrendArrowProps) {
+  const isPositive = invert ? direction === "down" : direction === "up"
+  const isNegative = invert ? direction === "up" : direction === "down"
+
+  const sizeClasses = {
+    sm: "h-3 w-3",
+    md: "h-4 w-4",
+    lg: "h-5 w-5",
+  }
+
+  const Icon =
+    direction === "up"
+      ? TrendingUp
+      : direction === "down"
+        ? TrendingDown
+        : Minus
+
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-center transition-transform duration-300",
+        isPositive && "text-green-600",
+        isNegative && "text-red-600",
+        direction === "neutral" && "text-muted-foreground",
+        animated && direction === "up" && "animate-trend-up",
+        animated && direction === "down" && "animate-trend-down"
+      )}
+    >
+      <Icon className={sizeClasses[size]} />
+      <style>{`
+        @keyframes trend-up {
+          0%, 100% { transform: translateY(0); }
+          50% { transform: translateY(-2px); }
+        }
+        @keyframes trend-down {
+          0%, 100% { transform: translateY(0); }
+          50% { transform: translateY(2px); }
+        }
+        .animate-trend-up {
+          animation: trend-up 2s ease-in-out infinite;
+        }
+        .animate-trend-down {
+          animation: trend-down 2s ease-in-out infinite;
+        }
+      `}</style>
+    </div>
+  )
+}
+
+// ============================================================================
+// Animated Value Component
+// ============================================================================
+
+interface AnimatedValueProps {
+  value: number
+  format?: (value: number) => string
+  unit?: string
+  className?: string
+  animated?: boolean
+}
+
+function AnimatedValue({ value, format, unit, className, animated = true }: AnimatedValueProps) {
+  const [displayValue, setDisplayValue] = React.useState(value)
+  const prevValueRef = React.useRef(value)
+
+  React.useEffect(() => {
+    if (!animated || value === prevValueRef.current) {
+      setDisplayValue(value)
+      prevValueRef.current = value
+      return
+    }
+
+    const startValue = prevValueRef.current
+    const endValue = value
+    const duration = 500
+    const startTime = performance.now()
+
+    const animate = (currentTime: number) => {
+      const elapsed = currentTime - startTime
+      const progress = Math.min(elapsed / duration, 1)
+      const eased = 1 - Math.pow(1 - progress, 3)
+      const currentValue = startValue + (endValue - startValue) * eased
+
+      setDisplayValue(currentValue)
+
+      if (progress < 1) {
+        requestAnimationFrame(animate)
+      }
+    }
+
+    requestAnimationFrame(animate)
+    prevValueRef.current = value
+  }, [value, animated])
+
+  const formatted = format
+    ? format(displayValue)
+    : Number.isInteger(displayValue)
+      ? displayValue.toLocaleString()
+      : displayValue.toLocaleString(undefined, { maximumFractionDigits: 2 })
+
+  return (
+    <span className={cn("tabular-nums", className)}>
+      {formatted}
+      {unit && <span className="text-muted-foreground ml-0.5">{unit}</span>}
+    </span>
+  )
+}
+
+// ============================================================================
+// Comparison Bar Component
+// ============================================================================
+
+interface ComparisonBarProps {
+  current: number
+  previous: number
+  color?: keyof typeof colorConfig
+  animated?: boolean
+}
+
+function ComparisonBar({
+  current,
+  previous,
+  color = "default",
+  animated = true,
+}: ComparisonBarProps) {
+  const [isVisible, setIsVisible] = React.useState(!animated)
+  const maxValue = Math.max(current, previous, 1)
+  const currentPercent = (current / maxValue) * 100
+  const previousPercent = (previous / maxValue) * 100
+
+  React.useEffect(() => {
+    if (animated) {
+      const timer = setTimeout(() => setIsVisible(true), 100)
+      return () => clearTimeout(timer)
+    }
+  }, [animated])
+
+  const colors = colorConfig[color]
+
+  return (
+    <div className="space-y-1.5">
+      {/* Current period bar */}
+      <div className="flex items-center gap-2">
+        <span className="text-[10px] text-muted-foreground w-12">Current</span>
+        <div className="flex-1 h-2 rounded-full bg-muted overflow-hidden">
+          <div
+            className={cn(
+              "h-full rounded-full transition-all duration-700 ease-out",
+              colors.bar
+            )}
+            style={{ width: isVisible ? `${currentPercent}%` : "0%" }}
+          />
+        </div>
+      </div>
+
+      {/* Previous period bar */}
+      <div className="flex items-center gap-2">
+        <span className="text-[10px] text-muted-foreground w-12">Previous</span>
+        <div className="flex-1 h-2 rounded-full bg-muted overflow-hidden">
+          <div
+            className={cn(
+              "h-full rounded-full transition-all duration-700 ease-out opacity-50",
+              colors.bar
+            )}
+            style={{ width: isVisible ? `${previousPercent}%` : "0%" }}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Period Selector Component
+// ============================================================================
+
+interface PeriodSelectorProps {
+  selectedPreset: PeriodPreset
+  onSelect: (preset: PeriodPreset) => void
+  currentPeriod: PeriodRange
+  previousPeriod: PeriodRange
+  className?: string
+}
+
+function PeriodSelector({
+  selectedPreset,
+  onSelect,
+  currentPeriod,
+  previousPeriod,
+  className,
+}: PeriodSelectorProps) {
+  const [isOpen, setIsOpen] = React.useState(false)
+  const containerRef = React.useRef<HTMLDivElement>(null)
+
+  // Close dropdown when clicking outside
+  React.useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false)
+      }
+    }
+
+    document.addEventListener("mousedown", handleClickOutside)
+    return () => document.removeEventListener("mousedown", handleClickOutside)
+  }, [])
+
+  const presets: PeriodPreset[] = ["last_week", "last_month", "last_quarter", "last_year", "custom"]
+
+  return (
+    <div ref={containerRef} className={cn("relative", className)}>
+      {/* Trigger button */}
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className={cn(
+          "flex items-center gap-2 px-3 py-2 rounded-lg border bg-card",
+          "text-sm font-medium transition-colors",
+          "hover:bg-muted focus:outline-none focus:ring-2 focus:ring-primary/20",
+          isOpen && "ring-2 ring-primary/20"
+        )}
+      >
+        <Calendar className="h-4 w-4 text-muted-foreground" />
+        <span>{periodPresetConfig[selectedPreset].label}</span>
+        <ChevronDown
+          className={cn(
+            "h-4 w-4 text-muted-foreground transition-transform duration-200",
+            isOpen && "rotate-180"
+          )}
+        />
+      </button>
+
+      {/* Dropdown menu */}
+      {isOpen && (
+        <div
+          className={cn(
+            "absolute top-full right-0 mt-2 z-50 min-w-[280px]",
+            "rounded-lg border bg-card shadow-lg",
+            "animate-in fade-in-0 zoom-in-95 duration-100"
+          )}
+        >
+          {/* Period range display */}
+          <div className="p-3 border-b">
+            <div className="flex items-center gap-2 text-sm">
+              <div className="flex-1 text-center">
+                <div className="text-[10px] uppercase text-muted-foreground mb-1">Current</div>
+                <div className="font-medium">{currentPeriod.label}</div>
+              </div>
+              <ArrowRight className="h-4 w-4 text-muted-foreground" />
+              <div className="flex-1 text-center">
+                <div className="text-[10px] uppercase text-muted-foreground mb-1">Previous</div>
+                <div className="font-medium">{previousPeriod.label}</div>
+              </div>
+            </div>
+          </div>
+
+          {/* Preset options */}
+          <div className="p-1">
+            {presets.map((preset) => (
+              <button
+                key={preset}
+                type="button"
+                onClick={() => {
+                  onSelect(preset)
+                  setIsOpen(false)
+                }}
+                className={cn(
+                  "flex items-center justify-between w-full px-3 py-2 rounded-md text-sm",
+                  "transition-colors hover:bg-muted",
+                  selectedPreset === preset && "bg-primary/10 text-primary"
+                )}
+              >
+                <span>{periodPresetConfig[preset].label}</span>
+                {selectedPreset === preset && <Check className="h-4 w-4" />}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Metric Card Component
+// ============================================================================
+
+interface MetricCardProps {
+  metric: Metric
+  showComparisonBars: boolean
+  animated: boolean
+  variant: "grid" | "list" | "compact"
+}
+
+function MetricCard({ metric, showComparisonBars, animated, variant }: MetricCardProps) {
+  const { percentage, absolute, direction } = calculateChange(
+    metric.value.current,
+    metric.value.previous
+  )
+  const colors = colorConfig[metric.color || "default"]
+
+  if (variant === "compact") {
+    return (
+      <div className="flex items-center justify-between py-2 border-b last:border-b-0">
+        <div className="flex items-center gap-2">
+          {metric.icon && <div className={cn("h-4 w-4", colors.icon)}>{metric.icon}</div>}
+          <span className="text-sm font-medium">{metric.name}</span>
+        </div>
+        <div className="flex items-center gap-3">
+          <AnimatedValue
+            value={metric.value.current}
+            format={metric.format}
+            unit={metric.unit}
+            animated={animated}
+            className="font-semibold"
+          />
+          <div className="flex items-center gap-1">
+            <TrendArrow
+              direction={direction}
+              invert={metric.invertTrend}
+              size="sm"
+              animated={animated}
+            />
+            <span
+              className={cn(
+                "text-xs font-medium",
+                (metric.invertTrend ? direction === "down" : direction === "up") && "text-green-600",
+                (metric.invertTrend ? direction === "up" : direction === "down") && "text-red-600",
+                direction === "neutral" && "text-muted-foreground"
+              )}
+            >
+              {formatPercentage(percentage)}
+            </span>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  if (variant === "list") {
+    return (
+      <div className="flex items-center gap-4 p-4 rounded-lg border bg-card">
+        {/* Icon */}
+        {metric.icon && (
+          <div className={cn("rounded-lg p-2", colors.barBg)}>
+            <div className={cn("h-5 w-5", colors.icon)}>{metric.icon}</div>
+          </div>
+        )}
+
+        {/* Name and values */}
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center justify-between mb-1">
+            <span className="font-medium truncate">{metric.name}</span>
+            <div className="flex items-center gap-2">
+              <TrendArrow
+                direction={direction}
+                invert={metric.invertTrend}
+                animated={animated}
+              />
+              <span
+                className={cn(
+                  "text-sm font-semibold",
+                  (metric.invertTrend ? direction === "down" : direction === "up") && "text-green-600",
+                  (metric.invertTrend ? direction === "up" : direction === "down") && "text-red-600",
+                  direction === "neutral" && "text-muted-foreground"
+                )}
+              >
+                {formatPercentage(percentage)}
+              </span>
+            </div>
+          </div>
+
+          <div className="flex items-baseline gap-3">
+            <AnimatedValue
+              value={metric.value.current}
+              format={metric.format}
+              unit={metric.unit}
+              animated={animated}
+              className="text-2xl font-bold"
+            />
+            <span className="text-sm text-muted-foreground">
+              from{" "}
+              <AnimatedValue
+                value={metric.value.previous}
+                format={metric.format}
+                unit={metric.unit}
+                animated={animated}
+                className="font-medium"
+              />
+            </span>
+          </div>
+
+          {showComparisonBars && (
+            <div className="mt-3">
+              <ComparisonBar
+                current={metric.value.current}
+                previous={metric.value.previous}
+                color={metric.color}
+                animated={animated}
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  // Grid variant (default)
+  return (
+    <div className="p-4 rounded-lg border bg-card">
+      {/* Header */}
+      <div className="flex items-start justify-between mb-3">
+        <div className="flex items-center gap-2">
+          {metric.icon && (
+            <div className={cn("rounded-lg p-1.5", colors.barBg)}>
+              <div className={cn("h-4 w-4", colors.icon)}>{metric.icon}</div>
+            </div>
+          )}
+          <span className="text-sm font-medium text-muted-foreground">{metric.name}</span>
+        </div>
+        <TrendArrow direction={direction} invert={metric.invertTrend} animated={animated} />
+      </div>
+
+      {/* Current value */}
+      <div className="mb-2">
+        <AnimatedValue
+          value={metric.value.current}
+          format={metric.format}
+          unit={metric.unit}
+          animated={animated}
+          className="text-2xl font-bold"
+        />
+      </div>
+
+      {/* Change indicators */}
+      <div className="flex items-center gap-2 text-sm">
+        <span
+          className={cn(
+            "font-semibold",
+            (metric.invertTrend ? direction === "down" : direction === "up") && "text-green-600",
+            (metric.invertTrend ? direction === "up" : direction === "down") && "text-red-600",
+            direction === "neutral" && "text-muted-foreground"
+          )}
+        >
+          {formatPercentage(percentage)}
+        </span>
+        <span className="text-muted-foreground">
+          ({formatAbsolute(absolute, metric.format, metric.unit)})
+        </span>
+      </div>
+
+      {/* Previous value */}
+      <div className="mt-1 text-xs text-muted-foreground">
+        Previous:{" "}
+        <AnimatedValue
+          value={metric.value.previous}
+          format={metric.format}
+          unit={metric.unit}
+          animated={animated}
+          className="font-medium"
+        />
+      </div>
+
+      {/* Comparison bars */}
+      {showComparisonBars && (
+        <div className="mt-4">
+          <ComparisonBar
+            current={metric.value.current}
+            previous={metric.value.previous}
+            color={metric.color}
+            animated={animated}
+          />
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Summary Card Component
+// ============================================================================
+
+interface SummaryCardProps {
+  summary: ComparePeriodSummary
+  metrics: Metric[]
+  animated: boolean
+}
+
+function SummaryCard({ summary, metrics, animated }: SummaryCardProps) {
+  const bestMetric = metrics.find((m) => m.id === summary.bestMetricId)
+  const worstMetric = metrics.find((m) => m.id === summary.worstMetricId)
+
+  return (
+    <div className="p-4 rounded-lg border bg-card">
+      <div className="flex items-center gap-2 mb-4">
+        <BarChart3 className="h-5 w-5 text-muted-foreground" />
+        <span className="font-semibold">Summary</span>
+      </div>
+
+      {/* Stats row */}
+      <div className="grid grid-cols-3 gap-4 mb-4">
+        <div className="text-center">
+          <div className="flex items-center justify-center gap-1 text-green-600 mb-1">
+            <TrendingUp className="h-4 w-4" />
+            <span className="text-xl font-bold">{summary.improving}</span>
+          </div>
+          <div className="text-xs text-muted-foreground">Improving</div>
+        </div>
+        <div className="text-center">
+          <div className="flex items-center justify-center gap-1 text-red-600 mb-1">
+            <TrendingDown className="h-4 w-4" />
+            <span className="text-xl font-bold">{summary.declining}</span>
+          </div>
+          <div className="text-xs text-muted-foreground">Declining</div>
+        </div>
+        <div className="text-center">
+          <div className="flex items-center justify-center gap-1 text-muted-foreground mb-1">
+            <Minus className="h-4 w-4" />
+            <span className="text-xl font-bold">{summary.unchanged}</span>
+          </div>
+          <div className="text-xs text-muted-foreground">Unchanged</div>
+        </div>
+      </div>
+
+      {/* Average change */}
+      <div className="p-3 rounded-lg bg-muted/50 mb-3">
+        <div className="flex items-center justify-between">
+          <span className="text-sm text-muted-foreground">Average Change</span>
+          <span
+            className={cn(
+              "font-bold",
+              summary.averageChange > 0 && "text-green-600",
+              summary.averageChange < 0 && "text-red-600"
+            )}
+          >
+            {formatPercentage(summary.averageChange)}
+          </span>
+        </div>
+      </div>
+
+      {/* Best and worst performers */}
+      <div className="space-y-2">
+        {bestMetric && (
+          <div className="flex items-center justify-between text-sm">
+            <span className="text-muted-foreground">Best performer</span>
+            <span className="font-medium text-green-600">{bestMetric.name}</span>
+          </div>
+        )}
+        {worstMetric && (
+          <div className="flex items-center justify-between text-sm">
+            <span className="text-muted-foreground">Needs attention</span>
+            <span className="font-medium text-red-600">{worstMetric.name}</span>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+export function WakaComparePeriod({
+  metrics,
+  currentPeriod,
+  previousPeriod,
+  periodPreset = "last_week",
+  onPeriodChange,
+  showPeriodSelector = true,
+  showComparisonBars = true,
+  showSummary = true,
+  animated = true,
+  variant = "grid",
+  columns = 3,
+  className,
+}: WakaComparePeriodProps) {
+  const [internalPreset, setInternalPreset] = React.useState(periodPreset)
+  const [internalCurrentPeriod, setInternalCurrentPeriod] = React.useState(currentPeriod)
+  const [internalPreviousPeriod, setInternalPreviousPeriod] = React.useState(previousPeriod)
+
+  // Calculate summary
+  const summary = React.useMemo((): ComparePeriodSummary => {
+    let improving = 0
+    let declining = 0
+    let unchanged = 0
+    let totalPercentage = 0
+    let bestChange = -Infinity
+    let worstChange = Infinity
+    let bestMetricId: string | undefined
+    let worstMetricId: string | undefined
+
+    metrics.forEach((metric) => {
+      const { percentage, direction } = calculateChange(
+        metric.value.current,
+        metric.value.previous
+      )
+
+      // Consider invertTrend for categorization
+      const effectiveDirection = metric.invertTrend
+        ? direction === "up"
+          ? "down"
+          : direction === "down"
+            ? "up"
+            : "neutral"
+        : direction
+
+      if (effectiveDirection === "up") improving++
+      else if (effectiveDirection === "down") declining++
+      else unchanged++
+
+      totalPercentage += percentage
+
+      // Track best and worst (considering invertTrend)
+      const effectivePercentage = metric.invertTrend ? -percentage : percentage
+      if (effectivePercentage > bestChange) {
+        bestChange = effectivePercentage
+        bestMetricId = metric.id
+      }
+      if (effectivePercentage < worstChange) {
+        worstChange = effectivePercentage
+        worstMetricId = metric.id
+      }
+    })
+
+    return {
+      improving,
+      declining,
+      unchanged,
+      averageChange: metrics.length > 0 ? totalPercentage / metrics.length : 0,
+      bestMetricId,
+      worstMetricId,
+    }
+  }, [metrics])
+
+  const handlePeriodChange = (preset: PeriodPreset) => {
+    setInternalPreset(preset)
+
+    if (preset !== "custom") {
+      const ranges = calculatePeriodRanges(preset)
+      setInternalCurrentPeriod(ranges.current)
+      setInternalPreviousPeriod(ranges.previous)
+      onPeriodChange?.(preset, ranges.current, ranges.previous)
+    } else {
+      onPeriodChange?.(preset, internalCurrentPeriod, internalPreviousPeriod)
+    }
+  }
+
+  const columnClasses = {
+    2: "grid-cols-2",
+    3: "grid-cols-3",
+    4: "grid-cols-4",
+  }
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Calendar className="h-4 w-4" />
+            <span>{internalCurrentPeriod.label}</span>
+            <ArrowRight className="h-3 w-3" />
+            <span>{internalPreviousPeriod.label}</span>
+          </div>
+        </div>
+
+        {showPeriodSelector && (
+          <PeriodSelector
+            selectedPreset={internalPreset}
+            onSelect={handlePeriodChange}
+            currentPeriod={internalCurrentPeriod}
+            previousPeriod={internalPreviousPeriod}
+          />
+        )}
+      </div>
+
+      {/* Metrics display */}
+      {variant === "compact" ? (
+        <div className="rounded-lg border bg-card p-4">
+          {metrics.map((metric) => (
+            <MetricCard
+              key={metric.id}
+              metric={metric}
+              showComparisonBars={false}
+              animated={animated}
+              variant="compact"
+            />
+          ))}
+        </div>
+      ) : variant === "list" ? (
+        <div className="space-y-3">
+          {metrics.map((metric) => (
+            <MetricCard
+              key={metric.id}
+              metric={metric}
+              showComparisonBars={showComparisonBars}
+              animated={animated}
+              variant="list"
+            />
+          ))}
+        </div>
+      ) : (
+        <div className={cn("grid gap-4", columnClasses[columns])}>
+          {metrics.map((metric) => (
+            <MetricCard
+              key={metric.id}
+              metric={metric}
+              showComparisonBars={showComparisonBars}
+              animated={animated}
+              variant="grid"
+            />
+          ))}
+        </div>
+      )}
+
+      {/* Summary */}
+      {showSummary && metrics.length > 0 && (
+        <SummaryCard summary={summary} metrics={metrics} animated={animated} />
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Hook: useComparePeriod
+// ============================================================================
+
+export interface UseComparePeriodOptions {
+  /** Initial period preset */
+  initialPreset?: PeriodPreset
+  /** Initial metrics data */
+  initialMetrics?: Metric[]
+  /** Reference date for calculations */
+  referenceDate?: Date
+  /** Auto-refresh interval in milliseconds */
+  autoRefreshInterval?: number
+  /** Callback to fetch new metric data */
+  onRefresh?: () => Promise<Metric[]>
+}
+
+export interface UseComparePeriodReturn {
+  /** Current period preset */
+  preset: PeriodPreset
+  /** Current period range */
+  currentPeriod: PeriodRange
+  /** Previous period range */
+  previousPeriod: PeriodRange
+  /** Metrics array */
+  metrics: Metric[]
+  /** Calculated summary */
+  summary: ComparePeriodSummary
+  /** Loading state */
+  isLoading: boolean
+  /** Error state */
+  error: Error | null
+  /** Set period preset */
+  setPreset: (preset: PeriodPreset) => void
+  /** Set custom period ranges */
+  setCustomPeriods: (current: PeriodRange, previous: PeriodRange) => void
+  /** Update metrics data */
+  setMetrics: React.Dispatch<React.SetStateAction<Metric[]>>
+  /** Update a single metric */
+  updateMetric: (id: string, value: MetricValue) => void
+  /** Trigger manual refresh */
+  refresh: () => Promise<void>
+  /** Get change for a specific metric */
+  getMetricChange: (id: string) => { percentage: number; absolute: number; direction: TrendDirection } | null
+}
+
+export function useComparePeriod(
+  options: UseComparePeriodOptions = {}
+): UseComparePeriodReturn {
+  const {
+    initialPreset = "last_week",
+    initialMetrics = [],
+    referenceDate = new Date(),
+    autoRefreshInterval,
+    onRefresh,
+  } = options
+
+  const [preset, setPreset] = React.useState(initialPreset)
+  const [metrics, setMetrics] = React.useState<Metric[]>(initialMetrics)
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [error, setError] = React.useState<Error | null>(null)
+
+  const [periods, setPeriods] = React.useState(() => calculatePeriodRanges(initialPreset, referenceDate))
+
+  // Update periods when preset changes
+  React.useEffect(() => {
+    if (preset !== "custom") {
+      setPeriods(calculatePeriodRanges(preset, referenceDate))
+    }
+  }, [preset, referenceDate])
+
+  // Auto-refresh
+  React.useEffect(() => {
+    if (!autoRefreshInterval || !onRefresh) return
+
+    const interval = setInterval(async () => {
+      try {
+        const newMetrics = await onRefresh()
+        setMetrics(newMetrics)
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error("Refresh failed"))
+      }
+    }, autoRefreshInterval)
+
+    return () => clearInterval(interval)
+  }, [autoRefreshInterval, onRefresh])
+
+  // Calculate summary
+  const summary = React.useMemo((): ComparePeriodSummary => {
+    let improving = 0
+    let declining = 0
+    let unchanged = 0
+    let totalPercentage = 0
+    let bestChange = -Infinity
+    let worstChange = Infinity
+    let bestMetricId: string | undefined
+    let worstMetricId: string | undefined
+
+    metrics.forEach((metric) => {
+      const { percentage, direction } = calculateChange(
+        metric.value.current,
+        metric.value.previous
+      )
+
+      const effectiveDirection = metric.invertTrend
+        ? direction === "up"
+          ? "down"
+          : direction === "down"
+            ? "up"
+            : "neutral"
+        : direction
+
+      if (effectiveDirection === "up") improving++
+      else if (effectiveDirection === "down") declining++
+      else unchanged++
+
+      totalPercentage += percentage
+
+      const effectivePercentage = metric.invertTrend ? -percentage : percentage
+      if (effectivePercentage > bestChange) {
+        bestChange = effectivePercentage
+        bestMetricId = metric.id
+      }
+      if (effectivePercentage < worstChange) {
+        worstChange = effectivePercentage
+        worstMetricId = metric.id
+      }
+    })
+
+    return {
+      improving,
+      declining,
+      unchanged,
+      averageChange: metrics.length > 0 ? totalPercentage / metrics.length : 0,
+      bestMetricId,
+      worstMetricId,
+    }
+  }, [metrics])
+
+  const setCustomPeriods = React.useCallback(
+    (current: PeriodRange, previous: PeriodRange) => {
+      setPreset("custom")
+      setPeriods({ current, previous })
+    },
+    []
+  )
+
+  const updateMetric = React.useCallback((id: string, value: MetricValue) => {
+    setMetrics((prev) =>
+      prev.map((m) => (m.id === id ? { ...m, value } : m))
+    )
+  }, [])
+
+  const refresh = React.useCallback(async () => {
+    if (!onRefresh) return
+
+    setIsLoading(true)
+    setError(null)
+
+    try {
+      const newMetrics = await onRefresh()
+      setMetrics(newMetrics)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Refresh failed"))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [onRefresh])
+
+  const getMetricChange = React.useCallback(
+    (id: string) => {
+      const metric = metrics.find((m) => m.id === id)
+      if (!metric) return null
+      return calculateChange(metric.value.current, metric.value.previous)
+    },
+    [metrics]
+  )
+
+  return {
+    preset,
+    currentPeriod: periods.current,
+    previousPeriod: periods.previous,
+    metrics,
+    summary,
+    isLoading,
+    error,
+    setPreset,
+    setCustomPeriods,
+    setMetrics,
+    updateMetric,
+    refresh,
+    getMetricChange,
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default WakaComparePeriod