react-cheminfo 0.15.0 → 0.17.0

package/src/parallel/ui/ParallelLabels.tsx

@@ -0,0 +1,77 @@
+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';
+import type { ParallelAxisDrag } from './useParallelAxisDrag.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 gesture that moves an axis by its name.
+   * @default undefined — the axes are fixed
+   */
+  drag?: ParallelAxisDrag | 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, 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"
+            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)
+              : 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,65 @@
+/**
+ * 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 type { ParallelCommit, ParallelDraft } from './parallelGestureModel.ts';
+export {
+  parallelAxisById,
+  parallelAxisNear,
+  parallelBandsOf,
+  parallelCommitOf,
+  parallelPointOf,
+} from './parallelGestureModel.ts';
+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 {
+  ParallelAxisDrag,
+  ParallelAxisDragOptions,
+  ParallelAxisDragState,
+  ParallelAxisHandleProps,
+} from './useParallelAxisDrag.ts';
+export { useParallelAxisDrag } from './useParallelAxisDrag.ts';
+export type {
+  ParallelGesture,
+  ParallelGestureOptions,
+} from './useParallelGesture.ts';
+export { useParallelGesture } from './useParallelGesture.ts';

package/src/parallel/ui/parallelCoordinatesProps.ts

@@ -0,0 +1,217 @@
+/**
+ * What a caller hands a `ParallelCoordinates`.
+ *
+ * The types the figure is *told* about — an axis, an interval, a colour ramp —
+ * live in `parallel/core`, because the same words describe the mask a table
+ * beside the figure filters on and the layout the painter reads. What is left
+ * here is what only a React component has: the render props, the inks a canvas
+ * cannot read off a stylesheet, and the controlled pairs.
+ */
+
+import type { ReactNode } from 'react';
+
+import type {
+  ParallelAxis,
+  ParallelColorBy,
+  ParallelRange,
+  ParallelRanges,
+} from '../core/parallelTypes.ts';
+
+/** What the pointer is over, and where. */
+export interface ParallelHover {
+  /** The row, as an index into the axes' value arrays. */
+  index: number;
+  /** 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;
+}
+
+/** The colours a canvas is painted with, which cannot read a custom property. */
+export interface ParallelInk {
+  /**
+   * The rows a brush left out, drawn under the rest.
+   * @default a light grey the dense mass can only converge on
+   */
+  excluded?: string;
+  /**
+   * The rows nothing is colouring, when no quantity was given.
+   * @default the value of `--text-muted` on the figure
+   */
+  line?: string;
+  /**
+   * The row under the pointer.
+   * @default the value of `--text` on the figure
+   */
+  hover?: string;
+  /**
+   * The rows singled out elsewhere — picked in a table, pinned by the reader.
+   * @default the value of `--accent` on the figure
+   */
+  selection?: string;
+  /**
+   * The halo a singled-out line is drawn over, so it reads against the mass.
+   * @default the value of `--surface`, at 85%
+   */
+  halo?: string;
+  /**
+   * The axis lines, their ticks and their labels.
+   * @default the value of `--text-muted`
+   */
+  axis?: string;
+  /**
+   * How strongly a kept line is drawn. Turn it down for a dense library.
+   * @default 0.35
+   */
+  includedAlpha?: number;
+}
+
+/** What `ParallelCoordinates` needs. */
+export interface ParallelCoordinatesProps {
+  /** The axes, from left to right. Fewer than two draws no lines. */
+  axes: readonly ParallelAxis[];
+  /**
+   * How many rows to draw.
+   * @default the shortest axis's value count
+   */
+  count?: number;
+  /** Total width, in pixels, normally from `useContainerSize`. */
+  width: number;
+  /**
+   * Total height, axis names and tick labels included.
+   * @default 320
+   */
+  height?: number;
+
+  /**
+   * 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;
+  /**
+   * The intervals in force before the reader touches anything.
+   * @default undefined — no axis is brushed
+   */
+  defaultRanges?: ParallelRanges;
+  /**
+   * 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, 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, 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`,
+   * which is exported so a table beside the figure filters on the same answer
+   * rather than on a second definition of "kept".
+   * @default undefined — worked out from the ranges
+   */
+  included?: Uint8Array;
+
+  /**
+   * The row under the pointer, or `-1`. Present, the caller owns it, which is
+   * what lets a table hovered elsewhere light up its line here.
+   * @default undefined — the figure keeps its own
+   */
+  hovered?: number;
+  /**
+   * Called with the row under the pointer, or `-1`, whenever that changes.
+   * @default undefined
+   */
+  onHoverChange?: (index: number) => void;
+  /**
+   * The rows singled out elsewhere, drawn over the mass in the selection ink.
+   * A row that is also the hovered one is drawn once, in the hover ink.
+   * @default undefined — nothing is singled out
+   */
+  selected?: readonly number[];
+  /**
+   * Called when a line is clicked, with the row, or `-1` for empty ground.
+   * @default undefined — the lines are not clickable
+   */
+  onRowClick?: (index: number) => void;
+
+  /**
+   * The quantity the lines are coloured by.
+   * @default undefined — every line takes one ink
+   */
+  color?: ParallelColorBy;
+  /**
+   * The id of the axis the lines are coloured by, for the common case where it
+   * is one of the axes already drawn. Ignored when `color` is given.
+   * @default undefined
+   */
+  colorAxis?: string;
+  /**
+   * The canvas colours, merged over the ones read off the figure's own tokens.
+   * @default {}
+   */
+  ink?: ParallelInk;
+
+  /**
+   * The card shown over the row under the pointer. It is placed by the figure,
+   * flipped rather than clipped at either edge, so a caller writes only what
+   * it says.
+   * @default undefined — no card is shown
+   */
+  renderTooltip?: (hover: ParallelHover) => ReactNode;
+  /**
+   * How an axis is named. The default writes the label and its unit; a caller
+   * wraps it to hang a help tooltip off the name.
+   * @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
+   */
+  empty?: ReactNode;
+  /**
+   * What floats over the figure — a legend, a colour scale key, a caption.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+
+  /**
+   * What a screen reader is told the figure shows.
+   * @default a sentence naming the axes and the row count
+   */
+  label?: string;
+  /**
+   * A class for the figure's outermost element, for a site placing it.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}

package/src/parallel/ui/parallelGestureModel.ts

@@ -0,0 +1,159 @@
+/**
+ * The questions the gesture asks that need neither React nor state: where a
+ * press landed, which axis it reached, and which band each axis should be
+ * drawn with once the one being dragged is taken into account.
+ *
+ * Kept out of the hook the way `lassoGesture.ts` is kept out of its own — each
+ * of these has exactly one answer, and none of them needs a render to be read.
+ */
+
+import type { SurfaceEvent } from '../../scatter/ui/lassoGesture.ts';
+import { surfacePosition } from '../../scatter/ui/lassoGesture.ts';
+import type { ParallelAxisLayout } from '../core/parallelAxes.ts';
+import { PARALLEL_MARGIN } from '../core/parallelAxes.ts';
+import type { ParallelBand } from '../core/parallelBrush.ts';
+import {
+  PARALLEL_BRUSH_HALF_WIDTH,
+  parallelBandOf,
+  parallelIsBand,
+  parallelRangeOf,
+} from '../core/parallelBrush.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;
+}
+
+/**
+ * Where an event landed, relative to the top left of the drawing area.
+ * @param event - The event, for where on the surface it happened.
+ * @returns The position, in pixels from the corner of the drawing area.
+ */
+export function parallelPointOf(event: SurfaceEvent): {
+  x: number;
+  y: number;
+} {
+  const position = surfacePosition(event, 0, 0);
+  return {
+    x: position.x - PARALLEL_MARGIN.left,
+    y: position.y - PARALLEL_MARGIN.top,
+  };
+}
+
+/**
+ * Which axis a press at that horizontal position took hold of.
+ * @param x - Pixels from the left of the drawing area.
+ * @param axes - The axes, from left to right.
+ * @returns The axis's index, or `-1` when the press landed between two of them.
+ */
+export function parallelAxisNear(
+  x: number,
+  axes: readonly ParallelAxisLayout[],
+): number {
+  let nearest = -1;
+  let nearestDistance = PARALLEL_BRUSH_HALF_WIDTH;
+  for (let index = 0; index < axes.length; index++) {
+    const axis = axes[index];
+    if (axis === undefined) continue;
+    const distance = Math.abs(x - axis.x);
+    if (distance <= nearestDistance) {
+      nearestDistance = distance;
+      nearest = index;
+    }
+  }
+  return nearest;
+}
+
+/**
+ * One axis, by the id a range is keyed on.
+ * @param axes - The axes, from left to right.
+ * @param axisId - The id to find.
+ * @returns The axis, or `undefined` when it is no longer drawn.
+ */
+export function parallelAxisById(
+  axes: readonly ParallelAxisLayout[],
+  axisId: string,
+): ParallelAxisLayout | undefined {
+  for (const axis of axes) {
+    if (axis.id === axisId) return axis;
+  }
+  return undefined;
+}
+
+/**
+ * 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 - 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. 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[]>();
+  for (const axis of axes) {
+    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));
+    }
+    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);
+}