basalt-ui 1.15.0 → 1.17.0

package/src/charts/cursor/resolve.ts

@@ -22,6 +22,27 @@ export function parseKey(key: string): number | null {
   return Number.isNaN(t) ? null : t
 }
 
+/**
+ * How a foreign key maps onto a chart's own points.
+ *
+ * `'nearest'` (default) treats every key as a POINT — the foreign key resolves to whichever own
+ * point sits closest to it. Correct when a chart's x-domain is a set of instants.
+ *
+ * `'leading'` treats every key as the LEADING EDGE of a bucket covering `[key, nextKey)` — the
+ * foreign key resolves to the LAST own key `<=` it. Use this when a chart's keys are bucket
+ * starts (a weekly series keyed by the Monday of each week, a monthly series keyed by the 1st):
+ * under `'nearest'`, a target landing in the back half of a bucket resolves to the FOLLOWING
+ * bucket instead of the one it's actually inside, and the shared crosshair lands one column off
+ * for every back-half hover.
+ *
+ * The two modes differ at the DOMAIN EDGES too, and deliberately: `'nearest'` tolerates one step
+ * past each end (the target is an instant, so the closest point is still a defensible answer),
+ * while `'leading'` bounds strictly to `[first, last + step)` — outside that range no bucket
+ * CONTAINS the key, and answering with the nearest one would paint a crosshair on a bucket that
+ * provably excludes it.
+ */
+export type CursorResolution = 'nearest' | 'leading'
+
 export type DomainIndex<T> = {
   byKey: Map<string, T>
   /** Parsed positions, ascending. Empty when the domain isn't parseable. */
@@ -30,10 +51,16 @@ export type DomainIndex<T> = {
   points: T[]
   /** Median spacing — the tolerance within which a foreign key still resolves. */
   step: number
+  /** The resolution strategy this index was built for. */
+  resolution: CursorResolution
 }
 
 /** Build the lookup structure once per `data` identity. */
-export function buildDomainIndex<T>(data: readonly T[], getKey: (d: T) => string): DomainIndex<T> {
+export function buildDomainIndex<T>(
+  data: readonly T[],
+  getKey: (d: T) => string,
+  resolution: CursorResolution = 'nearest',
+): DomainIndex<T> {
   const byKey = new Map<string, T>()
   const parsed: { value: number; point: T }[] = []
   let parseable = true
@@ -48,7 +75,9 @@ export function buildDomainIndex<T>(data: readonly T[], getKey: (d: T) => string
 
   // Under two parseable points there is no step to reason about, so nearest-match would be
   // unbounded — fall back to exact match.
-  if (!parseable || parsed.length < 2) return { byKey, values: [], points: [], step: 0 }
+  if (!parseable || parsed.length < 2) {
+    return { byKey, values: [], points: [], step: 0, resolution }
+  }
 
   parsed.sort((a, b) => a.value - b.value)
   const values = parsed.map((p) => p.value)
@@ -60,15 +89,39 @@ export function buildDomainIndex<T>(data: readonly T[], getKey: (d: T) => string
   }
   diffs.sort((a, b) => a - b)
 
-  return { byKey, values, points, step: diffs[Math.floor(diffs.length / 2)] ?? 0 }
+  return { byKey, values, points, step: diffs[Math.floor(diffs.length / 2)] ?? 0, resolution }
+}
+
+/** `'leading'` resolution: the last own position `<= target`. The caller has already rejected
+ * anything outside `[first, last + step)`, so a containing bucket is guaranteed to exist. */
+function resolveLeading<T>(index: DomainIndex<T>, target: number): T {
+  let lo = 0
+  let hi = index.values.length - 1
+  let result = 0
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1
+    if ((index.values[mid] as number) <= target) {
+      result = mid
+      lo = mid + 1
+    } else {
+      hi = mid - 1
+    }
+  }
+  return index.points[result] as T
 }
 
 /**
- * The own point a broadcast `key` maps to: exact match first, else the nearest parsed position
- * within one domain step. Out of range → null, so charts over unrelated domains never paint a
- * cursor for each other — which is what makes "shared by default" safe.
+ * The own point a broadcast `key` maps to: exact match first, else — per `index.resolution` — the
+ * nearest parsed position or the last position at/before the target, both within one domain step.
+ * Out of range → null, so charts over unrelated domains never paint a cursor for each other —
+ * which is what makes "shared by default" safe. A categorical (unparseable) domain falls back to
+ * exact-match-only in BOTH resolutions, since "nearest"/"leading" over a category is meaningless.
  */
-export function resolveCursorPoint<T>(index: DomainIndex<T>, key: string): T | null {
+export function resolveCursorPoint<T>(
+  index: DomainIndex<T>,
+  key: string,
+  resolution: CursorResolution = index.resolution,
+): T | null {
   const exact = index.byKey.get(key)
   if (exact !== undefined) return exact
 
@@ -77,6 +130,17 @@ export function resolveCursorPoint<T>(index: DomainIndex<T>, key: string): T | n
 
   const first = index.values[0] as number
   const last = index.values[index.values.length - 1] as number
+
+  if (resolution === 'leading') {
+    // Containment, NOT tolerance. A bucket keyed `k` covers `[k, nextKey)`, so a target before the
+    // first key sits in no bucket at all, and `last + step` is the first instant past the final
+    // one. Borrowing `'nearest'`'s symmetric ±step window here would snap a pre-domain target onto
+    // the first bucket and a post-domain one onto the last — painting a crosshair on a bucket that
+    // provably does not contain the hovered key, which is the exact lie this mode exists to remove.
+    if (target < first || target >= last + index.step) return null
+    return resolveLeading(index, target)
+  }
+
   if (target < first - index.step || target > last + index.step) return null
 
   let lo = 0

package/src/charts/hooks/useChartCursor.ts

@@ -1,6 +1,7 @@
 import { localPoint } from '@visx/event'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { KeyboardEvent, PointerEvent } from 'react'
+import type { CursorResolution } from '../cursor/resolve'
 import { buildDomainIndex, resolveCursorPoint } from '../cursor/resolve'
 import { useCursorState, useCursorStore } from '../cursor/scope'
 
@@ -38,6 +39,7 @@ export function useChartCursor<T>({
   getKey,
   xScale,
   marginLeft,
+  resolution = 'nearest',
 }: {
   data: readonly T[]
   chartId: string
@@ -45,6 +47,12 @@ export function useChartCursor<T>({
   /** Own x scale — maps a domain key to a plot-local x offset. */
   xScale: (key: string) => number | undefined
   marginLeft: number
+  /**
+   * How a sibling's broadcast key resolves against this chart's own points. Default `'nearest'`
+   * (point domains). Pass `'leading'` when `getKey` returns a bucket's leading edge (a weekly
+   * series keyed by its Monday, a monthly series keyed by its 1st) — see {@link CursorResolution}.
+   */
+  resolution?: CursorResolution
 }): ChartCursor<T> {
   const store = useCursorStore()
   const cursor = useCursorState()
@@ -58,7 +66,10 @@ export function useChartCursor<T>({
   const xScaleRef = useRef(xScale)
   xScaleRef.current = xScale
 
-  const index = useMemo(() => buildDomainIndex(data, getKeyRef.current), [data])
+  const index = useMemo(
+    () => buildDomainIndex(data, getKeyRef.current, resolution),
+    [data, resolution],
+  )
 
   const frameRef = useRef<number | null>(null)
   const pendingRef = useRef<CursorAnchor | null>(null)

package/src/charts/index.ts

@@ -57,6 +57,7 @@ export {
   resolveAxisDomain,
   type CartesianChartProps,
   type CartesianTooltipConfig,
+  type CartesianTooltipRowContext,
   type AxisConfig,
   type PlotContext,
 } from './primitives/CartesianChart'
@@ -90,6 +91,7 @@ export { AreaGradient, areaFillUrl } from './primitives/AreaGradient'
 
 // ── Hooks ────────────────────────────────────────────────────────────────
 export { useChartCursor, type ChartCursor, type CursorAnchor } from './hooks/useChartCursor'
+export type { CursorResolution } from './cursor/resolve'
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize'
 
 // ── Utils ────────────────────────────────────────────────────────────────

package/src/charts/kinds/Bars.test.tsx

@@ -0,0 +1,183 @@
+/**
+ * `Bars` — the `tooltip: false` seam threaded from `SeriesStyle.tooltip` through `BarsBar`/
+ * `BarsLine` (replacing the removed per-kind `hideBarTooltipRows`), plus the `BarsBar<T>`
+ * generic-default assignability guarantee. Real DOM harness (`tests/setup/dom.ts`): the cursor
+ * only advances via `useChartCursor`'s keyboard path (`ArrowRight` on the overlay's `role="slider"`),
+ * which is deterministic regardless of happy-dom's zeroed layout geometry — unlike the pointer path,
+ * which needs a real `getBoundingClientRect`.
+ */
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { ChartCursorScope } from '../cursor/scope'
+import { CartesianChart } from '../primitives/CartesianChart'
+import type { ChartSeries } from '../series'
+import { Bars } from './Bars'
+import type { BarsBar } from './Bars'
+
+type Row = { date: string; shown: number; quiet: number; trend: number }
+
+const rows: Row[] = [{ date: '2026-08-01', shown: 10, quiet: 5, trend: 7 }]
+
+describe('Bars — tooltip: false drops only that row', () => {
+  test('a quiet bar is drawn and legended but produces no tooltip row', async () => {
+    render(
+      <Bars<Row>
+        data={rows}
+        chartId="bars-tooltip"
+        getX={(d) => d.date}
+        getValue={(d, key) => d[key as 'shown' | 'quiet']}
+        positiveBars={[
+          { key: 'shown', label: 'Shown', color: '#111' },
+          { key: 'quiet', label: 'Quiet', color: '#222', tooltip: false },
+        ]}
+      />,
+    )
+
+    // Both series are legended regardless of the tooltip flag.
+    expect(screen.getByText('Shown')).toBeTruthy()
+    expect(screen.getByText('Quiet')).toBeTruthy()
+
+    const slider = screen.getByRole('slider')
+    fireEvent.keyDown(slider, { key: 'ArrowRight' })
+
+    // The tooltip row duplicates 'Shown' (legend + row); 'Quiet' stays legend-only. The tooltip
+    // anchor is set through a `requestAnimationFrame` coalesce, so wait for the SECOND 'Shown' to
+    // land rather than resolving on the legend's already-present first one.
+    await waitFor(() => expect(screen.getAllByText('Shown')).toHaveLength(2))
+    expect(screen.getAllByText('Quiet')).toHaveLength(1)
+  })
+})
+
+describe('Bars — lines[].tooltip: false drops only that row', () => {
+  test('a quiet line is drawn and legended but produces no tooltip row', async () => {
+    render(
+      <Bars<Row>
+        data={rows}
+        chartId="bars-line-tooltip"
+        getX={(d) => d.date}
+        getValue={(d, key) => d[key as 'shown' | 'quiet' | 'trend']}
+        positiveBars={[{ key: 'shown', label: 'Shown', color: '#111' }]}
+        lines={[{ key: 'trend', label: 'Trend', color: '#333', tooltip: false }]}
+      />,
+    )
+
+    // Both series are legended regardless of the tooltip flag.
+    expect(screen.getByText('Shown')).toBeTruthy()
+    expect(screen.getByText('Trend')).toBeTruthy()
+
+    const slider = screen.getByRole('slider')
+    fireEvent.keyDown(slider, { key: 'ArrowRight' })
+
+    // The tooltip row duplicates 'Shown' (legend + row); 'Trend' stays legend-only.
+    await waitFor(() => expect(screen.getAllByText('Shown')).toHaveLength(2))
+    expect(screen.getAllByText('Trend')).toHaveLength(1)
+  })
+})
+
+describe('Bars — lines[].strokeOpacity dims the plotted stroke', () => {
+  test('the line path carries the configured stroke-opacity attribute', () => {
+    const { container } = render(
+      <Bars<Row>
+        data={rows}
+        chartId="bars-line-opacity"
+        getX={(d) => d.date}
+        getValue={(d, key) => d[key as 'shown' | 'quiet' | 'trend']}
+        positiveBars={[{ key: 'shown', label: 'Shown', color: '#111' }]}
+        lines={[{ key: 'trend', label: 'Trend', color: '#333', strokeOpacity: 0.4 }]}
+      />,
+    )
+
+    const path = container.querySelector('path[stroke="#333"]')
+    expect(path?.getAttribute('stroke-opacity')).toBe('0.4')
+  })
+})
+
+describe('Bars — formatX', () => {
+  test('a custom formatX renders on the bottom axis instead of the default DD.MM', () => {
+    const { container } = render(
+      <Bars<Row>
+        data={rows}
+        chartId="bars-formatx"
+        getX={(d) => d.date}
+        getValue={(d, key) => d[key as 'shown' | 'quiet' | 'trend']}
+        positiveBars={[{ key: 'shown', label: 'Shown', color: '#111' }]}
+        formatX={(key) => `X:${key}`}
+      />,
+    )
+    expect(container.innerHTML).toContain('X:2026-08-01')
+  })
+})
+
+describe('Bars — cursorResolution threads through to sibling resolution', () => {
+  // Daily calendar Aug 01–14 (a plain CartesianChart driver) alongside a Bars 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. Proves the prop reaches THIS kind, not just
+  // `CartesianChart` (a kind dropping the forward would silently fall back to 'nearest').
+  const dailyRows: Row[] = Array.from({ length: 14 }, (_, i) => ({
+    date: `2026-08-${String(i + 1).padStart(2, '0')}`,
+    shown: i,
+    quiet: i,
+    trend: i,
+  }))
+  const foldedRows: Row[] = [
+    { date: '2026-08-01', shown: 0, quiet: 0, trend: 0 },
+    { date: '2026-08-08', shown: 1, quiet: 1, trend: 1 },
+  ]
+  const dailySeries: ChartSeries<Row>[] = [
+    { key: 'shown', label: 'Shown', color: '#111', mark: 'line', getValue: (d) => d.shown },
+  ]
+
+  function renderPair(cursorResolution?: 'leading') {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={dailyRows}
+          chartId="bars-daily"
+          getX={(d) => d.date}
+          series={dailySeries}
+          ariaLabel="Daily"
+        >
+          {() => null}
+        </CartesianChart>
+        <Bars<Row>
+          data={foldedRows}
+          chartId="bars-folded"
+          getX={(d) => d.date}
+          getValue={(d, key) => d[key as 'shown']}
+          positiveBars={[{ key: 'shown', label: 'Shown', color: '#111' }]}
+          ariaLabel="Folded"
+          {...(cursorResolution !== undefined && { cursorResolution })}
+        />
+      </ChartCursorScope>,
+    )
+  }
+
+  // Drives the daily chart to Aug 05 — the back half of the Aug 01–07 bucket (midpoint 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' })
+    expect(foldedSlider.getAttribute('aria-valuetext')).toBe('01.08')
+  })
+
+  test("without the prop (default 'nearest'), the same daily hover lands on the FOLLOWING bucket instead", () => {
+    renderPair()
+    driveDailyToAug05()
+    const foldedSlider = screen.getByRole('slider', { name: 'Folded' })
+    expect(foldedSlider.getAttribute('aria-valuetext')).toBe('08.08')
+  })
+})
+
+describe('BarsBar<T> — the `= unknown` default stays assignable', () => {
+  test('an existing untyped BarsBar[] array is assignable to BarsBar<Row>[] contravariantly', () => {
+    const bars: BarsBar[] = [{ key: 'shown', label: 'Shown', color: '#111' }]
+    const typed: BarsBar<Row>[] = bars
+    expect(typed).toBe(bars)
+  })
+})

package/src/charts/kinds/Bars.tsx

@@ -1,6 +1,7 @@
 import { curveMonotoneX } from '@visx/curve'
 import { LinePath } from '@visx/shape'
 import { memo, useMemo } from 'react'
+import type { CursorResolution } from '../cursor/resolve'
 import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import { CartesianChart } from '../primitives/CartesianChart'
@@ -10,7 +11,12 @@ import { LINE_OVERLAY_STROKE_WIDTH } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { padAutoLower } from '../utils/domain'
 
-export type BarsBar = {
+/**
+ * `T = unknown` is load-bearing, not a shortcut: it keeps a consumer's existing
+ * `const bars: BarsBar[] = [...]` compiling (and still assignable to `BarsBar<Row>[]`,
+ * contravariantly) even though the type is now generic over the datum.
+ */
+export type BarsBar<T = unknown> = {
   /** Field key — `getValue(d, key)` extracts the number (null = skip this slot, not domain hole). */
   key: string
   /** Tooltip + legend label. */
@@ -18,22 +24,30 @@ export type BarsBar = {
   /** Fill color (a resolved CSS color / token ref). Per `docs/DESIGN-SPEC.md` §5, the primary bar
    * series should typically resolve to `VX.accent`, a secondary companion to `VX.faint`. */
   color: string
-  /** Per-series tooltip value formatter — overrides the left/right axis's own format. */
-  formatValue?: (v: number) => string
+  /** Per-series tooltip value formatter — overrides the left/right axis's own format. Receives the
+   * hovered datum alongside the value. */
+  formatValue?: (v: number, d: T) => string
   /** Y axis to plot against. Honored only in grouped layout. Default 'left'. */
   axisSide?: 'left' | 'right'
   /** Relative width within the group (only honored in grouped layout). Default 1 — all bars equal. */
   weight?: number
+  /** Default true; false = drawn and legended, but never listed as a tooltip row — threads
+   * `SeriesStyle.tooltip` through `Bars`, replacing the removed per-kind `hideBarTooltipRows`. */
+  tooltip?: boolean
 }
 
-export type BarsLine = {
+export type BarsLine<T = unknown> = {
   key: string
   label: string
   color: string
   axisSide?: 'left' | 'right'
   strokeWidth?: number
   dashed?: boolean
-  formatValue?: (v: number) => string
+  formatValue?: (v: number, d: T) => string
+  /** Default true; false = drawn and legended, but never listed as a tooltip row. */
+  tooltip?: boolean
+  /** Dims the plotted stroke AND the legend swatch, never the tooltip row (`SeriesStyle.strokeOpacity`). */
+  strokeOpacity?: number
 }
 
 /** @deprecated Use ZoneSpec from primitives/ZoneRects. Kept as an alias. */
@@ -57,12 +71,12 @@ export type BarsProps<T> = {
   getValue: (d: T, key: string) => number | null
 
   /** 1+ bar series, stacked when ≥2, plotted above baseline (y >= 0). */
-  positiveBars: BarsBar[]
+  positiveBars: BarsBar<T>[]
   /** Optional bar series stacked below baseline (rendered as flipped negatives). */
-  negativeBars?: BarsBar[]
+  negativeBars?: BarsBar<T>[]
 
   /** 0–2 line overlays, each on left or right axis. */
-  lines?: BarsLine[]
+  lines?: BarsLine<T>[]
 
   /** Horizontal value-range overlays (target zones, optimal bands). */
   zones?: BarsZone[]
@@ -95,6 +109,14 @@ export type BarsProps<T> = {
 
   /** X tick count override. Default: as many as fit. */
   xTicks?: number
+  /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
+  formatX?: (key: string) => string
+  /**
+   * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
+   * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
+   * keyed by its Monday) — see `CursorResolution`.
+   */
+  cursorResolution?: CursorResolution
 
   /** `false` disables the tooltip entirely (and with it the crosshair dots). */
   tooltip?: CartesianTooltipConfig<T> | false
@@ -139,6 +161,8 @@ function BarsInner<T>(props: BarsProps<T>) {
     barLayout = 'stacked',
     barOpacity,
     xTicks,
+    formatX,
+    cursorResolution,
     tooltip,
     margin,
     legend,
@@ -157,6 +181,7 @@ function BarsInner<T>(props: BarsProps<T>) {
         ...(b.axisSide !== undefined && { axis: b.axisSide }),
         getValue: (d: T) => getValue(d, b.key),
         ...(b.formatValue !== undefined && { formatValue: b.formatValue }),
+        ...(b.tooltip !== undefined && { tooltip: b.tooltip }),
       })),
     [positiveBars, negativeBars, getValue],
   )
@@ -173,6 +198,8 @@ function BarsInner<T>(props: BarsProps<T>) {
         ...(ln.axisSide !== undefined && { axis: ln.axisSide }),
         getValue: (d: T) => getValue(d, ln.key),
         ...(ln.formatValue !== undefined && { formatValue: ln.formatValue }),
+        ...(ln.tooltip !== undefined && { tooltip: ln.tooltip }),
+        ...(ln.strokeOpacity !== undefined && { strokeOpacity: ln.strokeOpacity }),
       })),
     [lines, getValue],
   )
@@ -253,6 +280,8 @@ function BarsInner<T>(props: BarsProps<T>) {
       y={yConfig}
       {...(y2 !== undefined && { y2 })}
       {...(xTicks !== undefined && { xTicks })}
+      {...(formatX !== undefined && { formatX })}
+      {...(cursorResolution !== undefined && { cursorResolution })}
       {...(zones !== undefined && { zones })}
       {...(mappedRefLines !== undefined && { refLines: mappedRefLines })}
       {...(height !== undefined && { height })}
@@ -294,9 +323,9 @@ type LinePt<T> = { __d: T; __y: number }
 type BarsMarksProps<T> = {
   getX: (d: T) => string
   getValue: (d: T, key: string) => number | null
-  positiveBars: BarsBar[]
-  negativeBars: BarsBar[]
-  lines: BarsLine[]
+  positiveBars: BarsBar<T>[]
+  negativeBars: BarsBar<T>[]
+  lines: BarsLine<T>[]
   barWidthRatio: number
   barLayout: 'stacked' | 'grouped'
   barOpacity?: (d: T, key: string) => number
@@ -485,7 +514,7 @@ function BarsMarks<T>({
             stroke={ln.color}
             strokeWidth={ln.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
             strokeDasharray={ln.dashed ? VX.dashArray : undefined}
-            strokeOpacity={dim(ln.key)}
+            strokeOpacity={dim(ln.key) * (ln.strokeOpacity ?? 1)}
             curve={curveMonotoneX}
           />
         )