charts.ticks

/**
 * The tick step for about `count` ticks between start and stop: 1, 2 or 5
 * times a power of ten, as d3-array's tickIncrement chooses it.
 *
 * The power of ten is found by multiplying whole numbers, never with log10,
 * and a fractional step is returned as factor / 10^k, a single correctly
 * rounded division, so it is exactly the double 0.2 or 0.05 in every
 * language rather than 0.1 * 2 or 10^-2 * 5 with their stray last digits.
 */
export function tickStep(start: number, stop: number, count: number): number {
  const [mul, div] = tickSpec(start, stop, count);
  return mul / div;
}

// Exported for niceTicks, which needs the step as a multiplier or a divisor
// so every tick is one exact operation on a whole number.

/**
 * The step as [multiplier, divisor], one of which is 1: [20, 1] is a step of
 * 20, [1, 5] a step of 0.2. [0, 1] when start equals stop.
 */
export function tickSpec(start: number, stop: number, count: number): [number, number] {
  if (typeof start !== "number" || !Number.isFinite(start) || typeof stop !== "number" || !Number.isFinite(stop)) {
    throw new Error(`start and stop must be finite numbers; got ${start} and ${stop}`);
  }
  if (!Number.isInteger(count) || count < 1) throw new Error(`count must be a whole number of at least 1, got ${count}`);
  const raw = Math.abs(stop - start) / count;
  if (raw === 0) return [0, 1];
  if (raw >= 1) {
    let power = 1;
    while (power * 10 <= raw) power *= 10;
    return [niceFactor(raw / power) * power, 1];
  }
  let inverse = 1;
  while (raw * inverse < 1) inverse *= 10;
  const factor = niceFactor(raw * inverse);
  return factor === inverse ? [1, 1] : [1, inverse / factor];
}

/** d3's rule: round the mantissa (1 to 10) to 1, 2, 5 or 10 on a log scale. */
function niceFactor(error: number): number {
  if (error >= Math.sqrt(50)) return 10;
  if (error >= Math.sqrt(10)) return 5;
  if (error >= Math.sqrt(2)) return 2;
  return 1;
}

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 { tickSpec } from "./charts_ticks_tick_step.ts";  ← tickStep, another function of this group · built into the same file, even by a slim install

/**
 * Ticks at round values between start and stop, as d3.ticks: every multiple
 * of tickStep in [min, max], in the direction start to stop.
 *
 * Each tick is one exact operation on a whole number, i * step or i / divisor,
 * so the third tick of 0.1 steps is 0.3, not 0.30000000000000004 as adding
 * 0.1 three times gives.
 */
export function niceTicks(start: number, stop: number, count: number): readonly number[] {
  let [mul, div] = tickSpec(start, stop, count);
  if (start === stop) return [start + 0];
  const reverse = stop < start;
  const lo = reverse ? stop : start;
  const hi = reverse ? start : stop;
  let [i1, i2] = indexes(lo, hi, mul, div);
  if (i2 < i1 && count === 1) {
    // No multiple of the step for one tick falls inside; d3 retries with two.
    [mul, div] = tickSpec(start, stop, 2);
    [i1, i2] = indexes(lo, hi, mul, div);
  }
  const ticks: number[] = [];
  for (let i = i1; i <= i2; i++) ticks.push(div > 1 ? i / div : i * mul);
  if (reverse) ticks.reverse();
  return ticks.map((t) => t + 0);
}

function indexes(lo: number, hi: number, mul: number, div: number): [number, number] {
  if (div > 1) {
    let i1 = roundFloat(lo * div, 0);
    let i2 = roundFloat(hi * div, 0);
    if (i1 / div < lo) i1 += 1;
    if (i2 / div > hi) i2 -= 1;
    return [i1, i2];
  }
  let i1 = roundFloat(lo / mul, 0);
  let i2 = roundFloat(hi / mul, 0);
  if (i1 * mul < lo) i1 += 1;
  if (i2 * mul > hi) i2 -= 1;
  return [i1, i2];
}

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

import { type TimeTickInterval } from "./charts_ticks_types.ts";
import { epochDayFromIso } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { tickStep } from "./charts_ticks_tick_step.ts";  ← tickStep, another function of this group · built into the same file, even by a slim install

// d3-scale's calendar ladder (its time.js tickIntervals), from a day up, with
// the lengths in days it compares against: a month counts as 30, a quarter as
// 90, a year as 365.
const LADDER: [TimeTickInterval["interval"], number, number][] = [
  ["day", 1, 1],
  ["day", 2, 2],
  ["week", 1, 7],
  ["month", 1, 30],
  ["quarter", 1, 90],
  ["year", 1, 365],
];

/**
 * The calendar interval for about `count` ticks between two dates, as d3's
 * time scale picks it: the rung of the ladder nearest the ideal spacing (by
 * ratio), or whole years in steps of 1, 2 or 5 x 10^k beyond a year.
 */
export function timeTickInterval(start: string, stop: string, count: number): TimeTickInterval {
  if (!Number.isInteger(count) || count < 1) throw new Error(`count must be a whole number of at least 1, got ${count}`);
  const span = Math.abs(epochDayFromIso(stop) - epochDayFromIso(start));
  const target = span / count;
  let i = 0;
  while (i < LADDER.length && LADDER[i][2] <= target) i++;
  if (i === LADDER.length) {
    return { interval: "year", step: Math.max(1, tickStep(0, span / 365, count)) };
  }
  if (i === 0) return { interval: "day", step: 1 };
  const pick = target / LADDER[i - 1][2] < LADDER[i][2] / target ? LADDER[i - 1] : LADDER[i];
  return { interval: pick[0], step: pick[1] };
}

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

import { type TimeInterval } from "./charts_ticks_types.ts";
import { civilFromDays, daysFromCivil, epochDayFromIso, isoFromEpochDay } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune

// 1970-01-05, the first Monday on or after the epoch, as a day number.
const FIRST_MONDAY = 4;
const MAX_TICKS = 10000;

/**
 * Calendar boundaries between two dates, inclusive: every `step`-th day,
 * Monday, 1st of the month, quarter start or 1 January.
 *
 * The steps are anchored to the calendar, not to `start`, so panning an axis
 * does not make its ticks jump: days by day of the month ((day - 1) % step,
 * as d3's timeDay.every), weeks by whole weeks since 1970-01-05, months by
 * (month - 1) % step, quarters by quarter of the year, years by year % step.
 */
export function timeTicks(start: string, stop: string, interval: TimeInterval, step: number): readonly string[] {
  if (!Number.isInteger(step) || step < 1) throw new Error(`step must be a whole number of at least 1, got ${step}`);
  const a = epochDayFromIso(start);
  const b = epochDayFromIso(stop);
  const reverse = b < a;
  const lo = reverse ? b : a;
  const hi = reverse ? a : b;
  const days: number[] = [];
  const add = (day: number) => {
    if (days.length >= MAX_TICKS) throw new Error(`too many ticks: more than ${MAX_TICKS}; use a longer interval or step`);
    days.push(day);
  };

  if (interval === "day") {
    for (let d = lo; d <= hi; d++) {
      if ((civilFromDays(d).day - 1) % step === 0) add(d);
    }
  } else if (interval === "week") {
    let k = Math.ceil((lo - FIRST_MONDAY) / 7);
    k = Math.ceil(k / step) * step;
    for (let d = FIRST_MONDAY + 7 * k; d <= hi; d += 7 * step) add(d);
  } else if (interval === "month" || interval === "quarter" || interval === "year") {
    const months = interval === "month" ? step : interval === "quarter" ? 3 * step : 12;
    const first = civilFromDays(lo);
    let year = first.year;
    let month = first.month;
    for (;;) {
      const d = daysFromCivil(year, month, 1);
      if (d > hi) break;
      const onStep = interval === "year" ? month === 1 && year % step === 0 : (month - 1) % months === 0;
      if (d >= lo && onStep) add(d);
      month += 1;
      if (month > 12) {
        month = 1;
        year += 1;
      }
    }
  } else {
    throw new Error(`unknown time interval "${interval}"`);
  }
  const ticks = days.map(isoFromEpochDay);
  if (reverse) ticks.reverse();
  return ticks;
}