react-cheminfo 0.11.0 → 0.12.0

package/src/chrome/ui/SiteHeader.tsx

@@ -7,6 +7,7 @@ import { Wordmark } from '../../ecosystem/ui/Wordmark.tsx';
 import { SiteMark } from '../../ecosystem/ui/marks.tsx';
 
 import { NavLink } from './NavLink.tsx';
+import { NavMenuButton } from './NavMenuButton.tsx';
 import type { NavItem } from './navItem.ts';
 import { isModifiedClick } from './navItem.ts';
 
@@ -66,12 +67,22 @@ export interface SiteHeaderProps {
    * @default 'page'
    */
   width?: 'page' | 'full';
+  /**
+   * What the menu the pages fold into on a phone is called, for the pointer
+   * and a screen reader.
+   * @default 'Pages'
+   */
+  pagesLabel?: string;
 }
 
 /**
  * The bar every site of the family carries: the brand linking home at the left,
  * the pages next to it, and the utilities pushed to the right edge by the
  * spacer.
+ *
+ * The bar folds on its own width, with no hook to wire: under 48rem the
+ * utilities keep only their icons, under 36rem the pages fold into one menu,
+ * and under 22rem the name gives way to the mark.
  * @param props - The site, its pages, its utilities, and whether the page is
  * framed in another site.
  * @returns The bar, or nothing at all on an embedded page.
@@ -88,6 +99,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
     onHome,
     markSize = 28,
     width = 'page',
+    pagesLabel = 'Pages',
   } = props;
 
   if (embedded) return null;
@@ -121,6 +133,17 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
             </Fragment>
           ))}
         </nav>
+        {nav.length > 1 ? (
+          <div className="app-header-nav-menu">
+            <NavMenuButton
+              label={pagesLabel}
+              icon="menu"
+              compact
+              items={nav}
+              activeId={activeId}
+            />
+          </div>
+        ) : null}
         <span className="spacer" />
         {actions === undefined ? null : (
           <div className="app-header-actions">{actions}</div>

package/src/chrome/ui/navItem.ts

@@ -1,5 +1,5 @@
 import type { IconName } from '@blueprintjs/core';
-import type { MouseEvent, ReactNode } from 'react';
+import type { MouseEvent, ReactElement, ReactNode } from 'react';
 
 /**
  * One entry of a site's chrome: a page in the bar, a utility beside it, or a
@@ -19,10 +19,12 @@ export interface NavItem {
    */
   href?: string;
   /**
-   * Glyph before the label, drawn at 14 px.
+   * Glyph before the label, drawn at 14 px: a Blueprint icon name, or an
+   * element such as the site's own mark. An entry with a glyph is the kind that
+   * keeps only it when the bar runs out of room.
    * @default undefined
    */
-  icon?: IconName;
+  icon?: IconName | ReactElement;
   /**
    * What the pointer is told, and what names the entry to a screen reader when
    * the label is not text.

package/src/citation/core/index.ts

@@ -12,6 +12,7 @@ export {
   citationFilename,
   formatCitation,
 } from './formats.ts';
+export { OPENCHEMLIB_PAPER, OPENCHEMLIB_WORK } from './openchemlibPaper.ts';
 export { PLATFORM_PAPER, PLATFORM_WORK } from './platformPaper.ts';
 export type { Reference, ReferenceAuthor } from './reference.ts';
 export { doiUrl } from './reference.ts';

package/src/citation/core/openchemlibPaper.ts

@@ -0,0 +1,33 @@
+import type { Reference } from './reference.ts';
+import type { CitedWork } from './works.ts';
+
+/**
+ * The paper OpenChemLib's authors ask to be cited for the toolkit: it was
+ * published as the chemistry core of DataWarrior.
+ */
+export const OPENCHEMLIB_PAPER: Reference = {
+  authors: [
+    { given: 'T.', family: 'Sander' },
+    { given: 'J.', family: 'Freyss' },
+    { given: 'M.', family: 'von Korff' },
+    { given: 'C.', family: 'Rufener' },
+  ],
+  title:
+    'DataWarrior: an open-source program for chemistry aware data visualization and analysis',
+  journal: 'Journal of Chemical Information and Modeling',
+  journalAbbreviation: 'J. Chem. Inf. Model.',
+  year: 2015,
+  volume: '55',
+  issue: '2',
+  firstPage: '460',
+  lastPage: '473',
+  doi: '10.1021/ci500588j',
+  publisher: 'American Chemical Society',
+};
+
+/** OpenChemLib, for a site whose chemistry it computes. */
+export const OPENCHEMLIB_WORK: CitedWork = {
+  reference: OPENCHEMLIB_PAPER,
+  what: 'OpenChemLib',
+  note: 'Cite it for the cheminformatics toolkit every structure here goes through.',
+};

package/src/citation/core/platformPaper.ts

@@ -22,8 +22,8 @@ export const PLATFORM_PAPER: Reference = {
 };
 
 /**
- * The platform paper as the second work a site asks to be cited, after the work
- * the tool itself implements.
+ * The platform paper as the first work every site asks to be cited, before the
+ * works the tool itself implements.
  */
 export const PLATFORM_WORK: CitedWork = {
   reference: PLATFORM_PAPER,

package/src/clipboard/core/clipboardItem.ts

@@ -0,0 +1,28 @@
+/**
+ * Put one item on the clipboard through the async Clipboard API, without ever
+ * throwing.
+ *
+ * The item is built and the write started before anything is awaited: Safari
+ * only accepts a clipboard write that the click itself started, so a value
+ * still being produced — a figure being rasterized — has to go in as a promise
+ * the clipboard awaits, never be awaited first.
+ * @param items - The item's representations, keyed by MIME type.
+ * @returns Whether the clipboard took the item; `false` where the API or `ClipboardItem` is missing, or the write was refused.
+ */
+export async function writeClipboardItem(
+  items: Record<string, Blob | Promise<Blob>>,
+): Promise<boolean> {
+  const clipboard = globalThis.navigator?.clipboard;
+  if (
+    typeof clipboard?.write !== 'function' ||
+    typeof ClipboardItem === 'undefined'
+  ) {
+    return false;
+  }
+  try {
+    await clipboard.write([new ClipboardItem(items)]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/clipboard/core/index.ts

@@ -1 +1,4 @@
+export type { WriteBlobToClipboardOptions } from './writeBlobToClipboard.ts';
+export { writeBlobToClipboard } from './writeBlobToClipboard.ts';
+export type { ClipboardContent, ClipboardText } from './writeToClipboard.ts';
 export { writeToClipboard } from './writeToClipboard.ts';

package/src/clipboard/core/writeBlobToClipboard.ts

@@ -0,0 +1,43 @@
+import { writeClipboardItem } from './clipboardItem.ts';
+
+const DEFAULT_TYPE = 'image/png';
+
+/** How {@link writeBlobToClipboard} labels what it writes. */
+export interface WriteBlobToClipboardOptions {
+  /**
+   * The MIME type the clipboard is told the data has. Browsers accept
+   * `image/png` everywhere; other image types only in some of them.
+   * @default the blob's own type, or 'image/png' when it has none or is still a promise
+   */
+  type?: string;
+}
+
+/**
+ * Put an image — a figure, a rendered formula — on the clipboard, without ever
+ * throwing at the caller.
+ *
+ * Hand over the promise of the image rather than awaiting it first, e.g.
+ * `writeBlobToClipboard(renderPng(figure))` straight from the click handler:
+ * Safari only accepts a clipboard write the click itself started, and awaiting
+ * a rasterization first is enough to lose that.
+ * @param blob - The image, or the promise of it.
+ * @param options - See {@link WriteBlobToClipboardOptions}.
+ * @returns Whether the clipboard took it; `false` outside a secure context, in a browser whose clipboard takes text only, or when the image could not be produced.
+ */
+export function writeBlobToClipboard(
+  blob: Blob | Promise<Blob>,
+  options: WriteBlobToClipboardOptions = {},
+): Promise<boolean> {
+  if (blob instanceof Promise) {
+    // The clipboard reports a failed image as `false`; the promise itself must
+    // not also surface as an unhandled rejection.
+    blob.catch(() => undefined);
+  }
+  const type = options.type ?? ownType(blob) ?? DEFAULT_TYPE;
+  return writeClipboardItem({ [type]: blob });
+}
+
+function ownType(blob: Blob | Promise<Blob>): string | undefined {
+  if (blob instanceof Promise || blob.type === '') return undefined;
+  return blob.type;
+}

package/src/clipboard/core/writeToClipboard.ts

@@ -1,14 +1,46 @@
+import { writeClipboardItem } from './clipboardItem.ts';
+
+/** Text for the clipboard, with a rich rendering of it beside. */
+export interface ClipboardText {
+  /** The plain text, which every place it is pasted into can read. */
+  text: string;
+  /**
+   * The same content as HTML, which a word processor pastes with its
+   * emphasis and links; a plain text editor still receives `text`.
+   * @default undefined — only the text is written
+   */
+  html?: string;
+}
+
+/** What {@link writeToClipboard} puts on the clipboard: text, or text with its HTML. */
+export type ClipboardContent = string | ClipboardText;
+
 /**
  * Put a piece of text on the clipboard, without ever throwing at the caller.
  *
- * The async Clipboard API is tried first and a hidden textarea is the fallback,
- * which is what a page served over plain HTTP, an older Safari, or a browser
- * that refused the permission is left with. A refusal is an outcome the caller
- * shows rather than an error it has to catch, so both paths resolve.
- * @param text - What to put on the clipboard.
- * @returns Whether the clipboard now holds the text.
+ * With `html`, both renderings go on as one item, so a paste into Word or
+ * Google Docs keeps the formatting. Where that is refused, or for plain text,
+ * the async Clipboard API is tried and a hidden textarea is the fallback, which
+ * is what a page served over plain HTTP, an older Safari, or a browser that
+ * refused the permission is left with. A refusal is an outcome the caller
+ * shows rather than an error it has to catch, so every path resolves.
+ * @param content - The text, or the text and its HTML.
+ * @returns Whether the clipboard now holds the content — at least as text.
  */
-export async function writeToClipboard(text: string): Promise<boolean> {
+export async function writeToClipboard(
+  content: ClipboardContent,
+): Promise<boolean> {
+  const text = typeof content === 'string' ? content : content.text;
+  const html = typeof content === 'string' ? undefined : content.html;
+
+  if (html !== undefined && typeof Blob !== 'undefined') {
+    const written = await writeClipboardItem({
+      'text/html': new Blob([html], { type: 'text/html' }),
+      'text/plain': new Blob([text], { type: 'text/plain' }),
+    });
+    if (written) return true;
+  }
+
   const clipboard = globalThis.navigator?.clipboard;
   if (clipboard) {
     try {

package/src/clipboard/ui/CodeBlock.tsx

@@ -1,5 +1,8 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
 import { CopyButton } from './CopyButton.tsx';
 
 /** How a code block sits on the page it is shown in. */
@@ -20,8 +23,8 @@ const BASE_PRE_STYLE: CSSProperties = {
 const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
   default: {},
   muted: {
-    background: 'var(--surface-sunken, #f6f7f9)',
-    border: '1px solid var(--border, #d3d8de)',
+    background: TOKEN.surfaceSunken,
+    border: `1px solid ${TOKEN.border}`,
   },
   dark: {
     background: '#1e293b',
@@ -30,6 +33,7 @@ const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
   },
 };
 
+/** What {@link CodeBlock} shows, how it is painted, and whether it copies. */
 export interface CodeBlockProps {
   /** The text shown, and what the copy button hands over. */
   code: string;
@@ -80,7 +84,14 @@ export function CodeBlock(props: CodeBlockProps): ReactElement {
   } = props;
 
   return (
-    <div className={holderClassName(tone, className)} style={HOLDER_STYLE}>
+    <div
+      className={joinClassNames(
+        'code-block',
+        tone !== 'default' && `code-block--${tone}`,
+        className,
+      )}
+      style={HOLDER_STYLE}
+    >
       <pre style={preStyle(tone, copyable, maxHeight)}>{children ?? code}</pre>
       {copyable ? (
         <span style={COPY_STYLE}>
@@ -91,13 +102,6 @@ export function CodeBlock(props: CodeBlockProps): ReactElement {
   );
 }
 
-function holderClassName(tone: CodeBlockTone, className?: string): string {
-  const names = ['code-block'];
-  if (tone !== 'default') names.push(`code-block--${tone}`);
-  if (className !== undefined) names.push(className);
-  return names.join(' ');
-}
-
 function preStyle(
   tone: CodeBlockTone,
   copyable: boolean,

package/src/clipboard/ui/CopyButton.tsx

@@ -1,4 +1,4 @@
-import type { IconName } from '@blueprintjs/core';
+import type { IconName, Intent } from '@blueprintjs/core';
 import { Button } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
@@ -7,6 +7,7 @@ import {
   useCopyToClipboard,
 } from './useCopyToClipboard.ts';
 
+/** What {@link CopyButton} copies, and how it reads. */
 export interface CopyButtonProps {
   /**
    * What to copy. A function is called when the button is pressed, which is
@@ -26,6 +27,11 @@ export interface CopyButtonProps {
    * @default 'Copied'
    */
   copiedLabel?: string;
+  /**
+   * Text shown while a refused copy is being reported, when there is a label.
+   * @default 'Copy failed'
+   */
+  failedLabel?: string;
   /**
    * Whether the button drops its background, for a toolbar or a code block.
    * @default false
@@ -64,7 +70,8 @@ export interface CopyButtonProps {
 }
 
 /**
- * A button that puts a piece of text on the clipboard and says so.
+ * A button that puts a piece of text on the clipboard and says so — with a
+ * tick when it worked, and a cross when the browser refused it.
  * @param props - What to copy, what the button reads, and how it looks.
  * @returns The copy button.
  */
@@ -73,6 +80,7 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
     content,
     label,
     copiedLabel = 'Copied',
+    failedLabel = 'Copy failed',
     minimal = false,
     small = false,
     icon = 'duplicate',
@@ -81,16 +89,24 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
     title = 'Copy to clipboard',
     className,
   } = props;
-  const { copied, copy } = useCopyToClipboard(resetAfter);
+  const { copied, failed, copy } = useCopyToClipboard(resetAfter);
+  const look = buttonLook({
+    copied,
+    failed,
+    icon,
+    label,
+    copiedLabel,
+    failedLabel,
+  });
 
   return (
     <Button
       className={className}
       variant={minimal ? 'minimal' : 'solid'}
       size={small ? 'small' : 'medium'}
-      icon={copied ? 'tick' : icon}
-      intent={copied ? 'success' : 'none'}
-      text={buttonText(label, copiedLabel, copied)}
+      icon={look.icon}
+      intent={look.intent}
+      text={look.text}
       disabled={disabled}
       title={title}
       aria-label={label ?? title}
@@ -101,11 +117,35 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
   );
 }
 
-function buttonText(
-  label: string | undefined,
-  copiedLabel: string,
-  copied: boolean,
-): string | undefined {
-  if (label === undefined) return undefined;
-  return copied ? copiedLabel : label;
+interface ButtonLookInput {
+  copied: boolean;
+  failed: boolean;
+  icon: IconName;
+  label: string | undefined;
+  copiedLabel: string;
+  failedLabel: string;
+}
+
+function buttonLook(input: ButtonLookInput): {
+  icon: IconName;
+  intent: Intent;
+  text: string | undefined;
+} {
+  const { copied, failed, icon, label, copiedLabel, failedLabel } = input;
+  const hasLabel = label !== undefined;
+  if (copied) {
+    return {
+      icon: 'tick',
+      intent: 'success',
+      text: hasLabel ? copiedLabel : undefined,
+    };
+  }
+  if (failed) {
+    return {
+      icon: 'cross',
+      intent: 'danger',
+      text: hasLabel ? failedLabel : undefined,
+    };
+  }
+  return { icon, intent: 'none', text: label };
 }

package/src/clipboard/ui/CopyableValue.tsx

@@ -0,0 +1,138 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { MISSING_VALUE } from '../../format/core/missing.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import { CopyButton } from './CopyButton.tsx';
+
+const DEFAULT_BLOCK_HEIGHT = 160;
+
+/** What {@link CopyableValue} names, shows and copies. */
+export interface CopyableValueProps {
+  /** What the value is, written above it, e.g. `InChIKey`. */
+  label: string;
+  /** The value itself, which is also what the button copies. */
+  value: string;
+  /**
+   * A longer explanation of the label, shown on hover.
+   * @default undefined — the label carries no hover text
+   */
+  hint?: string;
+  /**
+   * Whether the value keeps its line breaks and scrolls past `maxHeight`, for
+   * a molfile or any other multi-line notation.
+   * @default false
+   */
+  block?: boolean;
+  /**
+   * Height past which a block value scrolls on its own.
+   * @default 160
+   */
+  maxHeight?: number | string;
+  /**
+   * What the pointer and a screen reader are told the button does.
+   * @default `Copy the ${label}`
+   */
+  copyTitle?: string;
+  /**
+   * What goes under the value: the links an identifier leads to, a note on it.
+   * @default undefined
+   */
+  children?: ReactNode;
+  /**
+   * Class the row carries, in addition to `copyable-value`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * One read-only value, named, with the button that copies it.
+ *
+ * A derived notation — a SMILES, an InChIKey, an accession — is only useful
+ * somewhere else, so it is shown with the single click that puts it on the
+ * clipboard, and selecting the value by hand takes all of it at once. An empty
+ * value reads as the missing marker and offers nothing to copy.
+ * @param props - See {@link CopyableValueProps}.
+ * @returns The labelled value and its copy button.
+ */
+export function CopyableValue(props: CopyableValueProps): ReactElement {
+  const {
+    label,
+    value,
+    hint,
+    block = false,
+    maxHeight = DEFAULT_BLOCK_HEIGHT,
+    copyTitle = `Copy the ${label}`,
+    children,
+    className,
+  } = props;
+  const isEmpty = value === '';
+
+  return (
+    <div
+      className={
+        className === undefined
+          ? 'copyable-value'
+          : `copyable-value ${className}`
+      }
+    >
+      <div style={HEADER_STYLE}>
+        <span
+          className="copyable-value__label"
+          style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
+          title={hint}
+        >
+          {label}
+        </span>
+        <CopyButton
+          content={value}
+          title={copyTitle}
+          disabled={isEmpty}
+          minimal
+          small
+        />
+      </div>
+      <code
+        className="copyable-value__value"
+        style={block ? { ...BLOCK_VALUE_STYLE, maxHeight } : VALUE_STYLE}
+      >
+        {isEmpty ? MISSING_VALUE : value}
+      </code>
+      {children}
+    </div>
+  );
+}
+
+const HEADER_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: TOKEN.textMuted,
+  fontSize: 12,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+const HINTED_LABEL_STYLE = {
+  ...LABEL_STYLE,
+  cursor: 'help',
+} as const satisfies CSSProperties;
+
+const VALUE_STYLE = {
+  display: 'block',
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 12,
+  overflowWrap: 'anywhere',
+  userSelect: 'all',
+} as const satisfies CSSProperties;
+
+const BLOCK_VALUE_STYLE = {
+  ...VALUE_STYLE,
+  whiteSpace: 'pre',
+  overflowWrap: 'normal',
+  overflow: 'auto',
+} as const satisfies CSSProperties;

package/src/clipboard/ui/copyFeedback.ts

@@ -0,0 +1,68 @@
+/** How the last copy went: taken by the clipboard, or refused. */
+type CopyOutcome = 'copied' | 'failed';
+
+/** What a copy leaves on screen for a moment. */
+export interface CopyFeedbackState {
+  /** How the last copy went, or `undefined` once its moment has passed. */
+  outcome: CopyOutcome | undefined;
+  /** The key the last copy was made under, so one entry of several shows it. */
+  key: string | undefined;
+}
+
+/** The state before anything was copied, and after the confirmation fades. */
+export const IDLE_COPY_FEEDBACK: CopyFeedbackState = {
+  outcome: undefined,
+  key: undefined,
+};
+
+/** The timer behind a copy confirmation. */
+export interface CopyFeedback {
+  /**
+   * Show how a copy went, replacing whatever was shown, for `resetAfter`.
+   * @param written - Whether the clipboard took it.
+   * @param key - Which of several copy actions it was.
+   */
+  announce: (written: boolean, key?: string) => void;
+  /**
+   * Stop the timer for good and clear an outcome still shown; later
+   * announcements show nothing.
+   */
+  dispose: () => void;
+}
+
+/**
+ * The confirmation a copy leaves behind, and the one timer that clears it.
+ *
+ * Kept apart from React so every copy action of the family — a button, a
+ * citation menu entry, a row of notations — confirms for the same time and
+ * leaves no timer behind once its component is gone.
+ * @param resetAfter - How long an outcome is shown, in milliseconds.
+ * @param onChange - Called with each new state.
+ * @returns The controller.
+ */
+export function createCopyFeedback(
+  resetAfter: number,
+  onChange: (state: CopyFeedbackState) => void,
+): CopyFeedback {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+
+  return {
+    announce: (written, key) => {
+      if (disposed) return;
+      clearTimeout(timer);
+      onChange({ outcome: written ? 'copied' : 'failed', key });
+      timer = setTimeout(() => {
+        timer = undefined;
+        onChange(IDLE_COPY_FEEDBACK);
+      }, resetAfter);
+    },
+    dispose: () => {
+      disposed = true;
+      if (timer === undefined) return;
+      clearTimeout(timer);
+      timer = undefined;
+      onChange(IDLE_COPY_FEEDBACK);
+    },
+  };
+}

package/src/clipboard/ui/index.ts

@@ -1,8 +1,10 @@
 export type { CodeBlockProps, CodeBlockTone } from './CodeBlock.tsx';
 export { CodeBlock } from './CodeBlock.tsx';
+export type { CopyableValueProps } from './CopyableValue.tsx';
+export { CopyableValue } from './CopyableValue.tsx';
 export type { CopyButtonProps } from './CopyButton.tsx';
 export { CopyButton } from './CopyButton.tsx';
-export type { CopyToClipboard } from './useCopyToClipboard.ts';
+export type { CopyContent, CopyToClipboard } from './useCopyToClipboard.ts';
 export {
   DEFAULT_COPY_RESET_AFTER,
   useCopyToClipboard,