@behackl/citation-js-extras 0.1.0 → 0.2.0

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,70 @@ 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. 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.
+
+## 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 +124,7 @@ 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`. |
 
 ### `bib.entries`
 

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import type { BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
-export type { BadgeConfig, BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
+export type { BadgeConfig, BibEntry, BibliographyOptions, 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?;
     constructor(options: BibliographyOptions);
     /**
      * Return entries whose custom fields match **all** given key/value pairs.

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,6 +10,7 @@ export class Bibliography {
     /** All parsed entries. */
     entries;
     customFieldNames;
+    math;
     constructor(options) {
         const bibData = maybeReadFile(options.data);
         this.customFieldNames = options.customFields ?? [];
@@ -21,7 +23,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) ?? {};
@@ -77,7 +87,8 @@ export class Bibliography {
         const rendered = this.renderCslEntries([entry]);
         const raw = rendered[0]?.[1] ?? "";
         const innerHtml = unwrapCslEntry(raw) ?? raw.trim();
-        return this.decorateEntryHtml(entry, innerHtml, options);
+        const decorated = this.decorateEntryHtml(entry, innerHtml, options);
+        return this.math ? this.math.restore(decorated, options.renderMath) : decorated;
     }
     /**
      * Format a list of entries as a complete HTML bibliography.
@@ -107,7 +118,7 @@ export class Bibliography {
         if (options.linkifyUrls !== false) {
             html = linkifyBareUrls(html);
         }
-        return html;
+        return this.math ? this.math.restore(html, options.renderMath) : html;
     }
     // -------------------------------------------------------------------------
     // 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,8 +41,16 @@ export interface BadgeConfig {
     /** CSS class name(s) for the badge `<a>` element. */
     className?: string;
 }
+/** Synchronous renderer returning trusted HTML. Sanitize untrusted renderer output. */
+export type MathRenderer = (tex: string, context: {
+    display: boolean;
+}) => string;
 /** Options passed to {@link Bibliography.formatHtml}. */
 export interface FormatOptions {
+    /** Render protected math as trusted HTML; requires preserveMath at construction.
+     * Without this callback, escaped original TeX delimiters are restored.
+     */
+    renderMath?: MathRenderer;
     /**
      * Fields to use for linking the title, checked in order.
      * A `doi` value is expanded to `https://doi.org/<value>`, an `arxiv`
@@ -92,6 +100,11 @@ export interface BibEntry {
 }
 /** Options for constructing a {@link Bibliography}. */
 export interface BibliographyOptions {
+    /** 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.0",
   "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"
+    ]
   }
-}
+}