@stesura/bibliography

Every plugin the bibliography needs. citationClipboardPlugin also runs in sub-editors; bibliographyPlugin is excluded from them by core.

Keeps citations and bibliographies rendered:

• in appendTransaction (sync), registers sources carried by pasted citations, flattens citations out of headers/footers, flags missing;
• after a change touching citations, rebuilds the registry store on a microtask (the TOC pattern);
• formats, debounced, and writes text / entries in a transaction kept out of history, so undo never steps through a re-render.

Options for bibliographyPlugin and bibliographyPlugins.

Runs any pending formatting now and resolves once its result is in the doc. For tests and for exports that need fresh text.

Replaces the selection with a citation and node-selects it. The plugin renders its text. False without items or where a citation can’t go.

What insertCitation and insertCitationAsFootnote take.

Whether a citation could replace the selection. The toolbar probes it.

Inserts a footnote at the end of the selection whose text is the citation: what a note style (Chicago notes) expects. Built by node name, as the notes plugin would, so this package needs no references import: the notes plugin numbers the anchor and keeps the body.

Changes the citation at pos (the selected one by default).

Removes one source from a citation; the whole citation when it was the last.

Moves the caret just after the citation at pos.

The citation at pos, or the selected one.

Inserts a bibliography at the caret. Refused where the schema can’t hold one (cells, notes, headers).

The bibliography at pos, or the selected one.

Changes a bibliography’s scope, uncited-sources and type filter.

Sets includeUncited on every bibliography in the document. False when there is none.

Sets the CSL style and, optionally, the locale (null: the document language).

Replaces a bibliography with its entries as plain paragraphs (Word’s “Convert bibliography to static text”): they stop following the citations.

Selects the bibliography listing sourceId: what a citation’s activation does, like a cross-reference’s. Doesn’t scroll: the caller reveals the entry (bibliography-react’s useGoToSource). False when no bibliography lists it.

Adds a source. An id taken (or empty) is replaced by a free one derived from the record; onAdded gets the id it ended up with. Never blocks on validation: an incomplete source is a placeholder, not an error.

Adds several sources in one step (an import). A record of a work the document already holds is skipped; a taken id is replaced by a free one. onAdded gets the count added.

Replaces the source with source.id.

Removes a source. Citations to it stay, flagged missing, as Word does: the text they show is kept until the source returns or they are deleted.

Merges duplicates into keepId: their citations are re-pointed (a citation citing both keeps one item) and the duplicates removed. Root editor only: the citations of the whole document, note bodies included, are rewritten.

The root doc’s sources.

The root doc’s source with this id.

A DOI without resolver prefix, lowercased; "" for none.

What makes two records the same work: the DOI when there is one, else the normalized title, year and first author. Null when there is too little to tell.

The plugin’s registry: citation order and per-source usage, and the bibliographies to render.

A bibliography node as the plugin renders it.

The default formatter: citeproc-js, with styles and locales from the adapter. One engine per style, locale and source set; a batch that edits a single citation in place goes through processCitationCluster, anything else (insertions, reorders) rebuilds the processor state, which sidesteps citeproc’s incremental quirks on reorder.

Turns sources and citations into runs. The citeproc implementation is the default.

Everything a CitationFormatter needs for one pass over the document.

A formatter’s output: runs, never HTML.

One citation as the formatter sees it, in reading order.

CSL XML of a bundled style. Rejects for a style that isn’t bundled.

CSL locale XML of the bundled locale closest to lang.

What a user typed into the citation picker: an identifier the lookup ladder can resolve, or a free-text query.

classifyInput’s result: an identifier, normalised, or a free-text query.

A DOI anywhere in the text, doi: and resolver prefixes included.

A DOI without resolver prefix or trailing punctuation, lowercased (DOIs are case-insensitive).

Whether the string is a bare DOI (10. prefix, registrant, suffix); no resolver prefix.

Whether the string is a valid ISBN-10 or ISBN-13.

Whether the string is an ISBN-10 with a valid check digit; spaces and hyphens ignored.

Whether the string is a 978/979 ISBN-13 with a valid check digit; spaces and hyphens ignored.

Whether the string is an ORCID iD, bare or as an orcid.org URL, with a valid ISO 7064 11,2 check digit.

Whether the string is an arXiv id, new (2101.00001v2) or old (hep-th/9901001) scheme, arXiv: prefix allowed.

Whether the string is an absolute http(s) URL.

The problems with one source, field by field.

Document-level problems: duplicates (same DOI, or same title, year and first author), uncited sources, and citations to sources the document lacks.

A problem with a source or a citation. Never a refusal: an incomplete source is a placeholder, and validation only reports. code is a stable key the UI translates; params fill its message.

The type’s field rule: which fields it needs and which it should have.

Fields a CSL type needs: each required entry is satisfied by any one of its fields (“author or editor”).

Sources from BibTeX, RIS, EndNote, PubMed (MEDLINE) or CSL-JSON text, the format detected.

Which format a file’s text is in, by its first significant characters.

Sources from BibTeX or BibLaTeX text, ids from the citation keys.

Sources from RIS text (EndNote, Mendeley, most databases).

Sources from CSL-JSON: an array of items, a single item, or Zotero’s { items: [...] }.

Parsed sources, ids as the file named them (citation keys); add them with addSource.

A record the parser skipped, with its line when the format has lines.

One BibTeX name: “Last, First”, “Last, Jr, First” or “First von Last”.

A CSL date from the forms bibliographic exports write: ISO-ish (2020, 2020-05-03, 2020/05), May 2020, and ISO ranges 2019/2020 or 2019-01/2019-03. Undefined for nothing usable; the text is kept in raw when it doesn’t parse.