basalt-ui 1.14.0 → 1.16.0

package/src/charts/primitives/XZoneRects.tsx

@@ -0,0 +1,132 @@
+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
+  /**
+   * `'center'` (default, unchanged behaviour) resolves a present bound to `xScale(key)` — the
+   * point's own center, so a band reads "from this sample to that sample" rather than
+   * edge-to-edge. `'edge'` resolves a present `from` to `xScale(from) - step/2` and a present `to`
+   * to `xScale(to) + step/2` (`step` read from `xScale.step()`), so the band covers both terminal
+   * slots in full — a two-key band widens by exactly one step, and `from === to` renders one step
+   * wide instead of being skipped as degenerate. An omitted `from`/`to` still resolves to the plot
+   * edge (`xScale.range()[0]`/`[1]`) in both modes, unshifted — omission means "the plot's own
+   * edge", not "the first/last sample's edge". A resolved `'edge'` bound is clamped into the plot
+   * range so a band anchored at the first or last sample cannot paint outside the plot area.
+   */
+  align?: 'center' | 'edge'
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Resolves one zone bound (`from` or `to`) to a pixel x. `edgeSign` is `-1` for `from` (subtract
+ * half a step) and `+1` for `to` (add half a step) — only consulted in `'edge'` mode.
+ */
+function resolveBound({
+  key,
+  omittedEdge,
+  xScale,
+  align,
+  edgeSign,
+  rangeMin,
+  rangeMax,
+}: {
+  key: string | undefined
+  omittedEdge: number
+  xScale: PointScale
+  align: 'center' | 'edge'
+  edgeSign: -1 | 1
+  rangeMin: number
+  rangeMax: number
+}): number | undefined {
+  if (key === undefined) return omittedEdge
+  const center = xScale(key)
+  if (center === undefined) return undefined
+  if (align === 'center') return center
+  return clamp(center + edgeSign * (xScale.step() / 2), rangeMin, rangeMax)
+}
+
+/**
+ * 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.
+ *
+ * Bound resolution depends on `XZoneSpec.align` (see its JSDoc for the full `'center'`/`'edge'`
+ * contract) — default `'center'` resolves a present key to the point's own center; `'edge'`
+ * widens by half a step at each present bound so the band covers the terminal slots in full.
+ *
+ * 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, in either mode. Clamping an unknown key 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. In `'center'` mode `from === to` is degenerate (skipped,
+ * today's behaviour); in `'edge'` mode it is NOT — the half-step widening on each side always
+ * produces a positive-width, one-step-wide 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 rangeMin = Math.min(rangeStart, rangeEnd)
+        const rangeMax = Math.max(rangeStart, rangeEnd)
+        const align = z.align ?? 'center'
+        const xFrom = resolveBound({
+          key: z.from,
+          omittedEdge: rangeStart,
+          xScale,
+          align,
+          edgeSign: -1,
+          rangeMin,
+          rangeMax,
+        })
+        const xTo = resolveBound({
+          key: z.to,
+          omittedEdge: rangeEnd,
+          xScale,
+          align,
+          edgeSign: 1,
+          rangeMin,
+          rangeMax,
+        })
+        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,112 @@
+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%')
+  })
+
+  test('formatValue receives the hovered datum alongside the value', () => {
+    type Set = { v: number; reps: number }
+    const rows = deriveTooltipRows(
+      [
+        {
+          key: 'set',
+          label: 'Set',
+          color: '#000',
+          mark: 'bar' as const,
+          getValue: (d: Set) => d.v,
+          formatValue: (v: number, d: Set) => `${v} kg (${d.reps} reps)`,
+        },
+      ],
+      { v: 97.5, reps: 3 },
+      fmt,
+    )
+    expect(rows[0]?.value).toBe('97.5 kg (3 reps)')
+  })
+
+  test('the fallback formatter (single-arg) still works once formatValue is 2-arg typed', () => {
+    const rows = deriveTooltipRows([{ ...base, key: 'a', label: 'A' }], { v: 5 }, fmt)
+    expect(rows[0]?.value).toBe('5')
+  })
+})
+
+describe('strokeOpacity — a mark property, not a tooltip property', () => {
+  test('reaches the derived legend entry', () => {
+    const [entry] = deriveLegend([{ ...baseSeries, strokeOpacity: 0.4 }])
+    expect(entry?.strokeOpacity).toBe(0.4)
+  })
+
+  test('is absent from the legend entry when unset', () => {
+    const [entry] = deriveLegend([baseSeries])
+    expect(entry).not.toHaveProperty('strokeOpacity')
+  })
+
+  test('never reaches TooltipRowData — the row is a 12px value chip, not a dimmed mark', () => {
+    const rows = deriveTooltipRows(
+      [
+        {
+          ...baseSeries,
+          strokeOpacity: 0.4,
+          getValue: () => 10,
+        },
+      ],
+      {},
+      (v) => String(v),
+    )
+    expect(rows[0]).not.toHaveProperty('strokeOpacity')
+  })
+})

package/src/charts/series.ts

@@ -43,6 +43,8 @@ export type ChartLegendConfig = {
   groups?: boolean
   /** Wrap cap → "+N more" rollup at high cardinality. */
   maxRows?: number
+  /** Clicking an entry hides that series. Default: on whenever there is more than one entry. */
+  toggle?: boolean
 }
 
 /** Visual identity of a series — everything the legend + tooltip swatch need. No accessors, no `T`. */
@@ -58,20 +60,42 @@ export type SeriesStyle = {
   strokeWidth?: number
   /** bar/area: the swatch honors this so it cannot lie. */
   fillOpacity?: number
+  /**
+   * A MARK property — dims the plotted stroke, e.g. a faint moving-average companion line. The
+   * legend swatch honors it too (parity with `fillOpacity`, which it already honors — a swatch
+   * that lies is the thing the derived-legend rule exists to prevent). The TOOLTIP ROW swatch and
+   * the CROSSHAIR DOT deliberately do NOT honor it: those are 12px value-readout chips where a
+   * sub-1 opacity reads as a rendering bug, not as data.
+   */
+  strokeOpacity?: number
+  /** Which y-axis this series is measured against. Default 'left'. `'right'` is what makes a
+   * chart dual-axis — `CartesianChart` reads it for the crosshair dots and the tooltip. */
+  axis?: 'left' | 'right'
   /** Default 'series'. */
   role?: SeriesRole
   /** Default true; false = companion folded under `parent`. */
   legend?: boolean
+  /**
+   * Default true; false = drawn and legended, but NEVER listed as a tooltip row. The replacement
+   * for the per-kind `hideBarTooltipRows` escape the old layer had: it belongs to the series, not to the kind, so
+   * one series can opt out without the kind growing a prop for it.
+   */
+  tooltip?: boolean
   /** e.g. an MA line names its parent so hover-dimming keeps the pair. */
   parent?: string
+  /** Short qualifier rendered after the label in muted text — e.g. a flat-at-zero series that is
+   * invisible in the plot. */
+  note?: string
 }
 
 /** Full descriptor = visual identity + data accessors. Generic over the point type. */
 export type ChartSeries<T> = SeriesStyle & {
   /** null = line gap + skipped tooltip row. */
   getValue: (d: T) => number | null
-  /** Per-series override of the shared tooltip/value formatter. */
-  formatValue?: (v: number) => string
+  /** 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 ×
+   * 3)`). */
+  formatValue?: (v: number, d: T) => string
   /** PR star / status dot. Return null for no marker at that point. */
   getMarker?: (d: T) => { color?: string; r?: number } | null
 }
@@ -98,7 +122,9 @@ function legendEntryFor(s: SeriesStyle): LegendEntry {
     dashed: s.dash === 'dashed',
     ...(s.strokeWidth !== undefined && { strokeWidth: s.strokeWidth }),
     ...(s.fillOpacity !== undefined && { fillOpacity: s.fillOpacity }),
+    ...(s.strokeOpacity !== undefined && { strokeOpacity: s.strokeOpacity }),
     ...(s.role !== undefined && { role: s.role }),
+    ...(s.note !== undefined && { note: s.note }),
   }
 }
 
@@ -136,7 +162,8 @@ export function deriveLegend(series: readonly SeriesStyle[]): LegendEntry[] {
 
 /**
  * Derive tooltip rows from a series descriptor array + the hovered datum. Skips rows where
- * `getValue(datum) === null`; honors per-series `formatValue` over the shared `fallbackFormat`.
+ * `getValue(datum) === null` or `tooltip === false`; honors per-series `formatValue` over the
+ * shared `fallbackFormat`.
  * Kinds pass `series.toReversed()` for stacked charts so the tooltip stack matches the visual stack.
  */
 export function deriveTooltipRows<T>(
@@ -146,14 +173,15 @@ export function deriveTooltipRows<T>(
 ): TooltipRowData[] {
   const rows: TooltipRowData[] = []
   for (const s of series) {
+    if (s.tooltip === false) continue
     const value = s.getValue(datum)
     if (value === null) continue
-    const format = s.formatValue ?? fallbackFormat
+    const format: (v: number, d: T) => string = s.formatValue ?? fallbackFormat
     rows.push({
       key: s.key,
       label: s.label,
       color: s.color,
-      value: format(value),
+      value: format(value, datum),
       shape: shapeFor(s.mark),
       dashed: s.dash === 'dashed',
       ...(s.strokeWidth !== undefined && { strokeWidth: s.strokeWidth }),

package/src/charts/utils/measure-text.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test'
+import { maxTextWidth, measureText, resetTextMetrics } from './measure-text'
+
+describe('measureText', () => {
+  test('width grows with the string and with the font size', () => {
+    resetTextMetrics()
+    expect(measureText('1,250,000', 11)).toBeGreaterThan(measureText('0', 11))
+    expect(measureText('0', 22)).toBeGreaterThan(measureText('0', 11))
+  })
+
+  test('an empty string measures zero', () => {
+    expect(measureText('', 11)).toBe(0)
+  })
+
+  test('repeated measurement is stable — the memo cannot return a different width', () => {
+    resetTextMetrics()
+    const first = measureText('2026-08-18', 11)
+    expect(measureText('2026-08-18', 11)).toBe(first)
+  })
+
+  test('the same text at a different size is NOT a cache hit', () => {
+    resetTextMetrics()
+    expect(measureText('88', 11)).not.toBe(measureText('88', 30))
+  })
+})
+
+describe('maxTextWidth', () => {
+  test('returns 0 for no labels — an axis with no ticks reserves nothing extra', () => {
+    expect(maxTextWidth([], 11)).toBe(0)
+  })
+
+  test('returns the widest label, not the last', () => {
+    const labels = ['1', '1,250,000', '25']
+    expect(maxTextWidth(labels, 11)).toBe(measureText('1,250,000', 11))
+  })
+})

package/src/charts/utils/measure-text.ts

@@ -0,0 +1,109 @@
+/**
+ * Text measurement for chart layout — the input to {@link autoMargin}.
+ *
+ * A static margin token cannot know how wide a tick label is, which is why charts used to have to be
+ * hand-nudged whenever a label grew (`docs/CHARTS-SPEC.md` §1). This measures the strings that
+ * will actually be painted, via an OFFSCREEN canvas 2D context: no element is attached, so there
+ * is no layout thrash and no reflow — unlike an SVG `getBBox()` probe.
+ *
+ * Mantine-free and dependency-free by construction (`charts/**` boundary).
+ */
+
+/** Fallback advance width per character, as a fraction of the font size, when no DOM is
+ * available (SSR, `renderToStaticMarkup`). Mono faces sit near 0.6em; being deterministic matters
+ * more than being exact, since the measured value is only ever a floor-raiser. */
+const FALLBACK_CHAR_RATIO = 0.6
+
+/** Last-resort family when the `--basalt-font-mono` custom property cannot be read. */
+const FALLBACK_MONO = 'ui-monospace, SFMono-Regular, Menlo, monospace'
+
+/**
+ * Cap on the memo table. Tick labels are low-cardinality per chart, but a long-lived SPA with a
+ * live counter or currency axis mints a new string every update, and an unbounded module-level Map
+ * would then grow for the life of the tab. On overflow the whole table is dropped rather than
+ * evicted one by one: the working set is tiny and re-measuring it costs microseconds, so an LRU's
+ * bookkeeping would cost more than the misses it avoids.
+ */
+const CACHE_LIMIT = 2000
+
+const cache = new Map<string, number>()
+
+let ctx: CanvasRenderingContext2D | null | undefined
+let monoFamily: string | undefined
+
+function canvasContext(): CanvasRenderingContext2D | null {
+  if (ctx !== undefined) return ctx
+  if (typeof document === 'undefined') {
+    ctx = null
+    return ctx
+  }
+  ctx = document.createElement('canvas').getContext('2d')
+  // Webfonts swap in after first paint; measurements taken against the fallback face would then
+  // be stale (usually too narrow). Drop the cache once, when the real faces are ready.
+  // `?.` on every hop: a non-browser DOM harness can expose `document` with no `fonts`, or a
+  // `fonts` with no `ready` — neither is a reason to fail a measurement.
+  document.fonts?.ready?.then?.(() => cache.clear()).catch(() => {})
+  return ctx
+}
+
+/**
+ * The resolved value of `--basalt-font-mono` — canvas needs a concrete family list, it cannot
+ * resolve a CSS custom property. Read once from the document element.
+ */
+export function monoFontFamily(): string {
+  if (monoFamily !== undefined) return monoFamily
+  if (typeof document === 'undefined' || typeof getComputedStyle !== 'function') {
+    monoFamily = FALLBACK_MONO
+    return monoFamily
+  }
+  const value = getComputedStyle(document.documentElement)
+    .getPropertyValue('--basalt-font-mono')
+    .trim()
+  monoFamily = value.length > 0 ? value : FALLBACK_MONO
+  return monoFamily
+}
+
+/**
+ * Width in px of `text` at `fontPx` in the chart tick font. Memoized per `font|text` — a chart
+ * re-measures the same ~10 tick labels on every resize, and the cache turns that into a Map hit.
+ */
+export function measureText(text: string, fontPx: number, fontFamily?: string): number {
+  const family = fontFamily ?? monoFontFamily()
+  const font = `${fontPx}px ${family}`
+  const key = `${font}|${text}`
+  const hit = cache.get(key)
+  if (hit !== undefined) return hit
+
+  const c = canvasContext()
+  let width: number
+  if (c === null) {
+    width = text.length * fontPx * FALLBACK_CHAR_RATIO
+  } else {
+    c.font = font
+    width = c.measureText(text).width
+  }
+  if (cache.size >= CACHE_LIMIT) cache.clear()
+  cache.set(key, width)
+  return width
+}
+
+/** Widest of `texts` at `fontPx`. Returns 0 for an empty list. */
+export function maxTextWidth(
+  texts: readonly string[],
+  fontPx: number,
+  fontFamily?: string,
+): number {
+  let max = 0
+  for (const text of texts) {
+    const width = measureText(text, fontPx, fontFamily)
+    if (width > max) max = width
+  }
+  return max
+}
+
+/** Test seam — drops the memo table (and the resolved family) so a test can change fonts. */
+export function resetTextMetrics(): void {
+  cache.clear()
+  ctx = undefined
+  monoFamily = undefined
+}

package/src/content/fence-block.tsx

@@ -139,9 +139,8 @@ function lookupFenceRenderer(
 
 // ── Throw containment ────────────────────────────────────────────────────────────────────────────
 
-/** A `useRef(false)` handle, mutated in place — same per-instance "warn once" idiom as
- * `useHoverSync`'s `warnedRef` (`charts/hooks/useHoverSync.ts`) rather than a module-level
- * singleton: a singleton would make the FIRST fence anywhere in the process to throw silence the
+/** A `useRef(false)` handle, mutated in place — a per-instance "warn once" gate rather than a
+ * module-level singleton: a singleton would make the FIRST fence anywhere in the process to throw silence the
  * warning for every OTHER, unrelated broken fence for the rest of the run (and, worse, for every
  * later test in this suite — this file has module-singleton order-dependence history). Scoping the
  * gate to one `FenceBlock`'s `useRef` means each rendered fence position gets its own warning, reset

package/src/surfaces.ts

@@ -211,7 +211,8 @@ export const SURFACES = {
     rule: 'charts',
     skill: ['basalt-charts'],
     guardKinds: ['raw-hex', 'raw-color-fn', 'raw-visx-axis', 'unframed-chart'],
-    description: 'visx chart primitives, sparklines, hooks, and token re-exports (Mantine-free)',
+    description:
+      'CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)',
     globs: {
       shipped: ['**/charts/**'],
       repo: ['packages/basalt-ui/src/charts/**'],

package/src/theme/spacing.test.ts

@@ -369,6 +369,7 @@ const SPACE_STEP_SWEEP: ReadonlyArray<
   ['chartLegendGap', 22, null],
   ['chartMarginTop', 12, null],
   ['chartMarginRight', 16, null],
+  ['chartMarginRightAxis', 40, null],
   ['chartMarginBottom', 30, null],
   ['chartMarginLeft', 44, null],
   ['chartDotR', 5, null],
@@ -406,6 +407,7 @@ describe('SPACE_STEP CSS-module spacing-sweep one-offs match the shipped identit
       'chartLegendGap',
       'chartMarginTop',
       'chartMarginRight',
+      'chartMarginRightAxis',
       'chartMarginBottom',
       'chartMarginLeft',
       'chartDotR',

package/src/tokens/chart-margin.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { chartMargin, VX } from './index'
+
+describe('chartMargin', () => {
+  test('a bare call deep-equals VX.margin', () => {
+    expect(chartMargin()).toEqual(VX.margin)
+  })
+
+  test('{ rightAxis: true } widens right to the right-axis minimum', () => {
+    expect(chartMargin({ rightAxis: true })).toEqual({
+      ...VX.margin,
+      right: 40,
+    })
+  })
+
+  test('{ rightAxis: false } (or omitted) leaves right at VX.margin.right', () => {
+    expect(chartMargin({ rightAxis: false })).toEqual(VX.margin)
+  })
+
+  test('an explicit right overrides the rightAxis-widened value', () => {
+    expect(chartMargin({ rightAxis: true, right: 12 })).toEqual({
+      ...VX.margin,
+      right: 12,
+    })
+  })
+
+  test('explicit sides override their VX.margin defaults independently', () => {
+    expect(chartMargin({ top: 1, left: 2 })).toEqual({
+      top: 1,
+      right: VX.margin.right,
+      bottom: VX.margin.bottom,
+      left: 2,
+    })
+  })
+
+  test('returns a new object each call', () => {
+    expect(chartMargin()).not.toBe(chartMargin())
+  })
+})

package/src/tokens/density.test.ts

@@ -242,6 +242,7 @@ describe('buildDensityCss', () => {
       'space-chart-legend-gap', // VX.legendGap / VX.margin / VX.dotR — visx SVG props
       'space-chart-margin-top',
       'space-chart-margin-right',
+      'space-chart-margin-right-axis',
       'space-chart-margin-bottom',
       'space-chart-margin-left',
       'space-chart-dot-r',

package/src/tokens/index.ts

@@ -241,6 +241,42 @@ export const VX = {
   minPxPerTick: 55,
 } as const
 
+/** Resolved chart plot-area margins — the return shape of {@link chartMargin}. */
+export type ChartMargin = { top: number; right: number; bottom: number; left: number }
+
+/**
+ * Chart plot-area margins — `VX.margin` widened for an `AxisRightNumeric`'s tick labels, and/or
+ * overridden per side. A token can't express "only when a right axis is rendered", so this is a
+ * function, not a second static token — also the seam that could one day track `density`
+ * (`VX.margin` itself is frozen at the level-0 snapshot; see `deriveSpacing`'s JSDoc).
+ *
+ * Law, applied in this order: start from `VX.margin`; when `rightAxis` is true, widen `right` to
+ * `Math.max(VX.margin.right, <right-axis minimum>)` (`SPACE_STEP.chartMarginRightAxis`); then any
+ * explicitly passed side wins last (including overriding `rightAxis`'s widened `right`).
+ * `chartMargin()` with no args deep-equals `VX.margin`.
+ *
+ * Returns a NEW object every call — memoize at the call site (`useMemo`), the same way `Bars`
+ * already memoizes its own margin.
+ */
+export function chartMargin(opts?: {
+  /** Reserve room for an `AxisRightNumeric`'s tick labels. */
+  rightAxis?: boolean
+  top?: number
+  right?: number
+  bottom?: number
+  left?: number
+}): ChartMargin {
+  const widenedRight = opts?.rightAxis
+    ? Math.max(VX.margin.right, SPACE_STEP.chartMarginRightAxis)
+    : VX.margin.right
+  return {
+    top: opts?.top ?? VX.margin.top,
+    right: opts?.right ?? widenedRight,
+    bottom: opts?.bottom ?? VX.margin.bottom,
+    left: opts?.left ?? VX.margin.left,
+  }
+}
+
 type Side = 'light' | 'dark'
 
 /** A CSS declaration line for a single `--vx-*` custom property. */

package/src/tokens/palette.ts

@@ -620,6 +620,9 @@ const SPACE_STEP_BASE = {
   chartMarginTop: 12,
   /** Chart plot-area margin, right (`VX.margin.right`). */
   chartMarginRight: 16,
+  /** Minimum right margin when an `AxisRightNumeric` is rendered — labels like "100"/"60m" need
+   * more room than the no-right-axis default (`chartMargin({ rightAxis: true })`, `tokens/index.ts`). */
+  chartMarginRightAxis: 40,
   /** Chart plot-area margin, bottom (`VX.margin.bottom`). */
   chartMarginBottom: 30,
   /** Chart plot-area margin, left (`VX.margin.left`). */

package/dist/charts/hooks/useChartTooltip.d.ts

@@ -1,13 +0,0 @@
-export type TooltipState<T> = {
-    data: T;
-    x: number;
-    y: number;
-} | null;
-export declare function useChartTooltip<T>(): {
-    tip: TooltipState<T>;
-    show: (data: T, event: React.MouseEvent) => void;
-    hide: () => void;
-    tooltipRef: import("react").RefObject<HTMLDivElement | null>;
-    lastDateRef: import("react").RefObject<string | null>;
-};
-//# sourceMappingURL=useChartTooltip.d.ts.map

package/dist/charts/hooks/useChartTooltip.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useChartTooltip.d.ts","sourceRoot":"","sources":["../../../src/charts/hooks/useChartTooltip.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAA;AAEtE,wBAAgB,eAAe,CAAC,CAAC;;iBAKC,CAAC,SAAS,KAAK,CAAC,UAAU;;;;EAqB3D"}

package/dist/charts/hooks/useChartTooltip.js

@@ -1,26 +0,0 @@
-import { useCallback, useRef, useState } from "react";
-function useChartTooltip() {
-  const [tip, setTip] = useState(null);
-  const tooltipRef = useRef(null);
-  const lastDateRef = useRef(null);
-  const show = useCallback((data, event) => {
-    const el = tooltipRef.current;
-    const width = el?.offsetWidth ?? 0;
-    const height = el?.offsetHeight ?? 0;
-    const margin = 8;
-    const vw = window.innerWidth;
-    const vh = window.innerHeight;
-    const overflowsRight = event.clientX + 12 + width + margin > vw;
-    const x = overflowsRight ? Math.max(margin, event.clientX - 12 - width) : event.clientX + 12;
-    const y = Math.min(Math.max(margin, event.clientY - 12), vh - height - margin);
-    setTip({ data, x, y });
-  }, []);
-  const hide = useCallback(() => {
-    setTip(null);
-    lastDateRef.current = null;
-  }, []);
-  return { tip, show, hide, tooltipRef, lastDateRef };
-}
-export {
-  useChartTooltip
-};