react-cheminfo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cheminfo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# react-cheminfo
+
+[![NPM version][npm-image]][npm-url]
+[![build status][ci-image]][ci-url]
+[![Test coverage][codecov-image]][codecov-url]
+[![npm download][download-image]][download-url]
+
+Assembled React components shared by the `*.cheminfo.org` sites.
+
+## What it is
+
+[`react-science`](https://www.npmjs.com/package/react-science) gives us
+**primitives** — `Toolbar`, `Accordion`, `SplitPane`, `Button`. This package is
+the layer above: **assemblies**, a component you hand data to and it delivers a
+whole feature, its copy, its interactions and its logic included. A site
+normally depends on both.
+
+## Installation
+
+```console
+npm i react-cheminfo
+```
+
+`react`, `react-dom`, `@blueprintjs/core` and `react-science` are peer
+dependencies: a site already has them, and a second copy of `react-science`
+would mean two Blueprint style trees in one page.
+
+## Two entry points
+
+| Import                | Holds                                                                         |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `react-cheminfo/ui`   | the React components                                                          |
+| `react-cheminfo/core` | the framework-free logic — citation formats, the site list — with no React in |
+
+A backend serving an RIS endpoint, and every unit test of that logic, therefore
+load no React at all.
+
+The sources are organised the other way round — one folder per component
+(`src/citation`, `src/ecosystem`), each holding a `core/` and a `ui/` half — and
+`src/core.ts` and `src/ui.ts` are the barrels the two entry points point at.
+`src/shared` holds what more than one of them is built on: `MenuButton`, the
+shape every button of a site header takes, which is why `CiteButton` and
+`EcosystemButton` differ only in their glyph and their menu, and why both accept
+the `compact` and `placement` props of the exported `HeaderButtonProps`.
+
+## Components
+
+### `CiteButton`
+
+The Cite entry of a site header: one button opening the work at its DOI, copying
+its reference in the style a journal asks for, and saving the files a reference
+manager imports.
+
+```tsx
+import { CiteButton } from 'react-cheminfo/ui';
+
+<CiteButton reference={PAPER} />;
+```
+
+- **HTML** and **Markdown**, each in the four styles chemists are asked for —
+  ACS, Nature, RSC and Wiley. An HTML copy is written to the clipboard in both
+  flavours, so Word and Google Docs keep the emphasis while a plain editor
+  receives a clean line; that is why plain text is not a separate entry.
+- **BibTeX**, **RIS** and the **DOI link**, which carry no style.
+- **RIS and BibTeX files**, served with the MIME types Zotero, Mendeley and
+  EndNote recognise, so opening the saved file imports it.
+- A hover **preview** of exactly what each entry copies or saves.
+- `compact` drops the text and the caret, leaving the icon alone to open the
+  menu, for a header that has run out of room. The label stays what the pointer
+  and a screen reader are told.
+
+Adding a style means one function in `citation/core/segments.ts` and one entry
+in `CITATION_STYLES` — the three output formats and the preview follow.
+
+### `EcosystemButton`
+
+The Tools entry of a site header: one button opening every other site of the
+family, each behind its own little logo and the two colours it owns.
+
+```tsx
+import { EcosystemButton } from 'react-cheminfo/ui';
+
+<EcosystemButton currentSiteId="vcl" />;
+```
+
+- `currentSiteId` is the one thing that differs per site: that tile is shown
+  with a _you are here_ label and is not a link. Passing nothing links all ten.
+- `compact` drops the text and the caret, leaving the icon alone to open the
+  menu, for a header that has run out of room. The label stays what the pointer
+  and a screen reader are told.
+- A tile **lights up in the colour of the site it opens**, so running the
+  pointer down the grid is what makes the ten pairs of colours read.
+
+Each mark keeps the geometry of that site's own logo where it has one, redrawn
+on a plate of the site's own colour so ten marks from ten sites still read as
+one row, and carrying the site's answering colour on exactly one element —
+which is what stops it collapsing into a flat shape at 16 px.
+
+**NMRium** keeps its artwork whole: the symbol is the one from `Logo.tsx` of the
+NMRium sources, in its orange, on the plum its logo sets the rest of the
+wordmark in. **ChemCalc** is the one mark that is ours — its logo is an atom
+that is unreadable small, so the tile draws what the tool returns, an isotopic
+pattern, in ChemCalc's own indigo and teal.
+
+The colours a name is set in are the site's own and are not retuned to reach the
+4.5:1 of body text: ChemCalc's teal and NMRium's orange both land just under it,
+which is why a name is set bold, where 3:1 is the threshold.
+
+## Styling
+
+**No stylesheet, nothing for a consumer to import.** Every rule is a
+module-level `CSSProperties` constant applied with `style`, the way `react-mf`
+does it — so there is no import step, no load-order surprise, and no specificity
+fight with Blueprint, since an inline rule outranks every selector.
+
+A component never hard-codes a site's identity: what differs per site is passed
+in as props, or read from a CSS variable (`--brand`, `--brand-alt`, `--accent`)
+so each site keeps the two colours it owns.
+
+## Development
+
+```console
+npm run dev
+```
+
+opens Storybook on <http://localhost:10815> — every component of the package,
+under every prop it takes, with the controls to set them and the snippet that
+reproduces what is on show. The **Brand** toolbar retunes `--brand` /
+`--brand-alt` / `--accent` on the canvas, so you can watch a component carry a
+site's two colours. Components land there as they move into the package.
+
+A story is a `*.stories.tsx` file in `stories/`, written in CSF: a default
+export naming the component, and one export per state the sites use it in. The
+prose and the types of the controls come from the props' own JSDoc, read off the
+source by `@storybook/addon-docs`, so a component is documented by documenting
+its props — never by writing a page for it. `stories/headerButton.ts` already
+describes the controls every header button shares.
+
+```console
+npm run build-storybook   # storybook-static/
+```
+
+is what GitHub Pages serves at <https://cheminfo.github.io/react-cheminfo/>,
+built and deployed by `.github/workflows/pages.yml` on every push to `main`.
+
+## Testing
+
+Unit tests cover the framework-free half, which is where the citation formats
+and the site list live:
+
+```console
+npm run test         # vitest + type-check + eslint + prettier
+```
+
+The components themselves are almost entirely interaction — Blueprint popovers
+with hover delays, submenus, clipboard writes in two flavours, file downloads —
+so they are tested in a real browser rather than a simulated DOM:
+
+```console
+npx playwright install --with-deps chromium   # once
+npm run test-e2e                              # or test-e2e-ui to watch
+```
+
+`npm run test-e2e` starts Storybook itself and drives each story on its own
+address (`/iframe.html?id=…`), so there is nothing to launch first. It is a
+separate command from `npm run test`, because it needs a browser that a plain CI
+job does not have; its own workflow installs one.
+
+## Testing a local build
+
+Before publishing, test the **packed artifact** rather than the sources: it is
+what a site will actually install, and it is where a missing file or a wrong
+`exports` entry shows up.
+
+```console
+npm run tsc                # build lib/
+npm pack                   # react-cheminfo-0.0.0.tgz
+```
+
+Then, from a throwaway app — or from the site you are about to adopt it in:
+
+```console
+npm i ../react-cheminfo/react-cheminfo-0.0.0.tgz
+```
+
+Import from both entry points, so the check covers the framework-free half too:
+
+```tsx
+import { CITATION_STYLES, formatCitation } from 'react-cheminfo/core';
+import { CiteButton, EcosystemButton } from 'react-cheminfo/ui';
+```
+
+Reinstall the tarball after every `npm pack` — npm caches it by name and
+version, and this package stays at `0.0.0` until release-please cuts the first
+one.
+
+## [API Documentation](https://cheminfo.github.io/react-cheminfo/)
+
+## License
+
+[MIT](./LICENSE)
+
+[npm-image]: https://img.shields.io/npm/v/react-cheminfo.svg
+[npm-url]: https://www.npmjs.com/package/react-cheminfo
+[ci-image]: https://github.com/cheminfo/react-cheminfo/workflows/Node.js%20CI/badge.svg?branch=main
+[ci-url]: https://github.com/cheminfo/react-cheminfo/actions?query=workflow%3A%22Node.js+CI%22
+[codecov-image]: https://img.shields.io/codecov/c/github/cheminfo/react-cheminfo.svg
+[codecov-url]: https://codecov.io/gh/cheminfo/react-cheminfo
+[download-image]: https://img.shields.io/npm/dm/react-cheminfo.svg
+[download-url]: https://www.npmjs.com/package/react-cheminfo

package/lib/citation/core/clipboard.d.ts

@@ -0,0 +1,14 @@
+import type { CitationFormatId } 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 declare function copyCitation(reference: Reference, format: CitationFormatId, style?: CitationStyleId): Promise<void>;
+//# sourceMappingURL=clipboard.d.ts.map

package/lib/citation/core/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/citation/core/clipboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,gBAAgB,EACxB,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/lib/citation/core/clipboard.js

@@ -0,0 +1,25 @@
+import { formatCitation } from "./formats.js";
+/**
+ * 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, format, style) {
+    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',
+            }),
+        }),
+    ]);
+}
+//# sourceMappingURL=clipboard.js.map

package/lib/citation/core/clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../../../src/citation/core/clipboard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAI9C;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAoB,EACpB,MAAwB,EACxB,KAAuB;IAEvB,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACvD,IAAI,MAAM,KAAK,MAAM,IAAI,OAAO,aAAa,KAAK,WAAW,EAAE,CAAC;QAC9D,OAAO,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC;QAC/B,IAAI,aAAa,CAAC;YAChB,WAAW,EAAE,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;YACrD,YAAY,EAAE,IAAI,IAAI,CAAC,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE;gBACjE,IAAI,EAAE,YAAY;aACnB,CAAC;SACH,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/lib/citation/core/download.d.ts

@@ -0,0 +1,11 @@
+import type { CitationDownload } 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 declare function downloadCitation(reference: Reference, download: CitationDownload): void;
+//# sourceMappingURL=download.d.ts.map

package/lib/citation/core/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../../src/citation/core/download.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CAYN"}

package/lib/citation/core/download.js

@@ -0,0 +1,20 @@
+import { citationFilename, formatCitation } from "./formats.js";
+/**
+ * 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, download) {
+    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);
+}
+//# sourceMappingURL=download.js.map

package/lib/citation/core/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../../src/citation/core/download.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGhE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAoB,EACpB,QAA0B;IAE1B,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAC7B,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CACjD,CAAC;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,MAAM,CAAC,QAAQ,GAAG,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,MAAM,CAAC,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/lib/citation/core/formats.d.ts

@@ -0,0 +1,91 @@
+import type { Reference } from './reference.ts';
+import type { CitationStyleId } 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 declare const CITATION_FORMATS: readonly [{
+    readonly id: "html";
+    readonly label: "HTML";
+    readonly hint: "Word, Docs, email";
+    readonly styled: true;
+}, {
+    readonly id: "markdown";
+    readonly label: "Markdown";
+    readonly hint: "README, issue";
+    readonly styled: true;
+}, {
+    readonly id: "bibtex";
+    readonly label: "BibTeX";
+    readonly hint: "LaTeX";
+    readonly styled: false;
+}, {
+    readonly id: "ris";
+    readonly label: "RIS";
+    readonly hint: "EndNote, Zotero";
+    readonly styled: false;
+}, {
+    readonly id: "doi";
+    readonly label: "DOI link";
+    readonly hint: "URL";
+    readonly styled: false;
+}];
+/** The style a format that has one is written in unless another is picked. */
+export declare const DEFAULT_CITATION_STYLE: CitationStyleId;
+/** 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 declare const CITATION_DOWNLOADS: readonly [{
+    readonly format: "ris";
+    readonly label: "RIS file";
+    readonly hint: "Zotero, Mendeley, EndNote";
+    readonly extension: "ris";
+    readonly mimeType: "application/x-research-info-systems";
+}, {
+    readonly format: "bibtex";
+    readonly label: "BibTeX file";
+    readonly hint: "JabRef, Overleaf";
+    readonly extension: "bib";
+    readonly mimeType: "application/x-bibtex";
+}];
+/**
+ * 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 declare function citationFilename(reference: Reference, extension: string): string;
+/**
+ * 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 declare function formatCitation(reference: Reference, format: CitationFormatId, style?: CitationStyleId): string;
+//# sourceMappingURL=formats.d.ts.map

package/lib/citation/core/formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../../../src/citation/core/formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAC1B,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAE1D,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,gBAAgB,CAAC;IACrB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;EAMiB,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,EAAE,eAAuB,CAAC;AAE7D,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAeiB,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,gBAAgB,EACxB,KAAK,GAAE,eAAwC,GAC9C,MAAM,CAiBR"}

package/lib/citation/core/formats.js

@@ -0,0 +1,125 @@
+import { doiUrl } from "./reference.js";
+import { renderHtml, renderMarkdown, renderText } from "./render.js";
+import { citationSegments } from "./segments.js";
+/**
+ * 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 },
+];
+/** The style a format that has one is written in unless another is picked. */
+export const DEFAULT_CITATION_STYLE = 'acs';
+/**
+ * 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',
+    },
+];
+/**
+ * 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, extension) {
+    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, format, style = DEFAULT_CITATION_STYLE) {
+    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) {
+    const { title, journal, year, volume, issue, publisher, doi } = reference;
+    const { firstPage, lastPage } = reference;
+    const fields = [
+        ['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) {
+    const { title, journal, year, volume, issue, publisher, doi } = reference;
+    const { authors, firstPage, lastPage } = reference;
+    const lines = [
+        ['TY', 'JOUR'],
+        ...authors.map((author) => [
+            '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, separator) {
+    return reference.authors
+        .map((author) => `${author.family}, ${author.given}`)
+        .join(separator);
+}
+function bibTeXKey(reference) {
+    const first = reference.authors[0];
+    const family = first === undefined ? 'reference' : first.family;
+    return `${family.replaceAll(/[^a-zA-Z]/g, '')}${reference.year}`;
+}
+//# sourceMappingURL=formats.js.map

package/lib/citation/core/formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../../../src/citation/core/formats.ts"],"names":[],"mappings":"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"}

package/lib/citation/core/index.d.ts

@@ -0,0 +1,10 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/lib/citation/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/citation/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EACV,eAAe,EACf,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/lib/citation/core/index.js

@@ -0,0 +1,7 @@
+export { copyCitation } from "./clipboard.js";
+export { downloadCitation } from "./download.js";
+export { CITATION_DOWNLOADS, CITATION_FORMATS, DEFAULT_CITATION_STYLE, citationFilename, formatCitation, } from "./formats.js";
+export { doiUrl } from "./reference.js";
+export { renderHtml, renderMarkdown, renderText } from "./render.js";
+export { CITATION_STYLES, citationSegments } from "./segments.js";
+//# sourceMappingURL=index.js.map

package/lib/citation/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/citation/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMjD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMrE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/lib/citation/core/reference.d.ts

@@ -0,0 +1,30 @@
+/** 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 declare function doiUrl(reference: Reference): string;
+//# sourceMappingURL=reference.d.ts.map

package/lib/citation/core/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../src/citation/core/reference.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAEnD"}

package/lib/citation/core/reference.js

@@ -0,0 +1,9 @@
+/**
+ * Resolvable address of a reference.
+ * @param reference - Reference to link to.
+ * @returns The `https://doi.org/…` URL.
+ */
+export function doiUrl(reference) {
+    return `https://doi.org/${reference.doi}`;
+}
+//# sourceMappingURL=reference.js.map

package/lib/citation/core/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/citation/core/reference.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,SAAoB;IACzC,OAAO,mBAAmB,SAAS,CAAC,GAAG,EAAE,CAAC;AAC5C,CAAC"}

package/lib/citation/core/render.d.ts

@@ -0,0 +1,21 @@
+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 declare function renderText(segments: readonly CitationSegment[]): string;
+/**
+ * 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 declare function renderHtml(segments: readonly CitationSegment[]): string;
+/**
+ * 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 declare function renderMarkdown(segments: readonly CitationSegment[]): string;
+//# sourceMappingURL=render.d.ts.map