basalt-ui 2.2.0 → 2.4.0

package/src/charts/Bars.tsx

@@ -27,7 +27,7 @@ export type BarsBar<T> = Pick<
   'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'
 > & {
   /** Default 0.85. */
-  fillOpacity?: number
+  fillOpacity?: number | undefined
 }
 
 /** A line overlay; `axis: 'right'` reads the chart's `y2`. */
@@ -54,11 +54,11 @@ export type BarsProps<T, X extends ChartX = ChartX> = Omit<
   'marks' | 'series'
 > & {
   bars: readonly BarsBar<T>[]
-  lines?: readonly BarsLine<T>[]
+  lines?: readonly BarsLine<T>[] | undefined
   /** Default `'stacked'`. `'normalized'` stacks each x to its share of the total. */
-  layout?: 'stacked' | 'grouped' | 'normalized'
+  layout?: 'stacked' | 'grouped' | 'normalized' | undefined
   /** Per-bar opacity (a partial week, an estimate). Overrides the series' `fillOpacity`. */
-  barOpacity?: (d: T, key: string) => number
+  barOpacity?: ((d: T, key: string) => number) | undefined
 }
 
 const DEFAULT_BAR_OPACITY = 0.85

package/src/charts/CartesianChart.tsx

@@ -9,7 +9,7 @@
 import { useCallback, useId, useMemo, useState } from 'react'
 import type { CSSProperties, ReactElement, ReactNode } from 'react'
 import { useInChartCard } from './card-context'
-import { compileCartesian } from './compile'
+import { compileCartesian, refLegendSeries } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { ChartLegend, legendEntries } from './legend'
@@ -170,9 +170,14 @@ export function CartesianRung<T, X extends ChartX>(
     (ctx: ShellContext) => compileCartesian({ ...stable, ...ctx }),
     [stable],
   )
+  // Reference lines that name themselves join the legend after the series (role `reference`).
+  const legendSeries = useMemo(
+    () => [...stable.series, ...refLegendSeries<T>(stable.refLines)],
+    [stable.series, stable.refLines],
+  )
   return (
     <ChartShell
-      series={series}
+      series={legendSeries}
       compile={compile}
       ariaLabel={ariaLabel}
       {...(legend !== undefined && { legend })}

package/src/charts/ChartCard.tsx

@@ -92,32 +92,38 @@ export type ChartCardSlot = 'root' | 'header' | 'body'
 
 export type ChartCardProps = BasaltProps &
   SlotStylesProps<ChartCardSlot> & {
-    title?: string
+    title?: string | undefined
     icon?: ReactNode
     /** A muted line below the title row; does not by itself render the header. */
-    subtitle?: string
+    subtitle?: string | undefined
     /** `WidgetHeader`'s info glyph beside the title. */
-    info?: string
+    info?: string | undefined
     /** A pre-formatted metric value, with `delta` on the hero row. */
-    value?: string
-    delta?: number
-    deltaPeriod?: string
-    deltaPolarity?: DeltaPolarity
+    value?: string | undefined
+    delta?: number | undefined
+    deltaPeriod?: string | undefined
+    deltaPolarity?: DeltaPolarity | undefined
     /** A mono count tag after the title. */
-    count?: number
+    count?: number | undefined
     /** Right-aligned controls. */
     actions?: ReactNode
     /** A resolved state replaces `children` with its placeholder; the header stays. */
-    state?: ChartState
+    state?: ChartState | undefined
     /** Body height while a placeholder shows. Default: the chart height law, i.e. exactly the box an
      * unsized chart takes — pass the chart's own `height` when it states one, so a `<Suspense
      * fallback={<ChartCard state={{ pending: true }} …/>}>` reserves the final size. */
-    placeholderHeight?: number | ResponsiveChartHeight
+    placeholderHeight?: number | ResponsiveChartHeight | undefined
     /** A retry button or a "clear filters" link under the placeholder. */
     stateAction?: ReactNode
     children?: ReactNode
   }
 
+/** Drops explicit `undefined`s: `WidgetHeader` is exact-optional, this props type is not. */
+const definedOnly = <T extends object>(o: T): { [K in keyof T]?: Exclude<T[K], undefined> } =>
+  Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as {
+    [K in keyof T]?: Exclude<T[K], undefined>
+  }
+
 /** A header renders when one of these is set (a subtitle or delta alone does not). */
 const HEADER_TRIGGERS = ['title', 'info', 'value', 'icon', 'count'] as const
 
@@ -150,7 +156,7 @@ export function ChartCard({
           <div className={cx(classes.header, classNames?.header)}>
             <WidgetHeader
               tier="widget"
-              {...header}
+              {...definedOnly(header)}
               title={header.title ?? ''}
               {...(actions !== undefined && {
                 actions: <span data-basalt-tier="widget">{actions}</span>,

package/src/charts/Donut.tsx

@@ -34,13 +34,13 @@ export type DonutProps<K extends string = string> = BasaltProps & {
   colorForKey: (key: K) => string
   formatValue: (v: number) => string
   /** Legend and tooltip label for a key. Default: the key. */
-  seriesLabel?: (key: K) => string
+  seriesLabel?: ((key: K) => string) | undefined
   /** The ring's centre text, and the smaller line under it. */
-  centerLabel?: string
-  centerSubLabel?: string
+  centerLabel?: string | undefined
+  centerSubLabel?: string | undefined
   /** Default 240. */
-  height?: number | ResponsiveChartHeight
-  state?: ChartState
+  height?: number | ResponsiveChartHeight | undefined
+  state?: ChartState | undefined
 }
 
 /** Slices kept before the rest fold into "Other". */

package/src/charts/DualPanel.tsx

@@ -14,7 +14,7 @@ import { useCallback, useMemo } from 'react'
 import type { ReactElement } from 'react'
 import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { defaultFormatX, defaultNumberFormat, visibleSeries } from './compile'
+import { defaultFormatX, defaultNumberFormat, engineRow, seriesRow, visibleSeries } from './compile'
 import { barMark, emphasis, lineMark, markersOf, thinFill } from './marks'
 import { PanelRung, paneX, paneY, rowsOf } from './panel'
 import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
@@ -61,15 +61,17 @@ export type DualPanelBar<T> = {
   positive: string
   /** The fill below zero. */
   negative: string
-  /** Tick and tooltip formatter. */
+  /** Tick formatter, and the tooltip's too unless `tooltipFormat` is given. */
   format: (v: number) => string
+  /** The tooltip row's formatter. Default: `format`. */
+  tooltipFormat?: ((v: number) => string) | undefined
   /** The tooltip row's value, for a unit or a decimal `format` cannot carry. */
-  formatValue?: (v: number, d: T) => string
+  formatValue?: ((v: number, d: T) => string) | undefined
   /** Default `'auto'`: a symmetric `[-maxAbs, maxAbs]` from the data, rounded to nice ticks. A tuple
    * is used verbatim. */
-  domain?: readonly [number, number] | 'auto'
+  domain?: readonly [number, number] | 'auto' | undefined
   /** When `'auto'`: floors `maxAbs`, so a plateau does not amplify to fill the pane. */
-  maxAbsFloor?: number
+  maxAbsFloor?: number | undefined
 }
 
 export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
@@ -91,15 +93,24 @@ export type DualPanelProps<T, X extends Date | number = Date | number> = Pick<
   series: readonly DualPanelLine<T>[]
   /** Top pane y axis. Default domain `'auto'`: the visible lines' span plus 8%, rounded to nice
    * ticks (not zero-based: the interesting range is often a narrow band far from zero). */
-  top?: { domain?: readonly [number, number] | 'auto'; format?: (v: number) => string }
+  top?:
+    | {
+        domain?: readonly [number, number] | 'auto' | undefined
+        format?: ((v: number) => string) | undefined
+        /** The lines' tooltip formatter. Default: `format`. */
+        tooltipFormat?: ((v: number) => string) | undefined
+      }
+    | undefined
   /**
    * Shades the band between two top lines (by key), where both are visible. `aboveFill` colours the
    * side where `to` runs above `from`; omitted, both sides take `fill`.
    */
-  fillBetween?: { from: string; to: string; fill: string; aboveFill?: string }
+  fillBetween?:
+    | { from: string; to: string; fill: string; aboveFill?: string | undefined }
+    | undefined
   bar: DualPanelBar<T>
   /** The top pane's share of the chart height. Default 0.62. */
-  topFraction?: number
+  topFraction?: number | undefined
 }
 
 type FillRow<T, X> = { x: X; from: number; to: number; series: string; datum: T }
@@ -150,6 +161,8 @@ export function DualPanel<T, X extends Date | number = Date | number>(
   )
   const all = useMemo(() => [...lines, barSeries], [lines, barSeries])
   const topFormat = top?.format ?? defaultNumberFormat
+  const topTooltipFormat = top?.tooltipFormat ?? topFormat
+  const barTooltipFormat = bar.tooltipFormat ?? bar.format
 
   const plan = useCallback(
     ({ hidden, highlighted }: PanelInput): PanelPlan<T> => {
@@ -300,26 +313,42 @@ export function DualPanel<T, X extends Date | number = Date | number>(
           for (const s of visible) {
             const v = s.getValue(d)
             if (s.tooltip === false || v === null || !Number.isFinite(v)) continue
-            out.push({
-              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-              value: s.formatValue ? s.formatValue(v, d) : topFormat(v),
-              color: s.color,
-              ...(highlighted === s.key && { active: true }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : topTooltipFormat(v),
+                highlighted === s.key,
+              ),
+            )
           }
           const v = barOn ? bar.getValue(d) : null
           if (v !== null && Number.isFinite(v))
-            out.push({
-              label: bar.label,
-              value: bar.formatValue ? bar.formatValue(v, d) : bar.format(v),
-              color: v >= 0 ? bar.positive : bar.negative,
-              ...(highlighted === BAR_KEY && { active: true }),
-            })
+            out.push(
+              engineRow({
+                label: bar.label,
+                value: bar.formatValue ? bar.formatValue(v, d) : barTooltipFormat(v),
+                color: v >= 0 ? bar.positive : bar.negative,
+                active: highlighted === BAR_KEY,
+              }),
+            )
           return out
         },
       }
     },
-    [data, x, lines, barSeries, top, fillBetween, bar, topFraction, topFormat, formatX],
+    [
+      data,
+      x,
+      lines,
+      barSeries,
+      top,
+      fillBetween,
+      bar,
+      topFraction,
+      topFormat,
+      topTooltipFormat,
+      barTooltipFormat,
+      formatX,
+    ],
   )
 
   return <PanelRung {...rung} series={all} plan={plan} />

package/src/charts/Heatmap.tsx

@@ -18,7 +18,7 @@ import type { CSSProperties, ReactElement } from 'react'
 import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { strideTicks } from './compile'
+import { engineRow, strideTicks } from './compile'
 import type { CartesianDefinition } from './compile'
 import { ChartEngine, idPrefixOf } from './host'
 import { useCoarsePointer } from '../common/use-media-query'
@@ -38,28 +38,28 @@ export type HeatmapProps<T> = BasaltProps & {
   /** The intensity; `null` is an absent cell (flat neutral), never a zero. */
   getValue: (d: T) => number | null
   /** Explicit band order. Default: first seen in `data`. */
-  rows?: readonly string[]
-  cols?: readonly string[]
+  rows?: readonly string[] | undefined
+  cols?: readonly string[] | undefined
   /** The ink at full intensity, a `VX.*` ref or a series token. Default `VX.line`. */
-  color?: string
+  color?: string | undefined
   /** The value range the color scale spans. Default `[0, max]` of the data. */
-  domain?: readonly [number, number]
+  domain?: readonly [number, number] | undefined
   /** Tooltip, legend-end and `aria` value format. Default: the number as-is. */
-  formatValue?: (v: number) => string
+  formatValue?: ((v: number) => string) | undefined
   /** Band tick and tooltip header labels. Default: the band key. */
-  formatRow?: (row: string) => string
-  formatCol?: (col: string) => string
+  formatRow?: ((row: string) => string) | undefined
+  formatCol?: ((col: string) => string) | undefined
   /** `false` hides the gradient legend; `label` titles it. */
-  legend?: false | { label?: string }
+  legend?: false | { label?: string | undefined } | undefined
   /** Rows after the value row, per cell (a sample count, a failure reason). Called with the datum. */
-  tooltip?: false | { rows?: (d: T) => readonly ChartTooltipRow[] }
+  tooltip?: (false | { rows?: ((d: T) => readonly ChartTooltipRow[]) | undefined }) | undefined
   /** A fixed height, or one per container class. Default: by row count (160–420px). */
-  height?: number | ResponsiveChartHeight
+  height?: number | ResponsiveChartHeight | undefined
   /** Fill the parent's height instead. Overrides `height`. CSS-owned like every other kind's box
    * (`ChartBox`, no measuring, SSR-stable), so the parent needs a definite CSS height — a grid or
    * flex stretch, `h-full`, an explicit height — which no kind can read off an auto-height parent. */
-  matchHeight?: boolean
-  state?: ChartState
+  matchHeight?: boolean | undefined
+  state?: ChartState | undefined
 }
 
 /** Intensity steps: quantized, so the gradient legend and the cells are the same ramp. */
@@ -244,7 +244,7 @@ export function Heatmap<T>(props: HeatmapProps<T>): ReactElement {
                         ...(point.color && { color: point.color }),
                       },
                     ]
-              return { title: header(c), rows: [...value, ...extra] }
+              return { title: header(c), rows: [...value, ...extra].map(engineRow) }
             },
           }
         : false,

package/src/charts/Lines.tsx

@@ -17,7 +17,7 @@ import { VX } from '../tokens'
 import { CartesianRung } from './CartesianChart'
 import { areaGradientId } from './compile'
 import { chartCurve } from './curves'
-import { lineMark, markersOf, yScaleOf } from './marks'
+import { drawnRows, lineMark, markersOf, yScaleOf } from './marks'
 import { rowX } from './types'
 import type {
   CartesianChartProps,
@@ -120,7 +120,7 @@ export function Lines<T, X extends ChartX = ChartX>(props: LinesProps<T, X>): Re
         if (!s.area) continue
         out.push(
           decorative(
-            areaY(plot.rows(s.key), {
+            areaY(drawnRows(plot, s), {
               id: `${s.key}-area`,
               x: rowX,
               y2: 'y',

package/src/charts/MirroredBars.tsx

@@ -21,7 +21,7 @@ import { useCallback, useMemo } from 'react'
 import type { ReactElement } from 'react'
 import { VX, alpha } from '../tokens'
 import { resolveContainerClass } from '../tokens/size-classes'
-import { defaultFormatX, defaultNumberFormat, visibleSeries } from './compile'
+import { defaultFormatX, defaultNumberFormat, seriesRow, visibleSeries } from './compile'
 import { barMark, emphasis } from './marks'
 import { PanelRung, paneX, paneY, rowsOf } from './panel'
 import type { PaneBuilder, PanelInput, PanelPlan } from './panel'
@@ -35,11 +35,11 @@ export type MirroredBarPane = {
    * entry throws: the pane would vanish, which reads as a measured zero. */
   key: string
   /** The pane's upper bound. `'auto'` (default) is its own visible maximum; a number pins it. */
-  max?: number | 'auto'
+  max?: number | 'auto' | undefined
   /** When `'auto'`: floors the upper bound, so a quiet window does not amplify noise to full height. */
-  autoMaxFloor?: number
+  autoMaxFloor?: number | undefined
   /** Tick count for this pane's own axis. Default 3. */
-  ticks?: number
+  ticks?: number | undefined
   /** Tick and tooltip formatter, in the pane's OWN units. */
   format: (v: number) => string
 }
@@ -71,18 +71,18 @@ export type MirroredBarsProps<T, X extends ChartX = ChartX> = Pick<
   /** Drawn below the baseline. */
   down: MirroredBarPane
   /** The up pane's share of the height. Default 0.35: the pair is usually asymmetric. */
-  upFraction?: number
+  upFraction?: number | undefined
   /** 0..1 of a bar's width that no source sample covers, drawn neutral across both panes. */
-  getAbsentFraction?: (d: T) => number
+  getAbsentFraction?: ((d: T) => number) | undefined
   /** Per-datum bar opacity: a real but qualified measurement (a short bucket) drawn dimmer. */
-  getBarOpacity?: (d: T) => number
+  getBarOpacity?: ((d: T) => number) | undefined
   /**
    * Collapse adjacent data where one band per datum would be sub-pixel. `merge` is the consumer's
    * (max, sum, or a rate from summed parts) and must keep `group[0]`'s x, the slot start.
    */
-  fold?: { minBandPx?: number; merge: (group: T[]) => T }
+  fold?: { minBandPx?: number | undefined; merge: (group: T[]) => T } | undefined
   /** Default `'leading'`: x is a slot's start. */
-  cursorResolution?: CartesianChartProps<T, X>['cursorResolution']
+  cursorResolution?: CartesianChartProps<T, X>['cursorResolution'] | undefined
 }
 
 const DEFAULT_UP_FRACTION = 0.35
@@ -277,12 +277,13 @@ export function MirroredBars<T, X extends ChartX = ChartX>(
             // Each pane's row falls back to ITS OWN formatter: the panes are in different units.
             const fallback =
               s.key === up.key ? up.format : s.key === down.key ? down.format : defaultNumberFormat
-            out.push({
-              label: s.note === undefined ? s.label : `${s.label} · ${s.note}`,
-              value: s.formatValue ? s.formatValue(v, d) : fallback(v),
-              color: s.color,
-              ...(highlighted === s.key && { active: true }),
-            })
+            out.push(
+              seriesRow(
+                s,
+                s.formatValue ? s.formatValue(v, d) : fallback(v),
+                highlighted === s.key,
+              ),
+            )
           }
           return out
         },

package/src/charts/Sparkline.tsx

@@ -29,18 +29,18 @@ export type SparklineProps = BasaltProps & {
   /** Height in px. */
   height: number
   /** Width in px. Default: the container's, measured by the host. */
-  width?: number
+  width?: number | undefined
   /** Default `'line'`. */
-  mark?: 'line' | 'bar'
+  mark?: 'line' | 'bar' | undefined
   /** A `VX.*` ref or a series token. Default `VX.faint`. */
-  color?: string
+  color?: string | undefined
   /** Paints the last point in `emphasisColor` — the one reading a trend beside a KPI is for. */
-  emphasizeLast?: boolean
+  emphasizeLast?: boolean | undefined
   /** Default `VX.accent`. */
-  emphasisColor?: string
+  emphasisColor?: string | undefined
   /** Pending / error / empty, the same contract as every other kind. The placeholder fills the
    * sparkline's own `width` × `height`, so a loading tile does not shift when the trend lands. */
-  state?: ChartState
+  state?: ChartState | undefined
 }
 
 type Point = { i: number; v: number | null }

package/src/charts/StackedArea.tsx

@@ -25,7 +25,7 @@ export type StackedAreaBand<T> = Pick<
   'key' | 'label' | 'color' | 'getValue' | 'formatValue' | 'tooltip' | 'legend' | 'role' | 'note'
 > & {
   /** Default 0.85. */
-  fillOpacity?: number
+  fillOpacity?: number | undefined
 }
 
 export type StackedAreaProps<T, X extends ChartX = ChartX> = Omit<
@@ -35,7 +35,7 @@ export type StackedAreaProps<T, X extends ChartX = ChartX> = Omit<
   /** The bands, bottom to top. */
   series: readonly StackedAreaBand<T>[]
   /** No `scale`: a log axis has no additive zero to stack from. */
-  y?: Omit<NonNullable<CartesianChartProps<T, X>['y']>, 'scale'>
+  y?: Omit<NonNullable<CartesianChartProps<T, X>['y']>, 'scale'> | undefined
 }
 
 export function StackedArea<T, X extends ChartX = ChartX>(