react-cheminfo 0.9.0 → 0.10.0

package/src/projection/ui/projectionVariablesModel.ts

@@ -0,0 +1,231 @@
+/**
+ * What the "what differs" panels draw, worked out before React sees it: the
+ * series, the slot names, and the line reported as the pointer crosses a
+ * measurement. The readout is the part a caller integrates against, so it
+ * should be readable, and testable, without a renderer. What the tab *says*
+ * about the panels lives beside this, in `projectionVariablesWords.ts`.
+ */
+
+import type { ChartSeries } from '../../chart/ui/TrackedLineChart.tsx';
+import type { ChartStickSeries } from '../../chart/ui/TrackedStickChart.tsx';
+import type {
+  LoadingProfile,
+  LoadingProfiles,
+} from '../core/loadingProfiles.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { variableDecimals, variableLabel } from '../core/variableAxis.ts';
+
+/** Where the pointer is on the "what differs" tab, and what stands under it. */
+export interface ProjectionVariableTrack {
+  /** Which original measurement, from 0. */
+  index: number;
+  /** What it is called — a name, or a value written out with its unit. */
+  label: string;
+  /**
+   * Its position on a number line, e.g. 1650 for a wavenumber.
+   * @default undefined — the measurements are named and have no position
+   */
+  position?: number;
+  /** Every drawn component and its value there, in the order the panels are in. */
+  series: ReadonlyArray<{
+    /** Which component, from 0. */
+    axis: number;
+    /** What it is called, e.g. `PC 2`. */
+    name: string;
+    /** The colour it carries on every tab. */
+    color: string;
+    /** Its value at this measurement, in whatever the current view draws. */
+    value: number;
+  }>;
+  /** The line the tab writes, e.g. `1650 cm⁻¹ · PC 2 weight +0.081`. */
+  readout: string;
+}
+
+/**
+ * What the pointer is over, with its readout already written.
+ *
+ * The sign is written as a real minus sign and never dropped, because a weight
+ * of −0.63 and one of +0.63 are the two opposite ends of the same component
+ * and a readout that shows them alike is worse than no readout.
+ * @param built - The panels as they were built.
+ * @param slot - Which drawn slot the pointer entered.
+ * @param panel - Which panel it entered, since that names the component.
+ * @param format - How a number is written.
+ * @returns The track.
+ */
+export function variableTrack(
+  built: LoadingProfiles,
+  slot: number,
+  panel: number,
+  format: (value: number) => string,
+): ProjectionVariableTrack {
+  const measurement = built.order[slot] ?? slot;
+  const label = variableLabel(built.axis, measurement);
+  const series: ProjectionVariableTrack['series'] = built.profiles.map(
+    (profile) => ({
+      axis: profile.index,
+      name: profile.label,
+      color: profile.color,
+      value: profile.values[slot] ?? Number.NaN,
+    }),
+  );
+  const here = built.profiles[panel];
+  const value = here?.values[slot] ?? Number.NaN;
+  const unit =
+    built.valueLabel === '' ? '' : `${built.valueLabel.toLowerCase()} `;
+  return {
+    index: measurement,
+    label,
+    position:
+      built.axis.kind === 'named' ? undefined : built.axis.values[measurement],
+    series,
+    readout: `${label} · ${here?.label ?? ''} ${unit}${signed(value, format)}`,
+  };
+}
+
+/**
+ * One panel's series: the faint average behind, then the component, then the
+ * component's other end where the view draws two.
+ * @param built - The panels as they were built.
+ * @param profile - The component this panel is for.
+ * @param bars - Whether it is drawn as bars from the zero line.
+ * @param average - Whether the average sample is drawn behind it.
+ * @param copy - The words the tab writes.
+ * @returns The series, in drawing order.
+ */
+export function panelSeries(
+  built: LoadingProfiles,
+  profile: LoadingProfile,
+  bars: boolean,
+  average: boolean,
+  copy: ProjectionCopy,
+): ChartSeries[] {
+  const series: ChartSeries[] = [];
+  if (average && built.mean !== undefined) {
+    series.push({
+      id: 'average',
+      label: copy.help.showAverage.title,
+      values: built.mean,
+      color: 'var(--text-faint)',
+      muted: true,
+    });
+  }
+  series.push({
+    id: `component-${profile.index}`,
+    label: profile.label,
+    values: profile.values,
+    color: profile.color,
+    kind: bars ? 'bar' : 'line',
+  });
+  if (profile.secondValues !== undefined) {
+    series.push({
+      id: `component-${profile.index}-other`,
+      label: profile.label,
+      values: profile.secondValues,
+      color: profile.color,
+    });
+  }
+  return series;
+}
+
+/**
+ * One panel's sticks, for measurements picked off a spectrum rather than
+ * sampled across one.
+ *
+ * The views part company from the line chart's here. A loading is a stick from
+ * the zero rule, up for the masses that make a score high and down for the
+ * ones that make it low, which is the drawing the panel exists for. The
+ * "effect" view cannot be two stick sets — they stand at the same masses, so
+ * the shorter one is hidden inside the taller and the reader sees one wrong
+ * spectrum — so it is one stick per peak spanning the two ends instead. That
+ * loses nothing: the two ends are symmetric about the average and share one
+ * colour on a line chart too, so what was being said was always the reach and
+ * never the direction.
+ * @param built - The panels as they were built.
+ * @param profile - The component this panel is for.
+ * @param average - Whether the average sample is drawn behind it.
+ * @param copy - The words the tab writes.
+ * @returns The series, in drawing order.
+ */
+export function panelSticks(
+  built: LoadingProfiles,
+  profile: LoadingProfile,
+  average: boolean,
+  copy: ProjectionCopy,
+): ChartStickSeries[] {
+  const series: ChartStickSeries[] = [];
+  if (average && built.mean !== undefined) {
+    series.push({
+      id: 'average',
+      label: copy.help.showAverage.title,
+      values: built.mean,
+      color: 'var(--text-faint)',
+      muted: true,
+    });
+  }
+  series.push({
+    id: `component-${profile.index}`,
+    label: profile.label,
+    values: profile.values,
+    from: profile.secondValues,
+    color: profile.color,
+  });
+  return series;
+}
+
+/**
+ * What each drawn slot is called, in the panels' own order.
+ * @param built - The panels as they were built, or nothing at all.
+ * @returns One name per slot.
+ */
+export function namesOfSlots(built: LoadingProfiles | null): string[] {
+  return slotLabels(built, undefined);
+}
+
+/**
+ * What the axis writes under the slots it labels, in the panels' own order.
+ *
+ * A number line is written to the axis's own precision here — `879 cm⁻¹`
+ * under a tick — while the readout goes on naming the one slot the pointer is
+ * over in the values the caller handed in.
+ * @param built - The panels as they were built, or nothing at all.
+ * @returns One label per slot.
+ */
+export function ticksOfSlots(built: LoadingProfiles | null): string[] {
+  if (built === null) return [];
+  return slotLabels(built, variableDecimals(built.axis));
+}
+
+/**
+ * Three decimals with the trailing zeros dropped — what a readout writes when
+ * the caller does not say otherwise.
+ * @param value - The number.
+ * @returns It, written out.
+ */
+export function writeValue(value: number): string {
+  if (!Number.isFinite(value)) return '';
+  return String(Math.round(value * DECIMALS) / DECIMALS);
+}
+
+function slotLabels(
+  built: LoadingProfiles | null,
+  decimals: number | undefined,
+): string[] {
+  if (built === null) return [];
+  const labels = new Array<string>(built.order.length);
+  for (let slot = 0; slot < built.order.length; slot++) {
+    labels[slot] = variableLabel(
+      built.axis,
+      built.order[slot] ?? slot,
+      decimals,
+    );
+  }
+  return labels;
+}
+
+function signed(value: number, format: (value: number) => string): string {
+  const sign = value < 0 ? '−' : '+';
+  return `${sign}${format(Math.abs(value))}`;
+}
+
+const DECIMALS = 1000;

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,155 @@
+/**
+ * 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';
+
+/** 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;
+  /**
+   * 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;
+}