@behackl/citation-js-extras 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Hackl
+
+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,198 @@
+# @behackl/citation-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.
+
+## 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.
+
+## 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",
+    },
+  ],
+});
+```
+
+## 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`. |
+
+### `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
+}
+```
+
+### `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?)`
+
+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,
+});
+```
+
+Entries are formatted in one citeproc pass, so style-dependent state (for example numeric labels in Vancouver) remains correct.
+
+### `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.
+
+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
+}
+```
+
+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
+```
+
+Badge labels are HTML-escaped before rendering. Generated badge links are emitted only for `http(s)` and `mailto:` URLs; unsafe schemes are skipped.
+
+### `linkifyBareUrls(html)`
+
+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.
+
+```ts
+import { linkifyBareUrls } from "@behackl/citation-js-extras";
+
+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"],
+});
+```
+
+The style is registered with citation-js and used for all formatting calls.
+
+Raw CSL XML styles are internally registered under deterministic content-hash names to avoid collisions between multiple `Bibliography` instances.
+
+## 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.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import type { BibEntry, BibliographyOptions, FormatOptions } from "./types.js";
+export type { BadgeConfig, BibEntry, BibliographyOptions, FormatOptions } 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;
+    constructor(options: BibliographyOptions);
+    /**
+     * Return entries whose custom fields match **all** given key/value pairs.
+     *
+     * @example
+     * bib.filter({ 'publication-status': 'published' })
+     */
+    filter(criteria: Record<string, string>): BibEntry[];
+    /**
+     * Return a sorted **copy** of the given entries.
+     *
+     * @param entries - entries to sort (not mutated)
+     * @param by - `'year'` (default) or a custom field name
+     * @param order - `'desc'` (default) or `'asc'`
+     */
+    sort(entries: BibEntry[], { by, order }?: {
+        by?: string;
+        order?: "asc" | "desc";
+    }): BibEntry[];
+    /**
+     * Format a single entry as an HTML string (no wrapper element).
+     * Applies title linking and badge injection.
+     */
+    formatEntry(entry: BibEntry, options?: FormatOptions): string;
+    /**
+     * Format a list of entries as a complete HTML bibliography.
+     */
+    formatHtml(entries: BibEntry[], options?: FormatOptions): string;
+    private registerStyle;
+    private renderCslEntries;
+    private decorateEntryHtml;
+    private resolveTitleLink;
+    private linkTitle;
+    private renderBadges;
+}
+/**
+ * Auto-linkify bare `http(s)://` URLs in HTML that aren't already inside
+ * an `<a>` tag. Trailing punctuation (`.`, `,`, `;`, etc.) is kept outside
+ * the link.
+ */
+export declare function linkifyBareUrls(html: string): string;

package/dist/index.js

@@ -0,0 +1,404 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import Cite from "citation-js";
+// ---------------------------------------------------------------------------
+// Bibliography class
+// ---------------------------------------------------------------------------
+export class Bibliography {
+    /** The CSL template name to use for formatting. */
+    templateName;
+    /** All parsed entries. */
+    entries;
+    customFieldNames;
+    constructor(options) {
+        const bibData = maybeReadFile(options.data);
+        this.customFieldNames = options.customFields ?? [];
+        // Register CSL style
+        this.templateName = this.registerStyle(options.cslStyle);
+        // Two-pass parse: raw (preserves all fields) + CSL (for formatting)
+        const { plugins } = Cite;
+        const rawEntries = plugins.input.chainLink(bibData);
+        const rawMap = new Map();
+        for (const entry of rawEntries) {
+            rawMap.set(entry.label, entry.properties);
+        }
+        const cite = new Cite(bibData);
+        this.entries = cite.data.map((csl) => {
+            const key = String(csl["citation-key"] || csl.id);
+            const raw = rawMap.get(key) ?? {};
+            const custom = {};
+            for (const f of this.customFieldNames) {
+                if (raw[f] != null)
+                    custom[f] = String(raw[f]);
+            }
+            return {
+                csl,
+                key,
+                year: csl.issued?.["date-parts"]?.[0]?.[0] ?? null,
+                custom,
+                raw,
+            };
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Filtering & sorting
+    // -------------------------------------------------------------------------
+    /**
+     * Return entries whose custom fields match **all** given key/value pairs.
+     *
+     * @example
+     * bib.filter({ 'publication-status': 'published' })
+     */
+    filter(criteria) {
+        return this.entries.filter((e) => Object.entries(criteria).every(([k, v]) => e.custom[k] === v));
+    }
+    /**
+     * Return a sorted **copy** of the given entries.
+     *
+     * @param entries - entries to sort (not mutated)
+     * @param by - `'year'` (default) or a custom field name
+     * @param order - `'desc'` (default) or `'asc'`
+     */
+    sort(entries, { by = "year", order = "desc" } = {}) {
+        return [...entries].sort((a, b) => {
+            const va = by === "year" ? (a.year ?? 0) : (a.custom[by] ?? "");
+            const vb = by === "year" ? (b.year ?? 0) : (b.custom[by] ?? "");
+            const cmp = va < vb ? -1 : va > vb ? 1 : 0;
+            return order === "desc" ? -cmp : cmp;
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Formatting
+    // -------------------------------------------------------------------------
+    /**
+     * Format a single entry as an HTML string (no wrapper element).
+     * Applies title linking and badge injection.
+     */
+    formatEntry(entry, options = {}) {
+        const rendered = this.renderCslEntries([entry]);
+        const raw = rendered[0]?.[1] ?? "";
+        const innerHtml = unwrapCslEntry(raw) ?? raw.trim();
+        return this.decorateEntryHtml(entry, innerHtml, options);
+    }
+    /**
+     * Format a list of entries as a complete HTML bibliography.
+     */
+    formatHtml(entries, options = {}) {
+        if (entries.length === 0)
+            return "";
+        const tag = options.list ?? "ol";
+        const attrs = options.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.
+        const rendered = this.renderCslEntries(entries);
+        const renderedMap = new Map(rendered.map(([id, html]) => [id, html]));
+        const itemTag = tag === "div" ? "div" : "li";
+        const items = entries.map((entry, index) => {
+            const id = String(entry.csl.id ?? entry.key);
+            const raw = renderedMap.get(id)
+                ?? renderedMap.get(entry.key)
+                ?? rendered[index]?.[1]
+                ?? "";
+            const innerRaw = unwrapCslEntry(raw) ?? raw.trim();
+            const inner = this.decorateEntryHtml(entry, innerRaw, options);
+            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;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    registerStyle(cslStyle) {
+        if (!cslStyle)
+            return "apa";
+        const config = Cite.plugins.config.get("@csl");
+        const templates = config.templates;
+        if (templateExists(templates, cslStyle)) {
+            return cslStyle;
+        }
+        const xml = readFileIfExists(cslStyle) ?? (looksLikeXml(cslStyle) ? cslStyle : null);
+        if (!xml) {
+            throw new Error(`Unknown CSL style "${cslStyle}". Provide a built-in name, file path, or CSL XML.`);
+        }
+        const name = `custom-${hashString(xml)}`;
+        if (!templateExists(templates, name)) {
+            templates.add(name, xml);
+        }
+        return name;
+    }
+    renderCslEntries(entries) {
+        const cite = new Cite(entries.map((entry) => entry.csl));
+        const out = cite.format("bibliography", {
+            format: "html",
+            template: this.templateName,
+            lang: "en-US",
+            nosort: true,
+            asEntryArray: true,
+        });
+        if (!Array.isArray(out))
+            return [];
+        return out
+            .filter((item) => Array.isArray(item) && item.length >= 2)
+            .map(([id, html]) => [String(id), String(html)]);
+    }
+    decorateEntryHtml(entry, html, options) {
+        let out = html;
+        // Link the title text
+        const titleUrl = this.resolveTitleLink(entry, options.titleLink);
+        const title = entry.csl.title;
+        if (titleUrl && typeof title === "string" && title.trim()) {
+            out = this.linkTitle(out, title, titleUrl);
+        }
+        // Append badges
+        const badges = options.badges ?? [];
+        const badgeHtml = this.renderBadges(entry, badges);
+        if (badgeHtml) {
+            out += ` ${badgeHtml}`;
+        }
+        return out;
+    }
+    resolveTitleLink(entry, fields) {
+        const order = fields ?? ["url", "doi", "arxiv"];
+        for (const field of order) {
+            const value = entry.raw[field] ?? entry.csl[field.toUpperCase()] ?? entry.csl[field];
+            if (!value)
+                continue;
+            const raw = String(value).trim();
+            if (!raw)
+                continue;
+            if (/^https?:\/\//i.test(raw) || /^mailto:/i.test(raw)) {
+                return sanitizeUrl(raw);
+            }
+            if (field === "doi") {
+                const doi = raw.replace(/^doi:\s*/i, "");
+                return sanitizeUrl(`https://doi.org/${doi}`);
+            }
+            if (field === "arxiv") {
+                return sanitizeUrl(`https://arxiv.org/abs/${raw.replace(/v\d+$/, "")}`);
+            }
+        }
+        return null;
+    }
+    linkTitle(html, title, url) {
+        const pattern = buildHtmlTextPattern(title);
+        if (!pattern)
+            return html;
+        const regex = new RegExp(pattern);
+        const tokens = html.split(/(<[^>]*>)/g);
+        let insideAnchor = false;
+        let insideScript = false;
+        let insideStyle = false;
+        let linked = false;
+        const output = [];
+        for (const token of tokens) {
+            if (token.startsWith("<")) {
+                const lower = token.toLowerCase();
+                if (/^<a\b/.test(lower))
+                    insideAnchor = true;
+                if (/^<\/a\b/.test(lower))
+                    insideAnchor = false;
+                if (/^<script\b/.test(lower))
+                    insideScript = true;
+                if (/^<\/script\b/.test(lower))
+                    insideScript = false;
+                if (/^<style\b/.test(lower))
+                    insideStyle = true;
+                if (/^<\/style\b/.test(lower))
+                    insideStyle = false;
+                output.push(token);
+                continue;
+            }
+            if (linked || insideAnchor || insideScript || insideStyle) {
+                output.push(token);
+                continue;
+            }
+            const replaced = token.replace(regex, (match) => {
+                linked = true;
+                return `<a href="${escapeAttr(url)}">${match}</a>`;
+            });
+            output.push(replaced);
+        }
+        return output.join("");
+    }
+    renderBadges(entry, badges) {
+        const parts = [];
+        for (const badge of badges) {
+            const rawValue = entry.raw[badge.field] ?? entry.custom[badge.field];
+            if (rawValue == null)
+                continue;
+            const strValue = String(rawValue);
+            let insertValue;
+            if (badge.match) {
+                const m = strValue.match(badge.match);
+                if (!m)
+                    continue;
+                insertValue = m[1] ?? m[0];
+            }
+            else {
+                insertValue = strValue;
+            }
+            const unsafeUrl = badge.url.replace(/\$1/g, insertValue);
+            const safeUrl = sanitizeUrl(unsafeUrl);
+            if (!safeUrl)
+                continue;
+            const cls = badge.className ? ` class="${escapeAttr(badge.className)}"` : "";
+            parts.push(`<a${cls} href="${escapeAttr(safeUrl)}">${escapeHtml(String(badge.label))}</a>`);
+        }
+        if (parts.length === 0)
+            return "";
+        return `<span class="bib-links">${parts.join(" ")}</span>`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Standalone utilities (exported for reuse)
+// ---------------------------------------------------------------------------
+/**
+ * Auto-linkify bare `http(s)://` URLs in HTML that aren't already inside
+ * an `<a>` tag. Trailing punctuation (`.`, `,`, `;`, etc.) is kept outside
+ * the link.
+ */
+export function linkifyBareUrls(html) {
+    const tokens = html.split(/(<[^>]*>)/g);
+    const urlRegex = /(https?:\/\/[^\s<>"',;)]+)/g;
+    let insideAnchor = false;
+    let insideScript = false;
+    let insideStyle = false;
+    const output = [];
+    for (const token of tokens) {
+        if (token.startsWith("<")) {
+            const lower = token.toLowerCase();
+            if (/^<a\b/.test(lower))
+                insideAnchor = true;
+            if (/^<\/a\b/.test(lower))
+                insideAnchor = false;
+            if (/^<script\b/.test(lower))
+                insideScript = true;
+            if (/^<\/script\b/.test(lower))
+                insideScript = false;
+            if (/^<style\b/.test(lower))
+                insideStyle = true;
+            if (/^<\/style\b/.test(lower))
+                insideStyle = false;
+            output.push(token);
+            continue;
+        }
+        if (insideAnchor || insideScript || insideStyle) {
+            output.push(token);
+            continue;
+        }
+        output.push(token.replace(urlRegex, (match) => {
+            const trimmed = match.replace(/[.,;:!?)]+$/, "");
+            const trailing = match.slice(trimmed.length);
+            return `<a href="${escapeAttr(trimmed)}">${trimmed}</a>${trailing}`;
+        }));
+    }
+    return output.join("");
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function readFileIfExists(input) {
+    if (!existsSync(input))
+        return null;
+    try {
+        if (!statSync(input).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return readFileSync(input, "utf-8");
+}
+function maybeReadFile(input) {
+    return readFileIfExists(input) ?? input;
+}
+function looksLikeXml(input) {
+    return /^\s*</.test(input);
+}
+function templateExists(templates, name) {
+    if (typeof templates.has === "function" && templates.has(name))
+        return true;
+    if (Array.isArray(templates.list?.()) && templates.list().includes(name))
+        return true;
+    return false;
+}
+function unwrapCslEntry(entryHtml) {
+    const trimmed = entryHtml.trim();
+    const match = trimmed.match(/^<div\b([^>]*)>([\s\S]*)<\/div>$/s);
+    if (!match)
+        return null;
+    const attrs = match[1] ?? "";
+    if (!/\bclass\s*=\s*["'][^"']*\bcsl-entry\b/i.test(attrs))
+        return null;
+    return (match[2] ?? "").trim();
+}
+function sanitizeUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    if (/^https?:\/\//i.test(trimmed) || /^mailto:/i.test(trimmed)) {
+        return trimmed;
+    }
+    return null;
+}
+function buildHtmlTextPattern(text) {
+    let pattern = "";
+    for (const ch of text) {
+        switch (ch) {
+            case "&":
+                pattern += "(?:&amp;|&#38;)";
+                break;
+            case "<":
+                pattern += "&lt;";
+                break;
+            case ">":
+                pattern += "&gt;";
+                break;
+            case '"':
+                pattern += "(?:&quot;|&#34;)";
+                break;
+            case "'":
+                pattern += "(?:&#39;|&apos;)";
+                break;
+            default:
+                pattern += escapeRegex(ch);
+        }
+    }
+    return pattern;
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function renderAttributes(attrs) {
+    const parts = [];
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v === true)
+            parts.push(k);
+        else if (v !== false)
+            parts.push(`${k}="${escapeAttr(String(v))}"`);
+    }
+    return parts.length ? " " + parts.join(" ") : "";
+}
+function hashString(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16);
+}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Declares a badge link to render alongside bibliography entries.
+ *
+ * The `url` is a template string where `$1` is replaced by the (optionally
+ * transformed) field value.  When `match` is provided, the field value is
+ * tested against it first: if it doesn't match the badge is skipped; if it
+ * does, `$1` in the URL is replaced by the **first capture group** (or the
+ * full match if there is no capture group).
+ *
+ * @example
+ * // Simple prefix-style DOI badge:
+ * { field: 'doi', label: 'doi', url: 'https://doi.org/$1' }
+ *
+ * @example
+ * // Strip trailing version from arXiv identifiers:
+ * { field: 'arxiv', label: 'arXiv',
+ *   url: 'https://arxiv.org/abs/$1',
+ *   match: /^(.+?)(?:v\d+)?$/ }
+ *
+ * @example
+ * // Only link zbMATH entries that look like a Zbl number:
+ * { field: 'zbl', label: 'zbMATH',
+ *   url: 'https://zbmath.org/?q=an:$1',
+ *   match: /^(\d{4}\.\d{5})$/ }
+ */
+export interface BadgeConfig {
+    /** BibTeX field name to read the value from. */
+    field: string;
+    /** Text to display inside the badge. */
+    label: string;
+    /** URL template — `$1` is replaced by the field value. */
+    url: string;
+    /**
+     * Optional regex applied to the field value.
+     *
+     * - If it **doesn't match**, the badge is skipped for that entry.
+     * - If it **matches**, `$1` in the URL is replaced by the first capture
+     *   group (or the full match when there are no capture groups).
+     */
+    match?: RegExp;
+    /** CSS class name(s) for the badge `<a>` element. */
+    className?: string;
+}
+/** Options passed to {@link Bibliography.formatHtml}. */
+export interface FormatOptions {
+    /**
+     * Fields to use for linking the title, checked in order.
+     * 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`.
+     *
+     * @default ['url', 'doi', 'arxiv']
+     */
+    titleLink?: string[];
+    /** Badge configurations to append to each entry. */
+    badges?: BadgeConfig[];
+    /**
+     * Wrapper list element.
+     * @default 'ol'
+     */
+    list?: "ol" | "ul" | "div";
+    /**
+     * HTML attributes for the wrapper element (e.g. `{ reversed: true }`).
+     * Boolean `true` renders as a valueless attribute.
+     *
+     * @default { reversed: true }  (when list is 'ol')
+     */
+    listAttributes?: Record<string, string | boolean>;
+    /**
+     * Auto-linkify bare `http(s)://` URLs in the rendered output that aren't
+     * already inside `<a>`, `<script>`, or `<style>` tags.
+     *
+     * @default true
+     */
+    linkifyUrls?: boolean;
+}
+/** A bibliography entry enriched with custom BibTeX fields. */
+export interface BibEntry {
+    /** The CSL-JSON object used by citation-js for formatting. */
+    csl: Record<string, any>;
+    /** The BibTeX citation key. */
+    key: string;
+    /** Publication year (extracted from CSL `issued`). */
+    year: number | null;
+    /**
+     * Custom BibTeX fields that were requested via `customFields`.
+     * Only fields that are present on the entry appear here.
+     */
+    custom: Record<string, string>;
+    /** The full raw BibTeX properties (unfiltered). */
+    raw: Record<string, any>;
+}
+/** Options for constructing a {@link Bibliography}. */
+export interface BibliographyOptions {
+    /**
+     * BibTeX input — either a raw BibTeX string or a file path.
+     * When a file path is given, it is read synchronously at construction time.
+     */
+    data: string;
+    /**
+     * CSL style — a built-in template name (e.g. `'apa'`), raw CSL XML, or a
+     * file path to a `.csl` file.  When a file path is given, it is read
+     * synchronously.
+     *
+     * When raw XML is provided, it is registered under an internal
+     * deterministic name (based on content hash) and used automatically by
+     * {@link Bibliography.formatHtml} and {@link Bibliography.formatEntry}.
+     *
+     * @default 'apa'
+     */
+    cslStyle?: string;
+    /**
+     * BibTeX field names to preserve through the citation-js pipeline.
+     * These are extracted from the raw BibTeX parse and made available on
+     * each {@link BibEntry} under `.custom`.
+     *
+     * Common examples: `['publication-status', 'arxiv', 'mrnumber', 'project']`.
+     */
+    customFields?: string[];
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@behackl/citation-js-extras",
+  "version": "0.1.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"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "citation-js",
+    "bibtex",
+    "bibliography",
+    "csl",
+    "custom-fields",
+    "academic"
+  ],
+  "author": "Benjamin Hackl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/behackl/citation-js-extra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/behackl/citation-js-extra/issues"
+  },
+  "homepage": "https://github.com/behackl/citation-js-extra#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "citation-js": ">=0.7.0"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}