@glyphui/ui 0.4.0 → 0.5.0

package/src/patterns/chart/heatmap.tsx

@@ -0,0 +1,339 @@
+import { type KeyboardEvent, type ReactNode, useMemo, useRef, useState } from 'react'
+import { cn } from '../../utils/cn'
+import {
+  type ChartColorValue,
+  ChartFrame,
+  type ChartStateProps,
+  defaultFormatter,
+  type Key,
+  resolveColor,
+  useChartParts,
+} from './chart-parts'
+import { useElementWidth } from './use-element-width'
+
+type Row = Record<string, unknown>
+
+export interface HeatmapProps<T extends object> extends ChartStateProps {
+  /** One row per day. Missing days count as zero. */
+  data: readonly T[]
+  /** Field holding the day: a Date, a timestamp or a `YYYY-MM-DD` string. */
+  date: Key<T>
+  /** Field holding the day's value. */
+  value: Key<T>
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  /** First day shown. Defaults to 52 weeks before `to`. */
+  from?: Date
+  /** Last day shown. Defaults to the latest day in `data`, or today. */
+  to?: Date
+  /** 0 starts weeks on Sunday, 1 on Monday. Default 0. */
+  weekStart?: 0 | 1
+  /** Default `chart-1`. Busier days get stronger tints of it. */
+  color?: ChartColorValue
+  /** Number of tint steps above zero. Default 4. */
+  levels?: number
+  valueFormatter?: (value: number) => string
+  /** Noun read after the value, e.g. `"deploys"` → "12 deploys on Mon, Oct 6". */
+  unit?: string
+  /** Locale for month and day names. Defaults to the browser's. */
+  locale?: string
+  onCellClick?: (date: Date, value: number) => void
+  className?: string
+}
+
+const CELL = 12
+const GAP = 3
+const LEFT = 30
+const TOP = 18
+const DAY = 86_400_000
+
+function toDate(input: unknown): Date | undefined {
+  if (input instanceof Date) return input
+  if (typeof input === 'number') return new Date(input)
+  if (typeof input === 'string') {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input)
+    if (m) return new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
+    const parsed = new Date(input)
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed
+  }
+  return undefined
+}
+
+const startOfDay = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate())
+const dayKey = (d: Date) => `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`
+const addDays = (d: Date, n: number) => new Date(d.getFullYear(), d.getMonth(), d.getDate() + n)
+
+interface Cell {
+  key: string
+  date: Date
+  value: number
+  level: number
+  week: number
+  weekday: number
+}
+
+/**
+ * Activity per day over months, like a contribution calendar. Each day is a keyboard
+ * reachable cell: Tab into the grid, then use the arrow keys, Home and End.
+ */
+export function Heatmap<T extends object>(props: HeatmapProps<T>) {
+  const {
+    data,
+    date,
+    value,
+    weekStart = 0,
+    levels = 4,
+    valueFormatter = defaultFormatter,
+    unit,
+    locale,
+  } = props
+  const { s, slots } = useChartParts()
+  const [ref, renderedWidth] = useElementWidth<HTMLDivElement>(0)
+  const gridRef = useRef<SVGSVGElement>(null)
+
+  const { cells, weeks, months, max, byKey, first, last } = useMemo(() => {
+    const values = new Map<string, number>()
+    let latest: Date | undefined
+    for (const row of data as readonly Row[]) {
+      const day = toDate(row[date])
+      if (!day) continue
+      const k = dayKey(day)
+      values.set(k, (values.get(k) ?? 0) + (Number(row[value]) || 0))
+      if (!latest || day > latest) latest = day
+    }
+    const end = startOfDay(props.to ?? latest ?? new Date())
+    const start = startOfDay(props.from ?? addDays(end, -7 * 52 + 1))
+    const offset = (start.getDay() - weekStart + 7) % 7
+    const gridStart = addDays(start, -offset)
+    const top = Math.max(0, ...values.values())
+    const list: Cell[] = []
+    const index = new Map<string, Cell>()
+    for (let d = start; d <= end; d = addDays(d, 1)) {
+      const k = dayKey(d)
+      const v = values.get(k) ?? 0
+      const days = Math.round((d.getTime() - gridStart.getTime()) / DAY)
+      const cell: Cell = {
+        key: k,
+        date: d,
+        value: v,
+        level: v <= 0 || top === 0 ? 0 : Math.min(levels, Math.ceil((v / top) * levels)),
+        week: Math.floor(days / 7),
+        weekday: days % 7,
+      }
+      list.push(cell)
+      index.set(k, cell)
+    }
+    const monthLabels: { week: number; label: string }[] = []
+    const monthFormat = new Intl.DateTimeFormat(locale, { month: 'short' })
+    let lastMonth = -1
+    for (const cell of list) {
+      if (cell.date.getDate() <= 7 && cell.weekday === 0 && cell.date.getMonth() !== lastMonth) {
+        const previous = monthLabels[monthLabels.length - 1]
+        if (!previous || cell.week - previous.week >= 3)
+          monthLabels.push({ week: cell.week, label: monthFormat.format(cell.date) })
+        lastMonth = cell.date.getMonth()
+      }
+    }
+    return {
+      cells: list,
+      weeks: (list[list.length - 1]?.week ?? 0) + 1,
+      months: monthLabels,
+      max: top,
+      byKey: index,
+      first: list[0],
+      last: list[list.length - 1],
+    }
+  }, [data, date, value, props.from, props.to, weekStart, levels, locale])
+
+  const [focused, setFocused] = useState<string | undefined>()
+  const [hovered, setHovered] = useState<string | undefined>()
+  const activeKey = focused && byKey.has(focused) ? focused : last?.key
+
+  const base = resolveColor(props.color ?? 'chart-1', 0)
+  const tint = (level: number) => {
+    if (level === 0) return 'var(--glyph-muted)'
+    const share = levels === 1 ? 100 : Math.round(30 + (70 * (level - 1)) / (levels - 1))
+    return share >= 100 ? base : `color-mix(in oklab, ${base} ${share}%, var(--glyph-muted))`
+  }
+
+  const width = LEFT + weeks * (CELL + GAP)
+  const height = TOP + 7 * (CELL + GAP)
+  const dayFormat = new Intl.DateTimeFormat(locale, {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  })
+  const weekdayFormat = new Intl.DateTimeFormat(locale, { weekday: 'short' })
+  const describe = (cell: Cell) =>
+    `${valueFormatter(cell.value)}${unit ? ` ${unit}` : ''} on ${dayFormat.format(cell.date)}`
+
+  const move = (event: KeyboardEvent<SVGRectElement>, cell: Cell) => {
+    const steps: Record<string, number> = {
+      ArrowLeft: -7,
+      ArrowRight: 7,
+      ArrowUp: -1,
+      ArrowDown: 1,
+      PageUp: -28,
+      PageDown: 28,
+    }
+    let target: Cell | undefined
+    if (event.key in steps) {
+      const next = byKey.get(dayKey(addDays(cell.date, steps[event.key]!)))
+      target = next ?? cell
+    } else if (event.key === 'Home') target = first
+    else if (event.key === 'End') target = last
+    else if ((event.key === 'Enter' || event.key === ' ') && props.onCellClick) {
+      event.preventDefault()
+      props.onCellClick(cell.date, cell.value)
+      return
+    } else return
+    event.preventDefault()
+    if (!target) return
+    setFocused(target.key)
+    gridRef.current?.querySelector<SVGRectElement>(`[data-day="${target.key}"]`)?.focus()
+  }
+
+  const tooltipCell = byKey.get(hovered ?? '') ?? (focused ? byKey.get(focused) : undefined)
+  const scale = renderedWidth > 0 ? Math.min(renderedWidth, width) / width : 1
+
+  const table = {
+    columns: ['Date', String(value)],
+    rows: cells.map((cell) => [dayFormat.format(cell.date), valueFormatter(cell.value)]),
+  }
+
+  return (
+    <ChartFrame
+      title={props.title}
+      description={props.description}
+      hideTitle={props.hideTitle}
+      className={props.className}
+      table={table}
+      height={height}
+      isEmpty={data.length === 0}
+      loading={props.loading}
+      error={props.error}
+      onRetry={props.onRetry}
+      empty={props.empty}
+      accessiblePlot
+    >
+      {/* The grid is drawn in SVG so it scales and exports; ARIA grid roles give it table
+          semantics and roving focus, which a <table> of tiny cells could not lay out. */}
+      {/* biome-ignore lint/a11y/useSemanticElements: see above */}
+      <div
+        ref={ref}
+        role="grid"
+        aria-label={props.title}
+        aria-rowcount={7}
+        className="relative w-full"
+        onMouseLeave={() => setHovered(undefined)}
+      >
+        <svg
+          ref={gridRef}
+          role="presentation"
+          viewBox={`0 0 ${width} ${height}`}
+          width="100%"
+          style={{ maxWidth: width }}
+          className="block h-auto overflow-visible"
+        >
+          {/* biome-ignore lint/a11y/noAriaHiddenOnFocusable: plain text labels, nothing focusable */}
+          <g aria-hidden="true" fontSize={10} fill="var(--glyph-muted-foreground)">
+            {months.map((month) => (
+              <text
+                key={`${month.week}-${month.label}`}
+                x={LEFT + month.week * (CELL + GAP)}
+                y={10}
+              >
+                {month.label}
+              </text>
+            ))}
+            {/* Label Monday, Wednesday and Friday, whichever rows they fall on. */}
+            {[1, 3, 5].map((day) => {
+              const row = (day - weekStart + 7) % 7
+              return (
+                <text key={day} x={0} y={TOP + row * (CELL + GAP) + CELL - 2}>
+                  {weekdayFormat.format(addDays(new Date(2023, 0, 1), day))}
+                </text>
+              )
+            })}
+          </g>
+          {Array.from({ length: 7 }, (_, weekday) => (
+            // biome-ignore lint/a11y/useSemanticElements: SVG has no table rows
+            <g key={weekday} role="row" aria-rowindex={weekday + 1}>
+              {cells
+                .filter((cell) => cell.weekday === weekday)
+                .map((cell) => (
+                  // biome-ignore lint/a11y/useSemanticElements: SVG has no table cells
+                  <rect
+                    key={cell.key}
+                    role="gridcell"
+                    data-day={cell.key}
+                    data-level={cell.level}
+                    aria-label={describe(cell)}
+                    aria-colindex={cell.week + 1}
+                    tabIndex={cell.key === activeKey ? 0 : -1}
+                    x={LEFT + cell.week * (CELL + GAP)}
+                    y={TOP + weekday * (CELL + GAP)}
+                    width={CELL}
+                    height={CELL}
+                    rx={2.5}
+                    fill={tint(cell.level)}
+                    className={cn(
+                      'outline-none focus-visible:stroke-ring focus-visible:[stroke-width:2]',
+                      props.onCellClick && 'cursor-pointer',
+                    )}
+                    onMouseEnter={() => setHovered(cell.key)}
+                    onFocus={() => setFocused(cell.key)}
+                    onBlur={() =>
+                      setFocused((current) => (current === cell.key ? undefined : current))
+                    }
+                    onKeyDown={(event) => move(event, cell)}
+                    onClick={() => props.onCellClick?.(cell.date, cell.value)}
+                  />
+                ))}
+            </g>
+          ))}
+        </svg>
+        {tooltipCell && (
+          <div
+            aria-hidden="true"
+            data-slot="chart-tooltip"
+            className={s.tooltip({
+              class: [
+                slots.tooltip,
+                'pointer-events-none absolute z-10 min-w-0 -translate-x-1/2 -translate-y-full whitespace-nowrap',
+              ],
+            })}
+            style={{
+              left: (LEFT + tooltipCell.week * (CELL + GAP) + CELL / 2) * scale,
+              top: (TOP + tooltipCell.weekday * (CELL + GAP)) * scale - 6,
+            }}
+          >
+            <span className={s.tooltipValue({ class: slots.tooltipValue })}>
+              {valueFormatter(tooltipCell.value)}
+              {unit ? ` ${unit}` : ''}
+            </span>{' '}
+            <span className="text-muted-foreground">{dayFormat.format(tooltipCell.date)}</span>
+          </div>
+        )}
+      </div>
+      <div
+        aria-hidden="true"
+        className="mt-2 flex items-center justify-end gap-1 text-caption text-muted-foreground"
+        style={{ maxWidth: width }}
+      >
+        <span className="mr-1">Less</span>
+        {Array.from({ length: levels + 1 }, (_, level) => (
+          <span
+            key={level}
+            className="size-2.5 rounded-[2px]"
+            style={{ background: tint(level) }}
+            title={level === levels && max > 0 ? `${valueFormatter(max)}` : undefined}
+          />
+        ))}
+        <span className="ml-1">More</span>
+      </div>
+    </ChartFrame>
+  )
+}

package/src/patterns/chart/icons.tsx

@@ -0,0 +1,44 @@
+import type { SVGProps } from 'react'
+
+type IconProps = SVGProps<SVGSVGElement>
+
+function Icon({ children, ...props }: IconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      {...props}
+    >
+      {children}
+    </svg>
+  )
+}
+
+export const TableIcon = (p: IconProps) => (
+  <Icon {...p}>
+    <rect x="3" y="4" width="18" height="16" rx="2" />
+    <path d="M3 10h18M3 15h18M9 10v10" />
+  </Icon>
+)
+
+export const ChartIcon = (p: IconProps) => (
+  <Icon {...p}>
+    <path d="M3 3v18h18" />
+    <path d="m7 15 4-4 3 3 5-6" />
+  </Icon>
+)
+
+export const DownloadIcon = (p: IconProps) => (
+  <Icon {...p}>
+    <path d="M12 4v11m0 0-4-4m4 4 4-4" />
+    <path d="M4 19h16" />
+  </Icon>
+)

package/src/patterns/chart/index.ts

@@ -2,12 +2,57 @@ export {
   AreaChart,
   BarChart,
   type CartesianChartProps,
-  type ChartColor,
+  type ChartAxisOptions,
+  type ChartBrushOptions,
+  type ChartReferenceArea,
+  type ChartReferenceLine,
   type ChartSeries,
-  DonutChart,
-  type DonutChartProps,
+  ComposedChart,
+  type ComposedChartProps,
+  type ComposedSeries,
   LineChart,
-  Sparkline,
-  type SparklineProps,
-} from './chart'
-export { type ChartVariants, chartStyles } from './chart.styles'
+} from './cartesian'
+export {
+  type ChartCardVariants,
+  type ChartVariants,
+  chartCardStyles,
+  chartStyles,
+} from './chart.styles'
+export { ChartCard, type ChartCardProps, type ChartPeriod } from './chart-card'
+export {
+  type ChartColor,
+  type ChartColorValue,
+  ChartLegend,
+  type ChartLegendProps,
+  type ChartStateProps,
+  ChartTooltipCard,
+  type ChartTooltipCardProps,
+  type LegendEntry,
+} from './chart-parts'
+export {
+  type ExportChartOptions,
+  exportChart,
+  type SerializeChartOptions,
+  serializeChart,
+} from './export'
+export { FunnelChart, type FunnelChartProps } from './funnel'
+export { Heatmap, type HeatmapProps } from './heatmap'
+export { DonutChart, type DonutChartProps, PieChart, type PieChartProps } from './pie'
+export {
+  Gauge,
+  type GaugeBand,
+  type GaugeProps,
+  RadarChart,
+  type RadarChartProps,
+  RadialBarChart,
+  type RadialBarChartProps,
+} from './radial'
+export {
+  SankeyChart,
+  type SankeyChartProps,
+  type SankeyLink,
+  type SankeyNode,
+} from './sankey'
+export { ScatterChart, type ScatterChartProps } from './scatter'
+export { Sparkline, type SparklineProps } from './sparkline'
+export { Treemap, type TreemapProps } from './treemap'

package/src/patterns/chart/pie.tsx

@@ -0,0 +1,169 @@
+import type { ReactNode } from 'react'
+import * as R from 'recharts'
+import { useControllableState } from '../../hooks/use-controllable-state'
+import { chartTooltip } from './cartesian'
+import {
+  type ChartColorValue,
+  ChartFrame,
+  type ChartStateProps,
+  categoryColor,
+  defaultFormatter,
+  type Key,
+  toggleIn,
+  useChartAnimation,
+  useChartParts,
+} from './chart-parts'
+
+export interface PieChartProps<T extends object> extends ChartStateProps {
+  data: readonly T[]
+  /** Field naming each slice. */
+  category: Key<T>
+  /** Field holding each slice's value. */
+  value: Key<T>
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  /** One color per slice, in order. Defaults follow the theme palette. */
+  colors?: readonly ChartColorValue[]
+  /** Content in the middle of a donut, e.g. the total. */
+  centerLabel?: ReactNode
+  valueFormatter?: (value: number) => string
+  /** Diameter in pixels. Default 200. */
+  size?: number
+  /** Hole size as a share of the radius, from 0 (pie) to 0.9. Default 0 for PieChart. */
+  innerRadius?: number
+  /** Text drawn next to each slice. Default `none`. */
+  labels?: 'none' | 'percent' | 'value' | 'name'
+  showLegend?: boolean
+  /** Slices hidden through the legend (controlled), by category name. */
+  hiddenSlices?: readonly string[]
+  onHiddenSlicesChange?: (hidden: string[]) => void
+  onSliceClick?: (row: T) => void
+  className?: string
+}
+
+export type DonutChartProps<T extends object> = PieChartProps<T>
+
+type Row = Record<string, unknown>
+
+/** Parts of a whole. Best with five or fewer slices; fold the rest into "Other". */
+export function PieChart<T extends object>(props: PieChartProps<T>) {
+  const {
+    data,
+    category,
+    value,
+    valueFormatter = defaultFormatter,
+    size = 200,
+    innerRadius = 0,
+    labels = 'none',
+  } = props
+  const { s, slots } = useChartParts()
+  const animation = useChartAnimation()
+  const [hidden, setHidden] = useControllableState<readonly string[]>({
+    value: props.hiddenSlices,
+    defaultValue: [],
+    onChange: props.onHiddenSlicesChange as ((value: readonly string[]) => void) | undefined,
+  })
+  const rows = data.map((row) => row as Row)
+  // Color follows the slice, not its position after hiding others.
+  const colored = rows.map((row, i) => ({
+    row,
+    name: String(row[category]),
+    color: categoryColor(props.colors?.[i], i),
+  }))
+  const visible = colored.filter((item) => !hidden.includes(item.name))
+  const total = visible.reduce((sum, item) => sum + (Number(item.row[value]) || 0), 0)
+  const table = {
+    columns: [String(category), String(value)],
+    rows: rows.map((row) => [String(row[category]), valueFormatter(Number(row[value]))]),
+  }
+  const legend =
+    (props.showLegend ?? true)
+      ? colored.map((item) => ({
+          key: item.name,
+          label: item.name,
+          color: item.color,
+          hidden: hidden.includes(item.name),
+        }))
+      : undefined
+  const ring = Math.min(Math.max(innerRadius, 0), 0.9)
+  const labelText = (entry: { value?: number; name?: string; percent?: number }) => {
+    if (labels === 'percent') return `${Math.round((entry.percent ?? 0) * 100)}%`
+    if (labels === 'value') return valueFormatter(Number(entry.value))
+    if (labels === 'name') return String(entry.name ?? '')
+    return ''
+  }
+  const outer = labels === 'none' ? '100%' : '78%'
+  return (
+    <ChartFrame
+      title={props.title}
+      description={props.description}
+      hideTitle={props.hideTitle}
+      className={props.className}
+      legend={legend}
+      onLegendToggle={
+        rows.length > 1 ? (key) => setHidden(toggleIn(hidden, key, rows.length)) : undefined
+      }
+      table={table}
+      height={size}
+      isEmpty={data.length === 0 || total === 0}
+      loading={props.loading}
+      error={props.error}
+      onRetry={props.onRetry}
+      empty={props.empty}
+    >
+      <div
+        className="relative mx-auto"
+        style={{ width: '100%', maxWidth: labels === 'none' ? size : size * 1.6, height: size }}
+      >
+        <R.ResponsiveContainer width="100%" height="100%">
+          <R.PieChart accessibilityLayer={false}>
+            {chartTooltip(valueFormatter, false)}
+            <R.Pie
+              rootTabIndex={-1}
+              data={visible.map((item) => ({ ...item.row, fill: item.color }))}
+              dataKey={value}
+              nameKey={category}
+              innerRadius={`${Math.round(ring * 100)}%`}
+              outerRadius={outer}
+              paddingAngle={ring > 0 ? 2 : 0}
+              cornerRadius={ring > 0 ? 3 : 0}
+              stroke="var(--glyph-surface)"
+              strokeWidth={2}
+              startAngle={90}
+              endAngle={-270}
+              activeShape={(shape: R.PieSectorDataItem) => (
+                <R.Sector {...shape} outerRadius={Number(shape.outerRadius ?? 0) + 5} />
+              )}
+              {...(props.onSliceClick && {
+                onClick: (_: unknown, i: number) => {
+                  const item = visible[i]
+                  if (item) props.onSliceClick?.(item.row as T)
+                },
+                style: { cursor: 'pointer' },
+              })}
+              {...(labels !== 'none' && {
+                label: (entry: { value?: number; name?: string; percent?: number }) =>
+                  labelText(entry),
+                labelLine: { stroke: 'var(--glyph-border-strong)' },
+              })}
+              {...animation}
+            >
+              {visible.map((item) => (
+                <R.Cell key={item.name} fill={item.color} />
+              ))}
+            </R.Pie>
+          </R.PieChart>
+        </R.ResponsiveContainer>
+        {props.centerLabel && ring > 0 && (
+          <div className={s.center({ class: slots.center })}>{props.centerLabel}</div>
+        )}
+      </div>
+    </ChartFrame>
+  )
+}
+
+/** A pie with a hole for a headline number. Same props as PieChart; `innerRadius` defaults to 0.68. */
+export function DonutChart<T extends object>(props: DonutChartProps<T>) {
+  return <PieChart {...props} innerRadius={props.innerRadius ?? 0.68} />
+}