react-cheminfo 0.9.0 → 0.11.0

package/src/download/core/index.ts

@@ -1,3 +1,39 @@
+export { cssTokenNames, resolveCssTokens } from './cssTokens.ts';
 export { downloadBlob } from './downloadBlob.ts';
+export type { DownloadFigureOptions, FigureFormat } from './downloadFigure.ts';
+export { downloadFigure } from './downloadFigure.ts';
 export { downloadText } from './downloadText.ts';
+export { FIGURE_PNG_TYPE, figurePng } from './figurePng.ts';
+export type { FigurePixels } from './figureScale.ts';
+export {
+  DEFAULT_FIGURE_SCALE,
+  FIGURE_MAX_PIXELS,
+  FIGURE_SCALES,
+  figurePixels,
+  figureScaleFits,
+  figureScaleLabel,
+  formatFigurePixels,
+} from './figureScale.ts';
+export type { FigureSvg, FigureSvgOptions } from './figureSvg.ts';
+export { FIGURE_SVG_TYPE, figureSvg } from './figureSvg.ts';
+export type {
+  FigurePiece,
+  FigureSvgDocumentOptions,
+} from './figureSvgDocument.ts';
+export { figureSvgDocument } from './figureSvgDocument.ts';
+export type {
+  FigureLegendCard,
+  FigureLegendMark,
+  FigureLegendPrint,
+  FigureLegendText,
+} from './figureLegend.ts';
+export { figureLegendMarkup } from './figureLegend.ts';
+export type { FigureBounds } from './figureTarget.ts';
+export {
+  figureBounds,
+  figureDrawings,
+  figureElement,
+  figureLegends,
+  figureSize,
+} from './figureTarget.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';

package/src/download/ui/FigureDownload.tsx

@@ -0,0 +1,158 @@
+import type { IconName } from '@blueprintjs/core';
+import { PopoverNext } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import { downloadFigure } from '../core/downloadFigure.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import { DEFAULT_FIGURE_SCALE, FIGURE_SCALES } from '../core/figureScale.ts';
+import { figureSize } from '../core/figureTarget.ts';
+
+import { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
+
+/** What {@link FigureDownload} needs. */
+export interface FigureDownloadProps {
+  /**
+   * The `id` of the box the figure is mounted in. Everything drawn inside it
+   * is saved — sixteen charts of a pair grid as readily as one scatter plot —
+   * and the controls floating over it are left behind.
+   */
+  targetId: string;
+  /**
+   * What the saved file is called, without its extension. Name it after the
+   * data rather than after the tool: a reader with four of these in a
+   * downloads folder cannot tell four `figure.png` apart.
+   * @default 'figure'
+   */
+  fileName?: string;
+  /**
+   * The format it opens on.
+   * @default 'png'
+   */
+  defaultFormat?: FigureFormat;
+  /**
+   * The resolution it opens on, as a multiple of the figure on screen.
+   * @default 2
+   */
+  defaultScale?: number;
+  /**
+   * The resolutions offered.
+   * @default [1, 2, 3, 4]
+   */
+  scales?: readonly number[];
+  /**
+   * What is painted under the figure. `transparent` leaves it unpainted, for a
+   * figure going onto a coloured slide.
+   * @default the surface the figure is drawn on
+   */
+  background?: string;
+  /**
+   * What the glyph is called, for the pointer and for a screen reader.
+   * @default 'Save this figure'
+   */
+  label?: string;
+  /**
+   * What the panel behind it is called.
+   * @default 'Save figure'
+   */
+  title?: string;
+  /**
+   * Its glyph.
+   * @default 'download'
+   */
+  icon?: IconName;
+  /**
+   * Value of the `data-testid` attribute of the glyph.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The glyph that takes the figure off the page as a file.
+ *
+ * It works from the `id` of the box the figure is mounted in rather than from
+ * the figure itself, so the control is free to sit in the bar above the
+ * picture — or anywhere else on the page — without the component that drew the
+ * figure having to hand anything over. That is also what lets one control save
+ * a view that is really several charts: whatever is inside the box is what is
+ * saved.
+ *
+ * Both formats are offered because they answer different questions. An SVG is
+ * the figure itself, sharp at any size and still editable, which is what a
+ * paper wants; a PNG is a picture of it, which is what every chat window and
+ * slide deck accepts. The resolution belongs to the second alone, and the
+ * panel writes out the pixels it is about to produce so nobody has to guess
+ * what `3×` means for the figure in front of them.
+ * @param props - See {@link FigureDownloadProps}.
+ * @returns The glyph and its panel.
+ */
+export function FigureDownload(props: FigureDownloadProps): ReactElement {
+  const { targetId, fileName, background, scales = FIGURE_SCALES } = props;
+  const { defaultFormat = 'png', defaultScale = DEFAULT_FIGURE_SCALE } = props;
+  const { label = 'Save this figure', title = 'Save figure' } = props;
+  const { icon = 'download', testId } = props;
+
+  const [open, setOpen] = useState(false);
+  const [format, setFormat] = useState<FigureFormat>(defaultFormat);
+  const [scale, setScale] = useState(defaultScale);
+  const [size, setSize] = useState<FigurePixels | null>(null);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  // The panel is held open from here rather than left to itself, because the
+  // figure has to be measured at the moment it opens: its size is what the
+  // panel writes out, and reading a bounding box on every render would cost a
+  // layout pass on a bar that is re-rendered on every pointer move.
+  function interact(next: boolean): void {
+    setOpen(next);
+    if (!next) return;
+    setSize(figureSize(targetId));
+    setFailure(null);
+  }
+
+  async function save(): Promise<void> {
+    setSaving(true);
+    try {
+      await downloadFigure(targetId, { format, scale, fileName, background });
+      setFailure(null);
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <PopoverNext
+      isOpen={open}
+      placement="bottom-end"
+      onInteraction={interact}
+      content={
+        <FigureDownloadPanel
+          title={title}
+          format={format}
+          scale={scale}
+          scales={scales}
+          size={size}
+          failure={failure}
+          saving={saving}
+          onFormatChange={setFormat}
+          onScaleChange={setScale}
+          onSave={() => void save()}
+        />
+      }
+    >
+      <OverlayIconButton
+        icon={icon}
+        label={label}
+        value={format.toUpperCase()}
+        active={open}
+        testId={testId}
+        opensMenu
+      />
+    </PopoverNext>
+  );
+}

package/src/download/ui/FigureDownloadPanel.tsx

@@ -0,0 +1,165 @@
+import type { ReactElement } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import {
+  figurePixels,
+  figureScaleFits,
+  figureScaleLabel,
+  formatFigurePixels,
+} from '../core/figureScale.ts';
+
+/** What {@link FigureDownloadPanel} is drawn from. */
+export interface FigureDownloadPanelProps {
+  /** What the panel is called. */
+  title: string;
+  /** Which file the reader is about to write. */
+  format: FigureFormat;
+  /** The multiple of the figure on screen it is painted at. */
+  scale: number;
+  /** The multiples offered. */
+  scales: readonly number[];
+  /** How big the figure is on the page, or `null` where there is none. */
+  size: FigurePixels | null;
+  /** What went wrong the last time save was pressed, if anything. */
+  failure: string | null;
+  /** Whether a file is being written right now. */
+  saving: boolean;
+  /** Called with the format the reader picked. */
+  onFormatChange: (format: FigureFormat) => void;
+  /** Called with the multiple they picked. */
+  onScaleChange: (scale: number) => void;
+  /** Called when they press save. */
+  onSave: () => void;
+}
+
+/**
+ * The two choices behind the save glyph, and the button that writes the file.
+ *
+ * The resolution stays in place and greyed while an SVG is selected rather
+ * than disappearing, because a control that vanishes is a control the reader
+ * concludes the figure does not have — and the sentence at the foot says why
+ * it is greyed, which is that an SVG has no resolution to choose.
+ *
+ * That sentence is the panel's own hint line rather than a row of its own: it
+ * is not a setting, it is what the two settings above it currently amount to,
+ * and it is the only thing here that answers the question a reader actually
+ * has, which is how big the file is going to be. Saving itself is a command
+ * rather than a setting, so it sits at the foot under the hairline: a button
+ * filed among the settings is read as one, and a press nobody meant to make.
+ * @param props - See {@link FigureDownloadPanelProps}.
+ * @returns The panel.
+ */
+export function FigureDownloadPanel(
+  props: FigureDownloadPanelProps,
+): ReactElement {
+  const { title, format, scale, scales, size, failure, saving } = props;
+  const { onFormatChange, onScaleChange, onSave } = props;
+
+  const vector = format === 'svg';
+
+  return (
+    <OverlayPanel
+      title={title}
+      hint={hintOf(format, size, scale, failure)}
+      actions={
+        <OverlayAction
+          text="Save"
+          icon="download"
+          intent="primary"
+          disabled={saving || size === null}
+          onClick={onSave}
+        />
+      }
+    >
+      <OverlaySegmented<FigureFormat>
+        label="Format"
+        help={FORMAT_HELP}
+        value={format}
+        options={FORMAT_CHOICES}
+        onChange={onFormatChange}
+      />
+      <OverlaySegmented
+        label="Resolution"
+        help={RESOLUTION_HELP}
+        value={String(scale)}
+        options={scaleChoices(scales, size)}
+        disabled={vector}
+        onChange={(picked) => onScaleChange(Number(picked))}
+      />
+    </OverlayPanel>
+  );
+}
+
+/** The two files a figure can leave the page as. */
+const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
+  { value: 'png', label: 'PNG' },
+  { value: 'svg', label: 'SVG' },
+];
+
+const FORMAT_HELP: HelpContent = {
+  title: 'Format',
+  body: 'A PNG is a picture of the figure, which is what a slide, a chat window or an issue accepts. An SVG is the figure itself: every line stays sharp however far it is enlarged, and it can still be edited afterwards.',
+};
+
+const RESOLUTION_HELP: HelpContent = {
+  title: 'Resolution',
+  body: 'How many pixels are painted for each pixel of the figure on screen. Two is right for a slide, three or four for print. An SVG carries no resolution of its own, so it is saved sharp at every size.',
+  example: {
+    code: '2×',
+    note: 'A figure 640 pixels wide on screen is saved 1280 pixels wide.',
+  },
+};
+
+/**
+ * The multiples offered, each saying what it would actually produce.
+ *
+ * One too large for the browser to paint is greyed rather than dropped, so the
+ * reader learns the ceiling exists before they meet it as a blank file.
+ * @param scales - The multiples the caller offers.
+ * @param size - How big the figure is on the page.
+ * @returns The choices, in the order offered.
+ */
+function scaleChoices(
+  scales: readonly number[],
+  size: FigurePixels | null,
+): readonly OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (const scale of scales) {
+    const pixels = size === null ? null : figurePixels(size, scale);
+    choices.push({
+      value: String(scale),
+      label: figureScaleLabel(scale),
+      title: pixels === null ? undefined : formatFigurePixels(pixels),
+      disabled: size !== null && !figureScaleFits(size, scale),
+    });
+  }
+  return choices;
+}
+
+/**
+ * The line at the foot of the panel: what pressing save is about to do.
+ * @param format - Which file the reader is about to write.
+ * @param size - How big the figure is on the page.
+ * @param scale - The multiple it is painted at.
+ * @param failure - What went wrong last time, if anything.
+ * @returns The sentence.
+ */
+function hintOf(
+  format: FigureFormat,
+  size: FigurePixels | null,
+  scale: number,
+  failure: string | null,
+): string {
+  if (failure !== null) return failure;
+  if (size === null) return 'There is no figure on the page to save yet.';
+  if (format === 'svg') {
+    return `An SVG stays sharp at any size, so the resolution does not apply. Drawn ${formatFigurePixels(size)}.`;
+  }
+  return `Saved ${formatFigurePixels(figurePixels(size, scale))}.`;
+}

package/src/download/ui/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Taking what is on the page off it, as a file.
+ *
+ * The one component here saves a figure, and it is given the `id` of the box
+ * the figure sits in rather than the figure itself: a chart does not have to
+ * know it is savable, and a bar above one can offer to save it without either
+ * of them holding a reference to the other.
+ */
+
+export type { FigureDownloadProps } from './FigureDownload.tsx';
+export { FigureDownload } from './FigureDownload.tsx';
+export type { FigureDownloadPanelProps } from './FigureDownloadPanel.tsx';
+export { FigureDownloadPanel } from './FigureDownloadPanel.tsx';

package/src/ecosystem/core/sites.ts

@@ -7,6 +7,7 @@ export type SiteId =
   | 'smiles'
   | 'chemcalc'
   | 'nmrium'
+  | 'metabo'
   | 'derepflow'
   | 'surge'
   | 'tex'
@@ -17,7 +18,8 @@ export type SiteId =
   | 'equilibrium'
   | 'polycarp'
   | '3d'
-  | 'periodic-table';
+  | 'periodic-table'
+  | 'database';
 
 export interface SiteName {
   /** First half of the name, set in the site's leading colour. */
@@ -132,6 +134,19 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     brandAlt: '#2b143e',
     mark: { plate: '#2b143e', accent: '#ea580c' },
   },
+  {
+    id: 'metabo',
+    // Not `.cheminfo`: the second half of a one-word name is the domain the
+    // site actually lives at, and this one is a sibling of NMRium rather than
+    // of the cheminfo tools.
+    name: { lead: 'metabo', alt: 'nmrium', dot: true },
+    host: 'metabo.nmrium.com',
+    repository: 'https://github.com/cheminfo/metabo',
+    tagline: 'Turn a batch of NMR spectra into a map of your samples.',
+    brand: '#4d7c0f',
+    brandAlt: '#b91c1c',
+    mark: { plate: '#4d7c0f', accent: '#b91c1c' },
+  },
   {
     id: 'derepflow',
     name: { lead: 'Derep', alt: 'Flow' },
@@ -242,6 +257,16 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     brandAlt: '#a16207',
     mark: { plate: '#15803d', accent: '#fbbf24' },
   },
+  {
+    id: 'database',
+    name: { lead: 'database', alt: 'cheminfo', dot: true },
+    host: 'database.cheminfo.org',
+    repository: 'https://github.com/cheminfo/database.cheminfo.org',
+    tagline: 'Query a real chemical dataset in SQL and in Mango.',
+    brand: '#7c2d12',
+    brandAlt: '#0b6e85',
+    mark: { plate: '#7c2d12', accent: '#06b6d4' },
+  },
 ];
 
 /**

package/src/ecosystem/ui/glyphs.tsx

@@ -148,6 +148,32 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       />
     </g>
   ),
+  // Two groups of samples with the outline that holds each: the picture the
+  // tool exists to draw. One is drawn and one is filled rather than both
+  // outlined, because two rings crossing close up into a blob at 16 px —
+  // checked at 16, 20, 24, 32 and 64 before this was settled on.
+  metabo: (accent) => (
+    <>
+      <ellipse
+        cx="12"
+        cy="12.5"
+        rx="5.8"
+        ry="9"
+        fill="none"
+        stroke="#ffffff"
+        strokeWidth="3"
+        transform="rotate(-32 12 12.5)"
+      />
+      <ellipse
+        cx="20.5"
+        cy="20"
+        rx="5.4"
+        ry="8.6"
+        fill={accent}
+        transform="rotate(32 20.5 20)"
+      />
+    </>
+  ),
   // One formula branching into every structure it can be.
   surge: (alt) => (
     <>
@@ -302,4 +328,20 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       <circle cx="16" cy="16" r="2.9" fill="#ffffff" />
     </>
   ),
+  // A stack of platters, the top one carrying the answering colour: the disk
+  // stack every database has been drawn as, and the two shapes this site asks
+  // the same question in.
+  database: (alt) => (
+    <>
+      <path
+        d="M5.8 9.4v5.3a10.2 3.9 0 0 0 20.4 0V9.4a10.2 3.9 0 0 1-20.4 0Z"
+        fill="#ffffff"
+      />
+      <path
+        d="M5.8 17.4v5.3a10.2 3.9 0 0 0 20.4 0v-5.3a10.2 3.9 0 0 1-20.4 0Z"
+        fill="#ffffff"
+      />
+      <ellipse cx="16" cy="9.4" rx="10.2" ry="3.9" fill={alt} />
+    </>
+  ),
 };

package/src/overlay/core/emptiestCorner.ts

@@ -0,0 +1,122 @@
+import type { OverlayCorner } from './overlayPlacement.ts';
+
+/** What {@link emptiestCorner} has to know about the figure. */
+export interface EmptiestCornerOptions {
+  /** Width of the plot, in pixels. */
+  width: number;
+  /** Height of the plot, in pixels. */
+  height: number;
+  /**
+   * Width the card is expected to take. It is an estimate on purpose: the card
+   * has not been laid out when the corner is chosen.
+   * @default 210
+   */
+  cardWidth?: number;
+  /**
+   * Height the card is expected to take.
+   * @default 76
+   */
+  cardHeight?: number;
+  /**
+   * The corner kept when two are equally empty, which is the common case on a
+   * sparse plot. Keeping a preference is what stops the card hopping between
+   * corners as one point is added.
+   * @default 'top-right'
+   */
+  preferred?: OverlayCorner;
+}
+
+/**
+ * The corner of a plot with the fewest marks under it.
+ *
+ * A card in a fixed corner eventually sits on the one cluster the reader came
+ * for. Counting first costs four comparisons per point, once per relayout, and
+ * it is the difference between chrome and an obstruction.
+ *
+ * Ties are settled by a fixed order so the answer never depends on which mark
+ * was read first: the preferred corner, then the one diagonally across from it,
+ * then the remaining two clockwise from the top left. The diagonal comes second
+ * because the preferred corner only loses when it holds marks, and the far side
+ * of the plot is the least likely place for the rest of that same cluster.
+ * @param x - Horizontal position of every mark, in pixels from the plot's left.
+ * @param y - Vertical position of every mark, in pixels from the plot's top.
+ * @param options - See {@link EmptiestCornerOptions}.
+ * @returns The emptiest corner; the preferred one when several tie. An empty
+ * plot, or one whose size has not been measured, is entirely empty and so
+ * returns the preferred corner too.
+ */
+export function emptiestCorner(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  options: EmptiestCornerOptions,
+): OverlayCorner {
+  const {
+    width,
+    height,
+    cardWidth = DEFAULT_CARD_WIDTH,
+    cardHeight = DEFAULT_CARD_HEIGHT,
+    preferred = 'top-right',
+  } = options;
+
+  const leftEdge = cardWidth;
+  const rightEdge = width - cardWidth;
+  const topEdge = cardHeight;
+  const bottomEdge = height - cardHeight;
+
+  const counts: Record<OverlayCorner, number> = {
+    'top-left': 0,
+    'top-right': 0,
+    'bottom-left': 0,
+    'bottom-right': 0,
+  };
+
+  const total = Math.min(x.length, y.length);
+  for (let index = 0; index < total; index++) {
+    const pointX = x[index];
+    const pointY = y[index];
+    if (pointX === undefined || pointY === undefined) continue;
+    const inLeft = pointX <= leftEdge;
+    const inRight = pointX >= rightEdge;
+    const inTop = pointY <= topEdge;
+    const inBottom = pointY >= bottomEdge;
+    if (inTop && inLeft) counts['top-left']++;
+    if (inTop && inRight) counts['top-right']++;
+    if (inBottom && inLeft) counts['bottom-left']++;
+    if (inBottom && inRight) counts['bottom-right']++;
+  }
+
+  let best = preferred;
+  let fewest = counts[preferred];
+  for (const corner of tieOrder(preferred)) {
+    if (counts[corner] >= fewest) continue;
+    best = corner;
+    fewest = counts[corner];
+  }
+  return best;
+}
+
+const DEFAULT_CARD_WIDTH = 210;
+const DEFAULT_CARD_HEIGHT = 76;
+
+const CORNERS: readonly OverlayCorner[] = [
+  'top-left',
+  'top-right',
+  'bottom-right',
+  'bottom-left',
+];
+
+const OPPOSITE: Record<OverlayCorner, OverlayCorner> = {
+  'top-left': 'bottom-right',
+  'top-right': 'bottom-left',
+  'bottom-left': 'top-right',
+  'bottom-right': 'top-left',
+};
+
+function tieOrder(preferred: OverlayCorner): OverlayCorner[] {
+  const opposite = OPPOSITE[preferred];
+  const order: OverlayCorner[] = [opposite];
+  for (const corner of CORNERS) {
+    if (corner !== preferred && corner !== opposite) order.push(corner);
+  }
+  return order;
+}

package/src/overlay/core/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a floating control sits over a figure, and how big it is.
+ *
+ * The geometry lives apart from the components that use it so it can be
+ * reasoned about and tested without a browser: which corner of a scatter is
+ * emptiest, whether a panel has room for a labelled strip or only a gear, and
+ * where a card must flip so it stays on screen.
+ */
+
+export type { EmptiestCornerOptions } from './emptiestCorner.ts';
+export { emptiestCorner } from './emptiestCorner.ts';
+export { shouldCollapseOverlay } from './overlayCollapse.ts';
+export type { OverlayMarkShape } from './overlayMarks.ts';
+export { OVERLAY_MARK_SHAPES, isFilledMark } from './overlayMarks.ts';
+export type {
+  OverlayDensity,
+  OverlayMetrics,
+  OverlayPointerKind,
+} from './overlayMetrics.ts';
+export { overlayMetrics } from './overlayMetrics.ts';
+export type {
+  OverlayCorner,
+  OverlayCornerStyle,
+  OverlayPlacement,
+} from './overlayPlacement.ts';
+export { overlayCornerStyle } from './overlayPlacement.ts';
+export type { OverlayTierRoom, OverlayTierSetting } from './overlayTierRoom.ts';
+export type { OverlayTier, OverlayTierWidths } from './overlayTiers.ts';
+export { overlayTier, overlayTierWidths } from './overlayTiers.ts';
+export type {
+  OverlayCardPlacement,
+  OverlayCardPlacementOptions,
+} from './placeOverlayCard.ts';
+export { placeOverlayCard } from './placeOverlayCard.ts';

package/src/overlay/core/overlayCollapse.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a floating card folds into a single button at this figure width.
+ *
+ * A width of zero — which is what a figure reports before it has been measured,
+ * and what a server render always reports — keeps the card expanded, so the
+ * string-rendering tests and the first paint both see the real controls. A
+ * threshold that is not a real number is read the same way, so a missing
+ * breakpoint never silently hides every control on the figure.
+ * @param width - Width of the figure, in pixels.
+ * @param collapseBelow - The width under which the card folds.
+ * @returns Whether it folds.
+ */
+export function shouldCollapseOverlay(
+  width: number,
+  collapseBelow: number,
+): boolean {
+  if (!Number.isFinite(width) || width <= 0) return false;
+  if (!Number.isFinite(collapseBelow)) return false;
+  return width < collapseBelow;
+}