basalt-ui 1.13.0 → 1.15.0

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,12 +60,24 @@ export type SeriesStyle = {
   strokeWidth?: number
   /** bar/area: the swatch honors this so it cannot lie. */
   fillOpacity?: 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. */
@@ -99,6 +113,7 @@ function legendEntryFor(s: SeriesStyle): LegendEntry {
     ...(s.strokeWidth !== undefined && { strokeWidth: s.strokeWidth }),
     ...(s.fillOpacity !== undefined && { fillOpacity: s.fillOpacity }),
     ...(s.role !== undefined && { role: s.role }),
+    ...(s.note !== undefined && { note: s.note }),
   }
 }
 
@@ -136,7 +151,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,6 +162,7 @@ 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

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/shell/app-sidebar.module.css

@@ -419,4 +419,15 @@
   .root[data-collapsed] .childList {
     display: none;
   }
+
+  /* `navExtra` has no sensible icon-rail representation (arbitrary consumer content, not a nav
+   * row) — hide it in the rail, same treatment as `.childList`. It stays mounted (never a JS
+   * conditional on `collapsed`): `collapsed` is one value shared by the desktop rail AND the
+   * mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` only ever un-collapses
+   * the mobile side), and the rail-vs-drawer split lives ENTIRELY in this media query, never in JS —
+   * a JS gate on `collapsed` would also drop `navExtra` from the mobile drawer, which opens at full
+   * width regardless of the persisted rail state. */
+  .root[data-collapsed] .navExtra {
+    display: none;
+  }
 }

package/src/shell/app-sidebar.module.css.d.ts

@@ -29,6 +29,7 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
+  readonly navExtra: string
   readonly ghostIcon: string
 }
 export default classes

package/src/shell/app-sidebar.test.tsx

@@ -0,0 +1,98 @@
+/**
+ * `navExtra` — the seam that lets a consumer put arbitrary content (a tree, a filter panel,
+ * a project list) inside the sidebar's nav scroll region instead of rendering a second column
+ * beside the shell. Four invariants:
+ *
+ *  1. It renders INSIDE the nav `ScrollArea`'s content (Mantine's own `.mantine-ScrollArea-content`
+ *     class, stable across runs — CSS-module class hashes are not available under `bun test`, see
+ *     `stat-card.test.tsx`/`use-basalt-spacing.test.tsx` for the same constraint elsewhere), as the
+ *     LAST child, so a long tree scrolls with the nav instead of fighting it for height.
+ *  2. It STAYS MOUNTED when `collapsed` — `collapsed` is one value shared by the desktop rail AND
+ *     the mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` never touches
+ *     the desktop side), and the rail-vs-drawer split lives entirely in a `min-width: sm` CSS media
+ *     query, never in JS. A JS gate on `collapsed` would silently drop `navExtra` from the mobile
+ *     drawer too, which opens at full width regardless of the persisted rail state. jsdom does not
+ *     evaluate the media query, so this asserts presence in the DOM, not computed visibility — the
+ *     CSS half (`.root[data-collapsed] .navExtra { display: none }`) is exercised by the guard rules
+ *     it shares with `.childList`/`.sectionBand`, not by this test.
+ *  3. `sections={[]}` plus only `navExtra` renders cleanly: the nav Stack holds exactly the
+ *     extra content, no orphan section wrapper.
+ *  4. Omitting the prop reproduces today's DOM exactly — the nav Stack's child count matches
+ *     `sections.length`, with no stray wrapper appended for the (absent) slot. This is the
+ *     regression guard for every existing consumer.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { AppSidebar } from './app-sidebar'
+import type { AppSidebarProps } from './app-sidebar'
+
+const BRAND = { name: 'Argo' }
+const ONE_SECTION: AppSidebarProps['sections'] = [
+  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
+]
+
+function renderSidebar(props: Partial<AppSidebarProps> & { navExtra?: ReactNode }) {
+  return render(
+    <MantineProvider>
+      <AppSidebar
+        brand={BRAND}
+        sections={ONE_SECTION}
+        collapsed={false}
+        onToggleCollapse={() => {}}
+        onClose={() => {}}
+        {...props}
+      />
+    </MantineProvider>,
+  )
+}
+
+/** The nav `ScrollArea`'s content Stack — the direct parent of `sections` and `navExtra`. */
+function navStack(container: HTMLElement): Element {
+  const stack = container.querySelector('.mantine-ScrollArea-content > .mantine-Stack-root')
+  if (!stack) throw new Error('expected the nav ScrollArea content Stack to render')
+  return stack
+}
+
+describe('navExtra', () => {
+  test('renders inside the nav scroll region, as the last child, when expanded', () => {
+    const { container } = renderSidebar({
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const extra = screen.getByTestId('nav-extra')
+    const stack = navStack(container)
+    expect(stack.contains(extra)).toBe(true)
+    expect(stack.lastElementChild?.contains(extra)).toBe(true)
+  })
+
+  test('stays mounted in the DOM when collapsed — hiding it is CSS-only, not a JS gate', () => {
+    const { container } = renderSidebar({
+      collapsed: true,
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const extra = screen.getByTestId('nav-extra')
+    const stack = navStack(container)
+    // Presence, not visibility — jsdom never evaluates the `min-width: sm` media query that hides
+    // this in the rail. A regression here (reintroducing `!collapsed &&` in app-sidebar.tsx) would
+    // fail this assertion instead of only breaking silently in a real mobile-drawer browser.
+    expect(stack.contains(extra)).toBe(true)
+  })
+
+  test('sections={[]} plus only navExtra renders cleanly — no orphan section wrapper', () => {
+    const { container } = renderSidebar({
+      sections: [],
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const stack = navStack(container)
+    expect(screen.getByTestId('nav-extra')).toBeTruthy()
+    expect(stack.children.length).toBe(1)
+  })
+
+  test("omitting the prop reproduces today's DOM — no stray wrapper for the unused slot", () => {
+    const { container } = renderSidebar({})
+    expect(screen.queryByTestId('nav-extra')).toBeNull()
+    const stack = navStack(container)
+    expect(stack.children.length).toBe(ONE_SECTION.length)
+  })
+})

package/src/shell/app-sidebar.tsx

@@ -92,6 +92,24 @@ export type AppSidebarProps = {
    * fixed, non-scrolling row. Pair with basalt-ui/commands' openSpotlight.
    */
   search?: SidebarSearchConfig
+  /**
+   * Arbitrary content appended after `sections` inside the nav `ScrollArea` — a tree, a filter
+   * panel, a project list, anything a set of `SidebarItem`s can't express. Renders as the last
+   * child of the scrolling nav column, so a long list scrolls with the rest of the nav instead of
+   * fighting it for height. Pass `sections={[]}` to use this slot exclusively; the section-spacing
+   * rule only fires between adjacent children, so an empty `sections` produces no orphan divider or
+   * dead padding above it.
+   *
+   * Hidden on the collapsed desktop rail; still present in the mobile drawer, which opens at full
+   * width. The rail is ~56px of icon buttons with no sensible representation for arbitrary
+   * consumer content, so the CSS media query that drives the rail hides this slot the same way it
+   * hides `.childList` — never a JS check on `collapsed`, since that one value is shared by the
+   * rail AND the drawer (only the media query tells them apart). `SidebarSearch` gets to adapt
+   * itself to the rail (it takes `collapsed` and renders its own icon-only form) because the shell
+   * owns that control; it cannot adapt content it knows nothing about, so this slot hides instead
+   * of squashing it.
+   */
+  navExtra?: ReactNode
 }
 
 /** Inline collapse/expand chevrons — keeps the shell icon-dependency-free. */
@@ -457,6 +475,7 @@ export function AppSidebar({
   footerExtra,
   account,
   search,
+  navExtra,
 }: AppSidebarProps) {
   // Density-tracking Menu dropdown width (`SPACE_STEP.sidebarSettingsMenuWidth`) — read the ACTIVE
   // resolved level, not the frozen level-0 constant (see that constant's own doc in
@@ -622,6 +641,9 @@ export function AppSidebar({
               </div>
             )
           })}
+          {navExtra !== undefined && navExtra !== null && (
+            <div className={classes.navExtra}>{navExtra}</div>
+          )}
         </Stack>
       </ScrollArea>
 

package/src/shell/index.test.tsx

@@ -0,0 +1,35 @@
+/**
+ * `BasaltShell`'s `sidebarNavExtra` forwarding path — `AppSidebar` (exercised directly in
+ * `app-sidebar.test.tsx`) is not the only place this prop can break. `BasaltShell` destructures
+ * `sidebarNavExtra` and hands it to `AppSidebar` as `navExtra`; a typo'd destructure key, a dropped
+ * prop, or a `sidebarFooterExtra`/`sidebarNavExtra` mix-up in that hand-off would ship silently
+ * without a test that renders `BasaltShell` itself.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { BasaltShell } from './index'
+import type { SidebarSection } from './index'
+
+const BRAND = { name: 'Argo' }
+const ONE_SECTION: SidebarSection[] = [
+  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
+]
+
+describe('BasaltShell sidebarNavExtra', () => {
+  test("reaches AppSidebar's nav scroll region through the BasaltShell -> AppSidebar hand-off", () => {
+    const { container } = render(
+      <MantineProvider>
+        <BasaltShell
+          brand={BRAND}
+          sections={ONE_SECTION}
+          sidebarNavExtra={<div data-testid="nav-extra">Extra</div>}
+        />
+      </MantineProvider>,
+    )
+    const extra = screen.getByTestId('nav-extra')
+    const stack = container.querySelector('.mantine-ScrollArea-content > .mantine-Stack-root')
+    expect(stack).not.toBeNull()
+    expect(stack?.contains(extra)).toBe(true)
+  })
+})

package/src/shell/index.tsx

@@ -115,6 +115,15 @@ export type BasaltShellProps = {
   globalActions?: ReactNode
   /** Extra content appended to the sidebar footer, beside the settings menu (mobile close, etc.). */
   sidebarFooterExtra?: ReactNode
+  /**
+   * Arbitrary content appended after `sections` inside the sidebar's nav scroll region (a tree, a
+   * filter panel, a project list, …). Hidden on the collapsed desktop rail; still present in the
+   * mobile drawer, which opens at full width — see `AppSidebarProps.navExtra`'s JSDoc for why.
+   * `AppSidebar` renders once and serves both the desktop rail and the mobile drawer (collapse
+   * styling is gated behind a `min-width: sm` media query, not a second render), so this slot
+   * reaches both.
+   */
+  sidebarNavExtra?: ReactNode
   /** Entries appended to the sidebar settings menu. */
   settingsMenuItems?: SettingsMenuItem[]
   /**
@@ -262,6 +271,7 @@ export function BasaltShell({
   renderNavLink,
   globalActions,
   sidebarFooterExtra,
+  sidebarNavExtra,
   settingsMenuItems,
   storageKey = 'basalt-sidebar-collapsed',
   collapsed: collapsedProp,
@@ -332,6 +342,7 @@ export function BasaltShell({
             onToggleCollapse={toggleCollapse}
             onClose={closeMobile}
             footerExtra={sidebarFooterExtra}
+            navExtra={sidebarNavExtra}
             {...(renderNavLink !== undefined && { renderNavLink })}
             {...(settingsMenuItems !== undefined && { settingsMenuItems })}
             {...(account !== undefined && { account })}

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
-};