insomni-plot 0.1.0-alpha.0

package/src/axis.ts

@@ -0,0 +1,765 @@
+import { BLACK, type Color, type GlyphAtlas, type Layer } from "insomni";
+import {
+  timeTickFormat,
+  timeTicks,
+  type AxisScale,
+  type BandScale,
+  type ContinuousScale,
+  type TickFormatter,
+  type TimeIntervalUnit,
+  type TimeScale,
+} from "./scales.ts";
+
+/**
+ * Explicit time interval for axis ticks: render one tick per `step × unit`
+ * regardless of how many fit. `quarter` is sugar for `month, step: 3`. Pairs
+ * with {@link AxisOptions.ticks} on time scales — ignored on numeric / band
+ * scales (those fall back to a default tick count).
+ */
+export interface TickIntervalSpec {
+  interval: TimeIntervalUnit;
+  step?: number;
+}
+
+/**
+ * Tick generation strategy on continuous scales:
+ * - `number` — target count (current default behavior).
+ * - `"auto"` — derive count from the axis's pixel span (~80px/tick horizontal,
+ *   ~50px/tick vertical). Cheap proxy for "as many ticks as comfortably fit."
+ * - `TickIntervalSpec` — explicit time interval (time scales only).
+ *
+ * `undefined` keeps the previous default of {@link DEFAULT_TICKS}.
+ */
+export type TickSpec = number | "auto" | TickIntervalSpec;
+
+/**
+ * Loose tick formatter signature consumed by the grammar's `AxisSpec.format`.
+ * The runtime calls it with the active scale's tick value — `number` for
+ * linear/log/sqrt, `Date` for time, `string` for band scales. Typed loose so
+ * consumers can write `(v: number) => ...` or `(v: Date) => ...` directly
+ * without a wrapping cast; narrow inside the function to the type your scale
+ * produces.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AxisTickFormatter = (value: any) => string;
+
+type AxisOrientation = "bottom" | "left" | "top" | "right";
+
+export interface AxisOrigin {
+  x?: number;
+  y?: number;
+}
+
+/**
+ * Configuration for axis tick labels. Currently only carries `maxWidth` —
+ * existing `labelFontSize` / `labelColor` / etc. live as flat keys on
+ * `AxisOptions` for back-compat. New per-label knobs go here.
+ */
+export interface AxisLabelConfig {
+  /**
+   * Maximum width in pixels for any tick label. Labels exceeding this width
+   * are truncated to the longest prefix that fits with a trailing ellipsis
+   * (`…`). Requires `atlas` to measure text. When unset, labels render at
+   * their natural width.
+   */
+  maxWidth?: number;
+}
+
+/**
+ * Axis title — accepts either a plain string or a config object. The object
+ * form lets callers cap the title's rendered width with an ellipsis.
+ */
+export type AxisTitle = string | { text: string; maxWidth?: number };
+
+export interface AxisOptions<Value> {
+  ticks?: TickSpec;
+  tickValues?: readonly Value[];
+  /**
+   * Render shorter, unlabeled minor tick marks between the major ticks.
+   * - Number `N`: subdivide each major interval into `N` parts (so `N=2`
+   *   places one minor halfway between every adjacent major pair).
+   * - Array: explicit minor tick values, used as-is.
+   *
+   * Minor ticks never render labels and don't affect axis measurement.
+   */
+  minorTicks?: number | readonly Value[];
+  /** Length of minor tick marks. Default `tickSize / 2`. */
+  minorTickSize?: number;
+  /**
+   * Render a tick label only every `N`th major tick. Default `1` (every
+   * major). Use `2` to label every other tick, etc. The hidden ticks still
+   * draw their tick mark and grid line. The first tick is always labeled.
+   */
+  labelStep?: number;
+  /**
+   * Automatic label collision avoidance. `"auto"` measures the
+   * formatted tick labels and inflates `labelStep` until no two visible
+   * labels overlap (with a small padding). Off by default — opt in when
+   * the axis density is data-driven (dense band axes, time axes whose
+   * domain rescales on zoom). Falls back to `labelStep` when no atlas
+   * is available.
+   */
+  labelCollision?: "auto";
+  format?: TickFormatter<Value>;
+  atlas?: GlyphAtlas;
+  labels?: boolean;
+  tickSize?: number;
+  tickWidth?: number;
+  tickColor?: Color;
+  axisLine?: boolean;
+  axisLineWidth?: number;
+  axisLineColor?: Color;
+  /**
+   * Override the axis-line extent in pixels along the axis direction. Defaults
+   * to the scale's range. Pass `[0, plotFrame.width]` (or `.height`) to draw
+   * the spine across the full plot frame even when the data range is inset
+   * (framePadding / `prepareRange` reservations).
+   */
+  axisLineExtent?: readonly [number, number];
+  labelPadding?: number;
+  labelColor?: Color;
+  labelFontSize?: number;
+  labelFontFamily?: string;
+  labelFontWeight?: string;
+  labelFontStyle?: string;
+  /** Per-label configuration (currently `maxWidth` for ellipsis truncation). */
+  label?: AxisLabelConfig;
+  gridLines?: boolean;
+  gridLength?: number;
+  gridWidth?: number;
+  gridColor?: Color;
+  /**
+   * Axis title. Rendered upright alongside the axis — outside the tick
+   * labels for horizontal axes, above the axis line for vertical axes.
+   * Requires `atlas`. Skipped when undefined / empty. Pass an object form
+   * `{ text, maxWidth }` to cap the title width with ellipsis.
+   */
+  title?: AxisTitle;
+  titlePadding?: number;
+  titleFontSize?: number;
+  titleFontFamily?: string;
+  titleFontWeight?: string;
+  titleFontStyle?: string;
+  titleColor?: Color;
+}
+
+const ELLIPSIS = "…";
+
+export interface TruncateFontOptions {
+  fontSize: number;
+  fontFamily?: string;
+  fontWeight?: string;
+  fontStyle?: string;
+}
+
+/**
+ * Truncate `text` so its rendered width fits within `maxWidth`, appending an
+ * ellipsis when the original text is too wide. Returns the original text if
+ * it already fits or if measurement is impossible. Uses binary search over
+ * prefix lengths for O(log n) `measureText` calls.
+ */
+export function truncateToWidth(
+  atlas: GlyphAtlas | undefined,
+  text: string,
+  maxWidth: number | undefined,
+  font: TruncateFontOptions,
+): string {
+  if (!atlas || !maxWidth || maxWidth <= 0 || text.length === 0) return text;
+  const measureOpts = {
+    fontSize: font.fontSize,
+    fontFamily: font.fontFamily ?? "sans-serif",
+    fontWeight: font.fontWeight ?? "normal",
+    fontStyle: font.fontStyle ?? "normal",
+    simple: true,
+  };
+  const fullWidth = atlas.measureText(text, measureOpts).width;
+  if (fullWidth <= maxWidth) return text;
+  const ellipsisWidth = atlas.measureText(ELLIPSIS, measureOpts).width;
+  if (ellipsisWidth >= maxWidth) return ELLIPSIS;
+  // Binary search the largest prefix length whose width + ellipsis fits.
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    const candidate = text.slice(0, mid) + ELLIPSIS;
+    if (atlas.measureText(candidate, measureOpts).width <= maxWidth) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return lo > 0 ? text.slice(0, lo) + ELLIPSIS : ELLIPSIS;
+}
+
+function resolveAxisTitle(title: AxisTitle | undefined): {
+  text: string;
+  maxWidth: number | undefined;
+} | null {
+  if (!title) return null;
+  if (typeof title === "string") {
+    return title.length > 0 ? { text: title, maxWidth: undefined } : null;
+  }
+  return title.text.length > 0 ? { text: title.text, maxWidth: title.maxWidth } : null;
+}
+
+export interface AxisMeasurement {
+  /**
+   * Total perpendicular space the axis needs. For horizontal axes this is
+   * tick size + label height + (title padding + title height when present),
+   * since the title sits below/above the labels. For vertical axes this is
+   * tick size + label width only — the title for vertical axes is rendered
+   * above the axis (parallel to the value range) and reported separately
+   * via `axialTitleOverhead` so callers can reserve vertical space for it.
+   */
+  readonly thickness: number;
+  /** Maximum measured width across all formatted tick labels. */
+  readonly maxLabelWidth: number;
+  /** Tick label height (font size). */
+  readonly labelHeight: number;
+  /** Whether a title is present and was measured. */
+  readonly hasTitle: boolean;
+  /** Measured title font size (0 if no title). */
+  readonly titleHeight: number;
+  /**
+   * Pixels the axis title needs *along* the value-range axis, on top of the
+   * axis itself. Non-zero only for vertical axes with a title (which is
+   * rendered above the axis line). Horizontal axes return 0 — their title's
+   * footprint is already included in `thickness`.
+   */
+  readonly axialTitleOverhead: number;
+}
+
+export interface AxisBuilder<Value> {
+  addTo(layer: Layer, origin?: AxisOrigin): Layer;
+  /**
+   * Measure how much room the axis will occupy on its perpendicular axis.
+   * Use the result as `AXIS_MARGIN.bottom/left/...` so callers don't have to
+   * hand-tune padding for long tick labels or axis titles.
+   *
+   * Requires an atlas — pass either `options.atlas` at construction or one
+   * via the `atlas` argument here.
+   */
+  measure(atlas?: GlyphAtlas): AxisMeasurement;
+  readonly tickValues: readonly Value[];
+}
+
+const DEFAULT_TICKS = 5;
+
+function withAlpha(color: Color, alpha: number): Color {
+  return { r: color.r, g: color.g, b: color.b, a: alpha };
+}
+
+function isBandScale<Value>(scale: AxisScale<Value>): scale is BandScale<Value> {
+  return "bandwidth" in scale;
+}
+
+function isTimeScale<Value>(scale: AxisScale<Value>): scale is TimeScale {
+  return !isBandScale(scale) && scale.domain[0] instanceof Date;
+}
+
+function isIntervalSpec(spec: TickSpec | undefined): spec is TickIntervalSpec {
+  return typeof spec === "object" && spec !== null && "interval" in spec;
+}
+
+const PIXELS_PER_TICK_HORIZONTAL = 80;
+const PIXELS_PER_TICK_VERTICAL = 50;
+
+function autoTickCount<Value>(scale: AxisScale<Value>, orientation: AxisOrientation): number {
+  const [r0, r1] = scale.range;
+  const span = Math.abs(r1 - r0);
+  const target =
+    orientation === "left" || orientation === "right"
+      ? PIXELS_PER_TICK_VERTICAL
+      : PIXELS_PER_TICK_HORIZONTAL;
+  return Math.max(2, Math.round(span / target));
+}
+
+function resolveTickCount<Value>(
+  scale: AxisScale<Value>,
+  options: AxisOptions<Value>,
+  orientation: AxisOrientation,
+): number {
+  const ticks = options.ticks;
+  if (typeof ticks === "number") return ticks;
+  if (ticks === "auto") return autoTickCount(scale, orientation);
+  return DEFAULT_TICKS;
+}
+
+function resolveTickValues<Value>(
+  scale: AxisScale<Value>,
+  options: AxisOptions<Value>,
+  orientation: AxisOrientation,
+): readonly Value[] {
+  if (options.tickValues) return options.tickValues;
+  if (isBandScale(scale)) {
+    return scale.ticks();
+  }
+  if (isIntervalSpec(options.ticks) && isTimeScale(scale)) {
+    return timeTicks(
+      scale.domain,
+      options.ticks.interval,
+      options.ticks.step ?? 1,
+    ) as readonly Value[];
+  }
+  const count = resolveTickCount(scale, options, orientation);
+  return (scale as ContinuousScale | TimeScale).ticks(count) as readonly Value[];
+}
+
+/**
+ * Compute minor tick positions in *axis-local pixel space* (relative to the
+ * range origin). Returns an empty array when no minor ticks are configured.
+ * Explicit value arrays are routed through the scale; numeric subdivisions
+ * are interpolated between adjacent majors.
+ */
+function resolveMinorTicks<Value>(
+  scale: AxisScale<Value>,
+  options: AxisOptions<Value>,
+  majors: readonly Value[],
+): readonly number[] {
+  const spec = options.minorTicks;
+  if (spec === undefined) return [];
+  if (Array.isArray(spec)) {
+    const out: number[] = [];
+    for (const v of spec) {
+      const px = positionForTick(scale, v as Value);
+      if (Number.isFinite(px)) out.push(px);
+    }
+    return out;
+  }
+  const subdivisions = Math.floor(spec as number);
+  if (subdivisions < 2 || majors.length < 2) return [];
+  const out: number[] = [];
+  for (let i = 0; i < majors.length - 1; i++) {
+    const a = positionForTick(scale, majors[i]!);
+    const b = positionForTick(scale, majors[i + 1]!);
+    if (!Number.isFinite(a) || !Number.isFinite(b)) continue;
+    for (let k = 1; k < subdivisions; k++) {
+      out.push(a + ((b - a) * k) / subdivisions);
+    }
+  }
+  return out;
+}
+
+function resolveFormatter<Value>(
+  scale: AxisScale<Value>,
+  options: AxisOptions<Value>,
+  orientation: AxisOrientation,
+): TickFormatter<Value> {
+  if (options.format) return options.format;
+  if (isBandScale(scale)) {
+    return scale.tickFormat();
+  }
+  if (isIntervalSpec(options.ticks) && isTimeScale(scale)) {
+    return timeTickFormat(options.ticks.interval, options.ticks.step ?? 1) as TickFormatter<Value>;
+  }
+  const count = resolveTickCount(scale, options, orientation);
+  return (scale as ContinuousScale | TimeScale).tickFormat(count) as TickFormatter<Value>;
+}
+
+function resolveAxisExtent<Value>(scale: AxisScale<Value>): readonly [number, number] {
+  return scale.range;
+}
+
+function resolveGridLength<Value>(scale: AxisScale<Value>, options: AxisOptions<Value>): number {
+  if (typeof options.gridLength === "number") return options.gridLength;
+  if (!options.gridLines) return 0;
+  const [start, stop] = resolveAxisExtent(scale);
+  return Math.abs(stop - start);
+}
+
+function positionForTick<Value>(scale: AxisScale<Value>, tick: Value): number {
+  const raw = scale(tick as never);
+  if (isBandScale(scale)) {
+    return raw + scale.bandwidth() / 2;
+  }
+  return raw;
+}
+
+function createAxis<Value>(
+  orientation: AxisOrientation,
+  scale: AxisScale<Value>,
+  options: AxisOptions<Value> = {},
+): AxisBuilder<Value> {
+  const tickValues = resolveTickValues(scale, options, orientation);
+  const minorPositions = resolveMinorTicks(scale, options, tickValues);
+  const format = resolveFormatter(scale, options, orientation);
+  const baseLabelStep = Math.max(1, Math.floor(options.labelStep ?? 1));
+
+  // Cache the post-collision label step so `measure` and `addTo` agree.
+  // Lazy because the atlas may arrive via `measure(atlasArg)` rather than
+  // `options.atlas`; first caller wins, subsequent callers reuse.
+  let cachedLabelStep: number | null = null;
+  const resolveLabelStep = (atlas: GlyphAtlas | undefined): number => {
+    if (cachedLabelStep !== null) return cachedLabelStep;
+    if (options.labelCollision !== "auto" || !atlas || tickValues.length < 2) {
+      cachedLabelStep = baseLabelStep;
+      return baseLabelStep;
+    }
+    const labelHeight = options.labelFontSize ?? 12;
+    const fontFamily = options.labelFontFamily ?? "sans-serif";
+    const fontWeight = options.labelFontWeight ?? "normal";
+    const fontStyle = options.labelFontStyle ?? "normal";
+    const labelMaxWidth = options.label?.maxWidth;
+    const horizontal = orientation === "bottom" || orientation === "top";
+
+    // Find the smallest gap between adjacent tick positions along the axis.
+    // For continuous scales the gap is uniform; for band scales the bandwidth
+    // varies only with padding. Sampling adjacents is cheap and correct.
+    let minGap = Infinity;
+    for (let i = 1; i < tickValues.length; i++) {
+      const a = (scale as (v: Value) => number)(tickValues[i - 1]!);
+      const b = (scale as (v: Value) => number)(tickValues[i]!);
+      const gap = Math.abs(b - a);
+      if (gap > 0 && gap < minGap) minGap = gap;
+    }
+    if (!Number.isFinite(minGap) || minGap <= 0) {
+      cachedLabelStep = baseLabelStep;
+      return baseLabelStep;
+    }
+
+    // For horizontal axes the constraint is label width vs. tick gap;
+    // for vertical axes it's label height vs. tick gap.
+    let neededPerTick = 0;
+    if (horizontal) {
+      let maxLabelWidth = 0;
+      for (let i = 0; i < tickValues.length; i++) {
+        const tick = tickValues[i]!;
+        const text = truncateToWidth(atlas, format(tick), labelMaxWidth, {
+          fontSize: labelHeight,
+          fontFamily,
+          fontWeight,
+          fontStyle,
+        });
+        const m = atlas.measureText(text, {
+          fontSize: labelHeight,
+          fontFamily,
+          fontWeight,
+          fontStyle,
+          simple: true,
+        });
+        if (m.width > maxLabelWidth) maxLabelWidth = m.width;
+      }
+      // Add a small padding so adjacent labels don't visually kiss.
+      neededPerTick = maxLabelWidth + 6;
+    } else {
+      neededPerTick = labelHeight + 4;
+    }
+    const computed = Math.max(baseLabelStep, Math.ceil(neededPerTick / minGap));
+    cachedLabelStep = computed;
+    return computed;
+  };
+
+  const labelVisible = (i: number, atlas: GlyphAtlas | undefined): boolean => {
+    const step = resolveLabelStep(atlas);
+    return step === 1 || i % step === 0;
+  };
+
+  return {
+    tickValues,
+    measure(atlasArg?: GlyphAtlas): AxisMeasurement {
+      const atlas = atlasArg ?? options.atlas;
+      const labelHeight = options.labelFontSize ?? 12;
+      const titleFontSize = options.titleFontSize ?? labelHeight * 1.1;
+      const labelPadding = options.labelPadding ?? 4;
+      const titlePadding = options.titlePadding ?? labelPadding * 3;
+      const tickSize = options.tickSize ?? 6;
+      const showLabels = options.labels ?? true;
+      const fontFamily = options.labelFontFamily ?? "sans-serif";
+      const fontWeight = options.labelFontWeight ?? "normal";
+      const fontStyle = options.labelFontStyle ?? "normal";
+      const labelMaxWidth = options.label?.maxWidth;
+
+      let maxLabelWidth = 0;
+      if (showLabels && atlas) {
+        for (let i = 0; i < tickValues.length; i++) {
+          if (!labelVisible(i, atlas)) continue;
+          const tick = tickValues[i]!;
+          const text = truncateToWidth(atlas, format(tick), labelMaxWidth, {
+            fontSize: labelHeight,
+            fontFamily,
+            fontWeight,
+            fontStyle,
+          });
+          const m = atlas.measureText(text, {
+            fontSize: labelHeight,
+            fontFamily,
+            fontWeight,
+            fontStyle,
+            simple: true,
+          });
+          if (m.width > maxLabelWidth) maxLabelWidth = m.width;
+        }
+      }
+
+      const titleSpec = resolveAxisTitle(options.title);
+      const hasTitle = titleSpec !== null;
+      const titleHeight = hasTitle ? titleFontSize : 0;
+
+      let thickness: number;
+      let axialTitleOverhead = 0;
+      if (orientation === "bottom" || orientation === "top") {
+        // Axis line + tick + gap + label height (+ title padding + title)
+        thickness = tickSize + labelPadding + (showLabels ? labelHeight : 0);
+        if (hasTitle) thickness += titlePadding + titleHeight;
+      } else {
+        // Vertical: thickness covers tick + label width only. The title
+        // is drawn above the axis line, so its footprint is parallel to
+        // the value range — reported via axialTitleOverhead.
+        thickness = tickSize + labelPadding + (showLabels ? maxLabelWidth : 0);
+        if (hasTitle) axialTitleOverhead = titlePadding + titleHeight;
+      }
+
+      return {
+        thickness,
+        maxLabelWidth,
+        labelHeight,
+        hasTitle,
+        titleHeight,
+        axialTitleOverhead,
+      };
+    },
+    addTo(layer: Layer, origin: AxisOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const tickSize = options.tickSize ?? 6;
+      const tickWidth = options.tickWidth ?? 1;
+      const tickColor = options.tickColor ?? BLACK;
+      const axisLineColor = options.axisLineColor ?? tickColor;
+      const axisLineWidth = options.axisLineWidth ?? tickWidth;
+      const labelPadding = options.labelPadding ?? 4;
+      const labelColor = options.labelColor ?? BLACK;
+      const labelFontSize = options.labelFontSize ?? 12;
+      const labelFontFamily = options.labelFontFamily ?? "sans-serif";
+      const labelFontWeight = options.labelFontWeight ?? "normal";
+      const labelFontStyle = options.labelFontStyle ?? "normal";
+      const labelMaxWidth = options.label?.maxWidth;
+      const labelFont: TruncateFontOptions = {
+        fontSize: labelFontSize,
+        fontFamily: labelFontFamily,
+        fontWeight: labelFontWeight,
+        fontStyle: labelFontStyle,
+      };
+      const showLabels = options.labels ?? true;
+      const gridLength = resolveGridLength(scale, options);
+      const gridWidth = options.gridWidth ?? 1;
+      const gridColor = options.gridColor ?? withAlpha(tickColor, tickColor.a * 0.25);
+      const [rangeStart, rangeStop] = resolveAxisExtent(scale);
+      const labelAtlas = options.atlas ?? layer.atlas;
+
+      if (options.axisLine ?? true) {
+        const [lineStart, lineStop] = options.axisLineExtent ?? [rangeStart, rangeStop];
+        if (orientation === "bottom" || orientation === "top") {
+          layer.pushLine({
+            x1: ox + lineStart,
+            y1: oy,
+            x2: ox + lineStop,
+            y2: oy,
+            color: axisLineColor,
+            width: axisLineWidth,
+          });
+        } else {
+          layer.pushLine({
+            x1: ox,
+            y1: oy + lineStart,
+            x2: ox,
+            y2: oy + lineStop,
+            color: axisLineColor,
+            width: axisLineWidth,
+          });
+        }
+      }
+
+      // `pushText` will throw with a helpful message if neither `options.atlas`
+      // nor `layer.atlas` (from `renderer.createLayer()`) resolves an atlas.
+
+      // Minor tick marks first (under the major ticks if they happen to overlap).
+      if (minorPositions.length > 0) {
+        const minorSize = options.minorTickSize ?? tickSize / 2;
+        for (const position of minorPositions) {
+          if (orientation === "bottom" || orientation === "top") {
+            const x = ox + position;
+            const tickDir = orientation === "bottom" ? 1 : -1;
+            layer.pushLine({
+              x1: x,
+              y1: oy,
+              x2: x,
+              y2: oy + tickDir * minorSize,
+              color: tickColor,
+              width: tickWidth,
+            });
+          } else {
+            const y = oy + position;
+            const tickDir = orientation === "left" ? -1 : 1;
+            layer.pushLine({
+              x1: ox,
+              y1: y,
+              x2: ox + tickDir * minorSize,
+              y2: y,
+              color: tickColor,
+              width: tickWidth,
+            });
+          }
+        }
+      }
+
+      for (let tickIndex = 0; tickIndex < tickValues.length; tickIndex++) {
+        const tick = tickValues[tickIndex]!;
+        const position = positionForTick(scale, tick);
+        const drawLabel = showLabels && labelAtlas != null && labelVisible(tickIndex, options.atlas);
+
+        if (orientation === "bottom" || orientation === "top") {
+          const x = ox + position;
+          const tickDir = orientation === "bottom" ? 1 : -1;
+          layer.pushLine({
+            x1: x,
+            y1: oy,
+            x2: x,
+            y2: oy + tickDir * tickSize,
+            color: tickColor,
+            width: tickWidth,
+          });
+
+          if (gridLength > 0 && options.gridLines) {
+            layer.pushLine({
+              x1: x,
+              y1: oy,
+              x2: x,
+              y2: oy - tickDir * gridLength,
+              color: gridColor,
+              width: gridWidth,
+            });
+          }
+
+          if (drawLabel) {
+            layer.pushText({
+              simple: true,
+              text: truncateToWidth(options.atlas, format(tick), labelMaxWidth, labelFont),
+              x,
+              y:
+                orientation === "bottom"
+                  ? oy + tickSize + labelPadding
+                  : oy - tickSize - labelPadding - labelFontSize,
+              fontSize: labelFontSize,
+              color: labelColor,
+              align: "center",
+            });
+          }
+
+          continue;
+        }
+
+        const y = oy + position;
+        const tickDir = orientation === "left" ? -1 : 1;
+        layer.pushLine({
+          x1: ox,
+          y1: y,
+          x2: ox + tickDir * tickSize,
+          y2: y,
+          color: tickColor,
+          width: tickWidth,
+        });
+
+        if (gridLength > 0 && options.gridLines) {
+          layer.pushLine({
+            x1: ox,
+            y1: y,
+            x2: ox - tickDir * gridLength,
+            y2: y,
+            color: gridColor,
+            width: gridWidth,
+          });
+        }
+
+        if (drawLabel) {
+          layer.pushText({
+            simple: true,
+            text: truncateToWidth(options.atlas, format(tick), labelMaxWidth, labelFont),
+            x: orientation === "left" ? ox - tickSize - labelPadding : ox + tickSize + labelPadding,
+            y: y - labelFontSize / 2,
+            fontSize: labelFontSize,
+            color: labelColor,
+            align: orientation === "left" ? "right" : "left",
+          });
+        }
+      }
+
+      // ---- Axis title ----
+      const titleSpec = resolveAxisTitle(options.title);
+      if (titleSpec && labelAtlas != null) {
+        const titleFontSize = options.titleFontSize ?? labelFontSize * 1.1;
+        const titlePadding = options.titlePadding ?? labelPadding * 3;
+        const titleColor = options.titleColor ?? labelColor;
+        const titleFontFamily = options.titleFontFamily ?? labelFontFamily;
+        const titleFontWeight = options.titleFontWeight ?? "600";
+        const titleFontStyle = options.titleFontStyle ?? labelFontStyle;
+        const titleText = truncateToWidth(options.atlas, titleSpec.text, titleSpec.maxWidth, {
+          fontSize: titleFontSize,
+          fontFamily: titleFontFamily,
+          fontWeight: titleFontWeight,
+          fontStyle: titleFontStyle,
+        });
+
+        if (orientation === "bottom" || orientation === "top") {
+          const midX = ox + (rangeStart + rangeStop) / 2;
+          const titleY =
+            orientation === "bottom"
+              ? oy + tickSize + labelPadding + labelFontSize + titlePadding
+              : oy - tickSize - labelPadding - labelFontSize - titlePadding - titleFontSize;
+          layer.pushText({
+            simple: true,
+            text: titleText,
+            x: midX,
+            y: titleY,
+            fontSize: titleFontSize,
+            color: titleColor,
+            align: "center",
+          });
+        } else {
+          // Vertical axes — place title above the axis, aligned with the axis line.
+          // (Text rotation isn't supported yet, so we keep it horizontal and short.)
+          const axisTop = oy + Math.min(rangeStart, rangeStop);
+          const titleY = axisTop - titlePadding - titleFontSize;
+          layer.pushText({
+            simple: true,
+            text: titleText,
+            x: ox,
+            y: titleY,
+            fontSize: titleFontSize,
+            color: titleColor,
+            align: orientation === "left" ? "left" : "right",
+          });
+        }
+      }
+
+      return layer;
+    },
+  };
+}
+
+export function bottomAxis<Value>(
+  scale: AxisScale<Value>,
+  options?: AxisOptions<Value>,
+): AxisBuilder<Value> {
+  return createAxis("bottom", scale, options);
+}
+
+export function leftAxis<Value>(
+  scale: AxisScale<Value>,
+  options?: AxisOptions<Value>,
+): AxisBuilder<Value> {
+  return createAxis("left", scale, options);
+}
+
+export function topAxis<Value>(
+  scale: AxisScale<Value>,
+  options?: AxisOptions<Value>,
+): AxisBuilder<Value> {
+  return createAxis("top", scale, options);
+}
+
+export function rightAxis<Value>(
+  scale: AxisScale<Value>,
+  options?: AxisOptions<Value>,
+): AxisBuilder<Value> {
+  return createAxis("right", scale, options);
+}