react-cheminfo 0.11.0 → 0.12.0

package/src/scatter/ui/scatterOutlineShape.tsx

@@ -11,6 +11,7 @@
 import type { ReactElement } from 'react';
 
 import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartRoundPixel } from '../../chart/core/chartScale.ts';
 import type { ConfidenceEllipse } from '../core/confidenceEllipse.ts';
 import type { PixelEllipse } from '../core/ellipseProjection.ts';
 import { ellipsePolygon, projectEllipse } from '../core/ellipseProjection.ts';
@@ -97,11 +98,11 @@ function projectedOutline(
         key={group}
         {...shared}
         {...fillOf(ink)}
-        cx={round(cx)}
-        cy={round(cy)}
-        rx={round(rx)}
-        ry={round(ry)}
-        transform={`rotate(${round(angleDegrees)} ${round(cx)} ${round(cy)})`}
+        cx={chartRoundPixel(cx)}
+        cy={chartRoundPixel(cy)}
+        rx={chartRoundPixel(rx)}
+        ry={chartRoundPixel(ry)}
+        transform={`rotate(${chartRoundPixel(angleDegrees)} ${chartRoundPixel(cx)} ${chartRoundPixel(cy)})`}
       />
     );
   }
@@ -115,10 +116,10 @@ function projectedOutline(
       fill="none"
       stroke={ink.color}
       strokeWidth={SEGMENT_STROKE_WIDTH}
-      x1={round(cx - alongX)}
-      y1={round(cy - alongY)}
-      x2={round(cx + alongX)}
-      y2={round(cy + alongY)}
+      x1={chartRoundPixel(cx - alongX)}
+      y1={chartRoundPixel(cy - alongY)}
+      x2={chartRoundPixel(cx + alongX)}
+      y2={chartRoundPixel(cy + alongY)}
     />
   );
 }
@@ -141,8 +142,8 @@ function sampledOutline(
   for (let index = 0; index < outline.length; index++) {
     const point = outline[index];
     if (point === undefined) continue;
-    const px = round(scaleX.offset + point.x * scaleX.factor);
-    const py = round(scaleY.offset + point.y * scaleY.factor);
+    const px = chartRoundPixel(scaleX.offset + point.x * scaleX.factor);
+    const py = chartRoundPixel(scaleY.offset + point.y * scaleY.factor);
     path += `${index === 0 ? 'M' : 'L'}${px} ${py}`;
   }
   return (
@@ -165,5 +166,3 @@ function fillOf(ink: ScatterOutlineInk): {
   if (!(share > 0)) return { fill: 'none' };
   return { fill: ink.color, fillOpacity: share };
 }
-
-const round = (value: number): number => Math.round(value * 100) / 100;

package/src/scatter/ui/scatterPlotModel.ts

@@ -8,18 +8,24 @@
  * hook cannot be called from inside the frame's render callback.
  */
 
-import { chartAxisScale } from '../../chart/core/chartAxisScale.ts';
 import type { ChartScale } from '../../chart/core/chartScale.ts';
-import { chartScale } from '../../chart/core/chartScale.ts';
-import type { ChartAxisSpec } from '../../chart/ui/ChartFrame.tsx';
-import { chartOuterRoom, chartPlotArea } from '../../chart/ui/chartStyles.ts';
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import { chartZoomViewport } from '../../chart/core/chartViewport.ts';
+import type {
+  ChartAxisSpec,
+  ChartFrameRender,
+} from '../../chart/ui/ChartFrame.tsx';
+import { chartFrameGeometry } from '../../chart/ui/chartFrameGeometry.ts';
 import type { ScreenPoints } from '../core/screenPoints.ts';
 
+import type { ScatterGroup } from './scatterFigureProps.ts';
 import type { ScatterPixelMark } from './scatterMarkGlyph.tsx';
-import type { ScatterGroup, ScatterMarker } from './scatterPlotProps.ts';
+import type { ScatterMarker } from './scatterPlotProps.ts';
 
 /** Where a scatter's data lands, and the rectangle it lands in. */
 export interface ScatterPlotView {
+  /** The frame's own geometry, handed to `ChartFrame` so it is not worked out twice. */
+  geometry: ChartFrameRender;
   /** The rectangle gestures are taken on, ready to spread onto a `<rect>`. */
   rect: { x: number; y: number; width: number; height: number };
   /** Data to pixels, horizontally. */
@@ -41,11 +47,10 @@ export interface ScatterGroupInk {
 /**
  * The plot rectangle, the two mappings, and every point in pixels.
  *
- * It repeats what `ChartFrame` works out for itself, from the same inputs and
- * through the same two functions, because the interaction needs the positions
- * before the frame has drawn anything and a hook cannot be called from inside
- * the frame's render callback. Both answers come out of `chartPlotArea`, so
- * they cannot drift apart without the frame's own tests saying so.
+ * The interaction needs the positions before the frame has drawn anything, and
+ * a hook cannot be called from inside the frame's render callback, so the
+ * geometry is worked out here with `chartFrameGeometry` and handed to the
+ * frame: the dots, the hit tests and the axes all read that one answer.
  * @param x - Horizontal coordinate of every point, in data units.
  * @param y - Vertical coordinate, in the same order.
  * @param width - Total width of the figure, in pixels.
@@ -62,30 +67,8 @@ export function scatterPlotGeometry(
   xAxis: ChartAxisSpec,
   yAxis: ChartAxisSpec,
 ): ScatterPlotView {
-  const across = chartAxisScale(xAxis.domain[0], xAxis.domain[1], {
-    count: xAxis.tickCount,
-    nice: xAxis.nice,
-  });
-  const up = chartAxisScale(yAxis.domain[0], yAxis.domain[1], {
-    count: yAxis.tickCount,
-    nice: yAxis.nice,
-  });
-  const plot = chartPlotArea(
-    width,
-    height,
-    {},
-    {
-      bottom: chartOuterRoom('bottom', xAxis, across),
-      left: chartOuterRoom('left', yAxis, up),
-    },
-  );
-  const toX = chartScale(
-    across.domain[0],
-    across.domain[1],
-    plot.left,
-    plot.right,
-  );
-  const toY = chartScale(up.domain[0], up.domain[1], plot.bottom, plot.top);
+  const geometry = chartFrameGeometry(width, height, xAxis, yAxis);
+  const { plot, x: toX, y: toY } = geometry;
   const total = Math.min(x.length, y.length);
   const pixelX = new Float64Array(total);
   const pixelY = new Float64Array(total);
@@ -94,6 +77,7 @@ export function scatterPlotGeometry(
     pixelY[index] = toY.offset + (y[index] ?? Number.NaN) * toY.factor;
   }
   return {
+    geometry,
     rect: { x: plot.left, y: plot.top, width: plot.width, height: plot.height },
     toX,
     toY,
@@ -156,7 +140,7 @@ export function scatterPixelMarks(
  * A figure with no label at all is hidden from a reader entirely, which for a
  * plot carrying the whole result is worse than a sentence nobody wrote by
  * hand. The axes are named the way the plot names them, so a reader hearing
- * `PC 2 against PC 1` hears the same words a sighted reader sees.
+ * `PC2 against PC1` hears the same words a sighted reader sees.
  * @param xAxis - The horizontal axis.
  * @param yAxis - The vertical axis.
  * @param count - How many points are drawn.
@@ -172,6 +156,36 @@ export function scatterPlotLabel(
   return `A scatter plot of ${count} points, ${up} against ${across}.`;
 }
 
+/**
+ * The frame a wheel turned over a scatter asks for.
+ *
+ * The pointer arrives as a share of the plot rectangle measured from its top
+ * left corner. The vertical axis grows upward while that share grows downward,
+ * so the vertical share is read from the top of the frame.
+ * @param full - What the axes cover unzoomed.
+ * @param shown - The frame showing, or `null` when all of it is.
+ * @param alongX - How far across the plot the pointer is, from 0 to 1.
+ * @param alongY - How far down it is, from 0 to 1.
+ * @param factor - How much wider the frame becomes; below one it narrows.
+ * @returns The new frame, or `null` once it covers everything again.
+ */
+export function scatterWheelViewport(
+  full: ChartViewport,
+  shown: ChartViewport | null,
+  alongX: number,
+  alongY: number,
+  factor: number,
+): ChartViewport | null {
+  const frame = shown ?? full;
+  return chartZoomViewport(
+    full,
+    shown,
+    along(frame.x, alongX),
+    along(frame.y, 1 - alongY),
+    factor,
+  );
+}
+
 /**
  * The ring being dragged. Dashed, and filled only faintly: it is a gesture in
  * progress and not anything the data says, and a solid shape over the cloud
@@ -198,3 +212,13 @@ export const SCATTER_HOVER_SLACK = 8;
  * of the group is still there — a reader mutes a group to see past it.
  */
 const MUTED_OPACITY = 0.2;
+
+/**
+ * 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/scatterPlotProps.ts

@@ -1,31 +1,21 @@
 /**
- * What a caller hands a {@link ScatterPlot}.
+ * What a caller hands a `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.
+ * own file would otherwise be mostly prose. What the plot shares with the
+ * cloud is declared in `scatterFigureProps.ts`; this adds the frame, the zoom
+ * and the marks only a flat map has.
  */
 
-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;
-}
+import type {
+  ScatterGroupProps,
+  ScatterInteractionProps,
+} from './scatterFigureProps.ts';
 
 /** A point drawn over the cloud that is not a sample — a cluster centre. */
 export interface ScatterMarker {
@@ -45,27 +35,9 @@ export interface ScatterMarker {
   shape?: OverlayMarkShape;
 }
 
-/** A point the reader opened, and where they opened it. */
-export interface ScatterPointOpen {
-  /** Its row, as an index into the arrays the caller passed. */
-  index: number;
-  /** Where the reader clicked, in pixels from the figure's left edge. */
-  x: number;
-  /** Where they clicked, in pixels from its top edge. */
-  y: number;
-  /**
-   * Where they clicked in the window, which is what an editor floating over
-   * the page — a menu, a popover, a dialog anchored on the point — is placed
-   * from. The pair above is the figure's own space, for a caller drawing
-   * inside it.
-   */
-  clientX: number;
-  /** Where they clicked in the window. */
-  clientY: number;
-}
-
-/** What {@link ScatterPlot} needs. */
-export interface ScatterPlotProps {
+/** What `ScatterPlot` needs. */
+export interface ScatterPlotProps
+  extends ScatterGroupProps, ScatterInteractionProps {
   /** Horizontal coordinate of every point, in data units. */
   x: ArrayLike<number>;
   /** Vertical coordinate of every point, in the same order. */
@@ -78,23 +50,6 @@ export interface ScatterPlotProps {
   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
@@ -123,104 +78,6 @@ export interface ScatterPlotProps {
    * @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 the reader double-clicks a point: the gesture for "tell me
-   * more about this one", or "let me change it".
-   *
-   * A double click is also two clicks, so the point is selected first and its
-   * card pinned. That is deliberate: the alternative is to hold every single
-   * click for the length of the double-click interval before acting on it, and
-   * clicking a dot is the commonest gesture in the figure — making it feel
-   * slow to save a redundant selection on the rarest one is the wrong trade.
-   *
-   * A double click on empty ground is not this. It puts the frame back around
-   * every point, which is the only way out of a zoom, and it keeps doing that
-   * whether or not this is given.
-   * @default undefined — a double click only ever resets the frame
-   */
-  onPointDoubleClick?: (point: ScatterPointOpen) => 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
@@ -232,7 +89,8 @@ export interface ScatterPlotProps {
    * 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.
+   * the picture they started with. A double click on empty ground puts the
+   * frame back around every point.
    * @default undefined — the plot keeps its own frame
    */
   viewport?: ChartViewport | null;
@@ -250,26 +108,4 @@ export interface ScatterPlotProps {
    * @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/useCapturedPointer.ts

@@ -0,0 +1,157 @@
+import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
+
+import type { ScatterSurfaceProps } from './lassoGesture.ts';
+import { capturePointer, dropFrame, scheduleFrame } from './lassoGesture.ts';
+
+/** What {@link useCapturedPointer} needs. */
+interface CapturedPointerOptions {
+  /**
+   * Whether a finger is claimed too. On, the surface stops the page scrolling
+   * under it; off, a touch passes through to the page.
+   */
+  touch: boolean;
+  /** The pointer the surface shows. */
+  cursor: CSSProperties['cursor'];
+  /**
+   * Called on a press while no pointer is claimed; answer whether to claim it.
+   */
+  onPress: (event: ReactPointerEvent<Element>) => boolean;
+  /**
+   * Called on every move of the claimed pointer, or of any pointer while none
+   * is claimed; answer whether a frame should be booked for it.
+   */
+  onMove: (event: ReactPointerEvent<Element>, claimed: boolean) => boolean;
+  /** Called on the booked frame, with whether a pointer is still claimed. */
+  onFrame: (claimed: boolean) => void;
+  /**
+   * Called once when a claim ends: with the event and `true` for a release,
+   * with the event and `false` when the browser took the pointer away, and
+   * with `null` and `false` when the gesture was abandoned from outside.
+   */
+  onRelease: (
+    event: ReactPointerEvent<Element> | null,
+    commit: boolean,
+  ) => void;
+  /**
+   * Called when the pointer leaves the surface with nothing claimed.
+   * @default undefined
+   */
+  onLeave?: () => void;
+}
+
+/** A surface that claims one pointer at a time. */
+interface CapturedPointer {
+  /** Spread onto the transparent rectangle laid over the figure. */
+  surface: ScatterSurfaceProps;
+  /** End a claim from outside — what Escape is wired to. */
+  abandon: () => void;
+}
+
+/**
+ * One pointer claimed for the length of a drag, whatever the drag draws.
+ *
+ * The pointer is captured on the way down, so a drag that wanders off the
+ * figure, or off the window, still ends. All three ways a capture can end —
+ * a release, `pointercancel` and `lostpointercapture` — lead to one callback:
+ * a gesture left half-done because one of them was handled and another 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 figure repaints it.
+ *
+ * The lasso and the turning cloud are both built on it and keep only their
+ * own state: a path being drawn, or a camera being turned.
+ * @param options - See {@link CapturedPointerOptions}.
+ * @returns The surface. See {@link CapturedPointer}.
+ */
+export function useCapturedPointer(
+  options: CapturedPointerOptions,
+): CapturedPointer {
+  const { touch, cursor, onPress, onMove, onFrame, onRelease, onLeave } =
+    options;
+  const pointerRef = useRef<number | null>(null);
+  const frameRef = useRef<number | null>(null);
+
+  const flush = useCallback(() => {
+    frameRef.current = null;
+    onFrame(pointerRef.current !== null);
+  }, [onFrame]);
+
+  const end = useCallback(
+    (event: ReactPointerEvent<Element> | null, commit: boolean) => {
+      const claimed = pointerRef.current;
+      if (claimed === null) return;
+      if (event !== null && event.pointerId !== claimed) return;
+      pointerRef.current = null;
+      dropFrame(frameRef);
+      onRelease(event, commit);
+    },
+    [onRelease],
+  );
+
+  const handleDown = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      if (pointerRef.current !== null || event.button > 0) return;
+      if (event.pointerType === 'touch' && !touch) return;
+      if (!onPress(event)) return;
+      pointerRef.current = event.pointerId;
+      capturePointer(event);
+    },
+    [onPress, touch],
+  );
+
+  const handleMove = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      const claimed = pointerRef.current;
+      if (claimed !== null && event.pointerId !== claimed) return;
+      if (onMove(event, claimed !== null)) scheduleFrame(frameRef, flush);
+    },
+    [flush, onMove],
+  );
+
+  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;
+    onLeave?.();
+  }, [onLeave]);
+
+  const abandon = useCallback(() => {
+    end(null, false);
+  }, [end]);
+
+  const surface = useMemo<ScatterSurfaceProps>(
+    () => ({
+      onPointerDown: handleDown,
+      onPointerMove: handleMove,
+      onPointerUp: handleUp,
+      onPointerCancel: handleAbandon,
+      onLostPointerCapture: handleAbandon,
+      onPointerLeave: handleLeave,
+      style: { cursor, touchAction: touch ? 'none' : 'auto' },
+    }),
+    [
+      cursor,
+      handleAbandon,
+      handleDown,
+      handleLeave,
+      handleMove,
+      handleUp,
+      touch,
+    ],
+  );
+
+  return { surface, abandon };
+}