basalt-ui 2.3.0 → 2.4.0

package/dist/state/fields.js

@@ -205,14 +205,14 @@ function assignDefined(into, from) {
     if (value !== void 0) into[key] = value;
   }
 }
-function resolveField(entry, search, record) {
+function resolveField(entry, search, record, fallback) {
   const fromUrl = search === null ? null : entry.codec.fromSearch(search);
   if (fromUrl !== null) return fromUrl;
   if (entry.codec.lane.persist) {
     const stored = entry.codec.decode(record[entry.name]);
     if (stored !== null) return stored;
   }
-  return entry.codec.fallback;
+  return fallback === void 0 ? entry.codec.fallback : fallback;
 }
 function createMemoryLane() {
   const values = /* @__PURE__ */ new Map();
@@ -232,9 +232,10 @@ function createMemoryLane() {
     getVersion: () => version,
     // `undefined` is the only "never written" marker the lane needs: no field kind has `undefined`
     // as a legal value, so it can never collide with a written one.
-    resolve: (entry) => {
+    resolve: (entry, fallback) => {
       const stored = values.get(entry.name);
-      return stored === void 0 ? entry.codec.fallback : stored;
+      if (stored !== void 0) return stored;
+      return fallback === void 0 ? entry.codec.fallback : fallback;
     },
     write: (name, value) => {
       values.set(name, value);
@@ -342,9 +343,12 @@ function createStoreCore(o) {
     },
     readRecord,
     memoryUse(entry) {
-      return () => {
+      return (read) => {
         useSyncExternalStore(memory.subscribe, memory.getVersion, memory.getVersion);
-        return [memory.resolve(entry), (next) => memory.write(entry.name, next)];
+        return [
+          memory.resolve(entry, read?.fallback),
+          (next) => memory.write(entry.name, next)
+        ];
       };
     },
     readMemoryValue: (entry) => memory.resolve(entry),
@@ -374,10 +378,12 @@ function createStoreCore(o) {
 }
 function createLocalStore(o) {
   const core = createStoreCore({ key: o.key, fields: o.fields, version: o.version });
-  const persistedUse = (entry) => () => {
+  const persistedUse = (entry) => (read) => {
     const [record, setRecord] = core.usePersistedRecord();
     return [
-      core.resolve(entry, null, record),
+      // The call-site fallback is applied here, in render, after the store read — never inside
+      // the snapshot — so React's out-of-render snapshot reads cannot disagree with it.
+      core.resolve(entry, null, record, read?.fallback),
       (next) => core.writeField(setRecord, entry.name, next)
     ];
   };

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.3.0
+# basalt-ui v2.4.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,7 +13,7 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.3.0
+Version: 2.4.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets",
   "keywords": [
     "charts",

package/src/charts/CartesianChart.tsx

@@ -9,7 +9,7 @@
 import { useCallback, useId, useMemo, useState } from 'react'
 import type { CSSProperties, ReactElement, ReactNode } from 'react'
 import { useInChartCard } from './card-context'
-import { compileCartesian } from './compile'
+import { compileCartesian, refLegendSeries } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { ChartLegend, legendEntries } from './legend'
@@ -170,9 +170,14 @@ export function CartesianRung<T, X extends ChartX>(
     (ctx: ShellContext) => compileCartesian({ ...stable, ...ctx }),
     [stable],
   )
+  // Reference lines that name themselves join the legend after the series (role `reference`).
+  const legendSeries = useMemo(
+    () => [...stable.series, ...refLegendSeries<T>(stable.refLines)],
+    [stable.series, stable.refLines],
+  )
   return (
     <ChartShell
-      series={series}
+      series={legendSeries}
       compile={compile}
       ariaLabel={ariaLabel}
       {...(legend !== undefined && { legend })}

package/src/charts/DualPanel.tsx

@@ -14,7 +14,7 @@ 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 { defaultFormatX, defaultNumberFormat, engineRow, seriesRow, 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'
@@ -61,8 +61,10 @@ export type DualPanelBar<T> = {
   positive: string
   /** The fill below zero. */
   negative: string
-  /** Tick and tooltip formatter. */
+  /** Tick formatter, and the tooltip's too unless `tooltipFormat` is given. */
   format: (v: number) => string
+  /** The tooltip row's formatter. Default: `format`. */
+  tooltipFormat?: ((v: number) => string) | undefined
   /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
   formatValue?: ((v: number, d: T) => string) | undefined
   /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
@@ -95,6 +97,8 @@ export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
     | {
         domain?: readonly [number, number] | 'auto' | undefined
         format?: ((v: number) => string) | undefined
+        /** The lines' tooltip formatter. Default: `format`. */
+        tooltipFormat?: ((v: number) => string) | undefined
       }
     | undefined
   /**
@@ -157,6 +161,8 @@ export function DualPanel<T, X extends Date | number = Date | number>(
   )
   const all = useMemo(() => [...lines, barSeries], [lines, barSeries])
   const topFormat = top?.format ?? defaultNumberFormat
+  const topTooltipFormat = top?.tooltipFormat ?? topFormat
+  const barTooltipFormat = bar.tooltipFormat ?? bar.format
 
   const plan = useCallback(
     ({ hidden, highlighted }: PanelInput): PanelPlan<T> => {
@@ -307,26 +313,42 @@ export function DualPanel<T, X extends Date | number = Date | number>(
           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 }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : topTooltipFormat(v),
+                highlighted === s.key,
+              ),
+            )
           }
           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 }),
-            })
+            out.push(
+              engineRow({
+                label: bar.label,
+                value: bar.formatValue ? bar.formatValue(v, d) : barTooltipFormat(v),
+                color: v >= 0 ? bar.positive : bar.negative,
+                active: highlighted === BAR_KEY,
+              }),
+            )
           return out
         },
       }
     },
-    [data, x, lines, barSeries, top, fillBetween, bar, topFraction, topFormat, formatX],
+    [
+      data,
+      x,
+      lines,
+      barSeries,
+      top,
+      fillBetween,
+      bar,
+      topFraction,
+      topFormat,
+      topTooltipFormat,
+      barTooltipFormat,
+      formatX,
+    ],
   )
 
   return <PanelRung {...rung} series={all} plan={plan} />

package/src/charts/Heatmap.tsx

@@ -18,7 +18,7 @@ import type { CSSProperties, ReactElement } from 'react'
 import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { strideTicks } from './compile'
+import { engineRow, strideTicks } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { useCoarsePointer } from '../common/use-media-query'
@@ -244,7 +244,7 @@ export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
                         ...(point.color && { color: point.color }),
                       },
                     ]
-              return { title: header(c), rows: [...value, ...extra] }
+              return { title: header(c), rows: [...value, ...extra].map(engineRow) }
             },
           }
         : false,

package/src/charts/Lines.tsx

@@ -17,7 +17,7 @@ import { VX } from '../tokens'
 import { CartesianRung } from './CartesianChart'
 import { areaGradientId } from './compile'
 import { chartCurve } from './curves'
-import { lineMark, markersOf, yScaleOf } from './marks'
+import { drawnRows, lineMark, markersOf, yScaleOf } from './marks'
 import { rowX } from './types'
 import type {
   CartesianChartProps,
@@ -120,7 +120,7 @@ export function Lines<T, X extends ChartX = ChartX>(props: LinesProps<T, X>): Re
         if (!s.area) continue
         out.push(
           decorative(
-            areaY(plot.rows(s.key), {
+            areaY(drawnRows(plot, s), {
               id: `${s.key}-area`,
               x: rowX,
               y2: 'y',

package/src/charts/MirroredBars.tsx

@@ -21,7 +21,7 @@ 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 { defaultFormatX, defaultNumberFormat, seriesRow, visibleSeries } from './compile'
 import { barMark, emphasis } from './marks'
 import { PanelRung, paneX, paneY, rowsOf } from './panel'
 import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
@@ -277,12 +277,13 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
             // Each pane's row falls back to ITS OWN formatter: the panes are in different units.
             const fallback =
               s.key === up.key ? up.format : s.key === down.key ? down.format : defaultNumberFormat
-            out.push({
-              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-              value: s.formatValue ? s.formatValue(v, d) : fallback(v),
-              color: s.color,
-              ...(highlighted === s.key && { active: true }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : fallback(v),
+                highlighted === s.key,
+              ),
+            )
           }
           return out
         },

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,8 @@ import type {
   ChartTooltipRow,
   ChartX,
   PlotRow,
+  RefLine,
+  ZoneEdge,
   ZoneSpec,
 } from './types'
 
@@ -136,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>[],
@@ -435,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] }], {
@@ -474,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]
@@ -484,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: {
@@ -568,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>
@@ -599,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))
@@ -625,6 +792,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,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/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