react-cheminfo 0.38.0 → 0.39.1

package/src/structure/ui/StructureExportDialog.tsx

@@ -0,0 +1,90 @@
+/**
+ * The dialog that hands a drawn structure over.
+ *
+ * The shell is here and the body is behind `React.lazy`, for the same reason
+ * `Structure` keeps its depiction there: this file must stay free of
+ * `openchemlib` so a site importing `react-cheminfo/structure` for the editor
+ * does not also download the notations nobody has asked for yet.
+ */
+
+import { Dialog, DialogBody } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { Suspense, lazy } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import type { StructureExportPanelProps } from './StructureExportPanel.tsx';
+
+const StructureExportPanel = lazy(async () => {
+  const module = await import('./StructureExportPanel.tsx');
+  return { default: module.StructureExportPanel };
+});
+
+/** What {@link StructureExportDialog} needs. */
+export interface StructureExportDialogProps extends StructureExportPanelProps {
+  /** Whether the dialog is on screen. */
+  isOpen: boolean;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+  /**
+   * Whether the dialog is rendered through a portal on `document.body`.
+   * @default true
+   */
+  usePortal?: boolean;
+}
+
+/**
+ * Take a structure off the page: as a notation, or as a picture.
+ *
+ * One dialog rather than a menu of downloads, because the question is never
+ * only "which format" — a reader comparing a SMILES against an idCode, or
+ * checking that the hash they are about to paste belongs to the molecule in
+ * front of them, needs to see the structure and the strings together.
+ * @param props - See {@link StructureExportDialogProps}.
+ * @returns The dialog.
+ */
+export function StructureExportDialog(
+  props: StructureExportDialogProps,
+): ReactElement {
+  const { isOpen, onClose, usePortal = true, ...panel } = props;
+  const t = useChromeT();
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      usePortal={usePortal}
+      title={t('structure.export.title')}
+      icon="export"
+      className="structure-export"
+      style={DIALOG_STYLE}
+    >
+      <DialogBody className="structure-export__body">
+        {/* Mounted with the body, so the notations are written from the
+            structure as it stands each time the dialog is opened. */}
+        {isOpen ? (
+          <Suspense
+            fallback={
+              <p style={LOADING_STYLE}>{t('structure.export.loading')}</p>
+            }
+          >
+            <StructureExportPanel {...panel} />
+          </Suspense>
+        ) : null}
+      </DialogBody>
+    </Dialog>
+  );
+}
+
+const DIALOG_STYLE = {
+  width: 'min(980px, 94vw)',
+} as const satisfies CSSProperties;
+
+const LOADING_STYLE = {
+  margin: 0,
+  padding: '2rem 0',
+  color: TOKEN.textFaint,
+  fontSize: 13,
+  textAlign: 'center',
+} as const satisfies CSSProperties;

package/src/structure/ui/StructureExportPanel.tsx

@@ -0,0 +1,156 @@
+/**
+ * The body of the export dialog, which is the half that reads the structure.
+ *
+ * It value-imports `openchemlib`, through the notations and the parser, so the
+ * dialog holds it behind `React.lazy`: a page carrying an editor downloads
+ * this only when somebody asks to export something.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import { CollapsibleSection } from '../../disclosure/ui/CollapsibleSection.tsx';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import { sourceMolecule } from '../core/sourceMolecule.ts';
+import { structureError } from '../core/structureError.ts';
+import { structureNotations } from '../core/structureNotations.ts';
+import type { StructureSourceInput } from '../core/structureSource.ts';
+import { structureSource } from '../core/structureSource.ts';
+
+import { StructureNotationRow } from './StructureNotationRow.tsx';
+import { StructurePicturePane } from './StructurePicturePane.tsx';
+
+/** What {@link StructureExportPanel} is handed. */
+export interface StructureExportPanelProps extends StructureSourceInput {
+  /**
+   * Base name of every file saved from here, extension excluded.
+   * @default 'structure'
+   */
+  name?: string;
+  /**
+   * Whether the structure is a query fragment, which is what a substructure
+   * filter draws. A fragment's idCode is not a molecule's, so this has to be
+   * said when the notation handed over does not already carry it.
+   * @default false
+   */
+  fragment?: boolean;
+}
+
+/**
+ * Every notation of a drawn structure, and the picture of it.
+ *
+ * The notations come first and in the order a chemist reaches for them — the
+ * SMILES, then the two molfiles — with the canonical identifiers folded away
+ * underneath: they answer a database question rather than a drawing one, so
+ * they are there for whoever came for them and out of the way of everyone
+ * else.
+ * @param props - See {@link StructureExportPanelProps}.
+ * @returns The panel.
+ */
+export function StructureExportPanel(
+  props: StructureExportPanelProps,
+): ReactElement {
+  const { idCode, coordinates, molfile, smiles } = props;
+  const { name = 'structure', fragment = false } = props;
+  const t = useChromeT();
+
+  const read = useMemo(
+    () => readStructure({ idCode, coordinates, molfile, smiles }, fragment),
+    [idCode, coordinates, molfile, smiles, fragment],
+  );
+
+  if (read.kind !== 'read') {
+    return (
+      <p style={EMPTY_STYLE}>
+        {read.kind === 'empty' ? t('structure.export.nothing') : read.message}
+      </p>
+    );
+  }
+
+  const fileName = sanitizeFileName(name, 'structure');
+  const notations = read.notations;
+  const common = notations.filter((notation) => !notation.canonical);
+  const identifiers = notations.filter((notation) => notation.canonical);
+
+  return (
+    <div className="structure-export__panes">
+      <StructurePicturePane molecule={read.molecule} fileName={fileName} />
+      <div className="structure-export__notations">
+        {common.map((notation) => (
+          <StructureNotationRow
+            key={notation.kind}
+            notation={notation}
+            fileName={fileName}
+          />
+        ))}
+        <CollapsibleSection
+          className="structure-export__identifiers"
+          title={t('structure.export.identifiers')}
+          defaultOpen={false}
+        >
+          {identifiers.map((notation) => (
+            <StructureNotationRow
+              key={notation.kind}
+              notation={notation}
+              fileName={fileName}
+            />
+          ))}
+        </CollapsibleSection>
+        {/* The convention is taught once here rather than with a glyph per
+            row — see the dotted underlines above. */}
+        <p style={FOOT_STYLE}>{t('overlay.hoverAName')}</p>
+      </div>
+    </div>
+  );
+}
+
+/** The structure the panel is showing, or the reason there is none. */
+type ReadStructure =
+  | {
+      kind: 'read';
+      molecule: ReturnType<typeof sourceMolecule>;
+      notations: ReturnType<typeof structureNotations>;
+    }
+  | { kind: 'empty' }
+  | { kind: 'error'; message: string };
+
+/**
+ * Read the notation the caller handed over, and write every other one from it.
+ * @param input - Whatever notations the caller has.
+ * @param fragment - Whether the structure is a query fragment.
+ * @returns The molecule and its notations, or why there are none.
+ */
+function readStructure(
+  input: StructureSourceInput,
+  fragment: boolean,
+): ReadStructure {
+  const source = structureSource(input);
+  if (source.kind === 'empty') return { kind: 'empty' };
+  try {
+    const molecule = sourceMolecule(source);
+    // Only ever set, never cleared: an idCode written by a query editor
+    // already carries the flag, and clearing it would export a different
+    // structure from the one that was drawn.
+    if (fragment) molecule.setFragment(true);
+    if (molecule.getAllAtoms() === 0) return { kind: 'empty' };
+    return { kind: 'read', molecule, notations: structureNotations(molecule) };
+  } catch (error) {
+    return { kind: 'error', message: structureError(error).message };
+  }
+}
+
+const EMPTY_STYLE = {
+  margin: 0,
+  padding: '2rem 0',
+  color: TOKEN.textMuted,
+  fontSize: 13,
+  textAlign: 'center',
+} as const satisfies CSSProperties;
+
+const FOOT_STYLE = {
+  margin: 0,
+  color: TOKEN.textFaint,
+  fontSize: 11,
+} as const satisfies CSSProperties;

package/src/structure/ui/StructureNotationRow.tsx

@@ -0,0 +1,74 @@
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { CopyableValue } from '../../clipboard/ui/CopyableValue.tsx';
+import { downloadText } from '../../download/core/downloadText.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { StructureNotation } from '../core/structureNotations.ts';
+
+import { notationText } from './structureNotationText.ts';
+
+/** What {@link StructureNotationRow} shows. */
+export interface StructureNotationRowProps {
+  /** The notation, as `structureNotations` wrote it. */
+  notation: StructureNotation;
+  /** Base name of the file this notation is saved as, extension excluded. */
+  fileName: string;
+}
+
+/**
+ * One notation: its name, the text, and the two ways of taking it away.
+ *
+ * The text is the button that copies it — a notation is only ever wanted
+ * somewhere else — and a notation that is also a file carries a save button on
+ * its name's line, where it cannot be hit while reaching for the text. The
+ * name explains itself on hover, dotted-underlined to say so, so the row needs
+ * no glyph of its own.
+ * @param props - See {@link StructureNotationRowProps}.
+ * @returns The row.
+ */
+export function StructureNotationRow(
+  props: StructureNotationRowProps,
+): ReactElement {
+  const { notation, fileName } = props;
+  const { kind, value, file, block } = notation;
+  const t = useChromeT();
+  const text = notationText(kind);
+
+  return (
+    <CopyableValue
+      className="structure-export__notation"
+      label={t(text.label)}
+      hint={t(text.hint)}
+      value={value}
+      block={block}
+      clip={block}
+      maxHeight={block ? BLOCK_HEIGHT : undefined}
+      action={
+        file === undefined || value === '' ? undefined : (
+          <Button
+            variant="minimal"
+            size="small"
+            icon="download"
+            text={t('download.save')}
+            onClick={() => {
+              downloadText(
+                value,
+                `${fileName}${file.suffix}.${file.extension}`,
+                `${file.mimeType};charset=utf-8`,
+              );
+            }}
+          />
+        )
+      }
+    />
+  );
+}
+
+/**
+ * How much of a molfile is shown: its header and the first lines of its
+ * connection table, which is enough to see which dialect and which molecule it
+ * is. The rest is faded out rather than scrolled — the whole file is what a
+ * click copies and what the save button writes.
+ */
+const BLOCK_HEIGHT = 92;

package/src/structure/ui/StructurePicturePane.tsx

@@ -0,0 +1,208 @@
+import { Button, SegmentedControl } from '@blueprintjs/core';
+import type { Molecule } from 'openchemlib';
+import type { CSSProperties, ReactElement } from 'react';
+import { useMemo, useState } from 'react';
+
+import { writeImageToClipboard } from '../../clipboard/core/copyPng.ts';
+import { downloadBlob } from '../../download/core/downloadBlob.ts';
+import { downloadText } from '../../download/core/downloadText.ts';
+import { figurePng } from '../../download/core/figurePng.ts';
+import {
+  FIGURE_SCALES,
+  figureScaleFits,
+  figureScaleLabel,
+  formatFigurePixels,
+} from '../../download/core/figureScale.ts';
+import { FIGURE_SVG_TYPE } from '../../download/core/figureSvg.ts';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { OVERLAY_HELP_NAME_STYLE } from '../../overlay/ui/overlayRowStyles.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import type { StructurePicture } from '../core/structurePicture.ts';
+import {
+  STRUCTURE_BOND_LENGTH,
+  structurePicture,
+} from '../core/structurePicture.ts';
+
+/** What {@link StructurePicturePane} draws and saves. */
+export interface StructurePicturePaneProps {
+  /** The structure. Not modified. */
+  molecule: Molecule;
+  /** Base name of the saved files, extension excluded. */
+  fileName: string;
+}
+
+/** The multiple the pictures are offered at first. */
+const DEFAULT_SCALE = 2;
+
+/**
+ * The structure as a picture: what it looks like, how big it leaves, and the
+ * three ways it leaves.
+ *
+ * What is shown is the file: the preview is the very SVG the save button
+ * writes, laid out smaller, so nobody saves a picture they have not seen. The
+ * resolution is a multiple rather than a pixel width because the multiple is
+ * the part a reader has an opinion about — one for a note, two for a slide,
+ * three or four for print — and the pixels it comes to are written under it.
+ * @param props - See {@link StructurePicturePaneProps}.
+ * @returns The pane.
+ */
+export function StructurePicturePane(
+  props: StructurePicturePaneProps,
+): ReactElement {
+  const { molecule, fileName } = props;
+  const t = useChromeT();
+  const [scale, setScale] = useState(DEFAULT_SCALE);
+  const [notice, setNotice] = useState<string | null>(null);
+
+  // Drawn once per resolution, so what is previewed, measured and saved is one
+  // picture rather than three that have to be kept in step.
+  const picture = useMemo(
+    () =>
+      structurePicture(molecule, { bondLength: STRUCTURE_BOND_LENGTH * scale }),
+    [molecule, scale],
+  );
+  // Shown as the document itself rather than as markup put into the page: the
+  // dialog never writes HTML it did not author, and the preview is the file.
+  const preview = `data:${FIGURE_SVG_TYPE},${encodeURIComponent(picture.markup)}`;
+  // The crop is the structure's own shape, so the size at one resolution is
+  // what every other one scales from: measured rather than assumed.
+  const base = useMemo(() => structurePicture(molecule), [molecule]);
+
+  async function png(): Promise<Blob> {
+    return figurePng(picture, 1);
+  }
+
+  async function run(write: () => Promise<string | null>): Promise<void> {
+    try {
+      setNotice(await write());
+    } catch (error) {
+      setNotice(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return (
+    <div className="structure-export__picture">
+      <img
+        className="structure-export__stage"
+        src={preview}
+        alt={t('structure.export.picture')}
+      />
+      <div className="structure-export__row">
+        <HelpTooltip
+          content={{
+            title: t('download.resolution'),
+            body: t('download.resolutionHelp'),
+            example: { code: '2×', note: t('download.resolutionExample') },
+          }}
+          placement="top-start"
+        >
+          <span style={NAME_STYLE}>{t('download.resolution')}</span>
+        </HelpTooltip>
+        <SegmentedControl
+          size="small"
+          options={scaleOptions(base)}
+          value={String(scale)}
+          onValueChange={(picked) => {
+            setNotice(null);
+            setScale(Number(picked));
+          }}
+        />
+      </div>
+      <p className="structure-export__pixels" style={PIXELS_STYLE}>
+        {formatFigurePixels(picture)}
+      </p>
+      <div className="structure-export__actions">
+        <Button
+          icon="download"
+          size="small"
+          text={t('structure.export.saveSvg')}
+          onClick={() =>
+            void run(async () => {
+              downloadText(picture.markup, `${fileName}.svg`, FIGURE_SVG_TYPE);
+              return null;
+            })
+          }
+        />
+        <Button
+          icon="download"
+          size="small"
+          intent="primary"
+          text={t('structure.export.savePng')}
+          onClick={() =>
+            void run(async () => {
+              downloadBlob(await png(), `${fileName}.png`);
+              return null;
+            })
+          }
+        />
+        <Button
+          icon="clipboard"
+          size="small"
+          text={t('structure.export.copyPng')}
+          onClick={() =>
+            // Safari only allows a clipboard write the click itself started,
+            // so the image is handed over as a promise rather than awaited
+            // first — see `writeImageToClipboard`.
+            void run(async () =>
+              (await writeImageToClipboard(png()))
+                ? t('download.hintCopied', {
+                    pixels: formatFigurePixels(picture),
+                  })
+                : t('download.copyUnsupported'),
+            )
+          }
+        />
+      </div>
+      {notice === null ? null : (
+        <p className="structure-export__notice" style={NOTICE_STYLE}>
+          {notice}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The multiples offered, each greyed when the picture it would produce is past
+ * what a browser will paint — the ceiling is met here rather than as a blank
+ * file, which is the rule the figure panel follows.
+ * @param base - The picture at the smallest resolution, which the others are
+ * multiples of.
+ * @returns The choices, in the order offered.
+ */
+function scaleOptions(base: StructurePicture): Array<{
+  label: string;
+  value: string;
+  disabled?: boolean;
+}> {
+  const options = [];
+  for (const scale of FIGURE_SCALES) {
+    options.push({
+      label: figureScaleLabel(scale),
+      value: String(scale),
+      disabled: !figureScaleFits(base, scale),
+    });
+  }
+  return options;
+}
+
+const NAME_STYLE = {
+  ...OVERLAY_HELP_NAME_STYLE,
+  color: TOKEN.textMuted,
+  fontSize: 12,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+const PIXELS_STYLE = {
+  margin: 0,
+  color: TOKEN.textFaint,
+  fontSize: 11,
+  fontVariantNumeric: 'tabular-nums',
+} as const satisfies CSSProperties;
+
+const NOTICE_STYLE = {
+  margin: 0,
+  color: TOKEN.textMuted,
+  fontSize: 11,
+} as const satisfies CSSProperties;

package/src/structure/ui/StructureSvg.tsx

@@ -8,13 +8,14 @@
  * every bundle, including the ones that only ever wanted the Tools menu.
  */
 
-import { Molecule } from 'openchemlib';
+import type { Molecule } from 'openchemlib';
 import type { ReactElement, ReactNode } from 'react';
 import { useMemo } from 'react';
 import { SvgRenderer } from 'react-ocl';
 
 import type { AtomLabelPlacement } from '../core/atomLabels.ts';
 import { applyAtomLabels } from '../core/atomLabels.ts';
+import { sourceMolecule } from '../core/sourceMolecule.ts';
 import type { StructureSource } from '../core/structureSource.ts';
 
 import { StructurePlaceholder } from './StructurePlaceholder.tsx';
@@ -163,7 +164,7 @@ function readDrawing(
 ): Drawing | null {
   let molecule: Molecule;
   try {
-    molecule = parseMolecule(kind, value, coordinates);
+    molecule = sourceMolecule({ kind, value, coordinates });
   } catch {
     return null;
   }
@@ -174,13 +175,3 @@ function readDrawing(
   const written = applyAtomLabels(molecule, labels, placement);
   return { molecule, labelled: written > 0 };
 }
-
-function parseMolecule(
-  kind: StructureSource['kind'],
-  value: string,
-  coordinates: string | undefined,
-): Molecule {
-  if (kind === 'idcode') return Molecule.fromIDCode(value, coordinates);
-  if (kind === 'molfile') return Molecule.fromMolfile(value);
-  return Molecule.fromSmiles(value);
-}

package/src/structure/ui/ToolbarTooltip.tsx

@@ -43,6 +43,7 @@ export function ToolbarTooltip(
       isOpen={hover.open}
       placement="right"
       content={<ButtonTip button={button} mode={mode} />}
+      popoverClassName="help-tooltip"
       renderTarget={({ ref }) => (
         <span ref={ref} aria-hidden style={{ ...TARGET_STYLE, ...hover.box }} />
       )}
@@ -87,7 +88,6 @@ const TIP_STYLE: CSSProperties = {
   display: 'flex',
   flexDirection: 'column',
   gap: 4,
-  maxWidth: 260,
   lineHeight: 1.4,
 };
 

package/src/structure/ui/index.ts

@@ -2,9 +2,10 @@
  * What a site imports to show or to draw a structure.
  *
  * **Nothing exported here may pull react-ocl or openchemlib in statically.**
- * `StructureSvg` and `EditorCanvas` are deliberately absent: re-exporting
- * either would make react-ocl reachable from this barrel, the `React.lazy`
- * boundaries inside `Structure` and `StructureEditor` would be defeated, and
+ * `StructureSvg`, `EditorCanvas` and `StructureExportPanel` are deliberately
+ * absent: re-exporting any of them would make react-ocl reachable from this
+ * barrel, the `React.lazy` boundaries inside `Structure`, `StructureEditor`
+ * and `StructureExportDialog` would be defeated, and
  * `react-cheminfo/structure` would stop being importable at all when those
  * optional peers are not installed — which is what a site wanting only the
  * Tools menu does. Type-only re-exports are erased and so are safe.
@@ -22,5 +23,8 @@ export type { StructureEditorProps } from './StructureEditor.tsx';
 export { StructureEditor } from './StructureEditor.tsx';
 export type { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
 export { StructureEditorHelp } from './StructureEditorHelp.tsx';
+export type { StructureExportDialogProps } from './StructureExportDialog.tsx';
+export { StructureExportDialog } from './StructureExportDialog.tsx';
+export type { StructureExportPanelProps } from './StructureExportPanel.tsx';
 export type { ToolbarFloorOptions } from './useToolbarFloor.ts';
 export { useToolbarFloor } from './useToolbarFloor.ts';

package/src/structure/ui/structureNotationText.ts

@@ -0,0 +1,56 @@
+/**
+ * What each notation is called, and the line that explains it.
+ *
+ * The core module writing the notations stays language-free, so the words live
+ * here: one record, so a notation added there is a compile error until it is
+ * named.
+ */
+
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { StructureNotationKind } from '../core/structureNotations.ts';
+
+/** The two lines a notation needs: its name, and what it is. */
+export interface StructureNotationText {
+  /** Its name, on the row. */
+  label: ChromeKey;
+  /** What it is, read by hovering the name. */
+  hint: ChromeKey;
+}
+
+const TEXT = {
+  smiles: {
+    label: 'structure.export.smiles',
+    hint: 'structure.export.smilesHelp',
+  },
+  molfileV3000: {
+    label: 'structure.export.molfileV3000',
+    hint: 'structure.export.molfileV3000Help',
+  },
+  molfileV2000: {
+    label: 'structure.export.molfileV2000',
+    hint: 'structure.export.molfileV2000Help',
+  },
+  idCode: {
+    label: 'structure.export.idCode',
+    hint: 'structure.export.idCodeHelp',
+  },
+  noStereoIdCode: {
+    label: 'structure.export.noStereoIdCode',
+    hint: 'structure.export.noStereoIdCodeHelp',
+  },
+  noStereoTautomerIdCode: {
+    label: 'structure.export.noStereoTautomerIdCode',
+    hint: 'structure.export.noStereoTautomerIdCodeHelp',
+  },
+} as const satisfies Record<StructureNotationKind, StructureNotationText>;
+
+/**
+ * How a notation is named and explained.
+ * @param kind - Which notation it is.
+ * @returns The two keys to format.
+ */
+export function notationText(
+  kind: StructureNotationKind,
+): StructureNotationText {
+  return TEXT[kind];
+}