react-cheminfo 0.22.0 → 0.24.0

package/src/projection/ui/ProjectionReadout.tsx

@@ -19,8 +19,14 @@ interface ProjectionReadoutProps {
   result: ProjectionResult;
   /** Who the rows are. */
   samples: ProjectionSamples;
-  /** The groups as the figure draws them, for the row's group and its colour. */
+  /** The grouping the figure is coloured by, for the colour of the row's group. */
   groups: ResolvedProjectionGroups;
+  /**
+   * Which grouping colours the figure, so the row of that grouping carries the
+   * colour its dot is drawn in.
+   * @default undefined — no row carries a colour
+   */
+  colorBy?: string;
   /** Which axis is drawn horizontally, from 0. */
   xAxis: number;
   /** Which axis is drawn vertically. */
@@ -85,6 +91,7 @@ export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
     result,
     samples,
     groups,
+    colorBy,
     xAxis,
     yAxis,
     zAxis,
@@ -104,8 +111,12 @@ export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
     [xAxis, yAxis, zAxis],
   );
   const rows = useMemo(
-    () => readoutRows(index, result, samples, groups, drawn, formatValue),
-    [drawn, formatValue, groups, index, result, samples],
+    () =>
+      readoutRows(index, result, samples, drawn, formatValue, {
+        groups,
+        colorBy,
+      }),
+    [colorBy, drawn, formatValue, groups, index, result, samples],
   );
 
   return (
@@ -114,7 +125,7 @@ export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
       y={y}
       boxWidth={boxWidth}
       boxHeight={boxHeight}
-      title={samples.ids[index] ?? ''}
+      title={samples.labels?.[index] ?? samples.ids[index] ?? ''}
       rows={rows}
       maxRows={maxRows}
       pinned={pinned}
@@ -128,9 +139,9 @@ function readoutRows(
   index: number,
   result: ProjectionResult,
   samples: ProjectionSamples,
-  groups: ResolvedProjectionGroups,
   drawn: readonly number[],
   formatValue: (value: number) => string,
+  coloured: { groups: ResolvedProjectionGroups; colorBy?: string },
 ): OverlayReadoutRow[] {
   const rows: OverlayReadoutRow[] = [];
   const { axes, scores } = result;
@@ -145,9 +156,18 @@ function readoutRows(
     });
   }
 
-  const group = groups.entries[groups.groupOf[index] ?? -1];
-  if (group !== undefined) {
-    rows.push({ label: groups.label, value: group.label, color: group.color });
+  // Every grouping is written, the one the dots are coloured by with its
+  // colour: a card naming only the colour's group would hide the very
+  // grouping the shapes stand for.
+  const { groups, colorBy } = coloured;
+  for (const grouping of samples.groupings ?? []) {
+    const value = grouping.groups[index];
+    if (value === undefined) continue;
+    const group =
+      grouping.id === colorBy
+        ? groups.entries[groups.groupOf[index] ?? -1]
+        : undefined;
+    rows.push({ label: grouping.label, value, color: group?.color });
   }
 
   if (known && samples.fields !== undefined) {

package/src/projection/ui/ProjectionSpaceControls.tsx

@@ -8,11 +8,11 @@ import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
 import { OverlayValueMenu } from '../../overlay/ui/OverlayValueMenu.tsx';
 import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
-import type {
-  ProjectionColorBy,
-  ProjectionOptions,
-} from '../core/projectionOptions.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { NO_GROUPING } from '../core/projectionOptions.ts';
+import type { ProjectionGrouping } from '../core/projectionSamples.ts';
 
+import { ProjectionColourPicker } from './ProjectionGroupingPickers.tsx';
 import type { ProjectionReading } from './projectionBarReadings.ts';
 import { projectionChipSettings } from './projectionBarReadings.ts';
 import {
@@ -20,7 +20,6 @@ import {
   ellipseKey,
   ellipseSize,
 } from './projectionEllipse.ts';
-import { projectionColourChoices } from './projectionMapChoices.ts';
 import { projectionCloudGestureChoices } from './projectionWordChoices.ts';
 
 /** What the cloud's controls are drawn from, wherever in the bar they sit. */
@@ -31,14 +30,11 @@ export interface ProjectionSpaceControlsProps {
   onChange: (patch: Partial<ProjectionOptions>) => void;
   /** The words the bar writes, already merged over the defaults. */
   copy: ProjectionCopy;
-  /** What the set of groups is called. */
-  groupLabel: string;
   /**
-   * Whether the samples carry groups at all. Without them the shells stand for
+   * Every grouping the samples carry. Without one the shells stand for
    * nothing, so their control is greyed rather than removed.
-   * @default false
    */
-  hasGroups?: boolean;
+  groupings: readonly ProjectionGrouping[];
   /**
    * What the settings currently read, built once for the bar and handed down.
    * @default [] — nothing is written, which is what the cog's panel wants
@@ -71,11 +67,12 @@ export interface ProjectionSpaceControlsProps {
 export function ProjectionSpaceControls(
   props: ProjectionSpaceControlsProps,
 ): ReactElement {
-  const { options, onChange, copy, groupLabel, hasGroups = false } = props;
+  const { options, onChange, copy, groupings } = props;
   const { readings = NO_READINGS, tier = 'full' } = props;
   const { bar, help, outline, reason } = copy;
 
-  const uncoloured = !hasGroups || options.colorBy === 'none';
+  const hasGroups = groupings.length > 0;
+  const uncoloured = !hasGroups || options.colorBy === NO_GROUPING;
   const names = (
     <>
       <OverlayToggle
@@ -109,8 +106,7 @@ export function ProjectionSpaceControls(
             options={options}
             onChange={onChange}
             copy={copy}
-            groupLabel={groupLabel}
-            hasGroups={hasGroups}
+            groupings={groupings}
           />
         </OverlayChip>
         {names}
@@ -151,10 +147,8 @@ interface SpaceSettingsProps {
   onChange: (patch: Partial<ProjectionOptions>) => void;
   /** The words the panel writes. */
   copy: ProjectionCopy;
-  /** What the set of groups is called, which is what `Colour by` offers. */
-  groupLabel: string;
-  /** Whether the samples carry groups at all. */
-  hasGroups: boolean;
+  /** Every grouping the samples carry. */
+  groupings: readonly ProjectionGrouping[];
 }
 
 /**
@@ -163,8 +157,8 @@ interface SpaceSettingsProps {
  * @returns The captioned controls.
  */
 function SpaceSettings(props: SpaceSettingsProps): ReactElement {
-  const { options, onChange, copy, groupLabel, hasGroups } = props;
-  const { bar, help, outline } = copy;
+  const { options, onChange, copy, groupings } = props;
+  const { help, outline } = copy;
 
   return (
     <>
@@ -175,19 +169,18 @@ function SpaceSettings(props: SpaceSettingsProps): ReactElement {
         options={projectionCloudGestureChoices(copy)}
         onChange={(cloudGesture) => onChange({ cloudGesture })}
       />
-      <OverlaySegmented<ProjectionColorBy>
+      <ProjectionColourPicker
         label={help.colorBy.title}
-        help={help.colorBy}
-        value={options.colorBy}
-        disabled={!hasGroups}
-        options={projectionColourChoices(groupLabel, bar.uncoloured)}
-        onChange={(colorBy) => onChange({ colorBy })}
+        options={options}
+        onChange={onChange}
+        copy={copy}
+        groupings={groupings}
       />
       <OverlaySelect
         label={help.ellipse.title}
         help={help.ellipse}
         value={ellipseKey(options.ellipse)}
-        disabled={!hasGroups || options.colorBy === 'none'}
+        disabled={groupings.length === 0 || options.colorBy === NO_GROUPING}
         options={ellipseChoices(options.ellipse, outline, 'space')}
         onChange={(value) => onChange({ ellipse: ellipseSize(value) })}
       />

package/src/projection/ui/ProjectionSpaceMore.tsx

@@ -11,6 +11,7 @@ import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
 import type { ProjectionResult } from '../core/projectionResult.ts';
 import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
 
+import { ProjectionShapePicker } from './ProjectionGroupingPickers.tsx';
 import type { ProjectionSpaceControlsProps } from './ProjectionSpaceControls.tsx';
 import { projectionAxisChoices } from './projectionAxisChoices.ts';
 import {
@@ -35,8 +36,8 @@ interface ProjectionSpaceMoreProps extends ProjectionSpaceControlsProps {
 }
 
 /**
- * What the cloud keeps behind the cog: its three axes, the dot size, and what
- * the two drags do.
+ * What the cloud keeps behind the cog: its three axes, the dot size and shape,
+ * and what the two drags do.
  *
  * It is the map's panel with one picker more and one action fewer. There is no
  * "zoom to selection" here, because a box has no frame to draw round a crowd:
@@ -49,7 +50,7 @@ interface ProjectionSpaceMoreProps extends ProjectionSpaceControlsProps {
 export function ProjectionSpaceMore(
   props: ProjectionSpaceMoreProps,
 ): ReactElement {
-  const { result, options, onChange, copy } = props;
+  const { result, options, onChange, copy, groupings } = props;
   const { selectedCount = 0, onResetView, onClearSelection } = props;
   const { action, help, panel, reason, tab } = copy;
 
@@ -122,6 +123,14 @@ export function ProjectionSpaceMore(
           unit="px"
           onChange={(pointRadius) => onChange({ pointRadius })}
         />
+        <ProjectionShapePicker
+          label={panel.name.shapeBy}
+          options={options}
+          onChange={onChange}
+          copy={copy}
+          groupings={groupings}
+          rows={result.scores.rows}
+        />
       </OverlayGroup>
       <OverlayGroup label={panel.section.handling}>
         <OverlaySegmented<CloudGesture>

package/src/projection/ui/ProjectionSpaceTab.tsx

@@ -7,8 +7,12 @@ import type { OrbitCamera } from '../../scatter3d/core/orbitCamera.ts';
 import { ScatterCloud } from '../../scatter3d/ui/ScatterCloud.tsx';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { NO_GROUPING } from '../core/projectionOptions.ts';
 import type { ProjectionResult } from '../core/projectionResult.ts';
-import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type {
+  ResolvedProjectionGroups,
+  ResolvedProjectionShapes,
+} from '../core/projectionSamples.ts';
 
 import type { SelectionReport } from './ProjectionMapCaption.tsx';
 import { ProjectionMapCaption } from './ProjectionMapCaption.tsx';
@@ -19,6 +23,7 @@ import {
   projectionAxisTitle,
   projectionMapCloud,
   projectionScatterGroups,
+  projectionScatterShapes,
 } from './projectionMapModel.ts';
 import { MINIMUM_SHELL_POINTS } from './projectionSpaceModel.ts';
 
@@ -26,8 +31,16 @@ import { MINIMUM_SHELL_POINTS } from './projectionSpaceModel.ts';
 interface ProjectionSpaceTabProps {
   /** What the run produced, whatever produced it. */
   result: ProjectionResult;
-  /** The groups, resolved once by the viewer so every tab colours alike. */
+  /**
+   * The grouping the dots are coloured by, resolved once by the viewer so every
+   * tab colours alike; empty while the colour stands for nothing.
+   */
   groups: ResolvedProjectionGroups;
+  /**
+   * The grouping the dots are shaped by, resolved once by the viewer.
+   * @default null — every dot is a disc
+   */
+  shapes?: ResolvedProjectionShapes | null;
   /** What the cloud is showing, already resolved against `result`. */
   options: ProjectionOptions;
   /** The words the cloud writes, already merged over the defaults. */
@@ -38,7 +51,7 @@ interface ProjectionSpaceTabProps {
    * What each sample is called, in the score matrix's row order.
    * @default undefined — the setting has nothing to write and draws nothing
    */
-  ids?: readonly string[];
+  names?: readonly string[];
   /** Width of the figure, in pixels. */
   width: number;
   /** Height of the figure, in pixels. */
@@ -113,7 +126,8 @@ export function ProjectionSpaceTab(
   props: ProjectionSpaceTabProps,
 ): ReactElement {
   const { result, groups, options, copy, chrome, width, height } = props;
-  const { ids, selected, report = null, camera, zoom } = props;
+  const { names, shapes = null, selected } = props;
+  const { report = null, camera, zoom } = props;
   const { onCameraChange, onZoomChange, wheelZoom } = props;
   const { onSelectionChange, onHoverChange, hoverCard, testId } = props;
   const { onPointDoubleClick } = props;
@@ -131,7 +145,8 @@ export function ProjectionSpaceTab(
     [scores, zAxis],
   );
 
-  const colored = colorBy === 'group' && groups.entries.length > 0;
+  const shapeList = useMemo(() => projectionScatterShapes(shapes), [shapes]);
+  const colored = colorBy !== NO_GROUPING && groups.entries.length > 0;
 
   return (
     <div style={{ position: 'relative' }} data-testid={testId}>
@@ -146,10 +161,12 @@ export function ProjectionSpaceTab(
         zLabel={axisName(result, zAxis)}
         groupOf={colored ? groups.groupOf : undefined}
         groups={colored ? projectionScatterGroups(groups) : undefined}
+        shapeOf={shapes?.shapeOf}
+        shapes={shapeList}
         ellipsoid={colored ? shells : null}
         ellipsoidMinimumPoints={MINIMUM_SHELL_POINTS}
         showGroupLabels={colored && showGroupLabels}
-        pointLabels={showIds ? ids : undefined}
+        pointLabels={showIds ? names : undefined}
         pointRadius={pointRadius}
         outlinedFrom={fittedCount}
         selected={selected}

package/src/projection/ui/ProjectionViewer.tsx

@@ -64,6 +64,7 @@ export function ProjectionViewer(props: ProjectionViewerProps): ReactElement {
     result,
     copy,
     groups: state.groups,
+    shapes: state.shapes,
     options: state.options,
     selected: state.selected,
     onSettle: state.settleSelection,

package/src/projection/ui/projectionBarReadings.ts

@@ -13,6 +13,7 @@ import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
 import type { OverlayChipSetting } from '../../overlay/ui/OverlayChip.tsx';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { NO_GROUPING } from '../core/projectionOptions.ts';
 import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
 import type { ProjectionTab } from '../core/projectionTabs.ts';
 
@@ -48,7 +49,10 @@ interface ProjectionReadingsInput {
   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. */
+  /**
+   * The grouping the figures are coloured by, whose colours the map writes;
+   * empty while nothing colours them.
+   */
   groups: ResolvedProjectionGroups;
 }
 
@@ -83,10 +87,9 @@ export function projectionBarReadings(
     ];
   }
   if (tab === 'space') {
-    const coverage =
-      options.colorBy === 'group' && groups.entries.length > 0
-        ? ellipseCoverageText(options.ellipse, 'space')
-        : '';
+    const coverage = isColoured(options, groups)
+      ? ellipseCoverageText(options.ellipse, 'space')
+      : '';
     return [
       {
         key: bar.key.cloudGesture,
@@ -163,14 +166,14 @@ export function projectionChipSettings(
  * 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.
+ * @param groups - The grouping the figures are coloured by.
  * @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;
+  if (!isColoured(options, groups)) return NO_COLORS;
   const colors: string[] = [];
   for (const entry of groups.entries) colors.push(entry.color);
   return colors;
@@ -195,7 +198,7 @@ function mapReadings(
   groups: ResolvedProjectionGroups,
 ): readonly ProjectionReading[] {
   const { bar, help } = copy;
-  const colored = options.colorBy === 'group';
+  const colored = isColoured(options, groups);
   const coverage = ellipseCoverageText(options.ellipse);
   return [
     {
@@ -212,5 +215,18 @@ function mapReadings(
   ];
 }
 
+/**
+ * Whether the colour stands for a grouping at all.
+ * @param options - What the figure is showing.
+ * @param groups - The grouping the figures are coloured by.
+ * @returns `true` when the dots are painted by group.
+ */
+function isColoured(
+  options: ProjectionOptions,
+  groups: ResolvedProjectionGroups,
+): boolean {
+  return options.colorBy !== NO_GROUPING && groups.entries.length > 0;
+}
+
 /** No colours at all, which is what an uncoloured map paints. */
 const NO_COLORS: readonly string[] = [];

package/src/projection/ui/projectionBarSlots.tsx

@@ -4,7 +4,10 @@ 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 {
+  ProjectionGrouping,
+  ResolvedProjectionGroups,
+} from '../core/projectionSamples.ts';
 import type { ProjectionTab } from '../core/projectionTabs.ts';
 
 import { ProjectionMapControls } from './ProjectionMapControls.tsx';
@@ -50,8 +53,10 @@ interface ProjectionBarSlotsInput {
   map: ProjectionMapView;
   /** Every option, already made safe against the result. */
   options: ProjectionOptions;
-  /** The groups as every figure draws them. */
+  /** The grouping the figures are coloured by; empty while nothing colours them. */
   groups: ResolvedProjectionGroups;
+  /** Every grouping the samples carry, which the pickers choose between. */
+  groupings: readonly ProjectionGrouping[];
   /** The selected rows, as indices. */
   selected: readonly number[];
   /** Width of the viewer, in pixels. */
@@ -79,16 +84,14 @@ export function projectionBarSlots(
   input: ProjectionBarSlotsInput,
 ): ProjectionBarSlots {
   const { tab, result, copy, models, map, readings, tier } = input;
-  const { options, groups, selected, width, onChange } = input;
+  const { options, groups, groupings, selected, width, onChange } = input;
 
-  const hasGroups = groups.entries.length > 0;
-  const colored = options.colorBy === 'group' && hasGroups;
-  const shared = { options, onChange, copy, groupLabel: groups.label };
+  const colored = groups.entries.length > 0;
+  const shared = { options, onChange, copy, groupings };
 
   if (tab === 'pairs') {
     const pairs = {
       ...shared,
-      hasGroups,
       axisCount: result.axes.length,
       width,
     };
@@ -102,7 +105,6 @@ export function projectionBarSlots(
     const space = {
       ...shared,
       result,
-      hasGroups,
       selectedCount: selected.length,
       onResetView: map.resetSpaceView,
       onClearSelection: map.clearSelection,
@@ -144,7 +146,6 @@ export function projectionBarSlots(
   const forMap = {
     ...shared,
     result,
-    hasGroups,
     selectedCount: selected.length,
     onZoomToSelection: map.zoomToSelection,
     onResetView: map.resetView,

package/src/projection/ui/projectionMapChoices.ts

@@ -1,5 +1,5 @@
 /**
- * What the map's two settings offer, in the two lengths the bar needs.
+ * What the map's settings offer, in the 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
@@ -9,10 +9,10 @@
 
 import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
-import type {
-  ProjectionColorBy,
-  ProjectionOptions,
-} from '../core/projectionOptions.ts';
+import { resolveProjectionShapes } from '../core/projectionGroupings.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { NO_GROUPING } from '../core/projectionOptions.ts';
+import type { ProjectionGrouping } from '../core/projectionSamples.ts';
 
 import {
   ellipseChoices,
@@ -21,19 +21,76 @@ import {
 } from './projectionEllipse.ts';
 
 /**
- * What the colour may stand for.
- * @param groupLabel - What the set of groups is called.
+ * What the colour may stand for: each grouping the samples carry, or nothing.
+ * @param groupings - The groupings the samples carry.
  * @param uncoloured - What "the colour stands for nothing" reads.
- * @returns The two choices.
+ * @returns The choices, in the order the groupings were handed in.
  */
 export function projectionColourChoices(
-  groupLabel: string,
+  groupings: readonly ProjectionGrouping[],
   uncoloured: string,
-): ReadonlyArray<OverlayOption<ProjectionColorBy>> {
-  return [
-    { value: 'group', label: groupLabel },
-    { value: 'none', label: uncoloured },
-  ];
+): readonly OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (const { id, label } of groupings) choices.push({ value: id, label });
+  choices.push({ value: NO_GROUPING, label: uncoloured });
+  return choices;
+}
+
+/**
+ * What the shape may stand for: each grouping the samples carry, or nothing.
+ *
+ * A grouping the colour already stands for is kept in the list but greyed, as
+ * is one of more groups than there are shapes, so the reader sees why it cannot
+ * be picked rather than wondering where it went.
+ * @param groupings - The groupings the samples carry.
+ * @param options - What the figure is showing, whose colour is taken.
+ * @param rows - How many rows there are, which is what a grouping is cut over.
+ * @param copy - The words the viewer writes.
+ * @returns The choices, in the order the groupings were handed in.
+ */
+export function projectionShapeChoices(
+  groupings: readonly ProjectionGrouping[],
+  options: ProjectionOptions,
+  rows: number,
+  copy: ProjectionCopy,
+): readonly OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (const grouping of groupings) {
+    const { id, label } = grouping;
+    const reason =
+      id === options.colorBy
+        ? copy.reason.shapeIsColour
+        : resolveProjectionShapes(grouping, rows) === null
+          ? copy.reason.tooManyShapes
+          : undefined;
+    choices.push({
+      value: id,
+      label,
+      disabled: reason !== undefined,
+      title: reason,
+    });
+  }
+  choices.push({ value: NO_GROUPING, label: copy.bar.unshaped });
+  return choices;
+}
+
+/**
+ * What changes when the colour is given to another grouping.
+ *
+ * A grouping drawn as the shape that is picked for the colour swaps places
+ * with it rather than being dropped, so the reader never loses one of the two
+ * groupings they were comparing by trading them round.
+ * @param options - What the figure is showing.
+ * @param colorBy - The grouping picked for the colour.
+ * @returns The options that change.
+ */
+export function projectionColourPatch(
+  options: ProjectionOptions,
+  colorBy: string,
+): Partial<ProjectionOptions> {
+  return colorBy !== NO_GROUPING && colorBy === options.shapeBy
+    ? { colorBy, shapeBy: options.colorBy }
+    : { colorBy };
 }
 
 /**