react-cheminfo 0.8.0 → 0.10.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,3 +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';
@@ -7,9 +9,17 @@ 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 './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

@@ -166,6 +166,68 @@ export const CREDITS = [
     description: 'typesets the mathematics, from LaTeX to what you read.',
     license: 'Apache-2.0',
   },
+  {
+    id: 'lexical',
+    name: 'Lexical',
+    href: 'https://lexical.dev/',
+    description: 'the editor a written page is composed and stored in.',
+    license: 'MIT',
+  },
+  {
+    id: 'katex',
+    name: 'KaTeX',
+    href: 'https://katex.org/',
+    description: 'typesets the mathematics inside a written page.',
+    license: 'MIT',
+  },
+  {
+    id: 'dnd-kit',
+    name: 'dnd kit',
+    href: 'https://dndkit.com/',
+    description: 'the dragging that arranges things into an order.',
+    license: 'MIT',
+  },
+  {
+    id: 'preact-signals',
+    name: 'Preact Signals',
+    href: 'https://preactjs.com/guide/v10/signals/',
+    description: 'the state the pages read, without a store around it.',
+    license: 'MIT',
+  },
+  {
+    id: 'fastify',
+    name: 'Fastify',
+    href: 'https://fastify.dev/',
+    description: 'the server that answers the API and serves the page.',
+    license: 'MIT',
+  },
+  {
+    id: 'sqlite',
+    name: 'SQLite',
+    href: 'https://sqlite.org/',
+    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/credits/ui/CreditsList.tsx

@@ -76,7 +76,7 @@ const ITEM_STYLE = {
 const NAME_STYLE = { fontWeight: 600 } as const satisfies CSSProperties;
 
 const LICENSE_STYLE = {
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 11,
   margin: '0 6px',
 } as const satisfies CSSProperties;

package/src/delimited/ui/DelimitedTextPanel.tsx

@@ -143,7 +143,7 @@ const CONTROLS_STYLE = {
 } as const satisfies CSSProperties;
 
 const LABEL_STYLE = {
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 12,
 } as const satisfies CSSProperties;
 

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/figurePng.ts

@@ -0,0 +1,87 @@
+/**
+ * A figure painted into pixels, at whatever resolution the reader asked for.
+ *
+ * The picture is drawn once as an SVG and then rasterized from it, rather than
+ * being drawn a second time into a canvas: a figure that is saved has to be
+ * 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.
+ */
+
+import { DEFAULT_FIGURE_SCALE, figurePixels } from './figureScale.ts';
+import type { FigureSvg } from './figureSvg.ts';
+import { FIGURE_SVG_TYPE } from './figureSvg.ts';
+
+/** What a saved raster figure is. */
+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.
+ * @throws {Error} When the browser cannot paint or encode it.
+ */
+export async function figurePng(
+  figure: FigureSvg,
+  scale: number = DEFAULT_FIGURE_SCALE,
+): Promise<Blob> {
+  const pixels = figurePixels(figure, scale);
+  const drawing = await loadFigure(figure);
+
+  const canvas = document.createElement('canvas');
+  canvas.width = pixels.width;
+  canvas.height = pixels.height;
+  const context = canvas.getContext('2d');
+  if (context === null) {
+    throw new Error('This browser cannot paint the figure into an image.');
+  }
+  context.drawImage(drawing, 0, 0, pixels.width, pixels.height);
+
+  return encode(canvas);
+}
+
+/**
+ * The SVG document, decoded and ready to be painted.
+ *
+ * It goes through an object URL rather than a `data:` one because a figure of
+ * a few thousand dots runs to hundreds of kilobytes, and a `data:` URL that
+ * long is refused outright by some browsers.
+ * @param figure - The figure, already copied off the page.
+ * @returns The decoded image.
+ */
+async function loadFigure(figure: FigureSvg): Promise<HTMLImageElement> {
+  const url = URL.createObjectURL(
+    new Blob([figure.markup], { type: FIGURE_SVG_TYPE }),
+  );
+  try {
+    const image = new Image(figure.width, figure.height);
+    await new Promise<void>((resolve, reject) => {
+      image.addEventListener('load', () => resolve());
+      image.addEventListener('error', () => {
+        reject(new Error('The figure could not be read back as an image.'));
+      });
+      image.src = url;
+    });
+    return image;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/**
+ * The painted canvas, as a file.
+ * @param canvas - The canvas the figure was painted into.
+ * @returns The image.
+ */
+function encode(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob === null) {
+        reject(new Error('The figure could not be encoded as a PNG.'));
+        return;
+      }
+      resolve(blob);
+    }, FIGURE_PNG_TYPE);
+  });
+}