@behackl/citation-js-extras 0.2.1 → 0.4.0

package/README.md

@@ -2,316 +2,116 @@
 
 ![NPM Version](https://img.shields.io/npm/v/%40behackl%2Fcitation-js-extras)
 
-Preserve custom BibTeX fields through [citation-js](https://citation.js.org/) and render academic bibliographies with linked titles, configurable badges, and more.
-
-## The problem
-
-citation-js converts BibTeX to CSL-JSON, but silently **drops all non-standard fields** during the conversion. There is no plugin hook or configuration option to preserve them. Fields like `arxiv`, `mrnumber`, `publication-status`, or project identifiers are lost.
-
-This package solves the problem with a two-pass parsing strategy: one pass extracts the raw BibTeX fields, the other produces CSL-JSON for formatting. The results are merged so you get the best of both worlds.
+Turn a BibTeX file into an HTML publication list with
+[citation-js](https://citation.js.org/): any CSL style, titles linked to the
+paper, badges for DOI, arXiv, MathSciNet and zbMATH, and mathematics in titles.
+
+- **Every BibTeX field stays available.** citation-js drops fields it doesn't
+  know (`status`, `project`, `mrnumber`, …); here they stay on each entry, for
+  grouping, filtering and links.
+- **Links, printed once.** The title links to the paper and identifiers become
+  badges. The style doesn't print a linked DOI or URL a second time as text.
+- **Exports work as they are.** `doi:10…` and `https://doi.org/10…`, arXiv ids
+  in biblatex's `eprint` field, titles with quotes, `\emph` or `&`.
+- **Mathematics.** `$…$` in titles survives the formatting and is typeset by
+  the renderer you pass in, such as KaTeX or MathJax.
+- **Your layout.** The markup is configurable; links are available as data;
+  hooks reach into the formatted citation.
 
 ## Install
 
 ```bash
 npm install @behackl/citation-js-extras citation-js
-# or
-pnpm add @behackl/citation-js-extras citation-js
 ```
 
-`citation-js` is a **peer dependency** — you bring your own version.
+`citation-js` is a peer dependency.
 
 ## Quick start
 
-```ts
-import { Bibliography } from "@behackl/citation-js-extras";
-
-const bib = new Bibliography({
-  data: "./references.bib", // file path or raw BibTeX string
-  cslStyle: "./my-style.csl", // optional: file path, raw XML, or registered template name
-  customFields: ["publication-status", "arxiv", "mrnumber"],
-});
-
-// Filter and sort
-const published = bib.filter({ "publication-status": "published" });
-const sorted = bib.sort(published, { by: "year", order: "desc" });
-
-// Render HTML
-const html = bib.formatHtml(sorted, {
-  titleLink: ["url", "doi", "arxiv"],
-  badges: [
-    { field: "doi", label: "doi", url: "https://doi.org/$1", className: "badge-doi" },
-    {
-      field: "arxiv",
-      label: "arXiv",
-      url: "https://arxiv.org/abs/$1",
-      match: /^(.+?)(?:v\d+)?$/,
-      className: "badge-arxiv",
-    },
-  ],
-});
-```
-
-## Preserving mathematics
-
-Citation.js normally converts TeX math to text, losing delimiters and potentially
-complex expressions. Enable preservation before parsing:
-
-```ts
-const bib = new Bibliography({
-  data: "./references.bib",
-  preserveMath: true,
-});
-
-// Restore HTML-escaped original TeX for client-side MathJax:
-const html = bib.formatHtml(bib.entries);
-
-// Or typeset at build time with your own synchronous renderer:
-const rendered = bib.formatHtml(bib.entries, {
-  renderMath: (tex, { display }) => myMathRenderer(tex, display),
-});
-```
-
-`myMathRenderer` is an application-supplied function returning **trusted HTML**
-(e.g. MathJax SVG or KaTeX output). No math renderer is bundled. Configure it for
-untrusted TeX as appropriate; the callback output is inserted verbatim, not
-sanitized. Treat renderer output as untrusted HTML unless you control both the
-renderer configuration and the TeX: substitute it only after the surrounding
-HTML has been sanitized (see below). Exceptions propagate to the caller. `renderMath` also works with
-`formatEntry`; it has no effect unless `preserveMath` was enabled.
-
-Supported delimiters are `$…$`, `$$…$$`, `\(…\)`, and `\[…\]`.
-Escape literal dollars as `\$`. Empty or unclosed expressions throw with the
-citation key and field name. This is a delimiter scanner, not a TeX validator:
-unsupported commands and mathematical validity are the renderer's responsibility.
-
-Protection covers `title`, `subtitle`, `titleaddon`, `shorttitle`, `booktitle`,
-`booksubtitle`, `booktitleaddon`, `maintitle`, `mainsubtitle`, `maintitleaddon`,
-`journaltitle`, `journalsubtitle`, `journal`, `note`, `annote`, `abstract`, and
-`howpublished`. Fields still need to be supported by Citation.js and the chosen
-CSL style to appear in the output. Names, identifiers, URLs, and custom metadata
-are not protected. BibTeX strings and concatenations are resolved before protection;
-inherited cross-reference text is protected during conversion.
-
-Original `.raw` and `.custom` values remain unchanged. With preservation enabled,
-`.csl` contains internal placeholders: use the formatting methods for HTML and
-raw fields for original source text, not `.csl` for plain-text exports. Placeholders
-also mean CSL title-based sorting/disambiguation operates on protected text rather
-than mathematical meaning. Existing caller-controlled ordering is retained.
-
-Restoration runs after title linking, badges, and URL linkification. Neither
-renderer output nor restored TeX is fed back through these HTML helpers. Disabling
-preservation (the default) retains the previous behavior.
-
-If `renderMath` throws, the error names the entry it came from
-(`entry doe:2024: Undefined control sequence: \\kk`), so a broken formula can be
-traced to a line in the `.bib` file.
-
-### Sanitizing formatted output
-
-Rendered mathematics does **not** survive an HTML sanitizer with default
-settings: KaTeX and MathJax output relies on `class`, `style` and MathML
-elements that `rehype-sanitize` strips, leaving empty boxes. Sanitize the
-citation HTML *first*, then insert the trusted renderer output:
-
-```js
-const math = [];
-const html = bib.formatHtml(entries, {
-  // Stand in for each formula while the HTML is sanitized ...
-  renderMath: (tex, { display }) => {
-    math.push(renderWithKatex(tex, display));
-    return `mathplaceholder${math.length - 1}end`;
-  },
-});
-const safe = sanitize(html);
-// ... then substitute the rendered markup back in.
-const final = safe.replace(/mathplaceholder(\d+)end/g, (_, i) => math[Number(i)]);
-```
-
-Two related gotchas when using `rehype-sanitize`:
-
-- its `defaultSchema` allows `className` only with an explicit value list *per
-  tag*, and that per-tag rule overrides anything added under `'*'`; to keep
-  badge or list classes, merge your class names into the existing entry for
-  that tag
-- pick a placeholder that cannot occur in your bibliography (append characters
-  until it is absent from the source)
-
-This recipe deliberately reinserts renderer output *after* sanitizing, so it is
-only as safe as the renderer: a renderer configured to emit arbitrary markup
-(for instance KaTeX with `trust: true`) can reintroduce `<script>`. Restrict the
-renderer configuration, or sanitize its output separately with a schema that
-keeps the elements and attributes mathematics needs.
-
-## Development checks
-
-```sh
-pnpm install --frozen-lockfile
-pnpm test          # Unit tests and actual MathJax SVG integration (base + AMS)
-pnpm test:package  # Build, pack, install into a temporary consumer, and test exports
-```
-
-The package check validates ESM imports, TypeScript declarations under both
-NodeNext and Bundler resolution, and MathJax rendering through the installed
-tarball. Its temporary consumer is removed afterwards. Installation prefers the
-local cache but may need registry access on a fresh machine. CI runs both checks.
-MathJax is a development-only dependency, not a runtime dependency for consumers.
-Use Node 24 LTS for these development checks, matching CI and publishing.
-
-## API
-
-### `new Bibliography(options)`
-
-| Option | Type | Description |
-|---|---|---|
-| `data` | `string` | BibTeX input — a raw string or a file path. |
-| `cslStyle` | `string?` | CSL style — a registered template name, raw XML, or a file path. Defaults to `'apa'`. |
-| `customFields` | `string[]?` | BibTeX field names to preserve. These appear on each entry under `.custom`. |
-| `preserveMath` | `boolean?` | Preserve math in display-text fields through CSL formatting. Defaults to `false`. |
-| `titleLink` | `string[]?` | Default fields used for the title link, checked in order. Defaults to `['url', 'doi', 'arxiv']`. |
-| `badges` | `BadgeConfig[]?` | Default badge configuration, used by every `formatHtml`/`formatEntry` call. No badges are rendered unless set. |
-| `linkifyUrls` | `boolean?` | Default for URL linkification. Defaults to `true`. |
-
-`titleLink`, `badges` and `linkifyUrls` are usually the same for every call, so
-they can be set once here; a value passed to `formatHtml`/`formatEntry` overrides
-the default for that call.
-
-### `bib.entries`
-
-All parsed entries as `BibEntry[]`:
-
-```ts
-interface BibEntry {
-  csl: Record<string, any>; // CSL-JSON data (for citation-js)
-  key: string; // BibTeX citation key
-  year: number | null; // extracted from CSL `issued`
-  custom: Record<string, string>; // declared custom fields
-  raw: Record<string, any>; // all raw BibTeX properties
+```bibtex
+@article{lindqvist2025,
+  author  = {Lindqvist, Maja and Sato, Ren},
+  title   = {Sobolev estimates for $L^p$ averages},
+  journal = {Annals of Invented Analysis},
+  volume  = {12},
+  pages   = {1--44},
+  year    = {2025},
+  doi     = {10.5555/aia.2025.12},
+  eprint  = {2501.01234},
+  eprinttype = {arxiv},
+  status  = {published},
 }
 ```
 
-### `bib.filter(criteria)`
-
-Filter entries by custom field values. All criteria must match (AND logic).
-
-```ts
-bib.filter({ "publication-status": "published" });
-bib.filter({ "publication-status": "published", project: "ABC-123" });
-```
-
-### `bib.sort(entries, options?)`
-
-Return a sorted **copy** of the entries (the input is not mutated).
-
 ```ts
-bib.sort(entries); // by year, descending (default)
-bib.sort(entries, { by: "year", order: "asc" });
-```
-
-### `bib.formatHtml(entries, options?)`
+import { Bibliography, badgePresets } from "@behackl/citation-js-extras";
 
-Render entries as a complete HTML bibliography list.
-
-```ts
-bib.formatHtml(entries, {
-  titleLink: ["url", "doi", "arxiv"],
-  badges: [ /* ... */ ],
-  list: "ol", // 'ol', 'ul', or 'div' (div uses <div class="csl-entry"> children)
-  listAttributes: { reversed: true },
-  linkifyUrls: true,
+const bib = new Bibliography({
+  data: "./publications.bib",        // a file path or BibTeX text
+  cslStyle: "apa",                   // a built-in style, a .csl file, or CSL XML
+  customFields: ["status"],          // non-standard fields to keep on `entry.custom`
+  badges: [badgePresets.doi, badgePresets.arxiv],
 });
-```
-
-Entries are formatted in one citeproc pass, so style-dependent state (for example numeric labels in Vancouver) remains correct.
-
-An empty entry list returns an empty string, not an empty wrapper element.
-
-### `bib.formatEntry(entry, options?)`
-
-Render a single entry as an HTML string (no list wrapper). The title link targets the actual CSL title text, regardless of italics.
-
-Accepts the same title linking, badge and `linkifyUrls` options as `formatHtml` and applies them identically (`list`/`listAttributes` are ignored — there is no wrapper). Bare URLs are linkified unless `linkifyUrls: false` is set, either per call or on the constructor.
-
-For citation styles that depend on multi-entry context (numbered labels, ibid behavior, etc.), prefer `formatHtml(...)`.
-
-Title links are only created for safe URL schemes (`http`, `https`, `mailto`) or normalized DOI/arXiv links.
 
-### Badges
-
-Badges are small inline links appended to each entry. They are configured declaratively:
-
-```ts
-interface BadgeConfig {
-  field: string; // BibTeX field name to read
-  label: string; // display text (e.g. "doi", "arXiv")
-  url: string; // URL template — $1 is replaced by the field value
-  match?: RegExp; // optional: validate/transform the field value
-  className?: string; // CSS class(es) for the <a> element
-}
+const published = bib.sort(bib.filter({ status: "published" }), { by: "date" });
+const html = bib.formatHtml(published);
 ```
 
-The `url` template uses `$1` as a placeholder for the field value:
-
-```ts
-{ field: "doi", label: "doi", url: "https://doi.org/$1" }
-// doi: "10.1234/example" → href="https://doi.org/10.1234/example"
-```
-
-When `match` is provided, the field value is tested against the regex. If it doesn't match, the badge is skipped. If it matches, `$1` in the URL is replaced by the **first capture group** (or the full match if there are no capture groups):
-
-```ts
-// Strip version suffix from arXiv IDs:
-{ field: "arxiv", label: "arXiv",
-  url: "https://arxiv.org/abs/$1",
-  match: /^(.+?)(?:v\d+)?$/ }
-// "2301.00001v3" → capture group "2301.00001" → href=".../2301.00001"
-
-// Only link if the field looks like a valid identifier:
-{ field: "zbl", label: "zbMATH",
-  url: "https://zbmath.org/?q=an:$1",
-  match: /^(\d+\.\d+)$/ }
-// "7654.12345" → match → linked
-// "not-a-number" → no match → badge skipped
+```html
+<ol reversed class="csl-bib-body">
+<li data-csl-entry-id="lindqvist2025" class="csl-entry">Lindqvist, M., &#38; Sato, R. (2025).
+  <a href="https://doi.org/10.5555/aia.2025.12">Sobolev estimates for $L^p$ averages</a>.
+  <i>Annals of Invented Analysis</i>, <i>12</i>, 1–44.
+  <span class="bib-links"><a href="https://doi.org/10.5555/aia.2025.12">DOI</a> <a href="https://arxiv.org/abs/2501.01234">arXiv</a></span></li>
+</ol>
 ```
 
-Badge labels are HTML-escaped before rendering. Generated badge links are emitted only for `http(s)` and `mailto:` URLs; unsafe schemes are skipped.
+Line breaks added for readability. APA would normally print the DOI after the
+journal; here it is linked as the title link and as a badge instead.
 
-### `linkifyBareUrls(html)`
+## Mathematics
 
-Standalone utility: auto-linkify bare `http(s)://` URLs in HTML text nodes that aren't already inside `<a>`, `<script>`, or `<style>` tags. Trailing punctuation is kept outside the link.
+With `preserveMath`, formulas in titles reach your renderer intact:
 
 ```ts
-import { linkifyBareUrls } from "@behackl/citation-js-extras";
+import katex from "katex";
 
-linkifyBareUrls("See https://example.com.");
-// → 'See <a href="https://example.com">https://example.com</a>.'
-```
-
-## Custom CSL styles
-
-Pass a file path or raw XML to `cslStyle`. You can also pass the name of any template already registered with citation-js:
-
-```ts
-const bib = new Bibliography({
-  data: bibtex,
-  cslStyle: "./styles/my-department.csl",
-  customFields: ["publication-status"],
+const bib = new Bibliography({ data: "./publications.bib", preserveMath: true });
+const html = bib.formatHtml(bib.entries, {
+  renderMath: (tex, { display }) => katex.renderToString(tex, { displayMode: display }),
+  sanitize: (html) => mySanitizer(html), // optional; runs before the math is inserted
 });
 ```
 
-The style is registered with citation-js and used for all formatting calls.
+See [Mathematics and sanitizing](docs/math.md).
 
-Raw CSL XML styles are internally registered under deterministic content-hash names to avoid collisions between multiple `Bibliography` instances.
+## Customising
 
-## How it works
-
-citation-js has a hardcoded list of ~106 BibTeX → CSL field mappings. Any field not in that list is silently dropped. There is no plugin API to extend this mapping.
-
-This package works around the limitation with a **two-pass parse**:
-
-1. `Cite.plugins.input.chainLink(bibData)` — returns raw BibTeX entries with **all** fields preserved (but no CSL conversion).
-2. `new Cite(bibData)` — returns CSL-JSON entries (needed for formatted output via citeproc) but with custom fields stripped.
-
-The results are merged by citation key, giving you CSL-formatted output **and** access to every custom BibTeX field.
+| To change | Use | Details |
+|---|---|---|
+| which fields you can read | `customFields`; `entry.raw` has every field | [API](docs/api.md#new-bibliographyoptions) |
+| which links follow an entry | `badges`: presets, `$1` templates, or functions | [Links and badges](docs/links.md#badges) |
+| where the title links to | `titleLink` | [Links and badges](docs/links.md#title-links) |
+| attributes of the links (class, `target`, a base path) | `linkAttributes` | [Links and badges](docs/links.md#link-attributes) |
+| how entries read | the CSL style (`cslStyle`) and locale (`lang`) | [Layout](docs/layout.md#styles-and-locales) |
+| the markup around entries | `list`, `listAttributes`, `itemAttributes`, `badgeListClassName` | [Layout](docs/layout.md#markup) |
+| a layout of your own | `links(entry)`, `appendBadges`, `wrapVariable` | [Layout](docs/layout.md#laying-out-entries-yourself) |
+| a "Copy BibTeX" button | `bibtex(entry)` | [Layout](docs/layout.md#copying-an-entrys-bibtex) |
+| what reaches the page | `sanitize`, `renderMath` | [Mathematics](docs/math.md) |
+| order and selection | `sort`, `filter`, or array methods on `bib.entries` | [API](docs/api.md#bibsortentries-options) |
+
+Formatting options can be given to the constructor as defaults, or to each
+`formatHtml`/`formatEntry` call.
+
+## Documentation
+
+- [API reference](docs/api.md)
+- [Links and badges](docs/links.md)
+- [Mathematics and sanitizing](docs/math.md)
+- [Layout: markup, styles, custom layouts](docs/layout.md)
+- [How it works](docs/how-it-works.md)
+
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
 
 ## License
 

package/dist/index.d.ts

@@ -1,14 +1,54 @@
-import type { BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
-export type { BadgeConfig, BibEntry, BibliographyOptions, FormatDefaults, FormatOptions, MathRenderer, } from "./types.js";
+import type { BibEntry, BibliographyOptions, BibtexOptions, EntryLinks, FormatOptions } from "./types.js";
+export type { BadgeConfig, BadgeFunction, BadgeLink, BibEntry, BibliographyOptions, BibtexOptions, EntryLinks, FormatDefaults, FormatOptions, HtmlAttributes, Link, MathRenderer, TitleLink, } from "./types.js";
+/**
+ * Ready-made badges for the identifiers of mathematical bibliographies. Their
+ * matchers accept the spellings found in real exports (`doi:10…`,
+ * `https://doi.org/10…`, `arXiv:2301.00001v2`, `MR1234567`). Use them as they
+ * are, or spread one to change a property:
+ *
+ * ```ts
+ * badges: [{ ...badgePresets.doi, className: "badge" }, badgePresets.arxiv]
+ * ```
+ *
+ * The title link uses the same preset for these fields, so both always agree.
+ */
+export declare const badgePresets: Readonly<{
+    doi: Readonly<{
+        field: "doi";
+        label: "DOI";
+        url: "https://doi.org/$1";
+        match: RegExp;
+    }>;
+    arxiv: Readonly<{
+        field: "arxiv";
+        label: "arXiv";
+        url: "https://arxiv.org/abs/$1";
+        match: RegExp;
+    }>;
+    mrnumber: Readonly<{
+        field: "mrnumber";
+        label: "MR";
+        url: "https://mathscinet.ams.org/mathscinet-getitem?mr=$1";
+        match: RegExp;
+    }>;
+    zbl: Readonly<{
+        field: "zbl";
+        label: "zbMATH";
+        url: "https://zbmath.org/?q=an:$1";
+        match: RegExp;
+    }>;
+}>;
 export declare class Bibliography {
     /** The CSL template name to use for formatting. */
     readonly templateName: string;
     /** All parsed entries. */
     readonly entries: BibEntry[];
     private readonly customFieldNames;
+    private readonly bibtexEntries;
     private readonly math?;
     /** Formatting defaults from the constructor; each call may override them. */
     private readonly formatDefaults;
+    private rendering?;
     constructor(options: BibliographyOptions);
     /**
      * Return entries whose custom fields match **all** given key/value pairs.
@@ -18,14 +58,15 @@ export declare class Bibliography {
      */
     filter(criteria: Record<string, string>): BibEntry[];
     /**
-     * Return a sorted **copy** of the given entries.
+     * Return a sorted **copy** of the given entries. Ties keep their input order.
      *
      * @param entries - entries to sort (not mutated)
-     * @param by - `'year'` (default) or a custom field name
+     * @param by - `'year'` (default), `'date'` (year, then month, then day; a
+     *   missing part counts as 0), or a custom field name
      * @param order - `'desc'` (default) or `'asc'`
      */
     sort(entries: BibEntry[], { by, order }?: {
-        by?: string;
+        by?: "year" | "date" | (string & {});
         order?: "asc" | "desc";
     }): BibEntry[];
     /**
@@ -34,32 +75,61 @@ export declare class Bibliography {
      */
     formatEntry(entry: BibEntry, options?: FormatOptions): string;
     /**
-     * Decorate, linkify and restore math for one rendered entry. Shared by
-     * `formatEntry` and `formatHtml` so both honour the same options.
-     *
-     * Linkification runs before math restoration: rendered MathML carries an
-     * xmlns URL that must not be turned into a link. Math is restored per entry
-     * so a failing formula can be reported with its citation key.
+     * Format a list of entries as a complete HTML bibliography.
+     */
+    formatHtml(entries: BibEntry[], options?: FormatOptions): string;
+    /**
+     * The links an entry gets with these options: its title link and badges.
+     * The same resolution the formatted HTML uses, so the two always agree; for
+     * rendering badges yourself, pair it with `appendBadges: false`.
+     */
+    links(entry: BibEntry, options?: FormatOptions): EntryLinks;
+    /**
+     * The entry as BibTeX that stands on its own, e.g. for readers to copy:
+     * `@string` abbreviations are resolved and the fields of `crossref` parents
+     * filled in using biblatex's title-remapping rules. Missing parents leave
+     * `crossref` unresolved, so the copy may still require its parent.
+     * Field values are the TeX of the `.bib` file. Requires this bibliography's
+     * original key and raw object; shallow entry copies are accepted.
+     */
+    bibtex(entry: BibEntry, options?: BibtexOptions): string;
+    /**
+     * An entry's fields with those inherited through `crossref`, using the same
+     * biblatex title-remapping rules as citation-js (`plugin-bibtex`'s
+     * `mapping/crossref.js`). Keep the mapping and exclusion tests in sync.
      */
-    private buildEntryHtml;
+    private withInherited;
     /** Per-call options win over the defaults given to the constructor. */
     private mergeOptions;
     /**
-     * Restore protected math, naming the entry when a renderer rejects a formula.
-     * Without the citation key, `renderMath` failures are near-impossible to
-     * trace back to a line in the .bib file.
+     * Entry HTML without wrapper, shared by `formatEntry` and `formatHtml` so
+     * both honour the same options. Links are resolved first: they decide what
+     * the style may print and what is added afterwards.
      */
-    private restoreMath;
+    private renderItems;
     /**
-     * Format a list of entries as a complete HTML bibliography.
+     * Called by citeproc for every variable it renders. Everything the library
+     * adds to the citation text happens here, one variable at a time, instead of
+     * by searching the finished HTML:
+     *
+     * - the title link, around the exact output of the title variable, so no
+     *   quotes, markup or capitalisation the style applies can hide the title;
+     * - bare URLs in a variable (e.g. in a `note`) become links. Formulas are
+     *   still placeholders here, so MathML's xmlns URL is never linked;
+     * - the consumer's `wrapVariable`, outermost.
      */
-    formatHtml(entries: BibEntry[], options?: FormatOptions): string;
+    private wrapVariable;
+    /** Sanitize while formulas are placeholders, then insert rendered math. */
+    private finish;
+    private resolveLinks;
     private registerStyle;
+    /**
+     * Render entries with citeproc, as `cite.format("bibliography")` does, but
+     * through an engine that has our variable wrapper: citeproc only accepts it
+     * when the engine is created. Styles and locales come from citation-js's
+     * registries, and the data is prepared the same way.
+     */
     private renderCslEntries;
-    private decorateEntryHtml;
-    private resolveTitleLink;
-    private linkTitle;
-    private renderBadges;
 }
 /**
  * Auto-linkify bare `http(s)://` URLs in HTML that aren't already inside