react-cheminfo 0.9.0 → 0.11.0

package/lib/spectra/ui/scaleOptions.js

@@ -0,0 +1,103 @@
+import { SCALE_METHODS } from "../core/settingsProblems.js";
+/** What each scaling is called, in the order the processor's switch lists them. */
+const METHOD_LABELS = {
+    min: 'Smallest value',
+    max: 'Largest value',
+    minmax: 'Both ends',
+    integration: 'Integral',
+};
+/** The method menu: leaving the spectra alone, then the only four that run. */
+export const SCALE_METHOD_OPTIONS = [
+    { value: '', label: 'None — every spectrum is left as it is' },
+    ...SCALE_METHODS.map((method) => ({
+        value: method,
+        label: METHOD_LABELS[method] ?? method,
+    })),
+];
+/**
+ * The method menu with whatever the settings actually hold in it.
+ *
+ * A menu that does not carry the held value draws the first option instead, so
+ * a settings object saying `MAX` — or saying something the processor throws on
+ * — would be shown as `None` while meaning nothing of the sort. The held
+ * spelling is added rather than corrected, because the panel reports what the
+ * settings say and never quietly rewrites them.
+ * @param method - What the settings hold.
+ * @returns The None prompt and the four scalings, plus the held one when the
+ * menu lacks it.
+ */
+export function scaleMethodOptions(method) {
+    if (method === undefined || method === '')
+        return SCALE_METHOD_OPTIONS;
+    for (const option of SCALE_METHOD_OPTIONS) {
+        if (option.value === method)
+            return SCALE_METHOD_OPTIONS;
+    }
+    const known = METHOD_LABELS[method.toLowerCase()];
+    return [
+        ...SCALE_METHOD_OPTIONS,
+        {
+            value: method,
+            label: known === undefined
+                ? `${method} — not a scaling the processor knows`
+                : `${method} — ${known}`,
+        },
+    ];
+}
+/**
+ * The scaling with another method, or with none when `None` is picked.
+ *
+ * A picked `None` drops the key rather than writing an empty string, because
+ * the processor reads any falsy method as "do not scale" and a key that is
+ * there but empty reads, to anyone looking at the settings, as a mistake.
+ * @param value - How every spectrum is scaled.
+ * @param method - What was picked.
+ * @returns A new scaling.
+ */
+export function withScaleMethod(value, method) {
+    const next = { ...value };
+    if (method === '')
+        delete next.method;
+    else
+        next.method = method;
+    return next;
+}
+/**
+ * The scaling with another reference, or with none when the box was emptied.
+ * @param value - How every spectrum is scaled.
+ * @param targetID - What was picked or typed.
+ * @returns A new scaling.
+ */
+export function withScaleTarget(value, targetID) {
+    const next = { ...value };
+    if (targetID === '')
+        delete next.targetID;
+    else
+        next.targetID = targetID;
+    return next;
+}
+/**
+ * The scaling measured over another window, dropping what is not set.
+ * @param value - How every spectrum is scaled.
+ * @param patch - The bounds that changed.
+ * @returns A new scaling, without a window at all once every bound is cleared.
+ */
+export function withScaleRange(value, patch) {
+    const merged = { ...value.range, ...patch };
+    const range = {};
+    if (merged.from !== undefined)
+        range.from = merged.from;
+    if (merged.to !== undefined)
+        range.to = merged.to;
+    if (merged.fromIndex !== undefined)
+        range.fromIndex = merged.fromIndex;
+    if (merged.toIndex !== undefined)
+        range.toIndex = merged.toIndex;
+    const next = { ...value };
+    if (Object.keys(range).length === 0)
+        delete next.range;
+    else
+        next.range = range;
+    return next;
+}
+//# sourceMappingURL=scaleOptions.js.map

package/lib/spectra/ui/scaleOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaleOptions.js","sourceRoot":"","sources":["../../../src/spectra/ui/scaleOptions.ts"],"names":[],"mappings":"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"}

package/lib/ui.d.ts

@@ -1,5 +1,6 @@
 export * from './about/ui/index.ts';
 export * from './capsule/ui/index.ts';
+export * from './chart/ui/index.ts';
 export * from './chrome/ui/index.ts';
 export * from './citation/ui/index.ts';
 export * from './clipboard/ui/index.ts';
@@ -7,13 +8,19 @@ export * from './color/ui/index.ts';
 export * from './credits/ui/index.ts';
 export * from './delimited/ui/index.ts';
 export * from './disclosure/ui/index.ts';
+export * from './download/ui/index.ts';
 export * from './ecosystem/ui/index.ts';
 export * from './error/ui/index.ts';
 export * from './help/ui/index.ts';
 export * from './hooks/ui/index.ts';
+export * from './overlay/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
+export * from './projection/ui/index.ts';
+export * from './scatter/ui/index.ts';
+export * from './scatter3d/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
+export * from './spectra/ui/index.ts';
 export * from './state/ui/index.ts';
 //# sourceMappingURL=ui.d.ts.map

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,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,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,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,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/lib/ui.js

@@ -1,5 +1,6 @@
 export * from "./about/ui/index.js";
 export * from "./capsule/ui/index.js";
+export * from "./chart/ui/index.js";
 export * from "./chrome/ui/index.js";
 export * from "./citation/ui/index.js";
 export * from "./clipboard/ui/index.js";
@@ -7,13 +8,19 @@ export * from "./color/ui/index.js";
 export * from "./credits/ui/index.js";
 export * from "./delimited/ui/index.js";
 export * from "./disclosure/ui/index.js";
+export * from "./download/ui/index.js";
 export * from "./ecosystem/ui/index.js";
 export * from "./error/ui/index.js";
 export * from "./help/ui/index.js";
 export * from "./hooks/ui/index.js";
+export * from "./overlay/ui/index.js";
 export * from "./pedagogy/ui/index.js";
 export * from "./periodic/ui/index.js";
+export * from "./projection/ui/index.js";
+export * from "./scatter/ui/index.js";
+export * from "./scatter3d/ui/index.js";
 export * from "./share/ui/index.js";
 export * from "./shared/ui/index.js";
+export * from "./spectra/ui/index.js";
 export * from "./state/ui/index.js";
 //# sourceMappingURL=ui.js.map

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,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,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,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,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "Assembled React components shared by the cheminfo sites: a Cite button and an ecosystem menu",
   "author": "Luc Patiny",
@@ -66,6 +66,9 @@
     "eslint": "^9.39.5",
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
+    "ml-dataset-iris": "^1.2.1",
+    "ml-pca": "^4.1.1",
+    "ml-signal-processing": "^2.2.2",
     "molstar": "^5.11.0",
     "openchemlib": "^9.25.0",
     "prettier": "^3.9.6",
@@ -74,6 +77,7 @@
     "react-ocl": "^8.7.2",
     "react-science": "^23.0.0",
     "rimraf": "^6.1.3",
+    "spectra-processor": "^5.0.0",
     "storybook": "^10.5.8",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
@@ -81,12 +85,15 @@
   },
   "peerDependencies": {
     "@blueprintjs/core": "^6.18.0",
+    "ml-pca": "^4.1.1",
+    "ml-signal-processing": "^2.2.2",
     "molstar": "^5.11.0",
     "openchemlib": "^9.24.0",
     "react": "^18.3.1 || >=19",
     "react-dom": "^18.3.1 || >=19",
     "react-ocl": "^8.7.1",
     "react-science": "^20.6.2 || ^21.0.0 || ^22.0.0 || ^23.0.0",
+    "spectra-processor": "^5.0.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "repository": {
@@ -98,6 +105,12 @@
   },
   "homepage": "https://github.com/cheminfo/react-cheminfo#readme",
   "peerDependenciesMeta": {
+    "ml-pca": {
+      "optional": true
+    },
+    "ml-signal-processing": {
+      "optional": true
+    },
     "molstar": {
       "optional": true
     },
@@ -107,6 +120,9 @@
     "react-ocl": {
       "optional": true
     },
+    "spectra-processor": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }

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;
+}