basalt-ui 1.22.0 → 1.23.1

package/src/charts/kinds/MirroredBars.tsx

@@ -0,0 +1,491 @@
+import { Group } from '@visx/group'
+import { scaleLinear } from '@visx/scale'
+import { memo, useMemo } from 'react'
+import type { ReactNode } from 'react'
+import { VX, alpha } from '../../tokens'
+import type { ChartMargin } from '../../tokens'
+import type { CursorResolution } from '../cursor/resolve'
+import { useBandPlot } from '../hooks/useBandPlot'
+import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot'
+import { probeAxisLabels } from '../layout/auto-margin'
+import { AxisBottomDate, AxisLeftNumeric } from '../primitives/Axes'
+import { ChartFrame, resolveLegend } from '../primitives/ChartFrame'
+import {
+  ChartTooltipFloat,
+  TooltipBody,
+  TooltipHeader,
+  TooltipRow,
+} from '../primitives/ChartTooltip'
+import { Crosshair } from '../primitives/Crosshair'
+import { HatchPattern, hatchFill, hatchSizeFor } from '../primitives/HatchPattern'
+import { HoverOverlay } from '../primitives/HoverOverlay'
+import { deriveTooltipRows } from '../series'
+import type { ChartLegendConfig, ChartSeries } from '../series'
+import { fmtAxisDate } from '../utils/format'
+
+/** One of the two panes. Each resolves its own domain — that is the whole point of the kind. */
+export type MirroredBarPane = {
+  /** Key of the `series` entry this pane draws: its colour, its legend entry, its tooltip row.
+   * A key naming no entry throws — see {@link assertPaneKey}. */
+  key: string
+  /**
+   * The pane's upper bound. `'auto'` (default) is its own visible maximum; a number pins it.
+   *
+   * A pane has no LOWER bound to configure — a mirrored bar's length is its magnitude measured
+   * from the shared baseline, so the pane's zero IS the baseline. That is also why the two panes
+   * never share a domain: an upload an order of magnitude below its download flattens to a line
+   * along the baseline on a shared scale, and it is the half that explains a stalled call.
+   */
+  max?: number | 'auto'
+  /** When `max` is `'auto'`: floors the upper bound, so a quiet window doesn't amplify noise to
+   * full height. */
+  autoMaxFloor?: number
+  /** Tick count for this pane's own axis. Default 3. */
+  ticks?: number
+  /** Tick + tooltip formatter for this pane. A pane's axis is in its OWN units — one shared
+   * formatter would be wrong for at least one of them whenever the two differ. */
+  format: (v: number) => string
+}
+
+export type MirroredBarsProps<T> = {
+  data: readonly T[]
+  chartId: string
+  /** Extracts the x-domain key — a slot start, hence the `'leading'` cursor default. */
+  getX: (d: T) => string
+  /**
+   * The single source of truth for bar colours, legend entries and tooltip rows. `up.key` and
+   * `down.key` name two of these; any further entry is legend-only (give it `getValue: () => null`)
+   * — which is how ABSENCE gets named, and it has to be: a hatched bar is the one mark on this
+   * chart a reader cannot decode from either axis.
+   */
+  series: readonly ChartSeries<T>[]
+  /** The pane drawn ABOVE the baseline. */
+  up: MirroredBarPane
+  /** The pane drawn BELOW the baseline. */
+  down: MirroredBarPane
+  /** The up pane's share of the bar band. Default 0.35 — the mirrored pair is usually asymmetric,
+   * and splitting evenly spends most of the chart on empty space above the smaller half. */
+  upFraction?: number
+  /**
+   * 0..1 of this bar's width no source sample covers, hatched across the FULL band height.
+   *
+   * Full height, both panes, deliberately: a hatch drawn on one pane only reads as "that half
+   * measured zero", which is the measured-and-idle state absence must stay distinguishable from.
+   */
+  getAbsentFraction?: (d: T) => number
+  /** Per-datum bar opacity — a real but qualified measurement (a short bucket, a partial interval)
+   * drawn dimmer. Default 1. */
+  getBarOpacity?: (d: T) => number
+  /** Fixed height in px, forwarded to `ChartFrame`. Default 240. */
+  height?: number
+  fill?: boolean
+  formatX?: (key: string) => string
+  xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[]
+  fold?: BandFold<T>
+  /** Default `'leading'` — see `BandStripProps.cursorResolution`. */
+  cursorResolution?: CursorResolution
+  tooltip?: BandTooltipConfig<T> | false
+  legend?: ChartLegendConfig | false
+  /** Series key whose colour the absence hatch is drawn in. Default `VX.neutral`. A key naming no
+   * `series` entry throws rather than falling back to the unnamed default. */
+  absentState?: string
+  margin?: Partial<ChartMargin>
+  ariaLabel?: string
+  isPending?: boolean
+}
+
+const DEFAULT_UP_FRACTION = 0.35
+const DEFAULT_PANE_TICKS = 3
+
+/**
+ * A pane key naming no `series` entry.
+ *
+ * This is `BandStrip`'s silent-drop bug in the shape this kind has: an unresolvable `up.key` left
+ * `upSeries` undefined, which made `upVisible` false, which hid the pane AND its axis — rendering
+ * as "that half measured nothing", the measured-and-idle state the whole kind exists to keep
+ * distinguishable from absence. Unlike `BandSpan.state`, a pane key is a PROP and never comes off a
+ * datum, so a typo can only ever be a wiring error: this throws in every environment, with no
+ * production fallback, because there is no honest way to draw a pane whose colour and legend entry
+ * do not exist.
+ */
+function assertPaneKey<T>(
+  side: 'up' | 'down',
+  key: string,
+  resolved: ChartSeries<T> | undefined,
+  series: readonly ChartSeries<T>[],
+): void {
+  if (resolved !== undefined) return
+  throw new Error(
+    `MirroredBars: ${side}.key "${key}" names no \`series\` entry ` +
+      `(known: ${series.map((s) => s.key).join(', ')}) — the pane would silently vanish, which ` +
+      'reads as a measured zero. Add the series, or point the pane at one that exists.',
+  )
+}
+
+/**
+ * Two bar panes over ONE x scale and one cursor, mirrored around a shared baseline, each in its
+ * own independent domain.
+ *
+ * **Why not `DualPanel`.** `DualPanel`'s two panes are a LINE pane and a signed-histogram pane: it
+ * requires `series` to be line series it draws with `LinePath`, and its bottom pane takes a single
+ * signed `getBar` over one symmetric `[-maxAbs, maxAbs]` scale. Neither half fits. Two independent
+ * magnitudes mirrored around a baseline are not one signed quantity — a 220 kB/s down and a 20 kB/s
+ * up are two readings, not `+220` and `−20` of one — and forcing them onto one scale is exactly the
+ * flattening this shape exists to avoid. Bending `DualPanel` to cover it would mean a
+ * `topMark: 'line' | 'bars'` switch, a second value accessor, and a per-pane domain law that
+ * contradicts its symmetric one: a fork of its internals wearing one name. It composes the same
+ * `useBandPlot` choreography instead, which is where the sharing actually belongs.
+ */
+function MirroredBarsInner<T>(props: MirroredBarsProps<T>) {
+  const { series, chartId, height, fill, legend, ariaLabel, isPending } = props
+
+  return (
+    <ChartFrame
+      series={series}
+      chartId={chartId}
+      {...(height !== undefined && { height })}
+      {...(fill !== undefined && { fill })}
+      {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
+      legend={resolveLegend(legend)}
+    >
+      {(plot) => <MirroredBarsPlot {...props} plot={plot} />}
+    </ChartFrame>
+  )
+}
+
+type MirroredBarsPlotProps<T> = MirroredBarsProps<T> & {
+  plot: { width: number; height: number; hidden: ReadonlySet<string> }
+}
+
+/** The measured plot — split so the scale/cursor hooks only run once `ChartFrame` has resolved a
+ * non-empty plot rect (parity with `DualPanel`). */
+function MirroredBarsPlot<T>(props: MirroredBarsPlotProps<T>) {
+  const {
+    data,
+    chartId,
+    getX,
+    series,
+    up,
+    down,
+    upFraction = DEFAULT_UP_FRACTION,
+    getAbsentFraction,
+    getBarOpacity,
+    formatX = fmtAxisDate,
+    xTickValues,
+    fold,
+    cursorResolution = 'leading',
+    tooltip,
+    absentState,
+    margin: marginOverride,
+    ariaLabel,
+    plot,
+  } = props
+
+  const { hidden } = plot
+  const seriesByKey = useMemo(() => new Map(series.map((s) => [s.key, s])), [series])
+  const upSeries = seriesByKey.get(up.key)
+  const downSeries = seriesByKey.get(down.key)
+  assertPaneKey('up', up.key, upSeries, series)
+  assertPaneKey('down', down.key, downSeries, series)
+  const upVisible = upSeries !== undefined && !hidden.has(up.key)
+  const downVisible = downSeries !== undefined && !hidden.has(down.key)
+
+  // ── Pass 1: the two domains and their tick labels, both independent of the pixel rect ────────
+  const upMax = usePaneMax(data, upSeries, up, upVisible)
+  const downMax = usePaneMax(data, downSeries, down, downVisible)
+  const upTicks = up.ticks ?? DEFAULT_PANE_TICKS
+  const downTicks = down.ticks ?? DEFAULT_PANE_TICKS
+
+  const leftLabels = useMemo(() => {
+    const labels: string[] = []
+    if (upVisible) {
+      labels.push(
+        ...probeAxisLabels({ domain: [0, upMax], ticks: upTicks, format: up.format }).labels,
+      )
+    }
+    if (downVisible) {
+      labels.push(
+        ...probeAxisLabels({ domain: [0, downMax], ticks: downTicks, format: down.format }).labels,
+      )
+    }
+    return labels
+  }, [upVisible, downVisible, upMax, downMax, upTicks, downTicks, up.format, down.format])
+
+  const band = useBandPlot<T>({
+    data,
+    chartId,
+    getX,
+    formatX,
+    width: plot.width,
+    cursorResolution,
+    leftLabels,
+    ...(fold !== undefined && { fold }),
+    ...(xTickValues !== undefined && { xTickValues }),
+    ...(marginOverride !== undefined && { margin: marginOverride }),
+    ...(tooltip !== undefined && { tooltip }),
+  })
+
+  const { bands, margin, plotWidth, scale, cursor, point, crosshairX, step, bandWidth } = band
+
+  // ── Pass 2: the pane rects, now that the plot height is known ───────────────────────────────
+  const barBand = Math.max(plot.height - margin.top - margin.bottom, 2)
+  const upHeight = Math.max(Math.round(barBand * upFraction), 1)
+  const downHeight = Math.max(barBand - upHeight, 1)
+  const baseline = upHeight
+
+  const upScale = useMemo(
+    () => scaleLinear<number>({ domain: [0, upMax], range: [0, upHeight] }),
+    [upMax, upHeight],
+  )
+  const downScale = useMemo(
+    () => scaleLinear<number>({ domain: [0, downMax], range: [0, downHeight] }),
+    [downMax, downHeight],
+  )
+  // The up AXIS reads top-to-bottom while the up BARS grow bottom-to-top, so its scale is the
+  // reverse of `upScale`. Same domain, same range — only the direction differs.
+  const upAxisScale = useMemo(
+    () => scaleLinear<number>({ domain: [upMax, 0], range: [0, upHeight] }),
+    [upMax, upHeight],
+  )
+
+  const hatchId = `${chartId}-mirrored-absent`
+  if (absentState !== undefined && !seriesByKey.has(absentState)) {
+    throw new Error(
+      `MirroredBars: absentState "${absentState}" names no \`series\` entry ` +
+        `(known: ${series.map((s) => s.key).join(', ')}) — the hatch would fall back to an unnamed ` +
+        'neutral, and a hatched bar is the one mark a reader cannot decode from either axis.',
+    )
+  }
+  const absentColor =
+    (absentState === undefined ? undefined : seriesByKey.get(absentState)?.color) ?? VX.neutral
+
+  const drawnUp = upVisible ? upSeries : undefined
+  const drawnDown = downVisible ? downSeries : undefined
+
+  const bars = useMemo<ReactNode[]>(() => {
+    const out: ReactNode[] = []
+    bands.forEach((d, i) => {
+      const x = i * step
+      const absent = clampFraction(getAbsentFraction?.(d))
+      const measuredWidth = bandWidth * (1 - absent)
+      const hatchWidth = bandWidth - measuredWidth
+      const opacity = getBarOpacity?.(d) ?? 1
+      // `Number.isNaN` as well as null: `deriveTooltipRows` skips only null, and a NaN reaching
+      // `scaleLinear` produces NaN `y`/`height` attributes — a bar that silently fails to paint
+      // while React logs a warning nobody reads. Same guard `DualPanel` applies to its line paths.
+      const upValue = finiteOrNull(drawnUp?.getValue(d))
+      const downValue = finiteOrNull(drawnDown?.getValue(d))
+      out.push(
+        <g key={getX(d)}>
+          {measuredWidth > 0 && drawnUp !== undefined && upValue !== null && (
+            <rect
+              x={x}
+              y={baseline - upScale(upValue)}
+              width={measuredWidth}
+              height={Math.max(upScale(upValue), upValue > 0 ? 1 : 0)}
+              fill={alpha(drawnUp.color, opacity)}
+              pointerEvents="none"
+            />
+          )}
+          {measuredWidth > 0 && drawnDown !== undefined && downValue !== null && (
+            <rect
+              x={x}
+              y={baseline}
+              width={measuredWidth}
+              height={Math.max(downScale(downValue), downValue > 0 ? 1 : 0)}
+              fill={alpha(drawnDown.color, opacity)}
+              pointerEvents="none"
+            />
+          )}
+          {hatchWidth > 0 && (
+            <rect
+              x={x + measuredWidth}
+              y={0}
+              width={hatchWidth}
+              height={barBand}
+              fill={hatchFill(hatchId)}
+              pointerEvents="none"
+            />
+          )}
+        </g>,
+      )
+    })
+    return out
+  }, [
+    bands,
+    step,
+    bandWidth,
+    barBand,
+    baseline,
+    getX,
+    getAbsentFraction,
+    getBarOpacity,
+    drawnUp,
+    drawnDown,
+    upScale,
+    downScale,
+    hatchId,
+  ])
+
+  if (plotWidth <= 0 || bands.length === 0) return null
+
+  const cfg = tooltip === false ? undefined : tooltip
+  const badge = cfg?.label === undefined || point === null ? null : cfg.label(point)
+  // Each pane's row falls back to ITS OWN axis formatter, never the other pane's — the two panes
+  // are in different units by construction (an explicit per-series `formatValue` still wins).
+  const visibleSeries = series
+    .filter((s) => !hidden.has(s.key))
+    .map((s) => {
+      if (s.formatValue !== undefined) return s
+      if (s.key === up.key) return { ...s, formatValue: (v: number) => up.format(v) }
+      if (s.key === down.key) return { ...s, formatValue: (v: number) => down.format(v) }
+      return s
+    })
+  const rows = point === null ? [] : deriveTooltipRows(visibleSeries, point, down.format)
+
+  return (
+    <>
+      <svg ref={band.svgRef} width={plot.width} height={plot.height}>
+        <defs>
+          <HatchPattern
+            id={hatchId}
+            color={absentColor}
+            opacity={0.7}
+            size={hatchSizeFor(bandWidth)}
+          />
+        </defs>
+        {/* theme-allow-file basalt/hand-rolled-plot — TWO bar panes over one x scale, in two
+            INDEPENDENT domains mirrored around a shared baseline. `CartesianChart`'s contract is a
+            single plot rect with one or two numeric y axes measured against the same marks, so it
+            cannot express two panes; `DualPanel` is the wrong shape for the reason this kind's own
+            docblock argues. Assembled from the SAME parts every other chart gets — `ChartFrame`,
+            `autoMargin`, `useChartCursor`, `ChartTooltipFloat` — through `useBandPlot`, shared with
+            `BandStrip` rather than copied from it. */}
+        <Group left={margin.left} top={margin.top}>
+          {bars}
+
+          {/* One axis per pane, each in its own scale's units — a single shared axis would be
+              wrong for at least one of them whenever the two domains differ, which is always. */}
+          {upVisible && (
+            <AxisLeftNumeric
+              scale={upAxisScale}
+              numTicks={upTicks}
+              tickFormat={(v) => up.format(Number(v))}
+            />
+          )}
+          {downVisible && (
+            <Group top={baseline}>
+              <AxisLeftNumeric
+                scale={downScale}
+                numTicks={downTicks}
+                tickFormat={(v) => down.format(Number(v))}
+              />
+            </Group>
+          )}
+
+          <line
+            x1={0}
+            x2={plotWidth}
+            y1={baseline}
+            y2={baseline}
+            stroke={VX.axisStroke}
+            strokeWidth={1}
+          />
+
+          {crosshairX !== null && <Crosshair x={crosshairX} top={0} bottom={barBand} />}
+
+          <AxisBottomDate
+            top={barBand}
+            scale={scale}
+            tickValues={band.tickValues}
+            tickFormat={(v) => formatX(String(v))}
+          />
+
+          <HoverOverlay
+            width={plotWidth}
+            height={barBand}
+            onMove={cursor.onPointerMove}
+            onLeave={cursor.onPointerLeave}
+            onKeyDown={cursor.onKeyDown}
+            onBlur={cursor.onBlur}
+            valueMax={Math.max(bands.length - 1, 0)}
+            {...(point !== null && {
+              valueNow: bands.indexOf(point),
+              valueText: formatX(getX(point)),
+            })}
+            {...(ariaLabel !== undefined && { ariaLabel })}
+          />
+        </Group>
+      </svg>
+
+      {band.showTooltip && point !== null && (
+        <ChartTooltipFloat anchor={band.tooltipAnchor} ariaLive={band.ariaLive}>
+          <TooltipHeader
+            date={getX(point)}
+            {...(cfg?.formatHeader !== undefined && {
+              format: (key: string) => cfg.formatHeader?.(key, point) ?? key,
+            })}
+            {...(badge !== null && { label: badge.text, labelColor: badge.color })}
+          />
+          <TooltipBody>
+            {cfg?.prependRows?.(point, { hidden })}
+            {rows.map((row) => (
+              <TooltipRow
+                key={row.key}
+                color={row.color}
+                label={row.label}
+                value={row.value}
+                shape={row.shape}
+                dashed={row.dashed}
+                {...(row.strokeWidth !== undefined && { strokeWidth: row.strokeWidth })}
+              />
+            ))}
+            {cfg?.extraRows?.(point, { hidden })}
+          </TooltipBody>
+        </ChartTooltipFloat>
+      )}
+    </>
+  )
+}
+
+/** A 0..1 share, non-finite included — see `BandStrip`'s identical guard. */
+function clampFraction(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return 0
+  return Math.min(Math.max(value, 0), 1)
+}
+
+/** A drawable value, or null. See the call site for why NaN is not drawable. */
+function finiteOrNull(v: number | null | undefined): number | null {
+  return v === null || v === undefined || Number.isNaN(v) ? null : v
+}
+
+/**
+ * One pane's upper bound. `|| 1` guards a window with no traffic at all — a zero-width domain
+ * renders as NaN geometry rather than as an empty chart.
+ */
+function usePaneMax<T>(
+  data: readonly T[],
+  paneSeries: ChartSeries<T> | undefined,
+  pane: MirroredBarPane,
+  visible: boolean,
+): number {
+  return useMemo(() => {
+    if (pane.max !== undefined && pane.max !== 'auto') return pane.max || 1
+    if (!visible || paneSeries === undefined) return 1
+    let max = 0
+    for (const d of data) {
+      const v = paneSeries.getValue(d)
+      if (v === null || Number.isNaN(v)) continue
+      if (v > max) max = v
+    }
+    const floored = pane.autoMaxFloor === undefined ? max : Math.max(max, pane.autoMaxFloor)
+    return floored || 1
+  }, [data, paneSeries, pane.max, pane.autoMaxFloor, visible])
+}
+
+/**
+ * Hand-memoized: React Compiler does not process the shipped dist, so the hot kind is wrapped in
+ * `React.memo` to retain the auto-memoization it had as source (parity with `DualPanel`).
+ */
+export const MirroredBars = memo(MirroredBarsInner) as typeof MirroredBarsInner

package/src/charts/kinds/MultiLine.tsx

@@ -34,8 +34,12 @@ export type MultiLineProps<T> = {
   xZones?: XZoneSpec[]
   /** Horizontal reference lines. Solid by default; set dashed: true for a dashed line. */
   refLines?: { value: number; color: string; dashed?: boolean }[]
-  /** Exact number of x ticks. Default: as many as fit. */
+  /** Exact number of x ticks. Default: as many as fit. Ignored when `xTickValues` is set. */
   xTicks?: number
+  /** Which domain keys get a tick, from the full key list and the resolved plot width. Takes
+   * precedence over `xTicks` — see `CartesianChartProps.xTickValues` for why a count is not
+   * always enough. */
+  xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
   /**
@@ -109,6 +113,7 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
     xZones,
     refLines,
     xTicks,
+    xTickValues,
     formatX,
     cursorResolution,
     tooltip,
@@ -138,6 +143,7 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
       {...(xZones !== undefined && { xZones })}
       {...(refLines !== undefined && { refLines })}
       {...(xTicks !== undefined && { xTicks })}
+      {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(tooltip !== undefined && { tooltip })}

package/src/charts/kinds/StackedArea.tsx

@@ -20,8 +20,12 @@ export type StackedAreaProps<T> = {
    * chart needs, since the plotted quantity is the cumulative band top, not any one series' own
    * value. Pass a fixed tuple or your own function to override. */
   y?: AxisConfig<T>
-  /** X tick count override. Default: as many as fit. */
+  /** Exact number of x ticks. Default: as many as fit. Ignored when `xTickValues` is set. */
   xTicks?: number
+  /** Which domain keys get a tick, from the full key list and the resolved plot width. Takes
+   * precedence over `xTicks` — see `CartesianChartProps.xTickValues` for why a count is not
+   * always enough. */
+  xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
   /**
@@ -60,6 +64,7 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
     series,
     y,
     xTicks,
+    xTickValues,
     formatX,
     cursorResolution,
     height,
@@ -121,6 +126,7 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
       y={yConfig}
       cursorValue={stackedCursorValue}
       {...(xTicks !== undefined && { xTicks })}
+      {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(height !== undefined && { height })}

package/src/charts/kinds/ZonedLine.tsx

@@ -50,8 +50,12 @@ export type ZonedLineProps<T> = {
   xZones?: XZoneSpec[]
   thresholds?: ZonedLineThreshold[]
   refLines?: ZonedLineRefLine[]
-  /** Exact number of x ticks. Default: as many as fit. */
+  /** Exact number of x ticks. Default: as many as fit. Ignored when `xTickValues` is set. */
   xTicks?: number
+  /** Which domain keys get a tick, from the full key list and the resolved plot width. Takes
+   * precedence over `xTicks` — see `CartesianChartProps.xTickValues` for why a count is not
+   * always enough. */
+  xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
   /**
@@ -119,6 +123,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
     thresholds,
     refLines,
     xTicks,
+    xTickValues,
     formatX,
     cursorResolution,
     tooltip,
@@ -151,6 +156,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
       {...(xZones !== undefined && { xZones })}
       {...(refLines !== undefined && { refLines })}
       {...(xTicks !== undefined && { xTicks })}
+      {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(tooltip !== undefined && { tooltip })}

package/src/charts/primitives/CartesianChart.test.tsx

@@ -1,4 +1,4 @@
-import { fireEvent, render, screen, within } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { ChartCursorScope } from '../cursor/scope'
@@ -389,10 +389,18 @@ describe('tooltip.onFollow — aria-live stays SOURCE-only', () => {
     )
 
     fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
-    await screen.findByText('b')
 
-    const tooltips = screen.getAllByRole('tooltip')
-    expect(tooltips).toHaveLength(2)
+    // The FOLLOWER anchors synchronously off its own svg rect, so its tooltip is in the DOM on the
+    // tick the broadcast lands. The SOURCE positions against `cursor.anchor`, which
+    // `useChartCursor` deliberately coalesces through `requestAnimationFrame` — one frame later.
+    // So waiting on the follower's 'b' is no barrier at all for the source tooltip: that only ever
+    // held because happy-dom mocks rAF with `setImmediate`, which usually — not reliably — lands
+    // before Testing Library's async drain. Wait for the PAIR, which is what's being asserted.
+    const tooltips = await waitFor(() => {
+      const found = screen.getAllByRole('tooltip')
+      expect(found).toHaveLength(2)
+      return found
+    })
     const sourceTooltip = tooltips.find((t) => within(t).queryByText('a') !== null)
     const followerTooltip = tooltips.find((t) => within(t).queryByText('b') !== null)
     expect(sourceTooltip?.getAttribute('aria-live')).toBe('polite')
@@ -439,3 +447,77 @@ describe('tooltip.onFollow — a follower whose domain never resolves the broadc
     expect(screen.queryAllByRole('tooltip')).toHaveLength(1)
   })
 })
+
+/**
+ * `xTickValues` — the seam a tick COUNT cannot express.
+ *
+ * `smartTicks`/`smartTicksEvery` append the final key unconditionally, so when the step misses the
+ * last index that appended tick lands a partial step from its neighbour and two rich labels print
+ * on top of each other at the right edge. No count fixes that; only choosing the VALUES does. It is
+ * the same prop `BandStrip`/`MirroredBars` take, so the seam does not fork by kind.
+ */
+describe('CartesianChart — xTickValues', () => {
+  const many: Row[] = Array.from({ length: 12 }, (_, i) => ({
+    date: `2026-08-${String(i + 1).padStart(2, '0')}`,
+    a: i,
+    b: i,
+  }))
+
+  const axisText = (markup: string): string =>
+    (/<g class="visx-axis-bottom[\s\S]*?<\/g><\/g>/.exec(markup)?.[0] ?? markup).replace(
+      /<[^>]+>/g,
+      ' ',
+    )
+
+  const renderWith = (props: Partial<Parameters<typeof CartesianChart<Row>>[0]>): string =>
+    renderToStaticMarkup(
+      <CartesianChart<Row>
+        data={many}
+        chartId="ctv"
+        getX={(d) => d.date}
+        series={[seriesFor('a')]}
+        legend={false}
+        formatX={(key) => key}
+        {...props}
+      >
+        {() => null}
+      </CartesianChart>,
+    )
+
+  test('picks exactly the keys the callback returns, and is handed the width to pick from', () => {
+    const seen: { count: number; width: number }[] = []
+    const markup = renderWith({
+      xTickValues: (keys, xMax) => {
+        seen.push({ count: keys.length, width: xMax })
+        return ['2026-08-02', '2026-08-07']
+      },
+    })
+    // Every key reaches the callback, alongside the plot width the chart already measured —
+    // which is the second half of the seam: no `useChartSize` box outside the chart.
+    expect(seen[0]?.count).toBe(12)
+    expect(seen[0]?.width).toBeGreaterThan(0)
+
+    const text = axisText(markup)
+    expect(text).toContain('2026-08-02')
+    expect(text).toContain('2026-08-07')
+    // ...and nothing else. A count could never have produced this pair.
+    expect(text).not.toContain('2026-08-01')
+    expect(text).not.toContain('2026-08-12')
+  })
+
+  test('takes precedence over xTicks, which keeps working on its own', () => {
+    const both = axisText(renderWith({ xTicks: 6, xTickValues: () => ['2026-08-05'] }))
+    expect(both).toContain('2026-08-05')
+    expect(both).not.toContain('2026-08-01')
+
+    // The count form is untouched: `smartTicksEvery` still appends the final key.
+    const countOnly = axisText(renderWith({ xTicks: 3 }))
+    expect(countOnly).toContain('2026-08-01')
+    expect(countOnly).toContain('2026-08-12')
+  })
+
+  test('returning no values draws a bare axis rather than falling back to smartTicks', () => {
+    const text = axisText(renderWith({ xTickValues: () => [] }))
+    expect(text).not.toContain('2026-08-')
+  })
+})