basalt-ui 1.41.0 → 2.0.1

package/src/charts/DualPanel.tsx

@@ -0,0 +1,326 @@
+/**
+ * `DualPanel` — a top line pane over a bottom signed-bar pane, ONE chart (`docs/V2-SPEC.md` § 9.2,
+ * § 9.3), composed by `panel.tsx`: one host, one cursor, one tooltip, one legend. The top pane may
+ * shade the band between two of its lines (`differenceY`); the bottom pane draws a signed value as
+ * bars around zero. Each pane resolves its own y domain; x is a Date or number, shared by both.
+ */
+import { differenceY } from '@tanstack/charts/difference'
+import { decorative } from '@tanstack/charts/mark/decorative'
+import { ruleY } from '@tanstack/charts/rule'
+import { scaleLinear } from '@tanstack/charts/scales/linear'
+import type { ChartTooltipRow as EngineTooltipRow, ChartValue } from '@tanstack/charts/types/core'
+import { scaleUtc } from 'd3-scale'
+import { useCallback, useMemo } from 'react'
+import type { ReactElement } from 'react'
+import { VX, alpha } from '../tokens'
+import { resolveContainerClass } from '../tokens/size-classes'
+import { defaultFormatX, defaultNumberFormat, visibleSeries } from './compile'
+import { barMark, emphasis, lineMark, markersOf, thinFill } from './marks'
+import { PanelRung, paneX, paneY, rowsOf } from './panel'
+import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
+import { xScaleFor } from './scales'
+import { rowX } from './types'
+import type { CartesianChartProps, ChartSeries, PlotContext, PlotRow } from './types'
+
+// ── DualPanel ───────────────────────────────────────────────────────────────────────────────────
+
+/** The bar's legend/toggle key. Reserved: a line may not use it. */
+const BAR_KEY = '__bar'
+const DEFAULT_TOP_FRACTION = 0.62
+/** Space between the panes in px. */
+const PANE_GAP = 8
+const BAR_OPACITY = 0.7
+const TOP_PAD = 0.08
+const TOP_TICKS = 4
+const BAR_TICKS = 3
+
+/** A top-pane line. */
+export type DualPanelLine<T> = Pick<
+  ChartSeries<T>,
+  | 'key'
+  | 'label'
+  | 'color'
+  | 'getValue'
+  | 'formatValue'
+  | 'tooltip'
+  | 'legend'
+  | 'role'
+  | 'note'
+  | 'dash'
+  | 'curve'
+  | 'strokeWidth'
+  | 'strokeOpacity'
+  | 'getMarker'
+>
+
+/** The bottom pane: one signed value as bars, coloured by sign. */
+export type DualPanelBar<T> = {
+  label: string
+  getValue: (d: T) => number | null
+  /** The fill above zero, and the legend swatch. */
+  positive: string
+  /** The fill below zero. */
+  negative: string
+  /** Tick and tooltip formatter. */
+  format: (v: number) => string
+  /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
+  formatValue?: (v: number, d: T) => string
+  /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
+   * is used verbatim. */
+  domain?: readonly [number, number] | 'auto'
+  /** When `'auto'`: floors `maxAbs`, so a plateau does not amplify to fill the pane. */
+  maxAbsFloor?: number
+}
+
+export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
+  CartesianChartProps<T, X>,
+  | 'ariaLabel'
+  | 'data'
+  | 'x'
+  | 'formatX'
+  | 'legend'
+  | 'height'
+  | 'state'
+  | 'cursorGroup'
+  | 'cursorResolution'
+  | 'tooltip'
+  | 'className'
+  | 'style'
+> & {
+  /** The top pane's lines. */
+  series: readonly DualPanelLine<T>[]
+  /** Top pane y axis. Default domain `'auto'`: the visible lines' span plus 8%, rounded to nice
+   * ticks (not zero-based: the interesting range is often a narrow band far from zero). */
+  top?: { domain?: readonly [number, number] | 'auto'; format?: (v: number) => string }
+  /**
+   * Shades the band between two top lines (by key), where both are visible. `aboveFill` colours the
+   * side where `to` runs above `from`; omitted, both sides take `fill`.
+   */
+  fillBetween?: { from: string; to: string; fill: string; aboveFill?: string }
+  bar: DualPanelBar<T>
+  /** The top pane's share of the chart height. Default 0.62. */
+  topFraction?: number
+}
+
+type FillRow<T, X> = { x: X; from: number; to: number; series: string; datum: T }
+
+/** A padded span, or the unit interval for no data. */
+function spanDomain(values: readonly number[]): [number, number] {
+  if (values.length === 0) return [0, 1]
+  let lo = Infinity
+  let hi = -Infinity
+  for (const v of values) {
+    if (v < lo) lo = v
+    if (v > hi) hi = v
+  }
+  const span = hi - lo || Math.abs(hi) || 1
+  return [lo - span * TOP_PAD, hi + span * TOP_PAD]
+}
+
+export function DualPanel<T, X extends Date | number = Date | number>(
+  props: DualPanelProps<T, X>,
+): ReactElement {
+  const {
+    data,
+    x,
+    series,
+    top,
+    fillBetween,
+    bar,
+    topFraction = DEFAULT_TOP_FRACTION,
+    ...rung
+  } = props
+  const { formatX } = rung
+
+  if (series.some((s) => s.key === BAR_KEY))
+    throw new Error(`[basalt] DualPanel: the series key "${BAR_KEY}" is reserved for the bar`)
+  const lines = useMemo<ChartSeries<T>[]>(
+    () => series.map((s) => ({ ...s, mark: 'line' as const })),
+    [series],
+  )
+  const barSeries = useMemo<ChartSeries<T>>(
+    () => ({
+      key: BAR_KEY,
+      label: bar.label,
+      color: bar.positive,
+      mark: 'bar',
+      getValue: bar.getValue,
+    }),
+    [bar.label, bar.positive, bar.getValue],
+  )
+  const all = useMemo(() => [...lines, barSeries], [lines, barSeries])
+  const topFormat = top?.format ?? defaultNumberFormat
+
+  const plan = useCallback(
+    ({ hidden, highlighted }: PanelInput): PanelPlan<T> => {
+      const model = xScaleFor<Date | number>(data.map(x), false)
+      const [lo, hi] = model.extent ?? [0, 1]
+      // Half a sample step each side: the first and last bar are whole, and a line point sits where
+      // the bar of its sample is centred.
+      const pad = model.step / 2
+      // One instance per pane: the engine sets a scale's range, and the panes' plots differ in width.
+      const xScale = () =>
+        model.kind === 'date'
+          ? scaleUtc().domain([new Date(lo - pad), new Date(hi + pad)])
+          : scaleLinear().domain([lo - pad, hi + pad])
+      // A row's x as a fraction of the plot (the domain is padded half a step each side).
+      const fillAt = (v: Date | number): number =>
+        ((v instanceof Date ? v.getTime() : v) - (lo - pad)) / (hi - lo + 2 * pad)
+      const format = (v: ChartValue): string => (formatX ? formatX(v as X) : defaultFormatX(v))
+
+      const visible = visibleSeries(lines, hidden)
+      const barOn = !hidden.has(BAR_KEY)
+      const rows = (s: ChartSeries<T>) => (visible.includes(s) ? rowsOf(data, x, s) : [])
+
+      const fixedTop = top?.domain && top.domain !== 'auto' ? top.domain : undefined
+      const topDomain: readonly [number, number] =
+        fixedTop ??
+        spanDomain(
+          visible.flatMap((s) =>
+            data.flatMap((d) => {
+              const v = s.getValue(d)
+              return v !== null && Number.isFinite(v) ? [v] : []
+            }),
+          ),
+        )
+      const topY = scaleLinear().domain([...topDomain])
+      if (!fixedTop) topY.nice()
+
+      let maxAbs = 0
+      for (const d of data) {
+        const v = bar.getValue(d)
+        if (v !== null && Number.isFinite(v)) maxAbs = Math.max(maxAbs, Math.abs(v))
+      }
+      maxAbs = Math.max(maxAbs, bar.maxAbsFloor ?? 0) || 1
+      const fixedBar = bar.domain && bar.domain !== 'auto' ? bar.domain : undefined
+      const barScale = scaleLinear().domain(fixedBar ? [...fixedBar] : [-maxAbs, maxAbs])
+      if (!fixedBar) barScale.nice()
+      const barDomain = fixedBar ?? ([...barScale.domain()] as [number, number])
+
+      const fromLine = fillBetween && visible.find((s) => s.key === fillBetween.from)
+      const toLine = fillBetween && visible.find((s) => s.key === fillBetween.to)
+      // The fill needs both lines visible: hiding either drops it.
+      const fill =
+        fillBetween && fromLine && toLine ? { ...fillBetween, fromLine, toLine } : undefined
+      const fillRows: FillRow<T, Date | number>[] = []
+      if (fill) {
+        for (const d of data) {
+          const a = fill.fromLine.getValue(d)
+          const b = fill.toLine.getValue(d)
+          if (a === null || b === null || !Number.isFinite(a) || !Number.isFinite(b)) continue
+          // Owned by the `to` line, so a hovered fill point resolves to its datum.
+          fillRows.push({ x: x(d), from: a, to: b, series: fill.to, datum: d })
+        }
+      }
+
+      const topPane: PaneBuilder = ({ width, height: h }) => {
+        const cls = resolveContainerClass(width)
+        const plot: PlotContext<T, Date | number> = {
+          rows: (key) => {
+            const s = lines.find((l) => l.key === key)
+            if (!s) throw new Error(`[basalt] DualPanel: no series "${key}"`)
+            return rows(s)
+          },
+          visible,
+          highlighted,
+          containerClass: cls,
+          width,
+          height: h,
+          y2: undefined,
+          yDomain: topDomain,
+          y2Domain: undefined,
+        }
+        return {
+          marks: [
+            ...(fill
+              ? [
+                  decorative(
+                    differenceY(
+                      thinFill(fillRows, width, (r) => fillAt(r.x)),
+                      {
+                        id: 'fill-between',
+                        x: (r) => r.x,
+                        y1: (r) => r.from,
+                        y2: (r) => r.to,
+                        positiveFill: fill.aboveFill ?? fill.fill,
+                        negativeFill: fill.fill,
+                        fillOpacity: 1,
+                        stroke: 'none',
+                        comparisonStroke: 'none',
+                      },
+                    ),
+                  ),
+                ]
+              : []),
+            ...visible.flatMap((s) => [lineMark(plot, s), ...markersOf(s, rows(s), undefined)]),
+          ],
+          scales: {
+            x: { scale: xScale(), axis: false },
+            y: paneY({ scale: topY, domain: topDomain, format: topFormat, ticks: TOP_TICKS, cls }),
+          },
+        }
+      }
+
+      const barPane: PaneBuilder = ({ width }) => {
+        const cls = resolveContainerClass(width)
+        const barRows = barOn ? rowsOf(data, x, barSeries) : []
+        const dim = emphasis(highlighted, { key: BAR_KEY })
+        return {
+          marks: [
+            ruleY([0], { id: 'zero', stroke: VX.axisStroke, strokeOpacity: 1, strokeWidth: 1 }),
+            barMark(barRows, {
+              id: 'bars',
+              x: rowX,
+              y: 'y',
+              fill: (row: PlotRow<T, Date | number>) =>
+                alpha((row.y ?? 0) >= 0 ? bar.positive : bar.negative, BAR_OPACITY * dim),
+            }),
+          ],
+          scales: {
+            x: paneX({ scale: xScale(), model, format, cls }),
+            y: paneY({
+              scale: barScale,
+              domain: barDomain,
+              format: bar.format,
+              ticks: BAR_TICKS,
+              cls,
+            }),
+          },
+        }
+      }
+
+      return {
+        keys: model.values,
+        top: topPane,
+        bottom: barPane,
+        topFraction,
+        gap: PANE_GAP,
+        rows: (d) => {
+          const out: EngineTooltipRow[] = []
+          for (const s of visible) {
+            const v = s.getValue(d)
+            if (s.tooltip === false || v === null || !Number.isFinite(v)) continue
+            out.push({
+              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
+              value: s.formatValue ? s.formatValue(v, d) : topFormat(v),
+              color: s.color,
+              ...(highlighted === s.key && { active: true }),
+            })
+          }
+          const v = barOn ? bar.getValue(d) : null
+          if (v !== null && Number.isFinite(v))
+            out.push({
+              label: bar.label,
+              value: bar.formatValue ? bar.formatValue(v, d) : bar.format(v),
+              color: v >= 0 ? bar.positive : bar.negative,
+              ...(highlighted === BAR_KEY && { active: true }),
+            })
+          return out
+        },
+      }
+    },
+    [data, x, lines, barSeries, top, fillBetween, bar, topFraction, topFormat, formatX],
+  )
+
+  return <PanelRung {...rung} series={all} plan={plan} />
+}

package/src/charts/Heatmap.tsx

@@ -0,0 +1,282 @@
+/**
+ * `Heatmap` — a band × band matrix of `cell` marks (`docs/V2-SPEC.md` § 9.3). Intensity is ABSOLUTE:
+ * the color scale spans `domain` (default `[0, max]`), never each row's own range, so two grids on
+ * one page read against the same ink. A cell with no datum, or a `null` value, is ABSENT: a flat
+ * `--vx-neutral` fill, no hatch. There is no cursor and no crosshair — the tooltip is per cell, its
+ * rows are `tooltip.rows(d)` data.
+ */
+import { colorGradientLegend } from '@tanstack/charts/legend'
+import { decorative } from '@tanstack/charts/mark/decorative'
+import { cell } from '@tanstack/charts/rect'
+import { scaleBand } from '@tanstack/charts/scales/band'
+import { tooltip as tooltipHost } from '@tanstack/charts/tooltip'
+import { portal } from '@tanstack/charts/tooltip/portal'
+import type { ChartBuildContext, ChartPoint, StoredChartSpec } from '@tanstack/charts/types/core'
+import { scaleQuantize } from 'd3-scale'
+import { useId, useMemo } from 'react'
+import type { CSSProperties, ReactElement } from 'react'
+import type { BasaltProps } from '../common/props'
+import { alpha, VX } from '../tokens'
+import { resolveContainerClass } from '../tokens/size-classes'
+import type { CartesianDefinition } from './compile'
+import { ChartEngine, idPrefixOf } from './host'
+import { useCoarsePointer } from '../common/use-media-query'
+import { HEIGHT_MAX, HEIGHT_MIN } from './box'
+import { ChartPlaceholder, resolveChartState } from './state'
+import { AXIS_LINE, CHART_THEME } from './theme'
+import type { ChartState, ChartTooltipRow, ResponsiveChartHeight } from './types'
+
+export type HeatmapProps<T> = BasaltProps & {
+  /** The accessible name. Required. */
+  ariaLabel: string
+  data: readonly T[]
+  /** The y band (a row) of a datum. */
+  getRow: (d: T) => string
+  /** The x band (a column) of a datum. */
+  getCol: (d: T) => string
+  /** The intensity; `null` is an absent cell (flat neutral), never a zero. */
+  getValue: (d: T) => number | null
+  /** Explicit band order. Default: first seen in `data`. */
+  rows?: readonly string[]
+  cols?: readonly string[]
+  /** The ink at full intensity, a `VX.*` ref or a series token. Default `VX.line`. */
+  color?: string
+  /** The value range the color scale spans. Default `[0, max]` of the data. */
+  domain?: readonly [number, number]
+  /** Tooltip, legend-end and `aria` value format. Default: the number as-is. */
+  formatValue?: (v: number) => string
+  /** Band tick and tooltip header labels. Default: the band key. */
+  formatRow?: (row: string) => string
+  formatCol?: (col: string) => string
+  /** `false` hides the gradient legend; `label` titles it. */
+  legend?: false | { label?: string }
+  /** Rows after the value row, per cell (a sample count, a failure reason). Called with the datum. */
+  tooltip?: false | { rows?: (d: T) => readonly ChartTooltipRow[] }
+  /** A fixed height, or one per container class. Default: by row count (160–420px). */
+  height?: number | ResponsiveChartHeight
+  /** Fill the parent's height instead (the parent needs a definite height). Overrides `height`. */
+  matchHeight?: boolean
+  state?: ChartState
+}
+
+/** Intensity steps: quantized, so the gradient legend and the cells are the same ramp. */
+const LEVELS = 8
+const MIN_LEVEL = 0.14
+const ROW_PITCH = 26
+const CHROME = 64
+const CELL_INSET = 1
+
+/** One grid position. `id` is its row-major index: the mark key, so no row/col pair can collide. */
+type Cell<T> = { id: number; row: string; col: string; value: number | null; datum: T | undefined }
+
+const identityLabel = (band: string): string => band
+
+const firstSeen = (keys: Iterable<string>): string[] => [...new Set(keys)]
+
+const ramp = (color: string): string[] =>
+  Array.from({ length: LEVELS }, (_, i) =>
+    alpha(color, MIN_LEVEL + ((1 - MIN_LEVEL) * i) / (LEVELS - 1)),
+  )
+
+const fillStyle: CSSProperties = { position: 'relative', height: '100%', minHeight: HEIGHT_MIN }
+
+export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
+  const {
+    ariaLabel,
+    data,
+    getRow,
+    getCol,
+    getValue,
+    color = VX.line,
+    domain,
+    formatValue = String,
+    formatRow = identityLabel,
+    formatCol = identityLabel,
+    legend,
+    tooltip,
+    height,
+    matchHeight = false,
+    state,
+    className,
+    style,
+  } = props
+  const chartId = useId()
+  // Primitives, so the definition does not rebuild for a fresh `{ label }` / `{ rows }` literal.
+  const showLegend = legend !== false
+  const legendLabel = legend === false ? undefined : legend?.label
+  const showTooltip = tooltip !== false
+  const tooltipRows = tooltip === false ? undefined : tooltip?.rows
+  const rows = useMemo(() => props.rows ?? firstSeen(data.map(getRow)), [props.rows, data, getRow])
+  const cols = useMemo(() => props.cols ?? firstSeen(data.map(getCol)), [props.cols, data, getCol])
+  const statedHeight =
+    height ?? Math.min(Math.max(rows.length * ROW_PITCH + CHROME, HEIGHT_MIN), HEIGHT_MAX)
+  const coarse = useCoarsePointer()
+  const boxHeight = matchHeight ? 'fill' : statedHeight
+
+  const definition = useMemo<CartesianDefinition>(() => {
+    const byBand = new Map<string, Map<string, T>>()
+    for (const d of data) {
+      const row = getRow(d)
+      const inRow = byBand.get(row) ?? new Map<string, T>()
+      inRow.set(getCol(d), d)
+      byBand.set(row, inRow)
+    }
+    // One pass: split the grid into measured, absent-with-a-datum and absent-with-none.
+    const present: Cell<T>[] = []
+    const absentWithDatum: Cell<T>[] = []
+    const absentEmpty: Cell<T>[] = []
+    let max = 0
+    for (const [r, row] of rows.entries()) {
+      for (const [c, col] of cols.entries()) {
+        const datum = byBand.get(row)?.get(col)
+        const raw = datum === undefined ? null : getValue(datum)
+        const value = raw !== null && Number.isFinite(raw) ? raw : null
+        const cellAt: Cell<T> = { id: r * cols.length + c, row, col, datum, value }
+        if (value !== null) {
+          present.push(cellAt)
+          max = Math.max(max, value)
+        } else if (datum === undefined) absentEmpty.push(cellAt)
+        else absentWithDatum.push(cellAt)
+      }
+    }
+    const [lo, hi] = domain ?? [0, max]
+    // A flat or inverted domain would map every value to one step; widen it to a unit.
+    const scale = scaleQuantize<string>()
+      .domain([lo, hi > lo ? hi : lo + 1])
+      .range(ramp(color))
+    const header = (c: Cell<T>): string => `${formatRow(c.row)} · ${formatCol(c.col)}`
+
+    return {
+      chart: ({ width }: ChartBuildContext): StoredChartSpec => {
+        const ticks = { line: false as const, size: 0 }
+        const tickLabels = {
+          fontSize: resolveContainerClass(width) === 'wide' ? VX.text.micro : VX.text.nano,
+          opacity: 1,
+          thin: true,
+        }
+        const marks = [
+          decorative(
+            cell(absentEmpty, {
+              id: 'absent-empty',
+              x: 'col',
+              y: 'row',
+              fill: VX.neutral,
+              fillOpacity: 0.12,
+              inset: CELL_INSET,
+            }),
+          ),
+          cell(absentWithDatum, {
+            id: 'absent',
+            x: 'col',
+            y: 'row',
+            fill: VX.neutral,
+            fillOpacity: 0.12,
+            inset: CELL_INSET,
+            key: 'id',
+          }),
+          cell(present, {
+            id: 'cells',
+            x: 'col',
+            y: 'row',
+            color: 'value',
+            inset: CELL_INSET,
+            key: 'id',
+          }),
+        ]
+        return {
+          marks,
+          scales: {
+            x: {
+              scale: scaleBand<string>().domain(cols).paddingInner(0).paddingOuter(0),
+              axis: {
+                line: AXIS_LINE,
+                ticks: { values: cols, format: (v) => formatCol(String(v)), ...ticks },
+                tickLabels,
+              },
+            },
+            y: {
+              scale: scaleBand<string>().domain(rows).paddingInner(0).paddingOuter(0),
+              axis: {
+                line: false,
+                ticks: { values: rows, format: (v) => formatRow(String(v)), ...ticks },
+                tickLabels,
+              },
+            },
+          },
+          color: {
+            scale,
+            ...(showLegend && {
+              legend: colorGradientLegend({
+                steps: LEVELS,
+                format: formatValue,
+                placement: 'bottom',
+                ...(legendLabel !== undefined && { label: legendLabel }),
+              }),
+            }),
+          },
+          theme: CHART_THEME,
+        }
+      },
+      tooltip: showTooltip
+        ? {
+            use: tooltipHost,
+            portal,
+            content: (points: readonly ChartPoint[]) => {
+              const point = points[0]
+              const c = point?.datum as Cell<T> | undefined
+              if (!point || !c) return { rows: [] }
+              const extra = c.datum === undefined ? [] : (tooltipRows?.(c.datum) ?? [])
+              const value: readonly ChartTooltipRow[] =
+                c.value === null
+                  ? [{ label: 'Value', value: 'No data' }]
+                  : [
+                      {
+                        label: 'Value',
+                        value: formatValue(c.value),
+                        ...(point.color && { color: point.color }),
+                      },
+                    ]
+              return { title: header(c), rows: [...value, ...extra] }
+            },
+          }
+        : false,
+    }
+  }, [
+    data,
+    rows,
+    cols,
+    getRow,
+    getCol,
+    getValue,
+    color,
+    domain,
+    formatValue,
+    formatRow,
+    formatCol,
+    legendLabel,
+    showLegend,
+    showTooltip,
+    tooltipRows,
+  ])
+
+  const resolved = resolveChartState(state)
+  return (
+    <div
+      data-basalt-chart=""
+      {...(className !== undefined && { className })}
+      style={matchHeight ? { ...fillStyle, ...style } : style}
+    >
+      {resolved === null ? (
+        <ChartEngine
+          definition={definition}
+          ariaLabel={ariaLabel}
+          height={boxHeight}
+          idPrefix={idPrefixOf(chartId)}
+          coarse={coarse}
+        />
+      ) : (
+        <ChartPlaceholder state={state} height={boxHeight} />
+      )}
+    </div>
+  )
+}