@wakastellar/ui 2.0.0 → 2.1.0

package/src/components/waka-cohort-table/index.tsx

@@ -0,0 +1,1011 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../utils/cn"
+import { Download, Info, TrendingDown, TrendingUp, Users } from "lucide-react"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type CohortPeriod = "day" | "week" | "month" | "quarter" | "year"
+
+export type CohortMetric = "retention" | "churn" | "revenue" | "engagement" | "custom"
+
+export interface CohortDataPoint {
+  /** Value for this period (0-100 for percentages, or raw value) */
+  value: number
+  /** Number of users/items at this point */
+  count?: number
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+}
+
+export interface CohortRow {
+  /** Unique identifier for the cohort */
+  id: string
+  /** Cohort label (e.g., "Jan 2024", "Week 1") */
+  label: string
+  /** Cohort start date */
+  date: Date
+  /** Initial cohort size */
+  size: number
+  /** Data points for each period */
+  data: CohortDataPoint[]
+}
+
+export interface CohortColorScale {
+  /** Minimum value color (e.g., for 0% retention) */
+  min: string
+  /** Maximum value color (e.g., for 100% retention) */
+  max: string
+  /** Optional midpoint color for gradient */
+  mid?: string
+  /** Midpoint value (defaults to 50) */
+  midValue?: number
+}
+
+export interface CohortExportOptions {
+  /** Export format */
+  format: "csv" | "json"
+  /** Include metadata in export */
+  includeMetadata?: boolean
+  /** Custom filename */
+  filename?: string
+}
+
+export interface WakaCohortTableProps {
+  /** Cohort data rows */
+  data: CohortRow[]
+  /** Period type for columns */
+  period?: CohortPeriod
+  /** Metric being displayed */
+  metric?: CohortMetric
+  /** Custom metric label */
+  metricLabel?: string
+  /** Whether to show as percentage */
+  showAsPercentage?: boolean
+  /** Number of decimal places */
+  decimalPlaces?: number
+  /** Color scale configuration */
+  colorScale?: CohortColorScale
+  /** Show cohort size column */
+  showCohortSize?: boolean
+  /** Show average row */
+  showAverageRow?: boolean
+  /** Show trend indicators */
+  showTrends?: boolean
+  /** Enable cell hover highlighting */
+  highlightOnHover?: boolean
+  /** Show color scale legend */
+  showLegend?: boolean
+  /** Enable export functionality */
+  enableExport?: boolean
+  /** Callback when cell is clicked */
+  onCellClick?: (row: CohortRow, periodIndex: number, value: CohortDataPoint) => void
+  /** Callback when export is triggered */
+  onExport?: (options: CohortExportOptions) => void
+  /** Custom cell renderer */
+  renderCell?: (value: CohortDataPoint, row: CohortRow, periodIndex: number) => React.ReactNode
+  /** Custom tooltip renderer */
+  renderTooltip?: (value: CohortDataPoint, row: CohortRow, periodIndex: number) => React.ReactNode
+  /** Custom className */
+  className?: string
+  /** Table className */
+  tableClassName?: string
+  /** Header cell className */
+  headerClassName?: string
+  /** Body cell className */
+  cellClassName?: string
+}
+
+// ============================================================================
+// Default Color Scale
+// ============================================================================
+
+const defaultColorScale: CohortColorScale = {
+  min: "#fef2f2", // red-50
+  mid: "#fef9c3", // yellow-100
+  max: "#dcfce7", // green-100
+  midValue: 50,
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function interpolateColor(
+  value: number,
+  min: number,
+  max: number,
+  colorScale: CohortColorScale
+): string {
+  const normalizedValue = Math.max(min, Math.min(max, value))
+  const percentage = (normalizedValue - min) / (max - min)
+
+  // Parse hex colors to RGB
+  const parseHex = (hex: string) => {
+    const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
+    return result
+      ? {
+          r: parseInt(result[1], 16),
+          g: parseInt(result[2], 16),
+          b: parseInt(result[3], 16),
+        }
+      : { r: 255, g: 255, b: 255 }
+  }
+
+  const minColor = parseHex(colorScale.min)
+  const maxColor = parseHex(colorScale.max)
+  const midColor = colorScale.mid ? parseHex(colorScale.mid) : null
+  const midValue = (colorScale.midValue ?? 50) / 100
+
+  let r: number, g: number, b: number
+
+  if (midColor && percentage <= midValue) {
+    // Interpolate between min and mid
+    const t = percentage / midValue
+    r = Math.round(minColor.r + (midColor.r - minColor.r) * t)
+    g = Math.round(minColor.g + (midColor.g - minColor.g) * t)
+    b = Math.round(minColor.b + (midColor.b - minColor.b) * t)
+  } else if (midColor && percentage > midValue) {
+    // Interpolate between mid and max
+    const t = (percentage - midValue) / (1 - midValue)
+    r = Math.round(midColor.r + (maxColor.r - midColor.r) * t)
+    g = Math.round(midColor.g + (maxColor.g - midColor.g) * t)
+    b = Math.round(midColor.b + (maxColor.b - midColor.b) * t)
+  } else {
+    // No mid color, interpolate directly
+    r = Math.round(minColor.r + (maxColor.r - minColor.r) * percentage)
+    g = Math.round(minColor.g + (maxColor.g - minColor.g) * percentage)
+    b = Math.round(minColor.b + (maxColor.b - minColor.b) * percentage)
+  }
+
+  return `rgb(${r}, ${g}, ${b})`
+}
+
+function formatValue(
+  value: number,
+  showAsPercentage: boolean,
+  decimalPlaces: number
+): string {
+  if (showAsPercentage) {
+    return `${value.toFixed(decimalPlaces)}%`
+  }
+  return value.toFixed(decimalPlaces)
+}
+
+function formatNumber(num: number): string {
+  if (num >= 1000000) {
+    return `${(num / 1000000).toFixed(1)}M`
+  }
+  if (num >= 1000) {
+    return `${(num / 1000).toFixed(1)}K`
+  }
+  return num.toString()
+}
+
+function getPeriodLabel(period: CohortPeriod, index: number): string {
+  const labels: Record<CohortPeriod, string> = {
+    day: "Day",
+    week: "Week",
+    month: "Month",
+    quarter: "Q",
+    year: "Year",
+  }
+  return `${labels[period]} ${index}`
+}
+
+function calculateAverages(data: CohortRow[]): CohortDataPoint[] {
+  if (data.length === 0) return []
+
+  const maxPeriods = Math.max(...data.map((row) => row.data.length))
+  const averages: CohortDataPoint[] = []
+
+  for (let i = 0; i < maxPeriods; i++) {
+    const values = data
+      .map((row) => row.data[i]?.value)
+      .filter((v): v is number => v !== undefined)
+
+    if (values.length > 0) {
+      const sum = values.reduce((a, b) => a + b, 0)
+      averages.push({
+        value: sum / values.length,
+        count: values.length,
+      })
+    }
+  }
+
+  return averages
+}
+
+function calculateTrend(current: number, previous: number): "up" | "down" | "neutral" {
+  const diff = current - previous
+  if (Math.abs(diff) < 0.5) return "neutral"
+  return diff > 0 ? "up" : "down"
+}
+
+function exportToCSV(data: CohortRow[], period: CohortPeriod, metricLabel: string): string {
+  const maxPeriods = Math.max(...data.map((row) => row.data.length))
+  const headers = [
+    "Cohort",
+    "Size",
+    ...Array.from({ length: maxPeriods }, (_, i) => getPeriodLabel(period, i)),
+  ]
+
+  const rows = data.map((row) => [
+    row.label,
+    row.size.toString(),
+    ...row.data.map((d) => d.value.toString()),
+  ])
+
+  return [headers.join(","), ...rows.map((r) => r.join(","))].join("\n")
+}
+
+function exportToJSON(data: CohortRow[], includeMetadata: boolean): string {
+  const exportData = data.map((row) => ({
+    id: row.id,
+    label: row.label,
+    date: row.date.toISOString(),
+    size: row.size,
+    data: row.data.map((d) => ({
+      value: d.value,
+      count: d.count,
+      ...(includeMetadata && d.metadata ? { metadata: d.metadata } : {}),
+    })),
+  }))
+
+  return JSON.stringify(exportData, null, 2)
+}
+
+// ============================================================================
+// Tooltip Component
+// ============================================================================
+
+interface TooltipProps {
+  children: React.ReactNode
+  content: React.ReactNode
+  visible: boolean
+  position: { x: number; y: number }
+}
+
+function Tooltip({ children, content, visible, position }: TooltipProps) {
+  return (
+    <div className="relative inline-block">
+      {children}
+      {visible && (
+        <div
+          className="fixed z-50 px-3 py-2 text-sm bg-popover text-popover-foreground rounded-md shadow-lg border max-w-xs"
+          style={{
+            left: position.x,
+            top: position.y - 10,
+            transform: "translate(-50%, -100%)",
+          }}
+        >
+          {content}
+          <div className="absolute left-1/2 -translate-x-1/2 top-full w-0 h-0 border-l-4 border-r-4 border-t-4 border-l-transparent border-r-transparent border-t-popover" />
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ============================================================================
+// Color Legend Component
+// ============================================================================
+
+interface ColorLegendProps {
+  colorScale: CohortColorScale
+  min: number
+  max: number
+  showAsPercentage: boolean
+}
+
+function ColorLegend({ colorScale, min, max, showAsPercentage }: ColorLegendProps) {
+  const steps = 5
+  const stepSize = (max - min) / (steps - 1)
+
+  return (
+    <div className="flex items-center gap-2 text-xs text-muted-foreground">
+      <span>{showAsPercentage ? `${min}%` : min}</span>
+      <div className="flex h-3 rounded overflow-hidden">
+        {Array.from({ length: 20 }, (_, i) => {
+          const value = min + (max - min) * (i / 19)
+          return (
+            <div
+              key={i}
+              className="w-3 h-full"
+              style={{ backgroundColor: interpolateColor(value, min, max, colorScale) }}
+            />
+          )
+        })}
+      </div>
+      <span>{showAsPercentage ? `${max}%` : max}</span>
+    </div>
+  )
+}
+
+// ============================================================================
+// Cohort Cell Component
+// ============================================================================
+
+interface CohortCellProps {
+  dataPoint: CohortDataPoint
+  row: CohortRow
+  periodIndex: number
+  colorScale: CohortColorScale
+  showAsPercentage: boolean
+  decimalPlaces: number
+  highlighted: boolean
+  onClick?: () => void
+  renderCell?: (value: CohortDataPoint, row: CohortRow, periodIndex: number) => React.ReactNode
+  renderTooltip?: (value: CohortDataPoint, row: CohortRow, periodIndex: number) => React.ReactNode
+  className?: string
+}
+
+function CohortCell({
+  dataPoint,
+  row,
+  periodIndex,
+  colorScale,
+  showAsPercentage,
+  decimalPlaces,
+  highlighted,
+  onClick,
+  renderCell,
+  renderTooltip,
+  className,
+}: CohortCellProps) {
+  const [tooltipVisible, setTooltipVisible] = React.useState(false)
+  const [tooltipPosition, setTooltipPosition] = React.useState({ x: 0, y: 0 })
+  const cellRef = React.useRef<HTMLTableCellElement>(null)
+
+  const backgroundColor = interpolateColor(dataPoint.value, 0, 100, colorScale)
+
+  const handleMouseEnter = (e: React.MouseEvent) => {
+    setTooltipVisible(true)
+    const rect = (e.target as HTMLElement).getBoundingClientRect()
+    setTooltipPosition({
+      x: rect.left + rect.width / 2,
+      y: rect.top,
+    })
+  }
+
+  const handleMouseLeave = () => {
+    setTooltipVisible(false)
+  }
+
+  const defaultTooltipContent = (
+    <div className="space-y-1">
+      <div className="font-medium">{row.label}</div>
+      <div>Period {periodIndex}: {formatValue(dataPoint.value, showAsPercentage, decimalPlaces)}</div>
+      {dataPoint.count !== undefined && (
+        <div className="text-muted-foreground">Count: {formatNumber(dataPoint.count)}</div>
+      )}
+      {dataPoint.metadata && Object.keys(dataPoint.metadata).length > 0 && (
+        <div className="pt-1 border-t">
+          {Object.entries(dataPoint.metadata).map(([key, value]) => (
+            <div key={key} className="text-muted-foreground">
+              {key}: {String(value)}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+
+  return (
+    <td
+      ref={cellRef}
+      className={cn(
+        "px-3 py-2 text-center text-sm font-medium transition-all cursor-pointer",
+        "border-r border-border last:border-r-0",
+        highlighted && "ring-2 ring-primary ring-inset",
+        className
+      )}
+      style={{ backgroundColor }}
+      onClick={onClick}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+    >
+      <Tooltip
+        content={renderTooltip ? renderTooltip(dataPoint, row, periodIndex) : defaultTooltipContent}
+        visible={tooltipVisible}
+        position={tooltipPosition}
+      >
+        {renderCell ? (
+          renderCell(dataPoint, row, periodIndex)
+        ) : (
+          formatValue(dataPoint.value, showAsPercentage, decimalPlaces)
+        )}
+      </Tooltip>
+    </td>
+  )
+}
+
+// ============================================================================
+// Main Component
+// ============================================================================
+
+export function WakaCohortTable({
+  data,
+  period = "month",
+  metric = "retention",
+  metricLabel,
+  showAsPercentage = true,
+  decimalPlaces = 1,
+  colorScale = defaultColorScale,
+  showCohortSize = true,
+  showAverageRow = true,
+  showTrends = true,
+  highlightOnHover = true,
+  showLegend = true,
+  enableExport = true,
+  onCellClick,
+  onExport,
+  renderCell,
+  renderTooltip,
+  className,
+  tableClassName,
+  headerClassName,
+  cellClassName,
+}: WakaCohortTableProps) {
+  const [hoveredRow, setHoveredRow] = React.useState<string | null>(null)
+  const [hoveredColumn, setHoveredColumn] = React.useState<number | null>(null)
+
+  // Calculate max periods across all rows
+  const maxPeriods = React.useMemo(
+    () => Math.max(...data.map((row) => row.data.length), 0),
+    [data]
+  )
+
+  // Calculate averages
+  const averages = React.useMemo(() => calculateAverages(data), [data])
+
+  // Handle export
+  const handleExport = React.useCallback(
+    (format: "csv" | "json") => {
+      const label = metricLabel || metric
+      const filename = `cohort-${label}-${new Date().toISOString().split("T")[0]}`
+
+      if (onExport) {
+        onExport({ format, filename, includeMetadata: true })
+        return
+      }
+
+      let content: string
+      let mimeType: string
+      let extension: string
+
+      if (format === "csv") {
+        content = exportToCSV(data, period, label)
+        mimeType = "text/csv"
+        extension = "csv"
+      } else {
+        content = exportToJSON(data, true)
+        mimeType = "application/json"
+        extension = "json"
+      }
+
+      const blob = new Blob([content], { type: mimeType })
+      const url = URL.createObjectURL(blob)
+      const link = document.createElement("a")
+      link.href = url
+      link.download = `${filename}.${extension}`
+      document.body.appendChild(link)
+      link.click()
+      document.body.removeChild(link)
+      URL.revokeObjectURL(url)
+    },
+    [data, period, metric, metricLabel, onExport]
+  )
+
+  // Handle cell highlighting
+  const handleCellMouseEnter = React.useCallback(
+    (rowId: string, columnIndex: number) => {
+      if (highlightOnHover) {
+        setHoveredRow(rowId)
+        setHoveredColumn(columnIndex)
+      }
+    },
+    [highlightOnHover]
+  )
+
+  const handleCellMouseLeave = React.useCallback(() => {
+    setHoveredRow(null)
+    setHoveredColumn(null)
+  }, [])
+
+  // Determine the display label for the metric
+  const displayMetricLabel = metricLabel || {
+    retention: "Retention",
+    churn: "Churn",
+    revenue: "Revenue",
+    engagement: "Engagement",
+    custom: "Value",
+  }[metric]
+
+  if (data.length === 0) {
+    return (
+      <div className={cn("flex flex-col items-center justify-center py-12 text-center", className)}>
+        <Users className="h-12 w-12 text-muted-foreground/50 mb-4" />
+        <h3 className="text-lg font-medium text-muted-foreground">No cohort data</h3>
+        <p className="text-sm text-muted-foreground/70 mt-1">
+          Add cohort data to see the analysis table.
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {/* Header with legend and export */}
+      <div className="flex items-center justify-between flex-wrap gap-4">
+        <div className="flex items-center gap-4">
+          <h3 className="text-lg font-semibold">{displayMetricLabel} Analysis</h3>
+          {showLegend && (
+            <ColorLegend
+              colorScale={colorScale}
+              min={0}
+              max={100}
+              showAsPercentage={showAsPercentage}
+            />
+          )}
+        </div>
+
+        {enableExport && (
+          <div className="flex items-center gap-2">
+            <button
+              onClick={() => handleExport("csv")}
+              className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-md border border-input bg-background hover:bg-accent hover:text-accent-foreground transition-colors"
+            >
+              <Download className="h-4 w-4" />
+              CSV
+            </button>
+            <button
+              onClick={() => handleExport("json")}
+              className="inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-md border border-input bg-background hover:bg-accent hover:text-accent-foreground transition-colors"
+            >
+              <Download className="h-4 w-4" />
+              JSON
+            </button>
+          </div>
+        )}
+      </div>
+
+      {/* Table */}
+      <div className="overflow-x-auto rounded-lg border border-border">
+        <table className={cn("w-full border-collapse", tableClassName)}>
+          <thead>
+            <tr className="bg-muted/50">
+              {/* Cohort header */}
+              <th
+                className={cn(
+                  "px-4 py-3 text-left text-sm font-semibold text-foreground border-b border-r border-border sticky left-0 bg-muted/50 z-10",
+                  headerClassName
+                )}
+              >
+                Cohort
+              </th>
+
+              {/* Size header */}
+              {showCohortSize && (
+                <th
+                  className={cn(
+                    "px-4 py-3 text-center text-sm font-semibold text-foreground border-b border-r border-border",
+                    headerClassName
+                  )}
+                >
+                  <div className="flex items-center justify-center gap-1">
+                    <Users className="h-4 w-4" />
+                    Size
+                  </div>
+                </th>
+              )}
+
+              {/* Period headers */}
+              {Array.from({ length: maxPeriods }, (_, i) => (
+                <th
+                  key={i}
+                  className={cn(
+                    "px-3 py-3 text-center text-sm font-semibold text-foreground border-b border-r border-border last:border-r-0 transition-colors",
+                    hoveredColumn === i && highlightOnHover && "bg-accent",
+                    headerClassName
+                  )}
+                >
+                  {getPeriodLabel(period, i)}
+                </th>
+              ))}
+            </tr>
+          </thead>
+
+          <tbody>
+            {data.map((row, rowIndex) => {
+              const isHighlightedRow = hoveredRow === row.id
+
+              return (
+                <tr
+                  key={row.id}
+                  className={cn(
+                    "transition-colors",
+                    isHighlightedRow && highlightOnHover && "bg-accent/30"
+                  )}
+                  onMouseEnter={() => setHoveredRow(row.id)}
+                  onMouseLeave={() => setHoveredRow(null)}
+                >
+                  {/* Cohort label */}
+                  <td
+                    className={cn(
+                      "px-4 py-2 text-sm font-medium text-foreground border-b border-r border-border sticky left-0 bg-background z-10",
+                      isHighlightedRow && highlightOnHover && "bg-accent/30",
+                      cellClassName
+                    )}
+                  >
+                    <div className="flex items-center gap-2">
+                      {row.label}
+                      {showTrends && rowIndex > 0 && row.data[0] && data[rowIndex - 1].data[0] && (
+                        <>
+                          {calculateTrend(row.data[0].value, data[rowIndex - 1].data[0].value) === "up" && (
+                            <TrendingUp className="h-3 w-3 text-green-600" />
+                          )}
+                          {calculateTrend(row.data[0].value, data[rowIndex - 1].data[0].value) === "down" && (
+                            <TrendingDown className="h-3 w-3 text-red-600" />
+                          )}
+                        </>
+                      )}
+                    </div>
+                  </td>
+
+                  {/* Cohort size */}
+                  {showCohortSize && (
+                    <td
+                      className={cn(
+                        "px-4 py-2 text-center text-sm text-muted-foreground border-b border-r border-border",
+                        cellClassName
+                      )}
+                    >
+                      {formatNumber(row.size)}
+                    </td>
+                  )}
+
+                  {/* Data cells */}
+                  {Array.from({ length: maxPeriods }, (_, i) => {
+                    const dataPoint = row.data[i]
+
+                    if (!dataPoint) {
+                      return (
+                        <td
+                          key={i}
+                          className={cn(
+                            "px-3 py-2 text-center text-sm text-muted-foreground border-b border-r border-border last:border-r-0 bg-muted/20",
+                            cellClassName
+                          )}
+                          onMouseEnter={() => handleCellMouseEnter(row.id, i)}
+                          onMouseLeave={handleCellMouseLeave}
+                        >
+                          -
+                        </td>
+                      )
+                    }
+
+                    const isHighlighted =
+                      (isHighlightedRow || hoveredColumn === i) && highlightOnHover
+
+                    return (
+                      <CohortCell
+                        key={i}
+                        dataPoint={dataPoint}
+                        row={row}
+                        periodIndex={i}
+                        colorScale={colorScale}
+                        showAsPercentage={showAsPercentage}
+                        decimalPlaces={decimalPlaces}
+                        highlighted={isHighlighted}
+                        onClick={() => onCellClick?.(row, i, dataPoint)}
+                        renderCell={renderCell}
+                        renderTooltip={renderTooltip}
+                        className={cn(
+                          "border-b",
+                          hoveredColumn === i && highlightOnHover && "ring-2 ring-primary/50 ring-inset",
+                          cellClassName
+                        )}
+                      />
+                    )
+                  })}
+                </tr>
+              )
+            })}
+
+            {/* Average row */}
+            {showAverageRow && averages.length > 0 && (
+              <tr className="bg-muted/30 font-medium">
+                <td
+                  className={cn(
+                    "px-4 py-2 text-sm font-semibold text-foreground border-r border-border sticky left-0 bg-muted/30 z-10",
+                    cellClassName
+                  )}
+                >
+                  <div className="flex items-center gap-2">
+                    <Info className="h-4 w-4 text-muted-foreground" />
+                    Average
+                  </div>
+                </td>
+
+                {showCohortSize && (
+                  <td
+                    className={cn(
+                      "px-4 py-2 text-center text-sm text-muted-foreground border-r border-border",
+                      cellClassName
+                    )}
+                  >
+                    {formatNumber(Math.round(data.reduce((sum, row) => sum + row.size, 0) / data.length))}
+                  </td>
+                )}
+
+                {Array.from({ length: maxPeriods }, (_, i) => {
+                  const avg = averages[i]
+
+                  if (!avg) {
+                    return (
+                      <td
+                        key={i}
+                        className={cn(
+                          "px-3 py-2 text-center text-sm text-muted-foreground border-r border-border last:border-r-0",
+                          cellClassName
+                        )}
+                      >
+                        -
+                      </td>
+                    )
+                  }
+
+                  return (
+                    <td
+                      key={i}
+                      className={cn(
+                        "px-3 py-2 text-center text-sm font-semibold border-r border-border last:border-r-0",
+                        cellClassName
+                      )}
+                      style={{
+                        backgroundColor: interpolateColor(avg.value, 0, 100, colorScale),
+                      }}
+                    >
+                      {formatValue(avg.value, showAsPercentage, decimalPlaces)}
+                    </td>
+                  )
+                })}
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Footer info */}
+      <div className="flex items-center justify-between text-xs text-muted-foreground">
+        <span>
+          {data.length} cohort{data.length !== 1 ? "s" : ""} | {maxPeriods} period{maxPeriods !== 1 ? "s" : ""}
+        </span>
+        <span>
+          Total users: {formatNumber(data.reduce((sum, row) => sum + row.size, 0))}
+        </span>
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Hook for managing cohort data
+// ============================================================================
+
+export interface UseCohortTableOptions {
+  /** Initial cohort data */
+  initialData?: CohortRow[]
+  /** Default period type */
+  defaultPeriod?: CohortPeriod
+  /** Default metric */
+  defaultMetric?: CohortMetric
+}
+
+export interface CohortStatistics {
+  /** Total number of cohorts */
+  totalCohorts: number
+  /** Total users across all cohorts */
+  totalUsers: number
+  /** Average initial cohort size */
+  averageCohortSize: number
+  /** Average retention at each period */
+  averageRetentionByPeriod: number[]
+  /** Overall average retention */
+  overallAverageRetention: number
+  /** Best performing cohort */
+  bestCohort: CohortRow | null
+  /** Worst performing cohort */
+  worstCohort: CohortRow | null
+}
+
+export function useCohortTable({
+  initialData = [],
+  defaultPeriod = "month",
+  defaultMetric = "retention",
+}: UseCohortTableOptions = {}) {
+  const [data, setData] = React.useState<CohortRow[]>(initialData)
+  const [period, setPeriod] = React.useState<CohortPeriod>(defaultPeriod)
+  const [metric, setMetric] = React.useState<CohortMetric>(defaultMetric)
+  const [selectedCohort, setSelectedCohort] = React.useState<string | null>(null)
+
+  // Calculate statistics
+  const statistics = React.useMemo<CohortStatistics>(() => {
+    if (data.length === 0) {
+      return {
+        totalCohorts: 0,
+        totalUsers: 0,
+        averageCohortSize: 0,
+        averageRetentionByPeriod: [],
+        overallAverageRetention: 0,
+        bestCohort: null,
+        worstCohort: null,
+      }
+    }
+
+    const totalUsers = data.reduce((sum, row) => sum + row.size, 0)
+    const averageCohortSize = totalUsers / data.length
+
+    // Calculate average retention by period
+    const maxPeriods = Math.max(...data.map((row) => row.data.length))
+    const averageRetentionByPeriod = Array.from({ length: maxPeriods }, (_, i) => {
+      const values = data
+        .map((row) => row.data[i]?.value)
+        .filter((v): v is number => v !== undefined)
+      return values.length > 0 ? values.reduce((a, b) => a + b, 0) / values.length : 0
+    })
+
+    const allValues = data.flatMap((row) => row.data.map((d) => d.value))
+    const overallAverageRetention =
+      allValues.length > 0 ? allValues.reduce((a, b) => a + b, 0) / allValues.length : 0
+
+    // Find best and worst cohorts by average retention
+    const cohortAverages = data.map((row) => ({
+      row,
+      average: row.data.length > 0
+        ? row.data.reduce((sum, d) => sum + d.value, 0) / row.data.length
+        : 0,
+    }))
+
+    const sorted = [...cohortAverages].sort((a, b) => b.average - a.average)
+    const bestCohort = sorted[0]?.row || null
+    const worstCohort = sorted[sorted.length - 1]?.row || null
+
+    return {
+      totalCohorts: data.length,
+      totalUsers,
+      averageCohortSize,
+      averageRetentionByPeriod,
+      overallAverageRetention,
+      bestCohort,
+      worstCohort,
+    }
+  }, [data])
+
+  // Add a new cohort
+  const addCohort = React.useCallback((cohort: CohortRow) => {
+    setData((prev) => [...prev, cohort])
+  }, [])
+
+  // Update an existing cohort
+  const updateCohort = React.useCallback((id: string, updates: Partial<CohortRow>) => {
+    setData((prev) =>
+      prev.map((row) => (row.id === id ? { ...row, ...updates } : row))
+    )
+  }, [])
+
+  // Remove a cohort
+  const removeCohort = React.useCallback((id: string) => {
+    setData((prev) => prev.filter((row) => row.id !== id))
+  }, [])
+
+  // Update a specific data point
+  const updateDataPoint = React.useCallback(
+    (cohortId: string, periodIndex: number, value: Partial<CohortDataPoint>) => {
+      setData((prev) =>
+        prev.map((row) => {
+          if (row.id !== cohortId) return row
+          const newData = [...row.data]
+          if (newData[periodIndex]) {
+            newData[periodIndex] = { ...newData[periodIndex], ...value }
+          }
+          return { ...row, data: newData }
+        })
+      )
+    },
+    []
+  )
+
+  // Sort cohorts
+  const sortCohorts = React.useCallback(
+    (sortBy: "date" | "size" | "retention", order: "asc" | "desc" = "desc") => {
+      setData((prev) => {
+        const sorted = [...prev].sort((a, b) => {
+          let comparison = 0
+
+          switch (sortBy) {
+            case "date":
+              comparison = a.date.getTime() - b.date.getTime()
+              break
+            case "size":
+              comparison = a.size - b.size
+              break
+            case "retention":
+              const avgA = a.data.length > 0
+                ? a.data.reduce((sum, d) => sum + d.value, 0) / a.data.length
+                : 0
+              const avgB = b.data.length > 0
+                ? b.data.reduce((sum, d) => sum + d.value, 0) / b.data.length
+                : 0
+              comparison = avgA - avgB
+              break
+          }
+
+          return order === "asc" ? comparison : -comparison
+        })
+
+        return sorted
+      })
+    },
+    []
+  )
+
+  // Filter cohorts by date range
+  const filterByDateRange = React.useCallback(
+    (startDate: Date, endDate: Date) => {
+      return data.filter(
+        (row) => row.date >= startDate && row.date <= endDate
+      )
+    },
+    [data]
+  )
+
+  // Get cohort by ID
+  const getCohortById = React.useCallback(
+    (id: string) => data.find((row) => row.id === id),
+    [data]
+  )
+
+  // Reset to initial data
+  const reset = React.useCallback(() => {
+    setData(initialData)
+    setPeriod(defaultPeriod)
+    setMetric(defaultMetric)
+    setSelectedCohort(null)
+  }, [initialData, defaultPeriod, defaultMetric])
+
+  return {
+    // State
+    data,
+    period,
+    metric,
+    selectedCohort,
+    statistics,
+
+    // Setters
+    setData,
+    setPeriod,
+    setMetric,
+    setSelectedCohort,
+
+    // Actions
+    addCohort,
+    updateCohort,
+    removeCohort,
+    updateDataPoint,
+    sortCohorts,
+    filterByDateRange,
+    getCohortById,
+    reset,
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default WakaCohortTable