react-cheminfo 0.8.0 → 0.10.0

package/src/chart/core/chartAxisScale.ts

@@ -0,0 +1,249 @@
+import { formatDecimal } from '../../format/core/numbers.ts';
+
+const DEFAULT_COUNT = 5;
+const MAXIMUM_COUNT = 100;
+const MAXIMUM_TICKS = 1000;
+const NICE_PASSES = 8;
+const ZERO_WIDTH_SHARE = 0.05;
+const ZERO_WIDTH_FALLBACK = 1;
+const COMFORTABLE_LABEL = 6;
+const SUPERSCRIPT_DIGITS = '⁰¹²³⁴⁵⁶⁷⁸⁹';
+const STEP_10 = Math.sqrt(50);
+const STEP_5 = Math.sqrt(10);
+const STEP_2 = Math.SQRT2;
+
+/** A niced axis: its domain, its ticks, and the labels they are written with. */
+export interface ChartAxisScale {
+  /** The domain the ticks span, widened outward to whole steps when asked. */
+  readonly domain: readonly [number, number];
+  /** The tick values, ascending. */
+  readonly values: readonly number[];
+  /** The spacing: always 1, 2 or 5 times a power of ten. */
+  readonly step: number;
+  /** Decimals every label on this axis carries, so a column of them lines up. */
+  readonly decimals: number;
+  /** A power of ten lifted out of every label, or `0` when none was. */
+  readonly exponent: number;
+  /** One label per value, already written out. */
+  readonly labels: readonly string[];
+}
+
+/** How an axis is divided. */
+export interface ChartAxisScaleOptions {
+  /**
+   * Roughly how many ticks to aim for; the real count lands near it.
+   * @default 5
+   */
+  count?: number;
+  /**
+   * Whether to widen the domain outward to whole steps, so the axis ends on a
+   * labelled tick. Turn it off when the domain is already exact — a share that
+   * must end at 100%.
+   * @default true
+   */
+  nice?: boolean;
+}
+
+/**
+ * The ticks an axis over `min`..`max` should carry.
+ *
+ * The step follows the standard 1/2/5 progression. Below one, the algorithm
+ * divides by an integer rather than multiplying by a power of ten, which is
+ * what makes a tenth come out as exactly `0.1` instead of
+ * `0.30000000000000004` three ticks later. A domain far from unity has a
+ * common power of ten lifted into {@link ChartAxisScale.exponent} so the
+ * labels stay two or three characters wide and the axis title carries the
+ * factor; it is lifted only where that actually shortens them, so a million
+ * and a hundredth keeps its digits rather than trading them for longer ones.
+ * @param min - One end of the data range, in either order.
+ * @param max - The other end.
+ * @param options - See {@link ChartAxisScaleOptions}.
+ * @returns The niced axis. A range holding a value that is not finite falls
+ * back to 0..1, and a zero-width one is opened by 5% either side so that a
+ * constant column still draws an axis.
+ */
+export function chartAxisScale(
+  min: number,
+  max: number,
+  options: ChartAxisScaleOptions = {},
+): ChartAxisScale {
+  const { count = DEFAULT_COUNT, nice = true } = options;
+  const wanted = tickCount(count);
+  const opened = openDomain(min, max);
+  const domain = nice ? chartNiceDomain(opened[0], opened[1], wanted) : opened;
+  const [first, last, increment] = tickSpec(domain[0], domain[1], wanted);
+  const spacing = increment < 0 ? -1 / increment : increment;
+  const step = Number.isFinite(spacing) && spacing > 0 ? spacing : 0;
+  const values = step === 0 ? [] : tickValues(first, last, increment);
+  const exponent = liftedExponent(values, step);
+  const decimals = Math.max(0, exponent - decimalExponent(step));
+  const labels: string[] = [];
+  for (const value of values) {
+    labels.push(chartTickLabel(value, decimals, exponent));
+  }
+  return { domain, values, step, decimals, exponent, labels };
+}
+
+/**
+ * The domain rounded outward until both ends land on a whole tick step.
+ *
+ * It iterates, because widening changes the span, which can change the step,
+ * which can widen it again; it settles in one or two passes.
+ * @param min - One end, in either order.
+ * @param max - The other end.
+ * @param count - Roughly how many ticks the domain will carry. Defaults to `5`.
+ * @returns The widened domain, ascending.
+ */
+export function chartNiceDomain(
+  min: number,
+  max: number,
+  count = DEFAULT_COUNT,
+): [number, number] {
+  const wanted = tickCount(count);
+  let [start, stop] = openDomain(min, max);
+  let previous = 0;
+  for (let pass = 0; pass < NICE_PASSES; pass++) {
+    const [, , increment] = tickSpec(start, stop, wanted);
+    if (increment === previous || !Number.isFinite(increment)) break;
+    const low = wholeStep(start, increment, true);
+    const high = wholeStep(stop, increment, false);
+    if (!Number.isFinite(low) || !Number.isFinite(high)) break;
+    start = low;
+    stop = high;
+    previous = increment;
+  }
+  return [start, stop];
+}
+
+/**
+ * How many decimals a label needs so that every tick on one axis is written
+ * the same width.
+ *
+ * A step is always 1, 2 or 5 times a power of ten, so the answer is the step's
+ * decimal exponent and nothing more.
+ * @param step - The tick spacing.
+ * @returns The decimals; `0` for a step of one or more.
+ */
+export function chartTickDecimals(step: number): number {
+  return Math.max(0, -decimalExponent(step));
+}
+
+/**
+ * One tick written out, through `formatDecimal` so an axis reads like the rest
+ * of the family's numbers.
+ * @param value - The tick value.
+ * @param decimals - Decimals to keep, from {@link chartTickDecimals}.
+ * @param exponent - A power of ten already lifted into the axis title. Defaults to `0`.
+ * @returns The label. A negative zero is written as zero, which is what a
+ * reader expects to find at an origin.
+ */
+export function chartTickLabel(
+  value: number,
+  decimals: number,
+  exponent = 0,
+): string {
+  const lift = Number.isFinite(exponent) ? Math.trunc(exponent) : 0;
+  const scaled = lift === 0 ? value : value / 10 ** lift;
+  return formatDecimal(scaled === 0 ? 0 : scaled, decimals);
+}
+
+/**
+ * The factor an axis title carries when its labels were divided down, written
+ * as ` (×10⁻⁹)` with real superscript digits.
+ * @param exponent - The power of ten lifted out; `0` for none.
+ * @returns The suffix, or an empty string when there is nothing to say.
+ */
+export function chartExponentSuffix(exponent: number): string {
+  if (!Number.isFinite(exponent)) return '';
+  const whole = Math.trunc(exponent);
+  if (whole === 0) return '';
+  const sign = whole < 0 ? '⁻' : '';
+  const digits = Math.abs(whole)
+    .toString()
+    .replaceAll(/\d/gu, (digit) => SUPERSCRIPT_DIGITS.charAt(Number(digit)));
+  return ` (×10${sign}${digits})`;
+}
+
+type TickSpec = [first: number, last: number, increment: number];
+
+function tickSpec(start: number, stop: number, count: number): TickSpec {
+  const rawStep = (stop - start) / count;
+  const power = Math.floor(Math.log10(rawStep));
+  const error = rawStep / 10 ** power;
+  let factor = 1;
+  if (error >= STEP_2) factor = 2;
+  if (error >= STEP_5) factor = 5;
+  if (error >= STEP_10) factor = 10;
+  if (power < 0) {
+    const divisor = 10 ** -power / factor;
+    let first = Math.round(start * divisor);
+    let last = Math.round(stop * divisor);
+    if (first / divisor < start) first += 1;
+    if (last / divisor > stop) last -= 1;
+    return [first, last, -divisor];
+  }
+  const increment = 10 ** power * factor;
+  let first = Math.round(start / increment);
+  let last = Math.round(stop / increment);
+  if (first * increment < start) first += 1;
+  if (last * increment > stop) last -= 1;
+  return [first, last, increment];
+}
+
+function tickValues(first: number, last: number, increment: number): number[] {
+  const total = last - first + 1;
+  if (!(total > 0) || total > MAXIMUM_TICKS) return [];
+  const divisor = increment < 0 ? -increment : 0;
+  const values: number[] = [];
+  for (let index = 0; index < total; index++) {
+    const tick = first + index;
+    values.push(divisor > 0 ? tick / divisor : tick * increment);
+  }
+  return values;
+}
+
+function wholeStep(value: number, increment: number, down: boolean): number {
+  // A negative increment is a divisor; dividing turns the rounding round.
+  const flips = increment < 0;
+  const scaled = flips ? value * increment : value / increment;
+  const whole = down === flips ? Math.ceil(scaled) : Math.floor(scaled);
+  return flips ? whole / increment : whole * increment;
+}
+
+function liftedExponent(values: readonly number[], step: number): number {
+  const low = Math.abs(values[0] ?? 0);
+  const largest = Math.max(low, Math.abs(values.at(-1) ?? 0));
+  if (largest === 0 || !Number.isFinite(largest) || step <= 0) return 0;
+  const top = decimalExponent(largest);
+  const fine = decimalExponent(step);
+  const plain = labelWidth(Math.max(1, top + 1), -fine);
+  if (plain <= COMFORTABLE_LABEL) return 0;
+  return labelWidth(1, top - fine) < plain ? top : 0;
+}
+
+function labelWidth(digits: number, decimals: number): number {
+  return decimals > 0 ? digits + decimals + 1 : digits;
+}
+
+function decimalExponent(value: number): number {
+  const exponent = Number(Math.abs(value).toExponential().split('e', 2)[1]);
+  return Number.isFinite(exponent) ? exponent : 0;
+}
+
+function tickCount(count: number): number {
+  if (!Number.isFinite(count)) return DEFAULT_COUNT;
+  return Math.min(MAXIMUM_COUNT, Math.max(1, Math.floor(count)));
+}
+
+function openDomain(min: number, max: number): [number, number] {
+  const usable = Number.isFinite(min) && Number.isFinite(max);
+  let low = usable ? Math.min(min, max) : 0;
+  let high = usable ? Math.max(min, max) : 1;
+  if (low === high) {
+    const share = Math.abs(low) * ZERO_WIDTH_SHARE;
+    const padding = share > 0 ? share : ZERO_WIDTH_FALLBACK;
+    low -= padding;
+    high += padding;
+  }
+  return [low, high];
+}

package/src/chart/core/chartBand.ts

@@ -0,0 +1,82 @@
+const DEFAULT_PADDING = 0.2;
+const MAXIMUM_PADDING = 0.9;
+
+/** Evenly spaced slots for a categorical axis, held as four numbers. */
+export interface ChartBand {
+  /** The pixel the first slot starts at. */
+  readonly offset: number;
+  /** Pixels from one slot's start to the next. */
+  readonly step: number;
+  /** How wide a bar may be drawn: `step` less the gap. */
+  readonly bandWidth: number;
+  /** How many slots there are. */
+  readonly count: number;
+}
+
+/** How a band scale spaces its slots. */
+export interface ChartBandOptions {
+  /**
+   * Share of a slot left empty between neighbours, held between 0 and 0.9.
+   * @default 0.2
+   */
+  padding?: number;
+}
+
+/**
+ * `count` slots laid across `rangeMin`..`rangeMax`.
+ * @param count - How many categories the axis carries.
+ * @param rangeMin - The pixel the axis starts at.
+ * @param rangeMax - The pixel it ends at.
+ * @param options - See {@link ChartBandOptions}.
+ * @returns The scale. A count of zero gives a `step` of zero, which every
+ * reader below treats as an empty axis rather than dividing by it.
+ */
+export function chartBand(
+  count: number,
+  rangeMin: number,
+  rangeMax: number,
+  options: ChartBandOptions = {},
+): ChartBand {
+  const { padding = DEFAULT_PADDING } = options;
+  const slots = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  const start = Number.isFinite(rangeMin) ? rangeMin : 0;
+  const reach = Number.isFinite(rangeMax) ? rangeMax - start : 0;
+  if (slots === 0 || reach === 0) {
+    return { offset: start, step: 0, bandWidth: 0, count: slots };
+  }
+  const step = reach / slots;
+  const gap = Number.isFinite(padding)
+    ? Math.min(MAXIMUM_PADDING, Math.max(0, padding))
+    : DEFAULT_PADDING;
+  return {
+    offset: start,
+    step,
+    bandWidth: Math.abs(step) * (1 - gap),
+    count: slots,
+  };
+}
+
+/**
+ * The middle of one slot, which is where a point, a bar and a tick all sit.
+ * @param band - The scale.
+ * @param index - Which slot, from 0.
+ * @returns The pixel.
+ */
+export function chartBandCenter(band: ChartBand, index: number): number {
+  return band.offset + band.step * (index + 0.5);
+}
+
+/**
+ * Which slot a pixel is nearest.
+ *
+ * This is the whole of the tracking hit test on a categorical axis: no search,
+ * no allocation, one division.
+ * @param band - The scale.
+ * @param pixel - The pointer's position along the axis.
+ * @returns An index held inside `0..count - 1`, or `-1` when the axis is empty.
+ */
+export function chartBandIndexAt(band: ChartBand, pixel: number): number {
+  if (band.count <= 0 || band.step === 0 || !Number.isFinite(pixel)) return -1;
+  const slot = Math.floor((pixel - band.offset) / band.step);
+  return Math.min(band.count - 1, Math.max(0, slot));
+}

package/src/chart/core/chartBins.ts

@@ -0,0 +1,96 @@
+import type { ChartExtent } from './chartExtent.ts';
+import type { MatrixLike } from './matrix.ts';
+
+/** Counts over one shared set of bin edges, optionally split by series. */
+export interface ChartBins {
+  /** `bins + 1` edges, ascending. */
+  edges: Float64Array;
+  /** `series * bins` counts, laid out one series after another. */
+  counts: Uint32Array;
+  /** How many series the counts hold; `1` when nothing was split. */
+  series: number;
+  /** How many bins each series has. */
+  bins: number;
+  /** The largest count in any one bin of any one series, for scaling the draw. */
+  peak: number;
+}
+
+/**
+ * How one column is spread, split by group over one shared set of edges.
+ *
+ * `xHistogram` from `ml-spectra-processing` is the published helper for a
+ * single series, but it accumulates every value into one series and takes a
+ * flat array where we hold a matrix column; hence this one, which reads the
+ * matrix in place in a single pass.
+ * @param matrix - The matrix to read.
+ * @param column - Which column to bin.
+ * @param range - The edges' two ends, normally the column's shared axis domain.
+ * @param bins - How many bins to cut it into, at least one.
+ * @param groups - One group index per row, or `null` for a single series.
+ * @param series - How many groups there are; ignored when `groups` is `null`.
+ * @returns The counts. A row whose value is not finite, is outside `range`, or carries a group outside `0..series - 1` is left out rather than clamped into an end bin, because a clamped outlier reads as a real peak at the edge.
+ */
+export function chartBinCounts(
+  matrix: MatrixLike,
+  column: number,
+  range: ChartExtent,
+  bins: number,
+  groups: ArrayLike<number> | null,
+  series: number,
+): ChartBins {
+  const binCount = wholeAtLeastOne(bins);
+  const seriesCount = groups === null ? 1 : wholeAtLeastOne(series);
+  const min = Number.isFinite(range.min) ? range.min : 0;
+  const max =
+    Number.isFinite(range.max) && range.max > min ? range.max : min + 1;
+  const span = max - min;
+
+  const edges = new Float64Array(binCount + 1);
+  for (let index = 0; index < binCount; index++) {
+    edges[index] = min + (span * index) / binCount;
+  }
+  edges[binCount] = max;
+
+  const counts = new Uint32Array(seriesCount * binCount);
+  for (let row = 0; row < matrix.rows; row++) {
+    const value = matrix.get(row, column);
+    if (!Number.isFinite(value) || value < min || value > max) continue;
+
+    const group = groupOf(groups, row, seriesCount);
+    if (group < 0) continue;
+
+    // The value that is exactly `max` sits on the closing edge, which belongs
+    // to the last bin rather than to a bin past the end of the axis.
+    const bin = Math.min(
+      binCount - 1,
+      Math.floor(((value - min) / span) * binCount),
+    );
+    const slot = group * binCount + bin;
+    counts[slot] = (counts[slot] ?? 0) + 1;
+  }
+
+  let peak = 0;
+  for (const count of counts) {
+    if (count > peak) peak = count;
+  }
+
+  return { edges, counts, series: seriesCount, bins: binCount, peak };
+}
+
+function wholeAtLeastOne(count: number): number {
+  if (!Number.isFinite(count)) return 1;
+  return Math.max(1, Math.floor(count));
+}
+
+function groupOf(
+  groups: ArrayLike<number> | null,
+  row: number,
+  seriesCount: number,
+): number {
+  if (groups === null) return 0;
+  const raw = groups[row];
+  if (raw === undefined || !Number.isFinite(raw)) return -1;
+  const group = Math.trunc(raw);
+  if (group < 0 || group >= seriesCount) return -1;
+  return group;
+}

package/src/chart/core/chartExtent.ts

@@ -0,0 +1,203 @@
+import type { MatrixLike } from './matrix.ts';
+
+/** The two ends of a range. */
+export interface ChartExtent {
+  /** The smallest value. */
+  min: number;
+  /** The largest. */
+  max: number;
+}
+
+/** How far into a run of numbers to read, and what to widen. */
+export interface ChartValuesExtentOptions {
+  /**
+   * How many values to read, for a series longer than the slots it is drawn
+   * in.
+   * @default every value
+   */
+  limit?: number;
+  /**
+   * A range to widen rather than start afresh, so several runs can be covered
+   * without an array of ranges being built to merge.
+   * @default undefined — the range starts empty
+   */
+  into?: ChartExtent;
+}
+
+/** How a column's range is read and widened. */
+export interface ChartColumnExtentOptions {
+  /**
+   * Share of the span added at each end, so points do not touch the frame.
+   * @default 0.05
+   */
+  padding?: number;
+  /**
+   * Whether to stretch the range to include zero, which a bar chart must and a
+   * scatter need not.
+   * @default false
+   */
+  includeZero?: boolean;
+  /**
+   * Whether to make the range symmetric about zero, so the origin sits in the
+   * middle — what a scores or a loadings axis usually wants.
+   * @default false
+   */
+  symmetric?: boolean;
+  /**
+   * Which rows to read, for a range over one group only.
+   * @default undefined — every row is read
+   */
+  indices?: ArrayLike<number>;
+}
+
+/**
+ * The range of one column of a matrix.
+ *
+ * The matrix is read in place through `get`: no column is copied out, and a
+ * value that is not finite is skipped rather than poisoning the range with a
+ * `NaN`.
+ *
+ * The padding goes on before the stretch to zero, so a bar chart's baseline
+ * lands on zero exactly rather than a twentieth of a span below it, where the
+ * bars would float clear of the line they are measured from.
+ * @param matrix - The matrix to read.
+ * @param column - Which column.
+ * @param options - See {@link ChartColumnExtentOptions}.
+ * @returns The range, widened as asked. A column with no finite value at all gives `{ min: 0, max: 1 }`, which draws an honest empty axis.
+ */
+export function chartColumnExtent(
+  matrix: MatrixLike,
+  column: number,
+  options: ChartColumnExtentOptions = {},
+): ChartExtent {
+  const {
+    padding = DEFAULT_PADDING,
+    includeZero = false,
+    symmetric = false,
+    indices,
+  } = options;
+
+  const seen = readColumn(matrix, column, indices);
+  if (seen === null) return { min: 0, max: 1 };
+
+  const padded = chartPadExtent(seen, padding);
+  const grounded = includeZero
+    ? { min: Math.min(padded.min, 0), max: Math.max(padded.max, 0) }
+    : padded;
+  if (!symmetric) return grounded;
+
+  const reach = Math.max(Math.abs(grounded.min), Math.abs(grounded.max));
+  return { min: -reach, max: reach };
+}
+
+/**
+ * A range widened by a share of its span.
+ * @param extent - The range.
+ * @param padding - Share added at each end. Defaults to `0.05`.
+ * @returns The widened range, its two ends in order. A zero-width one is opened by 5% of its own value, or to -1..1 when that value is zero, because an axis whose ends are the same number has nowhere to put a tick.
+ */
+export function chartPadExtent(
+  extent: ChartExtent,
+  padding: number = DEFAULT_PADDING,
+): ChartExtent {
+  const { min, max } = extent;
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return { min: 0, max: 1 };
+
+  const low = Math.min(min, max);
+  const high = Math.max(min, max);
+  const span = high - low;
+  if (span === 0) {
+    const opening = low === 0 ? 1 : Math.abs(low) * DEFAULT_PADDING;
+    return { min: low - opening, max: high + opening };
+  }
+
+  const share = Number.isFinite(padding) && padding > 0 ? padding : 0;
+  const room = span * share;
+  return { min: low - room, max: high + room };
+}
+
+/**
+ * The range covering several — the shared scale a row or a column of a pair
+ * grid draws against.
+ * @param extents - The ranges to cover.
+ * @returns The covering range, or `{ min: 0, max: 1 }` when none was given.
+ */
+export function chartMergeExtents(
+  extents: readonly ChartExtent[],
+): ChartExtent {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const extent of extents) {
+    if (Number.isFinite(extent.min) && extent.min < min) min = extent.min;
+    if (Number.isFinite(extent.max) && extent.max > max) max = extent.max;
+  }
+  if (min > max) return { min: 0, max: 1 };
+  return { min, max };
+}
+
+/**
+ * A range covering nothing, which every scan starts from.
+ *
+ * `min` above `max` is what says it is empty, and it is deliberate: a range
+ * that started at zero would report a run of nothing as a run of zeroes, and
+ * an axis would be drawn around a value the data never held.
+ */
+export const EMPTY_EXTENT: ChartExtent = {
+  min: Number.POSITIVE_INFINITY,
+  max: Number.NEGATIVE_INFINITY,
+};
+
+/**
+ * The range of a run of numbers, skipping anything that is not finite.
+ *
+ * The one scan every chart starts from, and the reason it is here rather than
+ * written out per chart: a copy that forgets the finiteness guard poisons a
+ * whole axis with one `NaN`, and a copy that forgets `limit` reads a series
+ * past the slots it is drawn in.
+ *
+ * `ml-spectra-processing`'s `xMinMaxValues` answers the same question, but
+ * this package draws in a browser and does not depend on it; a shared six-line
+ * scan is cheaper than the package for the one thing needed from it.
+ * @param values - The numbers to read, in place — nothing is copied.
+ * @param options - See {@link ChartValuesExtentOptions}.
+ * @returns The range. A run with no finite value at all gives an empty range —
+ * `min` above `max` — which `chartPadExtent` and the callers here read as
+ * nothing to draw rather than as a range around zero.
+ */
+export function chartValuesExtent(
+  values: ArrayLike<number>,
+  options: ChartValuesExtentOptions = {},
+): ChartExtent {
+  const { limit = values.length, into = EMPTY_EXTENT } = options;
+  let { min, max } = into;
+  const count = Math.min(limit, values.length);
+  for (let index = 0; index < count; index++) {
+    const value = values[index];
+    if (value === undefined || !Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  return { min, max };
+}
+
+const DEFAULT_PADDING = 0.05;
+
+function readColumn(
+  matrix: MatrixLike,
+  column: number,
+  indices: ArrayLike<number> | undefined,
+): ChartExtent | null {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  const count = indices === undefined ? matrix.rows : indices.length;
+  for (let step = 0; step < count; step++) {
+    const row = indices === undefined ? step : indices[step];
+    if (row === undefined) continue;
+    const value = matrix.get(row, column);
+    if (!Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  if (min > max) return null;
+  return { min, max };
+}

package/src/chart/core/chartLabels.ts

@@ -0,0 +1,68 @@
+/** How an axis title is written. */
+export interface ChartAxisTitleOptions {
+  /**
+   * The share of the differences the axis accounts for, between 0 and 1 — a
+   * fraction, never a percentage. Left out for a method that publishes no such
+   * number, and then nothing is written after the name.
+   * @default undefined
+   */
+  share?: number;
+  /**
+   * Decimals in the percentage.
+   *
+   * One, because the share is a reading aid rather than a measurement: it is
+   * there so a reader can see that the seventh component carries 0.3 % and is
+   * not worth plotting. A second decimal claims a precision the decomposition
+   * does not have once the data has been resampled and scaled, and costs two
+   * more characters in a picker whose lines are already long.
+   * @default 1
+   */
+  digits?: number;
+}
+
+/**
+ * An axis title: `PC1 — 74.2 %`, or a bare `UMAP1` when the method publishes
+ * no share.
+ *
+ * The em dash is the package's own pattern for a name followed by a gloss —
+ * `RGB — mix the channels`, `MAX — Largest value` — so a component reads the
+ * same way here as everything else the reader has already met. Kept out of the
+ * frame so the frame draws whatever string it is handed, and so every method
+ * builds its titles the same way.
+ * @param name - What the axis is called, e.g. `PC1`.
+ * @param options - See {@link ChartAxisTitleOptions}.
+ * @returns The title.
+ */
+export function chartAxisTitle(
+  name: string,
+  options: ChartAxisTitleOptions = {},
+): string {
+  const { share, digits = DEFAULT_DIGITS } = options;
+  if (share === undefined || !Number.isFinite(share)) return name;
+  return `${name} — ${chartShare(share, digits)} %`;
+}
+
+/**
+ * A share written as a percentage, with no unit after it: `74.2`.
+ *
+ * Every figure that quotes a share goes through here, so an axis title and the
+ * sentence under the same chart cannot disagree about how precise the number
+ * is. A reader who meets `PC1 — 73.0 %` beside "accounts for 72.96%" has to
+ * work out whether those are two quantities or one, and they are one.
+ * @param share - The share, between 0 and 1 — a fraction, never a percentage.
+ * @param digits - Decimals in the result, defaulting to the one decimal every
+ * figure of the family writes.
+ * @returns The percentage, written out.
+ */
+export function chartShare(share: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(share)) return '';
+  return (share * 100).toFixed(readableDigits(digits));
+}
+
+const DEFAULT_DIGITS = 1;
+const MOST_DIGITS = 20;
+
+function readableDigits(digits: number): number {
+  if (!Number.isFinite(digits)) return DEFAULT_DIGITS;
+  return Math.min(MOST_DIGITS, Math.max(0, Math.floor(digits)));
+}