react-cheminfo 0.9.0 → 0.11.0

package/lib/scatter/ui/useScatterFrame.d.ts

@@ -0,0 +1,80 @@
+import type { RefObject } from 'react';
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import type { ChartAxisSpec } from '../../chart/ui/ChartFrame.tsx';
+import type { ScatterPlotView } 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 declare function useScatterFrame(options: ScatterFrameOptions): ScatterFrame;
+//# sourceMappingURL=useScatterFrame.d.ts.map

package/lib/scatter/ui/useScatterFrame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterFrame.d.ts","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterFrame.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAInE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACrB,8CAA8C;IAC9C,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACrB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,EAAE,aAAa,CAAC;IACrB,yBAAyB;IACzB,KAAK,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5D;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,gEAAgE;IAChE,KAAK,EAAE,aAAa,CAAC;IACrB,wBAAwB;IACxB,KAAK,EAAE,aAAa,CAAC;IACrB,mEAAmE;IACnE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,wFAAwF;IACxF,GAAG,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACtC,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA8E1E"}

package/lib/scatter/ui/useScatterFrame.js

@@ -0,0 +1,101 @@
+import { useCallback, useMemo, useState } from 'react';
+import { chartAxisScale } from "../../chart/core/chartAxisScale.js";
+import { chartZoomViewport } from "../../chart/core/chartViewport.js";
+import { useWheelZoom } from "../../chart/ui/useWheelZoom.js";
+import { pointsWithinBounds } from "../core/screenPoints.js";
+import { scatterPlotGeometry } from "./scatterPlotModel.js";
+/**
+ * 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) {
+    const { x, y, width, height, xAxis, yAxis } = options;
+    const { viewport, onViewportChange, wheelZoom = false } = options;
+    const { wheelZoomDelay } = options;
+    const [own, setOwn] = useState(null);
+    const shown = viewport === undefined ? own : viewport;
+    const full = useMemo(() => ({ 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) => {
+        if (viewport === undefined)
+            setOwn(next);
+        onViewportChange?.(next);
+    }, [onViewportChange, viewport]);
+    const reset = useCallback(() => {
+        if (shown !== null)
+            change(null);
+    }, [change, shown]);
+    const zoom = useWheelZoom({
+        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) {
+    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, share) {
+    return domain[0] + share * (domain[1] - domain[0]);
+}
+//# sourceMappingURL=useScatterFrame.js.map

package/lib/scatter/ui/useScatterFrame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterFrame.js","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterFrame.ts"],"names":[],"mappings":"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"}

package/lib/scatter/ui/useScatterInteraction.d.ts

@@ -0,0 +1,112 @@
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+import type { ScreenPoints } from '../core/screenPoints.ts';
+import type { LassoGesture, ScatterSurfaceProps } from './lassoGesture.ts';
+import type { PointHoverApi } from './usePointHover.ts';
+import type { ScatterKeyboardApi } from './useScatterKeyboard.ts';
+import type { ScatterSelectionApi, SelectionChange } 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 declare function useScatterInteraction(options: ScatterInteractionOptions): ScatterInteractionApi;
+//# sourceMappingURL=useScatterInteraction.d.ts.map

package/lib/scatter/ui/useScatterInteraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterInteraction.d.ts","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterInteraction.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACtD;;;OAGG;IACH,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,OAAO,EAAE,mBAAmB,CAAC;IAC7B,oEAAoE;IACpE,SAAS,EAAE,mBAAmB,CAAC;IAC/B,sDAAsD;IACtD,KAAK,EAAE,aAAa,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,uDAAuD;IACvD,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;;OAOG;IACH,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,yBAAyB,GACjC,qBAAqB,CAiIvB"}

package/lib/scatter/ui/useScatterInteraction.js

@@ -0,0 +1,101 @@
+import { useCallback, useRef } from 'react';
+import { pointsInPolygon } from "../core/polygon.js";
+import { nearestPointIndex } from "../core/screenPoints.js";
+import { useLassoGesture } from "./useLassoGesture.js";
+import { DEFAULT_HOVER_RADIUS, usePointHover } from "./usePointHover.js";
+import { useScatterKeyboard } from "./useScatterKeyboard.js";
+import { useScatterSelection } from "./useScatterSelection.js";
+/**
+ * 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) {
+    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(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) => {
+        const hits = pointsInPolygon(points, path.xs, path.ys, path.length, hitsRef.current ?? undefined);
+        hitsRef.current = hits;
+        return hits;
+    }, [points]);
+    const onDraw = useCallback((path, mode) => {
+        preview(path === null ? null : caught(path), mode);
+    }, [caught, preview]);
+    const onComplete = useCallback((path, mode) => {
+        selectMask(caught(path), mode, 'lasso');
+    }, [caught, selectMask]);
+    const onClick = useCallback((x, y, mode) => {
+        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, y, drawing) => {
+        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, mode) => {
+        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, y) => nearestPointIndex(points, x, y, radius, included), [included, points, radius]);
+    return {
+        surface: lasso.surface,
+        selection,
+        hover,
+        keyboard,
+        lasso,
+        pointAt,
+    };
+}
+//# sourceMappingURL=useScatterInteraction.js.map

package/lib/scatter/ui/useScatterInteraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterInteraction.js","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterInteraction.ts"],"names":[],"mappings":"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"}

package/lib/scatter/ui/useScatterKeyboard.d.ts

@@ -0,0 +1,60 @@
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { ScatterSelectionMode } from '../core/scatterSelection.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 declare function useScatterKeyboard(options: ScatterKeyboardOptions): ScatterKeyboardApi;
+//# sourceMappingURL=useScatterKeyboard.d.ts.map

package/lib/scatter/ui/useScatterKeyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterKeyboard.d.ts","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterKeyboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAIjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAIxE,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAC/D;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,oDAAoD;IACpD,SAAS,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAC9B,kBAAkB,CAmDpB"}

package/lib/scatter/ui/useScatterKeyboard.js

@@ -0,0 +1,56 @@
+import { useCallback, useRef, useState } from 'react';
+import { handleListNavigationKey } from "../../hooks/ui/listNavigation.js";
+import { modifierMode } from "./lassoGesture.js";
+/**
+ * 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) {
+    const { count, enabled = true, pageStep, onCursorChange, onCommit, onCancel, } = options;
+    const [cursor, setCursorState] = useState(-1);
+    const cursorRef = useRef(-1);
+    const setCursor = useCallback((index) => {
+        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) => {
+        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 };
+}
+//# sourceMappingURL=useScatterKeyboard.js.map

package/lib/scatter/ui/useScatterKeyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterKeyboard.js","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterKeyboard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAG3E,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA6CjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA+B;IAE/B,MAAM,EACJ,KAAK,EACL,OAAO,GAAG,IAAI,EACd,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,QAAQ,GACT,GAAG,OAAO,CAAC;IAEZ,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7B,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,KAAa,EAAE,EAAE;QAChB,MAAM,IAAI,GACR,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtE,IAAI,IAAI,KAAK,SAAS,CAAC,OAAO;YAAE,OAAO;QACvC,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QACzB,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,EACD,CAAC,KAAK,EAAE,cAAc,CAAC,CACxB,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,KAAkC,EAAE,EAAE;QACrC,IAAI,CAAC,OAAO,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO;QACnC,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC3B,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,QAAQ,EAAE,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,KAAK,OAAO,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC;YAChC,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO;YACzB,KAAK,CAAC,cAAc,EAAE,CAAC;YACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QACD,uBAAuB,CAAC,KAAK,EAAE;YAC7B,MAAM,EAAE,KAAK;YACb,aAAa,EAAE,SAAS,CAAC,OAAO;YAChC,QAAQ;YACR,QAAQ,EAAE,SAAS;SACpB,CAAC,CAAC;IACL,CAAC,EACD,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAC1D,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAC1C,CAAC"}

package/lib/scatter/ui/useScatterSelection.d.ts

@@ -0,0 +1,78 @@
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+/** What a gesture did to a scatter's selection. */
+export interface SelectionChange {
+    /** The selected rows, ascending, as indices into the arrays the caller passed. */
+    indices: readonly number[];
+    /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+    mode: ScatterSelectionMode;
+    /** Which gesture produced it. */
+    source: 'lasso' | 'point' | 'keyboard' | 'clear' | 'all';
+}
+/** What {@link useScatterSelection} needs. */
+export interface ScatterSelectionOptions {
+    /** How many points the cloud holds. */
+    count: number;
+    /**
+     * The selected rows when the caller owns them. Present, it wins over
+     * anything the reader has done here — see {@link useScatterSelection} for
+     * what that means for a caller that stops passing it.
+     * @default undefined — the hook keeps the selection itself
+     */
+    selected?: readonly number[];
+    /**
+     * The rows selected before the reader touches anything, for the uncontrolled
+     * case. It is read once; changing it later moves nothing.
+     * @default undefined — nothing is selected
+     */
+    defaultSelected?: readonly number[];
+    /**
+     * Called once per settled gesture, never while a lasso is being drawn.
+     * @default undefined
+     */
+    onSelectionChange?: (change: SelectionChange) => void;
+}
+/** A scatter's selection, and the four ways a gesture changes it. */
+export interface ScatterSelectionApi {
+    /**
+     * One entry per point, `1` for selected. It includes whatever a lasso is
+     * currently previewing, so the dots under a half-drawn ring already look
+     * picked.
+     */
+    mask: Uint8Array;
+    /** The same, as ascending indices. */
+    indices: number[];
+    /** How many points that is, without walking the list again. */
+    selectedCount: number;
+    /** Whether a lasso is showing what it would do rather than having done it. */
+    previewing: boolean;
+    /** Settle a new selection from a list of rows. */
+    select: (rows: Iterable<number>, mode?: ScatterSelectionMode, source?: SelectionChange['source']) => void;
+    /** Settle one from a mask, which is the shape a lasso hands back. */
+    selectMask: (hits: Uint8Array, mode?: ScatterSelectionMode, source?: SelectionChange['source']) => void;
+    /** Show what a gesture would do without settling it; `null` clears it. */
+    preview: (hits: Uint8Array | null, mode?: ScatterSelectionMode) => void;
+    /** Empty the selection. */
+    clear: () => void;
+    /** Select every point. */
+    selectAll: () => void;
+}
+/**
+ * The set of points a scatter has picked out, controlled or not.
+ *
+ * A caller may own the selection and pass it back through `selected`, or leave
+ * it here and only listen. Both work through one hook, and the controlled
+ * value wins on every render: a parent that answers a change by passing
+ * something else — a filter that keeps only the rows still on screen — sees
+ * what it asked for and not what the gesture asked for. The hook keeps its own
+ * copy up to date all the same, so a caller that stops passing `selected`
+ * carries on from where the reader left off rather than from nothing.
+ *
+ * A preview is deliberately not a change. What a half-drawn lasso would catch
+ * is merged in for the render and never reported, which is what lets a
+ * controlled parent stay out of a drag it would otherwise be re-rendered by
+ * sixty times a second.
+ * @param options - See {@link ScatterSelectionOptions}.
+ * @returns The selection. See {@link ScatterSelectionApi}.
+ */
+export declare function useScatterSelection(options: ScatterSelectionOptions): ScatterSelectionApi;
+//# sourceMappingURL=useScatterSelection.d.ts.map

package/lib/scatter/ui/useScatterSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useScatterSelection.d.ts","sourceRoot":"","sources":["../../../src/scatter/ui/useScatterSelection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOxE,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,wFAAwF;IACxF,IAAI,EAAE,oBAAoB,CAAC;IAC3B,iCAAiC;IACjC,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,KAAK,CAAC;CAC1D;AAED,8CAA8C;AAC9C,MAAM,WAAW,uBAAuB;IACtC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;CACvD;AAED,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,EAAE,UAAU,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,kDAAkD;IAClD,MAAM,EAAE,CACN,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EACtB,IAAI,CAAC,EAAE,oBAAoB,EAC3B,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC/B,IAAI,CAAC;IACV,qEAAqE;IACrE,UAAU,EAAE,CACV,IAAI,EAAE,UAAU,EAChB,IAAI,CAAC,EAAE,oBAAoB,EAC3B,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC/B,IAAI,CAAC;IACV,0EAA0E;IAC1E,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxE,2BAA2B;IAC3B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,uBAAuB,GAC/B,mBAAmB,CAgFrB"}