react-cheminfo 0.15.0 → 0.17.0

package/src/parallel/core/parallelHit.ts

@@ -0,0 +1,106 @@
+/**
+ * Which row the pointer is over.
+ *
+ * Only the segment between the two axes the pointer sits between is tested, so
+ * the cost is one distance per row whatever the number of axes. The vertical
+ * gap to the segment is projected onto its normal, so a steep line is no
+ * harder to pick than a flat one — without which the only rows a reader can
+ * ever point at are the uninteresting ones.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+import { parallelPixelAt } from './parallelAxes.ts';
+
+/** How far the pointer may sit from a line and still pick it, in pixels. */
+export const PARALLEL_HOVER_TOLERANCE = 6;
+
+/** A pointer position, relative to the top left of the drawing area. */
+export interface ParallelPoint {
+  /** Pixels from the left of the drawing area. */
+  x: number;
+  /** Pixels from its top. */
+  y: number;
+}
+
+/** The pair of axes a pointer sits between, as indices into the layouts. */
+export interface ParallelSegment {
+  /** The axis to the left of the pointer. */
+  left: number;
+  /** The axis to its right. */
+  right: number;
+}
+
+/**
+ * The pair of axes a horizontal position sits between.
+ * @param x - Pixels from the left of the drawing area.
+ * @param axes - The axes, from left to right.
+ * @param tolerance - How far past the first and the last axis still counts. Defaults to {@link PARALLEL_HOVER_TOLERANCE}.
+ * @returns The pair, or `null` when there are fewer than two axes or the
+ * position is past either end of the figure.
+ */
+export function parallelSegmentAt(
+  x: number,
+  axes: readonly ParallelAxisLayout[],
+  tolerance: number = PARALLEL_HOVER_TOLERANCE,
+): ParallelSegment | null {
+  const first = axes[0];
+  const last = axes.at(-1);
+  if (first === undefined || last === undefined || axes.length < 2) return null;
+  if (x < first.x - tolerance || x > last.x + tolerance) return null;
+  for (let index = 1; index < axes.length; index++) {
+    const right = axes[index];
+    if (right === undefined) continue;
+    if (x <= right.x || index === axes.length - 1) {
+      return { left: index - 1, right: index };
+    }
+  }
+  return null;
+}
+
+/**
+ * The row whose line runs closest to the pointer.
+ * @param point - Where the pointer is, relative to the drawing area.
+ * @param axes - The axes, from left to right.
+ * @param values - Each axis's column, in the same order.
+ * @param count - How many rows are drawn.
+ * @param included - Which rows a brush keeps, a zero meaning the row is not pickable. Defaults to every row.
+ * @param tolerance - How far the pointer may sit from a line. Defaults to {@link PARALLEL_HOVER_TOLERANCE}.
+ * @returns The row, or `-1` when the pointer is over no line.
+ */
+export function parallelNearestRow(
+  point: ParallelPoint,
+  axes: readonly ParallelAxisLayout[],
+  values: ReadonlyArray<ArrayLike<number>>,
+  count: number,
+  included?: Uint8Array,
+  tolerance: number = PARALLEL_HOVER_TOLERANCE,
+): number {
+  const segment = parallelSegmentAt(point.x, axes, tolerance);
+  if (segment === null) return -1;
+  const left = axes[segment.left];
+  const right = axes[segment.right];
+  const leftColumn = values[segment.left];
+  const rightColumn = values[segment.right];
+  if (left === undefined || right === undefined) return -1;
+  if (leftColumn === undefined || rightColumn === undefined) return -1;
+
+  const width = right.x - left.x;
+  if (width <= 0) return -1;
+  const ratio = (point.x - left.x) / width;
+  const rows = Math.min(count, leftColumn.length, rightColumn.length);
+
+  let nearest = -1;
+  let nearestDistance = tolerance;
+  for (let row = 0; row < rows; row++) {
+    if (included?.[row] === 0) continue;
+    const leftY = parallelPixelAt(left.pixels, leftColumn[row] as number);
+    const rightY = parallelPixelAt(right.pixels, rightColumn[row] as number);
+    const gap = Math.abs(leftY + (rightY - leftY) * ratio - point.y);
+    const distance = (gap * width) / Math.hypot(width, rightY - leftY);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearest = row;
+    }
+  }
+  return nearest;
+}

package/src/parallel/core/parallelOrder.ts

@@ -0,0 +1,73 @@
+/**
+ * Which order the axes stand in, when the reader is the one deciding.
+ *
+ * A parallel-coordinates figure only shows a relationship between two columns
+ * that stand next to each other, so the order is not decoration: moving an
+ * axis is how a reader asks a different question of the same data. The
+ * arithmetic of the move is here, away from the pointer that starts it, so
+ * that dragging a name and pressing an arrow key are the same operation.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+
+/**
+ * The same ids with one of them moved.
+ * @param ids - The axes, from left to right.
+ * @param from - Which one is moving.
+ * @param to - The place it lands in, counted in the list it left.
+ * @returns The new order. The list comes back unchanged when either place is
+ * outside it or when nothing moves, so a caller can report without comparing.
+ */
+export function parallelMoveAxis(
+  ids: readonly string[],
+  from: number,
+  to: number,
+): string[] {
+  const order = [...ids];
+  if (from < 0 || from >= order.length) return order;
+  if (to < 0 || to >= order.length || to === from) return order;
+  const [moved] = order.splice(from, 1);
+  if (moved === undefined) return [...ids];
+  order.splice(to, 0, moved);
+  return order;
+}
+
+/**
+ * Where an axis dragged to that position would land.
+ * @param x - Where the pointer is, in pixels from the left of the drawing area.
+ * @param layouts - The axes, from left to right.
+ * @returns The index of the axis whose place it would take, or `-1` when there
+ * is nowhere to land. Nearest axis rather than nearest gap: a reader dragging
+ * a name over its neighbour means the two to swap, and the neighbour's own
+ * name is the thing they are aiming at.
+ */
+export function parallelDropIndex(
+  x: number,
+  layouts: readonly ParallelAxisLayout[],
+): number {
+  let nearest = -1;
+  let nearestDistance = Number.POSITIVE_INFINITY;
+  for (let index = 0; index < layouts.length; index++) {
+    const layout = layouts[index];
+    if (layout === undefined) continue;
+    const distance = Math.abs(x - layout.x);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearest = index;
+    }
+  }
+  return nearest;
+}
+
+/**
+ * The ids of the axes, from left to right.
+ * @param layouts - The axes, already placed.
+ * @returns Their ids, which is what an order is reported as.
+ */
+export function parallelAxisOrder(
+  layouts: readonly ParallelAxisLayout[],
+): string[] {
+  const ids: string[] = [];
+  for (const layout of layouts) ids.push(layout.id);
+  return ids;
+}

package/src/parallel/core/parallelPaint.ts

@@ -0,0 +1,242 @@
+/**
+ * The lines, painted into a canvas.
+ *
+ * The first canvas figure in the family, and for one reason: ten thousand
+ * polylines of a dozen points each is a hundred and twenty thousand SVG
+ * coordinates the browser would keep as elements. Everything a reader points
+ * at, brushes or reads is still SVG or HTML over the top, so only the mass of
+ * lines is pixels — which is also why saving the figure keeps the axes and
+ * loses the lines, and why a site that needs a downloadable figure should say
+ * so before choosing this one.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+import { PARALLEL_MARGIN, parallelPixelAt } from './parallelAxes.ts';
+
+/** How strongly one kept line is drawn, so that the mass reads as a density. */
+export const PARALLEL_INCLUDED_ALPHA = 0.35;
+
+/** How wide a singled-out line's halo is, in pixels. */
+const HALO_WIDTH = 5;
+
+/** How wide a singled-out line itself is. */
+const HIGHLIGHT_WIDTH = 2;
+
+/** How large the dot at each of its axis crossings is. */
+const HIGHLIGHT_DOT_RADIUS = 3;
+
+const FULL_TURN = 2 * Math.PI;
+
+/** What one pass of the line painter needs. */
+export interface ParallelPaint {
+  /** The axes, from left to right, already placed and measured. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** How many rows to draw. */
+  count: number;
+  /**
+   * Which rows the brushes keep, a zero meaning the row is drawn underneath in
+   * the excluded ink.
+   * @default null — every row is kept and nothing is drawn underneath
+   */
+  included?: Uint8Array | null;
+  /**
+   * Which colour each row takes, as a step into `palette`.
+   * @default null — every line takes `line`
+   */
+  steps?: Uint8Array | null;
+  /**
+   * The colours a step indexes, from `parallelPalette`.
+   * @default [] — nothing to index
+   */
+  palette?: readonly string[];
+  /** The ink a line takes when no quantity is colouring the lines. */
+  line: string;
+  /** The ink the rows a brush left out are drawn in. */
+  excluded: string;
+  /**
+   * How strongly a kept line is drawn. Turn it down for a dense library.
+   * @default PARALLEL_INCLUDED_ALPHA
+   */
+  includedAlpha?: number;
+}
+
+/** One row drawn over the mass, and the ink it is drawn in. */
+export interface ParallelHighlight {
+  /** The row. */
+  row: number;
+  /** Its ink. */
+  color: string;
+}
+
+/** What the highlight pass needs. */
+export interface ParallelHighlightPaint {
+  /** The rows to draw, the last one on top. */
+  highlights: readonly ParallelHighlight[];
+  /** The axes, from left to right. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** The ink the halo under each line is drawn in. */
+  halo: string;
+}
+
+/**
+ * Resize a canvas to the device pixel grid and move its origin to the drawing
+ * area, which also clears whatever it held.
+ * @param canvas - The canvas, or `null` before it is mounted.
+ * @param width - Width of the figure, in CSS pixels.
+ * @param height - Its height, in CSS pixels.
+ * @returns The context, or `null` when there is nothing to draw on.
+ */
+export function preparePlotCanvas(
+  canvas: HTMLCanvasElement | null,
+  width: number,
+  height: number,
+): CanvasRenderingContext2D | null {
+  if (canvas === null) return null;
+  const context = canvas.getContext('2d');
+  if (context === null) return null;
+  const pixelRatio = Math.max(globalThis.devicePixelRatio || 1, 1);
+  // Assigning the backing store is what clears it; there is no second clear.
+  canvas.width = Math.round(width * pixelRatio);
+  canvas.height = Math.round(height * pixelRatio);
+  context.resetTransform();
+  context.scale(pixelRatio, pixelRatio);
+  context.translate(PARALLEL_MARGIN.left, PARALLEL_MARGIN.top);
+  return context;
+}
+
+/**
+ * Draw one line per row: the ones a brush left out first, underneath, then the
+ * kept ones over them.
+ *
+ * The excluded rows are one single path stroked once, in a light grey rather
+ * than a translucent black: overlapping segments of one stroked path
+ * accumulate alpha, so a translucent black saturates to black wherever the
+ * library is dense, while a light grey is a colour the pile can only converge
+ * on.
+ * @param context - A context already scaled and moved to the drawing area by {@link preparePlotCanvas}.
+ * @param paint - See {@link ParallelPaint}.
+ */
+export function paintParallelLines(
+  context: CanvasRenderingContext2D,
+  paint: ParallelPaint,
+): void {
+  const { layouts, values, count, line, excluded, includedAlpha } = paint;
+  if (layouts.length < 2) return;
+  const included = paint.included ?? null;
+  const steps = paint.steps ?? null;
+  const palette = paint.palette ?? [];
+  context.lineWidth = 1;
+
+  if (included !== null) {
+    context.strokeStyle = excluded;
+    context.beginPath();
+    for (let row = 0; row < count; row++) {
+      if (included[row] !== 0) continue;
+      traceParallelRow(context, row, layouts, values);
+    }
+    context.stroke();
+  }
+
+  context.globalAlpha = includedAlpha ?? PARALLEL_INCLUDED_ALPHA;
+  context.strokeStyle = line;
+  let previousStep = -1;
+  for (let row = 0; row < count; row++) {
+    if (included !== null && included[row] === 0) continue;
+    if (steps !== null) {
+      const step = steps[row] as number;
+      if (step !== previousStep) {
+        // A step past the end of the ramp is a quantity nobody knows for this
+        // row; it is drawn in the neutral ink rather than in the ramp's first
+        // colour, which means the smallest value in the set.
+        context.strokeStyle = palette[step] ?? line;
+        previousStep = step;
+      }
+    }
+    context.beginPath();
+    traceParallelRow(context, row, layouts, values);
+    context.stroke();
+  }
+  context.globalAlpha = 1;
+}
+
+/**
+ * Draw a few singled-out rows over the mass, each over a halo and dotted at
+ * every axis crossing.
+ * @param context - A context already scaled and moved to the drawing area.
+ * @param paint - See {@link ParallelHighlightPaint}.
+ */
+export function paintParallelHighlights(
+  context: CanvasRenderingContext2D,
+  paint: ParallelHighlightPaint,
+): void {
+  const { highlights, layouts, values, halo } = paint;
+  if (layouts.length < 2) return;
+  context.lineJoin = 'round';
+  context.lineCap = 'round';
+  for (const { row, color } of highlights) {
+    context.beginPath();
+    traceParallelRow(context, row, layouts, values);
+    context.strokeStyle = halo;
+    context.lineWidth = HALO_WIDTH;
+    context.stroke();
+    context.strokeStyle = color;
+    context.lineWidth = HIGHLIGHT_WIDTH;
+    context.stroke();
+
+    context.fillStyle = color;
+    for (let index = 0; index < layouts.length; index++) {
+      const layout = layouts[index];
+      const column = values[index];
+      if (layout === undefined || column === undefined) continue;
+      const y = parallelPixelAt(layout.pixels, column[row] as number);
+      if (!Number.isFinite(y)) continue;
+      context.beginPath();
+      context.arc(layout.x, y, HIGHLIGHT_DOT_RADIUS, 0, FULL_TURN);
+      context.fill();
+    }
+  }
+}
+
+/**
+ * Add one row's line to the path being built.
+ *
+ * The line is one polyline per unbroken run of known values, so a row with a
+ * gap in the middle is drawn as two, and nothing is painted over an axis the
+ * row has no value on.
+ * @param context - A context already scaled and moved to the drawing area.
+ * @param row - The row to trace.
+ * @param layouts - The axes, from left to right.
+ * @param values - Each axis's column, in the same order.
+ */
+export function traceParallelRow(
+  context: CanvasRenderingContext2D,
+  row: number,
+  layouts: readonly ParallelAxisLayout[],
+  values: ReadonlyArray<ArrayLike<number>>,
+): void {
+  let started = false;
+  for (let index = 0; index < layouts.length; index++) {
+    const layout = layouts[index];
+    const column = values[index];
+    if (layout === undefined || column === undefined) continue;
+    const y = parallelPixelAt(layout.pixels, column[row] as number);
+    // A row whose value on this axis is not known yet has no point to draw,
+    // and the line breaks rather than bridging the axis: a segment drawn
+    // across it reads as a value the row does not hold, and the hit test,
+    // which has no endpoint there, cannot pick it back.
+    if (!Number.isFinite(y)) {
+      started = false;
+      continue;
+    }
+    if (started) {
+      context.lineTo(layout.x, y);
+    } else {
+      context.moveTo(layout.x, y);
+      started = true;
+    }
+  }
+}

package/src/parallel/core/parallelPalette.ts

@@ -0,0 +1,93 @@
+/**
+ * The colour each line is drawn in, as a step into a sampled ramp.
+ *
+ * A canvas reassigns `strokeStyle` once per line, and a thousand different
+ * colours is a thousand style writes. Quantising the ramp to 121 steps and
+ * keeping the rows in the order they came means the style is written about
+ * 121 times for the whole figure — while no reader can tell a hundred-and-
+ * twenty-first of a ramp apart from its neighbour.
+ */
+
+import type { ColorScale } from '../../color/core/interpolate.ts';
+import { evenScale, sampleScale } from '../../color/core/interpolate.ts';
+import { positionInRange } from '../../color/core/scale.ts';
+import { resolveColorScale } from '../../color/core/scaleText.ts';
+import { DEFAULT_COLOR_SCALE_ID } from '../../color/core/scales.ts';
+
+import { parallelExtent } from './parallelExtent.ts';
+import type { ParallelColorBy } from './parallelTypes.ts';
+
+/** How many steps the ramp is quantised into; there is one more colour than steps. */
+export const PARALLEL_PALETTE_STEPS = 120;
+
+/**
+ * The step a row whose colouring quantity is unknown takes.
+ *
+ * Past the end of the ramp on purpose: no colour indexes it, so the painter
+ * leaves such a row in the neutral ink rather than claiming for it the ink of
+ * the smallest value in the set.
+ */
+export const PARALLEL_PALETTE_UNKNOWN = PARALLEL_PALETTE_STEPS + 1;
+
+/**
+ * The ramp, sampled into the steps a line's colour is looked up by.
+ * @param scale - The ramp, as the registry hands it over or as a plain list of colours. Defaults to viridis.
+ * @returns `PARALLEL_PALETTE_STEPS + 1` colours, from the low end to the high end.
+ */
+export function parallelPalette(
+  scale?: ColorScale | readonly string[],
+): readonly string[] {
+  return sampleScale(resolveRamp(scale), PARALLEL_PALETTE_STEPS + 1);
+}
+
+/**
+ * Which step of the ramp each row takes.
+ *
+ * Worked out once per data change rather than per repaint, and held as bytes:
+ * a library of ten thousand rows costs ten kilobytes and the painter's inner
+ * loop reads an integer instead of placing a value on a ramp.
+ * @param color - The quantity the lines are coloured by.
+ * @param count - How many rows there are.
+ * @returns One step per row, from `0` to {@link PARALLEL_PALETTE_STEPS}, or
+ * {@link PARALLEL_PALETTE_UNKNOWN} for a row whose value is not a number.
+ */
+export function parallelColorSteps(
+  color: ParallelColorBy,
+  count: number,
+): Uint8Array {
+  const steps = new Uint8Array(count);
+  // A row the column does not reach is as unknown as one holding no number.
+  steps.fill(PARALLEL_PALETTE_UNKNOWN);
+  const extent = parallelExtent(color.values, count);
+  const min = color.min ?? extent.min;
+  const max = color.max ?? extent.max;
+  const logarithmic = color.logarithmic ?? false;
+  const span = max - min;
+  const rows = Math.min(count, color.values.length);
+  for (let row = 0; row < rows; row++) {
+    const value = color.values[row] as number;
+    if (!Number.isFinite(value)) continue;
+    steps[row] = logarithmic
+      ? Math.round(
+          positionInRange(value, min, max, { logarithmic: true }) *
+            PARALLEL_PALETTE_STEPS,
+        )
+      : colorStep(value, min, span);
+  }
+  return steps;
+}
+
+function resolveRamp(scale?: ColorScale | readonly string[]): ColorScale {
+  if (scale === undefined) {
+    return resolveColorScale(DEFAULT_COLOR_SCALE_ID).scale;
+  }
+  return 'stops' in scale ? scale : evenScale(scale);
+}
+
+function colorStep(value: number, min: number, span: number): number {
+  if (span <= 0) return 0;
+  const ratio = (value - min) / span;
+  if (Number.isNaN(ratio) || ratio < 0) return 0;
+  if (ratio > 1) return PARALLEL_PALETTE_STEPS;
+  return Math.round(ratio * PARALLEL_PALETTE_STEPS);
+}

package/src/parallel/core/parallelSelection.ts

@@ -0,0 +1,99 @@
+/**
+ * What an axis keeps, when it keeps more than one interval.
+ *
+ * The figure reports a list and accepts either a list or a bare interval, so a
+ * caller that only ever keeps one is not made to write `[[0, 1]]`. Everything
+ * downstream — the filter, the bands, the gesture — reads the list, which is
+ * what {@link parallelRangeList} is for: one normalisation, at the edge, and
+ * no `Array.isArray` scattered through the painter.
+ *
+ * Intervals on one axis are held sorted and disjoint. Two that touch are one
+ * interval drawn twice, and a reader dragging a band across its neighbour means
+ * to widen it rather than to stack two bands nobody can then take hold of.
+ */
+
+import type { ParallelRange, ParallelSelection } from './parallelTypes.ts';
+
+/** Nothing kept, shared so a normalisation never allocates for the common case. */
+const NONE: readonly ParallelRange[] = [];
+
+/**
+ * The intervals one axis keeps, however the caller wrote them.
+ * @param selection - One interval, several, or nothing at all.
+ * @returns The intervals, in the order given. Read in place — the caller's own
+ * array comes back when it gave one.
+ */
+export function parallelRangeList(
+  selection: ParallelSelection | undefined,
+): readonly ParallelRange[] {
+  if (selection === null || selection === undefined) return NONE;
+  if (selection.length === 0) return NONE;
+  // A bare interval is two numbers; a list of them holds arrays.
+  return typeof selection[0] === 'number'
+    ? [selection as ParallelRange]
+    : (selection as readonly ParallelRange[]);
+}
+
+/**
+ * Whether an axis keeps anything at all.
+ * @param selection - What that axis keeps.
+ * @returns Whether any interval is in force.
+ */
+export function parallelHasRange(
+  selection: ParallelSelection | undefined,
+): boolean {
+  return parallelRangeList(selection).length > 0;
+}
+
+/**
+ * The same intervals, sorted low to high and with the overlapping ones joined.
+ * @param ranges - The intervals, in any order, each low value first.
+ * @returns One list, sorted and disjoint. Intervals that touch at a point are
+ * joined too: a reader who dragged one band onto another meant one band.
+ */
+export function parallelMergeRanges(
+  ranges: readonly ParallelRange[],
+): ParallelRange[] {
+  if (ranges.length === 0) return [];
+  const sorted = ranges
+    .map((range) =>
+      range[0] <= range[1] ? range : ([range[1], range[0]] as ParallelRange),
+    )
+    .toSorted((left, right) => left[0] - right[0]);
+  const merged: ParallelRange[] = [];
+  let low = (sorted[0] as ParallelRange)[0];
+  let high = (sorted[0] as ParallelRange)[1];
+  for (let index = 1; index < sorted.length; index++) {
+    const range = sorted[index] as ParallelRange;
+    if (range[0] > high) {
+      merged.push([low, high]);
+      low = range[0];
+      high = range[1];
+      continue;
+    }
+    if (range[1] > high) high = range[1];
+  }
+  merged.push([low, high]);
+  return merged;
+}
+
+/**
+ * The intervals an axis keeps once one of them is replaced, removed or added.
+ * @param ranges - The intervals in force.
+ * @param index - Which one is being written, or `-1` to add one.
+ * @param range - The interval it becomes, or `null` to take it away.
+ * @returns The new list, sorted and disjoint. Never the same array.
+ */
+export function parallelWriteRange(
+  ranges: readonly ParallelRange[],
+  index: number,
+  range: ParallelRange | null,
+): ParallelRange[] {
+  const kept: ParallelRange[] = [];
+  for (let at = 0; at < ranges.length; at++) {
+    if (at === index) continue;
+    kept.push(ranges[at] as ParallelRange);
+  }
+  if (range !== null) kept.push(range);
+  return parallelMergeRanges(kept);
+}