react-cheminfo 0.9.0 → 0.11.0

package/src/scatter/core/polygon.ts

@@ -0,0 +1,155 @@
+import type { PixelBounds, ScreenPoints } from './screenPoints.ts';
+
+/**
+ * Whether a point falls inside a polygon.
+ *
+ * A ray cast from the point towards growing x, counting the edges it crosses:
+ * an odd count is inside, an even one is outside. Both tests that decide a
+ * crossing are half-open, and that is what settles the boundary. An edge is
+ * only considered for the ys it spans from its lower end up to, but not
+ * including, its upper end; and the crossing has to sit strictly beyond the
+ * point. So on the square `(0,0) (10,0) (10,10) (0,10)` the two edges meeting
+ * at `(0,0)` count as inside — `(5,0)` and `(0,5)` are in — while the two
+ * meeting at `(10,10)` count as outside, and `(5,10)` and `(10,5)` are out. Of
+ * the four corners only `(0,0)` is inside; `(10,0)`, `(0,10)` and `(10,10)`
+ * are not.
+ *
+ * The asymmetry is the point of the convention rather than an accident of it:
+ * it is what stops two polygons sharing an edge from both claiming the samples
+ * that lie along it, and what keeps a point from toggling in and out as a
+ * lasso is dragged a hundredth of a pixel.
+ * @param x - Horizontal position of the point, in pixels.
+ * @param y - Vertical position of the point, in pixels.
+ * @param xs - Horizontal position of each vertex, in order around the ring; the ring is closed for you.
+ * @param ys - Vertical position of each vertex, in the same order.
+ * @param vertexCount - How many leading entries of the two arrays are vertices, so that a growing buffer can be passed whole. Their common length when omitted.
+ * @returns Whether the point is inside; always `false` for fewer than three vertices, since nothing thinner than a triangle holds anything.
+ */
+export function pointInPolygon(
+  x: number,
+  y: number,
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+): boolean {
+  const count = usableVertexCount(xs, ys, vertexCount);
+  if (count < 3) return false;
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+
+  let previousX = xs[count - 1];
+  let previousY = ys[count - 1];
+  if (previousX === undefined || previousY === undefined) return false;
+
+  let inside = false;
+  for (let index = 0; index < count; index++) {
+    const currentX = xs[index];
+    const currentY = ys[index];
+    if (currentX === undefined || currentY === undefined) break;
+    if (currentY > y !== previousY > y) {
+      const crossing =
+        ((previousX - currentX) * (y - currentY)) / (previousY - currentY) +
+        currentX;
+      if (x < crossing) inside = !inside;
+    }
+    previousX = currentX;
+    previousY = currentY;
+  }
+  return inside;
+}
+
+/**
+ * The rectangle a polygon's vertices span.
+ * @param xs - Horizontal position of each vertex.
+ * @param ys - Vertical position of each vertex.
+ * @param vertexCount - How many leading entries are vertices. Their common length when omitted.
+ * @returns The rectangle, or `null` when no vertex has two finite coordinates. Vertices that do not are left out rather than poisoning the bounds with a `NaN`.
+ */
+export function polygonBounds(
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+): PixelBounds | null {
+  const count = usableVertexCount(xs, ys, vertexCount);
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let bounded = false;
+  for (let index = 0; index < count; index++) {
+    const vertexX = xs[index];
+    const vertexY = ys[index];
+    if (vertexX === undefined || vertexY === undefined) break;
+    if (!Number.isFinite(vertexX) || !Number.isFinite(vertexY)) continue;
+    if (vertexX < minX) minX = vertexX;
+    if (vertexX > maxX) maxX = vertexX;
+    if (vertexY < minY) minY = vertexY;
+    if (vertexY > maxY) maxY = vertexY;
+    bounded = true;
+  }
+  return bounded ? { minX, minY, maxX, maxY } : null;
+}
+
+/**
+ * Which of many points fall inside a polygon.
+ *
+ * Each point is measured against the polygon's rectangle first, which is four
+ * comparisons and rejects nearly every point of a cloud that a lasso has
+ * enclosed a corner of; only the survivors pay for a walk over every edge. The
+ * saving is the whole reason the prefilter is here: a released lasso has a
+ * vertex for every few pixels the pointer travelled, so the unfiltered cost is
+ * the point count times a few hundred, per drag, on the frame the user is
+ * waiting for.
+ *
+ * Nothing is allocated per point. The rectangle is computed once, the answer
+ * is written into the mask, and the mask itself is reused when the caller
+ * hands one of the right size back.
+ * @param points - Where every point sits on screen.
+ * @param xs - Horizontal position of each vertex.
+ * @param ys - Vertical position of each vertex.
+ * @param vertexCount - How many leading entries are vertices. Their common length when omitted.
+ * @param into - A mask to write into, so a drag does not allocate one per frame. It is used only when it already has one entry per point; otherwise a new one is allocated, because silently answering about a different number of points is worse than the allocation.
+ * @returns One entry per point, `1` for inside and `0` for outside. All zeros for fewer than three vertices.
+ */
+export function pointsInPolygon(
+  points: ScreenPoints,
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+  into?: Uint8Array,
+): Uint8Array {
+  const pointsX = points.x;
+  const pointsY = points.y;
+  const total = Math.min(pointsX.length, pointsY.length);
+  const mask = into?.length === total ? into : new Uint8Array(total);
+
+  const count = usableVertexCount(xs, ys, vertexCount);
+  const bounds = count < 3 ? null : polygonBounds(xs, ys, count);
+  if (bounds === null) {
+    mask.fill(0);
+    return mask;
+  }
+
+  const { minX, minY, maxX, maxY } = bounds;
+  for (let index = 0; index < total; index++) {
+    const pointX = pointsX[index];
+    const pointY = pointsY[index];
+    if (pointX === undefined || pointY === undefined) break;
+    if (pointX < minX || pointX > maxX || pointY < minY || pointY > maxY) {
+      mask[index] = 0;
+      continue;
+    }
+    mask[index] = pointInPolygon(pointX, pointY, xs, ys, count) ? 1 : 0;
+  }
+  return mask;
+}
+
+function usableVertexCount(
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount: number | undefined,
+): number {
+  const available = Math.min(xs.length, ys.length);
+  if (vertexCount === undefined) return available;
+  if (!Number.isFinite(vertexCount)) return 0;
+  return Math.max(0, Math.min(available, Math.floor(vertexCount)));
+}

package/src/scatter/core/scatterSelection.ts

@@ -0,0 +1,88 @@
+/** How a fresh set of hits joins the selection that is already on screen. */
+export type ScatterSelectionMode = 'replace' | 'add' | 'remove';
+
+/**
+ * The selection a gesture leaves behind, from the one before it and its hits.
+ *
+ * The result is always as long as `base`, because that is the cloud's own
+ * length and the only length a selection is meaningful at. A `hits` mask that
+ * is short leaves the points past its end untouched — an honest reading of "no
+ * hit there" — rather than throwing at the end of a drag.
+ *
+ * Every entry written is `0` or `1`, so a mask that has been through this
+ * function can be compared with `toStrictEqual` and handed to a renderer that
+ * only checks for truthiness, whatever the caller filled its input with.
+ * @param base - The selection before the gesture, one entry per point.
+ * @param hits - The points the gesture caught, one entry per point; a non-zero entry is a hit.
+ * @param mode - Whether the hits stand alone, join the selection, or leave it.
+ * @param into - A mask to write into, so a drag does not allocate one per frame. It is used only when it already has one entry per point; otherwise a new one is allocated.
+ * @returns The new selection, one `0` or `1` per point.
+ */
+export function mergeScatterSelection(
+  base: Uint8Array,
+  hits: Uint8Array,
+  mode: ScatterSelectionMode,
+  into?: Uint8Array,
+): Uint8Array {
+  const total = base.length;
+  const merged = into?.length === total ? into : new Uint8Array(total);
+
+  const replacing = mode === 'replace';
+  const removing = mode === 'remove';
+  for (let index = 0; index < total; index++) {
+    const previous = base[index];
+    const hit = hits[index];
+    const wasSelected = previous !== undefined && previous !== 0;
+    const isHit = hit !== undefined && hit !== 0;
+    let selected: boolean;
+    if (replacing) selected = isHit;
+    else if (removing) selected = wasSelected && !isHit;
+    else selected = wasSelected || isHit;
+    merged[index] = selected ? 1 : 0;
+  }
+  return merged;
+}
+
+/**
+ * Which points a mask has selected, as their indices.
+ *
+ * The list is what a caller reports, serialises or hands to a table, so it is
+ * a plain array of numbers and not a third mask; it comes out ascending
+ * because the mask is read in order.
+ * @param mask - One entry per point; a non-zero entry is selected.
+ * @returns The selected indices, ascending.
+ */
+export function scatterSelectedIndices(mask: Uint8Array): number[] {
+  const indices: number[] = [];
+  for (let index = 0; index < mask.length; index++) {
+    const flag = mask[index];
+    if (flag !== undefined && flag !== 0) indices.push(index);
+  }
+  return indices;
+}
+
+/**
+ * A mask over a cloud, from the indices that are selected.
+ *
+ * The inverse of {@link scatterSelectedIndices}, and the door a selection
+ * restored from a URL or a parent component comes in through. An index that is
+ * negative, past the end, or not a whole number is dropped rather than
+ * throwing: those lists arrive from outside, and a stale index in one is a
+ * reason to select one point fewer, not to fail a render.
+ * @param indices - The selected indices, in any order and possibly repeated.
+ * @param count - How many points the cloud holds.
+ * @returns One `0` or `1` per point.
+ */
+export function scatterSelectionMask(
+  indices: Iterable<number>,
+  count: number,
+): Uint8Array {
+  const total = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  const mask = new Uint8Array(total);
+  for (const index of indices) {
+    if (!Number.isInteger(index)) continue;
+    if (index < 0 || index >= total) continue;
+    mask[index] = 1;
+  }
+  return mask;
+}

package/src/scatter/core/screenPoints.ts

@@ -0,0 +1,110 @@
+/**
+ * Where every point sits on screen, as two parallel arrays.
+ *
+ * Parallel typed arrays rather than an array of objects: the hit tests are the
+ * only code that reads them, they read them in index order, and an `{ x, y }`
+ * per point would allocate one object per sample on every relayout.
+ */
+export interface ScreenPoints {
+  /** Horizontal position of each point, in pixels from the plot's left. */
+  x: Float64Array;
+  /** Vertical position of each point, in pixels from the plot's top. */
+  y: Float64Array;
+}
+
+/** The rectangle a set of coordinates spans, in pixels. */
+export interface PixelBounds {
+  /** Smallest horizontal position. */
+  minX: number;
+  /** Smallest vertical position. */
+  minY: number;
+  /** Largest horizontal position. */
+  maxX: number;
+  /** Largest vertical position. */
+  maxY: number;
+}
+
+/**
+ * The point nearest a position, when one is close enough to have been aimed at.
+ *
+ * Distances are compared squared. The caller only ever ranks them, so the
+ * square root would be computed once per point on every pointer move and then
+ * thrown away; a hover test over twenty thousand points is exactly where that
+ * is not affordable.
+ *
+ * A tie goes to the lower index. Two points that land on the same pixel then
+ * resolve the same way twice running, instead of the readout flickering
+ * between them as the pointer jitters.
+ * @param points - Where every point sits on screen.
+ * @param x - Horizontal position to search from, in pixels from the plot's left.
+ * @param y - Vertical position to search from, in pixels from the plot's top.
+ * @param radius - How far from that position to look, in pixels; a point exactly that far away still counts.
+ * @param included - One entry per point, a zero meaning the point cannot be hit. Every point can be hit when it is omitted, and a point past the end of a shorter mask cannot.
+ * @returns The index of the nearest point within the radius, or `-1` when no point is within it.
+ */
+export function nearestPointIndex(
+  points: ScreenPoints,
+  x: number,
+  y: number,
+  radius: number,
+  included?: Uint8Array,
+): number {
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(radius)) {
+    return -1;
+  }
+  const xs = points.x;
+  const ys = points.y;
+  let count = Math.min(xs.length, ys.length);
+  if (included !== undefined) count = Math.min(count, included.length);
+
+  const limit = radius * radius;
+  let nearest = -1;
+  let nearestDistance = 0;
+  for (let index = 0; index < count; index++) {
+    if (included?.[index] === 0) continue;
+    const pointX = xs[index];
+    const pointY = ys[index];
+    if (pointX === undefined || pointY === undefined) break;
+    const deltaX = pointX - x;
+    const deltaY = pointY - y;
+    const distance = deltaX * deltaX + deltaY * deltaY;
+    if (distance > limit) continue;
+    if (nearest === -1 || distance < nearestDistance) {
+      nearest = index;
+      nearestDistance = distance;
+    }
+  }
+  return nearest;
+}
+
+/**
+ * Which points fall inside a rectangle.
+ *
+ * A zoomed plot draws only part of its cloud, and the dots left outside the
+ * frame are clipped rather than dropped: they are still in the coordinate
+ * arrays, still one pixel away from the frame's edge, and still the nearest
+ * point to a pointer resting just inside it. Without this mask a reader
+ * zoomed in on one crowd gets hover cards about samples they cannot see.
+ * @param points - Where every point sits on screen.
+ * @param bounds - The rectangle, normally the plot's own; a point on an edge is inside it.
+ * @param into - A mask to write into, so a resize does not allocate one per frame. It is used only when it already has one entry per point.
+ * @returns One entry per point, `1` for inside.
+ */
+export function pointsWithinBounds(
+  points: ScreenPoints,
+  bounds: PixelBounds,
+  into?: Uint8Array,
+): Uint8Array {
+  const xs = points.x;
+  const ys = points.y;
+  const count = Math.min(xs.length, ys.length);
+  const mask = into?.length === count ? into.fill(0) : new Uint8Array(count);
+  const { minX, minY, maxX, maxY } = bounds;
+  for (let index = 0; index < count; index++) {
+    const x = xs[index] ?? Number.NaN;
+    const y = ys[index] ?? Number.NaN;
+    if (x < minX || x > maxX || y < minY || y > maxY) continue;
+    mask[index] = 1;
+  }
+  return mask;
+}

package/src/scatter/ui/ScatterEllipseLayer.tsx

@@ -0,0 +1,153 @@
+import type { ReactElement } from 'react';
+import { memo, useEffect, useRef } from 'react';
+
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import type { EllipsePoint, EllipseSize } from '../core/confidenceEllipse.ts';
+import { confidenceEllipse } from '../core/confidenceEllipse.ts';
+
+import { scatterOutlineShape } from './scatterOutlineShape.tsx';
+
+/** What {@link ScatterEllipseLayer} needs. */
+export interface ScatterEllipseLayerProps {
+  /** Horizontal coordinate of every point, in data units. */
+  x: ArrayLike<number>;
+  /** Vertical coordinate of every point, in the same order. */
+  y: ArrayLike<number>;
+  /**
+   * Which group each point belongs to, as an index into `colors`. A point with
+   * `-1`, or an index outside the range, is left out of every outline.
+   */
+  groupOf: ArrayLike<number>;
+  /** The colour of each group, in group order. */
+  colors: readonly string[];
+  /** Data to pixels, horizontally. */
+  scaleX: ChartScale;
+  /** Data to pixels, vertically; its `factor` is negative. */
+  scaleY: ChartScale;
+  /**
+   * How much of each group its outline holds.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many points a group needs before it is outlined at all. Below it the
+   * shape says more about the sample than about the group.
+   * @default 3
+   */
+  minimumPoints?: number;
+  /**
+   * How strongly each outline is drawn, in group order.
+   * @default undefined — every outline is drawn at full strength
+   */
+  opacities?: readonly number[];
+  /**
+   * How solid each region is; `0` draws nothing at all, since the fill is the
+   * whole outline. Turn it down when many groups overlap, since the fills
+   * compound.
+   * @default SCATTER_OUTLINE_FILL_OPACITY
+   */
+  fillOpacity?: number;
+  /**
+   * Called with the groups too small to outline, as indices into `colors`,
+   * whenever that set changes. An outline that quietly fails to appear reads
+   * as a bug in the plot, so the caller is handed what its caption has to
+   * account for.
+   * @default undefined
+   */
+  onSkippedGroups?: (groups: readonly number[]) => void;
+}
+
+/**
+ * One outline per group, drawn through both scales.
+ *
+ * The outline is measured in the data's own units and drawn in pixels, and the
+ * two axes almost never carry the same number of units per pixel — so scaling
+ * the two radii and keeping the data-space angle would draw an ellipse of the
+ * wrong shape at the wrong tilt. `scatterOutlineShape` transforms the spread
+ * first and decomposes it after, which is exact on a linear axis.
+ *
+ * The outlines are drawn under the dots, which is what lets the region be
+ * filled at all: the fill says where a group sits without taking the dots the
+ * reader is there to count.
+ * @param props - See {@link ScatterEllipseLayerProps}.
+ * @returns The outlines.
+ */
+export const ScatterEllipseLayer = memo(function ScatterEllipseLayer(
+  props: ScatterEllipseLayerProps,
+): ReactElement {
+  const {
+    x,
+    y,
+    groupOf,
+    colors,
+    scaleX,
+    scaleY,
+    size = DEFAULT_SIZE,
+    minimumPoints = 3,
+    opacities,
+    fillOpacity,
+    onSkippedGroups,
+  } = props;
+
+  const clouds = groupClouds(x, y, groupOf, colors.length);
+  const outlines: ReactElement[] = [];
+  const skipped: number[] = [];
+  for (let group = 0; group < clouds.length; group++) {
+    const color = colors[group];
+    const cloud = clouds[group];
+    if (color === undefined || cloud === undefined) continue;
+    const measured = confidenceEllipse(cloud, { size, minimumPoints });
+    if (measured === null) {
+      skipped.push(group);
+      continue;
+    }
+    const ink = { color, opacity: opacities?.[group], fillOpacity };
+    outlines.push(scatterOutlineShape(group, measured, scaleX, scaleY, ink));
+  }
+
+  useSkippedReport(skipped, onSkippedGroups);
+  return <g data-layer="ellipses">{outlines}</g>;
+});
+
+/** What a group is outlined at when the caller says nothing. */
+const DEFAULT_SIZE: EllipseSize = { kind: 'coverage', probability: 0.95 };
+
+/* Each group's points, gathered once so every group is measured in one pass. */
+function groupClouds(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  groupOf: ArrayLike<number>,
+  groups: number,
+): EllipsePoint[][] {
+  const clouds: EllipsePoint[][] = new Array(groups);
+  for (let group = 0; group < groups; group++) clouds[group] = [];
+  const total = Math.min(x.length, y.length, groupOf.length);
+  for (let index = 0; index < total; index++) {
+    const group = groupOf[index];
+    if (group === undefined || group < 0 || group >= groups) continue;
+    const px = x[index];
+    const py = y[index];
+    if (px === undefined || py === undefined) continue;
+    clouds[group]?.push({ x: px, y: py });
+  }
+  return clouds;
+}
+
+/*
+ * Report the skipped groups once each time the set changes. A fresh array is
+ * built every render, so it is the joined indices that are compared and not
+ * the array, which is what keeps a caller storing the answer from re-rendering
+ * for ever.
+ */
+function useSkippedReport(
+  skipped: readonly number[],
+  report: ((groups: readonly number[]) => void) | undefined,
+): void {
+  const last = useRef('');
+  const key = skipped.join(' ');
+  useEffect(() => {
+    if (last.current === key) return;
+    last.current = key;
+    report?.(skipped);
+  });
+}

package/src/scatter/ui/ScatterLabelLayer.tsx

@@ -0,0 +1,135 @@
+import type { ReactElement } from 'react';
+import { memo } from 'react';
+
+import {
+  SCATTER_GROUP_LABEL_SIZE,
+  SCATTER_LABEL_SIZE,
+} from './scatterLabelBoxes.ts';
+import type { PlacedScatterLabel } from './scatterLabelPlacement.ts';
+
+/** What {@link ScatterLabelLayer} draws. */
+export interface ScatterLabelLayerProps {
+  /** The words and where they go, from `placeScatterLabels`. */
+  labels: readonly PlacedScatterLabel[];
+  /**
+   * Radius of the dot a label stands beside, which a line back to it starts
+   * clear of.
+   * @default 3.5
+   */
+  radius?: number;
+  /**
+   * Whether the words are set in the heavier weight, for a group's name over
+   * its own crowd rather than a sample's name beside one dot.
+   * @default false
+   */
+  strong?: boolean;
+}
+
+/**
+ * The words written on a cloud of points.
+ *
+ * Every label is drawn twice over: once in the page's own background as a
+ * thick stroke and once in its colour as a fill. Without that halo a name
+ * landing on a crowd of dots is unreadable exactly where a reader most wants
+ * to read it, and the alternatives — a solid box behind each word, or moving
+ * the words off the data — either hide the dots the label is about or break
+ * the link between the two.
+ *
+ * A word that had to be pushed clear of another word gets a thin line back to
+ * what it names; the lines are drawn first so every halo cuts through them,
+ * which is what keeps a line from striking through the word it arrives at.
+ *
+ * The layer carries no event handler and no state, like every other layer of
+ * the plot: the gestures land on one transparent rectangle above it.
+ * @param props - See {@link ScatterLabelLayerProps}.
+ * @returns The words.
+ */
+export const ScatterLabelLayer = memo(function ScatterLabelLayer(
+  props: ScatterLabelLayerProps,
+): ReactElement {
+  const { labels, radius = 3.5, strong = false } = props;
+
+  const lines: ReactElement[] = [];
+  const written: ReactElement[] = [];
+  for (let index = 0; index < labels.length; index++) {
+    const label = labels[index];
+    if (label === undefined) continue;
+    const leader = label.leader;
+    if (leader !== undefined) {
+      const across = leader.x - label.x;
+      const down = leader.y - label.y;
+      const away = Math.hypot(across, down);
+      const start = Math.min((radius + LEADER_GAP) / away, 1);
+      lines.push(
+        <line
+          key={index}
+          x1={round(label.x + across * start)}
+          y1={round(label.y + down * start)}
+          x2={round(leader.x)}
+          y2={round(leader.y)}
+          stroke={label.color}
+          {...LEADER_STYLE}
+        />,
+      );
+    }
+    written.push(
+      <text
+        key={index}
+        x={round(label.textX)}
+        y={round(label.textY)}
+        fill={label.color}
+        textAnchor={label.anchor}
+        dominantBaseline="middle"
+        style={strong ? STRONG_LABEL_STYLE : LABEL_STYLE}
+      >
+        {label.text}
+      </text>,
+    );
+  }
+
+  return (
+    <g data-layer="labels" paintOrder="stroke" stroke="var(--surface)">
+      {lines}
+      {written}
+    </g>
+  );
+});
+
+/** How far a line back to a dot starts clear of that dot. */
+const LEADER_GAP = 2;
+
+/**
+ * The line from a word to what it names. Thin and faint: it is a pointer and
+ * not a reading, and drawn at full strength forty of them read as data.
+ */
+const LEADER_STYLE = {
+  strokeWidth: 0.75,
+  strokeOpacity: 0.55,
+  fill: 'none',
+} as const;
+
+/**
+ * A sample's own name. Small, because there is one per dot and the map is the
+ * thing being read; the halo is what makes it legible rather than the size.
+ */
+const LABEL_STYLE = {
+  fontSize: SCATTER_LABEL_SIZE,
+  strokeWidth: 3,
+  strokeLinejoin: 'round',
+  userSelect: 'none',
+} as const;
+
+/** A group's name, which stands over a crowd and has to win against it. */
+const STRONG_LABEL_STYLE = {
+  fontSize: SCATTER_GROUP_LABEL_SIZE,
+  fontWeight: 600,
+  strokeWidth: 3.5,
+  strokeLinejoin: 'round',
+  userSelect: 'none',
+} as const;
+
+/*
+ * Two decimals, which 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.
+ */
+const round = (value: number): number => Math.round(value * 100) / 100;