react-cheminfo 0.2.0 → 0.4.0

package/src/citation/ui/CitationMenu.tsx

@@ -1,76 +1,76 @@
 import { Menu, MenuDivider, MenuItem } from '@blueprintjs/core';
 import { SvgLogoDoi } from 'cheminfo-font';
 import type { CSSProperties, ReactElement } from 'react';
-import { useEffect, useRef, useState } from 'react';
 
-import { copyCitation } from '../core/clipboard.ts';
-import type { CitationFormat } from '../core/formats.ts';
-import { CITATION_DOWNLOADS, CITATION_FORMATS } from '../core/formats.ts';
+import { CITATION_DOWNLOADS } from '../core/formats.ts';
 import type { Reference } from '../core/reference.ts';
 import { doiUrl } from '../core/reference.ts';
-import type { CitationStyle } from '../core/segments.ts';
-import { CITATION_STYLES } from '../core/segments.ts';
+import type { CitedWork } from '../core/works.ts';
+import { citedReferences } from '../core/works.ts';
 
-import type { CopyState } from './entries.tsx';
-import { CopyEntry, DownloadEntry } from './entries.tsx';
-
-// How long the tick replaces the clipboard glyph of an entry after a copy.
-const FEEDBACK_MS = 1500;
+import { CopyFormatEntries } from './CopyFormatEntries.tsx';
+import { WorkEntry } from './WorkEntry.tsx';
+import { DownloadEntry } from './entries.tsx';
+import { useCopyFeedback } from './useCopyFeedback.ts';
 
 const MENU_STYLE: CSSProperties = { minWidth: 240 };
+// A set names what each work covers, which needs the room a title does not.
+const SET_MENU_STYLE: CSSProperties = { minWidth: 300 };
 const DOI_ICON_STYLE: CSSProperties = { width: 16, height: 16 };
 
-export interface CitationMenuProps {
+/** What a site asks to be cited when it is one work. */
+export interface CitedReferenceProps {
   /** The work being cited. */
   reference: Reference;
 }
 
+/** What a site asks to be cited when it is built on several works. */
+export interface CitedWorksProps {
+  /** The works being cited, in the order the site names them. */
+  works: readonly CitedWork[];
+  /**
+   * The line heading the menu, saying which of the works a reader is expected
+   * to cite.
+   * @default 'Please cite both works', or 'Please cite every work' past two
+   */
+  guidance?: string;
+}
+
+export type CitationMenuProps = CitedReferenceProps | CitedWorksProps;
+
 /**
  * What the Cite button opens: the article at its DOI, the reference copied in
- * the style a journal asks for, and the files a reference manager imports.
- * @param props - The work being cited.
+ * the style a journal asks for, and the files a reference manager imports. A
+ * site built on several works lists them all, each behind what citing it
+ * credits, and the copy and download entries then carry every reference at
+ * once.
+ * @param props - The work, or the works, being cited.
  * @returns The citation menu.
  */
 export function CitationMenu(props: CitationMenuProps): ReactElement {
-  const { reference } = props;
-  // Which entry showed feedback last, keyed `format` or `format:style`.
-  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);
-  }
-
-  function copy(format: CitationFormat, style?: CitationStyle): void {
-    const key = style === undefined ? format.id : `${format.id}:${style.id}`;
-    copyCitation(reference, format.id, style?.id).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);
-      },
-    );
+  if ('works' in props) {
+    if (props.works.length > 1) {
+      return <WorkSetMenu works={props.works} guidance={props.guidance} />;
+    }
+    const first = props.works[0];
+    if (first === undefined) {
+      throw new Error('a citation menu needs at least one work to cite');
+    }
+    return <OneWorkMenu reference={first.reference} />;
   }
+  return <OneWorkMenu reference={props.reference} />;
+}
 
-  function stateOf(key: string): CopyState | null {
-    return copied === key ? feedback(hasFailed) : null;
-  }
+/**
+ * The menu of a site asking for a single work: the article, then everything a
+ * reader does with its reference.
+ * @param props - The work being cited.
+ * @returns The menu.
+ */
+function OneWorkMenu(props: CitedReferenceProps): ReactElement {
+  const { reference } = props;
+  const feedback = useCopyFeedback();
+  const references = [reference];
 
   return (
     <Menu className="citation-menu" style={MENU_STYLE}>
@@ -83,50 +83,65 @@ export function CitationMenu(props: CitationMenuProps): ReactElement {
         rel="noreferrer"
       />
       <MenuDivider title="Copy the reference as" />
-      {CITATION_FORMATS.map((format) =>
-        format.styled ? (
-          <MenuItem
-            key={format.id}
-            icon="clipboard"
-            text={format.label}
-            label={format.hint}
-          >
-            {CITATION_STYLES.map((style) => (
-              <CopyEntry
-                key={style.id}
-                reference={reference}
-                format={format}
-                style={style}
-                state={stateOf(`${format.id}:${style.id}`)}
-                onCopy={copy}
-              />
-            ))}
-          </MenuItem>
-        ) : (
-          <CopyEntry
-            key={format.id}
-            reference={reference}
-            format={format}
-            state={stateOf(format.id)}
-            onCopy={copy}
-          />
-        ),
-      )}
+      <CopyFormatEntries references={references} feedback={feedback} />
+      <ImportSection references={references} />
+    </Menu>
+  );
+}
+
+/**
+ * The menu of a site asking for several works: what each one covers, then the
+ * whole set copied or saved at once.
+ * @param props - The works being cited, and the line heading them.
+ * @returns The menu.
+ */
+function WorkSetMenu(props: CitedWorksProps): ReactElement {
+  const { works, guidance } = props;
+  const feedback = useCopyFeedback();
+  const references = citedReferences(works);
+  const both = works.length === 2;
+
+  return (
+    <Menu className="citation-menu" style={SET_MENU_STYLE}>
+      <MenuDivider
+        title={
+          guidance ??
+          (both ? 'Please cite both works' : 'Please cite every work')
+        }
+      />
+      {works.map((work) => (
+        <WorkEntry key={work.reference.doi} work={work} feedback={feedback} />
+      ))}
+      <MenuDivider
+        title={both ? 'Copy both references as' : 'Copy every reference as'}
+      />
+      <CopyFormatEntries references={references} feedback={feedback} />
+      <ImportSection references={references} />
+    </Menu>
+  );
+}
+
+/**
+ * The files a reference manager imports, holding every reference the menu is
+ * about.
+ * @param props - The references saved by the entries.
+ * @param props.references - The works being saved.
+ * @returns The last section of the menu.
+ */
+function ImportSection(props: {
+  references: readonly Reference[];
+}): ReactElement {
+  const { references } = props;
+  return (
+    <>
       <MenuDivider title="Import into a reference manager" />
       {CITATION_DOWNLOADS.map((download) => (
         <DownloadEntry
           key={download.format}
-          reference={reference}
+          references={references}
           download={download}
         />
       ))}
-    </Menu>
+    </>
   );
 }
-
-function feedback(failed: boolean): CopyState {
-  if (failed) {
-    return { icon: 'cross', intent: 'danger', label: 'copy failed' };
-  }
-  return { icon: 'tick', intent: 'success', label: 'copied' };
-}

package/src/citation/ui/CitationPreview.tsx

@@ -1,10 +1,10 @@
 import type { CSSProperties, ReactElement } from 'react';
 
 import type { CitationFormatId } from '../core/formats.ts';
-import { formatCitation } from '../core/formats.ts';
 import type { Reference } from '../core/reference.ts';
 import type { CitationStyleId } from '../core/segments.ts';
 import { citationSegments } from '../core/segments.ts';
+import { formatCitations } from '../core/works.ts';
 
 // A BibTeX entry and a one-line citation share this box, so the text wraps and
 // the box never grows past what a tooltip can hold. The height is the last
@@ -28,10 +28,13 @@ const RICH_STYLE: CSSProperties = {
   fontSize: 12,
   lineHeight: 1.45,
 };
+// Two references pasted as HTML read as two lines, and preview as two.
+const RICH_LINE_STYLE: CSSProperties = { marginTop: 6 };
 const LINK_STYLE: CSSProperties = { color: '#8abbff' };
 
 export interface CitationPreviewProps {
-  reference: Reference;
+  /** The work, or the works, whose citation is previewed. */
+  reference: Reference | readonly Reference[];
   format: CitationFormatId;
   /** Journal style, for the formats that have one. */
   style?: CitationStyleId;
@@ -39,20 +42,27 @@ export interface CitationPreviewProps {
 
 /**
  * What a copy of the reference puts on the clipboard, as it will read once
- * pasted: the emphasis of the style for HTML, the source itself otherwise.
+ * pasted: the emphasis of the style for HTML, the source itself otherwise. A
+ * site asking for several works previews every one of them, in the order it
+ * names them.
  * @param props - Reference, format and style to preview.
  * @returns The body of the preview tooltip.
  */
 export function CitationPreview(props: CitationPreviewProps): ReactElement {
   const { reference, format, style } = props;
+  const references = Array.isArray(reference) ? reference : [reference];
 
   if (format === 'html' && style !== undefined) {
     return (
       <div className="citation-preview" style={RICH_STYLE}>
-        {citationSegments(reference, style).map((segment, index) => (
-          // The segments of one citation are a fixed list, never reordered.
-          // eslint-disable-next-line react/no-array-index-key
-          <Segment key={index} segment={segment} />
+        {references.map((one, line) => (
+          <div key={one.doi} style={line === 0 ? undefined : RICH_LINE_STYLE}>
+            {citationSegments(one, style).map((segment, index) => (
+              // The segments of one citation are a fixed list, never reordered.
+              // eslint-disable-next-line react/no-array-index-key
+              <Segment key={index} segment={segment} />
+            ))}
+          </div>
         ))}
       </div>
     );
@@ -60,7 +70,7 @@ export function CitationPreview(props: CitationPreviewProps): ReactElement {
 
   return (
     <pre className="citation-preview" style={PREVIEW_STYLE}>
-      {formatCitation(reference, format, style)}
+      {formatCitations(references, format, style)}
     </pre>
   );
 }

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';