react-cheminfo 0.9.0 → 0.11.0

package/src/scatter/ui/useScatterKeyboard.ts

@@ -0,0 +1,120 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { useCallback, useRef, useState } from 'react';
+
+import { handleListNavigationKey } from '../../hooks/ui/listNavigation.ts';
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+
+import { modifierMode } from './lassoGesture.ts';
+
+/** What {@link useScatterKeyboard} needs. */
+export interface ScatterKeyboardOptions {
+  /** How many points the cloud holds. */
+  count: number;
+  /**
+   * Whether the keys are read. Off, the plot still takes the focus but every
+   * key falls through to the page.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * How many points `PageUp` and `PageDown` move by.
+   * @default 10
+   */
+  pageStep?: number;
+  /**
+   * Called whenever the cursor lands somewhere new, including `-1`.
+   * @default undefined
+   */
+  onCursorChange?: (index: number) => void;
+  /**
+   * Called when the reader commits the cursor with `Enter` or the space bar,
+   * with the mode the held modifiers ask for.
+   * @default undefined
+   */
+  onCommit?: (index: number, mode: ScatterSelectionMode) => void;
+  /**
+   * Called on `Escape` — what a half-drawn lasso and a pinned card listen for.
+   * @default undefined
+   */
+  onCancel?: () => void;
+}
+
+/** A roving cursor over the points, for a reader with no pointer. */
+export interface ScatterKeyboardApi {
+  /** The point the cursor is on, or `-1` before any key. */
+  cursor: number;
+  /** Move it from outside, so a click and the cursor agree on where they are. */
+  setCursor: (index: number) => void;
+  /** Put on the focusable element around the plot. */
+  onKeyDown: (event: ReactKeyboardEvent<Element>) => void;
+}
+
+/**
+ * Reaching every point of a scatter without a pointer.
+ *
+ * The same roving cursor the periodic table and every list in this family use,
+ * over the same `handleListNavigationKey`, so the arrows, the page keys and
+ * `Home` and `End` behave identically wherever a reader meets them. Without
+ * it a lasso is the only way to pick anything, and a lasso needs a hand.
+ *
+ * The cursor is not the selection. It says where the reader is; `Enter` or the
+ * space bar is what settles it, with Shift and Alt meaning what they mean
+ * during a drag — otherwise arrowing across a cloud would replace the
+ * selection on every step and the reader could never build one up.
+ * @param options - See {@link ScatterKeyboardOptions}.
+ * @returns The cursor. See {@link ScatterKeyboardApi}.
+ */
+export function useScatterKeyboard(
+  options: ScatterKeyboardOptions,
+): ScatterKeyboardApi {
+  const {
+    count,
+    enabled = true,
+    pageStep,
+    onCursorChange,
+    onCommit,
+    onCancel,
+  } = options;
+
+  const [cursor, setCursorState] = useState(-1);
+  const cursorRef = useRef(-1);
+
+  const setCursor = useCallback(
+    (index: number) => {
+      const next =
+        Number.isInteger(index) && index >= 0 && index < count ? index : -1;
+      if (next === cursorRef.current) return;
+      cursorRef.current = next;
+      setCursorState(next);
+      onCursorChange?.(next);
+    },
+    [count, onCursorChange],
+  );
+
+  const onKeyDown = useCallback(
+    (event: ReactKeyboardEvent<Element>) => {
+      if (!enabled || count <= 0) return;
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        onCancel?.();
+        return;
+      }
+      if (event.key === 'Enter' || event.key === ' ') {
+        const index = cursorRef.current;
+        if (index === -1) return;
+        event.preventDefault();
+        onCommit?.(index, modifierMode(event, 'replace'));
+        return;
+      }
+      handleListNavigationKey(event, {
+        length: count,
+        selectedIndex: cursorRef.current,
+        pageStep,
+        onSelect: setCursor,
+      });
+    },
+    [count, enabled, onCancel, onCommit, pageStep, setCursor],
+  );
+
+  return { cursor, setCursor, onKeyDown };
+}

package/src/scatter/ui/useScatterSelection.ts

@@ -0,0 +1,189 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+import {
+  mergeScatterSelection,
+  scatterSelectedIndices,
+  scatterSelectionMask,
+} from '../core/scatterSelection.ts';
+
+/** What a gesture did to a scatter's selection. */
+export interface SelectionChange {
+  /** The selected rows, ascending, as indices into the arrays the caller passed. */
+  indices: readonly number[];
+  /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+  mode: ScatterSelectionMode;
+  /** Which gesture produced it. */
+  source: 'lasso' | 'point' | 'keyboard' | 'clear' | 'all';
+}
+
+/** What {@link useScatterSelection} needs. */
+export interface ScatterSelectionOptions {
+  /** How many points the cloud holds. */
+  count: number;
+  /**
+   * The selected rows when the caller owns them. Present, it wins over
+   * anything the reader has done here — see {@link useScatterSelection} for
+   * what that means for a caller that stops passing it.
+   * @default undefined — the hook keeps the selection itself
+   */
+  selected?: readonly number[];
+  /**
+   * The rows selected before the reader touches anything, for the uncontrolled
+   * case. It is read once; changing it later moves nothing.
+   * @default undefined — nothing is selected
+   */
+  defaultSelected?: readonly number[];
+  /**
+   * Called once per settled gesture, never while a lasso is being drawn.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+}
+
+/** A scatter's selection, and the four ways a gesture changes it. */
+export interface ScatterSelectionApi {
+  /**
+   * One entry per point, `1` for selected. It includes whatever a lasso is
+   * currently previewing, so the dots under a half-drawn ring already look
+   * picked.
+   */
+  mask: Uint8Array;
+  /** The same, as ascending indices. */
+  indices: number[];
+  /** How many points that is, without walking the list again. */
+  selectedCount: number;
+  /** Whether a lasso is showing what it would do rather than having done it. */
+  previewing: boolean;
+  /** Settle a new selection from a list of rows. */
+  select: (
+    rows: Iterable<number>,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Settle one from a mask, which is the shape a lasso hands back. */
+  selectMask: (
+    hits: Uint8Array,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Show what a gesture would do without settling it; `null` clears it. */
+  preview: (hits: Uint8Array | null, mode?: ScatterSelectionMode) => void;
+  /** Empty the selection. */
+  clear: () => void;
+  /** Select every point. */
+  selectAll: () => void;
+}
+
+/**
+ * The set of points a scatter has picked out, controlled or not.
+ *
+ * A caller may own the selection and pass it back through `selected`, or leave
+ * it here and only listen. Both work through one hook, and the controlled
+ * value wins on every render: a parent that answers a change by passing
+ * something else — a filter that keeps only the rows still on screen — sees
+ * what it asked for and not what the gesture asked for. The hook keeps its own
+ * copy up to date all the same, so a caller that stops passing `selected`
+ * carries on from where the reader left off rather than from nothing.
+ *
+ * A preview is deliberately not a change. What a half-drawn lasso would catch
+ * is merged in for the render and never reported, which is what lets a
+ * controlled parent stay out of a drag it would otherwise be re-rendered by
+ * sixty times a second.
+ * @param options - See {@link ScatterSelectionOptions}.
+ * @returns The selection. See {@link ScatterSelectionApi}.
+ */
+export function useScatterSelection(
+  options: ScatterSelectionOptions,
+): ScatterSelectionApi {
+  const { count, selected, defaultSelected, onSelectionChange } = options;
+
+  const [own, setOwn] = useState<readonly number[]>(defaultSelected ?? EMPTY);
+  const [draft, setDraft] = useState<SelectionDraft | null>(null);
+  const committed = selected ?? own;
+
+  const mask = useMemo(() => {
+    const base = scatterSelectionMask(committed, count);
+    if (draft === null) return base;
+    return mergeScatterSelection(base, draft.hits, draft.mode, base);
+  }, [committed, count, draft]);
+
+  const indices = useMemo(() => scatterSelectedIndices(mask), [mask]);
+
+  const commit = useCallback(
+    (
+      rows: number[],
+      mode: ScatterSelectionMode,
+      source: SelectionChange['source'],
+    ) => {
+      setDraft(null);
+      setOwn(rows);
+      onSelectionChange?.({ indices: rows, mode, source });
+    },
+    [onSelectionChange],
+  );
+
+  const selectMask = useCallback(
+    (
+      hits: Uint8Array,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'lasso',
+    ) => {
+      const base = scatterSelectionMask(committed, count);
+      const merged = mergeScatterSelection(base, hits, mode, base);
+      commit(scatterSelectedIndices(merged), mode, source);
+    },
+    [commit, committed, count],
+  );
+
+  const select = useCallback(
+    (
+      rows: Iterable<number>,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'point',
+    ) => {
+      selectMask(scatterSelectionMask(rows, count), mode, source);
+    },
+    [count, selectMask],
+  );
+
+  const preview = useCallback(
+    (hits: Uint8Array | null, mode: ScatterSelectionMode = 'replace') => {
+      setDraft(hits === null ? null : { hits, mode });
+    },
+    [],
+  );
+
+  const clear = useCallback(() => {
+    commit([], 'replace', 'clear');
+  }, [commit]);
+
+  const selectAll = useCallback(() => {
+    const rows = new Array<number>(Math.max(0, count));
+    for (let index = 0; index < rows.length; index++) rows[index] = index;
+    commit(rows, 'replace', 'all');
+  }, [commit, count]);
+
+  return {
+    mask,
+    indices,
+    selectedCount: indices.length,
+    previewing: draft !== null,
+    select,
+    selectMask,
+    preview,
+    clear,
+    selectAll,
+  };
+}
+
+/** Shared, so an uncontrolled scatter with nothing picked allocates nothing. */
+const EMPTY: readonly number[] = [];
+
+/** What a lasso is showing it would do, before it has been released. */
+interface SelectionDraft {
+  /** The points the half-drawn gesture is over. */
+  hits: Uint8Array;
+  /** What releasing would do with them. */
+  mode: ScatterSelectionMode;
+}

package/src/scatter3d/core/cloudGesture.ts

@@ -0,0 +1,16 @@
+/**
+ * What a drag over a cloud does.
+ *
+ * Two gestures want the same drag. Turning the box is the one a reader reaches
+ * for first and must stay a plain drag; drawing a lasso is the one the flat map
+ * has already taught them. Neither can be given a modifier without taking one
+ * that already means "add to the selection" or "take out of it", so the choice
+ * is a control the reader can see rather than a shortcut somebody has to tell
+ * them about — and inside a lasso the modifiers keep exactly the meaning they
+ * have on the map.
+ */
+export type CloudGesture =
+  /** Turn the box. A tap still picks the sample under it. */
+  | 'turn'
+  /** Draw a lasso, exactly as on the map. */
+  | 'select';

package/src/scatter3d/core/confidenceEllipsoid.ts

@@ -0,0 +1,177 @@
+/**
+ * The shell that summarises where a group of samples sits in the cloud.
+ *
+ * It is the outline of `scatter/core` with one dimension more, and it is
+ * described the same way — a centre and the axes of the group's own spread,
+ * in the data's units — so that turning it into something an SVG can draw
+ * stays a separate step. Here that step matters more than it does on a map:
+ * a shell has no `<ellipse>` to fall back on and has to be tessellated,
+ * projected and painted back to front.
+ */
+
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+
+import { standardDeviationsForCoverage3 } from './ellipsoidCoverage.ts';
+import type { Vector3 } from './orbitCamera.ts';
+import type { SymmetricMatrix3 } from './symmetricEigen.ts';
+import { symmetricEigen3 } from './symmetricEigen.ts';
+
+/** A group's shell, in the cloud's own units. */
+export interface ConfidenceEllipsoid {
+  /** Centre of the shell, which is the group's average. */
+  center: Vector3;
+  /**
+   * Three orthogonal semi-axes, longest first, each vector as long as its own
+   * radius. A direction the group has no spread in is the zero vector, which
+   * is what flattens the shell rather than giving it a false thickness.
+   */
+  axes: readonly [Vector3, Vector3, Vector3];
+  /** How many finite points went into it. */
+  count: number;
+}
+
+/** How {@link confidenceEllipsoid} measures a group. */
+export interface ConfidenceEllipsoidOptions {
+  /**
+   * How large to draw the shell. A share is read in three dimensions, so the
+   * same share gives a wider shell here than the same call gives on the map.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many finite points a group needs before it is given a shell at all.
+   * Below four a group has no volume to measure — three points lie on a plane
+   * however they are arranged — so fewer than four is read as four.
+   * @default 4
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * The shell that summarises a group of samples.
+ *
+ * Points that are not finite are skipped rather than poisoning the average,
+ * and the spread is measured with the `n - 1` divisor, so the shell estimates
+ * the group rather than describing the handful of samples that happen to have
+ * been measured — both exactly as the two-dimensional outline does.
+ * @param points - The group's samples, in the cloud's own units.
+ * @param options - See {@link ConfidenceEllipsoidOptions}.
+ * @returns The shell, or `null` when the group is too small to have a shape, when its coordinates are so large that squaring them overflows, or when the requested size is unbounded.
+ */
+export function confidenceEllipsoid(
+  points: readonly Vector3[],
+  options: ConfidenceEllipsoidOptions = {},
+): ConfidenceEllipsoid | null {
+  const { size = DEFAULT_SIZE, minimumPoints = 4 } = options;
+  const floor = Math.max(4, minimumPoints);
+
+  let count = 0;
+  let sumX = 0;
+  let sumY = 0;
+  let sumZ = 0;
+  for (const point of points) {
+    if (!isFinitePoint(point)) continue;
+    count++;
+    sumX += point[0];
+    sumY += point[1];
+    sumZ += point[2];
+  }
+  if (count < floor) return null;
+
+  const center: Vector3 = [sumX / count, sumY / count, sumZ / count];
+  const covariance = spreadAbout(points, center, count);
+  if (covariance === null) return null;
+
+  const radius = ellipsoidStandardDeviations(size);
+  if (!Number.isFinite(radius)) return null;
+
+  const { values, vectors } = symmetricEigen3(covariance);
+  const axes: Vector3[] = [];
+  for (let i = 0; i < 3; i++) {
+    const length = radius * Math.sqrt(Math.max(0, values[i] as number));
+    if (!Number.isFinite(length)) return null;
+    const direction = vectors[i] as Vector3;
+    axes.push([
+      direction[0] * length,
+      direction[1] * length,
+      direction[2] * length,
+    ]);
+  }
+
+  return {
+    center,
+    axes: [axes[0] as Vector3, axes[1] as Vector3, axes[2] as Vector3],
+    count,
+  };
+}
+
+/**
+ * How far out a size asks the shell to be drawn.
+ *
+ * Public because a legend has to be able to say what a share came to without
+ * building a shell to ask it.
+ * @param size - How large the shell was asked to be.
+ * @returns The number of standard deviations.
+ */
+export function ellipsoidStandardDeviations(size: EllipseSize): number {
+  if (size.kind === 'standardDeviations') return size.standardDeviations;
+  return standardDeviationsForCoverage3(size.probability);
+}
+
+function spreadAbout(
+  points: readonly Vector3[],
+  center: Vector3,
+  count: number,
+): SymmetricMatrix3 | null {
+  let xx = 0;
+  let xy = 0;
+  let xz = 0;
+  let yy = 0;
+  let yz = 0;
+  let zz = 0;
+  for (const point of points) {
+    if (!isFinitePoint(point)) continue;
+    const dx = point[0] - center[0];
+    const dy = point[1] - center[1];
+    const dz = point[2] - center[2];
+    xx += dx * dx;
+    xy += dx * dy;
+    xz += dx * dz;
+    yy += dy * dy;
+    yz += dy * dz;
+    zz += dz * dz;
+  }
+  const divisor = count - 1;
+  const covariance: SymmetricMatrix3 = {
+    xx: xx / divisor,
+    xy: xy / divisor,
+    xz: xz / divisor,
+    yy: yy / divisor,
+    yz: yz / divisor,
+    zz: zz / divisor,
+  };
+  if (
+    !Number.isFinite(center[0]) ||
+    !Number.isFinite(center[1]) ||
+    !Number.isFinite(center[2]) ||
+    !Number.isFinite(covariance.xx) ||
+    !Number.isFinite(covariance.yy) ||
+    !Number.isFinite(covariance.zz) ||
+    !Number.isFinite(covariance.xy) ||
+    !Number.isFinite(covariance.xz) ||
+    !Number.isFinite(covariance.yz)
+  ) {
+    return null;
+  }
+  return covariance;
+}
+
+function isFinitePoint(point: Vector3): boolean {
+  return (
+    Number.isFinite(point[0]) &&
+    Number.isFinite(point[1]) &&
+    Number.isFinite(point[2])
+  );
+}
+
+const DEFAULT_SIZE: EllipseSize = { kind: 'coverage', probability: 0.95 };

package/src/scatter3d/core/cubeFrame.ts

@@ -0,0 +1,72 @@
+/**
+ * The box the cloud sits in.
+ *
+ * A cloud of dots on an empty background has no orientation at all: turn it
+ * and nothing tells the reader it turned, and a dot near the top could be near
+ * or far. Twelve faint edges and three labelled arms fix that for the cost of
+ * fifteen lines, and they are the reason the projection can stay orthographic
+ * — the frame carries the depth that perspective would otherwise have to, and
+ * unlike perspective it distorts no distance.
+ */
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** The corner the three labelled arms are drawn from. */
+export const CUBE_ORIGIN: Vector3 = [-1, -1, -1];
+
+/**
+ * The twelve edges of the cube, each as its two corners.
+ *
+ * Every edge, not just the three at the back: which edges are hidden changes
+ * as the box turns, and drawing all twelve faintly reads as a wireframe, while
+ * drawing three reads as an axis system that keeps rearranging itself.
+ * @returns The edges. The order is stable but carries no meaning.
+ */
+export function cubeEdges(): Array<[Vector3, Vector3]> {
+  const corners: Vector3[] = [];
+  for (const x of [-1, 1]) {
+    for (const y of [-1, 1]) {
+      for (const z of [-1, 1]) corners.push([x, y, z]);
+    }
+  }
+
+  const edges: Array<[Vector3, Vector3]> = [];
+  for (let i = 0; i < corners.length; i++) {
+    for (let j = i + 1; j < corners.length; j++) {
+      const a = corners[i] as Vector3;
+      const b = corners[j] as Vector3;
+      // Two corners are joined by an edge exactly when they differ in one
+      // coordinate; differing in two is a face diagonal and in three is the
+      // body diagonal, and drawing either would turn the frame into a mesh.
+      const differing =
+        (a[0] === b[0] ? 0 : 1) +
+        (a[1] === b[1] ? 0 : 1) +
+        (a[2] === b[2] ? 0 : 1);
+      if (differing === 1) edges.push([a, b]);
+    }
+  }
+  return edges;
+}
+
+/** One labelled arm of the frame. */
+export interface CubeArm {
+  /** Which of the three axes it stands for. */
+  axis: 'x' | 'y' | 'z';
+  /** The far end of the arm. */
+  end: Vector3;
+  /** Where its name is written, just beyond the end. */
+  label: Vector3;
+}
+
+/**
+ * The three arms, from the origin corner along each axis.
+ *
+ * The label sits a little past the end of its arm so that it is outside the
+ * cloud whatever the box is turned to; at the end itself it would fall on the
+ * frame from about a third of the angles.
+ */
+export const CUBE_ARMS: readonly CubeArm[] = [
+  { axis: 'x', end: [1, -1, -1], label: [1.18, -1, -1] },
+  { axis: 'y', end: [-1, 1, -1], label: [-1, 1.18, -1] },
+  { axis: 'z', end: [-1, -1, 1], label: [-1, -1, 1.18] },
+];

package/src/scatter3d/core/cubePoints.ts

@@ -0,0 +1,75 @@
+/**
+ * Three runs of numbers, stretched into the cube the cloud is drawn in.
+ *
+ * A map draws its two axes at whatever scale each one needs, and the tick
+ * labels are the reader's record of that. A cloud has no such record: it is
+ * one solid seen from an angle, so three axes drawn at three scales would make
+ * a group lean in a direction that is an artefact of the scaling and not
+ * anything in the data. Every axis is therefore stretched to the same cube,
+ * the frame is labelled with which axis is which, and the numbers stay in the
+ * card the pointer raises.
+ *
+ * The shells are fitted in this cube for the same reason the map fits its
+ * outlines in pixels: a shell has to sit on the cloud the reader is looking
+ * at, not on a cloud in units nothing draws.
+ */
+
+import {
+  chartPadExtent,
+  chartValuesExtent,
+} from '../../chart/core/chartExtent.ts';
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** How {@link cubePoints} stretches the runs it is given. */
+export interface CubePointsOptions {
+  /**
+   * Share of each axis' span left empty at both ends, so the cloud does not
+   * touch the frame.
+   * @default 0.05
+   */
+  padding?: number;
+}
+
+/**
+ * Three runs of numbers, each stretched to `[-1, 1]`.
+ * @param x - Where every sample sits along the axis that runs left to right.
+ * @param y - Along the axis that runs bottom to top, in the same order.
+ * @param z - Along the axis that runs away from the reader.
+ * @param options - See {@link CubePointsOptions}.
+ * @returns One point per sample, as many as the shortest run holds. An axis with no spread at all puts every sample at the middle of it rather than dividing by zero, and a value that is not finite stays that way so nothing draws it.
+ */
+export function cubePoints(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  z: ArrayLike<number>,
+  options: CubePointsOptions = {},
+): Vector3[] {
+  const { padding = 0.05 } = options;
+  const toCube = [x, y, z].map((values) => axisMapper(values, padding));
+  const across = toCube[0] as Mapper;
+  const up = toCube[1] as Mapper;
+  const away = toCube[2] as Mapper;
+
+  const count = Math.min(x.length, y.length, z.length);
+  const points = new Array<Vector3>(count);
+  for (let index = 0; index < count; index++) {
+    points[index] = [
+      across(x[index] as number),
+      up(y[index] as number),
+      away(z[index] as number),
+    ];
+  }
+  return points;
+}
+
+type Mapper = (value: number) => number;
+
+function axisMapper(values: ArrayLike<number>, padding: number): Mapper {
+  const { min, max } = chartPadExtent(chartValuesExtent(values), padding);
+  const span = max - min;
+  if (!Number.isFinite(span) || span <= 0) {
+    return (value: number) => (Number.isFinite(value) ? 0 : Number.NaN);
+  }
+  return (value: number) => (2 * (value - min)) / span - 1;
+}