react-cheminfo 0.9.0 → 0.11.0

package/src/chart/core/matrix.ts

@@ -0,0 +1,100 @@
+/**
+ * Read-only view of a numeric matrix, satisfied by `ml-matrix`'s `Matrix`
+ * without a cast.
+ *
+ * Only `get` is required, because it is the cheapest read there is — 1.25 ns a
+ * cell against 12.2 ns through `to2DArray()`, which reallocates every row on
+ * every call. Nothing in this package ever copies a matrix out.
+ */
+export interface MatrixLike {
+  /** Number of rows. */
+  readonly rows: number;
+  /** Number of columns. */
+  readonly columns: number;
+  /**
+   * The value at a position.
+   * @param rowIndex - Which row, from 0.
+   * @param columnIndex - Which column, from 0.
+   * @returns The value, or `NaN` when either index is outside the matrix.
+   */
+  get: (rowIndex: number, columnIndex: number) => number;
+}
+
+/**
+ * A plain array of rows read as a matrix.
+ *
+ * The door every method that is not `ml-pca` comes through: a UMAP embedding
+ * or a k-means table is `number[][]`, and this gives it the one shape the rest
+ * of the package reads, with no copy and no dependency.
+ * @param rows - One array per row; the width is taken from the first.
+ * @returns The matrix view. An empty input gives a zero by zero matrix.
+ */
+export function rowMatrix(rows: ReadonlyArray<ArrayLike<number>>): MatrixLike {
+  const first = rows[0];
+  const columns = first === undefined ? 0 : first.length;
+  return {
+    rows: rows.length,
+    columns,
+    get(rowIndex: number, columnIndex: number): number {
+      if (columnIndex < 0 || columnIndex >= columns) return Number.NaN;
+      const row = rows[rowIndex];
+      if (row === undefined) return Number.NaN;
+      const value = row[columnIndex];
+      return value === undefined ? Number.NaN : value;
+    },
+  };
+}
+
+/**
+ * A matrix whose values pass through a function on the way out.
+ *
+ * It exists for the sign convention: a principal component's direction is
+ * arbitrary, so the scores of a flipped component have to be negated, and
+ * negating them in place would mean allocating a copy of the whole score
+ * matrix to change one column's sign.
+ * @param source - The matrix to read.
+ * @param transform - Applied to every value, given its position.
+ * @returns The mapped view, which holds a reference to `source` rather than a copy.
+ */
+export function mappedMatrix(
+  source: MatrixLike,
+  transform: (value: number, rowIndex: number, columnIndex: number) => number,
+): MatrixLike {
+  return {
+    rows: source.rows,
+    columns: source.columns,
+    get(rowIndex: number, columnIndex: number): number {
+      return transform(
+        source.get(rowIndex, columnIndex),
+        rowIndex,
+        columnIndex,
+      );
+    },
+  };
+}
+
+/**
+ * Two matrices of the same width read as one, the second below the first.
+ *
+ * It is how a set of samples a model was fitted on and a set placed into it
+ * afterwards reach a plot as one table, without either being copied: the rows
+ * of a projection and the rows of a later projection through the same model
+ * are two separate matrices that everything downstream wants to read as one.
+ * @param top - The upper matrix, whose width the result takes.
+ * @param bottom - The lower matrix; a column it does not reach reads as `NaN`.
+ * @returns The stacked view, holding a reference to both rather than a copy.
+ */
+export function stackedMatrix(top: MatrixLike, bottom: MatrixLike): MatrixLike {
+  const rows = top.rows + bottom.rows;
+  const { columns } = top;
+  return {
+    rows,
+    columns,
+    get(rowIndex: number, columnIndex: number): number {
+      if (rowIndex < 0 || rowIndex >= rows) return Number.NaN;
+      if (columnIndex < 0 || columnIndex >= columns) return Number.NaN;
+      if (rowIndex < top.rows) return top.get(rowIndex, columnIndex);
+      return bottom.get(rowIndex - top.rows, columnIndex);
+    },
+  };
+}

package/src/chart/ui/ChartAxis.tsx

@@ -0,0 +1,232 @@
+import type { ReactElement, SVGProps } from 'react';
+
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+import { chartExponentSuffix } from '../core/chartAxisScale.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartPixel } from '../core/chartScale.ts';
+
+import type { ChartPlotArea } from './ChartFrame.tsx';
+import {
+  CHART_AXIS_LINE_STYLE,
+  CHART_AXIS_TITLE_STYLE,
+  CHART_GRID_STYLE,
+  CHART_TICK_LABEL_INSET,
+  CHART_TICK_LABEL_OFFSET,
+  CHART_TICK_LABEL_STYLE,
+  CHART_TICK_LENGTH,
+  CHART_TICK_MARK_STYLE,
+  CHART_TICK_ROOM,
+  CHART_TITLE_OFFSET,
+  CHART_ZERO_RULE_STYLE,
+} from './chartStyles.ts';
+
+/** What {@link ChartAxis} draws. */
+export interface ChartAxisProps {
+  /** Which edge of the plot the axis is written along. */
+  orientation: 'bottom' | 'left';
+  /** The niced axis, from `chartAxisScale`. */
+  scale: ChartAxisScale;
+  /** Data to pixels along this axis's own direction. */
+  pixels: ChartScale;
+  /** The rectangle the data is drawn in. */
+  plot: ChartPlotArea;
+  /**
+   * What the axis measures, built with `chartAxisTitle`. Whatever power of ten
+   * the labels were divided by is appended here, never by the caller.
+   * @default '' — the axis carries no title
+   */
+  label?: string;
+  /**
+   * Which half is drawn. The two halves straddle the data: a frame draws the
+   * `grid` half before it and the `axis` half after, so a rule never lies over
+   * a mark and a tick is never buried under one.
+   * @default 'both'
+   */
+  layer?: 'grid' | 'axis' | 'both';
+  /**
+   * Whether the plot is ruled at every tick.
+   * @default true
+   */
+  showGrid?: boolean;
+  /**
+   * Whether the tick marks and their labels are drawn.
+   * @default true
+   */
+  showTicks?: boolean;
+}
+
+/**
+ * One axis of a figure: its rules, its line, its ticks and its title.
+ *
+ * A domain that straddles zero always gets a rule there, whatever the grid is
+ * doing, because it is the one line that says which side of nothing a value
+ * fell on — and it is drawn between the grid and the axis in weight so it
+ * reads as a landmark rather than as a second frame.
+ * @param props - See {@link ChartAxisProps}.
+ * @returns The axis.
+ */
+export function ChartAxis(props: ChartAxisProps): ReactElement {
+  const {
+    orientation,
+    scale,
+    pixels,
+    plot,
+    label = '',
+    layer = 'both',
+    showGrid = true,
+    showTicks = true,
+  } = props;
+
+  const horizontal = orientation === 'bottom';
+  const crossesZero = scale.domain[0] < 0 && scale.domain[1] > 0;
+  const title = `${label}${chartExponentSuffix(scale.exponent)}`;
+
+  return (
+    <g className={`chart-axis chart-axis-${orientation}`}>
+      {layer === 'axis'
+        ? null
+        : gridRules(horizontal, scale, pixels, plot, showGrid, crossesZero)}
+      {layer === 'grid'
+        ? null
+        : axisMarks(horizontal, scale, pixels, plot, showTicks, title)}
+    </g>
+  );
+}
+
+function gridRules(
+  horizontal: boolean,
+  scale: ChartAxisScale,
+  pixels: ChartScale,
+  plot: ChartPlotArea,
+  showGrid: boolean,
+  crossesZero: boolean,
+): ReactElement[] {
+  const rules: ReactElement[] = [];
+  if (showGrid) {
+    for (const value of scale.values) {
+      // The zero rule stands in for its own grid line rather than doubling it.
+      if (crossesZero && value === 0) continue;
+      rules.push(
+        <line
+          key={`grid-${value}`}
+          {...ruleGeometry(horizontal, chartPixel(pixels, value), plot)}
+          style={CHART_GRID_STYLE}
+        />,
+      );
+    }
+  }
+  if (crossesZero) {
+    rules.push(
+      <line
+        key="zero"
+        data-chart-rule="zero"
+        {...ruleGeometry(horizontal, chartPixel(pixels, 0), plot)}
+        style={CHART_ZERO_RULE_STYLE}
+      />,
+    );
+  }
+  return rules;
+}
+
+function axisMarks(
+  horizontal: boolean,
+  scale: ChartAxisScale,
+  pixels: ChartScale,
+  plot: ChartPlotArea,
+  showTicks: boolean,
+  title: string,
+): ReactElement[] {
+  const marks: ReactElement[] = [
+    <line
+      key="line"
+      {...(horizontal
+        ? { x1: plot.left, x2: plot.right, y1: plot.bottom, y2: plot.bottom }
+        : { x1: plot.left, x2: plot.left, y1: plot.top, y2: plot.bottom })}
+      style={CHART_AXIS_LINE_STYLE}
+    />,
+  ];
+  if (showTicks) {
+    for (let index = 0; index < scale.values.length; index++) {
+      const value = scale.values[index];
+      const text = scale.labels[index];
+      if (value === undefined || text === undefined) continue;
+      marks.push(tickMark(horizontal, chartPixel(pixels, value), text, plot));
+    }
+  }
+  if (title !== '') marks.push(axisTitle(horizontal, plot, showTicks, title));
+  return marks;
+}
+
+function tickMark(
+  horizontal: boolean,
+  at: number,
+  text: string,
+  plot: ChartPlotArea,
+): ReactElement {
+  const mark = horizontal
+    ? { x1: at, x2: at, y1: plot.bottom, y2: plot.bottom + CHART_TICK_LENGTH }
+    : { x1: plot.left - CHART_TICK_LENGTH, x2: plot.left, y1: at, y2: at };
+  const caption: SVGProps<SVGTextElement> = horizontal
+    ? { x: at, y: plot.bottom + CHART_TICK_LABEL_OFFSET, textAnchor: 'middle' }
+    : {
+        x: plot.left - CHART_TICK_LABEL_INSET,
+        y: at,
+        textAnchor: 'end',
+        dominantBaseline: 'middle',
+      };
+  return (
+    <g key={`tick-${at}`}>
+      <line {...mark} style={CHART_TICK_MARK_STYLE} />
+      <text {...caption} style={CHART_TICK_LABEL_STYLE}>
+        {text}
+      </text>
+    </g>
+  );
+}
+
+function axisTitle(
+  horizontal: boolean,
+  plot: ChartPlotArea,
+  showTicks: boolean,
+  title: string,
+): ReactElement {
+  if (horizontal) {
+    const room = showTicks ? CHART_TICK_ROOM.bottom : 0;
+    return (
+      <text
+        key="title"
+        x={(plot.left + plot.right) / 2}
+        y={plot.bottom + room + CHART_TITLE_OFFSET}
+        textAnchor="middle"
+        style={CHART_AXIS_TITLE_STYLE}
+      >
+        {title}
+      </text>
+    );
+  }
+  const room = showTicks ? CHART_TICK_ROOM.left : 0;
+  const x = plot.left - room - CHART_TICK_LENGTH;
+  const y = (plot.top + plot.bottom) / 2;
+  return (
+    <text
+      key="title"
+      x={x}
+      y={y}
+      textAnchor="middle"
+      transform={`rotate(-90 ${x} ${y})`}
+      style={CHART_AXIS_TITLE_STYLE}
+    >
+      {title}
+    </text>
+  );
+}
+
+function ruleGeometry(
+  horizontal: boolean,
+  at: number,
+  plot: ChartPlotArea,
+): { x1: number; x2: number; y1: number; y2: number } {
+  return horizontal
+    ? { x1: at, x2: at, y1: plot.top, y2: plot.bottom }
+    : { x1: plot.left, x2: plot.right, y1: at, y2: at };
+}

package/src/chart/ui/ChartFrame.tsx

@@ -0,0 +1,246 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useId } from 'react';
+
+import { OverlayLayer } from '../../overlay/ui/OverlayLayer.tsx';
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+import { chartAxisScale } from '../core/chartAxisScale.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartScale } from '../core/chartScale.ts';
+
+import { ChartAxis } from './ChartAxis.tsx';
+import {
+  CHART_SVG_STYLE,
+  chartFrameStyle,
+  chartOuterRoom,
+  chartPlotArea,
+} from './chartStyles.ts';
+
+/** How one axis of a {@link ChartFrame} is drawn. */
+export interface ChartAxisSpec {
+  /** The data range the axis covers, before nicing. */
+  domain: readonly [number, number];
+  /**
+   * The axis title, already carrying its share — build it with
+   * `chartAxisTitle`. Any power of ten the labels were divided by is appended
+   * by the frame itself.
+   * @default undefined — the axis carries no title and its margin shrinks
+   */
+  label?: string;
+  /**
+   * Roughly how many ticks to aim for.
+   * @default 5
+   */
+  tickCount?: number;
+  /**
+   * Whether to rule the plot at every tick.
+   * @default true
+   */
+  showGrid?: boolean;
+  /**
+   * Whether the tick marks and their labels are drawn. An inner cell of a pair
+   * grid turns them off and keeps the grid.
+   * @default true
+   */
+  showTicks?: boolean;
+  /**
+   * Whether the domain is widened outward to whole tick steps.
+   * @default true
+   */
+  nice?: boolean;
+}
+
+/** The rectangle the data is drawn in, in SVG pixels. */
+export interface ChartPlotArea {
+  /** Left edge. */
+  left: number;
+  /** Top edge. */
+  top: number;
+  /** Right edge. */
+  right: number;
+  /** Bottom edge. */
+  bottom: number;
+  /** Width. */
+  width: number;
+  /** Height. */
+  height: number;
+}
+
+/** Room left around the plot, in pixels. */
+export interface ChartMargins {
+  /** Above the plot. */
+  top: number;
+  /** To the right of it. */
+  right: number;
+  /** Below it, where the horizontal axis is written. */
+  bottom: number;
+  /** To its left, where the vertical axis is written. */
+  left: number;
+}
+
+/** What a {@link ChartFrame} hands the function that draws inside it. */
+export interface ChartFrameRender {
+  /** The rectangle to draw in. */
+  plot: ChartPlotArea;
+  /** Data to pixels, horizontally. */
+  x: ChartScale;
+  /** Data to pixels, vertically; its `factor` is negative. */
+  y: ChartScale;
+  /** The horizontal axis as it was niced. */
+  xAxis: ChartAxisScale;
+  /** The vertical axis as it was niced. */
+  yAxis: ChartAxisScale;
+}
+
+/** What {@link ChartFrame} needs. */
+export interface ChartFrameProps {
+  /** Total width, in pixels, normally from `useContainerSize`. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /** The horizontal axis. */
+  x: ChartAxisSpec;
+  /** The vertical axis. */
+  y: ChartAxisSpec;
+  /**
+   * What is drawn inside the plot, clipped to it: marks, outlines, a tracking
+   * rectangle, in the order they should stack.
+   */
+  children: (frame: ChartFrameRender) => ReactNode;
+  /**
+   * What floats over the chart in HTML rather than SVG — an `OverlayBar`, a
+   * legend, a readout. It is wrapped in an `OverlayLayer`, so it is not
+   * clipped, not scaled, and lets every pointer event through except on the
+   * cards themselves.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+  /**
+   * Whether the figure is repainting, which the overlay reads to drop its
+   * backdrop blur for a flat fill while a lasso is being dragged.
+   * @default false
+   */
+  busy?: boolean;
+  /**
+   * What a screen reader is told the chart shows. Without it the chart is
+   * decoration and is hidden from the reader.
+   * @default '' — the chart is hidden from a screen reader
+   */
+  label?: string;
+  /**
+   * Room left around the plot, merged over the defaults — which already shrink
+   * when an axis carries no title.
+   * @default {}
+   */
+  margins?: Partial<ChartMargins>;
+  /**
+   * Value of the `data-testid` attribute of the wrapper, for the end-to-end
+   * tests.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The frame every chart in the family is drawn in: a plot rectangle, two
+ * niced axes, a clip, and a layer of floating chrome over the top.
+ *
+ * The grid goes down before the caller's marks and the axes go over them, so
+ * a rule never crosses a point and a tick is never buried under one. The clip
+ * is keyed on a generated id: two frames on a page would otherwise share one,
+ * and the second would silently steal the first's.
+ * @param props - See {@link ChartFrameProps}.
+ * @returns The chart.
+ */
+export function ChartFrame(props: ChartFrameProps): ReactElement {
+  const {
+    width,
+    height,
+    x,
+    y,
+    children,
+    overlay,
+    busy = false,
+    label = '',
+    margins = {},
+    testId,
+  } = props;
+  const clipId = useId();
+
+  const xAxis = chartAxisScale(x.domain[0], x.domain[1], {
+    count: x.tickCount,
+    nice: x.nice,
+  });
+  const yAxis = chartAxisScale(y.domain[0], y.domain[1], {
+    count: y.tickCount,
+    nice: y.nice,
+  });
+
+  const plot = chartPlotArea(width, height, margins, {
+    bottom: chartOuterRoom('bottom', x, xAxis),
+    left: chartOuterRoom('left', y, yAxis),
+  });
+
+  const horizontal = {
+    orientation: 'bottom',
+    scale: xAxis,
+    pixels: chartScale(xAxis.domain[0], xAxis.domain[1], plot.left, plot.right),
+    plot,
+    label: x.label,
+    showGrid: x.showGrid,
+    showTicks: x.showTicks ?? true,
+  } as const;
+  const vertical = {
+    orientation: 'left',
+    scale: yAxis,
+    pixels: chartScale(yAxis.domain[0], yAxis.domain[1], plot.bottom, plot.top),
+    plot,
+    label: y.label,
+    showGrid: y.showGrid,
+    showTicks: y.showTicks ?? true,
+  } as const;
+  const frame: ChartFrameRender = {
+    plot,
+    x: horizontal.pixels,
+    y: vertical.pixels,
+    xAxis,
+    yAxis,
+  };
+
+  return (
+    <div
+      className="chart-frame"
+      style={chartFrameStyle(width, height)}
+      data-testid={testId}
+    >
+      <svg
+        width={Math.max(0, width)}
+        height={Math.max(0, height)}
+        style={CHART_SVG_STYLE}
+        role={label === '' ? undefined : 'img'}
+        aria-label={label === '' ? undefined : label}
+        aria-hidden={label === '' ? true : undefined}
+      >
+        <defs>
+          <clipPath id={clipId}>
+            <rect
+              x={plot.left}
+              y={plot.top}
+              width={plot.width}
+              height={plot.height}
+            />
+          </clipPath>
+        </defs>
+        <ChartAxis {...horizontal} layer="grid" />
+        <ChartAxis {...vertical} layer="grid" />
+        <g clipPath={`url(#${clipId})`}>{children(frame)}</g>
+        <ChartAxis {...horizontal} layer="axis" />
+        <ChartAxis {...vertical} layer="axis" />
+      </svg>
+      {overlay === undefined ? null : (
+        <OverlayLayer width={width} busy={busy}>
+          {overlay}
+        </OverlayLayer>
+      )}
+    </div>
+  );
+}

package/src/chart/ui/ChartSeriesMarks.tsx

@@ -0,0 +1,98 @@
+/**
+ * One series drawn over a band axis, as a line or as bars from the zero line.
+ *
+ * It is its own module because it is the one part of a band chart that a
+ * caller might reasonably want on its own — a sparkline, a preview inside a
+ * list row — and because the tracking layer beside it is about the pointer
+ * rather than about the data.
+ */
+
+import type { ReactElement } from 'react';
+
+import type { ChartBand } from '../core/chartBand.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+
+import type { ChartSeries } from './TrackedLineChart.tsx';
+
+/** What {@link ChartSeriesMarks} draws. */
+export interface ChartSeriesMarksProps {
+  /** The series to draw. */
+  item: ChartSeries;
+  /** The slots it is drawn over. */
+  band: ChartBand;
+  /** Data to pixels, vertically. */
+  y: ChartScale;
+  /**
+   * Which of the bar series this one is, and how many there are, so that two
+   * of them share a slot side by side instead of one painting over the other.
+   *
+   * Lines ignore it: two lines over one slot are both readable where two bars
+   * from the same baseline are not, and narrowing a line would say nothing.
+   * @default { index: 0, count: 1 } — the series has the slot to itself
+   */
+  lane?: { index: number; count: number };
+}
+
+/**
+ * One series over the band: a line as a single path, or a bar per slot growing
+ * from the zero line in whichever direction its value points. The line is one
+ * `d` string built in an indexed loop rather than an element per point, since
+ * a spectrum is two thousand points and four panels of them as separate
+ * elements is a page that will not scroll.
+ * @param props - See {@link ChartSeriesMarksProps}.
+ * @returns Its marks.
+ */
+export function ChartSeriesMarks(props: ChartSeriesMarksProps): ReactElement {
+  const { item, band, y, lane = SOLE_LANE } = props;
+  const slots = Math.min(band.count, item.values.length);
+  const muted = item.muted === true;
+  const grounded = item.kind === 'bar';
+  const lanes = Math.max(1, lane.count);
+  const wide = round(band.bandWidth / lanes);
+  const shift = band.bandWidth * ((lane.index + 0.5) / lanes - 0.5);
+  const rects: ReactElement[] = [];
+  let path = '';
+  let pen = 'M';
+  for (let index = 0; index < slots; index++) {
+    const value = item.values[index];
+    if (value === undefined || !Number.isFinite(value)) {
+      pen = 'M';
+      continue;
+    }
+    const x = band.offset + band.step * (index + 0.5);
+    const at = y.offset + value * y.factor;
+    if (!grounded) {
+      path += `${pen}${round(x)} ${round(at)}`;
+      pen = 'L';
+      continue;
+    }
+    const near = round(x + shift - band.bandWidth / lanes / 2);
+    const high = round(Math.min(at, y.offset));
+    const tall = round(Math.abs(at - y.offset));
+    rects.push(
+      <rect key={index} x={near} y={high} width={wide} height={tall} />,
+    );
+  }
+  if (grounded) {
+    return (
+      <g data-series={item.id} fill={item.color} opacity={muted ? 0.55 : 1}>
+        {rects}
+      </g>
+    );
+  }
+  return (
+    <path
+      data-series={item.id}
+      d={path}
+      fill="none"
+      stroke={item.color}
+      strokeWidth={muted ? 1 : 1.5}
+      strokeDasharray={muted ? '4 3' : undefined}
+    />
+  );
+}
+
+/** What a series drawn on its own is told, which is that it has the slot. */
+const SOLE_LANE = { index: 0, count: 1 } as const;
+
+const round = (value: number): number => Math.round(value * 100) / 100;