basalt-ui 1.26.0 → 1.28.0

package/src/charts/primitives/chart-frame-layout.ts

@@ -0,0 +1,212 @@
+/**
+ * Pure, DOM-free layout math behind `ChartFrame`'s plot/legend split — extracted so the arithmetic
+ * is testable without a `ResizeObserver` and `ChartFrame.tsx` stays the measuring/rendering shell.
+ */
+
+import { VX } from '../../tokens'
+import type { ChartMargin } from '../../tokens'
+import type { LegendEntry } from './ChartLegend'
+import { measureText } from '../utils/measure-text'
+
+/** Line box of one legend row at `VX.legendFontSize`. */
+const LEGEND_LINE_H = Math.ceil(VX.legendFontSize * 1.35)
+/** `ChartLegend`'s own vertical wrapper padding (`8px 0 2px`). */
+const LEGEND_PAD_Y = 10
+/** Swatch plus the gap to its label — the fixed part of a legend entry's width. */
+const LEGEND_SWATCH_W = 24
+
+/**
+ * The two size tiers a chart resolves to. There are exactly two, and there is no `tablet`: the
+ * tier exists to answer "is there room for full-size chrome around the plot", which is a yes/no
+ * question, and a third rung would need a third calibrated metric set nothing has asked for.
+ */
+export type ChartTier = 'phone' | 'desktop'
+
+/**
+ * The tier a chart's chrome resolves to, from the width of the box it was MEASURED in — never
+ * from a media query.
+ *
+ * A viewport breakpoint answers the wrong question. A chart in a 2-column grid cell on a 1440px
+ * desktop is exactly as narrow as one filling a phone, and `@media` cannot see that; the
+ * `ResizeObserver` `ChartFrame` already runs can. It also keeps this file (and the whole chart
+ * layer) Mantine-free — `theme.breakpoints` is on the coupled side of the boundary.
+ *
+ * An UNMEASURED box (`containerW <= 0` — SSR, or before the observer's first callback) resolves
+ * to `'desktop'`: the first frame must not paint phone chrome that then re-lays-out one frame
+ * later, and `resolvePlotRect` already treats an unmeasured width as the first-frame case.
+ */
+export function resolveChartTier(containerW: number): ChartTier {
+  return containerW > 0 && containerW < VX.phoneChartWidth ? 'phone' : 'desktop'
+}
+
+/**
+ * How much of `VX.margin` a phone-tier chart keeps as its FLOOR. The measured law is unchanged —
+ * a side may still only grow past its floor (`autoMargin`) — this only stops a static token from
+ * spending 44px of a 360px chart on a gutter three characters wide.
+ */
+const PHONE_MARGIN_SCALE = 0.75
+
+/** Phone-tier crosshair dot radius. One step in, so the marker still reads as a punched hole at
+ * the smaller stroke widths a narrow chart draws. */
+const PHONE_DOT_R = Math.max(VX.dotR - 1, 2)
+
+/** Legend entries a phone-tier legend renders before rolling the rest into `+N more`. Two is the
+ * cap because a third entry wraps at every realistic phone width, and a wrapped legend is what
+ * eats the plot (`legendEntryCap`). */
+const PHONE_LEGEND_MAX_ROWS = 2
+
+/** Tooltip `minWidth`, per tier — 140px is 39% of a 360px screen. */
+const TOOLTIP_MIN_WIDTH = { desktop: 140, phone: 110 } as const
+
+/** Every size a chart's chrome resolves per tier. One object so a new tier-sensitive size is added
+ * in one place and read by name, rather than each primitive branching on the tier itself. */
+export type ChartTierMetrics = {
+  /** Which tier these are, so a consumer of the metrics never needs both values threaded. */
+  tier: ChartTier
+  /** Axis tick label font size, px. Threaded into BOTH `autoMargin`'s measurement and the painted
+   * axis — measured labels must be the painted labels (`docs/CHARTS-SPEC.md` §1). */
+  axisFont: number
+  /** Legend label font size, px. */
+  legendFontSize: number
+  /** Crosshair dot radius, px. */
+  dotR: number
+  /** Floating tooltip `minWidth`, px. */
+  tooltipMinWidth: number
+  /** Default entry cap on the legend, or `undefined` for no default cap. An explicit
+   * `legend.maxRows` still wins as the upper bound. */
+  legendMaxRows: number | undefined
+  /** Per-side margin FLOORS (`VX.margin` is a floor, never a ceiling — §1). */
+  margin: ChartMargin
+}
+
+const DESKTOP_METRICS: ChartTierMetrics = {
+  tier: 'desktop',
+  axisFont: VX.axisFont,
+  legendFontSize: VX.legendFontSize,
+  dotR: VX.dotR,
+  tooltipMinWidth: TOOLTIP_MIN_WIDTH.desktop,
+  legendMaxRows: undefined,
+  margin: VX.margin,
+}
+
+const PHONE_METRICS: ChartTierMetrics = {
+  tier: 'phone',
+  // One step DOWN the shared type ladder, never an arbitrary px value: micro → nano for ticks,
+  // sm → xs for the legend (`TEXT` in tokens/index.ts).
+  axisFont: VX.text.nano,
+  legendFontSize: VX.text.xs,
+  dotR: PHONE_DOT_R,
+  tooltipMinWidth: TOOLTIP_MIN_WIDTH.phone,
+  legendMaxRows: PHONE_LEGEND_MAX_ROWS,
+  margin: {
+    top: Math.round(VX.margin.top * PHONE_MARGIN_SCALE),
+    right: Math.round(VX.margin.right * PHONE_MARGIN_SCALE),
+    bottom: Math.round(VX.margin.bottom * PHONE_MARGIN_SCALE),
+    left: Math.round(VX.margin.left * PHONE_MARGIN_SCALE),
+  },
+}
+
+/** The resolved sizes for one tier. Frozen module constants — never a new object per render. */
+export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
+  return tier === 'phone' ? PHONE_METRICS : DESKTOP_METRICS
+}
+
+/**
+ * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
+ * the two floors below are testable without a `ResizeObserver`.
+ *
+ * Two floors, and each is only a floor while it is honest:
+ * - **width** — `minWidth` is a FIRST-FRAME guard, applied only while `containerW` is still 0
+ *   (unmeasured, or SSR, where the observer never fires). Once measured the plot tracks the box
+ *   exactly, floored at 1 so no scale divides by zero: applying a 200px floor forever drew an SVG
+ *   wider than its own container inside any narrower grid cell.
+ * - **height** — the legend band is subtracted first (it always was), but the remainder can no
+ *   longer collapse: eight entries wrapping to five rows at phone width ate a fixed
+ *   `height={240}` toward zero and the body stopped rendering entirely. The plot stops at
+ *   `VX.minPlotHeight` and the frame's own box grows by the difference instead — it is a flex
+ *   column with `height: auto`, so that growth is automatic. Under `fill` the box CANNOT grow, so
+ *   the legend is capped instead ({@link legendEntryCap}). An unmeasured box (`resolvedHeight <=
+ *   0`, i.e. a `fill` frame before its first measurement) stays at 0 and renders nothing, exactly
+ *   as before — the floor must never invent a height for a box nobody has measured.
+ */
+export function resolvePlotRect(input: {
+  containerW: number
+  resolvedHeight: number
+  minWidth: number
+  sideLegendWidth: number
+  topBottomLegendHeight: number
+}): { width: number; height: number } {
+  const { containerW, resolvedHeight, minWidth, sideLegendWidth, topBottomLegendHeight } = input
+  return {
+    width: containerW === 0 ? minWidth : Math.max(containerW - sideLegendWidth, 1),
+    height:
+      resolvedHeight <= 0 ? 0 : Math.max(resolvedHeight - topBottomLegendHeight, VX.minPlotHeight),
+  }
+}
+
+/** Height of a legend band `rows` rows tall, wrapper padding included. */
+const legendBandHeight = (rows: number): number =>
+  LEGEND_PAD_Y + rows * LEGEND_LINE_H + Math.max(rows - 1, 0) * VX.legendGap
+
+/** Width one legend entry occupies — swatch, gap, label, and the note that rides after it. */
+const legendEntryWidth = (item: LegendEntry): number =>
+  LEGEND_SWATCH_W +
+  measureText(
+    item.note === undefined ? item.label : `${item.label} ${item.note}`,
+    VX.legendFontSize,
+  )
+
+/** How many of `items` fit in `rows` wrapped rows of `width` — the same greedy wrap the flex
+ * container performs, measured rather than assumed (`docs/CHARTS-SPEC.md` §1). */
+function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: number): number {
+  let row = 1
+  let x = 0
+  let fitted = 0
+  for (const item of items) {
+    const w = legendEntryWidth(item)
+    const next = x === 0 ? w : x + VX.legendGap + w
+    if (next > width && x > 0) {
+      row += 1
+      if (row > rows) return fitted
+      x = w
+    } else {
+      x = next
+    }
+    fitted += 1
+  }
+  return fitted
+}
+
+/**
+ * The entry cap a `fill` frame's legend must respect so the plot keeps `VX.minPlotHeight`.
+ *
+ * A fixed-height frame grows to fit its legend; a `fill` frame is pinned to its cell, so the only
+ * remaining lever is `ChartLegend`'s `maxRows` rollup (an ENTRY cap — see its JSDoc). The rows the
+ * legend may take follow from the height left over; how many entries that is follows from
+ * MEASURING the labels, not from assuming one entry per row — otherwise a five-entry legend that
+ * fits on one line would roll up to `+2 more` in every 240px cell, moving rendering for charts
+ * that never had the bug. Returns `undefined` when the whole legend already fits.
+ */
+export function legendEntryCap(input: {
+  items: readonly LegendEntry[]
+  containerW: number
+  /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
+  available: number
+  /** An explicit caller cap always wins as the upper bound. */
+  callerMaxRows?: number
+}): number | undefined {
+  const { items, containerW, available, callerMaxRows } = input
+  if (containerW <= 0 || items.length === 0) return callerMaxRows
+  const rows = Math.max(
+    1,
+    Math.floor((available - LEGEND_PAD_Y + VX.legendGap) / (LEGEND_LINE_H + VX.legendGap)),
+  )
+  if (
+    legendBandHeight(rows) <= available &&
+    entriesWithinRows(items, containerW, rows) >= items.length
+  ) {
+    return callerMaxRows
+  }
+  const fitted = Math.max(1, entriesWithinRows(items, containerW, rows))
+  return callerMaxRows === undefined ? fitted : Math.min(fitted, callerMaxRows)
+}

package/src/charts/primitives/chart-tier.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react'
+import type { ReactNode } from 'react'
+import { chartTierMetrics, resolveChartTier } from './chart-frame-layout'
+import type { ChartTier, ChartTierMetrics } from './chart-frame-layout'
+
+/**
+ * Ambient chart tier. `ChartFrame` publishes the tier it resolved from its own MEASURED width;
+ * the axes, the legend, the crosshair dots and the tooltip read it back without every kind having
+ * to thread a prop it does not otherwise care about.
+ *
+ * Default `'desktop'`, so a primitive rendered outside a `ChartFrame` (a hand-composed plot, a
+ * `TooltipRow` in a consumer's own tooltip) keeps exactly today's sizes.
+ */
+const ChartTierContext = createContext<ChartTier>('desktop')
+
+export type ChartTierProviderProps = {
+  tier: ChartTier
+  children: ReactNode
+}
+
+/** Publishes a resolved tier to the subtree. Mounted once, by `ChartFrame`. */
+export function ChartTierProvider({ tier, children }: ChartTierProviderProps): ReactNode {
+  return <ChartTierContext.Provider value={tier}>{children}</ChartTierContext.Provider>
+}
+
+/** The tier of the nearest measured `ChartFrame`, or `'desktop'` outside one. */
+export function useChartTier(): ChartTier {
+  return useContext(ChartTierContext)
+}
+
+/** The resolved sizes for the ambient tier — the form every primitive actually wants. */
+export function useChartTierMetrics(): ChartTierMetrics {
+  return chartTierMetrics(useContext(ChartTierContext))
+}
+
+export { chartTierMetrics, resolveChartTier }
+export type { ChartTier, ChartTierMetrics }

package/src/charts/series.ts

@@ -7,6 +7,13 @@
  * share one definition.
  */
 
+import {
+  curveLinear,
+  curveMonotoneX,
+  curveStep,
+  curveStepAfter,
+  curveStepBefore,
+} from '@visx/curve'
 import type { LegendEntry } from './primitives/ChartLegend'
 
 /**
@@ -24,6 +31,43 @@ export type SeriesMark = 'line' | 'bar' | 'area'
 /** Only meaningful for `mark: 'line'`. */
 export type SeriesDash = 'solid' | 'dashed'
 
+/**
+ * The interpolation between two plotted points. Named rather than a raw d3 `CurveFactory` so the
+ * set is closed, serializable, and identical across every kind — a chart cannot pick a curve the
+ * legend swatch and the sibling chart next to it do not also understand.
+ *
+ * - `monotone` (default, today's behaviour everywhere) — smoothed, overshoot-free.
+ * - `linear` — straight segments. The honest choice when the points are samples, not a signal.
+ * - `step` / `stepAfter` / `stepBefore` — the value HOLDS between samples and changes at one x.
+ *   Reach for these when the quantity is piecewise-constant (a price tier, a config value, a
+ *   discrete state): a smoothed curve through them draws intermediate values that never existed.
+ *   `stepAfter` holds the value forward from its own x, `stepBefore` holds it back from the next,
+ *   `step` changes at the midpoint.
+ */
+export type SeriesCurve = 'monotone' | 'linear' | 'step' | 'stepAfter' | 'stepBefore'
+
+/** d3's curve-factory shape, taken from a curve we already import rather than from
+ * `@visx/vendor/d3-shape` — that package is a transitive of `@visx/curve`, not one of the nine
+ * exact-pinned peers, so naming it in an import would add an undeclared dependency. */
+type CurveFactory = typeof curveMonotoneX
+
+const CURVES: Record<SeriesCurve, CurveFactory> = {
+  monotone: curveMonotoneX,
+  linear: curveLinear,
+  step: curveStep,
+  stepAfter: curveStepAfter,
+  stepBefore: curveStepBefore,
+}
+
+/**
+ * The d3 curve factory for a {@link SeriesCurve}. `undefined` resolves to `curveMonotoneX` — the
+ * value every kind hard-coded before this seam existed, so an omitted `curve` moves nothing.
+ * Exported for a hand-composed plot that draws its own `LinePath` from the same `series` array.
+ */
+export function curveFor(curve?: SeriesCurve): CurveFactory {
+  return curve === undefined ? curveMonotoneX : CURVES[curve]
+}
+
 /** Drives legend grouping/dividers. */
 export type SeriesRole = 'series' | 'overlay' | 'reference'
 
@@ -56,6 +100,12 @@ export type SeriesStyle = {
   mark: SeriesMark
   /** Default 'solid'. */
   dash?: SeriesDash
+  /**
+   * Interpolation between points for the line/area shapes this series draws. Default `'monotone'`
+   * — today's behaviour, unchanged, everywhere. See {@link SeriesCurve} for when a step curve is
+   * the honest one. Silently no-ops on `mark: 'bar'`, which has nothing to interpolate.
+   */
+  curve?: SeriesCurve
   /** Default VX.lineWidth (one width, everywhere). */
   strokeWidth?: number
   /** bar/area: the swatch honors this so it cannot lie. */
@@ -95,7 +145,12 @@ export type SeriesStyle = {
 
 /** Full descriptor = visual identity + data accessors. Generic over the point type. */
 export type ChartSeries<T> = SeriesStyle & {
-  /** null = line gap + skipped tooltip row. */
+  /**
+   * null = an ABSENCE, never a zero: a real gap in the line/area (`defined`, not a straight
+   * interpolation across the hole) plus a skipped tooltip row and no crosshair dot. In a STACKED
+   * kind the absence is contagious — a band with no value leaves no cumulative total, so the whole
+   * stack gaps at that x (`StackedArea`'s JSDoc has the accounting).
+   */
   getValue: (d: T) => number | null
   /** Per-series override of the shared tooltip/value formatter. Receives the hovered datum
    * alongside the value so a row can read fields beyond the plotted number (e.g. `97.5 kg (92.5 ×
@@ -195,3 +250,24 @@ export function deriveTooltipRows<T>(
   }
   return rows
 }
+
+/**
+ * Coerces a `ChartSeries.getValue` result into what a plotted point stores as its y: `null`,
+ * `undefined` and `NaN` all collapse to `null`, which downstream `definedOn` reads as a
+ * documented gap rather than a value to plot. Shared by `MultiLine`'s `seriesPoints` and
+ * `ZonedLine`'s `linePoints` — both used to reimplement this coercion independently.
+ */
+export function toPlotPoint(v: number | null | undefined): number | null {
+  return v === null || v === undefined || Number.isNaN(v) ? null : v
+}
+
+/**
+ * A `defined` predicate for `LinePath`/`AreaClosed`/`Threshold`, bound to one y-scale. A null
+ * `__y` is a documented gap (`ChartSeries.getValue`), and a non-positive value on a log scale maps
+ * to `NaN` via the scale itself — without excluding both, d3's generators either draw an
+ * interpolated straight line across the hole or blank the entire path from that point on (SVG's
+ * `NaN` path-command handling). Shared by `MultiLine` and `ZonedLine`.
+ */
+export function definedOn(scale: (y: number) => number): (d: { __y: number | null }) => boolean {
+  return (d) => d.__y !== null && Number.isFinite(scale(d.__y))
+}

package/src/charts/sparklines/BarSparkline.tsx

@@ -1,8 +1,9 @@
 import { scaleLinear } from '@visx/scale'
 import { useMemo } from 'react'
+import type { BasaltProps } from '../../common/props'
 import { VX } from '../../tokens'
 
-type BarSparklineProps = {
+export type BarSparklineProps = BasaltProps & {
   data: number[]
   width: number
   height: number
@@ -47,6 +48,8 @@ export function BarSparkline({
   emphasizeLast = false,
   emphasisColor,
   ariaLabel,
+  className,
+  style,
 }: BarSparklineProps) {
   const fillColor = color ?? VX.faint
   const lastColor = emphasisColor ?? VX.accent
@@ -57,14 +60,19 @@ export function BarSparkline({
     return scaleLinear<number>({ domain: [0, max], range: [0, height] })
   }, [data, height])
 
-  if (!data.length) return <svg width={width} height={height} {...a11yProps} />
+  const rootProps = {
+    ...(className !== undefined && { className }),
+    ...(style !== undefined && { style }),
+  }
+
+  if (!data.length) return <svg width={width} height={height} {...rootProps} {...a11yProps} />
 
   const step = width / data.length
   const barWidth = Math.max(step - barGap, 1)
   const lastIndex = data.length - 1
 
   return (
-    <svg width={width} height={height} {...a11yProps}>
+    <svg width={width} height={height} {...rootProps} {...a11yProps}>
       {data.map((v, i) => {
         const bh = Math.max(yScale(Math.max(v, 0)), 0)
         const isLast = emphasizeLast && i === lastIndex

package/src/charts/sparklines/LineSparkline.tsx

@@ -3,9 +3,10 @@ import { Group } from '@visx/group'
 import { scaleLinear } from '@visx/scale'
 import { LinePath } from '@visx/shape'
 import { useMemo } from 'react'
+import type { BasaltProps } from '../../common/props'
 import { VX } from '../../tokens'
 
-type LineSparklineProps = {
+export type LineSparklineProps = BasaltProps & {
   data: number[]
   width: number
   height: number
@@ -18,7 +19,15 @@ type LineSparklineProps = {
  * Quiet single-hue trend line (docs/DESIGN-SPEC.md §5: "single 1.6px faint line, no fill, no
  * axes, no dots"). Sparklines default to `VX.faint`, not the bolder `VX.line` used by full charts.
  */
-export function LineSparkline({ data, width, height, color, ariaLabel }: LineSparklineProps) {
+export function LineSparkline({
+  data,
+  width,
+  height,
+  color,
+  ariaLabel,
+  className,
+  style,
+}: LineSparklineProps) {
   const strokeColor = color ?? VX.faint
   const a11yProps = ariaLabel !== undefined ? { role: 'img' as const, 'aria-label': ariaLabel } : {}
 
@@ -36,12 +45,17 @@ export function LineSparkline({ data, width, height, color, ariaLabel }: LineSpa
     return scaleLinear<number>({ domain: [min - pad, max + pad], range: [height, 0] })
   }, [data, height])
 
-  if (data.length < 2) return <svg width={width} height={height} {...a11yProps} />
+  const rootProps = {
+    ...(className !== undefined && { className }),
+    ...(style !== undefined && { style }),
+  }
+
+  if (data.length < 2) return <svg width={width} height={height} {...rootProps} {...a11yProps} />
 
   const indexed = data.map((v, i) => ({ v, i }))
 
   return (
-    <svg width={width} height={height} {...a11yProps}>
+    <svg width={width} height={height} {...rootProps} {...a11yProps}>
       <Group>
         <LinePath<{ v: number; i: number }>
           data={indexed}

package/src/charts/sparklines/index.ts

@@ -1,2 +1,2 @@
-export { LineSparkline } from './LineSparkline'
-export { BarSparkline } from './BarSparkline'
+export { LineSparkline, type LineSparklineProps } from './LineSparkline'
+export { BarSparkline, type BarSparklineProps } from './BarSparkline'

package/src/charts/utils/format.ts

@@ -1,9 +1,22 @@
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
 const SHORT_DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
 
-/** Axis-friendly short date: DD.MM */
+/**
+ * What EVERY formatter here prints for input it cannot represent — `NaN`, `±Infinity`, an
+ * `Invalid Date`. An em dash (U+2014), the same glyph the tooltip already uses for a missing value.
+ *
+ * The rule is one rule on purpose. `Intl.NumberFormat` renders `NaN` as the literal string `"NaN"`
+ * and `Infinity` as `"∞"`, so a y axis whose domain collapsed (an empty series, a 0/0 rate, a log
+ * scale reaching zero) painted its own arithmetic accident as a tick label and a tooltip read
+ * `NaN%`. A chart may say it does not know; it may not print a number that is not one.
+ */
+export const NON_FINITE = '\u2014'
+
+/** Axis-friendly short date: DD.MM. A non-finite or invalid date prints {@link NON_FINITE}. */
 export function fmtAxisDate(value: unknown): string {
+  if (typeof value === 'number' && !Number.isFinite(value)) return NON_FINITE
   if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return NON_FINITE
     const dd = String(value.getDate()).padStart(2, '0')
     const mm = String(value.getMonth() + 1).padStart(2, '0')
     return `${dd}.${mm}`
@@ -14,9 +27,12 @@ export function fmtAxisDate(value: unknown): string {
   return s
 }
 
-/** Tooltip-friendly long date: "Mon Apr 21 2026" */
+/** Tooltip-friendly long date: "Mon Apr 21 2026". A non-finite or invalid date prints
+ * {@link NON_FINITE}. */
 export function fmtTooltipDate(date: unknown): string {
+  if (typeof date === 'number' && !Number.isFinite(date)) return NON_FINITE
   if (date instanceof Date) {
+    if (Number.isNaN(date.getTime())) return NON_FINITE
     return `${SHORT_DAYS[date.getDay()]} ${MONTHS[date.getMonth()]} ${date.getDate()} ${date.getFullYear()}`
   }
   const s = String(date ?? '')
@@ -25,3 +41,148 @@ export function fmtTooltipDate(date: unknown): string {
   const d = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]))
   return `${SHORT_DAYS[d.getDay()]} ${MONTHS[d.getMonth()]} ${d.getDate()} ${d.getFullYear()}`
 }
+
+/**
+ * The number-format law.
+ *
+ * `format.ts` shipped two date formatters and nothing else, so every axis and every tooltip in
+ * every demo and consumer hand-rolled its own `` `$${v}k` `` — a template literal that is not
+ * locale-aware, not compact-aware, and different in each of the places it was written. These four
+ * are `Intl.NumberFormat` with the arguments already decided, so a chart states WHAT a number is
+ * rather than how to punctuate it.
+ *
+ * `locale` defaults to `undefined`, which is `Intl`'s own "use the runtime's locale" — the correct
+ * default for an app whose reader is the person looking at it. Pass it explicitly (`'en-US'`) when
+ * the output must be stable regardless of where it runs, which is what the tests here do.
+ *
+ * Every one of them returns {@link NON_FINITE} for input that is not a finite number — see its
+ * JSDoc for why that is a law of this module rather than a per-call-site guard.
+ */
+
+/** Options every formatter here accepts. */
+type LocaleOption = {
+  /** BCP-47 tag. Default `undefined` — the runtime's own locale. */
+  locale?: string
+}
+
+/**
+ * `Intl.NumberFormat` construction is the expensive half of formatting and a chart formats one
+ * label per tick per frame, so instances are memoized on their own arguments. The key is the
+ * serialized options because that is exactly what identifies an instance.
+ */
+const formatterCache = new Map<string, Intl.NumberFormat>()
+
+/** The compact `K` suffix, matched only where it follows the digits it qualifies — so a currency
+ * prefix that happens to contain one (`HK$`) survives the lowercasing. */
+const COMPACT_K = /(\d\s?)K/
+
+function numberFormat(
+  locale: string | undefined,
+  options: Intl.NumberFormatOptions,
+): Intl.NumberFormat {
+  const key = `${locale ?? ''}|${JSON.stringify(options)}`
+  const cached = formatterCache.get(key)
+  if (cached !== undefined) return cached
+  const created = new Intl.NumberFormat(locale, options)
+  formatterCache.set(key, created)
+  return created
+}
+
+export type FmtCompactOptions = LocaleOption & {
+  /** Significant-ish fraction digits on the compacted number. Default 1 (`1.2k`, `3.4M`). */
+  digits?: number
+}
+
+/**
+ * Compact notation: `1.2k`, `3.4M`, `-820`. The axis formatter for any count whose range spans
+ * more than three digits — a y axis reading `1,200,000` spends a third of the plot width on a
+ * gutter. A non-finite value prints {@link NON_FINITE}.
+ *
+ * Note `Intl`'s compact notation is LOCALE text, not a suffix table: `en` gives `1.2K`, and this
+ * lowercases the `K` to match the package's own numeral style while leaving every other locale's
+ * word (`1,2 Mio.`) untouched. Only a `K` attached to the DIGITS is touched — `HK$1.2K` must keep
+ * its currency prefix, which a bare `replace('K', 'k')` ate.
+ */
+export function fmtCompact(value: number, options: FmtCompactOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 1, locale } = options
+  return numberFormat(locale, {
+    notation: 'compact',
+    compactDisplay: 'short',
+    maximumFractionDigits: digits,
+  })
+    .format(value)
+    .replace(COMPACT_K, '$1k')
+}
+
+export type FmtPercentOptions = LocaleOption & {
+  /** Fraction digits. Default 0 (`42%`). */
+  digits?: number
+  /**
+   * What the incoming number MEANS. `'ratio'` (default) is `0.42 → 42%`; `'percent'` is
+   * `42 → 42%`. Required as an explicit option rather than guessed from magnitude: a ratio of 1.2
+   * and a percentage of 1.2 are both perfectly ordinary numbers, and a heuristic would silently
+   * render one of them 100× wrong.
+   */
+  input?: 'ratio' | 'percent'
+}
+
+/** Percentages, from either a ratio or an already-scaled percentage. A non-finite value prints
+ * {@link NON_FINITE} — a rate is the commonest source of a 0/0. */
+export function fmtPercent(value: number, options: FmtPercentOptions = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { digits = 0, input = 'ratio', locale } = options
+  return numberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(input === 'percent' ? value / 100 : value)
+}
+
+export type FmtCurrencyOptions = LocaleOption & {
+  /** ISO 4217 code — required. There is no default currency; a wrong symbol is worse than a
+   * verbose call site. */
+  currency: string
+  /** Compact notation for the amount (`$1.2k`). Default false. */
+  compact?: boolean
+  /** Fraction digits. Default 0 compacted, else the currency's own default (`undefined`). */
+  digits?: number
+}
+
+/** Money. `fmtCurrency(1234, { currency: 'USD' })` → `$1,234`. A non-finite amount prints
+ * {@link NON_FINITE}. */
+export function fmtCurrency(value: number, options: FmtCurrencyOptions): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  const { currency, compact = false, digits, locale } = options
+  const fractionDigits = digits ?? (compact ? 1 : 0)
+  return numberFormat(locale, {
+    style: 'currency',
+    currency,
+    ...(compact && { notation: 'compact', compactDisplay: 'short' }),
+    minimumFractionDigits: compact ? 0 : fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  })
+    .format(value)
+    .replace(COMPACT_K, '$1k')
+}
+
+/** Grouped integer: `12,480`. Rounds — an integer formatter that printed `12,480.4` would be
+ * lying about its own name. A non-finite value prints {@link NON_FINITE}. */
+export function fmtInt(value: number, options: LocaleOption = {}): string {
+  if (!Number.isFinite(value)) return NON_FINITE
+  return numberFormat(options.locale, { maximumFractionDigits: 0 }).format(value)
+}
+
+/**
+ * Every shipped formatter under one name, so a chart can be handed the whole set
+ * (`format={formatters.compact}`) and a consumer has one import to reach for instead of four.
+ * Same members as the named exports — this is a convenience, never a second implementation.
+ */
+export const formatters = {
+  compact: fmtCompact,
+  percent: fmtPercent,
+  currency: fmtCurrency,
+  int: fmtInt,
+  axisDate: fmtAxisDate,
+  tooltipDate: fmtTooltipDate,
+} as const