basalt-ui 1.27.0 → 1.29.0

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,25 +12,33 @@ 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,
   tickFormat,
+  tickValues,
 }: {
   scale: AxisScale
   numTicks?: number
   tickFormat?: TickFormatter<number>
+  /** Exact tick positions (e.g. a compass axis at 0/90/180/270). Overrides `numTicks`. */
+  tickValues?: readonly number[]
 }) {
+  const { axisFont } = useChartTierMetrics()
   return (
     <AxisLeft
       scale={scale}
       numTicks={numTicks}
       {...(tickFormat !== undefined && { tickFormat })}
+      {...(tickValues !== undefined && { tickValues: [...tickValues] })}
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
-        fontSize: VX.axisFont,
+        fontSize: axisFont,
         dx: -4,
       }}
       stroke={VX.surface.border}
@@ -43,23 +53,28 @@ export function AxisRightNumeric({
   left,
   numTicks = 5,
   tickFormat,
+  tickValues,
 }: {
   scale: AxisScale
   /** Left offset inside the Group (typically xMax). Required since AxisRight needs positioning. */
   left: number
   numTicks?: number
   tickFormat?: TickFormatter<number>
+  /** Exact tick positions (e.g. a compass axis at 0/90/180/270). Overrides `numTicks`. */
+  tickValues?: readonly number[]
 }) {
+  const { axisFont } = useChartTierMetrics()
   return (
     <AxisRight
       left={left}
       scale={scale}
       numTicks={numTicks}
       {...(tickFormat !== undefined && { tickFormat })}
+      {...(tickValues !== undefined && { tickValues: [...tickValues] })}
       tickLabelProps={{
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
-        fontSize: VX.axisFont,
+        fontSize: axisFont,
         dx: 4,
       }}
       stroke={VX.surface.border}
@@ -68,12 +83,64 @@ export function AxisRightNumeric({
   )
 }
 
+/**
+ * Themed bottom numeric axis — the numeric twin of {@link AxisLeftNumeric}, for a plot whose x is
+ * a continuous number rather than a date/category (e.g. `sky-panorama.tsx`'s azimuth 0–360°,
+ * `docs/CHARTS-SPEC.md` issue #52). Exists so a bespoke continuous-x plot — declared exempt from
+ * `CartesianChart` by a `theme-allow-file hand-rolled-plot` waiver, since the point-scale x axis
+ * that primitive builds cannot represent one — stops re-implementing tick text/color/font by hand.
+ */
+export function AxisBottomNumeric({
+  scale,
+  top,
+  numTicks = 5,
+  tickFormat,
+  tickValues,
+}: {
+  scale: AxisScale
+  top: number
+  numTicks?: number
+  tickFormat?: TickFormatter<number>
+  /** Exact tick positions (e.g. a compass axis at 0/90/180/270). Overrides `numTicks`. */
+  tickValues?: readonly number[]
+}) {
+  const { axisFont } = useChartTierMetrics()
+  return (
+    <AxisBottom
+      top={top}
+      scale={scale}
+      numTicks={numTicks}
+      {...(tickFormat !== undefined && { tickFormat })}
+      {...(tickValues !== undefined && { tickValues: [...tickValues] })}
+      tickLabelProps={{
+        fill: VX.faint,
+        fontFamily: TICK_FONT_FAMILY,
+        fontSize: axisFont,
+        textAnchor: 'middle',
+      }}
+      stroke={VX.surface.border}
+      tickStroke={VX.surface.border}
+    />
+  )
+}
+
+/**
+ * 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 +150,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 +168,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}