basalt-ui 1.16.0 → 1.17.0

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

@@ -1,6 +1,7 @@
 import { fireEvent, render, screen } 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(

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,6 +87,14 @@ 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. */
@@ -149,6 +162,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 +217,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 +261,7 @@ export function CartesianChart<T>({
   tooltip,
   margin: marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   isPending,
   children,
@@ -274,6 +295,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 +333,7 @@ function CartesianPlot<T>({
   tooltip,
   marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   plot,
   highlighted,
@@ -430,6 +453,7 @@ function CartesianPlot<T>({
     getKey: getX,
     xScale,
     marginLeft: margin.left,
+    ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
   const svgRef = useRef<SVGSVGElement>(null)
@@ -438,6 +462,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).
@@ -574,6 +599,9 @@ function CartesianPlot<T>({
         <ChartTooltipFloat anchor={tooltipAnchor}>
           <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,23 @@
+/**
+ * `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 { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { 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')
+  })
+})

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

package/src/charts/series.ts

@@ -96,8 +96,9 @@ export type ChartSeries<T> = SeriesStyle & {
    * alongside the value so a row can read fields beyond the plotted number (e.g. `97.5 kg (92.5 ×
    * 3)`). */
   formatValue?: (v: number, d: T) => string
-  /** PR star / status dot. Return null for no marker at that point. */
-  getMarker?: (d: T) => { color?: string; r?: number } | null
+  /** PR star / status dot. Return null for no marker at that point. `ring` defaults true (today's
+   * punched-out stroke, unchanged); `false` omits the stroke entirely. `fillOpacity` defaults 1. */
+  getMarker?: (d: T) => { color?: string; r?: number; fillOpacity?: number; ring?: boolean } | null
 }
 
 /** A single derived tooltip row, ready for `TooltipRow`. */

package/src/charts/utils/domain.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test'
-import { padAutoLower } from './domain'
+import { padAutoLower, padAutoUpper } from './domain'
 
 describe('padAutoLower', () => {
   test('stays at 0 for the default zero-baseline case (never goes negative)', () => {
@@ -22,3 +22,33 @@ describe('padAutoLower', () => {
     }
   })
 })
+
+describe('padAutoUpper', () => {
+  test('stays at 0 (never pushed positive)', () => {
+    expect(padAutoUpper(0, 1.1)).toBe(0)
+  })
+
+  test('pads UP above a positive candidate', () => {
+    expect(padAutoUpper(78, 1.1)).toBeCloseTo(85.8, 5)
+  })
+
+  test('pads further up (toward and past zero) for a negative candidate', () => {
+    expect(padAutoUpper(-5, 1.1)).toBeCloseTo(-4.5454, 3)
+  })
+
+  test('upper never lands below the candidate it was derived from', () => {
+    for (const candidate of [-10, -0.5, 0, 0.5, 10, 78]) {
+      expect(padAutoUpper(candidate, 1.1)).toBeGreaterThanOrEqual(candidate)
+    }
+  })
+
+  test('the autoMaxFloor case: dataMax 3.2, pad 1.1, floor 6 -> 6.6', () => {
+    expect(padAutoUpper(Math.max(3.2, 6), 1.1)).toBeCloseTo(6.6, 5)
+  })
+
+  test('is the exact mirror of padAutoLower — same magnitude, opposite direction', () => {
+    for (const candidate of [-10, -0.5, 0.5, 10, 78]) {
+      expect(padAutoUpper(candidate, 1.1)).toBeCloseTo(-padAutoLower(-candidate, 1.1), 5)
+    }
+  })
+})

package/src/charts/utils/domain.ts

@@ -20,3 +20,22 @@ export function padAutoLower(candidate: number, pad: number): number {
   if (candidate === 0) return 0
   return candidate > 0 ? candidate / pad : candidate * pad
 }
+
+/**
+ * Auto y-domain upper-bound padding — the exact mirror of {@link padAutoLower}, sharing its
+ * sign-safety: pad AWAY from zero (`upper >= candidate`), never toward it. `candidate` is the
+ * caller's `Math.max(dataMax, floor)` — the `autoMaxFloor` clamp has already been applied, so
+ * padding runs AFTER the floor, not before it. Applying the floor post-pad (the pre-existing bug)
+ * lands a floored axis top exactly on the floor value with zero headroom — a target line pinned to
+ * that floor then sits glued to the plot edge instead of getting the same breathing room every
+ * other bound gets.
+ *
+ *  - `candidate === 0` stays exactly 0 — never pushed positive.
+ *  - `candidate > 0` multiplies by `pad`, moving the ceiling further UP (away from zero).
+ *  - `candidate < 0` divides by `pad`, moving the ceiling UP toward (and past) zero — the mirror of
+ *    `padAutoLower`'s `candidate > 0` branch.
+ */
+export function padAutoUpper(candidate: number, pad: number): number {
+  if (candidate === 0) return 0
+  return candidate > 0 ? candidate * pad : candidate / pad
+}