@cj-tech-master/excelts 9.6.0 → 9.6.1

package/dist/browser/modules/word/builder/document-handle.js

@@ -129,7 +129,7 @@ export const Document = {
         const fileName = `image${s.nextImageId}.${mediaType}`;
         const rId = `__img_${s.nextImageId}`;
         const drawingId = s.nextDrawingId++;
-        s.images.push({ data, mediaType, fileName, rId });
+        s.images.push({ data, mediaType, fileName, rId, fallbackData: options?.fallbackData });
         s.body.push(paragraph([
             {
                 content: [
@@ -153,7 +153,7 @@ export const Document = {
         const s = _toState(doc);
         const fileName = `image${s.nextImageId}.${mediaType}`;
         const rId = `__img_${s.nextImageId}`;
-        s.images.push({ data, mediaType, fileName, rId });
+        s.images.push({ data, mediaType, fileName, rId, fallbackData: options?.fallbackData });
         s.body.push(floatingImage({
             rId,
             width,
@@ -490,6 +490,18 @@ export const Document = {
             uiPriority: 99,
             unhideWhenUsed: true,
             runProperties: { color: "0563C1", underline: "single" }
+        }, {
+            // Word's built-in "visited hyperlink" character style. Referenced by
+            // hyperlinks created with `history: true` so visited links render in
+            // the standard purple instead of the unvisited blue.
+            type: "character",
+            styleId: "FollowedHyperlink",
+            name: "FollowedHyperlink",
+            basedOn: "DefaultParagraphFont",
+            uiPriority: 99,
+            semiHidden: true,
+            unhideWhenUsed: true,
+            runProperties: { color: "954F72", underline: "single" }
         }, {
             // Word's built-in zero-formatting base table style. Required so
             // that styles like TableGrid (which sets `basedOn: "TableNormal"`)

package/dist/browser/modules/word/builder/paragraph-builders.js

@@ -24,6 +24,15 @@ export function heading(content, level) {
 }
 /** Create a hyperlink. */
 export function hyperlink(linkText, options) {
+    // Reference the built-in character style so the colour is governed by the
+    // style table (and follows the theme) — Hyperlink for unvisited links,
+    // FollowedHyperlink for visited ones (`history: true`). We also emit the
+    // matching colour + underline as direct formatting so the link still renders
+    // correctly when the document has no style table (Word does the same).
+    const visited = options.history === true;
+    const defaultProps = visited
+        ? { style: "FollowedHyperlink", color: "954F72", underline: "single" }
+        : { style: "Hyperlink", color: "0563C1", underline: "single" };
     return {
         type: "hyperlink",
         rId: options.rId,
@@ -33,7 +42,7 @@ export function hyperlink(linkText, options) {
         docLocation: options.docLocation,
         tgtFrame: options.tgtFrame,
         history: options.history,
-        children: [text(linkText, options.properties ?? { color: "0563C1", underline: "single" })]
+        children: [text(linkText, options.properties ?? defaultProps)]
     };
 }
 /** Create a bookmark start. */

package/dist/browser/modules/word/builder/run-builders.d.ts

@@ -151,9 +151,26 @@ export declare function tocField(options?: {
     tcLevels?: string;
     /** Hyperlinks for entries. */
     hyperlink?: boolean;
-    /** Right-align page numbers. */
+    /**
+     * Right-align page numbers.
+     *
+     * NOTE: Right-aligned page numbers are the TOC default — they come from the
+     * right-aligned tab stop in the TOC paragraph styles, not from a field
+     * switch. The `\z` switch does NOT mean "right align": per ECMA-376 it
+     * *hides* the tab leader and page numbers in Web layout view. Mapping this
+     * option to `\z` therefore broke the layout, so we no longer emit it.
+     */
     rightAlignedPageNumbers?: boolean;
-    /** Use tab leader (default "." dots). */
+    /**
+     * Tab leader style between an entry and its page number.
+     *
+     * NOTE: The dotted leader is already the TOC default (a tab stop with dot
+     * leader defined by the TOC paragraph styles). The TOC field has no switch
+     * for choosing the leader glyph — the `\p` switch sets the *separator
+     * character* (replacing the tab entirely), which would DISABLE the leader
+     * dots and the right-aligned page number. We therefore do not translate
+     * this option into `\p`; the leader is controlled by the TOC styles.
+     */
     tabLeader?: "." | "-" | "_" | " ";
     /** Suppress page numbers. */
     noPageNumbers?: boolean;

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

@@ -271,12 +271,8 @@ export function tocField(options) {
     if (options?.hyperlink) {
         instruction += "\\h ";
     }
-    if (options?.rightAlignedPageNumbers) {
-        instruction += "\\z ";
-    }
-    if (options?.tabLeader) {
-        instruction += `\\p "${options.tabLeader}" `;
-    }
+    // Intentionally NOT emitting `\z` for rightAlignedPageNumbers — see note above.
+    // Intentionally NOT emitting `\p` for tabLeader — see the field note above.
     if (options?.noPageNumbers) {
         instruction += "\\n ";
     }

package/dist/browser/modules/word/convert/odt/odt.js

@@ -1168,7 +1168,12 @@ function sanitizeOdtPictureName(raw) {
  */
 export async function writeOdt(doc) {
     const encoder = utf8Encoder;
-    const archive = zip();
+    // `noSort: true` preserves insertion order. The ODF spec (OpenDocument
+    // v1.2 part 3, §3.3) requires the `mimetype` entry to be the FIRST entry in
+    // the package and STORED (uncompressed) so the file type can be detected by
+    // magic bytes. The default ZipArchive behaviour sorts entries alphabetically,
+    // which would push `mimetype` after `content.xml` and break ODF detection.
+    const archive = zip({ noSort: true });
     // Mimetype MUST be the first entry in the ZIP, uncompressed (ODF spec requirement)
     archive.add("mimetype", encoder.encode("application/vnd.oasis.opendocument.text"), { level: 0 });
     // Compute a sanitised rId → Pictures/<safe>.<ext> map up front so the

package/dist/browser/modules/word/layout/layout-full.d.ts

@@ -29,6 +29,18 @@ export interface PageGeometryOverride {
     readonly marginBottom?: number;
     readonly marginLeft?: number;
     readonly marginRight?: number;
+    /**
+     * Distance of the header band from the top edge of the page, in
+     * points. Overrides the section's `pgMar.header`. Header paragraphs
+     * are laid out starting at this y-offset from the page top.
+     */
+    readonly headerMargin?: number;
+    /**
+     * Distance of the footer band from the bottom edge of the page, in
+     * points. Overrides the section's `pgMar.footer`. The footer band's
+     * top is placed at `pageHeight - footerMargin`.
+     */
+    readonly footerMargin?: number;
 }
 /** Options for the full layout engine. */
 export interface FullLayoutOptions extends LayoutOptions {

package/dist/browser/modules/word/layout/layout-full.js

@@ -370,7 +370,7 @@ function layoutFootnotes(doc, ids, geometry, options, bodyBottomPageY, imageMap)
             noteById.set(note.id, note);
         }
     }
-    const footerOffsetPt = geometry.height - twipsToPt(doc.sectionProperties?.margins?.footer ?? 720);
+    const footerOffsetPt = geometry.height - geometry.footerOffset;
     /**
      * Vertical room available for the footnote stack on this page.
      * The stack must sit between `bodyBottomPageY` (top) and
@@ -604,7 +604,7 @@ function layoutHeader(doc, pageNumber, geometry, options, imageMap) {
     if (!part) {
         return [];
     }
-    const headerOffsetPt = twipsToPt(doc.sectionProperties?.margins?.header ?? 720);
+    const headerOffsetPt = geometry.headerOffset;
     return layoutHeaderFooterChildren(part.content.children, headerOffsetPt, geometry, options, imageMap);
 }
 function layoutFooter(doc, pageNumber, geometry, options, imageMap) {
@@ -627,7 +627,7 @@ function layoutFooter(doc, pageNumber, geometry, options, imageMap) {
     // where `pgMar.header` is the absolute offset of the band from the
     // page top). Renderers consume both bands with the same
     // "treat layout-y as page-y" rule.
-    const footerOffsetPt = geometry.height - twipsToPt(doc.sectionProperties?.margins?.footer ?? 720);
+    const footerOffsetPt = geometry.height - geometry.footerOffset;
     return layoutHeaderFooterChildren(part.content.children, footerOffsetPt, geometry, options, imageMap);
 }
 function layoutHeaderFooterChildren(children, initialCursorY, geometry, options, imageMap) {
@@ -657,6 +657,11 @@ function computePageGeometry(sectionProps, override) {
     const sectionMarginBottom = twipsToPt(sectionProps?.margins?.bottom ?? DEFAULT_PAGE_MARGIN_TWIPS);
     const sectionMarginLeft = twipsToPt(sectionProps?.margins?.left ?? DEFAULT_PAGE_MARGIN_TWIPS);
     const sectionMarginRight = twipsToPt(sectionProps?.margins?.right ?? DEFAULT_PAGE_MARGIN_TWIPS);
+    // Header / footer band offsets. Word's default `pgMar.header` /
+    // `pgMar.footer` is 720 twips (0.5") — the same default used by the
+    // header / footer layout helpers historically.
+    const sectionHeaderOffset = twipsToPt(sectionProps?.margins?.header ?? 720);
+    const sectionFooterOffset = twipsToPt(sectionProps?.margins?.footer ?? 720);
     // Per-axis override: callers (PDF bridge, custom hosts) may want to
     // pin the page size or margin on one axis without disturbing the
     // others — `pageWidth` doesn't imply overriding margins, etc.
@@ -666,6 +671,8 @@ function computePageGeometry(sectionProps, override) {
     const marginBottom = override?.marginBottom ?? sectionMarginBottom;
     const marginLeft = override?.marginLeft ?? sectionMarginLeft;
     const marginRight = override?.marginRight ?? sectionMarginRight;
+    const headerOffset = override?.headerMargin ?? sectionHeaderOffset;
+    const footerOffset = override?.footerMargin ?? sectionFooterOffset;
     return {
         width,
         height,
@@ -674,7 +681,9 @@ function computePageGeometry(sectionProps, override) {
         marginLeft,
         marginRight,
         contentWidth: width - marginLeft - marginRight,
-        contentHeight: height - marginTop - marginBottom
+        contentHeight: height - marginTop - marginBottom,
+        headerOffset,
+        footerOffset
     };
 }
 function computeSectionBreaks(layout) {
@@ -869,35 +878,64 @@ function layoutParagraph(para, startY, contentWidth, options, pageContext, image
 // =============================================================================
 function layoutTable(table, startY, contentWidth, sourceIndex, options, imageMap) {
     const numCols = table.rows.length > 0 ? table.rows[0].cells.length : 0;
-    const colWidth = numCols > 0 ? contentWidth / numCols : contentWidth;
+    // Resolve per-column widths (in points). Prefer the table's explicit
+    // `columnWidths` (twips) — populated e.g. by the Excel→Word bridge —
+    // scaled to fit the available content width so a table authored wider
+    // than the page still renders proportionally. Fall back to equal
+    // division when no column widths are declared. This mirrors the
+    // sister layout engine in `layout.ts` (which also honours
+    // `columnWidths` + `gridSpan`).
+    const colWidths = resolveColumnWidthsPt(table, numCols, contentWidth);
+    // Prefix sums so a cell at column `ci` starts at `colOffsets[ci]` and
+    // a `gridSpan` cell can sum the widths it covers.
+    const colOffsets = [0];
+    for (let i = 0; i < colWidths.length; i++) {
+        colOffsets.push(colOffsets[i] + colWidths[i]);
+    }
     const cells = [];
     let cursorY = 0;
     for (let ri = 0; ri < table.rows.length; ri++) {
         const row = table.rows[ri];
         let maxRowHeight = DEFAULT_FONT_SIZE_PT * 1.5; // minimum row height
+        // Track the grid column each cell occupies, honouring gridSpan so a
+        // 2-wide cell pushes the next cell two grid columns to the right.
+        let gridCol = 0;
         for (let ci = 0; ci < row.cells.length; ci++) {
             const cell = row.cells[ci];
-            const cellX = ci * colWidth;
+            const span = Math.max(1, cell.properties?.gridSpan ?? 1);
+            const startCol = Math.min(gridCol, colWidths.length - 1);
+            const endCol = Math.min(gridCol + span, colWidths.length);
+            const cellX = colOffsets[startCol] ?? 0;
+            const cellWidth = (colOffsets[endCol] ?? contentWidth) - cellX;
             const cellContent = [];
             let cellCursorY = 2; // cell padding top
             for (const block of cell.content) {
                 if (block.type === "paragraph") {
-                    const laid = layoutParagraph(block, cellCursorY, colWidth - 4, options, undefined, imageMap);
+                    const laid = layoutParagraph(block, cellCursorY, cellWidth - 4, options, undefined, imageMap);
                     cellContent.push({ ...laid, sourceIndex: -1 });
                     cellCursorY = laid.rect.y + laid.rect.height;
                 }
-                // nested tables skipped for simplicity
+                else if (block.type === "table") {
+                    // Nested table: lay it out within the cell's content width and
+                    // stack it below preceding content. The PDF/SVG renderers
+                    // already translate nested `LayoutTable` rects by the cell
+                    // origin, so emitting it here is all that's needed.
+                    const laidNested = layoutTable(block, cellCursorY, cellWidth - 4, -1, options, imageMap);
+                    cellContent.push(laidNested);
+                    cellCursorY = laidNested.rect.y + laidNested.rect.height;
+                }
             }
             const cellHeight = cellCursorY + 2; // cell padding bottom
             if (cellHeight > maxRowHeight) {
                 maxRowHeight = cellHeight;
             }
             cells.push({
-                rect: { x: cellX, y: startY + cursorY, width: colWidth, height: cellHeight },
+                rect: { x: cellX, y: startY + cursorY, width: cellWidth, height: cellHeight },
                 row: ri,
                 col: ci,
                 content: cellContent
             });
+            gridCol += span;
         }
         // Normalize cell heights to row max
         for (const c of cells) {
@@ -914,6 +952,33 @@ function layoutTable(table, startY, contentWidth, sourceIndex, options, imageMap
         sourceIndex
     };
 }
+/**
+ * Resolve a table's per-column widths in points.
+ *
+ * If `table.columnWidths` (twips) is present and covers all columns, it
+ * is used and proportionally scaled to fit `contentWidth` (so a table
+ * authored wider than the page shrinks to fit rather than overflowing).
+ * Otherwise the content width is divided equally among the columns.
+ */
+function resolveColumnWidthsPt(table, numCols, contentWidth) {
+    if (numCols <= 0) {
+        return [];
+    }
+    const declared = table.columnWidths;
+    if (declared && declared.length >= numCols) {
+        const pts = declared.slice(0, numCols).map(twipsToPt);
+        const total = pts.reduce((a, b) => a + b, 0);
+        if (total > 0) {
+            // Scale to fit the content width (shrink overflow, expand
+            // under-wide tables to use the full measure — matching how Word
+            // distributes a table set to a percentage / auto width).
+            const scale = contentWidth / total;
+            return pts.map(w => w * scale);
+        }
+    }
+    const equal = contentWidth / numCols;
+    return new Array(numCols).fill(equal);
+}
 /**
  * Walk a paragraph's children and emit a flat sequence of paragraph
  * segments — text runs preserve their formatting; inline images become

package/dist/browser/modules/word/layout/layout-model.d.ts

@@ -290,6 +290,18 @@ export interface PageGeometry {
     /** Usable content area. */
     readonly contentWidth: number;
     readonly contentHeight: number;
+    /**
+     * Distance of the header band from the top edge of the page, in
+     * points (ECMA-376 `pgMar.header`). Header paragraphs are laid out
+     * starting at this y-offset from the page top.
+     */
+    readonly headerOffset: number;
+    /**
+     * Distance of the footer band from the bottom edge of the page, in
+     * points (ECMA-376 `pgMar.footer`). The footer band's top sits at
+     * `height - footerOffset`.
+     */
+    readonly footerOffset: number;
 }
 /** A fully laid-out page. */
 export interface LayoutPage {

package/dist/browser/modules/word/query/merge.js

@@ -68,17 +68,33 @@ export function mergeDocuments(documents, options) {
     const mergedComments = base.comments ? [...base.comments] : [];
     for (let i = 1; i < documents.length; i++) {
         const doc = documents[i];
-        // Insert section break before appending next document
-        const sectionBreakPara = {
-            type: "paragraph",
-            properties: {
-                sectionProperties: {
-                    breakType
+        // Mark a section break BEFORE appending the next document. In OOXML a
+        // section break is carried by the `sectPr` of the LAST paragraph of the
+        // preceding section — NOT by an extra empty paragraph. Appending an empty
+        // <w:p> with only a sectPr makes Word render a stray blank line / blank
+        // page. So we attach the break to the last paragraph already in the body;
+        // only if the body currently ends with a non-paragraph block (e.g. a
+        // table, which cannot carry a sectPr directly) do we fall back to a
+        // minimal carrier paragraph.
+        const lastBlock = mergedBody[mergedBody.length - 1];
+        if (lastBlock && lastBlock.type === "paragraph") {
+            const para = lastBlock;
+            mergedBody[mergedBody.length - 1] = {
+                ...para,
+                properties: {
+                    ...para.properties,
+                    sectionProperties: { ...para.properties?.sectionProperties, breakType }
                 }
-            },
-            children: []
-        };
-        mergedBody.push(sectionBreakPara);
+            };
+        }
+        else {
+            const sectionBreakPara = {
+                type: "paragraph",
+                properties: { sectionProperties: { breakType } },
+                children: []
+            };
+            mergedBody.push(sectionBreakPara);
+        }
         // Compute id remappings BEFORE cloning the body so we can rewrite refs
         // during the clone in a single pass.
         const numMaps = mergeNumberingDefinitions(doc, mergedAbstractNums, mergedNumInstances);

package/dist/browser/modules/word/query/split.js

@@ -119,17 +119,83 @@ function paragraphHasExplicitPageBreakRun(para) {
     }
     return false;
 }
+/**
+ * Return a copy of `para` with every explicit page-break run content removed.
+ * Runs left empty by the removal are dropped. Used when splitting by page
+ * break so the trailing break that separated this segment from the next does
+ * not render as a blank page in the standalone split document.
+ */
+function stripPageBreakRuns(para) {
+    const newChildren = [];
+    for (const child of para.children) {
+        if (isRun(child)) {
+            const content = child.content.filter(c => !(c.type === "break" && c.breakType === "page"));
+            if (content.length > 0) {
+                newChildren.push({ ...child, content });
+            }
+            // Drop runs that became empty after removing the page break.
+        }
+        else {
+            newChildren.push(child);
+        }
+    }
+    return { ...para, children: newChildren };
+}
+/** True when a paragraph has no children (after page-break stripping). */
+function paragraphIsEmpty(para) {
+    return para.children.length === 0;
+}
 function buildSplitDoc(source, segment, opts) {
+    // When splitting by section, the segment's last paragraph carries the
+    // section break (often `nextPage`) that originally separated it from the
+    // following section. In a standalone split document that break has nothing
+    // after it, so Word renders a trailing blank page. Strip the paragraph-level
+    // sectPr and promote its page setup to the document's own section
+    // properties instead.
+    let body = segment;
+    let promotedSectPr;
+    if (opts.by === "section" && segment.length > 0) {
+        const last = segment[segment.length - 1];
+        if (last.type === "paragraph" && last.properties?.sectionProperties) {
+            const para = last;
+            const props = para.properties;
+            const sectionProperties = props.sectionProperties;
+            const restProps = { ...props };
+            delete restProps.sectionProperties;
+            // Drop the inter-section break type: in a standalone document this is
+            // the (only/first) section, so a "nextPage" break would just push all
+            // content onto page 2, leaving page 1 blank.
+            const { breakType: _drop, ...sectWithoutBreak } = sectionProperties;
+            promotedSectPr = sectWithoutBreak;
+            const cleaned = { ...para, properties: restProps };
+            body = [...segment.slice(0, -1), cleaned];
+        }
+    }
+    else if (opts.by === "pageBreak" && segment.length > 0) {
+        // The segment ends with the paragraph that held the splitting page break.
+        // In a standalone document that trailing page break has nothing after it
+        // and renders a blank page, so remove it. If the paragraph held only the
+        // page break, drop the now-empty paragraph entirely.
+        const last = segment[segment.length - 1];
+        if (last.type === "paragraph" && paragraphHasExplicitPageBreakRun(last)) {
+            const stripped = stripPageBreakRuns(last);
+            body = paragraphIsEmpty(stripped)
+                ? segment.slice(0, -1)
+                : [...segment.slice(0, -1), stripped];
+        }
+    }
     if (!opts.preserveSharedParts) {
         // Minimal split: just body + docType
         return {
             docType: source.docType,
-            body: segment
+            body,
+            ...(promotedSectPr ? { sectionProperties: promotedSectPr } : {})
         };
     }
     // Full split: preserve all shared parts
     return {
         ...source,
-        body: segment
+        body,
+        ...(promotedSectPr ? { sectionProperties: promotedSectPr } : {})
     };
 }

package/dist/browser/modules/word/reader/docx-reader.js

@@ -246,6 +246,23 @@ function parseDrawingShape(anchorEl, wspEl, ctx) {
                 shape.noOutline = true;
             }
         }
+        // Parse transform (rotation / flip) from a:xfrm
+        const xfrmEl = findChild(spPrEl, "a:xfrm") ?? findChildNs(spPrEl, "xfrm");
+        if (xfrmEl) {
+            const rot = xfrmEl.attributes["rot"];
+            if (rot) {
+                const n = parseInt(rot, 10);
+                if (!Number.isNaN(n)) {
+                    shape.rotation = n;
+                }
+            }
+            if (xfrmEl.attributes["flipH"] === "1") {
+                shape.flipHorizontal = true;
+            }
+            if (xfrmEl.attributes["flipV"] === "1") {
+                shape.flipVertical = true;
+            }
+        }
     }
     // Parse text content (wps:txbx > w:txbxContent)
     const txbxEl = findChild(wspEl, "wps:txbx") ?? findChildNs(wspEl, "txbx");
@@ -263,6 +280,12 @@ function parseDrawingShape(anchorEl, wspEl, ctx) {
             shape.textContent = paras;
         }
     }
+    // Parse text body vertical anchor (wps:bodyPr/@anchor)
+    const bodyPrEl = findChild(wspEl, "wps:bodyPr") ?? findChildNs(wspEl, "bodyPr");
+    const anchorAttr = bodyPrEl?.attributes["anchor"];
+    if (anchorAttr === "t" || anchorAttr === "ctr" || anchorAttr === "b") {
+        shape.textBodyAnchor = anchorAttr;
+    }
     // Parse positioning
     const posH = findChild(anchorEl, "wp:positionH");
     if (posH) {

package/dist/browser/modules/word/security/cfb-reader.d.ts

@@ -14,6 +14,15 @@ export interface CfbEntry {
     readonly name: string;
     /** Stream data. */
     readonly data: Uint8Array;
+    /**
+     * Optional storage path for the stream. Each element is a storage
+     * (directory) name; the stream lives inside the nested storages.
+     * For example `path: ["\u0006DataSpaces", "TransformInfo"]` with
+     * `name: "..."` places the stream at
+     * `\u0006DataSpaces/TransformInfo/<name>`. Omit or use `[]` for a
+     * top-level stream under the root storage.
+     */
+    readonly path?: readonly string[];
 }
 /**
  * Read a CFB (OLE2 Compound File) and extract all stream entries.
@@ -27,9 +36,11 @@ export declare function readCfb(buffer: Uint8Array): CfbEntry[];
 /**
  * Write a set of named stream entries into a CFB (OLE2 Compound File) container.
  *
- * Produces a minimal v3 CFB with 512-byte sectors. Does not use mini-streams
- * (all data is stored in regular sectors). This is suitable for encrypted Office
- * documents where every stream exceeds 4096 bytes.
+ * Produces a v3 CFB with 512-byte sectors. Streams smaller than 4096 bytes are
+ * stored in the mini-stream (64-byte mini-sectors) exactly as Office does;
+ * larger streams use regular sectors. Entries may declare a `path` to nest the
+ * stream inside one or more storages — required for the `\u0006DataSpaces`
+ * structure that Office demands in encrypted documents.
  *
  * @param entries - Named stream entries to include.
  * @returns The CFB file as a Uint8Array.