react-cheminfo 0.16.0 → 0.17.0

package/src/parallel/core/parallelSelection.ts

@@ -0,0 +1,99 @@
+/**
+ * What an axis keeps, when it keeps more than one interval.
+ *
+ * The figure reports a list and accepts either a list or a bare interval, so a
+ * caller that only ever keeps one is not made to write `[[0, 1]]`. Everything
+ * downstream — the filter, the bands, the gesture — reads the list, which is
+ * what {@link parallelRangeList} is for: one normalisation, at the edge, and
+ * no `Array.isArray` scattered through the painter.
+ *
+ * Intervals on one axis are held sorted and disjoint. Two that touch are one
+ * interval drawn twice, and a reader dragging a band across its neighbour means
+ * to widen it rather than to stack two bands nobody can then take hold of.
+ */
+
+import type { ParallelRange, ParallelSelection } from './parallelTypes.ts';
+
+/** Nothing kept, shared so a normalisation never allocates for the common case. */
+const NONE: readonly ParallelRange[] = [];
+
+/**
+ * The intervals one axis keeps, however the caller wrote them.
+ * @param selection - One interval, several, or nothing at all.
+ * @returns The intervals, in the order given. Read in place — the caller's own
+ * array comes back when it gave one.
+ */
+export function parallelRangeList(
+  selection: ParallelSelection | undefined,
+): readonly ParallelRange[] {
+  if (selection === null || selection === undefined) return NONE;
+  if (selection.length === 0) return NONE;
+  // A bare interval is two numbers; a list of them holds arrays.
+  return typeof selection[0] === 'number'
+    ? [selection as ParallelRange]
+    : (selection as readonly ParallelRange[]);
+}
+
+/**
+ * Whether an axis keeps anything at all.
+ * @param selection - What that axis keeps.
+ * @returns Whether any interval is in force.
+ */
+export function parallelHasRange(
+  selection: ParallelSelection | undefined,
+): boolean {
+  return parallelRangeList(selection).length > 0;
+}
+
+/**
+ * The same intervals, sorted low to high and with the overlapping ones joined.
+ * @param ranges - The intervals, in any order, each low value first.
+ * @returns One list, sorted and disjoint. Intervals that touch at a point are
+ * joined too: a reader who dragged one band onto another meant one band.
+ */
+export function parallelMergeRanges(
+  ranges: readonly ParallelRange[],
+): ParallelRange[] {
+  if (ranges.length === 0) return [];
+  const sorted = ranges
+    .map((range) =>
+      range[0] <= range[1] ? range : ([range[1], range[0]] as ParallelRange),
+    )
+    .toSorted((left, right) => left[0] - right[0]);
+  const merged: ParallelRange[] = [];
+  let low = (sorted[0] as ParallelRange)[0];
+  let high = (sorted[0] as ParallelRange)[1];
+  for (let index = 1; index < sorted.length; index++) {
+    const range = sorted[index] as ParallelRange;
+    if (range[0] > high) {
+      merged.push([low, high]);
+      low = range[0];
+      high = range[1];
+      continue;
+    }
+    if (range[1] > high) high = range[1];
+  }
+  merged.push([low, high]);
+  return merged;
+}
+
+/**
+ * The intervals an axis keeps once one of them is replaced, removed or added.
+ * @param ranges - The intervals in force.
+ * @param index - Which one is being written, or `-1` to add one.
+ * @param range - The interval it becomes, or `null` to take it away.
+ * @returns The new list, sorted and disjoint. Never the same array.
+ */
+export function parallelWriteRange(
+  ranges: readonly ParallelRange[],
+  index: number,
+  range: ParallelRange | null,
+): ParallelRange[] {
+  const kept: ParallelRange[] = [];
+  for (let at = 0; at < ranges.length; at++) {
+    if (at === index) continue;
+    kept.push(ranges[at] as ParallelRange);
+  }
+  if (range !== null) kept.push(range);
+  return parallelMergeRanges(kept);
+}

package/src/parallel/core/parallelTicks.ts

@@ -10,6 +10,7 @@
 import {
   chartAxisScale,
   chartTickDecimals,
+  chartTickLabel,
 } from '../../chart/core/chartAxisScale.ts';
 import { formatDecimal } from '../../format/core/numbers.ts';
 import { roundTo } from '../../format/core/roundTo.ts';
@@ -71,12 +72,15 @@ function nicedGraduation(
   wanted: number,
 ): ParallelGraduation {
   const scale = chartAxisScale(min, max, { count: wanted, nice: true });
+  // Not `scale.labels`: those have a common power of ten lifted out of them,
+  // on the understanding that the caller writes it beside the axis name, and
+  // this figure writes only the name. Each graduation carries its own value.
+  const decimals = chartTickDecimals(scale.step);
   const ticks: ParallelTick[] = [];
-  for (let index = 0; index < scale.values.length; index++) {
-    const value = scale.values[index] as number;
+  for (const value of scale.values) {
     const label =
       axis.format === undefined
-        ? (scale.labels[index] ?? formatDecimal(value, scale.decimals))
+        ? chartTickLabel(value, decimals)
         : axis.format(value);
     if (ticks.at(-1)?.label === label) continue;
     ticks.push({ value, label });

package/src/parallel/core/parallelTypes.ts

@@ -86,8 +86,20 @@ export interface ParallelAxis {
 /** An interval kept on one axis, in that axis's own units, low first. */
 export type ParallelRange = readonly [number, number];
 
+/**
+ * What one axis keeps: nothing, one interval, or several disjoint ones.
+ *
+ * A reader comparing molecules wants the light ones *and* the heavy ones, with
+ * nothing in between, which one interval cannot say. Several are read as a
+ * union — a row is kept when it falls in any of them — while the axes are
+ * still read as an intersection, so each axis narrows what the ones before it
+ * left. A bare interval means the same as a list holding only it, so a caller
+ * that only ever keeps one writes one.
+ */
+export type ParallelSelection = ParallelRange | readonly ParallelRange[] | null;
+
 /** Which rows a set of brushes keeps, keyed by axis id. */
-export type ParallelRanges = Readonly<Record<string, ParallelRange | null>>;
+export type ParallelRanges = Readonly<Record<string, ParallelSelection>>;
 
 /** How the lines are coloured. */
 export interface ParallelColorBy {

package/src/parallel/ui/ParallelAxesLayer.tsx

@@ -20,8 +20,8 @@ export interface ParallelAxesLayerProps {
   layouts: readonly ParallelAxisLayout[];
   /** Height of the drawing area, in pixels. */
   innerHeight: number;
-  /** The band each axis carries right now, the one being dragged included. */
-  bands: ReadonlyMap<string, ParallelBand>;
+  /** The bands each axis carries right now, the one being dragged included. */
+  bands: ReadonlyMap<string, ParallelBand[]>;
   /** The ink the axes, their ticks and their labels are drawn in. */
   axisInk: string;
   /** The ink a band is filled and outlined in. */
@@ -49,7 +49,7 @@ export function ParallelAxesLayer(props: ParallelAxesLayerProps): ReactElement {
       textAnchor="middle"
     >
       {layouts.map((layout) => {
-        const band = bands.get(layout.id) ?? null;
+        const drawn = bands.get(layout.id);
         return (
           <g
             key={layout.id}
@@ -83,7 +83,13 @@ export function ParallelAxesLayer(props: ParallelAxesLayerProps): ReactElement {
               fill="transparent"
               pointerEvents="none"
             />
-            {band === null ? null : <BrushBand band={band} ink={bandInk} />}
+            {drawn?.map((band) => (
+              <BrushBand
+                key={`${band.top}:${band.bottom}`}
+                band={band}
+                ink={bandInk}
+              />
+            ))}
           </g>
         );
       })}

package/src/parallel/ui/ParallelCoordinates.tsx

@@ -30,8 +30,10 @@ import {
 import {
   PARALLEL_SVG_STYLE,
   parallelCanvasStyle,
+  parallelDropMarkStyle,
   parallelFigureStyle,
 } from './parallelStyles.ts';
+import { useParallelAxisDrag } from './useParallelAxisDrag.ts';
 import { useParallelCanvas } from './useParallelCanvas.ts';
 import { useParallelGesture } from './useParallelGesture.ts';
 
@@ -70,6 +72,7 @@ export function ParallelCoordinates(
   const { ranges: ownedRanges, defaultRanges, included: givenMask } = props;
   const { color: givenColor, colorAxis, onRangeChange: report } = props;
   const { onRangePreview, hovered, onHoverChange, onRowClick } = props;
+  const { several = false, onAxisOrder } = props;
   const count = parallelRowCount(axes, props.count);
   const innerWidth = Math.max(
     width - PARALLEL_MARGIN.left - PARALLEL_MARGIN.right,
@@ -109,11 +112,11 @@ export function ParallelCoordinates(
     return parallelIncludedMask(axes, ranges, count);
   }, [givenMask, axes, ranges, count]);
 
-  function commitRange(axisId: string, range: ParallelRange | null): void {
+  function commitRange(axisId: string, kept: readonly ParallelRange[]): void {
     if (ownedRanges === undefined) {
-      setOwnRanges((previous) => ({ ...previous, [axisId]: range }));
+      setOwnRanges((previous) => ({ ...previous, [axisId]: kept }));
     }
-    report?.(axisId, range);
+    report?.(axisId, kept);
   }
 
   const gesture = useParallelGesture({
@@ -123,6 +126,7 @@ export function ParallelCoordinates(
     innerHeight,
     included,
     ranges,
+    several,
     onRangeChange: commitRange,
     onRangePreview,
     hovered,
@@ -148,6 +152,10 @@ export function ParallelCoordinates(
     ink,
   });
 
+  const axisDrag = useParallelAxisDrag({ layouts, onAxisOrder });
+  const dropAt =
+    axisDrag.active === null ? undefined : layouts[axisDrag.active.to];
+
   const label = given ?? parallelFigureLabel(axes, count);
   const canvasStyle = parallelCanvasStyle(height);
   const hover =
@@ -199,11 +207,22 @@ export function ParallelCoordinates(
               onClick={gesture.onClick}
               {...gesture.surface}
             />
+            {dropAt === undefined ? null : (
+              <line
+                data-parallel-drop={dropAt.id}
+                x1={PARALLEL_MARGIN.left + dropAt.x}
+                x2={PARALLEL_MARGIN.left + dropAt.x}
+                y1={PARALLEL_MARGIN.top}
+                y2={PARALLEL_MARGIN.top + innerHeight}
+                style={parallelDropMarkStyle(ink.selection)}
+              />
+            )}
           </svg>
           <ParallelLabels
             axes={axes}
             layouts={layouts}
             render={renderAxisLabel}
+            drag={axisDrag}
           />
           {hover === null || renderTooltip === undefined ? null : (
             <ParallelTooltip

package/src/parallel/ui/ParallelLabels.tsx

@@ -5,6 +5,7 @@ import { PARALLEL_MARGIN } from '../core/parallelAxes.ts';
 import type { ParallelAxis } from '../core/parallelTypes.ts';
 
 import { PARALLEL_LABELS_STYLE, parallelLabelStyle } from './parallelStyles.ts';
+import type { ParallelAxisDrag } from './useParallelAxisDrag.ts';
 
 /** What {@link ParallelLabels} writes. */
 export interface ParallelLabelsProps {
@@ -17,6 +18,11 @@ export interface ParallelLabelsProps {
    * @default undefined
    */
   render?: ((axis: ParallelAxis, index: number) => ReactNode) | undefined;
+  /**
+   * The gesture that moves an axis by its name.
+   * @default undefined — the axes are fixed
+   */
+  drag?: ParallelAxisDrag | undefined;
 }
 
 /**
@@ -29,17 +35,32 @@ export interface ParallelLabelsProps {
  * @returns The names.
  */
 export function ParallelLabels(props: ParallelLabelsProps): ReactElement {
-  const { axes, layouts, render } = props;
+  const { axes, layouts, render, drag } = props;
+  const draggable = drag?.enabled ?? false;
+  const active = drag?.active ?? null;
 
   return (
     <div className="parallel-coordinates-labels" style={PARALLEL_LABELS_STYLE}>
       {layouts.map((layout, index) => {
         const axis = axes[index];
+        const moving = active !== null && active.from === index;
         return (
           <div
             key={layout.id}
             className="parallel-axis-label"
-            style={parallelLabelStyle(PARALLEL_MARGIN.left + layout.x)}
+            data-parallel-label={layout.id}
+            style={parallelLabelStyle({
+              left: PARALLEL_MARGIN.left + layout.x,
+              draggable,
+              dx: moving ? active.dx : null,
+            })}
+            {...drag?.propsFor(index)}
+            {...(draggable
+              ? {
+                  role: 'button',
+                  'aria-label': `${layout.label}: move this axis with the left and right arrow keys`,
+                }
+              : null)}
           >
             {axis !== undefined && render !== undefined
               ? render(axis, index)

package/src/parallel/ui/index.ts

@@ -29,6 +29,14 @@ export {
 } from './parallelInk.ts';
 export { ParallelLabels } from './ParallelLabels.tsx';
 export type { ParallelLabelsProps } from './ParallelLabels.tsx';
+export type { ParallelCommit, ParallelDraft } from './parallelGestureModel.ts';
+export {
+  parallelAxisById,
+  parallelAxisNear,
+  parallelBandsOf,
+  parallelCommitOf,
+  parallelPointOf,
+} from './parallelGestureModel.ts';
 export {
   parallelColorOf,
   parallelFigureLabel,
@@ -43,6 +51,13 @@ export type {
   ParallelCanvases,
 } from './useParallelCanvas.ts';
 export { useParallelCanvas } from './useParallelCanvas.ts';
+export type {
+  ParallelAxisDrag,
+  ParallelAxisDragOptions,
+  ParallelAxisDragState,
+  ParallelAxisHandleProps,
+} from './useParallelAxisDrag.ts';
+export { useParallelAxisDrag } from './useParallelAxisDrag.ts';
 export type {
   ParallelGesture,
   ParallelGestureOptions,

package/src/parallel/ui/parallelCoordinatesProps.ts

@@ -84,10 +84,11 @@ export interface ParallelCoordinatesProps {
   height?: number;
 
   /**
-   * The interval each axis keeps, keyed by axis id. Present, the caller owns
-   * the brushes — which is what lets a table beside the figure filter on the
-   * same ranges. The band being dragged stays inside the component either way,
-   * so a controlled parent is never asked to re-render sixty times a second.
+   * What each axis keeps, keyed by axis id: one interval, several, or `null`.
+   * Present, the caller owns the brushes — which is what lets a table beside
+   * the figure filter on the same ranges. The band being dragged stays inside
+   * the component either way, so a controlled parent is never asked to
+   * re-render sixty times a second.
    * @default undefined — the figure keeps its own
    */
   ranges?: ParallelRanges;
@@ -97,17 +98,25 @@ export interface ParallelCoordinatesProps {
    */
   defaultRanges?: ParallelRanges;
   /**
-   * Called when a brush is released, with the interval it keeps or `null` when
-   * it was cleared — never while the band is being dragged.
+   * Whether one axis may keep several intervals at once — the light molecules
+   * and the heavy ones, with nothing in between. A reader brushes a second
+   * interval by dragging on a bare part of an axis that already carries one,
+   * and takes one away by clicking it.
+   * @default false — a new brush replaces the one the axis carried
+   */
+  several?: boolean;
+  /**
+   * Called when a brush is released, with every interval that axis now keeps —
+   * empty when the reader cleared it, and never while a band is being dragged.
    * @default undefined
    */
-  onRangeChange?: (axisId: string, range: ParallelRange | null) => void;
+  onRangeChange?: (axisId: string, ranges: readonly ParallelRange[]) => void;
   /**
    * Called on every frame a band grows, for a caption saying what letting go
    * would keep. Nothing else should be wired to it.
    * @default undefined
    */
-  onRangePreview?: (axisId: string, range: ParallelRange | null) => void;
+  onRangePreview?: (axisId: string, ranges: readonly ParallelRange[]) => void;
   /**
    * Which rows the brushes keep, one entry per row, a zero meaning excluded.
    * Left out, it is worked out from the ranges with `parallelIncludedMask`,
@@ -170,6 +179,15 @@ export interface ParallelCoordinatesProps {
    * @default the axis label, and its unit after it
    */
   renderAxisLabel?: (axis: ParallelAxis, index: number) => ReactNode;
+  /**
+   * Called with the axis ids in the order the reader dragged them into.
+   * Present, every axis name becomes a handle: drag it, or focus it and press
+   * the left and right arrow keys. Two columns only show their relationship
+   * when they stand next to each other, so this is how a reader asks a
+   * different question of the same figure.
+   * @default undefined — the axes stand in the order the caller gave them
+   */
+  onAxisOrder?: (ids: readonly string[]) => void;
   /**
    * What is shown in place of the figure when there is nothing to draw.
    * @default undefined — an empty figure of the given height

package/src/parallel/ui/parallelGestureModel.ts

@@ -15,13 +15,21 @@ import type { ParallelBand } from '../core/parallelBrush.ts';
 import {
   PARALLEL_BRUSH_HALF_WIDTH,
   parallelBandOf,
+  parallelIsBand,
+  parallelRangeOf,
 } from '../core/parallelBrush.ts';
-import type { ParallelRanges } from '../core/parallelTypes.ts';
+import {
+  parallelRangeList,
+  parallelWriteRange,
+} from '../core/parallelSelection.ts';
+import type { ParallelRange, ParallelRanges } from '../core/parallelTypes.ts';
 
 /** A band being dragged, before the interval it keeps is reported. */
 export interface ParallelDraft {
   /** The axis it is on. */
   axis: string;
+  /** Which of that axis's bands it is, or `-1` when it is a new one. */
+  index: number;
   /** Where it stands this frame. */
   band: ParallelBand;
 }
@@ -83,27 +91,69 @@ export function parallelAxisById(
 }
 
 /**
- * The band to draw on each axis: the one being dragged where there is one, and
- * the interval in force everywhere else.
+ * The bands to draw on each axis: the one being dragged where there is one,
+ * and the intervals in force everywhere else.
  * @param axes - The axes, from left to right.
- * @param ranges - The interval each axis keeps, or `null` for none.
+ * @param ranges - What each axis keeps: one interval, several, or none.
  * @param draft - The band being dragged, or `null` when nothing is.
- * @returns The bands, keyed by axis id; an axis with none is left out.
+ * @returns The bands, keyed by axis id; an axis with none is left out. The
+ * band being dragged replaces the interval it came from rather than being
+ * drawn beside it, so an interval never appears twice mid-gesture.
  */
 export function parallelBandsOf(
   axes: readonly ParallelAxisLayout[],
   ranges: ParallelRanges,
   draft: ParallelDraft | null,
-): ReadonlyMap<string, ParallelBand> {
-  const drawn = new Map<string, ParallelBand>();
+): ReadonlyMap<string, ParallelBand[]> {
+  const drawn = new Map<string, ParallelBand[]>();
   for (const axis of axes) {
-    if (draft !== null && draft.axis === axis.id) {
-      drawn.set(axis.id, draft.band);
-      continue;
+    const list = parallelRangeList(ranges[axis.id]);
+    const dragging = draft !== null && draft.axis === axis.id;
+    const bands: ParallelBand[] = [];
+    for (let index = 0; index < list.length; index++) {
+      if (dragging && index === draft.index) continue;
+      bands.push(parallelBandOf(list[index] as ParallelRange, axis));
     }
-    const range = ranges[axis.id];
-    if (range === null || range === undefined) continue;
-    drawn.set(axis.id, parallelBandOf(range, axis));
+    if (dragging) bands.push(draft.band);
+    if (bands.length > 0) drawn.set(axis.id, bands);
   }
   return drawn;
 }
+
+/** What a released band does to the intervals its axis already kept. */
+export interface ParallelCommit {
+  /** The intervals in force on that axis. */
+  list: readonly ParallelRange[];
+  /** Which of them the drag took hold of, or `-1` when it began a new one. */
+  index: number;
+  /** The band as the pointer left it. */
+  band: ParallelBand;
+  /** The axis it is on, to read the band back into its own units. */
+  layout: ParallelAxisLayout;
+  /** Whether the press took an interval and let it go without moving it. */
+  still: boolean;
+  /** Whether the axis may keep more than one interval. */
+  several: boolean;
+}
+
+/**
+ * The intervals an axis keeps once a band has been let go.
+ *
+ * A press that keeps nothing is a click, and a click says "take this away":
+ * the interval under the pointer when it landed on one, and every interval on
+ * the axis when it landed on bare axis. That is the only way to be rid of one
+ * interval on an axis carrying four, and it is the gesture that already
+ * cleared an axis before it could carry more than one.
+ * @param commit - See {@link ParallelCommit}.
+ * @returns The intervals, sorted and disjoint.
+ */
+export function parallelCommitOf(commit: ParallelCommit): ParallelRange[] {
+  const { list, index, band, layout, still, several } = commit;
+  if (still) return parallelWriteRange(list, index, null);
+  if (!parallelIsBand(band)) {
+    return index === -1 ? [] : parallelWriteRange(list, index, null);
+  }
+  const range = parallelRangeOf(band, layout);
+  if (!several && index === -1) return [range];
+  return parallelWriteRange(list, index, range);
+}

package/src/parallel/ui/parallelPlotModel.ts

@@ -10,6 +10,7 @@
 
 import { formatInteger } from '../../format/core/numbers.ts';
 import type { ParallelHighlight } from '../core/parallelPaint.ts';
+import { parallelHasRange } from '../core/parallelSelection.ts';
 import type {
   ParallelAxis,
   ParallelColorBy,
@@ -71,7 +72,7 @@ export function parallelColorOf(
 /**
  * Whether any axis on the figure carries an interval at all.
  * @param axes - The axes, whose ids the intervals are keyed by.
- * @param ranges - The interval each axis keeps.
+ * @param ranges - What each axis keeps.
  * @returns Whether anything is brushed, which is what decides whether a line
  * is ever drawn in the excluded ink.
  */
@@ -80,8 +81,7 @@ export function parallelIsBrushed(
   ranges: ParallelRanges,
 ): boolean {
   for (const axis of axes) {
-    const range = ranges[axis.id];
-    if (range !== null && range !== undefined) return true;
+    if (parallelHasRange(ranges[axis.id])) return true;
   }
   return false;
 }

package/src/parallel/ui/parallelStyles.ts

@@ -62,22 +62,64 @@ export const PARALLEL_LABELS_STYLE = {
   pointerEvents: 'none',
 } as const satisfies CSSProperties;
 
+/** How one axis name is placed, and whether it is being moved. */
+export interface ParallelLabelPlacement {
+  /** Where the axis stands, in pixels from the figure's left edge. */
+  left: number;
+  /**
+   * Whether the name can be dragged to move its axis.
+   * @default false
+   */
+  draggable?: boolean;
+  /**
+   * How far it has been dragged, in pixels, or `null` when it is not moving.
+   * @default null
+   */
+  dx?: number | null;
+}
+
 /**
  * One axis name, centred over its axis and taking the pointer back.
- * @param left - Where the axis stands, in pixels from the figure's left edge.
- * @returns The name's rules.
+ * @param placement - See {@link ParallelLabelPlacement}.
+ * @returns The name's rules. A name being dragged follows the pointer and is
+ * drawn over its neighbours, so it is never hidden behind the name it is
+ * about to change places with.
  */
-export function parallelLabelStyle(left: number): CSSProperties {
+export function parallelLabelStyle(
+  placement: ParallelLabelPlacement,
+): CSSProperties {
+  const { left, draggable = false, dx = null } = placement;
+  const moving = dx !== null;
   return {
     position: 'absolute',
+    zIndex: moving ? 2 : undefined,
     top: 2,
     left,
-    transform: 'translateX(-50%)',
+    transform:
+      dx === null ? 'translateX(-50%)' : `translateX(calc(-50% + ${dx}px))`,
     color: TOKEN.text,
     fontSize: 11,
     fontWeight: 600,
     whiteSpace: 'nowrap',
     pointerEvents: 'auto',
+    cursor: draggable ? (moving ? 'grabbing' : 'grab') : undefined,
+    opacity: moving ? 0.85 : undefined,
+    touchAction: draggable ? 'none' : undefined,
+    userSelect: draggable ? 'none' : undefined,
+  };
+}
+
+/**
+ * The axis a dragged name would take the place of, marked while it is moving.
+ * @param ink - The colour the figure singles things out in.
+ * @returns The mark's rules.
+ */
+export function parallelDropMarkStyle(ink: string): CSSProperties {
+  return {
+    stroke: ink,
+    strokeWidth: 2,
+    strokeOpacity: 0.7,
+    strokeDasharray: '4 3',
   };
 }