@fiduswriter/document 0.1.0-alpha.1

package/src/exporter/tools/zotero_csl.js

@@ -0,0 +1,93 @@
+/**
+ * Helper functions for creating Zotero-compatible citation data.
+ * Uses CSLExporter from biblatex-csl-converter to convert Fidus Writer's
+ * internal BibLaTeX format to CSL-JSON.
+ */
+
+import {CSLExporter} from "biblatex-csl-converter"
+
+/**
+ * Generate a random citation ID similar to Zotero's format.
+ * Zotero uses 8-10 character alphanumeric IDs.
+ */
+function generateCitationId() {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789"
+    let id = ""
+    for (let i = 0; i < 8; i++) {
+        id += chars.charAt(Math.floor(Math.random() * chars.length))
+    }
+    return id
+}
+
+/**
+ * Convert bibliography entries to CSL-JSON format.
+ * @param {Object} bibDB - The bibliography database
+ * @param {Array} ids - Array of entry IDs to convert
+ * @returns {Object} Object mapping IDs to CSL-JSON entries
+ */
+function convertToCSL(bibDB, ids) {
+    const exporter = new CSLExporter(bibDB.db, ids)
+    return exporter.parse()
+}
+
+/**
+ * Create a Zotero citation JSON object.
+ * @param {Array} references - Array of {id, prefix?, locator?} from citation node
+ * @param {Object} bibDB - Bibliography database
+ * @param {string} formattedCitation - Pre-formatted citation text from citeproc
+ * @param {string} citationId - Optional citation ID (generated if not provided)
+ * @returns {Object} Zotero citation JSON object
+ */
+export function createZoteroCitation(
+    references,
+    bibDB,
+    formattedCitation,
+    citationId = null
+) {
+    const citationID = citationId || generateCitationId()
+
+    // Get the IDs of all referenced items
+    const ids = references.map(ref => ref.id)
+
+    // Convert to CSL-JSON
+    const _cslData = convertToCSL(bibDB, ids)
+    const citationItems = references
+        .map(ref => {
+            const entry = bibDB.db[ref.id]
+
+            if (!entry) {
+                return null
+            }
+            const citationKey = entry.entry_key || String(ref.id)
+            const item = {
+                id: ref.id,
+                uris: [],
+                itemData: {
+                    ...ref.item,
+                    id: citationKey
+                }
+            }
+
+            if (ref.locator) {
+                item.locator = ref.locator
+            }
+
+            if (ref.prefix) {
+                item.prefix = ref.prefix
+            }
+
+            return item
+        })
+        .filter(item => item !== null)
+
+    return {
+        citationID,
+        properties: {
+            formattedCitation,
+            plainCitation: formattedCitation,
+            noteIndex: 0
+        },
+        citationItems,
+        schema: "https://github.com/citation-style-language/schema/raw/master/csl-citation.json"
+    }
+}

package/src/importer/citations.js

@@ -0,0 +1,129 @@
+/**
+ * Shared citation utilities for DOCX and ODT importers.
+ *
+ * Converts a CitationResult (from DocxCitationsParser or OdtCitationsParser
+ * static methods) plus a BibDB (entries) into a Fidus Writer citation node,
+ * and merges the new BibDB entries into the document bibliography.
+ *
+ * The `bibliography` object passed in is mutated in place: new entries are
+ * appended with sequential numeric string keys ("1", "2", …).
+ */
+
+/**
+ * Given a BibDB returned by a static Citations parser call and the current
+ * document bibliography, add every entry that is not yet present (matched by
+ * entry_key) and return a mapping from entry_key → bibliography key string.
+ *
+ * @param {Object} entries  BibDB (Record<number, EntryObject>) from parser
+ * @param {Object} bibliography  Fidus Writer bibliography (mutated in place)
+ * @returns {Object}  Map of entry_key → bibKey string
+ */
+function mergeBibEntries(entries, bibliography, bibDB) {
+    const keyMap = {}
+
+    for (const entry of Object.values(entries)) {
+        if (!entry || !entry.entry_key) {
+            continue
+        }
+        const entryKey = entry.entry_key
+
+        // Check whether this entry_key is already in the bibliography.
+        const existing = Object.entries(bibliography).find(
+            ([, bibEntry]) => bibEntry && bibEntry.entry_key === entryKey
+        )
+
+        if (existing) {
+            keyMap[entryKey] = existing[0]
+        } else {
+            if (bibDB && Object.keys(entry.fields).length === 0) {
+                // Jabref citations don't contain any fields. Look up values in bibDB instead
+                const bibEntry = Object.values(bibDB.db).find(
+                    bibEntry => bibEntry && bibEntry.entry_key === entryKey
+                )
+                if (bibEntry) {
+                    entry.fields = JSON.parse(JSON.stringify(bibEntry.fields))
+                    entry.bib_type = bibEntry.bib_type
+                }
+            }
+            // TODO: add for jabref citations - according to entry_key import from user
+            // library if useExternalDB is true
+            const bibKey = String(Object.keys(bibliography).length + 1)
+            bibliography[bibKey] = entry
+            keyMap[entryKey] = bibKey
+        }
+    }
+
+    return keyMap
+}
+
+/**
+ * Convert a CitationResult from a static DocxCitationsParser or
+ * OdtCitationsParser call into a Fidus Writer citation node.
+ *
+ * The `bibliography` object is mutated in place to include any new entries.
+ *
+ * Each item in `metadata` (when `retrieveMetadata` was true) may carry:
+ *   - id         : entry_key string identifying which entry this item refers to
+ *   - prefix     : citation prefix text
+ *   - suffix     : citation suffix / locator text (used as `locator`)
+ *   - locator    : explicit locator string (preferred over suffix when present)
+ *   - authorOnly : boolean – render author name only (maps to "textcite")
+ *   - suppressAuthor : boolean – suppress author name (ignored, maps to default)
+ *   - authorYear : boolean – render author name and year (maps to "textcite")
+ *
+ * `format` on the returned citation node matches the Fidus Writer citation schema:
+ *   - "textcite"  when authorOnly or authorYear is set on the (single) item (biblatex \textcite)
+ *   - "autocite"  otherwise, including when suppressAuthor is set (biblatex \autocite)
+ *
+ * @param {Object} result       CitationResult from a static parser method
+ * @param {Object} bibliography Fidus Writer bibliography (mutated in place)
+ * @returns {Object|null}  ProseMirror citation node or null
+ */
+export function citationResultToNode(result, bibliography, bibDB = false) {
+    if (!result || !result.isCitation || !result.entries) {
+        return null
+    }
+    const entries = result.entries
+    const metadata = result.metadata || []
+
+    if (Object.keys(entries).length === 0) {
+        return null
+    }
+    const keyMap = mergeBibEntries(entries, bibliography, bibDB)
+    // Build the references array from entries.
+    //
+    const references = Object.entries(entries).map(([_entryId, entry]) => {
+        const entryKey = entry.entry_key
+        const entryMetadata = metadata.find(meta => meta.entry_key === entryKey)
+        return {
+            id: keyMap[entryKey],
+            prefix: entryMetadata?.prefix || "",
+            locator: entryMetadata?.locator || entryMetadata?.suffix || ""
+        }
+    })
+
+    if (references.length === 0) {
+        return null
+    }
+
+    // Determine citation format from the first item's metadata flags.
+    // "textcite" corresponds to biblatex's \textcite (author-in-text / authorYear).
+    // Even authorOnly comes through as "textcite" since it's a similar concept.
+    // Everything else, including suppressAuthor, falls back to "autocite".
+    // TODO: When an authorOnly citation is followed directly by a suppressAuthor
+    // citation, this would display the same as a single authorYear citation and
+    // should be treated as such.
+    const format =
+        metadata.length === 1 &&
+        (metadata[0].authorOnly || metadata[0].authorYear)
+            ? "textcite"
+            : "autocite"
+
+    return {
+        type: "citation",
+        attrs: {
+            format,
+            references
+        }
+    }
+}

package/src/importer/docx/citations.js

@@ -0,0 +1,123 @@
+import {DocxCitationsParser} from "biblatex-csl-converter"
+import {citationResultToNode} from "../citations.js"
+
+/**
+ * Check whether a field instruction string belongs to a citation.
+ * Uses DocxCitationsParser.fieldCitation() with retrieve=false so no BibDB
+ * is allocated for the check.
+ *
+ * @param {string} instrText - Concatenated w:instrText content
+ * @returns {boolean}
+ */
+export function isDocxCitationField(instrText) {
+    if (!instrText) {
+        return false
+    }
+    return DocxCitationsParser.fieldCitation(instrText, false).isCitation
+}
+
+/**
+ * Check whether a field instruction string belongs to a bibliography region
+ * (Zotero ZOTERO_BIBL, Word native BIBLIOGRAPHY, EN.REFLIST, etc.).
+ * Uses DocxCitationsParser.fieldBibliography() with the accumulated
+ * instruction text between begin and separate markers.
+ *
+ * @param {string} instrText - Concatenated w:instrText content
+ * @returns {boolean}
+ */
+export function isDocxBibliographyField(instrText) {
+    if (!instrText) {
+        return false
+    }
+
+    return DocxCitationsParser.fieldBibliography(instrText).isBibliography
+}
+
+/**
+ * Check whether a w:sdt node contains a citation (Mendeley v3, Citavi).
+ * Uses DocxCitationsParser.sdtCitation() with retrieve=false.
+ *
+ * @param {Object} sdtNode - The parsed w:sdt XMLElement node
+ * @returns {boolean}
+ */
+export function isDocxSdtCitation(sdtNode) {
+    if (!sdtNode) {
+        return false
+    }
+    return DocxCitationsParser.sdtCitation(sdtNode.outerXML, false).isCitation
+}
+
+/**
+ * Check whether a w:sdt node is a bibliography rendering region
+ * (Mendeley v3 bibliography, Citavi bibliography).
+ * Uses DocxCitationsParser.sdtBibliography().
+ *
+ * @param {Object} sdtNode - The parsed w:sdt XMLElement node
+ * @returns {boolean}
+ */
+export function isDocxSdtBibliography(sdtNode) {
+    if (!sdtNode) {
+        return false
+    }
+    return DocxCitationsParser.sdtBibliography(sdtNode.outerXML).isBibliography
+}
+
+/**
+ * Parse a citation from a DOCX field instruction and add any new bibliography
+ * entries into `bibliography`.
+ *
+ * Handles all field-based citation managers: Zotero, Mendeley Desktop
+ * (legacy), EndNote (both inline and fldData forms), Citavi (older ADDIN
+ * form), and Word native (requires sourcesXml).
+ *
+ * @param {string}      instrText    - Concatenated w:instrText for this field
+ * @param {string|null} fldData      - Base64 content of w:fldData (EndNote),
+ *                                     or null/undefined if absent
+ * @param {string|null} sourcesXml   - Content of customXml/item1.xml (required
+ *                                     only for Word-native citations)
+ * @param {Object}      bibliography - Fidus Writer bibliography (mutated)
+ * @returns {Object|null}  ProseMirror citation node or null
+ */
+export function parseDocxFieldCitation(
+    instrText,
+    fldData,
+    sourcesXml,
+    bibliography
+) {
+    if (!instrText) {
+        return null
+    }
+    const options = sourcesXml ? {sourcesXml} : {}
+    const result = DocxCitationsParser.fieldCitation(
+        instrText,
+        true, // retrieve
+        true, // retrieveMetadata
+        true, // extractWordNative
+        fldData || undefined,
+        options
+    )
+    const node = citationResultToNode(result, bibliography)
+    return node
+}
+
+/**
+ * Parse a citation from a DOCX structured document tag (w:sdt) and add any
+ * new bibliography entries into `bibliography`.
+ *
+ * Handles Mendeley Cite v3 and Citavi (modern SDT form).
+ *
+ * @param {Object} sdtNode      - The parsed w:sdt XMLElement node
+ * @param {Object} bibliography - Fidus Writer bibliography (mutated)
+ * @returns {Object|null}  ProseMirror citation node or null
+ */
+export function parseDocxSdtCitation(sdtNode, bibliography) {
+    if (!sdtNode) {
+        return null
+    }
+    const result = DocxCitationsParser.sdtCitation(
+        sdtNode.outerXML,
+        true, // retrieve
+        true // retrieveMetadata
+    )
+    return citationResultToNode(result, bibliography)
+}