@behackl/citation-js-extras 0.2.0 → 0.3.0

package/dist/math.d.ts

@@ -6,5 +6,9 @@ export declare class MathProtector {
     constructor(source: string);
     protect(properties: Record<string, any>, key: string): Record<string, any>;
     private scan;
+    /**
+     * Replace placeholders in text (never in attribute values). A renderer error
+     * is rethrown naming the entry, so it can be traced to the .bib file.
+     */
     restore(html: string, render?: MathRenderer): string;
 }

package/dist/math.js

@@ -18,10 +18,11 @@ export class MathProtector {
         return Object.fromEntries(Object.entries(properties).map(([field, value]) => [
             field,
             TEXT_FIELDS.has(field) && typeof value === "string"
-                ? this.scan(value, `${key}.${field}`) : value,
+                ? this.scan(value, key, field) : value,
         ]));
     }
-    scan(value, context) {
+    scan(value, key, field) {
+        const context = `${key}.${field}`;
         let out = "";
         for (let i = 0; i < value.length;) {
             const opener = value.startsWith("$$", i) ? "$$"
@@ -51,23 +52,33 @@ export class MathProtector {
             if (!token) {
                 token = `${this.prefix}${this.expressions.size}end`;
                 this.tokensBySource.set(source, token);
-                this.expressions.set(token, { tex, source, display: opener === "$$" || opener === "\\[" });
+                this.expressions.set(token, { tex, source, key, display: opener === "$$" || opener === "\\[" });
             }
             out += token;
             i = end + closer.length;
         }
         return out;
     }
+    /**
+     * Replace placeholders in text (never in attribute values). A renderer error
+     * is rethrown naming the entry, so it can be traced to the .bib file.
+     */
     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);
+                if (!render)
+                    return escapeHtml(expression.source);
+                try {
+                    return render(expression.tex, { display: expression.display });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`entry ${expression.key}: ${message}`, { cause: error });
+                }
             })).join("");
     }
 }

package/dist/types.d.ts

@@ -22,14 +22,30 @@
  * { field: 'zbl', label: 'zbMATH',
  *   url: 'https://zbmath.org/?q=an:$1',
  *   match: /^(\d{4}\.\d{5})$/ }
+ *
+ * @example
+ * // Functions for what a template can't express, e.g. a site-relative link:
+ * { field: 'project', label: (code) => code,
+ *   url: (code) => `/projects/${code.toLowerCase()}/` }
  */
 export interface BadgeConfig {
-    /** BibTeX field name to read the value from. */
+    /**
+     * BibTeX field to read, case-insensitively. A field named like an eprint
+     * archive (`arxiv`, `hal`, ...) also reads `eprint` when `eprinttype` or
+     * `archivePrefix` names that archive.
+     */
     field: string;
-    /** Text to display inside the badge. */
-    label: string;
-    /** URL template — `$1` is replaced by the field value. */
-    url: string;
+    /**
+     * Text of the badge (HTML-escaped), or a function of the matched value and
+     * the entry.
+     */
+    label: string | BadgeFunction;
+    /**
+     * URL template in which `$1` is replaced by the matched value, or a function
+     * of the matched value and the entry. `http(s)`, `mailto` and relative URLs
+     * (`/…`, `./…`, `../…`, `#…`, `?…`) are kept; anything else drops the badge.
+     */
+    url: string | BadgeFunction;
     /**
      * Optional regex applied to the field value.
      *
@@ -38,29 +54,72 @@ export interface BadgeConfig {
      *   group (or the full match when there are no capture groups).
      */
     match?: RegExp;
-    /** CSS class name(s) for the badge `<a>` element. */
+    /**
+     * Split the field into several values, each rendered as its own badge, e.g.
+     * `project = {Alpha, Beta}` with `split: ","`. Values are trimmed and
+     * empty ones skipped; `match`, `label` and `url` apply to each value.
+     */
+    split?: string | RegExp;
+    /**
+     * CSS class name(s) for the badge `<a>` element. For classes that depend on
+     * the value or the entry, use {@link FormatOptions.linkAttributes}.
+     */
+    className?: string;
+}
+/** Computes a badge's label or URL from the matched field value. */
+export type BadgeFunction = (value: string, entry: BibEntry) => string;
+/** HTML attributes; `true` renders a valueless attribute, `false` omits it. */
+export type HtmlAttributes = Record<string, string | boolean>;
+/** A link the library resolved for an entry: its title link or a badge. */
+export interface Link {
+    kind: "title" | "badge";
+    /** The field the link was built from, as configured (`doi`, `url`, ...). */
+    field: string;
+    /** The matched value: `10.1000/x` for a DOI, one part of a `split` field. */
+    value: string;
+    url: string;
+    /** Badge text; absent for the title link. */
+    label?: string;
+    /** The badge's configured `className`, if any. */
     className?: string;
+    entry: BibEntry;
+}
+/** The links of one entry, as returned by `Bibliography.links`. */
+export interface EntryLinks {
+    title?: Link;
+    badges: Link[];
 }
 /** Synchronous renderer returning trusted HTML. Sanitize untrusted renderer output. */
 export type MathRenderer = (tex: string, context: {
     display: boolean;
 }) => string;
-/** Options passed to {@link Bibliography.formatHtml}. */
+/**
+ * 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.
-     * 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`.
+     * Fields to use for linking the title, checked in order; the first that
+     * yields a URL wins. A field with a {@link badgePresets} entry (`doi`,
+     * `arxiv`, ...) is expanded by that preset; another field with a configured
+     * badge by that badge; any other field must hold a URL itself.
+     * Overrides the constructor default, if any.
      *
      * @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,14 +128,73 @@ export interface FormatOptions {
     list?: "ol" | "ul" | "div";
     /**
      * HTML attributes for the wrapper element (e.g. `{ reversed: true }`).
-     * Boolean `true` renders as a valueless attribute.
+     * Boolean `true` renders as a valueless attribute. A `class` is added to
+     * `csl-bib-body`.
      *
      * @default { reversed: true }  (when list is 'ol')
      */
-    listAttributes?: Record<string, string | boolean>;
+    listAttributes?: HtmlAttributes;
     /**
-     * Auto-linkify bare `http(s)://` URLs in the rendered output that aren't
-     * already inside `<a>`, `<script>`, or `<style>` tags.
+     * Extra HTML attributes for each entry's `<li>`/`<div>` in `formatHtml`,
+     * e.g. to add anchors: `(entry) => ({ id: 'pub-' + entry.key })`. A `class` is added to
+     * `csl-entry`.
+     */
+    itemAttributes?: (entry: BibEntry) => HtmlAttributes;
+    /**
+     * Class of the `<span>` wrapping an entry's badges.
+     *
+     * @default 'bib-links'
+     */
+    badgeListClassName?: string;
+    /**
+     * Also let the CSL style print identifiers that are already linked. By
+     * default, the field used for the title link and the field of every rendered
+     * badge are withheld from the style, so a DOI or URL is not printed again
+     * as text next to its link.
+     *
+     * @default false
+     */
+    printLinkedIdentifiers?: boolean;
+    /**
+     * Sanitize the finished HTML. Runs while formulas are still placeholders, so
+     * `renderMath` output is inserted afterwards and never passes through the
+     * sanitizer (see "Sanitizing formatted output" in the README).
+     */
+    sanitize?: (html: string) => string;
+    /**
+     * Leave the badges out of the HTML, e.g. to render them yourself from
+     * `bib.links(entry)`. They are still withheld from the style.
+     *
+     * @default true
+     */
+    appendBadges?: boolean;
+    /**
+     * Extra attributes for every link the library writes: the title link, the
+     * badges, and the fallback title URL. A `class` is added to the badge's
+     * `className`; an `href` replaces the URL (it must still be `http(s)`,
+     * `mailto` or relative, or the link is dropped).
+     */
+    linkAttributes?: (link: Link) => HtmlAttributes;
+    /**
+     * Wrap the rendered HTML of each CSL variable in the bibliography (and the
+     * title outside its link), e.g. to mark it for CSS:
+     * `(html, { variable }) => '<span data-csl-variable="' + variable + '">' + html + '</span>'`.
+     */
+    wrapVariable?: (html: string, context: {
+        variable: string;
+        entry: BibEntry;
+    }) => string;
+    /**
+     * Locale for the CSL style's terms and dates. citation-js ships `en-US`,
+     * `de-DE`, `fr-FR`, `es-ES` and `nl-NL`.
+     *
+     * @default 'en-US'
+     */
+    lang?: string;
+    /**
+     * Turn bare `http(s)://` URLs that the style prints (e.g. in a `note`) into
+     * links. Applied to each variable as citeproc renders it, never to text the
+     * style adds around variables. Overrides the constructor default, if any.
      *
      * @default true
      */
@@ -98,8 +216,13 @@ 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" | "itemAttributes" | "badgeListClassName" | "printLinkedIdentifiers" | "sanitize" | "lang" | "appendBadges" | "linkAttributes" | "wrapVariable">;
 /** 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.
@@ -125,7 +248,8 @@ export interface BibliographyOptions {
     /**
      * 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`.
+     * each {@link BibEntry} under `.custom`, keyed as given here. Matching is
+     * case-insensitive, like BibTeX: `archivePrefix` finds `archiveprefix`.
      *
      * Common examples: `['publication-status', 'arxiv', 'mrnumber', 'project']`.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@behackl/citation-js-extras",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -63,5 +63,8 @@
     "onlyBuiltDependencies": [
       "esbuild"
     ]
+  },
+  "dependencies": {
+    "citeproc": "^2.4.6"
   }
 }