basalt-ui 1.30.2 → 1.31.0

package/src/charts/kinds/donut-layout.ts

@@ -0,0 +1,82 @@
+import type { ContainerClass } from '../../tokens/size-classes'
+
+/** Aspect (frame W/H) above which the legend moves beside the ring. */
+export const SIDE_LEGEND_ASPECT = 1.5
+/** Aspect a side layout must fall below before it stacks again — the gap stops a legend whose own
+ * placement changes the measured height from flipping the layout back and forth. */
+export const STACK_LEGEND_ASPECT = 1.35
+/** Most slices kept before the rest fold into "Other" (so 7 or more slices fold). */
+export const DONUT_MAX_SLICES = 6
+export const OTHER_KEY = '__other'
+/** Side layout: the ring's diameter never exceeds this share of the frame width. */
+export const SIDE_RING_MAX_WIDTH_SHARE = 0.55
+/** Space kept between the ring's outer edge and the plot box. */
+export const RING_PADDING = 4
+
+export type DonutLayout = { side: boolean }
+
+/** Side legend only on a wide-enough frame (`micro`/`compact` always stack under the ring).
+ * `wasSide` applies hysteresis: an already-side layout stays side until W/H falls below
+ * {@link STACK_LEGEND_ASPECT}. */
+export function resolveDonutLayout(input: {
+  frameW: number
+  frameH: number
+  containerClass: ContainerClass
+  wasSide?: boolean
+}): DonutLayout {
+  const { frameW, frameH, containerClass, wasSide = false } = input
+  const roomy = containerClass !== 'micro' && containerClass !== 'compact'
+  if (!roomy || frameH <= 0) return { side: false }
+  const aspect = frameW / frameH
+  return { side: wasSide ? aspect >= STACK_LEGEND_ASPECT : aspect > SIDE_LEGEND_ASPECT }
+}
+
+/** Ring outer radius: never negative and never wider than the plot; the side layout also caps the
+ * diameter at {@link SIDE_RING_MAX_WIDTH_SHARE} of the frame width. */
+export function resolveDonutRadius(input: {
+  plotW: number
+  plotH: number
+  frameW: number
+  side: boolean
+}): number {
+  const { plotW, plotH, frameW, side } = input
+  const diameter = side
+    ? Math.min(plotW, plotH, SIDE_RING_MAX_WIDTH_SHARE * frameW)
+    : Math.min(plotW, plotH)
+  return Math.max(0, diameter / 2 - RING_PADDING)
+}
+
+/** Share of `total` as a whole percent; an empty total is 0%. */
+export function sharePercent(value: number, total: number): number {
+  return total > 0 ? Math.round((value / total) * 100) : 0
+}
+
+/** A slice value a ring can draw: non-finite or negative counts as 0. */
+const safeValue = (value: number): number => (Number.isFinite(value) && value > 0 ? value : 0)
+
+/** The key for the synthesized "Other" bucket — {@link OTHER_KEY}, prefixed until no input key uses it. */
+export function resolveOtherKey(keys: readonly string[]): string {
+  const taken = new Set(keys)
+  let key = OTHER_KEY
+  while (taken.has(key)) key = `_${key}`
+  return key
+}
+
+/** Keeps the top {@link DONUT_MAX_SLICES} by value (in original order) and sums the rest into one
+ * trailing "Other" entry. Non-finite and negative values count as 0. */
+export function foldOther<T extends { key: string; value: number }>(
+  slices: readonly T[],
+): { kept: T[]; other: number | null } {
+  const safe = slices.map((s) => ({ ...s, value: safeValue(s.value) }))
+  if (safe.length <= DONUT_MAX_SLICES) return { kept: safe, other: null }
+  const top = new Set(
+    safe
+      .toSorted((a, b) => b.value - a.value)
+      .slice(0, DONUT_MAX_SLICES)
+      .map((s) => s.key),
+  )
+  return {
+    kept: safe.filter((s) => top.has(s.key)),
+    other: safe.reduce((sum, s) => (top.has(s.key) ? sum : sum + s.value), 0),
+  }
+}

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

@@ -124,15 +124,20 @@ export type AutoMarginInput = {
   /** 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
-   * (`chartTierMetrics().axisFont`) — the measured label must be the painted label. */
+   * (`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
-   * (`chartTierMetrics().margin`) so a static 44px left gutter does not spend an eighth of a 360px
+   * (`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>
 }
@@ -157,7 +162,16 @@ export type AutoMarginInput = {
  */
 export function autoMargin(input: AutoMarginInput = {}): ChartMargin {
   const fontPx = input.fontPx ?? VX.axisFont
-  const { left = [], right = [], bottom = [], rotate = 0, floor = VX.margin, override } = input
+  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)
@@ -166,7 +180,8 @@ export function autoMargin(input: AutoMarginInput = {}): ChartMargin {
   // 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
+  const bottomExtent =
+    rotate === 0 ? lineHeight(fontPx) * Math.max(bottomLines, 1) + AXIS_TICK_GAP : rotated.below
 
   return {
     top: override?.top ?? floor.top,
@@ -175,7 +190,11 @@ export function autoMargin(input: AutoMarginInput = {}): ChartMargin {
       Math.ceil(
         Math.max(
           floor.right,
-          right.length > 0 ? rightWidth + AXIS_TICK_GAP : rotate === 0 ? bottomWidth / 2 : 0,
+          right.length > 0
+            ? rightWidth + AXIS_TICK_GAP
+            : rotate === 0 && !anchorTerminals
+              ? bottomWidth / 2
+              : 0,
         ),
       ),
     bottom: override?.bottom ?? Math.ceil(Math.max(floor.bottom, bottomExtent)),

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

@@ -0,0 +1,135 @@
+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/primitives/Axes.tsx

@@ -1,46 +1,109 @@
 import { AxisBottom, AxisLeft, AxisRight } from '@visx/axis'
-import type { AxisScale, TickFormatter } from '@visx/axis'
+import type { AxisScale, TickFormatter, TickRendererProps } 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'
+import { useChartMetrics } from './chart-tier'
 
 /**
  * Tick label font — mono, per `docs/DESIGN-SPEC.md` §5 ("ticks mono 10.5px faint"). Not a `VX.*`
  * ref (the token layer is off-limits to font-family additions here) — a plain reference to the
- * `--basalt-font-mono` var that `styles.css` already defines.
+ * `--basalt-font-mono` var that `styles.css` already defines. Exported so `CartesianChart`'s own
+ * end-of-line labels (the same mono tick font, painted outside any `Axis*` primitive here) read it
+ * rather than keeping a second, driftable copy of the literal.
  */
-const TICK_FONT_FAMILY = 'var(--basalt-font-mono)'
+export const TICK_FONT_FAMILY = 'var(--basalt-font-mono)'
+
+/** Horizontal padding between the tick's gridline and the near edge of its label's halo. */
+const INSIDE_LABEL_PAD_X = 4
+/** Gap kept between the tick's gridline and the near edge of an inside label. */
+const INSIDE_LABEL_GAP = 3
+/** Halo stroke width, px — wide enough to clear a mark drawn directly under the digits. */
+const INSIDE_LABEL_HALO_WIDTH = 3
+/**
+ * A tick within this many line-heights of the plot's top edge (y=0) flips its label BELOW the
+ * tick line instead of above it — the SVG viewBox is sized exactly to the plot height, so an
+ * "above" label at the very top tick would otherwise clip against it.
+ */
+const TOP_CLEARANCE_LINES = 1
+
+/** Tick label colour. Default `VX.faint`; a dual-axis chart tints it with its series' colour. */
+type TickColor = { tickColor?: string }
+const DEFAULT_TICK_COLOR = VX.faint
+
+/**
+ * Custom tick renderer for an inside-placed y label: a `paint-order: stroke` halo (the surface
+ * colour stroked wide, under the fill) instead of an opaque background chip — the chip covered
+ * whatever mark sat under it (P1-5), a halo only pushes the mark's edge outward one stroke-width.
+ * Flips to sit BELOW its tick line near the plot's top edge instead of clipping against the SVG's
+ * own viewBox.
+ */
+function InsideTickLabel({ x, y, formattedValue, fontSize, fill }: TickRendererProps) {
+  if (formattedValue === undefined) return null
+  const size = typeof fontSize === 'number' ? fontSize : VX.axisFont
+  const lineHeight = Math.round(size * 1.3)
+  const nearTop = y <= lineHeight * TOP_CLEARANCE_LINES
+  const centerY = nearTop
+    ? y + INSIDE_LABEL_GAP + lineHeight / 2
+    : y - INSIDE_LABEL_GAP - lineHeight / 2
+  return (
+    <text
+      x={x + INSIDE_LABEL_PAD_X}
+      y={centerY}
+      dominantBaseline="middle"
+      textAnchor="start"
+      fill={fill}
+      stroke={VX.surface.panel}
+      strokeWidth={INSIDE_LABEL_HALO_WIDTH}
+      paintOrder="stroke"
+      fontFamily={TICK_FONT_FAMILY}
+      fontSize={size}
+    >
+      {formattedValue}
+    </text>
+  )
+}
 
 /** 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
+ * SAME size (`chartMetrics().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,
-}: {
+  inside = false,
+  tickColor = DEFAULT_TICK_COLOR,
+}: TickColor & {
   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[]
+  /** Labels drawn over the grid, left-aligned on a surface-coloured background chip (above their
+   * line, or below it for a tick within one line-height of the plot's top edge) — the caller
+   * reserves no gutter for them (`docs/CHARTS-SPEC.md` §8). */
+  inside?: boolean
 }) {
-  const { axisFont } = useChartTierMetrics()
+  const { axisFont } = useChartMetrics()
   return (
     <AxisLeft
       scale={scale}
       numTicks={numTicks}
       {...(tickFormat !== undefined && { tickFormat })}
       {...(tickValues !== undefined && { tickValues: [...tickValues] })}
-      tickLabelProps={{
-        fill: VX.faint,
-        fontFamily: TICK_FONT_FAMILY,
-        fontSize: axisFont,
-        dx: -4,
-      }}
+      {...(inside && { tickLength: 0, hideTicks: true, tickComponent: InsideTickLabel })}
+      tickLabelProps={
+        inside
+          ? { fill: tickColor, fontSize: axisFont }
+          : {
+              fill: tickColor,
+              fontFamily: TICK_FONT_FAMILY,
+              fontSize: axisFont,
+              dx: -4,
+            }
+      }
       stroke={VX.surface.border}
       tickStroke={VX.surface.border}
     />
@@ -54,7 +117,8 @@ export function AxisRightNumeric({
   numTicks = 5,
   tickFormat,
   tickValues,
-}: {
+  tickColor = DEFAULT_TICK_COLOR,
+}: TickColor & {
   scale: AxisScale
   /** Left offset inside the Group (typically xMax). Required since AxisRight needs positioning. */
   left: number
@@ -63,7 +127,7 @@ export function AxisRightNumeric({
   /** Exact tick positions (e.g. a compass axis at 0/90/180/270). Overrides `numTicks`. */
   tickValues?: readonly number[]
 }) {
-  const { axisFont } = useChartTierMetrics()
+  const { axisFont } = useChartMetrics()
   return (
     <AxisRight
       left={left}
@@ -72,7 +136,7 @@ export function AxisRightNumeric({
       {...(tickFormat !== undefined && { tickFormat })}
       {...(tickValues !== undefined && { tickValues: [...tickValues] })}
       tickLabelProps={{
-        fill: VX.faint,
+        fill: tickColor,
         fontFamily: TICK_FONT_FAMILY,
         fontSize: axisFont,
         dx: 4,
@@ -104,7 +168,7 @@ export function AxisBottomNumeric({
   /** Exact tick positions (e.g. a compass axis at 0/90/180/270). Overrides `numTicks`. */
   tickValues?: readonly number[]
 }) {
-  const { axisFont } = useChartTierMetrics()
+  const { axisFont } = useChartMetrics()
   return (
     <AxisBottom
       top={top}
@@ -134,6 +198,18 @@ export function AxisBottomNumeric({
  */
 const ROTATED_OFFSET = ROTATED_LABEL_OFFSET
 
+/** `textAnchor` of one x label: inward at the two terminals when asked, centred otherwise. */
+export function terminalAnchor(input: {
+  anchorTerminals: boolean
+  index: number
+  count: number
+}): 'start' | 'middle' | 'end' {
+  const { anchorTerminals, index, count } = input
+  if (!anchorTerminals || count < 2) return 'middle'
+  if (index === 0) return 'start'
+  return index === count - 1 ? 'end' : 'middle'
+}
+
 /** Themed bottom date axis — baked-in smartTicks + DD.MM formatting. */
 export function AxisBottomDate({
   scale,
@@ -141,10 +217,17 @@ export function AxisBottomDate({
   tickValues,
   tickFormat = fmtAxisDate,
   rotate,
+  anchorTerminals = false,
+  wrapWidth,
 }: {
   scale: AxisScale
   top: number
   tickValues: string[]
+  /** First label anchored `start`, last `end`, so the terminals stay inside the plot instead of
+   * overflowing it. Ignored when rotated. */
+  anchorTerminals?: boolean
+  /** Wrap each label to this many px (SVG tspans) instead of thinning or rotating it. */
+  wrapWidth?: number
   /**
    * Defaults to `fmtAxisDate` (DD.MM). Override for a sub-day window, where DD.MM collapses every
    * tick to the same label.
@@ -157,7 +240,7 @@ export function AxisBottomDate({
    */
   rotate?: 45 | 90
 }) {
-  const { axisFont } = useChartTierMetrics()
+  const { axisFont } = useChartMetrics()
   const rotated = rotate === undefined ? undefined : ROTATED_OFFSET[rotate]
   return (
     <AxisBottom
@@ -165,14 +248,22 @@ export function AxisBottomDate({
       scale={scale}
       tickValues={tickValues}
       tickFormat={tickFormat}
-      tickLabelProps={{
+      tickLabelProps={(_value, index, values) => ({
         fill: VX.faint,
         fontFamily: TICK_FONT_FAMILY,
         fontSize: axisFont,
-        textAnchor: rotated === undefined ? 'middle' : 'end',
+        textAnchor:
+          rotated !== undefined
+            ? 'end'
+            : terminalAnchor({ anchorTerminals, index, count: values.length }),
         ...(rotate !== undefined && { angle: -rotate }),
         ...(rotated !== undefined && { dx: rotated.dx, dy: rotated.dy }),
-      }}
+        // A wrapped label's default baseline anchors its LAST line, which stacks the earlier ones
+        // UPWARD into the axis line and ticks (R2C-7) — `autoMargin`'s `bottomLines` reserves room
+        // BELOW the axis, so the reservation and the paint have to agree on which line anchors.
+        ...(wrapWidth !== undefined &&
+          rotated === undefined && { width: wrapWidth, verticalAnchor: 'start', dy: '-0.35em' }),
+      })}
       stroke={VX.surface.border}
       tickStroke={VX.surface.border}
     />