react-cheminfo 0.15.0 → 0.17.0

package/src/parallel/ui/parallelInk.ts

@@ -0,0 +1,182 @@
+/**
+ * The colours the canvas is painted with, read off the figure itself.
+ *
+ * A canvas takes a colour, not a CSS declaration, so `var(--accent)` means
+ * nothing to it — and the family's accent is the one colour a site owns, so it
+ * cannot be written into a shared library either. The figure therefore asks
+ * the browser what its own tokens resolved to, once it is on the page, and
+ * paints with the answer.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+
+import { parseHexColor } from '../../color/core/hex.ts';
+import { FAMILY_TOKEN_VALUES } from '../../tokens/core/familyTokens.ts';
+import { PARALLEL_INCLUDED_ALPHA } from '../core/parallelPaint.ts';
+
+import type { ParallelInk } from './parallelCoordinatesProps.ts';
+
+/**
+ * The rows a brush left out. A light grey rather than a translucent black:
+ * overlapping segments of one stroked path accumulate alpha, so a translucent
+ * black saturates wherever the library is dense, while this is the colour the
+ * pile can only converge on.
+ */
+const EXCLUDED = 'rgba(171, 179, 191, 0.16)';
+
+/** How solid the halo under a singled-out line is. */
+const HALO_ALPHA = 0.85;
+
+/** The halo a page that declares no surface colour still gets. */
+const WHITE_HALO = `rgba(255, 255, 255, ${HALO_ALPHA})`;
+
+/** The four tokens the figure paints from, as the page resolved them. */
+export interface ParallelTokenInk {
+  /** What `--text` resolved to. */
+  text: string;
+  /** What `--text-muted` resolved to. */
+  textMuted: string;
+  /** What `--surface` resolved to. */
+  surface: string;
+  /** What `--accent` resolved to, or the text colour when a site declares none. */
+  accent: string;
+}
+
+/** Every colour the figure paints with, resolved to something a canvas takes. */
+export interface ParallelInkValues {
+  /** The rows a brush left out. */
+  excluded: string;
+  /** The rows nothing is colouring. */
+  line: string;
+  /** The row under the pointer. */
+  hover: string;
+  /** The rows singled out elsewhere. */
+  selection: string;
+  /** The halo a singled-out line is drawn over. */
+  halo: string;
+  /** The axis lines, their ticks and their labels. */
+  axis: string;
+  /** How strongly a kept line is drawn. */
+  includedAlpha: number;
+}
+
+/**
+ * What the figure's own tokens resolved to.
+ * @param element - The figure, once it is on the page, or `null` before it is.
+ * @returns The four colours. Off the page — a server render, a test — the
+ * family's own token values stand in, so the figure never paints with nothing.
+ */
+export function readParallelTokens(element: Element | null): ParallelTokenInk {
+  const text = tokenColor(element, '--text', FAMILY_TOKEN_VALUES['--text']);
+  return {
+    text,
+    textMuted: tokenColor(
+      element,
+      '--text-muted',
+      FAMILY_TOKEN_VALUES['--text-muted'],
+    ),
+    surface: tokenColor(element, '--surface', FAMILY_TOKEN_VALUES['--surface']),
+    // A site that declares no accent still singles a row out, in its ink.
+    accent: tokenColor(element, '--accent', text),
+  };
+}
+
+/**
+ * The inks to paint with, from the page's tokens and the caller's overrides.
+ * @param tokens - What the figure's own tokens resolved to.
+ * @param ink - What the caller insists on, over every one of them.
+ * @returns The inks.
+ */
+export function parallelInkFrom(
+  tokens: ParallelTokenInk,
+  ink: ParallelInk = {},
+): ParallelInkValues {
+  return {
+    excluded: ink.excluded ?? EXCLUDED,
+    line: ink.line ?? tokens.textMuted,
+    hover: ink.hover ?? tokens.text,
+    selection: ink.selection ?? tokens.accent,
+    halo: ink.halo ?? haloOf(tokens.surface),
+    axis: ink.axis ?? tokens.textMuted,
+    includedAlpha: ink.includedAlpha ?? PARALLEL_INCLUDED_ALPHA,
+  };
+}
+
+/**
+ * The inks to paint with, read off one element.
+ * @param element - The figure, once it is on the page, or `null` before it is.
+ * @param ink - What the caller insists on, over everything read off the page.
+ * @returns The inks.
+ */
+export function readParallelInk(
+  element: Element | null,
+  ink: ParallelInk = {},
+): ParallelInkValues {
+  return parallelInkFrom(readParallelTokens(element), ink);
+}
+
+/** The inks, and the ref that has to reach the figure for them to be read. */
+export interface ParallelInkBinding {
+  /** The colours to paint with. */
+  ink: ParallelInkValues;
+  /** Put on the figure's outermost element. */
+  ref: (element: Element | null) => void;
+}
+
+/**
+ * The inks, with the page's own tokens read the moment the figure is mounted.
+ *
+ * A callback ref rather than an effect, because the question is asked once, of
+ * the element itself, and there is nothing to keep in step afterwards.
+ * @param ink - What the caller insists on.
+ * @returns The inks and the ref. See {@link ParallelInkBinding}.
+ */
+export function useParallelInk(ink: ParallelInk = {}): ParallelInkBinding {
+  const [tokens, setTokens] = useState<ParallelTokenInk>(readFamilyTokens);
+  const { excluded, line, hover, selection, halo, axis, includedAlpha } = ink;
+
+  const ref = useCallback((element: Element | null) => {
+    if (element !== null) setTokens(readParallelTokens(element));
+  }, []);
+
+  const resolved = useMemo(
+    () =>
+      parallelInkFrom(tokens, {
+        excluded,
+        line,
+        hover,
+        selection,
+        halo,
+        axis,
+        includedAlpha,
+      }),
+    [tokens, excluded, line, hover, selection, halo, axis, includedAlpha],
+  );
+
+  return { ink: resolved, ref };
+}
+
+function readFamilyTokens(): ParallelTokenInk {
+  return readParallelTokens(null);
+}
+
+function tokenColor(
+  element: Element | null,
+  name: string,
+  fallback: string,
+): string {
+  const resolve = globalThis.getComputedStyle;
+  if (element === null || typeof resolve !== 'function') return fallback;
+  const declared = resolve(element).getPropertyValue(name).trim();
+  return declared === '' ? fallback : declared;
+}
+
+function haloOf(surface: string): string {
+  try {
+    const { red, green, blue } = parseHexColor(surface);
+    return `rgba(${red}, ${green}, ${blue}, ${HALO_ALPHA})`;
+  } catch {
+    // A surface written as anything but a hex colour still gets a halo.
+    return WHITE_HALO;
+  }
+}

package/src/parallel/ui/parallelPlotModel.ts

@@ -0,0 +1,130 @@
+/**
+ * The small answers the figure needs before it renders: how many rows there
+ * are, what is colouring the lines, which rows are drawn over the mass, and
+ * what a screen reader is told.
+ *
+ * Kept out of the component for the reason `scatterPlotModel.ts` is: none of
+ * them needs React to be read or checked, and a component that is mostly
+ * arithmetic is a component nobody can see the layout in.
+ */
+
+import { formatInteger } from '../../format/core/numbers.ts';
+import type { ParallelHighlight } from '../core/parallelPaint.ts';
+import { parallelHasRange } from '../core/parallelSelection.ts';
+import type {
+  ParallelAxis,
+  ParallelColorBy,
+  ParallelRanges,
+} from '../core/parallelTypes.ts';
+
+/**
+ * How many rows the figure draws.
+ * @param axes - The axes, whose columns are read.
+ * @param count - What the caller insists on, if anything.
+ * @returns The count — the shortest column, so no axis is ever read past its
+ * own end.
+ */
+export function parallelRowCount(
+  axes: readonly ParallelAxis[],
+  count?: number,
+): number {
+  if (count !== undefined) return Math.max(0, Math.trunc(count));
+  let shortest = 0;
+  for (let index = 0; index < axes.length; index++) {
+    const axis = axes[index];
+    if (axis === undefined) continue;
+    const length = axis.values.length;
+    if (index === 0 || length < shortest) shortest = length;
+  }
+  return shortest;
+}
+
+/**
+ * The quantity the lines are coloured by.
+ * @param color - The quantity the caller gave outright.
+ * @param colorAxis - The id of an axis already drawn, for the common case.
+ * @param axes - The axes, to find that id among.
+ * @returns The quantity, or `undefined` when the lines all take one ink. An
+ * axis named by `colorAxis` lends its own domain as well as its values, so the
+ * ramp and the axis beside it read the same range.
+ */
+export function parallelColorOf(
+  color: ParallelColorBy | undefined,
+  colorAxis: string | undefined,
+  axes: readonly ParallelAxis[],
+): ParallelColorBy | undefined {
+  if (color !== undefined) return color;
+  if (colorAxis === undefined) return undefined;
+  for (const axis of axes) {
+    if (axis.id !== colorAxis) continue;
+    const domain = axis.domain;
+    if (domain === undefined) return { values: axis.values };
+    return {
+      values: axis.values,
+      min: Math.min(domain[0], domain[1]),
+      max: Math.max(domain[0], domain[1]),
+      logarithmic: axis.scale === 'log',
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Whether any axis on the figure carries an interval at all.
+ * @param axes - The axes, whose ids the intervals are keyed by.
+ * @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.
+ */
+export function parallelIsBrushed(
+  axes: readonly ParallelAxis[],
+  ranges: ParallelRanges,
+): boolean {
+  for (const axis of axes) {
+    if (parallelHasRange(ranges[axis.id])) return true;
+  }
+  return false;
+}
+
+/**
+ * The rows drawn over the mass, in the order they are painted.
+ * @param selected - The rows singled out elsewhere.
+ * @param hovered - The row under the pointer, or `-1`.
+ * @param selectionInk - The ink a singled-out row takes.
+ * @param hoverInk - The ink the hovered row takes.
+ * @returns The highlights, the hovered row last so that it paints on top and
+ * a row that is both selected and hovered is drawn once rather than twice.
+ */
+export function parallelHighlightsOf(
+  selected: readonly number[] | undefined,
+  hovered: number,
+  selectionInk: string,
+  hoverInk: string,
+): ParallelHighlight[] {
+  const highlights: ParallelHighlight[] = [];
+  if (selected !== undefined) {
+    for (const row of selected) {
+      if (row < 0 || row === hovered) continue;
+      highlights.push({ row, color: selectionInk });
+    }
+  }
+  if (hovered >= 0) highlights.push({ row: hovered, color: hoverInk });
+  return highlights;
+}
+
+/**
+ * What a screen reader is told the figure shows.
+ * @param axes - The axes, from left to right.
+ * @param count - How many rows are drawn.
+ * @returns The sentence, naming every axis and how much is on the figure.
+ */
+export function parallelFigureLabel(
+  axes: readonly ParallelAxis[],
+  count: number,
+): string {
+  const names: string[] = [];
+  for (const axis of axes) names.push(axis.label);
+  const rows = count === 1 ? '1 row' : `${formatInteger(count)} rows`;
+  if (names.length === 0) return `Parallel coordinates of ${rows}.`;
+  return `Parallel coordinates of ${rows}, on ${names.join(', ')}.`;
+}

package/src/parallel/ui/parallelStyles.ts

@@ -0,0 +1,188 @@
+/**
+ * Every rule the figure is drawn with.
+ *
+ * The library ships no stylesheet for a figure — a chart writes inline style
+ * objects, so a site that never renders one pays nothing and a site that does
+ * cannot forget to import a file. The two colours that are not fixed here, the
+ * axis ink and the band's, are resolved off the page by `parallelInk.ts` and
+ * written onto the elements, so an override applies to the canvas and to the
+ * markup alike.
+ */
+
+import type { CSSProperties } from 'react';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+/** A layer covering the whole figure, stacked over the ones before it. */
+export const PARALLEL_LAYER_STYLE = {
+  position: 'absolute',
+  inset: 0,
+} as const satisfies CSSProperties;
+
+/**
+ * The block the figure occupies, which every layer is positioned against.
+ * @param height - Total height of the figure, in pixels.
+ * @returns The wrapper's rules.
+ */
+export function parallelFigureStyle(height: number): CSSProperties {
+  return {
+    position: 'relative',
+    height: Math.max(0, height),
+    minWidth: 0,
+  };
+}
+
+/**
+ * One of the two canvases, stretched over the figure.
+ * @param height - Total height of the figure, in pixels.
+ * @returns The canvas's rules.
+ */
+export function parallelCanvasStyle(height: number): CSSProperties {
+  return {
+    ...PARALLEL_LAYER_STYLE,
+    width: '100%',
+    height: Math.max(0, height),
+  };
+}
+
+/** The drawing surface the axes, the bands and the pointer target live in. */
+export const PARALLEL_SVG_STYLE = {
+  ...PARALLEL_LAYER_STYLE,
+  display: 'block',
+  overflow: 'visible',
+} as const satisfies CSSProperties;
+
+/**
+ * The layer the axis names sit in. It is HTML rather than SVG text so that a
+ * name can carry a tooltip, and it lets every pointer event through so that a
+ * brush started under a name still starts.
+ */
+export const PARALLEL_LABELS_STYLE = {
+  ...PARALLEL_LAYER_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 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(
+  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:
+      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',
+  };
+}
+
+/** One tick written out, tabular so a column of them lines up on the point. */
+export const PARALLEL_TICK_LABEL_STYLE = {
+  fontSize: 10,
+  fontVariantNumeric: 'tabular-nums',
+  userSelect: 'none',
+} as const satisfies CSSProperties;
+
+/** How far a tick mark reaches out of the axis, in pixels. */
+export const PARALLEL_TICK_LENGTH = 4;
+
+/** How far a tick label ends before its axis. */
+export const PARALLEL_TICK_LABEL_INSET = 7;
+
+/**
+ * The interval one brush keeps, filled in the site's own colour.
+ * @param ink - The colour to fill and outline it in.
+ * @returns The band's rules.
+ */
+export function parallelBandStyle(ink: string): CSSProperties {
+  return {
+    fill: ink,
+    fillOpacity: 0.16,
+    stroke: ink,
+    strokeOpacity: 0.55,
+  };
+}
+
+/**
+ * Either edge of a band, drawn so the reader can see it can be dragged.
+ * @param ink - The colour to draw it in.
+ * @returns The handle's rules.
+ */
+export function parallelHandleStyle(ink: string): CSSProperties {
+  return { fill: ink, fillOpacity: 0.9 };
+}
+
+/** How tall an edge handle is drawn, in pixels. */
+export const PARALLEL_HANDLE_HEIGHT = 3;
+
+/**
+ * The card over the row under the pointer.
+ * @param left - Where it sits, in pixels from the figure's left edge.
+ * @param top - Where it sits, in pixels from its top edge.
+ * @returns The card's rules.
+ */
+export function parallelTooltipStyle(left: number, top: number): CSSProperties {
+  return {
+    position: 'absolute',
+    zIndex: 5,
+    left,
+    top,
+    padding: '4px 8px',
+    borderRadius: 6,
+    background: TOKEN.text,
+    color: TOKEN.surface,
+    fontSize: 11,
+    fontVariantNumeric: 'tabular-nums',
+    lineHeight: 1.4,
+    pointerEvents: 'none',
+    whiteSpace: 'nowrap',
+    boxShadow: TOKEN.shadowMedium,
+  };
+}

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.
+}