react-cheminfo 0.16.0 → 0.17.0

package/src/parallel/ui/useParallelAxisDrag.ts

@@ -0,0 +1,147 @@
+/**
+ * Dragging an axis by its name to stand somewhere else.
+ *
+ * Two columns only show their relationship when they are neighbours, so the
+ * order the axes stand in is a question the reader asks, not a decision the
+ * caller takes once. The name is the handle: it is the only part of an axis
+ * that is not already spoken for by the brush, and it is what a reader reaches
+ * for anyway.
+ *
+ * The gesture moves the name and nothing else. Reordering the axes for real
+ * would repaint every line on every frame, which a library of ten thousand
+ * molecules cannot afford — so the figure shows where the axis would land and
+ * moves it once, on release.
+ */
+
+import type { KeyboardEvent, PointerEvent } from 'react';
+import { useRef, useState } from 'react';
+
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import {
+  parallelAxisOrder,
+  parallelDropIndex,
+  parallelMoveAxis,
+} from '../core/parallelOrder.ts';
+
+/** What {@link useParallelAxisDrag} needs. */
+export interface ParallelAxisDragOptions {
+  /** The axes, from left to right, already placed. */
+  layouts: readonly ParallelAxisLayout[];
+  /**
+   * Called with the axis ids in the order the reader put them in.
+   * @default undefined — the axes cannot be moved
+   */
+  onAxisOrder?: ((ids: readonly string[]) => void) | undefined;
+}
+
+/** The name being dragged, and where it would land. */
+export interface ParallelAxisDragState {
+  /** Which axis is moving, as an index into the axes. */
+  from: number;
+  /** How far its name has been dragged, in pixels. */
+  dx: number;
+  /** Which place it would take if let go now. */
+  to: number;
+}
+
+/** The reorder gesture, as the figure renders it. */
+export interface ParallelAxisDrag {
+  /** Whether the axes can be moved at all. */
+  enabled: boolean;
+  /** The name being dragged, or `null` when none is. */
+  active: ParallelAxisDragState | null;
+  /** Spread onto one axis's name. */
+  propsFor: (index: number) => ParallelAxisHandleProps;
+}
+
+/** What one axis name carries so it can be dragged and stepped with the keys. */
+export interface ParallelAxisHandleProps {
+  onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+  onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+  onPointerUp: (event: PointerEvent<HTMLElement>) => void;
+  onPointerCancel: (event: PointerEvent<HTMLElement>) => void;
+  onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+  tabIndex: number;
+}
+
+/** A name that has not been dragged, and is not moving anything. */
+const IDLE: ParallelAxisHandleProps = {
+  onPointerDown: noop,
+  onPointerMove: noop,
+  onPointerUp: noop,
+  onPointerCancel: noop,
+  onKeyDown: noop,
+  tabIndex: -1,
+};
+
+/**
+ * Move an axis by dragging its name, or by stepping it with the arrow keys.
+ * @param options - See {@link ParallelAxisDragOptions}.
+ * @returns The gesture. See {@link ParallelAxisDrag}.
+ */
+export function useParallelAxisDrag(
+  options: ParallelAxisDragOptions,
+): ParallelAxisDrag {
+  const { layouts, onAxisOrder } = options;
+  const [active, setActive] = useState<ParallelAxisDragState | null>(null);
+  const originRef = useRef(0);
+
+  function move(from: number, to: number): void {
+    if (onAxisOrder === undefined) return;
+    const order = parallelAxisOrder(layouts);
+    if (to < 0 || to >= order.length || to === from) return;
+    onAxisOrder(parallelMoveAxis(order, from, to));
+  }
+
+  function dropAt(from: number, dx: number): number {
+    const layout = layouts[from];
+    if (layout === undefined) return from;
+    return parallelDropIndex(layout.x + dx, layouts);
+  }
+
+  function propsFor(index: number): ParallelAxisHandleProps {
+    if (onAxisOrder === undefined) return IDLE;
+    return {
+      tabIndex: 0,
+      onPointerDown: (event) => {
+        if (event.button !== 0) return;
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        originRef.current = event.clientX;
+        setActive({ from: index, dx: 0, to: index });
+      },
+      onPointerMove: (event) => {
+        setActive((current) => {
+          if (current?.from !== index) return current;
+          const dx = event.clientX - originRef.current;
+          return { from: index, dx, to: dropAt(index, dx) };
+        });
+      },
+      onPointerUp: (event) => {
+        event.currentTarget.releasePointerCapture?.(event.pointerId);
+        setActive((current) => {
+          if (current !== null && current.from === index) {
+            move(current.from, current.to);
+          }
+          return null;
+        });
+      },
+      onPointerCancel: () => {
+        setActive(null);
+      },
+      onKeyDown: (event) => {
+        const step =
+          event.key === 'ArrowLeft' ? -1 : event.key === 'ArrowRight' ? 1 : 0;
+        if (step === 0) return;
+        event.preventDefault();
+        move(index, index + step);
+      },
+    };
+  }
+
+  return { enabled: onAxisOrder !== undefined, active, propsFor };
+}
+
+function noop(): void {
+  // A figure whose axes are fixed hands its names no handlers at all.
+}

package/src/parallel/ui/useParallelGesture.ts

@@ -25,11 +25,10 @@ import type { ParallelBand, ParallelBrushDrag } from '../core/parallelBrush.ts';
 import {
   parallelBandAt,
   parallelBandOf,
-  parallelBrushGrip,
-  parallelIsBand,
-  parallelRangeOf,
+  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';
@@ -37,6 +36,7 @@ import {
   parallelAxisById,
   parallelAxisNear,
   parallelBandsOf,
+  parallelCommitOf,
   parallelPointOf,
 } from './parallelGestureModel.ts';
 
@@ -54,11 +54,16 @@ export interface ParallelGestureOptions {
   included: Uint8Array | null;
   /** The intervals in force, whoever owns them. */
   ranges: ParallelRanges;
-  /** Called when a brush is released, with the interval it keeps or `null`. */
-  onRangeChange: (axisId: string, range: ParallelRange | null) => void;
+  /**
+   * 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, range: ParallelRange | null) => void) | undefined;
+    ((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`. */
@@ -73,8 +78,8 @@ export interface ParallelGesture {
   surface: ScatterSurfaceProps;
   /** Put on the same rectangle, for the click that picks a line. */
   onClick: (event: ReactMouseEvent<Element>) => void;
-  /** The band to draw on each axis, the one being dragged included. */
-  bands: ReadonlyMap<string, ParallelBand>;
+  /** 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. */
@@ -92,6 +97,7 @@ 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);
@@ -104,10 +110,20 @@ export function useParallelGesture(
   const reportedRef = useRef(-1);
   const claimedRef = useRef(false);
 
-  function rangeOf(axisId: string, band: ParallelBand): ParallelRange | null {
-    const layout = parallelAxisById(layouts, axisId);
-    if (layout === undefined || !parallelIsBand(band)) return null;
-    return parallelRangeOf(band, layout);
+  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 {
@@ -135,22 +151,24 @@ export function useParallelGesture(
       claimedRef.current = false;
       return false;
     }
-    const current = ranges[layout.id];
-    const band =
-      current === null || current === undefined
-        ? null
-        : parallelBandOf(current, layout);
+    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,
-      grip: parallelBrushGrip(point.y, band),
+      index: target.index,
+      grip: target.grip,
       originY: point.y,
-      origin: band ?? { top: point.y, bottom: 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;
@@ -161,8 +179,8 @@ export function useParallelGesture(
     const drag = dragRef.current;
     if (claimed && drag !== null) {
       const band = parallelBandAt(drag, point.y, innerHeight);
-      setDraft({ axis: drag.axis, band });
-      onRangePreview?.(drag.axis, rangeOf(drag.axis, band));
+      setDraft({ axis: drag.axis, index: drag.index, band });
+      onRangePreview?.(drag.axis, commit(drag, band));
       return;
     }
     setPointer({
@@ -172,22 +190,22 @@ export function useParallelGesture(
     report(findRow(point));
   }
 
-  function release(event: SurfaceEvent | null, commit: boolean): void {
+  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 (!commit) {
-      onRangePreview?.(drag.axis, ranges[drag.axis] ?? null);
+    if (!keep) {
+      onRangePreview?.(drag.axis, parallelRangeList(ranges[drag.axis]));
       return;
     }
-    const range = rangeOf(
-      drag.axis,
+    const kept = commit(
+      drag,
       parallelBandAt(drag, pointRef.current.y, innerHeight),
     );
-    onRangePreview?.(drag.axis, range);
-    onRangeChange(drag.axis, range);
+    onRangePreview?.(drag.axis, kept);
+    onRangeChange(drag.axis, kept);
   }
 
   const { surface } = useCapturedPointer({
@@ -225,3 +243,18 @@ export function useParallelGesture(
     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
+  );
+}