basalt-ui 1.16.0 → 1.18.0

package/src/charts/cursor/resolve.test.ts

@@ -59,3 +59,65 @@ describe('resolveCursorPoint', () => {
     expect(resolveCursorPoint(i, '2026-08-02')).toBeNull()
   })
 })
+
+describe("resolveCursorPoint — 'leading' resolution (bucket-keyed domains)", () => {
+  const weekly = (days: string[]) => buildDomainIndex(daily(days), (p) => p.date, 'leading')
+
+  test('resolves an exact key, same as nearest', () => {
+    const i = weekly(['01', '08', '15'])
+    expect(resolveCursorPoint(i, '2026-08-08')?.date).toBe('2026-08-08')
+  })
+
+  test("a target anywhere inside a bucket resolves to that bucket's LEADING key, not the nearest one", () => {
+    // The bug this replaces: a weekly chart keyed by the Monday of each week (step 7 days),
+    // hovered from a daily sibling landing in the back half of the bucket, used to resolve to the
+    // FOLLOWING week under nearest-match. Every back-half day must resolve to the bucket it is
+    // actually inside.
+    const i = weekly(['01', '08', '15'])
+    expect(resolveCursorPoint(i, '2026-08-02')?.date).toBe('2026-08-01')
+    expect(resolveCursorPoint(i, '2026-08-05')?.date).toBe('2026-08-01')
+    expect(resolveCursorPoint(i, '2026-08-07')?.date).toBe('2026-08-01')
+    expect(resolveCursorPoint(i, '2026-08-09')?.date).toBe('2026-08-08')
+    expect(resolveCursorPoint(i, '2026-08-14')?.date).toBe('2026-08-08')
+  })
+
+  test('a key BEFORE the first bucket resolves to null — no bucket contains it', () => {
+    // Deliberately NOT 'nearest''s one-step tolerance. The first key is the leading edge of the
+    // first bucket, so anything earlier is outside every bucket; snapping it onto the first one
+    // would paint a crosshair on a bucket that provably does not contain the hovered key.
+    const i = weekly(['02', '09', '16'])
+    expect(resolveCursorPoint(i, '2026-08-01')).toBeNull()
+    expect(resolveCursorPoint(i, '2026-08-02')?.date).toBe('2026-08-02')
+  })
+
+  test('the final bucket ends at last + step — that instant is already outside it', () => {
+    const i = weekly(['01', '08', '15']) // step = 7, so the last bucket covers [Aug 15, Aug 22)
+    expect(resolveCursorPoint(i, '2026-08-21')?.date).toBe('2026-08-15') // last day inside
+    expect(resolveCursorPoint(i, '2026-08-22')).toBeNull() // exactly last + step, exclusive
+    expect(resolveCursorPoint(i, '2026-08-23')).toBeNull()
+  })
+
+  test('returns null well beyond the domain, so unrelated charts never sync', () => {
+    const i = weekly(['01', '08', '15'])
+    expect(resolveCursorPoint(i, '2026-09-30')).toBeNull()
+  })
+
+  test('categorical domains fall back to exact match only, same as nearest', () => {
+    const points = [{ date: 'Direct' }, { date: 'Referral' }]
+    const i = buildDomainIndex(points, (p) => p.date, 'leading')
+    expect(resolveCursorPoint(i, 'Direct')?.date).toBe('Direct')
+    expect(resolveCursorPoint(i, 'Organic')).toBeNull()
+  })
+
+  test('a single-point chart resolves only its own key', () => {
+    const i = weekly(['01'])
+    expect(resolveCursorPoint(i, '2026-08-01')?.date).toBe('2026-08-01')
+    expect(resolveCursorPoint(i, '2026-08-02')).toBeNull()
+  })
+
+  test('an explicit resolution argument overrides the index-built default', () => {
+    // Built as 'nearest', resolved as 'leading' — the per-call argument wins.
+    const i = index(daily(['01', '08', '15']))
+    expect(resolveCursorPoint(i, '2026-08-05', 'leading')?.date).toBe('2026-08-01')
+  })
+})

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

@@ -91,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

@@ -8,6 +8,9 @@
  */
 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'
 
@@ -89,6 +92,88 @@ describe('Bars — lines[].strokeOpacity dims the plotted stroke', () => {
   })
 })
 
+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' }]

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'
@@ -108,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
@@ -152,6 +161,8 @@ function BarsInner<T>(props: BarsProps<T>) {
     barLayout = 'stacked',
     barOpacity,
     xTicks,
+    formatX,
+    cursorResolution,
     tooltip,
     margin,
     legend,
@@ -269,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 })}