react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/ProjectionSharesMarks.tsx

@@ -0,0 +1,241 @@
+import type { ReactElement } from 'react';
+
+import type { ChartBand } from '../../chart/core/chartBand.ts';
+import { chartBand, chartBandCenter } from '../../chart/core/chartBand.ts';
+import type { ChartFrameRender } from '../../chart/ui/ChartFrame.tsx';
+import type { ExplainedShares } from '../core/explainedShares.ts';
+
+import {
+  AXIS_CAPTION_STYLE,
+  AXIS_LAYER_STYLE,
+  AXIS_NAME_STYLE,
+  SHARES_BOTTOM_ROOM,
+  SHARES_CAPTION_OFFSET,
+  SHARES_LEFT_ROOM,
+  SHARES_NAME_OFFSET,
+  SHARES_RIGHT_ROOM,
+  TOTAL_LABEL_STYLE,
+  WHOLE_SHARE,
+} from './projectionTabStyles.ts';
+
+/** What {@link SharesMarks} draws. */
+export interface SharesMarksProps {
+  /** The bars, their running total and the target they are measured against. */
+  shares: ExplainedShares;
+  /** The frame they are drawn in. */
+  frame: ChartFrameRender;
+  /** The slots the bars stand on. */
+  band: ChartBand;
+}
+
+/**
+ * The bars, the running total over them, and the target they are measured
+ * against.
+ *
+ * Every bar takes its own component's colour. The total is one grey line with
+ * a dot per component and its name at its right-hand end, so the reader is
+ * never sent to a key to find out which of the two things on the chart is
+ * which. The target is one dashed rule and a light band reaching the first
+ * component that meets it — one honest marker, where Kaiser's rule and an
+ * elbow would be two folk rules a novice reads as verdicts.
+ * @param props - See {@link SharesMarksProps}.
+ * @returns The marks.
+ */
+export function SharesMarks(props: SharesMarksProps): ReactElement {
+  const { shares, frame, band } = props;
+  const { components, target, reachesTargetAt } = shares;
+  const { plot, y } = frame;
+  const zero = y.offset;
+  const bars: ReactElement[] = [];
+  const dots: ReactElement[] = [];
+  let path = '';
+  let lastX = plot.left;
+  let lastY = zero;
+
+  for (let index = 0; index < components.length; index++) {
+    const component = components[index];
+    if (component === undefined) continue;
+    const top = y.offset + component.share * WHOLE_SHARE * y.factor;
+    const middle = chartBandCenter(band, index);
+    bars.push(
+      <rect
+        key={component.number}
+        data-component={component.number}
+        x={middle - band.bandWidth / 2}
+        y={Math.min(top, zero)}
+        width={band.bandWidth}
+        height={Math.abs(zero - top)}
+        fill={component.color}
+      >
+        <title>{hoverCard(shares, index)}</title>
+      </rect>,
+    );
+    lastX = middle;
+    lastY = y.offset + component.cumulative * WHOLE_SHARE * y.factor;
+    path += `${index === 0 ? 'M' : 'L'}${round(middle)} ${round(lastY)}`;
+    dots.push(<circle key={component.number} cx={middle} cy={lastY} r={2.5} />);
+  }
+
+  const total = components.at(-1)?.cumulative ?? 0;
+  return (
+    <>
+      {target > 0 ? targetMark(target, reachesTargetAt, frame, band) : null}
+      <g data-shares="bars">{bars}</g>
+      <path
+        data-shares="total"
+        d={path}
+        fill="none"
+        stroke="var(--text-muted)"
+        strokeWidth={1.5}
+      />
+      <g data-shares="total-dots" fill="var(--text-muted)">
+        {dots}
+      </g>
+      <text
+        x={lastX - DOT_GAP}
+        y={Math.max(plot.top + LABEL_ROOM, lastY - DOT_GAP)}
+        textAnchor="end"
+        style={TOTAL_LABEL_STYLE}
+      >
+        {`Running total ${(total * WHOLE_SHARE).toFixed(1)}%`}
+      </text>
+    </>
+  );
+}
+
+/** What {@link SharesAxis} writes. */
+export interface SharesAxisProps {
+  /** The bars, for their names. */
+  shares: ExplainedShares;
+  /** Total width of the figure, in pixels, which the slots are laid out in. */
+  width: number;
+  /** Total height, which fixes the baseline the names sit on. */
+  height: number;
+  /** What the axis measures, written under the names. */
+  caption: string;
+}
+
+/**
+ * The component names under the bars, and what the axis measures under them.
+ *
+ * They are written in a layer of their own because a frame clips its children
+ * to the plot and these sit below it — the same reason the tracked line chart
+ * writes its slot names this way rather than as frame children.
+ * @param props - See {@link SharesAxisProps}.
+ * @returns The names.
+ */
+export function SharesAxis(props: SharesAxisProps): ReactElement {
+  const { shares, width, height, caption } = props;
+  const right = Math.max(SHARES_LEFT_ROOM, width - SHARES_RIGHT_ROOM);
+  const band = chartBand(shares.components.length, SHARES_LEFT_ROOM, right);
+  const baseline = height - SHARES_BOTTOM_ROOM;
+
+  return (
+    <svg width="100%" height="100%" style={AXIS_LAYER_STYLE}>
+      {shares.components.map((component, index) => (
+        <text
+          key={component.number}
+          x={chartBandCenter(band, index)}
+          y={baseline + SHARES_NAME_OFFSET}
+          textAnchor="middle"
+          style={AXIS_NAME_STYLE}
+        >
+          {component.label}
+        </text>
+      ))}
+      <text
+        x={(SHARES_LEFT_ROOM + right) / 2}
+        y={baseline + SHARES_CAPTION_OFFSET}
+        textAnchor="middle"
+        style={AXIS_CAPTION_STYLE}
+      >
+        {caption}
+      </text>
+    </svg>
+  );
+}
+
+/**
+ * The dashed rule at the target, and the light band over the components that
+ * reach it.
+ * @param target - The cumulative share the marker aims at.
+ * @param reachesTargetAt - The first component to meet it, counting from one.
+ * @param frame - The frame the marks are drawn in.
+ * @param band - The slots the bars stand on.
+ * @returns The marker.
+ */
+function targetMark(
+  target: number,
+  reachesTargetAt: number | null,
+  frame: ChartFrameRender,
+  band: ChartBand,
+): ReactElement {
+  const { plot, y } = frame;
+  const at = y.offset + target * WHOLE_SHARE * y.factor;
+  const covered =
+    reachesTargetAt === null
+      ? 0
+      : band.offset + band.step * reachesTargetAt - plot.left;
+
+  return (
+    <g data-shares="target">
+      {covered > 0 ? (
+        <rect
+          x={plot.left}
+          y={plot.top}
+          width={covered}
+          height={plot.bottom - plot.top}
+          fill={TARGET_BAND}
+        />
+      ) : null}
+      <line
+        x1={plot.left}
+        x2={plot.right}
+        y1={at}
+        y2={at}
+        stroke="var(--border-strong)"
+        strokeWidth={1}
+        strokeDasharray="4 3"
+      />
+    </g>
+  );
+}
+
+/**
+ * What the pointer is told about one bar: its own share, the running total up
+ * to it, and the variance of its scores as fine print for the one reader in
+ * fifty who wants it.
+ * @param shares - The bars.
+ * @param index - Which one, from 0.
+ * @returns The card's text.
+ */
+function hoverCard(shares: ExplainedShares, index: number): string {
+  const component = shares.components[index];
+  if (component === undefined) return '';
+  const own = (component.share * WHOLE_SHARE).toFixed(2);
+  const together = (component.cumulative * WHOLE_SHARE).toFixed(2);
+  const line = `${component.label} — ${own}% of the differences. The first ${component.number} together: ${together}%.`;
+  const { eigenvalue } = component;
+  return eigenvalue === undefined
+    ? line
+    : `${line}\nλ = ${Math.round(eigenvalue * ROUNDING) / ROUNDING}`;
+}
+
+/** The light wash over the components that reach the target. */
+const TARGET_BAND = 'color-mix(in srgb, var(--border-strong) 22%, transparent)';
+
+/**
+ * How far the total's name sits from its last dot, and how far it is kept
+ * below the top of the plot.
+ *
+ * A whole model's total is 100 %, which lands the last dot on the very top
+ * rule — and a name six pixels above that is six pixels outside the frame's
+ * clip, so it would simply not be drawn.
+ */
+const DOT_GAP = 6;
+const LABEL_ROOM = 12;
+
+/** Decimals the fine print rounds an eigenvalue to. */
+const ROUNDING = 1000;
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/projection/ui/ProjectionSharesMore.tsx

@@ -0,0 +1,53 @@
+import type { ReactElement } from 'react';
+
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import { PROJECTION_PANEL_NAME } from '../core/projectionStrings.ts';
+import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
+
+import type { ProjectionSharesControlsProps } from './ProjectionSharesControls.tsx';
+import { PROJECTION_SHARE_STEP, WHOLE_SHARE } from './projectionTabStyles.ts';
+
+/** What the shares panel behind the cog is drawn from. */
+export type ProjectionSharesMoreProps = Omit<
+  ProjectionSharesControlsProps,
+  'tier'
+>;
+
+/**
+ * What the shares figure keeps behind the cog: the one target it has, named
+ * and explained, and the way back to the share the figure came with.
+ *
+ * The stepper is on the bar as well, and that is not an oversight. The bar
+ * writes the number because the number is the tab's whole question — how much
+ * of the differences am I asking to account for — while this is the only place
+ * it is called anything, the only place the sentence behind its name is
+ * offered, and the only place a reader who has stepped it somewhere odd can
+ * put it back.
+ * @param props - See {@link ProjectionSharesMoreProps}.
+ * @returns The panel behind the cog.
+ */
+export function ProjectionSharesMore(
+  props: ProjectionSharesMoreProps,
+): ReactElement {
+  const { options, onChange, copy } = props;
+  const { help, tab } = copy;
+
+  return (
+    <OverlayPanel
+      title={tab.shares}
+      onReset={() => onChange(PROJECTION_TAB_DEFAULTS.shares)}
+    >
+      <OverlayNumber
+        label={PROJECTION_PANEL_NAME.shareTarget}
+        help={help.shareTarget}
+        value={Math.round(options.shareTarget * WHOLE_SHARE)}
+        min={0}
+        max={WHOLE_SHARE}
+        step={PROJECTION_SHARE_STEP}
+        unit="%"
+        onChange={(target) => onChange({ shareTarget: target / WHOLE_SHARE })}
+      />
+    </OverlayPanel>
+  );
+}

package/src/projection/ui/ProjectionSharesTab.tsx

@@ -0,0 +1,118 @@
+import type { ReactElement } from 'react';
+
+import { chartBand } from '../../chart/core/chartBand.ts';
+import { ChartFrame } from '../../chart/ui/ChartFrame.tsx';
+import type { ExplainedShares } from '../core/explainedShares.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { PROJECTION_COPY } from '../core/projectionCopy.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+
+import { SharesAxis, SharesMarks } from './ProjectionSharesMarks.tsx';
+import {
+  PROJECTION_TAB_HEIGHT,
+  SHARES_BOTTOM_ROOM,
+  WHOLE_SHARE,
+} from './projectionTabStyles.ts';
+
+/** What {@link ProjectionSharesTab} needs. */
+export interface ProjectionSharesTabProps {
+  /** What the run produced; every axis must carry a share. */
+  result: ProjectionResult;
+  /** The bars, worked out once by the viewer and explained in its bar. */
+  shares: ExplainedShares;
+  /**
+   * The words the tab writes.
+   * @default PROJECTION_COPY
+   */
+  copy?: ProjectionCopy;
+  /**
+   * Width of the figure, in pixels, from the viewer's measurement.
+   * @default 0 — nothing is drawn until the figure has been measured
+   */
+  width?: number;
+  /**
+   * Height of the figure, in pixels.
+   * @default 420
+   */
+  height?: number;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * One bar per component, each in its own component's colour, with the running
+ * total drawn over them.
+ *
+ * The colour is the whole point of this tab. On most charts of explained
+ * shares the bars are one colour, or a gradient, and a reader who asks what it
+ * means is right to ask, because it means nothing. Here every bar carries the
+ * colour its component carries on every other tab, so the reader learns one
+ * colour language rather than two.
+ *
+ * It is the one figure of the viewer with no key at all: every bar is named
+ * under itself in its own colour, and the running total writes its name at its
+ * right-hand end, so a key would be a second place to look for something both
+ * marks already say about themselves.
+ * @param props - See {@link ProjectionSharesTabProps}.
+ * @returns The figure.
+ */
+export function ProjectionSharesTab(
+  props: ProjectionSharesTabProps,
+): ReactElement {
+  const { result, shares, copy = PROJECTION_COPY, testId } = props;
+  const { width = 0, height = PROJECTION_TAB_HEIGHT } = props;
+
+  const slots = shares.components.length;
+
+  return (
+    <div data-testid={testId}>
+      <ChartFrame
+        width={width}
+        height={height}
+        margins={{ bottom: SHARES_BOTTOM_ROOM }}
+        x={{
+          domain: [0, slots],
+          showTicks: false,
+          showGrid: false,
+          nice: false,
+        }}
+        y={{ domain: [0, WHOLE_SHARE], label: VERTICAL_CAPTION, tickCount: 5 }}
+        label={`${result.method}. ${copy.intro.shares}`}
+        overlay={
+          <SharesAxis
+            shares={shares}
+            width={width}
+            height={height}
+            caption={HORIZONTAL_CAPTION}
+          />
+        }
+      >
+        {(frame) => (
+          <SharesMarks
+            shares={shares}
+            frame={frame}
+            band={chartBand(slots, frame.plot.left, frame.plot.right, {
+              padding: BAR_GAP,
+            })}
+          />
+        )}
+      </ChartFrame>
+    </div>
+  );
+}
+
+/** Share of a slot left empty between two bars. */
+const BAR_GAP = 0.3;
+
+/**
+ * The two axis captions, in words the reader already has.
+ *
+ * They are constants rather than copy because {@link ProjectionCopy} carries
+ * no slot for an axis, and adding one for two strings would put a translation
+ * seam in the middle of a figure.
+ */
+const HORIZONTAL_CAPTION = 'Components, strongest first';
+const VERTICAL_CAPTION = 'Share of the differences explained';

package/src/projection/ui/ProjectionSpaceControls.tsx

@@ -0,0 +1,219 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import type { OverlayChipSetting } from '../../overlay/ui/OverlayChip.tsx';
+import { OverlayChip } from '../../overlay/ui/OverlayChip.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
+import { OverlayValueMenu } from '../../overlay/ui/OverlayValueMenu.tsx';
+import type { CloudGesture } from '../../scatter3d/core/cloudGesture.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionColorBy,
+  ProjectionOptions,
+} from '../core/projectionOptions.ts';
+
+import type { ProjectionReading } from './projectionBarReadings.ts';
+import { CLOUD_GESTURE_CHOICES } from './projectionCloudChoices.ts';
+import { ellipseKey, ellipseSize } from './projectionEllipse.ts';
+import { ellipsoidChoices } from './projectionEllipsoid.ts';
+import { projectionColourChoices } from './projectionMapChoices.ts';
+
+/** What the cloud's controls are drawn from, wherever in the bar they sit. */
+export interface ProjectionSpaceControlsProps {
+  /** What the cloud is showing, already resolved against the result. */
+  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;
+  /** What the set of groups is called. */
+  groupLabel: string;
+  /**
+   * Whether the samples carry groups at all. Without them the shells stand for
+   * nothing, so their control is greyed rather than removed.
+   * @default false
+   */
+  hasGroups?: boolean;
+  /**
+   * What the settings currently read, built once for the bar and handed down.
+   * @default [] — nothing is written, which is what the cog's panel wants
+   */
+  readings?: readonly ProjectionReading[];
+  /**
+   * How much of itself the bar is writing.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+}
+
+/**
+ * The cloud settings a reader changes while looking at the picture.
+ *
+ * One of them is not on the map's bar at all, and it is the first: what a
+ * plain drag does. Turning the box and drawing a lasso both want that drag,
+ * and neither can be given a modifier without taking one that already means
+ * "add" or "take away" inside a lasso — so the choice is written on the bar
+ * where the reader can see it, rather than left as a shortcut they would have
+ * to be told about. It leads the row because it is the only setting on the bar
+ * that changes what the reader's own hand does.
+ *
+ * The rest are the map's, unchanged: how large the shells are, and the two
+ * name switches. The axes and the dot size wait behind the cog exactly as they
+ * do on the map.
+ * @param props - See {@link ProjectionSpaceControlsProps}.
+ * @returns The controls.
+ */
+export function ProjectionSpaceControls(
+  props: ProjectionSpaceControlsProps,
+): ReactElement {
+  const { options, onChange, copy, groupLabel, hasGroups = false } = props;
+  const { readings = NO_READINGS, tier = 'full' } = props;
+  const { bar, help } = copy;
+
+  const uncoloured = !hasGroups || options.colorBy === 'none';
+  const names = (
+    <>
+      <OverlayToggle
+        label={bar.switches.showGroupLabels}
+        help={help.showGroupLabels}
+        icon={GROUP_LABELS_GLYPH}
+        hideLabel
+        checked={options.showGroupLabels}
+        disabled={uncoloured}
+        onChange={(showGroupLabels) => onChange({ showGroupLabels })}
+      />
+      <OverlayToggle
+        label={bar.switches.showIds}
+        help={help.showIds}
+        icon={IDS_GLYPH}
+        hideLabel
+        checked={options.showIds}
+        onChange={(showIds) => onChange({ showIds })}
+      />
+    </>
+  );
+
+  if (tier === 'chip' || tier === 'tiny') {
+    return (
+      <>
+        <OverlayChip label={bar.settings} settings={chipSettings(readings)}>
+          <SpaceSettings
+            options={options}
+            onChange={onChange}
+            copy={copy}
+            groupLabel={groupLabel}
+            hasGroups={hasGroups}
+          />
+        </OverlayChip>
+        {names}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <OverlayValueMenu<CloudGesture>
+        label={help.cloudGesture.title}
+        keyWord={bar.key.cloudGesture}
+        showKey={tier === 'full'}
+        value={options.cloudGesture}
+        options={CLOUD_GESTURE_CHOICES}
+        onChange={(cloudGesture) => onChange({ cloudGesture })}
+      />
+      <OverlayValueMenu
+        label={help.ellipse.title}
+        keyWord={bar.key.ellipse}
+        showKey={tier === 'full'}
+        value={ellipseKey(options.ellipse)}
+        disabled={uncoloured}
+        disabledReason={UNCOLOURED_REASON}
+        options={ellipsoidChoices(options.ellipse)}
+        onChange={(value) => onChange({ ellipse: ellipseSize(value) })}
+      />
+      {names}
+    </>
+  );
+}
+
+/**
+ * What the chip reads out, which is every setting spelled in full.
+ * @param readings - What the settings currently read.
+ * @returns The chip's own settings.
+ */
+function chipSettings(
+  readings: readonly ProjectionReading[],
+): readonly OverlayChipSetting[] {
+  const settings: OverlayChipSetting[] = [];
+  for (const reading of readings) {
+    settings.push({
+      label: reading.label,
+      value: reading.value,
+      swatches: reading.swatches,
+    });
+  }
+  return settings;
+}
+
+/** What the captioned pair behind the chip is drawn from. */
+interface SpaceSettingsProps {
+  /** What the cloud is showing, already resolved against the result. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the panel writes. */
+  copy: ProjectionCopy;
+  /** What the set of groups is called, which is what `Colour by` offers. */
+  groupLabel: string;
+  /** Whether the samples carry groups at all. */
+  hasGroups: boolean;
+}
+
+/**
+ * The same settings with their captions, for the panel the chip opens.
+ * @param props - See {@link SpaceSettingsProps}.
+ * @returns The captioned controls.
+ */
+function SpaceSettings(props: SpaceSettingsProps): ReactElement {
+  const { options, onChange, copy, groupLabel, hasGroups } = props;
+  const { bar, help } = copy;
+
+  return (
+    <>
+      <OverlaySegmented<CloudGesture>
+        label={help.cloudGesture.title}
+        help={help.cloudGesture}
+        value={options.cloudGesture}
+        options={CLOUD_GESTURE_CHOICES}
+        onChange={(cloudGesture) => onChange({ cloudGesture })}
+      />
+      <OverlaySegmented<ProjectionColorBy>
+        label={help.colorBy.title}
+        help={help.colorBy}
+        value={options.colorBy}
+        disabled={!hasGroups}
+        options={projectionColourChoices(groupLabel, bar.uncoloured)}
+        onChange={(colorBy) => onChange({ colorBy })}
+      />
+      <OverlaySelect
+        label={help.ellipse.title}
+        help={help.ellipse}
+        value={ellipseKey(options.ellipse)}
+        disabled={!hasGroups || options.colorBy === 'none'}
+        options={ellipsoidChoices(options.ellipse)}
+        onChange={(value) => onChange({ ellipse: ellipseSize(value) })}
+      />
+    </>
+  );
+}
+
+/** The two glyphs the name switches ride as, the same pair the map uses. */
+const GROUP_LABELS_GLYPH = 'tag';
+const IDS_GLYPH = 'id-number';
+
+const UNCOLOURED_REASON =
+  'Shells follow the groups, so colour the cloud by them first.';
+
+/** No readings at all, which is what the panel behind the cog is handed. */
+const NO_READINGS: readonly ProjectionReading[] = [];