react-cheminfo 0.9.0 → 0.11.0

package/src/scatter3d/ui/useOrbitDrag.ts

@@ -0,0 +1,220 @@
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { ScatterSurfaceProps } from '../../scatter/ui/lassoGesture.ts';
+import {
+  capturePointer,
+  dropFrame,
+  modifierMode,
+  scheduleFrame,
+  surfacePosition,
+} from '../../scatter/ui/lassoGesture.ts';
+import type { OrbitCamera } from '../core/orbitCamera.ts';
+import { orbitByDrag } from '../core/orbitCamera.ts';
+
+/** What {@link useOrbitDrag} needs. */
+export interface OrbitDragOptions {
+  /**
+   * Whether a drag turns the box at all. Off, the surface still reports a tap,
+   * so the reader can pick a sample while the drag belongs to something else.
+   * @default true
+   */
+  enabled?: boolean;
+  /** Called with the camera each frame of a drag leaves behind. */
+  onOrbit: (turn: (camera: OrbitCamera) => OrbitCamera) => void;
+  /**
+   * Called when a press and release happened in one place — a click, however
+   * the reader's hand shook.
+   * @default undefined
+   */
+  onTap?: (x: number, y: number, mode: ScatterSelectionMode) => void;
+  /**
+   * Called with the pointer's position on every frame it moves without
+   * turning, which is what raises the card under it.
+   * @default undefined
+   */
+  onMove?: (x: number, y: number) => void;
+  /**
+   * Called when the pointer leaves the surface without a drag in progress.
+   * @default undefined
+   */
+  onLeave?: () => void;
+  /**
+   * What a tap with no modifier held does to the selection.
+   * @default 'replace'
+   */
+  mode?: ScatterSelectionMode;
+}
+
+/** A drag that turns the box, and the taps it lets through. */
+export interface OrbitDrag {
+  /** Whether the box is being turned right now. */
+  turning: boolean;
+  /** Spread onto the transparent rectangle over the figure. */
+  surface: ScatterSurfaceProps;
+}
+
+/**
+ * Turning the box with the pointer.
+ *
+ * It is the lasso's twin and is built the same way — the pointer is captured
+ * on the way down so a drag that wanders off the figure keeps turning it, all
+ * three ways a capture can end lead to one function, and moves are coalesced
+ * to one a frame because a pointer emits many per frame and each one that
+ * reaches the caller repaints every dot and every face.
+ *
+ * A press that goes nowhere is a tap rather than a turn of no degrees, because
+ * nobody presses a mouse button without moving it a pixel or two and a reader
+ * who meant to pick a sample must not have to hold their hand still to do it.
+ * @param options - See {@link OrbitDragOptions}.
+ * @returns The drag. See {@link OrbitDrag}.
+ */
+export function useOrbitDrag(options: OrbitDragOptions): OrbitDrag {
+  const {
+    enabled = true,
+    onOrbit,
+    onTap,
+    onMove,
+    onLeave,
+    mode: restingMode = 'replace',
+  } = options;
+
+  const pointerRef = useRef<number | null>(null);
+  const lastRef = useRef({ x: 0, y: 0 });
+  const travelRef = useRef(0);
+  const frameRef = useRef<number | null>(null);
+  const pendingRef = useRef<PendingTurn | null>(null);
+  const [turning, setTurning] = useState(false);
+
+  const flush = useCallback(() => {
+    frameRef.current = null;
+    const next = pendingRef.current;
+    pendingRef.current = null;
+    if (next === null) return;
+    if (pointerRef.current === null) {
+      onMove?.(next.x, next.y);
+      return;
+    }
+    onOrbit((camera) => orbitByDrag(camera, next.dx, next.dy));
+  }, [onMove, onOrbit]);
+
+  const end = useCallback(
+    (event: ReactPointerEvent<Element>, commit: boolean) => {
+      if (event.pointerId !== pointerRef.current) return;
+      pointerRef.current = null;
+      pendingRef.current = null;
+      dropFrame(frameRef);
+      setTurning(false);
+      if (!commit || travelRef.current > TAP_SLACK) return;
+      const at = surfacePosition(event, 0, 0);
+      onTap?.(at.x, at.y, modifierMode(event, restingMode));
+    },
+    [onTap, restingMode],
+  );
+
+  const handleDown = useCallback((event: ReactPointerEvent<Element>) => {
+    if (pointerRef.current !== null || event.button > 0) return;
+    pointerRef.current = event.pointerId;
+    lastRef.current = { x: event.clientX, y: event.clientY };
+    travelRef.current = 0;
+    setTurning(true);
+    capturePointer(event);
+  }, []);
+
+  const handleMove = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      const active = pointerRef.current;
+      if (active === null) {
+        const at = surfacePosition(event, 0, 0);
+        pendingRef.current = { x: at.x, y: at.y, dx: 0, dy: 0 };
+        scheduleFrame(frameRef, flush);
+        return;
+      }
+      if (event.pointerId !== active) return;
+      const last = lastRef.current;
+      const dx = event.clientX - last.x;
+      const dy = event.clientY - last.y;
+      lastRef.current = { x: event.clientX, y: event.clientY };
+      travelRef.current += Math.abs(dx) + Math.abs(dy);
+      if (!enabled) return;
+      const waiting = pendingRef.current;
+      pendingRef.current = {
+        x: 0,
+        y: 0,
+        dx: (waiting?.dx ?? 0) + dx,
+        dy: (waiting?.dy ?? 0) + dy,
+      };
+      scheduleFrame(frameRef, flush);
+    },
+    [enabled, flush],
+  );
+
+  const handleUp = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      end(event, true);
+    },
+    [end],
+  );
+
+  const handleAbandon = useCallback(
+    (event: ReactPointerEvent<Element>) => {
+      end(event, false);
+    },
+    [end],
+  );
+
+  const handleLeave = useCallback(() => {
+    if (pointerRef.current !== null) return;
+    pendingRef.current = null;
+    onLeave?.();
+  }, [onLeave]);
+
+  const surface = useMemo<ScatterSurfaceProps>(
+    () => ({
+      onPointerDown: handleDown,
+      onPointerMove: handleMove,
+      onPointerUp: handleUp,
+      onPointerCancel: handleAbandon,
+      onLostPointerCapture: handleAbandon,
+      onPointerLeave: handleLeave,
+      style: {
+        cursor: enabled ? (turning ? 'grabbing' : 'grab') : 'default',
+        touchAction: 'none',
+      },
+    }),
+    [
+      enabled,
+      handleAbandon,
+      handleDown,
+      handleLeave,
+      handleMove,
+      handleUp,
+      turning,
+    ],
+  );
+
+  return { turning, surface };
+}
+
+/**
+ * How far a press may travel and still be a tap, in pixels of total travel.
+ *
+ * Generous on purpose: a mouse moves a pixel or two under the click of its own
+ * button, and a finger moves rather more, so a stricter number turns "pick
+ * this sample" into "turn the box by nothing at all" for anybody whose hand is
+ * not steady.
+ */
+const TAP_SLACK = 5;
+
+/** What the pointer has done since the last frame, waiting for the next. */
+interface PendingTurn {
+  /** Where it is, for a move that is not turning anything. */
+  x: number;
+  /** Where it is. */
+  y: number;
+  /** How far it has moved across since the last frame. */
+  dx: number;
+  /** How far it has moved down. */
+  dy: number;
+}

package/src/share/core/query.ts

@@ -26,10 +26,16 @@ export function parseQuery(search: string): QueryEntry[] {
 }
 
 /**
- * Write pairs back into a query string, keeping the two characters a reader
- * of these links cares about legible: a comma stays a comma rather than
- * `%2C`, and a plus stays a plus rather than `%2B`. Both parse back
- * identically through {@link parseQuery}.
+ * Write pairs back into a query string, keeping the comma legible — `hide=a,b`
+ * rather than `hide=a%2Cb` — because a teacher has to read these links, and a
+ * comma has only one reading.
+ *
+ * A plus is written `%2B`, even though {@link parseQuery} would read a literal
+ * one back. We are liberal in what we accept and strict in what we write: a
+ * bare `+` in a query string is read as a space by `URLSearchParams`,
+ * `query-string` and every server-side parser, so `ionizations=H+` comes back
+ * as `H ` and `smiles=CC[N+](C)(C)C` as a different molecule — silently,
+ * anywhere the link is read by something other than {@link parseQuery}.
  * @param entries - The pairs to write, in the order they should appear.
  * @returns The query string, without its leading `?`.
  */
@@ -66,7 +72,5 @@ function decodeComponent(value: string): string {
 }
 
 function encodeComponent(value: string): string {
-  return encodeURIComponent(value)
-    .replaceAll('%2C', ',')
-    .replaceAll('%2B', '+');
+  return encodeURIComponent(value).replaceAll('%2C', ',');
 }

package/src/spectra/core/axisEntries.ts

@@ -0,0 +1,107 @@
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { RANGE_FIELDS, ZONE_FIELDS } from './filterEntries.ts';
+import {
+  booleanField,
+  enumField,
+  formulaField,
+  integerField,
+  numberField,
+} from './filterFields.ts';
+
+export const AXIS_ENTRIES = {
+  xFunction: {
+    label: 'Apply a formula to x',
+    group: 'x-axis',
+    summary:
+      'Rewrites every x through an expression, read the same way as the y one.',
+    fields: [
+      formulaField(
+        'function',
+        'Expression in x',
+        'For instance 10000000/x, which reads nanometres as wavenumbers.',
+      ),
+    ],
+    caution:
+      'Every range below is then read in the new units — including the resampling range, which runs last unless you resample first.',
+  },
+  fromTo: {
+    label: 'Crop',
+    group: 'x-axis',
+    summary: 'Keeps one stretch of the spectrum and drops the rest.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('fromIndex', 'From (point)', '0'),
+      integerField('toIndex', 'To (point)', 'the last point'),
+    ],
+    caution:
+      'Give x values or point numbers, not both: a point number silently wins over an x value.',
+  },
+  filterX: {
+    label: 'Keep or drop x zones',
+    group: 'x-axis',
+    summary:
+      'Keeps the points falling in the zones named, without resampling anything.',
+    fields: [...RANGE_FIELDS, ...ZONE_FIELDS],
+  },
+  equallySpaced: {
+    label: 'Resample on a regular grid',
+    group: 'x-axis',
+    summary: 'Interpolates onto evenly spaced x values.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('numberOfPoints', 'Number of points', '100'),
+      ...ZONE_FIELDS,
+    ],
+    caution:
+      'The settings above already resample once, so this resamples twice; whichever of the two runs last sets the point count.',
+  },
+  calibrateX: {
+    label: 'Calibrate x on a peak',
+    group: 'x-axis',
+    summary:
+      'Finds the strongest peaks in a stretch and shifts the whole axis so their mean lands on the value asked for.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('nbPeaks', 'Peaks to find', '1'),
+      numberField('targetX', 'Move them to', '0'),
+      booleanField('gsd.smoothY', 'Smooth before picking'),
+      booleanField(
+        'gsd.maxCriteria',
+        'Pick maxima',
+        'Off picks minima instead.',
+      ),
+      numberField(
+        'gsd.minMaxRatio',
+        'Smallest peak kept',
+        '0.00025',
+        'As a fraction of the tallest. A step added here starts at 0.1; empty the box and this far lower default takes over.',
+      ),
+      numberField('gsd.noiseLevel', 'Noise level', 'not set'),
+      booleanField('gsd.realTopDetection', 'Refine the summit'),
+      integerField('gsd.sgOptions.windowSize', 'Peak-picking window', '9'),
+      integerField('gsd.sgOptions.polynomial', 'Peak-picking polynomial', '3'),
+      enumField('gsd.peakDetectionAlgorithm', 'Detected on', [
+        { value: 'first', label: 'The first derivative' },
+        { value: 'second', label: 'The second derivative' },
+        { value: 'auto', label: 'Whichever fits' },
+      ]),
+    ],
+    caution:
+      'When fewer peaks are found than asked for, the spectrum is returned untouched and nothing says so.',
+  },
+  ensureGrowing: {
+    label: 'Make x strictly increasing',
+    group: 'utility',
+    summary:
+      'Drops the points that repeat or go backwards, which resampling and cropping both assume never happens.',
+    fields: [],
+  },
+  reverseIfNeeded: {
+    label: 'Reverse a descending x',
+    group: 'utility',
+    summary: 'Turns a descending axis the right way round.',
+    fields: [],
+    caution:
+      'The chain already does this before every step, so adding it here changes nothing.',
+  },
+} as const satisfies Record<string, FilterCatalogEntry>;

package/src/spectra/core/chainProblems.ts

@@ -0,0 +1,165 @@
+import { filterStepLabel, findFilterEntry } from './filterCatalog.ts';
+import type { SettingsProblem } from './problems.ts';
+import { problem } from './problems.ts';
+import type { SpectrumFilter, SpectrumFilterName } from './settings.ts';
+import { stepProblems } from './stepProblems.ts';
+
+/** The steps that all say "make the y scale comparable"; only the last survives. */
+const SCALING_STEPS: ReadonlySet<SpectrumFilterName> = new Set([
+  'divideBySD',
+  'normed',
+  'paretoNormalization',
+  'rescale',
+]);
+
+/** The steps that hand on plain arrays, whatever they were given. */
+const UNTYPES_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'equallySpaced',
+  'filterX',
+]);
+
+/** The steps that read x as a typed array and throw on a plain one. */
+const NEEDS_TYPED_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'calibrateX',
+  'fromTo',
+]);
+
+/**
+ * Everything wrong, or probably wrong, with one chain.
+ *
+ * The order of a chain is its meaning — scaling measured before a baseline is
+ * removed measures an offset that is about to change — so the advice below is
+ * as much about where a step sits as about what it is set to.
+ * @param chain - The steps, in the order they run.
+ * @param resampleFirst - Whether the settings resample before the chain runs.
+ * @returns Every problem found, errors and advice together.
+ */
+export function chainProblems(
+  chain: readonly SpectrumFilter[],
+  resampleFirst: boolean,
+): SettingsProblem[] {
+  const problems: SettingsProblem[] = [];
+  let baselines = 0;
+  let scalings = 0;
+  let firstScaling: number | undefined;
+  let plainX = resampleFirst;
+  let mayBePlainX = resampleFirst;
+
+  for (const [index, step] of chain.entries()) {
+    const where = filterStepLabel(step.name, index);
+    const entry = findFilterEntry(step.name);
+    problems.push(...stepProblems(step, where));
+
+    if (entry === undefined) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          `${step.name} is not one of the steps this editor knows, so its options are left as they are. The processor throws on a name it cannot dispatch.`,
+        ),
+      );
+      continue;
+    }
+
+    if (NEEDS_TYPED_X.has(step.name)) {
+      if (plainX) {
+        problems.push(problem('error', where, TYPED_X_MESSAGE));
+      } else if (mayBePlainX) {
+        problems.push(problem('warning', where, MAY_BE_PLAIN_MESSAGE));
+      }
+    }
+    if (UNTYPES_X.has(step.name)) {
+      plainX = true;
+      mayBePlainX = true;
+    }
+    if (step.name === 'ensureGrowing') mayBePlainX = true;
+
+    const { group } = entry;
+    if (group === 'baseline') {
+      baselines++;
+      if (firstScaling !== undefined) {
+        problems.push(
+          problem(
+            'warning',
+            where,
+            `Step ${String(firstScaling + 1)} scales the signal before this levels it, so the scaling is measured against an offset that then changes. Level first.`,
+          ),
+        );
+        firstScaling = undefined;
+      }
+    }
+    if (SCALING_STEPS.has(step.name)) {
+      scalings++;
+      firstScaling ??= index;
+    }
+    if (step.name === 'reverseIfNeeded') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'The chain already turns a descending axis round before every step, so this one does nothing.',
+        ),
+      );
+    }
+    if (step.name === 'equallySpaced') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          resampleFirst
+            ? 'The settings resample before the chain runs, so this resamples a second time and the point count set here is the one the matrix ends up with.'
+            : 'The settings resample after the chain runs, so this resamples a second time and the point count set above is the one the matrix ends up with.',
+        ),
+      );
+    }
+    if (
+      !resampleFirst &&
+      (step.name === 'xFunction' || step.name === 'calibrateX')
+    ) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'This changes the x axis before the resampling runs, so the range and the exclusions above are read in the new units.',
+        ),
+      );
+    }
+    if (resampleFirst && step.name === 'filterX') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'Cropping after the resampling can leave each spectrum on its own grid, and the matrix then lines up rows that do not match. Pin the range above, or turn resampling back to last.',
+        ),
+      );
+    }
+  }
+
+  if (baselines > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(baselines)} baselines are subtracted one after another, each estimated from what the last one left.`,
+      ),
+    );
+  }
+  if (scalings > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(scalings)} steps set the y scale; only the last of them still shows in the result.`,
+      ),
+    );
+  }
+  return problems;
+}
+
+/** What a step reading x as a typed array is told when it cannot be one. */
+const TYPED_X_MESSAGE =
+  'This step reads x as a typed array, and resampling or cropping has already turned it into a plain one, so the processor throws. Move it before them, or turn resampling back to last.';
+
+/** The same, when only the data can settle whether x was untyped. */
+const MAY_BE_PLAIN_MESSAGE =
+  'This step reads x as a typed array. An earlier step turns x into a plain one whenever it has points to drop, and the processor then throws on this step.';

package/src/spectra/core/filterCatalog.ts

@@ -0,0 +1,100 @@
+import { AXIS_ENTRIES } from './axisEntries.ts';
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { BASELINE_ENTRIES, SIGNAL_ENTRIES } from './filterEntries.ts';
+import type { FilterGroup } from './filterFields.ts';
+import { FILTER_GROUPS } from './filterFields.ts';
+import type { SpectrumFilterName } from './settings.ts';
+
+/**
+ * What the editor knows about every step `filterXY` dispatches.
+ *
+ * Keyed by the name rather than listed, so the day `ml-signal-processing` adds
+ * a filter this object stops compiling and the gap is a build failure instead
+ * of a step nobody can reach.
+ */
+export const FILTER_CATALOG: Readonly<
+  Record<SpectrumFilterName, FilterCatalogEntry>
+> = {
+  ...BASELINE_ENTRIES,
+  ...SIGNAL_ENTRIES,
+  ...AXIS_ENTRIES,
+};
+
+/** Every step name, in the order the menu offers them. */
+export const FILTER_NAMES: readonly SpectrumFilterName[] = Object.keys(
+  FILTER_CATALOG,
+) as SpectrumFilterName[];
+
+/**
+ * What the editor knows about one step.
+ * @param name - The step's name.
+ * @returns Its catalog entry.
+ */
+export function filterEntry(name: SpectrumFilterName): FilterCatalogEntry {
+  return FILTER_CATALOG[name];
+}
+
+/**
+ * What the editor knows about a step whose name it may not recognise.
+ *
+ * The settings the processor accepts are typed `{ name: string }`, and
+ * `filterXY` really does dispatch four more names than the union declares, so a
+ * chain reaching the editor can name a step the catalog has never heard of.
+ * Answering nothing lets the panel say so; throwing would take the whole page
+ * down over one row.
+ * @param name - The step's name, from settings that may come from anywhere.
+ * @returns Its catalog entry, or undefined when the name is not one of the 23.
+ */
+export function findFilterEntry(name: string): FilterCatalogEntry | undefined {
+  return Object.hasOwn(FILTER_CATALOG, name)
+    ? FILTER_CATALOG[name as SpectrumFilterName]
+    : undefined;
+}
+
+/**
+ * How the panel labels one step of a chain, whether or not it knows the step.
+ * @param name - The step's name.
+ * @param position - Where it sits, counting from zero.
+ * @returns The label the row and every problem about it share.
+ */
+export function filterStepLabel(name: string, position: number): string {
+  return `Step ${String(position + 1)} — ${findFilterEntry(name)?.label ?? name}`;
+}
+
+/**
+ * The steps of one group, in menu order.
+ * @param group - Which part of the signal the steps work on.
+ * @returns Their names.
+ */
+export function filterNamesInGroup(
+  group: FilterGroup,
+): readonly SpectrumFilterName[] {
+  const names: SpectrumFilterName[] = [];
+  for (const name of FILTER_NAMES) {
+    if (FILTER_CATALOG[name].group === group) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The whole menu, group by group, skipping a group that holds nothing.
+ *
+ * The 23 steps are unreadable as one list, and grouping them by what they touch
+ * is the same order a chain is usually built in: level the baseline, smooth,
+ * scale, then move the axis.
+ * @returns Each group with its steps.
+ */
+export function filterMenu(): ReadonlyArray<{
+  group: FilterGroup;
+  names: readonly SpectrumFilterName[];
+}> {
+  const menu: Array<{
+    group: FilterGroup;
+    names: readonly SpectrumFilterName[];
+  }> = [];
+  for (const group of FILTER_GROUPS) {
+    const names = filterNamesInGroup(group);
+    if (names.length > 0) menu.push({ group, names });
+  }
+  return menu;
+}