react-cheminfo 0.9.0 → 0.10.0

package/src/projection/ui/ProjectionMapControls.tsx

@@ -0,0 +1,271 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import type { OverlayChipSetting } from '../../overlay/ui/OverlayChip.tsx';
+import { OverlayChip } from '../../overlay/ui/OverlayChip.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
+import { OverlayValueMenu } from '../../overlay/ui/OverlayValueMenu.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionColorBy,
+  ProjectionOptions,
+} from '../core/projectionOptions.ts';
+
+import type { ProjectionReading } from './projectionBarReadings.ts';
+import {
+  ellipseChoices,
+  ellipseKey,
+  ellipseSize,
+} from './projectionEllipse.ts';
+import {
+  projectionColourChoices,
+  projectionOutlineChoices,
+} from './projectionMapChoices.ts';
+
+/** What the map's controls are drawn from, wherever in the bar they sit. */
+export interface ProjectionMapControlsProps {
+  /** What the map is showing, already resolved against the result. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** What the set of groups is called, which is what `Colour by` offers. */
+  groupLabel: string;
+  /**
+   * Whether the samples carry groups at all. Without them the colour and the
+   * outlines stand for nothing, so their controls are greyed rather than
+   * removed: a reader who cannot find a control assumes the figure has none.
+   * @default false
+   */
+  hasGroups?: boolean;
+  /**
+   * What the two settings currently read, with the figure's own colours. They
+   * are built once for the bar and handed down rather than spelled again here,
+   * so the chip can never write a value the fold was not measured against.
+   * @default [] — nothing is written, which is what the panel behind the cog
+   * wants
+   */
+  readings?: readonly ProjectionReading[];
+  /**
+   * How much of itself the bar is writing.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+}
+
+/**
+ * The map settings a reader changes while looking at the picture.
+ *
+ * They are the ones a reader who has never met a component still has an
+ * opinion about — what the colour means, whether the groups are ringed, and
+ * whether the picture writes the names — while the axes, the dot size and the
+ * gestures belong to somebody who already knows what they are looking for and
+ * wait behind the cog.
+ *
+ * The two names are switches rather than menus because they are the settings a
+ * reader throws and unthrows while reading rather than choosing once: a map of
+ * forty groups needs its crowds named, and a reader who has just found an
+ * outlier wants its name for as long as it takes to write it down.
+ *
+ * The first two are written as their values rather than as captions beside
+ * boxes: the name of a setting is read once, on the first visit, and its value
+ * is read every time the figure is looked at, so the bar says `Species` and
+ * `95%` and leaves `Colour by` and `Group outlines` to the pointer and the
+ * menu. Once the figure is too narrow to carry both, they gather into one chip
+ * that still reads them — a cog there would tell the reader nothing about how
+ * the picture in front of them is drawn.
+ *
+ * The two switches never gather. A switch has no value to write, so it is
+ * already as small as it can be drawn, and it stays a glyph on the bar at every
+ * width — beside the question mark and the cog, which are the same shape for
+ * the same reason.
+ * @param props - See {@link ProjectionMapControlsProps}.
+ * @returns The controls.
+ */
+export function ProjectionMapControls(
+  props: ProjectionMapControlsProps,
+): ReactElement {
+  const { options, onChange, copy, groupLabel, hasGroups = false } = props;
+  const { readings = NO_READINGS, tier = 'full' } = props;
+  const { bar, help } = copy;
+
+  const uncoloured = !hasGroups || options.colorBy === 'none';
+  const settings = (
+    <MapSettings
+      options={options}
+      onChange={onChange}
+      copy={copy}
+      groupLabel={groupLabel}
+      hasGroups={hasGroups}
+    />
+  );
+
+  const names = (
+    <>
+      <OverlayToggle
+        label={bar.switches.showGroupLabels}
+        help={help.showGroupLabels}
+        icon={GROUP_LABELS_GLYPH}
+        hideLabel
+        checked={options.showGroupLabels}
+        disabled={uncoloured}
+        onChange={(showGroupLabels) => onChange({ showGroupLabels })}
+      />
+      <OverlayToggle
+        label={bar.switches.showIds}
+        help={help.showIds}
+        icon={IDS_GLYPH}
+        hideLabel
+        checked={options.showIds}
+        onChange={(showIds) => onChange({ showIds })}
+      />
+    </>
+  );
+
+  if (tier === 'chip' || tier === 'tiny') {
+    return (
+      <>
+        <OverlayChip
+          label={bar.settings}
+          settings={chipSettings(readings)}
+          disabled={!hasGroups}
+        >
+          {settings}
+        </OverlayChip>
+        {names}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <OverlayValueMenu<ProjectionColorBy>
+        label={help.colorBy.title}
+        keyWord={bar.key.colorBy}
+        showKey={tier === 'full'}
+        value={options.colorBy}
+        swatches={swatchesOf(readings)}
+        disabled={!hasGroups}
+        disabledReason={NO_GROUPS_REASON}
+        options={projectionColourChoices(groupLabel, bar.uncoloured)}
+        onChange={(colorBy) => onChange({ colorBy })}
+      />
+      <OverlayValueMenu
+        label={help.ellipse.title}
+        keyWord={bar.key.ellipse}
+        showKey={tier === 'full'}
+        value={ellipseKey(options.ellipse)}
+        disabled={uncoloured}
+        disabledReason={UNCOLOURED_REASON}
+        options={projectionOutlineChoices(options, bar.noOutlines)}
+        onChange={(value) => onChange({ ellipse: ellipseSize(value) })}
+      />
+      {names}
+    </>
+  );
+}
+
+/**
+ * What the chip reads out, which is every setting spelled in full.
+ * @param readings - What the settings currently read.
+ * @returns The chip's own settings.
+ */
+function chipSettings(
+  readings: readonly ProjectionReading[],
+): readonly OverlayChipSetting[] {
+  const settings: OverlayChipSetting[] = [];
+  for (const reading of readings) {
+    settings.push({
+      label: reading.label,
+      value: reading.value,
+      swatches: reading.swatches,
+    });
+  }
+  return settings;
+}
+
+/**
+ * The figure's own colours, from whichever setting decides them.
+ * @param readings - What the settings currently read.
+ * @returns The colours, or nothing where the map is uncoloured.
+ */
+function swatchesOf(
+  readings: readonly ProjectionReading[],
+): readonly string[] | undefined {
+  for (const reading of readings) {
+    const { swatches } = reading;
+    if (swatches !== undefined && swatches.length > 0) return swatches;
+  }
+  return undefined;
+}
+
+/** What the captioned pair behind the chip is drawn from. */
+interface MapSettingsProps {
+  /** What the map is showing, already resolved against the result. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the panel writes. */
+  copy: ProjectionCopy;
+  /** What the set of groups is called. */
+  groupLabel: string;
+  /** Whether the samples carry groups at all. */
+  hasGroups: boolean;
+}
+
+/**
+ * The same settings with their captions, for the panel the chip opens.
+ *
+ * They are the full controls rather than a reduced set: a reader who has
+ * opened the chip has room for the words, and the sentence `95% of samples`
+ * is the one place the figure explains what its outlines actually cover.
+ * @param props - See {@link MapSettingsProps}.
+ * @returns The captioned controls.
+ */
+function MapSettings(props: MapSettingsProps): ReactElement {
+  const { options, onChange, copy, groupLabel, hasGroups } = props;
+  const { bar, help } = copy;
+
+  return (
+    <>
+      <OverlaySegmented<ProjectionColorBy>
+        label={help.colorBy.title}
+        help={help.colorBy}
+        value={options.colorBy}
+        disabled={!hasGroups}
+        options={projectionColourChoices(groupLabel, bar.uncoloured)}
+        onChange={(colorBy) => onChange({ colorBy })}
+      />
+      <OverlaySelect
+        label={help.ellipse.title}
+        help={help.ellipse}
+        value={ellipseKey(options.ellipse)}
+        disabled={!hasGroups || options.colorBy === 'none'}
+        options={ellipseChoices(options.ellipse)}
+        onChange={(value) => onChange({ ellipse: ellipseSize(value) })}
+      />
+    </>
+  );
+}
+
+/** Why the two settings are dead, written as the thing the data is missing. */
+/**
+ * The two glyphs the switches ride as.
+ *
+ * A tag is what a group's name is — one word pinned to a crowd — and a number
+ * plate is the sample's own, which is exactly the difference the two switches
+ * make to the picture. Neither is left to be guessed at: the pointer is given
+ * the switch's name, and a narrow figure spells both out inside the chip.
+ */
+const GROUP_LABELS_GLYPH = 'tag';
+const IDS_GLYPH = 'id-number';
+
+const NO_GROUPS_REASON = 'These samples carry no groups to colour by.';
+const UNCOLOURED_REASON =
+  'Outlines follow the groups, so colour the map by them first.';
+
+/** No readings at all, which is what the panel behind the cog is handed. */
+const NO_READINGS: readonly ProjectionReading[] = [];

package/src/projection/ui/ProjectionMapLegend.tsx

@@ -0,0 +1,70 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayLegendEntry } from '../../overlay/ui/OverlayLegend.tsx';
+import { OverlayLegend } from '../../overlay/ui/OverlayLegend.tsx';
+
+import type { ProjectionMapCloud } from './projectionMapModel.ts';
+import { projectionMapCorner } from './projectionMapModel.ts';
+import {
+  PROJECTION_PLOT_AREA_STYLE,
+  PROJECTION_PLOT_ROOM,
+} from './projectionTabStyles.ts';
+
+/** What {@link ProjectionMapLegend} needs. */
+export interface ProjectionMapLegendProps {
+  /** The one short sentence naming what the colour means here. */
+  title: string;
+  /** What each mark on the map means, in the order they are written. */
+  entries: readonly OverlayLegendEntry[];
+  /** Where every sample sits, in the embedding's own units. */
+  cloud: ProjectionMapCloud;
+  /** The range the horizontal axis covers. */
+  xDomain: readonly [number, number];
+  /** The range the vertical axis covers. */
+  yDomain: readonly [number, number];
+  /** Width of the whole figure, in pixels. */
+  width: number;
+  /** Its height. */
+  height: number;
+}
+
+/**
+ * The key, floating in the emptiest corner of the plot itself.
+ *
+ * It floats because an embedded figure cannot spend a block of somebody else's
+ * page on a card that says three words, and it is held inside the plot
+ * rectangle rather than inside the figure's own box because the strips outside
+ * that rectangle are where the axes are written: a key in the bottom left
+ * corner of the *figure* covers the vertical axis' labels and the name under
+ * the horizontal one, which is a worse trade than covering a few pixels of
+ * empty plot.
+ *
+ * Inside the plot every corner is honest, so the corner is chosen by counting
+ * the dots under each — a key in a fixed corner eventually sits on the one
+ * cluster the reader came for.
+ * @param props - See {@link ProjectionMapLegendProps}.
+ * @returns The key.
+ */
+export function ProjectionMapLegend(
+  props: ProjectionMapLegendProps,
+): ReactElement {
+  const { title, entries, cloud, xDomain, yDomain, width, height } = props;
+
+  const plotWidth =
+    width - PROJECTION_PLOT_ROOM.left - PROJECTION_PLOT_ROOM.right;
+  const plotHeight =
+    height - PROJECTION_PLOT_ROOM.top - PROJECTION_PLOT_ROOM.bottom;
+  const corner = projectionMapCorner(
+    cloud,
+    xDomain,
+    yDomain,
+    Math.max(0, plotWidth),
+    Math.max(0, plotHeight),
+  );
+
+  return (
+    <div style={PROJECTION_PLOT_AREA_STYLE}>
+      <OverlayLegend placement={corner} title={title} entries={entries} />
+    </div>
+  );
+}

package/src/projection/ui/ProjectionMapMore.tsx

@@ -0,0 +1,178 @@
+import type { ReactElement } from 'react';
+
+import { chartAxisTitle } from '../../chart/core/chartLabels.ts';
+import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
+import { OverlayGroup } from '../../overlay/ui/OverlayGroup.tsx';
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import {
+  PROJECTION_PANEL_NAME,
+  PROJECTION_PANEL_SECTION,
+} from '../core/projectionStrings.ts';
+import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
+
+import type { ProjectionMapControlsProps } from './ProjectionMapControls.tsx';
+
+/** What {@link ProjectionMapMore} needs beyond the map's own controls. */
+export interface ProjectionMapMoreProps extends ProjectionMapControlsProps {
+  /** The reduced space the controls apply to; its axes fill the two pickers. */
+  result: ProjectionResult;
+  /**
+   * How many samples are selected, which is what the two selection actions
+   * need before they can do anything.
+   * @default 0
+   */
+  selectedCount?: number;
+  /** Draws the frame around the selected samples. */
+  onZoomToSelection: () => void;
+  /** Puts the frame back around every sample. */
+  onResetView: () => void;
+  /** Empties the selection. */
+  onClearSelection: () => void;
+}
+
+/**
+ * What the map keeps behind the cog: the axes, the dot size, what a drag does,
+ * and the three buttons that act rather than change.
+ *
+ * Five settings is where a flat list stops being scannable, so they are filed
+ * under three headings — the two directions of the picture, the marks drawn in
+ * it, and the one gesture the reader makes over it — and the buttons leave the
+ * list entirely for the foot of the panel. A command sitting in a column of
+ * settings is read as one, and `Clear selection` read as a setting is a press
+ * nobody meant to make.
+ *
+ * The colour, the outlines and the two kinds of name are not here: they are on
+ * the bar itself, where a reader changes them while looking at the picture.
+ *
+ * The two selection actions are greyed rather than hidden while nothing is
+ * picked, so a reader learns that lassoing a crowd is worth doing before they
+ * have done it.
+ * @param props - See {@link ProjectionMapMoreProps}.
+ * @returns The panel behind the cog.
+ */
+export function ProjectionMapMore(props: ProjectionMapMoreProps): ReactElement {
+  const { result, options, onChange, copy, hasGroups = false } = props;
+  const { selectedCount = 0, onZoomToSelection } = props;
+  const { onResetView, onClearSelection } = props;
+  const { action, help, tab } = copy;
+
+  const nothingPicked = selectedCount === 0;
+  const uncoloured = !hasGroups || options.colorBy === 'none';
+
+  return (
+    <OverlayPanel
+      title={tab.map}
+      onReset={() => onChange(PROJECTION_TAB_DEFAULTS.map)}
+      actions={
+        <>
+          <OverlayAction
+            text={action.zoomToSelection}
+            icon="zoom-to-fit"
+            disabled={nothingPicked}
+            onClick={onZoomToSelection}
+          />
+          <OverlayAction
+            text={action.resetView}
+            icon="reset"
+            onClick={onResetView}
+          />
+          <OverlayAction
+            text={action.clearSelection}
+            icon="cross"
+            disabled={nothingPicked}
+            onClick={onClearSelection}
+          />
+        </>
+      }
+    >
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.axes} divider={false}>
+        <OverlaySelect
+          label={PROJECTION_PANEL_NAME.xAxis}
+          help={help.xAxis}
+          value={String(options.xAxis)}
+          options={axisChoices(result, options.yAxis)}
+          onChange={(value) => onChange({ xAxis: Number(value) })}
+        />
+        <OverlaySelect
+          label={PROJECTION_PANEL_NAME.yAxis}
+          help={help.yAxis}
+          value={String(options.yAxis)}
+          options={axisChoices(result, options.xAxis)}
+          onChange={(value) => onChange({ yAxis: Number(value) })}
+        />
+      </OverlayGroup>
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.drawing}>
+        <OverlayNumber
+          label={PROJECTION_PANEL_NAME.pointRadius}
+          help={help.pointRadius}
+          value={options.pointRadius}
+          min={1}
+          max={12}
+          step={0.5}
+          digits={1}
+          unit="px"
+          onChange={(pointRadius) => onChange({ pointRadius })}
+        />
+        <OverlayToggle
+          label={PROJECTION_PANEL_NAME.showGroupMeans}
+          help={help.showGroupMeans}
+          checked={options.showGroupMeans}
+          disabled={uncoloured}
+          onChange={(showGroupMeans) => onChange({ showGroupMeans })}
+        />
+      </OverlayGroup>
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.selecting}>
+        <OverlaySegmented<ScatterSelectionMode>
+          label={PROJECTION_PANEL_NAME.selectMode}
+          help={help.selectMode}
+          value={options.selectMode}
+          options={SELECT_MODE_CHOICES}
+          onChange={(selectMode) => onChange({ selectMode })}
+        />
+      </OverlayGroup>
+    </OverlayPanel>
+  );
+}
+
+const AXIS_TAKEN_NOTE = 'Already drawn on the other axis.';
+
+/**
+ * What a plain drag does. Three words rather than a sentence, because a
+ * segment has room for one word and the line over the plot says the rest while
+ * the drag is under way.
+ */
+const SELECT_MODE_CHOICES: ReadonlyArray<OverlayOption<ScatterSelectionMode>> =
+  [
+    { value: 'replace', label: 'Replace' },
+    { value: 'add', label: 'Add' },
+    { value: 'remove', label: 'Remove' },
+  ];
+
+/**
+ * The axes one picker offers, with the one already drawn kept but unreachable.
+ * @param result - The reduced space being drawn.
+ * @param taken - The axis the other picker is showing.
+ * @returns The choices, in the order the run produced them.
+ */
+function axisChoices(result: ProjectionResult, taken: number): OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (let index = 0; index < result.axes.length; index++) {
+    const axis = result.axes[index];
+    if (axis === undefined) continue;
+    const drawn = index === taken;
+    choices.push({
+      value: String(index),
+      label: chartAxisTitle(axis.name, { share: axis.share }),
+      disabled: drawn,
+      title: drawn ? AXIS_TAKEN_NOTE : undefined,
+    });
+  }
+  return choices;
+}