react-cheminfo 0.1.0

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "react-cheminfo",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Assembled React components shared by the cheminfo sites: a Cite button and an ecosystem menu",
+  "author": "Luc Patiny",
+  "keywords": [
+    "react",
+    "cheminfo",
+    "citation",
+    "components"
+  ],
+  "type": "module",
+  "exports": {
+    "./core": "./lib/core.js",
+    "./ui": "./lib/ui.js"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build-storybook": "storybook build",
+    "check-types": "tsc --noEmit",
+    "clean": "rimraf coverage lib storybook-static",
+    "dev": "storybook dev -p 10815",
+    "eslint": "eslint .",
+    "eslint-fix": "eslint . --fix",
+    "prepack": "npm run tsc",
+    "prettier": "prettier --check .",
+    "prettier-write": "prettier --write .",
+    "test": "npm run test-only && npm run check-types && npm run eslint && npm run prettier",
+    "test-e2e": "playwright test",
+    "test-e2e-ui": "playwright test --ui",
+    "test-only": "vitest run --coverage",
+    "tsc": "npm run clean && npm run tsc-build",
+    "tsc-build": "tsc --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "cheminfo-font": "^1.28.0"
+  },
+  "devDependencies": {
+    "@blueprintjs/core": "^6.18.0",
+    "@playwright/test": "^1.62.1",
+    "@storybook/addon-docs": "^10.5.8",
+    "@storybook/react-vite": "^10.5.8",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@zakodium/tsconfig": "^1.0.5",
+    "eslint": "^9.39.5",
+    "eslint-config-cheminfo-react": "^20.1.0",
+    "eslint-config-cheminfo-typescript": "^22.1.0",
+    "prettier": "^3.9.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-science": "^23.0.0",
+    "rimraf": "^6.1.3",
+    "storybook": "^10.5.8",
+    "typescript": "^6.0.3",
+    "vite": "^8.2.1",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@blueprintjs/core": "^6.18.0",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "react-science": "^21.0.0 || ^22.0.0 || ^23.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cheminfo/react-cheminfo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cheminfo/react-cheminfo/issues"
+  },
+  "homepage": "https://github.com/cheminfo/react-cheminfo#readme"
+}

package/src/citation/core/clipboard.ts

@@ -0,0 +1,32 @@
+import type { CitationFormatId } from './formats.ts';
+import { formatCitation } from './formats.ts';
+import type { Reference } from './reference.ts';
+import type { CitationStyleId } from './segments.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.
+ * @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> {
+  const value = formatCitation(reference, 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)], {
+        type: 'text/plain',
+      }),
+    }),
+  ]);
+}

package/src/citation/core/download.ts

@@ -0,0 +1,27 @@
+import type { CitationDownload } from './formats.ts';
+import { citationFilename, formatCitation } from './formats.ts';
+import type { Reference } from './reference.ts';
+
+/**
+ * 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.
+ * @param reference - Reference to save.
+ * @param download - File to write, from `CITATION_DOWNLOADS`.
+ */
+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);
+}

package/src/citation/core/formats.ts

@@ -0,0 +1,169 @@
+import type { Reference } from './reference.ts';
+import { doiUrl } from './reference.ts';
+import { renderHtml, renderMarkdown, renderText } from './render.ts';
+import type { CitationStyleId } from './segments.ts';
+import { citationSegments } from './segments.ts';
+
+/** The formats the reference can be copied in. */
+export type CitationFormatId =
+  'text' | 'html' | 'markdown' | 'bibtex' | 'ris' | 'doi';
+
+/** One entry of the copy menu. */
+export interface CitationFormat {
+  id: CitationFormatId;
+  /** Name of the format. */
+  label: string;
+  /** Where that format is pasted, shown on the right of the entry. */
+  hint: string;
+  /**
+   * Whether the format is written differently by each journal style, and so
+   * opens the submenu of styles rather than copying straight away.
+   */
+  styled: boolean;
+}
+
+/**
+ * Every format offered, in the order the menu lists them. Plain text is not
+ * one of them: an HTML copy carries it as its second flavour, so a paste into
+ * a plain editor already gives the unmarked line.
+ */
+export const CITATION_FORMATS = [
+  { id: 'html', label: 'HTML', hint: 'Word, Docs, email', styled: true },
+  { id: 'markdown', label: 'Markdown', hint: 'README, issue', styled: true },
+  { id: 'bibtex', label: 'BibTeX', hint: 'LaTeX', styled: false },
+  { id: 'ris', label: 'RIS', hint: 'EndNote, Zotero', styled: false },
+  { id: 'doi', label: 'DOI link', hint: 'URL', styled: false },
+] as const satisfies readonly CitationFormat[];
+
+/** The style a format that has one is written in unless another is picked. */
+export const DEFAULT_CITATION_STYLE: CitationStyleId = 'acs';
+
+/** One entry of the download menu: a file a reference manager imports. */
+export interface CitationDownload {
+  format: CitationFormatId;
+  label: string;
+  hint: string;
+  extension: string;
+  mimeType: string;
+}
+
+/**
+ * The files offered for download. Zotero, Mendeley and EndNote all import
+ * both, and their connectors recognise the MIME types below on their own.
+ */
+export const CITATION_DOWNLOADS = [
+  {
+    format: 'ris',
+    label: 'RIS file',
+    hint: 'Zotero, Mendeley, EndNote',
+    extension: 'ris',
+    mimeType: 'application/x-research-info-systems',
+  },
+  {
+    format: 'bibtex',
+    label: 'BibTeX file',
+    hint: 'JabRef, Overleaf',
+    extension: 'bib',
+    mimeType: 'application/x-bibtex',
+  },
+] as const satisfies readonly CitationDownload[];
+
+/**
+ * Name the saved file carries, e.g. `Vanderveen2015.ris`.
+ * @param reference - Reference the file holds.
+ * @param extension - Extension of the file, without its dot.
+ * @returns The file name.
+ */
+export function citationFilename(
+  reference: Reference,
+  extension: string,
+): string {
+  return `${bibTeXKey(reference)}.${extension}`;
+}
+
+/**
+ * Render a reference in one of the citation formats.
+ * @param reference - Reference to render.
+ * @param format - Format to render it in.
+ * @param style - Journal style, for the formats that have one.
+ * @returns The citation, ready to be copied to the clipboard.
+ */
+export function formatCitation(
+  reference: Reference,
+  format: CitationFormatId,
+  style: CitationStyleId = DEFAULT_CITATION_STYLE,
+): string {
+  switch (format) {
+    case 'text':
+      return renderText(citationSegments(reference, style));
+    case 'html':
+      return renderHtml(citationSegments(reference, style));
+    case 'markdown':
+      return renderMarkdown(citationSegments(reference, style));
+    case 'bibtex':
+      return formatBibTeX(reference);
+    case 'ris':
+      return formatRis(reference);
+    case 'doi':
+      return doiUrl(reference);
+    default:
+      throw new Error(`unknown citation format: ${String(format)}`);
+  }
+}
+
+function formatBibTeX(reference: Reference): string {
+  const { title, journal, year, volume, issue, publisher, doi } = reference;
+  const { firstPage, lastPage } = reference;
+  const fields: Array<[string, string]> = [
+    ['author', authorList(reference, ' and ')],
+    ['title', title],
+    ['journal', journal],
+    ['year', String(year)],
+    ['volume', volume],
+    ['number', issue],
+    ['pages', `${firstPage}--${lastPage}`],
+    ['publisher', publisher],
+    ['doi', doi],
+    ['url', doiUrl(reference)],
+  ];
+  const body = fields
+    .map(([name, value]) => `  ${name} = {${value}},`)
+    .join('\n');
+  return `@article{${bibTeXKey(reference)},\n${body}\n}`;
+}
+
+function formatRis(reference: Reference): string {
+  const { title, journal, year, volume, issue, publisher, doi } = reference;
+  const { authors, firstPage, lastPage } = reference;
+  const lines: Array<[string, string]> = [
+    ['TY', 'JOUR'],
+    ...authors.map((author): [string, string] => [
+      'AU',
+      `${author.family}, ${author.given}`,
+    ]),
+    ['TI', title],
+    ['JO', journal],
+    ['PY', String(year)],
+    ['VL', volume],
+    ['IS', issue],
+    ['SP', firstPage],
+    ['EP', lastPage],
+    ['PB', publisher],
+    ['DO', doi],
+    ['UR', doiUrl(reference)],
+    ['ER', ''],
+  ];
+  return lines.map(([tag, value]) => `${tag}  - ${value}`).join('\n');
+}
+
+function authorList(reference: Reference, separator: string): string {
+  return reference.authors
+    .map((author) => `${author.family}, ${author.given}`)
+    .join(separator);
+}
+
+function bibTeXKey(reference: Reference): string {
+  const first = reference.authors[0];
+  const family = first === undefined ? 'reference' : first.family;
+  return `${family.replaceAll(/[^a-zA-Z]/g, '')}${reference.year}`;
+}

package/src/citation/core/index.ts

@@ -0,0 +1,23 @@
+export { copyCitation } from './clipboard.ts';
+export { downloadCitation } from './download.ts';
+export type {
+  CitationDownload,
+  CitationFormat,
+  CitationFormatId,
+} from './formats.ts';
+export {
+  CITATION_DOWNLOADS,
+  CITATION_FORMATS,
+  DEFAULT_CITATION_STYLE,
+  citationFilename,
+  formatCitation,
+} 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';

package/src/citation/core/reference.ts

@@ -0,0 +1,33 @@
+/** One author of a reference, as the citation styles need them. */
+export interface ReferenceAuthor {
+  /** Initials or first name, e.g. `J. R.`. */
+  given: string;
+  /** Family name, e.g. `Vanderveen`. */
+  family: string;
+}
+
+/** A journal article, with everything the citation formats need. */
+export interface Reference {
+  authors: readonly ReferenceAuthor[];
+  title: string;
+  /** Full journal name, e.g. `Green Chemistry`. */
+  journal: string;
+  /** Abbreviated journal name, e.g. `Green Chem.`. */
+  journalAbbreviation: string;
+  year: number;
+  volume: string;
+  issue: string;
+  firstPage: string;
+  lastPage: string;
+  doi: string;
+  publisher: string;
+}
+
+/**
+ * Resolvable address of a reference.
+ * @param reference - Reference to link to.
+ * @returns The `https://doi.org/…` URL.
+ */
+export function doiUrl(reference: Reference): string {
+  return `https://doi.org/${reference.doi}`;
+}

package/src/citation/core/render.ts

@@ -0,0 +1,78 @@
+import type { CitationSegment } from './segments.ts';
+
+/**
+ * Write the segments as they read in an email or a manuscript.
+ * @param segments - Segments of the citation.
+ * @returns The citation, with no markup at all.
+ */
+export function renderText(segments: readonly CitationSegment[]): string {
+  let result = '';
+  for (const segment of segments) {
+    result += segment.kind === 'link' ? segment.href : segment.text;
+  }
+  return result;
+}
+
+/**
+ * Write the segments as HTML, so a paste into Word or a web page keeps the
+ * italics and the bold the style asks for.
+ * @param segments - Segments of the citation.
+ * @returns The citation as one line of HTML.
+ */
+export function renderHtml(segments: readonly CitationSegment[]): string {
+  let result = '';
+  for (const segment of segments) {
+    switch (segment.kind) {
+      case 'italic':
+        result += `<em>${escapeHtml(segment.text)}</em>`;
+        break;
+      case 'bold':
+        result += `<strong>${escapeHtml(segment.text)}</strong>`;
+        break;
+      case 'link':
+        result += `<a href="${escapeHtml(segment.href)}">${escapeHtml(segment.text)}</a>`;
+        break;
+      case 'text':
+        result += escapeHtml(segment.text);
+        break;
+      default:
+        break;
+    }
+  }
+  return result;
+}
+
+/**
+ * Write the segments as Markdown, for a README or an issue.
+ * @param segments - Segments of the citation.
+ * @returns The citation as one line of Markdown.
+ */
+export function renderMarkdown(segments: readonly CitationSegment[]): string {
+  let result = '';
+  for (const segment of segments) {
+    switch (segment.kind) {
+      case 'italic':
+        result += `*${segment.text}*`;
+        break;
+      case 'bold':
+        result += `**${segment.text}**`;
+        break;
+      case 'link':
+        result += `[${segment.text}](${segment.href})`;
+        break;
+      case 'text':
+        result += segment.text;
+        break;
+      default:
+        break;
+    }
+  }
+  return result;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}

package/src/citation/core/segments.ts

@@ -0,0 +1,170 @@
+import type { Reference } from './reference.ts';
+import { doiUrl } from './reference.ts';
+
+/** One piece of a written reference, with the emphasis its style asks for. */
+export type CitationSegment =
+  | { kind: 'text' | 'italic' | 'bold'; text: string }
+  | { kind: 'link'; text: string; href: string };
+
+/** The journal styles the reference can be written in. */
+export type CitationStyleId = 'acs' | 'nature' | 'rsc' | 'wiley';
+
+/** One entry of the style submenu. */
+export interface CitationStyle {
+  id: CitationStyleId;
+  /** Name of the style. */
+  label: string;
+  /** Journals that ask for it, shown on the right of the entry. */
+  hint: string;
+}
+
+/** Every style offered, in the order the menu lists them. */
+export const CITATION_STYLES = [
+  { id: 'acs', label: 'ACS', hint: 'JACS, Org. Lett.' },
+  { id: 'nature', label: 'Nature', hint: 'Nature, Nat. Chem.' },
+  { id: 'rsc', label: 'RSC', hint: 'Chem. Sci., Green Chem.' },
+  { id: 'wiley', label: 'Wiley', hint: 'Angew. Chem., Chem. Eur. J.' },
+] as const satisfies readonly CitationStyle[];
+
+/**
+ * Write a reference in one journal style, as the pieces every output format
+ * then renders with its own emphasis.
+ * @param reference - Reference to write.
+ * @param style - Style to write it in.
+ * @returns The segments of the citation, in reading order.
+ */
+export function citationSegments(
+  reference: Reference,
+  style: CitationStyleId,
+): CitationSegment[] {
+  switch (style) {
+    case 'acs':
+      return acs(reference);
+    case 'nature':
+      return nature(reference);
+    case 'rsc':
+      return rsc(reference);
+    case 'wiley':
+      return wiley(reference);
+    default:
+      throw new Error(`unknown citation style: ${String(style)}`);
+  }
+}
+
+function acs(reference: Reference): CitationSegment[] {
+  const { title, journalAbbreviation, year, volume } = reference;
+  return [
+    text(`${familyFirst(reference, '; ')} ${title}. `),
+    italic(journalAbbreviation),
+    text(' '),
+    bold(String(year)),
+    text(', '),
+    italic(volume),
+    text(`, ${pageRange(reference)}. `),
+    doiLink(reference),
+  ];
+}
+
+function nature(reference: Reference): CitationSegment[] {
+  const { title, journalAbbreviation, year, volume } = reference;
+  return [
+    text(`${familyFirstAmpersand(reference)} ${title}. `),
+    italic(journalAbbreviation),
+    text(' '),
+    bold(volume),
+    text(`, ${pageRange(reference)} (${year}). `),
+    doiLink(reference),
+  ];
+}
+
+function rsc(reference: Reference): CitationSegment[] {
+  const { journalAbbreviation, year, volume } = reference;
+  return [
+    text(`${initialsFirst(reference, ' and ')}, `),
+    italic(journalAbbreviation),
+    text(`, ${year}, `),
+    bold(volume),
+    text(`, ${pageRange(reference)}. `),
+    doiLink(reference),
+  ];
+}
+
+function wiley(reference: Reference): CitationSegment[] {
+  const { journalAbbreviation, year, volume } = reference;
+  return [
+    text(`${initialsFirst(reference, ', ')}, `),
+    italic(journalAbbreviation),
+    text(' '),
+    bold(String(year)),
+    text(', '),
+    italic(volume),
+    text(`, ${pageRange(reference)}. `),
+    doiLink(reference),
+  ];
+}
+
+function text(value: string): CitationSegment {
+  return { kind: 'text', text: value };
+}
+
+function italic(value: string): CitationSegment {
+  return { kind: 'italic', text: value };
+}
+
+function bold(value: string): CitationSegment {
+  return { kind: 'bold', text: value };
+}
+
+function doiLink(reference: Reference): CitationSegment {
+  return {
+    kind: 'link',
+    text: `doi:${reference.doi}`,
+    href: doiUrl(reference),
+  };
+}
+
+/**
+ * `Vanderveen, J. R.; Patiny, L.` — the family name leads.
+ * @param reference - The work being written.
+ * @param separator - What goes between two authors.
+ * @returns The authors, as one string.
+ */
+function familyFirst(reference: Reference, separator: string): string {
+  return reference.authors
+    .map((author) => `${author.family}, ${author.given}`)
+    .join(separator);
+}
+
+/**
+ * The same, with the last author introduced by an ampersand.
+ * @param reference - The work being written.
+ * @returns The authors, as one string.
+ */
+function familyFirstAmpersand(reference: Reference): string {
+  const names = reference.authors.map(
+    (author) => `${author.family}, ${author.given}`,
+  );
+  const last = names.at(-1);
+  if (names.length < 2 || last === undefined) return names.join(', ');
+  return `${names.slice(0, -1).join(', ')} & ${last}`;
+}
+
+/**
+ * `J. R. Vanderveen, L. Patiny` — the initials lead.
+ * @param reference - The work being written.
+ * @param lastSeparator - What introduces the last author.
+ * @returns The authors, as one string.
+ */
+function initialsFirst(reference: Reference, lastSeparator: string): string {
+  const names = reference.authors.map(
+    (author) => `${author.given} ${author.family}`,
+  );
+  const last = names.at(-1);
+  if (names.length < 2 || last === undefined) return names.join(', ');
+  return `${names.slice(0, -1).join(', ')}${lastSeparator}${last}`;
+}
+
+function pageRange(reference: Reference): string {
+  // En dash: what every style asks for in a page range.
+  return `${reference.firstPage}–${reference.lastPage}`;
+}