react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/projectionBarModel.ts

@@ -0,0 +1,194 @@
+/**
+ * How much of itself the settings bar writes at the width the figure has.
+ *
+ * The bar never wraps: a second row would change the figure's height as the
+ * host page resized, and an embedded figure that moves somebody else's layout
+ * while it is being read is worse than one whose settings have been written
+ * shorter. So what a narrowing figure loses is words, one rung at a time —
+ * the key word in front of each value, then the long form of the tab names,
+ * then the boxes around the settings, which gather into one chip that still
+ * reads the configuration. No rung ever takes a control away.
+ *
+ * Nothing here is a magic number. The thresholds come out of the content: a
+ * viewer with two tabs stays roomy far longer than one with six, and a site
+ * that has translated the tab names has changed exactly these widths. The
+ * ladder itself lives in the overlay domain; what this adds is the room a
+ * projection's own controls need that the ladder cannot see, because a stepper
+ * is two buttons around a number rather than words on a button.
+ */
+
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import type {
+  OverlayTierRoom,
+  OverlayTierSetting,
+} from '../../overlay/core/overlayTierRoom.ts';
+import {
+  overlayChipRoom,
+  overlaySettingsWidth,
+  overlayTailWidth,
+} from '../../overlay/core/overlayTierRoom.ts';
+import type {
+  OverlayTier,
+  OverlayTierWidths,
+} from '../../overlay/core/overlayTiers.ts';
+import {
+  overlayTier,
+  overlayTierWidths,
+} from '../../overlay/core/overlayTiers.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import type { ProjectionReading } from './projectionBarReadings.ts';
+import { projectionUnwrittenRoom } from './projectionBarReadings.ts';
+
+/** What the bar is holding, for the width it needs to hold it. */
+export interface ProjectionBarRoom {
+  /** What each pill of the strip reads; empty when there is no strip. */
+  tabLabels: readonly string[];
+  /** The short form of each, in the same order. */
+  shortTabLabels: readonly string[];
+  /** What the tab showing writes at the far end. */
+  readings: readonly ProjectionReading[];
+  /**
+   * How many bare glyphs ride at the very end: the `?` and the cog.
+   * @default 2
+   */
+  glyphs?: number;
+}
+
+/**
+ * How many bare glyphs the bar carries at its end on this tab.
+ *
+ * The save glyph rides every tab, because every tab draws a figure somebody may
+ * want to keep. The question mark and the cog ride all but the shares one,
+ * whose figure needs no explanation its own axes do not already give. The map
+ * carries two more: the switches that write the names onto the picture. They
+ * are glyphs because a switch has no value to write — it is thrown or it is not
+ * — so a word beside one would be a caption rather than a reading, and being
+ * already as small as a control can be drawn, they are the one thing on the bar
+ * that never folds.
+ * @param tab - The tab showing.
+ * @returns How many button-sized glyphs the far end must keep room for.
+ */
+export function projectionBarGlyphs(tab: ProjectionTab): number {
+  if (tab === 'shares') return SAVE_GLYPHS + 1;
+  const named = tab === 'map' || tab === 'space';
+  return SAVE_GLYPHS + (named ? MAP_BAR_GLYPHS : BAR_GLYPHS);
+}
+
+/** The one that takes the figure off the page, on every tab. */
+const SAVE_GLYPHS = 1;
+
+/** The question mark and the cog, which almost every tab carries. */
+const BAR_GLYPHS = 2;
+
+/** Those two, and the pair of name switches the map and the cloud both carry. */
+const MAP_BAR_GLYPHS = 4;
+
+/**
+ * How much of itself the bar writes at this width.
+ *
+ * The width is the figure's own, never the page's: an embedded figure has no
+ * idea how wide the page around it is, and the same viewer four hundred pixels
+ * wide in a wide page and filling a phone is the same problem. An unmeasured
+ * figure is given the roomiest rung, so a bar never opens folded and springs
+ * open a frame later on every page that embeds it.
+ * @param width - Width of the figure, in pixels.
+ * @param room - See {@link ProjectionBarRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The rung.
+ */
+export function projectionBarTier(
+  width: number,
+  room: ProjectionBarRoom,
+  metrics: OverlayMetrics,
+): OverlayTier {
+  if (!Number.isFinite(width) || width <= 0) return 'full';
+  const unwritten = projectionUnwrittenRoom(room.readings, metrics);
+  const written = Math.max(1, width - unwritten);
+  return overlayTier(written, tierRoom(room), metrics);
+}
+
+/**
+ * The figure width each rung needs, for this content at these measurements.
+ *
+ * Published so the ladder can be read and pinned rather than guessed at: the
+ * numbers a four-tab principal component viewer folds at are an answer, not a
+ * decision anybody made.
+ * @param room - See {@link ProjectionBarRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The four widths, in pixels.
+ */
+export function projectionBarTierWidths(
+  room: ProjectionBarRoom,
+  metrics: OverlayMetrics,
+): OverlayTierWidths {
+  const unwritten = projectionUnwrittenRoom(room.readings, metrics);
+  const widths = overlayTierWidths(tierRoom(room), metrics);
+  return {
+    full: widths.full + unwritten,
+    condensed: widths.condensed + unwritten,
+    short: widths.short + unwritten,
+    chip: widths.chip + unwritten,
+  };
+}
+
+/**
+ * How much of the figure's width the far end of the bar is about to take.
+ *
+ * The row is one flex line whose two ends are told they may both shrink, and a
+ * chip beside a cog cannot shrink — it would simply hang off the edge, taking
+ * the cog with it. So the strip of views is given a ceiling instead: whatever
+ * the settings and the glyphs do not need. The estimate is the ladder's own,
+ * and it errs high, which costs the reader a few pixels of scroll rather than
+ * a control they cannot reach.
+ * @param room - See {@link ProjectionBarRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @param tier - The rung the bar is on, which decides how much it writes.
+ * @returns The width in pixels, the bar's own padding included.
+ */
+export function projectionBarEndRoom(
+  room: ProjectionBarRoom,
+  metrics: OverlayMetrics,
+  tier: OverlayTier,
+): number {
+  const { settings } = tierRoom(room);
+  const gathered = tier === 'chip' || tier === 'tiny';
+  const written = gathered
+    ? overlayChipRoom(settings, metrics)
+    : overlaySettingsWidth(settings, tier === 'full', metrics);
+  // The question mark has folded into the cog by the last rung, so only one
+  // glyph is left to leave room for.
+  const glyphs = tier === 'tiny' ? 1 : (room.glyphs ?? 2);
+  return (
+    written +
+    overlayTailWidth(glyphs, metrics) +
+    projectionUnwrittenRoom(room.readings, metrics) +
+    // Written type is always a little wider than an estimate read off the
+    // characters, and every gap the chip sets between its parts is missed
+    // outright. A control's height of slack is what keeps the last glyph
+    // inside the figure's own padding rather than flush against its edge.
+    metrics.controlHeight
+  );
+}
+
+/**
+ * The bar's content in the shape the ladder reads.
+ * @param room - See {@link ProjectionBarRoom}.
+ * @returns The ladder's own description of the same bar.
+ */
+function tierRoom(room: ProjectionBarRoom): OverlayTierRoom {
+  const settings: OverlayTierSetting[] = [];
+  for (const reading of room.readings) {
+    settings.push({
+      key: reading.key,
+      value: reading.value,
+      swatches: reading.swatches !== undefined && reading.swatches.length > 0,
+    });
+  }
+  return {
+    tabs: room.tabLabels,
+    shortTabs: room.shortTabLabels,
+    settings,
+    glyphs: room.glyphs ?? 2,
+  };
+}

package/src/projection/ui/projectionBarReadings.ts

@@ -0,0 +1,195 @@
+/**
+ * What the settings at the far end of the bar currently read.
+ *
+ * The same four or five words are needed twice and must agree both times: once
+ * to work out how much room the bar needs before anything is drawn, and once
+ * to write them on the chip a narrow bar gathers them into. Building them here
+ * is what stops the estimate from measuring `Species` while the chip writes
+ * `Colour by species` and folding the bar at the wrong width.
+ */
+
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import { ellipseCoverageText } from './projectionEllipse.ts';
+import { ellipsoidCoverageText } from './projectionEllipsoid.ts';
+import { WHOLE_SHARE } from './projectionTabStyles.ts';
+
+/** One setting on the bar, as the reader sees it right now. */
+export interface ProjectionReading {
+  /** The one word written in front of the value where there is room. */
+  key: string;
+  /** What the setting is called in full, which is what it announces. */
+  label: string;
+  /** What it currently reads: `Species`, `95%`, `4`. */
+  value: string;
+  /**
+   * The figure's own colours, for the setting that decides them.
+   * @default undefined — no dots are drawn
+   */
+  swatches?: readonly string[];
+  /**
+   * Whether it is a stepper rather than words. A number is the one setting a
+   * value button cannot improve, so it keeps its two buttons — which the
+   * ladder cannot see, because they are not written.
+   * @default false
+   */
+  stepper?: boolean;
+}
+
+/** What the readings of the tab showing are built from. */
+export interface ProjectionReadingsInput {
+  /** The tab showing, whose own settings sit at the far end of the bar. */
+  tab: ProjectionTab;
+  /** The words the viewer writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** What the figure is showing, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The groups as every figure draws them, whose colours the map writes. */
+  groups: ResolvedProjectionGroups;
+}
+
+/**
+ * What the tab showing writes at the far end of the bar.
+ * @param input - See {@link ProjectionReadingsInput}.
+ * @returns The readings, in the order they are written.
+ */
+export function projectionBarReadings(
+  input: ProjectionReadingsInput,
+): readonly ProjectionReading[] {
+  const { tab, copy, options, groups } = input;
+  const { bar, help } = copy;
+
+  if (tab === 'pairs') {
+    return [
+      {
+        key: bar.key.pairCount,
+        label: help.pairCount.title,
+        value: String(options.pairCount),
+        stepper: true,
+      },
+    ];
+  }
+  if (tab === 'variables') {
+    return [
+      {
+        key: bar.key.variablesView,
+        label: help.variablesView.title,
+        value: bar.view[options.variablesView],
+      },
+    ];
+  }
+  if (tab === 'space') {
+    return [
+      {
+        key: bar.key.cloudGesture,
+        label: help.cloudGesture.title,
+        value: options.cloudGesture === 'turn' ? 'Turn' : 'Select',
+      },
+      {
+        key: bar.key.ellipse,
+        label: help.ellipse.title,
+        value:
+          options.colorBy === 'group' && groups.entries.length > 0
+            ? ellipsoidCoverageText(options.ellipse)
+            : bar.noOutlines,
+      },
+    ];
+  }
+  if (tab === 'shares') {
+    return [
+      {
+        key: bar.key.shareTarget,
+        label: help.shareTarget.title,
+        value: `${Math.round(options.shareTarget * WHOLE_SHARE)}%`,
+        stepper: true,
+      },
+    ];
+  }
+  return mapReadings(copy, options, groups);
+}
+
+/**
+ * How much room the readings need beyond the words on them.
+ *
+ * A stepper is two buttons around a number, and the ladder measures a setting
+ * from what is written on it — so without this a bar holding one would be
+ * given about a third of the room the stepper actually takes and would run its
+ * controls off the edge of the figure rather than folding.
+ * @param readings - What the tab showing writes.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The extra width, in pixels.
+ */
+export function projectionUnwrittenRoom(
+  readings: readonly ProjectionReading[],
+  metrics: OverlayMetrics,
+): number {
+  let extra = 0;
+  for (const reading of readings) {
+    if (reading.stepper === true) {
+      extra += 2 * metrics.buttonSize + 2 * metrics.gap;
+    }
+  }
+  return extra;
+}
+
+/**
+ * The colours the map is painting the groups in, for the swatch glyph.
+ *
+ * Empty while the colour stands for nothing, so a bar that says `Nothing`
+ * does not carry a row of dots contradicting it.
+ * @param options - What the figure is showing.
+ * @param groups - The groups as every figure draws them.
+ * @returns The colours, in the order the figure draws them.
+ */
+function projectionGroupColors(
+  options: ProjectionOptions,
+  groups: ResolvedProjectionGroups,
+): readonly string[] {
+  if (options.colorBy !== 'group') return NO_COLORS;
+  const colors: string[] = [];
+  for (const entry of groups.entries) colors.push(entry.color);
+  return colors;
+}
+
+/**
+ * What the map writes: what the colour stands for, and how wide the outlines
+ * are drawn.
+ *
+ * The two switches that write names on the picture are not here. A switch has
+ * no value to read out — it is thrown or it is not — so it rides the bar as a
+ * glyph, like the question mark and the cog, and is counted in the room the
+ * bar keeps for those rather than in the words it writes.
+ * @param copy - The words the viewer writes.
+ * @param options - What the figure is showing.
+ * @param groups - The groups as every figure draws them.
+ * @returns The two readings.
+ */
+function mapReadings(
+  copy: ProjectionCopy,
+  options: ProjectionOptions,
+  groups: ResolvedProjectionGroups,
+): readonly ProjectionReading[] {
+  const { bar, help } = copy;
+  const colored = options.colorBy === 'group';
+  const coverage = ellipseCoverageText(options.ellipse);
+  return [
+    {
+      key: bar.key.colorBy,
+      label: help.colorBy.title,
+      value: colored ? groups.label : bar.uncoloured,
+      swatches: projectionGroupColors(options, groups),
+    },
+    {
+      key: bar.key.ellipse,
+      label: help.ellipse.title,
+      value: coverage === '' ? bar.noOutlines : coverage,
+    },
+  ];
+}
+
+/** No colours at all, which is what an uncoloured map paints. */
+const NO_COLORS: readonly string[] = [];

package/src/projection/ui/projectionBarSlots.tsx

@@ -0,0 +1,158 @@
+import type { ReactNode } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import { ProjectionMapControls } from './ProjectionMapControls.tsx';
+import { ProjectionMapMore } from './ProjectionMapMore.tsx';
+import { ProjectionPairsControls } from './ProjectionPairsControls.tsx';
+import { ProjectionPairsMore } from './ProjectionPairsMore.tsx';
+import { ProjectionSharesControls } from './ProjectionSharesControls.tsx';
+import { ProjectionSharesMore } from './ProjectionSharesMore.tsx';
+import { ProjectionSpaceControls } from './ProjectionSpaceControls.tsx';
+import { ProjectionSpaceMore } from './ProjectionSpaceMore.tsx';
+import { ProjectionVariablesControls } from './ProjectionVariablesControls.tsx';
+import { ProjectionVariablesMore } from './ProjectionVariablesMore.tsx';
+import type { ProjectionReading } from './projectionBarReadings.ts';
+import type { ProjectionMapView } from './projectionMapView.ts';
+import {
+  projectionPairsInfo,
+  projectionSharesInfo,
+  projectionVariablesInfo,
+} from './projectionTabInfo.ts';
+import type { ProjectionModels } from './projectionTabModels.ts';
+
+/** The three things one tab puts in the bar. */
+export interface ProjectionBarSlots {
+  /** The settings of the tab showing, written to the rung the bar is on. */
+  end: ReactNode;
+  /** What waits behind the cog; nothing at all draws no cog. */
+  more: ReactNode;
+  /** What the question mark hands back; empty draws no question mark. */
+  info: string;
+}
+
+/** What the tab showing is asked for, to fill the bar with. */
+export interface ProjectionBarSlotsInput {
+  /** The tab showing. */
+  tab: ProjectionTab;
+  /** What the run produced. */
+  result: ProjectionResult;
+  /** The words the viewer writes. */
+  copy: ProjectionCopy;
+  /** The two figures the bar explains. */
+  models: ProjectionModels;
+  /** The map's frame and the buttons that change it. */
+  map: ProjectionMapView;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The groups as every figure draws them. */
+  groups: ResolvedProjectionGroups;
+  /** The selected rows, as indices. */
+  selected: readonly number[];
+  /** Width of the viewer, in pixels. */
+  width: number;
+  /** What the settings of the tab showing currently read. */
+  readings: readonly ProjectionReading[];
+  /** How much of itself the bar is writing at this width. */
+  tier: OverlayTier;
+  /** Called with only the options that changed. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+}
+
+/**
+ * The controls and the explanation of the tab showing.
+ *
+ * Each tab writes on the bar the one or two settings a reader of that tab
+ * actually looks at, and hands its whole panel of settings to the cog. What
+ * the rung decides is how much of the bar's settings is written — never which
+ * of them the reader is offered, because a control that has disappeared is a
+ * control the reader concludes the figure does not have.
+ * @param input - See {@link ProjectionBarSlotsInput}.
+ * @returns See {@link ProjectionBarSlots}.
+ */
+export function projectionBarSlots(
+  input: ProjectionBarSlotsInput,
+): ProjectionBarSlots {
+  const { tab, result, copy, models, map, readings, tier } = input;
+  const { options, groups, selected, width, onChange } = input;
+
+  const hasGroups = groups.entries.length > 0;
+  const colored = options.colorBy === 'group' && hasGroups;
+  const shared = { options, onChange, copy, groupLabel: groups.label };
+
+  if (tab === 'pairs') {
+    const pairs = {
+      ...shared,
+      hasGroups,
+      axisCount: result.axes.length,
+      width,
+    };
+    return {
+      end: <ProjectionPairsControls {...pairs} tier={tier} />,
+      more: <ProjectionPairsMore {...pairs} />,
+      info: projectionPairsInfo(copy, groups.label, colored),
+    };
+  }
+  if (tab === 'space') {
+    const space = {
+      ...shared,
+      result,
+      hasGroups,
+      selectedCount: selected.length,
+      onResetView: map.resetSpaceView,
+      onClearSelection: map.clearSelection,
+    };
+    return {
+      end: (
+        <ProjectionSpaceControls {...space} readings={readings} tier={tier} />
+      ),
+      more: <ProjectionSpaceMore {...space} />,
+      info: map.spaceChrome.caption,
+    };
+  }
+  if (tab === 'variables') {
+    const variables = {
+      options,
+      copy,
+      onChange,
+      axisCount: result.axes.length,
+      canShowEffect: result.loadings?.mean !== undefined,
+      canRescale: result.loadings?.scales !== undefined,
+      canPickSample: selected.length === 1,
+      continuous: models.profiles?.axis.kind === 'continuous',
+    };
+    return {
+      end: <ProjectionVariablesControls {...variables} tier={tier} />,
+      more: <ProjectionVariablesMore {...variables} />,
+      info: projectionVariablesInfo(models.profiles, copy, models.sampleName),
+    };
+  }
+  if (tab === 'shares') {
+    const shares = { options, copy, onChange };
+    return {
+      end: <ProjectionSharesControls {...shares} tier={tier} />,
+      more: <ProjectionSharesMore {...shares} />,
+      info: projectionSharesInfo(models.shares, copy),
+    };
+  }
+
+  const forMap = {
+    ...shared,
+    result,
+    hasGroups,
+    selectedCount: selected.length,
+    onZoomToSelection: map.zoomToSelection,
+    onResetView: map.resetView,
+    onClearSelection: map.clearSelection,
+  };
+  return {
+    end: <ProjectionMapControls {...forMap} readings={readings} tier={tier} />,
+    more: <ProjectionMapMore {...forMap} />,
+    info: map.chrome.caption,
+  };
+}