react-cheminfo 0.10.0 → 0.12.0

package/src/capsule/ui/CapsuleFilter.tsx

@@ -2,6 +2,9 @@ import type { Intent } from '@blueprintjs/core';
 import { Tag } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 
+import { formatInteger } from '../../format/core/numbers.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
 /** One capsule of a {@link CapsuleFilter} row. */
 export interface CapsuleOption<TValue extends string = string> {
   /** What picking this capsule selects. */
@@ -26,14 +29,26 @@ export interface CapsuleOption<TValue extends string = string> {
   title?: string;
 }
 
-/** What a row of filter capsules needs. */
-export interface CapsuleFilterProps<TValue extends string = string> {
+/** The capsule drawn first in a multiple row, which clears the selection. */
+export interface CapsuleAllOption {
+  /** What the capsule reads, e.g. `all types`. */
+  label: string;
+  /**
+   * How many rows an empty selection keeps, written after the label.
+   * @default undefined — the capsule carries no count
+   */
+  count?: number;
+  /**
+   * What the pointer is told when it rests on the capsule.
+   * @default undefined
+   */
+  title?: string;
+}
+
+/** What every row of filter capsules needs, whatever it selects. */
+export interface CapsuleFilterBaseProps<TValue extends string = string> {
   /** One entry per capsule, in the order they are drawn. */
   options: ReadonlyArray<CapsuleOption<TValue>>;
-  /** The selected capsule. */
-  value: TValue;
-  /** Called with the newly picked value. */
-  onChange: (value: TValue) => void;
   /**
    * What the group is called, for a screen reader reaching the row.
    * @default 'Filter'
@@ -41,7 +56,7 @@ export interface CapsuleFilterProps<TValue extends string = string> {
   label?: string;
   /**
    * How a count is written.
-   * @default the number in the reader's locale, e.g. `1,204`
+   * @default formatInteger — grouped in thousands, e.g. `1,204`
    */
   formatCount?: (count: number) => string;
   /**
@@ -51,8 +66,45 @@ export interface CapsuleFilterProps<TValue extends string = string> {
   className?: string;
 }
 
+/** A row where exactly one capsule is selected. */
+export interface SingleCapsuleFilterProps<
+  TValue extends string = string,
+> extends CapsuleFilterBaseProps<TValue> {
+  /**
+   * Whether several capsules may be selected at once.
+   * @default false
+   */
+  multiple?: false;
+  /** The selected capsule. */
+  value: TValue;
+  /** Called with the newly picked value. */
+  onChange: (value: TValue) => void;
+}
+
+/** A row where any number of capsules is selected, none meaning all of them. */
+export interface MultipleCapsuleFilterProps<
+  TValue extends string = string,
+> extends CapsuleFilterBaseProps<TValue> {
+  /** Whether several capsules may be selected at once. */
+  multiple: true;
+  /** The selected capsules; an empty selection keeps every row. */
+  values: readonly TValue[];
+  /** Called with the new selection, in the order of `options`. */
+  onChange: (values: TValue[]) => void;
+  /**
+   * The capsule that clears the selection, filled while nothing is selected.
+   * @default undefined — the row has no reset capsule
+   */
+  allOption?: CapsuleAllOption;
+}
+
+/** What a row of filter capsules needs: one selected capsule, or several. */
+export type CapsuleFilterProps<TValue extends string = string> =
+  SingleCapsuleFilterProps<TValue> | MultipleCapsuleFilterProps<TValue>;
+
 /**
- * The row of capsules that narrows a table to one outcome.
+ * The row of capsules that narrows a table to one outcome, or with `multiple`
+ * to any set of them.
  *
  * Every capsule keeps its semantic colour whether or not it is selected, so
  * what a status means stays learnable — the filled shape is what encodes the
@@ -64,51 +116,124 @@ export interface CapsuleFilterProps<TValue extends string = string> {
 export function CapsuleFilter<TValue extends string = string>(
   props: CapsuleFilterProps<TValue>,
 ): ReactElement {
-  const {
-    options,
-    value,
-    onChange,
-    label = 'Filter',
-    formatCount = defaultFormatCount,
-    className,
-  } = props;
+  const capsules =
+    props.multiple === true ? multipleCapsules(props) : singleCapsules(props);
+  const { label = 'Filter', className } = props;
 
   return (
     <div
       role="group"
       aria-label={label}
-      className={
-        className === undefined
-          ? 'capsule-filter'
-          : `capsule-filter ${className}`
-      }
+      className={joinClassNames('capsule-filter', className)}
       style={ROW_STYLE}
     >
-      {options.map((option) => {
-        const selected = option.value === value;
-        return (
-          <Tag
-            key={option.value}
-            interactive
-            round
-            minimal={!selected}
-            intent={option.intent}
-            aria-pressed={selected}
-            htmlTitle={option.title}
-            onClick={() => onChange(option.value)}
-          >
-            {option.count === undefined
-              ? option.label
-              : `${option.label} (${formatCount(option.count)})`}
-          </Tag>
-        );
-      })}
+      {capsules}
     </div>
   );
 }
 
-function defaultFormatCount(count: number): string {
-  return count.toLocaleString();
+function singleCapsules<TValue extends string>(
+  props: SingleCapsuleFilterProps<TValue>,
+): ReactElement[] {
+  const { options, value, onChange, formatCount = formatInteger } = props;
+  const capsules: ReactElement[] = [];
+  for (const option of options) {
+    capsules.push(
+      <Capsule
+        key={`option:${option.value}`}
+        text={capsuleText(option, formatCount)}
+        selected={option.value === value}
+        intent={option.intent}
+        title={option.title}
+        onClick={() => onChange(option.value)}
+      />,
+    );
+  }
+  return capsules;
+}
+
+function multipleCapsules<TValue extends string>(
+  props: MultipleCapsuleFilterProps<TValue>,
+): ReactElement[] {
+  const {
+    options,
+    values,
+    onChange,
+    allOption,
+    formatCount = formatInteger,
+  } = props;
+  const capsules: ReactElement[] = [];
+  if (allOption !== undefined) {
+    capsules.push(
+      <Capsule
+        key="all"
+        text={capsuleText(allOption, formatCount)}
+        selected={values.length === 0}
+        title={allOption.title}
+        onClick={() => onChange([])}
+      />,
+    );
+  }
+  for (const option of options) {
+    capsules.push(
+      <Capsule
+        key={`option:${option.value}`}
+        text={capsuleText(option, formatCount)}
+        selected={values.includes(option.value)}
+        intent={option.intent}
+        title={option.title}
+        onClick={() => onChange(toggled(options, values, option.value))}
+      />,
+    );
+  }
+  return capsules;
+}
+
+interface CapsuleProps {
+  text: string;
+  selected: boolean;
+  intent?: Intent;
+  title: string | undefined;
+  onClick: () => void;
+}
+
+function Capsule(props: CapsuleProps): ReactElement {
+  const { text, selected, intent, title, onClick } = props;
+  return (
+    <Tag
+      interactive
+      round
+      minimal={!selected}
+      intent={intent}
+      aria-pressed={selected}
+      htmlTitle={title}
+      onClick={onClick}
+    >
+      {text}
+    </Tag>
+  );
+}
+
+function capsuleText(
+  capsule: { label: string; count?: number },
+  formatCount: (count: number) => string,
+): string {
+  return capsule.count === undefined
+    ? capsule.label
+    : `${capsule.label} (${formatCount(capsule.count)})`;
+}
+
+function toggled<TValue extends string>(
+  options: ReadonlyArray<CapsuleOption<TValue>>,
+  values: readonly TValue[],
+  flipped: TValue,
+): TValue[] {
+  const next: TValue[] = [];
+  for (const option of options) {
+    const kept = values.includes(option.value);
+    if (option.value === flipped ? !kept : kept) next.push(option.value);
+  }
+  return next;
 }
 
 const ROW_STYLE = {

package/src/capsule/ui/index.ts

@@ -1,2 +1,9 @@
-export type { CapsuleFilterProps, CapsuleOption } from './CapsuleFilter.tsx';
+export type {
+  CapsuleAllOption,
+  CapsuleFilterBaseProps,
+  CapsuleFilterProps,
+  CapsuleOption,
+  MultipleCapsuleFilterProps,
+  SingleCapsuleFilterProps,
+} from './CapsuleFilter.tsx';
 export { CapsuleFilter } from './CapsuleFilter.tsx';

package/src/chart/core/chartAxisPair.ts

@@ -0,0 +1,47 @@
+import { clamp } from '../../format/core/clamp.ts';
+
+/** The two axes a flat figure is drawn against, counting from zero. */
+interface ChartAxisPair {
+  /** The axis along x. */
+  x: number;
+  /** The axis along y. */
+  y: number;
+}
+
+/**
+ * An axis index brought inside the axes that exist.
+ *
+ * A fraction is floored and anything that is not a number lands on the first
+ * axis, so a saved index resolves to the same axis in every figure that reads
+ * it.
+ * @param index - The axis asked for.
+ * @param last - The highest axis there is.
+ * @returns A whole number between zero and `last`.
+ */
+export function clampAxisIndex(index: number, last: number): number {
+  return Math.floor(clamp(index, 0, last));
+}
+
+/**
+ * A pair of axes made safe against the axes that were actually computed.
+ *
+ * A saved pair outlives the data it was made on: reload with fewer columns and
+ * axis eight no longer exists. Both axes are pulled back inside what exists,
+ * and kept apart, because one axis drawn against itself is a diagonal line
+ * that says nothing at all.
+ * @param x - The axis asked for along x.
+ * @param y - The axis asked for along y.
+ * @param count - How many axes there are.
+ * @returns Two axes that exist, and differ whenever there are two to pick from.
+ */
+export function clampAxisPair(
+  x: number,
+  y: number,
+  count: number,
+): ChartAxisPair {
+  const last = Math.max(0, count - 1);
+  const along = clampAxisIndex(x, last);
+  const up = clampAxisIndex(y, last);
+  if (up !== along) return { x: along, y: up };
+  return { x: along, y: along > 0 ? along - 1 : Math.min(1, last) };
+}

package/src/chart/core/chartAxisScale.ts

@@ -1,4 +1,6 @@
+import { clamp } from '../../format/core/clamp.ts';
 import { formatDecimal } from '../../format/core/numbers.ts';
+import { formatSuperscript } from '../../format/core/superscript.ts';
 
 const DEFAULT_COUNT = 5;
 const MAXIMUM_COUNT = 100;
@@ -7,7 +9,6 @@ const NICE_PASSES = 8;
 const ZERO_WIDTH_SHARE = 0.05;
 const ZERO_WIDTH_FALLBACK = 1;
 const COMFORTABLE_LABEL = 6;
-const SUPERSCRIPT_DIGITS = '⁰¹²³⁴⁵⁶⁷⁸⁹';
 const STEP_10 = Math.sqrt(50);
 const STEP_5 = Math.sqrt(10);
 const STEP_2 = Math.SQRT2;
@@ -157,11 +158,7 @@ export function chartExponentSuffix(exponent: number): string {
   if (!Number.isFinite(exponent)) return '';
   const whole = Math.trunc(exponent);
   if (whole === 0) return '';
-  const sign = whole < 0 ? '⁻' : '';
-  const digits = Math.abs(whole)
-    .toString()
-    .replaceAll(/\d/gu, (digit) => SUPERSCRIPT_DIGITS.charAt(Number(digit)));
-  return ` (×10${sign}${digits})`;
+  return ` (×10${formatSuperscript(whole)})`;
 }
 
 type TickSpec = [first: number, last: number, increment: number];
@@ -231,8 +228,7 @@ function decimalExponent(value: number): number {
 }
 
 function tickCount(count: number): number {
-  if (!Number.isFinite(count)) return DEFAULT_COUNT;
-  return Math.min(MAXIMUM_COUNT, Math.max(1, Math.floor(count)));
+  return Math.floor(clamp(count, 1, MAXIMUM_COUNT, DEFAULT_COUNT));
 }
 
 function openDomain(min: number, max: number): [number, number] {

package/src/chart/core/chartBins.ts

@@ -1,4 +1,5 @@
 import type { ChartExtent } from './chartExtent.ts';
+import { chartGroupIndex } from './chartGroups.ts';
 import type { MatrixLike } from './matrix.ts';
 
 /** Counts over one shared set of bin edges, optionally split by series. */
@@ -87,10 +88,5 @@ function groupOf(
   row: number,
   seriesCount: number,
 ): number {
-  if (groups === null) return 0;
-  const raw = groups[row];
-  if (raw === undefined || !Number.isFinite(raw)) return -1;
-  const group = Math.trunc(raw);
-  if (group < 0 || group >= seriesCount) return -1;
-  return group;
+  return groups === null ? 0 : chartGroupIndex(groups, row, seriesCount);
 }

package/src/chart/core/chartGroups.ts

@@ -0,0 +1,24 @@
+/**
+ * Which group a row belongs to, read the one way every figure reads it.
+ *
+ * A group index arrives as whatever the caller had: an `Int32Array` padded
+ * with `-1`, a `Float64Array` padded with `NaN` for the rows nobody assigned,
+ * or a plain array of classes. Every layer that colours, counts or outlines by
+ * group asks the same question of it, so the answer lives here once — a map
+ * and a cloud that disagreed about which group row 12 is in would draw the
+ * same sample in two colours.
+ * @param groupOf - Which group each row belongs to, as an index into the groups.
+ * @param row - Which row to read.
+ * @param groups - How many groups there are.
+ * @returns The group, truncated to a whole index, or `-1` when the entry is missing, not finite, or outside `0..groups - 1`.
+ */
+export function chartGroupIndex(
+  groupOf: ArrayLike<number> | undefined,
+  row: number,
+  groups: number,
+): number {
+  const raw = groupOf?.[row];
+  if (raw === undefined || !Number.isFinite(raw)) return -1;
+  const group = Math.trunc(raw);
+  return group < 0 || group >= groups ? -1 : group;
+}

package/src/chart/core/chartLabels.ts

@@ -1,3 +1,5 @@
+import { formatDecimal, formatPercent } from '../../format/core/numbers.ts';
+
 /** How an axis title is written. */
 export interface ChartAxisTitleOptions {
   /**
@@ -39,7 +41,7 @@ export function chartAxisTitle(
 ): string {
   const { share, digits = DEFAULT_DIGITS } = options;
   if (share === undefined || !Number.isFinite(share)) return name;
-  return `${name} — ${chartShare(share, digits)} %`;
+  return `${name} — ${formatPercent(share, digits)}`;
 }
 
 /**
@@ -56,13 +58,7 @@ export function chartAxisTitle(
  */
 export function chartShare(share: number, digits = DEFAULT_DIGITS): string {
   if (!Number.isFinite(share)) return '';
-  return (share * 100).toFixed(readableDigits(digits));
+  return formatDecimal(share * 100, Number.isFinite(digits) ? digits : 1);
 }
 
 const DEFAULT_DIGITS = 1;
-const MOST_DIGITS = 20;
-
-function readableDigits(digits: number): number {
-  if (!Number.isFinite(digits)) return DEFAULT_DIGITS;
-  return Math.min(MOST_DIGITS, Math.max(0, Math.floor(digits)));
-}

package/src/chart/core/chartPalette.ts

@@ -3,15 +3,18 @@
  * read from.
  *
  * - `group` — a species, a batch, a cluster: something a sample belongs to.
- * - `component` — an axis of the embedding: PC 1, PC 2.
+ * - `component` — an axis of the embedding: PC1, PC2.
  *
  * The two roles read the palette in different orders, so that the first four
  * groups and the first four components never share a hue. That is what stops a
- * reader who learnt "blue is setosa" on one tab from reading "blue is PC 1"
+ * reader who learnt "blue is setosa" on one tab from reading "blue is PC1"
  * on the next as though it meant the same thing.
  */
 export type ChartColorRole = 'group' | 'component';
 
+/** The blue a first group takes, and the answer when the palette is read past its end. */
+const FIRST_SERIES_COLOR = '#0072b2';
+
 /**
  * Eight hues that stay apart under deuteranopia, protanopia and tritanopia,
  * and that keep their order when a figure is printed in grey.
@@ -21,7 +24,7 @@ export type ChartColorRole = 'group' | 'component';
  * the eighth is a neutral dark, for the series past the ones anybody reads.
  */
 export const CHART_SERIES_COLORS: readonly string[] = [
-  '#0072b2', // blue
+  FIRST_SERIES_COLOR, // blue
   '#d55e00', // vermillion
   '#009e73', // bluish green
   '#cc79a7', // reddish purple
@@ -47,7 +50,7 @@ export function chartSeriesColor(
   const order = role === 'component' ? COMPONENT_ORDER : GROUP_ORDER;
   const step = Number.isFinite(index) && index > 0 ? Math.floor(index) : 0;
   const position = order[step % order.length] ?? 0;
-  return CHART_SERIES_COLORS[position] ?? DEFAULT_SERIES_COLOR;
+  return CHART_SERIES_COLORS[position] ?? FIRST_SERIES_COLOR;
 }
 
 /**
@@ -66,6 +69,3 @@ const GROUP_ORDER: readonly number[] = [0, 1, 2, 3, 6, 7, 4, 5];
  * entered from the two the groups leave alone longest, orange and sky blue.
  */
 const COMPONENT_ORDER: readonly number[] = [4, 5, 7, 6, 0, 1, 2, 3];
-
-/** The blue a first group takes, and the answer when the palette is read past its end. */
-const DEFAULT_SERIES_COLOR = '#0072b2';

package/src/chart/core/chartScale.ts

@@ -1,3 +1,5 @@
+import { roundTo } from '../../format/core/roundTo.ts';
+
 /**
  * A data-to-pixel mapping, held as the two numbers a multiply-add needs.
  *
@@ -70,3 +72,18 @@ export function chartValue(scale: ChartScale, pixel: number): number {
   const value = (pixel - scale.offset) / scale.factor;
   return value === 0 ? 0 : value;
 }
+
+/**
+ * A pixel coordinate rounded for the markup.
+ *
+ * Two decimals is under a tenth of a device pixel at any zoom a browser offers
+ * and keeps the markup short enough to read in a failing test. One decimal is
+ * for a mark written thousands of times into one `d` — a lasso, a stick chart,
+ * the dots of a pair grid — where the string length is the cost.
+ * @param value - The coordinate, in pixels.
+ * @param decimals - How many decimals to keep: `2` for a mark, `1` for a dense path.
+ * @returns The rounded coordinate.
+ */
+export function chartRoundPixel(value: number, decimals: 1 | 2 = 2): number {
+  return roundTo(value, decimals);
+}

package/src/chart/core/matrix.ts

@@ -45,6 +45,30 @@ export function rowMatrix(rows: ReadonlyArray<ArrayLike<number>>): MatrixLike {
   };
 }
 
+/**
+ * Parallel columns read as a matrix, one column per array.
+ *
+ * How a figure holding its coordinates as separate `x` and `y` runs hands them
+ * to anything that reads a matrix, without zipping them into rows first.
+ * @param columns - One array per column, in column order.
+ * @returns The matrix view, as many rows as the shortest column holds.
+ */
+export function columnMatrix(
+  columns: ReadonlyArray<ArrayLike<number>>,
+): MatrixLike {
+  let rows = columns.length === 0 ? 0 : Number.POSITIVE_INFINITY;
+  for (const column of columns) rows = Math.min(rows, column.length);
+  return {
+    rows,
+    columns: columns.length,
+    get(rowIndex: number, columnIndex: number): number {
+      if (rowIndex < 0 || rowIndex >= rows) return Number.NaN;
+      const value = columns[columnIndex]?.[rowIndex];
+      return value === undefined ? Number.NaN : value;
+    },
+  };
+}
+
 /**
  * A matrix whose values pass through a function on the way out.
  *

package/src/chart/ui/ChartAxis.tsx

@@ -150,7 +150,9 @@ function axisMarks(
       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));
+      marks.push(
+        tickMark(horizontal, value, chartPixel(pixels, value), text, plot),
+      );
     }
   }
   if (title !== '') marks.push(axisTitle(horizontal, plot, showTicks, title));
@@ -159,6 +161,7 @@ function axisMarks(
 
 function tickMark(
   horizontal: boolean,
+  value: number,
   at: number,
   text: string,
   plot: ChartPlotArea,
@@ -175,7 +178,7 @@ function tickMark(
         dominantBaseline: 'middle',
       };
   return (
-    <g key={`tick-${at}`}>
+    <g key={`tick-${value}`}>
       <line {...mark} style={CHART_TICK_MARK_STYLE} />
       <text {...caption} style={CHART_TICK_LABEL_STYLE}>
         {text}

package/src/chart/ui/ChartFrame.tsx

@@ -2,18 +2,13 @@ import type { ReactElement, ReactNode } from 'react';
 import { useId } from 'react';
 
 import { OverlayLayer } from '../../overlay/ui/OverlayLayer.tsx';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 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';
+import { chartFrameGeometry } from './chartFrameGeometry.ts';
+import { CHART_SVG_STYLE, chartFrameStyle } from './chartStyles.ts';
 
 /** How one axis of a {@link ChartFrame} is drawn. */
 export interface ChartAxisSpec {
@@ -132,6 +127,18 @@ export interface ChartFrameProps {
    * @default {}
    */
   margins?: Partial<ChartMargins>;
+  /**
+   * The plot rectangle and mappings, already worked out by
+   * `chartFrameGeometry` from the same size, axes and margins — for a figure
+   * that needed them before it rendered.
+   * @default undefined — the frame works them out itself
+   */
+  geometry?: ChartFrameRender;
+  /**
+   * A class added to the wrapper, for a site placing the figure.
+   * @default undefined
+   */
+  className?: string;
   /**
    * Value of the `data-testid` attribute of the wrapper, for the end-to-end
    * tests.
@@ -162,28 +169,19 @@ export function ChartFrame(props: ChartFrameProps): ReactElement {
     busy = false,
     label = '',
     margins = {},
+    geometry,
+    className,
     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 frame = geometry ?? chartFrameGeometry(width, height, x, y, margins);
+  const { plot, xAxis, yAxis, x: xPixels, y: yPixels } = frame;
 
   const horizontal = {
     orientation: 'bottom',
     scale: xAxis,
-    pixels: chartScale(xAxis.domain[0], xAxis.domain[1], plot.left, plot.right),
+    pixels: xPixels,
     plot,
     label: x.label,
     showGrid: x.showGrid,
@@ -192,23 +190,16 @@ export function ChartFrame(props: ChartFrameProps): ReactElement {
   const vertical = {
     orientation: 'left',
     scale: yAxis,
-    pixels: chartScale(yAxis.domain[0], yAxis.domain[1], plot.bottom, plot.top),
+    pixels: yPixels,
     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"
+      className={joinClassNames('chart-frame', className)}
       style={chartFrameStyle(width, height)}
       data-testid={testId}
     >