basalt-ui 1.8.0 → 1.9.0

package/src/charts/index.ts

@@ -46,6 +46,12 @@ export {
 // ── Primitives ───────────────────────────────────────────────────────────
 export { ResponsiveChart, type ResponsiveChartProps } from './primitives/ResponsiveChart'
 export { ChartFrame, type ChartFrameProps, type ChartFrameLegend } from './primitives/ChartFrame'
+export {
+  ChartCenter,
+  type ChartCenterProps,
+  ChartPending,
+  type ChartPendingProps,
+} from './primitives/ChartPending'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { ChartCard } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'

package/src/charts/kinds/Bars.tsx

@@ -139,6 +139,8 @@ export type BarsProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -164,6 +166,7 @@ function BarsInner<T>(props: BarsProps<T>) {
     height,
     legend,
     ariaLabel,
+    isPending,
   } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
@@ -207,6 +210,7 @@ function BarsInner<T>(props: BarsProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/Donut.tsx

@@ -53,6 +53,8 @@ export type DonutProps<K extends string = SeriesKey> = {
   padAngle?: number
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -64,7 +66,7 @@ export type DonutProps<K extends string = SeriesKey> = {
  * (donut ↔ bar, via the generalized key) is a distinct, deliberately deferred feature.
  */
 function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
-  const { data, height, colorForKey, seriesLabel = (k) => k, ariaLabel } = props
+  const { data, height, colorForKey, seriesLabel = (k) => k, ariaLabel, isPending } = props
 
   const series: SeriesStyle[] = data.map((d) => ({
     key: d.key,
@@ -78,6 +80,7 @@ function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
       series={series}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
     >
       {(plot) => <DonutPlot {...props} plot={plot} />}
     </ChartFrame>
@@ -136,13 +139,16 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
                 return (
                   <g
                     key={key}
-                    onMouseEnter={(event) => {
+                    onPointerEnter={(event) => {
                       show(arc.data, event)
                     }}
-                    onMouseMove={(event) => {
+                    onPointerMove={(event) => {
                       show(arc.data, event)
                     }}
-                    onMouseLeave={() => {
+                    onPointerLeave={() => {
+                      hide()
+                    }}
+                    onPointerCancel={() => {
                       hide()
                     }}
                     style={{ cursor: 'pointer' }}

package/src/charts/kinds/DualPanel.tsx

@@ -57,6 +57,8 @@ export type DualPanelProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 const PANE_GAP = 12
@@ -74,7 +76,8 @@ const PANE_GAP = 12
  * when a series has nulls; lines/bars skip null points (visual gaps).
  */
 function DualPanelInner<T>(props: DualPanelProps<T>) {
-  const { series, chartId, height, barLabel, barColorPositive, legend, ariaLabel } = props
+  const { series, chartId, height, barLabel, barColorPositive, legend, ariaLabel, isPending } =
+    props
 
   // Default the top-pane line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) —
   // applied once here so the plotted line, the derived legend swatch, and the derived tooltip row
@@ -101,6 +104,7 @@ function DualPanelInner<T>(props: DualPanelProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <DualPanelPlot {...props} series={styledSeries} plot={plot} />}

package/src/charts/kinds/Heatmap.tsx

@@ -8,6 +8,7 @@ import {
   TooltipRow,
   useTooltipStyles,
 } from '../primitives/ChartTooltip'
+import { ChartPending } from '../primitives/ChartPending'
 import { useChartTooltip } from '../hooks/useChartTooltip'
 import { VX, alpha } from '../../tokens'
 
@@ -47,6 +48,14 @@ export type HeatmapProps<T> = {
   renderTooltip?: (cell: HeatmapCell) => ReactNode
   /** Optional gradient legend strip below the grid (faint → solid color). */
   legend?: { min: string; max: string }
+  /**
+   * The query behind this chart hasn't resolved yet. Renders `ChartPending` (see its JSDoc for the
+   * three-state rationale) over the full `width` × `height` box in place of the grid, suppressing
+   * the legend strip and every cell/label/tooltip along with it. Unlike the other six kinds,
+   * `Heatmap` doesn't compose `ChartFrame` (it takes `width`/`height` directly rather than
+   * measuring), so this is handled locally instead of forwarded.
+   */
+  isPending?: boolean
 }
 
 /** Build a first-seen-ordered list of unique keys from data via an accessor. */
@@ -106,6 +115,7 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
     colLabel = (c) => c,
     renderTooltip,
     legend,
+    isPending,
   } = props
 
   const tooltipStyles = useTooltipStyles()
@@ -126,6 +136,12 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
     return { lookup: map, max: m }
   }, [data, getRow, getCol, getValue])
 
+  // Every hook above must still run on a pending render (Rules of Hooks) — the early return comes
+  // after them. No `ChartFrame` to forward to here (Heatmap measures via required `width`/`height`
+  // props, not `useChartSize`), so the placeholder is rendered directly in its place, same footprint,
+  // legend strip and all other content omitted along with it.
+  if (isPending) return <ChartPending width={width} height={height} />
+
   const legendH = legend ? LEGEND_H + LEGEND_LABEL_H : 0
   const gridW = Math.max(0, width - PAD_LEFT)
   const gridH = Math.max(0, height - PAD_TOP - PAD_BOTTOM - legendH)
@@ -152,8 +168,9 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
                   rx={cellRadius}
                   fill={fill}
                   style={{ cursor: has ? 'pointer' : 'default' }}
-                  onMouseMove={(e) => has && show({ row, col, value }, e)}
-                  onMouseLeave={hide}
+                  onPointerMove={(e) => has && show({ row, col, value }, e)}
+                  onPointerLeave={hide}
+                  onPointerCancel={hide}
                 />
               )
             }),

package/src/charts/kinds/MultiLine.tsx

@@ -67,6 +67,8 @@ export type MultiLineProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 const STAR_R = 6
@@ -96,7 +98,7 @@ function starPath(cx: number, cy: number, r: number): string {
  * has nulls; each series line skips null points (creating visual gaps).
  */
 function MultiLineInner<T>(props: MultiLineProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
   // Default line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied once
@@ -112,6 +114,7 @@ function MultiLineInner<T>(props: MultiLineProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/StackedArea.tsx

@@ -40,6 +40,8 @@ export type StackedAreaProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -48,7 +50,7 @@ export type StackedAreaProps<T> = {
  * The tooltip renders rows in reversed (top-to-bottom) stack order so it matches the visual stack.
  */
 function StackedAreaInner<T>(props: StackedAreaProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
   const [highlightedKey, setHighlightedKey] = useState<string | null>(null)
 
   return (
@@ -57,6 +59,7 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend, {
         highlighted: highlightedKey,
         onHighlight: setHighlightedKey,

package/src/charts/kinds/ZonedLine.tsx

@@ -101,6 +101,8 @@ export type ZonedLineProps<T> = {
   legend?: ChartLegendConfig | false
   /** Accessible text alternative, forwarded to `ChartFrame` as `aria-label` (+ `role="img"`). */
   ariaLabel?: string
+  /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
+  isPending?: boolean
 }
 
 /**
@@ -116,7 +118,7 @@ export type ZonedLineProps<T> = {
  * visual gaps).
  */
 function ZonedLineInner<T>(props: ZonedLineProps<T>) {
-  const { series, chartId, height, legend, ariaLabel } = props
+  const { series, chartId, height, legend, ariaLabel, isPending } = props
 
   // Default the line overlay to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied
   // once here so the plotted line, the derived legend swatch, and the derived tooltip row agree.
@@ -131,6 +133,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
       chartId={chartId}
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
+      {...(isPending !== undefined && { isPending })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <ZonedLinePlot {...props} series={styledSeries} plot={plot} />}

package/src/charts/primitives/Axes.tsx

@@ -73,17 +73,23 @@ export function AxisBottomDate({
   scale,
   top,
   tickValues,
+  tickFormat = fmtAxisDate,
 }: {
   scale: AxisScale
   top: number
   tickValues: string[]
+  /**
+   * Defaults to `fmtAxisDate` (DD.MM). Override for a sub-day window, where DD.MM collapses every
+   * tick to the same label.
+   */
+  tickFormat?: TickFormatter<string>
 }) {
   return (
     <AxisBottom
       top={top}
       scale={scale}
       tickValues={tickValues}
-      tickFormat={fmtAxisDate}
+      tickFormat={tickFormat}
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,

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

@@ -0,0 +1,64 @@
+/**
+ * `ChartFrame`'s `isPending` invariant — the one behavior here that regresses silently. A pending
+ * chart that quietly fell back to rendering its legend + body would put a densified "not measured"
+ * shape back on screen exactly where `ChartPending` is supposed to reserve a static, contentless
+ * placeholder (see `ChartPending`'s JSDoc for the three-state "nothing to draw" rationale).
+ *
+ * No jsdom is configured in this repo (see `theme/use-basalt-spacing.test.tsx`'s doc) —
+ * `renderToStaticMarkup` is enough here: `ChartFrame`/`ChartPending` live in `src/charts/**`, which
+ * is Mantine-free, so no `MantineProvider` wrapper is needed either. `useChartSize` never measures
+ * under SSR (no `ResizeObserver`), so the plot rect falls back to `minWidth` × the resolved fixed
+ * height — non-zero, which is what lets `children`/`ChartPending` render at all in this harness.
+ */
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { ChartFrame } from './ChartFrame'
+import type { SeriesStyle } from '../series'
+
+const series: SeriesStyle[] = [{ key: 'a', label: 'Series A', color: '#000', mark: 'line' }]
+
+const CHART_BODY_MARKER = 'CHART_BODY_MARKER'
+
+function renderFrame(isPending: boolean): string {
+  return renderToStaticMarkup(
+    <ChartFrame series={series} legend={{}} isPending={isPending}>
+      {() => <svg>{CHART_BODY_MARKER}</svg>}
+    </ChartFrame>,
+  )
+}
+
+describe('a pending ChartFrame renders neither the legend nor the chart body', () => {
+  const markup = renderFrame(true)
+
+  test('the legend is absent — no series label anywhere in the markup', () => {
+    expect(markup).not.toContain('Series A')
+  })
+
+  test('the chart body (children) never runs', () => {
+    expect(markup).not.toContain(CHART_BODY_MARKER)
+  })
+
+  test('the outer container is marked aria-busy', () => {
+    expect(markup).toContain('aria-busy="true"')
+  })
+
+  test('the placeholder label renders in its place', () => {
+    expect(markup).toContain('Loading…')
+  })
+})
+
+describe('a non-pending ChartFrame is unaffected — the legend and body both render', () => {
+  const markup = renderFrame(false)
+
+  test('the legend renders the series label', () => {
+    expect(markup).toContain('Series A')
+  })
+
+  test('the chart body renders', () => {
+    expect(markup).toContain(CHART_BODY_MARKER)
+  })
+
+  test('no aria-busy attribute is present', () => {
+    expect(markup).not.toContain('aria-busy')
+  })
+})

package/src/charts/primitives/ChartFrame.tsx

@@ -3,6 +3,7 @@ import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
 import { ChartLegend } from './ChartLegend'
+import { ChartPending } from './ChartPending'
 
 const DEFAULT_HEIGHT = 240
 const DEFAULT_MIN_WIDTH = 200
@@ -36,6 +37,13 @@ export type ChartFrameProps = {
   chartId?: string
   /** `false` only for the sparkline exemption — every other chart gets a legend by default. */
   legend?: ChartFrameLegend | false
+  /**
+   * The query behind this chart hasn't resolved yet. Renders `ChartPending` (see its JSDoc for the
+   * three-state "nothing to draw" rationale) over the full plot rect in place of `children`,
+   * suppresses the legend entirely (a legend naming a series with nothing yet to point at is its
+   * own small lie), and marks the outer container `aria-busy="true"`.
+   */
+  isPending?: boolean
   /**
    * Accessible text alternative for the chart, applied as `aria-label` (+ `role="img"`) on the
    * outer container so screen readers announce something other than an unlabeled graphic. Every
@@ -106,6 +114,7 @@ export function ChartFrame({
   chartId,
   legend = {},
   ariaLabel,
+  isPending = false,
   children,
 }: ChartFrameProps): ReactNode {
   const { ref: containerRef, width: containerW, height: containerH } = useChartSize()
@@ -113,6 +122,7 @@ export function ChartFrame({
 
   const placement = legend === false ? 'bottom' : (legend.placement ?? 'bottom')
   const vertical = placement === 'left' || placement === 'right'
+  const legendVisible = legend !== false && !isPending
 
   const resolvedHeight = fill
     ? containerH
@@ -120,8 +130,8 @@ export function ChartFrame({
       ? Math.round(containerW / aspectRatio)
       : (height ?? DEFAULT_HEIGHT)
 
-  const sideLegendWidth = legend !== false && vertical ? legendW : 0
-  const topBottomLegendHeight = legend !== false && !vertical ? legendH : 0
+  const sideLegendWidth = legendVisible && vertical ? legendW : 0
+  const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
 
   const plot = {
     width: Math.max(containerW - sideLegendWidth, minWidth),
@@ -129,7 +139,7 @@ export function ChartFrame({
   }
 
   const legendNode =
-    legend === false ? null : (
+    legend === false || isPending ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>
         <ChartLegend
           items={deriveLegend(series)}
@@ -148,9 +158,12 @@ export function ChartFrame({
       ref={containerRef}
       style={outerStyle(fill, vertical)}
       {...(ariaLabel !== undefined && { role: 'img', 'aria-label': ariaLabel })}
+      {...(isPending && { 'aria-busy': 'true' })}
     >
       {legendNode !== null && (placement === 'top' || placement === 'left') && legendNode}
-      {plot.width > 0 && plot.height > 0 ? children(plot) : null}
+      {plot.width > 0 &&
+        plot.height > 0 &&
+        (isPending ? <ChartPending width={plot.width} height={plot.height} /> : children(plot))}
       {legendNode !== null && (placement === 'bottom' || placement === 'right') && legendNode}
     </div>
   )

package/src/charts/primitives/ChartPending.tsx

@@ -0,0 +1,59 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { VX } from '../../tokens'
+
+export type ChartCenterProps = {
+  width: number
+  height: number
+  children: ReactNode
+}
+
+const centerStyle = (width: number, height: number): CSSProperties => ({
+  width,
+  height,
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+})
+
+/**
+ * Minimal layout primitive: centers `children` inside a `width` × `height` box. Exists because
+ * `src/charts/**` cannot import Mantine's `Flex`/`Group`/`Center` (the Mantine-free boundary), so
+ * there was previously nothing to reach for when a chart file needed to center something. Not a
+ * general layout system — width, height, children, nothing else.
+ */
+export function ChartCenter({ width, height, children }: ChartCenterProps): ReactNode {
+  return <div style={centerStyle(width, height)}>{children}</div>
+}
+
+export type ChartPendingProps = {
+  width: number
+  height: number
+  /** Default `'Loading…'`. */
+  label?: string
+}
+
+const labelStyle: CSSProperties = {
+  color: VX.faint,
+  fontSize: VX.text.sm,
+}
+
+/**
+ * The placeholder for a chart whose data hasn't arrived yet — the third "nothing to draw" state
+ * alongside measured-and-empty and measured-and-absent (a real gap in coverage). Collapsing an
+ * in-flight query into either of those (the `data ?? []` idiom) densifies it into a fully-hatched
+ * "not measured" window: a positive claim that the series WAS watched and carried nothing, when in
+ * fact it was never asked. `ChartPending` makes "not asked yet" its own rendered state instead of
+ * borrowing one of the other two.
+ *
+ * Reserves exactly the plot's footprint and draws NOTHING that could be mistaken for a
+ * measurement — no axes, no gridlines, no hatching, no data marks — just a faint, static, centered
+ * label. No animation: the package's motion doctrine bans looping/pulsing idle motion, so a static
+ * reserved box is the correct answer here, not a compromise.
+ */
+export function ChartPending({ width, height, label = 'Loading…' }: ChartPendingProps): ReactNode {
+  return (
+    <ChartCenter width={width} height={height}>
+      <span style={labelStyle}>{label}</span>
+    </ChartCenter>
+  )
+}

package/src/charts/primitives/ChartTooltip.tsx

@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode, RefObject } from 'react'
+import { createPortal } from 'react-dom'
 import { VX } from '../../tokens'
 import { fmtTooltipDate } from '../utils/format'
 
@@ -24,7 +25,10 @@ export function useTooltipStyles(): CSSProperties {
   return TOOLTIP_STYLES
 }
 
-/** Outer tooltip shell. Renders nothing when tip is null. */
+/**
+ * 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,
@@ -37,10 +41,18 @@ export function ChartTooltip({
   children: ReactNode
 }) {
   if (!tip) return null
-  return (
+  // 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>
+    </div>,
+    document.body,
   )
 }
 

package/src/charts/primitives/HoverOverlay.tsx

@@ -1,6 +1,7 @@
-import type { MouseEventHandler } from 'react'
+import type { PointerEventHandler } from 'react'
 
-/** Transparent <rect> that captures mouse events for tooltip + crosshair sync. */
+/** Transparent <rect> that captures pointer events (mouse + touch + pen) for tooltip + crosshair
+ * sync. */
 export function HoverOverlay({
   width,
   height,
@@ -9,16 +10,21 @@ export function HoverOverlay({
 }: {
   width: number
   height: number
-  onMove: MouseEventHandler<SVGRectElement>
-  onLeave: MouseEventHandler<SVGRectElement>
+  onMove: PointerEventHandler<SVGRectElement>
+  onLeave: PointerEventHandler<SVGRectElement>
 }) {
   return (
     <rect
       width={width}
       height={height}
       fill="transparent"
-      onMouseMove={onMove}
-      onMouseLeave={onLeave}
+      // `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.
+      style={{ touchAction: 'pan-y' }}
+      onPointerMove={onMove}
+      onPointerLeave={onLeave}
+      onPointerCancel={onLeave}
     />
   )
 }