react-cheminfo 0.9.0 → 0.10.0

package/src/scatter/ui/scatterLabelPlacement.ts

@@ -0,0 +1,325 @@
+/**
+ * Where a word actually goes once the words beside it are taken into account.
+ *
+ * A name written at the thing it names is right until two things are close
+ * together, and then both names are wrong: a map of forty groups whose crowds
+ * overlap writes forty names on top of each other and a reader can read none
+ * of them — the label layer's halo makes one word legible over dots, never
+ * over another word.
+ *
+ * So the words are placed one at a time, best first: each takes the nearest
+ * free seat around what it names, and a word that finds no seat within reach
+ * is not written at all. Dropping is the point rather than a failure. Twelve
+ * readable names beat forty unreadable ones, the twelve are the ones that
+ * speak for the most samples, and the crowded name is still one hover away.
+ *
+ * It is arithmetic over pixels, so it sits beside the layer that draws it and
+ * can be checked without rendering anything.
+ */
+
+import type { LabelBox } from './scatterLabelBoxes.ts';
+import {
+  LabelBoxField,
+  labelBoxHeight,
+  labelBoxWidth,
+} from './scatterLabelBoxes.ts';
+import type { ScatterPixelLabel } from './scatterLabels.ts';
+
+/** One word, with the seat it was given. */
+export interface PlacedScatterLabel extends ScatterPixelLabel {
+  /** Where the word itself is written, which is no longer where its subject is. */
+  textX: number;
+  /** The vertical middle of the word. */
+  textY: number;
+  /** Which end of the word sits at `textX`. */
+  anchor: 'start' | 'middle' | 'end';
+  /**
+   * Where a line drawn back to what the word names should reach it — the point
+   * of the word's own rectangle nearest its subject. Left out when the word is
+   * beside its subject already and a line would be clutter.
+   * @default undefined — no line is drawn
+   */
+  leader?: { x: number; y: number };
+}
+
+/** How {@link placeScatterLabels} seats the words. */
+export interface ScatterLabelPlacementOptions {
+  /**
+   * What the words are set in, in pixels — the same number the layer draws
+   * them at, or the room kept for them is the wrong size.
+   * @default 10
+   */
+  fontSize?: number;
+  /**
+   * Whether they are set in the heavier weight, which is wider.
+   * @default false
+   */
+  bold?: boolean;
+  /**
+   * Whether a word wants to sit over the middle of what it names rather than
+   * out to its right — which is what a group's name over its own crowd wants.
+   * @default false
+   */
+  centered?: boolean;
+  /**
+   * Radius of the dot a word stands beside, which is what its first seat
+   * clears.
+   * @default 3.5
+   */
+  radius?: number;
+  /**
+   * How far a word may be moved from what it names, in pixels. Past this it is
+   * dropped instead: a name floating eighty pixels from its dot in a crowded
+   * map names whatever the reader guesses it does.
+   * @default 40
+   */
+  shift?: number;
+  /**
+   * The rectangle words have to stay inside — the plot area, so a name never
+   * hangs over an axis or off the figure.
+   * @default undefined — words may go anywhere
+   */
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+/**
+ * The words that fit, each in its seat.
+ *
+ * Order of service is the weight a label carries — the size of the crowd a
+ * group's name speaks for — and then the order they came in, so the same map
+ * seats the same words every render and a name does not flicker between two
+ * places as the pointer moves.
+ * @param labels - The words and what they name, from `scatterPointLabels` or
+ * `scatterGroupLabels`.
+ * @param options - See {@link ScatterLabelPlacementOptions}.
+ * @returns The words that found room, in the order they were given.
+ */
+export function placeScatterLabels(
+  labels: readonly ScatterPixelLabel[],
+  options: ScatterLabelPlacementOptions = {},
+): PlacedScatterLabel[] {
+  const { fontSize = 10, bold = false, centered = false } = options;
+  const { radius = 3.5, shift = DEFAULT_SHIFT, bounds } = options;
+
+  const height = labelBoxHeight(fontSize);
+  const field = new LabelBoxField();
+  const seated = new Array<PlacedScatterLabel | undefined>(labels.length);
+  const order = placementOrder(labels);
+
+  for (const index of order) {
+    const label = labels[index];
+    if (label === undefined) continue;
+    const width = labelBoxWidth(label.text, fontSize, bold);
+    const box = freeSeat(label, width, height, {
+      radius,
+      centered,
+      shift,
+      bounds,
+      field,
+    });
+    if (box === undefined) continue;
+    field.add(box);
+    seated[index] = { ...label, ...written(box, label, radius) };
+  }
+
+  const placed: PlacedScatterLabel[] = [];
+  for (const label of seated) {
+    if (label !== undefined) placed.push(label);
+  }
+  return placed;
+}
+
+/** What {@link freeSeat} needs beyond the word itself. */
+interface SeatSearch {
+  radius: number;
+  centered: boolean;
+  shift: number;
+  bounds: ScatterLabelPlacementOptions['bounds'];
+  field: LabelBoxField;
+}
+
+/**
+ * The nearest place this word can go without landing on one already written,
+ * or `undefined` when there is none within reach.
+ * @param label - The word and what it names.
+ * @param width - How wide it will be drawn, in pixels.
+ * @param height - How tall.
+ * @param search - See {@link SeatSearch}.
+ * @returns The rectangle it takes, or nothing when none is free.
+ */
+function freeSeat(
+  label: ScatterPixelLabel,
+  width: number,
+  height: number,
+  search: SeatSearch,
+): LabelBox | undefined {
+  const { radius, centered, shift, bounds, field } = search;
+  const clear = radius + SEAT_GAP;
+  const near: LabelBox[] = centered
+    ? [box(label.x, label.y, width, height)]
+    : [];
+  near.push(
+    box(label.x + clear + width / 2, label.y, width, height),
+    box(label.x - clear - width / 2, label.y, width, height),
+    box(label.x, label.y - clear - height / 2, width, height),
+    box(label.x, label.y + clear + height / 2, width, height),
+  );
+  for (const seat of near) {
+    if (free(seat, bounds, field)) return seat;
+  }
+
+  for (let step = SEAT_STEP; step <= shift; step += SEAT_STEP) {
+    for (let index = 0; index < SEAT_DIRECTIONS.length; index += 2) {
+      const across = SEAT_DIRECTIONS[index] ?? 0;
+      const down = SEAT_DIRECTIONS[index + 1] ?? 0;
+      const seat = box(
+        label.x + across * (step + width / 2),
+        label.y + down * (step + height / 2),
+        width,
+        height,
+      );
+      if (free(seat, bounds, field)) return seat;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Whether a seat is inside the frame and free of every word already written.
+ * @param seat - Where the word would go.
+ * @param bounds - The rectangle it has to stay inside, if any.
+ * @param field - The words already placed.
+ * @returns Whether it may be written there.
+ */
+function free(
+  seat: LabelBox,
+  bounds: ScatterLabelPlacementOptions['bounds'],
+  field: LabelBoxField,
+): boolean {
+  if (bounds !== undefined) {
+    if (seat.left < bounds.x || seat.right > bounds.x + bounds.width) {
+      return false;
+    }
+    if (seat.top < bounds.y || seat.bottom > bounds.y + bounds.height) {
+      return false;
+    }
+  }
+  return field.fits(seat);
+}
+
+/**
+ * How the word is drawn once its seat is known.
+ * @param seat - The rectangle it took.
+ * @param label - The word and what it names.
+ * @param radius - Radius of the dot it stands beside.
+ * @returns Where the text goes, which end of it is pinned, and where a line
+ * back to its subject reaches it.
+ */
+function written(
+  seat: LabelBox,
+  label: ScatterPixelLabel,
+  radius: number,
+): Omit<PlacedScatterLabel, keyof ScatterPixelLabel> {
+  const edgeX = Math.min(Math.max(label.x, seat.left), seat.right);
+  const edgeY = Math.min(Math.max(label.y, seat.top), seat.bottom);
+  const across = label.x - edgeX;
+  const down = label.y - edgeY;
+  const away = Math.hypot(across, down);
+  const middle = (seat.left + seat.right) / 2;
+  // Pinned at the end nearest its subject, so the word grows away from the dot
+  // rather than back over it.
+  const anchor = away <= radius ? 'middle' : nearestSide(middle, label.x);
+  const placed = {
+    textX:
+      anchor === 'start' ? seat.left : anchor === 'end' ? seat.right : middle,
+    textY: (seat.top + seat.bottom) / 2,
+    anchor,
+  } as const;
+  return away > LEADER_FROM
+    ? { ...placed, leader: { x: edgeX, y: edgeY } }
+    : placed;
+}
+
+/**
+ * Which end of a word to pin, given which side of its subject it sits on.
+ * @param middle - The middle of the word, horizontally.
+ * @param subject - Where what it names sits, horizontally.
+ * @returns The anchor to draw it with.
+ */
+function nearestSide(
+  middle: number,
+  subject: number,
+): 'start' | 'middle' | 'end' {
+  if (middle > subject + 1) return 'start';
+  if (middle < subject - 1) return 'end';
+  return 'middle';
+}
+
+/**
+ * The rectangle of a word of this size, centred on a point.
+ * @param centerX - Middle of the rectangle, horizontally.
+ * @param centerY - Middle of it, vertically.
+ * @param width - How wide it is.
+ * @param height - How tall.
+ * @returns The rectangle.
+ */
+function box(
+  centerX: number,
+  centerY: number,
+  width: number,
+  height: number,
+): LabelBox {
+  return {
+    left: centerX - width / 2,
+    right: centerX + width / 2,
+    top: centerY - height / 2,
+    bottom: centerY + height / 2,
+  };
+}
+
+/**
+ * The order the words are served in: the heaviest first — a group's name
+ * carries the size of its crowd — and ties in the order they were given, so
+ * the answer never depends on how the sort was implemented.
+ * @param labels - The words, in the order the caller gave them.
+ * @returns Their indices, best served first.
+ */
+function placementOrder(labels: readonly ScatterPixelLabel[]): number[] {
+  const order = new Array<number>(labels.length);
+  for (let index = 0; index < labels.length; index++) order[index] = index;
+  return order.toSorted((one, other) => {
+    const first = labels[one]?.weight ?? 0;
+    const second = labels[other]?.weight ?? 0;
+    return second - first || one - other;
+  });
+}
+
+/** How far a word sits clear of the dot it belongs to, in pixels. */
+const SEAT_GAP = 3;
+
+/** How far a word may be moved from what it names before it is dropped. */
+const DEFAULT_SHIFT = 40;
+
+/** How far apart the rings of seats searched after the near four are. */
+const SEAT_STEP = 10;
+
+/**
+ * The directions a word is pushed in, as unit vectors, tried in this order:
+ * sideways first, because text runs sideways and a name pushed left or right
+ * still reads as belonging to the dot beside it, then the diagonals, then
+ * straight up and down last — a word directly above a dot is the one most
+ * easily read as belonging to the dot above it instead.
+ */
+const SEAT_DIRECTIONS = Float64Array.from([
+  1, 0, -1, 0, 0.87, -0.5, -0.87, -0.5, 0.87, 0.5, -0.87, 0.5, 0.5, -0.87, -0.5,
+  -0.87, 0.5, 0.87, -0.5, 0.87, 0, -1, 0, 1,
+]);
+
+/**
+ * How far a word has to have moved before a line is drawn back to its subject:
+ * just short of the first ring, so a word in one of the four seats beside its
+ * own dot gets no line and every word that had to leave them gets one. A word
+ * beside its dot needs no line and gains only clutter from one; a word pushed
+ * across a crowd is anybody's until the line says whose.
+ */
+const LEADER_FROM = 8;

package/src/scatter/ui/scatterLabels.ts

@@ -0,0 +1,147 @@
+/**
+ * Where the words written on a cloud of points go.
+ *
+ * A dot says where a sample landed and nothing about which sample it is, so a
+ * reader who has found an outlier has to hover it, and a reader looking at
+ * forty crowds has to keep walking back to the key. Both are answered by
+ * writing the name on the picture — and both are answered by a different name,
+ * which is why there are two functions here rather than one flag.
+ *
+ * The placing is arithmetic over pixels, so it sits beside the layer that
+ * draws it rather than inside it and can be checked without rendering
+ * anything.
+ */
+
+import type { ScreenPoints } from '../core/screenPoints.ts';
+
+/** One word written on the plot, already placed. */
+export interface ScatterPixelLabel {
+  /** Horizontal position of what it names, in the frame's pixels. */
+  x: number;
+  /** Vertical position of what it names. */
+  y: number;
+  /** What it says. */
+  text: string;
+  /** Its colour, which is the colour of what it names. */
+  color: string;
+  /**
+   * How much of the picture it speaks for — the size of the crowd behind a
+   * group's name. It decides who is served first when two words want the same
+   * pixels, so the name over five hundred samples keeps its place and the one
+   * over three moves or goes.
+   * @default undefined — read as nothing, so the words are served in order
+   */
+  weight?: number;
+}
+
+/** Which ink a label takes, worked out the way a dot's is. */
+export interface ScatterLabelInk {
+  /**
+   * Which group each point belongs to, as an index into `colors`. An entry of
+   * `-1`, or one outside the range, is a point in no group.
+   * @default undefined — every label takes `fallbackColor`
+   */
+  groupOf?: ArrayLike<number>;
+  /**
+   * The colour of each group, in the order the groups were given.
+   * @default undefined — every label takes `fallbackColor`
+   */
+  colors?: readonly string[];
+  /**
+   * Colour of a label naming something in no group.
+   * @default 'var(--text-muted)'
+   */
+  fallbackColor?: string;
+}
+
+/**
+ * Every sample's own name, beside its own dot.
+ *
+ * A sample with no name is skipped rather than drawn empty, so a caller may
+ * name the twenty samples it cares about and leave the rest of the array
+ * `undefined` — which is how a crowded map stays readable while the outliers
+ * are still labelled.
+ * @param points - Where every point sits, in the frame's pixels.
+ * @param labels - What each point is called, in point order.
+ * @param ink - Which colour each label takes.
+ * @returns One label per named point that has somewhere to be drawn.
+ */
+export function scatterPointLabels(
+  points: ScreenPoints,
+  labels: ReadonlyArray<string | undefined>,
+  ink: ScatterLabelInk = {},
+): ScatterPixelLabel[] {
+  const { groupOf, colors, fallbackColor = DEFAULT_LABEL_INK } = ink;
+  const placed: ScatterPixelLabel[] = [];
+  const count = Math.min(points.x.length, points.y.length, labels.length);
+  for (let index = 0; index < count; index++) {
+    const text = labels[index];
+    if (text === undefined || text === '') continue;
+    const x = points.x[index];
+    const y = points.y[index];
+    if (x === undefined || !Number.isFinite(x)) continue;
+    if (y === undefined || !Number.isFinite(y)) continue;
+    const group = groupOf?.[index] ?? -1;
+    placed.push({ x, y, text, color: colors?.[group] ?? fallbackColor });
+  }
+  return placed;
+}
+
+/**
+ * Each group's name, once, at the middle of the points in it.
+ *
+ * Once rather than on every dot: forty seizures over five hundred spectra
+ * would otherwise write forty names twelve times each, and a reader can read
+ * none of them. The average of the pixels is the same place as the average of
+ * the data on a linear axis and one pass fewer, and it is the same point the
+ * group-average cross is drawn at, so turning both on marks and names one
+ * spot rather than two.
+ * @param points - Where every point sits, in the frame's pixels.
+ * @param names - What each group is called, in group order.
+ * @param ink - Which colour each label takes; `groupOf` is what it reads.
+ * @returns One label per group that anything belongs to.
+ */
+export function scatterGroupLabels(
+  points: ScreenPoints,
+  names: readonly string[],
+  ink: ScatterLabelInk = {},
+): ScatterPixelLabel[] {
+  const { groupOf, colors, fallbackColor = DEFAULT_LABEL_INK } = ink;
+  const placed: ScatterPixelLabel[] = [];
+  if (groupOf === undefined) return placed;
+
+  const sums = new Float64Array(names.length * 3);
+  const count = Math.min(points.x.length, points.y.length, groupOf.length);
+  for (let index = 0; index < count; index++) {
+    const group = groupOf[index];
+    if (group === undefined || group < 0 || group >= names.length) continue;
+    const x = points.x[index];
+    const y = points.y[index];
+    if (x === undefined || !Number.isFinite(x)) continue;
+    if (y === undefined || !Number.isFinite(y)) continue;
+    sums[group * 3] = (sums[group * 3] ?? 0) + x;
+    sums[group * 3 + 1] = (sums[group * 3 + 1] ?? 0) + y;
+    sums[group * 3 + 2] = (sums[group * 3 + 2] ?? 0) + 1;
+  }
+
+  for (let group = 0; group < names.length; group++) {
+    const seen = sums[group * 3 + 2] ?? 0;
+    const text = names[group];
+    if (seen === 0 || text === undefined || text === '') continue;
+    placed.push({
+      x: (sums[group * 3] ?? 0) / seen,
+      y: (sums[group * 3 + 1] ?? 0) / seen,
+      text,
+      color: colors?.[group] ?? fallbackColor,
+      weight: seen,
+    });
+  }
+  return placed;
+}
+
+/**
+ * What a label naming nothing in particular is written in. It is the muted ink
+ * rather than the faint one a dot in no group takes: a word has to be read,
+ * where a dot only has to be seen.
+ */
+const DEFAULT_LABEL_INK = 'var(--text-muted)';

package/src/scatter/ui/scatterMarkGlyph.tsx

@@ -0,0 +1,94 @@
+/**
+ * A point drawn over the cloud that is not a sample, and the glyph it takes.
+ *
+ * It is its own module because three unrelated things place such a point — a
+ * caller's cluster centre, a group's own average, a rule laid across the plot
+ * — and only the first of them is anything the layer knows about.
+ */
+
+import type { ReactElement } from 'react';
+
+import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
+
+/** A point drawn over the cloud that is not a sample, already in pixels. */
+export interface ScatterPixelMark {
+  /** What it is called, which is what a hover card and an end-to-end test ask for. */
+  label: string;
+  /** Horizontal position, in the frame's pixels. */
+  x: number;
+  /** Vertical position, in the frame's pixels. */
+  y: number;
+  /** Its colour, normally the colour of the group it stands for. */
+  color: string;
+  /**
+   * The glyph it is drawn with, which is how a reader tells it from a sample.
+   * @default 'cross'
+   */
+  shape?: OverlayMarkShape;
+}
+
+/**
+ * One mark, drawn as the glyph its shape asks for.
+ *
+ * A rule laid across the cloud names no point, so the two rule shapes are
+ * drawn as the default cross.
+ * @param mark - What to draw, already in the frame's pixels.
+ * @param size - Side of the square the glyph is drawn in, in pixels.
+ * @param key - What React reconciles the glyph by.
+ * @returns The glyph.
+ */
+export function markGlyph(
+  mark: ScatterPixelMark,
+  size: number,
+  key: string,
+): ReactElement {
+  const { label, x, y, color, shape = 'cross' } = mark;
+  const half = size / 2;
+  const near = round(x - half);
+  const far = round(x + half);
+  const top = round(y - half);
+  const foot = round(y + half);
+  // `key` is passed on each element rather than spread: React reads a key
+  // out of JSX itself, and one arriving through a spread is dropped with a
+  // warning that only shows up once the page is running.
+  const shared = { 'data-mark': label };
+  if (shape === 'dot' || shape === 'ring') {
+    const filled = shape === 'dot';
+    return (
+      <circle
+        key={key}
+        {...shared}
+        cx={round(x)}
+        cy={round(y)}
+        r={half}
+        fill={filled ? color : 'none'}
+        stroke={filled ? 'none' : color}
+      />
+    );
+  }
+  if (shape === 'square') {
+    return (
+      <rect
+        key={key}
+        {...shared}
+        x={near}
+        y={top}
+        width={size}
+        height={size}
+        fill={color}
+        stroke="none"
+      />
+    );
+  }
+  return (
+    <path
+      key={key}
+      {...shared}
+      d={`M${near} ${top}L${far} ${foot}M${far} ${top}L${near} ${foot}`}
+      fill="none"
+      stroke={color}
+    />
+  );
+}
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/scatter/ui/scatterMatrixDots.tsx

@@ -0,0 +1,134 @@
+/**
+ * The dots of one cell of a pair grid, and the surface that finds them again.
+ *
+ * They are not an element each. Six axes over five thousand samples is a
+ * hundred and eighty thousand marks, and a browser handed that many nodes
+ * stops answering the pointer long before it paints; one path of zero-length
+ * round-capped segments a colour is at most sixteen nodes a cell and draws the
+ * same discs. The scores are read where they stand for the same reason: a grid
+ * copying a column per cell allocates n² arrays to show n.
+ */
+
+import type { CSSProperties, PointerEvent, ReactElement } from 'react';
+
+import type { ChartFrameRender } from '../../chart/ui/ChartFrame.tsx';
+
+import type { ScatterMatrixGrid } from './ScatterMatrixDiagonal.tsx';
+
+/**
+ * Every dot of one cell, as one path per colour, plus the rectangle that turns
+ * a pointer position back into a row when the caller wants hovering.
+ * @param grid - Everything the grid worked out once and every cell reads.
+ * @param row - Which row the cell sits in, which is the axis up its side.
+ * @param column - Which column, which is the axis along its foot.
+ * @param frame - The rectangle and the two scales the cell was given.
+ * @returns The marks, in the order they stack.
+ */
+export function scatterMatrixDots(
+  grid: ScatterMatrixGrid,
+  row: number,
+  column: number,
+  frame: ChartFrameRender,
+): ReactElement[] {
+  const { scores, colors, groupOf, mask, pointRadius, onHoverChange } = grid;
+  const { x, y, plot } = frame;
+  const inks = (colors?.length ?? 0) + 1;
+  const paths: string[] = new Array(inks * 2).fill('');
+
+  for (let index = 0; index < scores.rows; index++) {
+    const valueX = scores.get(index, column);
+    const valueY = scores.get(index, row);
+    if (!Number.isFinite(valueX) || !Number.isFinite(valueY)) continue;
+    const atX = Math.round((x.offset + valueX * x.factor) * 10) / 10;
+    const atY = Math.round((y.offset + valueY * y.factor) * 10) / 10;
+    const slot =
+      inkOf(groupOf, index, inks - 1) * 2 + (mask?.[index] === 0 ? 1 : 0);
+    paths[slot] = `${paths[slot] ?? ''}M${atX} ${atY}h0`;
+  }
+
+  const marks: ReactElement[] = [];
+  for (let slot = 0; slot < paths.length; slot++) {
+    const data = paths[slot];
+    if (data === undefined || data === '') continue;
+    const ink = colors?.[slot >> 1] ?? NO_GROUP_INK;
+    const style = dotStyle(ink, pointRadius, slot);
+    marks.push(<path key={slot} d={data} style={style} />);
+  }
+  if (onHoverChange !== undefined) {
+    marks.push(
+      <rect
+        key="tracking"
+        x={plot.left}
+        y={plot.top}
+        width={plot.width}
+        height={plot.height}
+        style={TRACKING_STYLE}
+        onPointerMove={(event) =>
+          onHoverChange(nearestRow(event, grid, row, column, frame))
+        }
+        onPointerLeave={() => onHoverChange(-1)}
+      />,
+    );
+  }
+  return marks;
+}
+
+/** How far from a dot the pointer still counts as resting on it, in pixels. */
+const HOVER_REACH = 10;
+
+/** Opacity of a dot in the selection, of one outside it, and the ungrouped ink. */
+const POINT_OPACITY = 0.85;
+const FAINT_OPACITY = 0.16;
+const NO_GROUP_INK = 'var(--text-muted)';
+
+/** The rectangle that takes the pointer, over the dots and invisible. */
+const TRACKING_STYLE = {
+  fill: 'none',
+  pointerEvents: 'all',
+} as const satisfies CSSProperties;
+
+function nearestRow(
+  event: PointerEvent<SVGRectElement>,
+  grid: ScatterMatrixGrid,
+  row: number,
+  column: number,
+  frame: ChartFrameRender,
+): number {
+  const { offsetX, offsetY } = event.nativeEvent;
+  const { scores } = grid;
+  const { x, y } = frame;
+  let best = -1;
+  let closest = HOVER_REACH * HOVER_REACH;
+
+  for (let index = 0; index < scores.rows; index++) {
+    const awayX = x.offset + scores.get(index, column) * x.factor - offsetX;
+    const awayY = y.offset + scores.get(index, row) * y.factor - offsetY;
+    const away = awayX * awayX + awayY * awayY;
+    if (away < closest) {
+      closest = away;
+      best = index;
+    }
+  }
+  return best;
+}
+
+function dotStyle(color: string, radius: number, slot: number): CSSProperties {
+  return {
+    fill: 'none',
+    stroke: color,
+    strokeWidth: radius * 2,
+    strokeLinecap: 'round',
+    strokeOpacity: (slot & 1) === 1 ? FAINT_OPACITY : POINT_OPACITY,
+  };
+}
+
+function inkOf(
+  groupOf: ArrayLike<number> | undefined,
+  row: number,
+  groups: number,
+): number {
+  const raw = groupOf?.[row];
+  if (raw === undefined || !Number.isFinite(raw)) return groups;
+  const group = Math.trunc(raw);
+  return group < 0 || group >= groups ? groups : group;
+}