@pluot/react 0.1.16 → 0.1.18

package/src/{Pluot.jsx → Pluot.tsx}

@@ -1,16 +1,22 @@
-import React, { useLayoutEffect, useEffect, useEffectEvent, useRef, useState, useMemo, useReducer, useCallback, useId } from "react";
+import React, { useLayoutEffect, useEffect, useEffectEvent, useRef, useState, useMemo, useReducer, useId, type CSSProperties } from "react";
 import lzs from "lz-string";
-import { isEqual, throttle } from "lodash-es";
+import { throttle } from "lodash-es";
 import {
   initialize, getIsWasmReady,
-  render_wasm, pick_wasm,
+  render_wasm, pick_wasm, brush_wasm,
   normalizeStores, getStore,
-  getBounds, getCameraMatrixFromBounds,
   checkWebGpuFeatureDetection,
   onMouseMove2d, onWheel2d,
   onMouseMove3d, onWheel3d,
+  type CameraMatrix,
 } from '@pluot/core';
 import { Tooltip } from "./Tooltip.js";
+import { BrushOverlay } from "./BrushOverlay.js";
+import { useBrush } from "./use-brush.js";
+import type {
+  BrushingResult, BrushState, HoverInfo, PickingResult, PluotProps, RawBrushingResult, RawPickingResult,
+  RenderParams, TooltipContent,
+} from "./types.js";
 
 // Needed due to "SyntaxError: Named export 'decompressFromUint8Array' not found.
 // The requested module 'lz-string' is a CommonJS module,
@@ -32,28 +38,44 @@ const DEFAULT_3D_VIEW = new Float32Array([
   0, 0, -10, 1,
 ]);
 
-const identity = (param) => param;
+const identity = <T,>(param: T): T => param;
 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;
 
-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,
+// `pick_wasm` is typed `any` by wasm-bindgen, so `RawPickingResult` is what
+// documents its wire format (see types.ts).
+function normalizePickingResult(data: RawPickingResult): PickingResult {
+  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: RawBrushingResult): BrushingResult {
+  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) {
+
+export function Pluot(props: PluotProps) {
   const {
     schemaVersion = null,
     width: widthProp,
@@ -84,15 +106,38 @@ export function Pluot(props) {
     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 : identity;
-  const onHover = typeof onHoverProp === 'function' ? onHoverProp : identity;
+  const onClick: (result: PickingResult) => void = typeof onClickProp === 'function' ? onClickProp : noop;
+  const onHover: (result: PickingResult) => TooltipContent = typeof onHoverProp === 'function' ? onHoverProp : identity;
 
 
 
   // If cameraMatrix is not provided, then we manage the camera matrix internally.
-  const [uncontrolledCameraMatrix, setUncontrolledCameraMatrix] = useState(
+  const [uncontrolledCameraMatrix, setUncontrolledCameraMatrix] = useState<CameraMatrix>(
     // Note: We use an initializer function here to avoid
     // sharing the same Float32Array among multiple Pluot
     // component instances that may be rendered on the same page.
@@ -115,7 +160,7 @@ export function Pluot(props) {
   const cameraMatrix = isControlledCamera && controlledCameraMatrix !== null
     ? controlledCameraMatrix
     : uncontrolledCameraMatrix;
-  const setCameraMatrix = isControlledCamera
+  const setCameraMatrix: (nextCameraMatrix: CameraMatrix) => void = isControlledCamera
     ? setControlledCameraMatrix
     : setUncontrolledCameraMatrix;
 
@@ -136,11 +181,14 @@ export function Pluot(props) {
 
   const [supportsWebGpu, supportsWebGpuMessage] = useMemo(checkWebGpuFeatureDetection, []);
 
-  const svgRef = useRef(null);
-  const canvasRef = useRef(null);
-  const cameraElementRef = useRef(null);
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const cameraElementRef = useRef<HTMLDivElement | null>(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<HTMLDivElement | null>(null);
 
-  const tempButtonRef = useRef(null);
+  const tempButtonRef = useRef<HTMLButtonElement | null>(null);
 
   // We may want to update these things without triggering a re-render.
   const isRenderingRef = useRef(false);
@@ -148,31 +196,101 @@ export function Pluot(props) {
 
   // Used to distinguish a plain click from a click that ends a drag
   // (e.g. panning), so that dragging does not trigger picking.
-  const dragStartRef = useRef(null);
+  const dragStartRef = useRef<{ x: number, y: number } | null>(null);
   const didDragRef = useRef(false);
 
   // TODO: do we want to use the backlog approach or not?
   // (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: number) => 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 [hoverInfo, setHoverInfo] = useState<HoverInfo | null>(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: BrushState): Promise<BrushingResult|undefined> => {
+
+    if (!isWasmReady) {
+      return;
+    }
+
+    const renderParams: 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()));
   }, []);
 
-  const wheelHandler = useEffectEvent((event) => {
+  const wheelHandler = useEffectEvent((event: WheelEvent) => {
     const onWheel = viewMode === "3d" ? onWheel3d : onWheel2d;
     const nextCameraMatrix = onWheel({
         width,
@@ -189,7 +307,11 @@ export function Pluot(props) {
     setCameraMatrix(nextCameraMatrix);
   });
 
-  const mouseMoveHandler = useEffectEvent((event) => {
+  const mouseMoveHandler = useEffectEvent((event: MouseEvent) => {
+    // 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,
@@ -208,8 +330,8 @@ export function Pluot(props) {
 
   // Runs the picking query against the wasm module and returns the normalized result.
   // Shared by the click (pickFrame) and hover (hoverFrame) callbacks below.
-  const pick = useEffectEvent(async (screenCoordX, screenCoordY) => {
-    const renderParams = {
+  const pick = useEffectEvent(async (screenCoordX: number, screenCoordY: number): Promise<PickingResult> => {
+    const renderParams: RenderParams = {
       schema_version: schemaVersion,
       width,
       height,
@@ -251,12 +373,12 @@ export function Pluot(props) {
   });
 
   // The click-picking callback.
-  const pickFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
-    setPickingResult(onClick(await pick(screenCoordX, screenCoordY)));
+  const pickFrame = useEffectEvent(async (screenCoordX: number, screenCoordY: number) => {
+    onClick(await pick(screenCoordX, screenCoordY));
   });
 
   // The hover-picking callback.
-  const hoverFrame = useEffectEvent(async (screenCoordX, screenCoordY) => {
+  const hoverFrame = useEffectEvent(async (screenCoordX: number, screenCoordY: number) => {
     const result = await pick(screenCoordX, screenCoordY);
     setHoverInfo({
       content: onHover(result),
@@ -292,11 +414,15 @@ export function Pluot(props) {
 
     // Track mousedown -> mousemove distance so that a drag (e.g. panning)
     // that ends on the camera element does not also trigger a click/pick.
-    const mouseDownHandler = (event) => {
+    const mouseDownHandler = (event: MouseEvent) => {
       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) => {
+    const dragDetectHandler = (event: MouseEvent) => {
       if (!dragStartRef.current) {
         return;
       }
@@ -310,19 +436,23 @@ export function Pluot(props) {
     cameraEl.addEventListener("mousemove", dragDetectHandler);
 
     // Set up an onClick handler for picking.
-    const clickHandler = (event) => {
+    const clickHandler = (event: MouseEvent) => {
       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) {
+    const hoverMoveHandler = (event: MouseEvent) => {
+      if (enableTooltip && !isBrushingRef.current) {
         throttledHoverFrame(event.offsetX, event.offsetY);
       }
     };
@@ -354,7 +484,7 @@ export function Pluot(props) {
     isRenderingRef.current = true;
     console.log('wasm.render');
 
-    const renderParams = {
+    const renderParams: RenderParams = {
       schema_version: schemaVersion,
       width,
       height,
@@ -383,7 +513,7 @@ export function Pluot(props) {
     };
 
     // Wrap render_wasm in try/catch, to handle Rust panics.
-    let arr;
+    let arr: Uint8Array;
     try {
       arr = await render_wasm(renderParams);
 
@@ -436,9 +566,9 @@ export function Pluot(props) {
       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();
         }
       });
@@ -496,7 +626,7 @@ export function Pluot(props) {
 
   // Position the hover tooltip so that it grows diagonally away from whichever
   // quadrant of the plot the mouse currently occupies, to avoid clipping.
-  const hoverStyle = useMemo(() => {
+  const hoverStyle = useMemo<CSSProperties | null>(() => {
     if (!hoverInfo) {
       return null;
     }
@@ -509,6 +639,8 @@ 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 }),
     };
@@ -516,7 +648,14 @@ export function Pluot(props) {
 
   return (
     <>
-      <div style={{ width, height, position: "relative", backgroundColor }}>
+      <div
+        ref={containerRef}
+        style={{
+          width, height, position: "relative", backgroundColor,
+          // Long-clicking to start a brush otherwise selects surrounding text.
+          userSelect: enableBrushCreate ? "none" : undefined,
+        }}
+      >
         {!supportsWebGpu ? (
           <p>{supportsWebGpuMessage}</p>
         ) : null}
@@ -570,8 +709,22 @@ export function Pluot(props) {
 
           />
         )}
+        <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 ? (
-          <div style={hoverStyle}>
+          <div style={hoverStyle ?? undefined}>
             <Tooltip content={hoverInfo.content} asTable />
           </div>
         ) : null}

package/src/{Tooltip.jsx → Tooltip.tsx}

@@ -1,9 +1,25 @@
-import React from "react";
+import React, { type ReactNode } from "react";
+import type { TooltipProps } from "./types.js";
 
 
 const boxShadow = '5px 5px 15px rgb(0 0 0 / 20%)';
 
-export function Tooltip(props) {
+// Table cell values come from arbitrary onHover return objects, so narrow
+// them to something React can actually render.
+function renderCell(value: unknown): ReactNode {
+  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: TooltipProps) {
   const {
     content,
     asTable = false,
@@ -24,7 +40,7 @@ export function Tooltip(props) {
             {Object.entries(content).map(([key, value]) => (
               <tr key={key}>
                 <th style={{ border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }}>{key}</th>
-                <td style={{ border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }}>{value}</td>
+                <td style={{ border: 'none', fontSize: '12px', outline: 0, padding: '0 2px', textAlign: 'left' }}>{renderCell(value)}</td>
               </tr>
             ))}
           </tbody>