basalt-ui 1.27.0 → 1.28.0

package/src/charts/kinds/ZonedLine.tsx

@@ -1,14 +1,16 @@
-import { curveMonotoneX } from '@visx/curve'
 import { AreaClosed, LinePath } from '@visx/shape'
 import { Threshold } from '@visx/threshold'
 import { memo, useMemo } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { AreaGradient, areaFillUrl } from '../primitives/AreaGradient'
 import type { CartesianTooltipConfig, AxisConfig, PlotContext } from '../primitives/CartesianChart'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { XZoneSpec } from '../primitives/XZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
-import { LINE_OVERLAY_STROKE_WIDTH } from '../series'
+import type { ChartState } from '../primitives/ChartPending'
+import { curveFor, definedOn, LINE_OVERLAY_STROKE_WIDTH, toPlotPoint } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
 import { VX } from '../../tokens'
 
@@ -30,7 +32,7 @@ export type ZonedLineRefLine = {
   dashed?: boolean
 }
 
-export type ZonedLineProps<T> = {
+export type ZonedLineProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
   height?: number
@@ -58,6 +60,9 @@ export type ZonedLineProps<T> = {
   xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
+  /** Tilt the x tick labels 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
+   * see `CartesianChartProps.xLabelRotate`. */
+  xLabelRotate?: 0 | 45 | 90
   /**
    * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
    * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
@@ -81,21 +86,22 @@ export type ZonedLineProps<T> = {
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
-type Valid<T> = T & { __y: number }
+type Pt<T> = T & { __y: number | null }
 
-/** The primary (and only) series' valid points — null values are dropped, creating line gaps. */
-function validPoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]): Valid<T>[] {
+/**
+ * Every row, in x order, with `__y: null` where the series reports no value. The null row STAYS in
+ * the array — see `MultiLine`'s `seriesPoints`: dropping it makes `LinePath`/`AreaClosed`/
+ * `Threshold` join straight across a coverage hole, drawing a measurement that was never taken.
+ * The shared `defined` guard below is what turns it back into a gap.
+ */
+function linePoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]): Pt<T>[] {
   if (!series) return []
-  const out: Valid<T>[] = []
-  for (const d of data) {
-    const y = series.getValue(d)
-    if (y !== null && y !== undefined && !Number.isNaN(y)) {
-      out.push(Object.assign({}, d, { __y: y }) as Valid<T>)
-    }
-  }
-  return out
+  return data.map((d) => Object.assign({}, d, { __y: toPlotPoint(series.getValue(d)) }) as Pt<T>)
 }
 
 /**
@@ -107,11 +113,15 @@ function validPoints<T>(series: ChartSeries<T> | undefined, data: readonly T[]):
  * and the derived tooltip — this kind draws ONLY the marks (thresholds, area fill, and the line).
  * Single-series, so the legend is optional in practice but present by default.
  *
- * X-axis is built from the full `data` array so the calendar is preserved even
- * when the series has nulls; the line itself skips null points (creating
- * visual gaps).
+ * X-axis is built from the full `data` array so the calendar is preserved even when the series has
+ * nulls; the line, the area fill and the threshold fills all BREAK at a null point, leaving a real
+ * gap rather than interpolating across it.
  */
 function ZonedLineInner<T>(props: ZonedLineProps<T>) {
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('ZonedLine', props, ['data', 'getX', 'series'])
   const {
     data,
     chartId,
@@ -125,6 +135,7 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
     xTicks,
     xTickValues,
     formatX,
+    xLabelRotate,
     cursorResolution,
     tooltip,
     areaFill,
@@ -132,6 +143,9 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
     legend,
     ariaLabel,
     isPending,
+    state,
+    className,
+    style,
   } = props
 
   // Default the line overlay to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) — applied
@@ -158,12 +172,16 @@ function ZonedLineInner<T>(props: ZonedLineProps<T>) {
       {...(xTicks !== undefined && { xTicks })}
       {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
+      {...(xLabelRotate !== undefined && { xLabelRotate })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(tooltip !== undefined && { tooltip })}
       {...(height !== undefined && { height })}
       {...(legend !== undefined && { legend })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(ctx: PlotContext<T>) => (
         <ZonedLineMarks
@@ -197,7 +215,22 @@ function ZonedLineMarks<T>({
   const primary = visible[0]
   // Memoized: the shared cursor re-renders every chart on every pointer frame, and this both
   // walks the full series and clones an object per point.
-  const valid = useMemo(() => validPoints(primary, data), [primary, data])
+  const pts = useMemo(() => linePoints(primary, data), [primary, data])
+
+  // ONE guard for all three shapes below, covering two absences. A null value is a documented GAP
+  // (`ChartSeries.getValue`), and a non-positive value on a log axis maps to NaN via `yScale` —
+  // without `defined` the first is drawn as an interpolated straight line across a coverage hole
+  // and the second emits a NaN path command, which per SVG error handling blanks the ENTIRE path
+  // from that point on.
+  const defined = definedOn(yScale)
+  // ONE curve for all three shapes: the threshold band, the area fill and the line are the SAME
+  // series drawn three ways, so a step line over a monotone fill would be two different readings
+  // of one measurement.
+  const curve = curveFor(primary?.curve)
+  // Never reached with a null `__y`: d3's line/area generators call the position accessors only
+  // for points `defined` accepted. The `NaN` floor is a type-level one, and it can never paint at
+  // zero the way a `?? 0` would.
+  const yOf = (d: Pt<T>) => yScale(d.__y ?? NaN)
 
   // Area is opt-in: pass a color token to get a cohesive single-hue fill under the line.
   // (A neutral fill under the neutral line just reads as grey haze, so there is no default-on.)
@@ -208,16 +241,17 @@ function ZonedLineMarks<T>({
   return (
     <>
       {thresholds.map((t, i) => (
-        <Threshold<Valid<T>>
+        <Threshold<Pt<T>>
           key={`thr-${i}`}
           id={`${chartId}-thr-${i}`}
-          data={valid}
+          data={pts}
+          defined={defined}
           x={(d) => xScale(getX(d)) ?? 0}
           y0={() => yScale(t.value)}
-          y1={(d) => yScale(d.__y)}
+          y1={yOf}
           clipAboveTo={0}
           clipBelowTo={yMax}
-          curve={curveMonotoneX}
+          curve={curve}
           belowAreaProps={{ fill: t.side === 'above' ? t.fill : 'transparent' }}
           aboveAreaProps={{ fill: t.side === 'below' ? t.fill : 'transparent' }}
         />
@@ -228,27 +262,29 @@ function ZonedLineMarks<T>({
           <defs>
             <AreaGradient id={areaId} color={areaColor} />
           </defs>
-          <AreaClosed<Valid<T>>
-            data={valid}
+          <AreaClosed<Pt<T>>
+            data={pts}
+            defined={defined}
             x={(d) => xScale(getX(d)) ?? 0}
-            y={(d) => yScale(d.__y)}
+            y={yOf}
             yScale={yScale}
-            curve={curveMonotoneX}
+            curve={curve}
             fill={areaFillUrl(areaId)}
           />
         </>
       )}
 
       {primary && (
-        <LinePath<Valid<T>>
-          data={valid}
+        <LinePath<Pt<T>>
+          data={pts}
+          defined={defined}
           x={(d) => xScale(getX(d)) ?? 0}
-          y={(d) => yScale(d.__y)}
+          y={yOf}
           stroke={primary.color}
           strokeWidth={primary.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
           strokeDasharray={primary.dash === 'dashed' ? VX.dashArray : undefined}
           strokeOpacity={primary.strokeOpacity ?? 1}
-          curve={curveMonotoneX}
+          curve={curve}
         />
       )}
     </>
@@ -259,4 +295,8 @@ function ZonedLineMarks<T>({
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot ZonedLine kind is
  * wrapped in `React.memo` to retain the auto-memoization it had as source (parity with Bars).
  */
-export const ZonedLine = memo(ZonedLineInner) as typeof ZonedLineInner
+const ZonedLineMemo = memo(ZonedLineInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+ZonedLineMemo.displayName = 'ZonedLine'
+export const ZonedLine = ZonedLineMemo as typeof ZonedLineInner

package/src/charts/layout/auto-margin.ts

@@ -13,6 +13,7 @@ import { scaleLinear } from '@visx/scale'
 import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import { maxTextWidth } from '../utils/measure-text'
+import { logTickValues, niceLogDomain } from './log-ticks'
 
 /**
  * Distance from the plot edge to the near edge of a tick LABEL: visx's default `tickLength` (8)
@@ -24,6 +25,95 @@ const AXIS_TICK_GAP = 12
 /** Line box of a single-line tick label at `fontPx`. */
 const lineHeight = (fontPx: number): number => Math.ceil(fontPx * 1.35)
 
+/**
+ * The line box split at the baseline. Only the DESCENT falls below it and only the ASCENT reaches
+ * back over the anchor, and a rotated label needs the two apart — its box is measured from the
+ * baseline point the axis anchors it at, not from a centred line box. The two ratios sum to
+ * {@link lineHeight}'s 1.35em, so nothing moves for the unrotated case.
+ */
+const DESCENT_RATIO = 0.3
+const descent = (fontPx: number): number => fontPx * DESCENT_RATIO
+const ascent = (fontPx: number): number => lineHeight(fontPx) - descent(fontPx)
+
+/**
+ * visx's own `tickLength` (`@visx/axis`'s `Axis` default) and the extra drop `Ticks` applies to a
+ * bottom-axis label — `to.y + max(10, fontSize)`. Together they are the distance from the axis LINE
+ * to the tick label's BASELINE, which is where a rotated label's box is measured from.
+ */
+const AXIS_TICK_LENGTH = 8
+const VISX_MIN_LABEL_FONT = 10
+
+/**
+ * The `dx`/`dy` nudge `primitives/Axes.tsx` paints a rotated tick label through — the d3 idiom
+ * that puts a 45° label under its tick's lower-left and centres a 90° one on its vertical line.
+ *
+ * It lives HERE, and the axis imports it, because it is the one number that must be in both
+ * places: the nudge was applied at paint and absent from the measure, so §1's measured-equals-
+ * painted law broke in exactly the rotated case §8 introduced (the first label crossed the SVG's
+ * left edge by 3.2px at 390 and 5.7px at 320, and every rotated label's descender row sat on the
+ * bottom clip line). Move a value here and the gutter moves with it.
+ */
+export const ROTATED_LABEL_OFFSET: Record<45 | 90, { dx: number; dy: number }> = {
+  45: { dx: -6, dy: 2 },
+  90: { dx: -4, dy: 4 },
+}
+
+/** Breathing room between a rotated label's painted box and the SVG's own clip edge. One px reads
+ * as flush; two is the smallest gap that reads as deliberate. */
+const ROTATED_CLEARANCE = 2
+
+const rotatedOffset = (rotate: number): { dx: number; dy: number } =>
+  ROTATED_LABEL_OFFSET[rotate as 45 | 90] ?? { dx: 0, dy: 0 }
+
+/**
+ * How far a rotated x label reaches LEFT of the plot's left edge, and how far BELOW the axis line —
+ * measured from the baseline point the axis anchors it at, through the same `dx`/`dy` the axis
+ * paints it with.
+ *
+ * `AxisBottomDate` anchors a rotated label at its right edge (`textAnchor: 'end'`) and rotates it
+ * counter-clockwise about that point, so the string runs down-and-to-the-LEFT from the tick it
+ * belongs to. The FIRST tick sits at the plot's left edge, so its label hangs into the left gutter;
+ * the LAST row of glyphs hangs below the axis. Rotating the label's box about its anchor gives both
+ * extents exactly:
+ *
+ * - left  = `cos θ · (width + ascent) − dx`  — zero at 90°, where the string runs straight down.
+ * - below = `tickLength + max(10, fontPx) + dy + sin θ · width + cos θ · descent`.
+ *
+ * Both carry {@link ROTATED_CLEARANCE} so the painted box clears the SVG's clip rather than
+ * touching it.
+ */
+export function rotatedLabelExtents(input: {
+  /** Width of the widest x tick label, already measured at the painted font. */
+  labelWidth: number
+  fontPx: number
+  rotate: number
+}): { left: number; below: number } {
+  const { labelWidth, fontPx, rotate } = input
+  if (rotate === 0) return { left: 0, below: 0 }
+  const radians = (rotate * Math.PI) / 180
+  const cos = Math.abs(Math.cos(radians))
+  const sin = Math.abs(Math.sin(radians))
+  const { dx, dy } = rotatedOffset(rotate)
+  return {
+    left: cos * (labelWidth + ascent(fontPx)) - dx + ROTATED_CLEARANCE,
+    below:
+      AXIS_TICK_LENGTH +
+      Math.max(VISX_MIN_LABEL_FONT, fontPx) +
+      dy +
+      sin * labelWidth +
+      cos * descent(fontPx) +
+      ROTATED_CLEARANCE,
+  }
+}
+
+/**
+ * The grouped-thousands default for a log axis with no explicit `format` — parity with the linear
+ * branch's own `probe.tickFormat(ticks)`, which already groups (`"100,000"`). Unbounded fraction
+ * digits (rather than `toLocaleString`'s default of 3) so a sub-unit log tick (`1e-7`) still prints
+ * its digits instead of truncating to `"0"`.
+ */
+const LOG_TICK_FORMAT = new Intl.NumberFormat('en-US', { maximumFractionDigits: 20 })
+
 export type AutoMarginInput = {
   /** Left-axis tick labels, already formatted. */
   left?: readonly string[]
@@ -33,8 +123,16 @@ export type AutoMarginInput = {
   bottom?: readonly string[]
   /** Degrees of counter-clockwise rotation applied to the x tick labels. Default 0. */
   rotate?: number
-  /** Tick-label font size. Default `VX.axisFont`. */
+  /** Tick-label font size. Default `VX.axisFont`. A phone-tier chart passes its own smaller size
+   * (`chartTierMetrics().axisFont`) — the measured label must be the painted label. */
   fontPx?: number
+  /**
+   * Per-side FLOORS. Default `VX.margin`. The phone tier passes its tightened set
+   * (`chartTierMetrics().margin`) so a static 44px left gutter does not spend an eighth of a 360px
+   * chart on a three-character label. The law itself does not move: a side may still only ever
+   * grow past its floor.
+   */
+  floor?: ChartMargin
   /** Explicit per-side overrides — applied LAST, so an escape hatch always wins. */
   override?: Partial<ChartMargin>
 }
@@ -42,44 +140,50 @@ export type AutoMarginInput = {
 /**
  * Resolve the four margins from measured labels.
  *
- * Law, per side:
- * - `left` — widest left label + gap, floored at `VX.margin.left`.
- * - `right` — with a right axis: widest right label + gap. Without one: half the widest x label,
- *   so the LAST x tick (centered on the plot's right edge) cannot clip. Both floored at
- *   `VX.margin.right`.
- * - `bottom` — one label line (or the rotated bounding height) + gap, floored at
- *   `VX.margin.bottom`.
+ * Law, per side (the floors are `VX.margin` by default; a tier may tighten them via `floor`):
+ * - `left` — widest left label + gap, floored at `VX.margin.left`. When the x labels are ROTATED
+ *   they also reach into this gutter, so the left side additionally clears their leftward
+ *   extent — see {@link rotatedLabelExtents}.
+ * - `right` — with a right axis: widest right label + gap. Without one, and the x labels are NOT
+ *   rotated: half the widest x label, so the LAST x tick (centered on the plot's right edge)
+ *   cannot clip. Without one AND rotated: nothing — a rotated label is anchored at its right edge
+ *   (`textAnchor: 'end'`, same as {@link rotatedLabelExtents}), so it hangs left of its tick, not
+ *   right, and reserving half its width would pad a side nothing paints into. Every case is
+ *   floored at `VX.margin.right`.
+ * - `bottom` — one label line + gap; when ROTATED, the label's measured drop below the axis line
+ *   ({@link rotatedLabelExtents}) instead. Floored at `VX.margin.bottom`.
  * - `top` — `VX.margin.top`. Nothing measures into it; a chart that draws into the top gutter
  *   passes an override.
  */
 export function autoMargin(input: AutoMarginInput = {}): ChartMargin {
   const fontPx = input.fontPx ?? VX.axisFont
-  const { left = [], right = [], bottom = [], rotate = 0, override } = input
+  const { left = [], right = [], bottom = [], rotate = 0, floor = VX.margin, override } = input
 
   const leftWidth = maxTextWidth(left, fontPx)
   const rightWidth = maxTextWidth(right, fontPx)
   const bottomWidth = maxTextWidth(bottom, fontPx)
 
-  const radians = (rotate * Math.PI) / 180
-  const bottomExtent =
-    rotate === 0
-      ? lineHeight(fontPx)
-      : Math.ceil(
-          Math.abs(bottomWidth * Math.sin(radians)) +
-            Math.abs(lineHeight(fontPx) * Math.cos(radians)),
-        )
+  // Measured EXACTLY as painted: through the same `dx`/`dy` `primitives/Axes.tsx` nudges a rotated
+  // label by, and from the baseline the axis anchors it at.
+  const rotated = rotatedLabelExtents({ labelWidth: bottomWidth, fontPx, rotate })
+  const bottomExtent = rotate === 0 ? lineHeight(fontPx) + AXIS_TICK_GAP : rotated.below
 
   return {
-    top: override?.top ?? VX.margin.top,
+    top: override?.top ?? floor.top,
     right:
       override?.right ??
       Math.ceil(
-        Math.max(VX.margin.right, right.length > 0 ? rightWidth + AXIS_TICK_GAP : bottomWidth / 2),
+        Math.max(
+          floor.right,
+          right.length > 0 ? rightWidth + AXIS_TICK_GAP : rotate === 0 ? bottomWidth / 2 : 0,
+        ),
       ),
-    bottom: override?.bottom ?? Math.ceil(Math.max(VX.margin.bottom, bottomExtent + AXIS_TICK_GAP)),
+    bottom: override?.bottom ?? Math.ceil(Math.max(floor.bottom, bottomExtent)),
     left:
       override?.left ??
-      Math.ceil(Math.max(VX.margin.left, left.length > 0 ? leftWidth + AXIS_TICK_GAP : 0)),
+      Math.ceil(
+        Math.max(floor.left, left.length > 0 ? leftWidth + AXIS_TICK_GAP : 0, rotated.left),
+      ),
   }
 }
 
@@ -99,7 +203,16 @@ export function probeAxisLabels(opts: {
   format?: (v: number) => string
   /** Must match the real scale's `nice` — niceing changes which ticks exist. */
   nice?: boolean
+  /** `'log'` measures through {@link logTickValues} instead of a linear probe scale — the same
+   * helper the axis paints from (CHARTS-SPEC §1: measured labels == painted labels). Default
+   * `'linear'`. */
+  scale?: 'linear' | 'log'
 }): { labels: string[]; format: (v: number) => string } {
+  if (opts.scale === 'log') {
+    const domain = opts.nice === true ? niceLogDomain(opts.domain) : opts.domain
+    const format = opts.format ?? ((v: number) => LOG_TICK_FORMAT.format(v))
+    return { labels: logTickValues(domain, opts.ticks).map(format), format }
+  }
   const probe = scaleLinear<number>({
     domain: opts.domain,
     range: [1, 0],

package/src/charts/layout/log-ticks.ts

@@ -0,0 +1,90 @@
+/**
+ * 1-2-5 mantissa tick law for a log axis (`docs/CHARTS-SPEC.md` §2).
+ *
+ * d3's own `scaleLog().ticks()` multiplies the mantissa density by the number of decades the
+ * domain spans, so a wide financial range (e.g. $10k–$300k) reads `$316,228 / $100,000 / $31,623 /
+ * $10,000` — every finance reference instead ticks a log price axis at `{1, 2, 5} × 10^n`
+ * (`$10,000 · $20,000 · $50,000 · $100,000`). Pure, no visx dependency, so both the measured
+ * (`probeAxisLabels`) and painted (`CartesianChart`) sides can share the exact same tick list.
+ */
+
+/**
+ * Escalating mantissa sets: the strict {1, 2, 5} law first, then progressively denser sets used
+ * only when the stricter one leaves too few in-domain candidates to read — a short span (a
+ * one-year BTC window, say, $58k–$139k) collapses {1, 2, 5} to a single tick, which is
+ * unreadable. Each set is ascending and never crosses a decade boundary within itself
+ * (`9 × 10^k < 1 × 10^(k+1)`), so the flatMap output stays sorted with no explicit sort.
+ */
+const MANTISSA_SETS = [
+  [1, 2, 5],
+  [1, 1.5, 2, 3, 4, 5, 7],
+  [1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8, 9],
+] as const
+
+/** Below this many in-domain candidates, escalate to the next denser mantissa set. */
+const DENSIFY_BELOW = 4
+
+/** Every base-10 exponent whose decade touches `[min, max]`. */
+function decadeExponents(min: number, max: number): number[] {
+  const lo = Math.floor(Math.log10(min))
+  const hi = Math.ceil(Math.log10(max))
+  const exponents: number[] = []
+  for (let k = lo; k <= hi; k++) exponents.push(k)
+  return exponents
+}
+
+/**
+ * Thin an ascending, over-budget value list toward `ticks`, keeping both extremes — a stride
+ * derived from the budget (`Math.ceil(length / ticks)`) rather than a fixed 2, so the result
+ * actually tracks `ticks` instead of only ever halving regardless of how far over budget the input
+ * is. May return one more than `ticks` when the last value doesn't land on the stride (an even
+ * decade count, say): keeping the axis's top labeled matters more than the exact count.
+ */
+function thinToBudget(values: number[], ticks: number): number[] {
+  if (values.length <= ticks) return values
+  const stride = Math.ceil(values.length / ticks)
+  const thinned = values.filter((_, i) => i % stride === 0)
+  const last = values[values.length - 1] as number
+  return thinned[thinned.length - 1] === last ? thinned : [...thinned, last]
+}
+
+/**
+ * Every `{1, 2, 5} × 10^k` value for every decade touching `[min, max]`, filtered to the domain —
+ * escalating through {@link MANTISSA_SETS} while a set leaves fewer than {@link DENSIFY_BELOW}
+ * candidates (a short span collapses the strict law to one tick). The exact same list is what
+ * `probeAxisLabels` measures and what `CartesianChart` paints, so the two can never disagree.
+ * An over-budget result collapses to whole decades only when the decades ALONE form a readable
+ * axis ({@link DENSIFY_BELOW}+ in-domain); otherwise it is thinned by a budget-derived stride
+ * (may exceed `ticks` by one — see {@link thinToBudget}). Collapsing to decades unconditionally
+ * is the bug this ordering exists to prevent: a 4-year BTC window ($15.5k–$139k) holds ONE whole
+ * decade, so the collapse produced a single-tick axis. Never returns a non-positive value; a
+ * non-positive or inverted domain (a log axis has no zero and no reversed extent) returns `[]`.
+ */
+export function logTickValues([min, max]: readonly [number, number], ticks: number): number[] {
+  if (min <= 0 || max <= 0 || min >= max) return []
+
+  const exponents = decadeExponents(min, max)
+  const inDomain = (v: number): boolean => v >= min && v <= max
+  const collect = (mantissas: readonly number[]): number[] =>
+    exponents.flatMap((k) => mantissas.map((m) => m * 10 ** k)).filter(inDomain)
+
+  let resolved: number[] = []
+  for (const mantissas of MANTISSA_SETS) {
+    resolved = collect(mantissas)
+    if (resolved.length >= DENSIFY_BELOW) break
+  }
+
+  if (resolved.length <= ticks) return resolved
+
+  const decades = exponents.map((k) => 10 ** k).filter(inDomain)
+  if (decades.length >= DENSIFY_BELOW) return thinToBudget(decades, ticks)
+
+  return thinToBudget(resolved, ticks)
+}
+
+/** Round a domain outward to the nearest enclosing power-of-10 bounds — the log analog of
+ * `scale.nice()`, used to keep `probeAxisLabels` (measurement) and the real niced scale
+ * (rendering) computing ticks from the same rounded domain. */
+export function niceLogDomain([min, max]: readonly [number, number]): [number, number] {
+  return [10 ** Math.floor(Math.log10(min)), 10 ** Math.ceil(Math.log10(max))]
+}

package/src/charts/primitives/Axes.tsx

@@ -1,7 +1,9 @@
 import { AxisBottom, AxisLeft, AxisRight } from '@visx/axis'
 import type { AxisScale, TickFormatter } from '@visx/axis'
 import { VX } from '../../tokens'
+import { ROTATED_LABEL_OFFSET } from '../layout/auto-margin'
 import { fmtAxisDate } from '../utils/format'
+import { useChartTierMetrics } from './chart-tier'
 
 /**
  * Tick label font — mono, per `docs/DESIGN-SPEC.md` §5 ("ticks mono 10.5px faint"). Not a `VX.*`
@@ -10,7 +12,10 @@ import { fmtAxisDate } from '../utils/format'
  */
 const TICK_FONT_FAMILY = 'var(--basalt-font-mono)'
 
-/** Themed left numeric axis — baked-in theme colors + font size. */
+/** Themed left numeric axis — baked-in theme colors + font size. The tick font tracks the ambient
+ * chart tier (`docs/CHARTS-SPEC.md` §8); a caller measuring its own gutter must measure at the
+ * SAME size (`chartTierMetrics().axisFont` into `autoMargin`'s `fontPx`), or the measured label
+ * and the painted one stop being the same string's width. */
 export function AxisLeftNumeric({
   scale,
   numTicks = 5,
@@ -20,6 +25,7 @@ export function AxisLeftNumeric({
   numTicks?: number
   tickFormat?: TickFormatter<number>
 }) {
+  const { axisFont } = useChartTierMetrics()
   return (
     <AxisLeft
       scale={scale}
@@ -28,7 +34,7 @@ export function AxisLeftNumeric({
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
-        fontSize: VX.axisFont,
+        fontSize: axisFont,
         dx: -4,
       }}
       stroke={VX.surface.border}
@@ -50,6 +56,7 @@ export function AxisRightNumeric({
   numTicks?: number
   tickFormat?: TickFormatter<number>
 }) {
+  const { axisFont } = useChartTierMetrics()
   return (
     <AxisRight
       left={left}
@@ -59,7 +66,7 @@ export function AxisRightNumeric({
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
-        fontSize: VX.axisFont,
+        fontSize: axisFont,
         dx: 4,
       }}
       stroke={VX.surface.border}
@@ -68,12 +75,23 @@ export function AxisRightNumeric({
   )
 }
 
+/**
+ * Nudge a rotated tick label back onto its tick. Both are the d3 idiom for the angle: a 45° label
+ * hangs from the tick's lower-left, a 90° one is centred on the tick's vertical line.
+ *
+ * Imported, never re-declared: `autoMargin` measures the gutter THROUGH this same nudge
+ * (`rotatedLabelExtents`), and a second copy here is exactly how the painted label came to sit
+ * 6px left of the box the measurement had reserved (`docs/CHARTS-SPEC.md` §1).
+ */
+const ROTATED_OFFSET = ROTATED_LABEL_OFFSET
+
 /** Themed bottom date axis — baked-in smartTicks + DD.MM formatting. */
 export function AxisBottomDate({
   scale,
   top,
   tickValues,
   tickFormat = fmtAxisDate,
+  rotate,
 }: {
   scale: AxisScale
   top: number
@@ -83,7 +101,15 @@ export function AxisBottomDate({
    * tick to the same label.
    */
   tickFormat?: TickFormatter<string>
+  /**
+   * Tilt each tick label counter-clockwise by 45° or 90°, anchored at its right edge — the answer
+   * to labels too wide to sit side by side. The caller owns the deepened bottom gutter it needs
+   * (`autoMargin({ rotate })`, `docs/CHARTS-SPEC.md` §1); this only paints them.
+   */
+  rotate?: 45 | 90
 }) {
+  const { axisFont } = useChartTierMetrics()
+  const rotated = rotate === undefined ? undefined : ROTATED_OFFSET[rotate]
   return (
     <AxisBottom
       top={top}
@@ -93,8 +119,10 @@ export function AxisBottomDate({
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
-        fontSize: VX.axisFont,
-        textAnchor: 'middle',
+        fontSize: axisFont,
+        textAnchor: rotated === undefined ? 'middle' : 'end',
+        ...(rotate !== undefined && { angle: -rotate }),
+        ...(rotated !== undefined && { dx: rotated.dx, dy: rotated.dy }),
       }}
       stroke={VX.surface.border}
       tickStroke={VX.surface.border}