basalt-ui 2.2.0 → 2.4.0

package/src/charts/compile.ts

@@ -8,7 +8,7 @@
 import { crosshair } from '@tanstack/charts/crosshair'
 import { decorative } from '@tanstack/charts/mark/decorative'
 import { rect } from '@tanstack/charts/rect'
-import { ruleY } from '@tanstack/charts/rule'
+import { ruleX, ruleY } from '@tanstack/charts/rule'
 import { scaleLinear } from '@tanstack/charts/scales/linear'
 import { scaleUtc } from 'd3-scale'
 import { tooltip as tooltipHost } from '@tanstack/charts/tooltip'
@@ -27,6 +27,7 @@ import { fmtCompact } from '../format/number'
 import { VX } from '../tokens'
 import type { ContainerClass } from '../tokens/size-classes'
 import { cursorBinding, sourceOnlyFocus } from './cursor'
+import { cursorDots } from './marks'
 import { resolveContainerClass } from '../tokens/size-classes'
 import { resolveYDomain, xScaleFor, xZoneFractions, yScaleFor } from './scales'
 import type { XScaleModel } from './scales'
@@ -39,6 +40,9 @@ import type {
   ChartTooltipRow,
   ChartX,
   PlotRow,
+  RefLine,
+  ZoneEdge,
+  ZoneSpec,
 } from './types'
 
 /**
@@ -135,6 +139,67 @@ export function defaultFormatX(v: ChartValue): string {
 const clampTo = (v: number, [lo, hi]: readonly [number, number]): number =>
   Math.min(Math.max(v, Math.min(lo, hi)), Math.max(lo, hi))
 
+/**
+ * A tooltip swatch is the engine's `background` shorthand, so a dashed one is a gradient: a 2px
+ * dashed line across the swatch's middle, in the row color.
+ */
+export const dashedSwatch = (color: string): string =>
+  `repeating-linear-gradient(90deg, ${color} 0 2px, transparent 2px 4px) center / 100% 2px no-repeat`
+
+/** A basalt tooltip row as the engine's: the swatch shape folded into the row color. */
+export function engineRow(
+  row: ChartTooltipRow & { active?: boolean | undefined },
+): EngineTooltipRow {
+  const { label, value, color, swatch, active } = row
+  return {
+    label,
+    value,
+    ...(color !== undefined && { color: swatch === 'dashed' ? dashedSwatch(color) : color }),
+    ...(active && { active }),
+  }
+}
+
+/** A series row of a tooltip: the label with its note, the swatch following the series' dash. */
+export function seriesRow(
+  s: Pick<ChartSeries<never>, 'label' | 'note' | 'color' | 'dash'>,
+  value: string,
+  active: boolean,
+): EngineTooltipRow {
+  return engineRow({
+    label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
+    value,
+    color: s.color,
+    swatch: s.dash === 'dashed' ? 'dashed' : 'solid',
+    active,
+  })
+}
+
+/** Keys the compiler reserves for the legend entries it derives from `refLines`. */
+const REF_KEY_PREFIX = '__ref-'
+
+/** The legend key of a reference line that names itself (`RefLine.legend`). */
+const refLegendKey = (index: number): string => `${REF_KEY_PREFIX}${index}`
+
+/** Legend-only entries for the reference lines that name themselves, in line order. */
+export function refLegendSeries<T>(refLines: readonly RefLine[] | undefined): ChartSeries<T>[] {
+  return (refLines ?? []).flatMap((r, i) =>
+    r.legend === undefined
+      ? []
+      : [
+          {
+            key: refLegendKey(i),
+            label: r.legend.label,
+            color: r.color,
+            role: 'reference' as const,
+            tooltip: false,
+            getValue: () => null,
+            ...(r.legend.mark !== undefined && { mark: r.legend.mark }),
+            ...(r.dashed && { dash: 'dashed' as const }),
+          },
+        ],
+  )
+}
+
 /** The visible series: not toggled off, and not a companion whose parent is. */
 export function visibleSeries<T>(
   series: readonly ChartSeries<T>[],
@@ -249,6 +314,86 @@ export function areaGradient(index: number, color: string): ChartGradient {
   }
 }
 
+const areaTint = (color: string): string =>
+  `color-mix(in srgb, ${color} var(--vx-area-top), transparent)`
+
+/**
+ * A series area filled by value zone: a vertical gradient whose stops sit at the zone boundaries.
+ * The engine writes `<linearGradient>` in the default `objectBoundingBox` units, so offsets are
+ * fractions of the AREA's own box, not of the plot: from the larger of the series' maximum and 0 down
+ * to the smaller of its minimum and 0, the baseline the area closes to even when the y domain
+ * excludes 0. A boundary at value `v` sits at `(ceiling - v) / (ceiling - floor)`. Hard edges:
+ * neighbouring zones meet at one offset; overlapping zones never run backwards. `null` when no zone
+ * reaches the area (the caller keeps the plain series-colour fade). Linear axes only.
+ */
+export function zoneAreaGradient(
+  index: number,
+  zones: readonly ZoneSpec[],
+  values: readonly (number | null)[],
+): ChartGradient | null {
+  let floor = 0
+  let ceiling = 0
+  for (const v of values) {
+    if (v === null || !Number.isFinite(v)) continue
+    if (v < floor) floor = v
+    if (v > ceiling) ceiling = v
+  }
+  const span = ceiling - floor
+  if (span <= 0) return null
+  const offsetOf = (v: number): number => (ceiling - Math.min(ceiling, Math.max(floor, v))) / span
+  const reaching = zones
+    .filter((z) => !Number.isNaN(z.from) && !Number.isNaN(z.to) && z.to > floor && z.from < ceiling)
+    .toSorted((p, q) => q.to - p.to)
+  let previous = 0
+  const stops = reaching.flatMap((z) =>
+    [offsetOf(z.to), offsetOf(z.from)].map((raw) => {
+      previous = Math.max(previous, raw)
+      return { offset: previous, color: areaTint(z.fill) }
+    }),
+  )
+  if (stops.length === 0) return null
+  return { id: areaGradientId(index), x1: 0, y1: 0, x2: 0, y2: 1, stops }
+}
+
+let warnedLogZones = false
+
+/** Zone stops are placed linearly in value; a log axis would put them in the wrong place (V2-SPEC
+ * § 9.9 precedent): dev throws, production logs once and keeps the series-colour fade. */
+function guardLogZones(onLog: boolean): boolean {
+  if (!onLog) return false
+  const message = "area: 'zones' cannot use a log axis; use area: true"
+  if (process.env.NODE_ENV !== 'production') throw new Error(message)
+  // oxlint-disable-next-line no-console -- the production leg of a dev-only throw
+  if (!warnedLogZones) console.error(message)
+  warnedLogZones = true
+  return true
+}
+
+/** The gradient resource for a series' `area` fill: zones, a colour ref, or the series colour. */
+function seriesAreaGradient<T, X extends ChartX>(
+  s: ChartSeries<T>,
+  index: number,
+  input: CartesianInput<T, X>,
+  axes: Axes<T>,
+): ChartGradient {
+  const plain = areaGradient(
+    index,
+    typeof s.area === 'string' && s.area !== 'zones' ? s.area : s.color,
+  )
+  if (s.area !== 'zones') return plain
+  const side = axes.onRight(s) ? 'right' : 'left'
+  const axisConfig = side === 'right' ? input.y2 : input.y
+  if (guardLogZones(axisConfig?.scale === 'log')) return plain
+  const zones = (input.zones ?? []).filter((z) => axes.scaleId(z.axisSide) === axes.scaleId(side))
+  return (
+    zoneAreaGradient(
+      index,
+      zones,
+      input.data.map((d) => s.getValue(d)),
+    ) ?? plain
+  )
+}
+
 const isBar = <T>(s: ChartSeries<T>): boolean => s.mark === 'bar'
 
 /** The two synthetic totals standing in for a stack's bars in its AUTO domain only: the positive
@@ -354,32 +499,93 @@ function resolveAxes<T, X extends ChartX>(
   }
 }
 
-/** Fixed paint under the kind's marks: zones, then x-zones. */
+/** The sides a `ZoneEdge` names, in a fixed order: the lower bound first. */
+const edgeSides = <A extends string, B extends string>(
+  edge: ZoneEdge<A | B> | undefined,
+  lower: A,
+  upper: B,
+): { lower: boolean; upper: boolean } => ({
+  lower: edge !== undefined && (edge.side === lower || edge.side === 'both'),
+  upper: edge !== undefined && (edge.side === upper || edge.side === 'both'),
+})
+
+const edgePaint = (edge: ZoneEdge<string>) => ({
+  stroke: edge.color,
+  strokeOpacity: 1,
+  strokeWidth: edge.width ?? 1,
+  ...(edge.dashed && { strokeDasharray: DASH }),
+})
+
+/**
+ * An edge rule at `position` when it lies strictly inside `(lo, hi)`: a bound at or past the plot
+ * edge (infinite, outside the domain, exactly on it) has no rule, for y- and x-zones alike.
+ */
+const edgeRule = (
+  position: number | null,
+  [lo, hi]: readonly [number, number],
+  make: (at: number) => ChartMarks[number],
+): ChartMarks => (position !== null && position > lo && position < hi ? [make(position)] : [])
+
+/** Fixed paint under the kind's marks: zones, then x-zones, each with its edge rules. */
 function underlayMarks<T, X extends ChartX>(
   input: CartesianInput<T, X>,
   model: XScaleModel<X>,
   axes: Axes<T>,
 ): ChartMarks {
   const fractionRows = [{ f0: 0, f1: 1 }]
-  const zones = (input.zones ?? []).map((z, i) => {
+  const zones = (input.zones ?? []).flatMap((z, i) => {
     const domain = axes.axisOf(z.axisSide).domain
-    return decorative(
-      rect(fractionRows, {
-        id: `zone-${i}`,
-        x1: 'f0',
-        x2: 'f1',
-        y1: () => clampTo(z.from, domain),
-        y2: () => clampTo(z.to, domain),
-        xScale: 'zx',
-        yScale: axes.scaleId(z.axisSide),
-        fill: z.fill,
-        inset: 0,
-      }),
-    )
+    const [lo, hi] = [Math.min(...domain), Math.max(...domain)]
+    const rule = (value: number, name: string) =>
+      edgeRule(value, [lo, hi], (at) =>
+        decorative(
+          ruleY([at], {
+            id: `zone-${i}-${name}`,
+            yScale: axes.scaleId(z.axisSide),
+            ...(z.edge && edgePaint(z.edge)),
+          }),
+        ),
+      )
+    const sides = edgeSides(z.edge, 'bottom', 'top')
+    return [
+      decorative(
+        rect(fractionRows, {
+          id: `zone-${i}`,
+          x1: 'f0',
+          x2: 'f1',
+          y1: () => clampTo(z.from, domain),
+          y2: () => clampTo(z.to, domain),
+          xScale: 'zx',
+          yScale: axes.scaleId(z.axisSide),
+          fill: z.fill,
+          inset: 0,
+        }),
+      ),
+      ...(sides.lower ? rule(Math.min(z.from, z.to), 'bottom') : []),
+      ...(sides.upper ? rule(Math.max(z.from, z.to), 'top') : []),
+    ]
   })
   const xZones = (input.xZones ?? []).flatMap((z, i) => {
     const f = xZoneFractions(z, model)
     if (!f) return []
+    const sides = edgeSides(z.edge, 'start', 'end')
+    // The bound's own plot fraction (widened like the band), unclamped: `f` is clamped to the plot.
+    const widen = z.align === 'edge' ? model.halfStep : 0
+    const bound = (value: X | undefined, sign: 1 | -1): number | null => {
+      const fraction = value === undefined ? null : model.fraction(value)
+      return fraction === null ? null : fraction + sign * widen
+    }
+    const rule = (value: X | undefined, sign: 1 | -1, name: string) =>
+      edgeRule(bound(value, sign), [0, 1], (at) =>
+        decorative(
+          ruleX([at], {
+            id: `xzone-${i}-${name}`,
+            x: (v: number) => v,
+            xScale: 'zx',
+            ...(z.edge && edgePaint(z.edge)),
+          }),
+        ),
+      )
     return [
       decorative(
         rect([{ f0: f[0], f1: f[1] }], {
@@ -393,6 +599,9 @@ function underlayMarks<T, X extends ChartX>(
           inset: 0,
         }),
       ),
+      // An omitted bound is the plot edge: nothing to draw a rule on.
+      ...(sides.lower ? rule(z.from, -1, 'start') : []),
+      ...(sides.upper ? rule(z.to, 1, 'end') : []),
     ]
   })
   return [...zones, ...xZones]
@@ -403,15 +612,20 @@ const refLineMarks = <T, X extends ChartX>(
   input: CartesianInput<T, X>,
   axes: Axes<T>,
 ): ChartMarks =>
-  (input.refLines ?? []).map((r, i) =>
-    ruleY([r.value], {
-      id: `ref-${i}`,
-      stroke: r.color,
-      strokeOpacity: 1,
-      strokeWidth: 1,
-      yScale: axes.scaleId(r.axis),
-      ...(r.dashed && { strokeDasharray: DASH }),
-    }),
+  (input.refLines ?? []).flatMap((r, i) =>
+    // A line that names itself in the legend can be toggled off there.
+    input.hidden?.has(refLegendKey(i))
+      ? []
+      : [
+          ruleY([r.value], {
+            id: `ref-${i}`,
+            stroke: r.color,
+            strokeOpacity: 1,
+            strokeWidth: 1,
+            yScale: axes.scaleId(r.axis),
+            ...(r.dashed && { strokeDasharray: DASH }),
+          }),
+        ],
   )
 
 function buildScales<T, X extends ChartX>(opts: {
@@ -487,6 +701,25 @@ function rowsOf<T, X extends ChartX>(
   }
 }
 
+/** The cursor dots of the visible series that opt in with `cursorValue`. */
+function cursorDotMarks<T, X extends ChartX>(
+  input: CartesianInput<T, X>,
+  visible: readonly ChartSeries<T>[],
+  axes: Axes<T>,
+): ChartMarks {
+  return visible.flatMap((s) => {
+    const { cursorValue } = s
+    if (!cursorValue) return []
+    const rows = input.data.flatMap((d): PlotRow<T, X>[] => {
+      const y = cursorValue(d)
+      return y === null || !Number.isFinite(y)
+        ? []
+        : [{ x: input.x(d), y, series: s.key, datum: d }]
+    })
+    return [cursorDots(s, rows, axes.onRight(s) ? 'y2' : undefined)]
+  })
+}
+
 function tooltipSpec<T, X extends ChartX>(opts: {
   input: CartesianInput<T, X>
   axes: Axes<T>
@@ -518,25 +751,40 @@ function tooltipSpec<T, X extends ChartX>(opts: {
       for (const s of rowSeries) {
         const v = s.getValue(d)
         if (v === null || !Number.isFinite(v)) continue
-        rows.push({
-          label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-          value: s.formatValue
-            ? s.formatValue(v, d)
-            : axes.axisOf(axes.onRight(s) ? 'right' : 'left').format(v),
-          color: s.color,
-          ...(input.highlighted === s.key && { active: true }),
-        })
+        rows.push(
+          seriesRow(
+            s,
+            s.formatValue
+              ? s.formatValue(v, d)
+              : axes.axisOf(axes.onRight(s) ? 'right' : 'left').format(v),
+            input.highlighted === s.key,
+          ),
+        )
       }
       const extra: readonly ChartTooltipRow[] =
         (input.tooltip || undefined)?.rows?.(d, { visible, hidden }) ?? []
-      return { title: tooltipHeader(input, formatX, x, d), rows: [...rows, ...extra] }
+      return {
+        title: tooltipHeader(input, formatX, x, d),
+        rows: [...rows, ...extra.map(engineRow)],
+      }
     },
   }
 }
 
+/** A consumer key in the legend's reserved `__ref-` namespace would collide with a reference line. */
+function guardReservedKeys<T>(series: readonly ChartSeries<T>[]): void {
+  if (process.env.NODE_ENV === 'production') return
+  const clash = series.find((s) => s.key.startsWith(REF_KEY_PREFIX))
+  if (clash)
+    throw new Error(
+      `[basalt] CartesianChart: the series key "${clash.key}" is reserved (\`${REF_KEY_PREFIX}\` prefix names reference-line legend entries)`,
+    )
+}
+
 export function compileCartesian<T, X extends ChartX>(
   input: CartesianInput<T, X>,
 ): CartesianDefinition {
+  guardReservedKeys(input.series)
   const visible = visibleSeries(input.series, input.hidden ?? new Set<string>())
   const visibleKeys = new Set(visible.map((s) => s.key))
   const keys = new Set(input.series.map((s) => s.key))
@@ -544,11 +792,12 @@ export function compileCartesian<T, X extends ChartX>(
   const axes = resolveAxes(input, visible)
   const under = underlayMarks(input, model, axes)
   const over = refLineMarks(input, axes)
+  const dots = cursorDotMarks(input, visible, axes)
   const rows = rowsOf(input, visibleKeys)
   const formatX = (v: ChartValue): string =>
     input.formatX ? input.formatX(v as X) : defaultFormatX(v)
   const gradients = input.series.flatMap((s, i) =>
-    s.area ? [areaGradient(i, typeof s.area === 'string' ? s.area : s.color)] : [],
+    s.area ? [seriesAreaGradient(s, i, input, axes)] : [],
   )
 
   return {
@@ -566,7 +815,7 @@ export function compileCartesian<T, X extends ChartX>(
         y2Domain: axes.right?.domain,
       })
       return {
-        marks: [...under, ...kindMarks, ...over, crosshair({ x: CROSSHAIR, y: false })],
+        marks: [...under, ...kindMarks, ...dots, ...over, crosshair({ x: CROSSHAIR, y: false })],
         scales: buildScales({ input, model, axes, formatX, cls, zoneScale: under.length > 0 }),
         theme: CHART_THEME,
         ...(gradients.length > 0 && { gradients }),

package/src/charts/index.ts

@@ -28,6 +28,7 @@ export {
 } from './MirroredBars'
 export { ChartCard, type ChartCardProps, type ChartCardSlot } from './ChartCard'
 export { chartCursor } from './cursor'
+export { chartCurve, type CurveName } from './curves'
 export type {
   AxisConfig,
   CartesianChartProps,

package/src/charts/marks.ts

@@ -30,12 +30,21 @@ export function emphasis<T>(
   return highlighted === null || highlighted === s.key || highlighted === s.parent ? 1 : DIMMED
 }
 
+/** The rows a series' line and area are drawn through: all of them, or only the non-null ones. */
+export function drawnRows<T, X extends ChartX>(
+  plot: PlotContext<T, X>,
+  s: Pick<ChartSeries<T>, 'key' | 'gaps'>,
+): PlotRow<T, X>[] {
+  const rows = plot.rows(s.key)
+  return s.gaps === 'connect' ? rows.filter((r) => r.y !== null) : rows
+}
+
 export function lineMark<T, X extends ChartX>(
   plot: PlotContext<T, X>,
   s: ChartSeries<T>,
 ): ChartMarks[number] {
   const yScale = yScaleOf(plot, s)
-  return lineY(plot.rows(s.key), {
+  return lineY(drawnRows(plot, s), {
     id: s.key,
     x: rowX,
     y: 'y',
@@ -96,6 +105,31 @@ export function markersOf<T, X extends ChartX>(
   )
 }
 
+/**
+ * The cursor dot of a series the consumer draws itself (`ChartSeries.cursorValue`): a dot per datum,
+ * invisible until the cursor is on that datum's x. It is NOT decorative, so the engine counts it as
+ * a focus point and the shared cursor, the focus group and the tooltip reach the series.
+ */
+export function cursorDots<T, X extends ChartX>(
+  s: ChartSeries<T>,
+  rows: readonly PlotRow<T, X>[],
+  yScale: 'y2' | undefined,
+): ChartMarks[number] {
+  return dot(rows, {
+    id: `${s.key}-cursor`,
+    x: rowX,
+    y: 'y',
+    r: VX.dotR,
+    fill: s.color,
+    fillOpacity: 0,
+    stroke: VX.surface.panel,
+    strokeWidth: 1.5,
+    strokeOpacity: 0,
+    states: [{ when: { focus: 'x' }, style: { fillOpacity: 1, strokeOpacity: 1 } }],
+    ...(yScale !== undefined && { yScale }),
+  })
+}
+
 /**
  * A single-series `barY`. The engine stacks every `barY` that has no explicit extent, and a row with
  * no `z`/`color` channel is its own series: an N-by-N matrix (a 5k-row `DualPanel` took 10 s). So

package/src/charts/panel.tsx

@@ -21,7 +21,7 @@ import { useCallback } from 'react'
 import type { ReactElement } from 'react'
 import { ChartShell } from './CartesianChart'
 import type { ChartShellProps, ShellContext } from './CartesianChart'
-import { defaultFormatX, utcHeaderDate, visibleSeries, xGuide, yGuide } from './compile'
+import { defaultFormatX, engineRow, utcHeaderDate, visibleSeries, xGuide, yGuide } from './compile'
 import type { CartesianDefinition } from './compile'
 import { cursorBinding, sourceOnlyFocus } from './cursor'
 import type { XScaleModel } from './scales'
@@ -205,7 +205,7 @@ function panelDefinition<T, X extends ChartX>(
               const { x, d } = sourceOf<T>(primary, owned)
               const extra: readonly ChartTooltipRow[] =
                 tooltip?.rows?.(d, { visible, hidden: hiddenSeries }) ?? []
-              return { title: header(x, d), rows: [...plan.rows(d), ...extra] }
+              return { title: header(x, d), rows: [...plan.rows(d), ...extra.map(engineRow)] }
             },
           },
   }