react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/projectionVariablesWords.ts

@@ -0,0 +1,105 @@
+/**
+ * What the "what differs" tab says about its own panels: the sentence over
+ * them, the key naming their colours, and the name under the horizontal axis.
+ *
+ * They are separated from what the panels draw because every one of them is a
+ * claim about the picture rather than part of it, and a claim is worth reading
+ * — and testing — on its own. A caption that promises bars over a panel of
+ * lines is a bug nobody sees in a series array.
+ */
+
+import type { OverlayLegendEntry } from '../../overlay/ui/OverlayLegend.tsx';
+import type { LoadingProfiles } from '../core/loadingProfiles.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { fillCopy } from '../core/projectionCopy.ts';
+import type { VariableAxis } from '../core/variableAxis.ts';
+
+/**
+ * The tab's own sentence, which has to describe the view the reader is looking
+ * at and the shape it is drawn in.
+ *
+ * Both matter, and neither can stand in for the other. Two of the four views
+ * draw a sample profile as a line whatever the measurements are, so a sentence
+ * chosen from the axis alone promises bars over a panel of lines. The other two
+ * draw weights, and there the axis decides: named measurements become bars and
+ * a number line stays a line.
+ * @param built - The panels as they were built, for the view and the axis.
+ * @param copy - The words the tab writes.
+ * @returns The sentence.
+ */
+export function variablesCaption(
+  built: LoadingProfiles,
+  copy: ProjectionCopy,
+): string {
+  const { axis, view } = built;
+  if (view === 'effect') return copy.intro.variablesEffect;
+  if (view === 'sample') return copy.intro.variablesSample;
+  if (axis.kind === 'named') return copy.intro.variablesNamed;
+  return fillCopy(copy.intro.variablesContinuous, { axis: plural(axis.label) });
+}
+
+/**
+ * The sentence naming what colour and shape mean, which is the view's own.
+ * @param built - The panels as they were built.
+ * @param copy - The words the tab writes.
+ * @param sample - What the one selected sample is called.
+ * @returns The sentence.
+ */
+export function legendTitle(
+  built: LoadingProfiles,
+  copy: ProjectionCopy,
+  sample: string,
+): string {
+  const { legend } = copy;
+  if (built.view === 'effect') return legend.variablesEffect;
+  if (built.view === 'rescaled') return legend.variablesRescaled;
+  if (built.view === 'sample') {
+    return fillCopy(legend.variablesSample, { sample });
+  }
+  return legend.variablesWeights;
+}
+
+/**
+ * Every drawn component as a line, and the average as a grey dashed one.
+ * @param built - The panels as they were built.
+ * @param average - Whether the average sample is drawn.
+ * @param copy - The words the tab writes.
+ * @returns The entries, in the panels' own order.
+ */
+export function legendEntries(
+  built: LoadingProfiles,
+  average: boolean,
+  copy: ProjectionCopy,
+): OverlayLegendEntry[] {
+  const entries: OverlayLegendEntry[] = built.profiles.map((profile) => ({
+    id: `component-${profile.index}`,
+    label: profile.label,
+    color: profile.color,
+    shape: 'line',
+  }));
+  if (average) {
+    entries.push({
+      id: 'average',
+      label: copy.help.showAverage.title,
+      color: 'var(--text-faint)',
+      shape: 'dashed',
+    });
+  }
+  return entries;
+}
+
+/**
+ * What the horizontal axis measures, with its unit in brackets.
+ * @param axis - How the measurements are laid out.
+ * @returns The axis title.
+ */
+export function axisCaption(axis: VariableAxis): string {
+  if (axis.kind === 'named') return axis.label ?? 'Measurement';
+  const unit = axis.unit ?? '';
+  return unit === '' ? axis.label : `${axis.label} (${unit})`;
+}
+
+function plural(word: string): string {
+  const lower = word.toLowerCase();
+  return lower.endsWith('s') ? lower : `${lower}s`;
+}

package/src/projection/ui/projectionViewChoices.ts

@@ -0,0 +1,77 @@
+/**
+ * The four views of the "what differs" tab, and which of them a run can draw.
+ *
+ * The bar offers them and so does the panel behind the cog, and a list built
+ * twice is a list where one copy keeps offering a view the other has already
+ * learnt to grey out.
+ */
+
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionVariablesView } from '../core/projectionOptions.ts';
+
+/** Which of the four views the run has the data to draw. */
+export interface ProjectionVariablesAvailability {
+  /** Whether the run reported the average sample and how far each component reaches. */
+  canShowEffect: boolean;
+  /** Whether the model divided each measurement by its own spread. */
+  canRescale: boolean;
+  /** Whether exactly one sample is selected. */
+  canPickSample: boolean;
+}
+
+/**
+ * The four views, each greyed with its reason when the run cannot draw it.
+ *
+ * A view whose data the run never reported is greyed rather than dropped, with
+ * the reason on the choice itself: a reader who cannot see that "Weights in
+ * your units" exists never learns to ask their colleague for a scaled model.
+ * @param copy - The words the viewer writes.
+ * @param available - See {@link ProjectionVariablesAvailability}.
+ * @returns The choices, in the order they are offered.
+ */
+export function projectionViewChoices(
+  copy: ProjectionCopy,
+  available: ProjectionVariablesAvailability,
+): ReadonlyArray<OverlayOption<ProjectionVariablesView>> {
+  const { canShowEffect, canRescale, canPickSample } = available;
+  const { view } = copy.bar;
+
+  return [
+    {
+      value: 'effect',
+      label: view.effect,
+      ...whenOff(canShowEffect, NO_AVERAGE),
+    },
+    { value: 'weights', label: view.weights },
+    {
+      value: 'rescaled',
+      label: view.rescaled,
+      ...whenOff(canRescale, NO_SCALES),
+    },
+    {
+      value: 'sample',
+      label: view.sample,
+      ...whenOff(canPickSample, NO_SAMPLE),
+    },
+  ];
+}
+
+/**
+ * A choice the run cannot support, greyed with the reason on it.
+ * @param available - Whether the data behind the choice is there.
+ * @param reason - What to tell a reader whose pointer cannot take it.
+ * @returns The two fields an unavailable choice carries, or neither.
+ */
+function whenOff(
+  available: boolean,
+  reason: string,
+): { disabled?: true; title?: string } {
+  return available ? {} : { disabled: true, title: reason };
+}
+
+/** Why a view is greyed, written as the thing the reader would have to change. */
+const NO_AVERAGE =
+  'Only when the run reported an average sample to push along the component.';
+const NO_SCALES = 'Only when the model divided each measurement by its spread.';
+const NO_SAMPLE = 'Select exactly one sample on the map first.';

package/src/projection/ui/projectionViewerProps.ts

@@ -0,0 +1,190 @@
+/**
+ * What a caller hands a {@link ProjectionViewer}, and what it hands back.
+ *
+ * The types live beside the component rather than inside it because the shell
+ * is short and its options are not: a reader looking for what the viewer does
+ * should not have to scroll past a page of documented props to find it.
+ */
+
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionCopyPatch } from '../core/projectionCopyPatch.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ProjectionSamples } from '../core/projectionSamples.ts';
+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. */
+  result: ProjectionResult;
+  /** Who the rows are. */
+  samples: ProjectionSamples;
+  /**
+   * The tab showing. Present, the caller owns it, which is how a page puts the
+   * tab in its own URL.
+   * @default undefined — the viewer keeps its own
+   */
+  tab?: ProjectionTab;
+  /**
+   * Which panels the site offers, in any order.
+   *
+   * The viewer already hides a panel the result cannot fill, so this is for the
+   * other reason a panel should not be there: the page around it has no room,
+   * or has already said the same thing in its own words. Naming a panel the
+   * result cannot fill does not conjure it, and the map survives every filter —
+   * a viewer showing nothing at all is not a viewer.
+   *
+   * With one panel left there are no pills, so `panels={['map']}` is how a site
+   * embeds the scores plot and nothing else.
+   * @default undefined — every panel the result can fill
+   */
+  panels?: readonly ProjectionTab[];
+  /**
+   * The tab it opens on. A tab the result cannot fill, or that `panels` leaves
+   * out, is ignored.
+   * @default the first tab the result can fill
+   */
+  defaultTab?: ProjectionTab;
+  /**
+   * Called when the reader moves to another tab.
+   * @default undefined
+   */
+  onTabChange?: (tab: ProjectionTab) => void;
+  /**
+   * The selected rows, by name. Present, the caller owns the selection; the
+   * outline drawn while a lasso is being dragged stays inside the viewer
+   * either way.
+   * @default undefined — the viewer keeps its own
+   */
+  selected?: readonly string[];
+  /**
+   * The rows selected when it opens.
+   * @default undefined — nothing is selected
+   */
+  defaultSelected?: readonly string[];
+  /**
+   * Called when a lasso is released, a dot is clicked, a group is picked from
+   * the legend, or the selection is cleared — never while a lasso is being
+   * drawn, because a caller filtering a table behind it could not survive
+   * sixty calls a second. The rows arrive by name, so a caller never has to
+   * keep a second copy of the row order to read them.
+   * @default undefined
+   */
+  onSelectionChange?: (selection: ProjectionSelection) => void;
+  /**
+   * Called as the pointer crosses the "what differs" panels, and with `null`
+   * when it leaves. It fires on every measurement the pointer enters, so a
+   * caller doing real work in it — lighting a band on a spectrum beside the
+   * viewer — should hold the value in a ref rather than in state.
+   * @default undefined
+   */
+  onTrackVariable?: (track: ProjectionVariableTrack | null) => void;
+  /**
+   * Called with the row under the pointer on the map, or `null`. The card is
+   * drawn either way; this is for a page lighting up its own table.
+   * @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.
+   * @default undefined — the viewer keeps its own
+   */
+  options?: Partial<ProjectionOptions>;
+  /**
+   * The options it opens with, when it keeps its own.
+   * @default {}
+   */
+  defaultOptions?: Partial<ProjectionOptions>;
+  /**
+   * Called with every option after a change, not only the one that changed.
+   * @default undefined
+   */
+  onOptionsChange?: (options: ProjectionOptions) => void;
+  /**
+   * The words the viewer writes, merged over its own one key at a time.
+   * @default PROJECTION_COPY
+   */
+  copy?: ProjectionCopyPatch<ProjectionCopy>;
+  /**
+   * Height of the figure, in pixels. The width always follows the container.
+   * @default 460
+   */
+  height?: number;
+  /**
+   * How a number is written in a hover card and a readout.
+   * @default a rounding to three decimals with the trailing zeros dropped
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Whether a drag on a touch screen draws a lasso rather than scrolling the
+   * page.
+   * @default false
+   */
+  touchLasso?: boolean;
+  /**
+   * Whether the wheel zooms the map about the pointer, once the pointer has
+   * rested on the picture for half a second. On, because the viewer is given a
+   * panel of its own; a page that sets it in a column of prose should turn it
+   * off, so that a reader on their way past the figure keeps their scroll.
+   * @default true
+   */
+  wheelZoom?: boolean;
+  /**
+   * What a figure saved from the bar is called, without its extension; the
+   * view it was saved from is added to it, so the map of a run called
+   * `ecstasy` arrives as `ecstasy-map.png`. Name it after the data rather than
+   * after the tool: a reader with four of these in a downloads folder cannot
+   * tell four `projection-map.png` apart.
+   * @default 'projection'
+   */
+  fileName?: string;
+  /**
+   * Class the viewer carries, in addition to `projection-viewer`.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Value of the `data-testid` attribute of the viewer.
+   * @default undefined
+   */
+  testId?: string;
+}

package/src/projection/ui/useProjectionState.ts

@@ -0,0 +1,224 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { resolveProjectionOptions } from '../core/projectionOptions.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import { resolveProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+import { projectionTabs } from '../core/projectionTabs.ts';
+
+import type { ProjectionSelection } from './projectionSelection.ts';
+import {
+  indexProjectionIds,
+  projectionNamesOf,
+  projectionRowsOf,
+} from './projectionSelection.ts';
+import type { ProjectionViewerProps } from './projectionViewerProps.ts';
+
+/**
+ * What {@link useProjectionState} needs: the run, the rows, and the three
+ * pieces of state a caller may take over.
+ *
+ * It is the viewer's own props narrowed rather than a second list of the same
+ * eleven fields, so a default documented on the component is the default the
+ * hook actually applies and the two cannot drift apart.
+ */
+export type ProjectionStateOptions = Pick<
+  ProjectionViewerProps,
+  | 'result'
+  | 'samples'
+  | 'tab'
+  | 'defaultTab'
+  | 'onTabChange'
+  | 'selected'
+  | 'defaultSelected'
+  | 'onSelectionChange'
+  | 'options'
+  | 'panels'
+  | 'defaultOptions'
+  | 'onOptionsChange'
+>;
+
+/** What every tab reads, and the five ways any of them changes it. */
+export interface ProjectionStateApi {
+  /** The tabs this result can fill, in reading order. */
+  tabs: readonly ProjectionTab[];
+  /** The one showing. */
+  tab: ProjectionTab;
+  /** Move to another tab. One the result cannot fill is ignored. */
+  setTab: (tab: ProjectionTab) => void;
+  /** The groups as every figure draws them, resolved once per change. */
+  groups: ResolvedProjectionGroups;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** Change some of them; the rest are carried over and checked again. */
+  setOptions: (patch: Partial<ProjectionOptions>) => void;
+  /** The selected rows, as indices, which is what a plot draws. */
+  selected: readonly number[];
+  /** Settle a selection a plot's own gesture produced. */
+  settleSelection: (change: SelectionChange) => void;
+  /** Settle one from elsewhere — a legend entry, a table beside the figure. */
+  selectRows: (
+    rows: readonly number[],
+    mode: ScatterSelectionMode,
+    source: ProjectionSelection['source'],
+  ) => void;
+  /** Draw one pair of axes on the map, which is what a cell of the grid does. */
+  selectPair: (xAxis: number, yAxis: number) => void;
+}
+
+/**
+ * The tab, the pair of axes, the selection and the options, controlled or not.
+ *
+ * The tabs are one tool only while they agree, which is why this is one hook
+ * and not four pieces of state in the shell: a pair promoted from the grid has
+ * to arrive on the map, and a lasso drawn there has to still be selected when
+ * the reader comes back to it.
+ *
+ * Each of tab, selection and options is owned by the caller from the moment
+ * its prop is passed and by the hook otherwise, and the two are never mixed: a
+ * controlled value wins on every render, so a caller told about a change that
+ * does not pass the new value back sees the figure stay where it was, rather
+ * than drift out of step with the address bar it is driven from. A `default`
+ * is read once, when the viewer mounts, and changing it later moves nothing.
+ *
+ * Selections cross this boundary as names rather than row numbers. A caller
+ * lighting up its own table already holds the names; handing back indices
+ * would make it keep a second copy of the row order, and that copy is exactly
+ * what goes stale the first time the data behind it is filtered.
+ * @param options - See {@link ProjectionStateOptions}.
+ * @returns The shared state. See {@link ProjectionStateApi}.
+ */
+export function useProjectionState(
+  options: ProjectionStateOptions,
+): ProjectionStateApi {
+  const {
+    result,
+    samples,
+    tab,
+    defaultTab,
+    onTabChange,
+    selected,
+    defaultSelected,
+    onSelectionChange,
+    options: heldOptions,
+    defaultOptions,
+    onOptionsChange,
+    panels,
+  } = options;
+
+  const { ids } = samples;
+  const tabs = useMemo(() => projectionTabs(result, panels), [result, panels]);
+  const rowOfId = useMemo(() => indexProjectionIds(ids), [ids]);
+
+  const [ownTab, setOwnTab] = useState<ProjectionTab | undefined>(defaultTab);
+  const [ownSelected, setOwnSelected] = useState<readonly number[]>(() =>
+    projectionRowsOf(defaultSelected, rowOfId),
+  );
+  const [ownOptions, setOwnOptions] = useState<Partial<ProjectionOptions>>(
+    () => defaultOptions ?? {},
+  );
+
+  const groups = useMemo(
+    () => resolveProjectionGroups(samples, result.scores.rows),
+    [result, samples],
+  );
+  const settled = useMemo(
+    () => resolveProjectionOptions(heldOptions ?? ownOptions, result),
+    [heldOptions, ownOptions, result],
+  );
+
+  const setTab = useCallback(
+    (wanted: ProjectionTab) => {
+      const reachable = inReach(wanted, tabs);
+      if (reachable === undefined) return;
+      if (tab === undefined) setOwnTab(reachable);
+      onTabChange?.(reachable);
+    },
+    [onTabChange, tab, tabs],
+  );
+
+  const setOptions = useCallback(
+    (patch: Partial<ProjectionOptions>) => {
+      const next = resolveProjectionOptions({ ...settled, ...patch }, result);
+      if (heldOptions === undefined) setOwnOptions(next);
+      onOptionsChange?.(next);
+    },
+    [heldOptions, onOptionsChange, result, settled],
+  );
+
+  const selectRows = useCallback(
+    (
+      rows: readonly number[],
+      mode: ScatterSelectionMode,
+      source: ProjectionSelection['source'],
+    ) => {
+      if (selected === undefined) setOwnSelected(rows);
+      onSelectionChange?.({
+        ids: projectionNamesOf(rows, ids),
+        indices: rows,
+        mode,
+        source,
+      });
+    },
+    [ids, onSelectionChange, selected],
+  );
+
+  const settleSelection = useCallback(
+    (change: SelectionChange) => {
+      selectRows(change.indices, change.mode, change.source);
+    },
+    [selectRows],
+  );
+
+  const selectPair = useCallback(
+    (xAxis: number, yAxis: number) => {
+      setOptions({ xAxis, yAxis });
+      setTab('map');
+    },
+    [setOptions, setTab],
+  );
+
+  return {
+    tabs,
+    // The last resort is the first tab offered, never the map: a site that
+    // narrowed `panels` away from it would otherwise be shown the one panel it
+    // said it had no room for, under a strip that does not name it.
+    tab: inReach(tab, tabs) ?? inReach(ownTab, tabs) ?? tabs[0] ?? 'map',
+    setTab,
+    groups,
+    options: settled,
+    setOptions,
+    selected:
+      selected === undefined
+        ? ownSelected
+        : projectionRowsOf(selected, rowOfId),
+    settleSelection,
+    selectRows,
+    selectPair,
+  };
+}
+
+/**
+ * The wanted tab, when the result can actually fill it.
+ *
+ * A saved tab outlives the data it was saved on: a page reopening on the
+ * shares tab and handed a UMAP would otherwise show an empty panel with no
+ * obvious way back, so an unreachable tab is answered with nothing and the
+ * caller falls through to the first tab there is.
+ * @param wanted - The tab asked for, if any.
+ * @param tabs - The tabs the result can fill.
+ * @returns The tab, or `undefined` when it is not one of them.
+ */
+function inReach(
+  wanted: ProjectionTab | undefined,
+  tabs: readonly ProjectionTab[],
+): ProjectionTab | undefined {
+  if (wanted === undefined) return undefined;
+  for (const tab of tabs) {
+    if (tab === wanted) return wanted;
+  }
+  return undefined;
+}