react-cheminfo 0.10.0 → 0.11.0

package/src/projection/ui/projectionBarSlots.tsx

@@ -13,6 +13,8 @@ import { ProjectionPairsControls } from './ProjectionPairsControls.tsx';
 import { ProjectionPairsMore } from './ProjectionPairsMore.tsx';
 import { ProjectionSharesControls } from './ProjectionSharesControls.tsx';
 import { ProjectionSharesMore } from './ProjectionSharesMore.tsx';
+import { ProjectionSpaceControls } from './ProjectionSpaceControls.tsx';
+import { ProjectionSpaceMore } from './ProjectionSpaceMore.tsx';
 import { ProjectionVariablesControls } from './ProjectionVariablesControls.tsx';
 import { ProjectionVariablesMore } from './ProjectionVariablesMore.tsx';
 import type { ProjectionReading } from './projectionBarReadings.ts';
@@ -96,6 +98,23 @@ export function projectionBarSlots(
       info: projectionPairsInfo(copy, groups.label, colored),
     };
   }
+  if (tab === 'space') {
+    const space = {
+      ...shared,
+      result,
+      hasGroups,
+      selectedCount: selected.length,
+      onResetView: map.resetSpaceView,
+      onClearSelection: map.clearSelection,
+    };
+    return {
+      end: (
+        <ProjectionSpaceControls {...space} readings={readings} tier={tier} />
+      ),
+      more: <ProjectionSpaceMore {...space} />,
+      info: map.spaceChrome.caption,
+    };
+  }
   if (tab === 'variables') {
     const variables = {
       options,

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/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/projectionMapChrome.ts

@@ -16,6 +16,7 @@ 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. */
@@ -38,6 +39,14 @@ export interface ProjectionMapChromeInput {
   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. */
@@ -73,7 +82,7 @@ export function projectionMapChrome(
   input: ProjectionMapChromeInput,
 ): ProjectionMapChrome {
   const { copy, groups, colored, ellipse, showGroupMeans, markers } = input;
-  const { minimumPoints, fittedCount, total } = input;
+  const { minimumPoints, fittedCount, total, figure = 'map' } = input;
   const entries: OverlayLegendEntry[] = [];
   const skipped: string[] = [];
 
@@ -114,7 +123,15 @@ export function projectionMapChrome(
   return {
     title: legendTitle(copy, groups, colored),
     entries,
-    caption: captionFor(copy, groups, colored, ellipse, skipped, hollow),
+    caption: captionFor(
+      copy,
+      groups,
+      colored,
+      ellipse,
+      skipped,
+      hollow,
+      figure,
+    ),
   };
 }
 
@@ -169,15 +186,19 @@ function captionFor(
   ellipse: EllipseSize | null,
   skipped: readonly string[],
   hollow: boolean,
+  figure: 'map' | 'space',
 ): string {
-  let sentence = copy.intro.map;
+  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(copy.legend.map, {
+    sentence += ` ${fillCopy(solid ? copy.legend.space : copy.legend.map, {
       groups: groups.label.toLowerCase(),
-      coverage: ellipseCoverageText(ellipse),
+      coverage: solid
+        ? ellipsoidCoverageText(ellipse)
+        : ellipseCoverageText(ellipse),
     })}`;
   }
   if (skipped.length > 0) {

package/src/projection/ui/projectionMapView.ts

@@ -14,6 +14,8 @@ import { useCallback, useMemo, useState } from 'react';
 import type { ChartViewport } from '../../chart/core/chartViewport.ts';
 import { chartClampViewport } from '../../chart/core/chartViewport.ts';
 import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { OrbitCamera } from '../../scatter3d/core/orbitCamera.ts';
+import { DEFAULT_ORBIT_CAMERA } from '../../scatter3d/core/orbitCamera.ts';
 import type { ProjectionCopy } from '../core/projectionCopy.ts';
 import type { ProjectionOptions } from '../core/projectionOptions.ts';
 import type {
@@ -33,6 +35,7 @@ import {
   projectionMapDomain,
   projectionMapViewport,
 } from './projectionMapModel.ts';
+import { MINIMUM_SHELL_POINTS } from './projectionSpaceModel.ts';
 
 /** What {@link useProjectionMapView} needs. */
 export interface ProjectionMapViewInput {
@@ -54,6 +57,18 @@ export interface ProjectionMapViewInput {
 export interface ProjectionMapView {
   /** The key's title, the key's entries, and the paragraph behind the `?`. */
   chrome: ProjectionMapChrome;
+  /** The same three for the cloud, which promises a different share. */
+  spaceChrome: ProjectionMapChrome;
+  /** Where the reader is standing in the cloud. */
+  camera: OrbitCamera;
+  /** Turn the box. */
+  setCamera: (camera: OrbitCamera) => void;
+  /** How far in the cloud is zoomed. */
+  zoom: number;
+  /** Zoom the box. */
+  setZoom: (zoom: number) => void;
+  /** Put the box back where it was first seen, at the size it was first drawn. */
+  resetSpaceView: () => void;
   /** The frame the map is drawn in, or `null` when it is drawn around every sample. */
   viewport: ChartViewport | null;
   /** Draw the map in another frame, which is what the wheel does. */
@@ -84,6 +99,8 @@ export function useProjectionMapView(
 
   const [zoom, setZoom] = useState<AxisFrame | null>(null);
   const [report, setReport] = useState<SelectionReport | null>(null);
+  const [camera, setCamera] = useState<OrbitCamera>(DEFAULT_ORBIT_CAMERA);
+  const [cloudZoom, setCloudZoom] = useState(1);
 
   // A frame belongs to the pair of axes it was drawn on. Carrying it onto
   // another pair would show the reader a corner of a picture they never
@@ -117,6 +134,11 @@ export function useProjectionMapView(
     setViewport(null);
   }, [setViewport]);
 
+  const resetSpaceView = useCallback(() => {
+    setCamera(DEFAULT_ORBIT_CAMERA);
+    setCloudZoom(1);
+  }, []);
+
   const colored = colorBy === 'group' && groups.entries.length > 0;
   const chrome = useMemo(
     () =>
@@ -143,6 +165,23 @@ export function useProjectionMapView(
     ],
   );
 
+  const spaceChrome = useMemo(
+    () =>
+      projectionMapChrome({
+        copy,
+        groups,
+        colored,
+        ellipse: colored ? ellipse : null,
+        minimumPoints: MINIMUM_SHELL_POINTS,
+        showGroupMeans: false,
+        markers: NO_MARKERS,
+        fittedCount: fittedCount ?? scores.rows,
+        total: scores.rows,
+        figure: 'space',
+      }),
+    [copy, groups, colored, ellipse, fittedCount, scores],
+  );
+
   const settle = useCallback(
     (change: SelectionChange) => {
       setReport((previous) => ({
@@ -164,8 +203,14 @@ export function useProjectionMapView(
 
   return {
     chrome,
+    spaceChrome,
     viewport,
     setViewport,
+    camera,
+    setCamera,
+    zoom: cloudZoom,
+    setZoom: setCloudZoom,
+    resetSpaceView,
     report,
     settle,
     zoomToSelection,

package/src/projection/ui/projectionSpaceModel.ts

@@ -0,0 +1,14 @@
+/**
+ * The one number the cloud sets differently from the map.
+ */
+
+/**
+ * How many samples a group needs before it is given a shell.
+ *
+ * One more than the map asks for, and for the same reason the map asks for
+ * three: a shape fitted to the fewest points that can define it describes those
+ * points and not the group they came from. Three samples lie on a plane
+ * however they are arranged, so three is the number at which a shell is
+ * arithmetic rather than a finding.
+ */
+export const MINIMUM_SHELL_POINTS = 4;

package/src/projection/ui/projectionViewerProps.ts

@@ -16,6 +16,25 @@ import type { ProjectionTab } from '../core/projectionTabs.ts';
 import type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
 import type { ProjectionSelection } from './projectionSelection.ts';
 
+/** A sample the reader opened, and where they opened it. */
+export interface ProjectionSampleOpen {
+  /** Its name, from `samples.ids` — the currency every other callback uses. */
+  id: string;
+  /** Its row in the score matrix, for a caller that would rather index. */
+  index: number;
+  /** Where the reader clicked, in pixels from the figure's left edge. */
+  x: number;
+  /** Where they clicked, in pixels from its top edge. */
+  y: number;
+  /**
+   * Where they clicked in the window, which is what an editor floating over
+   * the page is anchored to.
+   */
+  clientX: number;
+  /** Where they clicked in the window. */
+  clientY: number;
+}
+
 /** What {@link ProjectionViewer} needs. */
 export interface ProjectionViewerProps {
   /** What the run produced, whatever produced it. */
@@ -88,6 +107,22 @@ export interface ProjectionViewerProps {
    * @default undefined
    */
   onHoverSample?: (id: string | null) => void;
+  /**
+   * Called when the reader double-clicks a sample, on the map or in the cloud.
+   *
+   * The viewer says what a sample *is*; this is the door to what the page
+   * around it can do with one — open its record, edit the class it was given,
+   * show the spectrum behind the dot. The viewer does nothing itself, so a
+   * page that does not pass it has a double click that only ever resets the
+   * frame.
+   *
+   * The sample is selected first, because a double click is also two clicks.
+   * Holding every single click for the double-click interval to avoid that
+   * would make the commonest gesture in the figure feel slow, which is a worse
+   * trade than a redundant selection on the rarest one.
+   * @default undefined
+   */
+  onSampleDoubleClick?: (sample: ProjectionSampleOpen) => void;
   /**
    * What the figure is showing. Present, the caller owns every option, which
    * is how a site persists them or writes them into a share link.

package/src/scatter/ui/ScatterPlot.tsx

@@ -1,4 +1,4 @@
-import type { ReactElement } from 'react';
+import type { MouseEvent as ReactMouseEvent, ReactElement } from 'react';
 import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
 
 import { ChartFrame } from '../../chart/ui/ChartFrame.tsx';
@@ -7,6 +7,7 @@ import { ScatterEllipseLayer } from './ScatterEllipseLayer.tsx';
 import { ScatterLabelLayer } from './ScatterLabelLayer.tsx';
 import { ScatterMarkLayer } from './ScatterMarkLayer.tsx';
 import { ScatterPointLayer } from './ScatterPointLayer.tsx';
+import { surfacePosition } from './lassoGesture.ts';
 import {
   SCATTER_GROUP_LABEL_SIZE,
   SCATTER_LABEL_SIZE,
@@ -28,6 +29,7 @@ export type {
   ScatterGroup,
   ScatterMarker,
   ScatterPlotProps,
+  ScatterPointOpen,
 } from './scatterPlotProps.ts';
 
 /**
@@ -68,6 +70,7 @@ export function ScatterPlot(props: ScatterPlotProps): ReactElement {
     selectMode,
     onHoverChange,
     onPinChange,
+    onPointDoubleClick,
     onLassoChange,
     touchLasso,
     viewport,
@@ -151,6 +154,22 @@ export function ScatterPlot(props: ScatterPlotProps): ReactElement {
     onPinChange,
   });
 
+  function handleDoubleClick(event: ReactMouseEvent<SVGRectElement>): void {
+    const at = surfacePosition(event, rect.x, rect.y);
+    const index = interaction.pointAt(at.x, at.y);
+    if (index === -1 || onPointDoubleClick === undefined) {
+      reset();
+      return;
+    }
+    onPointDoubleClick({
+      index,
+      x: at.x,
+      y: at.y,
+      clientX: event.clientX,
+      clientY: event.clientY,
+    });
+  }
+
   // Held in a ref so an inline arrow, which is how every caller writes it, does
   // not put the callback in the effect's dependencies and report a drag that
   // never changed on every render.
@@ -224,7 +243,7 @@ export function ScatterPlot(props: ScatterPlotProps): ReactElement {
             fill="transparent"
             tabIndex={0}
             onKeyDown={interaction.keyboard.onKeyDown}
-            onDoubleClick={reset}
+            onDoubleClick={handleDoubleClick}
             {...interaction.surface}
           />
         </>

package/src/scatter/ui/lassoGesture.ts

@@ -163,6 +163,16 @@ export function modifierMode(
   return resting;
 }
 
+/** The little of an event that says where on the surface it happened. */
+export interface SurfaceEvent {
+  /** The element the handler is on, which is the rectangle being measured. */
+  currentTarget: Element;
+  /** Where the event happened, in the window. */
+  clientX: number;
+  /** Where the event happened, in the window. */
+  clientY: number;
+}
+
 /**
  * Where the pointer is, in the space the points were measured in.
  *
@@ -170,13 +180,16 @@ export function modifierMode(
  * the plot's own corner, so the answer can be compared with a point coordinate
  * without the caller mapping anything. An element that cannot be measured —
  * a server render — reports the corner itself rather than throwing.
- * @param event - The pointer event.
+ *
+ * It takes the three fields it actually reads rather than a pointer event,
+ * because a double click arrives as a mouse event and asks the same question.
+ * @param event - The event, or anything carrying those three fields.
  * @param originX - The rectangle's left edge in the points' space.
  * @param originY - Its top edge.
  * @returns The position, in pixels.
  */
 export function surfacePosition(
-  event: ReactPointerEvent<Element>,
+  event: SurfaceEvent,
   originX: number,
   originY: number,
 ): { x: number; y: number } {

package/src/scatter/ui/scatterPlotProps.ts

@@ -45,6 +45,25 @@ export interface ScatterMarker {
   shape?: OverlayMarkShape;
 }
 
+/** A point the reader opened, and where they opened it. */
+export interface ScatterPointOpen {
+  /** Its row, as an index into the arrays the caller passed. */
+  index: number;
+  /** Where the reader clicked, in pixels from the figure's left edge. */
+  x: number;
+  /** Where they clicked, in pixels from its top edge. */
+  y: number;
+  /**
+   * Where they clicked in the window, which is what an editor floating over
+   * the page — a menu, a popover, a dialog anchored on the point — is placed
+   * from. The pair above is the figure's own space, for a caller drawing
+   * inside it.
+   */
+  clientX: number;
+  /** Where they clicked in the window. */
+  clientY: number;
+}
+
 /** What {@link ScatterPlot} needs. */
 export interface ScatterPlotProps {
   /** Horizontal coordinate of every point, in data units. */
@@ -174,6 +193,22 @@ export interface ScatterPlotProps {
    * @default undefined
    */
   onPinChange?: (index: number) => void;
+  /**
+   * Called when the reader double-clicks a point: the gesture for "tell me
+   * more about this one", or "let me change it".
+   *
+   * A double click is also two clicks, so the point is selected first and its
+   * card pinned. That is deliberate: the alternative is to hold every single
+   * click for the length of the double-click interval before acting on it, and
+   * clicking a dot is the commonest gesture in the figure — making it feel
+   * slow to save a redundant selection on the rarest one is the wrong trade.
+   *
+   * A double click on empty ground is not this. It puts the frame back around
+   * every point, which is the only way out of a zoom, and it keeps doing that
+   * whether or not this is given.
+   * @default undefined — a double click only ever resets the frame
+   */
+  onPointDoubleClick?: (point: ScatterPointOpen) => void;
   /**
    * Called when a lasso starts being drawn and again when it ends, and never
    * in between.

package/src/scatter/ui/useScatterInteraction.ts

@@ -97,6 +97,15 @@ export interface ScatterInteractionApi {
   keyboard: ScatterKeyboardApi;
   /** The outline being drawn, for the plot to stroke. */
   lasso: LassoGesture;
+  /**
+   * Which point is near a position, or `-1`.
+   *
+   * The same search a click runs, offered on its own so that a gesture the
+   * hook does not own — a double click, which the plot answers because only
+   * the plot knows what a double click on empty ground means — asks it in the
+   * same words and with the same radius.
+   */
+  pointAt: (x: number, y: number) => number;
 }
 
 /**
@@ -233,5 +242,17 @@ export function useScatterInteraction(
 
   const keyboard = useScatterKeyboard({ count, onCommit, onCancel });
 
-  return { surface: lasso.surface, selection, hover, keyboard, lasso };
+  const pointAt = useCallback(
+    (x: number, y: number) => nearestPointIndex(points, x, y, radius, included),
+    [included, points, radius],
+  );
+
+  return {
+    surface: lasso.surface,
+    selection,
+    hover,
+    keyboard,
+    lasso,
+    pointAt,
+  };
 }

package/src/scatter3d/core/cloudGesture.ts

@@ -0,0 +1,16 @@
+/**
+ * What a drag over a cloud does.
+ *
+ * Two gestures want the same drag. Turning the box is the one a reader reaches
+ * for first and must stay a plain drag; drawing a lasso is the one the flat map
+ * has already taught them. Neither can be given a modifier without taking one
+ * that already means "add to the selection" or "take out of it", so the choice
+ * is a control the reader can see rather than a shortcut somebody has to tell
+ * them about — and inside a lasso the modifiers keep exactly the meaning they
+ * have on the map.
+ */
+export type CloudGesture =
+  /** Turn the box. A tap still picks the sample under it. */
+  | 'turn'
+  /** Draw a lasso, exactly as on the map. */
+  | 'select';