basalt-ui 1.15.0 → 1.17.0

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. */
@@ -53,6 +58,23 @@ export type AxisConfig<T> = {
   format?: (v: number) => string
   /** Horizontal grid rules. Default: on for the left axis, off for the right. */
   grid?: boolean
+  /**
+   * Round the scale's domain outward to nice tick values (d3's `scale.nice()`). Threaded to BOTH
+   * `probeAxisLabels` (measurement) and the real `scaleLinear` (rendering) — they must agree, or
+   * the measured margin is computed from ticks the axis never paints.
+   *
+   * Default `false`, deliberately: flipping the default would move the domain of every
+   * already-migrated chart. Opt in per axis.
+   */
+  nice?: boolean
+}
+
+/** Handed to `prependRows`/`extraRows` alongside the hovered datum — the same `visible`/`hidden`
+ * the plot itself draws from, so a hand-authored row can't structurally desync from legend
+ * toggling. */
+export type CartesianTooltipRowContext<T> = {
+  visible: readonly ChartSeries<T>[]
+  hidden: ReadonlySet<string>
 }
 
 export type CartesianTooltipConfig<T> = {
@@ -65,10 +87,20 @@ 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
-  /** Rows rendered BEFORE the derived per-series rows (a total, a context line). */
-  prependRows?: (d: T) => ReactNode
-  /** Rows appended after the derived per-series rows. */
-  extraRows?: (d: T) => ReactNode
+  /**
+   * 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
 }
 
 /** Everything a mark renderer needs. Handed to `CartesianChart`'s child on every render. */
@@ -130,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. */
@@ -177,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
@@ -222,6 +261,7 @@ export function CartesianChart<T>({
   tooltip,
   margin: marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   isPending,
   children,
@@ -255,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}
@@ -292,6 +333,7 @@ function CartesianPlot<T>({
   tooltip,
   marginOverride,
   cursorValue,
+  cursorResolution,
   ariaLabel,
   plot,
   highlighted,
@@ -339,9 +381,10 @@ function CartesianPlot<T>({
       probeAxisLabels({
         domain: leftDomain,
         ticks: leftTicks,
+        nice: y?.nice ?? false,
         ...(y?.format !== undefined && { format: y.format }),
       }),
-    [leftDomain, leftTicks, y?.format],
+    [leftDomain, leftTicks, y?.format, y?.nice],
   )
 
   const { labels: rightLabels, format: rightFormat } = useMemo(
@@ -351,9 +394,10 @@ function CartesianPlot<T>({
         : probeAxisLabels({
             domain: rightDomain,
             ticks: rightTicks,
+            nice: y2?.nice ?? false,
             ...(y2?.format !== undefined && { format: y2.format }),
           }),
-    [rightDomain, rightTicks, y2?.format],
+    [rightDomain, rightTicks, y2?.format, y2?.nice],
   )
 
   const xLabels = useMemo(() => keys.map(formatX), [keys, formatX])
@@ -378,13 +422,24 @@ function CartesianPlot<T>({
     [keys, xMax],
   )
   const yScale = useMemo(
-    () => scaleLinear<number>({ domain: leftDomain, range: [yMax, 0] }),
-    [leftDomain, yMax],
+    () =>
+      scaleLinear<number>({
+        domain: leftDomain,
+        range: [yMax, 0],
+        ...(y?.nice === true && { nice: true }),
+      }),
+    [leftDomain, yMax, y?.nice],
   )
   const y2Scale = useMemo(
     () =>
-      rightDomain === null ? null : scaleLinear<number>({ domain: rightDomain, range: [yMax, 0] }),
-    [rightDomain, yMax],
+      rightDomain === null
+        ? null
+        : scaleLinear<number>({
+            domain: rightDomain,
+            range: [yMax, 0],
+            ...(y2?.nice === true && { nice: true }),
+          }),
+    [rightDomain, yMax, y2?.nice],
   )
 
   const tickValues = useMemo(
@@ -398,6 +453,7 @@ function CartesianPlot<T>({
     getKey: getX,
     xScale,
     marginLeft: margin.left,
+    ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
   const svgRef = useRef<SVGSVGElement>(null)
@@ -406,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).
@@ -542,10 +599,13 @@ 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>
-            {tooltipCfg?.prependRows?.(point)}
+            {tooltipCfg?.prependRows?.(point, { visible, hidden })}
             {rows.map((row) => (
               <TooltipRow
                 key={row.key}
@@ -557,7 +617,7 @@ function CartesianPlot<T>({
                 {...(row.strokeWidth !== undefined && { strokeWidth: row.strokeWidth })}
               />
             ))}
-            {tooltipCfg?.extraRows?.(point)}
+            {tooltipCfg?.extraRows?.(point, { visible, hidden })}
           </TooltipBody>
         </ChartTooltipFloat>
       )}

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/ChartLegend.test.tsx

@@ -46,3 +46,33 @@ describe('ChartLegend note', () => {
     expect(markup).toContain('est.')
   })
 })
+
+describe('ChartLegend strokeOpacity — the swatch cannot lie about a dimmed line', () => {
+  test('a line swatch honors a fractional strokeOpacity', () => {
+    const markup = render([{ ...BASE, shape: 'line', strokeOpacity: 0.4 }])
+    expect(markup).toContain('stroke-opacity="0.4"')
+  })
+
+  test('defaults to full opacity when unset', () => {
+    const markup = render([{ ...BASE, shape: 'line' }])
+    expect(markup).toContain('stroke-opacity="1"')
+  })
+
+  test('a folded MA-companion child swatch honors it too', () => {
+    const markup = render([
+      {
+        ...BASE,
+        children: [
+          {
+            key: 'ma',
+            label: '7d MA',
+            color: 'var(--vx-fill-2)',
+            shape: 'line',
+            strokeOpacity: 0.4,
+          },
+        ],
+      },
+    ])
+    expect(markup).toContain('stroke-opacity="0.4"')
+  })
+})

package/src/charts/primitives/ChartLegend.tsx

@@ -13,6 +13,9 @@ export type LegendEntry = {
   dashed?: boolean
   /** bar swatch opacity — honored instead of a hardcoded value, so it cannot lie about the fill. */
   fillOpacity?: number
+  /** line/splitLine swatch stroke opacity — parity with `fillOpacity` above, so a dimmed
+   * companion line's swatch cannot lie about its own opacity either. */
+  strokeOpacity?: number
   /** Drives `groups` rendering (series → hairline divider → overlay → reference). */
   role?: SeriesRole
   /** Companions folded under this entry via `parent` (`deriveLegend`) — rendered as compact,
@@ -113,6 +116,7 @@ function LegendSwatch({ item, idPrefix }: { item: LegendEntry; idPrefix: string
           y2={7}
           stroke={item.color}
           strokeWidth={item.strokeWidth ?? 2.5}
+          strokeOpacity={item.strokeOpacity ?? 1}
           strokeDasharray={item.dashed ? VX.dashArray : undefined}
         />
         <line
@@ -122,6 +126,7 @@ function LegendSwatch({ item, idPrefix }: { item: LegendEntry; idPrefix: string
           y2={7}
           stroke={item.secondColor}
           strokeWidth={item.strokeWidth ?? 2.5}
+          strokeOpacity={item.strokeOpacity ?? 1}
           strokeDasharray={item.dashed ? VX.dashArray : undefined}
         />
       </svg>
@@ -173,6 +178,7 @@ function LegendSwatch({ item, idPrefix }: { item: LegendEntry; idPrefix: string
         y2={3}
         stroke={item.color}
         strokeWidth={item.strokeWidth ?? 3}
+        strokeOpacity={item.strokeOpacity ?? 1}
         strokeLinecap="round"
         strokeDasharray={item.dashed ? VX.dashArray : undefined}
       />
@@ -222,6 +228,7 @@ function LegendChildSwatch({ item }: { item: LegendEntry }) {
         y2={5}
         stroke={item.color}
         strokeWidth={item.strokeWidth ?? 2}
+        strokeOpacity={item.strokeOpacity ?? 1}
         strokeDasharray={item.dashed ? VX.dashArray : undefined}
       />
     </svg>

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/primitives/XZoneRects.test.tsx

@@ -60,4 +60,64 @@ describe('XZoneRects', () => {
   test('an empty zones array renders no rects', () => {
     expect(render([])).not.toContain('<rect')
   })
+
+  // Mirrors XZoneRects' own bound resolution exactly (same clamp + sign math), so expectations
+  // never drift from the implementation's floating-point arithmetic.
+  function edgeBound(key: string, sign: 1 | -1): number {
+    const step = xScale.step()
+    const [rangeStart, rangeEnd] = xScale.range() as [number, number]
+    const rangeMin = Math.min(rangeStart, rangeEnd)
+    const rangeMax = Math.max(rangeStart, rangeEnd)
+    const center = xScale(key) as number
+    return Math.min(Math.max(center + sign * (step / 2), rangeMin), rangeMax)
+  }
+
+  test('align: "edge" widens a two-key band by exactly one step over center mode', () => {
+    const step = xScale.step()
+    const centerFrom = xScale('b') as number
+    const centerTo = xScale('c') as number
+    const centerMarkup = render([{ from: 'b', to: 'c', fill: 'red' }])
+    const edgeMarkup = render([{ from: 'b', to: 'c', fill: 'red', align: 'edge' }])
+    expect(centerMarkup).toContain(`width="${centerTo - centerFrom}"`)
+    const edgeFrom = edgeBound('b', -1)
+    const edgeTo = edgeBound('c', 1)
+    expect(edgeMarkup).toContain(`x="${edgeFrom}"`)
+    expect(edgeMarkup).toContain(`width="${edgeTo - edgeFrom}"`)
+    expect(edgeTo - edgeFrom).toBeCloseTo(centerTo - centerFrom + step, 10)
+  })
+
+  test('align: "edge" with from === to renders exactly one step wide, where center renders nothing', () => {
+    const step = xScale.step()
+    const centerMarkup = render([{ from: 'b', to: 'b', fill: 'red' }])
+    const edgeMarkup = render([{ from: 'b', to: 'b', fill: 'red', align: 'edge' }])
+    expect(centerMarkup).not.toContain('<rect')
+    const edgeFrom = edgeBound('b', -1)
+    const edgeTo = edgeBound('b', 1)
+    expect(edgeMarkup).toContain(`x="${edgeFrom}"`)
+    expect(edgeMarkup).toContain(`width="${edgeTo - edgeFrom}"`)
+    expect(edgeTo - edgeFrom).toBeCloseTo(step, 10)
+  })
+
+  test('an unknown key is skipped in both align modes', () => {
+    const centerMarkup = render([{ from: 'not-in-domain', to: 'c', fill: 'red' }])
+    const edgeMarkup = render([{ from: 'not-in-domain', to: 'c', fill: 'red', align: 'edge' }])
+    expect(centerMarkup).not.toContain('<rect')
+    expect(edgeMarkup).not.toContain('<rect')
+  })
+
+  test('align: "edge" clamps the widened left edge at the first sample into the plot range', () => {
+    const [rangeStart] = xScale.range() as [number, number]
+    const markup = render([{ from: 'a', to: 'a', fill: 'red', align: 'edge' }])
+    const edgeTo = edgeBound('a', 1)
+    expect(markup).toContain(`x="${rangeStart}"`)
+    expect(markup).toContain(`width="${edgeTo - rangeStart}"`)
+  })
+
+  test('align: "edge" clamps the widened right edge at the last sample into the plot range', () => {
+    const [, rangeEnd] = xScale.range() as [number, number]
+    const markup = render([{ from: 'd', to: 'd', fill: 'red', align: 'edge' }])
+    const edgeFrom = edgeBound('d', -1)
+    expect(markup).toContain(`x="${edgeFrom}"`)
+    expect(markup).toContain(`width="${rangeEnd - edgeFrom}"`)
+  })
 })

package/src/charts/primitives/XZoneRects.tsx

@@ -13,6 +13,50 @@ export type XZoneSpec = {
   /** Right edge — a domain key produced by the kind's `getX`. Omit for "end of the plot area". */
   to?: string
   fill: string
+  /**
+   * `'center'` (default, unchanged behaviour) resolves a present bound to `xScale(key)` — the
+   * point's own center, so a band reads "from this sample to that sample" rather than
+   * edge-to-edge. `'edge'` resolves a present `from` to `xScale(from) - step/2` and a present `to`
+   * to `xScale(to) + step/2` (`step` read from `xScale.step()`), so the band covers both terminal
+   * slots in full — a two-key band widens by exactly one step, and `from === to` renders one step
+   * wide instead of being skipped as degenerate. An omitted `from`/`to` still resolves to the plot
+   * edge (`xScale.range()[0]`/`[1]`) in both modes, unshifted — omission means "the plot's own
+   * edge", not "the first/last sample's edge". A resolved `'edge'` bound is clamped into the plot
+   * range so a band anchored at the first or last sample cannot paint outside the plot area.
+   */
+  align?: 'center' | 'edge'
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Resolves one zone bound (`from` or `to`) to a pixel x. `edgeSign` is `-1` for `from` (subtract
+ * half a step) and `+1` for `to` (add half a step) — only consulted in `'edge'` mode.
+ */
+function resolveBound({
+  key,
+  omittedEdge,
+  xScale,
+  align,
+  edgeSign,
+  rangeMin,
+  rangeMax,
+}: {
+  key: string | undefined
+  omittedEdge: number
+  xScale: PointScale
+  align: 'center' | 'edge'
+  edgeSign: -1 | 1
+  rangeMin: number
+  rangeMax: number
+}): number | undefined {
+  if (key === undefined) return omittedEdge
+  const center = xScale(key)
+  if (center === undefined) return undefined
+  if (align === 'center') return center
+  return clamp(center + edgeSign * (xScale.step() / 2), rangeMin, rangeMax)
 }
 
 /**
@@ -20,18 +64,20 @@ export type XZoneSpec = {
  * <rect> per zone, spanning y=[0, height] and x=[scale(from), scale(to)]. The x analog of
  * `ZoneRects`, for a `scalePoint` x-axis instead of a `scaleLinear` y-axis.
  *
- * An omitted `from` resolves to `0` (start of the plot area); an omitted `to` resolves to
- * `xScale.range()[1]` (the plot's right edge). A present key resolves to `xScale(key)` — the
- * POINT CENTER, so a band reads as "from this sample to that sample", not edge-to-edge.
+ * Bound resolution depends on `XZoneSpec.align` (see its JSDoc for the full `'center'`/`'edge'`
+ * contract) — default `'center'` resolves a present key to the point's own center; `'edge'`
+ * widens by half a step at each present bound so the band covers the terminal slots in full.
  *
  * A key that is not in the scale's domain skips that band entirely (renders nothing for it) —
- * it is NEVER clamped to a plot edge. Clamping would silently paint a band across the whole
- * chart for a typo'd or stale key, which is the exact class of quiet lie the repo's "nothing to
- * draw is two different states" doctrine rejects: an unknown key must read as "not drawn", not
- * as "the whole plot".
+ * it is NEVER clamped to a plot edge, in either mode. Clamping an unknown key would silently
+ * paint a band across the whole chart for a typo'd or stale key, which is the exact class of
+ * quiet lie the repo's "nothing to draw is two different states" doctrine rejects: an unknown key
+ * must read as "not drawn", not as "the whole plot".
  *
  * A degenerate resolved range (right edge <= left edge, e.g. an inverted `from`/`to` pair) is
- * also skipped — no negative-width rect.
+ * also skipped — no negative-width rect. In `'center'` mode `from === to` is degenerate (skipped,
+ * today's behaviour); in `'edge'` mode it is NOT — the half-step widening on each side always
+ * produces a positive-width, one-step-wide rect.
  */
 export function XZoneRects({
   zones,
@@ -47,8 +93,27 @@ export function XZoneRects({
     <>
       {zones.map((z, i) => {
         const [rangeStart, rangeEnd] = xScale.range() as [number, number]
-        const xFrom = z.from === undefined ? rangeStart : xScale(z.from)
-        const xTo = z.to === undefined ? rangeEnd : xScale(z.to)
+        const rangeMin = Math.min(rangeStart, rangeEnd)
+        const rangeMax = Math.max(rangeStart, rangeEnd)
+        const align = z.align ?? 'center'
+        const xFrom = resolveBound({
+          key: z.from,
+          omittedEdge: rangeStart,
+          xScale,
+          align,
+          edgeSign: -1,
+          rangeMin,
+          rangeMax,
+        })
+        const xTo = resolveBound({
+          key: z.to,
+          omittedEdge: rangeEnd,
+          xScale,
+          align,
+          edgeSign: 1,
+          rangeMin,
+          rangeMax,
+        })
         if (xFrom === undefined || xTo === undefined) return null
         if (xTo <= xFrom) return null
         return (

package/src/charts/series.test.ts

@@ -58,4 +58,55 @@ describe('deriveTooltipRows', () => {
     )
     expect(rows[0]?.value).toBe('42%')
   })
+
+  test('formatValue receives the hovered datum alongside the value', () => {
+    type Set = { v: number; reps: number }
+    const rows = deriveTooltipRows(
+      [
+        {
+          key: 'set',
+          label: 'Set',
+          color: '#000',
+          mark: 'bar' as const,
+          getValue: (d: Set) => d.v,
+          formatValue: (v: number, d: Set) => `${v} kg (${d.reps} reps)`,
+        },
+      ],
+      { v: 97.5, reps: 3 },
+      fmt,
+    )
+    expect(rows[0]?.value).toBe('97.5 kg (3 reps)')
+  })
+
+  test('the fallback formatter (single-arg) still works once formatValue is 2-arg typed', () => {
+    const rows = deriveTooltipRows([{ ...base, key: 'a', label: 'A' }], { v: 5 }, fmt)
+    expect(rows[0]?.value).toBe('5')
+  })
+})
+
+describe('strokeOpacity — a mark property, not a tooltip property', () => {
+  test('reaches the derived legend entry', () => {
+    const [entry] = deriveLegend([{ ...baseSeries, strokeOpacity: 0.4 }])
+    expect(entry?.strokeOpacity).toBe(0.4)
+  })
+
+  test('is absent from the legend entry when unset', () => {
+    const [entry] = deriveLegend([baseSeries])
+    expect(entry).not.toHaveProperty('strokeOpacity')
+  })
+
+  test('never reaches TooltipRowData — the row is a 12px value chip, not a dimmed mark', () => {
+    const rows = deriveTooltipRows(
+      [
+        {
+          ...baseSeries,
+          strokeOpacity: 0.4,
+          getValue: () => 10,
+        },
+      ],
+      {},
+      (v) => String(v),
+    )
+    expect(rows[0]).not.toHaveProperty('strokeOpacity')
+  })
 })