react-cheminfo 0.76.0 → 0.78.0

package/lib/structure/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EACV,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/lib/structure/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAiB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAuB,CAAC;AAExD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAqB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA2B,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAqB,CAAC;AAGpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAiB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAuB,CAAC;AAExD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAqB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA2B,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA6B,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAqB,CAAC;AAOpD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",
@@ -27,6 +27,8 @@
     "./molecule3d": "./lib/molecule3d.js",
     "./molstar/*": "./lib/molstar/*/index.js",
     "./orbital": "./lib/orbital.js",
+    "./osiris": "./lib/osiris.js",
+    "./osiris-ui": "./lib/osiris-ui.js",
     "./pages": "./lib/pages.js",
     "./raman": "./lib/raman.js",
     "./server": "./lib/server.js",
@@ -78,6 +80,7 @@
     "cheminfo-font": "^1.28.0",
     "cheminfo-types": "^1.16.0",
     "convert-to-jcamp": "^7.0.1",
+    "crc-32": "^1.2.2",
     "intl-messageformat": "^11.2.15",
     "ir-spectrum": "^4.2.0",
     "jcampconverter": "^12.5.11",

package/src/card/core/cardAddress.ts

@@ -18,6 +18,13 @@ import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
 /** The parameter asking for the answer's card instead of the page. */
 export const CARD_PARAM = 'card';
 
+/**
+ * The parameter naming what a precise question asked, e.g. `only=formula`:
+ * the card then draws what the answer is about and only those facts. Without
+ * it the card draws everything it would.
+ */
+export const ONLY_PARAM = 'only';
+
 /**
  * Whether an address asks for a card.
  * @param search - The query string, with or without its leading `?`.
@@ -30,6 +37,29 @@ export function isCardAddress(search: string): boolean {
   return false;
 }
 
+/**
+ * The facts a card's `only` names, among those the site's card can single
+ * out. A name the card does not know is ignored, so a link written before a
+ * fact was renamed still opens, on the facts it still names.
+ * @param value - The value of `only` as the query holds it, comma-separated;
+ *   null or undefined when the address has none.
+ * @param known - Every fact the card can single out.
+ * @returns The facts named, each once, in the order written; empty when none
+ *   is known, and the card then draws everything.
+ */
+export function parseOnlyParam<Fact extends string>(
+  value: string | null | undefined,
+  known: readonly Fact[],
+): Fact[] {
+  const facts: Fact[] = [];
+  if (value == null) return facts;
+  for (const part of value.split(',')) {
+    const fact = known.find((candidate) => candidate === part.trim());
+    if (fact !== undefined && !facts.includes(fact)) facts.push(fact);
+  }
+  return facts;
+}
+
 /**
  * The address a card is at: `globalThis.location`, a `URL`, or any record of
  * the three parts.
@@ -62,7 +92,7 @@ export interface SitePageOptions {
   /**
    * A parameter the page at a given path does not read, though another page
    * of the site does: a tutorial step reads no InChI, the converter does.
-   * @default undefined - nothing beyond `card`, `embed`, `hide` and
+   * @default undefined - nothing beyond `card`, `only`, `embed`, `hide` and
    *   `cardParams` is left out
    */
   isCardOnly?: (key: string, pathname: string) => boolean;
@@ -70,7 +100,7 @@ export interface SitePageOptions {
 
 /**
  * The site's own page a card stands for, with its chrome: the card's address
- * without `card`, `embed`, `hide` and what only the card reads. Every other
+ * without `card`, `only`, `embed`, `hide` and what only the card reads. Every other
  * parameter is kept exactly as it was written, so the `+` of a charged atom
  * stays a plus and the commas of a list stay commas. This is the address an
  * answer's `link` names, and the one the card's Details button opens.
@@ -84,7 +114,13 @@ export function sitePageUrl(
   options: SitePageOptions = {},
 ): string {
   const { cardParams = [], literalPlus = true, isCardOnly } = options;
-  const dropped = new Set([CARD_PARAM, EMBED_PARAM, HIDE_PARAM, ...cardParams]);
+  const dropped = new Set([
+    CARD_PARAM,
+    ONLY_PARAM,
+    EMBED_PARAM,
+    HIDE_PARAM,
+    ...cardParams,
+  ]);
   const kept: string[] = [];
   const search = location.search.startsWith('?')
     ? location.search.slice(1)

package/src/card/core/cardPageUrl.ts

@@ -9,7 +9,7 @@ import type { QueryEntry } from '../../router/core/query.ts';
 import { formatQueryEntries } from '../../router/core/query.ts';
 import { EMBED_PARAM, HIDE_PARAM } from '../../share/core/config.ts';
 
-import { CARD_PARAM } from './cardAddress.ts';
+import { CARD_PARAM, ONLY_PARAM } from './cardAddress.ts';
 
 /** How {@link framedPageUrl} frames a page. */
 export interface FramedPageOptions {
@@ -30,7 +30,13 @@ export interface CardPageOptions extends FramedPageOptions {
    */
   card?: string;
   /**
-   * What only the card reads, written after `card` in the order given, e.g.
+   * The facts a precise question asked, written `only=formula,mass` after
+   * `card`: the card draws what the answer is about and only those.
+   * @default [] - the card draws everything
+   */
+  only?: readonly string[];
+  /**
+   * What only the card reads, written after `card` and `only` in the order given, e.g.
    * `{ rows: '10' }`. A value left `undefined` or empty is not written.
    * @default {}
    */
@@ -67,8 +73,9 @@ export function cardPageUrl(
   page: string,
   options: CardPageOptions = {},
 ): string {
-  const { card = '1', extra = {} } = options;
+  const { card = '1', only = [], extra = {} } = options;
   const entries: QueryEntry[] = [[CARD_PARAM, card]];
+  if (only.length > 0) entries.push([ONLY_PARAM, only.join(',')]);
   for (const [key, value] of Object.entries(extra)) {
     if (value !== undefined && value !== '') entries.push([key, value]);
   }

package/src/card/core/index.ts

@@ -1,5 +1,11 @@
 export type { CardLocation, SitePageOptions } from './cardAddress.ts';
-export { CARD_PARAM, isCardAddress, sitePageUrl } from './cardAddress.ts';
+export {
+  CARD_PARAM,
+  ONLY_PARAM,
+  isCardAddress,
+  parseOnlyParam,
+  sitePageUrl,
+} from './cardAddress.ts';
 export type { CardPageOptions, FramedPageOptions } from './cardPageUrl.ts';
 export { cardPageUrl, framedPageUrl } from './cardPageUrl.ts';
 export type { OpenPanel } from './panelRoom.ts';

package/src/credits/core/credits.ts

@@ -84,6 +84,46 @@ export const CREDITS = [
     description: 'the substructure and similarity search, inside SQLite.',
     license: 'MIT',
   },
+  {
+    id: 'openchemlib-search-wasm',
+    name: 'openchemlib-search-wasm',
+    href: 'https://github.com/cheminfo/openchemlib-search-wasm',
+    description:
+      'the functional-group keys of every structure, and the dictionary that names them.',
+    license: 'BSD-3-Clause',
+  },
+  {
+    id: 'chemcaption',
+    name: 'ChemCaption',
+    href: 'https://github.com/lamalab-org/chem-caption',
+    description:
+      'definitions of functional groups, adapted in the function-key dictionary.',
+    license: 'MIT',
+  },
+  {
+    id: 'accfg',
+    name: 'AccFG',
+    href: 'https://github.com/xuanliugit/AccFG',
+    description:
+      'definitions of functional groups, adapted in the function-key dictionary.',
+    license: 'MIT',
+  },
+  {
+    id: 'medchem',
+    name: 'medchem',
+    href: 'https://github.com/datamol-io/medchem',
+    description:
+      'definitions of functional groups, adapted in the function-key dictionary.',
+    license: 'Apache-2.0',
+  },
+  {
+    id: 'rdkit',
+    name: 'RDKit',
+    href: 'https://github.com/rdkit/rdkit',
+    description:
+      'definitions of functional groups, and the reference every key was checked against.',
+    license: 'BSD-3-Clause',
+  },
   {
     id: 'osiris-property-explorer',
     name: 'OSIRIS Property Explorer',

package/src/download/core/downloadFigure.ts

@@ -11,7 +11,7 @@
 import { downloadBlob } from './downloadBlob.ts';
 import { figurePng } from './figurePng.ts';
 import { defaultFigureScale } from './figureScale.ts';
-import type { FigureSvgOptions } from './figureSvg.ts';
+import type { FigureSvg, FigureSvgOptions } from './figureSvg.ts';
 import { FIGURE_SVG_TYPE, figureSvg } from './figureSvg.ts';
 import { sanitizeFileName } from './sanitizeFileName.ts';
 
@@ -67,3 +67,28 @@ export async function downloadFigure(
   const figure = figureSvg(target, { background });
   downloadBlob(await figurePng(figure, scale), `${name}.png`);
 }
+
+/**
+ * Save a figure its page wrote as an SVG document itself, rather than one
+ * copied off the page: a drawing whose file carries more than its picture.
+ * The SVG is saved as written, at the size it states; the PNG is painted from
+ * it at the multiple asked for.
+ * @param figure - The document, and its size in pixels of the page.
+ * @param options - Which file, at what multiple, and its name; a background
+ * is the document's own business.
+ * @throws {Error} When the browser cannot paint it.
+ */
+export async function downloadFigureSvg(
+  figure: FigureSvg,
+  options: Omit<DownloadFigureOptions, 'background'> = {},
+): Promise<void> {
+  const { format = 'png', fileName = DEFAULT_FILE_NAME } = options;
+  const name = sanitizeFileName(fileName, DEFAULT_FILE_NAME);
+  if (format === 'svg') {
+    const blob = new Blob([figure.markup], { type: FIGURE_SVG_TYPE });
+    downloadBlob(blob, `${name}.svg`);
+    return;
+  }
+  const scale = options.scale ?? defaultFigureScale(format);
+  downloadBlob(await figurePng(figure, scale), `${name}.png`);
+}

package/src/download/core/figureDpi.ts

@@ -0,0 +1,94 @@
+/**
+ * A figure's resolution stated in dots per inch.
+ *
+ * A pixel of the page is a ninety-sixth of an inch, by the definition of CSS,
+ * so every figure on screen already has a printed size, and the multiple it is
+ * painted at is a resolution in another unit: 1× is 96 dpi. A figure whose size
+ * on the page is the size it prints at — a structure drawn to a journal's bond
+ * length — is offered its resolution in dots per inch, which is what a journal
+ * asks for; any other figure is offered multiples of what the reader sees.
+ */
+
+import type { FigurePixels } from './figureScale.ts';
+import { figureScaleLabel } from './figureScale.ts';
+
+/** How the resolution of a figure is offered. */
+export type FigureResolutionUnit = 'multiple' | 'dpi';
+
+/** How many pixels of the page make an inch. */
+export const CSS_PIXELS_PER_INCH = 96;
+
+/**
+ * The dots per inch offered: a slide, a journal's halftone, its combination
+ * art, and its line art.
+ */
+export const FIGURE_DPIS: readonly number[] = [150, 300, 600, 1200];
+
+/** The dots per inch a figure with a printed size is saved at by default. */
+export const DEFAULT_FIGURE_DPI = 300;
+
+/** Centimetres in an inch. */
+const CENTIMETRES_PER_INCH = 2.54;
+
+/**
+ * The multiple a figure is painted at to reach this many dots per inch.
+ * @param dpi - Dots per inch.
+ * @returns The multiple of its size on the page.
+ */
+export function dpiScale(dpi: number): number {
+  return dpi / CSS_PIXELS_PER_INCH;
+}
+
+/**
+ * The dots per inch a figure painted at this multiple has, when it is printed
+ * at its size on the page.
+ * @param scale - The multiple of its size on the page.
+ * @returns Whole dots per inch.
+ */
+export function figureDpi(scale: number): number {
+  return Math.round(scale * CSS_PIXELS_PER_INCH);
+}
+
+/**
+ * The size a figure prints at.
+ * @param size - Its size on the page, in pixels.
+ * @returns Its width and height in centimetres.
+ */
+export function figureCentimetres(size: FigurePixels): FigurePixels {
+  const factor = CENTIMETRES_PER_INCH / CSS_PIXELS_PER_INCH;
+  return { width: size.width * factor, height: size.height * factor };
+}
+
+/**
+ * The size a figure prints at, written out to a tenth of a centimetre.
+ * @param size - Its size on the page, in pixels.
+ * @param language - The language the numbers are written in.
+ * @returns Its width and height in centimetres, as text: `8.5` or `8,5`.
+ */
+export function formatFigureCentimetres(
+  size: FigurePixels,
+  language: string,
+): { width: string; height: string } {
+  const printed = figureCentimetres(size);
+  const format = new Intl.NumberFormat(language, {
+    minimumFractionDigits: 1,
+    maximumFractionDigits: 1,
+  });
+  return {
+    width: format.format(printed.width),
+    height: format.format(printed.height),
+  };
+}
+
+/**
+ * What a resolution reads on a button: `2×`, or `300 dpi`.
+ * @param scale - The multiple of the figure's size on the page.
+ * @param unit - How the resolution is offered.
+ * @returns Its label.
+ */
+export function figureResolutionLabel(
+  scale: number,
+  unit: FigureResolutionUnit,
+): string {
+  return unit === 'dpi' ? `${figureDpi(scale)} dpi` : figureScaleLabel(scale);
+}

package/src/download/core/figurePng.ts

@@ -6,11 +6,16 @@
  * the figure that was read, and two drawing paths are two things to keep in
  * step. Scaling is the browser's own, so a figure saved at three times is
  * genuinely three times the detail rather than a stretched screenshot.
+ *
+ * The file states its resolution, so a document places it at the size the
+ * figure has on the page rather than at one pixel per point.
  */
 
+import { figureDpi } from './figureDpi.ts';
 import { DEFAULT_FIGURE_SCALE, figurePixels } from './figureScale.ts';
 import type { FigureSvg } from './figureSvg.ts';
 import { FIGURE_SVG_TYPE } from './figureSvg.ts';
+import { withPngDpi } from './pngDpi.ts';
 
 /** What a saved raster figure is. */
 export const FIGURE_PNG_TYPE = 'image/png';
@@ -19,7 +24,7 @@ export const FIGURE_PNG_TYPE = 'image/png';
  * The figure as a PNG.
  * @param figure - The figure, already copied off the page.
  * @param scale - How many pixels are painted per pixel on screen.
- * @returns The image.
+ * @returns The image, stating `96 × scale` dots per inch.
  * @throws {Error} When the browser cannot paint or encode it.
  */
 export async function figurePng(
@@ -38,7 +43,11 @@ export async function figurePng(
   }
   context.drawImage(drawing, 0, 0, pixels.width, pixels.height);
 
-  return encode(canvas);
+  const encoded = await encode(canvas);
+  const png = new Uint8Array(await encoded.arrayBuffer());
+  return new Blob([withPngDpi(png, figureDpi(scale))], {
+    type: FIGURE_PNG_TYPE,
+  });
 }
 
 /**

package/src/download/core/index.ts

@@ -4,8 +4,19 @@ export { copySvg } from './copySvg.ts';
 export { cssTokenNames, resolveCssTokens } from './cssTokens.ts';
 export { downloadBlob } from './downloadBlob.ts';
 export type { DownloadFigureOptions, FigureFormat } from './downloadFigure.ts';
-export { downloadFigure } from './downloadFigure.ts';
+export { downloadFigure, downloadFigureSvg } from './downloadFigure.ts';
 export { downloadText } from './downloadText.ts';
+export type { FigureResolutionUnit } from './figureDpi.ts';
+export {
+  CSS_PIXELS_PER_INCH,
+  DEFAULT_FIGURE_DPI,
+  FIGURE_DPIS,
+  dpiScale,
+  figureCentimetres,
+  figureDpi,
+  figureResolutionLabel,
+  formatFigureCentimetres,
+} from './figureDpi.ts';
 export type { FigureLayout } from './figureLayout.ts';
 export {
   FIGURE_COLUMN_WIDTH,
@@ -53,6 +64,7 @@ export {
   figurePaintings,
   figureSize,
 } from './figureTarget.ts';
+export { pngDpi, withPngDpi } from './pngDpi.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';
 
 export { drawingIn, stackDrawings } from './stackedDrawing.ts';

package/src/download/core/pngDpi.ts

@@ -0,0 +1,84 @@
+/**
+ * The resolution a PNG states, in its `pHYs` chunk.
+ *
+ * A browser writes none, and a word processor or a slide then places the
+ * picture as if it were 72 or 96 dpi — a figure painted for print arrives
+ * several times too large. Stated, it arrives at the size it was drawn.
+ */
+
+import CRC32 from 'crc-32';
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** Metres in an inch: `pHYs` counts pixels per metre. */
+const METRES_PER_INCH = 0.0254;
+
+/**
+ * A PNG stating a resolution, any resolution it stated before dropped.
+ * @param png - The PNG file's bytes.
+ * @param dpi - Dots per inch.
+ * @returns A new PNG file.
+ * @throws {Error} When the bytes are not a PNG.
+ */
+export function withPngDpi(
+  png: Uint8Array,
+  dpi: number,
+): Uint8Array<ArrayBuffer> {
+  for (let index = 0; index < SIGNATURE.length; index++) {
+    if (png[index] !== SIGNATURE[index]) throw new Error('Not a PNG file.');
+  }
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  const chunks: Uint8Array[] = [png.subarray(0, SIGNATURE.length)];
+  let offset = SIGNATURE.length;
+  while (offset + 8 <= png.length) {
+    const end = offset + 12 + view.getUint32(offset);
+    const type = chunkType(png, offset);
+    if (type !== 'pHYs') chunks.push(png.subarray(offset, end));
+    if (type === 'IHDR') chunks.push(physChunk(dpi));
+    offset = end;
+  }
+  let total = 0;
+  for (const chunk of chunks) total += chunk.length;
+  const result = new Uint8Array(total);
+  let position = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, position);
+    position += chunk.length;
+  }
+  return result;
+}
+
+/**
+ * The resolution a PNG states.
+ * @param png - The PNG file's bytes.
+ * @returns Whole dots per inch, or `undefined` when it states none.
+ */
+export function pngDpi(png: Uint8Array): number | undefined {
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  let offset = SIGNATURE.length;
+  while (offset + 8 <= png.length) {
+    if (chunkType(png, offset) === 'pHYs' && png[offset + 16] === 1) {
+      return Math.round(view.getUint32(offset + 8) * METRES_PER_INCH);
+    }
+    offset += 12 + view.getUint32(offset);
+  }
+  return undefined;
+}
+
+function chunkType(png: Uint8Array, offset: number): string {
+  return String.fromCodePoint(...png.subarray(offset + 4, offset + 8));
+}
+
+function physChunk(dpi: number): Uint8Array {
+  const chunk = new Uint8Array(21);
+  const view = new DataView(chunk.buffer);
+  view.setUint32(0, 9);
+  chunk.set([0x70, 0x48, 0x59, 0x73], 4);
+  const perMetre = Math.round(dpi / METRES_PER_INCH);
+  view.setUint32(8, perMetre);
+  view.setUint32(12, perMetre);
+  // The unit: 1 is the metre, 0 an aspect ratio with no size.
+  chunk[16] = 1;
+  view.setInt32(17, CRC32.buf(chunk.subarray(4, 17)));
+  return chunk;
+}

package/src/download/ui/FigureDownloadPanel.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement, ReactNode } from 'react';
 
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
 import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
@@ -7,18 +8,14 @@ import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
 import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
 import type { FigureNotice } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigureResolutionUnit } from '../core/figureDpi.ts';
 import { figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
-import {
-  figurePixels,
-  figureScaleFits,
-  figureScaleLabel,
-  formatFigurePixels,
-} from '../core/figureScale.ts';
 
 import type { FigureSizing } from './FigureSizeRows.tsx';
 import { FigureSizeRows } from './FigureSizeRows.tsx';
 import { hintOf } from './figureDownloadHint.ts';
+import { resolutionHelp, scaleChoices } from './resolutionChoices.ts';
 
 /** What {@link FigureDownloadPanel} is drawn from. */
 export interface FigureDownloadPanelProps {
@@ -30,6 +27,18 @@ export interface FigureDownloadPanelProps {
   scale: number;
   /** The multiples offered. */
   scales: readonly number[];
+  /**
+   * How the resolution reads: multiples of the figure on screen, or the dots
+   * per inch it has printed at its size on the page — 1× is 96 dpi.
+   * @default 'multiple'
+   */
+  unit?: FigureResolutionUnit;
+  /**
+   * Whether an SVG is saved at the size it states, whatever the resolution:
+   * the resolution then paints the PNG alone, and is not offered for the SVG.
+   * @default false
+   */
+  svgAtOwnSize?: boolean;
   /** 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. */
@@ -100,7 +109,9 @@ export function FigureDownloadPanel(
   const { title, format, scale, scales, size, failure, saving } = props;
   const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
   const { sizing, onCopy, notice = null, children } = props;
+  const { unit = 'multiple', svgAtOwnSize = false } = props;
   const t = useChromeT();
+  const language = useLanguage();
 
   // What the file is drawn at: the figure on screen, or the shape picked.
   const drawn =
@@ -109,13 +120,23 @@ export function FigureDownloadPanel(
       : figureLayoutSize(sizing.layout, size, sizing.custom ?? size);
 
   const painted = format === 'png' || rasterSvg;
+  const offerResolution = format === 'png' || !svgAtOwnSize;
 
   return (
     <OverlayPanel
       title={title}
-      width={PANEL_WIDTH}
+      width={unit === 'dpi' ? DPI_PANEL_WIDTH : PANEL_WIDTH}
       hint={hintOf(
-        { format, size: drawn, scale, failure, notice, rasterSvg },
+        {
+          format,
+          size: drawn,
+          scale,
+          failure,
+          notice,
+          rasterSvg,
+          unit,
+          language,
+        },
         t,
       )}
       actions={
@@ -152,20 +173,15 @@ export function FigureDownloadPanel(
       {sizing === undefined ? null : (
         <FigureSizeRows sizing={sizing} size={size} />
       )}
-      <OverlaySegmented
-        label={t('download.resolution')}
-        help={{
-          title: t('download.resolution'),
-          body: t('download.resolutionHelp'),
-          example: {
-            code: '2×',
-            note: t('download.resolutionExample'),
-          },
-        }}
-        value={String(scale)}
-        options={scaleChoices(scales, drawn, painted)}
-        onChange={(picked) => onScaleChange(Number(picked))}
-      />
+      {offerResolution ? (
+        <OverlaySegmented
+          label={t('download.resolution')}
+          help={resolutionHelp(unit, t)}
+          value={String(scale)}
+          options={scaleChoices(scales, drawn, painted, unit)}
+          onChange={(picked) => onScaleChange(Number(picked))}
+        />
+      ) : null}
     </OverlayPanel>
   );
 }
@@ -176,37 +192,11 @@ export function FigureDownloadPanel(
  */
 const PANEL_WIDTH = '27em';
 
+/** Wide enough for the four dots per inch on one row, `1200 dpi` last. */
+const DPI_PANEL_WIDTH = '33em';
+
 /** The two files a figure can leave the page as. */
 const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
   { value: 'png', label: 'PNG' },
   { value: 'svg', label: 'SVG' },
 ];
-
-/**
- * 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. An SVG
- * is not painted, so it has no such ceiling.
- * @param scales - The multiples the caller offers.
- * @param size - How big the figure is drawn for the file.
- * @param painted - Whether the file is painted into pixels.
- * @returns The choices, in the order offered.
- */
-function scaleChoices(
-  scales: readonly number[],
-  size: FigurePixels | null,
-  painted: boolean,
-): 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: painted && size !== null && !figureScaleFits(size, scale),
-    });
-  }
-  return choices;
-}