basalt-ui 1.14.0 → 1.15.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,48 @@
+/**
+ * `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.')
+  })
+})

package/src/charts/primitives/ChartLegend.tsx

@@ -18,6 +18,9 @@ export type LegendEntry = {
   /** 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 +47,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. */
@@ -174,6 +180,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',
@@ -221,6 +234,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 +248,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 +267,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 +281,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 +300,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 +324,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,63 @@
+/**
+ * `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')
+  })
+})

package/src/charts/primitives/XZoneRects.tsx

@@ -0,0 +1,67 @@
+import type { scalePoint } from '@visx/scale'
+
+/**
+ * The point-scale instance type, derived from `@visx/scale`'s own `scalePoint` return type.
+ * Equivalent to d3's `ScalePoint<string>` but resolved through `@visx/scale` (an installed dep) so
+ * it needs no `@types/d3-scale` and stays inside the visx-only-in-charts boundary.
+ */
+type PointScale = ReturnType<typeof scalePoint<string>>
+
+export type XZoneSpec = {
+  /** Left edge — a domain key produced by the kind's `getX`. Omit for "start of the plot area". */
+  from?: string
+  /** Right edge — a domain key produced by the kind's `getX`. Omit for "end of the plot area". */
+  to?: string
+  fill: string
+}
+
+/**
+ * Vertical zone backgrounds (x-range overlays — twilight bands, a shaded time window) — one
+ * <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.
+ *
+ * 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".
+ *
+ * A degenerate resolved range (right edge <= left edge, e.g. an inverted `from`/`to` pair) is
+ * also skipped — no negative-width rect.
+ */
+export function XZoneRects({
+  zones,
+  height,
+  xScale,
+}: {
+  zones: XZoneSpec[]
+  /** Plot-area height (yMax); rects span from 0 to this. */
+  height: number
+  xScale: PointScale
+}) {
+  return (
+    <>
+      {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)
+        if (xFrom === undefined || xTo === undefined) return null
+        if (xTo <= xFrom) return null
+        return (
+          <rect
+            key={`xzone-${i}`}
+            x={xFrom}
+            y={0}
+            width={xTo - xFrom}
+            height={height}
+            fill={z.fill}
+          />
+        )
+      })}
+    </>
+  )
+}

package/src/charts/series.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test'
+import { deriveLegend, deriveTooltipRows } from './series'
+import type { SeriesStyle } from './series'
+
+const baseSeries: SeriesStyle = {
+  key: 'low-cloud',
+  label: 'Low cloud',
+  color: '#000',
+  mark: 'line',
+}
+
+describe('deriveLegend note passthrough', () => {
+  test('carries note through when set', () => {
+    const [entry] = deriveLegend([{ ...baseSeries, note: '0% all night' }])
+    expect(entry?.note).toBe('0% all night')
+  })
+
+  test('omits the note key entirely when unset', () => {
+    const [entry] = deriveLegend([baseSeries])
+    expect(entry).not.toHaveProperty('note')
+  })
+})
+
+describe('deriveTooltipRows', () => {
+  type Row = { v: number }
+  const base = { color: '#000', mark: 'bar' as const, getValue: (d: Row) => d.v }
+  const fmt = (v: number) => String(v)
+
+  test('a `tooltip: false` series is drawn and legended but produces no row', () => {
+    const rows = deriveTooltipRows(
+      [
+        { ...base, key: 'shown', label: 'Shown' },
+        { ...base, key: 'quiet', label: 'Quiet', tooltip: false },
+      ],
+      { v: 1 },
+      fmt,
+    )
+    expect(rows.map((r) => r.key)).toEqual(['shown'])
+    expect(deriveLegend([{ ...base, key: 'quiet', label: 'Quiet', tooltip: false }])).toHaveLength(
+      1,
+    )
+  })
+
+  test('a null value still skips its row', () => {
+    const rows = deriveTooltipRows(
+      [{ ...base, key: 'gap', label: 'Gap', getValue: () => null }],
+      { v: 1 },
+      fmt,
+    )
+    expect(rows).toHaveLength(0)
+  })
+
+  test('a per-series formatValue wins over the shared fallback', () => {
+    const rows = deriveTooltipRows(
+      [{ ...base, key: 'a', label: 'A', formatValue: (v) => `${v}%` }],
+      { v: 42 },
+      fmt,
+    )
+    expect(rows[0]?.value).toBe('42%')
+  })
+})