react-cheminfo 0.3.0 → 0.4.0

package/src/citation/ui/CiteButton.tsx

@@ -2,13 +2,11 @@ import type { ReactElement } from 'react';
 
 import type { HeaderButtonProps } from '../../shared/ui/MenuButton.tsx';
 import { MenuButton } from '../../shared/ui/MenuButton.tsx';
-import type { Reference } from '../core/reference.ts';
 
+import type { CitedReferenceProps, CitedWorksProps } from './CitationMenu.tsx';
 import { CitationMenu } from './CitationMenu.tsx';
 
-export interface CiteButtonProps extends HeaderButtonProps {
-  /** The work the site asks to be cited. */
-  reference: Reference;
+interface CiteButtonBaseProps extends HeaderButtonProps {
   /**
    * Text of the button. In a compact bar it is not written, but it stays what
    * the pointer and a screen reader are told.
@@ -17,23 +15,40 @@ export interface CiteButtonProps extends HeaderButtonProps {
   label?: string;
 }
 
+/** The button of a site asking for one work. */
+export interface CiteOneWorkProps
+  extends CiteButtonBaseProps, CitedReferenceProps {}
+
+/** The button of a site asking for the several works it is built on. */
+export interface CiteWorksProps extends CiteButtonBaseProps, CitedWorksProps {}
+
+export type CiteButtonProps = CiteOneWorkProps | CiteWorksProps;
+
 /**
  * The Cite entry of a site header: one button opening the article at its DOI,
  * the reference in the style a journal asks for, and the files a reference
- * manager imports.
- * @param props - The work being cited, and how the menu opens.
+ * manager imports. A site built on several works passes `works` rather than
+ * `reference`, and each is then listed behind what citing it credits.
+ * @param props - The work or works being cited, and how the menu opens.
  * @returns The button and its menu.
  */
 export function CiteButton(props: CiteButtonProps): ReactElement {
-  const { reference, label = 'Cite', ...rest } = props;
+  const label = props.label ?? 'Cite';
 
   return (
     <MenuButton
-      {...rest}
+      compact={props.compact}
+      placement={props.placement}
       className="citation-button"
       icon="citation"
       label={label}
-      menu={<CitationMenu reference={reference} />}
+      menu={
+        'works' in props ? (
+          <CitationMenu works={props.works} guidance={props.guidance} />
+        ) : (
+          <CitationMenu reference={props.reference} />
+        )
+      }
     />
   );
 }

package/src/citation/ui/CopyFormatEntries.tsx

@@ -0,0 +1,84 @@
+import { MenuItem } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { CITATION_FORMATS } from '../core/formats.ts';
+import type { Reference } from '../core/reference.ts';
+import { CITATION_STYLES } from '../core/segments.ts';
+
+import { CopyEntry } from './entries.tsx';
+import type { CopyFeedback } from './useCopyFeedback.ts';
+
+export interface CopyFormatEntriesProps {
+  /** The works the entries copy, in reading order. */
+  references: readonly Reference[];
+  /** The copy action and the feedback of the menu these entries sit in. */
+  feedback: CopyFeedback;
+  /**
+   * What the feedback keys are prefixed with, so two lists of formats in one
+   * menu never light up together.
+   * @default ''
+   */
+  keyPrefix?: string;
+  /**
+   * Whether a format written differently by each journal opens its submenu of
+   * styles. A list nested in a work's own submenu does not: three levels of
+   * menu are more than a reader picking a reference should have to walk, so it
+   * copies in the default style instead.
+   * @default true
+   */
+  styled?: boolean;
+}
+
+/**
+ * One entry per format the references can be copied in, previewing on hover
+ * what each puts on the clipboard.
+ * @param props - The references, the feedback, and whether the styles nest.
+ * @returns The entries of the copy section.
+ */
+export function CopyFormatEntries(
+  props: CopyFormatEntriesProps,
+): ReactElement[] {
+  const { references, feedback, keyPrefix = '', styled = true } = props;
+
+  return CITATION_FORMATS.map((format) => {
+    if (!styled || !format.styled) {
+      const key = `${keyPrefix}${format.id}`;
+      return (
+        <CopyEntry
+          key={format.id}
+          references={references}
+          format={format}
+          state={feedback.stateOf(key)}
+          onCopy={() => {
+            feedback.copy(key, references, format.id);
+          }}
+        />
+      );
+    }
+
+    return (
+      <MenuItem
+        key={format.id}
+        icon="clipboard"
+        text={format.label}
+        label={format.hint}
+      >
+        {CITATION_STYLES.map((style) => {
+          const key = `${keyPrefix}${format.id}:${style.id}`;
+          return (
+            <CopyEntry
+              key={style.id}
+              references={references}
+              format={format}
+              style={style}
+              state={feedback.stateOf(key)}
+              onCopy={() => {
+                feedback.copy(key, references, format.id, style.id);
+              }}
+            />
+          );
+        })}
+      </MenuItem>
+    );
+  });
+}

package/src/citation/ui/WorkEntry.tsx

@@ -0,0 +1,80 @@
+import { MenuDivider, MenuItem } from '@blueprintjs/core';
+import { SvgLogoDoi } from 'cheminfo-font';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { CITATION_DOWNLOADS } from '../core/formats.ts';
+import { doiUrl } from '../core/reference.ts';
+import type { CitedWork } from '../core/works.ts';
+
+import { CopyFormatEntries } from './CopyFormatEntries.tsx';
+import { DownloadEntry } from './entries.tsx';
+import type { CopyFeedback } from './useCopyFeedback.ts';
+
+const DOI_ICON_STYLE: CSSProperties = { width: 16, height: 16 };
+const WHAT_STYLE: CSSProperties = { fontWeight: 600 };
+// The sentence saying what citing the work credits, read under its name: it is
+// a sentence, so it wraps rather than stretching the menu.
+const NOTE_STYLE: CSSProperties = {
+  maxWidth: 260,
+  opacity: 0.7,
+  fontSize: 11.5,
+  lineHeight: 1.35,
+  whiteSpace: 'normal',
+};
+
+export interface WorkEntryProps {
+  /** The work, and what a reader is citing it for. */
+  work: CitedWork;
+  /** The copy action and the feedback of the menu this entry sits in. */
+  feedback: CopyFeedback;
+}
+
+/**
+ * One work of a site that asks for several: what it is, what citing it credits,
+ * and a submenu holding the article at its DOI and that one reference on its
+ * own — in the default style, the styles being offered on the whole set.
+ * @param props - The work, and the feedback of its copy entries.
+ * @returns The menu entry of the work.
+ */
+export function WorkEntry(props: WorkEntryProps): ReactElement {
+  const { work, feedback } = props;
+  const { reference, what, note } = work;
+  const references = [reference];
+
+  return (
+    <MenuItem
+      icon={<SvgLogoDoi style={DOI_ICON_STYLE} />}
+      text={
+        <span>
+          <span style={WHAT_STYLE}>{what}</span>
+          {note === undefined ? null : <div style={NOTE_STYLE}>{note}</div>}
+        </span>
+      }
+      label={`${reference.journalAbbreviation} ${reference.year}`}
+    >
+      <MenuItem
+        icon={<SvgLogoDoi style={DOI_ICON_STYLE} />}
+        text="Open the article"
+        label={reference.doi}
+        href={doiUrl(reference)}
+        target="_blank"
+        rel="noreferrer"
+      />
+      <MenuDivider title="Copy this reference as" />
+      <CopyFormatEntries
+        references={references}
+        feedback={feedback}
+        keyPrefix={`${reference.doi}:`}
+        styled={false}
+      />
+      <MenuDivider title="Import this reference" />
+      {CITATION_DOWNLOADS.map((download) => (
+        <DownloadEntry
+          key={download.format}
+          references={references}
+          download={download}
+        />
+      ))}
+    </MenuItem>
+  );
+}

package/src/citation/ui/entries.tsx

@@ -2,7 +2,7 @@ import type { IconName, Intent } from '@blueprintjs/core';
 import { MenuItem, Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 
-import { downloadCitation } from '../core/download.ts';
+import { downloadCitations } from '../core/download.ts';
 import type { CitationDownload, CitationFormat } from '../core/formats.ts';
 import type { Reference } from '../core/reference.ts';
 import type { CitationStyle } from '../core/segments.ts';
@@ -27,8 +27,8 @@ export interface CopyState {
 }
 
 export interface CopyEntryProps {
-  /** The work being cited. */
-  reference: Reference;
+  /** The works being cited, in reading order. */
+  references: readonly Reference[];
   /** The format the entry copies. */
   format: CitationFormat;
   /**
@@ -38,21 +38,21 @@ export interface CopyEntryProps {
   style?: CitationStyle;
   /** Feedback of the last copy, while it is showing. */
   state: CopyState | null;
-  /** Called with what the entry copies. */
-  onCopy: (format: CitationFormat, style?: CitationStyle) => void;
+  /** Called when the entry is clicked. */
+  onCopy: () => void;
 }
 
 /**
  * One entry that copies, previewing on hover what it puts on the clipboard.
- * @param props - The reference, the format, and the feedback showing.
+ * @param props - The references, the format, and the feedback showing.
  * @returns The menu entry.
  */
 export function CopyEntry(props: CopyEntryProps): ReactElement {
-  const { reference, format, style, state, onCopy } = props;
+  const { references, format, style, state, onCopy } = props;
   const entry = style ?? format;
 
   return (
-    <PreviewTooltip reference={reference} format={format.id} style={style}>
+    <PreviewTooltip references={references} format={format.id} style={style}>
       {(targetProps) => (
         <MenuItem
           {...targetProps}
@@ -69,9 +69,7 @@ export function CopyEntry(props: CopyEntryProps): ReactElement {
             )
           }
           shouldDismissPopover={false}
-          onClick={() => {
-            onCopy(format, style);
-          }}
+          onClick={onCopy}
         />
       )}
     </PreviewTooltip>
@@ -79,8 +77,8 @@ export function CopyEntry(props: CopyEntryProps): ReactElement {
 }
 
 export interface DownloadEntryProps {
-  /** The work being saved. */
-  reference: Reference;
+  /** The works being saved, in reading order. */
+  references: readonly Reference[];
   /** The file to write, from `CITATION_DOWNLOADS`. */
   download: CitationDownload;
 }
@@ -91,9 +89,9 @@ export interface DownloadEntryProps {
  * @returns The menu entry.
  */
 export function DownloadEntry(props: DownloadEntryProps): ReactElement {
-  const { reference, download } = props;
+  const { references, download } = props;
   return (
-    <PreviewTooltip reference={reference} format={download.format}>
+    <PreviewTooltip references={references} format={download.format}>
       {(targetProps) => (
         <MenuItem
           {...targetProps}
@@ -102,7 +100,7 @@ export function DownloadEntry(props: DownloadEntryProps): ReactElement {
           text={download.label}
           labelElement={download.hint}
           onClick={() => {
-            downloadCitation(reference, download);
+            downloadCitations(references, download);
           }}
         />
       )}
@@ -113,19 +111,19 @@ export function DownloadEntry(props: DownloadEntryProps): ReactElement {
 /**
  * The hover preview of what an entry copies or saves.
  * @param props - The preview options.
- * @param props.reference - The work being written.
+ * @param props.references - The works being written.
  * @param props.format - The format the entry produces.
  * @param props.style - The journal style, for a format that has one.
  * @param props.children - The entry the preview is anchored on.
  * @returns The entry, wrapped in its preview tooltip.
  */
 function PreviewTooltip(props: {
-  reference: Reference;
+  references: readonly Reference[];
   format: CitationFormat['id'];
   style?: CitationStyle;
   children: (targetProps: Record<string, unknown>) => ReactElement;
 }): ReactElement {
-  const { reference, format, style, children } = props;
+  const { references, format, style, children } = props;
   return (
     <Tooltip
       placement="left"
@@ -133,7 +131,7 @@ function PreviewTooltip(props: {
       hoverOpenDelay={PREVIEW_OPEN_DELAY}
       content={
         <CitationPreview
-          reference={reference}
+          reference={references}
           format={format}
           style={style?.id}
         />

package/src/citation/ui/index.ts

@@ -1,6 +1,14 @@
-export type { CitationMenuProps } from './CitationMenu.tsx';
+export type {
+  CitationMenuProps,
+  CitedReferenceProps,
+  CitedWorksProps,
+} from './CitationMenu.tsx';
 export { CitationMenu } from './CitationMenu.tsx';
 export type { CitationPreviewProps } from './CitationPreview.tsx';
 export { CitationPreview } from './CitationPreview.tsx';
-export type { CiteButtonProps } from './CiteButton.tsx';
+export type {
+  CiteButtonProps,
+  CiteOneWorkProps,
+  CiteWorksProps,
+} from './CiteButton.tsx';
 export { CiteButton } from './CiteButton.tsx';

package/src/citation/ui/useCopyFeedback.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { copyCitations } from '../core/clipboard.ts';
+import type { CitationFormatId } from '../core/formats.ts';
+import type { Reference } from '../core/reference.ts';
+import type { CitationStyleId } from '../core/segments.ts';
+
+import type { CopyState } from './entries.tsx';
+
+// How long the tick replaces the clipboard glyph of an entry after a copy.
+const FEEDBACK_MS = 1500;
+
+/** Copying, with the feedback the entry that was clicked then shows. */
+export interface CopyFeedback {
+  /** The feedback showing on the entry known as `key`, if any. */
+  stateOf: (key: string) => CopyState | null;
+  /**
+   * Copy the references, and announce the outcome on the entry known as `key`.
+   */
+  copy: (
+    key: string,
+    references: readonly Reference[],
+    format: CitationFormatId,
+    style?: CitationStyleId,
+  ) => void;
+}
+
+/**
+ * Hold which entry of a citation menu was clicked last and how it went, so the
+ * tick — or the cross a denied clipboard leaves — shows on that entry alone.
+ * @returns The copy action, and the feedback of the entry that used it.
+ */
+export function useCopyFeedback(): CopyFeedback {
+  const [copied, setCopied] = useState<string | null>(null);
+  const [hasFailed, setHasFailed] = useState(false);
+  const timeout = useRef<number | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timeout.current !== null) window.clearTimeout(timeout.current);
+    };
+  }, []);
+
+  function announce(key: string, failed: boolean): void {
+    setCopied(key);
+    setHasFailed(failed);
+    if (timeout.current !== null) window.clearTimeout(timeout.current);
+    timeout.current = window.setTimeout(() => {
+      setCopied(null);
+      setHasFailed(false);
+    }, FEEDBACK_MS);
+  }
+
+  return {
+    stateOf: (key) => (copied === key ? feedback(hasFailed) : null),
+    copy: (key, references, format, style) => {
+      copyCitations(references, format, style).then(
+        () => {
+          announce(key, false);
+        },
+        () => {
+          // A denied clipboard permission is the usual cause, and the menu is
+          // the only place the user can be told about it.
+          announce(key, true);
+        },
+      );
+    },
+  };
+}
+
+function feedback(failed: boolean): CopyState {
+  if (failed) {
+    return { icon: 'cross', intent: 'danger', label: 'copy failed' };
+  }
+  return { icon: 'tick', intent: 'success', label: 'copied' };
+}

package/src/clipboard/core/index.ts

@@ -0,0 +1 @@
+export { writeToClipboard } from './writeToClipboard.ts';

package/src/clipboard/core/writeToClipboard.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+export async function writeToClipboard(text: string): Promise<boolean> {
+  const clipboard = globalThis.navigator?.clipboard;
+  if (clipboard) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // A denied permission, or a call the browser no longer considers to come
+      // from a user gesture. The textarea below still works in both cases.
+    }
+  }
+  return writeWithTextArea(text);
+}
+
+function writeWithTextArea(text: string): boolean {
+  if (typeof document === 'undefined') return false;
+
+  const textArea = document.createElement('textarea');
+  textArea.value = text;
+  textArea.setAttribute('readonly', '');
+  // Off the screen rather than hidden: a `display: none` element selects
+  // nothing, and a visible one scrolls the page as it is focused.
+  textArea.style.position = 'fixed';
+  textArea.style.top = '-9999px';
+  textArea.style.opacity = '0';
+  document.body.append(textArea);
+  textArea.select();
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the deprecated command is what the fallback is
+    return document.execCommand('copy');
+  } catch {
+    return false;
+  } finally {
+    textArea.remove();
+  }
+}

package/src/clipboard/ui/CodeBlock.tsx

@@ -0,0 +1,110 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { CopyButton } from './CopyButton.tsx';
+
+/** How a code block sits on the page it is shown in. */
+export type CodeBlockTone = 'default' | 'muted' | 'dark';
+
+const HOLDER_STYLE: CSSProperties = { position: 'relative' };
+const COPY_STYLE: CSSProperties = { position: 'absolute', top: 4, right: 4 };
+
+const BASE_PRE_STYLE: CSSProperties = {
+  margin: 0,
+  padding: '8px 10px',
+  borderRadius: 4,
+  fontSize: 12,
+  whiteSpace: 'pre-wrap',
+  overflowWrap: 'anywhere',
+};
+
+const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
+  default: {},
+  muted: { background: '#f6f7f9', border: '1px solid #d3d8de' },
+  dark: {
+    background: '#1e293b',
+    border: '1px solid #1e293b',
+    color: '#e2e8f0',
+  },
+};
+
+export interface CodeBlockProps {
+  /** The text shown, and what the copy button hands over. */
+  code: string;
+  /**
+   * What is drawn in place of the plain text — syntax coloured spans, for
+   * instance. The code itself is still what gets copied.
+   * @default undefined — the code is shown as it is
+   */
+  children?: ReactNode;
+  /**
+   * How the block is painted: nothing of its own, a light grey panel, or a
+   * dark one.
+   * @default 'default'
+   */
+  tone?: CodeBlockTone;
+  /**
+   * Whether a copy button sits in the corner of the block.
+   * @default false
+   */
+  copyable?: boolean;
+  /**
+   * Height past which the block scrolls on its own rather than pushing what
+   * follows it down the page.
+   * @default undefined — the block is as tall as its content
+   */
+  maxHeight?: number | string;
+  /**
+   * Class the holder carries, in addition to `code-block`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A block of text to hand over: the address of a page, the markup that frames
+ * it, or a sample meant to be pasted into an editor and run.
+ * @param props - The code, how it is painted, and whether it can be copied.
+ * @returns The code block.
+ */
+export function CodeBlock(props: CodeBlockProps): ReactElement {
+  const {
+    code,
+    children,
+    tone = 'default',
+    copyable = false,
+    maxHeight,
+    className,
+  } = props;
+
+  return (
+    <div className={holderClassName(tone, className)} style={HOLDER_STYLE}>
+      <pre style={preStyle(tone, copyable, maxHeight)}>{children ?? code}</pre>
+      {copyable ? (
+        <span style={COPY_STYLE}>
+          <CopyButton content={code} minimal small />
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+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,
+  maxHeight: number | string | undefined,
+): CSSProperties {
+  return {
+    ...BASE_PRE_STYLE,
+    ...TONE_STYLE[tone],
+    // The button floats over the corner, so the text stops before it.
+    ...(copyable ? { paddingRight: 42 } : {}),
+    ...(maxHeight === undefined ? {} : { maxHeight, overflowY: 'auto' }),
+  };
+}