@behackl/citation-js-extras 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,7 @@
 # @behackl/citation-js-extras
 
+![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
@@ -49,6 +51,112 @@ const html = bib.formatHtml(sorted, {
 });
 ```
 
+## 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)`
@@ -58,6 +166,14 @@ const html = bib.formatHtml(sorted, {
 | `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`
 
@@ -107,10 +223,14 @@ bib.formatHtml(entries, {
 
 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.

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import type { BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
-export type { BadgeConfig, BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
+export type { BadgeConfig, BibEntry, BibliographyOptions, FormatDefaults, FormatOptions, MathRenderer, } from "./types.js";
 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 math?;
+    /** Formatting defaults from the constructor; each call may override them. */
+    private readonly formatDefaults;
     constructor(options: BibliographyOptions);
     /**
      * Return entries whose custom fields match **all** given key/value pairs.
@@ -27,9 +30,26 @@ export declare class Bibliography {
     }): BibEntry[];
     /**
      * Format a single entry as an HTML string (no wrapper element).
-     * Applies title linking and badge injection.
+     * Applies title linking, badge injection and URL linkification.
      */
     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.
+     */
+    private buildEntryHtml;
+    /** 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.
+     */
+    private restoreMath;
     /**
      * Format a list of entries as a complete HTML bibliography.
      */

package/dist/index.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import Cite from "citation-js";
+import { MathProtector } from "./math.js";
 // ---------------------------------------------------------------------------
 // Bibliography class
 // ---------------------------------------------------------------------------
@@ -9,9 +10,17 @@ export class Bibliography {
     /** All parsed entries. */
     entries;
     customFieldNames;
+    math;
+    /** Formatting defaults from the constructor; each call may override them. */
+    formatDefaults;
     constructor(options) {
         const bibData = maybeReadFile(options.data);
         this.customFieldNames = options.customFields ?? [];
+        this.formatDefaults = {
+            titleLink: options.titleLink,
+            badges: options.badges,
+            linkifyUrls: options.linkifyUrls,
+        };
         // Register CSL style
         this.templateName = this.registerStyle(options.cslStyle);
         // Two-pass parse: raw (preserves all fields) + CSL (for formatting)
@@ -21,7 +30,15 @@ export class Bibliography {
         for (const entry of rawEntries) {
             rawMap.set(entry.label, entry.properties);
         }
-        const cite = new Cite(bibData);
+        // Protect resolved raw fields, after BibTeX strings/concatenations are parsed
+        // but before the lossy TeX-to-CSL conversion. Keep the original raw map intact.
+        this.math = options.preserveMath
+            ? new MathProtector(JSON.stringify(rawEntries)) : undefined;
+        const cite = this.math
+            ? new Cite(rawEntries.map(entry => ({
+                ...entry, properties: this.math.protect(entry.properties, entry.label),
+            })))
+            : new Cite(bibData);
         this.entries = cite.data.map((csl) => {
             const key = String(csl["citation-key"] || csl.id);
             const raw = rawMap.get(key) ?? {};
@@ -71,13 +88,53 @@ export class Bibliography {
     // -------------------------------------------------------------------------
     /**
      * Format a single entry as an HTML string (no wrapper element).
-     * Applies title linking and badge injection.
+     * Applies title linking, badge injection and URL linkification.
      */
     formatEntry(entry, options = {}) {
+        const merged = this.mergeOptions(options);
         const rendered = this.renderCslEntries([entry]);
         const raw = rendered[0]?.[1] ?? "";
         const innerHtml = unwrapCslEntry(raw) ?? raw.trim();
-        return this.decorateEntryHtml(entry, innerHtml, options);
+        return this.buildEntryHtml(entry, innerHtml, merged);
+    }
+    /**
+     * 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.
+     */
+    buildEntryHtml(entry, innerRaw, merged) {
+        let inner = this.decorateEntryHtml(entry, innerRaw, merged);
+        if (merged.linkifyUrls !== false)
+            inner = linkifyBareUrls(inner);
+        return this.restoreMath(inner, merged, entry);
+    }
+    /** Per-call options win over the defaults given to the constructor. */
+    mergeOptions(options) {
+        return {
+            ...options,
+            titleLink: options.titleLink ?? this.formatDefaults.titleLink,
+            badges: options.badges ?? this.formatDefaults.badges,
+            linkifyUrls: options.linkifyUrls ?? this.formatDefaults.linkifyUrls,
+        };
+    }
+    /**
+     * 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.
+     */
+    restoreMath(html, options, entry) {
+        if (!this.math)
+            return html;
+        try {
+            return this.math.restore(html, options.renderMath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(entry ? `entry ${entry.key}: ${message}` : message, { cause: error });
+        }
     }
     /**
      * Format a list of entries as a complete HTML bibliography.
@@ -85,8 +142,9 @@ export class Bibliography {
     formatHtml(entries, options = {}) {
         if (entries.length === 0)
             return "";
-        const tag = options.list ?? "ol";
-        const attrs = options.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
+        const merged = this.mergeOptions(options);
+        const tag = merged.list ?? "ol";
+        const attrs = merged.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
         const attrStr = renderAttributes(attrs);
         // Render all entries in one citeproc run so style-dependent numbering/state
         // (e.g. vancouver left-margin labels) remains correct.
@@ -100,14 +158,10 @@ export class Bibliography {
                 ?? rendered[index]?.[1]
                 ?? "";
             const innerRaw = unwrapCslEntry(raw) ?? raw.trim();
-            const inner = this.decorateEntryHtml(entry, innerRaw, options);
+            const inner = this.buildEntryHtml(entry, innerRaw, merged);
             return `<${itemTag} data-csl-entry-id="${escapeAttr(entry.key)}" class="csl-entry">${inner}</${itemTag}>`;
         });
-        let html = `<${tag}${attrStr} class="csl-bib-body">\n${items.join("\n")}\n</${tag}>`;
-        if (options.linkifyUrls !== false) {
-            html = linkifyBareUrls(html);
-        }
-        return html;
+        return `<${tag}${attrStr} class="csl-bib-body">\n${items.join("\n")}\n</${tag}>`;
     }
     // -------------------------------------------------------------------------
     // Private helpers

package/dist/math.d.ts

@@ -0,0 +1,10 @@
+import type { MathRenderer } from "./types.js";
+export declare class MathProtector {
+    private readonly expressions;
+    private readonly tokensBySource;
+    private readonly prefix;
+    constructor(source: string);
+    protect(properties: Record<string, any>, key: string): Record<string, any>;
+    private scan;
+    restore(html: string, render?: MathRenderer): string;
+}

package/dist/math.js

@@ -0,0 +1,77 @@
+/** Text fields only: identifiers, URLs, names and custom metadata are untouched. */
+const TEXT_FIELDS = new Set([
+    "title", "subtitle", "titleaddon", "shorttitle", "booktitle", "booksubtitle",
+    "booktitleaddon", "maintitle", "mainsubtitle", "maintitleaddon", "journaltitle",
+    "journalsubtitle", "journal", "note", "annote", "abstract", "howpublished",
+]);
+export class MathProtector {
+    expressions = new Map();
+    tokensBySource = new Map();
+    prefix;
+    constructor(source) {
+        let prefix = "bibmathplaceholder";
+        while (source.toLowerCase().includes(prefix))
+            prefix += "x";
+        this.prefix = prefix;
+    }
+    protect(properties, key) {
+        return Object.fromEntries(Object.entries(properties).map(([field, value]) => [
+            field,
+            TEXT_FIELDS.has(field) && typeof value === "string"
+                ? this.scan(value, `${key}.${field}`) : value,
+        ]));
+    }
+    scan(value, context) {
+        let out = "";
+        for (let i = 0; i < value.length;) {
+            const opener = value.startsWith("$$", i) ? "$$"
+                : value[i] === "$" ? "$"
+                    : value.startsWith("\\(", i) ? "\\("
+                        : value.startsWith("\\[", i) ? "\\[" : null;
+            if (!opener) {
+                // Consume escaped characters together, including literal dollars.
+                const length = value[i] === "\\" && i + 1 < value.length ? 2 : 1;
+                out += value.slice(i, i + length);
+                i += length;
+                continue;
+            }
+            const closer = opener === "\\(" ? "\\)" : opener === "\\[" ? "\\]" : opener;
+            let end = i + opener.length;
+            while (end < value.length && !value.startsWith(closer, end)) {
+                end += value[end] === "\\" ? 2 : 1;
+            }
+            if (end >= value.length)
+                throw new Error(`Unclosed math delimiter ${opener} in ${context}`);
+            const tex = value.slice(i + opener.length, end);
+            if (!tex.trim())
+                throw new Error(`Empty math expression in ${context}`);
+            const source = value.slice(i, end + closer.length);
+            // Identical source must remain identical to citeproc (e.g. title grouping).
+            let token = this.tokensBySource.get(source);
+            if (!token) {
+                token = `${this.prefix}${this.expressions.size}end`;
+                this.tokensBySource.set(source, token);
+                this.expressions.set(token, { tex, source, display: opener === "$$" || opener === "\\[" });
+            }
+            out += token;
+            i = end + closer.length;
+        }
+        return out;
+    }
+    restore(html, render) {
+        const pattern = new RegExp(`${this.prefix}\\d+end`, "gi");
+        // Only replace text, never attribute values. Renderer output is inserted last.
+        return html.split(/(<[^>]*>)/g).map(part => part.startsWith("<") ? part
+            : part.replace(pattern, token => {
+                const expression = this.expressions.get(token.toLowerCase());
+                if (!expression)
+                    throw new Error(`Unknown math placeholder: ${token}`);
+                return render ? render(expression.tex, { display: expression.display })
+                    : escapeHtml(expression.source);
+            })).join("");
+    }
+}
+function escapeHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}

package/dist/types.d.ts

@@ -41,10 +41,24 @@ export interface BadgeConfig {
     /** CSS class name(s) for the badge `<a>` element. */
     className?: string;
 }
-/** Options passed to {@link Bibliography.formatHtml}. */
+/** Synchronous renderer returning trusted HTML. Sanitize untrusted renderer output. */
+export type MathRenderer = (tex: string, context: {
+    display: boolean;
+}) => string;
+/**
+ * Options passed to {@link Bibliography.formatHtml} or
+ * {@link Bibliography.formatEntry}. `list` and `listAttributes` only apply to
+ * `formatHtml`, which is the only method emitting a wrapper element.
+ */
 export interface FormatOptions {
+    /** Render protected math as trusted HTML; requires preserveMath at construction.
+     * Without this callback, escaped original TeX delimiters are restored.
+     * Not settable on the constructor.
+     */
+    renderMath?: MathRenderer;
     /**
      * Fields to use for linking the title, checked in order.
+     * Overrides the constructor default, if any.
      * A `doi` value is expanded to `https://doi.org/<value>`, an `arxiv`
      * value to `https://arxiv.org/abs/<value>`, and direct values are only
      * accepted when they use `http`, `https`, or `mailto`.
@@ -52,7 +66,12 @@ export interface FormatOptions {
      * @default ['url', 'doi', 'arxiv']
      */
     titleLink?: string[];
-    /** Badge configurations to append to each entry. */
+    /**
+     * Badge configurations to append to each entry.
+     * Overrides the constructor default, if any.
+     *
+     * @default [] (no badges)
+     */
     badges?: BadgeConfig[];
     /**
      * Wrapper list element.
@@ -69,6 +88,7 @@ export interface FormatOptions {
     /**
      * Auto-linkify bare `http(s)://` URLs in the rendered output that aren't
      * already inside `<a>`, `<script>`, or `<style>` tags.
+     * Overrides the constructor default, if any.
      *
      * @default true
      */
@@ -90,8 +110,18 @@ export interface BibEntry {
     /** The full raw BibTeX properties (unfiltered). */
     raw: Record<string, any>;
 }
+/**
+ * Formatting options that can be set once on the constructor and overridden
+ * by the options of an individual `formatHtml`/`formatEntry` call.
+ */
+export type FormatDefaults = Pick<FormatOptions, "titleLink" | "badges" | "linkifyUrls">;
 /** Options for constructing a {@link Bibliography}. */
-export interface BibliographyOptions {
+export interface BibliographyOptions extends FormatDefaults {
+    /** Preserve math in supported display-text fields before CSL conversion.
+     * Opt-in; entries' CSL text contains internal placeholders until HTML formatting.
+     * Raw/custom fields remain unchanged. Unclosed or empty math throws.
+     */
+    preserveMath?: boolean;
     /**
      * BibTeX input — either a raw BibTeX string or a file path.
      * When a file path is given, it is read synchronously at construction time.

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@behackl/citation-js-extras",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Preserve custom BibTeX fields through citation-js and render academic bibliographies with linked titles, badges, and more.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -16,6 +16,13 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:package": "pnpm build && node scripts/test-package.mjs",
+    "prepublishOnly": "tsc"
+  },
   "keywords": [
     "citation-js",
     "bibtex",
@@ -28,12 +35,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/behackl/citation-js-extra.git"
+    "url": "git+https://github.com/behackl/citation-js-extras.git"
   },
   "bugs": {
-    "url": "https://github.com/behackl/citation-js-extra/issues"
+    "url": "https://github.com/behackl/citation-js-extras/issues"
   },
-  "homepage": "https://github.com/behackl/citation-js-extra#readme",
+  "homepage": "https://github.com/behackl/citation-js-extras#readme",
   "publishConfig": {
     "access": "public"
   },
@@ -41,18 +48,20 @@
     "node": ">=18"
   },
   "sideEffects": false,
+  "packageManager": "pnpm@10.29.1",
   "peerDependencies": {
     "citation-js": ">=0.7.0"
   },
   "devDependencies": {
+    "@mathjax/src": "4.1.0",
     "@types/node": "^25.2.3",
     "citation-js": "^0.7.22",
     "typescript": "^5.9.3",
     "vitest": "^3.1.4"
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
-}
+}