react-cheminfo 0.10.0 → 0.12.0

package/src/download/core/figureLegend.ts

@@ -0,0 +1,167 @@
+/**
+ * The key, painted into the file the figure leaves the page as.
+ *
+ * A legend is HTML — it is a filter the reader presses, not a drawing — so it
+ * is inside the chrome the export otherwise leaves behind. But a saved figure
+ * without its key says nothing: a reader looking at three colours has no way
+ * back to the three species. So the card is redrawn, once, in SVG, from the
+ * boxes the browser laid it out in.
+ *
+ * It is redrawn from measurements rather than re-derived from the styles that
+ * made it, so the copy cannot drift from the card on screen: whatever the
+ * browser did with the wrapping, the folding and the type, that is what the
+ * file gets.
+ */
+
+/** The card the entries sit on. */
+export interface FigureLegendCard {
+  /** Its width, in pixels. */
+  width: number;
+  /** Its height. */
+  height: number;
+  /**
+   * How round its corners are, in pixels.
+   * @default 0
+   */
+  radius?: number;
+  /**
+   * What is painted behind it.
+   * @default undefined — nothing is painted
+   */
+  background?: string;
+  /**
+   * The colour of the line round it.
+   * @default undefined — no line is drawn
+   */
+  border?: string;
+  /**
+   * How heavy that line is, in pixels.
+   * @default 1
+   */
+  borderWidth?: number;
+}
+
+/** One mark of the key, already an SVG of its own. */
+export interface FigureLegendMark {
+  /** The `<svg>` element as it was serialized, tokens already resolved. */
+  markup: string;
+  /** Its left edge, in pixels from the left of the card. */
+  x: number;
+  /** Its top edge, in pixels from the top of the card. */
+  y: number;
+}
+
+/** One run of words of the key. */
+export interface FigureLegendText {
+  /** What it says. */
+  text: string;
+  /** Its left edge, in pixels from the left of the card. */
+  x: number;
+  /** The middle of its line, in pixels from the top of the card. */
+  y: number;
+  /**
+   * Its colour.
+   * @default undefined — the document's own
+   */
+  color?: string;
+  /**
+   * Its size, in pixels.
+   * @default undefined — the document's own
+   */
+  fontSize?: number;
+  /**
+   * Its weight.
+   * @default undefined — the document's own
+   */
+  fontWeight?: string;
+}
+
+/** A key, measured off the page and ready to be painted. */
+export interface FigureLegendPrint {
+  /** The card itself. */
+  card: FigureLegendCard;
+  /** Its marks, in the order they are drawn. */
+  marks: readonly FigureLegendMark[];
+  /** Its words, in the order they are drawn. */
+  texts: readonly FigureLegendText[];
+}
+
+/**
+ * A key, as the markup that goes into the saved figure.
+ * @param print - The card, its marks and its words. See {@link FigureLegendPrint}.
+ * @returns The markup, in the card's own coordinates: the caller places it.
+ */
+export function figureLegendMarkup(print: FigureLegendPrint): string {
+  const { card, marks, texts } = print;
+  const parts: string[] = [groundMarkup(card)];
+
+  for (const mark of marks) {
+    parts.push(
+      `<g transform="translate(${round(mark.x)} ${round(mark.y)})">${mark.markup}</g>`,
+    );
+  }
+  for (const run of texts) parts.push(textMarkup(run));
+
+  return parts.join('');
+}
+
+/**
+ * The card the entries are written on.
+ * @param card - Its measurements. See {@link FigureLegendCard}.
+ * @returns Its markup, or nothing when the card has neither ground nor line.
+ */
+function groundMarkup(card: FigureLegendCard): string {
+  const { width, height, radius = 0, background, border } = card;
+  if (background === undefined && border === undefined) return '';
+
+  const borderWidth = card.borderWidth ?? 1;
+  // Drawn inside its own line, which a stroke otherwise straddles: half of it
+  // would fall outside the card and be clipped by the figure's edge.
+  const inset = border === undefined ? 0 : borderWidth / 2;
+  const line =
+    border === undefined
+      ? ''
+      : ` stroke="${attribute(border)}" stroke-width="${round(borderWidth)}"`;
+
+  return (
+    `<rect x="${round(inset)}" y="${round(inset)}"` +
+    ` width="${round(Math.max(0, width - inset * 2))}"` +
+    ` height="${round(Math.max(0, height - inset * 2))}"` +
+    ` rx="${round(radius)}" fill="${attribute(background ?? 'none')}"${line}/>`
+  );
+}
+
+/**
+ * One run of words, set on the middle of the line it was laid out on.
+ * @param run - The words and where they sit. See {@link FigureLegendText}.
+ * @returns Its markup, or nothing when it says nothing.
+ */
+function textMarkup(run: FigureLegendText): string {
+  if (run.text === '') return '';
+
+  const fill = run.color === undefined ? '' : ` fill="${attribute(run.color)}"`;
+  const size =
+    run.fontSize === undefined ? '' : ` font-size="${round(run.fontSize)}px"`;
+  const weight =
+    run.fontWeight === undefined
+      ? ''
+      : ` font-weight="${attribute(run.fontWeight)}"`;
+
+  return (
+    `<text x="${round(run.x)}" y="${round(run.y)}" dominant-baseline="central"` +
+    `${fill}${size}${weight}>${text(run.text)}</text>`
+  );
+}
+
+function attribute(value: string): string {
+  return text(value).replaceAll('"', '&quot;');
+}
+
+function text(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/download/core/figureSvg.ts

@@ -8,9 +8,16 @@
  */
 
 import { cssTokenNames, resolveCssTokens } from './cssTokens.ts';
+import type { FigureLegendMark, FigureLegendText } from './figureLegend.ts';
+import { figureLegendMarkup } from './figureLegend.ts';
 import type { FigurePiece } from './figureSvgDocument.ts';
 import { figureSvgDocument } from './figureSvgDocument.ts';
-import { figureBounds, figureDrawings, figureElement } from './figureTarget.ts';
+import {
+  figureBounds,
+  figureDrawings,
+  figureElement,
+  figureLegends,
+} from './figureTarget.ts';
 
 /** How the figure is copied. */
 export interface FigureSvgOptions {
@@ -69,6 +76,17 @@ export function figureSvg(
     });
   }
 
+  for (const legend of figureLegends(element)) {
+    const box = legend.getBoundingClientRect();
+    if (box.width <= 0 || box.height <= 0) continue;
+    pieces.push({
+      markup: legendMarkup(legend, box),
+      x: box.left - bounds.left,
+      y: box.top - bounds.top,
+      kind: 'legend',
+    });
+  }
+
   const styles = window.getComputedStyle(element);
   const markup = figureSvgDocument(pieces, {
     width: bounds.width,
@@ -85,6 +103,68 @@ export function figureSvg(
   };
 }
 
+/**
+ * One key, measured off the page and painted as SVG.
+ *
+ * Everything is read from where the browser put it — the card's own ground and
+ * corner, each mark's box, each run of words and the type it is set in — so
+ * the copy in the file is the card the reader was looking at, folding and all.
+ * The ground is painted at full strength however faint the card had gone on
+ * screen: a key that fades when the pointer leaves the figure is a property of
+ * pointing at it, not of the figure.
+ * @param legend - The card, as it sits on the page.
+ * @param box - Its box, so the pieces inside it can be placed against it.
+ * @returns Its markup, in the card's own coordinates.
+ */
+function legendMarkup(legend: Element, box: DOMRect): string {
+  const ground = legend.firstElementChild;
+  const styles = ground === null ? undefined : window.getComputedStyle(ground);
+
+  const marks: FigureLegendMark[] = [];
+  for (const mark of legend.querySelectorAll('svg')) {
+    const at = mark.getBoundingClientRect();
+    marks.push({
+      markup: drawingMarkup(mark),
+      x: at.left - box.left,
+      y: at.top - box.top,
+    });
+  }
+
+  const texts: FigureLegendText[] = [];
+  for (const run of legend.querySelectorAll('*')) {
+    if (run.firstElementChild !== null) continue;
+    const words = run.textContent?.trim() ?? '';
+    if (words === '') continue;
+    const at = run.getBoundingClientRect();
+    const type = window.getComputedStyle(run);
+    texts.push({
+      text: words,
+      x: at.left - box.left,
+      y: at.top - box.top + at.height / 2,
+      color: type.color,
+      fontSize: Number.parseFloat(type.fontSize),
+      fontWeight: type.fontWeight,
+    });
+  }
+
+  return figureLegendMarkup({
+    card: {
+      width: box.width,
+      height: box.height,
+      radius:
+        styles === undefined
+          ? 0
+          : Number.parseFloat(styles.borderTopLeftRadius),
+      background: styles?.backgroundColor,
+      border: styles?.borderTopColor,
+      borderWidth:
+        styles === undefined ? 1 : Number.parseFloat(styles.borderTopWidth),
+    },
+    marks,
+    texts,
+  });
+}
+
 /**
  * One drawing, serialized with every token it names written out.
  *

package/src/download/core/figureSvgDocument.ts

@@ -12,14 +12,21 @@
  * that decides what the file *is* can be read without a DOM to run it in.
  */
 
-/** One drawing on the page, and where it sits inside the saved figure. */
+/** One piece of the page, and where it sits inside the saved figure. */
 export interface FigurePiece {
-  /** The `<svg>` element as it was serialized, tokens already resolved. */
+  /** The markup, tokens already resolved. */
   markup: string;
   /** Its left edge, in pixels from the left of the saved figure. */
   x: number;
   /** Its top edge, in pixels from the top of the saved figure. */
   y: number;
+  /**
+   * What it is. Written into the file, so a reader — a test, or somebody
+   * editing the figure afterwards — can tell the drawings from the key that
+   * was painted over them.
+   * @default 'drawing'
+   */
+  kind?: 'drawing' | 'legend';
 }
 
 /** How the file around the drawings is written. */
@@ -71,7 +78,10 @@ export function figureSvgDocument(
       ? ''
       : `<rect width="100%" height="100%" fill="${escapeAttribute(background)}"/>`;
   for (const piece of pieces) {
-    inside += `<g transform="translate(${round(piece.x)} ${round(piece.y)})">${piece.markup}</g>`;
+    const kind = piece.kind ?? 'drawing';
+    inside +=
+      `<g data-figure="${kind}" transform="translate(${round(piece.x)} ${round(piece.y)})">` +
+      `${piece.markup}</g>`;
   }
 
   return (

package/src/download/core/figureTarget.ts

@@ -13,6 +13,9 @@ import type { FigurePixels } from './figureScale.ts';
 /** Chrome floating over a figure, which is not part of the picture. */
 const CHROME = '[data-figure="chrome"]';
 
+/** A key floating over a figure, which is. */
+const LEGEND = '[data-figure="legend"]';
+
 /** A figure's box on the page, in the coordinates a bounding box reports. */
 export interface FigureBounds {
   /** Its left edge. */
@@ -70,6 +73,24 @@ export function figureDrawings(element: Element): readonly SVGSVGElement[] {
   return drawings;
 }
 
+/**
+ * The keys inside it.
+ *
+ * A key is chrome — it is a filter the reader presses — and is therefore not
+ * among the drawings, but it is still part of the picture: a saved figure
+ * whose colours stand for nothing is not a figure. So it is collected
+ * separately, to be redrawn over the drawings rather than copied with them.
+ * @param element - The box the figure is mounted in.
+ * @returns The keys, in the order they are painted.
+ */
+export function figureLegends(element: Element): readonly Element[] {
+  const legends: Element[] = [];
+  for (const legend of element.querySelectorAll(LEGEND)) {
+    legends.push(legend);
+  }
+  return legends;
+}
+
 /**
  * The box every drawing of a figure fits in.
  * @param drawings - The drawings, as they sit on the page.

package/src/download/core/index.ts

@@ -21,11 +21,19 @@ export type {
   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/FigureDownloadPanel.tsx

@@ -36,6 +36,12 @@ export interface FigureDownloadPanelProps {
   onScaleChange: (scale: number) => void;
   /** Called when they press save. */
   onSave: () => void;
+  /**
+   * Whether the SVG holds a rendered picture rather than vector drawings, as
+   * for a WebGL scene: its resolution then applies, and the hint says so.
+   * @default false
+   */
+  rasterSvg?: boolean;
 }
 
 /**
@@ -59,14 +65,14 @@ export function FigureDownloadPanel(
   props: FigureDownloadPanelProps,
 ): ReactElement {
   const { title, format, scale, scales, size, failure, saving } = props;
-  const { onFormatChange, onScaleChange, onSave } = props;
+  const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
 
-  const vector = format === 'svg';
+  const vector = format === 'svg' && !rasterSvg;
 
   return (
     <OverlayPanel
       title={title}
-      hint={hintOf(format, size, scale, failure)}
+      hint={hintOf(format, size, scale, failure, rasterSvg)}
       actions={
         <OverlayAction
           text="Save"
@@ -148,6 +154,7 @@ function scaleChoices(
  * @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.
+ * @param rasterSvg - Whether the SVG embeds a rendered picture.
  * @returns The sentence.
  */
 function hintOf(
@@ -155,9 +162,13 @@ function hintOf(
   size: FigurePixels | null,
   scale: number,
   failure: string | null,
+  rasterSvg: boolean,
 ): string {
   if (failure !== null) return failure;
   if (size === null) return 'There is no figure on the page to save yet.';
+  if (format === 'svg' && rasterSvg) {
+    return `An SVG holding a picture of ${formatFigurePixels(figurePixels(size, scale))}: a 3D scene has no vector form.`;
+  }
   if (format === 'svg') {
     return `An SVG stays sharp at any size, so the resolution does not apply. Drawn ${formatFigurePixels(size)}.`;
   }

package/src/ecosystem/core/groups.ts

@@ -0,0 +1,59 @@
+/**
+ * The topics the family's tools are gathered under.
+ *
+ * A single grid of tiles tells a visitor nothing about which of them is for
+ * a first-year student and which is for a research project. The groups are the
+ * answer, and they read as a progression: the chemistry a course opens with,
+ * then the molecule itself, then what was measured of it, then the work only a
+ * project needs — and last the three tools that are not chemistry at all.
+ */
+
+/** The topics, in the order they are written. */
+export type SiteGroupId =
+  'basics' | 'structures' | 'spectra' | 'research' | 'computing';
+
+/** One topic the family's tools are gathered under. */
+export interface SiteGroup {
+  /** The identifier a site names in its `group`. */
+  id: SiteGroupId;
+  /** The heading the group is written under. */
+  label: string;
+  /**
+   * The line under the heading. It says who the group is for rather than what
+   * it contains — the tiles already say that, one tagline each.
+   */
+  blurb: string;
+}
+
+/**
+ * Every topic, in the order a menu and a footer write them. A site names one of
+ * these in its `group`, and that is the only place the order of the menu is
+ * decided; within a topic, sites keep the order they are declared in.
+ */
+export const SITE_GROUPS: readonly SiteGroup[] = [
+  {
+    id: 'basics',
+    label: 'Chemistry basics',
+    blurb: 'Where a course starts, and what you go back to.',
+  },
+  {
+    id: 'structures',
+    label: 'Structures & notation',
+    blurb: 'Draw a molecule, convert it between notations, see it in space.',
+  },
+  {
+    id: 'spectra',
+    label: 'Spectra',
+    blurb: 'Process a measurement, and work back to the structure behind it.',
+  },
+  {
+    id: 'research',
+    label: 'Research & data',
+    blurb: 'Specialised work: real datasets, and molecules nobody has made.',
+  },
+  {
+    id: 'computing',
+    label: 'Computing & teaching',
+    blurb: 'Around the chemistry: build a course, typeset it, parse it.',
+  },
+];

package/src/ecosystem/core/index.ts

@@ -1,5 +1,14 @@
-export { renderEcosystemLinksHtml } from './links.ts';
-export { findSiteByHost, siteById, siteDisplayName } from './lookup.ts';
+export type { SiteGroup, SiteGroupId } from './groups.ts';
+export { SITE_GROUPS } from './groups.ts';
+export type { GroupedSites } from './lookup.ts';
+export {
+  findSiteByHost,
+  groupedSites,
+  siteById,
+  siteDisplayName,
+} from './lookup.ts';
+export type { SiteNameColors, SiteNameColorsOptions } from './nameColors.ts';
+export { siteNameColors } from './nameColors.ts';
 export type {
   EcosystemSite,
   SiteId,
@@ -7,4 +16,4 @@ export type {
   SiteName,
 } from './sites.ts';
 export { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
-export { siteThemeColor, siteTokensCss } from './tokens.ts';
+export { siteTokensCss } from './tokens.ts';

package/src/ecosystem/core/lookup.ts

@@ -1,6 +1,44 @@
+import type { SiteGroup, SiteGroupId } from './groups.ts';
+import { SITE_GROUPS } from './groups.ts';
 import type { EcosystemSite, SiteId } from './sites.ts';
 import { ECOSYSTEM_SITES } from './sites.ts';
 
+/** One topic and the sites written under it. */
+export interface GroupedSites {
+  /** The topic. */
+  group: SiteGroup;
+  /** Its sites, in the order they are declared. */
+  sites: EcosystemSite[];
+}
+
+/**
+ * The family gathered under its topics, which is how a menu and a footer list
+ * it. A topic nobody is written under is left out rather than headed over an
+ * empty space.
+ * @returns Each topic that has sites, in the order the topics are declared.
+ */
+export function groupedSites(): GroupedSites[] {
+  const grouped: GroupedSites[] = [];
+  for (const group of SITE_GROUPS) {
+    const sites = sitesInGroup(group.id);
+    if (sites.length > 0) grouped.push({ group, sites });
+  }
+  return grouped;
+}
+
+/**
+ * The sites written under one topic.
+ * @param id - The topic being asked for.
+ * @returns Its sites, in the order they are declared.
+ */
+export function sitesInGroup(id: SiteGroupId): EcosystemSite[] {
+  const sites: EcosystemSite[] = [];
+  for (const site of ECOSYSTEM_SITES) {
+    if (site.group === id) sites.push(site);
+  }
+  return sites;
+}
+
 /**
  * One site of the family, by the identifier its entry carries.
  * @param id - The site being asked for.

package/src/ecosystem/core/nameColors.ts

@@ -0,0 +1,50 @@
+import { FAMILY_TOKEN_VALUES, TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import type { EcosystemSite } from './types.ts';
+
+/** The colour each half of a site's name is written in. */
+export interface SiteNameColors {
+  /** The first half of the name. */
+  lead: string;
+  /** The second half of the name. */
+  alt: string;
+  /** The faint dot between an address-shaped name's two halves. */
+  dot: string;
+}
+
+/** Where the family's own colours in a name come from. */
+export interface SiteNameColorsOptions {
+  /**
+   * `tokens` reads the family's ink and faint grey from the page, falling back
+   * to their values; `literal` writes the values out, for a document that
+   * loads no stylesheet of ours, such as a social card.
+   * @default 'tokens'
+   */
+  colors?: 'tokens' | 'literal';
+}
+
+/**
+ * How a site's name is coloured, so a wordmark in a header, a tile in a menu
+ * and a social card never write the same name two different ways.
+ *
+ * A site whose own logo leaves one half in black says so with `name.ink`, and
+ * the colour it owns then falls on the other half rather than being spent on
+ * both.
+ * @param site - The site being named.
+ * @param options - Whether the family's colours are read from the page.
+ * @returns The colour of each half, and of the dot between them.
+ */
+export function siteNameColors(
+  site: EcosystemSite,
+  options: SiteNameColorsOptions = {},
+): SiteNameColors {
+  const literal = options.colors === 'literal';
+  const ink = literal ? FAMILY_TOKEN_VALUES['--text'] : TOKEN.text;
+  const { ink: inkHalf } = site.name;
+  return {
+    lead: inkHalf === 'lead' ? ink : site.brand,
+    alt:
+      inkHalf === 'alt' ? ink : inkHalf === 'lead' ? site.brand : site.brandAlt,
+    dot: literal ? FAMILY_TOKEN_VALUES['--text-faint'] : TOKEN.textFaint,
+  };
+}