react-cheminfo 0.11.0 → 0.12.0

package/src/scatter/ui/useLassoGesture.ts

@@ -1,5 +1,5 @@
 import type { PointerEvent as ReactPointerEvent } from 'react';
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 
 import type { LassoPath } from '../core/lassoPath.ts';
 import {
@@ -10,38 +10,22 @@ import {
 } from '../core/lassoPath.ts';
 import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
 
-import type {
-  LassoGesture,
-  LassoGestureOptions,
-  ScatterSurfaceProps,
-} from './lassoGesture.ts';
+import type { LassoGesture, LassoGestureOptions } 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';
+import { useCapturedPointer } from './useCapturedPointer.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.
+ * The pointer is claimed through `useCapturedPointer`, which is what makes a
+ * drag that wanders off the figure keep drawing and still finish, and what
+ * coalesces the moves to one a frame — each one that reaches the caller costs
+ * a walk over every point. What is left here is the path itself.
  * @param options - See {@link LassoGestureOptions}.
  * @returns The gesture. See {@link LassoGesture}.
  */
@@ -66,140 +50,96 @@ export function useLassoGesture(
   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(
+  const press = useCallback(
     (event: ReactPointerEvent<Element>) => {
-      if (!enabled || pointerRef.current !== null || event.button > 0) return;
-      if (event.pointerType === 'touch' && !touch) return;
+      if (!enabled) return false;
       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);
+      return true;
     },
-    [enabled, originX, originY, path, restingMode, touch],
+    [enabled, originX, originY, path, restingMode],
   );
 
-  const handleMove = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      const active = pointerRef.current;
-      if (active !== null && event.pointerId !== active) return;
+  const follow = useCallback(
+    (event: ReactPointerEvent<Element>, claimed: boolean) => {
       const { x, y } = surfacePosition(event, originX, originY);
-      const drawn = active !== null;
-      pendingRef.current = {
-        x,
-        y,
-        mode: drawn ? modifierMode(event, restingMode) : restingMode,
-      };
-      scheduleFrame(frameRef, flush);
+      const gesture = claimed ? modifierMode(event, restingMode) : restingMode;
+      pendingRef.current = { x, y, mode: gesture };
+      return true;
     },
-    [flush, originX, originY, restingMode],
+    [originX, originY, restingMode],
   );
 
-  const handleUp = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      if (event.pointerId === pointerRef.current) end(true);
+  const flush = useCallback(
+    (claimed: boolean) => {
+      const next = pendingRef.current;
+      pendingRef.current = null;
+      if (next === null) return;
+      if (!claimed) {
+        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);
     },
-    [end],
+    [minDistance, onDraw, onMove, path],
   );
 
-  const handleAbandon = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      if (event.pointerId === pointerRef.current) end(false);
+  const finish = useCallback(
+    (_event: ReactPointerEvent<Element> | null, commit: boolean) => {
+      pendingRef.current = null;
+      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);
     },
-    [end],
+    [onClick, onComplete, onDraw, path],
   );
 
-  const handleLeave = useCallback(() => {
-    if (pointerRef.current !== null) return;
+  const forget = useCallback(() => {
     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,
-    ],
-  );
+  const { surface, abandon } = useCapturedPointer({
+    touch,
+    cursor: enabled ? 'crosshair' : 'default',
+    onPress: press,
+    onMove: follow,
+    onFrame: flush,
+    onRelease: finish,
+    onLeave: forget,
+  });
 
   return {
     surface,
     drawing,
     pathData,
     mode: drawing ? mode : restingMode,
-    cancel,
+    cancel: abandon,
   };
 }
 

package/src/scatter/ui/useScatterFrame.ts

@@ -3,13 +3,15 @@ import { useCallback, useMemo, useState } from 'react';
 
 import { chartAxisScale } from '../../chart/core/chartAxisScale.ts';
 import type { ChartViewport } from '../../chart/core/chartViewport.ts';
-import { chartZoomViewport } from '../../chart/core/chartViewport.ts';
 import type { ChartAxisSpec } from '../../chart/ui/ChartFrame.tsx';
 import { useWheelZoom } from '../../chart/ui/useWheelZoom.ts';
 import { pointsWithinBounds } from '../core/screenPoints.ts';
 
 import type { ScatterPlotView } from './scatterPlotModel.ts';
-import { scatterPlotGeometry } from './scatterPlotModel.ts';
+import {
+  scatterPlotGeometry,
+  scatterWheelViewport,
+} from './scatterPlotModel.ts';
 
 /** What {@link useScatterFrame} needs. */
 export interface ScatterFrameOptions {
@@ -130,18 +132,7 @@ export function useScatterFrame(options: ScatterFrameOptions): ScatterFrame {
     enabled: wheelZoom,
     delay: wheelZoomDelay,
     onZoom: (alongX, alongY, factor) => {
-      const frame = shown ?? full;
-      change(
-        chartZoomViewport(
-          full,
-          shown,
-          along(frame.x, alongX),
-          // The vertical axis grows upward while the pointer's share grows
-          // downward, so the share is read from the top of the frame.
-          along(frame.y, 1 - alongY),
-          factor,
-        ),
-      );
+      change(scatterWheelViewport(full, shown, alongX, alongY, factor));
     },
   });
 
@@ -179,13 +170,3 @@ function nicedDomain(axis: ChartAxisSpec): readonly [number, number] {
     nice: axis.nice,
   }).domain;
 }
-
-/**
- * The value a share of the way along a range stands for.
- * @param domain - The range.
- * @param share - How far along, from 0 to 1.
- * @returns The value.
- */
-function along(domain: readonly [number, number], share: number): number {
-  return domain[0] + share * (domain[1] - domain[0]);
-}

package/src/scatter/ui/useScatterInteraction.ts

@@ -1,113 +1,21 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
 
 import type { LassoPath } from '../core/lassoPath.ts';
 import { pointsInPolygon } from '../core/polygon.ts';
 import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
-import type { ScreenPoints } from '../core/screenPoints.ts';
 import { nearestPointIndex } from '../core/screenPoints.ts';
 
-import type { LassoGesture, ScatterSurfaceProps } from './lassoGesture.ts';
+import type { SurfaceEvent } from './lassoGesture.ts';
+import { surfacePosition } from './lassoGesture.ts';
+import type {
+  ScatterInteractionApi,
+  ScatterInteractionOptions,
+} from './scatterInteractionTypes.ts';
 import { useLassoGesture } from './useLassoGesture.ts';
-import type { PointHoverApi } from './usePointHover.ts';
 import { DEFAULT_HOVER_RADIUS, usePointHover } from './usePointHover.ts';
-import type { ScatterKeyboardApi } from './useScatterKeyboard.ts';
 import { useScatterKeyboard } from './useScatterKeyboard.ts';
-import type {
-  ScatterSelectionApi,
-  SelectionChange,
-} from './useScatterSelection.ts';
 import { useScatterSelection } from './useScatterSelection.ts';
 
-/** What {@link useScatterInteraction} needs. */
-export interface ScatterInteractionOptions {
-  /** Where every point sits on screen; how many there are is read from it. */
-  points: ScreenPoints;
-  /**
-   * Where the plot's left edge is, so a gesture lands in the same space the
-   * points were measured in.
-   * @default 0
-   */
-  originX?: number;
-  /**
-   * Where its top edge is.
-   * @default 0
-   */
-  originY?: number;
-  /**
-   * The selected rows when the caller owns them.
-   * @default undefined — the hook keeps them
-   */
-  selected?: readonly number[];
-  /**
-   * The rows selected before the reader touches anything.
-   * @default undefined
-   */
-  defaultSelected?: readonly number[];
-  /**
-   * Called once per settled gesture, never during a drag.
-   * @default undefined
-   */
-  onSelectionChange?: (change: SelectionChange) => void;
-  /**
-   * What a gesture with no modifier held does to the selection.
-   * @default 'replace'
-   */
-  selectMode?: ScatterSelectionMode;
-  /**
-   * Whether a drag draws a lasso at all. The hover card works either way.
-   * @default true
-   */
-  enabled?: boolean;
-  /**
-   * Whether a finger draws one rather than scrolling the page.
-   * @default false
-   */
-  touchLasso?: boolean;
-  /**
-   * How near the pointer a point must be to be hovered or clicked, in pixels.
-   * @default 12
-   */
-  hoverRadius?: number;
-  /**
-   * One entry per point, a zero meaning it cannot be hovered or clicked.
-   * @default undefined — every point can be
-   */
-  included?: Uint8Array;
-  /**
-   * Called with the row under the pointer, or `-1`.
-   * @default undefined
-   */
-  onHoverChange?: (index: number) => void;
-  /**
-   * Called with the row whose card is pinned, or `-1`.
-   * @default undefined
-   */
-  onPinChange?: (index: number) => void;
-}
-
-/** Everything a scatter needs to be touched, in five pieces. */
-export interface ScatterInteractionApi {
-  /** Spread onto the transparent rectangle over the plot. */
-  surface: ScatterSurfaceProps;
-  /** What is picked, including what a half-drawn lasso would pick. */
-  selection: ScatterSelectionApi;
-  /** The point a card is about, and where to put it. */
-  hover: PointHoverApi;
-  /** The roving cursor, whose `onKeyDown` goes on the focusable wrapper. */
-  keyboard: ScatterKeyboardApi;
-  /** The outline being drawn, for the plot to stroke. */
-  lasso: LassoGesture;
-  /**
-   * Which point is near a position, or `-1`.
-   *
-   * The same search a click runs, offered on its own so that a gesture the
-   * hook does not own — a double click, which the plot answers because only
-   * the plot knows what a double click on empty ground means — asks it in the
-   * same words and with the same radius.
-   */
-  pointAt: (x: number, y: number) => number;
-}
-
 /**
  * Every way a reader touches a scatter, wired together.
  *
@@ -141,6 +49,7 @@ export function useScatterInteraction(
     included,
     onHoverChange,
     onPinChange,
+    onLassoChange,
   } = options;
 
   const radius = hoverRadius ?? DEFAULT_HOVER_RADIUS;
@@ -193,7 +102,7 @@ export function useScatterInteraction(
     [caught, selectMask],
   );
 
-  const onClick = useCallback(
+  const clickAt = useCallback(
     (x: number, y: number, mode: ScatterSelectionMode) => {
       const index = nearestPointIndex(points, x, y, radius, included);
       if (index === -1) {
@@ -222,7 +131,7 @@ export function useScatterInteraction(
     mode: selectMode,
     onDraw,
     onComplete,
-    onClick,
+    onClick: clickAt,
     onMove,
     onLeave: leave,
   });
@@ -247,6 +156,29 @@ export function useScatterInteraction(
     [included, points, radius],
   );
 
+  const openAt = useCallback(
+    (event: SurfaceEvent) => {
+      const at = surfacePosition(event, originX, originY);
+      const index = pointAt(at.x, at.y);
+      if (index === -1) return null;
+      const { clientX, clientY } = event;
+      return { index, x: at.x, y: at.y, clientX, clientY };
+    },
+    [originX, originY, pointAt],
+  );
+
+  // Held in a ref so an inline arrow, which is how every caller writes it, does
+  // not put the callback in the effect's dependencies and report a drag that
+  // never changed on every render.
+  const reportLasso = useRef(onLassoChange);
+  useLayoutEffect(() => {
+    reportLasso.current = onLassoChange;
+  });
+  const drawing = lasso.drawing;
+  useEffect(() => {
+    reportLasso.current?.(drawing);
+  }, [drawing]);
+
   return {
     surface: lasso.surface,
     selection,
@@ -254,5 +186,7 @@ export function useScatterInteraction(
     keyboard,
     lasso,
     pointAt,
+    clickAt,
+    openAt,
   };
 }

package/src/scatter/ui/useScatterLabels.ts

@@ -0,0 +1,88 @@
+import { useMemo } from 'react';
+
+import type { ScreenPoints } from '../core/screenPoints.ts';
+
+import type { ScatterGroup } from './scatterFigureProps.ts';
+import {
+  SCATTER_GROUP_LABEL_SIZE,
+  SCATTER_LABEL_SIZE,
+} from './scatterLabelBoxes.ts';
+import type { PlacedScatterLabel } from './scatterLabelPlacement.ts';
+import { placeScatterLabels } from './scatterLabelPlacement.ts';
+import { scatterGroupLabels, scatterPointLabels } from './scatterLabels.ts';
+
+/** What {@link useScatterLabels} places. */
+interface ScatterLabelsOptions {
+  /** What each point is called, or nothing when no point is named. */
+  pointLabels: ReadonlyArray<string | undefined> | undefined;
+  /** Whether each group's name is written over its own crowd. */
+  showGroupLabels: boolean;
+  /** The groups, whose names a crowd is written with. */
+  groups: readonly ScatterGroup[] | undefined;
+  /** Which group each point belongs to. */
+  groupOf: ArrayLike<number> | undefined;
+  /** The colour of each group, which its words take. */
+  colors: readonly string[];
+  /** Radius of a dot, which a word stands clear of. */
+  radius: number;
+  /** The rectangle every word has to stay inside. */
+  bounds: { x: number; y: number; width: number; height: number };
+}
+
+/** The words a scatter figure writes, already seated. */
+export interface ScatterLabels {
+  /** Each named point's own name, or nothing when no point is named. */
+  named: readonly PlacedScatterLabel[] | undefined;
+  /** Each group's name, or nothing when group names are off. */
+  crowds: readonly PlacedScatterLabel[] | undefined;
+}
+
+/**
+ * The names a scatter figure writes, placed so that no two overlap.
+ *
+ * Both figures place their words the same way from the same screen positions,
+ * so a name moves with its dot on the map and in the turning cloud alike. The
+ * placing runs only when the positions or the words change, never on a hover.
+ * @param points - Where every point sits, in the figure's pixels.
+ * @param options - See {@link ScatterLabelsOptions}.
+ * @returns The seated words. See {@link ScatterLabels}.
+ */
+export function useScatterLabels(
+  points: ScreenPoints,
+  options: ScatterLabelsOptions,
+): ScatterLabels {
+  const { pointLabels, showGroupLabels, groups, groupOf } = options;
+  const { colors, radius, bounds } = options;
+
+  const named = useMemo(
+    () =>
+      pointLabels === undefined
+        ? undefined
+        : placeScatterLabels(
+            scatterPointLabels(points, pointLabels, { groupOf, colors }),
+            { fontSize: SCATTER_LABEL_SIZE, radius, bounds },
+          ),
+    [points, pointLabels, groupOf, colors, radius, bounds],
+  );
+  const crowds = useMemo(
+    () =>
+      showGroupLabels && groups !== undefined
+        ? placeScatterLabels(
+            scatterGroupLabels(
+              points,
+              groups.map((group) => group.label),
+              { groupOf, colors },
+            ),
+            {
+              fontSize: SCATTER_GROUP_LABEL_SIZE,
+              bold: true,
+              centered: true,
+              radius,
+              bounds,
+            },
+          )
+        : undefined,
+    [points, showGroupLabels, groups, groupOf, colors, radius, bounds],
+  );
+  return { named, crowds };
+}