react-cheminfo 0.9.0 → 0.10.0

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/ProjectionSurface.tsx

@@ -0,0 +1,63 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import { overlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import type { OverlaySurface } from '../../overlay/ui/overlaySurface.ts';
+import {
+  OverlaySurfaceContext,
+  useCoarsePointer,
+  useOverlaySurface,
+} from '../../overlay/ui/overlaySurface.ts';
+
+/** What {@link ProjectionSurface} needs. */
+export interface ProjectionSurfaceProps {
+  /** The chrome drawn at the compact size: the settings bar, a floating key. */
+  children: ReactNode;
+  /**
+   * Width of the figure, in pixels, for the chrome that has to decide whether
+   * it still fits. Only the settings bar needs it — chrome inside a chart is
+   * already over a measured figure and inherits its width.
+   * @default undefined — whatever the surface above it was measured at
+   */
+  width?: number;
+}
+
+/**
+ * The compact measurements every piece of this viewer's chrome is drawn from.
+ *
+ * The viewer is meant to be embedded in somebody else's page, so its chrome
+ * takes the smallest measurements the overlay domain offers rather than the
+ * roomier ones a figure standing alone can afford. A finger still wins: the
+ * pointer is read here, and a coarse one is handed the largest set whatever
+ * the figure asked for.
+ *
+ * It is a surface of its own rather than an `OverlayLayer` because the
+ * settings bar is in the flow above the picture, and a layer is absolutely
+ * positioned over one — a bar inside a layer would float over the very data it
+ * introduces. Everything else about the surface it stands on is carried
+ * through, so a key nested inside a chart's own layer still fades with that
+ * chart and still knows it is repainting.
+ * @param props - See {@link ProjectionSurfaceProps}.
+ * @returns The chrome, drawn compact.
+ */
+export function ProjectionSurface(props: ProjectionSurfaceProps): ReactElement {
+  const { children, width } = props;
+  const above = useOverlaySurface();
+  const pointer = useCoarsePointer() ? 'coarse' : 'fine';
+
+  const surface = useMemo<OverlaySurface>(
+    () => ({
+      ...above,
+      metrics: overlayMetrics('compact', pointer),
+      pointer,
+      width: width ?? above.width,
+    }),
+    [above, pointer, width],
+  );
+
+  return (
+    <OverlaySurfaceContext.Provider value={surface}>
+      {children}
+    </OverlaySurfaceContext.Provider>
+  );
+}

package/src/projection/ui/ProjectionTabStrip.tsx

@@ -0,0 +1,144 @@
+import type { ReactElement } from 'react';
+import { useEffect, useMemo, useRef } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import type { OverlayPillOption } from '../../overlay/ui/OverlayPills.tsx';
+import { OverlayPills } from '../../overlay/ui/OverlayPills.tsx';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import {
+  projectionTabScroll,
+  projectionTabTrackStyle,
+} from './projectionBarStyles.ts';
+
+/** What {@link ProjectionTabStrip} needs. */
+export interface ProjectionTabStripProps {
+  /** The tabs the result can fill, in reading order. */
+  tabs: readonly ProjectionTab[];
+  /** The one showing. */
+  tab: ProjectionTab;
+  /** Called with the tab the reader moved to. */
+  onTabChange: (tab: ProjectionTab) => void;
+  /** What each tab is called, from the viewer's copy. */
+  labels: Readonly<Record<ProjectionTab, string>>;
+  /**
+   * What each tab is called on a bar with no room for the long name. They are
+   * written out rather than truncated: "How much each explains" cut to the
+   * width that fits reads "How much each e…", which says less than the one
+   * word the tab is about.
+   */
+  shortLabels: Readonly<Record<ProjectionTab, string>>;
+  /**
+   * Stem of the `id` every button carries, so the panel below can name the tab
+   * it belongs to and a screen reader can walk between the two.
+   */
+  baseId: string;
+  /**
+   * The `id` of the panel the buttons drive. One panel is shared, because only
+   * the showing tab is ever rendered.
+   */
+  panelId: string;
+  /**
+   * How much of itself the bar is writing, which decides whether the names are
+   * written in full and whether the strip may scroll rather than shrink.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+  /**
+   * The most room the strip may take once it is scrolling, which is whatever
+   * the settings and the glyphs at the far end do not need. Without it the row
+   * would hand the strip and the settings a share of the shortfall each, and
+   * the settings — a chip beside a cog — have nothing to give.
+   * @default Number.POSITIVE_INFINITY — the strip takes what it needs
+   */
+  maxWidth?: number;
+  /**
+   * What the strip is called, for a reader arriving by tab.
+   * @default 'Views'
+   */
+  label?: string;
+}
+
+/**
+ * The connected pills that move between a projection's four views.
+ *
+ * They are the package's one segmented control rather than a strip of their
+ * own, so a reader who has pressed the choices inside a settings card has
+ * already learned to press these — and the pills sit at the start of the same
+ * bar those settings sit at the end of, which is what makes the two read as
+ * one piece of chrome instead of two rows stacked over the figure.
+ *
+ * What a narrowing figure takes from them is words and never views. First the
+ * long names give way to the short ones; then, on a figure too narrow to hold
+ * four names however short, the strip scrolls and the view in force is brought
+ * into sight — a reader who cannot see which view they are on, or cannot reach
+ * the others, is stuck rather than merely short of room.
+ *
+ * The shell draws none at all when the result can fill only one tab: a single
+ * pill says nothing about the data and still costs the reader a glance to rule
+ * out. The bar itself stays, because the settings and the explanation still
+ * belong somewhere.
+ * @param props - See {@link ProjectionTabStripProps}.
+ * @returns The strip.
+ */
+export function ProjectionTabStrip(
+  props: ProjectionTabStripProps,
+): ReactElement {
+  const { tabs, tab, onTabChange, labels, shortLabels } = props;
+  const { baseId, panelId, tier = 'full', label } = props;
+  const { maxWidth = Number.POSITIVE_INFINITY } = props;
+  const track = useRef<HTMLDivElement>(null);
+
+  const scrolls = tier === 'tiny';
+  const written =
+    tier === 'full' || tier === 'condensed' ? labels : shortLabels;
+  const options = useMemo<Array<OverlayPillOption<ProjectionTab>>>(
+    () => tabs.map((entry) => ({ value: entry, label: written[entry] })),
+    [tabs, written],
+  );
+
+  useEffect(() => {
+    if (!scrolls) return;
+    showSelected(track.current);
+  }, [scrolls, tab, options, maxWidth]);
+
+  return (
+    <div ref={track} style={projectionTabTrackStyle(scrolls, maxWidth)}>
+      <OverlayPills<ProjectionTab>
+        role="tablist"
+        label={label ?? 'Views'}
+        value={tab}
+        options={options}
+        baseId={baseId}
+        panelId={panelId}
+        onChange={onTabChange}
+      />
+    </div>
+  );
+}
+
+/**
+ * Bring the view in force back into sight inside a scrolling strip.
+ *
+ * The box is scrolled by hand rather than through `scrollIntoView`, which asks
+ * every scrolling ancestor to move as well — so a figure halfway down somebody
+ * else's page would jump under the reader for a tab they can already see.
+ *
+ * Where the view sits is measured against the strip's own box rather than read
+ * off `offsetLeft`, which is relative to whichever ancestor happens to be
+ * positioned — here the card, several boxes further out.
+ * @param box - The scrolling box, when it has been laid out.
+ */
+function showSelected(box: HTMLDivElement | null): void {
+  if (box === null) return;
+  const selected = box.querySelector<HTMLElement>('[aria-selected="true"]');
+  if (selected === null) return;
+  const seen = selected.getBoundingClientRect();
+  const left = seen.left - box.getBoundingClientRect().left + box.scrollLeft;
+  box.scrollLeft = projectionTabScroll(
+    left,
+    left + seen.width,
+    box.scrollLeft,
+    box.clientWidth,
+  );
+}

package/src/projection/ui/ProjectionVariablesControls.tsx

@@ -0,0 +1,62 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import { OverlayValueMenu } from '../../overlay/ui/OverlayValueMenu.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionOptions,
+  ProjectionVariablesView,
+} from '../core/projectionOptions.ts';
+
+import type { ProjectionVariablesAvailability } from './projectionViewChoices.ts';
+import { projectionViewChoices } from './projectionViewChoices.ts';
+
+/** What the "what differs" picker on the bar is drawn from. */
+export interface ProjectionVariablesControlsProps extends ProjectionVariablesAvailability {
+  /** Every option the panels are drawn from. */
+  options: ProjectionOptions;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /**
+   * How much of itself the bar is writing.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+}
+
+/**
+ * The one control of the "what differs" tab that stays on the bar.
+ *
+ * "Show" is the only choice here that changes what the panels mean rather than
+ * how they are drawn, and it is the one a reader who has never met a loading
+ * needs first. 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 props - See {@link ProjectionVariablesControlsProps}.
+ * @returns The picker.
+ */
+export function ProjectionVariablesControls(
+  props: ProjectionVariablesControlsProps,
+): ReactElement {
+  const { options, copy, onChange, tier = 'full' } = props;
+  const { canShowEffect, canRescale, canPickSample } = props;
+  const { bar, help } = copy;
+
+  return (
+    <OverlayValueMenu<ProjectionVariablesView>
+      label={help.variablesView.title}
+      keyWord={bar.key.variablesView}
+      showKey={tier === 'full'}
+      value={options.variablesView}
+      options={projectionViewChoices(copy, {
+        canShowEffect,
+        canRescale,
+        canPickSample,
+      })}
+      onChange={(variablesView) => onChange({ variablesView })}
+    />
+  );
+}

package/src/projection/ui/ProjectionVariablesMore.tsx

@@ -0,0 +1,144 @@
+import type { ReactElement } from 'react';
+
+import { OverlayGroup } from '../../overlay/ui/OverlayGroup.tsx';
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionOptions,
+  ProjectionVariablesView,
+} from '../core/projectionOptions.ts';
+import {
+  PROJECTION_PANEL_NAME,
+  PROJECTION_PANEL_SECTION,
+} from '../core/projectionStrings.ts';
+import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
+
+import type { ProjectionVariablesAvailability } from './projectionViewChoices.ts';
+import { projectionViewChoices } from './projectionViewChoices.ts';
+
+/** What the panels keep behind the cog is drawn from. */
+export interface ProjectionVariablesMoreProps extends ProjectionVariablesAvailability {
+  /** Every option the panels are drawn from. */
+  options: ProjectionOptions;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** How many components the run produced, which caps the panel count. */
+  axisCount: number;
+  /** Whether the measurements lie along a number line, which fixes their order. */
+  continuous: boolean;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+}
+
+/**
+ * What the "what differs" tab keeps behind the cog: which view the panels
+ * draw, how many of them there are, what they are measured against, and how
+ * the marks along them are drawn.
+ *
+ * Six settings in one column is a list the eye slides off, so the two that
+ * decide what a panel *is* stand at the top under no heading at all, and the
+ * rest are filed under what they are about — the scale the panels are read
+ * against, then the marks drawn on them. The first two need no heading
+ * precisely because they are first: a caption over the top of a panel repeats
+ * the panel's own title.
+ * @param props - See {@link ProjectionVariablesMoreProps}.
+ * @returns The panel behind the cog.
+ */
+export function ProjectionVariablesMore(
+  props: ProjectionVariablesMoreProps,
+): ReactElement {
+  const { options, copy, axisCount, continuous, onChange } = props;
+  const { canShowEffect, canRescale, canPickSample } = props;
+  const { help, tab } = copy;
+
+  return (
+    <OverlayPanel
+      title={tab.variables}
+      onReset={() => onChange(PROJECTION_TAB_DEFAULTS.variables)}
+    >
+      <OverlaySelect<ProjectionVariablesView>
+        label={PROJECTION_PANEL_NAME.variablesView}
+        help={help.variablesView}
+        value={options.variablesView}
+        options={projectionViewChoices(copy, {
+          canShowEffect,
+          canRescale,
+          canPickSample,
+        })}
+        onChange={(variablesView) => onChange({ variablesView })}
+      />
+      <OverlayNumber
+        label={PROJECTION_PANEL_NAME.variablesCount}
+        help={help.variablesCount}
+        value={options.variablesCount}
+        min={1}
+        max={Math.max(1, axisCount)}
+        onChange={(variablesCount) => onChange({ variablesCount })}
+      />
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.scale}>
+        <OverlayToggle
+          label={PROJECTION_PANEL_NAME.sharedScale}
+          help={help.sharedScale}
+          checked={options.sharedScale}
+          onChange={(sharedScale) => onChange({ sharedScale })}
+        />
+        <OverlayNumber
+          label={PROJECTION_PANEL_NAME.spread}
+          help={help.spread}
+          value={options.spread}
+          min={SMALLEST_REACH}
+          max={LARGEST_REACH}
+          step={SMALLEST_REACH}
+          digits={1}
+          disabled={options.variablesView !== 'effect'}
+          onChange={(spread) => onChange({ spread })}
+        />
+      </OverlayGroup>
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.drawing}>
+        <OverlayToggle
+          label={PROJECTION_PANEL_NAME.showAverage}
+          help={help.showAverage}
+          checked={options.showAverage}
+          onChange={(showAverage) => onChange({ showAverage })}
+        />
+        <OverlaySegmented
+          label={PROJECTION_PANEL_NAME.variableOrder}
+          help={help.variableOrder}
+          value={options.variableOrder}
+          disabled={continuous}
+          options={ORDER_CHOICES}
+          onChange={(variableOrder) => onChange({ variableOrder })}
+        />
+      </OverlayGroup>
+    </OverlayPanel>
+  );
+}
+
+/**
+ * The two orders the bars of a panel can be drawn in.
+ *
+ * Both are written as what the reader gets rather than as what the code does,
+ * because "original" and "strongest" name the sort rather than the picture it
+ * produces.
+ */
+const ORDER_CHOICES: ReadonlyArray<
+  OverlayOption<ProjectionOptions['variableOrder']>
+> = [
+  { value: 'original', label: 'Your order' },
+  { value: 'strongest', label: 'Strongest first' },
+];
+
+/**
+ * How far the average sample may be pushed, in standard deviations.
+ *
+ * Half a deviation is the smallest step worth a redraw, and four reaches past
+ * every sample of a well-behaved component in both directions, so anything
+ * beyond it draws a sample nobody in the table resembles.
+ */
+const SMALLEST_REACH = 0.5;
+const LARGEST_REACH = 4;