charts.axis

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import type { Axis, AxisOrient, AxisTick, Line } from "./charts_axis_types.ts";

// d3-axis's default gap between the end of a tick mark and its label.
const LABEL_PADDING = 3;

/** A pixel coordinate rounded to 2 places, the precision every axis output uses. */
export function axisPixel(value: number): number {
  return roundFloat(value, 2);
}

export function axisLine(x1: number, y1: number, x2: number, y2: number): Line {
  return { x1: axisPixel(x1), y1: axisPixel(y1), x2: axisPixel(x2), y2: axisPixel(y2) };
}

/** Throws unless orient is one of the four sides, so a typo is not drawn as a left axis. */
export function checkOrient(orient: string): void {
  if (orient !== "bottom" && orient !== "top" && orient !== "left" && orient !== "right") {
    throw new RangeError(`orient must be bottom, top, left or right, received "${orient}"`);
  }
}

/**
 * Axis geometry from tick positions and labels, for any scale.
 *
 * Follows d3-axis: marks point away from the plot (down for a bottom axis,
 * left for a left axis), labels sit 3 pixels past the mark's end, centred
 * under a horizontal axis and right-aligned beside a left one.
 */
export function axisFromTicks(
  positions: readonly number[],
  labels: readonly string[],
  range: readonly number[],
  orient: AxisOrient,
  position: number,
  tickSize: number,
): Axis {
  checkOrient(orient);
  if (positions.length !== labels.length) {
    throw new RangeError(`positions and labels must be the same length, received ${positions.length} and ${labels.length}`);
  }
  if (range.length !== 2) throw new RangeError(`range must have exactly 2 values, [from, to]; got ${range.length}`);
  const horizontal = orient === "bottom" || orient === "top";
  // Bottom and right axes grow in +y and +x; top and left ones in -y and -x.
  const sign = orient === "bottom" || orient === "right" ? 1 : -1;
  const markEnd = position + sign * tickSize;
  const labelAt = position + sign * (tickSize + LABEL_PADDING);
  const ticks: AxisTick[] = positions.map((p, i) => {
    if (horizontal) {
      return {
        position: axisPixel(p),
        label: labels[i],
        tick: axisLine(p, position, p, markEnd),
        labelX: axisPixel(p),
        labelY: axisPixel(labelAt),
        anchor: "middle",
        baseline: orient === "bottom" ? "hanging" : "alphabetic",
      };
    }
    return {
      position: axisPixel(p),
      label: labels[i],
      tick: axisLine(position, p, markEnd, p),
      labelX: axisPixel(labelAt),
      labelY: axisPixel(p),
      anchor: orient === "left" ? "end" : "start",
      baseline: "middle",
    };
  });
  const line = horizontal ? axisLine(range[0], position, range[1], position) : axisLine(position, range[0], position, range[1]);
  return { orient, position: axisPixel(position), line, ticks };
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { axisFromTicks } from "./charts_axis_axis_from_ticks.ts";  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
import type { Axis, AxisOrient } from "./charts_axis_types.ts";
import { formatTick } from "./charts_format_format_tick.ts";
import { linearScale } from "./charts_scale_linear_scale.ts";
import { niceTicks } from "./charts_ticks_nice_ticks.ts";
import { tickStep } from "./charts_ticks_tick_step.ts";

/**
 * A linear number axis: nice tick values inside the domain (charts.ticks),
 * placed by charts.scale's linearScale and labelled with just enough decimal
 * places for the tick step (charts.format), so 0.1-steps read 0.1, 0.2, 0.3
 * rather than 0.30000000000000004.
 */
export function numberAxis(
  domain: readonly number[],
  range: readonly number[],
  count: number,
  orient: AxisOrient,
  position: number,
  tickSize: number,
): Axis {
  if (domain.length !== 2) throw new RangeError(`domain must have exactly 2 values, [from, to]; got ${domain.length}`);
  const lo = Math.min(domain[0], domain[1]);
  const hi = Math.max(domain[0], domain[1]);
  const values = niceTicks(domain[0], domain[1], count);
  const step = tickStep(lo, hi, count);
  const positions = values.map((v) => linearScale(domain, range, v, false));
  const labels = values.map((v) => formatTick(v, step));
  return axisFromTicks(positions, labels, range, orient, position, tickSize);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { axisFromTicks } from "./charts_axis_axis_from_ticks.ts";  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
import type { Axis, AxisOrient } from "./charts_axis_types.ts";
import { formatDate } from "./charts_format_format_date.ts";
import { timeScale } from "./charts_scale_time_scale.ts";
import { timeTickInterval } from "./charts_ticks_time_tick_interval.ts";
import { timeTicks } from "./charts_ticks_time_ticks.ts";

/**
 * A date axis: the calendar interval that gives about `count` ticks (days,
 * weeks, months, quarters or years), ticks on its boundaries, placed by
 * timeScale and labelled for that interval ("Sep 2026" for months).
 */
export function timeAxis(
  domain: readonly string[],
  range: readonly number[],
  count: number,
  orient: AxisOrient,
  position: number,
  tickSize: number,
): Axis {
  if (domain.length !== 2) throw new RangeError(`domain must have exactly 2 values, [from, to]; got ${domain.length}`);
  const lo = domain[0] < domain[1] ? domain[0] : domain[1];
  const hi = domain[0] < domain[1] ? domain[1] : domain[0];
  const chosen = timeTickInterval(lo, hi, count);
  const values = timeTicks(lo, hi, chosen.interval, chosen.step);
  const positions = values.map((v) => timeScale(domain, range, v, false));
  const labels = values.map((v) => formatDate(v, chosen.interval));
  return axisFromTicks(positions, labels, range, orient, position, tickSize);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { axisFromTicks } from "./charts_axis_axis_from_ticks.ts";  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
import type { Axis, AxisOrient } from "./charts_axis_types.ts";
import { bandScale } from "./charts_scale_band_scale.ts";

/**
 * A category axis: one tick at the centre of each band, labelled with the
 * category itself. The padding is the band scale's, so ticks line up with the
 * bars drawn from the same scale.
 */
export function bandAxis(
  domain: readonly string[],
  range: readonly number[],
  paddingInner: number,
  paddingOuter: number,
  orient: AxisOrient,
  position: number,
  tickSize: number,
): Axis {
  const positions = domain.map((v) => bandScale(domain, range, v, paddingInner, paddingOuter, 0.5).center);
  return axisFromTicks(positions, domain, range, orient, position, tickSize);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { axisLine, checkOrient } from "./charts_axis_axis_from_ticks.ts";  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
import type { Axis, Line } from "./charts_axis_types.ts";

/**
 * One gridline per tick, from the axis line across the plot: up from a bottom
 * axis, down from a top one, right from a left axis and left from a right one.
 */
export function gridLines(axis: Axis, length: number): readonly Line[] {
  checkOrient(axis.orient);
  if (typeof length !== "number" || !Number.isFinite(length) || length < 0) {
    throw new RangeError(`length must be a finite number of zero or more, received ${length}`);
  }
  const pos = axis.position;
  return axis.ticks.map((t) => {
    const p = t.position;
    if (axis.orient === "bottom") return axisLine(p, pos, p, pos - length);
    if (axis.orient === "top") return axisLine(p, pos, p, pos + length);
    if (axis.orient === "left") return axisLine(pos, p, pos + length, p);
    return axisLine(pos, p, pos - length, p);
  });
}