react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/projectionBarStyles.ts

@@ -0,0 +1,174 @@
+/**
+ * Every rule the settings bar over the figure is drawn with.
+ *
+ * They sit apart from the rules the tabs themselves are drawn with because the
+ * bar is the viewer's own chrome rather than part of any figure: it is one row
+ * whatever the tab, and what changes with the figure's width is how much of
+ * itself it writes rather than what it holds. Every colour is a family token,
+ * so the bar on any site of the family is that site's own grey.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+
+/**
+ * The row the settings bar is laid into, which is one height for every tab.
+ *
+ * Two of the four tabs put a picker on the bar and two put a stepper, and a
+ * picker is the taller of the two whatever size the surface asks it for.
+ * Without a floor the bar would be six pixels shorter on the pair grid than on
+ * the map, and the whole figure under it would jump every time the reader
+ * moved between them — which is the one thing an embedded figure must never do
+ * to the page hosting it.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The row's rules.
+ */
+export function projectionBarRowStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    alignItems: 'stretch',
+    minHeight:
+      metrics.paddingY * 2 + Math.max(metrics.controlHeight, PICKER_HEIGHT),
+  };
+}
+
+/** How tall a picker stands, which no measurement of ours makes it smaller. */
+const PICKER_HEIGHT = 30;
+
+/**
+ * The box the strip of views sits in.
+ *
+ * On every width but the narrowest it refuses to shrink, so a bar whose
+ * estimate was a few pixels out clips nothing and the views keep their words.
+ * At the last rung it becomes a scroller instead: a figure three hundred
+ * pixels wide cannot hold four names however short they are written, and a
+ * strip that scrolls is one the reader can still reach every view from, where
+ * a strip squeezed further is a row of initials nobody can read.
+ *
+ * Two things make that scroller read as deliberate rather than as a fault. Its
+ * ceiling is set by the caller from what the settings and the glyphs need, so
+ * the row can never push the cog off the edge of the figure; and its trailing
+ * edge fades, so a name cut in half says there is more to the right instead of
+ * looking clipped. The scrollbar itself is hidden — inside a thirty pixel bar
+ * it would take a fifth of the height and say nothing the fade does not.
+ * @param scrolls - Whether the strip is at the rung that lets it scroll.
+ * @param maxWidth - The most it may take, in pixels.
+ * @returns The box's rules.
+ */
+export function projectionTabTrackStyle(
+  scrolls: boolean,
+  maxWidth: number,
+): CSSProperties {
+  if (!scrolls) return { display: 'flex', flexShrink: 0 };
+  return {
+    boxSizing: 'border-box',
+    display: 'flex',
+    minWidth: 0,
+    maxWidth,
+    paddingRight: PROJECTION_TRACK_FADE,
+    overflowX: 'auto',
+    scrollbarWidth: 'none',
+    maskImage: TRACK_FADE_MASK,
+    WebkitMaskImage: TRACK_FADE_MASK,
+  };
+}
+
+/**
+ * How wide the strip's trailing edge fades over.
+ *
+ * The same run of pixels is kept clear after the last view as well, so a
+ * reader scrolled to the end of the strip is not shown its last name fading
+ * out — which would say there is more when there is not.
+ */
+const PROJECTION_TRACK_FADE = 14;
+
+const TRACK_FADE_MASK = `linear-gradient(to right, black calc(100% - ${PROJECTION_TRACK_FADE}px), transparent)`;
+
+/**
+ * Where a scrolling strip has to sit for the view in force to be read.
+ *
+ * A view wider than the strip itself is shown from its start rather than its
+ * end: on the narrowest figures the name in force does not fit at all, and a
+ * reader shown its last three letters cannot tell which view they are on.
+ * @param left - The view's left edge inside the strip.
+ * @param right - Its right edge.
+ * @param scrollLeft - Where the strip is scrolled to now.
+ * @param clientWidth - How much of the strip is in sight.
+ * @returns Where it should be scrolled to; unchanged when the view is in sight.
+ */
+export function projectionTabScroll(
+  left: number,
+  right: number,
+  scrollLeft: number,
+  clientWidth: number,
+): number {
+  const room = clientWidth - PROJECTION_TRACK_FADE;
+  if (right - left >= room || left < scrollLeft) return left;
+  if (right > scrollLeft + room) return right - room;
+  return scrollLeft;
+}
+
+/**
+ * The settings at the far end of the bar.
+ *
+ * They never shrink. A flex row hands its shrinkage out in proportion to what
+ * each side asked for, which would take pixels off a chip that is already the
+ * shortest honest way to write the configuration — so the strip of views is
+ * the one thing that gives, and it gives by scrolling rather than by clipping.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The end's rules.
+ */
+export function projectionBarEndStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    flexShrink: 0,
+    alignItems: 'center',
+    gap: metrics.gap,
+  };
+}
+
+/**
+ * The figure's own explanation, once it has folded in behind the cog.
+ *
+ * On the narrowest figures the question mark is the glyph that goes, because
+ * the reader still has to be able to reach the settings and the second tier —
+ * so the paragraph it used to open is written at the head of the panel the cog
+ * opens instead. Not one word of it is dropped in the move.
+ *
+ * It brings its own room and its own hairline, because the panel under it
+ * brings both of those and the popover holding the two brings neither: a
+ * paragraph flush against the edge of a card reads as a rendering fault, and
+ * one running straight into a panel header reads as part of the header.
+ *
+ * The band and the measure are two rules rather than one. Capping the band
+ * itself would stop its hairline short of both edges of a panel wider than the
+ * cap, which reads as a mis-drawn line rather than as a division — so the band
+ * takes the panel's width and the sentence inside it is what is held to a
+ * readable measure.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The band's rules.
+ */
+export function projectionFoldedCaptionStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    padding: `${metrics.gap + 5}px ${metrics.gap + 8}px ${metrics.gap + 4}px`,
+    borderBottom: '1px solid var(--border)',
+    color: 'var(--text)',
+    fontSize: metrics.labelSize + 1,
+    lineHeight: 1.4,
+    textWrap: 'pretty',
+  };
+}
+
+/**
+ * The sentence inside that band.
+ *
+ * Capped short of a wide panel, because a line running the full width of one
+ * is a line the eye loses the start of on the way back from the end of it.
+ */
+export const PROJECTION_CAPTION_TEXT_STYLE = {
+  margin: 0,
+  maxWidth: 280,
+} as const satisfies CSSProperties;

package/src/projection/ui/projectionCloudChoices.ts

@@ -0,0 +1,23 @@
+/**
+ * What the cloud's own settings offer.
+ *
+ * One list, read by the value menu on the bar and by the segmented control in
+ * the panel behind the cog, so the two can never offer different words for the
+ * same thing.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
+
+/**
+ * What a plain drag does.
+ *
+ * Written as the action rather than as the name of a mode: `Turn` and `Select`
+ * are what the reader's hand is about to do, where `Orbit` would be a state
+ * they have to translate first.
+ */
+export const CLOUD_GESTURE_CHOICES: ReadonlyArray<OverlayOption<CloudGesture>> =
+  [
+    { value: 'turn', label: 'Turn' },
+    { value: 'select', label: 'Select' },
+  ];

package/src/projection/ui/projectionEllipse.ts

@@ -0,0 +1,104 @@
+/**
+ * How large a group outline is: what the picker offers, what each choice
+ * reads, and how one travels through a `<select>` and back.
+ *
+ * All of it in one module because the same size has to be written twice — in
+ * the control that sets it and in the legend sentence that explains it — and a
+ * pair like that drifts apart the moment each file spells it for itself.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import { coverageForStandardDeviations } from '../../scatter/core/ellipseCoverage.ts';
+
+/**
+ * How much of a group its outline holds, written the way a sentence wants it.
+ *
+ * A share rather than a multiple of the spread, because on a map a number of
+ * standard deviations does not hold the fraction everyone has been taught it
+ * does — two of them cover about 86 % of a group and not 95 % — and a legend
+ * quoting the multiple is how a figure comes to promise more than it draws.
+ * @param size - How large the outlines are, or `null` for none.
+ * @returns The share, e.g. `95%`; the empty string when nothing is outlined.
+ */
+export function ellipseCoverageText(size: EllipseSize | null): string {
+  if (size === null) return '';
+  const share =
+    size.kind === 'coverage'
+      ? size.probability
+      : coverageForStandardDeviations(size.standardDeviations);
+  return `${Math.round(share * 100)}%`;
+}
+
+/**
+ * What one choice of the outline picker reads.
+ * @param size - The size that choice stands for, or `null` for no outlines.
+ * @returns The label, e.g. `95% of samples`, or `2 SD (about 86%)`.
+ */
+export function ellipseSizeLabel(size: EllipseSize | null): string {
+  if (size === null) return NO_OUTLINES_LABEL;
+  const share = ellipseCoverageText(size);
+  if (size.kind === 'coverage') return `${share} of samples`;
+  return `${size.standardDeviations} SD (about ${share})`;
+}
+
+/**
+ * The sizes the picker offers, with the current one kept in the list.
+ *
+ * A site that asked for a size of its own — a multiple of the spread, or a
+ * share the four do not cover — keeps its place at the head of the list, so
+ * opening the picker never silently changes the figure.
+ * @param current - The size the map is drawn at, or `null` for no outlines.
+ * @returns The choices, in the order they are offered.
+ */
+export function ellipseChoices(current: EllipseSize | null): OverlayOption[] {
+  const choices: OverlayOption[] = [
+    { value: NO_ELLIPSE, label: ellipseSizeLabel(null) },
+  ];
+  for (const probability of ELLIPSE_SHARES) {
+    const size: EllipseSize = { kind: 'coverage', probability };
+    choices.push({ value: ellipseKey(size), label: ellipseSizeLabel(size) });
+  }
+
+  const key = ellipseKey(current);
+  for (const choice of choices) {
+    if (choice.value === key) return choices;
+  }
+  choices.splice(1, 0, { value: key, label: ellipseSizeLabel(current) });
+  return choices;
+}
+
+/**
+ * The value one size travels as, through a picker that only carries strings.
+ * @param size - The size, or `null` for no outlines.
+ * @returns The value.
+ */
+export function ellipseKey(size: EllipseSize | null): string {
+  if (size === null) return NO_ELLIPSE;
+  if (size.kind === 'coverage') return `share:${size.probability}`;
+  return `sd:${size.standardDeviations}`;
+}
+
+/**
+ * The size a picker's value stands for.
+ * @param key - The value, from {@link ellipseKey}.
+ * @returns The size; `null` for no outlines, and for anything unreadable, since a figure with no outlines is the safe reading of a value nobody wrote.
+ */
+export function ellipseSize(key: string): EllipseSize | null {
+  if (key === NO_ELLIPSE) return null;
+  const value = Number(key.slice(key.indexOf(':') + 1));
+  if (!Number.isFinite(value)) return null;
+  if (key.startsWith('sd:')) {
+    return { kind: 'standardDeviations', standardDeviations: value };
+  }
+  return { kind: 'coverage', probability: value };
+}
+
+/*
+ * Written as shares of the samples rather than as multiples of the spread,
+ * which is the one decision this control makes for the reader.
+ */
+const ELLIPSE_SHARES: readonly number[] = [0.5, 0.9, 0.95, 0.99];
+
+const NO_ELLIPSE = 'none';
+const NO_OUTLINES_LABEL = 'No outlines';

package/src/projection/ui/projectionEllipsoid.ts

@@ -0,0 +1,78 @@
+/**
+ * How large a group's shell is, in the words the cloud writes.
+ *
+ * It is the flat map's `projectionEllipse` with one dimension more, and the
+ * two cannot share an implementation for the one reason worth having a second
+ * module for: the same share is a different distance in three dimensions than
+ * in two. A shell drawn where the map's 95 % outline is drawn holds about 74 %
+ * of its group, so a cloud quoting the map's number promises a fifth of the
+ * samples it does not contain.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import { coverageForStandardDeviations3 } from '../../scatter3d/core/ellipsoidCoverage.ts';
+
+import { ellipseKey } from './projectionEllipse.ts';
+
+const WHOLE_SHARE = 100;
+
+/**
+ * How much of a group its shell holds, written the way a sentence wants it.
+ * @param size - How large the shells are, or `null` for none.
+ * @returns The share, e.g. `95%`; the empty string when nothing is shelled.
+ */
+export function ellipsoidCoverageText(size: EllipseSize | null): string {
+  if (size === null) return '';
+  const share =
+    size.kind === 'coverage'
+      ? size.probability
+      : coverageForStandardDeviations3(size.standardDeviations);
+  return `${Math.round(share * WHOLE_SHARE)}%`;
+}
+
+/**
+ * What one choice of the cloud's shell picker reads.
+ * @param size - The size that choice stands for, or `null` for no shells.
+ * @returns The label, e.g. `95% of samples`, or `2 SD (about 74%)`.
+ */
+export function ellipsoidSizeLabel(size: EllipseSize | null): string {
+  if (size === null) return NO_SHELLS_LABEL;
+  const share = ellipsoidCoverageText(size);
+  if (size.kind === 'coverage') return `${share} of samples`;
+  return `${size.standardDeviations} SD (about ${share})`;
+}
+
+/**
+ * The sizes the cloud's picker offers, with the current one kept in the list.
+ *
+ * The same shares the map offers, because a share means the same thing in both
+ * pictures — it is the distance it comes out at that differs, and that is the
+ * geometry's business rather than the reader's. A size given in standard
+ * deviations is the one place the difference shows, and it is written here
+ * with the share a shell at that distance actually holds: two of them cover
+ * 86 % of a flat group and 74 % of a solid one.
+ * @param current - The size the cloud is drawn at, or `null` for no shells.
+ * @returns The choices, in the order they are offered.
+ */
+export function ellipsoidChoices(current: EllipseSize | null): OverlayOption[] {
+  const choices: OverlayOption[] = [
+    { value: ellipseKey(null), label: ellipsoidSizeLabel(null) },
+  ];
+  for (const probability of SHELL_SHARES) {
+    const size: EllipseSize = { kind: 'coverage', probability };
+    choices.push({ value: ellipseKey(size), label: ellipsoidSizeLabel(size) });
+  }
+
+  const key = ellipseKey(current);
+  for (const choice of choices) {
+    if (choice.value === key) return choices;
+  }
+  choices.splice(1, 0, { value: key, label: ellipsoidSizeLabel(current) });
+  return choices;
+}
+
+/* The same four the map offers, so the two pictures are set the same way. */
+const SHELL_SHARES: readonly number[] = [0.5, 0.9, 0.95, 0.99];
+
+const NO_SHELLS_LABEL = 'No shells';

package/src/projection/ui/projectionFormat.ts

@@ -0,0 +1,18 @@
+/**
+ * A number as a hover card writes it.
+ *
+ * Three decimals, with the trailing zeros dropped, so a column of scores lines
+ * up on its decimal point without `0.478000` claiming six digits of precision
+ * that a projection of four measurements does not have. A value that is not a
+ * number at all is written as a dash rather than as `NaN`, which reads to
+ * everyone outside programming as a fault in the page.
+ * @param value - The number.
+ * @returns It, written out.
+ */
+export function formatProjectionValue(value: number): string {
+  if (!Number.isFinite(value)) return UNKNOWN_VALUE;
+  return String(Number(value.toFixed(DECIMALS)));
+}
+
+const DECIMALS = 3;
+const UNKNOWN_VALUE = '—';

package/src/projection/ui/projectionMapChoices.ts

@@ -0,0 +1,64 @@
+/**
+ * What the map's two settings offer, in the two lengths the bar needs.
+ *
+ * The same choices are written twice — once as bare shares on a value menu
+ * whose own heading already says what they are shares of, and once as whole
+ * sentences in the panel a reader opens with room to read them — so both are
+ * built here and neither file spells the other's list for itself.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type {
+  ProjectionColorBy,
+  ProjectionOptions,
+} from '../core/projectionOptions.ts';
+
+import {
+  ellipseChoices,
+  ellipseCoverageText,
+  ellipseSize,
+} from './projectionEllipse.ts';
+
+/**
+ * What the colour may stand for.
+ * @param groupLabel - What the set of groups is called.
+ * @param uncoloured - What "the colour stands for nothing" reads.
+ * @returns The two choices.
+ */
+export function projectionColourChoices(
+  groupLabel: string,
+  uncoloured: string,
+): ReadonlyArray<OverlayOption<ProjectionColorBy>> {
+  return [
+    { value: 'group', label: groupLabel },
+    { value: 'none', label: uncoloured },
+  ];
+}
+
+/**
+ * How large the outlines may be, written as bare shares.
+ *
+ * A menu opens under its own heading, so a choice reading `95%` is already
+ * inside a list called `Group outlines` and the words "of samples" are not
+ * needed a fifth time. They stay on the pointer, because `2 SD (about 86%)` is
+ * the one case where the share alone hides which size a site actually asked
+ * for.
+ * @param options - What the map is showing.
+ * @param noOutlines - What "no outlines at all" reads.
+ * @returns The choices, in the order they are offered.
+ */
+export function projectionOutlineChoices(
+  options: ProjectionOptions,
+  noOutlines: string,
+): readonly OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (const choice of ellipseChoices(options.ellipse)) {
+    const share = ellipseCoverageText(ellipseSize(choice.value));
+    choices.push({
+      value: choice.value,
+      label: share === '' ? noOutlines : share,
+      title: choice.label,
+    });
+  }
+  return choices;
+}

package/src/projection/ui/projectionMapChrome.ts

@@ -0,0 +1,228 @@
+/**
+ * The words one map writes around its own picture: the legend that says what
+ * colour and shape mean on it, and the sentences under it.
+ *
+ * They are built here rather than in the component so that what the figure
+ * claims can be read, and tested, without rendering a chart — which is the
+ * only way a promise like "this outline covers 95 % of the group" stays
+ * honest as the controls around it change.
+ */
+
+import type { OverlayLegendEntry } from '../../overlay/ui/OverlayLegend.tsx';
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { fillCopy } from '../core/projectionCopy.ts';
+import type { ProjectionMarker } from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+
+import { ellipseCoverageText } from './projectionEllipse.ts';
+import { ellipsoidCoverageText } from './projectionEllipsoid.ts';
+import { UNGROUPED_INK } from './projectionMapModel.ts';
+
+/** What the map's chrome is built from. */
+export interface ProjectionMapChromeInput {
+  /** The words the map writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** The groups as the map colours them. */
+  groups: ResolvedProjectionGroups;
+  /** Whether colour stands for the group at all. */
+  colored: boolean;
+  /** How large the group outlines are, or `null` for none. */
+  ellipse: EllipseSize | null;
+  /** How many samples a group needs before it is outlined at all. */
+  minimumPoints: number;
+  /** Whether each group's average is marked with a cross. */
+  showGroupMeans: boolean;
+  /** The reference points drawn over the cloud. */
+  markers: readonly ProjectionMarker[];
+  /** How many leading rows the model was built from. */
+  fittedCount: number;
+  /** How many rows there are in all. */
+  total: number;
+  /**
+   * Which figure the chrome is for. The cloud says the same things about
+   * itself, in its own words and about its own geometry: a share is a wider
+   * shape in three dimensions than in two, so the sentence promising one has
+   * to be built from the dimension it will be read in.
+   * @default 'map'
+   */
+  figure?: 'map' | 'space';
+}
+
+/** The legend and the standing caption of one map. */
+export interface ProjectionMapChrome {
+  /**
+   * The sentence over the legend, naming what colour and shape mean here.
+   *
+   * It is one short clause, because the legend floats on the picture and its
+   * title is written on a single line: everything else the encoding needs
+   * explaining with — how much of a group an outline holds — is in the
+   * caption, which the reader opens rather than reads over the data.
+   */
+  title: string;
+  /** The legend's entries, in the order they are written. */
+  entries: OverlayLegendEntry[];
+  /** The paragraph the map's question mark hands back. */
+  caption: string;
+}
+
+/**
+ * The legend and the caption of one map.
+ *
+ * The legend's title always names the encoding, because a reader who cannot
+ * say what the colour stands for carries the wrong meaning from one tab to the
+ * next. And every mark the figure can draw that is not a plain filled dot — a
+ * group average, a cluster centre, a sample the model never saw — earns an
+ * entry, because a mark nobody named is a mark the reader counts as one more
+ * group.
+ * @param input - See {@link ProjectionMapChromeInput}.
+ * @returns The legend's title and entries, and the standing caption.
+ */
+export function projectionMapChrome(
+  input: ProjectionMapChromeInput,
+): ProjectionMapChrome {
+  const { copy, groups, colored, ellipse, showGroupMeans, markers } = input;
+  const { minimumPoints, fittedCount, total, figure = 'map' } = input;
+  const entries: OverlayLegendEntry[] = [];
+  const skipped: string[] = [];
+
+  if (colored) {
+    for (const entry of groups.entries) {
+      const thin = ellipse !== null && entry.count < minimumPoints;
+      if (thin) skipped.push(entry.label);
+      entries.push({
+        id: entry.id,
+        label: entry.label,
+        color: entry.color,
+        shape: 'dot',
+        count: entry.count,
+        note: thin ? NOT_OUTLINED_NOTE : undefined,
+      });
+    }
+    if (showGroupMeans) {
+      entries.push({
+        id: 'group-average',
+        label: copy.help.showGroupMeans.title,
+        color: UNGROUPED_INK,
+        shape: 'cross',
+      });
+    }
+  }
+  appendMarkerEntries(entries, markers, groups);
+
+  const hollow = fittedCount < total;
+  if (hollow) {
+    entries.push({
+      id: 'projected',
+      label: HOLLOW_LEGEND_LABEL,
+      color: 'var(--text-muted)',
+      shape: 'ring',
+    });
+  }
+
+  return {
+    title: legendTitle(copy, groups, colored),
+    entries,
+    caption: captionFor(
+      copy,
+      groups,
+      colored,
+      ellipse,
+      skipped,
+      hollow,
+      figure,
+    ),
+  };
+}
+
+/**
+ * The sentence reporting what a gesture picked out.
+ * @param copy - The words the map writes.
+ * @param count - How many samples are selected.
+ * @param total - How many there are in all.
+ * @returns The sentence.
+ */
+export function projectionSelectionSentence(
+  copy: ProjectionCopy,
+  count: number,
+  total: number,
+): string {
+  if (count === 0) return copy.sentence.selectionNone;
+  return fillCopy(copy.sentence.selection, {
+    count: count.toLocaleString(),
+    total: total.toLocaleString(),
+  });
+}
+
+const NOT_OUTLINED_NOTE = 'Not outlined: too few samples.';
+const HOLLOW_LEGEND_LABEL = 'Hollow = added after the map was built';
+const HOLLOW_SENTENCE =
+  'The hollow dots were placed on the finished map afterwards, so one of them landing far out is a finding rather than a fault.';
+
+/**
+ * What the legend says when colour stands for nothing.
+ *
+ * The entries left are all shape, so the title names the shape channel: a
+ * legend naming no encoding at all is the one fault this title exists to
+ * prevent, and it is not fixed by leaving the title out.
+ */
+const SHAPE_LEGEND_TITLE = 'Shape = what each mark is.';
+
+function legendTitle(
+  copy: ProjectionCopy,
+  groups: ResolvedProjectionGroups,
+  colored: boolean,
+): string {
+  if (!colored || groups.entries.length === 0) return SHAPE_LEGEND_TITLE;
+  return fillCopy(copy.legend.mapNoEllipse, {
+    groups: groups.label.toLowerCase(),
+  });
+}
+
+function captionFor(
+  copy: ProjectionCopy,
+  groups: ResolvedProjectionGroups,
+  colored: boolean,
+  ellipse: EllipseSize | null,
+  skipped: readonly string[],
+  hollow: boolean,
+  figure: 'map' | 'space',
+): string {
+  const solid = figure === 'space';
+  let sentence = solid ? copy.intro.space : copy.intro.map;
+  // What an outline actually holds is the one claim the figure makes that the
+  // reader cannot check by looking, so it is said in full here rather than
+  // squeezed onto the key floating over the dots.
+  if (colored && ellipse !== null) {
+    sentence += ` ${fillCopy(solid ? copy.legend.space : copy.legend.map, {
+      groups: groups.label.toLowerCase(),
+      coverage: solid
+        ? ellipsoidCoverageText(ellipse)
+        : ellipseCoverageText(ellipse),
+    })}`;
+  }
+  if (skipped.length > 0) {
+    const names = skipped.join(', ');
+    sentence += ` ${fillCopy(copy.sentence.skippedGroups, { names })}`;
+  }
+  if (hollow) sentence += ` ${HOLLOW_SENTENCE}`;
+  return sentence;
+}
+
+function appendMarkerEntries(
+  entries: OverlayLegendEntry[],
+  markers: readonly ProjectionMarker[],
+  groups: ResolvedProjectionGroups,
+): void {
+  const named = new Set<string>();
+  for (const marker of markers) {
+    if (named.has(marker.label)) continue;
+    named.add(marker.label);
+    entries.push({
+      id: `marker-${marker.label}`,
+      label: marker.label,
+      color: groups.entries[marker.group ?? -1]?.color ?? UNGROUPED_INK,
+      shape: marker.shape ?? 'cross',
+    });
+  }
+}