basalt-ui 1.14.0 → 1.16.0

package/src/charts/primitives/ChartFrame.tsx

@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from 'react'
+import { useCallback, useState } from 'react'
 import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
@@ -20,6 +21,13 @@ export type ChartFrameLegend = {
   /** Hover-dim wiring lifted from the kind — optional. */
   highlighted?: string | null
   onHighlight?: (key: string | null) => void
+  /**
+   * Clicking a legend entry hides that series. Defaults to true whenever there is more than one
+   * entry to toggle between — hiding the only series a chart draws is never useful. The hidden
+   * key set reaches the marks through the `children` render prop, so a hidden series leaves the
+   * plot, the tooltip, and the auto domain together (`docs/CHARTS-SPEC.md` §5).
+   */
+  toggle?: boolean
 }
 
 export type ChartFrameProps = {
@@ -50,8 +58,16 @@ export type ChartFrameProps = {
    * kind composing `ChartFrame` should accept and forward this from its own props.
    */
   ariaLabel?: string
-  /** Draw the SVG marks given the plot rect that already excludes the legend band. */
-  children: (plot: { width: number; height: number }) => ReactNode
+  /** Draw the SVG marks given the plot rect that already excludes the legend band, plus the set
+   * of series keys the legend has toggled off. */
+  children: (plot: PlotRect) => ReactNode
+}
+
+/** What `ChartFrame` hands its child: the resolved plot rect plus legend-toggle state. */
+export type PlotRect = {
+  width: number
+  height: number
+  hidden: ReadonlySet<string>
 }
 
 const outerStyle = (fill: boolean, vertical: boolean): CSSProperties => ({
@@ -89,6 +105,7 @@ export function resolveLegend(
     placement: config?.placement ?? 'bottom',
     ...(config?.groups !== undefined && { groups: config.groups }),
     ...(config?.maxRows !== undefined && { maxRows: config.maxRows }),
+    ...(config?.toggle !== undefined && { toggle: config.toggle }),
     ...(hover !== undefined && { highlighted: hover.highlighted, onHighlight: hover.onHighlight }),
   }
 }
@@ -119,6 +136,16 @@ export function ChartFrame({
 }: ChartFrameProps): ReactNode {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize()
   const { ref: legendRef, width: legendW, height: legendH } = useChartSize()
+  const [hidden, setHidden] = useState<ReadonlySet<string>>(() => new Set())
+
+  const toggleKey = useCallback((key: string) => {
+    setHidden((prev) => {
+      const next = new Set(prev)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }, [])
 
   const placement = legend === false ? 'bottom' : (legend.placement ?? 'bottom')
   const vertical = placement === 'left' || placement === 'right'
@@ -138,12 +165,17 @@ export function ChartFrame({
     height: resolvedHeight - topBottomLegendHeight,
   }
 
+  const legendItems = legend === false ? [] : deriveLegend(series)
+  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
+
   const legendNode =
     legend === false || isPending ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>
         <ChartLegend
-          items={deriveLegend(series)}
+          items={legendItems}
           placement={placement}
+          hidden={hidden}
+          {...(togglable && { onToggle: toggleKey })}
           {...(chartId !== undefined && { chartId })}
           {...(legend.groups !== undefined && { groups: legend.groups })}
           {...(legend.maxRows !== undefined && { maxRows: legend.maxRows })}
@@ -163,7 +195,11 @@ export function ChartFrame({
       {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}
       {plot.width > 0 &&
         plot.height > 0 &&
-        (isPending ? <ChartPending width={plot.width} height={plot.height} /> : children(plot))}
+        (isPending ? (
+          <ChartPending width={plot.width} height={plot.height} />
+        ) : (
+          children({ ...plot, hidden })
+        ))}
       {legendNode !== null && (placement === 'bottom' || placement === 'right') && legendNode}
     </div>
   )

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

@@ -0,0 +1,78 @@
+/**
+ * `ChartLegend` — the `note` qualifier. Same SSR harness as `ChartFrame.test.tsx`:
+ * `src/charts/**` is Mantine-free, so `renderToStaticMarkup` needs no provider wrapper.
+ */
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { ChartLegend } from './ChartLegend'
+import type { LegendEntry } from './ChartLegend'
+
+const BASE: LegendEntry = { key: 'cloud-low', label: 'Low cloud', color: 'var(--vx-fill-1)' }
+
+const render = (items: LegendEntry[]): string => renderToStaticMarkup(<ChartLegend items={items} />)
+
+describe('ChartLegend note', () => {
+  test('renders after the label when set', () => {
+    const markup = render([{ ...BASE, note: '0% all night' }])
+    expect(markup).toContain('Low cloud')
+    expect(markup).toContain('0% all night')
+  })
+
+  test('is absent when unset', () => {
+    expect(render([BASE])).not.toContain('<span style="opacity:0.75">')
+  })
+
+  test('an empty note renders no span (truthiness, not !== undefined)', () => {
+    expect(render([{ ...BASE, note: '' }])).not.toContain('<span style="opacity:0.75">')
+  })
+
+  test('reaches the accessible name — the explicit aria-label would otherwise replace it', () => {
+    const markup = render([{ ...BASE, note: '0% all night' }])
+    expect(markup).toContain('aria-label="Low cloud — 0% all night"')
+  })
+
+  test('aria-label stays the bare label when there is no note', () => {
+    expect(render([BASE])).toContain('aria-label="Low cloud"')
+  })
+
+  test('a folded companion carries its own note', () => {
+    const markup = render([
+      {
+        ...BASE,
+        children: [{ key: 'ma', label: '7d MA', color: 'var(--vx-fill-2)', note: 'est.' }],
+      },
+    ])
+    expect(markup).toContain('7d MA')
+    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,11 +13,17 @@ 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,
    * subordinate sub-entries beside the parent's label instead of vanishing. */
   children?: LegendEntry[]
+  /** Short qualifier rendered after the label in muted text — e.g. a flat-at-zero series that is
+   * invisible in the plot. */
+  note?: string
 }
 
 const LEGEND_ITEM_BASE: CSSProperties = {
@@ -44,6 +50,9 @@ const LEGEND_ITEM_BUTTON: CSSProperties = {
 
 const GROUP_ORDER: SeriesRole[] = ['series', 'overlay', 'reference']
 
+/** Stable empty set — a fresh `new Set()` default would be a new identity on every render. */
+const NO_HIDDEN: ReadonlySet<string> = new Set()
+
 const roleOf = (item: LegendEntry): SeriesRole => item.role ?? 'series'
 
 /** Order entries series → overlay → reference and record where a divider belongs. */
@@ -107,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
@@ -116,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>
@@ -167,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}
       />
@@ -174,6 +186,13 @@ function LegendSwatch({ item, idPrefix }: { item: LegendEntry; idPrefix: string
   )
 }
 
+// Same dimming as `LEGEND_CHILD_STYLE` below — the legend wrapper already sets the base text color
+// to `VX.muted` (`wrapperStyle`), so subordinate text is just that color at reduced opacity, never
+// a second color token.
+const LEGEND_NOTE_STYLE: CSSProperties = {
+  opacity: 0.75,
+}
+
 const LEGEND_CHILD_STYLE: CSSProperties = {
   display: 'flex',
   alignItems: 'center',
@@ -209,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>
@@ -221,6 +241,9 @@ function LegendChild({ item }: { item: LegendEntry }) {
     <span style={LEGEND_CHILD_STYLE}>
       <LegendChildSwatch item={item} />
       <span>{item.label}</span>
+      {/* No LEGEND_NOTE_STYLE here — LEGEND_CHILD_STYLE already dims the whole child block, and
+          compounding the two opacities would push a folded companion's note near-invisible. */}
+      {item.note ? <span>{item.note}</span> : null}
     </span>
   )
 }
@@ -232,11 +255,17 @@ function LegendChild({ item }: { item: LegendEntry }) {
  * reference bands instead of one flat smear. `maxRows` caps the number of rendered entries and
  * rolls the remainder into a `+N more` chip (row-accurate wrap measurement is `ChartFrame`'s job —
  * this is an entry-count cap, a deliberate simplification until that primitive lands).
+ *
+ * `onToggle` makes an entry a real toggle: clicking it hides the series in the plot, the tooltip,
+ * and the auto y-domain together (`ChartFrame` owns the `hidden` set — see `docs/CHARTS-SPEC.md`
+ * §5). Omit it for a static legend; a hidden entry is announced via `aria-pressed`.
  */
 export function ChartLegend({
   items,
   highlighted = null,
   onHighlight,
+  hidden = NO_HIDDEN,
+  onToggle,
   chartId = '',
   placement = 'bottom',
   groups = false,
@@ -245,6 +274,10 @@ export function ChartLegend({
   items: LegendEntry[]
   highlighted?: string | null
   onHighlight?: (key: string | null) => void
+  /** Keys currently toggled off. */
+  hidden?: ReadonlySet<string>
+  /** Present = entries are clickable toggles. */
+  onToggle?: (key: string) => void
   chartId?: string
   placement?: LegendPlacement
   groups?: boolean
@@ -255,6 +288,10 @@ export function ChartLegend({
     if (key !== undefined) onHighlight?.(key)
   }
   const handleLeave = () => onHighlight?.(null)
+  const handleToggle = (e: MouseEvent<HTMLButtonElement>) => {
+    const key = e.currentTarget.dataset['legendKey']
+    if (key !== undefined) onToggle?.(key)
+  }
 
   const idPrefix = chartId ? `${chartId}-` : ''
   const vertical = placement === 'left' || placement === 'right'
@@ -270,11 +307,23 @@ export function ChartLegend({
         key={item.key}
         type="button"
         data-legend-key={item.key}
-        aria-label={item.label}
+        // The note is the whole point for a series that is invisible in the plot, so it has to
+        // reach a screen reader too — an explicit aria-label would otherwise replace it.
+        aria-label={item.note ? `${item.label} — ${item.note}` : item.label}
+        {...(onToggle !== undefined && { 'aria-pressed': !hidden.has(item.key) })}
         style={{
           ...LEGEND_ITEM_BUTTON,
-          opacity: highlighted === null || highlighted === item.key ? 1 : 0.3,
+          cursor: onToggle === undefined ? 'default' : 'pointer',
+          // Toggled-off wins over hover-dimming: a hidden series must read as hidden even while
+          // it is the one being hovered.
+          opacity: hidden.has(item.key)
+            ? 0.35
+            : highlighted === null || highlighted === item.key
+              ? 1
+              : 0.3,
+          textDecoration: hidden.has(item.key) ? 'line-through' : 'none',
         }}
+        {...(onToggle !== undefined && { onClick: handleToggle })}
         onMouseEnter={handleEnter}
         onMouseLeave={handleLeave}
         onFocus={handleEnter}
@@ -282,6 +331,7 @@ export function ChartLegend({
       >
         <LegendSwatch item={item} idPrefix={idPrefix} />
         <span>{item.label}</span>
+        {item.note ? <span style={LEGEND_NOTE_STYLE}>{item.note}</span> : null}
         {item.children?.map((child) => (
           <LegendChild key={child.key} item={child} />
         ))}

package/src/charts/primitives/ChartTooltip.tsx

@@ -1,4 +1,5 @@
-import type { CSSProperties, ReactNode, RefObject } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { useLayoutEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { VX } from '../../tokens'
 import { fmtTooltipDate } from '../utils/format'
@@ -20,42 +21,6 @@ const TOOLTIP_STYLES: CSSProperties = {
   minWidth: 140,
 }
 
-/** Theme-aware tooltip container styles — use with useChartTooltip(). */
-export function useTooltipStyles(): CSSProperties {
-  return TOOLTIP_STYLES
-}
-
-/**
- * Outer tooltip shell. Renders nothing when tip is null. Renders to `document.body` via a
- * portal, so it may be authored anywhere in the tree, including inside `<svg>`.
- */
-export function ChartTooltip({
-  tip,
-  tooltipRef,
-  styles,
-  children,
-}: {
-  tip: { x: number; y: number } | null
-  tooltipRef?: RefObject<HTMLDivElement | null>
-  styles: CSSProperties
-  children: ReactNode
-}) {
-  if (!tip) return null
-  // SSR guard: react-dom/server (renderToStaticMarkup, used by this repo's tests — see
-  // dashboard/stat-card.test.tsx) has no jsdom and does not support portals.
-  if (typeof document === 'undefined') return null
-  // Portal to document.body for two reasons: (1) authoring this inside an <svg> tree would
-  // otherwise create the div in the SVG namespace, where it mounts, accepts every prop, and
-  // is never painted; (2) TOOLTIP_STYLES' position: 'fixed' breaks inside any transformed
-  // ancestor unless the node is portalled out to the body.
-  return createPortal(
-    <div ref={tooltipRef} style={{ ...styles, left: tip.x, top: tip.y }}>
-      {children}
-    </div>,
-    document.body,
-  )
-}
-
 /** Tooltip header — shows formatted date + optional right-aligned label with color. */
 export function TooltipHeader({
   date,
@@ -168,3 +133,68 @@ export function TooltipRow({
 export function TooltipBody({ children }: { children: ReactNode }) {
   return <div style={{ padding: '5px 0' }}>{children}</div>
 }
+
+/** Gap between the anchor point and the tooltip box, and the minimum distance kept from the
+ * viewport edge. */
+const TOOLTIP_GAP = 12
+const VIEWPORT_MARGIN = 8
+
+/**
+ * Floating tooltip positioned against a viewport-space anchor, with flip + clamp handled once for
+ * every chart instead of per call site (this used to be recomputed inside each chart's own `useChartTooltip`, and only for
+ * charts that remembered to use it).
+ *
+ * The box is measured after mount via `useLayoutEffect`, so the first paint of a given tooltip is
+ * hidden rather than misplaced — a tooltip that flashes at the wrong corner reads as a bug.
+ */
+export function ChartTooltipFloat({
+  anchor,
+  children,
+}: {
+  anchor: { x: number; y: number } | null
+  children: ReactNode
+}) {
+  const ref = useRef<HTMLDivElement>(null)
+  const [box, setBox] = useState<{ width: number; height: number } | null>(null)
+
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (el === null) return
+    const { offsetWidth, offsetHeight } = el
+    setBox((prev) =>
+      prev !== null && prev.width === offsetWidth && prev.height === offsetHeight
+        ? prev
+        : { width: offsetWidth, height: offsetHeight },
+    )
+  }, [children, anchor])
+
+  if (anchor === null) return null
+  // SSR guard: react-dom/server has no jsdom and does not support portals.
+  if (typeof document === 'undefined') return null
+
+  const width = box?.width ?? 0
+  const height = box?.height ?? 0
+  const vw = window.innerWidth
+  const vh = window.innerHeight
+
+  const flipsLeft = anchor.x + TOOLTIP_GAP + width + VIEWPORT_MARGIN > vw
+  const left = flipsLeft
+    ? Math.max(VIEWPORT_MARGIN, anchor.x - TOOLTIP_GAP - width)
+    : anchor.x + TOOLTIP_GAP
+  const top = Math.min(
+    Math.max(VIEWPORT_MARGIN, anchor.y - TOOLTIP_GAP),
+    Math.max(VIEWPORT_MARGIN, vh - height - VIEWPORT_MARGIN),
+  )
+
+  return createPortal(
+    <div
+      ref={ref}
+      role="tooltip"
+      aria-live="polite"
+      style={{ ...TOOLTIP_STYLES, left, top, visibility: box === null ? 'hidden' : 'visible' }}
+    >
+      {children}
+    </div>,
+    document.body,
+  )
+}

package/src/charts/primitives/HoverOverlay.tsx

@@ -1,23 +1,59 @@
-import type { PointerEventHandler } from 'react'
+import type { FocusEventHandler, KeyboardEventHandler, PointerEventHandler } from 'react'
 
-/** Transparent <rect> that captures pointer events (mouse + touch + pen) for tooltip + crosshair
- * sync. */
+/**
+ * Transparent <rect> that captures pointer events (mouse + touch + pen) for tooltip + crosshair
+ * sync.
+ *
+ * With `onKeyDown` it also becomes the chart's keyboard affordance: the rect takes focus and
+ * ←/→ scrub the cursor, so a chart's values are reachable without a pointer.
+ */
 export function HoverOverlay({
   width,
   height,
   onMove,
   onLeave,
+  onKeyDown,
+  onBlur,
+  ariaLabel,
+  valueNow,
+  valueMax,
+  valueText,
 }: {
   width: number
   height: number
   onMove: PointerEventHandler<SVGRectElement>
   onLeave: PointerEventHandler<SVGRectElement>
+  /** Present = the overlay is focusable and scrubs on ←/→. */
+  onKeyDown?: KeyboardEventHandler<SVGRectElement>
+  onBlur?: FocusEventHandler<SVGRectElement>
+  ariaLabel?: string
+  /** Index of the focused point — announced as the slider position. */
+  valueNow?: number
+  /** Last index of the domain. */
+  valueMax?: number
+  /** Human-readable label for the focused point (the formatted x key). */
+  valueText?: string
 }) {
   return (
     <rect
       width={width}
       height={height}
       fill="transparent"
+      {...(onKeyDown !== undefined && {
+        tabIndex: 0,
+        // `slider`, not `application`: `application` would drop this node out of the screen
+        // reader's normal browse mode entirely, which is a far bigger hammer than an arrow-key
+        // scrub needs. A slider announces both the affordance and the focused point.
+        role: 'slider',
+        'aria-label': ariaLabel ?? 'Chart data — use arrow keys to scrub',
+        'aria-orientation': 'horizontal' as const,
+        'aria-valuemin': 0,
+        ...(valueMax !== undefined && { 'aria-valuemax': valueMax }),
+        ...(valueNow !== undefined && { 'aria-valuenow': valueNow }),
+        ...(valueText !== undefined && { 'aria-valuetext': valueText }),
+        onKeyDown,
+        ...(onBlur !== undefined && { onBlur }),
+      })}
       // `pan-y`, not `none`: `none` would turn a full-width chart into a scroll dead zone on a
       // phone. `pan-y` lets vertical page scroll pass through while a horizontal drag still
       // reaches this overlay to scrub the chart.

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

@@ -0,0 +1,123 @@
+/**
+ * `XZoneRects` — the x-analog of `ZoneRects`. Same SSR harness as `ChartFrame.test.tsx`:
+ * `src/charts/**` is Mantine-free, so `renderToStaticMarkup` needs no provider wrapper.
+ */
+import { scalePoint } from '@visx/scale'
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { XZoneRects } from './XZoneRects'
+import type { XZoneSpec } from './XZoneRects'
+
+const DOMAIN = ['a', 'b', 'c', 'd']
+const xScale = scalePoint<string>({ domain: DOMAIN, range: [0, 100], padding: 0.3 })
+
+function render(zones: XZoneSpec[]): string {
+  return renderToStaticMarkup(<XZoneRects zones={zones} height={50} xScale={xScale} />)
+}
+
+describe('XZoneRects', () => {
+  test('both bounds present -> rect spans center-to-center', () => {
+    const from = xScale('b') as number
+    const to = xScale('c') as number
+    const markup = render([{ from: 'b', to: 'c', fill: 'red' }])
+    expect(markup).toContain(`x="${from}"`)
+    expect(markup).toContain(`width="${to - from}"`)
+    expect(markup).toContain('height="50"')
+    expect(markup).toContain('fill="red"')
+  })
+
+  test('omitted from -> resolves to the plot left edge (0)', () => {
+    const to = xScale('b') as number
+    const [rangeStart] = xScale.range() as [number, number]
+    const markup = render([{ to: 'b', fill: 'red' }])
+    expect(markup).toContain(`x="${rangeStart}"`)
+    expect(markup).toContain(`width="${to - rangeStart}"`)
+  })
+
+  test('omitted to -> resolves to the plot right edge (xScale.range()[1])', () => {
+    const from = xScale('c') as number
+    const [, rangeEnd] = xScale.range() as [number, number]
+    const markup = render([{ from: 'c', fill: 'red' }])
+    expect(markup).toContain(`x="${from}"`)
+    expect(markup).toContain(`width="${rangeEnd - from}"`)
+  })
+
+  test('an unknown key skips the band entirely — no rect, no clamping to a plot edge', () => {
+    const markup = render([{ from: 'not-in-domain', to: 'c', fill: 'red' }])
+    expect(markup).not.toContain('<rect')
+  })
+
+  test('an inverted range (to before from) renders no rect', () => {
+    const markup = render([{ from: 'c', to: 'a', fill: 'red' }])
+    expect(markup).not.toContain('<rect')
+  })
+
+  test('a degenerate zero-width range (from === to) renders no rect', () => {
+    const markup = render([{ from: 'b', to: 'b', fill: 'red' }])
+    expect(markup).not.toContain('<rect')
+  })
+
+  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}"`)
+  })
+})