react-cheminfo 0.2.0 → 0.4.0

package/src/chrome/ui/NavMenuButton.tsx

@@ -0,0 +1,95 @@
+import type { IconName, PopoverNextProps } from '@blueprintjs/core';
+import { Icon, Menu, MenuItem, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+export interface NavMenuButtonProps {
+  /** Text of the trigger, which is also what a screen reader is told. */
+  label: string;
+  /** The pages the menu holds, in the order it lists them. */
+  items: readonly NavItem[];
+  /**
+   * Which page is on show, named by its `id`. The trigger takes the brand tint
+   * when the menu is the one holding it.
+   * @default undefined
+   */
+  activeId?: string;
+  /**
+   * Glyph before the label.
+   * @default undefined
+   */
+  icon?: IconName;
+  /**
+   * Side the menu opens on.
+   * @default 'bottom-start'
+   */
+  placement?: PopoverNextProps['placement'];
+  /**
+   * What the menu adds under the pages — a divider and an action, typically.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The pages that do not need a place of their own in the bar, folded into one
+ * menu. The trigger is dressed as a `nav-link`, so it reads as one of the
+ * entries beside it rather than as a button dropped among them.
+ * @param props - The label, the pages, the page on show, and how the menu
+ * opens.
+ * @returns The trigger and its menu.
+ */
+export function NavMenuButton(props: NavMenuButtonProps): ReactElement {
+  const {
+    label,
+    items,
+    activeId,
+    icon,
+    placement = 'bottom-start',
+    children,
+  } = props;
+
+  const holdsActive = items.some((item) => item.id === activeId);
+
+  return (
+    <PopoverNext
+      placement={placement}
+      content={
+        <Menu className="nav-menu">
+          {items.map((item) => (
+            <MenuItem
+              key={item.id}
+              icon={item.icon}
+              text={item.label}
+              // A real address, so a crawler reaching the menu can follow it
+              // and a middle click opens a tab of its own.
+              href={item.href}
+              target={item.external ? '_blank' : undefined}
+              active={item.id === activeId}
+              onClick={(event) => {
+                if (item.onSelect === undefined || isModifiedClick(event)) {
+                  return;
+                }
+                event.preventDefault();
+                item.onSelect();
+              }}
+            />
+          ))}
+          {children}
+        </Menu>
+      }
+    >
+      <button
+        type="button"
+        className={holdsActive ? 'nav-link nav-link--active' : 'nav-link'}
+        aria-label={label}
+      >
+        {icon === undefined ? null : <Icon icon={icon} size={14} />}
+        {label}
+        <Icon icon="caret-down" size={14} />
+      </button>
+    </PopoverNext>
+  );
+}

package/src/chrome/ui/SiteFooter.tsx

@@ -0,0 +1,65 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { EcosystemLinks } from '../../ecosystem/ui/EcosystemLinks.tsx';
+
+export interface SiteFooterProps {
+  /** The site the footer sits on, which is written but never linked. */
+  siteId: SiteId;
+  /**
+   * How much of each sibling site is written. `grid` gives every one its mark,
+   * its name and the line saying what it does; `row` writes the names only.
+   * @default 'grid'
+   */
+  layout?: 'grid' | 'row';
+  /**
+   * What introduces the family.
+   * @default undefined
+   */
+  heading?: string;
+  /**
+   * Whether the page is framed in another site, in which case no footer is
+   * drawn at all.
+   * @default false
+   */
+  embedded?: boolean;
+  /**
+   * What the site adds under the family — a licence line, a version, a link to
+   * the sources.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The strip under every page of the family: each sibling site as a plain link,
+ * so a crawler — and a reader with no patience for menus — walks from one of
+ * our tools to the next. It carries `no-print`, because it is chrome.
+ * @param props - The site it sits on, how much of each sibling is written, and
+ * whatever the site adds below.
+ * @returns The footer, or nothing at all on an embedded page.
+ */
+export function SiteFooter(props: SiteFooterProps): ReactElement | null {
+  const {
+    siteId,
+    layout = 'grid',
+    heading,
+    embedded = false,
+    children,
+  } = props;
+
+  if (embedded) return null;
+
+  return (
+    <footer className="app-footer no-print">
+      <div className="app-footer__inner">
+        <EcosystemLinks
+          currentSiteId={siteId}
+          layout={layout}
+          heading={heading}
+        />
+        {children}
+      </div>
+    </footer>
+  );
+}

package/src/chrome/ui/SiteHeader.tsx

@@ -0,0 +1,119 @@
+import type { ReactElement, ReactNode } from 'react';
+import { Fragment } from 'react';
+
+import { siteById } from '../../ecosystem/core/lookup.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { Wordmark } from '../../ecosystem/ui/Wordmark.tsx';
+import { SiteMark } from '../../ecosystem/ui/marks.tsx';
+
+import { NavLink } from './NavLink.tsx';
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+export interface SiteHeaderProps {
+  /** The site the bar belongs to, which draws its mark and writes its name. */
+  siteId: SiteId;
+  /** The pages, in the order the bar lists them. */
+  nav: readonly NavItem[];
+  /**
+   * Which of the pages is on show, named by its `id`.
+   * @default undefined
+   */
+  activeId?: string;
+  /**
+   * The utilities pushed to the right edge — Cite, Tools, Share, sign in. They
+   * arrive dressed as bar items, so a plain `nav-link` and a `CiteButton` read
+   * alike beside each other.
+   * @default undefined
+   */
+  actions?: ReactNode;
+  /**
+   * Draws one page the site's own way, for a bar whose entries need a tooltip
+   * or a wrapper of their own.
+   * @default undefined
+   */
+  renderNavItem?: (item: NavItem, isActive: boolean) => ReactNode;
+  /**
+   * Whether the page is framed in another site, in which case no bar is drawn
+   * at all — what a host page frames already carries its own navigation.
+   * @default false
+   */
+  embedded?: boolean;
+  /**
+   * Where the brand leads.
+   * @default '/'
+   */
+  homeHref?: string;
+  /**
+   * What the site does when the brand is picked, for a page that routes in
+   * place. A modified click is left to the browser.
+   * @default undefined
+   */
+  onHome?: () => void;
+  /**
+   * Edge of the site's mark, in pixels.
+   * @default 28
+   */
+  markSize?: number;
+}
+
+/**
+ * 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.
+ * @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.
+ */
+export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
+  const {
+    siteId,
+    nav,
+    activeId,
+    actions,
+    renderNavItem,
+    embedded = false,
+    homeHref = '/',
+    onHome,
+    markSize = 28,
+  } = props;
+
+  if (embedded) return null;
+
+  const site = siteById(siteId);
+
+  return (
+    <header className="app-header no-print">
+      <div className="app-header__inner">
+        <a
+          className="brand"
+          href={homeHref}
+          title={site.host}
+          onClick={(event) => {
+            if (onHome === undefined || isModifiedClick(event)) return;
+            event.preventDefault();
+            onHome();
+          }}
+        >
+          <SiteMark siteId={siteId} size={markSize} />
+          <Wordmark siteId={siteId} />
+        </a>
+        <nav className="app-header-nav">
+          {nav.map((item) => (
+            <Fragment key={item.id}>
+              {renderNavItem === undefined ? (
+                <NavLink item={item} active={item.id === activeId} />
+              ) : (
+                renderNavItem(item, item.id === activeId)
+              )}
+            </Fragment>
+          ))}
+        </nav>
+        <span className="spacer" />
+        {actions === undefined ? null : (
+          <div className="app-header-actions">{actions}</div>
+        )}
+      </div>
+    </header>
+  );
+}

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