react-cheminfo 0.3.0 → 0.4.0

package/src/chrome/ui/index.ts

@@ -0,0 +1,11 @@
+export type { NavItem } from './navItem.ts';
+export type { NavLinkProps } from './NavLink.tsx';
+export { NavLink } from './NavLink.tsx';
+export type { NavMenuButtonProps } from './NavMenuButton.tsx';
+export { NavMenuButton } from './NavMenuButton.tsx';
+export type { SiteFooterProps } from './SiteFooter.tsx';
+export { SiteFooter } from './SiteFooter.tsx';
+export type { SiteHeaderProps } from './SiteHeader.tsx';
+export { SiteHeader } from './SiteHeader.tsx';
+export type { UseCompactHeaderOptions } from './useCompactHeader.ts';
+export { useCompactHeader } from './useCompactHeader.ts';

package/src/chrome/ui/navItem.ts

@@ -0,0 +1,60 @@
+import type { IconName } from '@blueprintjs/core';
+import type { MouseEvent, ReactNode } from 'react';
+
+/**
+ * One entry of a site's chrome: a page in the bar, a utility beside it, or a
+ * line of a header menu. It is a plain description, so the same array feeds the
+ * bar, the menu it overflows into, and a site's own renderer.
+ */
+export interface NavItem {
+  /** What tells this entry apart, and what the active entry is named by. */
+  id: string;
+  /** What the entry reads. */
+  label: ReactNode;
+  /**
+   * The address the entry opens. Writing it keeps the entry a real link, so a
+   * crawler walks the site and a middle click opens a tab of its own, even when
+   * the plain click is taken over by `onSelect`.
+   * @default undefined
+   */
+  href?: string;
+  /**
+   * Glyph before the label, drawn at 14 px.
+   * @default undefined
+   */
+  icon?: IconName;
+  /**
+   * What the pointer is told, and what names the entry to a screen reader when
+   * the label is not text.
+   * @default undefined
+   */
+  title?: string;
+  /**
+   * Whether the address leaves the site, in which case it opens in a tab of its
+   * own.
+   * @default false
+   */
+  external?: boolean;
+  /**
+   * What the site does when the entry is picked. An entry that also carries an
+   * `href` takes over the plain click only — a modified one is left to the
+   * browser.
+   * @default undefined
+   */
+  onSelect?: () => void;
+  /**
+   * What follows the label: a count, a tag, anything the entry reports.
+   * @default undefined
+   */
+  after?: ReactNode;
+}
+
+/**
+ * Whether a click asked the browser for something other than following the link
+ * in place — a tab of its own, a window, a download.
+ * @param event - The click on the entry.
+ * @returns True when the browser is to be left alone.
+ */
+export function isModifiedClick(event: MouseEvent): boolean {
+  return event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+}

package/src/chrome/ui/useCompactHeader.ts

@@ -0,0 +1,81 @@
+import type { RefObject } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
+
+// Below this the bar has run out of room: the utilities keep their icons and
+// give up their labels rather than pushing the pages off the edge.
+const COMPACT_MAX_WIDTH = 1000;
+
+export interface UseCompactHeaderOptions {
+  /**
+   * Width in pixels at or below which the bar counts as narrow.
+   * @default 1000
+   */
+  maxWidth?: number;
+}
+
+/**
+ * Whether the bar has run out of room, so its utilities should be reduced to
+ * their icons and its page list allowed to fold away.
+ *
+ * The bar is measured rather than the window whenever a reference to it is
+ * given, so a tool sitting beside a panel folds on its own width; with no
+ * reference, or before the first paint, the window is what is read.
+ * @param ref - The bar itself, usually the `app-header__inner` element.
+ * @param options - The width at which the bar counts as narrow.
+ * @returns True while the bar is too narrow to write every label.
+ */
+export function useCompactHeader(
+  ref?: RefObject<HTMLElement | null>,
+  options: UseCompactHeaderOptions = {},
+): boolean {
+  const { maxWidth = COMPACT_MAX_WIDTH } = options;
+
+  const subscribe = useCallback(
+    (onChange: () => void) => watchWidth(ref?.current ?? null, onChange),
+    [ref],
+  );
+  const getSnapshot = useCallback(
+    () => isCompactBar(ref?.current ?? null, maxWidth),
+    [ref, maxWidth],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, notCompact);
+}
+
+/**
+ * Whether a bar of this width has run out of room. An element that has not been
+ * laid out yet, and a page with no window to measure, are both taken as roomy:
+ * a bar that flashes its icons before its labels is worse than one that never
+ * folds.
+ * @param element - The bar, when there is one to measure.
+ * @param maxWidth - Width at or below which it counts as narrow.
+ * @returns True when the bar is narrow.
+ */
+export function isCompactBar(
+  element: HTMLElement | null,
+  maxWidth = COMPACT_MAX_WIDTH,
+): boolean {
+  const measured = element === null ? 0 : element.clientWidth;
+  const width = measured > 0 ? measured : globalThis.innerWidth;
+
+  if (!Number.isFinite(width) || width <= 0) return false;
+  return width <= maxWidth;
+}
+
+function watchWidth(
+  element: HTMLElement | null,
+  onChange: () => void,
+): () => void {
+  if (element !== null && typeof ResizeObserver === 'function') {
+    const observer = new ResizeObserver(onChange);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }
+
+  globalThis.addEventListener('resize', onChange);
+  return () => globalThis.removeEventListener('resize', onChange);
+}
+
+function notCompact(): boolean {
+  return false;
+}

package/src/citation/core/clipboard.ts

@@ -1,32 +1,48 @@
 import type { CitationFormatId } from './formats.ts';
-import { formatCitation } from './formats.ts';
 import type { Reference } from './reference.ts';
 import type { CitationStyleId } from './segments.ts';
+import { formatCitations } from './works.ts';
 
 /**
- * Put a reference on the clipboard. HTML goes on in both flavours, so a paste
- * into Word or Google Docs keeps the emphasis of the style while a plain text
- * editor still receives a readable line rather than the markup.
- * @param reference - Reference to copy.
- * @param format - Format to copy it in.
+ * Put every reference a site asks for on the clipboard, in one value. HTML goes
+ * on in both flavours, so a paste into Word or Google Docs keeps the emphasis of
+ * the style while a plain text editor still receives readable lines rather than
+ * the markup.
+ * @param references - References to copy, in reading order.
+ * @param format - Format to copy them in.
  * @param style - Journal style, for the formats that have one.
- * @returns Resolves once the clipboard holds the citation.
+ * @returns Resolves once the clipboard holds the citations.
  */
-export function copyCitation(
-  reference: Reference,
+export function copyCitations(
+  references: readonly Reference[],
   format: CitationFormatId,
   style?: CitationStyleId,
 ): Promise<void> {
-  const value = formatCitation(reference, format, style);
+  const value = formatCitations(references, format, style);
   if (format !== 'html' || typeof ClipboardItem === 'undefined') {
     return navigator.clipboard.writeText(value);
   }
   return navigator.clipboard.write([
     new ClipboardItem({
       'text/html': new Blob([value], { type: 'text/html' }),
-      'text/plain': new Blob([formatCitation(reference, 'text', style)], {
+      'text/plain': new Blob([formatCitations(references, 'text', style)], {
         type: 'text/plain',
       }),
     }),
   ]);
 }
+
+/**
+ * Put one reference on the clipboard.
+ * @param reference - Reference to copy.
+ * @param format - Format to copy it in.
+ * @param style - Journal style, for the formats that have one.
+ * @returns Resolves once the clipboard holds the citation.
+ */
+export function copyCitation(
+  reference: Reference,
+  format: CitationFormatId,
+  style?: CitationStyleId,
+): Promise<void> {
+  return copyCitations([reference], format, style);
+}

package/src/citation/core/download.ts

@@ -1,11 +1,31 @@
+import { downloadBlob } from '../../download/core/downloadBlob.ts';
+
 import type { CitationDownload } from './formats.ts';
-import { citationFilename, formatCitation } from './formats.ts';
 import type { Reference } from './reference.ts';
+import { citationsFilename, formatCitations } from './works.ts';
+
+/**
+ * Save every reference a site asks for as the one file a reference manager
+ * imports — both formats hold several entries, so a site asking for two works
+ * hands out one file with both. The MIME type is the one Zotero, Mendeley and
+ * EndNote recognise, so opening the saved file hands it to whichever of them is
+ * installed.
+ * @param references - References to save, in reading order.
+ * @param download - File to write, from `CITATION_DOWNLOADS`.
+ */
+export function downloadCitations(
+  references: readonly Reference[],
+  download: CitationDownload,
+): void {
+  const content = formatCitations(references, download.format);
+  downloadBlob(
+    new Blob([content], { type: download.mimeType }),
+    citationsFilename(references, download.extension),
+  );
+}
 
 /**
- * Save the reference as the file a reference manager imports. The MIME type
- * is the one Zotero, Mendeley and EndNote recognise, so opening the saved
- * file hands it to whichever of them is installed.
+ * Save one reference as the file a reference manager imports.
  * @param reference - Reference to save.
  * @param download - File to write, from `CITATION_DOWNLOADS`.
  */
@@ -13,15 +33,5 @@ export function downloadCitation(
   reference: Reference,
   download: CitationDownload,
 ): void {
-  const content = formatCitation(reference, download.format);
-  const url = URL.createObjectURL(
-    new Blob([content], { type: download.mimeType }),
-  );
-  const anchor = document.createElement('a');
-  anchor.href = url;
-  anchor.download = citationFilename(reference, download.extension);
-  document.body.append(anchor);
-  anchor.click();
-  anchor.remove();
-  URL.revokeObjectURL(url);
+  downloadCitations([reference], download);
 }

package/src/citation/core/index.ts

@@ -1,5 +1,5 @@
-export { copyCitation } from './clipboard.ts';
-export { downloadCitation } from './download.ts';
+export { copyCitation, copyCitations } from './clipboard.ts';
+export { downloadCitation, downloadCitations } from './download.ts';
 export type {
   CitationDownload,
   CitationFormat,
@@ -14,10 +14,15 @@ export {
 } from './formats.ts';
 export type { Reference, ReferenceAuthor } from './reference.ts';
 export { doiUrl } from './reference.ts';
-export { renderHtml, renderMarkdown, renderText } from './render.ts';
 export type {
   CitationSegment,
   CitationStyle,
   CitationStyleId,
 } from './segments.ts';
 export { CITATION_STYLES, citationSegments } from './segments.ts';
+export type { CitedWork } from './works.ts';
+export {
+  citationsFilename,
+  citedReferences,
+  formatCitations,
+} from './works.ts';

package/src/citation/core/works.ts

@@ -0,0 +1,81 @@
+import type { CitationFormatId } from './formats.ts';
+import { citationFilename, formatCitation } from './formats.ts';
+import type { Reference } from './reference.ts';
+import type { CitationStyleId } from './segments.ts';
+
+/**
+ * One of the works a site asks to be cited, with the words that say which part
+ * of the site it covers: a reader handed two references has to be told what is
+ * what before they can pick one.
+ */
+export interface CitedWork {
+  /** The bibliographic record. */
+  reference: Reference;
+  /** What the work is, in a few words, e.g. `The isomer generator`. */
+  what: string;
+  /**
+   * One sentence saying what citing it credits, read under `what`.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/**
+ * What separates two citations written at once: a line for the formats that
+ * read as a list, a blank line for the ones whose entries are paragraphs.
+ */
+const SEPARATORS: Record<CitationFormatId, string> = {
+  text: '\n',
+  html: '<br>',
+  markdown: '\n\n',
+  bibtex: '\n\n',
+  ris: '\n',
+  doi: '\n',
+};
+
+/** What the file holding several references is called, before its extension. */
+const SET_FILENAME = 'references';
+
+/**
+ * The references of a list of works, in the order the site names them.
+ * @param works - The works being cited.
+ * @returns Their bibliographic records.
+ */
+export function citedReferences(works: readonly CitedWork[]): Reference[] {
+  return works.map((work) => work.reference);
+}
+
+/**
+ * Render several references in one of the citation formats, as the one value a
+ * paste or a saved file holds: an RIS or BibTeX file takes every entry, and a
+ * written citation takes one reference per line.
+ * @param references - References to render, in reading order.
+ * @param format - Format to render them in.
+ * @param style - Journal style, for the formats that have one.
+ * @returns The citations, ready to be copied to the clipboard or saved.
+ */
+export function formatCitations(
+  references: readonly Reference[],
+  format: CitationFormatId,
+  style?: CitationStyleId,
+): string {
+  return references
+    .map((reference) => formatCitation(reference, format, style))
+    .join(SEPARATORS[format]);
+}
+
+/**
+ * Name the saved file carries: the author and the year of the work when there
+ * is one, and a plain `references` when the site asks for several.
+ * @param references - References the file holds.
+ * @param extension - Extension of the file, without its dot.
+ * @returns The file name.
+ */
+export function citationsFilename(
+  references: readonly Reference[],
+  extension: string,
+): string {
+  const only = references.length === 1 ? references[0] : undefined;
+  if (only === undefined) return `${SET_FILENAME}.${extension}`;
+  return citationFilename(only, extension);
+}

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>
   );
 }