react-cheminfo 0.15.0 → 0.16.0

package/src/parallel/ui/parallelCoordinatesProps.ts

@@ -0,0 +1,199 @@
+/**
+ * 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;
+
+  /**
+   * 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.
+   * @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;
+  /**
+   * Called when a brush is released, with the interval it keeps or `null` when
+   * it was cleared — never while the band is being dragged.
+   * @default undefined
+   */
+  onRangeChange?: (axisId: string, range: ParallelRange | null) => 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;
+  /**
+   * 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;
+  /**
+   * 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,109 @@
+/**
+ * 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,
+} from '../core/parallelBrush.ts';
+import type { 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;
+  /** 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 band to draw on each axis: the one being dragged where there is one, and
+ * the interval in force everywhere else.
+ * @param axes - The axes, from left to right.
+ * @param ranges - The interval each axis keeps, or `null` for 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.
+ */
+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) {
+    if (draft !== null && draft.axis === axis.id) {
+      drawn.set(axis.id, draft.band);
+      continue;
+    }
+    const range = ranges[axis.id];
+    if (range === null || range === undefined) continue;
+    drawn.set(axis.id, parallelBandOf(range, axis));
+  }
+  return drawn;
+}

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 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 - The interval 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) {
+    const range = ranges[axis.id];
+    if (range !== null && range !== undefined) 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(', ')}.`;
+}