@fiduswriter/document 0.1.0-alpha.3 → 0.1.0-alpha.5

package/src/types.ts

@@ -0,0 +1,314 @@
+/**
+ * Core types shared across the @fiduswriter/document package.
+ *
+ * These types describe the JSON-shaped document tree that Fidus Writer stores
+ * and exchanges with its importers/exporters. They intentionally mirror the
+ * ProseMirror schema while staying serialisable.
+ */
+
+/** A generic JSON value. */
+export type JSONValue =
+    | string
+    | number
+    | boolean
+    | null
+    | JSONValue[]
+    | {[key: string]: JSONValue}
+
+/** Attributes that every Fidus node may carry. */
+export interface NodeAttrs {
+    [key: string]: unknown
+    id?: string
+    track?: Track[]
+    hidden?: boolean
+}
+
+/** A tracked change entry attached to a node or mark. */
+export interface Track {
+    type: "insertion" | "deletion" | "block_change"
+    user: number
+    username: string
+    date: number
+    approved?: boolean
+    before?: FidusNode
+}
+
+/** A Fidus document mark (inline formatting or annotation). */
+export interface FidusMark {
+    type: string
+    attrs?: NodeAttrs
+}
+
+/** A node in the Fidus document tree. */
+export interface FidusNode {
+    type: string
+    attrs?: NodeAttrs
+    content?: FidusNode[]
+    marks?: FidusMark[]
+    text?: string
+}
+
+/** Top-level document settings stored on the `doc` node. */
+export interface DocSettings {
+    documentstyle?: string
+    tracked?: boolean
+    citationstyle?: string
+    citationstyles?: string[]
+    language?: string
+    languages?: string[]
+    papersize?: string
+    papersizes?: string[]
+    footnote_marks?: string[]
+    footnote_elements?: string[]
+    bibliography_header?: FidusNode
+    metadata?: Record<string, JSONValue>
+    [key: string]: unknown
+}
+
+/** The root Fidus document node. */
+export interface FidusDoc {
+    type: "doc"
+    attrs?: DocSettings
+    content: FidusNode[]
+}
+
+/** A fully populated document object passed to exporters. */
+export interface ExportDoc {
+    id: string | number
+    title: string
+    path?: string
+    content: FidusNode
+    settings: DocSettings
+    comments?: Record<string, CommentData>
+    version?: string
+}
+
+/** A document contributor extracted from a contributors_part node. */
+export interface Contributor {
+    firstname?: string
+    lastname?: string
+    institution?: string
+    role?: string
+    email?: string
+    id_type?: string
+    id_value?: string
+    [key: string]: unknown
+}
+
+/** Metadata bundle assembled by exporters and passed to metadata handlers. */
+export interface ExportMetadata {
+    title: string
+    authors: Contributor[]
+    contributors: Contributor[]
+    keywords: string[]
+    language?: string
+    citationStyle?: string
+}
+
+/** A user reference passed to importers. */
+export interface User {
+    id: number
+    name?: string
+    avatar?: string
+    username?: string
+}
+
+/** A single comment thread. */
+export interface CommentData {
+    id?: number
+    user: number
+    username: string
+    date: number
+    resolved?: boolean
+    comment: FidusNode[]
+    answers?: Array<{
+        id?: string
+        user: number
+        username: string
+        date: number
+        answer: FidusNode[]
+    }>
+}
+
+/** A bibliographic database entry (format depends on the CSL engine). */
+export interface BibDBEntry {
+    entry_key?: string
+    bib_type?: string
+    fields?: Record<string, JSONValue>
+    [key: string]: JSONValue | undefined
+}
+
+/** Flat map of bibliography entries keyed by internal ID. */
+export type BibDBEntries = Record<string, BibDBEntry>
+
+/** Bibliography database wrapper used by importers/exporters. */
+export interface BibDB {
+    db: BibDBEntries
+    getDB?: () => Promise<void>
+}
+
+/** An entry in the image database. */
+export interface ImageDBEntry {
+    id: number
+    title?: string
+    file_type?: string
+    image?: string | ArrayBuffer | Blob
+    copyright?: Record<string, JSONValue>
+    [key: string]: unknown
+}
+
+/** Flat map of image entries keyed by internal ID. */
+export type ImageDBEntries = Record<string, ImageDBEntry>
+
+/** Image database wrapper used by importers/exporters. */
+export interface ImageDB {
+    db: ImageDBEntries
+}
+
+/** A parsed CSL/CSL-M stylesheet node. */
+export interface CSLStyleNode {
+    name: string
+    attrs?: Record<string, unknown>
+    children?: CSLStyleNode[]
+}
+
+/** A parsed CSL/CSL-M stylesheet. */
+export interface CSLStyle {
+    children: CSLStyleNode[]
+}
+
+/** A CSL/CSL-M stylesheet reference / engine provider. */
+export interface CSL {
+    citationType?: string
+    getStyle?: (styleId: string) => Promise<CSLStyle>
+    getEngine?: (
+        sys: unknown,
+        styleId: string,
+        lang: string
+    ) => Promise<CiteprocInstance>
+    getEngineSync?: (
+        sys: unknown,
+        styleId: string,
+        lang: string
+    ) => CiteprocInstance | undefined
+}
+
+/** A minimal citeproc-js engine interface. */
+export interface CiteprocInstance {
+    updateItems: (ids: string[]) => void
+    appendCitationCluster: (
+        citation: unknown,
+        flag?: boolean
+    ) => Array<[number, string]>
+    makeCitationCluster: (items: unknown[]) => string
+    cslXml: {dataObj: {attrs: {class: string}}}
+    citation: {opt: {layout_delimiter?: string}}
+    makeBibliography: () => BibliographyResult
+    sys?: unknown
+}
+
+/** citeproc-js makeBibliography() result tuple. */
+export interface BibliographyResult extends Array<unknown> {
+    0: {
+        entry_ids: string[]
+        bibstart: string
+        bibend: string
+        entryspacing: number
+        linespacing: number
+        hangingindent?: boolean
+        maxoffset: number
+        "second-field-align"?: "margin" | "flush"
+    }
+    1: string[]
+}
+
+/** Common constructor options for exporters. */
+export interface ExporterOptions {
+    doc: ExportDoc
+    templateUrl?: string
+    bibDB?: BibDB
+    imageDB?: ImageDB
+    csl?: CSL
+}
+
+/** JSON representation of a DOM node used by the native exporter. */
+export interface NativeDomNode {
+    t?: string
+    co?: string
+    nn?: string
+    a?: Array<[string, string]>
+    c?: NativeDomNode[]
+}
+
+/** A document template extracted from document content. */
+export interface Template {
+    content: FidusNode
+    exportTemplates: Array<Record<string, JSONValue>>
+    documentStyles: Array<Record<string, JSONValue>>
+    files?: Array<{filename: string; content: Blob | ArrayBuffer | string}>
+}
+
+/** Files bundled with a document template. */
+export interface TemplateFiles {
+    textFiles: Array<{filename: string; contents: string}>
+    httpFiles: Array<{url: string; filename: string}>
+}
+
+/** Backend callbacks used by the generic NativeImporter. */
+export interface NativeImporterBackend {
+    createDoc: (
+        template: Template,
+        importId: string | number | null,
+        requestedPath: string,
+        e2eeOptions: E2EEOptions | null,
+        files: Record<string, File[]>
+    ) => Promise<{id: number; path: string; e2ee?: boolean}>
+    saveImages: (
+        images: ImageDB,
+        docId: number,
+        e2eeOptions: E2EEOptions | null
+    ) => Promise<Record<number | string, number>>
+    saveDocument: (
+        saveData: Record<string, unknown>,
+        e2eeOptions: E2EEOptions | null
+    ) => Promise<{added: number; updated: number}>
+    extractTemplate?: (doc: FidusNode) => Template
+    decryptBufferToBase64?: (base64: string, key: CryptoKey) => Promise<string>
+    encryptImage?: (file: Blob, key: CryptoKey) => Promise<Blob>
+    encryptObject?: (obj: unknown, key: CryptoKey) => Promise<unknown>
+    encrypt?: (text: string, key: CryptoKey) => Promise<unknown>
+    storeKeyInSession?: (docId: number, key: CryptoKey) => void
+}
+
+/** E2EE options used during import/export/copy. */
+export interface E2EEOptions {
+    enabled?: boolean
+    key?: CryptoKey
+    sourceKey?: CryptoKey
+    targetE2EE?: boolean
+    targetPassword?: string
+    salt?: string
+    iterations?: number
+}
+
+/** Callback that uploads a native revision blob. */
+export type UploadRevision = (blob: Blob, doc: Record<string, unknown>) => unknown
+
+/** E2EE helper object used by SaveCopy. */
+export interface SaveCopyE2EE {
+    decryptObject: (encrypted: unknown, key: CryptoKey) => Promise<unknown>
+    encryptObject: (obj: unknown, key: CryptoKey) => Promise<unknown>
+    encrypt: (text: string, key: CryptoKey) => Promise<unknown>
+    encryptImage: (file: Blob, key: CryptoKey) => Promise<Blob>
+    generateSalt: () => Uint8Array
+    deriveKey: (password: string, salt: Uint8Array, iterations: number) => Promise<CryptoKey>
+}
+
+/** Callback used by SaveCopy to import a copied document. */
+export type ImportDocument = (
+    doc: Record<string, unknown>,
+    bibDB: BibDB,
+    imageDB: ImageDB,
+    httpIncludes: Array<{url: string; filename: string}>,
+    options: Record<string, unknown>
+) => Promise<{doc: Record<string, unknown>; docInfo: Record<string, unknown>}>

package/jest.config.js

@@ -1,24 +0,0 @@
-export default {
-    rootDir: ".",
-    testEnvironment: "node",
-    transform: {},
-    moduleDirectories: ["node_modules"],
-    moduleNameMapper: {
-        "^downloadjs$": "<rootDir>/test/exporter/mocks/downloadjs.js",
-        "^mathlive$": "<rootDir>/test/exporter/mocks/mathlive.js",
-        "^mathml2omml$": "<rootDir>/test/exporter/mocks/mathml2omml.js",
-        "^@vivliostyle/print$": "<rootDir>/test/exporter/mocks/vivliostyle.js",
-        "^pretty$": "<rootDir>/test/exporter/mocks/pretty.js",
-        "^biblatex-csl-converter$": "<rootDir>/test/exporter/mocks/biblatex-csl-converter.js",
-        "^jszip$": "<rootDir>/test/importer/mocks/jszip.js",
-        "^mathml-to-latex$": "<rootDir>/test/importer/mocks/mathml-to-latex.js",
-        "^fwtoolkit$": "<rootDir>/test/exporter/mocks/common.js",
-        "^fwtoolkit/.*": "<rootDir>/test/exporter/mocks/common.js",
-        "^@fiduswriter/document/citations/format$": "<rootDir>/test/exporter/mocks/citations-format.js",
-        "^@fiduswriter/document/bibliography/csl_bib$": "<rootDir>/test/exporter/mocks/csl-bib-schema.js",
-        "^@fiduswriter/document/mathlive/opf_includes$": "<rootDir>/test/exporter/mocks/empty-module.js"
-    },
-    testMatch: ["<rootDir>/test/**/*.test.js"],
-    setupFiles: ["<rootDir>/test/setup.js"],
-    moduleFileExtensions: ["js", "mjs", "json"]
-}

package/src/exporter/docx/images.js

@@ -1,101 +0,0 @@
-import {get} from "fwtoolkit"
-import {descendantNodes} from "../tools/doc_content.js"
-import {svg2png} from "../tools/svg.js"
-
-export class DOCXExporterImages {
-    constructor(docContent, imageDB, xml, rels) {
-        this.docContent = docContent
-        this.imageDB = imageDB
-        this.xml = xml
-        this.rels = rels
-
-        this.images = {}
-        this.ctXML = false
-    }
-
-    init() {
-        return this.xml.getXml("[Content_Types].xml").then(ctXML => {
-            this.ctXML = ctXML
-            return this.exportImages()
-        })
-    }
-
-    // add an image to the list of files
-    addImage(imgFileName, image) {
-        const rId = this.rels.addImageRel(imgFileName)
-        this.addContentType(imgFileName.split(".").pop())
-        this.xml.addExtraFile(`word/media/${imgFileName}`, image)
-        return rId
-    }
-
-    // add a global contenttype declaration for an image type (if needed)
-    addContentType(fileEnding) {
-        const types = this.ctXML.query("Types")
-        const contentDec = types.query("Default", {Extension: fileEnding})
-        if (!contentDec) {
-            const string = `<Default ContentType="image/${fileEnding}" Extension="${fileEnding}"/>`
-            types.appendXML(string)
-        }
-    }
-
-    // Find all images used in file and add these to the export zip.
-    // TODO: This will likely fail on image types docx doesn't support such as SVG.
-    // Try out and fix.
-    exportImages() {
-        const usedImgs = []
-        descendantNodes(this.docContent).forEach(node => {
-            if (node.type === "image" && node.attrs.image !== false) {
-                if (!usedImgs.includes(node.attrs.image)) {
-                    usedImgs.push(node.attrs.image)
-                }
-            }
-        })
-        return new Promise(resolveExportImages => {
-            const p = []
-            usedImgs.forEach(image => {
-                const imgDBEntry = this.imageDB.db[image]
-                p.push(
-                    get(imgDBEntry.image)
-                        .then(response => response.blob())
-                        .then(blob => {
-                            if (blob.type === "image/svg+xml") {
-                                // DOCX doesn't support SVG. Convert to PNG.
-                                return svg2png(blob).then(
-                                    ({blob: pngBlob, width, height}) => {
-                                        const wImgId = this.addImage(
-                                            imgDBEntry.image
-                                                .split("/")
-                                                .pop()
-                                                .replace(/.svg$/g, ".png"),
-                                            pngBlob
-                                        )
-                                        this.images[image] = {
-                                            id: wImgId,
-                                            width,
-                                            height,
-                                            title: imgDBEntry.title
-                                        }
-                                    }
-                                )
-                            } else {
-                                const wImgId = this.addImage(
-                                    imgDBEntry.image.split("/").pop(),
-                                    blob
-                                )
-                                this.images[image] = {
-                                    id: wImgId,
-                                    width: imgDBEntry.width,
-                                    height: imgDBEntry.height,
-                                    title: imgDBEntry.title
-                                }
-                            }
-                        })
-                )
-            })
-
-            Promise.all(p).then(() => {
-                resolveExportImages()
-            })
-        })
-    }
-}

package/src/exporter/jats/bibliography.js

@@ -1,183 +0,0 @@
-import {escapeText} from "fwtoolkit"
-import {convertTexts} from "./text.js"
-
-// This list is based on values listed at https://jats.nlm.nih.gov/archiving/tag-library/1.2/attribute/publication-type.html
-// And the advice given here: https://jats4r.org/citations/#recommendation
-const PUBLICATION_TYPES = {
-    article: "journal",
-    "article-journal": "journal",
-    "article-magazine": "journal",
-    "article-newspaper": "journal",
-    book: "book",
-    bookinbook: "book",
-    booklet: "book",
-    chapter: "book",
-    collection: "standard",
-    dataset: "dataset",
-    "entry-dictionary": "standard",
-    "entry-encyclopedia": "standard",
-    inbook: "book",
-    incollection: "book",
-    inproceedings: "standard",
-    inreference: "standard",
-    manual: "book",
-    misc: "standard",
-    mvbook: "book",
-    mvcollection: "standard",
-    mvproceedings: "book",
-    mvreference: "standard",
-    online: "standard",
-    patent: "patent",
-    periodical: "book",
-    post: "standards",
-    "post-weblog": "standard",
-    proceedings: "book",
-    reference: "standard",
-    report: "report",
-    review: "review",
-    suppbook: "book",
-    suppcollection: "book",
-    suppperiodical: "journal",
-    thesis: "standard",
-    unpublished: "standard"
-}
-
-export function jatsBib(bib, id) {
-    let start = "",
-        end = ""
-    start += `<ref id="ref-${id}">`
-    end = "</ref>" + end
-    // Type
-    const publicationType = PUBLICATION_TYPES[bib.bib_type] ?? "standard"
-    start += `<element-citation publication-type="${publicationType}">`
-    end = "</element-citation>" + end
-
-    // authors
-    if (bib.fields.author && bib.fields.author.length) {
-        start += `<person-group person-group-type="author">${bib.fields.author
-            .map(author => {
-                if (author.literal) {
-                    return `<collab>${convertTexts(author.literal)}</collab>`
-                }
-                let nameStart = `<name><surname>${convertTexts(author.family)}</surname> <given-names>${convertTexts(author.given)}</given-names>`
-                if (author.prefix && author.prefix.length) {
-                    nameStart += ` <prefix>${convertTexts(author.prefix)}</prefix>`
-                }
-                if (author.suffix && author.suffix.length) {
-                    nameStart += ` <suffix>${convertTexts(author.suffix)}</suffix>`
-                }
-                const nameEnd = "</name>"
-                return nameStart + nameEnd
-            })
-            .join(", ")}</person-group>`
-    }
-
-    // title && container title
-    if (bib.fields.title) {
-        if (
-            bib.fields.shortjournal ||
-            bib.fields.booktitle ||
-            bib.fields.journaltitle
-        ) {
-            start += `<source>${convertTexts(bib.fields.shortjournal || bib.fields.booktitle || bib.fields.journaltitle)}</source>`
-            start += `<article-title>${convertTexts(bib.fields.title)}</article-title>`
-        } else {
-            start += `<source>${convertTexts(bib.fields.title)}</source>`
-        }
-    }
-
-    // editors
-    if (bib.fields.editor && bib.fields.editor.length) {
-        start += `<person-group person-group-type="editor">${bib.fields.editor
-            .map(editor => {
-                if (editor.literal) {
-                    return `<collab>${convertTexts(editor.literal)}</collab>`
-                }
-                let nameStart = `<name><surname>${convertTexts(editor.family)}</surname> <given-names>${convertTexts(editor.given)}</given-names>`
-                const nameEnd = "</name>"
-                if (editor.prefix && editor.prefix.length) {
-                    nameStart = `<prefix>${convertTexts(editor.prefix)}</prefix>`
-                }
-                if (editor.suffix && editor.suffix.length) {
-                    nameStart = `<suffix>${convertTexts(editor.suffix)}</suffix>`
-                }
-                return nameStart + nameEnd
-            })
-            .join(", ")}</person-group>`
-    }
-
-    // publisher
-    if (bib.fields.publisher && bib.fields.publisher.length) {
-        start += bib.fields.publisher
-            .map(
-                publisher =>
-                    `<publisher-name>${convertTexts(publisher)}</publisher-name>`
-            )
-            .join("")
-    }
-
-    // location
-    if (bib.fields.location && bib.fields.location.length) {
-        start += bib.fields.location
-            .map(
-                location =>
-                    `<publisher-loc>${convertTexts(location)}</publisher-loc>`
-            )
-            .join("")
-    }
-
-    // date
-    if (bib.fields.date && bib.fields.date.length) {
-        const date = bib.fields.date
-        const dateParts = date.split("-")
-        start += `<date iso-8601-date="${date}" date-type="published">${
-            dateParts.length > 2 ? `<day>${dateParts[2]}</day>` : ""
-        }${
-            dateParts.length > 1 ? `<month>${dateParts[1]}</month>` : ""
-        }<year>${dateParts[0]}</year></date>`
-    }
-
-    // volume
-    if (bib.fields.volume && bib.fields.volume.length) {
-        start += `<volume>${convertTexts(bib.fields.volume)}</volume>`
-    }
-
-    // issue
-    if (bib.fields.issue && bib.fields.issue.length) {
-        start += `<issue>${convertTexts(bib.fields.issue)}</issue>`
-    }
-
-    // pages
-    if (bib.fields.pages && bib.fields.pages.length) {
-        start += `<fpage>${convertTexts(bib.fields.pages[0][0])}</fpage>`
-        start += `<lpage>${convertTexts(bib.fields.pages.slice(-1)[0].slice(-1)[0])}</lpage>`
-        if (bib.fields.pages.length > 1) {
-            start += `<page-range>${bib.fields.pages
-                .map(pages => pages.map(page => convertTexts(page)).join("-"))
-                .join(", ")}</page-range>`
-        }
-    }
-
-    // doi
-    if (bib.fields.doi && bib.fields.doi.length) {
-        start += `<pub-id pub-id-type="doi">${escapeText(bib.fields.doi)}</pub-id>`
-    }
-
-    // url
-    if (bib.fields.url && bib.fields.url.length) {
-        start += `<ext-link ext-link-type="web" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${escapeText(bib.fields.url)}"/>`
-    }
-
-    // url date
-    if (bib.fields.urldate && bib.fields.urldate.length) {
-        const date = bib.fields.urldate
-        const dateParts = date.split("-")
-        start += `<date-in-citation content-type="access-date" iso-8601-date="${date}">${
-            dateParts.length > 2 ? `<day>${dateParts[2]}</day>` : ""
-        }${
-            dateParts.length > 1 ? `<month>${dateParts[1]}</month>` : ""
-        }<year>${dateParts[0]}</year></date-in-citation>`
-    }
-
-    return start + end
-}