react-cheminfo 0.8.0 → 0.10.0

package/src/spectra/ui/SettingsPart.tsx

@@ -0,0 +1,60 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+/** What {@link SettingsPart} frames. */
+export interface SettingsPartProps {
+  /** What the part is called, drawn above everything in it. */
+  title: string;
+  /**
+   * One line under the heading saying what the part decides.
+   * @default undefined — the title says enough
+   */
+  summary?: string;
+  /** The controls the part is made of. */
+  children: ReactNode;
+}
+
+/**
+ * One part of a settings stage, under a heading of its own.
+ *
+ * The settings are long enough that a reader scrolling past a bare row of
+ * boxes cannot tell which stage they belong to, so every part carries the same
+ * heading, the same spacing and the same one-line summary — the panel is then
+ * read by its headings rather than by its fields.
+ * @param props - See {@link SettingsPartProps}.
+ * @returns The headed part.
+ */
+export function SettingsPart(props: SettingsPartProps): ReactElement {
+  const { title, summary, children } = props;
+
+  return (
+    <section style={PART_STYLE}>
+      <h4 style={TITLE_STYLE}>{title}</h4>
+      {summary === undefined ? null : (
+        <span style={SUMMARY_STYLE}>{summary}</span>
+      )}
+      {children}
+    </section>
+  );
+}
+
+const PART_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+  padding: 12,
+  borderRadius: 'var(--radius, 6px)',
+  border: '1px solid var(--border, #d8dee6)',
+  background: 'var(--surface, #ffffff)',
+} as const satisfies CSSProperties;
+
+const TITLE_STYLE = {
+  margin: 0,
+  fontSize: 13,
+  fontWeight: 600,
+  color: 'var(--text, #1c2127)',
+} as const satisfies CSSProperties;
+
+const SUMMARY_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;

package/src/spectra/ui/SpectraSettingsEditor.tsx

@@ -0,0 +1,143 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type {
+  PrincipalComponentSelection,
+  PrincipalComponentSettings,
+} from '../core/principalComponents.ts';
+import type {
+  PostProcessingSettings,
+  SpectraProcessorSettings,
+  SpectraSettings,
+} from '../core/settings.ts';
+import { settingsProblems } from '../core/settingsProblems.ts';
+
+import { NormalizationEditor } from './NormalizationEditor.tsx';
+import { PostProcessingEditor } from './PostProcessingEditor.tsx';
+import { PrincipalComponentSelect } from './PrincipalComponentSelect.tsx';
+import { ProblemList } from './ProblemList.tsx';
+import { SettingsPart } from './SettingsPart.tsx';
+
+/** A decomposition the panel offers a component picker for. */
+export interface PrincipalComponentPanel {
+  /** Which two components are drawn — both zero-based columns of the score matrix. */
+  selection: PrincipalComponentSelection;
+  /** Called with the pair whenever either axis changes. */
+  onSelectionChange: (selection: PrincipalComponentSelection) => void;
+  /** How many components the decomposition produced. */
+  count: number;
+  /**
+   * What `pca.getExplainedVariance()` returned, as fractions.
+   * @default undefined — the components are named without their share
+   */
+  explainedVariance?: readonly number[];
+  /**
+   * How the decomposition is computed, when the panel is to offer that too.
+   * @default undefined — only the two axes are offered
+   */
+  settings?: PrincipalComponentSettings;
+  /**
+   * Called with the decomposition's options; needed for them to be offered.
+   * @default undefined — the options are not offered
+   */
+  onSettingsChange?: (settings: PrincipalComponentSettings) => void;
+}
+
+/** What {@link SpectraSettingsEditor} edits. */
+export interface SpectraSettingsEditorProps {
+  /** Both settings objects the processor takes. */
+  value: SpectraSettings;
+  /** Called with the whole settings object on every edit. */
+  onChange: (settings: SpectraSettings) => void;
+  /**
+   * The spectra the processor holds, which turns every place an id is typed
+   * into a place one is picked.
+   * @default undefined — an id is typed rather than picked
+   */
+  spectrumIds?: readonly string[];
+  /**
+   * The decomposition, when the page draws one.
+   * @default undefined — no component picker is drawn
+   */
+  principalComponents?: PrincipalComponentPanel;
+}
+
+/**
+ * Everything `spectra-processor` can be told, in the order it happens.
+ *
+ * The panel is laid out as the pipeline runs — every spectrum is brought onto
+ * one grid first, then the matrix of them all is worked on, then the components
+ * are picked — because the settings only make sense in that order: a range is
+ * read in whatever units the chain has left the x axis in, and the matrix stage
+ * cannot say anything until every row is the same length.
+ *
+ * Nothing here blocks. A reader mid-thought may hold settings the processor
+ * would throw on, and the panel says which value it would throw on rather than
+ * refusing the edit.
+ * @param props - See {@link SpectraSettingsEditorProps}.
+ * @returns The whole settings panel.
+ */
+export function SpectraSettingsEditor(
+  props: SpectraSettingsEditorProps,
+): ReactElement {
+  const { value, onChange, spectrumIds, principalComponents } = props;
+  const problems = settingsProblems(value);
+
+  function writeProcessor(processor: SpectraProcessorSettings): void {
+    onChange({ ...value, processor });
+  }
+
+  function writePostProcessing(postProcessing: PostProcessingSettings): void {
+    onChange({ ...value, postProcessing });
+  }
+
+  return (
+    <div style={PANEL_STYLE}>
+      <SettingsPart
+        title="Every spectrum onto one grid"
+        summary="What the processor is built with. Until this is settled no two spectra can be compared, and changing it recomputes every one of them."
+      >
+        <NormalizationEditor
+          value={value.processor}
+          problems={problems}
+          onChange={writeProcessor}
+        />
+      </SettingsPart>
+
+      <SettingsPart
+        title="The matrix of them all"
+        summary="What every comparison reads, once the rows are the same length."
+      >
+        <PostProcessingEditor
+          value={value.postProcessing}
+          problems={problems}
+          spectrumIds={spectrumIds}
+          onChange={writePostProcessing}
+        />
+      </SettingsPart>
+
+      {principalComponents === undefined ? null : (
+        <SettingsPart
+          title="Principal components"
+          summary="Which two of them a score plot is drawn against."
+        >
+          <PrincipalComponentSelect
+            value={principalComponents.selection}
+            count={principalComponents.count}
+            explainedVariance={principalComponents.explainedVariance}
+            settings={principalComponents.settings}
+            onChange={principalComponents.onSelectionChange}
+            onSettingsChange={principalComponents.onSettingsChange}
+          />
+        </SettingsPart>
+      )}
+
+      <ProblemList problems={problems} title="The settings as they stand" />
+    </div>
+  );
+}
+
+const PANEL_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 12,
+} as const satisfies CSSProperties;

package/src/spectra/ui/SpectrumSelection.tsx

@@ -0,0 +1,193 @@
+import { Checkbox, InputGroup } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+/** What {@link SpectrumSelection} edits. */
+export interface SpectrumSelectionProps {
+  /**
+   * The ids the stage is asked for.
+   * @default undefined — every spectrum the processor holds is used
+   */
+  value?: readonly string[];
+  /** Called with the new list, or with undefined for every spectrum. */
+  onChange: (ids: string[] | undefined) => void;
+  /**
+   * The ids the processor holds, so they are ticked rather than typed.
+   * @default undefined — the ids are typed in as a comma-separated list
+   */
+  spectrumIds?: readonly string[];
+}
+
+/**
+ * Which spectra the stage is run over.
+ *
+ * Ticking every box hands up nothing at all rather than a list of every id,
+ * because the two are not the same thing: a list goes stale the moment another
+ * spectrum is loaded, while no list means whatever the processor holds now. An
+ * id the settings name and the processor does not hold gets a box of its own
+ * rather than being left out, since a box nobody can see is one the next click
+ * silently throws away.
+ * @param props - See {@link SpectrumSelectionProps}.
+ * @returns The boxes, or the field the ids are typed into.
+ */
+export function SpectrumSelection(props: SpectrumSelectionProps): ReactElement {
+  const { value, onChange, spectrumIds } = props;
+  const text = asText(value);
+  const [draft, setDraft] = useState(() => ({ text, held: text }));
+
+  // The settings changed from somewhere else — a preset, a reset, a pasted
+  // configuration — so the box has to follow rather than hold the old text.
+  if (draft.held !== text) setDraft({ text, held: text });
+
+  if (spectrumIds === undefined) {
+    return (
+      <label style={FIELD_STYLE}>
+        <span style={LABEL_STYLE}>Spectra</span>
+        <InputGroup
+          size="small"
+          fill
+          aria-label="Spectra"
+          placeholder="every spectrum the processor holds"
+          spellCheck={false}
+          autoComplete="off"
+          value={draft.text}
+          onValueChange={(typed) => {
+            setDraft({ text: typed, held: text });
+            onChange(readIds(typed));
+          }}
+        />
+        <span style={HELP_STYLE}>
+          One id per entry, separated by commas. Leave it empty for every
+          spectrum.
+        </span>
+      </label>
+    );
+  }
+
+  const chosen = new Set(value ?? spectrumIds);
+  const boxes = withHeld(spectrumIds, value);
+  const held = new Set(spectrumIds);
+  return (
+    <div style={FIELD_STYLE}>
+      <span style={LABEL_STYLE}>Spectra</span>
+      {boxes.map((id) => (
+        <Checkbox
+          key={id}
+          style={BOX_STYLE}
+          label={
+            held.has(id) ? id : `${id} — not a spectrum the processor holds`
+          }
+          checked={chosen.has(id)}
+          onChange={(event) => {
+            onChange(
+              toggle(
+                boxes,
+                spectrumIds,
+                chosen,
+                id,
+                event.currentTarget.checked,
+              ),
+            );
+          }}
+        />
+      ))}
+      <span style={HELP_STYLE}>
+        With every box ticked the settings name no spectrum at all, so one
+        loaded later is included too.
+      </span>
+    </div>
+  );
+}
+
+/**
+ * The ids as the box shows them.
+ * @param ids - What the settings hold.
+ * @returns Their text, empty when the settings name none.
+ */
+function asText(ids: readonly string[] | undefined): string {
+  return ids === undefined ? '' : ids.join(', ');
+}
+
+/**
+ * The text as a list of ids.
+ * @param text - What was typed.
+ * @returns The ids, or undefined when nothing is left once trimmed.
+ */
+function readIds(text: string): string[] | undefined {
+  const ids = text
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '');
+  return ids.length === 0 ? undefined : ids;
+}
+
+/**
+ * Every id that gets a box: the processor's, then any the settings add to them.
+ * @param spectrumIds - Every id the processor holds.
+ * @param value - The ids the settings name.
+ * @returns The processor's ids first, so the order never moves under a click.
+ */
+function withHeld(
+  spectrumIds: readonly string[],
+  value: readonly string[] | undefined,
+): string[] {
+  const boxes = [...spectrumIds];
+  const held = new Set(spectrumIds);
+  for (const id of value ?? []) {
+    if (!held.has(id)) {
+      held.add(id);
+      boxes.push(id);
+    }
+  }
+  return boxes;
+}
+
+/**
+ * The selection with one spectrum added or taken out.
+ * @param boxes - Every id drawn, in the order it is drawn.
+ * @param spectrumIds - Every id the processor holds.
+ * @param chosen - The ids ticked now.
+ * @param id - Which one was clicked.
+ * @param checked - Whether it is now ticked.
+ * @returns The new list, or undefined once it is exactly what the processor holds.
+ */
+function toggle(
+  boxes: readonly string[],
+  spectrumIds: readonly string[],
+  chosen: ReadonlySet<string>,
+  id: string,
+  checked: boolean,
+): string[] | undefined {
+  const next: string[] = [];
+  for (const held of boxes) {
+    const keep = held === id ? checked : chosen.has(held);
+    if (keep) next.push(held);
+  }
+  if (next.length !== spectrumIds.length) return next;
+  for (let index = 0; index < next.length; index++) {
+    if (next[index] !== spectrumIds[index]) return next;
+  }
+  return undefined;
+}
+
+const FIELD_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--text-muted, #5b6875)',
+} as const satisfies CSSProperties;
+
+const BOX_STYLE = {
+  margin: 0,
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const HELP_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;

package/src/spectra/ui/ZoneRows.tsx

@@ -0,0 +1,159 @@
+import { Button, Switch } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+import { NumberField } from './NumberField.tsx';
+import { fitKeys, nextKey } from './rowKeys.ts';
+
+/** One stretch of x, as every part of the settings spells it. */
+export interface Zone {
+  /** Where it starts, in x units. */
+  from?: number;
+  /** Where it ends, in x units. */
+  to?: number;
+  /** Whether it is only hidden from the chart. */
+  ignore?: boolean;
+}
+
+/** What {@link ZoneRows} edits. */
+export interface ZoneRowsProps {
+  /** What the list is called. */
+  label: string;
+  /** The stretches, in the order they are listed. */
+  value: readonly Zone[];
+  /** Called with the new list on every edit. */
+  onChange: (zones: Zone[]) => void;
+  /**
+   * Whether each row offers the switch that hides a zone from the chart.
+   * @default false — only the two bounds are drawn
+   */
+  withIgnore?: boolean;
+  /**
+   * One line under the list saying what the zones do.
+   * @default undefined — the label says enough
+   */
+  help?: string;
+}
+
+/**
+ * A list of x stretches: exclusions, zones to keep, zones to drop.
+ *
+ * The same widget stands for all four places the settings ask for them, because
+ * they are the same thing and a reader who has learnt one row has learnt them
+ * all. A new row opens empty rather than guessing bounds — a zone the reader
+ * did not choose would silently change the data.
+ * @param props - See {@link ZoneRowsProps}.
+ * @returns The labelled list.
+ */
+export function ZoneRows(props: ZoneRowsProps): ReactElement {
+  const { label, value, onChange, withIgnore = false, help } = props;
+  const [rowKeys, setRowKeys] = useState<readonly number[]>(() =>
+    value.map((_, index) => index),
+  );
+
+  // A zone carries no identity of its own, so one is kept beside the list:
+  // without it React reuses a removed row's box for the row that slides up,
+  // and the half-typed number in it goes with the wrong zone.
+  if (rowKeys.length !== value.length) {
+    setRowKeys(fitKeys(rowKeys, value.length));
+  }
+
+  function write(index: number, patch: Zone): void {
+    onChange(
+      value.map((zone, at) => (at === index ? { ...zone, ...patch } : zone)),
+    );
+  }
+
+  return (
+    <div style={LIST_STYLE}>
+      <span style={LABEL_STYLE}>{label}</span>
+      {value.length === 0 ? (
+        <span style={EMPTY_STYLE}>None — the whole range is used.</span>
+      ) : null}
+      {value.map((zone, index) => (
+        <div key={rowKeys[index] ?? index} style={ROW_STYLE}>
+          <NumberField
+            label="From"
+            value={zone.from}
+            onChange={(from) => {
+              write(index, { from });
+            }}
+          />
+          <NumberField
+            label="To"
+            value={zone.to}
+            onChange={(to) => {
+              write(index, { to });
+            }}
+          />
+          {withIgnore ? (
+            <Switch
+              checked={zone.ignore === true}
+              label="Hide on the chart only"
+              style={SWITCH_STYLE}
+              onChange={(event) => {
+                write(index, { ignore: event.currentTarget.checked });
+              }}
+            />
+          ) : null}
+          <Button
+            icon="cross"
+            variant="minimal"
+            size="small"
+            aria-label={`Remove ${label} ${String(index + 1)}`}
+            onClick={() => {
+              setRowKeys(rowKeys.filter((_, at) => at !== index));
+              onChange(value.filter((_, at) => at !== index));
+            }}
+          />
+        </div>
+      ))}
+      <div>
+        <Button
+          icon="plus"
+          size="small"
+          text="Add a zone"
+          onClick={() => {
+            setRowKeys([...rowKeys, nextKey(rowKeys)]);
+            onChange([...value, {}]);
+          }}
+        />
+      </div>
+      {help === undefined ? null : <span style={HELP_STYLE}>{help}</span>}
+    </div>
+  );
+}
+
+const LIST_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--text-muted, #5b6875)',
+} as const satisfies CSSProperties;
+
+const EMPTY_STYLE = {
+  fontSize: 12,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'flex-end',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const SWITCH_STYLE = {
+  margin: 0,
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const HELP_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;

package/src/spectra/ui/index.ts

@@ -0,0 +1,9 @@
+export type { FilterChainEditorProps } from './FilterChainEditor.tsx';
+export { FilterChainEditor } from './FilterChainEditor.tsx';
+export type { PrincipalComponentSelectProps } from './PrincipalComponentSelect.tsx';
+export { PrincipalComponentSelect } from './PrincipalComponentSelect.tsx';
+export type {
+  PrincipalComponentPanel,
+  SpectraSettingsEditorProps,
+} from './SpectraSettingsEditor.tsx';
+export { SpectraSettingsEditor } from './SpectraSettingsEditor.tsx';

package/src/spectra/ui/matrixSteps.ts

@@ -0,0 +1,128 @@
+import type { MatrixFilter, MatrixFilterName } from '../core/settings.ts';
+import { MATRIX_FILTER_NAMES } from '../core/settingsProblems.ts';
+
+/** One editable option of a matrix step. */
+export interface MatrixOptionField {
+  /** Which key it sits under in the step's options. */
+  key: string;
+  /** What the field is called. */
+  label: string;
+  /**
+   * What upstream does when it is left empty.
+   * @default undefined — the field carries no placeholder
+   */
+  placeholder?: string;
+}
+
+/** What the editor knows about one matrix step. */
+export interface MatrixStep {
+  /** What it is called in the list. */
+  label: string;
+  /** One line saying what it does to the matrix. */
+  summary: string;
+  /** Its editable options, empty when it takes none. */
+  fields: readonly MatrixOptionField[];
+}
+
+/**
+ * What the editor knows about the three steps the matrix stage dispatches.
+ *
+ * Keyed by the name rather than listed, so a name the processor's own switch
+ * does not match cannot reach the menu: an unknown name is the one way this
+ * stage throws.
+ */
+export const MATRIX_STEPS: Readonly<Record<MatrixFilterName, MatrixStep>> = {
+  pqn: {
+    label: 'Probabilistic quotient normalization',
+    summary:
+      'Divides every spectrum by its own dilution factor, read against the median spectrum. Min is declared upstream but never read.',
+    fields: [
+      { key: 'min', label: 'Min' },
+      { key: 'max', label: 'Max', placeholder: '100' },
+    ],
+  },
+  centerMean: {
+    label: 'Centre on the mean',
+    summary:
+      'Subtracts the mean of every column. It takes no options: anything set here is ignored.',
+    fields: [],
+  },
+  rescale: {
+    label: 'Rescale',
+    summary: 'Brings the whole matrix between two values.',
+    fields: [
+      { key: 'min', label: 'Min', placeholder: '0' },
+      { key: 'max', label: 'Max', placeholder: '1' },
+    ],
+  },
+};
+
+/** The add menu: the empty prompt, then the only three names that run. */
+export const MATRIX_ADD_OPTIONS: ReadonlyArray<{
+  value: string;
+  label: string;
+}> = [
+  { value: '', label: 'Add a matrix step…' },
+  ...MATRIX_FILTER_NAMES.map((name) => ({
+    value: name,
+    label: MATRIX_STEPS[name].label,
+  })),
+];
+
+/**
+ * What the editor knows about a step, when it knows it at all.
+ * @param name - The name the settings hold.
+ * @returns Its entry, or undefined for a name the processor would throw on.
+ */
+export function matrixStep(name: string | undefined): MatrixStep | undefined {
+  if (name === undefined) return undefined;
+  return Object.hasOwn(MATRIX_STEPS, name)
+    ? MATRIX_STEPS[name as MatrixFilterName]
+    : undefined;
+}
+
+/**
+ * What one option of a step is set to.
+ * @param step - The step.
+ * @param key - Which option to read.
+ * @returns The number, or undefined when the step leaves it to upstream.
+ */
+export function readMatrixOption(
+  step: MatrixFilter,
+  key: string,
+): number | undefined {
+  const options: unknown = step.options;
+  if (typeof options !== 'object' || options === null) return undefined;
+  const held = (options as Record<string, unknown>)[key];
+  return typeof held === 'number' ? held : undefined;
+}
+
+/**
+ * The step with one option set, or dropped when the box was emptied.
+ *
+ * Dropping rather than writing `undefined` is what lets a cleared box mean
+ * "whatever upstream does", which is the only way back to the default once a
+ * reader has typed over it.
+ * @param step - The step.
+ * @param key - Which option to write.
+ * @param value - What to set it to, or undefined to clear it.
+ * @returns A new step.
+ */
+export function writeMatrixOption(
+  step: MatrixFilter,
+  key: string,
+  value: number | undefined,
+): MatrixFilter {
+  const held: unknown = step.options;
+  const source: Record<string, unknown> =
+    typeof held === 'object' && held !== null
+      ? (held as Record<string, unknown>)
+      : {};
+  const options: Record<string, unknown> = {};
+  for (const [name, option] of Object.entries(source)) {
+    if (name !== key) options[name] = option;
+  }
+  if (value !== undefined) options[key] = value;
+  if (Object.keys(options).length === 0) return { name: step.name };
+  return { name: step.name, options };
+}