react-cheminfo 0.14.0 → 0.16.0

package/src/parallel/core/parallelTypes.ts

@@ -0,0 +1,147 @@
+/**
+ * What a parallel-coordinates figure is asked to draw: one axis per column,
+ * the intervals the reader brushed on them, and the quantity the lines are
+ * coloured by.
+ *
+ * The figure itself is index-based — every axis hands over its column as an
+ * `ArrayLike<number>` read in place — so a repaint costs an indexed read per
+ * value rather than a call. {@link parallelAxisOf} is the one place a row type
+ * is named, and it is run once per data change rather than once per repaint.
+ */
+
+import type { ColorScale } from '../../color/core/interpolate.ts';
+
+/** How a value is placed along an axis. */
+export type ParallelAxisScale = 'linear' | 'log';
+
+/** One labelled graduation a caller writes itself. */
+export interface ParallelTick {
+  /** Where it sits, in the axis's own units. */
+  value: number;
+  /** What is written beside it. */
+  label: string;
+}
+
+/** One vertical axis of a parallel-coordinates figure, and the column it draws. */
+export interface ParallelAxis {
+  /**
+   * A stable key, which is how a brushed range is reported and how a caller
+   * names the axis the colour is read from. Never an index: axes are added and
+   * reordered, and a range keyed on a position outlives the axis it belonged
+   * to.
+   */
+  id: string;
+  /** What it is called, written over the axis. */
+  label: string;
+  /**
+   * Every row's value, in the figure's row order. Read in place — nothing is
+   * copied — so a `Float64Array` is the cheapest thing to pass.
+   */
+  values: ArrayLike<number>;
+  /**
+   * The two ends of the axis, low first. Left out, they are the column's own
+   * smallest and largest finite value, and a column with no spread at all is
+   * opened by half a unit on each side so that it still draws.
+   * @default undefined — the column's own range
+   */
+  domain?: readonly [number, number];
+  /**
+   * How values are placed between the ends. `log` needs a domain whose low end
+   * is above zero; a value at or below zero is pinned to the low end.
+   * @default 'linear'
+   */
+  scale?: ParallelAxisScale;
+  /**
+   * How a tick is written. Left out, the ticks carry as many decimals as the
+   * spacing needs.
+   * @default undefined
+   */
+  format?: (value: number) => string;
+  /**
+   * The graduations, written out by the caller — what a coded quantity needs,
+   * where `0`, `1`, `2` should read `none`, `low`, `high`.
+   * @default undefined — the figure graduates the axis itself
+   */
+  ticks?: readonly ParallelTick[];
+  /**
+   * Roughly how many graduations to aim for, when the figure picks them.
+   * @default 5
+   */
+  tickCount?: number;
+  /**
+   * Whether the ends are rounded outward to whole tick steps. Off, so the axis
+   * ends exactly on the data — a reader comparing two molecules on a drug
+   * score must see the best one touch the top of its axis, not float below a
+   * round number nothing reached.
+   * @default false
+   */
+  nice?: boolean;
+  /**
+   * The unit written after the axis name, e.g. `g/mol`.
+   * @default '' — nothing is written
+   */
+  unit?: string;
+}
+
+/** An interval kept on one axis, in that axis's own units, low first. */
+export type ParallelRange = readonly [number, number];
+
+/** Which rows a set of brushes keeps, keyed by axis id. */
+export type ParallelRanges = Readonly<Record<string, ParallelRange | null>>;
+
+/** How the lines are coloured. */
+export interface ParallelColorBy {
+  /** The quantity read for each row, in the figure's row order. */
+  values: ArrayLike<number>;
+  /**
+   * The value at the low end of the ramp.
+   * @default the smallest finite value
+   */
+  min?: number;
+  /**
+   * The value at its high end.
+   * @default the largest finite value
+   */
+  max?: number;
+  /**
+   * The ramp, as the registry hands it over or as a plain list of colours.
+   * @default viridis — `resolveColorScale(DEFAULT_COLOR_SCALE_ID).scale`
+   */
+  scale?: ColorScale | readonly string[];
+  /**
+   * Whether the quantity is read on a base-10 logarithmic ramp.
+   * @default false
+   */
+  logarithmic?: boolean;
+}
+
+/** An axis described by the field to read off each row, rather than by its column. */
+export type ParallelAxisSource<Row> = Omit<ParallelAxis, 'values'> & {
+  /**
+   * The value this axis reads off one row. Called once per row per data
+   * change, never per repaint.
+   */
+  readonly value: (row: Row) => number;
+};
+
+/**
+ * One axis built by reading a field off each row.
+ *
+ * The one place a row type is named: the figure itself reads numbers out of a
+ * typed array, so a repaint costs an indexed read rather than a call per
+ * value. Call it inside a `useMemo` keyed on the rows.
+ * @param rows - The rows, in the order the figure will index them.
+ * @param axis - The axis, with the field to read instead of its values.
+ * @returns The axis, with its values filled in.
+ */
+export function parallelAxisOf<Row>(
+  rows: readonly Row[],
+  axis: ParallelAxisSource<Row>,
+): ParallelAxis {
+  const { value, ...rest } = axis;
+  const values = new Float64Array(rows.length);
+  for (let row = 0; row < rows.length; row++) {
+    values[row] = value(rows[row] as Row);
+  }
+  return { ...rest, values };
+}

package/src/parallel/ui/ParallelAxesLayer.tsx

@@ -0,0 +1,123 @@
+import type { ReactElement } from 'react';
+
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import { PARALLEL_MARGIN, parallelValueToY } from '../core/parallelAxes.ts';
+import type { ParallelBand } from '../core/parallelBrush.ts';
+import { PARALLEL_BRUSH_HALF_WIDTH } from '../core/parallelBrush.ts';
+
+import {
+  PARALLEL_HANDLE_HEIGHT,
+  PARALLEL_TICK_LABEL_INSET,
+  PARALLEL_TICK_LABEL_STYLE,
+  PARALLEL_TICK_LENGTH,
+  parallelBandStyle,
+  parallelHandleStyle,
+} from './parallelStyles.ts';
+
+/** What {@link ParallelAxesLayer} draws. */
+export interface ParallelAxesLayerProps {
+  /** The axes, from left to right, already placed and graduated. */
+  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 ink the axes, their ticks and their labels are drawn in. */
+  axisInk: string;
+  /** The ink a band is filled and outlined in. */
+  bandInk: string;
+}
+
+/**
+ * The axes, their graduations and the intervals brushed on them.
+ *
+ * Every axis carries a `data-parallel-brush` rectangle over the strip a press
+ * on it reaches, which nothing points at: one surface over the whole figure
+ * takes every event, so the rectangle exists to be found — by a test driving
+ * a drag, and by a reader's eye, which is the same thing.
+ * @param props - See {@link ParallelAxesLayerProps}.
+ * @returns The axes.
+ */
+export function ParallelAxesLayer(props: ParallelAxesLayerProps): ReactElement {
+  const { layouts, innerHeight, bands, axisInk, bandInk } = props;
+  const stroke = { stroke: axisInk };
+
+  return (
+    <g
+      transform={`translate(${PARALLEL_MARGIN.left},${PARALLEL_MARGIN.top})`}
+      style={{ fill: axisInk }}
+      textAnchor="middle"
+    >
+      {layouts.map((layout) => {
+        const band = bands.get(layout.id) ?? null;
+        return (
+          <g
+            key={layout.id}
+            className="parallel-axis"
+            data-parallel-axis={layout.id}
+            transform={`translate(${layout.x},0)`}
+          >
+            <line y2={innerHeight} style={stroke} />
+            {layout.ticks.map((tick) => (
+              <g
+                key={tick.value}
+                transform={`translate(0,${parallelValueToY(tick.value, layout)})`}
+              >
+                <line x1={-PARALLEL_TICK_LENGTH} style={stroke} />
+                <text
+                  x={-PARALLEL_TICK_LABEL_INSET}
+                  dy="0.32em"
+                  textAnchor="end"
+                  style={PARALLEL_TICK_LABEL_STYLE}
+                >
+                  {tick.label}
+                </text>
+              </g>
+            ))}
+            <rect
+              data-parallel-brush={layout.id}
+              x={-PARALLEL_BRUSH_HALF_WIDTH}
+              y={0}
+              width={PARALLEL_BRUSH_HALF_WIDTH * 2}
+              height={Math.max(0, innerHeight)}
+              fill="transparent"
+              pointerEvents="none"
+            />
+            {band === null ? null : <BrushBand band={band} ink={bandInk} />}
+          </g>
+        );
+      })}
+    </g>
+  );
+}
+
+function BrushBand(props: { band: ParallelBand; ink: string }): ReactElement {
+  const { band, ink } = props;
+  const height = Math.max(0, band.bottom - band.top);
+  const width = PARALLEL_BRUSH_HALF_WIDTH * 2;
+  return (
+    <g className="parallel-axis-band" pointerEvents="none">
+      <rect
+        x={-PARALLEL_BRUSH_HALF_WIDTH}
+        y={band.top}
+        width={width}
+        height={height}
+        style={parallelBandStyle(ink)}
+      />
+      <rect
+        x={-PARALLEL_BRUSH_HALF_WIDTH}
+        y={band.top - PARALLEL_HANDLE_HEIGHT / 2}
+        width={width}
+        height={PARALLEL_HANDLE_HEIGHT}
+        style={parallelHandleStyle(ink)}
+      />
+      <rect
+        x={-PARALLEL_BRUSH_HALF_WIDTH}
+        y={band.bottom - PARALLEL_HANDLE_HEIGHT / 2}
+        width={width}
+        height={PARALLEL_HANDLE_HEIGHT}
+        style={parallelHandleStyle(ink)}
+      />
+    </g>
+  );
+}

package/src/parallel/ui/ParallelCoordinates.tsx

@@ -0,0 +1,233 @@
+import type { ReactElement } from 'react';
+import { useMemo, useState } from 'react';
+
+import { OverlayLayer } from '../../overlay/ui/OverlayLayer.tsx';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import { PARALLEL_MARGIN, parallelAxisLayouts } from '../core/parallelAxes.ts';
+import { parallelIncludedMask } from '../core/parallelFilter.ts';
+import {
+  parallelColorSteps,
+  parallelPalette,
+} from '../core/parallelPalette.ts';
+import type {
+  ParallelAxis,
+  ParallelRange,
+  ParallelRanges,
+} from '../core/parallelTypes.ts';
+
+import { ParallelAxesLayer } from './ParallelAxesLayer.tsx';
+import { ParallelLabels } from './ParallelLabels.tsx';
+import { ParallelTooltip } from './ParallelTooltip.tsx';
+import type { ParallelCoordinatesProps } from './parallelCoordinatesProps.ts';
+import { useParallelInk } from './parallelInk.ts';
+import {
+  parallelColorOf,
+  parallelFigureLabel,
+  parallelHighlightsOf,
+  parallelIsBrushed,
+  parallelRowCount,
+} from './parallelPlotModel.ts';
+import {
+  PARALLEL_SVG_STYLE,
+  parallelCanvasStyle,
+  parallelFigureStyle,
+} from './parallelStyles.ts';
+import { useParallelCanvas } from './useParallelCanvas.ts';
+import { useParallelGesture } from './useParallelGesture.ts';
+
+/** Height the figure takes when the caller names none. */
+const DEFAULT_HEIGHT = 320;
+
+/** The smallest drawing area the figure will lay out, in pixels. */
+const SMALLEST_SIDE = 10;
+
+/** No axis is brushed, shared so an uncontrolled figure never rebuilds it. */
+const NO_RANGES: ParallelRanges = Object.freeze({});
+
+/**
+ * One vertical axis per column, one line per row, and a brush on every axis.
+ *
+ * It is told nothing about what the rows are: a library of molecules, a set of
+ * runs and a table of measurements all arrive as one `ArrayLike<number>` per
+ * axis, read in place. The lines are painted into a canvas because ten
+ * thousand of them are not ten thousand elements; everything the reader points
+ * at, brushes or reads is SVG and HTML over the top.
+ *
+ * The brush reports on release, never while the band is being dragged, so a
+ * table filtering on the same intervals re-renders once per gesture. What it
+ * keeps is `parallelIncludedMask`, which that table should filter with — two
+ * definitions of "kept" is how a figure and the list under it come to disagree.
+ * @param props - See {@link ParallelCoordinatesProps}.
+ * @returns The figure, or what the caller asked to show in its place when
+ * there is nothing to draw.
+ */
+export function ParallelCoordinates(
+  props: ParallelCoordinatesProps,
+): ReactElement {
+  const { axes, width, height = DEFAULT_HEIGHT, empty, overlay } = props;
+  const { selected, renderTooltip, renderAxisLabel } = props;
+  const { className, testId, ink: inkProp, label: given } = props;
+  const { ranges: ownedRanges, defaultRanges, included: givenMask } = props;
+  const { color: givenColor, colorAxis, onRangeChange: report } = props;
+  const { onRangePreview, hovered, onHoverChange, onRowClick } = props;
+  const count = parallelRowCount(axes, props.count);
+  const innerWidth = Math.max(
+    width - PARALLEL_MARGIN.left - PARALLEL_MARGIN.right,
+    SMALLEST_SIDE,
+  );
+  const innerHeight = Math.max(
+    height - PARALLEL_MARGIN.top - PARALLEL_MARGIN.bottom,
+    SMALLEST_SIDE,
+  );
+
+  const [ownRanges, setOwnRanges] = useState<ParallelRanges>(
+    defaultRanges ?? NO_RANGES,
+  );
+  const ranges = ownedRanges ?? ownRanges;
+
+  const layouts = useMemo(
+    () => parallelAxisLayouts(axes, count, innerWidth, innerHeight),
+    [axes, count, innerWidth, innerHeight],
+  );
+  const values = useMemo(() => columnsOf(axes), [axes]);
+  const { ink, ref: figure } = useParallelInk(inkProp);
+  const color = useMemo(
+    () => parallelColorOf(givenColor, colorAxis, axes),
+    [givenColor, colorAxis, axes],
+  );
+  const steps = useMemo(
+    () => (color === undefined ? null : parallelColorSteps(color, count)),
+    [color, count],
+  );
+  const palette = useMemo(
+    () => (color === undefined ? [] : parallelPalette(color.scale)),
+    [color],
+  );
+  const included = useMemo(() => {
+    if (givenMask !== undefined) return givenMask;
+    if (!parallelIsBrushed(axes, ranges)) return null;
+    return parallelIncludedMask(axes, ranges, count);
+  }, [givenMask, axes, ranges, count]);
+
+  function commitRange(axisId: string, range: ParallelRange | null): void {
+    if (ownedRanges === undefined) {
+      setOwnRanges((previous) => ({ ...previous, [axisId]: range }));
+    }
+    report?.(axisId, range);
+  }
+
+  const gesture = useParallelGesture({
+    layouts,
+    values,
+    count,
+    innerHeight,
+    included,
+    ranges,
+    onRangeChange: commitRange,
+    onRangePreview,
+    hovered,
+    onHoverChange,
+    onRowClick,
+  });
+
+  const highlights = useMemo(
+    () =>
+      parallelHighlightsOf(selected, gesture.hovered, ink.selection, ink.hover),
+    [selected, gesture.hovered, ink.selection, ink.hover],
+  );
+  const { lines: lineCanvas, marks: markCanvas } = useParallelCanvas({
+    width,
+    height,
+    layouts,
+    values,
+    count,
+    included,
+    steps,
+    palette,
+    highlights,
+    ink,
+  });
+
+  const label = given ?? parallelFigureLabel(axes, count);
+  const canvasStyle = parallelCanvasStyle(height);
+  const hover =
+    gesture.pointer === null || gesture.hovered < 0
+      ? null
+      : { index: gesture.hovered, ...gesture.pointer };
+
+  return (
+    <div
+      ref={figure}
+      className={joinClassNames('parallel-coordinates', className)}
+      style={parallelFigureStyle(height)}
+      data-testid={testId}
+    >
+      {count === 0 || layouts.length === 0 ? (
+        empty
+      ) : (
+        <>
+          <canvas
+            ref={lineCanvas}
+            className="parallel-coordinates-canvas"
+            style={canvasStyle}
+          />
+          <canvas
+            ref={markCanvas}
+            className="parallel-coordinates-canvas"
+            style={canvasStyle}
+          />
+          <svg
+            width={Math.max(0, width)}
+            height={Math.max(0, height)}
+            style={PARALLEL_SVG_STYLE}
+            role="img"
+            aria-label={label}
+          >
+            <ParallelAxesLayer
+              layouts={layouts}
+              innerHeight={innerHeight}
+              bands={gesture.bands}
+              axisInk={ink.axis}
+              bandInk={ink.selection}
+            />
+            <rect
+              x={0}
+              y={0}
+              width={Math.max(0, width)}
+              height={Math.max(0, height)}
+              fill="transparent"
+              onClick={gesture.onClick}
+              {...gesture.surface}
+            />
+          </svg>
+          <ParallelLabels
+            axes={axes}
+            layouts={layouts}
+            render={renderAxisLabel}
+          />
+          {hover === null || renderTooltip === undefined ? null : (
+            <ParallelTooltip
+              x={hover.x}
+              y={hover.y}
+              boxWidth={width}
+              boxHeight={height}
+            >
+              {renderTooltip(hover)}
+            </ParallelTooltip>
+          )}
+        </>
+      )}
+      {overlay === undefined ? null : (
+        <OverlayLayer width={width} busy={gesture.brushing}>
+          {overlay}
+        </OverlayLayer>
+      )}
+    </div>
+  );
+}
+
+function columnsOf(axes: readonly ParallelAxis[]): Array<ArrayLike<number>> {
+  const columns: Array<ArrayLike<number>> = [];
+  for (const axis of axes) columns.push(axis.values);
+  return columns;
+}

package/src/parallel/ui/ParallelLabels.tsx

@@ -0,0 +1,56 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import { PARALLEL_MARGIN } from '../core/parallelAxes.ts';
+import type { ParallelAxis } from '../core/parallelTypes.ts';
+
+import { PARALLEL_LABELS_STYLE, parallelLabelStyle } from './parallelStyles.ts';
+
+/** What {@link ParallelLabels} writes. */
+export interface ParallelLabelsProps {
+  /** The axes as the caller described them, for a caller's own renderer. */
+  axes: readonly ParallelAxis[];
+  /** The same axes, placed, so each name sits over its own axis. */
+  layouts: readonly ParallelAxisLayout[];
+  /**
+   * How a name is written. Left out, it is the label and the unit after it.
+   * @default undefined
+   */
+  render?: ((axis: ParallelAxis, index: number) => ReactNode) | undefined;
+}
+
+/**
+ * The axis names, as HTML over the figure.
+ *
+ * HTML rather than SVG text so that a name can carry a tooltip explaining what
+ * the axis measures. The layer lets every pointer event through and only the
+ * names themselves take it back, so a brush started under a name still starts.
+ * @param props - See {@link ParallelLabelsProps}.
+ * @returns The names.
+ */
+export function ParallelLabels(props: ParallelLabelsProps): ReactElement {
+  const { axes, layouts, render } = props;
+
+  return (
+    <div className="parallel-coordinates-labels" style={PARALLEL_LABELS_STYLE}>
+      {layouts.map((layout, index) => {
+        const axis = axes[index];
+        return (
+          <div
+            key={layout.id}
+            className="parallel-axis-label"
+            style={parallelLabelStyle(PARALLEL_MARGIN.left + layout.x)}
+          >
+            {axis !== undefined && render !== undefined
+              ? render(axis, index)
+              : defaultLabel(layout)}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function defaultLabel(layout: ParallelAxisLayout): string {
+  return layout.unit === '' ? layout.label : `${layout.label} (${layout.unit})`;
+}

package/src/parallel/ui/ParallelTooltip.tsx

@@ -0,0 +1,55 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useRef } from 'react';
+
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import { placeOverlayCard } from '../../overlay/core/placeOverlayCard.ts';
+
+import { parallelTooltipStyle } from './parallelStyles.ts';
+
+/** What {@link ParallelTooltip} shows, and where. */
+export interface ParallelTooltipProps {
+  /** Where the pointer is, in pixels from the figure's left edge. */
+  x: number;
+  /** Where it is, in pixels from its top edge. */
+  y: number;
+  /** Width of the figure, so the card is flipped rather than clipped. */
+  boxWidth: number;
+  /** Its height. */
+  boxHeight: number;
+  /** What the card says, written by the caller. */
+  children: ReactNode;
+}
+
+/**
+ * The card over the row under the pointer.
+ *
+ * It measures itself and flips rather than being clipped, because a card that
+ * runs off the bottom right of a figure is exactly where a reader points last
+ * — and it never takes the pointer, so moving towards it never dismisses it by
+ * moving off the line underneath.
+ * @param props - See {@link ParallelTooltipProps}.
+ * @returns The card.
+ */
+export function ParallelTooltip(props: ParallelTooltipProps): ReactElement {
+  const { x, y, boxWidth, boxHeight, children } = props;
+  const card = useRef<HTMLDivElement>(null);
+  const size = useContainerSize(card);
+  const placed = placeOverlayCard({
+    pointerX: x,
+    pointerY: y,
+    cardWidth: size.width,
+    cardHeight: size.height,
+    boxWidth,
+    boxHeight,
+  });
+
+  return (
+    <div
+      ref={card}
+      className="parallel-coordinates-tooltip"
+      style={parallelTooltipStyle(placed.left, placed.top)}
+    >
+      {children}
+    </div>
+  );
+}

package/src/parallel/ui/index.ts

@@ -0,0 +1,50 @@
+/**
+ * A parallel-coordinates figure the reader can interrogate: brush any axis to
+ * keep an interval of it, rest on a line for what is known about that row, and
+ * colour every line by whichever column answers the question being asked.
+ *
+ * Nothing here knows what the rows are. The same figure draws a library of
+ * molecules, a set of experimental runs and a table of measurements, which is
+ * why it is its own domain rather than part of the first viewer to want one.
+ */
+
+export { ParallelAxesLayer } from './ParallelAxesLayer.tsx';
+export type { ParallelAxesLayerProps } from './ParallelAxesLayer.tsx';
+export { ParallelCoordinates } from './ParallelCoordinates.tsx';
+export type {
+  ParallelCoordinatesProps,
+  ParallelHover,
+  ParallelInk,
+} from './parallelCoordinatesProps.ts';
+export type {
+  ParallelInkBinding,
+  ParallelInkValues,
+  ParallelTokenInk,
+} from './parallelInk.ts';
+export {
+  parallelInkFrom,
+  readParallelInk,
+  readParallelTokens,
+  useParallelInk,
+} from './parallelInk.ts';
+export { ParallelLabels } from './ParallelLabels.tsx';
+export type { ParallelLabelsProps } from './ParallelLabels.tsx';
+export {
+  parallelColorOf,
+  parallelFigureLabel,
+  parallelHighlightsOf,
+  parallelIsBrushed,
+  parallelRowCount,
+} from './parallelPlotModel.ts';
+export { ParallelTooltip } from './ParallelTooltip.tsx';
+export type { ParallelTooltipProps } from './ParallelTooltip.tsx';
+export type {
+  ParallelCanvasOptions,
+  ParallelCanvases,
+} from './useParallelCanvas.ts';
+export { useParallelCanvas } from './useParallelCanvas.ts';
+export type {
+  ParallelGesture,
+  ParallelGestureOptions,
+} from './useParallelGesture.ts';
+export { useParallelGesture } from './useParallelGesture.ts';