@advui/charts 0.5.0

package/src/charts/LinePlot.tsx

@@ -0,0 +1,216 @@
+import { CategoryLabels, ValueGrid, cartesianPadding } from './cartesian'
+import {
+  ChartFrame,
+  type ChartLabels,
+  type ChartSeries,
+  useChartColors,
+  useChartInk,
+} from './ChartFrame'
+import { formatFull, numberAt } from './format'
+import { linearScale, niceTicks } from './scale'
+import { Circle, G, Line, Path, Svg } from './svg'
+
+export interface LinePlotProps {
+  title: string
+  description?: string
+  /** One object per x position, e.g. `{ month: 'Jan', reached: 1200 }`. */
+  data: Record<string, unknown>[]
+  /** The field holding each row's x label. */
+  index: string
+  /** Heading of the x column in the table view. Default: `index`. */
+  indexLabel?: string
+  /** The numeric fields to plot, in color order. */
+  series: ChartSeries[]
+  /** Height in pixels, including the axes. Default: 240. */
+  height?: number
+  width?: number
+  /** Formats values in the tooltip and table. Axis ticks are compact (1.2K). */
+  valueFormatter?: (value: number) => string
+  /** Plot area always starts at zero. Default: true for areas, false for lines. */
+  startAtZero?: boolean
+  /**
+   * Color of the surface the chart sits on, for the ring around markers.
+   * Default: `$background`; use `$card` inside a Card.
+   */
+  surface?: string
+  labels?: Partial<ChartLabels>
+}
+
+/** Shared by LineChart and AreaChart. */
+export function LinePlot({
+  title,
+  description,
+  data,
+  index,
+  indexLabel = index,
+  series,
+  height = 240,
+  width,
+  valueFormatter = formatFull,
+  startAtZero,
+  surface = '$background',
+  labels,
+  area = false,
+  stacked = false,
+}: LinePlotProps & { area?: boolean; stacked?: boolean }) {
+  const colors = useChartColors()
+  const ink = useChartInk(surface)
+  const categories = data.map((row) => String(row[index] ?? ''))
+  const values = data.map((row) => series.map((s) => numberAt(row, s.key)))
+
+  // Stacked areas draw each series on top of the ones before it.
+  const tops = values.map((row) => {
+    let sum = 0
+    return row.map((v) => (v == null ? null : stacked ? (sum += v) : v))
+  })
+  const all = tops.flat().filter((v): v is number => v != null)
+  const zero = startAtZero ?? area
+  const ticks = niceTicks(
+    zero ? Math.min(0, ...all) : Math.min(...all),
+    zero ? Math.max(0, ...all) : Math.max(...all),
+  )
+  const pad = cartesianPadding(ticks)
+  const n = data.length
+
+  const scales = (w: number) => {
+    const step = (w - pad.left - pad.right) / Math.max(1, n)
+    return {
+      step,
+      x: (i: number) => pad.left + (i + 0.5) * step,
+      y: linearScale([ticks[0]!, ticks.at(-1)!], [height - pad.bottom, pad.top]),
+    }
+  }
+
+  const format = (value: number | null) => (value == null ? '–' : valueFormatter(value))
+  const shape = area ? ('square' as const) : ('line' as const)
+
+  return (
+    <ChartFrame
+      title={title}
+      description={description}
+      legend={
+        series.length > 1
+          ? series.map((s, i) => ({ label: s.label, color: colors[i % 8]!, shape }))
+          : []
+      }
+      height={height}
+      width={width}
+      count={n}
+      hitTest={(x, _y, w) => {
+        const { step } = scales(w)
+        const i = Math.round((x - pad.left) / step - 0.5)
+        return Math.max(0, Math.min(n - 1, i))
+      }}
+      anchor={(i, w) => ({ x: scales(w).x(i), 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,
+        })),
+      })}
+      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 { x, y, step } = scales(w)
+        const base = (i: number, j: number) =>
+          stacked && j > 0 ? (tops[i]![j - 1] ?? 0) : Math.max(ticks[0]!, 0)
+        return (
+          <Svg width={w} height={height}>
+            <ValueGrid ticks={ticks} y={y} left={pad.left} right={w - pad.right} ink={ink} />
+            <CategoryLabels
+              labels={categories}
+              x={x}
+              y={height - pad.bottom + 4}
+              available={step}
+              ink={ink}
+            />
+            {active != null ? (
+              <Line
+                x1={x(active)}
+                x2={x(active)}
+                y1={pad.top}
+                y2={height - pad.bottom}
+                stroke={ink.axis}
+                strokeWidth={1}
+              />
+            ) : null}
+            {series.map((s, j) => {
+              const color = colors[j % 8]!
+              // A missing value breaks the line instead of dropping to zero.
+              const runs: number[][] = [[]]
+              tops.forEach((row, i) => {
+                if (row[j] == null) runs.push([])
+                else runs.at(-1)!.push(i)
+              })
+              return (
+                <G key={s.key}>
+                  {runs
+                    .filter((run) => run.length > 0)
+                    .map((run) => {
+                      const line = run
+                        .map((i, k) => `${k === 0 ? 'M' : 'L'}${x(i)},${y(tops[i]![j]!)}`)
+                        .join('')
+                      const fill = area
+                        ? `${line}${[...run]
+                            .reverse()
+                            .map((i) => `L${x(i)},${y(base(i, j))}`)
+                            .join('')}Z`
+                        : null
+                      // A lone value between gaps has no line to draw: show it as a dot.
+                      if (run.length === 1) {
+                        const i = run[0]!
+                        return <Circle key={i} cx={x(i)} cy={y(tops[i]![j]!)} r={3} fill={color} />
+                      }
+                      return (
+                        <G key={run[0]}>
+                          {fill ? <Path d={fill} fill={color} fillOpacity={0.1} /> : null}
+                          <Path
+                            d={line}
+                            fill="none"
+                            stroke={color}
+                            strokeWidth={2}
+                            strokeLinejoin="round"
+                            strokeLinecap="round"
+                          />
+                        </G>
+                      )
+                    })}
+                </G>
+              )
+            })}
+            {/* End markers, and every series' marker at the hovered position, ringed in the surface color. */}
+            {series.map((s, j) => {
+              const color = colors[j % 8]!
+              const lastIndex = tops.reduce<number>(
+                (last, row, i) => (row[j] != null ? i : last),
+                -1,
+              )
+              const points = new Set([lastIndex, ...(active != null ? [active] : [])])
+              return [...points]
+                .filter((i) => i >= 0 && tops[i]?.[j] != null)
+                .map((i) => (
+                  <Circle
+                    key={`${s.key}-${i}`}
+                    cx={x(i)}
+                    cy={y(tops[i]![j]!)}
+                    r={4}
+                    fill={color}
+                    stroke={ink.surface}
+                    strokeWidth={2}
+                  />
+                ))
+            })}
+          </Svg>
+        )
+      }}
+    </ChartFrame>
+  )
+}

package/src/charts/cartesian.tsx

@@ -0,0 +1,99 @@
+import { Line, SvgText } from './svg'
+import { formatCompact } from './format'
+
+/** Space around the plot for axis labels. */
+export function cartesianPadding(
+  ticks: number[],
+  format: (value: number) => string = formatCompact,
+) {
+  // About 7px per character of the widest tick label at 12px.
+  const labelWidth = Math.max(...ticks.map((t) => format(t).length)) * 7
+  return { top: 8, right: 8, bottom: 24, left: labelWidth + 12 }
+}
+
+/** Horizontal gridlines with value labels on the left. */
+export function ValueGrid({
+  ticks,
+  y,
+  left,
+  right,
+  ink,
+  format = formatCompact,
+}: {
+  ticks: number[]
+  y: (value: number) => number
+  left: number
+  right: number
+  ink: { text: string; grid: string; axis: string }
+  format?: (value: number) => string
+}) {
+  return (
+    <>
+      {ticks.map((tick) => (
+        <Line
+          key={`grid-${tick}`}
+          x1={left}
+          x2={right}
+          y1={y(tick)}
+          y2={y(tick)}
+          stroke={tick === 0 ? ink.axis : ink.grid}
+          strokeWidth={1}
+        />
+      ))}
+      {ticks.map((tick) => (
+        <SvgText
+          key={`label-${tick}`}
+          x={left - 8}
+          y={y(tick)}
+          dy="0.35em"
+          fill={ink.text}
+          fontSize={12}
+          textAnchor="end"
+        >
+          {format(tick)}
+        </SvgText>
+      ))}
+    </>
+  )
+}
+
+/**
+ * Category labels under the plot. When they would overlap, only every nth
+ * is drawn (the first and the rest in steps), so none collide.
+ */
+export function CategoryLabels({
+  labels,
+  x,
+  y,
+  available,
+  ink,
+}: {
+  labels: string[]
+  x: (index: number) => number
+  y: number
+  /** Width each label may use before thinning kicks in. */
+  available: number
+  ink: { text: string }
+}) {
+  const widest = Math.max(1, ...labels.map((l) => l.length)) * 7 + 8
+  const step = Math.max(1, Math.ceil(widest / Math.max(1, available)))
+  return (
+    <>
+      {labels.map((label, index) =>
+        index % step === 0 ? (
+          <SvgText
+            key={`${label}-${index}`}
+            x={x(index)}
+            y={y}
+            dy="0.9em"
+            fill={ink.text}
+            fontSize={12}
+            textAnchor="middle"
+          >
+            {label}
+          </SvgText>
+        ) : null,
+      )}
+    </>
+  )
+}

package/src/charts/format.ts

@@ -0,0 +1,14 @@
+const compact = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 })
+const full = new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 })
+
+/** Axis ticks: 1.2K, 3.4M. */
+export const formatCompact = (value: number) => compact.format(value)
+
+/** Tooltips and the table: 1,234.5. */
+export const formatFull = (value: number) => full.format(value)
+
+/** Reads a numeric field; anything else counts as missing. */
+export function numberAt(row: Record<string, unknown>, key: string): number | null {
+  const value = row[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}

package/src/charts/index.ts

@@ -0,0 +1,16 @@
+export {
+  ChartFrame,
+  defaultChartLabels,
+  useChartColors,
+  useChartInk,
+  type ChartFrameProps,
+  type ChartLabels,
+  type ChartSeries,
+  type LegendItem,
+  type TooltipContent,
+} from './ChartFrame'
+export { CategoryLabels, ValueGrid, cartesianPadding } from './cartesian'
+export { LinePlot, type LinePlotProps } from './LinePlot'
+export { formatCompact, formatFull, numberAt } from './format'
+export { arcPath, bandScale, barPath, linearScale, niceTicks } from './scale'
+export { Circle, G, Line, Path, Rect, Svg, SvgText } from './svg'

package/src/charts/scale.ts

@@ -0,0 +1,91 @@
+/** Clean, round tick values ("nice numbers") covering [min, max]. */
+export function niceTicks(min: number, max: number, count = 5): number[] {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return [0]
+  if (min === max) {
+    if (min === 0) return [0, 1]
+    ;[min, max] = min > 0 ? [0, min] : [min, 0]
+  }
+  const step = niceStep((max - min) / Math.max(1, count - 1))
+  const start = Math.floor(min / step) * step
+  const end = Math.ceil(max / step) * step
+  const ticks: number[] = []
+  // Rounding keeps 0.1 + 0.2 style float noise out of the labels.
+  for (let v = start; v <= end + step / 2; v += step) ticks.push(Number(v.toPrecision(12)))
+  return ticks
+}
+
+function niceStep(raw: number): number {
+  const power = 10 ** Math.floor(Math.log10(raw))
+  const fraction = raw / power
+  const nice =
+    fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10
+  return nice * power
+}
+
+/** Maps a value in [d0, d1] to [r0, r1]. */
+export function linearScale([d0, d1]: [number, number], [r0, r1]: [number, number]) {
+  const span = d1 - d0 || 1
+  return (value: number) => r0 + ((value - d0) / span) * (r1 - r0)
+}
+
+/**
+ * Splits [start, end] into `count` equal bands; `band(i)` is the start of
+ * band i and `bandwidth` its size.
+ */
+export function bandScale(count: number, [start, end]: [number, number]) {
+  const bandwidth = (end - start) / Math.max(1, count)
+  return { band: (index: number) => start + index * bandwidth, bandwidth }
+}
+
+/**
+ * A rectangle with rounded corners on its data end only (the end away from
+ * the baseline), as an SVG path. `direction` is where the data end points.
+ */
+export function barPath(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radius: number,
+  direction: 'up' | 'down' | 'right' | 'left',
+): string {
+  if (width <= 0 || height <= 0) return ''
+  const r = Math.max(0, Math.min(radius, width / 2, height / 2))
+  const x2 = x + width
+  const y2 = y + height
+  switch (direction) {
+    case 'up':
+      return `M${x},${y2}V${y + r}Q${x},${y} ${x + r},${y}H${x2 - r}Q${x2},${y} ${x2},${y + r}V${y2}Z`
+    case 'down':
+      return `M${x},${y}V${y2 - r}Q${x},${y2} ${x + r},${y2}H${x2 - r}Q${x2},${y2} ${x2},${y2 - r}V${y}Z`
+    case 'right':
+      return `M${x},${y}H${x2 - r}Q${x2},${y} ${x2},${y + r}V${y2 - r}Q${x2},${y2} ${x2 - r},${y2}H${x}Z`
+    case 'left':
+      return `M${x2},${y}H${x + r}Q${x},${y} ${x},${y + r}V${y2 - r}Q${x},${y2} ${x + r},${y2}H${x2}Z`
+  }
+}
+
+/** A pie or donut slice as an SVG path; angles in radians, 0 at 12 o'clock. */
+export function arcPath(
+  cx: number,
+  cy: number,
+  outer: number,
+  inner: number,
+  start: number,
+  end: number,
+): string {
+  const point = (radius: number, angle: number) =>
+    `${cx + radius * Math.sin(angle)},${cy - radius * Math.cos(angle)}`
+  const large = end - start > Math.PI ? 1 : 0
+  // A full circle cannot be one arc: split it in two.
+  if (end - start >= Math.PI * 2 - 1e-6) {
+    const mid = start + Math.PI
+    return inner > 0
+      ? `M${point(outer, start)}A${outer},${outer} 0 1 1 ${point(outer, mid)}A${outer},${outer} 0 1 1 ${point(outer, start)}` +
+          `M${point(inner, start)}A${inner},${inner} 0 1 0 ${point(inner, mid)}A${inner},${inner} 0 1 0 ${point(inner, start)}Z`
+      : `M${point(outer, start)}A${outer},${outer} 0 1 1 ${point(outer, mid)}A${outer},${outer} 0 1 1 ${point(outer, start)}Z`
+  }
+  return inner > 0
+    ? `M${point(outer, start)}A${outer},${outer} 0 ${large} 1 ${point(outer, end)}L${point(inner, end)}A${inner},${inner} 0 ${large} 0 ${point(inner, start)}Z`
+    : `M${cx},${cy}L${point(outer, start)}A${outer},${outer} 0 ${large} 1 ${point(outer, end)}Z`
+}

package/src/charts/svg.native.tsx

@@ -0,0 +1,62 @@
+import type { ReactNode } from 'react'
+import NativeSvg, {
+  Circle as NativeCircle,
+  G as NativeG,
+  Line as NativeLine,
+  Path as NativePath,
+  Rect as NativeRect,
+  Text as NativeText,
+} from 'react-native-svg'
+
+// Native: the web file's components, mapped onto react-native-svg.
+
+type Common = { children?: ReactNode; opacity?: number }
+type Paint = { fill?: string; fillOpacity?: number; stroke?: string; strokeWidth?: number }
+
+export function Svg({ width, height, children }: Common & { width: number; height: number }) {
+  return (
+    <NativeSvg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      accessible={false}
+      importantForAccessibility="no-hide-descendants"
+    >
+      {children}
+    </NativeSvg>
+  )
+}
+
+export const G = ({ children, opacity }: Common) => <NativeG opacity={opacity}>{children}</NativeG>
+
+export const Rect = (props: Paint & { x: number; y: number; width: number; height: number }) => (
+  <NativeRect {...props} />
+)
+
+export const Path = (
+  props: Paint & { d: string; strokeLinejoin?: 'round'; strokeLinecap?: 'round' },
+) => <NativePath {...props} />
+
+export const Line = (props: Paint & { x1: number; y1: number; x2: number; y2: number }) => (
+  <NativeLine {...props} />
+)
+
+export const Circle = (props: Paint & { cx: number; cy: number; r: number }) => (
+  <NativeCircle {...props} />
+)
+
+export function SvgText({
+  children,
+  ...props
+}: {
+  children: ReactNode
+  x: number
+  y: number
+  fill: string
+  fontSize: number
+  fontWeight?: string
+  textAnchor?: 'start' | 'middle' | 'end'
+  dy?: string
+}) {
+  return <NativeText {...(props as object)}>{children}</NativeText>
+}

package/src/charts/svg.tsx

@@ -0,0 +1,57 @@
+import type { ReactNode } from 'react'
+
+// Web: plain DOM SVG, so web bundles do not need react-native-svg. The
+// native file maps the same components onto react-native-svg.
+
+type Common = { children?: ReactNode; opacity?: number }
+type Paint = { fill?: string; fillOpacity?: number; stroke?: string; strokeWidth?: number }
+
+export function Svg({ width, height, children }: Common & { width: number; height: number }) {
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      style={{ display: 'block', overflow: 'visible', fontFamily: 'inherit' }}
+      aria-hidden
+      focusable="false"
+    >
+      {children}
+    </svg>
+  )
+}
+
+export const G = ({ children, opacity }: Common) => <g opacity={opacity}>{children}</g>
+
+export const Rect = (props: Paint & { x: number; y: number; width: number; height: number }) => (
+  <rect {...props} />
+)
+
+export const Path = (
+  props: Paint & { d: string; strokeLinejoin?: 'round'; strokeLinecap?: 'round' },
+) => <path {...props} />
+
+export const Line = (props: Paint & { x1: number; y1: number; x2: number; y2: number }) => (
+  <line {...props} />
+)
+
+export const Circle = (props: Paint & { cx: number; cy: number; r: number }) => (
+  <circle {...props} />
+)
+
+export function SvgText({
+  children,
+  ...props
+}: {
+  children: ReactNode
+  x: number
+  y: number
+  fill: string
+  fontSize: number
+  fontWeight?: string
+  textAnchor?: 'start' | 'middle' | 'end'
+  /** Vertical nudge: 0.35em centers text on y. */
+  dy?: string
+}) {
+  return <text {...props}>{children}</text>
+}

package/src/components/area-chart/AreaChart.tsx

@@ -0,0 +1,14 @@
+import { LinePlot, type LinePlotProps } from '../../charts'
+
+export interface AreaChartProps extends LinePlotProps {
+  /** Stacks the series, so the top edge is their total (part-to-whole over time). */
+  stacked?: boolean
+}
+
+/**
+ * A line chart with a light wash under each line, from zero. Best for one
+ * series, or for stacked totals over time.
+ */
+export function AreaChart({ stacked = false, ...props }: AreaChartProps) {
+  return <LinePlot {...props} area stacked={stacked} />
+}

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

@@ -0,0 +1 @@
+export { AreaChart, type AreaChartProps } from './AreaChart'