react-cheminfo 0.27.0 → 0.29.0

package/lib/panel/ui/useVirtualWindowRows.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Drawing only the rows the page is showing, for a list that scrolls with it.
+ *
+ * `useVirtualRows` measures a scroll region of its own, which is what a panel
+ * beside a chart has. A table filling a tab has none: it flows down the document
+ * and the browser window is what scrolls it, so giving the list its own
+ * `overflow` would grow a second scrollbar inside the first and cap the table at
+ * whatever height it was handed — a layout change made to serve the virtualiser
+ * rather than the reader.
+ */
+import type { VirtualRows } from './useVirtualRows.ts';
+/** The rows to draw, and what the list reports its own position through. */
+export interface VirtualWindowRows extends VirtualRows {
+    /**
+     * What the element holding the rows reports its position through, as its
+     * `ref`. Without it every offset is reckoned from the top of the document and
+     * the wrong rows are drawn, by however tall whatever sits above the list is.
+     */
+    measureList: (node: HTMLElement | null) => void;
+}
+/**
+ * Draw only the rows the page is showing, however long the list is.
+ *
+ * The rows are measured against the window, so the list only has to say how far
+ * down the page it begins — which is what the virtualiser calls its scroll
+ * margin, and what `measureList` reports.
+ *
+ * That position is read in a ref callback rather than in an effect, which is
+ * how `useChartSize` reads a box for the same reason: the node is the only
+ * thing the measurement needs, so it is taken the moment React has one and
+ * taken again whenever it hands over another. A filter that cuts a thousand
+ * rows to fifty changes how tall the list is and not where it starts, so there
+ * is nothing to remeasure when the count moves.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw, the spacers standing in for the others, and the
+ * ref the list reports its position through.
+ */
+export declare function useVirtualWindowRows(count: number, estimatedRowHeight: number): VirtualWindowRows;
+//# sourceMappingURL=useVirtualWindowRows.d.ts.map

package/lib/panel/ui/useVirtualWindowRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualWindowRows.d.ts","sourceRoot":"","sources":["../../../src/panel/ui/useVirtualWindowRows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD;;;;OAIG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,kBAAkB,EAAE,MAAM,GACzB,iBAAiB,CA2BnB"}

package/lib/panel/ui/useVirtualWindowRows.js

@@ -0,0 +1,65 @@
+/**
+ * Drawing only the rows the page is showing, for a list that scrolls with it.
+ *
+ * `useVirtualRows` measures a scroll region of its own, which is what a panel
+ * beside a chart has. A table filling a tab has none: it flows down the document
+ * and the browser window is what scrolls it, so giving the list its own
+ * `overflow` would grow a second scrollbar inside the first and cap the table at
+ * whatever height it was handed — a layout change made to serve the virtualiser
+ * rather than the reader.
+ */
+import { useWindowVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useState } from 'react';
+import { rowSpacers } from "../core/rowSpacers.js";
+/**
+ * Draw only the rows the page is showing, however long the list is.
+ *
+ * The rows are measured against the window, so the list only has to say how far
+ * down the page it begins — which is what the virtualiser calls its scroll
+ * margin, and what `measureList` reports.
+ *
+ * That position is read in a ref callback rather than in an effect, which is
+ * how `useChartSize` reads a box for the same reason: the node is the only
+ * thing the measurement needs, so it is taken the moment React has one and
+ * taken again whenever it hands over another. A filter that cuts a thousand
+ * rows to fifty changes how tall the list is and not where it starts, so there
+ * is nothing to remeasure when the count moves.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw, the spacers standing in for the others, and the
+ * ref the list reports its position through.
+ */
+export function useVirtualWindowRows(count, estimatedRowHeight) {
+    const [scrollMargin, setScrollMargin] = useState(0);
+    const measureList = useCallback((node) => {
+        if (node === null)
+            return;
+        setScrollMargin(node.getBoundingClientRect().top + window.scrollY);
+    }, []);
+    const virtualizer = useWindowVirtualizer({
+        count,
+        estimateSize: () => estimatedRowHeight,
+        overscan: OVERSCAN,
+        scrollMargin,
+    });
+    const drawn = virtualizer.getVirtualItems();
+    const indices = new Array(drawn.length);
+    for (let position = 0; position < drawn.length; position++) {
+        indices[position] = drawn[position].index;
+    }
+    return {
+        indices,
+        ...rowSpacers(drawn, virtualizer.getTotalSize()),
+        measure: virtualizer.measureElement,
+        measureList,
+    };
+}
+/**
+ * How many rows are drawn beyond each end of the window.
+ *
+ * The same reasoning as `useVirtualRows`, and the same number: enough that a
+ * wheel gesture never reaches the edge of what was drawn before the next render
+ * has run.
+ */
+const OVERSCAN = 12;
+//# sourceMappingURL=useVirtualWindowRows.js.map

package/lib/panel/ui/useVirtualWindowRows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualWindowRows.js","sourceRoot":"","sources":["../../../src/panel/ui/useVirtualWindowRows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAcnD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAa,EACb,kBAA0B;IAE1B,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEpD,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,IAAwB,EAAE,EAAE;QAC3D,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAC1B,eAAe,CAAC,IAAI,CAAC,qBAAqB,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACrE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,WAAW,GAAG,oBAAoB,CAAC;QACvC,KAAK;QACL,YAAY,EAAE,GAAG,EAAE,CAAC,kBAAkB;QACtC,QAAQ,EAAE,QAAQ;QAClB,YAAY;KACb,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,WAAW,CAAC,eAAe,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAI,KAAK,CAAS,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,IAAI,QAAQ,GAAG,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC;QAC3D,OAAO,CAAC,QAAQ,CAAC,GAAI,KAAK,CAAC,QAAQ,CAAuB,CAAC,KAAK,CAAC;IACnE,CAAC;IAED,OAAO;QACL,OAAO;QACP,GAAG,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC;QAChD,OAAO,EAAE,WAAW,CAAC,cAAc;QACnC,WAAW;KACZ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,QAAQ,GAAG,EAAE,CAAC"}

package/lib/ui.d.ts

@@ -17,6 +17,7 @@ export * from './hooks/ui/index.ts';
 export * from './i18n/ui/index.ts';
 export * from './language/ui/index.ts';
 export * from './overlay/ui/index.ts';
+export * from './panel/ui/index.ts';
 export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';

package/lib/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/lib/ui.js

@@ -17,6 +17,7 @@ export * from "./hooks/ui/index.js";
 export * from "./i18n/ui/index.js";
 export * from "./language/ui/index.js";
 export * from "./overlay/ui/index.js";
+export * from "./panel/ui/index.js";
 export * from "./parallel/ui/index.js";
 export * from "./pedagogy/ui/index.js";
 export * from "./periodic/ui/index.js";

package/lib/ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",
@@ -18,6 +18,7 @@
     "./build-info": "./lib/build-info.js",
     "./conformers": "./lib/conformers.js",
     "./core": "./lib/core.js",
+    "./ir": "./lib/ir.js",
     "./molecule3d": "./lib/molecule3d.js",
     "./orbital": "./lib/orbital.js",
     "./slides": "./lib/slides.js",
@@ -61,9 +62,14 @@
   },
   "dependencies": {
     "@formatjs/icu-messageformat-parser": "^3.5.20",
+    "@tanstack/react-virtual": "^3.14.13",
     "cheminfo-font": "^1.28.0",
+    "cheminfo-types": "^1.16.0",
+    "convert-to-jcamp": "^7.0.1",
     "intl-messageformat": "^11.2.15",
+    "ir-spectrum": "^4.2.0",
     "leven": "^4.1.0",
+    "ml-spectra-processing": "^14.35.1",
     "openchemlib": "^9.25.0",
     "react-markdown": "^10.1.0",
     "rehype-raw": "^7.0.0",
@@ -85,6 +91,7 @@
     "eslint": "^9.39.5",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
+    "jsdom": "^30.1.1",
     "ml-dataset-iris": "^1.2.1",
     "ml-pca": "^4.1.1",
     "ml-signal-processing": "^2.2.2",

package/src/chart/core/axisLabels.ts

@@ -0,0 +1,117 @@
+/**
+ * How a number is written wherever a chart writes one.
+ *
+ * The axis decides, not the number: the precision comes from the tick step, and
+ * the notation from the largest tick, so every label on one axis is written the
+ * same way and a reader can run an eye down a column of them. `chartAxisScale`
+ * works both out; this is where they turn into text.
+ *
+ * It is a second way of writing the labels `chartAxisScale` already carries,
+ * and it exists because the two answer different questions. A figure lifts a
+ * common power of ten into its axis title and writes short labels under it — a
+ * chart whose axis title is fixed by the measurement cannot, so a spectrum
+ * writes the magnitude into each label instead.
+ */
+
+import type { ChartAxisScale } from './chartAxisScale.ts';
+
+/**
+ * Write a number the way an axis label or a readout wants it.
+ *
+ * The decimals come from the axis, so every label on it is written to the same
+ * precision — but a tick that happens to land on a round number then reads
+ * `500.0000` where `500` was meant, and half its width is zeros carrying
+ * nothing. They are trimmed off the end only, never out of the middle, so
+ * `500.0002` keeps every digit it needs.
+ *
+ * `toFixed` also writes `-0` for anything that rounds to zero from below, which
+ * is never what an axis means and is jarring on the one tick a chemist looks at
+ * most.
+ * @param value - The number to write.
+ * @param decimals - How many decimals to write it to, as `niceTicks` derived.
+ * @returns The label.
+ */
+export function formatNumber(value: number, decimals: number): string {
+  const text = value.toFixed(Math.min(20, Math.max(0, Math.floor(decimals))));
+  const trimmed = text.includes('.') ? text.replace(/\.?0+$/, '') : text;
+  return trimmed === '-0' ? '0' : trimmed;
+}
+
+/**
+ * The magnitude above which a number is quicker read as a power of ten.
+ *
+ * An ion count is quoted in whatever the instrument counted in, so an intensity
+ * axis written out in full reads `200000000` — nine digits a reader has to group
+ * into threes before knowing which power of ten they are looking at, and wide
+ * enough to run into the axis title printed beside them. Above this the same
+ * tick is written `2e+8`, which says the magnitude first and in four characters.
+ *
+ * A hundred thousand rather than a million because that is where a number stops
+ * being read at a glance, and because it is the threshold every intensity in the
+ * mass side is already written against — a colourbar and an axis that disagreed
+ * about how one count is spelled would read as two measurements.
+ */
+export const SCIENTIFIC_ABOVE = 1e5;
+
+/**
+ * The magnitude below which the digits that mean anything are all behind zeros.
+ *
+ * The mirror of `SCIENTIFIC_ABOVE`: `0.00002` is four characters of nothing
+ * followed by the one digit that was measured.
+ */
+export const SCIENTIFIC_BELOW = 1e-4;
+
+/**
+ * Write a number as a mantissa and a power of ten.
+ *
+ * With no precision asked for, the mantissa keeps only the digits it needs — a
+ * tick at a hundred and fifty million is `1.5e+8` and the one above it `2e+8`,
+ * rather than both being padded to the same width with zeros that say nothing.
+ * The value is rounded to a few significant digits first, because a tick is
+ * reached by multiplying a step by an index and `3 * 0.1` is `0.30000000000000004`
+ * — which the shortest form would write out in full, every digit of it noise.
+ * @param value - The number to write.
+ * @param digits - How many decimals the mantissa carries. Left out, it carries
+ * as few as tell this number from its neighbours.
+ * @returns The number in scientific notation, or `0` for zero, which has no
+ * exponent and is written the same way on any axis.
+ */
+export function formatScientific(value: number, digits?: number): string {
+  if (value === 0) return '0';
+  if (digits === undefined) {
+    return Number(value.toPrecision(SCIENTIFIC_DIGITS)).toExponential();
+  }
+  return value.toExponential(Math.min(100, Math.max(0, Math.floor(digits))));
+}
+
+/**
+ * How one axis writes every one of its labels.
+ *
+ * The notation is chosen once, from the largest tick on the axis, and then used
+ * for all of them — including the small ones and the zero. An axis is read by
+ * running an eye along it, and one whose labels changed notation partway would
+ * have to be read a label at a time instead.
+ * @param axis - The axis, as `chartAxisScale` divided it.
+ * @returns A writer for every label on that axis.
+ */
+export function axisLabeller(axis: ChartAxisScale): (value: number) => string {
+  const { values, decimals } = axis;
+  let largest = 0;
+  for (const tick of values) {
+    const magnitude = Math.abs(tick);
+    if (magnitude > largest) largest = magnitude;
+  }
+  const scientific =
+    largest >= SCIENTIFIC_ABOVE || (largest > 0 && largest < SCIENTIFIC_BELOW);
+  return scientific
+    ? (value) => formatScientific(value)
+    : (value) => formatNumber(value, decimals);
+}
+
+/**
+ * How many significant digits survive the rounding that sheds floating noise.
+ *
+ * A tick is 1, 2 or 5 times a power of ten times an index, so two digits carry
+ * every one of them and six is room to spare for a readout written this way.
+ */
+const SCIENTIFIC_DIGITS = 6;

package/src/chart/core/boxLayout.ts

@@ -0,0 +1,126 @@
+/**
+ * Keeping the labels above the peaks apart from one another.
+ *
+ * An annotated spectrum wants a box over every peak it explains, and an
+ * isotopologue cluster puts four of them within a few pixels. Sliding them
+ * apart is most of the job, and the leader line back to the stick is what says
+ * which peak a box belongs to — so a box a little out of place is still
+ * readable.
+ *
+ * A box slid *far* out of place is not. Spacing a crowd out marches the last of
+ * them across the whole plot, where it comes to rest over peaks it says nothing
+ * about, with a leader long enough to be read as pointing at one of them. Those
+ * are dropped, and only those: a mark still sits on every annotated peak, so
+ * the fragment is not one the chemist concludes the spectrum lacks — it is one
+ * whose picture is a zoom away.
+ */
+
+import type { NumberArray } from 'cheminfo-types';
+
+/**
+ * Slide overlapping boxes apart, keeping every one of them inside the plot.
+ *
+ * Two sweeps, and the order of the clamps is the whole behaviour. The first
+ * sweep runs left to right and pushes each box far enough past its neighbour to
+ * clear it, which piles the crowding up against the right edge; the second runs
+ * back the other way, pulling that pile inside the right bound and spacing it
+ * out leftwards again.
+ *
+ * The left bound is then applied last, after the spacing, and so beats it. A
+ * cluster too wide for the room it is in therefore ends with its leftmost boxes
+ * overlapping rather than with one of them hanging off the plot — an overlap is
+ * two labels a reader can still pick apart with the leader lines, while a box
+ * outside the plot is clipped away and reads as an annotation that was never
+ * made.
+ * @param centres - Where each box would like to be centred, in pixels; any
+ * order, and the result comes back in that same order.
+ * @param bounds - `[from, to]` in pixels that no box may extend beyond.
+ * @param width - How wide every box is.
+ * @param gap - The clear space wanted between two neighbouring boxes.
+ * @param maximumDrift - How far a box may be slid from where it wanted to be
+ * before it is dropped instead, in pixels. Defaults to two whole box steps.
+ * @returns The centre each box was actually given, `NaN` for one that was slid
+ * too far and dropped.
+ */
+export function layoutAnnotationBoxes(
+  centres: NumberArray,
+  bounds: readonly [number, number],
+  width: number,
+  gap: number,
+  maximumDrift = (width + gap) * MAXIMUM_DRIFT_STEPS,
+): Float64Array {
+  const count = centres.length;
+  const placed = new Float64Array(count);
+  if (count === 0) return placed;
+
+  const half = width / 2;
+  const minimumCentre = bounds[0] + half;
+  const maximumCentre = bounds[1] - half;
+  const step = width + gap;
+  const order = ascendingOrder(centres);
+
+  let previous = Number.NEGATIVE_INFINITY;
+  for (let position = 0; position < count; position++) {
+    const index = order[position] as number;
+    let centre = Math.min(
+      Math.max(centres[index] as number, minimumCentre),
+      maximumCentre,
+    );
+    if (centre < previous + step) centre = previous + step;
+    placed[index] = centre;
+    previous = centre;
+  }
+
+  let next = Number.POSITIVE_INFINITY;
+  for (let position = count - 1; position >= 0; position--) {
+    const index = order[position] as number;
+    let centre = placed[index] as number;
+    if (centre > maximumCentre) centre = maximumCentre;
+    if (centre > next - step) centre = next - step;
+    if (centre < minimumCentre) centre = minimumCentre;
+    placed[index] = centre;
+    next = centre;
+  }
+
+  // A picture that has been slid too far from the peak it explains is worse
+  // than no picture: it hangs over a peak it says nothing about, and the leader
+  // back to its own is long enough to be read as pointing at something else.
+  // Those are dropped rather than drawn, and the mark on the peak still says
+  // the annotation is there.
+  for (let index = 0; index < count; index++) {
+    const wanted = centres[index] as number;
+    if (Math.abs((placed[index] as number) - wanted) > maximumDrift) {
+      placed[index] = Number.NaN;
+    }
+  }
+  return placed;
+}
+
+/**
+ * How far a picture may be slid from its peak, counted in whole box steps.
+ *
+ * Two: a box may be pushed past two neighbours and still be read as belonging
+ * to the peak under it, which is what a cluster of three peaks needs. Past that
+ * the leader is longer than the box is wide and reaches across other peaks, so
+ * the picture reads as answering for one of them instead.
+ */
+export const MAXIMUM_DRIFT_STEPS = 2;
+
+/**
+ * The indices of the boxes, ordered by where they want to be.
+ *
+ * The sweeps only make sense left to right, and the caller's order is whatever
+ * the annotations came in — usually by mass, but a second producer's marks are
+ * appended rather than merged.
+ * @param centres - Where each box would like to be centred.
+ * @returns The indices, ascending by centre.
+ */
+function ascendingOrder(centres: NumberArray): Uint32Array {
+  const order = new Uint32Array(centres.length);
+  for (let index = 0; index < centres.length; index++) {
+    order[index] = index;
+  }
+  return order.toSorted(
+    (first, second) => (centres[first] as number) - (centres[second] as number),
+  );
+}

package/src/chart/core/chartAxisScale.ts

@@ -12,6 +12,15 @@ const COMFORTABLE_LABEL = 6;
 const STEP_10 = Math.sqrt(50);
 const STEP_5 = Math.sqrt(10);
 const STEP_2 = Math.SQRT2;
+/**
+ * How far a fraction may sit above 1, 2 or 5 and still count as being on it.
+ *
+ * `span / count` is computed in floating point, so a window that ought to give
+ * a step of exactly one lands a hair above it — `1.0000000000000002` — and an
+ * exact comparison would take the next step up and halve the number of ticks
+ * for no visible reason.
+ */
+const STEP_EPSILON = 1e-9;
 
 /** A niced axis: its domain, its ticks, and the labels they are written with. */
 export interface ChartAxisScale {
@@ -29,6 +38,22 @@ export interface ChartAxisScale {
   readonly labels: readonly string[];
 }
 
+/**
+ * How the step is chosen when an even division lands between two nice ones.
+ *
+ * - `nearest` — take whichever of 1, 2 or 5 the division is closest to, which
+ *   puts the tick count near what was asked for from either side.
+ * - `atMost` — always take the larger, so the count asked for is a budget the
+ *   axis never exceeds.
+ *
+ * The difference is not cosmetic. A figure asking for about five ticks wants
+ * them spaced as evenly as the numbers allow, and one either way costs it
+ * nothing. An axis in a two-hundred-pixel panel has worked its count out from
+ * the room it has and the width of a label, so one tick more than it asked for
+ * is two labels touching.
+ */
+export type ChartAxisStep = 'nearest' | 'atMost';
+
 /** How an axis is divided. */
 export interface ChartAxisScaleOptions {
   /**
@@ -39,10 +64,15 @@ export interface ChartAxisScaleOptions {
   /**
    * 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%.
+   * must end at 100%, or a window a reader dragged out for themselves.
    * @default true
    */
   nice?: boolean;
+  /**
+   * How the step is chosen. See {@link ChartAxisStep}.
+   * @default 'nearest'
+   */
+  step?: ChartAxisStep;
 }
 
 /**
@@ -68,11 +98,34 @@ export function chartAxisScale(
   max: number,
   options: ChartAxisScaleOptions = {},
 ): ChartAxisScale {
-  const { count = DEFAULT_COUNT, nice = true } = options;
+  const { count = DEFAULT_COUNT, nice = true, step: rounding } = options;
   const wanted = tickCount(count);
+  // A window of one point is not a window: there is no step to read a
+  // precision off, so the single label is written at the precision its own
+  // magnitude asks for. Only when the domain is taken as given — a domain that
+  // is to be niced is opened instead, so that a constant column still draws an
+  // axis to stand on.
+  if (!nice && min === max && Number.isFinite(min)) {
+    const decimals = chartTickDecimals(Math.abs(min));
+    return {
+      domain: [min, min],
+      values: [min],
+      step: 0,
+      decimals,
+      exponent: 0,
+      labels: [chartTickLabel(min, decimals)],
+    };
+  }
   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 domain = nice
+    ? chartNiceDomain(opened[0], opened[1], wanted, rounding)
+    : opened;
+  const [first, last, increment] = tickSpec(
+    domain[0],
+    domain[1],
+    wanted,
+    rounding,
+  );
   const spacing = increment < 0 ? -1 / increment : increment;
   const step = Number.isFinite(spacing) && spacing > 0 ? spacing : 0;
   const values = step === 0 ? [] : tickValues(first, last, increment);
@@ -93,18 +146,20 @@ export function chartAxisScale(
  * @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`.
+ * @param rounding - How the step is chosen. See {@link ChartAxisStep}.
  * @returns The widened domain, ascending.
  */
 export function chartNiceDomain(
   min: number,
   max: number,
   count = DEFAULT_COUNT,
+  rounding: ChartAxisStep = 'nearest',
 ): [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);
+    const [, , increment] = tickSpec(start, stop, wanted, rounding);
     if (increment === previous || !Number.isFinite(increment)) break;
     const low = wholeStep(start, increment, true);
     const high = wholeStep(stop, increment, false);
@@ -163,14 +218,41 @@ export function chartExponentSuffix(exponent: number): string {
 
 type TickSpec = [first: number, last: number, increment: number];
 
-function tickSpec(start: number, stop: number, count: number): TickSpec {
+/**
+ * The nice factor a division is closest to.
+ * @param error - The division's mantissa, between 1 and 10.
+ * @returns 1, 2, 5 or 10.
+ */
+function stepNearest(error: number): number {
+  if (error >= STEP_10) return 10;
+  if (error >= STEP_5) return 5;
+  if (error >= STEP_2) return 2;
+  return 1;
+}
+
+/**
+ * The smallest nice factor at or above a division, so the ticks are never
+ * closer together than asked for.
+ * @param error - The division's mantissa, between 1 and 10.
+ * @returns 1, 2, 5 or 10.
+ */
+function stepAtMost(error: number): number {
+  if (error <= 1 + STEP_EPSILON) return 1;
+  if (error <= 2 + STEP_EPSILON) return 2;
+  if (error <= 5 + STEP_EPSILON) return 5;
+  return 10;
+}
+
+function tickSpec(
+  start: number,
+  stop: number,
+  count: number,
+  rounding: ChartAxisStep = 'nearest',
+): 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;
+  const factor = rounding === 'atMost' ? stepAtMost(error) : stepNearest(error);
   if (power < 0) {
     const divisor = 10 ** -power / factor;
     let first = Math.round(start * divisor);