react-cheminfo 0.9.0 → 0.10.0

package/src/projection/ui/projectionBarReadings.ts

@@ -0,0 +1,177 @@
+/**
+ * What the settings at the far end of the bar currently read.
+ *
+ * The same four or five words are needed twice and must agree both times: once
+ * to work out how much room the bar needs before anything is drawn, and once
+ * to write them on the chip a narrow bar gathers them into. Building them here
+ * is what stops the estimate from measuring `Species` while the chip writes
+ * `Colour by species` and folding the bar at the wrong width.
+ */
+
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import { ellipseCoverageText } from './projectionEllipse.ts';
+import { WHOLE_SHARE } from './projectionTabStyles.ts';
+
+/** One setting on the bar, as the reader sees it right now. */
+export interface ProjectionReading {
+  /** The one word written in front of the value where there is room. */
+  key: string;
+  /** What the setting is called in full, which is what it announces. */
+  label: string;
+  /** What it currently reads: `Species`, `95%`, `4`. */
+  value: string;
+  /**
+   * The figure's own colours, for the setting that decides them.
+   * @default undefined — no dots are drawn
+   */
+  swatches?: readonly string[];
+  /**
+   * Whether it is a stepper rather than words. A number is the one setting a
+   * value button cannot improve, so it keeps its two buttons — which the
+   * ladder cannot see, because they are not written.
+   * @default false
+   */
+  stepper?: boolean;
+}
+
+/** What the readings of the tab showing are built from. */
+export interface ProjectionReadingsInput {
+  /** The tab showing, whose own settings sit at the far end of the bar. */
+  tab: ProjectionTab;
+  /** The words the viewer writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** What the figure is showing, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The groups as every figure draws them, whose colours the map writes. */
+  groups: ResolvedProjectionGroups;
+}
+
+/**
+ * What the tab showing writes at the far end of the bar.
+ * @param input - See {@link ProjectionReadingsInput}.
+ * @returns The readings, in the order they are written.
+ */
+export function projectionBarReadings(
+  input: ProjectionReadingsInput,
+): readonly ProjectionReading[] {
+  const { tab, copy, options, groups } = input;
+  const { bar, help } = copy;
+
+  if (tab === 'pairs') {
+    return [
+      {
+        key: bar.key.pairCount,
+        label: help.pairCount.title,
+        value: String(options.pairCount),
+        stepper: true,
+      },
+    ];
+  }
+  if (tab === 'variables') {
+    return [
+      {
+        key: bar.key.variablesView,
+        label: help.variablesView.title,
+        value: bar.view[options.variablesView],
+      },
+    ];
+  }
+  if (tab === 'shares') {
+    return [
+      {
+        key: bar.key.shareTarget,
+        label: help.shareTarget.title,
+        value: `${Math.round(options.shareTarget * WHOLE_SHARE)}%`,
+        stepper: true,
+      },
+    ];
+  }
+  return mapReadings(copy, options, groups);
+}
+
+/**
+ * How much room the readings need beyond the words on them.
+ *
+ * A stepper is two buttons around a number, and the ladder measures a setting
+ * from what is written on it — so without this a bar holding one would be
+ * given about a third of the room the stepper actually takes and would run its
+ * controls off the edge of the figure rather than folding.
+ * @param readings - What the tab showing writes.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The extra width, in pixels.
+ */
+export function projectionUnwrittenRoom(
+  readings: readonly ProjectionReading[],
+  metrics: OverlayMetrics,
+): number {
+  let extra = 0;
+  for (const reading of readings) {
+    if (reading.stepper === true) {
+      extra += 2 * metrics.buttonSize + 2 * metrics.gap;
+    }
+  }
+  return extra;
+}
+
+/**
+ * The colours the map is painting the groups in, for the swatch glyph.
+ *
+ * Empty while the colour stands for nothing, so a bar that says `Nothing`
+ * does not carry a row of dots contradicting it.
+ * @param options - What the figure is showing.
+ * @param groups - The groups as every figure draws them.
+ * @returns The colours, in the order the figure draws them.
+ */
+function projectionGroupColors(
+  options: ProjectionOptions,
+  groups: ResolvedProjectionGroups,
+): readonly string[] {
+  if (options.colorBy !== 'group') return NO_COLORS;
+  const colors: string[] = [];
+  for (const entry of groups.entries) colors.push(entry.color);
+  return colors;
+}
+
+/**
+ * What the map writes: what the colour stands for, and how wide the outlines
+ * are drawn.
+ *
+ * The two switches that write names on the picture are not here. A switch has
+ * no value to read out — it is thrown or it is not — so it rides the bar as a
+ * glyph, like the question mark and the cog, and is counted in the room the
+ * bar keeps for those rather than in the words it writes.
+ * @param copy - The words the viewer writes.
+ * @param options - What the figure is showing.
+ * @param groups - The groups as every figure draws them.
+ * @returns The two readings.
+ */
+function mapReadings(
+  copy: ProjectionCopy,
+  options: ProjectionOptions,
+  groups: ResolvedProjectionGroups,
+): readonly ProjectionReading[] {
+  const { bar, help } = copy;
+  const colored = options.colorBy === 'group';
+  const coverage = ellipseCoverageText(options.ellipse);
+  return [
+    {
+      key: bar.key.colorBy,
+      label: help.colorBy.title,
+      value: colored ? groups.label : bar.uncoloured,
+      swatches: projectionGroupColors(options, groups),
+    },
+    {
+      key: bar.key.ellipse,
+      label: help.ellipse.title,
+      value: coverage === '' ? bar.noOutlines : coverage,
+    },
+  ];
+}
+
+/** No colours at all, which is what an uncoloured map paints. */
+const NO_COLORS: readonly string[] = [];

package/src/projection/ui/projectionBarSlots.tsx

@@ -0,0 +1,139 @@
+import type { ReactNode } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import { ProjectionMapControls } from './ProjectionMapControls.tsx';
+import { ProjectionMapMore } from './ProjectionMapMore.tsx';
+import { ProjectionPairsControls } from './ProjectionPairsControls.tsx';
+import { ProjectionPairsMore } from './ProjectionPairsMore.tsx';
+import { ProjectionSharesControls } from './ProjectionSharesControls.tsx';
+import { ProjectionSharesMore } from './ProjectionSharesMore.tsx';
+import { ProjectionVariablesControls } from './ProjectionVariablesControls.tsx';
+import { ProjectionVariablesMore } from './ProjectionVariablesMore.tsx';
+import type { ProjectionReading } from './projectionBarReadings.ts';
+import type { ProjectionMapView } from './projectionMapView.ts';
+import {
+  projectionPairsInfo,
+  projectionSharesInfo,
+  projectionVariablesInfo,
+} from './projectionTabInfo.ts';
+import type { ProjectionModels } from './projectionTabModels.ts';
+
+/** The three things one tab puts in the bar. */
+export interface ProjectionBarSlots {
+  /** The settings of the tab showing, written to the rung the bar is on. */
+  end: ReactNode;
+  /** What waits behind the cog; nothing at all draws no cog. */
+  more: ReactNode;
+  /** What the question mark hands back; empty draws no question mark. */
+  info: string;
+}
+
+/** What the tab showing is asked for, to fill the bar with. */
+export interface ProjectionBarSlotsInput {
+  /** The tab showing. */
+  tab: ProjectionTab;
+  /** What the run produced. */
+  result: ProjectionResult;
+  /** The words the viewer writes. */
+  copy: ProjectionCopy;
+  /** The two figures the bar explains. */
+  models: ProjectionModels;
+  /** The map's frame and the buttons that change it. */
+  map: ProjectionMapView;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The groups as every figure draws them. */
+  groups: ResolvedProjectionGroups;
+  /** The selected rows, as indices. */
+  selected: readonly number[];
+  /** Width of the viewer, in pixels. */
+  width: number;
+  /** What the settings of the tab showing currently read. */
+  readings: readonly ProjectionReading[];
+  /** How much of itself the bar is writing at this width. */
+  tier: OverlayTier;
+  /** Called with only the options that changed. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+}
+
+/**
+ * The controls and the explanation of the tab showing.
+ *
+ * Each tab writes on the bar the one or two settings a reader of that tab
+ * actually looks at, and hands its whole panel of settings to the cog. What
+ * the rung decides is how much of the bar's settings is written — never which
+ * of them the reader is offered, because a control that has disappeared is a
+ * control the reader concludes the figure does not have.
+ * @param input - See {@link ProjectionBarSlotsInput}.
+ * @returns See {@link ProjectionBarSlots}.
+ */
+export function projectionBarSlots(
+  input: ProjectionBarSlotsInput,
+): ProjectionBarSlots {
+  const { tab, result, copy, models, map, readings, tier } = input;
+  const { options, groups, selected, width, onChange } = input;
+
+  const hasGroups = groups.entries.length > 0;
+  const colored = options.colorBy === 'group' && hasGroups;
+  const shared = { options, onChange, copy, groupLabel: groups.label };
+
+  if (tab === 'pairs') {
+    const pairs = {
+      ...shared,
+      hasGroups,
+      axisCount: result.axes.length,
+      width,
+    };
+    return {
+      end: <ProjectionPairsControls {...pairs} tier={tier} />,
+      more: <ProjectionPairsMore {...pairs} />,
+      info: projectionPairsInfo(copy, groups.label, colored),
+    };
+  }
+  if (tab === 'variables') {
+    const variables = {
+      options,
+      copy,
+      onChange,
+      axisCount: result.axes.length,
+      canShowEffect: result.loadings?.mean !== undefined,
+      canRescale: result.loadings?.scales !== undefined,
+      canPickSample: selected.length === 1,
+      continuous: models.profiles?.axis.kind === 'continuous',
+    };
+    return {
+      end: <ProjectionVariablesControls {...variables} tier={tier} />,
+      more: <ProjectionVariablesMore {...variables} />,
+      info: projectionVariablesInfo(models.profiles, copy, models.sampleName),
+    };
+  }
+  if (tab === 'shares') {
+    const shares = { options, copy, onChange };
+    return {
+      end: <ProjectionSharesControls {...shares} tier={tier} />,
+      more: <ProjectionSharesMore {...shares} />,
+      info: projectionSharesInfo(models.shares, copy),
+    };
+  }
+
+  const forMap = {
+    ...shared,
+    result,
+    hasGroups,
+    selectedCount: selected.length,
+    onZoomToSelection: map.zoomToSelection,
+    onResetView: map.resetView,
+    onClearSelection: map.clearSelection,
+  };
+  return {
+    end: <ProjectionMapControls {...forMap} readings={readings} tier={tier} />,
+    more: <ProjectionMapMore {...forMap} />,
+    info: map.chrome.caption,
+  };
+}

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/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/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;
+}