@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/text/Texts.mjs

@@ -0,0 +1,187 @@
+// CR-012 phase 2: the text model's facade, docx4j's org.docx4j.model.text.Texts.
+import { Part } from '../../parts/Part.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { TextOptions, TextOptionError } from './TextOptions.mjs';
+import { Extractor } from './Extractor.mjs';
+import { PlainText } from './PlainText.mjs';
+import { PackageTrees, TextContext } from './TextContext.mjs';
+import { normalize } from './normalize.mjs';
+const WML_CONTENT_TYPES = {
+    main: ['application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml', 'application/vnd.ms-word.document.macroEnabled.main+xml',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml', 'application/vnd.ms-word.template.macroEnabledTemplate.main+xml'],
+    header: 'application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml',
+    footer: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml',
+    footnotes: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml',
+    endnotes: 'application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml',
+    comments: 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml',
+};
+function optionsOf(options) {
+    const o = TextOptions.of(options);
+    o.checkImplemented();
+    return o;
+}
+/** A content object: a typed value (`TYPE_NAME`) or an element pair. */
+function isContent(value) {
+    var _a;
+    if (typeof value !== 'object' || value === null || value instanceof TextOptions)
+        return false;
+    if (typeof value.TYPE_NAME === 'string')
+        return true;
+    return 'name' in value && 'value' in value && typeof ((_a = value.value) === null || _a === void 0 ? void 0 : _a.TYPE_NAME) === 'string';
+}
+function isPackage(value) {
+    return typeof value === 'object' && value !== null && typeof value.getMainDocumentPart === 'function'
+        && typeof value.getPropertyResolver === 'function';
+}
+/**
+ * docx4j's text model (its CR-046; the portfolio's *WordprocessingML Text Extraction*, WD): a text is
+ * `serialize(scope(view(resolve(package))))` (WD REQ-201). `Texts.of` makes the block model
+ * (`TextResult`); `PlainText.of` writes plain text from it.
+ *
+ * ```ts
+ * const result = await Texts.of(pkg, { view: 'markup', include: ['headers', 'footers'], hidden: true });
+ * PlainText.of(result);
+ * result.warnings;
+ * ```
+ *
+ * - **resolve**: each `mc:AlternateContent` is read from the branch the content API reads
+ *   (`selectedBranchOf`, CR-010), so that the text model and `Paragraph.text` take the same branch.
+ * - **view**: `accepted` (the default), `original` or `markup`; the first two are the text of the document
+ *   `acceptAllRevisions` or `rejectAllRevisions` leaves, worked out without resolving anything
+ *   (`ResolvedView`), held equal to that copy route by the agreement test (REQ-406).
+ * - **scope**: the main story, each text box once after its anchoring paragraph (after the table for one in
+ *   a cell), then the footnotes and endnotes in reference order; headers, footers and comments where
+ *   included, and the glossary, last, under `include: glossary`; hidden text excluded; placeholders
+ *   included; a bound control's value from its custom XML part; images' descriptions by an
+ *   `ImageDescriber`; the document properties in the metadata.
+ *
+ * **Not yet** (CR-012 section 5): `fields: update` and `embedded: true` are refused (REQ-1001); an equation
+ * is its text inside `$...$`, not LaTeX (phase 5b); a chart or SmartArt contributes nothing (5c); an
+ * `altChunk` is not expanded and raises `altchunk.not_expanded` (5e).
+ *
+ * **The package is never changed** (REQ-204): every part is read with `readContents()`, the live tree where
+ * the part is unmarshalled and a private one where it is not, so a save afterwards is byte for byte where it
+ * was before.
+ *
+ * **Cost.** Each call reads every story and, in the `accepted` and `original` views, their tracked changes
+ * once, whether it reads the whole package or one paragraph of it. A `TextContext` (`contextOf`) holds what
+ * was read, so calls under one context read it once.
+ *
+ * **Not Office JS's text.** `Paragraph.text` and the other Office JS readers keep Office JS's text (CR-012
+ * D2, REQ-202's emulated-API exemption); each `TextRun` records where its text lies in its paragraph's
+ * `Paragraph.text` (`officeOffset`), so that the two map onto each other.
+ */
+export class Texts {
+    constructor() { }
+    static async of(first, second, third, fourth) {
+        if (first instanceof Part)
+            return Texts.ofPart(first, second, third);
+        if (isPackage(first)) {
+            if (isContent(second))
+                return Texts.ofContent(first, second, third, fourth);
+            const o = optionsOf(second);
+            const context = await Texts.context(first, third, o);
+            return new Extractor(context.trees, o, 'view', context).extract();
+        }
+        if (isContent(first)) {
+            const o = optionsOf(second);
+            return new Extractor(PackageTrees.none(), o, 'planless', new TextContext(PackageTrees.none())).extractContent(first, 'MAIN', 'content', undefined);
+        }
+        throw new Docx4JException('Texts.of takes a WordprocessingMLPackage, a story part of one, or content');
+    }
+    static async ofContent(pkg, content, options, given) {
+        const o = optionsOf(options);
+        const context = await Texts.context(pkg, given, o);
+        const v = 'name' in content && 'value' in content ? content.value : content;
+        return new Extractor(context.trees, o, 'view', context).extractContent(content, 'MAIN', 'content', context.trees.partOf(v));
+    }
+    static async ofPart(part, options, given) {
+        const o = optionsOf(options);
+        const pkg = part.package;
+        if (!isPackage(pkg))
+            throw new Docx4JException(`${part.partName.name} belongs to no WordprocessingML package; read content with Texts.of(content)`);
+        const context = await Texts.context(pkg, given, o);
+        const trees = context.trees;
+        const main = trees.main;
+        const ct = part.contentType;
+        if (main && part === main.part) {
+            return new Extractor(trees, o, 'view', context).extractContent(main.document, 'MAIN', 'body', part);
+        }
+        if (ct === WML_CONTENT_TYPES.header || ct === WML_CONTENT_TYPES.footer) {
+            const rId = main ? relationshipIdOf(main.part, part) : undefined;
+            return new Extractor(trees, o, 'view', context).headerOrFooterPart(part, ct === WML_CONTENT_TYPES.header ? 'HEADER' : 'FOOTER', rId !== null && rId !== void 0 ? rId : part.partName.name);
+        }
+        if (ct === WML_CONTENT_TYPES.footnotes || ct === WML_CONTENT_TYPES.endnotes) {
+            if (!context.mainRead && main) {
+                // the notes are numbered in their references' order: read the main story for it, its blocks unused
+                const first = context.sibling();
+                new Extractor(trees, o, 'view', first).extractContent(main.document, 'MAIN', 'body', main.part);
+                context.adoptNotes(first);
+                context.mainRead = true;
+            }
+            return new Extractor(trees, o, 'view', context).extractNotes(ct === WML_CONTENT_TYPES.footnotes ? 'footnote' : 'endnote');
+        }
+        if (ct === WML_CONTENT_TYPES.comments)
+            return new Extractor(trees, o, 'view', context).extractComments();
+        throw new Docx4JException(`Not a story part: ${part.partName.name}; use Texts.of(package)`);
+    }
+    /**
+     * The text of a package that `acceptAllRevisions` or `rejectAllRevisions` has already resolved, read with
+     * no view logic: the copy route of WD REQ-406, which the views of `Texts.of` are held equal to. The
+     * options' view says which resolution it was (`accepted` or `original`).
+     */
+    static async ofResolved(resolved, options) {
+        const o = optionsOf(options);
+        if (o.view === 'markup')
+            throw new TextOptionError('A resolved package has no markup view', 'view', 'REQ-406', 'invalid');
+        const context = await Texts.context(resolved, undefined, o);
+        return new Extractor(context.trees, o, 'resolved', context).extract();
+    }
+    /** Plain text of a package (WD section 7.1): `PlainText.of(await Texts.of(pkg, options))`. */
+    static async plainText(pkg, options) {
+        return PlainText.of(await Texts.of(pkg, options));
+    }
+    /**
+     * A context for calls over one package (CR-012 section 4.4): it reads the package's stories once, makes
+     * each view's plan once, and carries the note numbers, numbering states and bookmarks from one call to the
+     * next. A snapshot: after the package changes, make another.
+     */
+    static async contextOf(pkg) {
+        return new TextContext(await PackageTrees.read(pkg));
+    }
+    /** WD REQ-1201's normalisation, under which texts are compared. */
+    static normalize(value) {
+        return normalize(value);
+    }
+    static async context(pkg, given, o) {
+        return contextFor(pkg, given, o);
+    }
+}
+/**
+ * The context a call reads under: the one given, checked against the package and the view, or a new one
+ * (internal: `Texts` and the outline reader share it).
+ */
+export async function contextFor(pkg, given, o) {
+    if (given !== undefined && given.pkg !== pkg)
+        throw new Docx4JException('This TextContext was made for another package');
+    const context = given !== null && given !== void 0 ? given : await Texts.contextOf(pkg);
+    if (context.view !== undefined && context.view !== o.view) {
+        throw new TextOptionError(`This TextContext read in the ${context.view} view, and its note numbers and list counts are that view's: make another for ${o.view}`, 'view', 'REQ-401', 'invalid');
+    }
+    context.view = o.view;
+    if (o.includes.has('glossary'))
+        await context.trees.readGlossary();
+    return context;
+}
+/** Options checked as `Texts.of` checks them (internal). */
+export { optionsOf, isPackage };
+/** The id of the main document part's relationship to a part. */
+function relationshipIdOf(main, part) {
+    var _a;
+    const rels = main.getRelationshipsPart(false);
+    for (const rel of (_a = rels === null || rels === void 0 ? void 0 : rels.relationships.relationship) !== null && _a !== void 0 ? _a : []) {
+        if ((rels === null || rels === void 0 ? void 0 : rels.getPart(rel)) === part)
+            return rel.id;
+    }
+    return undefined;
+}

package/dist/model/text/WmlToMarkdown.d.mts

@@ -0,0 +1,120 @@
+import type { PropertyResolver } from '../properties/PropertyResolver.mjs';
+import type { TextResult, TextRun } from './TextResult.mjs';
+import { MdDocument, MdImage } from './commonmark.mjs';
+/** An image node waiting for its destination, which needs its part's bytes (`MarkdownExporter`). */
+export interface PendingImage {
+    readonly node: MdImage;
+    readonly run: TextRun;
+}
+/**
+ * Writes the text model's block model (`TextResult`) as a Markdown tree (WD REQ-703): a heading from its
+ * outline level, not its style's name; a list from its numbering; bold, italic, struck-through and code text
+ * from what a run adds to its paragraph's style (so a heading's inherent bold doesn't become `**markers**`);
+ * links from a `w:hyperlink` or a HYPERLINK field; images with the describer's text; notes as `[^n]`; in the
+ * `markup` view, CriticMarkup (`{++ ++}`, `{-- --}`, `{>> <<}`). A table of contents is the text model's to
+ * leave out (`toc: false`, the default). Each node made for a block carries it as its `tag`, so that
+ * `MarkdownExporter.blocks` can say where each block's Markdown begins. docx4j `WmlToMarkdown`.
+ */
+export declare class WmlToMarkdown {
+    private readonly result;
+    /** For a style's own indent (a block quote's depth); undefined where there are no styles to ask. */
+    private readonly resolver;
+    /** The schemes a link may use beyond `LinkTargets`' defaults (`MarkdownExportOptions.linkSchemes`). */
+    private readonly linkSchemes;
+    private readonly textOptions;
+    /** The open lists, the deepest last. */
+    private readonly openLists;
+    /** The count each list level last showed (`numId/ilvl`), for a parent item reopened after an interruption. */
+    private readonly lastValues;
+    private openQuote;
+    private openQuoteDepth;
+    /** Above 0 while building a GFM header row, whose bold is convention, not markup. */
+    private tableHeaderDepth;
+    private readonly styleIndents;
+    /** The images, in the order written, for their destinations. */
+    readonly images: PendingImage[];
+    /** Whether a link target was refused (`LinkTargets`): logged once per document. */
+    private linkRefused;
+    constructor(result: TextResult, 
+    /** For a style's own indent (a block quote's depth); undefined where there are no styles to ask. */
+    resolver: PropertyResolver | undefined, 
+    /** The schemes a link may use beyond `LinkTargets`' defaults (`MarkdownExportOptions.linkSchemes`). */
+    linkSchemes?: readonly string[]);
+    convert(): MdDocument;
+    private body;
+    /** Returns the index of the last block consumed (a code block spans several). */
+    private block;
+    private paragraph;
+    private inlineParagraph;
+    /** A code paragraph's text, unescaped; in `markup`, its revisions marked. */
+    private codeText;
+    /** A paragraph style's own left indent, in twips: 0 where it has none, or there are no styles to ask. */
+    private styleIndentLeft;
+    private appendToQuote;
+    private closeQuote;
+    /**
+     * The open list whose last item an unlabelled paragraph continues: the deepest whose item's text the
+     * paragraph is indented to (its left indent at least the item's, and not at the margin), or the deepest
+     * open list for a ListParagraph-styled paragraph; the lists deeper than it are closed. Undefined where
+     * none: the paragraph ends the lists.
+     */
+    private followOnItem;
+    private top;
+    private listParagraph;
+    private closeLists;
+    /**
+     * GFM pipes: the header row is the table's `w:tblHeader` rows, else its first (several `w:tblHeader` rows
+     * are one header, their cells' texts ` / ` apart, as plain text's listed format joins them); block content
+     * in cells flattens to inline with `<br>`, a nested table's paragraphs included; `w:vMerge` and
+     * `w:gridSpan` degrade (top-left wins, empty cells elsewhere), GFM having no spans.
+     *
+     * The table style's formatting is left out on purpose (docx4j CR-030 decision 4): a header row the style
+     * makes bold is not written `**bold**` (its being the GFM header says as much), and GFM has no table
+     * styling for the rest.
+     */
+    private table;
+    /** The header: one row's cells, or several rows' cells by grid column, ` / ` apart. */
+    private headerRow;
+    private tableCell;
+    /**
+     * A cell's paragraphs, a nested table's included, `<br>` apart (GFM cells are single-line); its empty
+     * paragraphs left out, as plain text leaves them out (Word ends every cell with a paragraph, so a nested
+     * table or a block-level control comes with an empty one after it).
+     *
+     * A cell's alignment is its first paragraph's effective `w:jc`, empty or not; GFM aligns a column, from
+     * its header cell's (the delimiter row), so a body cell's is not seen.
+     */
+    private cellContent;
+    /**
+     * A chart: its note (docx4j CR-047: `[chart: clustered column; value axis: Revenue]`), its title and its
+     * data as a table, after the paragraph it is in, the categories down and the series across (CR-012 phase
+     * 5c fills them in; until then the text model makes no chart block).
+     */
+    private chart;
+    private inlines;
+    /** A block's runs, in `markup` each revision's between its CriticMarkup marks (REQ-703, REQ-702). */
+    private runs;
+    /** Runs, those with the same link target in one link. */
+    private linked;
+    private run;
+    private text;
+    private comment;
+    /** Runs under one marker: the same type, and the same author and date where the detail shows them. */
+    private sameMarker;
+    /** The marker as one string, for a code block, where nothing is markup. */
+    private open;
+    /** The marker in a paragraph: its braces raw, its author and date text (docx4j's `open(revision, sink)`). */
+    private openMarker;
+    /**
+     * The marker's author and date as text, which the renderer escapes as it does any document text (docx4j CR-056,
+     * `30fb41024`; CR-012 section 21.1): only the braces are raw. Before, the detail went out raw with them, so an
+     * author of `<script>...</script>` reached a renderer that allows raw HTML as markup.
+     */
+    private detailText;
+    private detail;
+    /**
+     * A picture with the describer's text (REQ-703, REQ-514); its destination, which needs its image part's
+     * bytes, is the exporter's to fill in (`images`), empty for a picture whose image can't be had.
+     */
+    private image;
+}