@behackl/citation-js-extras 0.3.0 → 0.4.0

package/README.md

@@ -96,6 +96,7 @@ See [Mathematics and sanitizing](docs/math.md).
 | 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) |
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { BibEntry, BibliographyOptions, EntryLinks, FormatOptions } from "./types.js";
-export type { BadgeConfig, BadgeFunction, BibEntry, BibliographyOptions, EntryLinks, FormatDefaults, FormatOptions, HtmlAttributes, Link, 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…`,
@@ -44,6 +44,7 @@ export declare class Bibliography {
     /** 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;
@@ -83,6 +84,21 @@ export declare class Bibliography {
      * 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 withInherited;
     /** Per-call options win over the defaults given to the constructor. */
     private mergeOptions;
     /**

package/dist/index.js

@@ -80,6 +80,7 @@ export class Bibliography {
     /** All parsed entries. */
     entries;
     customFieldNames;
+    bibtexEntries = new Map();
     math;
     /** Formatting defaults from the constructor; each call may override them. */
     formatDefaults;
@@ -97,12 +98,11 @@ export class Bibliography {
         // Two-pass parse: raw (preserves all fields) + CSL (for formatting)
         const { plugins } = Cite;
         const rawEntries = plugins.input.chainLink(bibData);
-        const rawMap = new Map();
         const duplicates = new Set();
         for (const entry of rawEntries) {
-            if (rawMap.has(entry.label))
+            if (this.bibtexEntries.has(entry.label))
                 duplicates.add(entry.label);
-            rawMap.set(entry.label, entry.properties);
+            this.bibtexEntries.set(entry.label, entry);
         }
         // Raw fields are merged by key, so a duplicate would silently give one
         // entry the other's fields.
@@ -120,7 +120,7 @@ export class Bibliography {
             : new Cite(bibData);
         this.entries = cite.data.map((csl) => {
             const key = String(csl["citation-key"] || csl.id);
-            const raw = rawMap.get(key) ?? {};
+            const raw = this.bibtexEntries.get(key)?.properties ?? {};
             const custom = {};
             for (const f of this.customFieldNames) {
                 const value = raw[f.toLowerCase()] ?? raw[f];
@@ -205,9 +205,62 @@ export class Bibliography {
     links(entry, options = {}) {
         return this.resolveLinks(entry, this.mergeOptions(options));
     }
+    /**
+     * 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, options = {}) {
+        const source = this.bibtexEntries.get(entry.key);
+        if (!source || source.properties !== entry.raw) {
+            throw new Error(`entry ${entry.key}: not in this bibliography`);
+        }
+        const { type } = source;
+        const fields = this.withInherited(type, entry.raw);
+        if (fields !== entry.raw)
+            delete fields.crossref;
+        const exclude = new Set((options.exclude ?? []).map(field => field.toLowerCase()));
+        const lines = Object.entries(fields)
+            .filter(([name, value]) => value != null && !exclude.has(name))
+            .map(([name, value]) => `  ${name} = ${bibtexValue(name, value)},`);
+        return [`@${type}{${entry.key},`, ...lines, "}"].join("\n");
+    }
     // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    withInherited(type, raw) {
+        const parent = raw.crossref == null ? undefined : this.bibtexEntries.get(String(raw.crossref));
+        if (!parent || parent.properties === raw)
+            return raw;
+        const inherited = { ...this.withInherited(parent.type, parent.properties) };
+        for (const field of NOT_INHERITED)
+            delete inherited[field];
+        if ((parent.type === "mvbook" || parent.type === "book") && BOOK_PARTS.includes(type)) {
+            inherited.bookauthor = inherited.author;
+        }
+        const [prefix, children] = TITLE_INHERITANCE[parent.type] ?? [];
+        if (prefix && children.includes(type)) {
+            inherited[`${prefix}title`] = inherited.title;
+            inherited[`${prefix}subtitle`] = inherited.subtitle;
+            if (prefix !== "journal")
+                inherited[`${prefix}titleaddon`] = inherited.titleaddon;
+            for (const field of TITLE_FIELDS)
+                delete inherited[field];
+        }
+        const fields = { ...raw };
+        for (const [name, value] of Object.entries(inherited))
+            if (!Object.hasOwn(fields, name))
+                fields[name] = value;
+        return fields;
+    }
     /** Per-call options win over the defaults given to the constructor. */
     mergeOptions(options) {
         const merged = { ...options };
@@ -397,6 +450,39 @@ export function linkifyBareUrls(html) {
 // ---------------------------------------------------------------------------
 // Fields and links
 // ---------------------------------------------------------------------------
+/**
+ * Biblatex's non-inherited metadata. Intentionally uses `shorthand` and
+ * `shorthandintro`: plugin-bibtex 0.7.21 misspells these as `shortand` and
+ * `shortandintro`, so this exclusion differs from that version's implementation.
+ */
+const NOT_INHERITED = [
+    "ids", "crossref", "xref", "entryset", "entrysubtype", "execute", "label", "options", "presort",
+    "related", "relatedoptions", "relatedstring", "relatedtype", "shorthand", "shorthandintro", "sortkey",
+];
+const TITLE_FIELDS = ["title", "subtitle", "titleaddon", "shorttitle", "sorttitle", "indextitle", "indexsorttitle"];
+const BOOK_PARTS = ["inbook", "bookinbook", "suppbook"];
+const COLLECTION_PARTS = ["incollection", "inreference", "suppcollection"];
+/** A parent's `title` becomes `<prefix>title` in children of these types. */
+const TITLE_INHERITANCE = {
+    mvbook: ["main", ["book", ...BOOK_PARTS]],
+    mvcollection: ["main", ["collection", "reference", ...COLLECTION_PARTS]],
+    mvreference: ["main", ["collection", "reference", ...COLLECTION_PARTS]],
+    mvproceedings: ["main", ["proceedings", "inproceedings"]],
+    book: ["book", BOOK_PARTS],
+    collection: ["book", COLLECTION_PARTS],
+    reference: ["book", COLLECTION_PARTS],
+    proceedings: ["book", ["inproceedings"]],
+    periodical: ["journal", ["article", "suppperiodical"]],
+};
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+/** A field value in braces, with the whitespace BibTeX would compress anyway compressed. */
+function bibtexValue(name, value) {
+    const text = String(value).replace(/\s*\n\s*/g, " ");
+    // citation-js reads `month = mar` as "03"; the abbreviation is what BibTeX styles expect.
+    if (name === "month" && /^(?:0[1-9]|1[0-2])$/.test(text))
+        return MONTHS[Number(text) - 1];
+    return `{${text}}`;
+}
 /**
  * The value of a BibTeX field, and the only place fields are read. Names are
  * case-insensitive. A field named like an eprint archive falls back to
@@ -497,7 +583,7 @@ function decorate(html, titleLinked, links, options) {
     if (links.title && !titleLinked)
         out += ` ${linkHtml(links.title, escapeHtml(links.title.url), options)}`;
     if (links.badges.length && options.appendBadges !== false) {
-        const badges = links.badges.map(link => linkHtml(link, escapeHtml(link.label ?? ""), options));
+        const badges = links.badges.map(link => linkHtml(link, escapeHtml(link.label), options));
         out += ` <span class="${escapeAttr(options.badgeListClassName ?? "bib-links")}">${badges.join(" ")}</span>`;
     }
     return out;
@@ -626,7 +712,7 @@ function renderAttributes(attrs) {
     for (const [k, v] of Object.entries(attrs)) {
         if (v === true)
             parts.push(k);
-        else if (v !== false)
+        else if (v !== false && v !== undefined)
             parts.push(`${k}="${escapeAttr(String(v))}"`);
     }
     return parts.length ? " " + parts.join(" ") : "";

package/dist/types.d.ts

@@ -68,8 +68,11 @@ export interface BadgeConfig {
 }
 /** 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>;
+/**
+ * HTML attributes; `true` renders a valueless attribute, `false` and
+ * `undefined` omit it.
+ */
+export type HtmlAttributes = Record<string, string | boolean | undefined>;
 /** A link the library resolved for an entry: its title link or a badge. */
 export interface Link {
     kind: "title" | "badge";
@@ -84,10 +87,21 @@ export interface Link {
     className?: string;
     entry: BibEntry;
 }
+/** An entry's title link. */
+export interface TitleLink extends Link {
+    kind: "title";
+    label?: never;
+    className?: never;
+}
+/** A badge link, which always has a label. */
+export interface BadgeLink extends Link {
+    kind: "badge";
+    label: string;
+}
 /** The links of one entry, as returned by `Bibliography.links`. */
 export interface EntryLinks {
-    title?: Link;
-    badges: Link[];
+    title?: TitleLink;
+    badges: BadgeLink[];
 }
 /** Synchronous renderer returning trusted HTML. Sanitize untrusted renderer output. */
 export type MathRenderer = (tex: string, context: {
@@ -174,7 +188,7 @@ export interface FormatOptions {
      * `className`; an `href` replaces the URL (it must still be `http(s)`,
      * `mailto` or relative, or the link is dropped).
      */
-    linkAttributes?: (link: Link) => HtmlAttributes;
+    linkAttributes?: (link: TitleLink | BadgeLink) => 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:
@@ -200,6 +214,11 @@ export interface FormatOptions {
      */
     linkifyUrls?: boolean;
 }
+/** Options for {@link Bibliography.bibtex}. */
+export interface BibtexOptions {
+    /** Fields to leave out, case-insensitively, e.g. private ones like `status` or `file`. */
+    exclude?: string[];
+}
 /** A bibliography entry enriched with custom BibTeX fields. */
 export interface BibEntry {
     /** The CSL-JSON object used by citation-js for formatting. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@behackl/citation-js-extras",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -19,6 +19,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.test.json",
     "test:watch": "vitest",
     "test:package": "pnpm build && node scripts/test-package.mjs",
     "prepublishOnly": "tsc"