basalt-ui 1.16.0 → 1.18.0

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

@@ -1,6 +1,7 @@
-import { fireEvent, render, screen } from '@testing-library/react'
+import { fireEvent, render, screen, within } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'
+import { ChartCursorScope } from '../cursor/scope'
 import type { ChartSeries } from '../series'
 import { CartesianChart, resolveAxisDomain } from './CartesianChart'
 
@@ -44,9 +45,27 @@ describe('resolveAxisDomain', () => {
     expect(min).toBeLessThanOrEqual(-40)
   })
 
-  test('autoMaxFloor raises a low upper bound', () => {
+  test('autoMaxFloor raises a low upper bound, then pads it (mirrors autoMinCeil)', () => {
+    // The floor clamps the RAW upper bound first (44 -> 500), padding applies after: 500 * 1.1.
     const [, max] = resolveAxisDomain({ autoMaxFloor: 500 }, rows, both)
-    expect(max).toBe(500)
+    expect(max).toBeCloseTo(550, 5)
+  })
+
+  test('autoMaxFloor at exactly the padded case (dataMax 3.2, pad 1.1, floor 6) yields 6.6', () => {
+    const single: ChartSeries<Row>[] = [{ ...seriesFor('a'), getValue: () => 3.2 }]
+    const [, max] = resolveAxisDomain({ autoMaxFloor: 6, autoPad: 1.1 }, rows, single)
+    expect(max).toBeCloseTo(6.6, 5)
+  })
+
+  test('autoMaxFloor and autoMinCeil pad symmetrically — both clamp first, pad second', () => {
+    // Upper: floor 6 clamps 3.2 -> 6, then pads to 6.6 (multiply, away from zero).
+    const positive: ChartSeries<Row>[] = [{ ...seriesFor('a'), getValue: () => 3.2 }]
+    const [, max] = resolveAxisDomain({ autoMaxFloor: 6, autoPad: 1.1 }, rows, positive)
+    expect(max).toBeCloseTo(6.6, 5)
+    // Lower: ceil -6 clamps -3.2 -> -6, then pads to -6.6 (multiply, away from zero) — the mirror.
+    const negative: ChartSeries<Row>[] = [{ ...seriesFor('a'), getValue: () => -3.2 }]
+    const [min] = resolveAxisDomain({ autoMinCeil: -6, autoPad: 1.1 }, rows, negative)
+    expect(min).toBeCloseTo(-6.6, 5)
   })
 
   test('the domain follows the VISIBLE series — hiding the tall one shrinks the axis', () => {
@@ -69,6 +88,33 @@ describe('resolveAxisDomain', () => {
   })
 })
 
+describe('resolveAxisDomain — autoMaxFloor composed with an all-negative series', () => {
+  // getValue -> -d.a - 20 over rows a=[10, 40, 25] yields [-30, -60, -45]: data max is -30, data
+  // min is -60 — deliberately NOT a flat series, so this exercises the real clamp-then-pad path
+  // rather than the degenerate flat-collapse branch covered separately below.
+  const allNegative: ChartSeries<Row>[] = [{ ...seriesFor('a'), getValue: (d) => -d.a - 20 }]
+
+  test('a floor above the data max clamps to the floor, then pads TOWARD zero', () => {
+    const [, max] = resolveAxisDomain({ autoMaxFloor: -10 }, rows, allNegative)
+    // clamp: Math.max(-30, -10) = -10; padAutoUpper divides for a negative candidate (toward zero).
+    expect(max).toBeCloseTo(-10 / 1.1, 10)
+  })
+
+  test('without a floor, the existing all-negative behavior is unchanged', () => {
+    const [, max] = resolveAxisDomain(undefined, rows, allNegative)
+    // no floor -> candidate stays the raw data max, -30.
+    expect(max).toBeCloseTo(-30 / 1.1, 10)
+  })
+
+  test('autoMaxFloor / autoMinCeil clamp-then-pad symmetrically through resolveAxisDomain', () => {
+    // Mirror series: same magnitudes, positive instead of negative (data min 30, not data max -30).
+    const allPositive: ChartSeries<Row>[] = [{ ...seriesFor('a'), getValue: (d) => d.a + 20 }]
+    const [, maxFromFloor] = resolveAxisDomain({ autoMaxFloor: -10 }, rows, allNegative)
+    const [minFromCeil] = resolveAxisDomain({ autoMinCeil: 10 }, rows, allPositive)
+    expect(maxFromFloor).toBeCloseTo(-minFromCeil, 10)
+  })
+})
+
 describe('resolveAxisDomain — overlay bounds', () => {
   test('a zone past the data stretches the axis instead of clipping', () => {
     const [, max] = resolveAxisDomain(undefined, rows, both, [0, 200])
@@ -127,6 +173,69 @@ describe('AxisConfig.nice — threaded to BOTH the probe and the real scale', ()
   })
 })
 
+describe('cursorResolution — threads through to sibling resolution (CartesianChart)', () => {
+  // Daily calendar Aug 01–14, plus a sibling folded into 2 weekly buckets keyed by each week's
+  // leading day (Aug 01, Aug 08) — the exact shape of the playground's "Weekly digest" pairing.
+  const dailyRows: Row[] = Array.from({ length: 14 }, (_, i) => ({
+    date: `2026-08-${String(i + 1).padStart(2, '0')}`,
+    a: i,
+    b: i,
+  }))
+  const foldedRows: Row[] = [
+    { date: '2026-08-01', a: 0, b: 0 },
+    { date: '2026-08-08', a: 1, b: 1 },
+  ]
+
+  function renderPair(cursorResolution?: 'leading') {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={dailyRows}
+          chartId="daily"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Daily"
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={foldedRows}
+          chartId="folded"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Folded"
+          {...(cursorResolution !== undefined && { cursorResolution })}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+  }
+
+  // Drives the daily chart to Aug 05 — the back half of the Aug 01–07 bucket (its midpoint is
+  // Aug 04) — via 5 keyboard ArrowRights from an unfocused slider (1st press lands on index 0).
+  function driveDailyToAug05() {
+    const dailySlider = screen.getByRole('slider', { name: 'Daily' })
+    for (let i = 0; i < 5; i++) fireEvent.keyDown(dailySlider, { key: 'ArrowRight' })
+  }
+
+  test("cursorResolution='leading' resolves the back-half day to the bucket it's INSIDE, not the following one", () => {
+    renderPair('leading')
+    driveDailyToAug05()
+    const foldedSlider = screen.getByRole('slider', { name: 'Folded' })
+    // Aug 05 is inside the Aug01-07 bucket — 'leading' must resolve to its leading key, Aug 01.
+    expect(foldedSlider.getAttribute('aria-valuetext')).toBe('01.08')
+  })
+
+  test("without the prop (default 'nearest'), the same daily hover lands on the FOLLOWING bucket — proves cursorResolution actually threads through, not just the resolver it wraps", () => {
+    renderPair()
+    driveDailyToAug05()
+    const foldedSlider = screen.getByRole('slider', { name: 'Folded' })
+    // Aug 05 is closer to Aug 08 (distance 3) than Aug 01 (distance 4) — 'nearest' picks Aug 08.
+    expect(foldedSlider.getAttribute('aria-valuetext')).toBe('08.08')
+  })
+})
+
 describe('tooltip extraRows — ctx.visible/ctx.hidden track legend toggling', () => {
   test('toggling a series off via its legend entry updates the ctx the row reads', async () => {
     render(
@@ -158,3 +267,175 @@ describe('tooltip extraRows — ctx.visible/ctx.hidden track legend toggling', (
     expect((await screen.findByTestId('extra-ctx')).textContent).toContain('visible:a|hidden:b')
   })
 })
+
+describe('tooltip.onFollow — the follower renders when a SIBLING owns the cursor', () => {
+  function renderPair(onFollow?: boolean) {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="of-source"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="of-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, ...(onFollow !== undefined && { onFollow }) }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+  }
+
+  test('onFollow: true renders the follower tooltip rows while the source owns the cursor', async () => {
+    renderPair(true)
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    expect(await screen.findByText('b')).toBeTruthy()
+  })
+
+  test('without onFollow (default false), the follower renders no tooltip at all', async () => {
+    renderPair()
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    // The SOURCE still renders its own tooltip ('a') — only the follower ('b') stays silent.
+    expect(await screen.findByText('a')).toBeTruthy()
+    expect(screen.queryByText('b')).toBeNull()
+    expect(screen.queryAllByRole('tooltip')).toHaveLength(1)
+  })
+
+  // `follow` is deliberately left at its default (true, pointer-tracking) here — unlike every
+  // other case in this file, which hardcodes `follow: false` on the follower. That hardcoding
+  // means `useAnchoredPosition`'s FIRST clause (`tooltipCfg?.follow === false`) always already
+  // satisfies the anchored branch, so those tests can't tell `|| isFollowerRender` apart from a
+  // no-op. With `follow` left at its pointer-tracking default, anchoring can only come from
+  // `isFollowerRender` — and a follower's own `cursor.anchor` (set only by pointer/keyboard
+  // events ON THIS CHART, never by a sibling's) stays null for the whole test, since only the
+  // SOURCE is ever interacted with. So: `isFollowerRender` present → anchored position resolves
+  // from the crosshair and the tooltip mounts; `isFollowerRender` absent → the pointer-tracking
+  // branch falls through to the follower's own (never-set) `cursor.anchor`, which is null, and
+  // `ChartTooltipFloat` renders nothing at all for a null anchor. Presence/absence of the
+  // follower tooltip is what's observable here — happy-dom zeroes every `getBoundingClientRect`,
+  // so the anchor's actual pixel coordinates can't discriminate the two branches.
+  test('onFollow: true with follow left at its pointer-tracking default still anchors to the crosshair', async () => {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="of-anchor-source"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="of-anchor-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    expect(await screen.findByText('b')).toBeTruthy()
+  })
+})
+
+describe('tooltip.onFollow — aria-live stays SOURCE-only', () => {
+  test('the source tooltip is aria-live; the follower tooltip is not', async () => {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="al-source"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="al-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+    await screen.findByText('b')
+
+    const tooltips = screen.getAllByRole('tooltip')
+    expect(tooltips).toHaveLength(2)
+    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')
+    expect(followerTooltip?.hasAttribute('aria-live')).toBe(false)
+  })
+})
+
+describe('tooltip.onFollow — a follower whose domain never resolves the broadcast key renders nothing', () => {
+  test('an unrelated calendar stays silent, not an empty tooltip shell', async () => {
+    const foreignRows: Row[] = [{ date: '2027-01-15', a: 99, b: 99 }]
+
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="unres-source"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={foreignRows}
+          chartId="unres-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    // The SOURCE still renders its own tooltip — only the follower with no resolvable point stays
+    // silent, rather than mounting an empty tooltip shell.
+    expect(await screen.findByText('a')).toBeTruthy()
+    expect(screen.queryByText('b')).toBeNull()
+    expect(screen.queryAllByRole('tooltip')).toHaveLength(1)
+  })
+})

package/src/charts/primitives/CartesianChart.tsx

@@ -5,11 +5,12 @@ import { useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
+import type { CursorResolution } from '../cursor/resolve'
 import { useChartCursor } from '../hooks/useChartCursor'
 import { autoMargin, probeAxisLabels } from '../layout/auto-margin'
 import { deriveTooltipRows } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
-import { padAutoLower } from '../utils/domain'
+import { padAutoLower, padAutoUpper } from '../utils/domain'
 import { fmtAxisDate } from '../utils/format'
 import { smartTicks, smartTicksEvery } from '../utils/ticks'
 import { AxisBottomDate, AxisLeftNumeric, AxisRightNumeric } from './Axes'
@@ -41,7 +42,11 @@ export type AxisConfig<T> = {
     | [number, number]
     | 'auto'
     | ((data: readonly T[], visible: readonly ChartSeries<T>[]) => [number, number])
-  /** When 'auto': the upper bound is at least this. */
+  /**
+   * When 'auto': the raw upper bound is at least this, and padding is applied AFTER — mirroring
+   * `autoMinCeil`, which clamps first and pads second. A floor that padded before the clamp used
+   * to land the axis top exactly on the floor value with zero headroom.
+   */
   autoMaxFloor?: number
   /** When 'auto': the lower bound is at most this. Default 0 (forced zero baseline). `Infinity`
    * pads down from the raw data minimum instead. */
@@ -82,12 +87,37 @@ export type CartesianTooltipConfig<T> = {
   follow?: boolean
   /** Right-aligned badge in the tooltip header (e.g. a status label). */
   label?: (d: T) => { text: string; color: string } | null
+  /**
+   * Overrides the tooltip header's date text. Default: `TooltipHeader`'s own `fmtTooltipDate`
+   * behavior, unchanged. `fmtTooltipDate` regexes `YYYY-MM-DD` out of the domain key and builds a
+   * LOCAL `Date` from it — a UTC ISO key then names the wrong day next to `formatX`, the tooltip
+   * badge, and every sibling chart, which all resolve locally. Receives the raw `getX` key
+   * alongside the hovered datum, so a caller can format from either.
+   */
+  formatHeader?: (key: string, d: T) => string
   /** Rows rendered BEFORE the derived per-series rows (a total, a context line). The second
    * argument carries the same `visible`/`hidden` the plot draws from, so a hand-authored row
    * stays in sync with legend toggling instead of naming a series the plot no longer draws. */
   prependRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
   /** Rows appended after the derived per-series rows. Same `ctx` as {@link prependRows}. */
   extraRows?: (d: T, ctx: CartesianTooltipRowContext<T>) => ReactNode
+  /**
+   * Render this chart's tooltip when it is a cursor FOLLOWER (the crosshair came from a sibling
+   * chart sharing the cursor), not only when this chart is the SOURCE. Default false — today's
+   * behaviour, nothing moves. A follower has no pointer under it, so its tooltip is always ANCHORED
+   * to the crosshair — the same positioning `follow: false` gives the source — regardless of what
+   * `follow` is set to on this chart: there is no other valid position for a chart nobody is
+   * hovering. `follow` keeps governing the SOURCE's own tooltip exactly as before; the two options
+   * only interact for a follower, where `onFollow` always wins on positioning. Only the SOURCE's
+   * tooltip is `aria-live` — followers announce nothing, so a shared-cursor page doesn't fire N
+   * live-region updates per pointer move.
+   *
+   * Cost, since it scales with the page rather than the chart: anchoring reads one
+   * `getBoundingClientRect` per hovered frame (the same cost `follow: false` documents), so N
+   * opted-in followers pay N of them per frame. That is the reason this is opt-in per chart rather
+   * than a page-level switch — turn it on for the charts a reader actually correlates.
+   */
+  onFollow?: boolean
 }
 
 /** Everything a mark renderer needs. Handed to `CartesianChart`'s child on every render. */
@@ -149,6 +179,14 @@ export type CartesianChartProps<T> = {
     series: ChartSeries<T>,
     visible: readonly ChartSeries<T>[],
   ) => number | null
+  /**
+   * How a sibling chart's broadcast cursor key resolves against THIS chart's points. Default
+   * `'nearest'`, correct when `getX` returns an instant. Pass `'leading'` when it returns a
+   * bucket's leading edge (a weekly series keyed by its Monday): under `'nearest'` a hover landing
+   * in the back half of a bucket resolves to the FOLLOWING bucket, so the shared crosshair sits
+   * one column right of the data the reader is pointing at.
+   */
+  cursorResolution?: CursorResolution
   ariaLabel?: string
   isPending?: boolean
   /** Draw ONLY the marks. Everything around them is the primitive's job. */
@@ -196,11 +234,10 @@ export function resolveAxisDomain<T>(
 
   const pad = cfg?.autoPad ?? DEFAULT_AUTO_PAD
   const ceil = cfg?.autoMinCeil ?? 0
-  // Pad AWAY from zero, never by multiplying: `max * pad` on an all-negative series moves the
-  // upper bound further negative (`-5 * 1.1 = -5.5`), i.e. past the data, clipping the largest
-  // value out of the plot. Mirrors `padAutoLower`'s reasoning for the lower bound.
-  const paddedMax = max > 0 ? max * pad : max < 0 ? max / pad : 0
-  const upper = Math.max(paddedMax, cfg?.autoMaxFloor ?? -Infinity)
+  // Symmetric with the lower bound: clamp the RAW value against the floor/ceiling first, then pad
+  // once, away from zero. Padding before the clamp (the old law) lands a floored axis top exactly
+  // on the floor with zero headroom — a target line pinned there sits glued to the plot edge.
+  const upper = padAutoUpper(Math.max(max, cfg?.autoMaxFloor ?? -Infinity), pad)
   const lower = padAutoLower(Math.min(min, ceil), pad)
   // A flat series (every value identical, the all-zero case included) collapses to `[n, n]`,
   // which is a scale with no extent: every point maps to the same pixel and the line renders as a
@@ -241,6 +278,7 @@ export function CartesianChart<T>({
   tooltip,
   margin: marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   isPending,
   children,
@@ -274,6 +312,7 @@ export function CartesianChart<T>({
           {...(tooltip !== undefined && { tooltip })}
           {...(marginOverride !== undefined && { marginOverride })}
           {...(cursorValue !== undefined && { cursorValue })}
+          {...(cursorResolution !== undefined && { cursorResolution })}
           {...(ariaLabel !== undefined && { ariaLabel })}
           plot={plot}
           highlighted={highlighted}
@@ -311,6 +350,7 @@ function CartesianPlot<T>({
   tooltip,
   marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   plot,
   highlighted,
@@ -430,6 +470,7 @@ function CartesianPlot<T>({
     getKey: getX,
     xScale,
     marginLeft: margin.left,
+    ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
   const svgRef = useRef<SVGSVGElement>(null)
@@ -438,6 +479,7 @@ function CartesianPlot<T>({
   const point = cursor.point
   const cursorX = point === null ? null : (xScale(getX(point)) ?? null)
   const badge = tooltipCfg?.label === undefined || point === null ? null : tooltipCfg.label(point)
+  const formatHeader = tooltipCfg?.formatHeader
 
   // Each series falls back to ITS OWN axis's tick format, so a right-axis value is never
   // formatted with the left axis's rules (an explicit per-series `formatValue` still wins).
@@ -454,10 +496,17 @@ function CartesianPlot<T>({
   const rows =
     tooltipEnabled && point !== null ? deriveTooltipRows(tooltipSeries, point, leftFormat) : []
 
+  // This chart renders its tooltip either as the cursor SOURCE (always) or, opted in via
+  // `onFollow`, as a FOLLOWER (a sibling owns the cursor). A follower has no pointer under it, so
+  // it is always positioned via the anchored (crosshair) path below, regardless of `follow`.
+  const isFollowerRender = !cursor.isSource && tooltipCfg?.onFollow === true
+  const showTooltip = tooltipEnabled && point !== null && (cursor.isSource || isFollowerRender)
+
   // Anchored mode resolves the crosshair's plot-local x into viewport space; following mode uses
-  // the pointer position `useChartCursor` already recorded.
-  const anchorX =
-    tooltipCfg?.follow === false && point !== null && cursorX !== null ? cursorX : null
+  // the pointer position `useChartCursor` already recorded. A follower render always anchors, since
+  // `follow`'s pointer-tracking path has no pointer to read on this chart.
+  const useAnchoredPosition = tooltipCfg?.follow === false || isFollowerRender
+  const anchorX = useAnchoredPosition && point !== null && cursorX !== null ? cursorX : null
   const svgRect = anchorX === null ? undefined : svgRef.current?.getBoundingClientRect()
   const tooltipAnchor =
     svgRect === undefined || anchorX === null
@@ -570,10 +619,13 @@ function CartesianPlot<T>({
         </Group>
       </svg>
 
-      {tooltipEnabled && cursor.isSource && point !== null && (
-        <ChartTooltipFloat anchor={tooltipAnchor}>
+      {showTooltip && (
+        <ChartTooltipFloat anchor={tooltipAnchor} ariaLive={cursor.isSource}>
           <TooltipHeader
             date={getX(point)}
+            {...(formatHeader !== undefined && {
+              format: (key: string) => formatHeader(key, point),
+            })}
             {...(badge !== null && { label: badge.text, labelColor: badge.color })}
           />
           <TooltipBody>

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

@@ -13,9 +13,11 @@
  * to the DOM harness would only be worth it if a future assertion here needed a real measured size
  * (a live `ResizeObserver` reading) rather than this SSR fallback rect.
  */
+import { render } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { ChartFrame } from './ChartFrame'
+import { HoverOverlay } from './HoverOverlay'
 import type { SeriesStyle } from '../series'
 
 const series: SeriesStyle[] = [{ key: 'a', label: 'Series A', color: '#000', mark: 'line' }]
@@ -66,6 +68,46 @@ describe('a non-pending ChartFrame is unaffected — the legend and body both re
   })
 })
 
+describe('ariaLabel: the label is announced WITHOUT swallowing the interactive slider', () => {
+  // The regression this guards: `role="img"` marks every descendant presentational per the ARIA
+  // spec, so a screen reader would announce the label and then never expose `HoverOverlay`'s
+  // `role="slider"` at all — the keyboard-scrubbable affordance becomes unreachable with no error
+  // anywhere. `role="group"` announces the same label while keeping descendants in the tree.
+  test('the outer container is role="group" with the label, never role="img"', () => {
+    const { container } = render(
+      <ChartFrame series={series} ariaLabel="Revenue over time" legend={false}>
+        {() => <svg />}
+      </ChartFrame>,
+    )
+    const outer = container.firstElementChild as HTMLElement
+    expect(outer.getAttribute('role')).toBe('group')
+    expect(outer.getAttribute('aria-label')).toBe('Revenue over time')
+    expect(container.querySelector('[role="img"]')).toBeNull()
+  })
+
+  test('the slider stays a reachable descendant of the labeled container', () => {
+    const { container } = render(
+      <ChartFrame series={series} ariaLabel="Revenue over time" legend={false}>
+        {() => (
+          <svg>
+            <HoverOverlay
+              width={100}
+              height={100}
+              onMove={() => {}}
+              onLeave={() => {}}
+              onKeyDown={() => {}}
+            />
+          </svg>
+        )}
+      </ChartFrame>,
+    )
+    const outer = container.firstElementChild as HTMLElement
+    expect(outer.getAttribute('role')).toBe('group')
+    const slider = outer.querySelector('[role="slider"]')
+    expect(slider).not.toBeNull()
+  })
+})
+
 const twoSeries: SeriesStyle[] = [
   { key: 'a', label: 'Series A', color: '#000', mark: 'line' },
   { key: 'b', label: 'Series B', color: '#111', mark: 'bar' },

package/src/charts/primitives/ChartFrame.tsx

@@ -53,9 +53,16 @@ export type ChartFrameProps = {
    */
   isPending?: boolean
   /**
-   * Accessible text alternative for the chart, applied as `aria-label` (+ `role="img"`) on the
+   * Accessible text alternative for the chart, applied as `aria-label` (+ `role="group"`) on the
    * outer container so screen readers announce something other than an unlabeled graphic. Every
    * kind composing `ChartFrame` should accept and forward this from its own props.
+   *
+   * MUST stay `role="group"`, never `role="img"`. Per the ARIA spec, every descendant of an
+   * `role="img"` element is presentational, which erases the `HoverOverlay`'s `role="slider"` from
+   * the accessibility tree entirely — a screen reader announces the label and then the
+   * keyboard-scrubbable slider underneath it is simply unreachable, silently, with no error
+   * anywhere. `role="group"` announces the same label while keeping descendants exposed. Do not
+   * "simplify" this back to `img` — it looks like a no-op refactor and it is not.
    */
   ariaLabel?: string
   /** Draw the SVG marks given the plot rect that already excludes the legend band, plus the set
@@ -189,7 +196,7 @@ export function ChartFrame({
     <div
       ref={containerRef}
       style={outerStyle(fill, vertical)}
-      {...(ariaLabel !== undefined && { role: 'img', 'aria-label': ariaLabel })}
+      {...(ariaLabel !== undefined && { role: 'group', 'aria-label': ariaLabel })}
       {...(isPending && { 'aria-busy': 'true' })}
     >
       {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}

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

@@ -0,0 +1,44 @@
+/**
+ * `TooltipHeader` — the `format` seam that lets a caller override `fmtTooltipDate`. Added because
+ * `fmtTooltipDate` regexes `YYYY-MM-DD` out of the key and builds a LOCAL `Date`, so a UTC ISO
+ * domain key names the wrong day next to `formatX`/the tooltip badge, which both resolve locally.
+ */
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { ChartTooltipFloat, TooltipHeader } from './ChartTooltip'
+
+describe('TooltipHeader — format prop', () => {
+  test('defaults to fmtTooltipDate when omitted', () => {
+    const html = renderToStaticMarkup(<TooltipHeader date="2026-04-21" />)
+    expect(html).toContain('Tue Apr 21 2026')
+  })
+
+  test('a custom format overrides fmtTooltipDate entirely', () => {
+    const html = renderToStaticMarkup(
+      <TooltipHeader date="2026-04-21" format={(d) => `custom:${d}`} />,
+    )
+    expect(html).toContain('custom:2026-04-21')
+    expect(html).not.toContain('Tue Apr 21 2026')
+  })
+})
+
+describe('ChartTooltipFloat — ariaLive', () => {
+  test('defaults to an aria-live="polite" region', () => {
+    render(
+      <ChartTooltipFloat anchor={{ x: 10, y: 10 }}>
+        <span>content</span>
+      </ChartTooltipFloat>,
+    )
+    expect(screen.getByRole('tooltip').getAttribute('aria-live')).toBe('polite')
+  })
+
+  test('ariaLive: false drops the live-region attribute entirely — a follower is visual only', () => {
+    render(
+      <ChartTooltipFloat anchor={{ x: 10, y: 10 }} ariaLive={false}>
+        <span>content</span>
+      </ChartTooltipFloat>,
+    )
+    expect(screen.getByRole('tooltip').hasAttribute('aria-live')).toBe(false)
+  })
+})

package/src/charts/primitives/ChartTooltip.tsx

@@ -26,10 +26,16 @@ export function TooltipHeader({
   date,
   label,
   labelColor,
+  format = fmtTooltipDate,
 }: {
   date: string
   label?: string
   labelColor?: string
+  /** Overrides `fmtTooltipDate` for the header text. Default: today's `fmtTooltipDate` behavior,
+   * unchanged. The seam exists because `fmtTooltipDate` regexes `YYYY-MM-DD` out of the key and
+   * builds a LOCAL `Date`, so a UTC ISO domain key names the wrong day next to `formatX`/the
+   * tooltip badge, which both resolve locally — a caller with a UTC key needs to supply its own. */
+  format?: (date: string) => string
 }) {
   return (
     <div
@@ -50,7 +56,7 @@ export function TooltipHeader({
           color: VX.ink,
         }}
       >
-        {fmtTooltipDate(date)}
+        {format(date)}
       </span>
       {label !== undefined && (
         <span
@@ -149,9 +155,15 @@ const VIEWPORT_MARGIN = 8
  */
 export function ChartTooltipFloat({
   anchor,
+  ariaLive = true,
   children,
 }: {
   anchor: { x: number; y: number } | null
+  /** Whether this tooltip announces itself to screen readers on every position change. Default
+   * true. Pass false for a cursor FOLLOWER's tooltip — N followers on a shared-cursor page all
+   * announcing on every pointer move would make the page unusable with a screen reader; only the
+   * cursor SOURCE should be `aria-live`. */
+  ariaLive?: boolean
   children: ReactNode
 }) {
   const ref = useRef<HTMLDivElement>(null)
@@ -190,7 +202,7 @@ export function ChartTooltipFloat({
     <div
       ref={ref}
       role="tooltip"
-      aria-live="polite"
+      {...(ariaLive && { 'aria-live': 'polite' as const })}
       style={{ ...TOOLTIP_STYLES, left, top, visibility: box === null ? 'hidden' : 'visible' }}
     >
       {children}