@fiduswriter/books-document 0.1.28 → 0.1.29

package/src/ui/book_dialog/export.ts

@@ -0,0 +1,398 @@
+/**
+ * Book export initiation.
+ *
+ * Wraps every book exporter of this package in the chapter-data preloading
+ * and progress reporting the dialog's export menu needs, and delivers the
+ * resulting Blob through the host-supplied
+ * {@link BookExportContext.deliver}.
+ *
+ * The exporters themselves are environment-agnostic: they load chapter data
+ * through injected strategies (defaulting to no-ops) and simply return the
+ * produced Blob. Preloading here with the host's `chapterLoader`/`e2ee` makes
+ * the exporters' own internal `getMissingChapterData` call a no-op.
+ */
+
+import type {ProgressCallback} from "@fiduswriter/document/exporter/tools/progress"
+import {BITSBookExporter} from "../../exporter/bits/index.js"
+import {DOCXBookExporter} from "../../exporter/docx/index.js"
+import {EpubBookExporter} from "../../exporter/epub/index.js"
+import {HTMLBookExporter} from "../../exporter/html/index.js"
+import {LatexBookExporter} from "../../exporter/latex/index.js"
+import {NativeBookExporter} from "../../exporter/native/index.js"
+import {ODTBookExporter} from "../../exporter/odt/index.js"
+import {PrintBookExporter} from "../../exporter/print/index.js"
+import {getMissingChapterData} from "../../exporter/tools.js"
+import type {Book, DocumentListEntry} from "../../types.js"
+import {addAlert, addProgress, gettext} from "fwtoolkit"
+import type {ContentMenuInit} from "fwtoolkit/content_menu"
+import type {BookExportContext} from "./types.js"
+
+/**
+ * The subset of a book exporter this module needs. Every exporter of
+ * `@fiduswriter/books-document` exposes these members; the declared return
+ * type of `init()` differs slightly between them (some return `false`, some
+ * `void`, instead of a Blob), so it is kept loose here. `mimeType` likewise
+ * only exists on the DOCX/ODT exporters, which read it off the instance.
+ */
+export interface BookExporterLike {
+    book: Book
+    defaultFilename: string
+    // Declared inconsistently across the exporters: some resolve to `false`
+    // or nothing, and BITS/DOCX/ODT can return `false` synchronously.
+    init(
+        progressCallback?: ProgressCallback
+    ): Promise<Blob | false | void> | false
+}
+
+/**
+ * Arguments passed to the callbacks of the single-book export menu. The
+ * dialog assembles them once and hands them to every entry.
+ */
+export interface BookExportMenuArgs {
+    saveBook: () => Promise<unknown>
+    book: Book
+    documentList: DocumentListEntry[]
+    context: BookExportContext
+}
+
+/** Model of the book dialog's export menu (a content menu of actions). */
+export type BookExportMenu = ContentMenuInit
+
+/**
+ * Load any missing chapter data (fetching content lazily and decrypting E2EE
+ * chapters), run the given exporter, then hand the resulting Blob to the
+ * host's `deliver`.
+ *
+ * @param exporter - A constructed book exporter instance.
+ * @param documentList - Document entries for the book's chapters.
+ * @param context - The host's schema, chapter loader, E2EE strategy and
+ *   delivery callback.
+ * @param mimeType - MIME type of the produced file.
+ * @param rawContent - Whether the exporter needs doc.rawContent.
+ */
+export const runBookExport = (
+    exporter: BookExporterLike,
+    documentList: DocumentListEntry[],
+    context: BookExportContext,
+    mimeType: string,
+    rawContent = false
+): Promise<unknown> => {
+    const {schema, chapterLoader, e2ee, deliver} = context
+    const formatName =
+        exporter.defaultFilename.split(".").pop()?.toUpperCase() ||
+        gettext("Book")
+    const task = addProgress(
+        "info",
+        `${exporter.book.title}: ${gettext("Exporting")} ${formatName}...`,
+        {autoClose: 6000}
+    )
+    const progressCallback: ProgressCallback = (message, percentage) =>
+        task.update(percentage ?? null, message)
+
+    return getMissingChapterData(exporter.book, documentList, schema, {
+        rawContent,
+        loader: chapterLoader,
+        e2ee,
+        progressCallback
+    })
+        .then(() => exporter.init(progressCallback))
+        .then(blob => {
+            task.update(100, gettext("Export complete."))
+            if (blob) {
+                const extension = `.${exporter.defaultFilename.split(".").pop()}`
+                deliver(blob, exporter.defaultFilename, {
+                    description: exporter.book.title,
+                    mimeType,
+                    extensions: [extension]
+                })
+            }
+            return blob
+        })
+        .catch((error: Error) => {
+            task.close()
+            addAlert("error", error.message || gettext("Book export failed."))
+        })
+}
+
+/** Export a book as an Epub file. */
+export const exportEpub = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) =>
+    runBookExport(
+        new EpubBookExporter(
+            context.schema,
+            context.csl,
+            context.bookStyles,
+            book,
+            context.user,
+            documentList,
+            book.updated ?? 0
+        ),
+        documentList,
+        context,
+        "application/epub+zip"
+    )
+
+/** Export a book as a BITS (Book Interchange Tag Set) file. */
+export const exportBITS = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) =>
+    runBookExport(
+        new BITSBookExporter(
+            context.schema,
+            context.csl,
+            book,
+            context.user,
+            documentList,
+            book.updated ?? 0
+        ),
+        documentList,
+        context,
+        "application/zip"
+    )
+
+/** Export a book as a multi-file HTML archive. */
+export const exportHTML = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext,
+    multiDoc = true
+) =>
+    runBookExport(
+        new HTMLBookExporter(
+            context.schema,
+            context.csl,
+            context.bookStyles,
+            book,
+            context.user,
+            documentList,
+            book.updated ?? 0,
+            multiDoc
+        ),
+        documentList,
+        context,
+        "application/zip"
+    )
+
+/** Export a book as a single-file HTML archive. */
+export const exportSingleHTML = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) => exportHTML(book, documentList, context, false)
+
+/** Export a book as LaTeX. */
+export const exportLatex = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) =>
+    runBookExport(
+        new LatexBookExporter(
+            context.schema,
+            book,
+            context.user,
+            documentList,
+            book.updated ?? 0
+        ),
+        documentList,
+        context,
+        "application/zip"
+    )
+
+/** Export a book as DOCX, using the book's DOCX template. */
+export const exportDOCX = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) => {
+    const exporter = new DOCXBookExporter(
+        context.schema,
+        context.csl,
+        book,
+        context.user,
+        documentList,
+        book.updated ?? 0
+    )
+    return runBookExport(
+        exporter,
+        documentList,
+        context,
+        exporter.mimeType,
+        true
+    )
+}
+
+/** Export a book as ODT, using the book's ODT template. */
+export const exportODT = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) => {
+    const exporter = new ODTBookExporter(
+        context.schema,
+        context.csl,
+        book,
+        context.user,
+        documentList,
+        book.updated ?? 0
+    )
+    return runBookExport(
+        exporter,
+        documentList,
+        context,
+        exporter.mimeType,
+        true
+    )
+}
+
+/** Open a book's print/PDF view. */
+export const exportPrint = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) =>
+    runBookExport(
+        new PrintBookExporter(
+            context.schema,
+            context.csl,
+            context.bookStyles,
+            book,
+            context.user,
+            documentList
+        ),
+        documentList,
+        context,
+        "text/html"
+    )
+
+/** Export a book as a native `.fidusbook` file. */
+export const exportFidusbook = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    context: BookExportContext
+) =>
+    runBookExport(
+        new NativeBookExporter(
+            context.schema,
+            book,
+            context.user,
+            documentList,
+            book.updated ?? 0
+        ),
+        documentList,
+        context,
+        "application/vnd.fiduswriter.book+zip"
+    )
+
+/**
+ * Model of the book dialog's export menu.
+ *
+ * Every entry saves the book first, so an export always reflects what is on
+ * screen. The DOCX and ODT entries are disabled while the book has no
+ * matching template.
+ */
+export const bookExportMenuModel = (): BookExportMenu => ({
+    content: [
+        {
+            type: "action",
+            title: gettext("Export as BITS"),
+            tooltip: gettext("Export book as Book Interchange Tag Set."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportBITS(book, documentList, context))
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as Epub"),
+            tooltip: gettext("Export book as Epub."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportEpub(book, documentList, context))
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as HTML"),
+            tooltip: gettext("Export book as HTML."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() =>
+                    exportHTML(book, documentList, context, true)
+                )
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as Unified HTML"),
+            tooltip: gettext("Export book as Single-file HTML."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportSingleHTML(book, documentList, context))
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as LaTeX"),
+            tooltip: gettext("Export book as LaTeX."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportLatex(book, documentList, context))
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as DOCX"),
+            tooltip: gettext("Export book as DOCX."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportDOCX(book, documentList, context))
+            },
+            disabled: (page: unknown) => !(page as BookExportMenuArgs).book.docx_template
+        },
+        {
+            type: "action",
+            title: gettext("Export as ODT"),
+            tooltip: gettext("Export book as ODT."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportODT(book, documentList, context))
+            },
+            disabled: (page: unknown) => !(page as BookExportMenuArgs).book.odt_template
+        },
+        {
+            type: "action",
+            title: gettext("Export to Print/PDF"),
+            tooltip: gettext("Export book to the print dialog."),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportPrint(book, documentList, context))
+            }
+        },
+        {
+            type: "action",
+            title: gettext("Export as Fidusbook"),
+            tooltip: gettext(
+                "Export book as a .fidusbook file (for moving to another server)."
+            ),
+            action: (page: unknown) => {
+                const {saveBook, book, documentList, context} =
+                    page as BookExportMenuArgs
+                saveBook().then(() => exportFidusbook(book, documentList, context))
+            }
+        }
+    ]
+})

package/src/ui/book_dialog/index.ts

@@ -0,0 +1,81 @@
+/**
+ * The book edit dialog.
+ *
+ * A reusable, backend-agnostic tabbed dialog for editing a book's metadata,
+ * settings, cover image and chapter list, running a sanity check and starting
+ * an export. Import it from the `@fiduswriter/books-document/ui/book_dialog`
+ * subpath so that the main entry stays free of DOM code and remains usable
+ * from Node (as `@fiduswriter/cli` needs).
+ *
+ * ```js
+ * import {BookDialog} from "@fiduswriter/books-document/ui/book_dialog"
+ *
+ * new BookDialog({
+ *     book, // omit to create a new book
+ *     documentList,
+ *     schema,
+ *     chapterLoader, // @fiduswriter/books-document
+ *     e2ee, // @fiduswriter/books-document
+ *     backend: {
+ *         saveBook: book => postJson("/api/book/save/", {book}),
+ *         selectCoverImage: id => showImagePicker(id),
+ *         saveDocxTemplate: (book, file) => uploadTemplate(book, file)
+ *     },
+ *     exportContext: {schema, chapterLoader, e2ee, csl, bookStyles, user, deliver: saveFile}
+ * }).open()
+ * ```
+ *
+ * `ChapterLoader` and `E2EEStrategy` are the same interfaces the book
+ * exporters already accept, so a host that can export a book needs no extra
+ * wiring to run a sanity check.
+ */
+
+export {BookDialog} from "./dialog.js"
+export {
+    bookSanityCheck
+} from "./sanity_check.js"
+export {
+    bookBasicInfoTemplate,
+    bookBibliographyDataTemplate,
+    bookChapterDialogTemplate,
+    bookChapterListTemplate,
+    bookDialogChaptersTemplate,
+    bookDialogTemplate,
+    bookDOCXDataRowTemplate,
+    bookDOCXDataTemplate,
+    bookEpubDataCoverTemplate,
+    bookEpubDataTemplate,
+    bookODTDataRowTemplate,
+    bookODTDataTemplate,
+    bookPrintDataTemplate,
+    bookSanityCheckTemplate
+} from "./templates.js"
+export {
+    bookExportMenuModel,
+    exportBITS,
+    exportDOCX,
+    exportEpub,
+    exportFidusbook,
+    exportHTML,
+    exportLatex,
+    exportODT,
+    exportPrint,
+    exportSingleHTML,
+    runBookExport
+} from "./export.js"
+export type {
+    BookExportMenu,
+    BookExportMenuArgs,
+    BookExporterLike
+} from "./export.js"
+export type {
+    BookDataContext,
+    BookDialogBackend,
+    BookDialogCoverImage,
+    BookDialogImageDB,
+    BookDialogInfo,
+    BookDialogOptions,
+    BookDialogPart,
+    BookExportContext,
+    BookExportDeliverer
+} from "./types.js"

package/src/ui/book_dialog/sanity_check.ts

@@ -0,0 +1,208 @@
+/**
+ * Book sanity check.
+ *
+ * Loads whatever chapter data is missing, decrypts encrypted chapters through
+ * the injected {@link BookDataContext} and reports unresolved tracked changes,
+ * comments, cross references and internal links.
+ *
+ * Only the context touches the host; the analysis itself is entirely
+ * host-agnostic and shared by every consumer of this package.
+ */
+
+import {getMissingChapterData} from "../../exporter/tools.js"
+import type {Book, Chapter, DocumentListEntry} from "../../types.js"
+import {gettext, longFilePath} from "fwtoolkit"
+import type {BookDataContext} from "./types.js"
+
+/** A node of a chapter's raw ProseMirror content. */
+interface RawNode {
+    type?: string
+    attrs?: Record<string, never> & {
+        track?: unknown[]
+        href?: string
+        title?: string
+        id?: string
+        approved?: boolean
+    }
+    marks?: RawMark[]
+    content?: RawNode[]
+}
+
+/** A mark of a raw ProseMirror node. */
+interface RawMark {
+    type?: string
+    attrs?: {
+        href?: string
+        title?: string
+        id?: string
+        approved?: boolean
+    }
+}
+
+/** The chapters' collected issues, split by severity. */
+interface SanityMessages {
+    warnings: string[]
+    errors: string[]
+}
+
+/*
+ * Chapters whose document the user cannot see have no `doc` to take a title
+ * and path from, so fall back to the same placeholder `longFilePath` uses for
+ * an untitled document.
+ */
+const labelChapter = (chapter: Chapter, doc?: DocumentListEntry): string =>
+    `(${gettext("Chapter")} ${chapter.number}, ${longFilePath(
+        doc?.title ?? gettext("Untitled"),
+        doc?.path ?? "/"
+    )})`
+
+function findContentIssues(
+    node: RawNode,
+    chapter: Chapter,
+    doc: DocumentListEntry,
+    messages: SanityMessages
+): void {
+    if (node.attrs?.track?.length) {
+        messages.warnings.push(
+            `${gettext("Unresolved tracked changes")} ${labelChapter(chapter, doc)}`
+        )
+    }
+    if (node.marks) {
+        node.marks.forEach(mark => {
+            if (
+                mark.type == "link" &&
+                mark.attrs?.href?.charAt(0) === "#" &&
+                !mark.attrs?.title
+            ) {
+                messages.warnings.push(
+                    `${gettext("Internal links without target")} ${labelChapter(
+                        chapter,
+                        doc
+                    )}`
+                )
+            } else if (
+                mark.type == "comment" &&
+                (doc.comments as Array<{resolved?: boolean}> | undefined)?.[
+                    Number.parseInt(mark.attrs?.id as string)
+                ]?.resolved === false
+            ) {
+                messages.warnings.push(
+                    `${gettext("Unresolved comments")} ${labelChapter(chapter, doc)}`
+                )
+            } else if (
+                mark.type === "deletion" ||
+                (mark.type === "insertion" && mark.attrs?.approved === false)
+            ) {
+                messages.warnings.push(
+                    `${gettext("Unresolved tracked changes")} ${labelChapter(
+                        chapter,
+                        doc
+                    )}`
+                )
+            }
+        })
+    }
+    if (node.type === "cross_reference" && !node.attrs?.title) {
+        messages.warnings.push(
+            `${gettext("Cross references without targets")} ${labelChapter(
+                chapter,
+                doc
+            )}`
+        )
+    }
+
+    if (node.content) {
+        node.content.forEach(subNode =>
+            findContentIssues(subNode, chapter, doc, messages)
+        )
+    }
+}
+
+/**
+ * Run a sanity check on a book.
+ *
+ * @param book - The book to check.
+ * @param documentList - Document entries for the book's chapters.
+ * @param context - The host's schema, chapter loader and E2EE strategy.
+ * @returns A promise resolving to the report as an HTML fragment.
+ */
+export const bookSanityCheck = (
+    book: Book,
+    documentList: DocumentListEntry[],
+    {schema, chapterLoader, e2ee}: BookDataContext
+): Promise<string> => {
+    if (!book.chapters.length) {
+        return Promise.resolve(
+            `<ul class="fw-errorlist"><li>${gettext(
+                "The book contains no chapters."
+            )}</li></ul>`
+        )
+    }
+    return getMissingChapterData(book, documentList, schema, {
+        rawContent: true,
+        loader: chapterLoader,
+        e2ee
+    })
+        .then(() => {
+            const messages: SanityMessages = {
+                warnings: [],
+                errors: []
+            }
+            book.chapters.forEach(chapter => {
+                const doc = documentList.find(doc => doc.id === chapter.text)
+                if (!doc || !doc.rawContent) {
+                    messages.errors.push(
+                        `${gettext("No access")} ${labelChapter(chapter, doc)}`
+                    )
+                    return
+                }
+                if (!doc.title || !doc.title.length) {
+                    messages.warnings.push(
+                        `${gettext("No chapter title")} ${labelChapter(chapter, doc)}`
+                    )
+                }
+                findContentIssues(
+                    doc.rawContent as unknown as RawNode,
+                    chapter,
+                    doc,
+                    messages
+                )
+            })
+
+            const warnings = Array.from(new Set(messages.warnings))
+            const errors = Array.from(new Set(messages.errors))
+            if (!warnings.length && !errors.length) {
+                return `<p>${gettext("No issues were found:")}</p>
+                    <p>${gettext("The book contains chapters.")}</p>
+                    <p>${gettext("Each chapter has a title.")}</p>
+                    <p>${gettext("There are no unresolved tracked changes.")}</p>
+                    <p>${gettext("There are no unresolved comments.")}</p>
+                    <p>${gettext("All cross references have working targets.")}</p>
+                    <p>${gettext(
+                        "All internal links have working targets."
+                    )}</p>`
+            }
+            return `<ul class="warninglist">
+                    ${warnings.map(warning => `<li>${warning}</li>`).join("")}
+                </ul>
+                <ul class="fw-errorlist">
+                    ${errors.map(error => `<li>${error}</li>`).join("")}
+                </ul>`
+        })
+        .catch((err: Error) => {
+            // Passphrase unavailable or user cancelled the unlock dialog.
+            if (
+                err.message &&
+                err.message.toLowerCase().includes("passphrase is required")
+            ) {
+                return `<ul class="fw-errorlist"><li>${gettext(
+                    "This book contains encrypted chapters. A personal passphrase is required to perform a sanity check. Please set up or unlock your personal passphrase in your profile settings."
+                )}</li></ul>`
+            }
+            // Individual chapter decryption failure — alerts were already
+            // shown by decryptE2EEChapters; show a summary here.
+            return `<ul class="fw-errorlist"><li>${gettext(
+                "One or more encrypted chapters could not be decrypted. See the error notifications for details."
+            )}</li></ul>`
+        })
+}