react-cheminfo 0.9.0 → 0.11.0

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

package/src/scatter/ui/useScatterFrame.ts

@@ -0,0 +1,191 @@
+import type { RefObject } from 'react';
+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';
+
+/** What {@link useScatterFrame} needs. */
+export interface ScatterFrameOptions {
+  /** Horizontal coordinate of every point, in data units. */
+  x: ArrayLike<number>;
+  /** Vertical coordinate, in the same order. */
+  y: ArrayLike<number>;
+  /** Total width of the figure, in pixels. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /** The horizontal axis, covering everything there is to show. */
+  xAxis: ChartAxisSpec;
+  /** The vertical axis. */
+  yAxis: ChartAxisSpec;
+  /**
+   * The frame showing, when the caller owns it; `null` shows the whole of both
+   * axes. Present, it wins on every render, the same way `selected` does.
+   * @default undefined — the hook keeps the frame itself
+   */
+  viewport?: ChartViewport | null;
+  /**
+   * Called with the frame a gesture 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, once the pointer has rested over the plot.
+   * @default false
+   */
+  wheelZoom?: boolean;
+  /**
+   * How long it has to rest first, in milliseconds.
+   * @default CHART_WHEEL_DWELL
+   */
+  wheelZoomDelay?: number;
+}
+
+/** Where a scatter's data lands, and the frame it landed in. */
+export interface ScatterFrame extends ScatterPlotView {
+  /** The horizontal axis as it should be drawn, zoom included. */
+  xAxis: ChartAxisSpec;
+  /** The vertical one. */
+  yAxis: ChartAxisSpec;
+  /** The frame showing, or `null` when the whole of both axes is. */
+  viewport: ChartViewport | null;
+  /**
+   * One entry per point, a zero for a point outside the frame, or `undefined`
+   * when every point is inside it — which is what an unzoomed plot hands the
+   * hit tests, so that the common case allocates nothing.
+   */
+  inside: Uint8Array | undefined;
+  /** Goes on the surface the gestures land on, which is what the wheel is caught over. */
+  ref: RefObject<SVGRectElement | null>;
+  /** Put the frame back around everything — what a double click does. */
+  reset: () => void;
+}
+
+/**
+ * The rectangle a scatter draws in, the mapping into it, and the zoom that
+ * chose it.
+ *
+ * A zoom is a domain and never a transform: the frame is handed a narrower
+ * range and the points, the outlines, the ticks and the hit tests are computed
+ * from it exactly as they are computed unzoomed. Nothing downstream is told a
+ * zoom happened, and nothing has to be.
+ *
+ * Two details are what make it feel right rather than merely work. The niced
+ * domain is what a zoom starts from and returns to, so a wheel turned back out
+ * lands on the chart the reader began with rather than a frame three percent
+ * inside it. And a zoomed axis stops being niced: rounding a frame outward to
+ * whole ticks would move the value the pointer is anchored on, and the reader
+ * would feel the picture slip away from where they aimed it.
+ * @param options - See {@link ScatterFrameOptions}.
+ * @returns The frame. See {@link ScatterFrame}.
+ */
+export function useScatterFrame(options: ScatterFrameOptions): ScatterFrame {
+  const { x, y, width, height, xAxis, yAxis } = options;
+  const { viewport, onViewportChange, wheelZoom = false } = options;
+  const { wheelZoomDelay } = options;
+
+  const [own, setOwn] = useState<ChartViewport | null>(null);
+  const shown = viewport === undefined ? own : viewport;
+
+  const full = useMemo<ChartViewport>(
+    () => ({ x: nicedDomain(xAxis), y: nicedDomain(yAxis) }),
+    [xAxis, yAxis],
+  );
+  const axes = useMemo(
+    () =>
+      shown === null
+        ? { x: xAxis, y: yAxis }
+        : {
+            x: { ...xAxis, domain: shown.x, nice: false },
+            y: { ...yAxis, domain: shown.y, nice: false },
+          },
+    [shown, xAxis, yAxis],
+  );
+  const view = useMemo(
+    () => scatterPlotGeometry(x, y, width, height, axes.x, axes.y),
+    [x, y, width, height, axes],
+  );
+
+  const change = useCallback(
+    (next: ChartViewport | null) => {
+      if (viewport === undefined) setOwn(next);
+      onViewportChange?.(next);
+    },
+    [onViewportChange, viewport],
+  );
+
+  const reset = useCallback(() => {
+    if (shown !== null) change(null);
+  }, [change, shown]);
+
+  const zoom = useWheelZoom<SVGRectElement>({
+    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,
+        ),
+      );
+    },
+  });
+
+  const inside = useMemo(() => {
+    if (shown === null) return undefined;
+    const { points, rect } = view;
+    return pointsWithinBounds(points, {
+      minX: rect.x,
+      minY: rect.y,
+      maxX: rect.x + rect.width,
+      maxY: rect.y + rect.height,
+    });
+  }, [shown, view]);
+
+  return {
+    ...view,
+    xAxis: axes.x,
+    yAxis: axes.y,
+    viewport: shown,
+    inside,
+    ref: zoom.ref,
+    reset,
+  };
+}
+
+/**
+ * The range an axis actually covers once it has been niced, which is the range
+ * a zoom has to measure itself against.
+ * @param axis - The axis as the caller asked for it.
+ * @returns The domain the frame will draw.
+ */
+function nicedDomain(axis: ChartAxisSpec): readonly [number, number] {
+  return chartAxisScale(axis.domain[0], axis.domain[1], {
+    count: axis.tickCount,
+    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

@@ -0,0 +1,258 @@
+import { useCallback, 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 { 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.
+ *
+ * The four hooks underneath are separately usable and separately tested; this
+ * is the one a plot calls, and it holds the decisions that only make sense
+ * between them — that a click on empty ground clears rather than selecting
+ * nothing, that hovering stops while a lasso is drawn, and that `Escape`
+ * abandons the drag and lets the card go.
+ *
+ * The buffer the polygon test writes into is kept across frames: a drag runs
+ * that test once a frame over every point, and a fresh mask per frame is an
+ * allocation the collector answers for during the one interaction where a
+ * dropped frame shows as a kink in the line being drawn.
+ * @param options - See {@link ScatterInteractionOptions}.
+ * @returns The interaction. See {@link ScatterInteractionApi}.
+ */
+export function useScatterInteraction(
+  options: ScatterInteractionOptions,
+): ScatterInteractionApi {
+  const {
+    points,
+    originX = 0,
+    originY = 0,
+    selected,
+    defaultSelected,
+    onSelectionChange,
+    selectMode = 'replace',
+    enabled = true,
+    touchLasso = false,
+    hoverRadius,
+    included,
+    onHoverChange,
+    onPinChange,
+  } = options;
+
+  const radius = hoverRadius ?? DEFAULT_HOVER_RADIUS;
+  const count = Math.min(points.x.length, points.y.length);
+  const hitsRef = useRef<Uint8Array | null>(null);
+
+  const selection = useScatterSelection({
+    count,
+    selected,
+    defaultSelected,
+    onSelectionChange,
+  });
+  const hover = usePointHover({
+    points,
+    radius,
+    included,
+    onHoverChange,
+    onPinChange,
+  });
+
+  const { clear, preview, select, selectMask } = selection;
+  const { leave, moveTo, pin, unpin } = hover;
+
+  const caught = useCallback(
+    (path: LassoPath) => {
+      const hits = pointsInPolygon(
+        points,
+        path.xs,
+        path.ys,
+        path.length,
+        hitsRef.current ?? undefined,
+      );
+      hitsRef.current = hits;
+      return hits;
+    },
+    [points],
+  );
+
+  const onDraw = useCallback(
+    (path: LassoPath | null, mode: ScatterSelectionMode) => {
+      preview(path === null ? null : caught(path), mode);
+    },
+    [caught, preview],
+  );
+
+  const onComplete = useCallback(
+    (path: LassoPath, mode: ScatterSelectionMode) => {
+      selectMask(caught(path), mode, 'lasso');
+    },
+    [caught, selectMask],
+  );
+
+  const onClick = useCallback(
+    (x: number, y: number, mode: ScatterSelectionMode) => {
+      const index = nearestPointIndex(points, x, y, radius, included);
+      if (index === -1) {
+        unpin();
+        if (mode === 'replace') clear();
+        return;
+      }
+      select([index], mode, 'point');
+      pin(index);
+    },
+    [clear, included, pin, points, radius, select, unpin],
+  );
+
+  const onMove = useCallback(
+    (x: number, y: number, drawing: boolean) => {
+      if (!drawing) moveTo(x, y);
+    },
+    [moveTo],
+  );
+
+  const lasso = useLassoGesture({
+    enabled,
+    touch: touchLasso,
+    originX,
+    originY,
+    mode: selectMode,
+    onDraw,
+    onComplete,
+    onClick,
+    onMove,
+    onLeave: leave,
+  });
+
+  const onCommit = useCallback(
+    (index: number, mode: ScatterSelectionMode) => {
+      select([index], mode, 'keyboard');
+      pin(index);
+    },
+    [pin, select],
+  );
+
+  const onCancel = useCallback(() => {
+    lasso.cancel();
+    unpin();
+  }, [lasso, unpin]);
+
+  const keyboard = useScatterKeyboard({ count, onCommit, onCancel });
+
+  const pointAt = useCallback(
+    (x: number, y: number) => nearestPointIndex(points, x, y, radius, included),
+    [included, points, radius],
+  );
+
+  return {
+    surface: lasso.surface,
+    selection,
+    hover,
+    keyboard,
+    lasso,
+    pointAt,
+  };
+}