react-cheminfo 0.11.0 → 0.13.0

package/src/scatter/ui/scatterInteractionTypes.ts

@@ -0,0 +1,127 @@
+/**
+ * What `useScatterInteraction` is asked for and what it hands back, kept apart
+ * from the hook so the hook's own file stays about the decisions it makes.
+ */
+
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+import type { ScreenPoints } from '../core/screenPoints.ts';
+
+import type {
+  LassoGesture,
+  ScatterSurfaceProps,
+  SurfaceEvent,
+} from './lassoGesture.ts';
+import type { ScatterPointOpen } from './scatterFigureProps.ts';
+import type { PointHoverApi } from './usePointHover.ts';
+import type { ScatterKeyboardApi } from './useScatterKeyboard.ts';
+import type {
+  ScatterSelectionApi,
+  SelectionChange,
+} from './useScatterSelection.ts';
+
+/** What `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;
+  /**
+   * Called when a lasso starts being drawn and again when it ends.
+   * @default undefined
+   */
+  onLassoChange?: (drawing: boolean) => 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;
+  /**
+   * What a click at a position does: select and pin the nearest point, or,
+   * on empty ground, let the card go and clear a replacing selection. For a
+   * gesture the hook does not own that ends in a click — a tap on a cloud
+   * being turned.
+   */
+  clickAt: (x: number, y: number, mode: ScatterSelectionMode) => void;
+  /**
+   * The point a double click landed on, with where it landed, or `null` on
+   * empty ground.
+   */
+  openAt: (event: SurfaceEvent) => ScatterPointOpen | null;
+}

package/src/scatter/ui/scatterLabels.ts

@@ -12,7 +12,9 @@
  * anything.
  */
 
+import { chartGroupIndex } from '../../chart/core/chartGroups.ts';
 import type { ScreenPoints } from '../core/screenPoints.ts';
+import { scatterGroupPixelSums } from '../core/screenPoints.ts';
 
 /** One word written on the plot, already placed. */
 export interface ScatterPixelLabel {
@@ -81,7 +83,7 @@ export function scatterPointLabels(
     const y = points.y[index];
     if (x === undefined || !Number.isFinite(x)) continue;
     if (y === undefined || !Number.isFinite(y)) continue;
-    const group = groupOf?.[index] ?? -1;
+    const group = chartGroupIndex(groupOf, index, colors?.length ?? 0);
     placed.push({ x, y, text, color: colors?.[group] ?? fallbackColor });
   }
   return placed;
@@ -110,20 +112,7 @@ export function scatterGroupLabels(
   const placed: ScatterPixelLabel[] = [];
   if (groupOf === undefined) return placed;
 
-  const sums = new Float64Array(names.length * 3);
-  const count = Math.min(points.x.length, points.y.length, groupOf.length);
-  for (let index = 0; index < count; index++) {
-    const group = groupOf[index];
-    if (group === undefined || group < 0 || group >= names.length) continue;
-    const x = points.x[index];
-    const y = points.y[index];
-    if (x === undefined || !Number.isFinite(x)) continue;
-    if (y === undefined || !Number.isFinite(y)) continue;
-    sums[group * 3] = (sums[group * 3] ?? 0) + x;
-    sums[group * 3 + 1] = (sums[group * 3 + 1] ?? 0) + y;
-    sums[group * 3 + 2] = (sums[group * 3 + 2] ?? 0) + 1;
-  }
-
+  const sums = scatterGroupPixelSums(points, groupOf, names.length);
   for (let group = 0; group < names.length; group++) {
     const seen = sums[group * 3 + 2] ?? 0;
     const text = names[group];

package/src/scatter/ui/scatterMarkGlyph.tsx

@@ -8,6 +8,7 @@
 
 import type { ReactElement } from 'react';
 
+import { chartRoundPixel } from '../../chart/core/chartScale.ts';
 import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
 
 /** A point drawn over the cloud that is not a sample, already in pixels. */
@@ -44,10 +45,10 @@ export function markGlyph(
 ): ReactElement {
   const { label, x, y, color, shape = 'cross' } = mark;
   const half = size / 2;
-  const near = round(x - half);
-  const far = round(x + half);
-  const top = round(y - half);
-  const foot = round(y + half);
+  const near = chartRoundPixel(x - half);
+  const far = chartRoundPixel(x + half);
+  const top = chartRoundPixel(y - half);
+  const foot = chartRoundPixel(y + half);
   // `key` is passed on each element rather than spread: React reads a key
   // out of JSX itself, and one arriving through a spread is dropped with a
   // warning that only shows up once the page is running.
@@ -58,8 +59,8 @@ export function markGlyph(
       <circle
         key={key}
         {...shared}
-        cx={round(x)}
-        cy={round(y)}
+        cx={chartRoundPixel(x)}
+        cy={chartRoundPixel(y)}
         r={half}
         fill={filled ? color : 'none'}
         stroke={filled ? 'none' : color}
@@ -90,5 +91,3 @@ export function markGlyph(
     />
   );
 }
-
-const round = (value: number): number => Math.round(value * 100) / 100;

package/src/scatter/ui/scatterMatrixDots.tsx

@@ -11,9 +11,13 @@
 
 import type { CSSProperties, PointerEvent, ReactElement } from 'react';
 
+import { chartGroupIndex } from '../../chart/core/chartGroups.ts';
+import { chartRoundPixel } from '../../chart/core/chartScale.ts';
 import type { ChartFrameRender } from '../../chart/ui/ChartFrame.tsx';
 
 import type { ScatterMatrixGrid } from './ScatterMatrixDiagonal.tsx';
+import { surfacePosition } from './lassoGesture.ts';
+import { SCATTER_HOVER_SLACK } from './scatterPlotModel.ts';
 
 /**
  * Every dot of one cell, as one path per colour, plus the rectangle that turns
@@ -39,8 +43,8 @@ export function scatterMatrixDots(
     const valueX = scores.get(index, column);
     const valueY = scores.get(index, row);
     if (!Number.isFinite(valueX) || !Number.isFinite(valueY)) continue;
-    const atX = Math.round((x.offset + valueX * x.factor) * 10) / 10;
-    const atY = Math.round((y.offset + valueY * y.factor) * 10) / 10;
+    const atX = chartRoundPixel(x.offset + valueX * x.factor, 1);
+    const atY = chartRoundPixel(y.offset + valueY * y.factor, 1);
     const slot =
       inkOf(groupOf, index, inks - 1) * 2 + (mask?.[index] === 0 ? 1 : 0);
     paths[slot] = `${paths[slot] ?? ''}M${atX} ${atY}h0`;
@@ -73,9 +77,6 @@ export function scatterMatrixDots(
   return marks;
 }
 
-/** How far from a dot the pointer still counts as resting on it, in pixels. */
-const HOVER_REACH = 10;
-
 /** Opacity of a dot in the selection, of one outside it, and the ungrouped ink. */
 const POINT_OPACITY = 0.85;
 const FAINT_OPACITY = 0.16;
@@ -94,17 +95,22 @@ function nearestRow(
   column: number,
   frame: ChartFrameRender,
 ): number {
-  const { offsetX, offsetY } = event.nativeEvent;
-  const { scores } = grid;
-  const { x, y } = frame;
+  const { scores, pointRadius } = grid;
+  const { x, y, plot } = frame;
+  const at = surfacePosition(event, plot.left, plot.top);
+  const reach = pointRadius + SCATTER_HOVER_SLACK;
+  const limit = reach * reach;
   let best = -1;
-  let closest = HOVER_REACH * HOVER_REACH;
+  let closest = 0;
 
   for (let index = 0; index < scores.rows; index++) {
-    const awayX = x.offset + scores.get(index, column) * x.factor - offsetX;
-    const awayY = y.offset + scores.get(index, row) * y.factor - offsetY;
+    const awayX = x.offset + scores.get(index, column) * x.factor - at.x;
+    const awayY = y.offset + scores.get(index, row) * y.factor - at.y;
     const away = awayX * awayX + awayY * awayY;
-    if (away < closest) {
+    // The rule `nearestPointIndex` keeps on the map: a dot exactly at the reach
+    // counts, a tie goes to the lower row, a missing value is never in reach.
+    if (!(away <= limit)) continue;
+    if (best === -1 || away < closest) {
       closest = away;
       best = index;
     }
@@ -127,8 +133,6 @@ function inkOf(
   row: number,
   groups: number,
 ): number {
-  const raw = groupOf?.[row];
-  if (raw === undefined || !Number.isFinite(raw)) return groups;
-  const group = Math.trunc(raw);
-  return group < 0 || group >= groups ? groups : group;
+  const group = chartGroupIndex(groupOf, row, groups);
+  return group === -1 ? groups : group;
 }

package/src/scatter/ui/scatterMatrixLayout.ts

@@ -61,7 +61,7 @@ export const SCATTER_MATRIX_SMALLEST_PLOT = 50;
 /**
  * The narrowest cell that writes its share into its axis title.
  *
- * `PC 1 — 73.0 %` is about a hundred pixels of type, and an axis title is
+ * `PC1 — 73.0 %` is about a hundred pixels of type, and an axis title is
  * centred on a cell that may be seventy: three of them along the foot of a
  * narrow grid run into one another and none of the three can be read. Under
  * this the title is the component's name alone, which is the half a reader

package/src/scatter/ui/scatterMatrixOutlines.tsx

@@ -12,9 +12,9 @@
 import type { ReactElement } from 'react';
 
 import type { ChartFrameRender } from '../../chart/ui/ChartFrame.tsx';
+import { scatterPairEllipse } from '../core/scatterGroupSpread.ts';
 
 import type { ScatterMatrixGrid } from './ScatterMatrixDiagonal.tsx';
-import { scatterPairEllipse } from './scatterGroupSpread.ts';
 import { scatterOutlineShape } from './scatterOutlineShape.tsx';
 
 /**

package/src/scatter/ui/scatterMatrixProps.ts

@@ -12,11 +12,12 @@ import type { ReactNode } from 'react';
 import type { MatrixLike } from '../../chart/core/matrix.ts';
 import type { EllipseSize } from '../core/confidenceEllipse.ts';
 
-import type { ScatterGroup } from './scatterPlotProps.ts';
+import type { ScatterMatrix } from './ScatterMatrix.tsx';
+import type { ScatterGroup } from './scatterFigureProps.ts';
 
 /** One axis of a {@link ScatterMatrix}. */
 export interface ScatterMatrixAxis {
-  /** What it is called, e.g. `PC 1`. */
+  /** What it is called, e.g. `PC1`. */
   name: string;
   /**
    * The share of the differences it accounts for, between 0 and 1.
@@ -100,4 +101,9 @@ export interface ScatterMatrixProps {
    * @default undefined
    */
   testId?: string;
+  /**
+   * Class names added to the root element.
+   * @default undefined
+   */
+  className?: string;
 }

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