react-cheminfo 0.8.0 → 0.10.0

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,237 @@
+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;
+}
+
+/**
+ * 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 });
+
+  return { surface: lasso.surface, selection, hover, keyboard, lasso };
+}

package/src/scatter/ui/useScatterKeyboard.ts

@@ -0,0 +1,120 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { useCallback, useRef, useState } from 'react';
+
+import { handleListNavigationKey } from '../../hooks/ui/listNavigation.ts';
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+
+import { modifierMode } from './lassoGesture.ts';
+
+/** What {@link useScatterKeyboard} needs. */
+export interface ScatterKeyboardOptions {
+  /** How many points the cloud holds. */
+  count: number;
+  /**
+   * Whether the keys are read. Off, the plot still takes the focus but every
+   * key falls through to the page.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * How many points `PageUp` and `PageDown` move by.
+   * @default 10
+   */
+  pageStep?: number;
+  /**
+   * Called whenever the cursor lands somewhere new, including `-1`.
+   * @default undefined
+   */
+  onCursorChange?: (index: number) => void;
+  /**
+   * Called when the reader commits the cursor with `Enter` or the space bar,
+   * with the mode the held modifiers ask for.
+   * @default undefined
+   */
+  onCommit?: (index: number, mode: ScatterSelectionMode) => void;
+  /**
+   * Called on `Escape` — what a half-drawn lasso and a pinned card listen for.
+   * @default undefined
+   */
+  onCancel?: () => void;
+}
+
+/** A roving cursor over the points, for a reader with no pointer. */
+export interface ScatterKeyboardApi {
+  /** The point the cursor is on, or `-1` before any key. */
+  cursor: number;
+  /** Move it from outside, so a click and the cursor agree on where they are. */
+  setCursor: (index: number) => void;
+  /** Put on the focusable element around the plot. */
+  onKeyDown: (event: ReactKeyboardEvent<Element>) => void;
+}
+
+/**
+ * Reaching every point of a scatter without a pointer.
+ *
+ * The same roving cursor the periodic table and every list in this family use,
+ * over the same `handleListNavigationKey`, so the arrows, the page keys and
+ * `Home` and `End` behave identically wherever a reader meets them. Without
+ * it a lasso is the only way to pick anything, and a lasso needs a hand.
+ *
+ * The cursor is not the selection. It says where the reader is; `Enter` or the
+ * space bar is what settles it, with Shift and Alt meaning what they mean
+ * during a drag — otherwise arrowing across a cloud would replace the
+ * selection on every step and the reader could never build one up.
+ * @param options - See {@link ScatterKeyboardOptions}.
+ * @returns The cursor. See {@link ScatterKeyboardApi}.
+ */
+export function useScatterKeyboard(
+  options: ScatterKeyboardOptions,
+): ScatterKeyboardApi {
+  const {
+    count,
+    enabled = true,
+    pageStep,
+    onCursorChange,
+    onCommit,
+    onCancel,
+  } = options;
+
+  const [cursor, setCursorState] = useState(-1);
+  const cursorRef = useRef(-1);
+
+  const setCursor = useCallback(
+    (index: number) => {
+      const next =
+        Number.isInteger(index) && index >= 0 && index < count ? index : -1;
+      if (next === cursorRef.current) return;
+      cursorRef.current = next;
+      setCursorState(next);
+      onCursorChange?.(next);
+    },
+    [count, onCursorChange],
+  );
+
+  const onKeyDown = useCallback(
+    (event: ReactKeyboardEvent<Element>) => {
+      if (!enabled || count <= 0) return;
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        onCancel?.();
+        return;
+      }
+      if (event.key === 'Enter' || event.key === ' ') {
+        const index = cursorRef.current;
+        if (index === -1) return;
+        event.preventDefault();
+        onCommit?.(index, modifierMode(event, 'replace'));
+        return;
+      }
+      handleListNavigationKey(event, {
+        length: count,
+        selectedIndex: cursorRef.current,
+        pageStep,
+        onSelect: setCursor,
+      });
+    },
+    [count, enabled, onCancel, onCommit, pageStep, setCursor],
+  );
+
+  return { cursor, setCursor, onKeyDown };
+}