react-cheminfo 0.10.0 → 0.11.0

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

package/src/scatter3d/ui/useOrbitDrag.ts

@@ -0,0 +1,220 @@
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { ScatterSurfaceProps } from '../../scatter/ui/lassoGesture.ts';
+import {
+  capturePointer,
+  dropFrame,
+  modifierMode,
+  scheduleFrame,
+  surfacePosition,
+} from '../../scatter/ui/lassoGesture.ts';
+import type { OrbitCamera } from '../core/orbitCamera.ts';
+import { orbitByDrag } from '../core/orbitCamera.ts';
+
+/** What {@link useOrbitDrag} needs. */
+export interface OrbitDragOptions {
+  /**
+   * Whether a drag turns the box at all. Off, the surface still reports a tap,
+   * so the reader can pick a sample while the drag belongs to something else.
+   * @default true
+   */
+  enabled?: boolean;
+  /** Called with the camera each frame of a drag leaves behind. */
+  onOrbit: (turn: (camera: OrbitCamera) => OrbitCamera) => void;
+  /**
+   * Called when a press and release happened in one place — a click, however
+   * the reader's hand shook.
+   * @default undefined
+   */
+  onTap?: (x: number, y: number, mode: ScatterSelectionMode) => void;
+  /**
+   * Called with the pointer's position on every frame it moves without
+   * turning, which is what raises the card under it.
+   * @default undefined
+   */
+  onMove?: (x: number, y: number) => void;
+  /**
+   * Called when the pointer leaves the surface without a drag in progress.
+   * @default undefined
+   */
+  onLeave?: () => void;
+  /**
+   * What a tap with no modifier held does to the selection.
+   * @default 'replace'
+   */
+  mode?: ScatterSelectionMode;
+}
+
+/** A drag that turns the box, and the taps it lets through. */
+export interface OrbitDrag {
+  /** Whether the box is being turned right now. */
+  turning: boolean;
+  /** Spread onto the transparent rectangle over the figure. */
+  surface: ScatterSurfaceProps;
+}
+
+/**
+ * Turning the box with the pointer.
+ *
+ * It is the lasso's twin and is built the same way — the pointer is captured
+ * on the way down so a drag that wanders off the figure keeps turning it, all
+ * three ways a capture can end lead to one function, and moves are coalesced
+ * to one a frame because a pointer emits many per frame and each one that
+ * reaches the caller repaints every dot and every face.
+ *
+ * A press that goes nowhere is a tap rather than a turn of no degrees, because
+ * nobody presses a mouse button without moving it a pixel or two and a reader
+ * who meant to pick a sample must not have to hold their hand still to do it.
+ * @param options - See {@link OrbitDragOptions}.
+ * @returns The drag. See {@link OrbitDrag}.
+ */
+export function useOrbitDrag(options: OrbitDragOptions): OrbitDrag {
+  const {
+    enabled = true,
+    onOrbit,
+    onTap,
+    onMove,
+    onLeave,
+    mode: restingMode = 'replace',
+  } = options;
+
+  const pointerRef = useRef<number | null>(null);
+  const lastRef = useRef({ x: 0, y: 0 });
+  const travelRef = useRef(0);
+  const frameRef = useRef<number | null>(null);
+  const pendingRef = useRef<PendingTurn | null>(null);
+  const [turning, setTurning] = useState(false);
+
+  const flush = useCallback(() => {
+    frameRef.current = null;
+    const next = pendingRef.current;
+    pendingRef.current = null;
+    if (next === null) return;
+    if (pointerRef.current === null) {
+      onMove?.(next.x, next.y);
+      return;
+    }
+    onOrbit((camera) => orbitByDrag(camera, next.dx, next.dy));
+  }, [onMove, onOrbit]);
+
+  const end = useCallback(
+    (event: ReactPointerEvent<Element>, commit: boolean) => {
+      if (event.pointerId !== pointerRef.current) return;
+      pointerRef.current = null;
+      pendingRef.current = null;
+      dropFrame(frameRef);
+      setTurning(false);
+      if (!commit || travelRef.current > TAP_SLACK) return;
+      const at = surfacePosition(event, 0, 0);
+      onTap?.(at.x, at.y, modifierMode(event, restingMode));
+    },
+    [onTap, restingMode],
+  );
+
+  const handleDown = useCallback((event: ReactPointerEvent<Element>) => {
+    if (pointerRef.current !== null || event.button > 0) return;
+    pointerRef.current = event.pointerId;
+    lastRef.current = { x: event.clientX, y: event.clientY };
+    travelRef.current = 0;
+    setTurning(true);
+    capturePointer(event);
+  }, []);
+
+  const handleMove = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      const active = pointerRef.current;
+      if (active === null) {
+        const at = surfacePosition(event, 0, 0);
+        pendingRef.current = { x: at.x, y: at.y, dx: 0, dy: 0 };
+        scheduleFrame(frameRef, flush);
+        return;
+      }
+      if (event.pointerId !== active) return;
+      const last = lastRef.current;
+      const dx = event.clientX - last.x;
+      const dy = event.clientY - last.y;
+      lastRef.current = { x: event.clientX, y: event.clientY };
+      travelRef.current += Math.abs(dx) + Math.abs(dy);
+      if (!enabled) return;
+      const waiting = pendingRef.current;
+      pendingRef.current = {
+        x: 0,
+        y: 0,
+        dx: (waiting?.dx ?? 0) + dx,
+        dy: (waiting?.dy ?? 0) + dy,
+      };
+      scheduleFrame(frameRef, flush);
+    },
+    [enabled, flush],
+  );
+
+  const handleUp = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      end(event, true);
+    },
+    [end],
+  );
+
+  const handleAbandon = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      end(event, false);
+    },
+    [end],
+  );
+
+  const handleLeave = useCallback(() => {
+    if (pointerRef.current !== null) return;
+    pendingRef.current = null;
+    onLeave?.();
+  }, [onLeave]);
+
+  const surface = useMemo<ScatterSurfaceProps>(
+    () => ({
+      onPointerDown: handleDown,
+      onPointerMove: handleMove,
+      onPointerUp: handleUp,
+      onPointerCancel: handleAbandon,
+      onLostPointerCapture: handleAbandon,
+      onPointerLeave: handleLeave,
+      style: {
+        cursor: enabled ? (turning ? 'grabbing' : 'grab') : 'default',
+        touchAction: 'none',
+      },
+    }),
+    [
+      enabled,
+      handleAbandon,
+      handleDown,
+      handleLeave,
+      handleMove,
+      handleUp,
+      turning,
+    ],
+  );
+
+  return { turning, surface };
+}
+
+/**
+ * How far a press may travel and still be a tap, in pixels of total travel.
+ *
+ * Generous on purpose: a mouse moves a pixel or two under the click of its own
+ * button, and a finger moves rather more, so a stricter number turns "pick
+ * this sample" into "turn the box by nothing at all" for anybody whose hand is
+ * not steady.
+ */
+const TAP_SLACK = 5;
+
+/** What the pointer has done since the last frame, waiting for the next. */
+interface PendingTurn {
+  /** Where it is, for a move that is not turning anything. */
+  x: number;
+  /** Where it is. */
+  y: number;
+  /** How far it has moved across since the last frame. */
+  dx: number;
+  /** How far it has moved down. */
+  dy: number;
+}

package/src/ui.ts

@@ -18,6 +18,7 @@ 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';

package/styles/chrome.css

@@ -29,13 +29,13 @@
   --shadow-md: 0 4px 14px rgb(16 32 48 / 10%);
   --shadow-lg: 0 12px 32px rgb(16 32 48 / 16%);
 
-  --header-height: 3.5rem;
+  --header-height: 3rem;
   --page-max: 84rem;
 }
 
 /* The size goes on `body`, never on `html`: `rem` has to stay the browser's
    16px, or every measurement written here shrinks by 6.25% and the bar renders
-   52.5px tall on one site and 56px on its sibling. */
+   45px tall on one site and 48px on its sibling. */
 body {
   font-family:
     -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial,
@@ -75,6 +75,14 @@ button {
   gap: 1rem;
 }
 
+/* A bar over something that fills the window rather than over a column of
+   content. The cap exists so the bar lines up with the page under it; on a
+   workbench there is no such column, and the centred bar reads as a mistake —
+   the brand floats inwards while the tool below runs to both edges. */
+.app-header__inner--full {
+  max-width: none;
+}
+
 .brand {
   display: flex;
   align-items: center;
@@ -148,7 +156,7 @@ button {
 .nav-link {
   display: inline-flex;
   align-items: center;
-  padding: 0.4rem 0.7rem;
+  padding: 0.3rem 0.7rem;
   border: 0;
   border-radius: 8px;
   background: none;
@@ -175,6 +183,16 @@ button {
   color: var(--accent);
 }
 
+/* A page the site cannot open yet: still listed, so the reader learns it is
+   there, but plainly not pressable. It never takes the hover wash, or it would
+   read as reachable under the pointer. */
+.nav-link--disabled,
+.nav-link--disabled:hover {
+  background: none;
+  color: var(--text-faint);
+  cursor: default;
+}
+
 .nav-link svg {
   width: 14px;
   height: 14px;
@@ -184,7 +202,8 @@ button {
    type is brought to the one the links beside them are set in. */
 .citation-button .bp6-button,
 .ecosystem-button .bp6-button {
-  padding: 0.4rem 0.7rem;
+  min-height: 0;
+  padding: 0.3rem 0.7rem;
   border-radius: 8px;
   color: var(--text-muted);
   font-size: 0.875rem;
@@ -214,6 +233,12 @@ button {
   margin: 0 auto;
 }
 
+/* Under a tool that fills the window, for the reason the bar runs full width
+   above it: the two edges of the chrome answer the two edges of the page. */
+.app-footer__inner--full {
+  max-width: none;
+}
+
 /* ── Printing ────────────────────────────────────────────────────────────── */
 
 /* Students print the cheatsheet. Let them, without the chrome. */