basalt-ui 2.3.0 → 2.5.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'
@@ -23,10 +23,12 @@ import type {
   ResponsiveChartDefinition,
   StoredChartSpec,
 } from '@tanstack/charts/types/core'
+import { SHORT_CHART_HEIGHT } from './box'
 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 +41,8 @@ import type {
   ChartTooltipRow,
   ChartX,
   PlotRow,
+  RefLine,
+  ZoneEdge,
   ZoneSpec,
 } from './types'
 
@@ -94,6 +98,14 @@ const LADDER = {
 const INSIDE_LABEL_DX = 4
 const INSIDE_LABEL_DY = -6
 
+/**
+ * Y labels go inside the plot only for the compact class under `SHORT_CHART_HEIGHT` (the box's own
+ * short signal); otherwise they sit in a left gutter. `height` is the whole chart's, `0` before it
+ * is measured, which keeps the gutter rather than flipping a first paint inside.
+ */
+const labelsInside = (cls: ContainerClass, height: number): boolean =>
+  cls === 'compact' && height > 0 && height < SHORT_CHART_HEIGHT
+
 export function defaultNumberFormat(v: number): string {
   return fmtCompact(v, { digits: Math.abs(v) >= 1000 ? 1 : 2 })
 }
@@ -136,6 +148,83 @@ 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}`
+
+/**
+ * A reference line is drawn translucent (`*-ref`, 20-30% alpha) so it recedes behind the data, but
+ * a 16x8 swatch at that alpha vanishes on the dark surface. The legend takes the status solid,
+ * which the color gate holds to 3:1 on the panel in both schemes, like a series swatch.
+ */
+const SWATCH_SOLID: ReadonlyMap<string, string> = new Map([
+  [VX.goodRef, VX.goodSolid],
+  [VX.badRef, VX.badSolid],
+  [VX.warnRef, VX.warnSolid],
+  // The tinted status fills are as translucent, and a consumer may pass either as a line color.
+  [VX.good, VX.goodSolid],
+  [VX.goodSoft, VX.goodSolid],
+  [VX.bad, VX.badSolid],
+  [VX.warn, VX.warnSolid],
+])
+
+/** 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: SWATCH_SOLID.get(r.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>[],
@@ -154,8 +243,10 @@ export function yGuide<T>(opts: {
   cls: ContainerClass
   side: 'left' | 'right'
   grid: boolean
+  /** The whole chart's height: decides inside or gutter labels. */
+  height: number
 }): Omit<ChartPositionScaleOptions<number>, 'scale'> {
-  const { cfg, axis, cls, side, grid } = opts
+  const { cfg, axis, cls, side, grid, height } = opts
   const ladder = LADDER[cls]
   const ticks =
     typeof cfg?.ticks === 'object'
@@ -163,8 +254,8 @@ export function yGuide<T>(opts: {
       : { count: typeof cfg?.ticks === 'number' ? cfg.ticks : ladder.yTicks }
   const gridLine = grid ? { grid: GRID_LINE } : {}
   if (cls === 'micro') return { ...gridLine, axis: false }
-  // Compact: labels sit INSIDE the plot, above their grid line, so the plot keeps the full width.
-  const inside = cls === 'compact'
+  // Labels sit INSIDE the plot, above their grid line, so the plot keeps the full width.
+  const inside = labelsInside(cls, height)
   return {
     ...gridLine,
     ...(side === 'right' && { side: 'right' as const }),
@@ -212,9 +303,12 @@ export function xGuide<X extends ChartX>(opts: {
   xTicks: number | readonly X[] | undefined
   format: (v: ChartValue) => string
   cls: ContainerClass
+  /** The whole chart's height: decides whether the left margin is locked to zero. */
+  height: number
 }): Omit<ChartPositionScaleOptions<ChartValue>, 'scale'> {
-  const { model, xTicks, format, cls } = opts
+  const { model, xTicks, format, cls, height } = opts
   const ladder = LADDER[cls]
+  const inside = labelsInside(cls, height)
   const ticks = xTickPolicy(model, xTicks ?? ladder.xTicks)
   return {
     axis: {
@@ -224,8 +318,8 @@ export function xGuide<X extends ChartX>(opts: {
         fontSize: ladder.font,
         opacity: 1,
         thin: true,
-        // A locked-zero left margin (compact) must not clip the first label.
-        ...(cls === 'compact' && {
+        // A locked-zero left margin (inside labels) must not clip the first label.
+        ...(inside && {
           anchor: ({ index }: { index: number }) => (index === 0 ? ('start' as const) : undefined),
         }),
       },
@@ -435,32 +529,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] }], {
@@ -474,6 +629,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]
@@ -484,15 +642,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: {
@@ -501,18 +664,26 @@ function buildScales<T, X extends ChartX>(opts: {
   axes: Axes<T>
   formatX: (v: ChartValue) => string
   cls: ContainerClass
+  height: number
   zoneScale: boolean
 }): StoredChartSpec['scales'] {
-  const { input, model, axes, formatX, cls, zoneScale } = opts
+  const { input, model, axes, formatX, cls, height, zoneScale } = opts
   const { left, right } = axes
   return {
     x: {
       scale: model.scale,
-      ...xGuide({ model, xTicks: input.xTicks, format: formatX, cls }),
+      ...xGuide({ model, xTicks: input.xTicks, format: formatX, cls, height }),
     },
     y: {
       scale: yScaleFor(input.y, left.domain),
-      ...yGuide({ cfg: input.y, axis: left, cls, side: 'left', grid: input.y?.grid ?? true }),
+      ...yGuide({
+        cfg: input.y,
+        axis: left,
+        cls,
+        height,
+        side: 'left',
+        grid: input.y?.grid ?? true,
+      }),
     },
     ...(right && {
       y2: {
@@ -522,6 +693,7 @@ function buildScales<T, X extends ChartX>(opts: {
           cfg: input.y2,
           axis: right,
           cls,
+          height,
           side: 'right',
           grid: input.y2?.grid ?? false,
         }),
@@ -568,6 +740,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>
@@ -599,25 +790,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))
@@ -625,6 +831,7 @@ 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)
@@ -647,12 +854,20 @@ export function compileCartesian<T, X extends ChartX>(
         y2Domain: axes.right?.domain,
       })
       return {
-        marks: [...under, ...kindMarks, ...over, crosshair({ x: CROSSHAIR, y: false })],
-        scales: buildScales({ input, model, axes, formatX, cls, zoneScale: under.length > 0 }),
+        marks: [...under, ...kindMarks, ...dots, ...over, crosshair({ x: CROSSHAIR, y: false })],
+        scales: buildScales({
+          input,
+          model,
+          axes,
+          formatX,
+          cls,
+          height,
+          zoneScale: under.length > 0,
+        }),
         theme: CHART_THEME,
         ...(gradients.length > 0 && { gradients }),
         clip: true,
-        ...(cls === 'compact' && { margin: { left: 0, ...(axes.right && { right: 0 }) } }),
+        ...(labelsInside(cls, height) && { margin: { left: 0, ...(axes.right && { right: 0 }) } }),
       }
     },
     // Followers paint the crosshair only, unless the chart opts into following tooltips.

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'
@@ -83,12 +83,15 @@ export const paneY = (opts: {
   format: (v: number) => string
   ticks: number
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
   ...yGuide({
     cfg: { ticks: opts.ticks },
     axis: { domain: opts.domain, format: opts.format },
     cls: opts.cls,
+    height: opts.height,
     side: 'left',
     grid: true,
   }),
@@ -102,11 +105,23 @@ export const paneX = <X extends ChartX>(opts: {
   model: XScaleModel<X>
   format: (v: ChartValue) => string
   cls: ContainerClass
+  /** The whole chart's height ({@link chartHeightOf}). */
+  height: number
 }): StoredChartSpec['scales'][string] => ({
   scale: opts.scale,
-  ...xGuide({ model: opts.model, xTicks: undefined, format: opts.format, cls: opts.cls }),
+  ...xGuide({
+    model: opts.model,
+    xTicks: undefined,
+    format: opts.format,
+    cls: opts.cls,
+    height: opts.height,
+  }),
 })
 
+/** The whole chart's height from one pane's: a pane gets `share` of the height less the gap. */
+export const chartHeightOf = (paneHeight: number, share: number, gap: number): number =>
+  paneHeight > 0 && share > 0 ? paneHeight / share + gap : 0
+
 /** One row per datum for a series: a `null` or non-finite value is kept as a gap. */
 export function rowsOf<T, X extends ChartX>(
   data: readonly T[],
@@ -205,7 +220,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)] }
             },
           },
   }

package/src/charts/types.ts

@@ -31,6 +31,13 @@ export type ChartSeries<T> = {
    * tier, a config value) is a step: a smoothed curve draws values that never existed. */
   curve?: CurveName | undefined
   strokeWidth?: number | undefined
+  /**
+   * What a `null` value does to the line (and its `area`). `'break'` (default) leaves a gap;
+   * `'connect'` draws through the series' non-null points only, skipping the null rows, so a series
+   * that is null on most shared x values (one lift in a wide table) is one continuous line. Points,
+   * markers, the cursor and the tooltip still read real values: a null row has no tooltip row.
+   */
+  gaps?: 'break' | 'connect' | undefined
   /** Dims the plotted stroke (a faint companion line). Strokes only. */
   strokeOpacity?: number | undefined
   /** Bars and areas. */
@@ -53,6 +60,12 @@ export type ChartSeries<T> = {
   note?: string | undefined
   /** Per-series tooltip value format; receives the datum so a row can read more than the value. */
   formatValue?: ((v: number, d: T) => string) | undefined
+  /**
+   * A cursor dot for a series whose mark the consumer draws itself (`marks`, so `getValue` stays
+   * `null`): the y of the dot at each datum, `null` for none. The dot shows while the cursor is on
+   * that datum's x and takes the series color. A series drawn from `plot.rows` already has one.
+   */
+  cursorValue?: ((d: T) => number | null) | undefined
   /** A marker at a point (a PR star, a status dot); `null` for none. */
   getMarker?:
     | ((d: T) => {
@@ -95,12 +108,24 @@ export type AxisConfig<T> = {
   scale?: 'linear' | 'log' | undefined
 }
 
+/** A rule along a band's boundary, painted with the band. A bound at the plot edge draws none. */
+export type ZoneEdge<S extends string> = {
+  side: S | 'both'
+  color: string
+  dashed?: boolean | undefined
+  /** Default `1`. */
+  width?: number | undefined
+}
+
 /** A horizontal band on one y axis. `±Infinity` reaches the plot edge. */
 export type ZoneSpec = {
   from: number
   to: number
   fill: string
   axisSide?: 'left' | 'right' | undefined
+  /** A rule on the band's visual `top` (the larger bound) and/or `bottom` (the smaller), whichever
+   * of `from`/`to` that is. */
+  edge?: ZoneEdge<'top' | 'bottom'> | undefined
 }
 
 /**
@@ -113,6 +138,8 @@ export type XZoneSpec<X extends ChartX = ChartX> = {
   to?: X | undefined
   fill: string
   align?: 'center' | 'edge' | undefined
+  /** A rule on the band's `start` (`from`) and/or `end` (`to`) boundary; an omitted bound has none. */
+  edge?: ZoneEdge<'start' | 'end'> | undefined
 }
 
 /** A horizontal reference line — annotation only, no domain role beyond staying inside the plot. */
@@ -121,6 +148,13 @@ export type RefLine = {
   color: string
   dashed?: boolean | undefined
   axis?: 'left' | 'right' | undefined
+  /**
+   * Names the line in the legend (its color, dashed as `dashed`; a toggle hides the line), so a
+   * threshold needs no always-`null` series. `mark` is the swatch shape. Default `'line'`. The
+   * toggle state is keyed by the line's index in `refLines`: reordering the array while a line is
+   * toggled off moves the "off" to whichever line now sits at that index.
+   */
+  legend?: { label: string; mark?: 'line' | 'bar' | undefined } | undefined
 }
 
 /** A fill between the line and a value, on one side of it, tracking the line. */
@@ -138,7 +172,9 @@ export type ChartTooltipRow = {
   label: string
   value: string
   /** The row swatch; omitted, the row has none. */
-  color?: string
+  color?: string | undefined
+  /** The swatch shape; `'dashed'` for a reference or dashed series. Default `'solid'`. */
+  swatch?: 'solid' | 'dashed' | undefined
 }
 
 export type ChartTooltipConfig<T, X extends ChartX = ChartX> = {

package/src/index.ts

@@ -12,7 +12,7 @@ export {
   type BasaltRouter,
   type BasaltRouterContext,
 } from './provider/create-router'
-export type { BasaltEvent } from './telemetry'
+export type { BasaltEvent, ChatTurnEnd, ChatTurnTrace, Telemetry, TraceHeaders } from './telemetry'
 export {
   defineNav,
   navGroup,