react-cheminfo 0.9.0 → 0.10.0

package/src/scatter/ui/scatterPlotProps.ts

@@ -0,0 +1,240 @@
+/**
+ * What a caller hands a {@link ScatterPlot}.
+ *
+ * The types live beside the component rather than inside it because the plot's
+ * own file would otherwise be mostly prose: a reader looking for what the
+ * component does should not have to scroll past twenty documented options to
+ * find it.
+ */
+
+import type { ReactNode } from 'react';
+
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import type { ChartAxisSpec } from '../../chart/ui/ChartFrame.tsx';
+import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
+import type { EllipseSize } from '../core/confidenceEllipse.ts';
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+
+import type { SelectionChange } from './useScatterSelection.ts';
+
+/** One group of points on a scatter plot. */
+export interface ScatterGroup {
+  /** A stable id, named in the legend and in a group's own callbacks. */
+  id: string;
+  /** What it is called, in the reader's words. */
+  label: string;
+  /** Its colour, normally from `chartSeriesColor`. */
+  color: string;
+}
+
+/** A point drawn over the cloud that is not a sample — a cluster centre. */
+export interface ScatterMarker {
+  /** What it is called, for its own hover card. */
+  label: string;
+  /** Horizontal position, in the plot's data units. */
+  x: number;
+  /** Vertical position, in the plot's data units. */
+  y: number;
+  /** Its colour. */
+  color: string;
+  /**
+   * The glyph it is drawn with, which is how a reader tells it from a sample
+   * without reading the legend first.
+   * @default 'cross'
+   */
+  shape?: OverlayMarkShape;
+}
+
+/** What {@link ScatterPlot} needs. */
+export interface ScatterPlotProps {
+  /** Horizontal coordinate of every point, in data units. */
+  x: ArrayLike<number>;
+  /** Vertical coordinate of every point, in the same order. */
+  y: ArrayLike<number>;
+  /** Total width, in pixels, from `useContainerSize`. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /** The horizontal axis. */
+  xAxis: ChartAxisSpec;
+  /** The vertical axis. */
+  yAxis: ChartAxisSpec;
+  /**
+   * Which group each point belongs to, as an index into `groups`. A point with
+   * `-1`, or an index outside the range, is drawn in the muted ink and left
+   * out of every outline.
+   * @default undefined — every point 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 outlines are, or `null` for none.
+   * @default null
+   */
+  ellipse?: EllipseSize | null;
+  /**
+   * How many points a group needs before it is outlined at all. Below it the
+   * shape says more about the sample than about the group.
+   * @default 3
+   */
+  ellipseMinimumPoints?: number;
+  /**
+   * How solid each group outline is; `0` draws nothing at all, since the fill
+   * is the whole outline. Turn it down when many groups overlap, since the
+   * fills compound where two of them cross.
+   * @default SCATTER_OUTLINE_FILL_OPACITY
+   */
+  ellipseFillOpacity?: number;
+  /**
+   * Whether each group's average is marked with a cross.
+   * @default false
+   */
+  showGroupMeans?: boolean;
+  /**
+   * Points drawn over the cloud that are not samples.
+   * @default undefined
+   */
+  markers?: readonly ScatterMarker[];
+  /**
+   * Radius of a dot, in pixels.
+   * @default 3.5
+   */
+  pointRadius?: number;
+  /**
+   * The index from which points are drawn as outlines rather than filled.
+   *
+   * It is how a sample the model was built from is told from one placed into
+   * it afterwards: the first kind helped choose where the axes point and is
+   * bound to sit somewhere reasonable, while the second can land anywhere.
+   * Points before it are filled, points from it on are hollow.
+   * @default undefined — every point is filled
+   */
+  outlinedFrom?: number;
+  /**
+   * What each point is called, written beside its own dot. A point whose entry
+   * is `undefined` is left unnamed, so a caller may label the twenty samples
+   * it cares about and leave the crowd alone.
+   *
+   * Names are placed so that no two overlap: one that cannot be fitted near
+   * its own dot is moved aside with a line back to it, and one with nowhere
+   * left to go is dropped rather than written over another.
+   * @default undefined — no point is named
+   */
+  pointLabels?: ReadonlyArray<string | undefined>;
+  /**
+   * Whether each group's name is written once, over the middle of that group.
+   * It needs `groupOf` and `groups`, since it is their names it writes. They
+   * are placed like `pointLabels`, biggest group first, so the name that
+   * speaks for the most samples keeps the middle of its own crowd.
+   * @default false
+   */
+  showGroupLabels?: boolean;
+  /**
+   * The selected rows. Present, the caller owns the selection; the outline
+   * drawn while a lasso is being dragged stays inside the component either
+   * way, so a controlled parent is never asked to re-render sixty times a
+   * second.
+   * @default undefined — the plot keeps its own
+   */
+  selected?: readonly number[];
+  /**
+   * The rows selected before the reader touches anything.
+   * @default undefined — nothing is selected
+   */
+  defaultSelected?: readonly number[];
+  /**
+   * Called when a lasso is released, a dot is clicked, or the keyboard commits
+   * — never while a lasso is being drawn.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+  /**
+   * What a drag does to the selection when no modifier is held. Shift always
+   * adds and Alt always removes, whatever this says.
+   * @default 'replace'
+   */
+  selectMode?: ScatterSelectionMode;
+  /**
+   * Called with the row under the pointer, or `-1` when the pointer is on
+   * none.
+   * @default undefined
+   */
+  onHoverChange?: (index: number) => void;
+  /**
+   * Called with the row whose card the reader pinned, or `-1`.
+   * @default undefined
+   */
+  onPinChange?: (index: number) => void;
+  /**
+   * Called when a lasso starts being drawn and again when it ends, and never
+   * in between.
+   *
+   * The floating chrome reads the drag from the overlay surface instead, which
+   * costs the caller nothing. This is for the piece of chrome that has to say
+   * what letting go will do while sitting *outside* the plot — a caption in the
+   * flow beneath it, which cannot reach that surface and must not cover the
+   * axis title to get at it.
+   * @default undefined
+   */
+  onLassoChange?: (drawing: boolean) => void;
+  /**
+   * Whether a drag on a touch screen draws a lasso rather than scrolling the
+   * page. Off, because a chart that traps the page scroll on a phone is a
+   * worse fault than a missing gesture.
+   * @default false
+   */
+  touchLasso?: boolean;
+  /**
+   * The frame the plot is zoomed into, in data units. Present, the caller owns
+   * the zoom; `null` shows the whole of both axes. A frame reaching outside
+   * the axes is pulled back inside them — the reader can never zoom out past
+   * the picture they started with.
+   * @default undefined — the plot keeps its own frame
+   */
+  viewport?: ChartViewport | null;
+  /**
+   * Called with the frame a wheel or a double click asks for, and with `null`
+   * when it has reached back out to the whole of the data.
+   * @default undefined
+   */
+  onViewportChange?: (viewport: ChartViewport | null) => void;
+  /**
+   * Whether the wheel zooms about the pointer, once the pointer has rested
+   * over the plot for `wheelZoomDelay`. Off, because a figure set in a page of
+   * prose must not take the reader's scroll on their way past it; a figure
+   * given a panel of its own should turn it on.
+   * @default false
+   */
+  wheelZoom?: boolean;
+  /**
+   * How long the pointer has to rest over the plot before the wheel is caught,
+   * in milliseconds.
+   * @default CHART_WHEEL_DWELL
+   */
+  wheelZoomDelay?: number;
+  /**
+   * What floats over the plot — an `OverlayBar`, a legend, a caption, a
+   * readout.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+  /**
+   * What a screen reader is told the plot shows.
+   * @default a sentence built from the two axis titles and the point count
+   */
+  label?: string;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}

package/src/scatter/ui/useLassoGesture.ts

@@ -0,0 +1,214 @@
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import type { LassoPath } from '../core/lassoPath.ts';
+import {
+  appendLassoPoint,
+  createLassoPath,
+  lassoPathData,
+  resetLassoPath,
+} from '../core/lassoPath.ts';
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+
+import type {
+  LassoGesture,
+  LassoGestureOptions,
+  ScatterSurfaceProps,
+} from './lassoGesture.ts';
+import {
+  DEFAULT_LASSO_MIN_DISTANCE,
+  MINIMUM_RING_VERTICES,
+  capturePointer,
+  dropFrame,
+  modifierMode,
+  scheduleFrame,
+  surfacePosition,
+} from './lassoGesture.ts';
+
+export type {
+  LassoGesture,
+  LassoGestureOptions,
+  ScatterSurfaceProps,
+} from './lassoGesture.ts';
+
+/**
+ * A free-hand outline drawn over a plot with the pointer.
+ *
+ * The pointer is captured on the way down, so a drag that wanders off the
+ * figure, or off the window, keeps drawing and still finishes. All three ways
+ * a capture can end lead to one function: a lasso left half-drawn because
+ * `pointercancel` was handled and `lostpointercapture` was not is the classic
+ * fault here, and it leaves a stroke on screen that nothing can clear.
+ *
+ * Moves are coalesced to one a frame, because a pointer emits many per frame
+ * and each one that reaches the caller costs a walk over every point.
+ * @param options - See {@link LassoGestureOptions}.
+ * @returns The gesture. See {@link LassoGesture}.
+ */
+export function useLassoGesture(
+  options: LassoGestureOptions = {},
+): LassoGesture {
+  const {
+    enabled = true,
+    touch = false,
+    minDistance = DEFAULT_LASSO_MIN_DISTANCE,
+    originX = 0,
+    originY = 0,
+    mode: restingMode = 'replace',
+    onDraw,
+    onComplete,
+    onClick,
+    onMove,
+    onLeave,
+  } = options;
+
+  const pathRef = useRef<LassoPath | null>(null);
+  pathRef.current ??= createLassoPath();
+  const path = pathRef.current;
+
+  const pointerRef = useRef<number | null>(null);
+  const modeRef = useRef<ScatterSelectionMode>(restingMode);
+  const frameRef = useRef<number | null>(null);
+  const pendingRef = useRef<PendingMove | null>(null);
+
+  const [drawing, setDrawing] = useState(false);
+  const [pathData, setPathData] = useState('');
+  const [mode, setMode] = useState<ScatterSelectionMode>(restingMode);
+
+  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, false);
+      return;
+    }
+    modeRef.current = next.mode;
+    setMode(next.mode);
+    if (appendLassoPoint(path, next.x, next.y, minDistance)) {
+      setPathData(lassoPathData(path, false));
+      onDraw?.(path, next.mode);
+    }
+    onMove?.(next.x, next.y, true);
+  }, [minDistance, onDraw, onMove, path]);
+
+  const end = useCallback(
+    (commit: boolean) => {
+      if (pointerRef.current === null) return;
+      pointerRef.current = null;
+      pendingRef.current = null;
+      dropFrame(frameRef);
+      const gesture = modeRef.current;
+      setDrawing(false);
+      setPathData('');
+      if (commit) {
+        if (path.length >= MINIMUM_RING_VERTICES) onComplete?.(path, gesture);
+        else onClick?.(path.xs[0] ?? 0, path.ys[0] ?? 0, gesture);
+      }
+      onDraw?.(null, gesture);
+      resetLassoPath(path);
+    },
+    [onClick, onComplete, onDraw, path],
+  );
+
+  const handleDown = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      if (!enabled || pointerRef.current !== null || event.button > 0) return;
+      if (event.pointerType === 'touch' && !touch) return;
+      const position = surfacePosition(event, originX, originY);
+      const gesture = modifierMode(event, restingMode);
+      pointerRef.current = event.pointerId;
+      modeRef.current = gesture;
+      resetLassoPath(path);
+      appendLassoPoint(path, position.x, position.y, 0);
+      setMode(gesture);
+      setDrawing(true);
+      setPathData(lassoPathData(path, false));
+      capturePointer(event);
+    },
+    [enabled, originX, originY, path, restingMode, touch],
+  );
+
+  const handleMove = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      const active = pointerRef.current;
+      if (active !== null && event.pointerId !== active) return;
+      const { x, y } = surfacePosition(event, originX, originY);
+      const drawn = active !== null;
+      pendingRef.current = {
+        x,
+        y,
+        mode: drawn ? modifierMode(event, restingMode) : restingMode,
+      };
+      scheduleFrame(frameRef, flush);
+    },
+    [flush, originX, originY, restingMode],
+  );
+
+  const handleUp = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      if (event.pointerId === pointerRef.current) end(true);
+    },
+    [end],
+  );
+
+  const handleAbandon = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      if (event.pointerId === pointerRef.current) end(false);
+    },
+    [end],
+  );
+
+  const handleLeave = useCallback(() => {
+    if (pointerRef.current !== null) return;
+    pendingRef.current = null;
+    onLeave?.();
+  }, [onLeave]);
+
+  const cancel = useCallback(() => {
+    end(false);
+  }, [end]);
+
+  const surface = useMemo<ScatterSurfaceProps>(
+    () => ({
+      onPointerDown: handleDown,
+      onPointerMove: handleMove,
+      onPointerUp: handleUp,
+      onPointerCancel: handleAbandon,
+      onLostPointerCapture: handleAbandon,
+      onPointerLeave: handleLeave,
+      style: {
+        cursor: enabled ? 'crosshair' : 'default',
+        touchAction: touch ? 'none' : 'auto',
+      },
+    }),
+    [
+      enabled,
+      handleAbandon,
+      handleDown,
+      handleLeave,
+      handleMove,
+      handleUp,
+      touch,
+    ],
+  );
+
+  return {
+    surface,
+    drawing,
+    pathData,
+    mode: drawing ? mode : restingMode,
+    cancel,
+  };
+}
+
+/** The last position the pointer reported, waiting for the next frame. */
+interface PendingMove {
+  /** Horizontal position, in the points' space. */
+  x: number;
+  /** Vertical position. */
+  y: number;
+  /** What a release at that moment would have done. */
+  mode: ScatterSelectionMode;
+}

package/src/scatter/ui/usePointHover.ts

@@ -0,0 +1,187 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import type { ScreenPoints } from '../core/screenPoints.ts';
+import { nearestPointIndex } from '../core/screenPoints.ts';
+
+/** Where a hover card is placed, and what it is about. */
+export interface HoverAnchor {
+  /** Horizontal position to place the card against, in the plot's pixels. */
+  x: number;
+  /** Vertical position. */
+  y: number;
+  /** The row the card describes. */
+  index: number;
+  /** Whether the reader pinned it, which is what stops it following. */
+  pinned: boolean;
+}
+
+/** What {@link usePointHover} needs. */
+export interface PointHoverOptions {
+  /** Where every point sits on screen. */
+  points: ScreenPoints;
+  /**
+   * How far from the pointer a point still counts as aimed at, in pixels.
+   * Wider than a dot: a reader aims at a cloud, not at three and a half
+   * pixels, and a card that only appears on a direct hit reads as broken.
+   * @default 12
+   */
+  radius?: number;
+  /**
+   * One entry per point, a zero meaning it cannot be hovered — which is how a
+   * muted group stops answering for points the reader can barely see.
+   * @default undefined — every point can be hovered
+   */
+  included?: Uint8Array;
+  /**
+   * Whether a click keeps the card open. Worth leaving on wherever the card
+   * holds more than a line: an unpinned card follows the pointer, so a reader
+   * moving towards a long list pushes it away and never reaches it.
+   * @default true
+   */
+  pinnable?: boolean;
+  /**
+   * Called with the row under the pointer, or `-1`, whenever that changes.
+   * @default undefined
+   */
+  onHoverChange?: (index: number) => void;
+  /**
+   * Called with the pinned row, or `-1` when the card is let go.
+   * @default undefined
+   */
+  onPinChange?: (index: number) => void;
+}
+
+/** The point a card is about, and how the reader moves it. */
+export interface PointHoverApi {
+  /** The row the card describes: the pinned one, else the hovered one, else `-1`. */
+  index: number;
+  /** The row under the pointer, whether or not a card is pinned. */
+  hovered: number;
+  /** Whether the card is pinned. */
+  pinned: boolean;
+  /** Where to place the card, or `null` when there is nothing to place. */
+  anchor: HoverAnchor | null;
+  /** Report a pointer position, in the same space the points were measured in. */
+  moveTo: (x: number, y: number) => void;
+  /** Report the pointer leaving the figure. */
+  leave: () => void;
+  /** Pin the row under the pointer, or let a pinned card go. */
+  togglePin: () => void;
+  /** Pin a named row, anchored on the point itself — what a key press uses. */
+  pin: (index: number) => void;
+  /** Let the card go. */
+  unpin: () => void;
+}
+
+/**
+ * The point under the pointer, and the card that says everything about it.
+ *
+ * The nearest point within a radius rather than the one actually under the
+ * pointer, because a scatter is aimed at with a hand and not with a pixel; the
+ * search runs once per position reported, so give it positions that have
+ * already been coalesced to a frame.
+ *
+ * Pinning is the part that matters for a card with a long list in it. An
+ * unpinned card follows the pointer, so a reader moving to read it pushes it
+ * away and the list can never be reached, let alone selected from. A pinned
+ * card stops where it was and stays on the row it was about, while the hover
+ * carries on underneath so the ring still tracks the pointer.
+ * @param options - See {@link PointHoverOptions}.
+ * @returns The hover. See {@link PointHoverApi}.
+ */
+export function usePointHover(options: PointHoverOptions): PointHoverApi {
+  const {
+    points,
+    radius = DEFAULT_HOVER_RADIUS,
+    included,
+    pinnable = true,
+    onHoverChange,
+    onPinChange,
+  } = options;
+
+  const [hovered, setHovered] = useState(-1);
+  const [position, setPosition] = useState<PointerPosition | null>(null);
+  const [pinnedAnchor, setPinnedAnchor] = useState<HoverAnchor | null>(null);
+  const hoveredRef = useRef(-1);
+
+  const reportHover = useCallback(
+    (index: number) => {
+      if (hoveredRef.current === index) return;
+      hoveredRef.current = index;
+      setHovered(index);
+      onHoverChange?.(index);
+    },
+    [onHoverChange],
+  );
+
+  const moveTo = useCallback(
+    (x: number, y: number) => {
+      setPosition({ x, y });
+      reportHover(nearestPointIndex(points, x, y, radius, included));
+    },
+    [included, points, radius, reportHover],
+  );
+
+  const leave = useCallback(() => {
+    setPosition(null);
+    reportHover(-1);
+  }, [reportHover]);
+
+  const unpin = useCallback(() => {
+    if (pinnedAnchor === null) return;
+    setPinnedAnchor(null);
+    onPinChange?.(-1);
+  }, [onPinChange, pinnedAnchor]);
+
+  const pin = useCallback(
+    (index: number) => {
+      const x = points.x[index];
+      const y = points.y[index];
+      if (x === undefined || y === undefined) return;
+      setPinnedAnchor({ x, y, index, pinned: true });
+      onPinChange?.(index);
+    },
+    [onPinChange, points],
+  );
+
+  const togglePin = useCallback(() => {
+    if (!pinnable) return;
+    if (pinnedAnchor !== null) {
+      unpin();
+      return;
+    }
+    const index = hoveredRef.current;
+    if (index === -1 || position === null) return;
+    setPinnedAnchor({ x: position.x, y: position.y, index, pinned: true });
+    onPinChange?.(index);
+  }, [onPinChange, pinnable, pinnedAnchor, position, unpin]);
+
+  const anchor = useMemo<HoverAnchor | null>(() => {
+    if (pinnedAnchor !== null) return pinnedAnchor;
+    if (hovered === -1 || position === null) return null;
+    return { x: position.x, y: position.y, index: hovered, pinned: false };
+  }, [hovered, pinnedAnchor, position]);
+
+  return {
+    index: pinnedAnchor === null ? hovered : pinnedAnchor.index,
+    hovered,
+    pinned: pinnedAnchor !== null,
+    anchor,
+    moveTo,
+    leave,
+    togglePin,
+    pin,
+    unpin,
+  };
+}
+
+/** How far a point may be from the pointer and still be the one meant. */
+export const DEFAULT_HOVER_RADIUS = 12;
+
+/** The last place the pointer was seen, in the points' own space. */
+interface PointerPosition {
+  /** Horizontal position, in pixels. */
+  x: number;
+  /** Vertical position, in pixels. */
+  y: number;
+}