@pluot/react 0.1.16 → 0.1.18

package/dist-tsc/BrushOverlay.d.ts

@@ -0,0 +1,31 @@
+import React, { type RefObject } from "react";
+import { type BrushEdge, type BrushGeometry } from "./brush.js";
+import type { BrushState } from "./types.js";
+import { type BrushPressProgress } from "./use-brush.js";
+export type BrushOverlayProps = {
+    width: number;
+    height: number;
+    /** From `useBrush`, so that presses on the handles below are not read as new brushes. */
+    overlayRef: RefObject<SVGSVGElement | null>;
+    /** Supplies the brushable region, which everything drawn here is clipped to. */
+    geometry: BrushGeometry;
+    /** Stroke color of the brush outline/handles; the fill uses the same color at reduced opacity. */
+    color: string;
+    brushState: BrushState | undefined;
+    pressProgress: BrushPressProgress | null;
+    /** Whether to draw the clear button (the pointer is over the brush and `enableBrushClear`). */
+    isBrushHovered: boolean;
+    enableBrushEdit: boolean;
+    onVertexMouseDown: (vertexIndex: number, event: React.MouseEvent) => void;
+    onEdgeMouseDown: (edge: BrushEdge, event: React.MouseEvent) => void;
+    onClearClick: (event: React.MouseEvent) => void;
+};
+/**
+ * Draws the brush as an SVG above the plot: a rectangle (or lasso polygon) with
+ * a circle at each vertex, plus the long-click progress wedge and the clear button.
+ *
+ * The SVG root is `pointerEvents: none` so that it never intercepts the camera's
+ * pan/zoom; only the vertex handles and the clear button opt back in.
+ */
+export declare function BrushOverlay(props: BrushOverlayProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=BrushOverlay.d.ts.map

package/dist-tsc/BrushOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrushOverlay.d.ts","sourceRoot":"","sources":["../src/BrushOverlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAkB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EAEL,KAAK,SAAS,EAAE,KAAK,aAAa,EACnC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAgBjF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,UAAU,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,EAAE,aAAa,CAAC;IACxB,kGAAkG;IAClG,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;IACnC,aAAa,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC1E,eAAe,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACpE,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;CACjD,CAAC;AA0BF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,2CAyLpD"}

package/dist-tsc/BrushOverlay.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from "react";
+import { describeWedgePath, getClearButtonCenter, getEdgeLine, getEditableEdges, getVerticesBoundingBox, } from "./brush.js";
+import { CLEAR_BUTTON_RADIUS_PX } from "./use-brush.js";
+const VERTEX_HANDLE_RADIUS_PX = 4;
+const PRESS_INDICATOR_RADIUS_PX = 10;
+/** How wide a side's invisible grab target is. Kept generous, since a side is 1.5px of ink. */
+const EDGE_HANDLE_WIDTH_PX = 9;
+/** Opacity of the brush's fill, relative to `color`; the stroke and handles stay fully opaque. */
+const BRUSH_FILL_OPACITY = 0.15;
+const HANDLE_FILL = "#ffffff";
+const CLEAR_FILL = "#b34040";
+/** A side is dragged along its perpendicular, so it takes the matching resize cursor. */
+function getEdgeCursor(edge) {
+    return edge === "Left" || edge === "Right" ? "ew-resize" : "ns-resize";
+}
+/**
+ * The cursor for corner `vertexIndex`, which advertises the axes that corner can
+ * actually move: a range brush only resizes along the axis it selects, and a rect
+ * corner resizes along the diagonal it sits on.
+ */
+function getVertexCursor(shape, vertexIndex) {
+    if (shape === "RangeX") {
+        return "ew-resize";
+    }
+    if (shape === "RangeY") {
+        return "ns-resize";
+    }
+    if (shape === "Rect") {
+        // Corners are ordered clockwise from the top-left.
+        return vertexIndex % 2 === 0 ? "nwse-resize" : "nesw-resize";
+    }
+    return "grab";
+}
+/**
+ * Draws the brush as an SVG above the plot: a rectangle (or lasso polygon) with
+ * a circle at each vertex, plus the long-click progress wedge and the clear button.
+ *
+ * The SVG root is `pointerEvents: none` so that it never intercepts the camera's
+ * pan/zoom; only the vertex handles and the clear button opt back in.
+ */
+export function BrushOverlay(props) {
+    const { width, height, overlayRef, geometry, color, brushState, pressProgress, isBrushHovered, enableBrushEdit, onVertexMouseDown, onEdgeMouseDown, onClearClick, } = props;
+    const vertices = brushState?.vertices ?? [];
+    // Every shape but the lasso is a closed rectangle throughout the drag; a lasso
+    // is left open while the user is still drawing it, and closed once the drag completes.
+    const isClosed = (brushState !== undefined && brushState.shape !== "Polygon")
+        || brushState?.status === "Complete";
+    const pathData = useMemo(() => {
+        if (vertices.length === 0) {
+            return null;
+        }
+        const points = vertices.map(v => `${v.x_pixels},${v.y_pixels}`).join(" L ");
+        return `M ${points}${isClosed ? " Z" : ""}`;
+    }, [vertices, isClosed]);
+    const clearButtonCenter = getClearButtonCenter(vertices, CLEAR_BUTTON_RADIUS_PX, geometry);
+    // `useId` emits colons, which are legal in an id but awkward inside `url(#...)`.
+    const clipPathId = `pluot-brush-clip-${useId().replace(/:/g, "")}`;
+    // While drawing a lasso, the intermediate vertices are too dense to be useful
+    // as handles, and they are not editable until the drag completes. RangeX/RangeY
+    // brushes only resize along one axis via their edges, so their corners are not
+    // meaningful drag handles either.
+    const shouldShowVertexHandles = isClosed
+        && brushState?.shape !== "RangeX"
+        && brushState?.shape !== "RangeY";
+    // Sides are draggable only once the shape is settled, and only for the
+    // axis-aligned shapes; a lasso has no meaningful sides.
+    const editableEdges = enableBrushEdit && isClosed && brushState
+        ? getEditableEdges(brushState.shape)
+        : [];
+    // The side handles are the only thing here that needs the extent, so it is not
+    // computed for a lasso or for a brush whose sides are not draggable.
+    const edgeBoundingBox = editableEdges.length > 0 ? getVerticesBoundingBox(vertices) : null;
+    return (_jsxs("svg", { ref: overlayRef, style: {
+            position: "absolute",
+            top: 0,
+            left: 0,
+            marginTop: 0,
+            marginLeft: 0,
+            marginRight: 0,
+            marginBottom: 0,
+            pointerEvents: "none",
+            // Sit above the canvas/SVG plot and the camera element.
+            zIndex: 1,
+        }, width: width, height: height, viewBox: `0 0 ${width} ${height}`, xmlns: "http://www.w3.org/2000/svg", children: [_jsx("defs", { children: _jsx("clipPath", { id: clipPathId, children: _jsx("rect", { x: geometry.brushLeft, y: geometry.brushTop, width: Math.max(geometry.brushRight - geometry.brushLeft, 0), height: Math.max(geometry.brushBottom - geometry.brushTop, 0) }) }) }), _jsxs("g", { clipPath: `url(#${clipPathId})`, children: [pathData ? (_jsx("path", { d: pathData, fill: isClosed ? color : "none", fillOpacity: isClosed ? BRUSH_FILL_OPACITY : undefined, stroke: color, strokeWidth: 1.5, strokeDasharray: brushState?.status === "Drawing" ? "4 3" : undefined })) : null, edgeBoundingBox === null ? null : editableEdges.map(edge => {
+                        const [x1, y1, x2, y2] = getEdgeLine(edge, edgeBoundingBox);
+                        return (_jsx("line", { x1: x1, y1: y1, x2: x2, y2: y2, 
+                            // Invisible ink, but a wide grab target.
+                            stroke: "transparent", strokeWidth: EDGE_HANDLE_WIDTH_PX, strokeLinecap: "butt", style: { pointerEvents: "stroke", cursor: getEdgeCursor(edge) }, onMouseDown: event => onEdgeMouseDown(edge, event) }, edge));
+                    }), shouldShowVertexHandles ? vertices.map((vertex, vertexIndex) => (_jsx("circle", { cx: vertex.x_pixels, cy: vertex.y_pixels, r: VERTEX_HANDLE_RADIUS_PX, fill: HANDLE_FILL, stroke: color, strokeWidth: 1.5, style: {
+                            pointerEvents: enableBrushEdit ? "auto" : "none",
+                            cursor: enableBrushEdit ? getVertexCursor(brushState?.shape, vertexIndex) : "default",
+                        }, onMouseDown: enableBrushEdit ? (event => onVertexMouseDown(vertexIndex, event)) : undefined }, vertexIndex))) : null, isBrushHovered && clearButtonCenter ? (_jsxs("g", { style: { pointerEvents: "auto", cursor: "pointer" }, onClick: onClearClick, role: "button", "aria-label": "Clear brush", children: [_jsx("circle", { cx: clearButtonCenter[0], cy: clearButtonCenter[1], r: CLEAR_BUTTON_RADIUS_PX, fill: CLEAR_FILL }), _jsx("path", { d: `M ${clearButtonCenter[0] - 4} ${clearButtonCenter[1] - 4} L ${clearButtonCenter[0] + 4} ${clearButtonCenter[1] + 4} `
+                                    + `M ${clearButtonCenter[0] + 4} ${clearButtonCenter[1] - 4} L ${clearButtonCenter[0] - 4} ${clearButtonCenter[1] + 4}`, stroke: "#ffffff", strokeWidth: 1.5, strokeLinecap: "round" })] })) : null, pressProgress ? (_jsxs("g", { children: [_jsx("circle", { cx: pressProgress.xPixels, cy: pressProgress.yPixels, r: PRESS_INDICATOR_RADIUS_PX, fill: "rgba(255, 255, 255, 0.6)", stroke: color, strokeWidth: 1.5 }), _jsx("path", { d: describeWedgePath(pressProgress.xPixels, pressProgress.yPixels, PRESS_INDICATOR_RADIUS_PX, pressProgress.fraction), fill: color })] })) : null] })] }));
+}

package/dist-tsc/Pluot.d.ts

@@ -1,2 +1,3 @@
-export function Pluot(props: any): any;
+import type { PluotProps } from "./types.js";
+export declare function Pluot(props: PluotProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Pluot.d.ts.map

package/dist-tsc/Pluot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pluot.d.ts","sourceRoot":"","sources":["../src/Pluot.jsx"],"names":[],"mappings":"AAuDA,uCA8gBC"}
+{"version":3,"file":"Pluot.d.ts","sourceRoot":"","sources":["../src/Pluot.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAC4C,UAAU,EAEjE,MAAM,YAAY,CAAC;AA2DpB,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,2CAipBtC"}

package/dist-tsc/Pluot.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import React, { useLayoutEffect, useEffect, useEffectEvent, useRef, useState, useMemo, useReducer, useCallback, useId } from "react";
+import { useLayoutEffect, useEffect, useEffectEvent, useRef, useState, useMemo, useReducer, useId } from "react";
 import lzs from "lz-string";
-import { isEqual, throttle } from "lodash-es";
-import { initialize, getIsWasmReady, render_wasm, pick_wasm, normalizeStores, getStore, getBounds, getCameraMatrixFromBounds, checkWebGpuFeatureDetection, onMouseMove2d, onWheel2d, onMouseMove3d, onWheel3d, } from '@pluot/core';
+import { throttle } from "lodash-es";
+import { initialize, getIsWasmReady, render_wasm, pick_wasm, brush_wasm, normalizeStores, getStore, checkWebGpuFeatureDetection, onMouseMove2d, onWheel2d, onMouseMove3d, onWheel3d, } from '@pluot/core';
 import { Tooltip } from "./Tooltip.js";
+import { BrushOverlay } from "./BrushOverlay.js";
+import { useBrush } from "./use-brush.js";
 // Needed due to "SyntaxError: Named export 'decompressFromUint8Array' not found.
 // The requested module 'lz-string' is a CommonJS module,
 // which may not support all module.exports as named exports."
@@ -25,24 +27,44 @@ const noop = () => { };
 // Mouse movement (in pixels) beyond which a mousedown-to-click is
 // considered a drag rather than a click, so that picking is skipped.
 const DRAG_THRESHOLD_PX = 3;
+// `pick_wasm` is typed `any` by wasm-bindgen, so `RawPickingResult` is what
+// documents its wire format (see types.ts).
 function normalizePickingResult(data) {
-    const result = data;
-    if (data && Array.isArray(result.layer_results)) {
-        result.layer_results = result.layer_results.map(obj => ({
-            layer_id: obj.layer_id,
+    return {
+        ...data,
+        layer_results: data.layer_results.map(({ layer_id, info }) => ({
+            layer_id,
             // This is needed because serde-wasm-bindgen
             // converts Rust HashMap to JS Map.
-            info: Object.fromEntries(Array.from(obj.info)),
-        }));
-    }
-    return result;
+            info: Object.fromEntries(info),
+        })),
+    };
+}
+// `brush_wasm` is typed `any` by wasm-bindgen, so `RawBrushingResult` is what
+// documents its wire format (see types.ts).
+function normalizeBrushingResult(data) {
+    return {
+        ...data,
+        layer_results: data.layer_results.map(({ layer_id, info, element_info }) => ({
+            layer_id,
+            // This is needed because serde-wasm-bindgen
+            // converts Rust HashMap to JS Map.
+            info: Object.fromEntries(info),
+            element_info: Object.fromEntries(element_info),
+        })),
+    };
 }
 export function Pluot(props) {
     const { schemaVersion = null, width: widthProp, height: heightProp, plotId, plotType, store: storeProp, storeName: storeNameProp, stores: storesProp, registerStores = true, plotParams, viewMode = "2d", marginBottom = 100.0, marginLeft = 100.0, marginTop = 100.0, marginRight = 100.0, aspectRatioMode = "Contain", // "Ignore", "Contain", "Cover"
     aspectRatioAlignmentMode = "Start", // "Center", "Start", "End"
     format = "Raster", // "Raster", "Vector"
-    minTimeout = 32, maxTimeout = 5000, allowSimultaneousRenders = true, debugMargins = false, backgroundColor = undefined, cameraMatrix: controlledCameraMatrix = null, setCameraMatrix: setControlledCameraMatrix = null, enableClick = false, enableTooltip = false, onClick: onClickProp = null, onHover: onHoverProp = null, } = props;
-    const onClick = typeof onClickProp === 'function' ? onClickProp : identity;
+    minTimeout = 32, maxTimeout = 5000, allowSimultaneousRenders = true, debugMargins = false, backgroundColor = undefined, cameraMatrix: controlledCameraMatrix = null, setCameraMatrix: setControlledCameraMatrix = null, enableClick = false, enableTooltip = false, onClick: onClickProp = null, onHover: onHoverProp = null, brushUnitsModeX = "Data", brushUnitsModeY = "Data", brushMarginTop, brushMarginRight, brushMarginBottom, brushMarginLeft, enableBrushCreate = false, enableBrushEdit = false, enableBrushClear = false, brushDelay = 1500, maybeBrushDelay = 250, persistBrush = false, brushMode = "Rect", brushColor = "#3b6ea5", 
+    // An omitted `brush` means uncontrolled; a controlled parent signals the
+    // empty state with `NO_BRUSH`, never `undefined`.
+    brush = null, onBrush, onBrushEnd, onBrushClear, 
+    // Temporary workaround. See comments in LruStore.clearCache.
+    shouldClearCache = true, } = props;
+    const onClick = typeof onClickProp === 'function' ? onClickProp : noop;
     const onHover = typeof onHoverProp === 'function' ? onHoverProp : identity;
     // If cameraMatrix is not provided, then we manage the camera matrix internally.
     const [uncontrolledCameraMatrix, setUncontrolledCameraMatrix] = useState(
@@ -84,6 +106,9 @@ export function Pluot(props) {
     const svgRef = useRef(null);
     const canvasRef = useRef(null);
     const cameraElementRef = useRef(null);
+    // The outer (width x height) element, which is the coordinate space that both
+    // the brush overlay and the hover tooltip are positioned within.
+    const containerRef = useRef(null);
     const tempButtonRef = useRef(null);
     // We may want to update these things without triggering a re-render.
     const isRenderingRef = useRef(false);
@@ -96,15 +121,68 @@ export function Pluot(props) {
     // (Similar to the one used in the Vitessce heatmap)
     // Reference: https://github.com/vitessce/vitessce/blob/71f17fb605768e0428fb15ed87b3ea34bcbb4803/packages/view-types/heatmap/src/Heatmap.js#L368
     //const backlogRef = useRef([]);
-    const [backlogIteration, incBacklogIteration] = useReducer(i => i + 1, 0);
+    const [backlogIteration, incBacklogIteration] = useReducer((i) => i + 1, 0);
     const [isWasmReady, setIsWasmReady] = useState(false);
     const [didFirstRender, setDidFirstRender] = useState(false);
     const [bailedEarly, setBailedEarly] = useState(true);
-    const [pickingResult, setPickingResult] = useState(null);
     // hoverInfo.mouseX/mouseY are in the coordinate space of the outer
     // (width x height) container, used to position the hover tooltip.
     const [hoverInfo, setHoverInfo] = useState(null);
     const progressBarId = useId();
+    // Runs the brush query against the wasm module for a given brush state,
+    // analogous to `pick` below (defined here, ahead of `pick`, since `useBrush`
+    // needs it immediately).
+    const runBrush = useEffectEvent(async (state) => {
+        if (!isWasmReady) {
+            return;
+        }
+        const renderParams = {
+            schema_version: schemaVersion,
+            width,
+            height,
+            format: format,
+            margin_bottom: marginBottom,
+            margin_left: marginLeft,
+            margin_top: marginTop,
+            margin_right: marginRight,
+            device_pixel_ratio: window.devicePixelRatio,
+            aspect_ratio_mode: aspectRatioMode,
+            aspect_ratio_alignment_mode: aspectRatioAlignmentMode,
+            view_mode: viewMode,
+            pickable: false,
+            camera_view: cameraMatrix,
+            plot_id: plotId,
+            plot_type: plotType,
+            stores,
+            plot_params: plotParams,
+            timeout: currentTimeout.current,
+            wait_for_store_gets: false,
+            cache_enabled: true,
+            svg_compression_enabled: true,
+            svg_include_document: false,
+        };
+        // Brush vertices are container-relative pixels with Y increasing downwards;
+        // the wasm side expects screen coordinates with Y increasing upwards (as
+        // with the `screenCoordX`/`screenCoordY` passed to `pick_wasm` below).
+        const brushParams = {
+            screen_vertices: state.vertices.map((vertex) => ({ x: vertex.x_pixels, y: height - vertex.y_pixels })),
+            brush_units_mode_x: brushUnitsModeX,
+            brush_units_mode_y: brushUnitsModeY,
+            brush_mode: state.shape,
+        };
+        return normalizeBrushingResult(await brush_wasm(renderParams, brushParams));
+    });
+    const { brushState, overlayRef: brushOverlayRef, geometry: brushGeometry, pressProgress, isBrushHovered, isBrushingRef, shouldSuppressClickRef, onVertexMouseDown, onEdgeMouseDown, onClearClick, } = useBrush({
+        containerRef,
+        width, height,
+        marginTop, marginRight, marginBottom, marginLeft,
+        aspectRatioMode, aspectRatioAlignmentMode, cameraMatrix,
+        brushUnitsModeX, brushUnitsModeY,
+        brushMarginTop, brushMarginRight, brushMarginBottom, brushMarginLeft,
+        enableBrushCreate, enableBrushEdit, enableBrushClear,
+        brushDelay, maybeBrushDelay, persistBrush, brushMode,
+        brush, onBrush, onBrushEnd, onBrushClear, runBrush,
+    });
     useLayoutEffect(() => {
         initialize().then(() => setIsWasmReady(getIsWasmReady()));
     }, []);
@@ -125,6 +203,10 @@ export function Pluot(props) {
         setCameraMatrix(nextCameraMatrix);
     });
     const mouseMoveHandler = useEffectEvent((event) => {
+        // A drag that is drawing or editing a brush must not also pan/rotate the camera.
+        if (isBrushingRef.current) {
+            return;
+        }
         const onMouseMove = viewMode === "3d" ? onMouseMove3d : onMouseMove2d;
         const nextCameraMatrix = onMouseMove({
             width,
@@ -179,7 +261,7 @@ export function Pluot(props) {
     });
     // The click-picking callback.
     const pickFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
-        setPickingResult(onClick(await pick(screenCoordX, screenCoordY)));
+        onClick(await pick(screenCoordX, screenCoordY));
     });
     // The hover-picking callback.
     const hoverFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
@@ -210,6 +292,10 @@ export function Pluot(props) {
         const mouseDownHandler = (event) => {
             dragStartRef.current = { x: event.clientX, y: event.clientY };
             didDragRef.current = false;
+            // A brush drag that ended outside the camera element never produced the
+            // click that would have consumed this flag, so clear it as the next
+            // interaction begins rather than letting it suppress that one too.
+            shouldSuppressClickRef.current = false;
         };
         const dragDetectHandler = (event) => {
             if (!dragStartRef.current) {
@@ -226,16 +312,20 @@ export function Pluot(props) {
         // Set up an onClick handler for picking.
         const clickHandler = (event) => {
             const wasDrag = didDragRef.current;
+            // A brush drag (or a click on the clear button) ends with a click on the
+            // camera element, which should not also run a picking query.
+            const wasBrush = shouldSuppressClickRef.current;
             dragStartRef.current = null;
             didDragRef.current = false;
-            if (enableClick && !wasDrag) {
+            shouldSuppressClickRef.current = false;
+            if (enableClick && !wasDrag && !wasBrush) {
                 pickFrame(event.offsetX, event.offsetY);
             }
         };
         cameraEl.addEventListener("click", clickHandler);
         // Set up hover handlers for picking, only when the onHover prop is provided.
         const hoverMoveHandler = (event) => {
-            if (enableTooltip) {
+            if (enableTooltip && !isBrushingRef.current) {
                 throttledHoverFrame(event.offsetX, event.offsetY);
             }
         };
@@ -338,9 +428,9 @@ export function Pluot(props) {
             currentTimeout.current = minTimeout;
             setBailedEarly(false); // Update this to hide the loading indicator.
             // Clear the LRU cache for the store (via its store_name) corresponding to the rendered plot.
-            Object.keys(stores).forEach(storeName => {
+            Object.keys(stores ?? {}).forEach(storeName => {
                 const storeUsed = getStore(storeName);
-                if (storeUsed && storeUsed.clearCache && typeof storeUsed.clearCache === 'function') {
+                if (storeUsed && typeof storeUsed.clearCache === 'function' && shouldClearCache) {
                     storeUsed.clearCache();
                 }
             });
@@ -396,11 +486,17 @@ export function Pluot(props) {
         return {
             position: "absolute",
             pointerEvents: "none",
+            // Above the brush overlay, so a persisted brush does not tint the tooltip.
+            zIndex: 2,
             ...(isTop ? { top: mouseY + offsetPx } : { bottom: height - mouseY + offsetPx + extraPx }),
             ...(isLeft ? { left: mouseX + offsetPx + extraPx } : { right: width - mouseX + offsetPx }),
         };
     }, [hoverInfo, width, height]);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { style: { width, height, position: "relative", backgroundColor }, children: [!supportsWebGpu ? (_jsx("p", { children: supportsWebGpuMessage })) : null, _jsx("div", { ref: cameraElementRef, style: {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: containerRef, style: {
+                    width, height, position: "relative", backgroundColor,
+                    // Long-clicking to start a brush otherwise selects surrounding text.
+                    userSelect: enableBrushCreate ? "none" : undefined,
+                }, children: [!supportsWebGpu ? (_jsx("p", { children: supportsWebGpuMessage })) : null, _jsx("div", { ref: cameraElementRef, style: {
                             position: "absolute",
                             top: marginTop,
                             left: marginLeft,
@@ -418,5 +514,5 @@ export function Pluot(props) {
                         }) : {}) })) : (_jsx("canvas", { ref: canvasRef, style: { width, height, border: `${debugMargins ? 1 : 0}px solid black` }, width: width, height: height, ...(bailedEarly ? ({
                             ['aria-busy']: true,
                             ['aria-describedby']: progressBarId,
-                        }) : {}) })), hoverInfo ? (_jsx("div", { style: hoverStyle, children: _jsx(Tooltip, { content: hoverInfo.content, asTable: true }) })) : null] }), _jsx("button", { ref: tempButtonRef, style: { display: 'none' }, children: "Try lookAt" })] }));
+                        }) : {}) })), _jsx(BrushOverlay, { width: width, height: height, overlayRef: brushOverlayRef, geometry: brushGeometry, color: brushColor, brushState: brushState, pressProgress: pressProgress, isBrushHovered: isBrushHovered, enableBrushEdit: enableBrushEdit, onVertexMouseDown: onVertexMouseDown, onEdgeMouseDown: onEdgeMouseDown, onClearClick: onClearClick }), hoverInfo ? (_jsx("div", { style: hoverStyle ?? undefined, children: _jsx(Tooltip, { content: hoverInfo.content, asTable: true }) })) : null] }), _jsx("button", { ref: tempButtonRef, style: { display: 'none' }, children: "Try lookAt" })] }));
 }

package/dist-tsc/Tooltip.d.ts

@@ -1,2 +1,3 @@
-export function Tooltip(props: any): any;
+import type { TooltipProps } from "./types.js";
+export declare function Tooltip(props: TooltipProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=Tooltip.d.ts.map

package/dist-tsc/Tooltip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.jsx"],"names":[],"mappings":"AAKA,yCA6BC"}
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../src/Tooltip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAoB/C,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,kDA6B1C"}

package/dist-tsc/Tooltip.js

@@ -1,6 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 const boxShadow = '5px 5px 15px rgb(0 0 0 / 20%)';
+// Table cell values come from arbitrary onHover return objects, so narrow
+// them to something React can actually render.
+function renderCell(value) {
+    if (value === null || value === undefined || typeof value === "boolean") {
+        return null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return value;
+    }
+    if (React.isValidElement(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
 export function Tooltip(props) {
     const { content, asTable = false, } = props;
     if (!content) {
@@ -13,7 +27,7 @@ export function Tooltip(props) {
         return content;
     }
     if (asTable) {
-        return (_jsx("table", { style: { display: 'inline-block', marginBottom: 0, opacity: 0.9, padding: '5px', backgroundColor: 'white', borderRadius: '2px', boxShadow }, children: _jsx("tbody", { children: Object.entries(content).map(([key, value]) => (_jsxs("tr", { children: [_jsx("th", { style: { border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }, children: key }), _jsx("td", { style: { border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }, children: value })] }, key))) }) }));
+        return (_jsx("table", { style: { display: 'inline-block', marginBottom: 0, opacity: 0.9, padding: '5px', backgroundColor: 'white', borderRadius: '2px', boxShadow }, children: _jsx("tbody", { children: Object.entries(content).map(([key, value]) => (_jsxs("tr", { children: [_jsx("th", { style: { border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }, children: key }), _jsx("td", { style: { border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }, children: renderCell(value) })] }, key))) }) }));
     }
     return _jsx("pre", { children: JSON.stringify(content, null, 2) });
 }

package/dist-tsc/brush.d.ts

@@ -0,0 +1,155 @@
+import { type AspectRatioMode, type AspectRatioAlignmentMode, type Bounds, type CameraMatrix } from "@pluot/core";
+import type { BrushMode, BrushState, BrushUnitsMode, BrushVertex, RectLikeBrushMode } from "./types.js";
+/** An axis-aligned brush extent, in container pixels. */
+export type BrushBoundingBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** One side of an axis-aligned brush, which the user can drag to extend it. */
+export type BrushEdge = "Top" | "Right" | "Bottom" | "Left";
+/**
+ * Everything needed to convert a brush vertex between the three units modes.
+ *
+ * There are two rectangles involved, both expressed in *container* pixels
+ * (relative to the top-left of the outer `width` x `height` element, Y down),
+ * which is also the coordinate space of the brush overlay SVG:
+ *
+ * - The **layer** rect (the camera region, inside `margin*`), which anchors the
+ *   `Data` units mode, since that is the region the camera matrix maps onto.
+ * - The **brushable** rect (inside `brushMargin*`), which bounds where the user
+ *   may draw and which anchors the `Normalized` units mode.
+ *
+ * Note that `Data` and `Normalized` are Y-up (matching Pluot's data coordinate
+ * system, where `getBounds().yMin` is the bottom of the layer), whereas
+ * `Pixels` is Y-down (matching the DOM/SVG convention).
+ */
+export type BrushGeometry = {
+    layerLeft: number;
+    layerTop: number;
+    layerWidth: number;
+    layerHeight: number;
+    brushLeft: number;
+    brushTop: number;
+    brushRight: number;
+    brushBottom: number;
+    /** The visible data range of the layer rect, under the current camera. */
+    dataBounds: Required<Bounds>;
+};
+export type BrushGeometryParams = {
+    width: number;
+    height: number;
+    marginTop: number;
+    marginRight: number;
+    marginBottom: number;
+    marginLeft: number;
+    /** Each defaults to the corresponding layer margin when undefined. */
+    brushMarginTop: number | undefined;
+    brushMarginRight: number | undefined;
+    brushMarginBottom: number | undefined;
+    brushMarginLeft: number | undefined;
+    brushUnitsModeX: BrushUnitsMode;
+    brushUnitsModeY: BrushUnitsMode;
+    aspectRatioMode: AspectRatioMode;
+    aspectRatioAlignmentMode: AspectRatioAlignmentMode;
+    cameraMatrix: CameraMatrix;
+};
+export declare function getBrushGeometry(params: BrushGeometryParams): BrushGeometry;
+/**
+ * Build a full {@link BrushVertex} (all three units modes) from a position in
+ * container pixels.
+ */
+export declare function vertexFromPixels(xPixels: number, yPixels: number, geom: BrushGeometry): BrushVertex;
+/**
+ * Recover the container-pixel position of a vertex from whichever of its
+ * representations is authoritative for each axis.
+ *
+ * Only the representation matching the units mode survives a camera or resize
+ * change; the other two are derived, so they must be recomputed rather than
+ * read back (see {@link reprojectVertex}).
+ */
+export declare function pixelsFromVertex(vertex: BrushVertex, geom: BrushGeometry, brushUnitsModeX: BrushUnitsMode, brushUnitsModeY: BrushUnitsMode): [number, number];
+/**
+ * Re-derive the non-authoritative representations of a vertex under the current
+ * geometry. This is what makes a `Data`-units brush track the camera as the user
+ * zooms/pans: `x_data`/`y_data` stay fixed while the pixel positions move.
+ */
+export declare function reprojectVertex(vertex: BrushVertex, geom: BrushGeometry, brushUnitsModeX: BrushUnitsMode, brushUnitsModeY: BrushUnitsMode): BrushVertex;
+export declare function reprojectBrushState(state: BrushState, geom: BrushGeometry, brushUnitsModeX: BrushUnitsMode, brushUnitsModeY: BrushUnitsMode): BrushState;
+/** Restrict a container-pixel position to the brushable region. */
+export declare function clampToBrushRegion(xPixels: number, yPixels: number, geom: BrushGeometry): [number, number];
+/**
+ * The four corners of the rect spanned by two opposite corners, ordered
+ * clockwise in pixel space starting from the top-left, so that corner `i` is
+ * always diagonally opposite corner `(i + 2) % 4`.
+ *
+ * `RangeX` and `RangeY` select along a single axis, so the other axis is
+ * discarded and pinned to the full extent of the brushable region.
+ */
+export declare function rectVerticesFromCorners(x0: number, y0: number, x1: number, y1: number, geom: BrushGeometry, shape?: RectLikeBrushMode): BrushVertex[];
+/** The bounding box, in container pixels, of a list of already-reprojected vertices. */
+export declare function getVerticesBoundingBox(vertices: BrushVertex[]): BrushBoundingBox | null;
+/**
+ * Whether a brush is too small to be a selection.
+ *
+ * A long-click that never turns into a drag produces a rect whose four corners
+ * coincide, which draws as a stray dot rather than as nothing, so these states
+ * are held back instead of being committed.
+ */
+export declare function isDegenerateBrush(state: BrushState): boolean;
+/**
+ * Where the clear button sits: adjacent to the brush's first vertex — the
+ * top-left corner of a rect, or the point a lasso was started from.
+ *
+ * Anchoring to the first vertex keeps the button in one place while a lasso is
+ * being drawn, rather than trailing the cursor around the shape. It is pushed
+ * outwards along the ray from the centroid through that vertex, so it lands
+ * outside the brush and does not obscure the brushed content. Returns `null` for
+ * an empty brush.
+ *
+ * The result is kept within the brushable region, since the overlay is clipped to
+ * that region and a button pushed outside it would be invisible and unclickable.
+ */
+export declare function getClearButtonCenter(vertices: BrushVertex[], radius: number, geom: BrushGeometry): [number, number] | null;
+/**
+ * Which sides of a brush the user may drag to extend it.
+ *
+ * A range brush pins its unselected axis to the whole brushable region, so
+ * dragging those two sides could not change anything and they are left out.
+ */
+export declare function getEditableEdges(shape: BrushMode): BrushEdge[];
+/** The endpoints `[x1, y1, x2, y2]` of an edge, in container pixels. */
+export declare function getEdgeLine(edge: BrushEdge, boundingBox: BrushBoundingBox): [number, number, number, number];
+/**
+ * The two opposite corners that dragging `edge` spans: the corner that stays
+ * put, and the corner that follows the cursor along `axis` only.
+ *
+ * Expressing an edge drag as a pair of corners lets it reuse
+ * {@link rectVerticesFromCorners}, which also means dragging a side past its
+ * opposite side flips the brush rather than inverting it.
+ */
+export declare function getEdgeDragCorners(edge: BrushEdge, boundingBox: BrushBoundingBox): {
+    axis: "X" | "Y";
+    fixedX: number;
+    fixedY: number;
+    movingX: number;
+    movingY: number;
+};
+/**
+ * Whether a container-pixel position lies inside a brush, used to decide when to
+ * reveal the clear button. Hit-testing is done here rather than with SVG pointer
+ * events so that the overlay never swallows camera pan/zoom interactions.
+ * TODO: replace this by using the regular onHover events in the brush overlay SVG.
+ * The challenge with using the regular onHover events in the overlay is that
+ * it makes it tricky to avoid absorbing the hover/mouse events which the camera pan/zoom need.
+ * An alternative/intermediate optimization would be to compute the polygon bounding box
+ * upon the polygon creation/modification, and do hit-testing against that cached bounding box instead.
+ */
+export declare function isPointInBrush(xPixels: number, yPixels: number, vertices: BrushVertex[]): boolean;
+/**
+ * An SVG path for a pie wedge filled clockwise from 12 o'clock, used to
+ * visualize progress towards the long-click that starts a brush.
+ */
+export declare function describeWedgePath(cx: number, cy: number, radius: number, fraction: number): string;
+//# sourceMappingURL=brush.d.ts.map

package/dist-tsc/brush.d.ts.map

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