@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/esm/modules/word/convert/markdown/markdown-import.js

@@ -21,46 +21,60 @@ import { isRun } from "../../core/text-utils.js";
 /**
  * Convert a Markdown string into a complete DocxDocument.
  *
+ * Supports the full GFM feature set including inline images (embedded via the
+ * `resolveImage` callback) and footnotes (`[^id]` references with `[^id]: …`
+ * definitions). Because image resolution and document packaging are inherently
+ * asynchronous, this function is async.
+ *
  * @param markdown - The GFM Markdown string.
  * @param options - Optional conversion settings.
- * @returns A DocxDocument ready to be packaged.
+ * @returns A Promise resolving to a DocxDocument ready to be packaged.
  */
-export function markdownToDocx(markdown, options) {
-    const { body, state } = markdownToDocxBodyInternal(markdown, options);
+export async function markdownToDocx(markdown, options) {
+    const { body, state } = await markdownToDocxBodyInternal(markdown, options);
     return {
         body,
         styles: defaultMarkdownStyles(),
         abstractNumberings: state.abstractNumberings,
-        numberingInstances: state.numberingInstances
+        numberingInstances: state.numberingInstances,
+        ...(state.footnotes.length > 0 ? { footnotes: state.footnotes } : {}),
+        ...(state.images.length > 0 ? { images: state.images } : {})
     };
 }
 /**
- * Convert a Markdown string into an array of DOCX body content blocks.
+ * Convert a Markdown string into DOCX body content plus the supporting
+ * document-level definitions it references.
  *
- * **Caveat — body content is not self-contained.**
- *   - **Lists** (bullet / numbered / task) reference numbering ids that
- *     live in document-level `abstractNumberings` + `numberingInstances`,
- *     which this helper does NOT return.
- *   - **Block quotes** reference the named `Quote` style.
- *   - **Code blocks** reference the named code styles.
+ * **Caveat — body content is not self-contained.** The returned `body` may
+ * reference:
+ *   - **Numbering** (`abstractNumberings` / `numberingInstances`) — used by
+ *     bullet / numbered / task lists.
+ *   - **Footnotes** (`footnotes`) — referenced by footnote-reference runs.
+ *   - **Images** (`images`) — referenced by inline image runs.
+ *   - The named `Quote` / `CodeBlock` styles (for block quotes / code blocks).
  *
- * Splicing markdown that uses any of these constructs into a document that
- * lacks the matching numbering / styles yields invalid OOXML. Either keep
- * the input flat (paragraphs + headings + inline formatting) before
- * splicing, or use the higher-level {@link markdownToDocx} which returns a
- * complete `DocxDocument` with the supporting definitions populated.
+ * Splice the relevant arrays into your host document alongside the body, or
+ * use the higher-level {@link markdownToDocx} which returns a complete
+ * `DocxDocument` with everything populated.
  *
  * @param markdown - The GFM Markdown string.
  * @param options - Optional conversion settings.
- * @returns Array of BodyContent blocks (no numbering / styles attached).
+ * @returns A Promise resolving to the body and its supporting definitions.
  */
-export function markdownToDocxBody(markdown, options) {
-    return markdownToDocxBodyInternal(markdown, options).body;
+export async function markdownToDocxBody(markdown, options) {
+    const { body, state } = await markdownToDocxBodyInternal(markdown, options);
+    return {
+        body,
+        abstractNumberings: state.abstractNumberings,
+        numberingInstances: state.numberingInstances,
+        footnotes: state.footnotes,
+        images: state.images
+    };
 }
 /**
  * Internal implementation: converts markdown and returns both body and state.
  */
-function markdownToDocxBodyInternal(markdown, options) {
+async function markdownToDocxBodyInternal(markdown, options) {
     const state = createState();
     const opts = {
         codeFont: "Courier New",
@@ -68,8 +82,14 @@ function markdownToDocxBodyInternal(markdown, options) {
         ...options
     };
     const lines = markdown.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
-    const blocks = parseMarkdownBlocks(lines, 0, lines.length);
-    const body = convertBlocks(blocks, opts, state);
+    // First pass: extract footnote definitions (`[^id]: …`) so references can
+    // resolve regardless of definition order, then parse the remaining blocks.
+    const { lines: contentLines, definitions } = extractFootnoteDefinitions(lines);
+    state.footnoteDefinitions = definitions;
+    const blocks = parseMarkdownBlocks(contentLines, 0, contentLines.length);
+    const body = await convertBlocks(blocks, opts, state);
+    // Emit footnote definitions that were actually referenced, in reference order.
+    await finalizeFootnotes(state, opts);
     return { body, state };
 }
 function createState() {
@@ -78,10 +98,106 @@ function createState() {
         numberingInstances: [],
         nextNumId: 1,
         bulletNumId: undefined,
-        orderedNumId: undefined
+        orderedNumId: undefined,
+        footnotes: [],
+        images: [],
+        footnoteDefinitions: new Map(),
+        footnoteIds: new Map(),
+        footnoteOrder: [],
+        nextFootnoteId: 1,
+        nextImageId: 1,
+        nextDrawingId: 1
     };
 }
 // =============================================================================
+// Footnote definition extraction (first pass)
+// =============================================================================
+/**
+ * Matches a footnote definition line: `[^label]: content`.
+ * Continuation lines (indented under a definition) are folded in.
+ */
+const FOOTNOTE_DEF_RE = /^\[\^([^\]]+)\]:\s?(.*)$/;
+/**
+ * Strip footnote definitions (`[^id]: …`) out of the line stream before block
+ * parsing, returning the remaining content lines plus a label→text map. A
+ * definition may span continuation lines that are indented by at least one
+ * space; those are joined with a single space.
+ */
+function extractFootnoteDefinitions(lines) {
+    const definitions = new Map();
+    const contentLines = [];
+    let i = 0;
+    while (i < lines.length) {
+        // Preserve fenced code blocks verbatim — a `[^id]:`-looking line inside a
+        // code fence is code, not a footnote definition.
+        const fenceMatch = lines[i].match(/^(`{3,}|~{3,})/);
+        if (fenceMatch) {
+            const fence = fenceMatch[1];
+            const closeRe = new RegExp(`^${fence[0]}{${fence.length},}$`);
+            contentLines.push(lines[i]);
+            i++;
+            while (i < lines.length) {
+                contentLines.push(lines[i]);
+                const isClose = closeRe.test(lines[i].trim());
+                i++;
+                if (isClose) {
+                    break;
+                }
+            }
+            continue;
+        }
+        const match = lines[i].match(FOOTNOTE_DEF_RE);
+        if (match) {
+            const label = match[1];
+            const parts = [match[2]];
+            i++;
+            // Fold indented continuation lines into the definition.
+            while (i < lines.length && /^\s+\S/.test(lines[i])) {
+                parts.push(lines[i].trim());
+                i++;
+            }
+            definitions.set(label, parts.join(" ").trim());
+            continue;
+        }
+        contentLines.push(lines[i]);
+        i++;
+    }
+    return { lines: contentLines, definitions };
+}
+/**
+ * After conversion, emit a `FootnoteDef` for every footnote that was actually
+ * referenced, in reference order. References to undefined labels still get a
+ * footnote (with empty content) so the reference mark remains valid OOXML.
+ */
+function finalizeFootnotes(state, opts) {
+    return (async () => {
+        for (const label of state.footnoteOrder) {
+            const id = state.footnoteIds.get(label);
+            if (id === undefined) {
+                continue;
+            }
+            const text = state.footnoteDefinitions.get(label) ?? "";
+            const inlines = parseInlines(text);
+            const para = await convertParagraph(inlines, opts, state, { style: "FootnoteText" });
+            state.footnotes.push({ id, content: [para] });
+        }
+    })();
+}
+/**
+ * Resolve (or assign) the numeric footnote id for a markdown label, recording
+ * reference order on first use.
+ */
+function resolveFootnoteId(label, state) {
+    const existing = state.footnoteIds.get(label);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const id = state.nextFootnoteId++;
+    state.footnoteIds.set(label, id);
+    state.footnoteOrder.push(label);
+    return id;
+}
+// =============================================================================
 // Block Parser
 // =============================================================================
 function parseMarkdownBlocks(lines, start, end) {
@@ -432,6 +548,15 @@ function parseInlines(text) {
                 continue;
             }
         }
+        // Footnote reference [^label]
+        if (text[i] === "[" && text[i + 1] === "^") {
+            const result = parseFootnoteRef(text, i);
+            if (result) {
+                nodes.push(result.node);
+                i = result.end;
+                continue;
+            }
+        }
         // Link [text](url "title")
         if (text[i] === "[") {
             const result = parseLink(text, i);
@@ -537,6 +662,17 @@ function parseInlineCode(text, start) {
     }
     return { node: { type: "code", text: code }, end: afterClose };
 }
+function parseFootnoteRef(text, start) {
+    // [^label] — label may not contain ']' or whitespace.
+    const match = text.slice(start).match(/^\[\^([^\]\s]+)\]/);
+    if (!match) {
+        return null;
+    }
+    return {
+        node: { type: "footnoteRef", label: match[1] },
+        end: start + match[0].length
+    };
+}
 function parseImage(text, start) {
     // ![alt](url "title")
     const altStart = start + 2; // skip "!["
@@ -759,20 +895,20 @@ function parseStrikethrough(text, start) {
         end: closeIdx + 2
     };
 }
-function convertBlocks(blocks, opts, state) {
+async function convertBlocks(blocks, opts, state) {
     const result = [];
     for (const block of blocks) {
-        const converted = convertBlock(block, opts, 0, state);
+        const converted = await convertBlock(block, opts, 0, state);
         result.push(...converted);
     }
     return result;
 }
-function convertBlock(block, opts, listLevel, state) {
+async function convertBlock(block, opts, listLevel, state) {
     switch (block.type) {
         case "heading":
-            return [convertHeading(block)];
+            return [await convertHeading(block, opts, state)];
         case "paragraph":
-            return [convertParagraph(block.inlines, opts)];
+            return [await convertParagraph(block.inlines, opts, state)];
         case "blockquote":
             return convertBlockquote(block, opts, state);
         case "fencedCode":
@@ -782,7 +918,7 @@ function convertBlock(block, opts, listLevel, state) {
         case "list":
             return convertList(block, opts, listLevel, state);
         case "table":
-            return [convertTable(block, opts)];
+            return [await convertTable(block, opts, state)];
         case "html":
             // Pass through as plain text paragraph
             return [
@@ -792,8 +928,8 @@ function convertBlock(block, opts, listLevel, state) {
             return [];
     }
 }
-function convertHeading(block) {
-    const children = inlinesToRuns(block.inlines, {});
+async function convertHeading(block, opts, state) {
+    const children = await inlinesToRuns(block.inlines, opts, state, true);
     return {
         type: "paragraph",
         properties: {
@@ -803,19 +939,19 @@ function convertHeading(block) {
         children
     };
 }
-function convertParagraph(inlines, opts, props) {
-    const children = inlinesToRuns(inlines, opts);
+async function convertParagraph(inlines, opts, state, props) {
+    const children = await inlinesToRuns(inlines, opts, state, false);
     return {
         type: "paragraph",
         properties: props,
         children
     };
 }
-function convertBlockquote(block, opts, state) {
+async function convertBlockquote(block, opts, state) {
     // Convert blockquote children with "Quote" style and left indent
     const result = [];
     for (const child of block.children) {
-        const converted = convertBlock(child, opts, 0, state);
+        const converted = await convertBlock(child, opts, 0, state);
         for (const item of converted) {
             if (item.type === "paragraph") {
                 result.push({
@@ -875,7 +1011,7 @@ function convertThematicBreak() {
         children: []
     };
 }
-function convertList(block, opts, parentLevel, state) {
+async function convertList(block, opts, parentLevel, state) {
     // Ordered lists with a non-default `start` need their own numbering
     // instance so the override actually takes effect — sharing one numId
     // across all lists would force every list to start at the same number.
@@ -888,7 +1024,7 @@ function convertList(block, opts, parentLevel, state) {
         for (const child of item.children) {
             if (child.type === "list") {
                 // Nested list — increase level
-                const nested = convertList(child, opts, parentLevel + 1, state);
+                const nested = await convertList(child, opts, parentLevel + 1, state);
                 result.push(...nested);
             }
             else if (child.type === "paragraph") {
@@ -897,7 +1033,7 @@ function convertList(block, opts, parentLevel, state) {
                     const props = {
                         numbering: { numId, level: parentLevel }
                     };
-                    const para = convertParagraph(child.inlines, opts, props);
+                    const para = await convertParagraph(child.inlines, opts, state, props);
                     // Handle task list checkbox prefix
                     if (item.checked !== undefined) {
                         const checkbox = item.checked ? "☑ " : "☐ ";
@@ -918,11 +1054,11 @@ function convertList(block, opts, parentLevel, state) {
                     const props = {
                         indent: { left: 720 * (parentLevel + 1) }
                     };
-                    result.push(convertParagraph(child.inlines, opts, props));
+                    result.push(await convertParagraph(child.inlines, opts, state, props));
                 }
             }
             else {
-                const converted = convertBlock(child, opts, parentLevel, state);
+                const converted = await convertBlock(child, opts, parentLevel, state);
                 result.push(...converted);
                 firstBlock = false;
             }
@@ -930,10 +1066,12 @@ function convertList(block, opts, parentLevel, state) {
     }
     return result;
 }
-function convertTable(block, opts) {
+async function convertTable(block, opts, state) {
     const colCount = block.headers.length;
     // Header row
-    const headerCells = block.headers.map((cell, ci) => {
+    const headerCells = [];
+    for (let ci = 0; ci < block.headers.length; ci++) {
+        const cell = block.headers[ci];
         const cellProps = {
             shading: { fill: "F0F0F0" },
             verticalAlign: "center"
@@ -941,7 +1079,7 @@ function convertTable(block, opts) {
         const paraProps = {
             alignment: block.alignments[ci]
         };
-        const para = convertParagraph(cell, opts, paraProps);
+        const para = await convertParagraph(cell, opts, state, paraProps);
         // Bold header text
         const boldPara = {
             ...para,
@@ -952,21 +1090,22 @@ function convertTable(block, opts) {
                 return child;
             })
         };
-        return { properties: cellProps, content: [boldPara] };
-    });
+        headerCells.push({ properties: cellProps, content: [boldPara] });
+    }
     // Data rows
-    const dataRows = block.rows.map(rowCells => {
+    const dataRows = [];
+    for (const rowCells of block.rows) {
         const cells = [];
         for (let ci = 0; ci < colCount; ci++) {
             const cellInlines = ci < rowCells.length ? rowCells[ci] : [];
             const paraProps = {
                 alignment: block.alignments[ci]
             };
-            const para = convertParagraph(cellInlines, opts, paraProps);
+            const para = await convertParagraph(cellInlines, opts, state, paraProps);
             cells.push({ content: [para] });
         }
-        return { cells };
-    });
+        dataRows.push({ cells });
+    }
     const allRows = [
         { properties: { tableHeader: true }, cells: headerCells },
         ...dataRows
@@ -991,37 +1130,41 @@ function convertTable(block, opts) {
 // =============================================================================
 // Inline to Run Conversion
 // =============================================================================
-function inlinesToRuns(inlines, opts) {
+async function inlinesToRuns(inlines, opts, state, isHeading) {
     const result = [];
     for (const node of inlines) {
-        inlineToRuns(node, result, {}, opts);
+        await inlineToRuns(node, result, {}, opts, state, isHeading);
     }
     return result;
 }
-function inlineToRuns(node, output, inheritedProps, opts) {
+async function inlineToRuns(node, output, inheritedProps, opts, state, isHeading) {
     switch (node.type) {
         case "text": {
-            const textProps = {
-                ...inheritedProps,
-                ...(opts.defaultFont && !inheritedProps.font ? { font: opts.defaultFont } : {}),
-                ...(opts.defaultFontSize && !inheritedProps.size ? { size: opts.defaultFontSize } : {})
-            };
+            // Headings derive their font/size from the named Heading style; only
+            // body text picks up the document default font/size.
+            const textProps = isHeading
+                ? inheritedProps
+                : {
+                    ...inheritedProps,
+                    ...(opts.defaultFont && !inheritedProps.font ? { font: opts.defaultFont } : {}),
+                    ...(opts.defaultFontSize && !inheritedProps.size ? { size: opts.defaultFontSize } : {})
+                };
             output.push(makeRun(node.text, textProps));
             break;
         }
         case "bold":
             for (const child of node.children) {
-                inlineToRuns(child, output, { ...inheritedProps, bold: true }, opts);
+                await inlineToRuns(child, output, { ...inheritedProps, bold: true }, opts, state, isHeading);
             }
             break;
         case "italic":
             for (const child of node.children) {
-                inlineToRuns(child, output, { ...inheritedProps, italic: true }, opts);
+                await inlineToRuns(child, output, { ...inheritedProps, italic: true }, opts, state, isHeading);
             }
             break;
         case "strikethrough":
             for (const child of node.children) {
-                inlineToRuns(child, output, { ...inheritedProps, strike: true }, opts);
+                await inlineToRuns(child, output, { ...inheritedProps, strike: true }, opts, state, isHeading);
             }
             break;
         case "code":
@@ -1036,7 +1179,7 @@ function inlineToRuns(node, output, inheritedProps, opts) {
             const linkChildren = [];
             for (const child of node.children) {
                 const tempOutput = [];
-                inlineToRuns(child, tempOutput, { ...inheritedProps, color: "0563C1", underline: "single" }, opts);
+                await inlineToRuns(child, tempOutput, { ...inheritedProps, color: "0563C1", underline: "single" }, opts, state, isHeading);
                 for (const run of tempOutput) {
                     if ("content" in run) {
                         linkChildren.push(run);
@@ -1053,20 +1196,71 @@ function inlineToRuns(node, output, inheritedProps, opts) {
             output.push(link);
             break;
         }
-        case "image":
-            // Images require async resolution — for sync API we insert a placeholder
-            // The resolveImage callback in options would be used in an async variant
-            output.push(makeRun(`[Image: ${node.alt || node.url}]`, {
-                ...inheritedProps,
-                italic: true,
-                color: "666666"
-            }));
+        case "image": {
+            const run = await resolveImageRun(node, inheritedProps, opts, state);
+            output.push(run);
             break;
+        }
+        case "footnoteRef": {
+            const id = resolveFootnoteId(node.label, state);
+            output.push({
+                properties: { ...inheritedProps, style: "FootnoteReference" },
+                content: [{ type: "footnoteRef", id }]
+            });
+            break;
+        }
         case "lineBreak":
             output.push(makeRun("", undefined, [{ type: "break" }]));
             break;
     }
 }
+/**
+ * Resolve an inline image. If `resolveImage` returns image data, embed it as a
+ * real `InlineImageContent` run and register the media in `state.images`;
+ * otherwise fall back to an italic `[Image: alt]` placeholder so the output
+ * remains valid.
+ */
+async function resolveImageRun(node, inheritedProps, opts, state) {
+    const data = opts.resolveImage ? await opts.resolveImage(node.url, node.alt) : undefined;
+    if (!data) {
+        return makeRun(`[Image: ${node.alt || node.url}]`, {
+            ...inheritedProps,
+            italic: true,
+            color: "666666"
+        });
+    }
+    const n = state.nextImageId++;
+    const fileName = `image${n}.${imageExtension(data.mediaType)}`;
+    const rId = `mdimg${n}`;
+    // For SVG, the packager auto-splits the PNG fallback into its own media
+    // part, assigns a second relationship, and back-fills `svgRId` on the inline
+    // image — so we only ever push a single ImageDef and a single rId here.
+    state.images.push({
+        data: data.data,
+        mediaType: data.mediaType,
+        fileName,
+        rId,
+        ...(data.fallbackData ? { fallbackData: data.fallbackData } : {})
+    });
+    const DEFAULT_DIM = 914400; // 1 inch fallback when no size given
+    return {
+        content: [
+            {
+                type: "image",
+                rId,
+                width: (data.width ?? DEFAULT_DIM),
+                height: (data.height ?? DEFAULT_DIM),
+                altText: node.alt || undefined,
+                name: node.alt || fileName,
+                drawingId: state.nextDrawingId++
+            }
+        ]
+    };
+}
+/** Map an image media type to its word/media/ file extension. */
+function imageExtension(mediaType) {
+    return mediaType === "jpeg" ? "jpg" : mediaType;
+}
 // =============================================================================
 // Numbering Helpers
 // =============================================================================
@@ -1320,6 +1514,22 @@ function defaultMarkdownStyles() {
             name: "Code Block",
             basedOn: "Normal",
             runProperties: { font: "Courier New", size: 20 }
+        },
+        {
+            // Character style applied to the in-text footnote reference mark so it
+            // renders as a superscript number, matching Word's built-in style.
+            type: "character",
+            styleId: "FootnoteReference",
+            name: "footnote reference",
+            runProperties: { vertAlign: "superscript" }
+        },
+        {
+            // Paragraph style for footnote body text (smaller font, like Word).
+            type: "paragraph",
+            styleId: "FootnoteText",
+            name: "footnote text",
+            basedOn: "Normal",
+            runProperties: { size: 20 }
         }
     ];
 }