react-cheminfo 0.10.0 → 0.11.0

package/lib/scatter3d/ui/useOrbitDrag.js

@@ -0,0 +1,129 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { capturePointer, dropFrame, modifierMode, scheduleFrame, surfacePosition, } from "../../scatter/ui/lassoGesture.js";
+import { orbitByDrag } from "../core/orbitCamera.js";
+/**
+ * Turning the box with the pointer.
+ *
+ * It is the lasso's twin and is built the same way — the pointer is captured
+ * on the way down so a drag that wanders off the figure keeps turning it, all
+ * three ways a capture can end lead to one function, and moves are coalesced
+ * to one a frame because a pointer emits many per frame and each one that
+ * reaches the caller repaints every dot and every face.
+ *
+ * A press that goes nowhere is a tap rather than a turn of no degrees, because
+ * nobody presses a mouse button without moving it a pixel or two and a reader
+ * who meant to pick a sample must not have to hold their hand still to do it.
+ * @param options - See {@link OrbitDragOptions}.
+ * @returns The drag. See {@link OrbitDrag}.
+ */
+export function useOrbitDrag(options) {
+    const { enabled = true, onOrbit, onTap, onMove, onLeave, mode: restingMode = 'replace', } = options;
+    const pointerRef = useRef(null);
+    const lastRef = useRef({ x: 0, y: 0 });
+    const travelRef = useRef(0);
+    const frameRef = useRef(null);
+    const pendingRef = useRef(null);
+    const [turning, setTurning] = useState(false);
+    const flush = useCallback(() => {
+        frameRef.current = null;
+        const next = pendingRef.current;
+        pendingRef.current = null;
+        if (next === null)
+            return;
+        if (pointerRef.current === null) {
+            onMove?.(next.x, next.y);
+            return;
+        }
+        onOrbit((camera) => orbitByDrag(camera, next.dx, next.dy));
+    }, [onMove, onOrbit]);
+    const end = useCallback((event, commit) => {
+        if (event.pointerId !== pointerRef.current)
+            return;
+        pointerRef.current = null;
+        pendingRef.current = null;
+        dropFrame(frameRef);
+        setTurning(false);
+        if (!commit || travelRef.current > TAP_SLACK)
+            return;
+        const at = surfacePosition(event, 0, 0);
+        onTap?.(at.x, at.y, modifierMode(event, restingMode));
+    }, [onTap, restingMode]);
+    const handleDown = useCallback((event) => {
+        if (pointerRef.current !== null || event.button > 0)
+            return;
+        pointerRef.current = event.pointerId;
+        lastRef.current = { x: event.clientX, y: event.clientY };
+        travelRef.current = 0;
+        setTurning(true);
+        capturePointer(event);
+    }, []);
+    const handleMove = useCallback((event) => {
+        const active = pointerRef.current;
+        if (active === null) {
+            const at = surfacePosition(event, 0, 0);
+            pendingRef.current = { x: at.x, y: at.y, dx: 0, dy: 0 };
+            scheduleFrame(frameRef, flush);
+            return;
+        }
+        if (event.pointerId !== active)
+            return;
+        const last = lastRef.current;
+        const dx = event.clientX - last.x;
+        const dy = event.clientY - last.y;
+        lastRef.current = { x: event.clientX, y: event.clientY };
+        travelRef.current += Math.abs(dx) + Math.abs(dy);
+        if (!enabled)
+            return;
+        const waiting = pendingRef.current;
+        pendingRef.current = {
+            x: 0,
+            y: 0,
+            dx: (waiting?.dx ?? 0) + dx,
+            dy: (waiting?.dy ?? 0) + dy,
+        };
+        scheduleFrame(frameRef, flush);
+    }, [enabled, flush]);
+    const handleUp = useCallback((event) => {
+        end(event, true);
+    }, [end]);
+    const handleAbandon = useCallback((event) => {
+        end(event, false);
+    }, [end]);
+    const handleLeave = useCallback(() => {
+        if (pointerRef.current !== null)
+            return;
+        pendingRef.current = null;
+        onLeave?.();
+    }, [onLeave]);
+    const surface = useMemo(() => ({
+        onPointerDown: handleDown,
+        onPointerMove: handleMove,
+        onPointerUp: handleUp,
+        onPointerCancel: handleAbandon,
+        onLostPointerCapture: handleAbandon,
+        onPointerLeave: handleLeave,
+        style: {
+            cursor: enabled ? (turning ? 'grabbing' : 'grab') : 'default',
+            touchAction: 'none',
+        },
+    }), [
+        enabled,
+        handleAbandon,
+        handleDown,
+        handleLeave,
+        handleMove,
+        handleUp,
+        turning,
+    ]);
+    return { turning, surface };
+}
+/**
+ * How far a press may travel and still be a tap, in pixels of total travel.
+ *
+ * Generous on purpose: a mouse moves a pixel or two under the click of its own
+ * button, and a finger moves rather more, so a stricter number turns "pick
+ * this sample" into "turn the box by nothing at all" for anybody whose hand is
+ * not steady.
+ */
+const TAP_SLACK = 5;
+//# sourceMappingURL=useOrbitDrag.js.map

package/lib/scatter3d/ui/useOrbitDrag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOrbitDrag.js","sourceRoot":"","sources":["../../../src/scatter3d/ui/useOrbitDrag.ts"],"names":[],"mappings":"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"}

package/lib/ui.d.ts

@@ -18,6 +18,7 @@ export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
 export * from './projection/ui/index.ts';
 export * from './scatter/ui/index.ts';
+export * from './scatter3d/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
 export * from './spectra/ui/index.ts';

package/lib/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/lib/ui.js

@@ -18,6 +18,7 @@ export * from "./pedagogy/ui/index.js";
 export * from "./periodic/ui/index.js";
 export * from "./projection/ui/index.js";
 export * from "./scatter/ui/index.js";
+export * from "./scatter3d/ui/index.js";
 export * from "./share/ui/index.js";
 export * from "./shared/ui/index.js";
 export * from "./spectra/ui/index.js";

package/lib/ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "Assembled React components shared by the cheminfo sites: a Cite button and an ecosystem menu",
   "author": "Luc Patiny",

package/src/chrome/ui/NavLink.tsx

@@ -30,24 +30,26 @@ export interface NavLinkProps {
  */
 export function NavLink(props: NavLinkProps): ReactElement {
   const { item, active = false, className } = props;
-  const { href, external = false, onSelect, title } = item;
+  const { href, external = false, onSelect, title, disabled = false } = item;
 
   const classes = [
     'nav-link',
     active ? 'nav-link--active' : null,
+    disabled ? 'nav-link--disabled' : null,
     className ?? null,
   ]
     .filter((part) => part !== null)
     .join(' ');
 
-  if (href === undefined) {
+  if (href === undefined || disabled) {
     return (
       <button
         type="button"
         className={classes}
         title={title}
         aria-label={title}
-        onClick={onSelect}
+        disabled={disabled}
+        onClick={disabled ? undefined : onSelect}
       >
         <NavLinkBody item={item} />
       </button>

package/src/chrome/ui/SiteFooter.tsx

@@ -29,6 +29,14 @@ export interface SiteFooterProps {
    * @default undefined
    */
   children?: ReactNode;
+  /**
+   * How wide the footer's contents run, read exactly as `SiteHeader`'s: `page`
+   * caps them at `--page-max`, `full` runs them to both edges. A site sets the
+   * two alike, or its chrome is capped at one end of the page and not at the
+   * other.
+   * @default 'page'
+   */
+  width?: 'page' | 'full';
 }
 
 /**
@@ -46,13 +54,14 @@ export function SiteFooter(props: SiteFooterProps): ReactElement | null {
     heading,
     embedded = false,
     children,
+    width = 'page',
   } = props;
 
   if (embedded) return null;
 
   return (
     <footer className="app-footer no-print">
-      <div className="app-footer__inner">
+      <div className={INNER_CLASS[width]}>
         <EcosystemLinks
           currentSiteId={siteId}
           layout={layout}
@@ -63,3 +72,9 @@ export function SiteFooter(props: SiteFooterProps): ReactElement | null {
     </footer>
   );
 }
+
+/** The two widths the footer's contents run at, as the classes that set them. */
+const INNER_CLASS = {
+  page: 'app-footer__inner',
+  full: 'app-footer__inner app-footer__inner--full',
+} as const;

package/src/chrome/ui/SiteHeader.tsx

@@ -55,6 +55,17 @@ export interface SiteHeaderProps {
    * @default 28
    */
   markSize?: number;
+  /**
+   * How wide the bar's contents run.
+   *
+   * `page` caps them at `--page-max` and centres them, so the brand sits over
+   * the first word of a page that is capped the same way — which is what a
+   * site of reading matter wants. `full` runs them to both edges, for a tool
+   * that fills the window: there the cap leaves the brand floating inwards
+   * with the tool running past it on both sides, and reads as a fault.
+   * @default 'page'
+   */
+  width?: 'page' | 'full';
 }
 
 /**
@@ -76,6 +87,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
     homeHref = '/',
     onHome,
     markSize = 28,
+    width = 'page',
   } = props;
 
   if (embedded) return null;
@@ -84,7 +96,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
 
   return (
     <header className="app-header no-print">
-      <div className="app-header__inner">
+      <div className={INNER_CLASS[width]}>
         <a
           className="brand"
           href={homeHref}
@@ -117,3 +129,9 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
     </header>
   );
 }
+
+/** The two widths the bar's contents run at, as the classes that set them. */
+const INNER_CLASS = {
+  page: 'app-header__inner',
+  full: 'app-header__inner app-header__inner--full',
+} as const;

package/src/chrome/ui/navItem.ts

@@ -47,6 +47,18 @@ export interface NavItem {
    * @default undefined
    */
   after?: ReactNode;
+  /**
+   * Whether the page cannot be opened yet — a view that needs data the site
+   * has not been given.
+   *
+   * It is greyed rather than left out, because a bar that grows entries as a
+   * reader works is a bar they have to keep re-reading, and a page they cannot
+   * see is a page they conclude the site does not have. `title` is where the
+   * reason goes; without one the entry is dead and says nothing, which is the
+   * one thing worse than leaving it out.
+   * @default false
+   */
+  disabled?: boolean;
 }
 
 /**

package/src/core.ts

@@ -15,6 +15,7 @@ export * from './periodic/core/index.ts';
 export * from './projection/core/index.ts';
 export * from './router/core/index.ts';
 export * from './scatter/core/index.ts';
+export * from './scatter3d/core/index.ts';
 export * from './seo/core/index.ts';
 export * from './share/core/index.ts';
 // The deck format and its navigation are framework-free, so a backend can read

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.