react-cheminfo 0.9.0 → 0.10.0

package/src/download/core/figureTarget.ts

@@ -0,0 +1,130 @@
+/**
+ * Finding the drawings inside whatever the caller pointed at.
+ *
+ * A caller names a figure by the `id` of the box it is mounted in — never by
+ * handing over an element it had to hold a ref to — because the box is
+ * something a page already has a name for, and because the thing that saves
+ * the figure is then free to sit anywhere on the page rather than inside the
+ * component that drew it.
+ */
+
+import type { FigurePixels } from './figureScale.ts';
+
+/** Chrome floating over a figure, which is not part of the picture. */
+const CHROME = '[data-figure="chrome"]';
+
+/** A figure's box on the page, in the coordinates a bounding box reports. */
+export interface FigureBounds {
+  /** Its left edge. */
+  left: number;
+  /** Its top edge. */
+  top: number;
+  /** Its width. */
+  width: number;
+  /** Its height. */
+  height: number;
+}
+
+/**
+ * The element a caller named.
+ * @param target - The `id` of the box the figure is mounted in, or the element
+ *   itself.
+ * @returns The element.
+ * @throws {Error} When no element on the page carries that `id`.
+ */
+export function figureElement(target: string | Element): Element {
+  if (typeof target !== 'string') return target;
+  // Escaped, because the ids React generates are not bare identifiers: a raw
+  // `#«r3»-panel` is not a selector any browser will parse.
+  const element = document.querySelector(`#${CSS.escape(target)}`);
+  if (element === null) {
+    throw new Error(`No element with the id ${target} to save.`);
+  }
+  return element;
+}
+
+/**
+ * The drawings inside it, in the order they are painted.
+ *
+ * What is collected is every `<svg>` that is part of the picture: one for a
+ * plain chart, sixteen for a pair grid. The glyphs of the controls floating
+ * over a figure are `<svg>` too, so anything inside an element marked as
+ * chrome is left behind — a cog saved into the middle of a scatter plot is the
+ * bug this exists to prevent. A drawing with no area is left behind as well,
+ * because a tab that is not showing is still in the document.
+ * @param element - The box the figure is mounted in.
+ * @returns The drawings.
+ */
+export function figureDrawings(element: Element): readonly SVGSVGElement[] {
+  if (element.tagName.toLowerCase() === 'svg') {
+    return [element as SVGSVGElement];
+  }
+  const drawings: SVGSVGElement[] = [];
+  for (const drawing of element.querySelectorAll('svg')) {
+    if (drawing.closest(CHROME) !== null) continue;
+    if (isNested(drawings, drawing)) continue;
+    const box = drawing.getBoundingClientRect();
+    if (box.width <= 0 || box.height <= 0) continue;
+    drawings.push(drawing);
+  }
+  return drawings;
+}
+
+/**
+ * The box every drawing of a figure fits in.
+ * @param drawings - The drawings, as they sit on the page.
+ * @returns The box, or one with no area where there are no drawings.
+ */
+export function figureBounds(drawings: readonly SVGSVGElement[]): FigureBounds {
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const drawing of drawings) {
+    const box = drawing.getBoundingClientRect();
+    if (box.left < left) left = box.left;
+    if (box.top < top) top = box.top;
+    if (box.right > right) right = box.right;
+    if (box.bottom > bottom) bottom = box.bottom;
+  }
+  if (!Number.isFinite(left) || !Number.isFinite(top)) {
+    return { left: 0, top: 0, width: 0, height: 0 };
+  }
+  return { left, top, width: right - left, height: bottom - top };
+}
+
+/**
+ * How big the saved figure would be at its own size, for a control that has to
+ * write the resulting file size before anybody presses save.
+ * @param target - The `id` of the box the figure is mounted in, or the element.
+ * @returns The size in pixels, or `null` where there is nothing to save.
+ */
+export function figureSize(target: string | Element): FigurePixels | null {
+  let bounds: FigureBounds;
+  try {
+    bounds = figureBounds(figureDrawings(figureElement(target)));
+  } catch {
+    return null;
+  }
+  if (bounds.width <= 0 || bounds.height <= 0) return null;
+  return {
+    width: Math.round(bounds.width),
+    height: Math.round(bounds.height),
+  };
+}
+
+/**
+ * Whether a drawing already sits inside one that was taken.
+ * @param taken - The drawings collected so far.
+ * @param drawing - The one being considered.
+ * @returns Whether it is already part of the figure.
+ */
+function isNested(
+  taken: readonly SVGSVGElement[],
+  drawing: SVGSVGElement,
+): boolean {
+  for (const other of taken) {
+    if (other.contains(drawing)) return true;
+  }
+  return false;
+}

package/src/download/core/index.ts

@@ -1,3 +1,31 @@
+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 { FigureBounds } from './figureTarget.ts';
+export {
+  figureBounds,
+  figureDrawings,
+  figureElement,
+  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

@@ -17,7 +17,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. */
@@ -242,6 +243,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

@@ -302,4 +302,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;
+}