@cj-tech-master/excelts 9.6.0 → 9.6.1

package/dist/types/modules/pdf/excel-bridge.d.ts

@@ -17,6 +17,7 @@
  */
 import type { Chart, RegionMapDataOptions } from "../excel/chart/index.js";
 import type { Workbook } from "../excel/workbook.browser.js";
+import type { LayoutChart } from "../word/layout/layout-model.js";
 import type { Chart as WordChart } from "../word/types.js";
 import { type PdfPageBuilder } from "./builder/document-builder.js";
 import { type PdfExportOptions } from "./types.js";
@@ -126,3 +127,34 @@ export declare function createWordChartPdfRenderer(): (chart: WordChart, page: P
     width: number;
     height: number;
 }) => void;
+/**
+ * Create a layout-aware chart renderer for use as the internal
+ * `RenderLayoutOptions.chartRenderer` of the Word→PDF bridge.
+ *
+ * Unlike {@link createWordChartPdfRenderer} (which only sees the inner
+ * classic `Chart` model), this renderer receives the full
+ * {@link LayoutChart} and therefore handles **both** chart families
+ * with the full Excel rendering engine:
+ *
+ * - Classic `<c:chart>` (`chartKind === "chart"`) → `wordChartToChartModel`
+ *   → `drawChartPdf` (vector).
+ * - Modern `<cx:chartSpace>` ChartEx (`chartKind === "chartEx"`,
+ *   e.g. sunburst / treemap / waterfall / funnel / boxWhisker /
+ *   histogram / pareto / regionMap) → `parseChartEx` → `drawChartExPdf`
+ *   (vector) when the layout is vector-capable, otherwise the
+ *   pre-rendered SVG carried on the `LayoutChart` is left for the
+ *   translator's fallback.
+ *
+ * Returns `false` to decline a chart so the translator's built-in
+ * fallback (inline SVG, then a titled placeholder box) takes over. This
+ * keeps "fail soft" behaviour: a chart the engine can't draw still
+ * renders *something* rather than a blank slot.
+ *
+ * Requires `installChartSupport()` to have been called.
+ */
+export declare function createWordLayoutChartPdfRenderer(): (chart: LayoutChart, page: PdfPageBuilder, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}) => boolean | void;

package/dist/types/modules/pdf/word-bridge.d.ts

@@ -53,19 +53,21 @@ export interface DocxToPdfOptions {
     /** Default font size in points (default: 11). */
     readonly defaultFontSize?: number;
     /**
-     * Header margin from top edge in points (default: 36).
+     * Header band distance from the top edge of the page, in points
+     * (default: section's `pgMar.header`, or 36pt / 0.5").
      *
-     * @deprecated Currently has no effect on the layout-driven render
-     * path: header paragraphs are rendered into the page's `marginTop`
-     * strip starting at y=0 without an additional offset. Influence
-     * header placement by widening `marginTop` instead.
+     * Header paragraphs are laid out starting at this y-offset from the
+     * page top. Overriding it moves the entire header band — useful when
+     * the source document declares no section properties or you want to
+     * tighten / loosen the header position without touching `marginTop`.
      */
     readonly headerMargin?: number;
     /**
-     * Footer margin from bottom edge in points (default: 36).
+     * Footer band distance from the bottom edge of the page, in points
+     * (default: section's `pgMar.footer`, or 36pt / 0.5").
      *
-     * @deprecated See {@link DocxToPdfOptions.headerMargin}. Footer
-     * paragraphs are rendered starting at `pageHeight - marginBottom`.
+     * The footer band's top sits at `pageHeight - footerMargin`. The
+     * footnote stack (if any) is placed directly above this line.
      */
     readonly footerMargin?: number;
     /**
@@ -89,14 +91,17 @@ export interface DocxToPdfOptions {
      * destination rectangle in PDF coordinates. The implementation
      * should draw the chart into the rectangle.
      *
-     * Return `false` to decline a chart (the translator then falls back
-     * to its built-in placeholder rendering: an outlined rectangle with
-     * the chart title centred). Return `void` or `true` to indicate the
-     * chart was handled.
+     * Return `false` to decline a chart. The translator then falls back
+     * to the built-in layout-aware Excel renderer (which also handles
+     * `chartEx` charts), then to the inline `LayoutChart.svg` if present,
+     * and finally to a placeholder rectangle with the chart title
+     * centred. Return `void` or `true` to indicate the chart was handled.
      *
-     * Note: `chartEx` charts never reach this callback because there is
-     * no `Chart` instance to pass; they always render through the
-     * translator's built-in path.
+     * Note: `chartEx` charts (sunburst / treemap / waterfall / funnel /
+     * boxWhisker / …) never reach this `Chart`-typed callback because
+     * there is no classic `Chart` instance to pass. They are rendered by
+     * the built-in layout-aware renderer instead (full vector output when
+     * `installChartSupport()` has been called).
      */
     readonly chartRenderer?: (chart: Chart, page: PdfPageBuilder, rect: {
         x: number;

package/dist/types/modules/stream/common/consumers.d.ts

@@ -5,9 +5,10 @@
  * Used by both Node.js and browser implementations.
  */
 type StreamInput = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>;
+type BlobOptions = NonNullable<ConstructorParameters<typeof Blob>[1]>;
 export interface StreamConsumers {
     arrayBuffer(stream: StreamInput): Promise<ArrayBuffer>;
-    blob(stream: StreamInput, options?: BlobPropertyBag): Promise<Blob>;
+    blob(stream: StreamInput, options?: BlobOptions): Promise<Blob>;
     buffer(stream: StreamInput): Promise<Uint8Array>;
     json(stream: StreamInput): Promise<unknown>;
     text(stream: StreamInput, encoding?: string): Promise<string>;

package/dist/types/modules/word/builder/document-handle.d.ts

@@ -66,6 +66,7 @@ export declare const Document: {
     addImage(doc: DocumentHandle, data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
         altText?: string;
         name?: string;
+        fallbackData?: Uint8Array;
     }): {
         rId: string;
         drawingId: number;
@@ -88,6 +89,7 @@ export declare const Document: {
         rotation?: number;
         flipHorizontal?: boolean;
         flipVertical?: boolean;
+        fallbackData?: Uint8Array;
     }): string;
     /** Add a custom font definition. */
     addFont(doc: DocumentHandle, font: FontDef): void;

package/dist/types/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/types/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/types/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/types/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.

package/dist/types/modules/word/types.d.ts

@@ -991,6 +991,17 @@ export interface TableProperties {
     readonly indent?: Twips;
     /** Table look (conditional formatting). */
     readonly look?: TableLook;
+    /**
+     * Number of rows in a single horizontal banding stripe (`w:tblStyleRowBandSize`).
+     * Defaults to 1 in Word. Set on table styles so the `band1Horz`/`band2Horz`
+     * conditional formats render as visible row banding.
+     */
+    readonly rowBandSize?: number;
+    /**
+     * Number of columns in a single vertical banding stripe (`w:tblStyleColBandSize`).
+     * Defaults to 1 in Word.
+     */
+    readonly colBandSize?: number;
     /** Floating table properties. */
     readonly float?: TableFloat;
     /** Cell spacing in twips. */
@@ -1450,6 +1461,8 @@ export interface DrawingShape {
     readonly noOutline?: boolean;
     /** Text content inside the shape. */
     readonly textContent?: readonly Paragraph[];
+    /** Vertical anchoring of the text body inside the shape (a:bodyPr/@anchor). */
+    readonly textBodyAnchor?: "t" | "ctr" | "b" | "just" | "dist";
     /** Alternative text. */
     readonly altText?: string;
     /** Shape name. */
@@ -1475,6 +1488,10 @@ export interface DrawingShape {
     readonly behindDoc?: boolean;
     /** Rotation in 60,000ths of a degree. */
     readonly rotation?: number;
+    /** Flip the shape horizontally (a:xfrm/@flipH). */
+    readonly flipHorizontal?: boolean;
+    /** Flip the shape vertically (a:xfrm/@flipV). */
+    readonly flipVertical?: boolean;
     /** Raw XML string (for preserving unrecognized shape details on round-trip). */
     readonly rawXml?: string;
     /**

package/dist/types/modules/word/units.d.ts

@@ -7,10 +7,16 @@
 export declare const TWIPS_PER_INCH = 1440;
 /** Twips per point. */
 export declare const TWIPS_PER_POINT = 20;
-/** Twips per centimeter (approximate). */
-export declare const TWIPS_PER_CM = 567;
-/** Twips per millimeter (approximate). */
-export declare const TWIPS_PER_MM = 56.7;
+/**
+ * Twips per centimeter, derived exactly from 1 inch = 2.54 cm = 1440 twips
+ * (= 566.9291…). Using the exact factor — rather than the rounded 567 — keeps
+ * metric page sizes aligned with their canonical twip values, e.g.
+ * `cmToTwips(21)` → 11906 and `cmToTwips(29.7)` → 16838 (A4), matching
+ * `A4_PAGE_WIDTH` / `A4_PAGE_HEIGHT` in constants.ts.
+ */
+export declare const TWIPS_PER_CM: number;
+/** Twips per millimeter, derived exactly from {@link TWIPS_PER_CM}. */
+export declare const TWIPS_PER_MM: number;
 /** EMU (English Metric Units) per inch — DrawingML coordinate space. */
 export declare const EMU_PER_INCH = 914400;
 /** EMU per centimeter. */

package/dist/types/modules/word/writer/image-writer.d.ts

@@ -7,4 +7,4 @@
 import type { XmlSink } from "../../xml/types.js";
 import type { FloatingImage } from "../types.js";
 /** Render a floating image as a standalone paragraph with wp:anchor. */
-export declare function renderFloatingImage(xml: XmlSink, img: FloatingImage, imageRemap?: ReadonlyMap<string, string>): void;
+export declare function renderFloatingImage(xml: XmlSink, img: FloatingImage, imageRemap?: ReadonlyMap<string, string>, nextDocPrId?: () => number): void;

package/dist/types/modules/word/writer/render-context.d.ts

@@ -29,6 +29,21 @@ export interface RenderHelpers {
     readonly imageRemap?: ReadonlyMap<string, string>;
     /** See WordRenderContext.hyperlinkRIds. */
     readonly hyperlinkRIds?: ReadonlyWeakMap<object, string>;
+    /**
+     * Allocates the next document-wide unique drawing object id, used for
+     * `wp:docPr/@id` (and the matching `pic:cNvPr/@id` / `wps:cNvPr/@id`).
+     *
+     * Word requires every drawing object id to be a unique positive integer
+     * across the entire document — including body, headers, footers, footnotes,
+     * endnotes, comments and text boxes. The packager seeds a single counter on
+     * the render context and exposes it here so every drawing renderer draws
+     * from the same id space, regardless of what (possibly duplicate or unset)
+     * `drawingId` the model carries.
+     *
+     * When undefined (e.g. a standalone renderer call without a context),
+     * renderers fall back to the model's `drawingId` or `1`.
+     */
+    readonly nextDocPrId?: () => number;
     /**
      * Raw XML output policy. Controls how preserved/opaque rawXml fragments
      * (opaqueRun, opaqueParagraphChild, opaqueDrawing, _advancedFillXml, …)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "9.6.0",
+  "version": "9.6.1",
   "description": "Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.",
   "keywords": [
     "archive",
@@ -340,7 +340,7 @@
     "test:browser": "pnpm generate:csv-worker && rimraf dist && pnpm build:browser:bundle && vitest run --config vitest.browser.config.ts",
     "test:watch": "vitest",
     "build": "pnpm generate:csv-worker && rimraf dist && concurrently \"pnpm build:esm\" \"pnpm build:cjs\" \"pnpm build:browser\" \"pnpm build:browser:bundle\" && pnpm build:verify",
-    "build:verify": "tsc --noEmit --ignoreConfig --module NodeNext --moduleResolution NodeNext --lib ESNext,DOM --types node dist/types/index.d.ts dist/types/modules/archive/index.d.ts dist/types/modules/csv/index.d.ts dist/types/modules/formula/index.d.ts dist/types/modules/markdown/index.d.ts dist/types/modules/pdf/index.d.ts dist/types/modules/stream/index.d.ts dist/types/modules/xml/index.d.ts dist/types/modules/word/index.d.ts dist/types/modules/word/html.d.ts dist/types/modules/word/crypto.d.ts dist/types/modules/word/markdown.d.ts dist/types/modules/word/excel.d.ts",
+    "build:verify": "tsc --noEmit --ignoreConfig --module NodeNext --moduleResolution NodeNext --lib ESNext --types node dist/types/index.d.ts dist/types/modules/archive/index.d.ts dist/types/modules/csv/index.d.ts dist/types/modules/formula/index.d.ts dist/types/modules/markdown/index.d.ts dist/types/modules/pdf/index.d.ts dist/types/modules/stream/index.d.ts dist/types/modules/xml/index.d.ts dist/types/modules/word/index.d.ts dist/types/modules/word/html.d.ts dist/types/modules/word/crypto.d.ts dist/types/modules/word/markdown.d.ts dist/types/modules/word/excel.d.ts",
     "verify:treeshake": "node scripts/treeshake-verify.ts",
     "analyze:browser": "rimraf dist && node --input-type=module -e \"import { execSync } from 'node:child_process'; process.env.ANALYZE='true'; execSync('rolldown -c rolldown.config.ts', { stdio: 'inherit' });\"",
     "clean": "pnpm dlx --reporter=silent rimraf \"**/node_modules\" pnpm-lock.yaml \"**/dist\" -g && pnpm i",