react-cheminfo 0.10.0 → 0.11.0

package/src/download/core/index.ts

@@ -21,11 +21,19 @@ export type {
   FigureSvgDocumentOptions,
 } from './figureSvgDocument.ts';
 export { figureSvgDocument } from './figureSvgDocument.ts';
+export type {
+  FigureLegendCard,
+  FigureLegendMark,
+  FigureLegendPrint,
+  FigureLegendText,
+} from './figureLegend.ts';
+export { figureLegendMarkup } from './figureLegend.ts';
 export type { FigureBounds } from './figureTarget.ts';
 export {
   figureBounds,
   figureDrawings,
   figureElement,
+  figureLegends,
   figureSize,
 } from './figureTarget.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';

package/src/ecosystem/core/sites.ts

@@ -7,6 +7,7 @@ export type SiteId =
   | 'smiles'
   | 'chemcalc'
   | 'nmrium'
+  | 'metabo'
   | 'derepflow'
   | 'surge'
   | 'tex'
@@ -133,6 +134,19 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     brandAlt: '#2b143e',
     mark: { plate: '#2b143e', accent: '#ea580c' },
   },
+  {
+    id: 'metabo',
+    // Not `.cheminfo`: the second half of a one-word name is the domain the
+    // site actually lives at, and this one is a sibling of NMRium rather than
+    // of the cheminfo tools.
+    name: { lead: 'metabo', alt: 'nmrium', dot: true },
+    host: 'metabo.nmrium.com',
+    repository: 'https://github.com/cheminfo/metabo',
+    tagline: 'Turn a batch of NMR spectra into a map of your samples.',
+    brand: '#4d7c0f',
+    brandAlt: '#b91c1c',
+    mark: { plate: '#4d7c0f', accent: '#b91c1c' },
+  },
   {
     id: 'derepflow',
     name: { lead: 'Derep', alt: 'Flow' },

package/src/ecosystem/ui/glyphs.tsx

@@ -148,6 +148,32 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       />
     </g>
   ),
+  // Two groups of samples with the outline that holds each: the picture the
+  // tool exists to draw. One is drawn and one is filled rather than both
+  // outlined, because two rings crossing close up into a blob at 16 px —
+  // checked at 16, 20, 24, 32 and 64 before this was settled on.
+  metabo: (accent) => (
+    <>
+      <ellipse
+        cx="12"
+        cy="12.5"
+        rx="5.8"
+        ry="9"
+        fill="none"
+        stroke="#ffffff"
+        strokeWidth="3"
+        transform="rotate(-32 12 12.5)"
+      />
+      <ellipse
+        cx="20.5"
+        cy="20"
+        rx="5.4"
+        ry="8.6"
+        fill={accent}
+        transform="rotate(32 20.5 20)"
+      />
+    </>
+  ),
   // One formula branching into every structure it can be.
   surge: (alt) => (
     <>

package/src/overlay/ui/OverlayLegend.tsx

@@ -103,7 +103,13 @@ export function OverlayLegend(props: OverlayLegendProps): ReactElement {
   const written = folded === 0 ? entries : entries.slice(0, room - 1);
 
   return (
-    <div style={overlayCardStyle(placement, metrics)} data-testid={testId}>
+    <div
+      style={overlayCardStyle(placement, metrics)}
+      // The key is chrome, since its entries are pressed, but it is part of
+      // the picture all the same: the export redraws it into the saved file.
+      data-figure="legend"
+      data-testid={testId}
+    >
       <div style={overlayGroundStyle(awake ? 1 : RESTING_OPACITY, busy)} />
       <div
         role="group"

package/src/projection/core/projectionCopy.ts

@@ -29,6 +29,8 @@ export interface ProjectionCopy {
   intro: {
     /** The map. */
     map: string;
+    /** The cloud. */
+    space: string;
     /** The pair grid. */
     pairs: string;
     /**
@@ -49,6 +51,8 @@ export interface ProjectionCopy {
   legend: {
     /** The map. Carries `{groups}` and `{coverage}`. */
     map: string;
+    /** The cloud. Carries `{groups}` and `{coverage}`. */
+    space: string;
     /** The map with no outlines. Carries `{groups}`. */
     mapNoEllipse: string;
     /** The pair grid. Carries `{groups}`. */
@@ -126,6 +130,7 @@ export interface ProjectionCopy {
 export const PROJECTION_COPY: ProjectionCopy = {
   tab: {
     map: 'Map',
+    space: 'Map in 3D',
     pairs: 'Every pair',
     variables: 'What differs',
     shares: 'How much each explains',
@@ -134,6 +139,8 @@ export const PROJECTION_COPY: ProjectionCopy = {
   bar: PROJECTION_BAR_WORDS,
   intro: {
     map: 'Each dot is one sample. Dots that sit together are alike; dots far apart are the ones that differ most. The two axes are the strongest patterns of difference, called components.',
+    space:
+      'The same map with a third component, in a box you can turn. Two groups that sit on top of each other on the flat map often come apart as soon as the box moves. The frame says which axis is which; the numbers are in the card you get by pointing at a dot.',
     pairs:
       'The same map drawn for every pair of components. A grouping the first two miss often shows up in another pair.',
     variablesContinuous:
@@ -149,6 +156,8 @@ export const PROJECTION_COPY: ProjectionCopy = {
   },
   legend: {
     map: 'Colour = {groups}. Each outline covers about {coverage} of that group, assuming the group is roughly bell-shaped.',
+    space:
+      'Colour = {groups}. Each shell holds about {coverage} of that group, assuming the group is roughly bell-shaped. A shell has to hold a sample in three directions at once, so it is wider than the outline the same share draws on the flat map.',
     mapNoEllipse: 'Colour = {groups}.',
     pairs:
       'Colour = {groups}. The strip along the diagonal shows how the samples spread out along that component on its own.',

package/src/projection/core/projectionOptions.ts

@@ -1,5 +1,6 @@
 import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
 import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
 
 import type { ProjectionResult } from './projectionResult.ts';
 import { drawableVariablesView } from './variablesView.ts';
@@ -33,6 +34,17 @@ export interface ProjectionOptions {
    * @default 1
    */
   yAxis: number;
+  /**
+   * Which axis runs away from the reader, on the cloud alone. The map and the
+   * pair grid never read it, so moving it leaves them where they were.
+   * @default 2
+   */
+  zAxis: number;
+  /**
+   * What a drag over the cloud does: turn the box, or draw a lasso.
+   * @default 'turn'
+   */
+  cloudGesture: CloudGesture;
   /**
    * What decides a dot's colour.
    * @default 'group'
@@ -123,6 +135,8 @@ export type ProjectionOptionId = keyof ProjectionOptions;
 export const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
   xAxis: 0,
   yAxis: 1,
+  zAxis: 2,
+  cloudGesture: 'turn',
   colorBy: 'group',
   ellipse: { kind: 'coverage', probability: 0.95 },
   pointRadius: 3.5,
@@ -163,14 +177,21 @@ export function resolveProjectionOptions(
   const axisCount = result.axes.length;
   const lastAxis = Math.max(0, axisCount - 1);
   const xAxis = clampIndex(pick(overrides, 'xAxis'), lastAxis);
+  const yAxis = apart(
+    clampIndex(pick(overrides, 'yAxis'), lastAxis),
+    xAxis,
+    lastAxis,
+  );
 
   return {
     xAxis,
-    yAxis: apart(
-      clampIndex(pick(overrides, 'yAxis'), lastAxis),
-      xAxis,
+    yAxis,
+    zAxis: apartFrom(
+      clampIndex(pick(overrides, 'zAxis'), lastAxis),
+      [xAxis, yAxis],
       lastAxis,
     ),
+    cloudGesture: pick(overrides, 'cloudGesture'),
     colorBy: pick(overrides, 'colorBy'),
     ellipse: pick(overrides, 'ellipse'),
     pointRadius: atLeast(pick(overrides, 'pointRadius'), 3.5, 0),
@@ -223,6 +244,30 @@ function apart(yAxis: number, xAxis: number, lastAxis: number): number {
   return xAxis > 0 ? xAxis - 1 : Math.min(1, lastAxis);
 }
 
+/**
+ * An axis that is none of the ones already drawn.
+ *
+ * The cloud's third direction has two axes to avoid rather than one, and an
+ * axis drawn against itself in a box is a flat map stood on its edge — worse
+ * than the diagonal line it is on a map, because the reader cannot see from
+ * the picture that it happened.
+ * @param wanted - The axis asked for, already inside the result.
+ * @param taken - The axes already drawn.
+ * @param lastAxis - The highest axis there is.
+ * @returns The axis to draw; the lowest one still free when the wanted one is taken, and the wanted one back when every axis is.
+ */
+function apartFrom(
+  wanted: number,
+  taken: readonly number[],
+  lastAxis: number,
+): number {
+  if (!taken.includes(wanted)) return wanted;
+  for (let axis = 0; axis <= lastAxis; axis++) {
+    if (!taken.includes(axis)) return axis;
+  }
+  return wanted;
+}
+
 function clampCount(
   value: number,
   fallback: number,

package/src/projection/core/projectionStrings.ts

@@ -58,6 +58,14 @@ export const PROJECTION_HELP: Record<ProjectionOptionId, ProjectionHelp> = {
     title: 'Up',
     body: 'Which pattern of difference runs bottom to top.',
   },
+  zAxis: {
+    title: 'Into',
+    body: 'Which pattern of difference runs away from you, into the box. Only the cloud draws it; the map and the pair grid never read it.',
+  },
+  cloudGesture: {
+    title: 'Drag does',
+    body: 'Turning the box and drawing a lasso both want a plain drag, so you say which one it is. Inside a lasso, Shift still adds and Alt still takes away.',
+  },
   colorBy: {
     title: 'Colour by',
     body: 'What a dot’s colour stands for. Colouring by nothing is useful when the groups are what you are trying to find rather than what you already know.',
@@ -137,6 +145,7 @@ export const PROJECTION_HELP: Record<ProjectionOptionId, ProjectionHelp> = {
  */
 export const PROJECTION_SHORT_TAB: Record<ProjectionTab, string> = {
   map: 'Map',
+  space: '3D',
   pairs: 'Pairs',
   variables: 'Differs',
   shares: 'Explains',
@@ -155,6 +164,8 @@ export interface ProjectionBarWords {
     colorBy: string;
     /** In front of how much of a group its outline covers. */
     ellipse: string;
+    /** In front of what a drag over the cloud does. */
+    cloudGesture: string;
     /** In front of how many components the pair grid lays out. */
     pairCount: string;
     /** In front of what the "what differs" panels are drawing. */
@@ -197,6 +208,7 @@ export const PROJECTION_BAR_WORDS: ProjectionBarWords = {
   key: {
     colorBy: 'Colour',
     ellipse: 'Outlines',
+    cloudGesture: 'Drag',
     pairCount: 'Components',
     variablesView: 'Show',
     shareTarget: 'Target',
@@ -228,6 +240,8 @@ export const PROJECTION_BAR_WORDS: ProjectionBarWords = {
 export const PROJECTION_PANEL_NAME: Record<ProjectionOptionId, string> = {
   xAxis: 'Across',
   yAxis: 'Up',
+  zAxis: 'Into',
+  cloudGesture: 'Drag does',
   colorBy: 'Colour by',
   ellipse: 'Outlines',
   pointRadius: 'Dot size',
@@ -260,6 +274,8 @@ export const PROJECTION_PANEL_SECTION = {
   drawing: 'Drawing',
   /** What a drag over the figure does to the selection. */
   selecting: 'Selecting',
+  /** What a drag over the cloud does at all, before the selection hears of it. */
+  handling: 'Handling',
   /** What the panels of the "what differs" tab are measured against. */
   scale: 'Scale',
 } as const;

package/src/projection/core/projectionTabDefaults.ts

@@ -31,6 +31,18 @@ export const PROJECTION_TAB_DEFAULTS: Record<
     showIds: DEFAULT_PROJECTION_OPTIONS.showIds,
     selectMode: DEFAULT_PROJECTION_OPTIONS.selectMode,
   },
+  space: {
+    xAxis: DEFAULT_PROJECTION_OPTIONS.xAxis,
+    yAxis: DEFAULT_PROJECTION_OPTIONS.yAxis,
+    zAxis: DEFAULT_PROJECTION_OPTIONS.zAxis,
+    cloudGesture: DEFAULT_PROJECTION_OPTIONS.cloudGesture,
+    colorBy: DEFAULT_PROJECTION_OPTIONS.colorBy,
+    ellipse: DEFAULT_PROJECTION_OPTIONS.ellipse,
+    pointRadius: DEFAULT_PROJECTION_OPTIONS.pointRadius,
+    showGroupLabels: DEFAULT_PROJECTION_OPTIONS.showGroupLabels,
+    showIds: DEFAULT_PROJECTION_OPTIONS.showIds,
+    selectMode: DEFAULT_PROJECTION_OPTIONS.selectMode,
+  },
   pairs: {
     pairCount: DEFAULT_PROJECTION_OPTIONS.pairCount,
     colorBy: DEFAULT_PROJECTION_OPTIONS.colorBy,

package/src/projection/core/projectionTabs.ts

@@ -1,10 +1,18 @@
 import type { ProjectionAxis, ProjectionResult } from './projectionResult.ts';
 
 /** Which tab of a projection viewer is showing. The ids are stable, so a site may put one in its own URL. */
-export type ProjectionTab = 'map' | 'pairs' | 'variables' | 'shares';
+export type ProjectionTab = 'map' | 'space' | 'pairs' | 'variables' | 'shares';
 
 const PAIRS_MINIMUM_AXES = 3;
 
+/**
+ * How many axes a cloud needs, which is one per direction of the box.
+ *
+ * A run that produced two is not shown a third empty axis: the cloud would be
+ * a flat map stood on its edge, which says less than the map it came from.
+ */
+const SPACE_MINIMUM_AXES = 3;
+
 /**
  * The tabs a result can actually fill.
  *
@@ -32,6 +40,7 @@ export function projectionTabs(
   const tabs: ProjectionTab[] = ['map'];
   const enoughAxes = result.axes.length >= PAIRS_MINIMUM_AXES;
 
+  if (result.axes.length >= SPACE_MINIMUM_AXES) tabs.push('space');
   if (enoughAxes) tabs.push('pairs');
   if (result.loadings !== undefined) tabs.push('variables');
   if (enoughAxes && everyAxisPublishesAShare(result.axes)) tabs.push('shares');

package/src/projection/ui/ProjectionMapTab.tsx

@@ -3,6 +3,7 @@ import { useMemo, useState } from 'react';
 
 import type { ChartViewport } from '../../chart/core/chartViewport.ts';
 import { ScatterPlot } from '../../scatter/ui/ScatterPlot.tsx';
+import type { ScatterPointOpen } from '../../scatter/ui/scatterPlotProps.ts';
 import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
@@ -82,6 +83,11 @@ export interface ProjectionMapTabProps {
    * @default undefined
    */
   onHoverChange?: (index: number) => void;
+  /**
+   * Called when the reader double-clicks a sample.
+   * @default undefined
+   */
+  onPointDoubleClick?: (point: ScatterPointOpen) => void;
   /**
    * The card that follows the pointer. The viewer builds it, because it has to
    * say the same thing on every tab.
@@ -121,6 +127,7 @@ export function ProjectionMapTab(props: ProjectionMapTabProps): ReactElement {
   const { result, groups, options, copy, chrome, width, height } = props;
   const { ids, selected, viewport = null, report = null } = props;
   const { onSelectionChange, onHoverChange, hoverCard } = props;
+  const { onPointDoubleClick } = props;
   const { onViewportChange, wheelZoom, touchLasso, testId } = props;
   const { scores, fittedCount, markers } = result;
   const { xAxis, yAxis, colorBy, showGroupMeans, pointRadius } = options;
@@ -173,6 +180,7 @@ export function ProjectionMapTab(props: ProjectionMapTabProps): ReactElement {
       onSelectionChange={onSelectionChange}
       selectMode={selectMode}
       onHoverChange={onHoverChange}
+      onPointDoubleClick={onPointDoubleClick}
       onLassoChange={setDrawing}
       touchLasso={touchLasso}
       testId={testId}

package/src/projection/ui/ProjectionPanel.tsx

@@ -1,6 +1,7 @@
 import type { PointerEvent, ReactElement } from 'react';
 import { useRef, useState } from 'react';
 
+import type { ScatterPointOpen } from '../../scatter/ui/scatterPlotProps.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionResult } from '../core/projectionResult.ts';
 import type { ProjectionSamples } from '../core/projectionSamples.ts';
@@ -9,10 +10,12 @@ import { ProjectionMapTab } from './ProjectionMapTab.tsx';
 import { ProjectionPairsTab } from './ProjectionPairsTab.tsx';
 import { ProjectionReadout } from './ProjectionReadout.tsx';
 import { ProjectionSharesTab } from './ProjectionSharesTab.tsx';
+import { ProjectionSpaceTab } from './ProjectionSpaceTab.tsx';
 import type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
 import { ProjectionVariablesTab } from './ProjectionVariablesTab.tsx';
 import type { ProjectionMapView } from './projectionMapView.ts';
 import type { ProjectionModels } from './projectionTabModels.ts';
+import type { ProjectionSampleOpen } from './projectionViewerProps.ts';
 import type { ProjectionStateApi } from './useProjectionState.ts';
 
 /** What {@link ProjectionPanel} needs. */
@@ -46,6 +49,11 @@ export interface ProjectionPanelProps {
    * @default undefined
    */
   onHoverSample?: (id: string | null) => void;
+  /**
+   * Called when the reader double-clicks a sample, on either figure.
+   * @default undefined
+   */
+  onSampleDoubleClick?: (sample: ProjectionSampleOpen) => void;
   /**
    * Called as the pointer crosses the "what differs" panels.
    * @default undefined
@@ -83,6 +91,7 @@ export function ProjectionPanel(props: ProjectionPanelProps): ReactElement {
   const { state, result, samples, copy, models, map } = props;
   const { width, height, formatValue, baseId, panelId, strip } = props;
   const { onHoverSample, onTrackVariable, touchLasso, wheelZoom } = props;
+  const { onSampleDoubleClick } = props;
 
   const box = useRef<HTMLDivElement>(null);
   const pointer = useRef(NOWHERE);
@@ -102,6 +111,19 @@ export function ProjectionPanel(props: ProjectionPanelProps): ReactElement {
     onHoverSample?.(index < 0 ? null : (samples.ids[index] ?? null));
   }
 
+  // The figures speak in row numbers, because that is what a hit test hands
+  // back; every callback out of the viewer speaks in names, so a caller never
+  // has to keep a second copy of the row order. The translation is one line
+  // and it belongs here, once, rather than in each of the two tabs.
+  const openSample =
+    onSampleDoubleClick === undefined
+      ? undefined
+      : (point: ScatterPointOpen) => {
+          const id = samples.ids[point.index];
+          if (id === undefined) return;
+          onSampleDoubleClick({ ...point, id });
+        };
+
   return (
     <div
       ref={box}
@@ -143,6 +165,46 @@ export function ProjectionPanel(props: ProjectionPanelProps): ReactElement {
           height={height}
         />
       ) : null}
+      {state.tab === 'space' ? (
+        <ProjectionSpaceTab
+          result={result}
+          groups={state.groups}
+          options={state.options}
+          copy={copy}
+          chrome={map.spaceChrome}
+          ids={samples.ids}
+          width={width}
+          height={height}
+          selected={state.selected}
+          camera={map.camera}
+          onCameraChange={map.setCamera}
+          zoom={map.zoom}
+          onZoomChange={map.setZoom}
+          wheelZoom={wheelZoom}
+          report={map.report}
+          onSelectionChange={map.settle}
+          onHoverChange={noteHover}
+          onPointDoubleClick={openSample}
+          hoverCard={
+            anchor.index < 0 ? null : (
+              <ProjectionReadout
+                index={anchor.index}
+                result={result}
+                samples={samples}
+                groups={state.groups}
+                xAxis={state.options.xAxis}
+                yAxis={state.options.yAxis}
+                zAxis={state.options.zAxis}
+                x={anchor.x}
+                y={anchor.y}
+                boxWidth={width}
+                boxHeight={height}
+                formatValue={formatValue}
+              />
+            )
+          }
+        />
+      ) : null}
       {state.tab === 'map' ? (
         <ProjectionMapTab
           result={result}
@@ -160,6 +222,7 @@ export function ProjectionPanel(props: ProjectionPanelProps): ReactElement {
           selected={state.selected}
           onSelectionChange={map.settle}
           onHoverChange={noteHover}
+          onPointDoubleClick={openSample}
           touchLasso={touchLasso}
           hoverCard={
             anchor.index < 0 ? null : (

package/src/projection/ui/ProjectionReadout.tsx

@@ -25,6 +25,13 @@ export interface ProjectionReadoutProps {
   xAxis: number;
   /** Which axis is drawn vertically. */
   yAxis: number;
+  /**
+   * Which axis runs away from the reader, on the cloud. It is the one place a
+   * cloud's third number is written at all: the box carries no tick labels, so
+   * a reader who wants a value points at the sample.
+   * @default undefined — the card names two axes, as the map's does
+   */
+  zAxis?: number;
   /** Where the pointer is, in pixels from the figure's left. */
   x: number;
   /** Where the pointer is, in pixels from the figure's top. */
@@ -80,6 +87,7 @@ export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
     groups,
     xAxis,
     yAxis,
+    zAxis,
     x,
     y,
     boxWidth,
@@ -91,10 +99,13 @@ export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
     testId,
   } = props;
 
+  const drawn = useMemo(
+    () => (zAxis === undefined ? [xAxis, yAxis] : [xAxis, yAxis, zAxis]),
+    [xAxis, yAxis, zAxis],
+  );
   const rows = useMemo(
-    () =>
-      readoutRows(index, result, samples, groups, xAxis, yAxis, formatValue),
-    [formatValue, groups, index, result, samples, xAxis, yAxis],
+    () => readoutRows(index, result, samples, groups, drawn, formatValue),
+    [drawn, formatValue, groups, index, result, samples],
   );
 
   return (
@@ -118,15 +129,14 @@ function readoutRows(
   result: ProjectionResult,
   samples: ProjectionSamples,
   groups: ResolvedProjectionGroups,
-  xAxis: number,
-  yAxis: number,
+  drawn: readonly number[],
   formatValue: (value: number) => string,
 ): OverlayReadoutRow[] {
   const rows: OverlayReadoutRow[] = [];
   const { axes, scores } = result;
   const known = index >= 0 && index < scores.rows;
 
-  for (const axis of [xAxis, yAxis]) {
+  for (const axis of drawn) {
     const name = axes[axis]?.name;
     if (name === undefined) continue;
     rows.push({