react-cheminfo 0.15.0 → 0.17.0

package/src/parallel/ui/useParallelCanvas.ts

@@ -0,0 +1,104 @@
+/**
+ * The two canvases, and when they are repainted.
+ *
+ * Two rather than one, because the mass of lines changes when the data or the
+ * brushes do, while the row under the pointer changes on every frame the
+ * pointer moves. Repainting ten thousand lines to move one highlight is the
+ * difference between a figure that follows the pointer and one that lags it.
+ */
+
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import type { ParallelHighlight } from '../core/parallelPaint.ts';
+import {
+  paintParallelHighlights,
+  paintParallelLines,
+  preparePlotCanvas,
+} from '../core/parallelPaint.ts';
+
+import type { ParallelInkValues } from './parallelInk.ts';
+
+/** What {@link useParallelCanvas} needs. */
+export interface ParallelCanvasOptions {
+  /** Total width of the figure, in CSS pixels. */
+  width: number;
+  /** Its total height. */
+  height: number;
+  /** The axes, from left to right. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** How many rows are drawn. */
+  count: number;
+  /** Which rows the brushes keep, or `null` when they keep every one. */
+  included: Uint8Array | null;
+  /** Which colour each row takes, or `null` when nothing is colouring them. */
+  steps: Uint8Array | null;
+  /** The colours a step indexes. */
+  palette: readonly string[];
+  /** The rows drawn over the mass, the last one on top. */
+  highlights: readonly ParallelHighlight[];
+  /** The colours to paint with. */
+  ink: ParallelInkValues;
+}
+
+/** The two canvases a figure stacks. */
+export interface ParallelCanvases {
+  /** The mass of lines, underneath. */
+  lines: RefObject<HTMLCanvasElement | null>;
+  /** The singled-out rows, over them. */
+  marks: RefObject<HTMLCanvasElement | null>;
+}
+
+/**
+ * Keep both canvases sized to the device pixel grid and painted.
+ * @param options - See {@link ParallelCanvasOptions}.
+ * @returns The two refs to hand to the `<canvas>` elements.
+ */
+export function useParallelCanvas(
+  options: ParallelCanvasOptions,
+): ParallelCanvases {
+  const { width, height, layouts, values, count } = options;
+  const { included, steps, palette, highlights, ink } = options;
+  const lines = useRef<HTMLCanvasElement>(null);
+  const marks = useRef<HTMLCanvasElement>(null);
+  const { line, excluded, includedAlpha, halo } = ink;
+
+  useEffect(() => {
+    const context = preparePlotCanvas(lines.current, width, height);
+    if (context === null) return;
+    paintParallelLines(context, {
+      layouts,
+      values,
+      count,
+      included,
+      steps,
+      palette,
+      line,
+      excluded,
+      includedAlpha,
+    });
+  }, [
+    width,
+    height,
+    layouts,
+    values,
+    count,
+    included,
+    steps,
+    palette,
+    line,
+    excluded,
+    includedAlpha,
+  ]);
+
+  useEffect(() => {
+    const context = preparePlotCanvas(marks.current, width, height);
+    if (context === null) return;
+    paintParallelHighlights(context, { highlights, layouts, values, halo });
+  }, [width, height, highlights, layouts, values, halo]);
+
+  return { lines, marks };
+}

package/src/parallel/ui/useParallelGesture.ts

@@ -0,0 +1,260 @@
+/**
+ * One pointer over the whole figure, serving both the brush and the hover.
+ *
+ * A hook cannot be called inside a `map`, so a brush per axis would have to
+ * live in refs and be attached by hand; one surface that works out from the
+ * press which axis was grabbed has no such problem, and it gives the hover
+ * search the same once-a-frame coalescing the drag already pays for.
+ *
+ * The band follows the pointer live and the interval is reported on release
+ * only: a table filtering on the reported interval is asked to re-render once
+ * per gesture rather than sixty times a second.
+ */
+
+import type { MouseEvent as ReactMouseEvent } from 'react';
+import { useMemo, useRef, useState } from 'react';
+
+import type {
+  ScatterSurfaceProps,
+  SurfaceEvent,
+} from '../../scatter/ui/lassoGesture.ts';
+import { useCapturedPointer } from '../../scatter/ui/useCapturedPointer.ts';
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import { PARALLEL_MARGIN } from '../core/parallelAxes.ts';
+import type { ParallelBand, ParallelBrushDrag } from '../core/parallelBrush.ts';
+import {
+  parallelBandAt,
+  parallelBandOf,
+  parallelBrushTarget,
+} from '../core/parallelBrush.ts';
+import { parallelNearestRow } from '../core/parallelHit.ts';
+import { parallelRangeList } from '../core/parallelSelection.ts';
+import type { ParallelRange, ParallelRanges } from '../core/parallelTypes.ts';
+
+import type { ParallelDraft } from './parallelGestureModel.ts';
+import {
+  parallelAxisById,
+  parallelAxisNear,
+  parallelBandsOf,
+  parallelCommitOf,
+  parallelPointOf,
+} from './parallelGestureModel.ts';
+
+/** What {@link useParallelGesture} needs. */
+export interface ParallelGestureOptions {
+  /** The axes, from left to right. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** How many rows are drawn. */
+  count: number;
+  /** Height of the drawing area, in pixels. */
+  innerHeight: number;
+  /** Which rows a brush keeps, so an excluded line cannot be pointed at. */
+  included: Uint8Array | null;
+  /** The intervals in force, whoever owns them. */
+  ranges: ParallelRanges;
+  /**
+   * Whether one axis may keep several intervals at once.
+   * @default false
+   */
+  several?: boolean | undefined;
+  /** Called when a brush is released, with every interval that axis now keeps. */
+  onRangeChange: (axisId: string, ranges: readonly ParallelRange[]) => void;
+  /** Called on every frame a band grows. */
+  onRangePreview?:
+    ((axisId: string, ranges: readonly ParallelRange[]) => void) | undefined;
+  /** The row the caller says is hovered, if it owns that. */
+  hovered?: number | undefined;
+  /** Called with the row under the pointer, or `-1`. */
+  onHoverChange?: ((index: number) => void) | undefined;
+  /** Called when a line is clicked, with the row, or `-1` for empty ground. */
+  onRowClick?: ((index: number) => void) | undefined;
+}
+
+/** The gesture, as the figure renders it. */
+export interface ParallelGesture {
+  /** Spread onto the transparent rectangle laid over the figure. */
+  surface: ScatterSurfaceProps;
+  /** Put on the same rectangle, for the click that picks a line. */
+  onClick: (event: ReactMouseEvent<Element>) => void;
+  /** The bands to draw on each axis, the one being dragged included. */
+  bands: ReadonlyMap<string, ParallelBand[]>;
+  /** The row under the pointer, or `-1`. */
+  hovered: number;
+  /** Where the pointer is in the figure, or `null` when it is away. */
+  pointer: { x: number; y: number } | null;
+  /** Whether a band is being dragged right now. */
+  brushing: boolean;
+}
+
+/**
+ * The brush and the hover, over one surface.
+ * @param options - See {@link ParallelGestureOptions}.
+ * @returns The gesture. See {@link ParallelGesture}.
+ */
+export function useParallelGesture(
+  options: ParallelGestureOptions,
+): ParallelGesture {
+  const { layouts, values, count, innerHeight, included, ranges } = options;
+  const { several = false } = options;
+  const { onRangeChange, onRangePreview, onHoverChange, onRowClick } = options;
+
+  const [draft, setDraft] = useState<ParallelDraft | null>(null);
+  const [ownHovered, setOwnHovered] = useState(-1);
+  const [pointer, setPointer] = useState<{ x: number; y: number } | null>(null);
+  const hovered = options.hovered ?? ownHovered;
+
+  const dragRef = useRef<ParallelBrushDrag | null>(null);
+  const pointRef = useRef({ x: 0, y: 0 });
+  const reportedRef = useRef(-1);
+  const claimedRef = useRef(false);
+
+  function commit(
+    drag: ParallelBrushDrag,
+    band: ParallelBand,
+  ): readonly ParallelRange[] {
+    const layout = parallelAxisById(layouts, drag.axis);
+    if (layout === undefined) return parallelRangeList(ranges[drag.axis]);
+    return parallelCommitOf({
+      list: parallelRangeList(ranges[drag.axis]),
+      index: drag.index,
+      band,
+      layout,
+      still: unmoved(drag, band),
+      several,
+    });
+  }
+
+  function report(index: number): void {
+    if (index === reportedRef.current) return;
+    reportedRef.current = index;
+    setOwnHovered(index);
+    onHoverChange?.(index);
+  }
+
+  function findRow(point: { x: number; y: number }): number {
+    return parallelNearestRow(
+      point,
+      layouts,
+      values,
+      count,
+      included ?? undefined,
+    );
+  }
+
+  function press(event: SurfaceEvent): boolean {
+    const point = parallelPointOf(event);
+    const index = parallelAxisNear(point.x, layouts);
+    const layout = layouts[index];
+    if (layout === undefined || point.y < 0 || point.y > innerHeight) {
+      claimedRef.current = false;
+      return false;
+    }
+    const list = parallelRangeList(ranges[layout.id]);
+    const bands: ParallelBand[] = [];
+    for (const range of list) bands.push(parallelBandOf(range, layout));
+    const target = parallelBrushTarget(point.y, bands);
+    const held = target.index === -1 ? undefined : bands[target.index];
+    const drag: ParallelBrushDrag = {
+      axis: layout.id,
+      index: target.index,
+      grip: target.grip,
+      originY: point.y,
+      origin: held ?? { top: point.y, bottom: point.y },
+    };
+    dragRef.current = drag;
+    pointRef.current = point;
+    claimedRef.current = true;
+    setDraft({
+      axis: layout.id,
+      index: target.index,
+      band: parallelBandAt(drag, point.y, innerHeight),
+    });
+    return true;
+  }
+
+  function frame(claimed: boolean): void {
+    const point = pointRef.current;
+    const drag = dragRef.current;
+    if (claimed && drag !== null) {
+      const band = parallelBandAt(drag, point.y, innerHeight);
+      setDraft({ axis: drag.axis, index: drag.index, band });
+      onRangePreview?.(drag.axis, commit(drag, band));
+      return;
+    }
+    setPointer({
+      x: point.x + PARALLEL_MARGIN.left,
+      y: point.y + PARALLEL_MARGIN.top,
+    });
+    report(findRow(point));
+  }
+
+  function release(event: SurfaceEvent | null, keep: boolean): void {
+    const drag = dragRef.current;
+    dragRef.current = null;
+    setDraft(null);
+    if (drag === null) return;
+    if (event !== null) pointRef.current = parallelPointOf(event);
+    if (!keep) {
+      onRangePreview?.(drag.axis, parallelRangeList(ranges[drag.axis]));
+      return;
+    }
+    const kept = commit(
+      drag,
+      parallelBandAt(drag, pointRef.current.y, innerHeight),
+    );
+    onRangePreview?.(drag.axis, kept);
+    onRangeChange(drag.axis, kept);
+  }
+
+  const { surface } = useCapturedPointer({
+    touch: false,
+    cursor: 'crosshair',
+    onPress: press,
+    onMove: (event) => {
+      pointRef.current = parallelPointOf(event);
+      return true;
+    },
+    onFrame: frame,
+    onRelease: release,
+    onLeave: () => {
+      setPointer(null);
+      report(-1);
+    },
+  });
+
+  const bands = useMemo(
+    () => parallelBandsOf(layouts, ranges, draft),
+    [layouts, ranges, draft],
+  );
+
+  function handleClick(event: ReactMouseEvent<Element>): void {
+    if (claimedRef.current || onRowClick === undefined) return;
+    onRowClick(findRow(parallelPointOf(event)));
+  }
+
+  return {
+    surface,
+    onClick: handleClick,
+    bands,
+    hovered,
+    pointer,
+    brushing: draft !== null,
+  };
+}
+
+/**
+ * Whether a press took hold of an interval and let it go where it found it,
+ * which is a click on that interval rather than a move of it.
+ * @param drag - The drag, as it began.
+ * @param band - The band as the pointer left it.
+ * @returns Whether nothing moved.
+ */
+function unmoved(drag: ParallelBrushDrag, band: ParallelBand): boolean {
+  return (
+    drag.index !== -1 &&
+    band.top === drag.origin.top &&
+    band.bottom === drag.origin.bottom
+  );
+}

package/src/structure/ui/useToolbarFloor.ts

@@ -38,44 +38,49 @@ export function useToolbarFloor(
     const container = containerRef.current;
     if (container === null) return;
 
-    let observer: ResizeObserver | null = null;
-    let frame = 0;
-    let attempts = 0;
+    let toolbar: HTMLCanvasElement | null = null;
+    let size: ResizeObserver | null = null;
 
-    // The editor builds itself asynchronously, so the toolbar is usually not
-    // there yet on the first look; watching for it is what keeps a slow first
-    // paint from leaving the container at its unmeasured height for good.
     const attach = (): void => {
-      const toolbar = findToolbar(container);
-      if (toolbar === null) {
-        attempts++;
-        if (attempts > MAX_ATTEMPTS) return;
-        frame = globalThis.requestAnimationFrame(attach);
-        return;
-      }
-      observer = new ResizeObserver(() => {
+      const found = findToolbar(container);
+      if (found === null) return;
+      size?.disconnect();
+      toolbar = found;
+      size = new ResizeObserver(() => {
         // offsetHeight, because a dialog opens under a scaling transform and a
         // measured rectangle would be that of the half drawn toolbar.
-        const floor = toolbarFloorHeight(toolbar.offsetHeight, minHeight);
-        container.style.minHeight = `${floor}px`;
+        const height = found.offsetHeight;
+        // Zero is a toolbar being torn down or not yet laid out, never a
+        // toolbar that needs no room: writing the fallback for it would undo a
+        // correct floor and leave the palette cut off.
+        if (height === 0) return;
+        container.style.minHeight = `${toolbarFloorHeight(height, minHeight)}px`;
       });
-      observer.observe(toolbar);
+      size.observe(found);
     };
 
+    // The editor is imported lazily and builds itself asynchronously, so it is
+    // almost never there on the first look, and how long it takes is a cold
+    // module graph and a network away from anything this code can predict. So
+    // the arrival is watched for rather than waited out: a deadline that
+    // expires leaves the toolbar cut off for the life of the page, with
+    // nothing on screen to say why.
+    const arrivals = new MutationObserver(() => {
+      if (toolbar?.isConnected === true) return;
+      attach();
+    });
+    arrivals.observe(container, { childList: true, subtree: true });
     attach();
 
     return () => {
-      if (frame !== 0) globalThis.cancelAnimationFrame(frame);
-      observer?.disconnect();
+      arrivals.disconnect();
+      size?.disconnect();
     };
   }, [minHeight, revision]);
 
   return containerRef;
 }
 
-/** Roughly two seconds of frames, after which the editor is not coming. */
-const MAX_ATTEMPTS = 120;
-
 /**
  * Find the toolbar canvas of the editor.
  *

package/src/ui.ts

@@ -15,6 +15,7 @@ export * from './error/ui/index.ts';
 export * from './help/ui/index.ts';
 export * from './hooks/ui/index.ts';
 export * from './overlay/ui/index.ts';
+export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
 export * from './projection/ui/index.ts';