react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/ProjectionPanel.tsx

@@ -0,0 +1,262 @@
+import type { PointerEvent, ReactElement } from 'react';
+import { useRef, useState } from 'react';
+
+import type { ScatterPointOpen } from '../../scatter/ui/scatterPlotProps.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ProjectionSamples } from '../core/projectionSamples.ts';
+
+import { ProjectionMapTab } from './ProjectionMapTab.tsx';
+import { ProjectionPairsTab } from './ProjectionPairsTab.tsx';
+import { ProjectionReadout } from './ProjectionReadout.tsx';
+import { ProjectionSharesTab } from './ProjectionSharesTab.tsx';
+import { ProjectionSpaceTab } from './ProjectionSpaceTab.tsx';
+import type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
+import { ProjectionVariablesTab } from './ProjectionVariablesTab.tsx';
+import type { ProjectionMapView } from './projectionMapView.ts';
+import type { ProjectionModels } from './projectionTabModels.ts';
+import type { ProjectionSampleOpen } from './projectionViewerProps.ts';
+import type { ProjectionStateApi } from './useProjectionState.ts';
+
+/** What {@link ProjectionPanel} needs. */
+export interface ProjectionPanelProps {
+  /** The tab, the options and the selection every tab shares. */
+  state: ProjectionStateApi;
+  /** What the run produced, whatever produced it. */
+  result: ProjectionResult;
+  /** Who the rows are. */
+  samples: ProjectionSamples;
+  /** The words the viewer writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** The two figures the bar explains and a tab draws. */
+  models: ProjectionModels;
+  /** The map's frame, its last report, and the words around it. */
+  map: ProjectionMapView;
+  /** Width of the figure, in pixels. */
+  width: number;
+  /** Height of the figure, in pixels. */
+  height: number;
+  /** How a number is written in a hover card and a readout. */
+  formatValue: (value: number) => string;
+  /** Stem of the `id` every pill carries, which names this panel's own tab. */
+  baseId: string;
+  /** The `id` the pills point at, when there are pills. */
+  panelId: string;
+  /** Whether the bar carries a strip of views at all. */
+  strip: boolean;
+  /**
+   * Called with the row under the pointer on the map, or `null`.
+   * @default undefined
+   */
+  onHoverSample?: (id: string | null) => void;
+  /**
+   * Called when the reader double-clicks a sample, on either figure.
+   * @default undefined
+   */
+  onSampleDoubleClick?: (sample: ProjectionSampleOpen) => void;
+  /**
+   * Called as the pointer crosses the "what differs" panels.
+   * @default undefined
+   */
+  onTrackVariable?: (track: ProjectionVariableTrack | null) => void;
+  /**
+   * Whether a drag on a touch screen draws a lasso rather than scrolling.
+   * @default false
+   */
+  touchLasso?: boolean;
+  /**
+   * Whether the wheel zooms the map, once the pointer has rested on it.
+   * @default false
+   */
+  wheelZoom?: boolean;
+}
+
+/**
+ * The one figure showing, and the card that follows the pointer over it.
+ *
+ * The four tabs are drawn here rather than in the shell because only one of
+ * them is ever rendered and all four sit in the same box under the same bar: a
+ * reader moving between them should see the picture change and nothing else
+ * move. The pointer is tracked at this level for the same reason — the card is
+ * the viewer's, so it says the same thing wherever it is raised.
+ *
+ * The box is named whether or not there is a strip of tabs above it, because
+ * that name is what the save glyph in the bar points at: a figure is saved by
+ * the `id` of the box holding it, and a box named only where there happen to be
+ * several tabs would be savable on some viewers and not on others.
+ * @param props - See {@link ProjectionPanelProps}.
+ * @returns The panel.
+ */
+export function ProjectionPanel(props: ProjectionPanelProps): ReactElement {
+  const { state, result, samples, copy, models, map } = props;
+  const { width, height, formatValue, baseId, panelId, strip } = props;
+  const { onHoverSample, onTrackVariable, touchLasso, wheelZoom } = props;
+  const { onSampleDoubleClick } = props;
+
+  const box = useRef<HTMLDivElement>(null);
+  const pointer = useRef(NOWHERE);
+  const [anchor, setAnchor] = useState(NO_ANCHOR);
+
+  function trackPointer(event: PointerEvent<HTMLDivElement>): void {
+    const rect = box.current?.getBoundingClientRect();
+    if (rect === undefined) return;
+    pointer.current = {
+      x: event.clientX - rect.left,
+      y: event.clientY - rect.top,
+    };
+  }
+
+  function noteHover(index: number): void {
+    setAnchor({ index, ...pointer.current });
+    onHoverSample?.(index < 0 ? null : (samples.ids[index] ?? null));
+  }
+
+  // The figures speak in row numbers, because that is what a hit test hands
+  // back; every callback out of the viewer speaks in names, so a caller never
+  // has to keep a second copy of the row order. The translation is one line
+  // and it belongs here, once, rather than in each of the two tabs.
+  const openSample =
+    onSampleDoubleClick === undefined
+      ? undefined
+      : (point: ScatterPointOpen) => {
+          const id = samples.ids[point.index];
+          if (id === undefined) return;
+          onSampleDoubleClick({ ...point, id });
+        };
+
+  return (
+    <div
+      ref={box}
+      id={panelId}
+      role={strip ? 'tabpanel' : undefined}
+      aria-labelledby={strip ? `${baseId}-${state.tab}` : undefined}
+      onPointerMove={trackPointer}
+    >
+      {state.tab === 'pairs' ? (
+        <ProjectionPairsTab
+          result={result}
+          groups={state.groups}
+          options={state.options}
+          copy={copy}
+          width={width}
+          height={height}
+          selected={state.selected}
+          onSelectPair={state.selectPair}
+        />
+      ) : null}
+      {state.tab === 'variables' ? (
+        <ProjectionVariablesTab
+          profiles={models.profiles}
+          options={state.options}
+          copy={copy}
+          sampleName={models.sampleName}
+          width={width}
+          height={height}
+          onTrackVariable={onTrackVariable}
+          formatValue={formatValue}
+        />
+      ) : null}
+      {state.tab === 'shares' ? (
+        <ProjectionSharesTab
+          result={result}
+          shares={models.shares}
+          copy={copy}
+          width={width}
+          height={height}
+        />
+      ) : null}
+      {state.tab === 'space' ? (
+        <ProjectionSpaceTab
+          result={result}
+          groups={state.groups}
+          options={state.options}
+          copy={copy}
+          chrome={map.spaceChrome}
+          ids={samples.ids}
+          width={width}
+          height={height}
+          selected={state.selected}
+          camera={map.camera}
+          onCameraChange={map.setCamera}
+          zoom={map.zoom}
+          onZoomChange={map.setZoom}
+          wheelZoom={wheelZoom}
+          report={map.report}
+          onSelectionChange={map.settle}
+          onHoverChange={noteHover}
+          onPointDoubleClick={openSample}
+          hoverCard={
+            anchor.index < 0 ? null : (
+              <ProjectionReadout
+                index={anchor.index}
+                result={result}
+                samples={samples}
+                groups={state.groups}
+                xAxis={state.options.xAxis}
+                yAxis={state.options.yAxis}
+                zAxis={state.options.zAxis}
+                x={anchor.x}
+                y={anchor.y}
+                boxWidth={width}
+                boxHeight={height}
+                formatValue={formatValue}
+              />
+            )
+          }
+        />
+      ) : null}
+      {state.tab === 'map' ? (
+        <ProjectionMapTab
+          result={result}
+          groups={state.groups}
+          options={state.options}
+          copy={copy}
+          chrome={map.chrome}
+          ids={samples.ids}
+          viewport={map.viewport}
+          onViewportChange={map.setViewport}
+          wheelZoom={wheelZoom}
+          report={map.report}
+          width={width}
+          height={height}
+          selected={state.selected}
+          onSelectionChange={map.settle}
+          onHoverChange={noteHover}
+          onPointDoubleClick={openSample}
+          touchLasso={touchLasso}
+          hoverCard={
+            anchor.index < 0 ? null : (
+              <ProjectionReadout
+                index={anchor.index}
+                result={result}
+                samples={samples}
+                groups={state.groups}
+                xAxis={state.options.xAxis}
+                yAxis={state.options.yAxis}
+                x={anchor.x}
+                y={anchor.y}
+                boxWidth={width}
+                boxHeight={height}
+                formatValue={formatValue}
+              />
+            )
+          }
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/** Where the pointer is before it has been anywhere. */
+const NOWHERE = { x: 0, y: 0 };
+
+/**
+ * No row under the pointer, which is what draws no card at all.
+ *
+ * The pointer's position is kept in a ref and read into this state only when
+ * the row under it changes, because a card that re-rendered the figure on
+ * every pointer move would repaint two thousand dots sixty times a second to
+ * shift a tooltip by three pixels. Between two rows the card therefore stands
+ * where it was raised, which is where the reader is already looking.
+ */
+const NO_ANCHOR = { index: -1, x: 0, y: 0 };

package/src/projection/ui/ProjectionReadout.tsx

@@ -0,0 +1,159 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { OverlayReadoutRow } from '../../overlay/ui/OverlayReadout.tsx';
+import { OverlayReadout } from '../../overlay/ui/OverlayReadout.tsx';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type {
+  ProjectionSamples,
+  ResolvedProjectionGroups,
+} from '../core/projectionSamples.ts';
+
+import { formatProjectionValue } from './projectionFormat.ts';
+
+/** What {@link ProjectionReadout} says, and where. */
+export interface ProjectionReadoutProps {
+  /** The row the card is about, as an index into the score matrix. */
+  index: number;
+  /** What the run produced, for the axis names and the sample's own scores. */
+  result: ProjectionResult;
+  /** Who the rows are. */
+  samples: ProjectionSamples;
+  /** The groups as the figure draws them, for the row's group and its colour. */
+  groups: ResolvedProjectionGroups;
+  /** Which axis is drawn horizontally, from 0. */
+  xAxis: number;
+  /** Which axis is drawn vertically. */
+  yAxis: number;
+  /**
+   * Which axis runs away from the reader, on the cloud. It is the one place a
+   * cloud's third number is written at all: the box carries no tick labels, so
+   * a reader who wants a value points at the sample.
+   * @default undefined — the card names two axes, as the map's does
+   */
+  zAxis?: number;
+  /** Where the pointer is, in pixels from the figure's left. */
+  x: number;
+  /** Where the pointer is, in pixels from the figure's top. */
+  y: number;
+  /** Width of the figure, so the card can be flipped rather than clipped. */
+  boxWidth: number;
+  /** Height of the figure. */
+  boxHeight: number;
+  /**
+   * How a number is written.
+   * @default a rounding to three decimals with the trailing zeros dropped
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * The most rows shown before a `+ n more` footer.
+   * @default 12
+   */
+  maxRows?: number;
+  /**
+   * Whether the card stays until it is dismissed.
+   * @default false
+   */
+  pinned?: boolean;
+  /**
+   * Called when the reader dismisses a pinned card.
+   * @default undefined
+   */
+  onUnpin?: () => void;
+  /**
+   * Value of the `data-testid` attribute of the card.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The card that says everything known about the sample under the pointer.
+ *
+ * It opens with what the reader can name the sample by, and only then with the
+ * two numbers the figure is drawn from: a card that led with `−2.257` would be
+ * asking a reader who has never met a component to care about the arithmetic
+ * before they have found their own sample in it. Whatever else is known comes
+ * last and in the caller's own order, because it is the part they came for and
+ * the part this package cannot guess at.
+ * @param props - See {@link ProjectionReadoutProps}.
+ * @returns The card.
+ */
+export function ProjectionReadout(props: ProjectionReadoutProps): ReactElement {
+  const {
+    index,
+    result,
+    samples,
+    groups,
+    xAxis,
+    yAxis,
+    zAxis,
+    x,
+    y,
+    boxWidth,
+    boxHeight,
+    formatValue = formatProjectionValue,
+    maxRows = 12,
+    pinned = false,
+    onUnpin,
+    testId,
+  } = props;
+
+  const drawn = useMemo(
+    () => (zAxis === undefined ? [xAxis, yAxis] : [xAxis, yAxis, zAxis]),
+    [xAxis, yAxis, zAxis],
+  );
+  const rows = useMemo(
+    () => readoutRows(index, result, samples, groups, drawn, formatValue),
+    [drawn, formatValue, groups, index, result, samples],
+  );
+
+  return (
+    <OverlayReadout
+      x={x}
+      y={y}
+      boxWidth={boxWidth}
+      boxHeight={boxHeight}
+      title={samples.ids[index] ?? ''}
+      rows={rows}
+      maxRows={maxRows}
+      pinned={pinned}
+      onUnpin={onUnpin}
+      testId={testId}
+    />
+  );
+}
+
+function readoutRows(
+  index: number,
+  result: ProjectionResult,
+  samples: ProjectionSamples,
+  groups: ResolvedProjectionGroups,
+  drawn: readonly number[],
+  formatValue: (value: number) => string,
+): OverlayReadoutRow[] {
+  const rows: OverlayReadoutRow[] = [];
+  const { axes, scores } = result;
+  const known = index >= 0 && index < scores.rows;
+
+  for (const axis of drawn) {
+    const name = axes[axis]?.name;
+    if (name === undefined) continue;
+    rows.push({
+      label: name,
+      value: formatValue(known ? scores.get(index, axis) : Number.NaN),
+    });
+  }
+
+  const group = groups.entries[groups.groupOf[index] ?? -1];
+  if (group !== undefined) {
+    rows.push({ label: groups.label, value: group.label, color: group.color });
+  }
+
+  if (known && samples.fields !== undefined) {
+    for (const field of samples.fields(index)) {
+      rows.push({ label: field.label, value: field.value });
+    }
+  }
+  return rows;
+}

package/src/projection/ui/ProjectionSharesControls.tsx

@@ -0,0 +1,56 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+
+import { PROJECTION_SHARE_STEP, WHOLE_SHARE } from './projectionTabStyles.ts';
+
+/** What the shares control is drawn from. */
+export interface ProjectionSharesControlsProps {
+  /** What the figure is showing; only the target is read here. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /**
+   * How much of itself the bar is writing. The caption in front of the
+   * stepper is the first thing to go, since the percentage beside it is what
+   * the reader is looking at and the name is in every announcement.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+}
+
+/**
+ * How much of the differences the reader wants accounted for, which is the
+ * only thing this tab has to change.
+ *
+ * It is written on the bar rather than left behind the cog because it is the
+ * tab's whole question — how many components do I have to keep — and a reader
+ * should not have to open anything to see the answer the figure is drawn
+ * against. The panel behind the cog offers the same setting named and
+ * explained; here it is the value alone.
+ * @param props - See {@link ProjectionSharesControlsProps}.
+ * @returns The stepper.
+ */
+export function ProjectionSharesControls(
+  props: ProjectionSharesControlsProps,
+): ReactElement {
+  const { options, onChange, copy, tier = 'full' } = props;
+
+  return (
+    <OverlayNumber
+      label={copy.help.shareTarget.title}
+      hideLabel={tier !== 'full'}
+      value={Math.round(options.shareTarget * WHOLE_SHARE)}
+      min={0}
+      max={WHOLE_SHARE}
+      step={PROJECTION_SHARE_STEP}
+      unit="%"
+      onChange={(target) => onChange({ shareTarget: target / WHOLE_SHARE })}
+    />
+  );
+}