@kolkrabbi/kol-component 0.6.0 → 0.7.0

package/src/dashboards/charts/DonutChart.jsx

@@ -0,0 +1,87 @@
+import { useMemo } from 'react'
+import useChartTooltip from '../shared/useChartTooltip'
+import DashTooltip from '../shared/DashTooltip'
+
+const DonutChart = ({
+  segments = [],
+  size = 120,
+  thickness = 20,
+  centerLabel,
+  showLegend = false
+}) => {
+  const total = useMemo(() => segments.reduce((sum, s) => sum + s.value, 0), [segments])
+  const { activeIndex, handlers, containerHandlers, containerRef } = useChartTooltip()
+
+  const radius = (size - thickness) / 2
+  const circumference = 2 * Math.PI * radius
+  const center = size / 2
+
+  const arcs = useMemo(() => {
+    let offset = 0
+    return segments.map((seg) => {
+      const pct = total > 0 ? seg.value / total : 0
+      const dash = pct * circumference
+      const gap = circumference - dash
+      const rotation = (offset / total) * 360
+      offset += seg.value
+      return { ...seg, dash, gap, rotation, pct }
+    })
+  }, [segments, total, circumference])
+
+  return (
+    <div className="inline-flex flex-col items-center gap-3">
+      <div
+        className="relative"
+        style={{ width: size, height: size }}
+        ref={containerRef}
+        {...containerHandlers}
+      >
+        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
+          {arcs.map((arc, i) => (
+            <circle
+              key={i}
+              className={`dash-donut-segment ${activeIndex === i ? 'dash-chart-element--active' : ''}`}
+              cx={center}
+              cy={center}
+              r={radius}
+              fill="none"
+              stroke={arc.color}
+              strokeWidth={thickness}
+              strokeDasharray={`${arc.dash} ${arc.gap}`}
+              transform={`rotate(${arc.rotation - 90} ${center} ${center})`}
+              style={{ cursor: 'default' }}
+              {...handlers(i)}
+            />
+          ))}
+        </svg>
+
+        {centerLabel && (
+          <div className="absolute inset-0 flex items-center justify-center pointer-events-none">
+            <span className="dash-body text-fg-88">{centerLabel}</span>
+          </div>
+        )}
+
+        <DashTooltip visible={activeIndex !== null}>
+          {activeIndex !== null && arcs[activeIndex] && (
+            <span className="dash-caption">
+              {arcs[activeIndex].label ? `${arcs[activeIndex].label}: ` : ''}{arcs[activeIndex].value} ({(arcs[activeIndex].pct * 100).toFixed(1)}%)
+            </span>
+          )}
+        </DashTooltip>
+      </div>
+
+      {showLegend && (
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-1 justify-center">
+          {segments.map((seg, i) => (
+            <div key={i} className="flex items-center gap-1.5">
+              <span className="w-2 h-2 rounded-full shrink-0" style={{ backgroundColor: seg.color }} />
+              <span className="dash-caption text-fg-64">{seg.label}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default DonutChart

package/src/dashboards/charts/Heatmap.jsx

@@ -0,0 +1,79 @@
+import useChartTooltip from '../shared/useChartTooltip'
+import DashTooltip from '../shared/DashTooltip'
+
+const Heatmap = ({
+  data = [],
+  rows = [],
+  cols = [],
+  colorScale = ['var(--kol-palette-blue)', 'var(--kol-palette-yellow)'],
+  cellSize = 32,
+  fill = false
+}) => {
+  const { activeIndex, handlers, containerHandlers, containerRef } = useChartTooltip()
+
+  const cells = Array.isArray(data[0])
+    ? data.flatMap((row, r) => row.map((value, c) => ({ row: r, col: c, value })))
+    : data
+
+  const maxValue = Math.max(...cells.map(c => c.value), 1)
+  const colCount = cols.length || (Array.isArray(data[0]) ? data[0].length : Math.max(...cells.map(c => c.col)) + 1)
+
+  return (
+    <div className={`flex gap-2 min-w-0${fill ? ' h-full' : ''}`} ref={containerRef} {...containerHandlers}>
+      {rows.length > 0 && (
+        <div
+          className="grid shrink-0 items-center"
+          style={{ gridTemplateRows: `repeat(${rows.length}, ${fill ? '1fr' : `${cellSize}px`})`, gap: '4px' }}
+        >
+          {rows.map((label, i) => (
+            <span key={i} className="dash-caption text-fg-64 text-right">{label}</span>
+          ))}
+        </div>
+      )}
+
+      <div className="flex-1 flex flex-col gap-2 min-w-0">
+        <div
+          className={`grid gap-1${fill ? ' flex-1' : ''}`}
+          style={{
+            gridTemplateColumns: `repeat(${colCount}, 1fr)`,
+            gridAutoRows: fill ? '1fr' : `${cellSize}px`
+          }}
+        >
+          {cells.map((cell, idx) => {
+            const pct = Math.round((cell.value / maxValue) * 100)
+            return (
+              <div
+                key={idx}
+                className={`dash-heatmap-cell rounded-sm ${activeIndex === idx ? 'dash-chart-element--active' : ''}`}
+                style={{
+                  backgroundColor: `color-mix(in srgb, ${colorScale[1]} ${pct}%, ${colorScale[0]})`
+                }}
+                {...handlers(idx)}
+              />
+            )
+          })}
+        </div>
+
+        {cols.length > 0 && (
+          <div className="flex justify-around">
+            {cols.map((label, i) => (
+              <span key={i} className="dash-caption text-fg-64 text-center">{label}</span>
+            ))}
+          </div>
+        )}
+
+        <DashTooltip visible={activeIndex !== null}>
+          {activeIndex !== null && cells[activeIndex] && (
+            <span className="dash-caption">
+              {rows[cells[activeIndex].row] ?? `R${cells[activeIndex].row}`},{' '}
+              {cols[cells[activeIndex].col] ?? `C${cells[activeIndex].col}`}:{' '}
+              {cells[activeIndex].value}
+            </span>
+          )}
+        </DashTooltip>
+      </div>
+    </div>
+  )
+}
+
+export default Heatmap

package/src/dashboards/charts/Histogram.jsx

@@ -0,0 +1,56 @@
+import useChartTooltip from '../shared/useChartTooltip'
+import DashTooltip from '../shared/DashTooltip'
+
+const Histogram = ({
+  data = [],
+  barColor = 'var(--kol-accent-primary)'
+}) => {
+  const maxCount = Math.max(...data.map(d => d.count), 1)
+  const { activeIndex, handlers, containerHandlers, containerRef } = useChartTooltip()
+
+  return (
+    <div className="flex min-w-0 flex-1 min-h-0">
+      <div className="flex flex-col justify-between pr-2 shrink-0">
+        <span className="dash-caption text-fg-64 text-right">{maxCount}</span>
+        <span className="dash-caption text-fg-64 text-right">{Math.round(maxCount / 2)}</span>
+        <span className="dash-caption text-fg-64 text-right">0</span>
+      </div>
+
+      <div className="flex-1 flex flex-col gap-2 min-w-0" ref={containerRef} {...containerHandlers}>
+        <div className="relative flex items-end gap-1 flex-1">
+          {data.map((bucket, idx) => {
+            const pct = Math.round((bucket.count / maxCount) * 100)
+            return (
+              <div
+                key={idx}
+                className={`flex-1 flex items-end min-w-0 h-full ${activeIndex === idx ? 'dash-chart-element--active' : ''}`}
+                {...handlers(idx)}
+              >
+                <div
+                  className="w-full rounded-t-sm"
+                  style={{ height: `${pct}%`, backgroundColor: barColor }}
+                />
+              </div>
+            )
+          })}
+
+          <DashTooltip visible={activeIndex !== null}>
+            {activeIndex !== null && data[activeIndex] && (
+              <span className="dash-caption">{data[activeIndex].range}: {data[activeIndex].count}</span>
+            )}
+          </DashTooltip>
+        </div>
+
+        <div className="flex items-start gap-1">
+          {data.map((bucket, idx) => (
+            <div key={idx} className="flex-1 flex flex-col items-center min-w-0 overflow-hidden">
+              <span className="dash-caption text-fg-64 truncate w-full text-center">{bucket.range}</span>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default Histogram

package/src/dashboards/charts/LineChart.jsx

@@ -0,0 +1,157 @@
+import { useMemo } from 'react'
+import useChartTooltip from '../shared/useChartTooltip'
+import DashTooltip from '../shared/DashTooltip'
+
+const SVG_HEIGHT = 100
+
+const normalizeAll = (seriesArr) => {
+  const allValues = seriesArr.flatMap(s => s.data.map(d => d.y))
+  const min = Math.min(...allValues)
+  const max = Math.max(...allValues)
+  const range = max - min || 1
+
+  return seriesArr.map(s => ({
+    ...s,
+    points: s.data.map((d, i) => ({
+      x: (i / Math.max(s.data.length - 1, 1)) * 100,
+      y: SVG_HEIGHT - ((d.y - min) / range) * (SVG_HEIGHT * 0.8) - SVG_HEIGHT * 0.1,
+      raw: d
+    }))
+  }))
+}
+
+const buildPath = (points) =>
+  points.map((p, i) => `${i === 0 ? 'M' : 'L'} ${p.x.toFixed(2)} ${p.y.toFixed(2)}`).join(' ')
+
+const buildAreaPath = (linePath) =>
+  `${linePath} L 100 ${SVG_HEIGHT} L 0 ${SVG_HEIGHT} Z`
+
+const LineChart = ({
+  data,
+  series,
+  height = 240,
+  fill = false,
+  xLabels,
+  yLabels,
+  showArea = false,
+  showDots = false
+}) => {
+  const resolvedSeries = useMemo(() => {
+    if (series) return series
+    if (data) return [{ data, color: 'var(--kol-accent-primary)' }]
+    return []
+  }, [data, series])
+
+  const normalizedSeries = useMemo(() => normalizeAll(resolvedSeries), [resolvedSeries])
+
+  const { activeIndex, handlers, containerHandlers, containerRef } = useChartTooltip()
+
+  const gradientIds = normalizedSeries.map((_, i) => `line-area-grad-${i}`)
+
+  return (
+    <div className={`flex min-w-0${fill ? ' h-full' : ''}`}>
+      {yLabels && (
+        <div className="flex flex-col justify-between pr-2 shrink-0" style={fill ? undefined : { height }}>
+          {[...yLabels].reverse().map((label, i) => (
+            <span key={i} className="dash-caption text-fg-64 text-right">{label}</span>
+          ))}
+        </div>
+      )}
+
+      <div className="flex-1 flex flex-col gap-2 min-w-0" ref={containerRef} {...containerHandlers}>
+        <div className={`relative${fill ? ' flex-1' : ''}`} style={fill ? undefined : { height }}>
+          <svg
+            className="absolute inset-0 w-full h-full"
+            viewBox={`0 0 100 ${SVG_HEIGHT}`}
+            preserveAspectRatio="none"
+          >
+            <defs>
+              {normalizedSeries.map((s, i) => (showArea || s.fill) && (
+                <linearGradient key={i} id={gradientIds[i]} x1="0%" y1="0%" x2="0%" y2="100%">
+                  <stop offset="0%" stopColor={s.color} stopOpacity="0.3" />
+                  <stop offset="100%" stopColor={s.color} stopOpacity="0" />
+                </linearGradient>
+              ))}
+            </defs>
+
+            {normalizedSeries.map((s, i) => {
+              const path = buildPath(s.points)
+              return (
+                <g key={i}>
+                  {(showArea || s.fill) && (
+                    <path
+                      className="dash-line-area"
+                      d={buildAreaPath(path)}
+                      fill={`url(#${gradientIds[i]})`}
+                    />
+                  )}
+                  <path
+                    className="dash-line-path"
+                    d={path}
+                    fill="none"
+                    stroke={s.color}
+                    strokeWidth="2"
+                    strokeLinejoin="round"
+                    strokeLinecap="round"
+                    vectorEffect="non-scaling-stroke"
+                  />
+                </g>
+              )
+            })}
+          </svg>
+
+          {showDots && normalizedSeries.map((s, si) =>
+            s.points.map((p, pi) => (
+              <span
+                key={`${si}-${pi}`}
+                className={`absolute block w-2 h-2 rounded-full ${activeIndex === pi ? 'dash-chart-element--active' : ''}`}
+                style={{
+                  backgroundColor: s.color,
+                  left: `${p.x}%`,
+                  top: `${p.y}%`,
+                  transform: 'translate(-50%, -50%)'
+                }}
+                {...handlers(pi)}
+              />
+            ))
+          )}
+
+          {!showDots && normalizedSeries[0]?.points.map((p, pi) => (
+            <span
+              key={pi}
+              className="absolute top-0 bottom-0"
+              style={{ left: `${p.x}%`, width: `${100 / Math.max(normalizedSeries[0].points.length - 1, 1)}%`, transform: 'translateX(-50%)' }}
+              {...handlers(pi)}
+            />
+          ))}
+
+          <DashTooltip visible={activeIndex !== null}>
+            {activeIndex !== null && (
+              <div className="flex flex-col gap-0.5">
+                {normalizedSeries.map((s, si) => {
+                  const pt = s.points[activeIndex]
+                  if (!pt) return null
+                  return (
+                    <span key={si} className="dash-caption">
+                      {pt.raw.x != null ? `${pt.raw.x}: ` : ''}{pt.raw.y}
+                    </span>
+                  )
+                })}
+              </div>
+            )}
+          </DashTooltip>
+        </div>
+
+        {xLabels && (
+          <div className="flex justify-between">
+            {xLabels.map((label, i) => (
+              <span key={i} className="dash-caption text-fg-64">{label}</span>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default LineChart

package/src/dashboards/charts/ScatterPlot.jsx

@@ -0,0 +1,93 @@
+import useChartTooltip from '../shared/useChartTooltip'
+import DashTooltip from '../shared/DashTooltip'
+
+const ScatterPlot = ({
+  data = [],
+  maxX = 200,
+  maxY = 3000,
+  xLabels = [],
+  yLabels = [],
+  pointColor = 'var(--kol-palette-blue)',
+  height = 320
+}) => {
+  const formatY = (v) => v === 0 ? '0' : v >= 1000 ? `${(v / 1000).toFixed(1).replace('.0', '')}K` : v
+  const { activeIndex, handlers, containerHandlers, containerRef } = useChartTooltip()
+
+  const minY = yLabels.length > 0 ? Math.min(...yLabels) : 0
+  const rangeY = maxY - minY || 1
+  const scaleY = (v) => ((v - minY) / rangeY) * 90 + 5
+  const scaleX = (v) => (v / maxX) * 100
+
+  return (
+    <div className="flex">
+      <div className="relative pr-2 shrink-0 w-10" style={{ height }}>
+        {yLabels.map((yValue) => (
+          <span
+            key={yValue}
+            className="absolute right-2 dash-caption text-fg-64"
+            style={{ bottom: `${scaleY(yValue)}%`, transform: 'translateY(50%)' }}
+          >
+            {formatY(yValue)}
+          </span>
+        ))}
+      </div>
+
+      <div className="flex-1 flex flex-col min-w-0">
+        <div className="relative rounded" style={{ height }} ref={containerRef} {...containerHandlers}>
+          {yLabels.map((yValue) => (
+            <div
+              key={yValue}
+              className="absolute left-0 right-0 border-t border-fg-08"
+              style={{ bottom: `${scaleY(yValue)}%` }}
+            />
+          ))}
+
+          {xLabels.map((xValue) => (
+            <div
+              key={xValue}
+              className="absolute top-0 bottom-0 border-l border-fg-08"
+              style={{ left: `${scaleX(xValue)}%` }}
+            />
+          ))}
+
+          {data.map(point => (
+            <span
+              key={point.id}
+              className={`absolute block dash-scatter-point ${activeIndex === point.id ? 'dash-chart-element--active' : ''}`}
+              style={{
+                background: pointColor,
+                left: `${scaleX(point.x)}%`,
+                bottom: `${scaleY(point.y)}%`,
+                transform: 'translate(-50%, 50%)'
+              }}
+              {...handlers(point.id)}
+            />
+          ))}
+
+          <DashTooltip visible={activeIndex !== null}>
+            {activeIndex !== null && (() => {
+              const point = data.find(p => p.id === activeIndex)
+              if (!point) return null
+              return (
+                <div className="flex flex-col gap-0.5">
+                  {point.id != null && <span className="dash-caption text-fg-64">{point.id}</span>}
+                  <span className="dash-caption">x: {point.x}</span>
+                  <span className="dash-caption">y: {point.y}</span>
+                </div>
+              )
+            })()}
+          </DashTooltip>
+        </div>
+
+        <div className="flex justify-between pt-2">
+          <span className="dash-caption text-fg-64">0</span>
+          {xLabels.map((xValue) => (
+            <span key={xValue} className="dash-caption text-fg-64">{xValue}</span>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default ScatterPlot

package/src/dashboards/charts/Sparkline.jsx

@@ -0,0 +1,63 @@
+import { useMemo } from 'react'
+
+const Sparkline = ({
+  data = [],
+  color = 'var(--kol-surface-on-primary)',
+  height = 24,
+  fill = false
+}) => {
+  const path = useMemo(() => {
+    if (data.length < 2) return ''
+    const min = Math.min(...data)
+    const max = Math.max(...data)
+    const range = max - min || 1
+
+    return data
+      .map((v, i) => {
+        const x = (i / (data.length - 1)) * 100
+        const y = 100 - ((v - min) / range) * 80 - 10
+        return `${i === 0 ? 'M' : 'L'} ${x.toFixed(2)} ${y.toFixed(2)}`
+      })
+      .join(' ')
+  }, [data])
+
+  if (!path) return null
+
+  const id = useMemo(() => `spark-${Math.random().toString(36).slice(2, 8)}`, [])
+
+  return (
+    <svg
+      width="100%"
+      height={height}
+      viewBox="0 0 100 100"
+      preserveAspectRatio="none"
+      style={{ display: 'block' }}
+    >
+      {fill && (
+        <>
+          <defs>
+            <linearGradient id={id} x1="0%" y1="0%" x2="0%" y2="100%">
+              <stop offset="0%" stopColor={color} stopOpacity="0.25" />
+              <stop offset="100%" stopColor={color} stopOpacity="0" />
+            </linearGradient>
+          </defs>
+          <path
+            d={`${path} L 100 100 L 0 100 Z`}
+            fill={`url(#${id})`}
+          />
+        </>
+      )}
+      <path
+        d={path}
+        fill="none"
+        stroke={color}
+        strokeWidth="2"
+        strokeLinejoin="round"
+        strokeLinecap="round"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  )
+}
+
+export default Sparkline

package/src/dashboards/index.js

@@ -0,0 +1,28 @@
+// Cards
+export { default as DashMetricCard } from './cards/DashMetricCard'
+export { default as DashStackedBarCard } from './cards/DashStackedBarCard'
+export { default as DashChartCard } from './cards/DashChartCard'
+export { default as DashListCard } from './cards/DashListCard'
+export { default as DashFeaturedCard } from './cards/DashFeaturedCard'
+export { default as DashAlertCard } from './cards/DashAlertCard'
+export { default as DashSlotCard } from './cards/DashSlotCard'
+export { default as DashTableCard } from './cards/DashTableCard'
+
+// Chart visualizations
+export { default as Histogram } from './charts/Histogram'
+export { default as Candlestick } from './charts/Candlestick'
+export { default as ScatterPlot } from './charts/ScatterPlot'
+export { default as LineChart } from './charts/LineChart'
+export { default as DonutChart } from './charts/DonutChart'
+export { default as Sparkline } from './charts/Sparkline'
+export { default as Heatmap } from './charts/Heatmap'
+
+// Layout
+export { default as DashboardGrid } from './layout/DashboardGrid'
+export { default as GridCard } from './layout/GridCard'
+
+// Shared
+export { default as DashTooltip } from './shared/DashTooltip'
+export { default as useChartTooltip } from './shared/useChartTooltip'
+export { default as useCountUp } from './shared/useCountUp'
+export { default as formatMetric, formatCompact, formatPercent, formatDelta } from './shared/formatMetric'

package/src/dashboards/layout/DashboardGrid.jsx

@@ -0,0 +1,30 @@
+import React from 'react'
+
+/**
+ * DashboardGrid - Flexible grid system for chess dashboard layouts
+ *
+ * Layouts:
+ * - '4-col': 4 columns × 200px rows (default)
+ * - '6-col': 6 columns × 180px rows (dense)
+ * - 'board-focus': 3fr/2fr columns × 240px rows (board emphasis)
+ * - '3-col': 3 columns × 200px rows (simple)
+ *
+ * @param {string} layout - Grid configuration preset
+ * @param {string} className - Additional CSS classes
+ * @param {React.ReactNode} children - GridCard components
+ */
+const DashboardGrid = ({
+  layout = '4-col',
+  className = '',
+  children
+}) => {
+  return (
+    <div style={{ containerType: 'inline-size' }}>
+      <div className={`dash-grid ${className}`.trim()}>
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export default DashboardGrid

package/src/dashboards/layout/GridCard.jsx

@@ -0,0 +1,44 @@
+import React from 'react'
+
+/**
+ * GridCard - Wrapper for components in the dashboard grid
+ *
+ * Span configurations:
+ * - '1x1': Single cell (default)
+ * - '2x1': 2 columns × 1 row
+ * - '2x2': 2 columns × 2 rows
+ * - '3x2': 3 columns × 2 rows
+ * - '4x2': 4 columns × 2 rows (full width, double height)
+ * - '1x2': 1 column × 2 rows (tall card)
+ * - '3x1': 3 columns × 1 row
+ * - '4x1': 4 columns × 1 row (full width strip)
+ *
+ * @param {string} span - Grid span configuration
+ * @param {string} className - Additional CSS classes
+ * @param {React.ReactNode} children - Component to display
+ * @param {boolean} asCard - Wrap in card styling (for non-component content)
+ */
+const GridCard = ({
+  span = '1x1',
+  className = '',
+  children,
+  asCard = false
+}) => {
+  const [cols, rows] = (span || '1x1').split('x').map(Number)
+
+  const style = {
+    gridColumn: `span ${cols || 1}`,
+    gridRow: `span ${rows || 1}`
+  }
+
+  // If asCard, add card styling; otherwise just grid positioning
+  const cardClass = asCard ? 'dash-card' : ''
+
+  return (
+    <div data-cols={cols || 1} style={style} className={`h-full ${cardClass} ${className}`.trim()}>
+      {children}
+    </div>
+  )
+}
+
+export default GridCard

package/src/dashboards/shared/DashTooltip.jsx

@@ -0,0 +1,6 @@
+const DashTooltip = ({ visible, children }) => {
+  if (!visible) return null
+  return <div className="dash-tooltip">{children}</div>
+}
+
+export default DashTooltip

package/src/dashboards/shared/formatMetric.js

@@ -0,0 +1,26 @@
+export const formatCompact = (n) => {
+  if (n >= 1000000) {
+    return `${(n / 1000000).toFixed(1).replace(/\.0$/, '')}M`
+  }
+  if (n >= 1000) {
+    const formatted = (n / 1000).toFixed(n >= 10000 ? 0 : 1)
+    return `${formatted.replace(/\.0$/, '')}K`
+  }
+  return n.toLocaleString()
+}
+
+export const formatPercent = (n) => {
+  if (!Number.isFinite(n)) return '0'
+  const formatted = n >= 10 ? n.toFixed(0) : n.toFixed(1)
+  return `${formatted.replace(/\.0$/, '')}%`
+}
+
+export const formatDelta = (n) => {
+  if (!Number.isFinite(n)) return '0%'
+  const sign = n > 0 ? '+' : ''
+  const formatted = Math.abs(n) >= 10 ? n.toFixed(0) : n.toFixed(1)
+  return `${sign}${formatted.replace(/\.0$/, '')}%`
+}
+
+const formatMetric = { formatCompact, formatPercent, formatDelta }
+export default formatMetric