@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/esm/modules/word/advanced/field-engine.js

@@ -42,7 +42,7 @@ export function updateFields(doc, options) {
     // Build style → paragraphs index for STYLEREF
     const styleIndex = buildStyleIndex(doc);
     // Collect INDEX entries (XE fields) from all body content
-    const indexEntries = collectIndexEntries(doc);
+    const indexEntries = collectIndexEntries(doc, layout);
     // Update body content
     const newBody = updateBody(doc, layout, bookmarkInfo, seqValues, styleIndex, indexEntries, opts);
     // If TOC was updated, register the TOC1..TOCn paragraph styles so the
@@ -610,23 +610,33 @@ function findStyleRef(styleIndex, styleName, bodyIndex) {
 // =============================================================================
 // Index Entry Collection (for INDEX field)
 // =============================================================================
-/** Collect all XE (Index Entry) fields from the document body. */
-function collectIndexEntries(doc) {
+/**
+ * Collect all XE (Index Entry) fields from the document body, tagging each
+ * with the page it falls on. Page numbers come from `layout.contentPages`
+ * keyed by the enclosing top-level body index (the same mechanism used for
+ * headings/TOC); entries inside nested structures inherit their outer block's
+ * page, falling back to 1 when layout produced no page for that block.
+ */
+function collectIndexEntries(doc, layout) {
     const entries = [];
-    walkBlocks(doc.body, {
-        visitRunContent(content) {
-            if (content.type !== "field") {
-                return;
-            }
-            const { type, args } = parseFieldInstruction(content.instruction);
-            if (type === "XE") {
-                const term = parseXeTerm(args);
-                if (term) {
-                    entries.push({ term, page: 1 });
+    const { contentPages } = layout;
+    for (let i = 0; i < doc.body.length; i++) {
+        const page = contentPages[i] ?? 1;
+        walkBlocks([doc.body[i]], {
+            visitRunContent(content) {
+                if (content.type !== "field") {
+                    return;
+                }
+                const { type, args } = parseFieldInstruction(content.instruction);
+                if (type === "XE") {
+                    const term = parseXeTerm(args);
+                    if (term) {
+                        entries.push({ term, page });
+                    }
                 }
             }
-        }
-    });
+        });
+    }
     return entries;
 }
 /** Parse the term from an XE field argument: XE "term" or XE term. */
@@ -643,17 +653,32 @@ function buildIndexContent(entries, args) {
     if (entries.length === 0) {
         return "";
     }
-    // Sort entries alphabetically by term
-    const sorted = [...entries].sort((a, b) => a.term.localeCompare(b.term));
+    // Merge entries that share the same term: a term marked on several pages
+    // produces a single index line listing each distinct page (Word behaviour),
+    // e.g. "widget, 1, 4" rather than two separate "widget" rows.
+    const byTerm = new Map();
+    for (const entry of entries) {
+        let pages = byTerm.get(entry.term);
+        if (!pages) {
+            pages = new Set();
+            byTerm.set(entry.term, pages);
+        }
+        pages.add(entry.page);
+    }
+    // Sort terms alphabetically; within each term sort pages numerically.
+    const merged = [...byTerm.entries()]
+        .map(([term, pages]) => ({ term, pages: [...pages].sort((a, b) => a - b) }))
+        .sort((a, b) => a.term.localeCompare(b.term));
+    const formatEntry = (e) => `${e.term}\t${e.pages.join(", ")}`;
     // Check for \h switch (group by first letter with headings)
     const grouped = /\\h\b/i.test(args);
     if (!grouped) {
-        return sorted.map(e => `${e.term}\t${e.page}`).join("\n");
+        return merged.map(formatEntry).join("\n");
     }
     // Group by first letter
     const lines = [];
     let currentLetter = "";
-    for (const entry of sorted) {
+    for (const entry of merged) {
         const letter = entry.term.charAt(0).toUpperCase();
         if (letter !== currentLetter) {
             currentLetter = letter;
@@ -662,7 +687,7 @@ function buildIndexContent(entries, args) {
             }
             lines.push(currentLetter);
         }
-        lines.push(`${entry.term}\t${entry.page}`);
+        lines.push(formatEntry(entry));
     }
     return lines.join("\n");
 }

package/dist/esm/modules/word/advanced/glossary.js

@@ -4,17 +4,16 @@
  * Provides types and utilities for working with Glossary Document parts,
  * which contain AutoText entries, Quick Parts, and other Building Blocks.
  *
- * INTEGRATION STATUS: This module provides data structures and query helpers
- * for building blocks. The actual reading/writing of glossary parts from/to
- * DOCX archives is handled via the opaqueParts round-trip mechanism —
- * glossary parts in existing files are preserved as opaque parts during
- * read/write. This module is useful for:
+ * INTEGRATION STATUS: This module provides the glossary data model and query
+ * helpers. To embed a glossary in a document, assign a {@link GlossaryDocument}
+ * to `doc.glossary`; the packager then serialises it to
+ * `word/glossary/document.xml`, registers the `glossaryDocument` relationship,
+ * and adds the `[Content_Types].xml` override (the canonical OOXML location
+ * Word reads Quick Parts / AutoText from). Glossary parts in existing files are
+ * round-tripped via the same channel. This module is useful for:
  * - Building glossary data structures programmatically
  * - Querying/filtering building block collections
- * - Preparing data for future direct glossary part writing
- *
- * To add glossary content to a document currently, include it as an
- * OpaquePart with path "word/glossary/document.xml".
+ * - Assembling a glossary to attach via `doc.glossary`
  */
 import { generateGuid } from "../core/internal-utils.js";
 // =============================================================================

package/dist/esm/modules/word/advanced/math-convert.js

@@ -79,20 +79,98 @@ function convertNodeToMathML(node) {
     }
 }
 function convertMathRunToMathML(node) {
-    const text = xmlEncode(node.text);
-    // Operators and special characters
-    if (isOperator(node.text)) {
-        return `<mo>${text}</mo>`;
+    const raw = node.text;
+    // A single OMML run can hold a mix of letters, digits, operators and
+    // whitespace (e.g. "a + b = "). MathML presentation markup expects each
+    // token to be wrapped in the element matching its semantic category:
+    // <mi> for identifiers, <mn> for numbers, <mo> for operators and <mtext>
+    // for runs of whitespace / other text. Tokenize the run and emit one
+    // element per token so a mixed run is no longer flattened into a single
+    // (incorrect) <mi>.
+    const normalVariant = node.properties?.italic === false;
+    const tokens = tokenizeMathRun(raw);
+    // Fast path / backwards-compatibility: a run that is a single token keeps
+    // producing exactly one element (e.g. "x" -> <mi>x</mi>, "42" -> <mn>42</mn>,
+    // "+" -> <mo>+</mo>), matching the historical output.
+    return tokens.map(tok => emitMathToken(tok, normalVariant)).join("");
+}
+function classifyMathChar(ch) {
+    if (/\s/.test(ch)) {
+        return "text";
+    }
+    if (isOperator(ch)) {
+        return "operator";
+    }
+    if (/[0-9.]/.test(ch)) {
+        return "number";
+    }
+    if (/[A-Za-z]/.test(ch)) {
+        return "identifier";
+    }
+    // Letters outside ASCII (Greek, CJK, etc.) and any other symbol fall back to
+    // identifier — this matches how OMML treats variable names.
+    return "identifier";
+}
+function tokenizeMathRun(text) {
+    const tokens = [];
+    // Use code points so astral / combined characters are not split mid-symbol.
+    const chars = Array.from(text);
+    for (const ch of chars) {
+        const kind = classifyMathChar(ch);
+        const last = tokens[tokens.length - 1];
+        // Operators are always emitted as their own token (each operator is a
+        // distinct <mo>). Numbers, identifiers and text coalesce with the
+        // previous token of the same kind so "42" stays a single <mn> and a run
+        // of spaces stays a single <mtext>.
+        if (last && last.kind === kind && kind !== "operator") {
+            last.value += ch;
+        }
+        else {
+            tokens.push({ kind, value: ch });
+        }
     }
-    // Numbers
-    if (/^\d+(\.\d+)?$/.test(node.text)) {
-        return `<mn>${text}</mn>`;
+    return mergeDecimalPoints(tokens);
+}
+/**
+ * A "." between two digit groups is a decimal point, not an operator. The
+ * char classifier sees "." as an operator (it is a valid math operator on its
+ * own, e.g. function composition), so stitch `<number> "." <number>` back into
+ * a single number token here.
+ */
+function mergeDecimalPoints(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        const prev = out[out.length - 1];
+        const next = tokens[i + 1];
+        if (tok.kind === "operator" &&
+            tok.value === "." &&
+            prev &&
+            prev.kind === "number" &&
+            next &&
+            next.kind === "number") {
+            prev.value += "." + next.value;
+            i++; // consume the following number token
+            continue;
+        }
+        out.push(tok);
     }
-    // Identifiers
-    if (node.properties?.italic === false) {
-        return `<mi mathvariant="normal">${text}</mi>`;
+    return out;
+}
+function emitMathToken(tok, normalVariant) {
+    const text = xmlEncode(tok.value);
+    switch (tok.kind) {
+        case "operator":
+            return `<mo>${text}</mo>`;
+        case "number":
+            // A lone "." is not a number; treat it as an operator/text fallback.
+            return /\d/.test(tok.value) ? `<mn>${text}</mn>` : `<mo>${text}</mo>`;
+        case "text":
+            return `<mtext>${text}</mtext>`;
+        case "identifier":
+        default:
+            return normalVariant ? `<mi mathvariant="normal">${text}</mi>` : `<mi>${text}</mi>`;
     }
-    return `<mi>${text}</mi>`;
 }
 function convertFractionToMathML(node) {
     const num = childrenToMathML(node.numerator);
@@ -254,7 +332,11 @@ function convertMMLElement(el) {
         }
         case "msqrt": {
             const content = convertMMLChildren(el.children);
-            return { type: "mathRadical", content };
+            // A bare square root has no degree. OOXML still emits an (empty)
+            // <m:deg/>, so we must set hideDegree → <m:degHide m:val="1"/>;
+            // otherwise Word treats the empty degree as visible and draws an empty
+            // degree box (a small square) at the radical's upper-left.
+            return { type: "mathRadical", content, hideDegree: true };
         }
         case "mroot": {
             const children = getElementChildren(el);

package/dist/esm/modules/word/advanced/ole-objects.js

@@ -13,6 +13,8 @@
  * This module focuses on preservation (round-trip) and metadata extraction,
  * not full OLE compound document manipulation.
  */
+import { xmlEncodeAttr } from "../../xml/encode.js";
+import { ContentType } from "../constants.js";
 import { getFileName } from "../core/opc-paths.js";
 // =============================================================================
 // OLE Object Extraction
@@ -28,14 +30,33 @@ import { getFileName } from "../core/opc-paths.js";
 export function extractOleObjects(doc) {
     const objects = [];
     const summary = {};
-    // Scan opaque parts for OLE embeddings
+    const pushObject = (obj) => {
+        objects.push(obj);
+        summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+    };
+    // Structured OLE objects wired on document.xml.rels (preferred form —
+    // these carry the real rId and, when available, the round-tripped progId).
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            pushObject({
+                rId: ole.rId,
+                progId: ole.progId ?? detectProgIdFromData(ole.data),
+                objectType: "embedded",
+                displayAs: "icon",
+                imageRId: ole.previewRId,
+                fileName: getFileName(ole.path),
+                data: ole.data
+            });
+        }
+    }
+    // Scan opaque parts for OLE embeddings (legacy / hand-built documents that
+    // did not go through the structured oleObjects channel).
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
                 const obj = parseOlePartMetadata(part);
                 if (obj) {
-                    objects.push(obj);
-                    summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+                    pushObject(obj);
                 }
             }
         }
@@ -45,11 +66,10 @@ export function extractOleObjects(doc) {
         if (element.type === "opaqueDrawing") {
             const oleFromDrawing = extractOleFromRawXml(element.rawXml);
             if (oleFromDrawing) {
-                // Check if we already have this object from opaque parts
-                const exists = objects.some(o => o.rId === oleFromDrawing.rId);
+                // Check if we already have this object (by rId)
+                const exists = objects.some(o => o.rId === oleFromDrawing.rId && o.rId !== "");
                 if (!exists) {
-                    objects.push(oleFromDrawing);
-                    summary[oleFromDrawing.progId] = (summary[oleFromDrawing.progId] ?? 0) + 1;
+                    pushObject(oleFromDrawing);
                 }
             }
         }
@@ -60,6 +80,9 @@ export function extractOleObjects(doc) {
  * Check if a document contains any OLE embedded objects.
  */
 export function hasOleObjects(doc) {
+    if (doc.oleObjects && doc.oleObjects.length > 0) {
+        return true;
+    }
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
@@ -74,6 +97,14 @@ export function hasOleObjects(doc) {
  * Returns undefined if not found.
  */
 export function getOleObjectData(doc, rId) {
+    // Structured OLE objects carry the exact rId used on document.xml.rels.
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            if (ole.rId === rId) {
+                return ole.data;
+            }
+        }
+    }
     if (!doc.opaqueParts) {
         return undefined;
     }
@@ -126,16 +157,14 @@ export function createOleEmbedding(data, progId, options) {
     const olePart = {
         path: `word/embeddings/${fileName}`,
         data,
-        contentType: "application/vnd.openxmlformats-officedocument.oleObject",
+        contentType: ContentType.OleObject,
         relationships: undefined
     };
     const oleRId = `rIdOle${oleSeq}`;
-    // progId is metadata for downstream consumers — not stored on
-    // OpaquePart but accepted in the signature so callers can pass it
-    // alongside without a separate channel. We don't need it here.
-    void progId;
+    // progId is carried back on the result so addOleObject() can persist it
+    // into the body `<o:OLEObject ProgID="…">` markup for round-trip.
     if (!options?.previewImage) {
-        return { olePart, oleRId };
+        return { olePart, oleRId, progId };
     }
     if (!options.previewContentType) {
         throw new Error("createOleEmbedding: options.previewImage requires options.previewContentType");
@@ -150,7 +179,78 @@ export function createOleEmbedding(data, progId, options) {
         relationships: undefined
     };
     const previewRId = `rIdOleImg${previewSeq}`;
-    return { olePart, oleRId, previewPart, previewRId };
+    return { olePart, oleRId, progId, previewPart, previewRId };
+}
+/**
+ * Wire an {@link OleEmbeddingResult} into a document so the OLE object is
+ * actually rendered and resolvable, returning a new {@link DocxDocument}.
+ *
+ * Unlike just stuffing the part into `opaqueParts` (which leaves the binary
+ * dangling — no relationship, no body reference), this:
+ *
+ *  - registers the OLE binary (and optional preview) on
+ *    `doc.oleObjects` so the packager emits a `word/_rels/document.xml.rels`
+ *    relationship with the exact rId and a `[Content_Types].xml` override;
+ *  - appends a body paragraph carrying a `<w:object>` / `<o:OLEObject>`
+ *    that references the same rId and embeds the ProgId, so the object is
+ *    visible in Word and round-trips through `readDocx`.
+ *
+ * @param doc - The document to add the OLE object to.
+ * @param embedding - Result from {@link createOleEmbedding}.
+ * @param options - Display geometry (defaults to a 2"×2" icon box).
+ */
+export function addOleObject(doc, embedding, options) {
+    const widthPt = options?.widthPt ?? 96;
+    const heightPt = options?.heightPt ?? 96;
+    const drawAspect = (options?.displayAs ?? "icon") === "icon" ? "Icon" : "Content";
+    const olePartEntry = {
+        path: embedding.olePart.path,
+        data: embedding.olePart.data,
+        rId: embedding.oleRId,
+        progId: embedding.progId,
+        contentType: embedding.olePart.contentType,
+        ...(embedding.previewPart && embedding.previewRId
+            ? {
+                previewPath: embedding.previewPart.path,
+                previewData: embedding.previewPart.data,
+                previewRId: embedding.previewRId,
+                previewContentType: embedding.previewPart.contentType
+            }
+            : {})
+    };
+    // Build the VML-hosted <w:object>. The o:OLEObject carries ProgID + the
+    // r:id of the binary; the v:shape provides geometry and (when present) the
+    // preview image fill via v:imagedata. This is the canonical OOXML shape for
+    // an embedded OLE object (ECMA-376 §17.3.3.19 + VML).
+    const shapeId = `_ole_${embedding.oleRId}`;
+    const styleWidth = widthPt.toFixed(0);
+    const styleHeight = heightPt.toFixed(0);
+    const imageData = embedding.previewRId != null
+        ? `<v:imagedata r:id="${xmlEncodeAttr(embedding.previewRId)}" o:title=""/>`
+        : "";
+    const rawXml = `<w:object>` +
+        `<v:shape id="${xmlEncodeAttr(shapeId)}" type="#_x0000_t75" ` +
+        `style="width:${styleWidth}pt;height:${styleHeight}pt">` +
+        imageData +
+        `</v:shape>` +
+        `<o:OLEObject Type="Embed" ProgID="${xmlEncodeAttr(embedding.progId)}" ` +
+        `ShapeID="${xmlEncodeAttr(shapeId)}" DrawAspect="${drawAspect}" ` +
+        `r:id="${xmlEncodeAttr(embedding.oleRId)}"/>` +
+        `</w:object>`;
+    const referencedRIds = [embedding.oleRId];
+    if (embedding.previewRId != null) {
+        referencedRIds.push(embedding.previewRId);
+    }
+    const drawing = {
+        type: "opaqueDrawing",
+        rawXml,
+        referencedRIds
+    };
+    return {
+        ...doc,
+        body: [...doc.body, drawing],
+        oleObjects: [...(doc.oleObjects ?? []), olePartEntry]
+    };
 }
 /** Module-level counters used to allocate unique file names per call. */
 let _oleSeq = 0;
@@ -242,17 +342,20 @@ function tryDecodeAscii(data) {
     return str;
 }
 function extractOleFromRawXml(rawXml) {
-    // Parse OLE object info from raw XML using regex (lightweight)
-    const progIdMatch = rawXml.match(/ProgID="([^"]+)"/i) ?? rawXml.match(/progId="([^"]+)"/i);
-    const rIdMatch = rawXml.match(/r:id="([^"]+)"/i);
-    const typeMatch = rawXml.match(/Type="([^"]+)"/i);
+    // Pull metadata from the <o:OLEObject> element specifically, so a preview
+    // image's <v:imagedata r:id="…"> earlier in the markup is not mistaken for
+    // the OLE binary's relationship id.
+    const oleTag = rawXml.match(/<o:OLEObject\b[^>]*>/i)?.[0] ?? rawXml;
+    const progIdMatch = oleTag.match(/ProgID="([^"]+)"/i) ?? oleTag.match(/progId="([^"]+)"/i);
+    const rIdMatch = oleTag.match(/r:id="([^"]+)"/i);
+    const typeMatch = oleTag.match(/Type="([^"]+)"/i);
     if (!progIdMatch) {
         return null;
     }
     const progId = progIdMatch[1];
     const rId = rIdMatch ? rIdMatch[1] : "";
     const objectType = typeMatch && typeMatch[1].toLowerCase().includes("link") ? "linked" : "embedded";
-    // Extract dimensions
+    // Extract dimensions (from the surrounding shape, hence full rawXml)
     const widthMatch = rawXml.match(/(?:cx|width)="(\d+)"/i);
     const heightMatch = rawXml.match(/(?:cy|height)="(\d+)"/i);
     return {

package/dist/esm/modules/word/advanced/style-map.js

@@ -139,14 +139,8 @@ export const DEFAULT_STYLE_MAP = {
  * ```
  */
 export function parseStyleMap(dsl, options) {
-    const rules = [];
-    // Include defaults if requested
-    if (options?.includeDefaults !== false && options?.base) {
-        rules.push(...options.base.rules);
-    }
-    else if (options?.includeDefaults !== false && !options?.base) {
-        rules.push(...DEFAULT_STYLE_MAP.rules);
-    }
+    // User-defined rules from the DSL.
+    const userRules = [];
     const lines = dsl
         .split("\n")
         .map(l => l.trim())
@@ -154,10 +148,37 @@ export function parseStyleMap(dsl, options) {
     for (const line of lines) {
         const rule = parseRule(line);
         if (rule) {
-            rules.push(rule);
+            userRules.push(rule);
         }
     }
-    // Sort by priority (highest first)
+    // Default / base rules requested via `includeDefaults`.
+    const defaultRules = [];
+    if (options?.includeDefaults !== false && options?.base) {
+        defaultRules.push(...options.base.rules);
+    }
+    else if (options?.includeDefaults !== false && !options?.base) {
+        defaultRules.push(...DEFAULT_STYLE_MAP.rules);
+    }
+    // An explicit DSL rule should always win over a default rule for the same
+    // element — that is the whole point of providing one. Default rules,
+    // however, carry their own priorities (e.g. "Heading 1" => h1 has priority
+    // 10) that can exceed the fixed priority `parseRule` assigns to user rules.
+    // To guarantee user intent wins while preserving the relative priority
+    // ordering *within* each group, lift every user rule above the highest
+    // default priority. When there are no defaults this offset is 0 and user
+    // priorities are untouched.
+    const maxDefaultPriority = defaultRules.reduce((m, r) => Math.max(m, r.priority ?? 0), 0);
+    const userOffset = defaultRules.length > 0 ? maxDefaultPriority + 1 : 0;
+    const liftedUserRules = userOffset === 0
+        ? userRules
+        : userRules.map(r => ({ ...r, priority: (r.priority ?? 0) + userOffset }));
+    // User rules come first so that, after a stable sort, an explicit DSL rule
+    // also wins over any default rule that happens to share its (lifted)
+    // priority. The sort below only reorders by priority; equal priorities
+    // preserve this user-before-default ordering.
+    const rules = [...liftedUserRules, ...defaultRules];
+    // Sort by priority (highest first). Array.prototype.sort is stable, so
+    // rules of equal priority keep their relative order (user rules first).
     rules.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
     return { rules };
 }

package/dist/esm/modules/word/builder/run-builders.js

@@ -449,7 +449,13 @@ export function mathSubSuperScript(base, subScript, superScript) {
 export function mathPreSubSuperScript(base, preSubScript, preSuperScript) {
     return { type: "mathPreSubSuperScript", base, preSubScript, preSuperScript };
 }
-/** Create a math phantom (invisible expression that takes up space). */
+/**
+ * Create a math phantom (an expression that takes up space).
+ *
+ * Note: in OOXML the phantom base is *shown* by default. To make the classic
+ * "occupies space but invisible" phantom pass `{ show: false }`; passing only
+ * `transparent: true` is not sufficient to hide the base in Word.
+ */
 export function mathPhantom(content, options) {
     return { type: "mathPhantom", content, ...options };
 }

package/dist/esm/modules/word/constants.js

@@ -268,7 +268,11 @@ export const ContentType = {
     ChartEx: "application/vnd.ms-office.chartEx+xml",
     Xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     CustomXml: "application/xml",
-    VbaProject: "application/vnd.ms-office.vbaProject"
+    VbaProject: "application/vnd.ms-office.vbaProject",
+    /** Glossary (Building Blocks) document part. */
+    Glossary: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml",
+    /** OLE embedded object binary. */
+    OleObject: "application/vnd.openxmlformats-officedocument.oleObject"
 };
 /** Map from image file extension to content type. */
 export const IMAGE_CONTENT_TYPES = {