@advui/charts 0.5.0

package/src/components/bar-chart/BarChart.tsx

@@ -0,0 +1,300 @@
+import {
+  CategoryLabels,
+  ChartFrame,
+  type ChartLabels,
+  type ChartSeries,
+  G,
+  Line,
+  Path,
+  Svg,
+  SvgText,
+  ValueGrid,
+  bandScale,
+  barPath,
+  cartesianPadding,
+  formatCompact,
+  formatFull,
+  linearScale,
+  niceTicks,
+  numberAt,
+  useChartColors,
+  useChartInk,
+} from '../../charts'
+
+const MAX_BAR = 24
+const GAP = 2
+const RADIUS = 4
+
+export interface BarChartProps {
+  /** Names the chart: its heading and accessible name. */
+  title: string
+  description?: string
+  /** One object per category, e.g. `{ month: 'Jan', health: 120, wash: 80 }`. */
+  data: Record<string, unknown>[]
+  /** The field holding each row's category name. */
+  index: string
+  /** Heading of the category column in the table view. Default: `index`. */
+  indexLabel?: string
+  /** The numeric fields to plot, in color order. */
+  series: ChartSeries[]
+  /** `vertical` draws columns; `horizontal` bars suit long category names. */
+  layout?: 'vertical' | 'horizontal'
+  /** Stacks the series in one bar per category (part-to-whole). */
+  stacked?: boolean
+  /** Height in pixels. Default: 240, or 36 per category for horizontal bars. */
+  height?: number
+  /** Fixed width; by default the chart fills its container. */
+  width?: number
+  /** Formats values in the tooltip and table. Axis ticks are always compact (1.2K). */
+  valueFormatter?: (value: number) => string
+  labels?: Partial<ChartLabels>
+}
+
+/**
+ * Compares values across categories as columns or bars, grouped or stacked.
+ * Includes a legend, a tooltip (hover, tap or arrow keys) and a table view.
+ */
+export function BarChart({
+  title,
+  description,
+  data,
+  index,
+  indexLabel = index,
+  series,
+  layout = 'vertical',
+  stacked = false,
+  height: heightProp,
+  width,
+  valueFormatter = formatFull,
+  labels,
+}: BarChartProps) {
+  const colors = useChartColors()
+  const ink = useChartInk('$background')
+  const horizontal = layout === 'horizontal'
+  const height = heightProp ?? (horizontal ? Math.max(120, data.length * 36 + 32) : 240)
+  const categories = data.map((row) => String(row[index] ?? ''))
+  const values = data.map((row) => series.map((s) => numberAt(row, s.key)))
+
+  // Stacks sum positives up and negatives down; groups need each value.
+  const extents = values.flatMap((row) =>
+    stacked
+      ? [
+          row.reduce<number>((sum, v) => sum + Math.max(0, v ?? 0), 0),
+          row.reduce<number>((sum, v) => sum + Math.min(0, v ?? 0), 0),
+        ]
+      : row.map((v) => v ?? 0),
+  )
+  const ticks = niceTicks(Math.min(0, ...extents), Math.max(0, ...extents))
+  const domain: [number, number] = [ticks[0]!, ticks.at(-1)!]
+
+  const categoryWidth = horizontal
+    ? Math.min(160, Math.max(...categories.map((c) => c.length), 1) * 7 + 12)
+    : 0
+  const pad = horizontal
+    ? { top: 8, right: 16, bottom: 24, left: categoryWidth }
+    : cartesianPadding(ticks)
+
+  const layoutAt = (w: number) => {
+    const valueScale = horizontal
+      ? linearScale(domain, [pad.left, w - pad.right])
+      : linearScale(domain, [height - pad.bottom, pad.top])
+    const band = horizontal
+      ? bandScale(data.length, [pad.top, height - pad.bottom])
+      : bandScale(data.length, [pad.left, w - pad.right])
+    const k = stacked ? 1 : series.length
+    // Bars never fill their slot: at most 24px, and the rest of the band is air.
+    const thickness = Math.max(2, Math.min(MAX_BAR, (band.bandwidth * 0.7 - GAP * (k - 1)) / k))
+    const group = k * thickness + (k - 1) * GAP
+    return { valueScale, band, thickness, group }
+  }
+
+  const hitTest = (x: number, y: number, w: number) => {
+    const { band } = layoutAt(w)
+    const position = horizontal ? y : x
+    const i = Math.floor((position - (horizontal ? pad.top : pad.left)) / band.bandwidth)
+    return i >= 0 && i < data.length ? i : null
+  }
+
+  const format = (value: number | null) => (value == null ? '–' : valueFormatter(value))
+  const legend =
+    series.length > 1
+      ? series.map((s, i) => ({ label: s.label, color: colors[i % 8]!, shape: 'square' as const }))
+      : []
+
+  return (
+    <ChartFrame
+      title={title}
+      description={description}
+      legend={legend}
+      height={height}
+      width={width}
+      count={data.length}
+      hitTest={hitTest}
+      anchor={(i, w) => {
+        const { band } = layoutAt(w)
+        const center = band.band(i) + band.bandwidth / 2
+        return horizontal ? { x: w - pad.right, y: center } : { x: center, y: pad.top }
+      }}
+      tooltip={(i) => ({
+        title: categories[i]!,
+        rows: series.map((s, j) => ({
+          label: s.label,
+          value: format(values[i]![j]!),
+          color: colors[j % 8]!,
+          shape: 'square',
+        })),
+      })}
+      table={{
+        columns: [indexLabel, ...series.map((s) => s.label)],
+        rows: data.map((_, i) => [categories[i]!, ...values[i]!.map(format)]),
+        numeric: [false, ...series.map(() => true)],
+      }}
+      labels={labels}
+    >
+      {(w, active) => {
+        const { valueScale, band, thickness, group } = layoutAt(w)
+        const zero = valueScale(0)
+        return (
+          <Svg width={w} height={height}>
+            {horizontal ? (
+              <>
+                {ticks.map((tick) => (
+                  <Line
+                    key={`grid-${tick}`}
+                    x1={valueScale(tick)}
+                    x2={valueScale(tick)}
+                    y1={pad.top}
+                    y2={height - pad.bottom}
+                    stroke={tick === 0 ? ink.axis : ink.grid}
+                    strokeWidth={1}
+                  />
+                ))}
+                {ticks.map((tick) => (
+                  <SvgText
+                    key={`tick-${tick}`}
+                    x={valueScale(tick)}
+                    y={height - pad.bottom + 4}
+                    dy="0.9em"
+                    fill={ink.text}
+                    fontSize={12}
+                    textAnchor="middle"
+                  >
+                    {formatCompact(tick)}
+                  </SvgText>
+                ))}
+                {categories.map((category, i) => (
+                  <SvgText
+                    key={`cat-${i}`}
+                    x={pad.left - 8}
+                    y={band.band(i) + band.bandwidth / 2}
+                    dy="0.35em"
+                    fill={ink.text}
+                    fontSize={12}
+                    textAnchor="end"
+                  >
+                    {truncate(category, Math.floor((pad.left - 12) / 7))}
+                  </SvgText>
+                ))}
+              </>
+            ) : (
+              <>
+                <ValueGrid
+                  ticks={ticks}
+                  y={valueScale}
+                  left={pad.left}
+                  right={w - pad.right}
+                  ink={ink}
+                />
+                <CategoryLabels
+                  labels={categories}
+                  x={(i) => band.band(i) + band.bandwidth / 2}
+                  y={height - pad.bottom + 4}
+                  available={band.bandwidth}
+                  ink={ink}
+                />
+              </>
+            )}
+            {values.map((row, i) => {
+              const start = band.band(i) + (band.bandwidth - group) / 2
+              let positive = 0
+              let negative = 0
+              // In a stack, only the outermost segment on each side gets the rounded end.
+              const lastPositive = row.reduce<number>((last, v, j) => ((v ?? 0) > 0 ? j : last), -1)
+              const lastNegative = row.reduce<number>((last, v, j) => ((v ?? 0) < 0 ? j : last), -1)
+              return (
+                <G key={i} opacity={active == null || active === i ? 1 : 0.55}>
+                  {row.map((value, j) => {
+                    if (value == null || value === 0) return null
+                    const offset = stacked ? start : start + j * (thickness + GAP)
+                    const from = stacked ? (value > 0 ? positive : negative) : 0
+                    const to = from + value
+                    if (stacked) {
+                      if (value > 0) positive = to
+                      else negative = to
+                    }
+                    const a = valueScale(from)
+                    const b = valueScale(to)
+                    // A 2px gap separates a stacked segment from the one on its baseline side.
+                    const inset = stacked && from !== 0 ? GAP : 0
+                    const rounded = !stacked || j === (value > 0 ? lastPositive : lastNegative)
+                    const radius = rounded ? RADIUS : 0
+                    const d = horizontal
+                      ? value > 0
+                        ? barPath(
+                            Math.min(a, b) + inset,
+                            offset,
+                            Math.abs(b - a) - inset,
+                            thickness,
+                            radius,
+                            'right',
+                          )
+                        : barPath(
+                            Math.min(a, b),
+                            offset,
+                            Math.abs(b - a) - inset,
+                            thickness,
+                            radius,
+                            'left',
+                          )
+                      : value > 0
+                        ? barPath(
+                            offset,
+                            Math.min(a, b),
+                            thickness,
+                            Math.abs(b - a) - inset,
+                            radius,
+                            'up',
+                          )
+                        : barPath(
+                            offset,
+                            Math.min(a, b) + inset,
+                            thickness,
+                            Math.abs(b - a) - inset,
+                            radius,
+                            'down',
+                          )
+                    return <Path key={j} d={d} fill={colors[j % 8]} />
+                  })}
+                </G>
+              )
+            })}
+            {horizontal ? null : (
+              <Line
+                x1={pad.left}
+                x2={w - pad.right}
+                y1={zero}
+                y2={zero}
+                stroke={ink.axis}
+                strokeWidth={1}
+              />
+            )}
+          </Svg>
+        )
+      }}
+    </ChartFrame>
+  )
+}
+
+function truncate(text: string, max: number) {
+  return text.length > max ? `${text.slice(0, Math.max(1, max - 1))}…` : text
+}

package/src/components/bar-chart/index.ts

@@ -0,0 +1 @@
+export { BarChart, type BarChartProps } from './BarChart'

package/src/components/line-chart/LineChart.tsx

@@ -0,0 +1,11 @@
+import { LinePlot, type LinePlotProps } from '../../charts'
+
+export type LineChartProps = LinePlotProps
+
+/**
+ * Shows change over an ordered axis (months, years) as 2px lines, with a
+ * crosshair tooltip (hover, tap or arrow keys), a legend and a table view.
+ */
+export function LineChart(props: LineChartProps) {
+  return <LinePlot {...props} />
+}

package/src/components/line-chart/index.ts

@@ -0,0 +1 @@
+export { LineChart, type LineChartProps } from './LineChart'

package/src/components/pie-chart/PieChart.tsx

@@ -0,0 +1,192 @@
+import { useIconColor } from '@advui/icons'
+import {
+  ChartFrame,
+  type ChartLabels,
+  G,
+  Path,
+  Svg,
+  SvgText,
+  arcPath,
+  formatFull,
+  useChartColors,
+  useChartInk,
+} from '../../charts'
+
+export interface PieSlice {
+  label: string
+  value: number
+}
+
+export interface PieChartProps {
+  /** Names the chart: its heading and accessible name. */
+  title: string
+  description?: string
+  /** The parts of the whole. Negative and zero values are left out. */
+  data: PieSlice[]
+  /** `donut` leaves room for the total in the middle. */
+  variant?: 'donut' | 'pie'
+  /** More slices than this fold the smallest into "Other". Default: 6. */
+  maxSlices?: number
+  /** Height in pixels. Default: 240. */
+  height?: number
+  width?: number
+  /** Formats values in the legend, tooltip and table. */
+  valueFormatter?: (value: number) => string
+  /** Headings for the table and the folded slice, for translation. */
+  text?: { label?: string; value?: string; share?: string; other?: string; total?: string }
+  labels?: Partial<ChartLabels>
+}
+
+const percent = (part: number, total: number) =>
+  total > 0 ? `${Math.round((part / total) * 1000) / 10}%` : '0%'
+
+/**
+ * Part-to-whole at a glance, for up to six parts. Each slice is named in the
+ * legend with its share; the tooltip (hover, tap or arrow keys) and the
+ * table view give the exact values. For close values, a bar chart reads better.
+ */
+export function PieChart({
+  title,
+  description,
+  data,
+  variant = 'donut',
+  maxSlices = 6,
+  height = 240,
+  width,
+  valueFormatter = formatFull,
+  text: textProp,
+  labels,
+}: PieChartProps) {
+  const text = {
+    label: 'Label',
+    value: 'Value',
+    share: 'Share',
+    other: 'Other',
+    total: 'Total',
+    ...textProp,
+  }
+  const colors = useChartColors()
+  const ink = useChartInk('$background')
+  const foreground = useIconColor('$foreground') ?? 'currentColor'
+
+  // Largest first; past the limit, the tail folds into one "Other" slice.
+  const positive = data.filter((d) => d.value > 0).sort((a, b) => b.value - a.value)
+  const slices =
+    positive.length > maxSlices
+      ? [
+          ...positive.slice(0, maxSlices - 1),
+          {
+            label: text.other,
+            value: positive.slice(maxSlices - 1).reduce((sum, d) => sum + d.value, 0),
+          },
+        ]
+      : positive
+  const folded = positive.length > maxSlices
+  const total = slices.reduce((sum, d) => sum + d.value, 0)
+  const colorOf = (i: number) => (folded && i === slices.length - 1 ? ink.axis : colors[i % 8]!)
+
+  let angle = 0
+  const arcs = slices.map((slice, i) => {
+    const start = angle
+    angle += total > 0 ? (slice.value / total) * Math.PI * 2 : 0
+    return { ...slice, start, end: angle, color: colorOf(i) }
+  })
+
+  const geometry = (w: number) => {
+    const outer = Math.min(w, height) / 2 - 8
+    return { cx: w / 2, cy: height / 2, outer, inner: variant === 'donut' ? outer * 0.62 : 0 }
+  }
+
+  return (
+    <ChartFrame
+      title={title}
+      description={description}
+      legend={arcs.map((arc) => ({
+        label: arc.label,
+        color: arc.color,
+        shape: 'square',
+        detail: percent(arc.value, total),
+      }))}
+      height={height}
+      width={width}
+      count={arcs.length}
+      hitTest={(x, y, w) => {
+        const { cx, cy, outer, inner } = geometry(w)
+        const dx = x - cx
+        const dy = y - cy
+        const r = Math.hypot(dx, dy)
+        if (r > outer + 8 || r < inner) return null
+        const a = (Math.atan2(dx, -dy) + Math.PI * 2) % (Math.PI * 2)
+        const found = arcs.findIndex((arc) => a >= arc.start && a < arc.end)
+        return found >= 0 ? found : null
+      }}
+      anchor={(i, w) => {
+        const { cx, outer } = geometry(w)
+        const mid = (arcs[i]!.start + arcs[i]!.end) / 2
+        return { x: cx + outer * Math.sin(mid), y: 0 }
+      }}
+      tooltip={(i) => ({
+        title: arcs[i]!.label,
+        rows: [
+          {
+            label: percent(arcs[i]!.value, total),
+            value: valueFormatter(arcs[i]!.value),
+            color: arcs[i]!.color,
+            shape: 'square',
+          },
+        ],
+      })}
+      table={{
+        columns: [text.label, text.value, text.share],
+        rows: [
+          ...arcs.map((arc) => [arc.label, valueFormatter(arc.value), percent(arc.value, total)]),
+          [text.total, valueFormatter(total), '100%'],
+        ],
+        numeric: [false, true, true],
+      }}
+      labels={labels}
+    >
+      {(w, active) => {
+        const { cx, cy, outer, inner } = geometry(w)
+        // A 2px gap between slices, as angle at the outer edge.
+        const gap = arcs.length > 1 ? 2 / outer : 0
+        return (
+          <Svg width={w} height={height}>
+            {arcs.map((arc, i) => (
+              <G key={arc.label} opacity={active == null || active === i ? 1 : 0.55}>
+                <Path
+                  d={arcPath(
+                    cx,
+                    cy,
+                    active === i ? outer + 4 : outer,
+                    inner,
+                    arc.start + gap / 2,
+                    Math.max(arc.start + gap / 2, arc.end - gap / 2),
+                  )}
+                  fill={arc.color}
+                />
+              </G>
+            ))}
+            {variant === 'donut' ? (
+              <>
+                <SvgText
+                  x={cx}
+                  y={cy - 6}
+                  fill={foreground}
+                  fontSize={20}
+                  fontWeight="600"
+                  textAnchor="middle"
+                >
+                  {valueFormatter(total)}
+                </SvgText>
+                <SvgText x={cx} y={cy + 16} fill={ink.text} fontSize={12} textAnchor="middle">
+                  {text.total}
+                </SvgText>
+              </>
+            ) : null}
+          </Svg>
+        )
+      }}
+    </ChartFrame>
+  )
+}

package/src/components/pie-chart/index.ts

@@ -0,0 +1 @@
+export { PieChart, type PieChartProps, type PieSlice } from './PieChart'

package/src/index.ts

@@ -0,0 +1,6 @@
+// Chart components. The shared internals in ./charts (frame, legend, tooltip,
+// table view, scales and the SVG layer) are not part of the public API.
+export * from './components/area-chart'
+export * from './components/bar-chart'
+export * from './components/line-chart'
+export * from './components/pie-chart'