basalt-ui 1.8.0 → 1.10.0

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,67 @@
+/**
+ * `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).
+ *
+ * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
+ * `theme/use-basalt-spacing.test.tsx`'s doc) — `renderToStaticMarkup` is used deliberately here
+ * instead: `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. Converting
+ * to the DOM harness would only be worth it if a future assertion here needed a real measured size
+ * (a live `ResizeObserver` reading) rather than this SSR fallback rect.
+ */
+import { 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}
     />
   )
 }