basalt-ui 1.41.0 → 2.0.0

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

@@ -1,242 +0,0 @@
-/**
- * Plot-rect margins derived from the labels that will actually be painted.
- *
- * `VX.margin` is a static token, so charts used to clip (or get hand-nudged) whenever a tick label
- * outgrew it — the "I always push the charts around" failure mode. Here the token becomes a
- * FLOOR: a measured side may only ever grow past it, never shrink below it, so no chart gets
- * tighter than it was, and a wide label widens its own gutter automatically.
- *
- * See `docs/CHARTS-SPEC.md` §1.
- */
-
-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)
- * plus the ±4 `dx` the themed axes in `primitives/Axes.tsx` apply. Kept in one place so the
- * measured gutter and the painted axis agree.
- */
-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[]
-  /** Right-axis tick labels, already formatted. Presence (not a flag) is what widens `right`. */
-  right?: readonly string[]
-  /** X-axis tick labels, already formatted. */
-  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`. A phone-tier chart passes its own smaller size
-   * (`chartMetrics().axisFont`) — the measured label must be the painted label. */
-  fontPx?: number
-  /**
-   * Per-side FLOORS. Default `VX.margin`. The phone tier passes its tightened set
-   * (`chartMetrics().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
-  /** X labels anchored inward at the terminals (`AxisBottomDate anchorTerminals`): the last label
-   * no longer centres on the right edge, so the half-label right reservation is dropped. */
-  anchorTerminals?: boolean
-  /** Lines the tallest (wrapped) x label takes. Default 1. */
-  bottomLines?: number
-  /** Explicit per-side overrides — applied LAST, so an escape hatch always wins. */
-  override?: Partial<ChartMargin>
-}
-
-/**
- * Resolve the four margins from measured labels.
- *
- * 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,
-    floor = VX.margin,
-    anchorTerminals = false,
-    bottomLines = 1,
-    override,
-  } = input
-
-  const leftWidth = maxTextWidth(left, fontPx)
-  const rightWidth = maxTextWidth(right, fontPx)
-  const bottomWidth = maxTextWidth(bottom, fontPx)
-
-  // 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) * Math.max(bottomLines, 1) + AXIS_TICK_GAP : rotated.below
-
-  return {
-    top: override?.top ?? floor.top,
-    right:
-      override?.right ??
-      Math.ceil(
-        Math.max(
-          floor.right,
-          right.length > 0
-            ? rightWidth + AXIS_TICK_GAP
-            : rotate === 0 && !anchorTerminals
-              ? bottomWidth / 2
-              : 0,
-        ),
-      ),
-    bottom: override?.bottom ?? Math.ceil(Math.max(floor.bottom, bottomExtent)),
-    left:
-      override?.left ??
-      Math.ceil(
-        Math.max(floor.left, left.length > 0 ? leftWidth + AXIS_TICK_GAP : 0, rotated.left),
-      ),
-  }
-}
-
-/**
- * The tick labels a linear axis WILL paint, derived before the plot rect exists.
- *
- * This is what breaks the margin/scale circularity: a linear scale's tick VALUES depend only on
- * its domain, so a throwaway-range probe yields the exact label strings {@link autoMargin} needs
- * to measure — and returning the resolved `format` alongside them guarantees the measured string
- * and the painted string are the same one. Shared by `CartesianChart` and by hand-composed kinds
- * (`DualPanel`) so the two can't drift.
- */
-export function probeAxisLabels(opts: {
-  domain: [number, number]
-  ticks: number
-  /** Overrides d3's own tick format. */
-  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],
-    ...(opts.nice === true && { nice: true }),
-  })
-  const format = opts.format ?? probe.tickFormat(opts.ticks)
-  return { labels: probe.ticks(opts.ticks).map(format), format }
-}

package/src/charts/layout/end-labels.ts

@@ -1,135 +0,0 @@
-import type { ContainerClass } from '../../tokens/size-classes'
-import type { ChartSeries } from '../series'
-import { measureText } from '../utils/measure-text'
-
-/** Space between the plot edge and an end label's first glyph. */
-export const END_LABEL_GAP = 6
-
-/** End labels are for a handful of lines; past this the legend alone names them. */
-export const MAX_END_LABELS = 3
-
-/** Line box of one end label, as a multiple of its font size — the collision gap. */
-export const END_LABEL_LINE_HEIGHT = 1.3
-
-/** The gutter may take at most this share of the plot width; past it the labels are not drawn. */
-const MAX_GUTTER_SHARE = 0.25
-
-/**
- * Greedy collision nudging for direct labels. Each `ys` entry is a label's preferred CENTRE; the
- * result keeps input order and holds every label at least `minGap` from its neighbours, inside
- * `[min, max]`. Sorted by y, each label yields to the one above it, then a backward pass pulls the
- * stack up off the bottom edge. Returns `null` when the labels cannot all fit — the caller draws
- * none (the legend still names every series) rather than a partial or overlapping set.
- */
-export function nudgeLabels(input: {
-  ys: readonly number[]
-  minGap: number
-  min: number
-  max: number
-}): number[] | null {
-  const { ys, minGap, min, max } = input
-  if (ys.length === 0) return []
-  if (ys.some((y) => !Number.isFinite(y))) return null
-  if ((ys.length - 1) * minGap > max - min) return null
-
-  const order = ys.map((y, i) => ({ y, i })).toSorted((a, b) => a.y - b.y)
-
-  let prev = Number.NEGATIVE_INFINITY
-  const forward = order.map(({ y, i }) => {
-    prev = Math.max(y, min, prev + minGap)
-    return { i, y: prev }
-  })
-
-  let next = Number.POSITIVE_INFINITY
-  const back = forward.toReversed().map(({ i, y }) => {
-    next = Math.min(y, max, next - minGap)
-    return { i, y: next }
-  })
-  if (next < min) return null
-
-  return back.toSorted((a, b) => a.i - b.i).map((p) => p.y)
-}
-
-/**
- * The right gutter the end labels need: the widest label plus the gap. `null` when it would eat
- * more than a quarter of the plot — a label longer than that has no honest place in a gutter.
- */
-export function endLabelGutter(input: {
-  labels: readonly string[]
-  fontPx: number
-  plotWidth: number
-}): number | null {
-  const { labels, fontPx, plotWidth } = input
-  if (labels.length === 0) return null
-  const widest = labels.reduce((max, label) => Math.max(max, measureText(label, fontPx)), 0)
-  const gutter = Math.ceil(widest) + END_LABEL_GAP
-  return gutter > plotWidth * MAX_GUTTER_SHARE ? null : gutter
-}
-
-/** One drawn end label: the series it names and its nudged centre y. */
-export type EndLabel<T> = { series: ChartSeries<T>; y: number }
-
-/**
- * Whether and how a chart draws end-of-line labels. Eligible only on a wide container with one y
- * axis, no consumer `margin.right`, no header legend already naming every series for free (R2C-10:
- * end labels REPLACE the legend, they never duplicate it), and 2..{@link MAX_END_LABELS} visible
- * series that are all lines — a single line has its own title doing that job already (the same law
- * that already suppresses a single-entry legend, `ChartFrame.resolveLegend`'s JSDoc). Each label
- * sits at its line's last non-null value, nudged apart; the plan is `null` — no gutter reserved,
- * nothing drawn — when any rule fails, a series has no plottable value, the stack cannot fit, or
- * the gutter would be too wide. The gutter is measured from the label text.
- */
-export function planEndLabels<T>(input: {
-  containerClass: ContainerClass
-  hasY2: boolean
-  hasMarginRight: boolean
-  /** A `ChartCard` header slot already named every visible series — end labels would only repeat
-   * it, at the cost of a right-hand gutter the header slot cost nothing (R2C-10). */
-  hasHeaderLegend: boolean
-  visible: readonly ChartSeries<T>[]
-  data: readonly T[]
-  yScale: (value: number) => number
-  yMax: number
-  fontPx: number
-  /** Plot width before any gutter is taken. */
-  plotWidth: number
-}): { gutter: number; labels: EndLabel<T>[] } | null {
-  const {
-    containerClass,
-    hasY2,
-    hasMarginRight,
-    hasHeaderLegend,
-    visible,
-    data,
-    yScale,
-    yMax,
-    fontPx,
-    plotWidth,
-  } = input
-  if (containerClass !== 'wide' || hasY2 || hasMarginRight || hasHeaderLegend) return null
-  if (visible.length < 2 || visible.length > MAX_END_LABELS) return null
-  if (!visible.every((s) => s.mark === 'line')) return null
-
-  const gutter = endLabelGutter({ labels: visible.map((s) => s.label), fontPx, plotWidth })
-  if (gutter === null) return null
-
-  const placed = visible.flatMap((s) => {
-    const last = data.findLast((d) => s.getValue(d) !== null)
-    if (last === undefined) return []
-    const value = s.getValue(last)
-    if (value === null) return []
-    const y = yScale(value)
-    return Number.isFinite(y) ? [{ series: s, y }] : []
-  })
-  if (placed.length !== visible.length) return null
-
-  const lineHeight = Math.ceil(fontPx * END_LABEL_LINE_HEIGHT)
-  const ys = nudgeLabels({
-    ys: placed.map((p) => p.y),
-    minGap: lineHeight,
-    min: lineHeight / 2,
-    max: yMax - lineHeight / 2,
-  })
-  if (ys === null) return null
-  return { gutter, labels: placed.map((p, i) => ({ series: p.series, y: ys[i] ?? p.y })) }
-}

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

@@ -1,90 +0,0 @@
-/**
- * 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/AreaGradient.tsx

@@ -1,26 +0,0 @@
-/**
- * AreaGradient — the single source for the soft single-hue area fill under a line.
- *
- * Renders a vertical <linearGradient> that fades a series/line color from `--vx-area-top`
- * opacity at the data peak to `--vx-area-bottom` at the baseline. Both stops are
- * `color-mix` of a CSS-var color, so they stay theme-aware AND the dev theme lab can retune
- * the whole app's gradient strength by overriding two vars on :root — no chart edits.
- *
- * Usage (inside an <svg>):
- *   <defs><AreaGradient id={`${chartId}-area`} color={VX.line} /></defs>
- *   <AreaClosed ... fill={areaFillUrl(`${chartId}-area`)} />
- */
-
-const areaStop = (color: string, edge: 'top' | 'bottom'): string =>
-  `color-mix(in srgb, ${color} var(--vx-area-${edge}), transparent)`
-
-export function AreaGradient({ id, color }: { id: string; color: string }) {
-  return (
-    <linearGradient id={id} x1="0" x2="0" y1="0" y2="1">
-      <stop offset="0%" stopColor={areaStop(color, 'top')} />
-      <stop offset="100%" stopColor={areaStop(color, 'bottom')} />
-    </linearGradient>
-  )
-}
-
-export const areaFillUrl = (id: string): string => `url(#${id})`