react-cheminfo 0.9.0 → 0.11.0

package/src/color/ui/ColorScaleSelect.tsx

@@ -0,0 +1,252 @@
+import {
+  Button,
+  Menu,
+  MenuDivider,
+  MenuItem,
+  PopoverNext,
+} from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+import type { ColorScale } from '../core/interpolate.ts';
+import { formatColorScale, resolveColorScale } from '../core/scaleText.ts';
+import type { ColorScaleKind } from '../core/scales.ts';
+import { COLOR_SCALES, COLOR_SCALE_KIND_LABELS } from '../core/scales.ts';
+
+import { ColorScaleBar } from './ColorScaleBar.tsx';
+import { ColorScaleEditor } from './ColorScaleEditor.tsx';
+
+const BUTTON_BAR_WIDTH = 72;
+
+/** What {@link ColorScaleSelect} chooses. */
+export interface ColorScaleSelectProps {
+  /**
+   * The scale in force: the id of one of {@link COLOR_SCALES}, or a scale of
+   * the reader's own as `formatColorScale` writes it.
+   */
+  value: string;
+  /** Called with the text of the scale that was chosen. */
+  onChange: (value: string) => void;
+  /**
+   * Caption written above the button.
+   * @default '' — no caption
+   */
+  label?: string;
+  /**
+   * Whether the menu offers a scale of the reader's own.
+   * @default true
+   */
+  allowCustom?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the button, for the end-to-end tests.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The picker a quantity's colours are chosen with: every scale drawn as itself,
+ * and a way to build one.
+ *
+ * A ramp is picked by looking at it rather than by reading its name, so the
+ * menu is the strips; the reader who needs the rainbow their course used, or
+ * the grey a photocopier will keep, finds it without knowing what viridis is.
+ * @param props - See {@link ColorScaleSelectProps}.
+ * @returns The button, and the menu it opens.
+ */
+export function ColorScaleSelect(props: ColorScaleSelectProps): ReactElement {
+  const { value, onChange, label = '', allowCustom = true, testId } = props;
+  const [isOpen, setOpen] = useState(false);
+  const [isEditing, setEditing] = useState(false);
+  const resolved = resolveColorScale(value);
+
+  const content = isEditing ? (
+    <div>
+      <div style={EDITOR_HEADER_STYLE}>
+        <Button
+          icon="chevron-left"
+          variant="minimal"
+          size="small"
+          text="Scales"
+          onClick={() => {
+            setEditing(false);
+          }}
+        />
+        <Button
+          size="small"
+          text="Done"
+          onClick={() => {
+            setEditing(false);
+            setOpen(false);
+          }}
+        />
+      </div>
+      <ColorScaleEditor
+        value={resolved.scale}
+        onChange={(scale) => {
+          onChange(formatColorScale(scale));
+        }}
+      />
+    </div>
+  ) : (
+    <Menu style={MENU_STYLE}>
+      {COLOR_SCALES.map((entry, index) => (
+        <ScaleEntry
+          key={entry.id}
+          id={entry.id}
+          label={entry.label}
+          kind={entry.kind}
+          description={entry.description}
+          previous={COLOR_SCALES[index - 1]?.kind}
+          selected={entry.id === resolved.id}
+          onChange={onChange}
+        />
+      ))}
+      {allowCustom ? (
+        <>
+          <MenuDivider />
+          <MenuItem
+            icon="edit"
+            text="Custom…"
+            label={resolved.id === null ? 'in use' : undefined}
+            shouldDismissPopover={false}
+            onClick={() => {
+              setEditing(true);
+            }}
+          />
+        </>
+      ) : null}
+    </Menu>
+  );
+
+  return (
+    <label style={FIELD_STYLE}>
+      {label === '' ? null : <span style={CAPTION_STYLE}>{label}</span>}
+      <PopoverNext
+        // A fade, like the pickers a site puts beside this one: the default
+        // grows the panel from a third of its size over about a second, which
+        // reads as the row behaving differently control by control.
+        animation="minimal"
+        arrow={false}
+        placement="bottom-start"
+        isOpen={isOpen}
+        content={content}
+        onInteraction={(next) => {
+          setOpen(next);
+          if (!next) setEditing(false);
+        }}
+      >
+        <Button
+          alignText="start"
+          aria-label={label === '' ? 'Colour scale' : label}
+          data-testid={testId}
+          endIcon="caret-down"
+          fill
+          text={
+            <span style={BUTTON_TEXT_STYLE}>
+              <span>{resolved.label}</span>
+              <ColorScaleBar
+                scale={resolved.scale}
+                style={{ width: BUTTON_BAR_WIDTH }}
+              />
+            </span>
+          }
+        />
+      </PopoverNext>
+    </label>
+  );
+}
+
+/**
+ * One line of the menu, under the heading of its kind when the kind changes.
+ * @param props - The scale the line offers, and what precedes it.
+ * @param props.id - Id of the scale, which is what a link carries.
+ * @param props.label - What the line is called.
+ * @param props.kind - What the scale is for, which is the heading it sits under.
+ * @param props.description - One line on when to reach for it, read on hover.
+ * @param props.previous - Kind of the line above, so a heading is written once.
+ * @param props.selected - Whether it is the scale in force.
+ * @param props.onChange - Called with the id when the line is chosen.
+ * @returns The line, with its heading when it opens a kind.
+ */
+function ScaleEntry(props: {
+  id: string;
+  label: string;
+  kind: ColorScaleKind;
+  description: string;
+  previous: ColorScaleKind | undefined;
+  selected: boolean;
+  onChange: (value: string) => void;
+}): ReactElement {
+  const { id, label, kind, description, previous, selected, onChange } = props;
+  const entry = (
+    <MenuItem
+      roleStructure="listoption"
+      selected={selected}
+      htmlTitle={description}
+      text={
+        <span style={ITEM_STYLE}>
+          <span>{label}</span>
+          <ColorScaleBar scale={scaleOf(id)} />
+        </span>
+      }
+      onClick={() => {
+        onChange(id);
+      }}
+    />
+  );
+  if (previous === kind) return entry;
+  return (
+    <>
+      <MenuDivider title={COLOR_SCALE_KIND_LABELS[kind]} />
+      {entry}
+    </>
+  );
+}
+
+function scaleOf(id: string): ColorScale {
+  return resolveColorScale(id).scale;
+}
+
+const FIELD_STYLE = {
+  display: 'flex',
+  flex: '1 1 auto',
+  flexDirection: 'column',
+  gap: 3,
+  minWidth: 180,
+  maxWidth: 420,
+} as const satisfies CSSProperties;
+
+const CAPTION_STYLE = {
+  color: 'var(--text-muted, #5b6875)',
+  fontSize: 12,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+const BUTTON_TEXT_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 10,
+  width: '100%',
+} as const satisfies CSSProperties;
+
+const ITEM_STYLE = {
+  display: 'grid',
+  gridTemplateColumns: '7rem 1fr',
+  alignItems: 'center',
+  gap: 10,
+  minWidth: 220,
+} as const satisfies CSSProperties;
+
+const MENU_STYLE = {
+  maxHeight: '60vh',
+  overflowY: 'auto',
+} as const satisfies CSSProperties;
+
+const EDITOR_HEADER_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+  padding: '8px 12px 0',
+} as const satisfies CSSProperties;

package/src/color/ui/index.ts

@@ -1,2 +1,8 @@
+export type { ColorScaleBarProps } from './ColorScaleBar.tsx';
+export { ColorScaleBar } from './ColorScaleBar.tsx';
+export type { ColorScaleEditorProps } from './ColorScaleEditor.tsx';
+export { ColorScaleEditor } from './ColorScaleEditor.tsx';
 export type { ColorScaleLegendProps } from './ColorScaleLegend.tsx';
 export { ColorScaleLegend } from './ColorScaleLegend.tsx';
+export type { ColorScaleSelectProps } from './ColorScaleSelect.tsx';
+export { ColorScaleSelect } from './ColorScaleSelect.tsx';

package/src/core.ts

@@ -1,4 +1,5 @@
 export * from './about/core/index.ts';
+export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';
 export * from './color/core/index.ts';
@@ -8,13 +9,18 @@ export * from './download/core/index.ts';
 export * from './ecosystem/core/index.ts';
 export * from './format/core/index.ts';
 export * from './orbital/core/index.ts';
+export * from './overlay/core/index.ts';
 export * from './pedagogy/core/index.ts';
 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
 // a manifest without loading React: `react-cheminfo/slides` is the player.
 export * from './slides/core/index.ts';
+export * from './spectra/core/index.ts';
 export * from './tokens/core/index.ts';
 export * from './worker/core/index.ts';

package/src/credits/core/credits.ts

@@ -208,6 +208,26 @@ export const CREDITS = [
     description: 'the database, one file, read through the Node built-in.',
     license: 'Public domain',
   },
+  {
+    id: 'sqlite-wasm',
+    name: 'SQLite Wasm',
+    href: 'https://sqlite.org/wasm/',
+    description: 'runs the same engine in the page, compiled to WebAssembly.',
+    license: 'Public domain',
+  },
+  {
+    id: 'pouchdb',
+    name: 'PouchDB',
+    href: 'https://pouchdb.com/',
+    description: 'answers Mango selectors the way CouchDB answers them.',
+    license: 'Apache-2.0',
+  },
+  {
+    id: 'chemexper',
+    name: 'ChemExper',
+    href: 'https://www.chemexper.com/',
+    description: 'the catalogue the compounds and their spectra come from.',
+  },
   {
     id: 'react',
     name: 'React',

package/src/download/core/cssTokens.ts

@@ -0,0 +1,90 @@
+/**
+ * Reading the tokens a figure is drawn with out of its markup, and writing
+ * their values back into it.
+ *
+ * Every chart in this package takes its ink from the family's custom
+ * properties — `var(--border)`, `var(--text-muted)` — which is what lets one
+ * figure follow the site it is embedded in. A file saved to disk has left that
+ * site: nothing there declares `--border`, so a `var()` that survives the
+ * export resolves to nothing at all and the picture arrives with no axes. So
+ * the values are read off the live element while it is still on the page, and
+ * written into the copy that leaves.
+ */
+
+/**
+ * One `var(--name)` call, with the fallback it carries where it has one. The
+ * fallback may not itself contain brackets, so a nested call is left to the
+ * next pass rather than half-matched here.
+ */
+const TOKEN_CALL =
+  /var\(\s*(?<name>--[\w-]+)\s*(?:,\s*(?<fallback>[^()]*?)\s*)?\)/gu;
+
+/** How many times a resolved value may itself name another token. */
+const MAX_PASSES = 4;
+
+/**
+ * Every token a piece of markup asks for, each named once.
+ * @param text - The markup, or a single declaration.
+ * @returns The token names, `--` included, in the order first written.
+ */
+export function cssTokenNames(text: string): readonly string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const match of text.matchAll(TOKEN_CALL)) {
+    const name = match.groups?.name;
+    if (name === undefined || seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The same markup with every token it names written out in full.
+ *
+ * A token whose value is itself written with `var()` — which is how a site
+ * points `--accent` at its own `--brand` — is resolved in turn, up to a few
+ * passes deep. A token nobody has a value for keeps its fallback where the
+ * call carries one, and is otherwise left exactly as written: an unresolved
+ * `var()` is at worst the colour that was already missing, while a guess would
+ * be a colour nobody chose.
+ * @param text - The markup, or a single declaration.
+ * @param values - What each token is worth, keyed by name with its `--`.
+ * @returns The markup, resolved.
+ */
+export function resolveCssTokens(
+  text: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  let resolved = text;
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    if (!resolved.includes('var(')) break;
+    const next = resolveOnce(resolved, values);
+    if (next === resolved) break;
+    resolved = next;
+  }
+  return resolved;
+}
+
+/**
+ * One pass over the markup, replacing the calls that can be answered.
+ * @param text - The markup as it stands.
+ * @param values - What each token is worth.
+ * @returns The markup, one layer of tokens shallower.
+ */
+function resolveOnce(
+  text: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  let written = '';
+  let read = 0;
+  for (const match of text.matchAll(TOKEN_CALL)) {
+    const { name, fallback } = match.groups ?? {};
+    const value = name === undefined ? undefined : values[name]?.trim();
+    written += text.slice(read, match.index);
+    written +=
+      value !== undefined && value !== '' ? value : (fallback ?? match[0]);
+    read = match.index + match[0].length;
+  }
+  return written + text.slice(read);
+}

package/src/download/core/downloadFigure.ts

@@ -0,0 +1,66 @@
+/**
+ * Saving a figure that is on the page, named by the box it is mounted in.
+ *
+ * Which of the two formats a reader wants is not a question the figure can
+ * answer for them: an SVG is the one to put in a paper, where it stays sharp
+ * at any size and can still be edited, and a PNG is the one every chat window,
+ * slide deck and issue tracker actually accepts. So both are offered, and the
+ * resolution goes with the second.
+ */
+
+import { downloadBlob } from './downloadBlob.ts';
+import { figurePng } from './figurePng.ts';
+import { DEFAULT_FIGURE_SCALE } from './figureScale.ts';
+import type { FigureSvgOptions } from './figureSvg.ts';
+import { FIGURE_SVG_TYPE, figureSvg } from './figureSvg.ts';
+import { sanitizeFileName } from './sanitizeFileName.ts';
+
+/** Which file a figure is saved as. */
+export type FigureFormat = 'svg' | 'png';
+
+/** How a figure is saved. */
+export interface DownloadFigureOptions extends FigureSvgOptions {
+  /**
+   * Which file to write.
+   * @default 'png'
+   */
+  format?: FigureFormat;
+  /**
+   * How many pixels are painted per pixel on screen. An SVG ignores it: it
+   * carries no resolution of its own.
+   * @default 2
+   */
+  scale?: number;
+  /**
+   * What the saved file is called, without its extension.
+   * @default 'figure'
+   */
+  fileName?: string;
+}
+
+/** What a figure is called when the caller does not say. */
+const DEFAULT_FILE_NAME = 'figure';
+
+/**
+ * Save the figure mounted in that box.
+ * @param target - The `id` of the box, or the element itself.
+ * @param options - See {@link DownloadFigureOptions}.
+ * @throws {Error} When the box holds no figure, or the browser cannot paint it.
+ */
+export async function downloadFigure(
+  target: string | Element,
+  options: DownloadFigureOptions = {},
+): Promise<void> {
+  const { format = 'png', scale = DEFAULT_FIGURE_SCALE } = options;
+  const { fileName = DEFAULT_FILE_NAME, background } = options;
+
+  const figure = figureSvg(target, { background });
+  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;
+  }
+  downloadBlob(await figurePng(figure, scale), `${name}.png`);
+}

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;