react-cheminfo 0.9.0 → 0.11.0

package/src/scatter3d/ui/cloudGeometry.ts

@@ -0,0 +1,200 @@
+/**
+ * Where the cube, the cloud and the shells land on screen for one camera.
+ *
+ * Everything a cloud draws is cut once, in cube units, and re-projected on
+ * every turn — so an orbit costs one multiply-add per vertex and nothing else.
+ * That is what keeps a drag smooth on a figure holding a dozen shells of a
+ * hundred and sixty faces each, and it is why the cutting and the projecting
+ * are two steps rather than one.
+ */
+
+import type { ScreenPoints } from '../../scatter/core/screenPoints.ts';
+import type { ConfidenceEllipsoid } from '../core/confidenceEllipsoid.ts';
+import { ellipsoidSilhouette } from '../core/ellipsoidSilhouette.ts';
+import type {
+  OrbitCamera,
+  OrbitViewport,
+  Vector3,
+} from '../core/orbitCamera.ts';
+import { projectPoint } from '../core/orbitCamera.ts';
+
+/** Room kept between the figure's edge and the cube, in pixels. */
+export const CLOUD_MARGIN = 16;
+
+/**
+ * How much of the shorter side the cube spans before the reader zooms.
+ *
+ * Well short of the whole: the cube is drawn turned, so its silhouette is a
+ * hexagon as wide as its body diagonal, and a cube sized to the box edge-on
+ * would push two of its corners past the frame the moment it was turned.
+ */
+export const CLOUD_FILL = 0.62;
+
+/** The rectangle the cloud is drawn in, and how the cube maps into it. */
+export interface CloudView {
+  /** The drawing area, ready to spread onto a `<rect>`. */
+  rect: { x: number; y: number; width: number; height: number };
+  /** Where the middle of the cube sits, and how large it is drawn. */
+  viewport: OrbitViewport;
+}
+
+/**
+ * The drawing area and the cube's place in it.
+ * @param width - Total width of the figure, in pixels.
+ * @param height - Total height.
+ * @param zoom - What the reader has zoomed to; `1` is the resting size.
+ * @returns See {@link CloudView}.
+ */
+export function cloudView(
+  width: number,
+  height: number,
+  zoom: number,
+): CloudView {
+  const inner = Math.max(0, width - CLOUD_MARGIN * 2);
+  const tall = Math.max(0, height - CLOUD_MARGIN * 2);
+  const factor = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+  return {
+    rect: { x: CLOUD_MARGIN, y: CLOUD_MARGIN, width: inner, height: tall },
+    viewport: {
+      scale: (Math.min(inner, tall) / 2) * CLOUD_FILL * factor,
+      centerX: CLOUD_MARGIN + inner / 2,
+      centerY: CLOUD_MARGIN + tall / 2,
+    },
+  };
+}
+
+/** Where every sample landed, and in what order they are painted. */
+export interface CloudCloud {
+  /** The positions, in the same space a gesture arrives in. */
+  points: ScreenPoints;
+  /** How far towards the reader each one is, in cube units. */
+  depths: Float64Array;
+  /** The rows, furthest first, which is the order they are drawn in. */
+  order: Uint32Array;
+}
+
+/**
+ * Every sample, projected and ordered back to front.
+ *
+ * The order is what makes the cloud read as a solid: a dot at the front drawn
+ * over a dot at the back says which is which, where the same two dots in row
+ * order say nothing at all. It is a separate array rather than a sorted copy
+ * of the points because the hit test, the labels and the selection all index
+ * by row and must not be reordered with the painting.
+ * @param cube - Every sample, in cube units.
+ * @param camera - Where the reader is standing.
+ * @param viewport - Where the middle of the cube is, and how large it is drawn.
+ * @returns See {@link CloudCloud}.
+ */
+export function projectCloud(
+  cube: readonly Vector3[],
+  camera: OrbitCamera,
+  viewport: OrbitViewport,
+): CloudCloud {
+  const count = cube.length;
+  const x = new Float64Array(count);
+  const y = new Float64Array(count);
+  const depths = new Float64Array(count);
+  for (let index = 0; index < count; index++) {
+    const at = projectPoint(cube[index] as Vector3, camera, viewport);
+    x[index] = at.x;
+    y[index] = at.y;
+    depths[index] = at.depth;
+  }
+
+  const rows = new Uint32Array(count);
+  for (let index = 0; index < count; index++) rows[index] = index;
+  const order = rows.toSorted(
+    (a, b) => (depths[a] as number) - (depths[b] as number),
+  );
+
+  return { points: { x, y }, depths, order };
+}
+
+/** One shell's outline, ready to be filled. */
+export interface CloudOutline {
+  /** Where its middle landed, in pixels from the left. */
+  cx: number;
+  /** And from the top. */
+  cy: number;
+  /** Half its longest width, in pixels. */
+  rx: number;
+  /** Half its width across that, in pixels. */
+  ry: number;
+  /** How far the long axis is turned from the horizontal, in degrees. */
+  angle: number;
+  /** How far towards the reader its middle is, in cube units. */
+  depth: number;
+}
+
+/**
+ * Where one shell's outline lands on screen.
+ * @param ellipsoid - The shell, in cube units.
+ * @param camera - Where the reader is standing.
+ * @param viewport - Where the middle of the cube is, and how large it is drawn.
+ * @returns See {@link CloudOutline}, or `null` when the camera sends the shell nowhere a browser can draw.
+ */
+export function projectShellOutline(
+  ellipsoid: ConfidenceEllipsoid,
+  camera: OrbitCamera,
+  viewport: OrbitViewport,
+): CloudOutline | null {
+  const at = projectPoint(ellipsoid.center, camera, viewport);
+  const { rx, ry, angle } = ellipsoidSilhouette(ellipsoid, camera);
+  const outline = {
+    cx: round(at.x),
+    cy: round(at.y),
+    rx: round(rx * viewport.scale),
+    ry: round(ry * viewport.scale),
+    angle: round((angle * 180) / Math.PI),
+    depth: at.depth,
+  };
+  for (const value of [outline.cx, outline.cy, outline.rx, outline.ry]) {
+    if (!Number.isFinite(value)) return null;
+  }
+  return outline;
+}
+
+/** A segment of the frame, in pixels. */
+export interface CloudSegment {
+  /** Where it starts. */
+  x1: number;
+  /** Where it starts. */
+  y1: number;
+  /** Where it ends. */
+  x2: number;
+  /** Where it ends. */
+  y2: number;
+}
+
+/**
+ * A run of cube-space segments, projected.
+ * @param segments - The segments, as pairs of corners in cube units.
+ * @param camera - Where the reader is standing.
+ * @param viewport - Where the middle of the cube is, and how large it is drawn.
+ * @returns The segments, in pixels, in the order they were given.
+ */
+export function projectSegments(
+  segments: ReadonlyArray<readonly [Vector3, Vector3]>,
+  camera: OrbitCamera,
+  viewport: OrbitViewport,
+): CloudSegment[] {
+  const lines: CloudSegment[] = [];
+  for (const [from, to] of segments) {
+    const start = projectPoint(from, camera, viewport);
+    const end = projectPoint(to, camera, viewport);
+    lines.push({
+      x1: round(start.x),
+      y1: round(start.y),
+      x2: round(end.x),
+      y2: round(end.y),
+    });
+  }
+  return lines;
+}
+
+/*
+ * Two decimals, which is under a tenth of a device pixel at any zoom a browser
+ * offers and keeps the markup short enough to read in a failing test.
+ */
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/scatter3d/ui/cloudShellStyles.ts

@@ -0,0 +1,74 @@
+/**
+ * How solid the glass is, and how it thickens from the middle to the rim.
+ */
+
+/**
+ * How solid one wall of the glass is, seen square on, by default.
+ *
+ * Low, because a ray straight through a shell already meets two walls, and two
+ * shells that overlap put four in the reader's way.
+ */
+export const SHELL_FILL_OPACITY = 0.1;
+
+/**
+ * How many walls' worth of glass the rim is allowed to reach.
+ *
+ * The path through a shell grows as the secant of the angle it is seen at, so
+ * at the silhouette it is unbounded and the rim would go opaque. Held to a few
+ * walls it reads as the swell of a ball; unheld it reads as a ring drawn round
+ * a disc, which is the wireframe this fill replaced.
+ */
+const RIM_WALLS = 6;
+
+/** One stop of the glass gradient. */
+export interface ShellGlassStop {
+  /** How far out it sits, from `0` at the middle to `1` at the rim. */
+  offset: number;
+  /** How solid the glass is there. */
+  opacity: number;
+}
+
+/**
+ * The gradient one shell is filled with, which is what gives it its relief.
+ *
+ * A shell is a surface, not a filled solid, so what the reader looks through
+ * is two walls of it. Straight through the middle they are met square on and
+ * the glass is at its thinnest; towards the rim the same two walls are met at
+ * a closing angle and the path through them lengthens as the secant of it, so
+ * the shell swells towards its edge and reads as round. That is the whole of
+ * the modelling the tessellated version did, minus the seams between the faces
+ * it needed to do it.
+ *
+ * The walls are composited rather than added, so two of them at a tenth are
+ * not a fifth but a nineteenth-something — the same arithmetic the browser was
+ * doing when they were stacked polygons.
+ * @param strength - How solid one wall is, after the group's own opacity.
+ * @returns The stops, from the middle outwards.
+ */
+export function shellGlassStops(strength: number): ShellGlassStop[] {
+  const wall = Math.min(1, Math.max(0, strength));
+  const clear = 1 - wall;
+  return GLASS_OFFSETS.map((offset) => ({
+    offset,
+    opacity: round(1 - clear ** wallsAt(offset)),
+  }));
+}
+
+/**
+ * How much glass a ray meets at a given distance out from the middle.
+ * @param offset - How far out, from `0` at the middle to `1` at the rim.
+ * @returns The number of walls' worth, held to {@link RIM_WALLS}.
+ */
+function wallsAt(offset: number): number {
+  const facing = Math.sqrt(Math.max(0, 1 - offset * offset));
+  if (facing <= 0) return RIM_WALLS;
+  return Math.min(RIM_WALLS, 2 / facing);
+}
+
+/*
+ * Close together near the rim, where the glass thickens quickest, and sparse
+ * through the middle, where it barely changes.
+ */
+const GLASS_OFFSETS = [0, 0.3, 0.5, 0.66, 0.78, 0.87, 0.93, 0.97, 1];
+
+const round = (value: number): number => Math.round(value * 10000) / 10000;

package/src/scatter3d/ui/cloudZoom.ts

@@ -0,0 +1,22 @@
+/**
+ * How far the reader may stand back from the box, and how near they may get.
+ *
+ * A cloud without a zoom cannot be read where its groups overlap, which on a
+ * projection is exactly where the reader is looking. The range is kept modest
+ * at both ends: past four the frame is off the picture and there is nothing
+ * left to say which way is which, and below four tenths the cloud is a smudge
+ * in the middle of an empty box.
+ */
+
+/** How far the wheel may zoom out and in. */
+export const CLOUD_ZOOM_RANGE = { min: 0.4, max: 4 } as const;
+
+/**
+ * A zoom held inside what the box can usefully be seen at.
+ * @param zoom - The zoom asked for.
+ * @returns The zoom to draw at; `1` for anything that is not a number.
+ */
+export function clampCloudZoom(zoom: number): number {
+  if (!Number.isFinite(zoom)) return 1;
+  return Math.min(CLOUD_ZOOM_RANGE.max, Math.max(CLOUD_ZOOM_RANGE.min, zoom));
+}

package/src/scatter3d/ui/index.ts

@@ -0,0 +1,41 @@
+/**
+ * A cloud of samples in a box the reader can turn.
+ *
+ * It is the `scatter` domain's twin, and deliberately so: the same selection,
+ * the same lasso, the same hover card, the same labels and the same group
+ * colours, so that a reader who has learned the map has learned this too. What
+ * is new is everything the third axis forces — a box to say which way is up, a
+ * drag that turns it, glass shells instead of outlines, and one scale across
+ * all three axes, because a solid seen from an angle has nowhere to write
+ * three sets of tick labels.
+ */
+
+export type { CloudFrameLayerProps } from './CloudFrameLayer.tsx';
+export { CloudFrameLayer } from './CloudFrameLayer.tsx';
+export type { CloudPointLayerProps } from './CloudPointLayer.tsx';
+export { CloudPointLayer } from './CloudPointLayer.tsx';
+export type { CloudShell, CloudShellLayerProps } from './CloudShellLayer.tsx';
+export { CloudShellLayer } from './CloudShellLayer.tsx';
+export type {
+  CloudCloud,
+  CloudOutline,
+  CloudSegment,
+  CloudView,
+} from './cloudGeometry.ts';
+export {
+  CLOUD_FILL,
+  CLOUD_MARGIN,
+  cloudView,
+  projectCloud,
+  projectSegments,
+  projectShellOutline,
+} from './cloudGeometry.ts';
+export type { ShellGlassStop } from './cloudShellStyles.ts';
+export { SHELL_FILL_OPACITY, shellGlassStops } from './cloudShellStyles.ts';
+export { CLOUD_ZOOM_RANGE, clampCloudZoom } from './cloudZoom.ts';
+export type { CloudShellsInput } from './scatterCloudModel.ts';
+export { cloudLabel, cloudShells } from './scatterCloudModel.ts';
+export type { CloudGesture, ScatterCloudProps } from './scatterCloudProps.ts';
+export { ScatterCloud } from './ScatterCloud.tsx';
+export type { OrbitDrag, OrbitDragOptions } from './useOrbitDrag.ts';
+export { useOrbitDrag } from './useOrbitDrag.ts';

package/src/scatter3d/ui/scatterCloudModel.ts

@@ -0,0 +1,98 @@
+/**
+ * What a cloud is made of before any of it is drawn: the shell around each
+ * group, and the sentence a screen reader is given instead of the picture.
+ *
+ * It is kept out of the component for the same reason the flat scatter's model
+ * is — a shell has to be cut before there is anything to project, and cutting
+ * it inside the render callback would cut it again on every turn.
+ */
+
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import type { ScatterGroupInk } from '../../scatter/ui/scatterPlotModel.ts';
+import type { ScatterGroup } from '../../scatter/ui/scatterPlotProps.ts';
+import { confidenceEllipsoid } from '../core/confidenceEllipsoid.ts';
+import type { Vector3 } from '../core/orbitCamera.ts';
+
+import type { CloudShell } from './CloudShellLayer.tsx';
+
+/** What {@link cloudShells} needs to fit one shell per group. */
+export interface CloudShellsInput {
+  /** Every sample, in cube units. */
+  cube: readonly Vector3[];
+  /** Which group each sample belongs to, as an index into `groups`. */
+  groupOf: ArrayLike<number>;
+  /** The groups, in the order they are coloured. */
+  groups: readonly ScatterGroup[];
+  /** The colour and the strength each group is drawn at. */
+  ink: ScatterGroupInk;
+  /** How large the shells are. */
+  size: EllipseSize;
+  /**
+   * How many samples a group needs before it is given a shell.
+   * @default 4
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * One shell per group that has enough samples to have a shape.
+ *
+ * The shells are fitted in cube units rather than in the data's own, because
+ * the three axes were stretched to one cube and a shell fitted before that
+ * stretch would not sit on the cloud the reader is looking at. It is the same
+ * reasoning the map uses when it fits its outlines in pixels.
+ *
+ * A group the reader has switched off in the legend keeps its shell and loses
+ * its strength, so the shape it was making is still visible behind the groups
+ * that are left — which is the whole point of switching one off.
+ * @param input - See {@link CloudShellsInput}.
+ * @returns The shells, in group order. A group too small for a shape is left out rather than given a shell that describes its handful of samples.
+ */
+export function cloudShells(input: CloudShellsInput): CloudShell[] {
+  const { cube, groupOf, groups, ink, size, minimumPoints } = input;
+
+  const held: Vector3[][] = groups.map(() => []);
+  const count = Math.min(cube.length, groupOf.length);
+  for (let index = 0; index < count; index++) {
+    const group = groupOf[index];
+    if (group === undefined || group < 0 || group >= groups.length) continue;
+    (held[group] as Vector3[]).push(cube[index] as Vector3);
+  }
+
+  const shells: CloudShell[] = [];
+  for (const [group, entry] of groups.entries()) {
+    const ellipsoid = confidenceEllipsoid(held[group] as Vector3[], {
+      size,
+      minimumPoints,
+    });
+    if (ellipsoid === null) continue;
+    shells.push({
+      id: entry.id,
+      color: ink.colors[group] ?? entry.color,
+      ellipsoid,
+      opacity: ink.opacities[group] ?? 1,
+    });
+  }
+  return shells;
+}
+
+/**
+ * What a screen reader is told the figure shows.
+ *
+ * It names all three axes, because a reader who cannot see the box has no
+ * frame to read them off, and the frame is where a sighted reader learns which
+ * axis is which.
+ * @param xLabel - What the axis running left to right is called.
+ * @param yLabel - What the axis running bottom to top is called.
+ * @param zLabel - What the axis running away from the reader is called.
+ * @param count - How many samples there are.
+ * @returns The sentence.
+ */
+export function cloudLabel(
+  xLabel: string,
+  yLabel: string,
+  zLabel: string,
+  count: number,
+): string {
+  return `A three-dimensional scatter plot of ${count} samples: ${xLabel} across, ${yLabel} up, and ${zLabel} into the picture.`;
+}

package/src/scatter3d/ui/scatterCloudProps.ts

@@ -0,0 +1,191 @@
+/**
+ * What a caller hands a `ScatterCloud`.
+ *
+ * The types live beside the component rather than inside it because the
+ * component's own file would otherwise be mostly prose, exactly as the flat
+ * scatter's are.
+ */
+
+import type { ReactNode } from 'react';
+
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type {
+  ScatterGroup,
+  ScatterPointOpen,
+} from '../../scatter/ui/scatterPlotProps.ts';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { CloudGesture } from '../core/cloudGesture.ts';
+import type { OrbitCamera } from '../core/orbitCamera.ts';
+
+export type { CloudGesture } from '../core/cloudGesture.ts';
+
+/** What a `ScatterCloud` needs. */
+export interface ScatterCloudProps {
+  /** Where every sample sits along the axis that runs left to right, in data units. */
+  x: ArrayLike<number>;
+  /** Along the axis that runs bottom to top, in the same order. */
+  y: ArrayLike<number>;
+  /** Along the axis that runs away from the reader. */
+  z: ArrayLike<number>;
+  /** Total width, in pixels, from `useContainerSize`. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /** What the axis running left to right is called, written on the frame. */
+  xLabel: string;
+  /** What the axis running bottom to top is called. */
+  yLabel: string;
+  /** What the axis running away from the reader is called. */
+  zLabel: string;
+  /**
+   * Which group each sample belongs to, as an index into `groups`. A sample
+   * with `-1`, or an index outside the range, is drawn in the muted ink and
+   * left out of every shell.
+   * @default undefined — every sample is one crowd
+   */
+  groupOf?: ArrayLike<number>;
+  /**
+   * The groups, in the order they are coloured and listed.
+   * @default undefined
+   */
+  groups?: readonly ScatterGroup[];
+  /**
+   * Which groups are drawn faint, by id — what a legend entry switches.
+   * @default undefined — every group is drawn in full
+   */
+  mutedGroups?: ReadonlySet<string>;
+  /**
+   * How large the group shells are, or `null` for none. A share is read in
+   * three dimensions here, so the same share gives a wider shell than the same
+   * call gives on the map — which is the point of asking for a share rather
+   * than for a distance.
+   * @default null
+   */
+  ellipsoid?: EllipseSize | null;
+  /**
+   * How many samples a group needs before it is given a shell. Below four a
+   * group has no volume to measure, so anything less is read as four.
+   * @default 4
+   */
+  ellipsoidMinimumPoints?: number;
+  /**
+   * How solid the glass is; `0` draws no shells at all.
+   * @default SHELL_FILL_OPACITY
+   */
+  ellipsoidFillOpacity?: number;
+  /**
+   * Whether each group's name is written once, over the middle of its own
+   * shell. It needs `groups`, since it is their names it writes.
+   * @default false
+   */
+  showGroupLabels?: boolean;
+  /**
+   * What each sample is called, written beside its own dot. A sample whose
+   * entry is `undefined` is left unnamed.
+   * @default undefined — no sample is named
+   */
+  pointLabels?: ReadonlyArray<string | undefined>;
+  /**
+   * Radius of a dot at the middle of the box, in pixels. One at the front is
+   * drawn larger and one at the back smaller, about this.
+   * @default 3.5
+   */
+  pointRadius?: number;
+  /**
+   * The index from which samples are drawn as outlines rather than filled,
+   * which is how one the model was fitted on is told from one placed into it
+   * afterwards.
+   * @default undefined — every sample is filled
+   */
+  outlinedFrom?: number;
+  /**
+   * What a drag does. The cloud never changes it on its own, because the
+   * control belongs in the bar above the figure rather than on top of the
+   * picture, so it is a plain setting rather than a controlled value.
+   * @default 'turn'
+   */
+  gesture?: CloudGesture;
+  /**
+   * Where the reader is standing. Present, the caller owns the camera, which
+   * is how a site puts a viewpoint in a share link.
+   * @default undefined — the cloud keeps its own
+   */
+  camera?: OrbitCamera;
+  /**
+   * Called with the camera every frame of a turn leaves behind.
+   * @default undefined
+   */
+  onCameraChange?: (camera: OrbitCamera) => void;
+  /**
+   * How far in the reader has zoomed; `1` is the resting size. Present, the
+   * caller owns it.
+   * @default undefined — the cloud keeps its own
+   */
+  zoom?: number;
+  /**
+   * Called with the zoom a wheel asks for.
+   * @default undefined
+   */
+  onZoomChange?: (zoom: number) => void;
+  /**
+   * Whether the wheel zooms the box. On, because a cloud that cannot be zoomed
+   * cannot be read where its groups overlap; a figure set in a column of prose
+   * should turn it off so a reader on their way past keeps their scroll.
+   * @default true
+   */
+  wheelZoom?: boolean;
+  /**
+   * The selected rows. Present, the caller owns the selection.
+   * @default undefined — the cloud keeps its own
+   */
+  selected?: readonly number[];
+  /**
+   * The rows selected before the reader touches anything.
+   * @default undefined
+   */
+  defaultSelected?: readonly number[];
+  /**
+   * Called when a lasso is released or a dot is tapped — never while a lasso
+   * is being drawn, and never while the box is being turned.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+  /**
+   * What a gesture with no modifier held does to the selection. Shift always
+   * adds and Alt always removes, exactly as on the map.
+   * @default 'replace'
+   */
+  selectMode?: ScatterSelectionMode;
+  /**
+   * Called with the row under the pointer, or `-1`.
+   * @default undefined
+   */
+  onHoverChange?: (index: number) => void;
+  /**
+   * Called when the reader double-clicks a sample, exactly as on the flat map:
+   * the gesture for "tell me more about this one", or "let me change it".
+   *
+   * It fires whichever gesture a drag is set to, because a double click is not
+   * a drag — a reader turning the box must not have to switch to Select to
+   * open a sample. The sample is selected first, since a double click is also
+   * two clicks; the map says why, and the two behave alike on purpose.
+   * @default undefined
+   */
+  onPointDoubleClick?: (point: ScatterPointOpen) => void;
+  /**
+   * What floats over the figure — a bar, a key, a caption, a card.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+  /**
+   * What a screen reader is told the figure shows.
+   * @default a sentence built from the three axis names and the sample count
+   */
+  label?: string;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}