charts.shape

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

import { formatDecimal } from "./text_format_decimal.ts";  ← from text.format-decimal ^1.0.0 · built alongside by fune
import type { Point } from "./charts_shape_types.ts";

/**
 * A polyline as SVG path data, in d3.line's format ("M10,20L30,40").
 * A null y ends the current subpath; a run of one point is "Mx,yZ", as d3
 * closes it so a round line cap still shows a dot.
 */
export function linePath(points: readonly Point[]): string {
  let out = "";
  for (const run of pointRuns(points)) {
    run.forEach(([x, y], i) => {
      out += (i === 0 ? "M" : "L") + svgPair(x, y);
    });
    if (run.length === 1) out += "Z";
  }
  return out;
}

// Shared with the other path functions of this group.

/** "x,y" with each number rounded to 2 places, trailing zeros dropped. */
export function svgPair(x: number, y: number): string {
  return formatDecimal(x, 2, true, "") + "," + formatDecimal(y, 2, true, "");
}

/** The unbroken runs of a series: a point with a null y separates them. */
export function pointRuns(points: readonly Point[]): [number, number][][] {
  const runs: [number, number][][] = [];
  let current: [number, number][] = [];
  for (const p of points) {
    if (p.y === null || p.y === undefined) {
      if (current.length > 0) runs.push(current);
      current = [];
    } else {
      current.push([p.x, p.y]);
    }
  }
  if (current.length > 0) runs.push(current);
  return runs;
}

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

import { svgPair } from "./charts_shape_line_path.ts";  ← linePath, another function of this group · built into the same file, even by a slim install
import type { AreaPoint } from "./charts_shape_types.ts";

/**
 * A filled area as SVG path data, in d3.area's format: along the top edge
 * (y1) left to right, back along the baseline (y0) right to left, closed.
 * A null y1 ends one area and starts the next.
 */
export function areaPath(points: readonly AreaPoint[]): string {
  let out = "";
  let run: AreaPoint[] = [];
  const flush = () => {
    if (run.length === 0) return;
    run.forEach((p, i) => {
      out += (i === 0 ? "M" : "L") + svgPair(p.x, p.y1 as number);
    });
    for (let i = run.length - 1; i >= 0; i--) out += "L" + svgPair(run[i].x, run[i].y0);
    out += "Z";
    run = [];
  };
  for (const p of points) {
    if (p.y1 === null || p.y1 === undefined) flush();
    else run.push(p);
  }
  flush();
  return out;
}

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

import { pointRuns, svgPair } from "./charts_shape_line_path.ts";  ← linePath, another function of this group · built into the same file, even by a slim install
import type { Point, StepPosition } from "./charts_shape_types.ts";

/**
 * A step line as SVG path data, as d3.curveStepBefore, d3.curveStep and
 * d3.curveStepAfter draw it: horizontal then vertical moves only.
 */
export function stepPath(points: readonly Point[], position: StepPosition): string {
  let t: number;
  if (position === "before") t = 0;
  else if (position === "middle") t = 0.5;
  else if (position === "after") t = 1;
  else throw new RangeError(`step position must be before, middle or after, received ${position}`);
  let out = "";
  for (const run of pointRuns(points)) {
    out += "M" + svgPair(run[0][0], run[0][1]);
    for (let i = 1; i < run.length; i++) {
      const [px, py] = run[i - 1];
      const [x, y] = run[i];
      if (t <= 0) {
        out += "L" + svgPair(px, y) + "L" + svgPair(x, y);
      } else {
        // d3's own expression, so the midpoint rounds as d3's does.
        const x1 = px * (1 - t) + x * t;
        out += "L" + svgPair(x1, py) + "L" + svgPair(x1, y);
      }
    }
    if (t > 0 && t < 1 && run.length >= 2) {
      const [lx, ly] = run[run.length - 1];
      out += "L" + svgPair(lx, ly);
    }
    if (run.length === 1) out += "Z";
  }
  return out;
}

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

import { pointRuns, svgPair } from "./charts_shape_line_path.ts";  ← linePath, another function of this group · built into the same file, even by a slim install
import type { Point } from "./charts_shape_types.ts";

function sign(x: number): number {
  return x < 0 ? -1 : 1;
}

// Fritsch–Carlson: the tangent at the middle of three points, limited so the
// curve cannot overshoot either neighbouring value. Written as d3's slope3.
function slope3(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number): number {
  const h0 = x1 - x0;
  const h1 = x2 - x1;
  const s0 = (y1 - y0) / h0;
  const s1 = (y2 - y1) / h1;
  const p = (s0 * h1 + s1 * h0) / (h0 + h1);
  return (sign(s0) + sign(s1)) * Math.min(Math.abs(s0), Math.abs(s1), 0.5 * Math.abs(p)) || 0;
}

// The tangent at an end, from the one-sided slope and the known tangent (d3's slope2).
function slope2(x0: number, y0: number, x1: number, y1: number, t: number): number {
  return (3 * (y1 - y0) / (x1 - x0) - t) / 2;
}

function bezier(x0: number, y0: number, x1: number, y1: number, t0: number, t1: number): string {
  const dx = (x1 - x0) / 3;
  return "C" + svgPair(x0 + dx, y0 + dx * t0) + "," + svgPair(x1 - dx, y1 - dx * t1) + "," + svgPair(x1, y1);
}

/**
 * A smooth line through the points that stays monotone wherever the data is,
 * so it never invents a peak or dip between samples: d3.curveMonotoneX,
 * Hermite segments with Fritsch–Carlson tangents, as cubic Béziers.
 */
export function monotoneCurve(points: readonly Point[]): string {
  let out = "";
  for (const run of pointRuns(points)) {
    for (let i = 1; i < run.length; i++) {
      if (!(run[i][0] > run[i - 1][0])) {
        throw new RangeError(`monotone curve needs x strictly increasing, but ${run[i][0]} follows ${run[i - 1][0]}`);
      }
    }
    out += "M" + svgPair(run[0][0], run[0][1]);
    const n = run.length;
    if (n === 1) {
      out += "Z";
      continue;
    }
    if (n === 2) {
      out += "L" + svgPair(run[1][0], run[1][1]);
      continue;
    }
    // Tangent at each interior point, then the ends from their neighbours.
    let t0 = 0;
    for (let i = 2; i < n; i++) {
      const [ax, ay] = run[i - 2];
      const [bx, by] = run[i - 1];
      const [cx, cy] = run[i];
      const t1 = slope3(ax, ay, bx, by, cx, cy);
      const start = i === 2 ? slope2(ax, ay, bx, by, t1) : t0;
      out += bezier(ax, ay, bx, by, start, t1);
      t0 = t1;
    }
    const [ax, ay] = run[n - 2];
    const [bx, by] = run[n - 1];
    out += bezier(ax, ay, bx, by, t0, slope2(ax, ay, bx, by, t0));
  }
  return out;
}

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 { BarSpec, Orientation, Rect } from "./charts_shape_types.ts";

/**
 * Rectangles for bars. The edges are rounded to 2 places and the sizes are the
 * differences of the rounded edges, so bars that share an edge share it
 * exactly, and the height of a negative bar is still positive.
 */
export function barRects(bars: readonly BarSpec[], orientation: Orientation): readonly Rect[] {
  if (orientation !== "vertical" && orientation !== "horizontal") {
    throw new RangeError(`orientation must be vertical or horizontal, received ${orientation}`);
  }
  return bars.map((bar) => {
    if (!(bar.thickness >= 0)) throw new RangeError(`bar thickness must not be negative, received ${bar.thickness}`);
    const a0 = roundFloat(bar.band, 2);
    const a1 = roundFloat(bar.band + bar.thickness, 2);
    const v0 = roundFloat(Math.min(bar.base, bar.value), 2);
    const v1 = roundFloat(Math.max(bar.base, bar.value), 2);
    const across = roundFloat(a1 - a0, 2);
    const along = roundFloat(v1 - v0, 2);
    return orientation === "vertical"
      ? { x: a0, y: v0, width: across, height: along }
      : { x: v0, y: a0, width: along, height: across };
  });
}

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

import { sinCos } from "./math_sin_cos.ts";  ← from math.sin-cos ^1.0.0 · built alongside by fune
import { svgPair } from "./charts_shape_line_path.ts";  ← linePath, another function of this group · built into the same file, even by a slim install
import type { Arc } from "./charts_shape_types.ts";

const PI = 3.141592653589793;
const TAU = 6.283185307179586;

function arcPoint(arc: Arc, r: number, angle: number): string {
  const sc = sinCos(angle);
  return svgPair(arc.cx + r * sc.sin, arc.cy - r * sc.cos);
}

function arcTo(arc: Arc, r: number, large: number, sweep: number, angle: number): string {
  const radius = svgPair(r, r);
  return "A" + radius + ",0," + large + "," + sweep + "," + arcPoint(arc, r, angle);
}

/**
 * An annular sector as SVG path data. Angles are radians from 12 o'clock,
 * clockwise, as in d3.arc. See the README for the exact path format.
 */
export function arcPath(arc: Arc): string {
  const { innerRadius: ri, outerRadius: ro, startAngle: a0, endAngle: a1 } = arc;
  if (!(ri >= 0) || !(ro >= ri)) {
    throw new RangeError(`arc radii must satisfy 0 <= innerRadius <= outerRadius, received ${ri} and ${ro}`);
  }
  const span = a1 - a0;
  if (span === 0 || ro === 0) return "";
  const sweep = span > 0 ? 1 : 0;
  const back = 1 - sweep;
  const dir = span > 0 ? 1 : -1;
  if (Math.abs(span) >= TAU) {
    // One SVG arc cannot start and end at the same point, so a full turn is
    // two half turns; the hole is drawn the other way round so it stays empty.
    const half = a0 + dir * PI;
    let out = "M" + arcPoint(arc, ro, a0) + arcTo(arc, ro, 1, sweep, half) + arcTo(arc, ro, 1, sweep, a0) + "Z";
    if (ri > 0) {
      const back = a0 - dir * PI;
      out += "M" + arcPoint(arc, ri, a0) + arcTo(arc, ri, 1, 1 - sweep, back) + arcTo(arc, ri, 1, 1 - sweep, a0) + "Z";
    }
    return out;
  }
  const large = Math.abs(span) > PI ? 1 : 0;
  let out = "M" + arcPoint(arc, ro, a0) + arcTo(arc, ro, large, sweep, a1);
  if (ri > 0) out += "L" + arcPoint(arc, ri, a1) + arcTo(arc, ri, large, back, a0);
  else out += "L" + svgPair(arc.cx, arc.cy);
  return out + "Z";
}

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 { PieSlice } from "./charts_shape_types.ts";

const TAU = 6.283185307179586;

/**
 * Start and end angles of pie slices in input order: d3.pie with sort(null),
 * then half the pad trimmed from each side, so the angles can go straight
 * into arcPath and neighbouring slices show a gap of padAngle.
 */
export function pieAngles(values: readonly number[], startAngle: number, endAngle: number, padAngle: number): readonly PieSlice[] {
  if (!(padAngle >= 0)) throw new RangeError(`padAngle must not be negative, received ${padAngle}`);
  const n = values.length;
  let sum = 0;
  for (const v of values) {
    if (!(v >= 0)) throw new RangeError(`pie values must be zero or more, received ${v}`);
    sum += v;
  }
  let a0 = startAngle;
  const da = Math.min(TAU, Math.max(-TAU, endAngle - a0));
  const p = n > 0 ? Math.min(Math.abs(da) / n, padAngle) : 0;
  const pa = p * (da < 0 ? -1 : 1);
  const k = sum > 0 ? (da - n * pa) / sum : 0;
  const out: PieSlice[] = [];
  for (const v of values) {
    const a1 = a0 + (v > 0 ? v * k : 0) + pa;
    out.push({ value: v, startAngle: roundFloat(a0 + pa / 2, 6), endAngle: roundFloat(a1 - pa / 2, 6) });
    a0 = a1;
  }
  return out;
}