react-cheminfo 0.28.0 → 0.29.0

package/src/download/ui/ExportDialogFrame.tsx

@@ -0,0 +1,86 @@
+import type { IconName } from '@blueprintjs/core';
+import { Button, Dialog, DialogBody, DialogFooter } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+
+import { useConfirmOnEnter } from '../../panel/ui/useConfirmOnEnter.ts';
+import { exportNoteStyle } from '../core/exportStyles.ts';
+
+export interface ExportDialogFrameProps {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /** What it is about, along the top. */
+  title: string;
+  /** The icon beside that title. */
+  icon: IconName;
+  /**
+   * The name saved files take, without their extension; the section is keyed on
+   * it, so a file saved under a new name is what the name box opens on next
+   * time rather than what was typed and then thought better of.
+   */
+  filename: string;
+  /**
+   * How wide the dialog opens, in pixels. A section showing text needs the room
+   * to show a molfile line whole; one showing controls does not.
+   * @default 560
+   */
+  width?: number;
+  /**
+   * Whether the section is mounted only while the dialog is open, for a section
+   * whose work — measuring a picture off the page — is only worth doing while
+   * it is being looked at.
+   * @default false
+   */
+  mountWhileOpen?: boolean;
+  /** The section, built with the status setter the footer reads. */
+  children: (onStatus: (status: string) => void) => ReactNode;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+}
+
+/**
+ * The frame every export dialog shares: the section, and what it last did.
+ *
+ * Each thing the editor writes out gets a dialog of its own rather than one
+ * shared dialog of tabs, since a picture, a structure and a sequence are asked
+ * for at different moments; what they have in common is only the frame, which
+ * is here so the three cannot come to differ in how they close or where they
+ * say what they wrote.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function ExportDialogFrame(props: ExportDialogFrameProps) {
+  const {
+    isOpen,
+    title,
+    icon,
+    filename,
+    width = DEFAULT_WIDTH,
+    mountWhileOpen = false,
+    children,
+    onClose,
+  } = props;
+
+  const [status, setStatus] = useState<string | null>(null);
+
+  useConfirmOnEnter(isOpen, onClose);
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      title={title}
+      icon={icon}
+      style={{ width, maxWidth: '92vw' }}
+      onClose={onClose}
+    >
+      <DialogBody key={filename}>
+        {mountWhileOpen && !isOpen ? null : children(setStatus)}
+      </DialogBody>
+      <DialogFooter actions={<Button text="Close" onClick={onClose} />}>
+        <span style={exportNoteStyle}>{status}</span>
+      </DialogFooter>
+    </Dialog>
+  );
+}
+
+const DEFAULT_WIDTH = 560;

package/src/download/ui/ExportImageDialog.tsx

@@ -0,0 +1,91 @@
+import { useState } from 'react';
+
+import { DEFAULT_IMAGE_RESOLUTION } from '../core/imageResolution.ts';
+import type { PictureFrame } from '../core/pictureExport.ts';
+
+import { ExportDialogFrame } from './ExportDialogFrame.tsx';
+import { ExportPictureSection } from './ExportPictureSection.tsx';
+
+export interface ExportImageDialogProps {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /**
+   * The drawing the picture is taken of, as it is rendered. Read when a button
+   * is pressed rather than passed in, since a drawing is laid out again on
+   * every resize. `null` when nothing is drawn.
+   */
+  getDrawing: () => SVGSVGElement | null;
+  /**
+   * The name saved files take, without their extension.
+   * @default 'picture'
+   */
+  filename?: string;
+  /**
+   * What the picture is read out as in the file it is written to, in place of
+   * the instructions the element carries for whoever is working it.
+   * @default 'Drawing'
+   */
+  label?: string;
+  /**
+   * Whether the picture is the drawing inside the element — a canvas, which is
+   * mostly the empty space around what is on it — or the element as it is laid
+   * out, which is what a chart drawn to the box it was given is.
+   * @default 'content'
+   */
+  frame?: PictureFrame;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+}
+
+/**
+ * A drawing as a picture: PNG at a chosen resolution, or SVG.
+ *
+ * How big it comes out is asked rather than guessed, since only one size could
+ * be the default and neither a figure nor a thumbnail is it. SVG is the honest
+ * answer wherever it is accepted — it is drawn again at whatever size it is
+ * printed — so the resolution there is only the size the file opens at.
+ *
+ * The same dialog writes out a glycan, a molecule and a spectrum, because none
+ * of what it does depends on what is drawn: it is handed an SVG element that is
+ * already on the page, and asks it how big it is.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function ExportImageDialog(props: ExportImageDialogProps) {
+  const {
+    isOpen,
+    getDrawing,
+    filename = 'picture',
+    label = 'Drawing',
+    frame,
+    onClose,
+  } = props;
+
+  const [resolutionId, setResolutionId] = useState<string>(
+    DEFAULT_IMAGE_RESOLUTION.id,
+  );
+
+  return (
+    <ExportDialogFrame
+      isOpen={isOpen}
+      title="Export as an image"
+      icon="media"
+      filename={filename}
+      width={460}
+      mountWhileOpen
+      onClose={onClose}
+    >
+      {(onStatus) => (
+        <ExportPictureSection
+          getDrawing={getDrawing}
+          resolutionId={resolutionId}
+          onResolutionChange={setResolutionId}
+          filename={filename}
+          label={label}
+          frame={frame}
+          onStatus={onStatus}
+        />
+      )}
+    </ExportDialogFrame>
+  );
+}

package/src/download/ui/ExportNameField.tsx

@@ -0,0 +1,148 @@
+import { useLayoutEffect, useRef } from 'react';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+export interface ExportNameFieldProps {
+  /** What is in the box, without an extension. */
+  name: string;
+  /**
+   * The extension the file is about to take, shown after what is typed.
+   * @default ''
+   */
+  extension?: string;
+  /** Called with what was typed. */
+  onChange: (name: string) => void;
+}
+
+/**
+ * What the file about to be written out is called.
+ *
+ * It sits at the right of the row of buttons, against the one that writes the
+ * file, because that is what it is about — copying takes no name, and puts
+ * itself at the other end of the row. The name the editor came in with is
+ * offered, since that is what a glycan is usually saved under, but a picture
+ * for a slide and a molfile for a docking run are rarely wanted under it.
+ *
+ * The box grows with what is typed, so the extension sits directly against the
+ * name and the two read as the one filename they are about to become. Held to a
+ * fixed width instead, the extension hangs at the far edge with the gap between
+ * them reading as part of neither.
+ * @param props - Component props.
+ * @returns The field.
+ */
+export function ExportNameField(props: ExportNameFieldProps) {
+  const { name, extension = '', onChange } = props;
+
+  const input = useRef<HTMLInputElement>(null);
+  const mirror = useRef<HTMLSpanElement>(null);
+  const ruler = useRef<HTMLSpanElement>(null);
+
+  // Measured off a copy of the text in the same font rather than counted in
+  // characters, which only holds for a monospace one. The width is set on the
+  // element instead of kept in state: it is what the browser has just measured,
+  // so rendering again to store it would measure the same thing twice.
+  useLayoutEffect(() => {
+    if (!input.current || !mirror.current || !ruler.current) return;
+    const measured = mirror.current.offsetWidth + CARET;
+    const floor = ruler.current.offsetWidth;
+    input.current.style.width = `${Math.min(Math.max(measured, floor), MAXIMUM)}px`;
+  });
+
+  return (
+    <div style={fieldStyle}>
+      <div className="bp6-input" style={boxStyle}>
+        <input
+          ref={input}
+          value={name}
+          aria-label="File name"
+          placeholder={PLACEHOLDER}
+          spellCheck={false}
+          autoComplete="off"
+          style={inputStyle}
+          onChange={(event) => onChange(event.target.value)}
+          // The name is in force as it is typed, so Enter has nothing left to
+          // confirm — and is kept off the dialog, whose answer is to close.
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') event.stopPropagation();
+          }}
+        />
+        {extension === '' ? null : (
+          <span style={extensionStyle}>{extension}</span>
+        )}
+        {/* Inside the box rather than beside it, so the copy the width is
+            measured off is in the font the box gives its own text and not in
+            whatever the dialog around it happens to use. */}
+        <span ref={mirror} style={mirrorStyle} aria-hidden="true">
+          {name === '' ? PLACEHOLDER : name}
+        </span>
+        <span ref={ruler} style={mirrorStyle} aria-hidden="true">
+          {FLOOR_SAMPLE}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+/** What the box says when nothing has been typed into it. */
+const PLACEHOLDER = 'File name';
+
+/** Room for the caret past the last character, so it is never clipped. */
+const CARET = 2;
+
+/**
+ * Twenty characters, which the box is never narrower than.
+ *
+ * A name is typed into this box as often as it is read out of it, and a box cut
+ * to `glycan` leaves no room to do that in — so the floor is a name of the
+ * length one usually is, measured in the box's own font rather than counted at
+ * some assumed character width. `n` is about the average width of a lowercase
+ * letter, which is what a filename is mostly made of.
+ */
+const FLOOR_SAMPLE = 'n'.repeat(20);
+
+/** Past this a name scrolls inside the box rather than pushing the dialog. */
+const MAXIMUM = 260;
+
+// Held against the right of the row beside the button that writes the file, so
+// the space in the row falls between copying and saving rather than inside the
+// name.
+const fieldStyle = { marginLeft: 'auto', flexShrink: 0 } as const;
+
+// Blueprint's own input chrome, worn by the box rather than by the field inside
+// it, so the name and the extension sit within one border. Positioned, so the
+// hidden copy the width is measured off can be taken out of the layout without
+// leaving the box it takes its font from.
+const boxStyle = {
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  width: 'fit-content',
+} as const;
+
+// The field itself brings nothing of its own: the box around it is what is
+// seen, and the text has to be in the font the width was measured in.
+const inputStyle = {
+  font: 'inherit',
+  border: 'none',
+  outline: 'none',
+  padding: 0,
+  margin: 0,
+  background: 'transparent',
+  color: 'inherit',
+} as const;
+
+const extensionStyle = {
+  color: TOKEN.textMuted,
+  whiteSpace: 'pre',
+} as const;
+
+// A copy of what is typed, in the same font, laid out but never painted.
+const mirrorStyle = {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  visibility: 'hidden',
+  pointerEvents: 'none',
+  whiteSpace: 'pre',
+  font: 'inherit',
+} as const;

package/src/download/ui/ExportPictureSection.tsx

@@ -0,0 +1,142 @@
+import { Button, HTMLSelect } from '@blueprintjs/core';
+import { useState } from 'react';
+
+import {
+  exportButtonsStyle,
+  exportNoteStyle,
+  exportSectionStyle,
+} from '../core/exportStyles.ts';
+import {
+  IMAGE_RESOLUTIONS,
+  formatImageSize,
+  imageResolution,
+} from '../core/imageResolution.ts';
+import type { PictureFrame } from '../core/pictureExport.ts';
+import {
+  copyPicture,
+  pictureSize,
+  savePngPicture,
+  saveSvgPicture,
+} from '../core/pictureExport.ts';
+import { sanitizeFileName } from '../core/sanitizeFileName.ts';
+
+import { ExportNameField } from './ExportNameField.tsx';
+
+export interface ExportPictureSectionProps {
+  /** The drawing a picture is taken of, as it is rendered. */
+  getDrawing: () => SVGSVGElement | null;
+  /** Which of the resolutions is picked. */
+  resolutionId: string;
+  /** Called with the resolution that was picked. */
+  onResolutionChange: (id: string) => void;
+  /**
+   * The name the name box opens on, and falls back to when it is cleared,
+   * without its extension.
+   */
+  filename: string;
+  /** What the picture is read out as in the file it is written to. */
+  label: string;
+  /**
+   * Whether the picture is the drawing inside the element or the element as it
+   * is laid out.
+   * @default 'content'
+   */
+  frame?: PictureFrame;
+  /** Called with what became of the last thing written out. */
+  onStatus: (status: string) => void;
+}
+
+/**
+ * The drawing as a picture: how big it comes out, and where it goes.
+ *
+ * The size the file will be is shown beside the resolution rather than after
+ * the fact, since that is the number the choice is made on — a figure for a
+ * paper and a thumbnail for a slide are the same drawing at very different
+ * sizes. What is measured is what the picture will be of and not whatever is on
+ * screen, so the answer does not change when the window is resized or the
+ * drawing panned.
+ * @param props - Component props.
+ * @returns The section.
+ */
+export function ExportPictureSection(props: ExportPictureSectionProps) {
+  const {
+    getDrawing,
+    resolutionId,
+    onResolutionChange,
+    filename,
+    label,
+    frame,
+    onStatus,
+  } = props;
+
+  const [name, setName] = useState(filename);
+
+  const savedName = sanitizeFileName(name, filename);
+  const { scale } = imageResolution(resolutionId);
+  const size = pictureSize(getDrawing(), scale, { frame });
+  const options = { scale, filename: savedName, label, frame };
+
+  return (
+    <section style={exportSectionStyle}>
+      <div style={resolutionStyle}>
+        <HTMLSelect
+          value={resolutionId}
+          aria-label="Resolution"
+          onChange={(event) => onResolutionChange(event.currentTarget.value)}
+        >
+          {IMAGE_RESOLUTIONS.map((resolution) => (
+            <option key={resolution.id} value={resolution.id}>
+              {resolution.label}
+            </option>
+          ))}
+        </HTMLSelect>
+        <span style={exportNoteStyle}>{formatImageSize(size)}</span>
+      </div>
+      <div style={exportButtonsStyle}>
+        <Button
+          icon="duplicate"
+          disabled={size === null}
+          text="Copy PNG"
+          onClick={() => {
+            // The rasterization is started here rather than awaited: Safari
+            // only allows a clipboard write the click itself started.
+            void copyPicture(getDrawing(), options).then(
+              (copied) =>
+                onStatus(copied ? 'Picture copied.' : 'Nothing was copied.'),
+              () => onStatus('Nothing was copied.'),
+            );
+          }}
+        />
+        <ExportNameField name={name} onChange={setName} />
+        <Button
+          icon="download"
+          disabled={size === null}
+          text="Save PNG"
+          title={`Save as ${savedName}.png`}
+          onClick={() => {
+            void savePngPicture(getDrawing(), options).then((saved) => {
+              if (saved) onStatus(`Saved as ${savedName}.png.`);
+            });
+          }}
+        />
+        <Button
+          icon="download"
+          disabled={size === null}
+          text="Save SVG"
+          title={`Save as ${savedName}.svg`}
+          onClick={() => {
+            if (saveSvgPicture(getDrawing(), options)) {
+              onStatus(`Saved as ${savedName}.svg.`);
+            }
+          }}
+        />
+      </div>
+    </section>
+  );
+}
+
+const resolutionStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+} as const;

package/src/download/ui/index.ts

@@ -11,3 +11,14 @@ export type { FigureDownloadProps } from './FigureDownload.tsx';
 export { FigureDownload } from './FigureDownload.tsx';
 export type { FigureDownloadPanelProps } from './FigureDownloadPanel.tsx';
 export { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
+
+export type { ExportDialogFrameProps } from './ExportDialogFrame.tsx';
+export { ExportDialogFrame } from './ExportDialogFrame.tsx';
+export type { ExportImageDialogProps } from './ExportImageDialog.tsx';
+export { ExportImageDialog } from './ExportImageDialog.tsx';
+export type { ExportNameFieldProps } from './ExportNameField.tsx';
+export { ExportNameField } from './ExportNameField.tsx';
+export type { ExportPictureSectionProps } from './ExportPictureSection.tsx';
+export { ExportPictureSection } from './ExportPictureSection.tsx';
+export type { DrawingBox } from './useDrawingBox.ts';
+export { useDrawingBox } from './useDrawingBox.ts';

package/src/download/ui/useDrawingBox.ts

@@ -0,0 +1,37 @@
+import { useCallback, useRef } from 'react';
+
+import { drawingIn } from '../core/stackedDrawing.ts';
+
+/** The box a picture is taken out of. */
+export interface DrawingBox {
+  /** Put on the box the drawing sits in, so it can be found again. */
+  attach: (element: HTMLElement | null) => void;
+  /**
+   * The drawing a picture is taken of, `null` when the box holds none — which
+   * is what an editor showing nothing yet, or one whose box has not been
+   * mounted, hands the export dialog.
+   */
+  getDrawing: () => SVGSVGElement | null;
+}
+
+/**
+ * Find the drawing a picture is to be taken of, when it is asked for.
+ *
+ * A drawing is laid out again on every resize, so the element itself is never
+ * held onto: what is kept is the box it sits in, and the drawing is read out of
+ * it at the moment a button is pressed. What counts as the drawing in there —
+ * the one element for an editor showing one, the panes composed for an editor
+ * showing a stack of charts — is `drawingIn`.
+ * @returns The box to attach, and the drawing inside it.
+ */
+export function useDrawingBox(): DrawingBox {
+  const box = useRef<HTMLElement | null>(null);
+
+  const attach = useCallback((element: HTMLElement | null) => {
+    box.current = element;
+  }, []);
+
+  const getDrawing = useCallback(() => drawingIn(box.current), []);
+
+  return { attach, getDrawing };
+}

package/src/error/core/describeSource.ts

@@ -0,0 +1,18 @@
+/**
+ * Name the source of a failed read.
+ *
+ * A reader is met by a user exactly once — when it fails — so what it says
+ * then is the whole of its interface, and saying it in one voice across a site
+ * matters more than in most code.
+ *
+ * A message that opens with the file's own name tells whoever dropped eleven
+ * files which of them is the problem; one that opens with `The pasted text`
+ * tells them the message is about the box they just typed into.
+ * @param fileName - The file's name, absent for a paste.
+ * @returns A subject a sentence can start with.
+ * @example
+ * `${describeSource(fileName)} holds no readable peak list.`
+ */
+export function describeSource(fileName?: string): string {
+  return fileName === undefined ? 'The pasted text' : fileName;
+}

package/src/error/core/index.ts

@@ -1 +1,2 @@
+export { describeSource } from './describeSource.ts';
 export { errorMessage, toError } from './toError.ts';

package/src/help/ui/HelpBody.tsx

@@ -20,6 +20,15 @@ export interface HelpExample {
   note?: string;
 }
 
+/**
+ * Help written as prose: one paragraph, or several.
+ *
+ * Several because an explanation worth reading is rarely one thought, and a
+ * dozen sentences run together into one block is a wall nobody reads to the
+ * end — which is the same as not having written it.
+ */
+export type HelpText = string | readonly string[];
+
 /** Everything a piece of help says, wherever it is shown. */
 export interface HelpContent {
   /**
@@ -28,7 +37,8 @@ export interface HelpContent {
    */
   title?: string;
   /**
-   * The explanation: one or two sentences, or any content of the site's own.
+   * The explanation: one or two sentences, any content of the site's own, or
+   * an array of strings, which is set as one paragraph each.
    * @default undefined
    */
   body?: ReactNode;
@@ -82,7 +92,9 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
       style={{ ...BODY_STYLE, maxWidth: width }}
     >
       {title === undefined ? null : <div style={TITLE_STYLE}>{title}</div>}
-      {body === undefined ? null : <div style={TEXT_STYLE}>{body}</div>}
+      {body === undefined ? null : (
+        <div style={TEXT_STYLE}>{paragraphsOf(body)}</div>
+      )}
       {examplesOf(example).map((item) => (
         <div key={exampleKey(item)} style={EXAMPLE_STYLE}>
           <code style={CODE_STYLE}>{item.code}</code>
@@ -110,6 +122,30 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
   );
 }
 
+/**
+ * The body, with an array of strings set as paragraphs rather than run
+ * together.
+ *
+ * React renders `['one', 'two']` as `onetwo`, which is never what a caller who
+ * wrote two sentences meant. Anything else is handed back untouched: a body
+ * built of elements is the site's own and is laid out by whoever wrote it.
+ * @param body - The body, as the caller wrote it.
+ * @returns What to render.
+ */
+function paragraphsOf(body: ReactNode): ReactNode {
+  if (!Array.isArray(body)) return body;
+  const paragraphs: string[] = [];
+  for (const piece of body) {
+    if (typeof piece !== 'string') return body;
+    paragraphs.push(piece);
+  }
+  return paragraphs.map((paragraph) => (
+    <p key={paragraph} style={PARAGRAPH_STYLE}>
+      {paragraph}
+    </p>
+  ));
+}
+
 // Two examples are only the same when all three of their parts are, and a help
 // that repeats one example has nothing to gain from drawing it twice.
 function exampleKey(example: HelpExample): string {
@@ -130,6 +166,9 @@ function examplesOf(example: HelpContent['example']): readonly HelpExample[] {
   return unique;
 }
 
+/** The gap between paragraphs is the column's, so the margin is nobody's. */
+const PARAGRAPH_STYLE = { margin: 0 } as const satisfies CSSProperties;
+
 /** How wide a piece of help is drawn when the caller does not say. */
 const DEFAULT_WIDTH = 280;
 

package/src/help/ui/index.ts

@@ -1,4 +1,9 @@
-export type { HelpBodyProps, HelpContent, HelpExample } from './HelpBody.tsx';
+export type {
+  HelpBodyProps,
+  HelpContent,
+  HelpExample,
+  HelpText,
+} from './HelpBody.tsx';
 export { HelpBody } from './HelpBody.tsx';
 export type { HelpIconProps } from './HelpIcon.tsx';
 export { HelpIcon } from './HelpIcon.tsx';