@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/{browser/modules/word/writers → types/modules/word/writer}/header-footer-writer.d.ts

@@ -5,9 +5,10 @@
  */
 import type { XmlSink } from "../../xml/types.js";
 import type { HeaderFooterContent, Watermark } from "../types.js";
+import type { RenderHelpers } from "./render-context.js";
 /** Render a header part (word/header{N}.xml). */
-export declare function renderHeader(xml: XmlSink, content: HeaderFooterContent): void;
+export declare function renderHeader(xml: XmlSink, content: HeaderFooterContent, helpers?: RenderHelpers): void;
 /** Render a footer part (word/footer{N}.xml). */
-export declare function renderFooter(xml: XmlSink, content: HeaderFooterContent): void;
+export declare function renderFooter(xml: XmlSink, content: HeaderFooterContent, helpers?: RenderHelpers): void;
 /** Render a header part containing a watermark. */
 export declare function renderWatermarkHeader(xml: XmlSink, watermark: Watermark, imageRId?: string): void;

package/dist/{browser/modules/word/writers → 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): void;
+export declare function renderFloatingImage(xml: XmlSink, img: FloatingImage, imageRemap?: ReadonlyMap<string, string>): void;

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

@@ -0,0 +1,20 @@
+/**
+ * DOCX Writers - Math / Equations (OMML)
+ *
+ * Renders Office Math Markup Language elements (m:oMath).
+ */
+import type { XmlSink } from "../../xml/types.js";
+import type { MathBlock } from "../types.js";
+/**
+ * Render a math block (`m:oMathPara` containing one `m:oMath`).
+ *
+ * The OOXML schema only allows `m:oMathPara` inside a paragraph
+ * (`EG_PContent` includes `m:oMathPara`); it must not appear directly as
+ * a `EG_BlockLevelElts`. We therefore wrap it in `<w:p>` so the result is
+ * valid at the body level.
+ *
+ * Empty math blocks (`content.length === 0`) skip rendering altogether —
+ * an empty `<m:oMath/>` violates the schema (it requires at least one
+ * `OMathArg` child).
+ */
+export declare function renderMathBlock(xml: XmlSink, math: MathBlock): void;

package/dist/types/modules/word/{writers → writer}/numbering-writer.d.ts

@@ -7,4 +7,4 @@
 import type { XmlSink } from "../../xml/types.js";
 import type { AbstractNumbering, NumberingInstance, NumPicBullet } from "../types.js";
 /** Render word/numbering.xml. */
-export declare function renderNumbering(xml: XmlSink, abstractNums?: readonly AbstractNumbering[], instances?: readonly NumberingInstance[], numPicBullets?: readonly NumPicBullet[]): void;
+export declare function renderNumbering(xml: XmlSink, abstractNums?: readonly AbstractNumbering[], instances?: readonly NumberingInstance[], numPicBullets?: readonly NumPicBullet[], rawXmlPolicy?: "preserve" | "strip" | "reject"): void;

package/dist/types/modules/word/{writers → writer}/paragraph-writer.d.ts

@@ -5,9 +5,10 @@
  */
 import type { XmlSink } from "../../xml/types.js";
 import type { ParagraphProperties, Paragraph, Border } from "../types.js";
+import type { RenderHelpers } from "./render-context.js";
 /** Render a single border element. */
 export declare function renderBorder(xml: XmlSink, tagName: string, border: Border): void;
 /** Render w:pPr (paragraph properties). */
 export declare function renderParagraphProperties(xml: XmlSink, pPr: ParagraphProperties, insidePropertyChange?: boolean): void;
 /** Render a w:p element. */
-export declare function renderParagraph(xml: XmlSink, para: Paragraph): void;
+export declare function renderParagraph(xml: XmlSink, para: Paragraph, helpers?: RenderHelpers): void;

package/dist/types/modules/word/{writers → writer}/parts-writer.d.ts

@@ -7,7 +7,7 @@
 import type { XmlSink } from "../../xml/types.js";
 import type { DocumentSettings, CoreProperties, AppProperties, FontDef, DocumentBackground, CustomProperty, DocumentTheme, WebSettings, PersonInfo } from "../types.js";
 /** Render word/settings.xml. */
-export declare function renderSettings(xml: XmlSink, settings?: DocumentSettings): void;
+export declare function renderSettings(xml: XmlSink, settings?: DocumentSettings, rawXmlPolicy?: "preserve" | "strip" | "reject"): void;
 /** Render word/fontTable.xml. */
 export declare function renderFontTable(xml: XmlSink, fonts?: readonly FontDef[]): void;
 /** Render docProps/core.xml. */
@@ -19,8 +19,8 @@ export declare function renderDocumentBackground(xml: XmlSink, bg: DocumentBackg
 /** Render docProps/custom.xml. */
 export declare function renderCustomProperties(xml: XmlSink, properties: readonly CustomProperty[]): void;
 /** Render word/theme/theme1.xml (minimal theme). */
-export declare function renderTheme(xml: XmlSink, theme?: DocumentTheme): void;
+export declare function renderTheme(xml: XmlSink, theme?: DocumentTheme, rawXmlPolicy?: "preserve" | "strip" | "reject"): void;
 /** Render word/webSettings.xml. */
-export declare function renderWebSettings(xml: XmlSink, ws?: WebSettings): void;
+export declare function renderWebSettings(xml: XmlSink, ws?: WebSettings, rawXmlPolicy?: "preserve" | "strip" | "reject"): void;
 /** Render word/people.xml. */
 export declare function renderPeople(xml: XmlSink, people: readonly PersonInfo[]): void;

package/dist/types/modules/word/writer/reference-scanners.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DOCX Module - Reference Scanners
+ *
+ * Shared helpers for scanning the document model for image / hyperlink /
+ * chart references that need to be registered against a part-level .rels
+ * file. Used by both the bulk packager and the streaming writer to avoid
+ * behaviour drift in how header/footer/notes/comments parts collect their
+ * own relationships.
+ */
+import type { ChartContent, HeaderFooterContent, Hyperlink, Paragraph, ParagraphChild } from "../types.js";
+/**
+ * Recursively collect image rIds referenced inside a list of paragraph
+ * children. Descends into track-change wrappers (`InsertedRun`,
+ * `MovedToRun`, etc.) so an image embedded inside `<w:ins>...</w:ins>` is
+ * not silently lost.
+ */
+export declare function scanChildrenForImages(children: readonly ParagraphChild[], out: Set<string>): void;
+/**
+ * Recursively collect external-URL hyperlinks from a list of paragraph
+ * children. Descends into track-change wrappers so an inserted hyperlink
+ * isn't dropped.
+ *
+ * Always emits hyperlinks that carry a `url`, regardless of whether the
+ * model already has an `rId`. Reader-supplied `rId`s are stale once the
+ * package is repackaged because the relationship table is rebuilt from
+ * scratch — the packager assigns its own canonical `rId<N>` and exposes
+ * it via the `hyperlinkRIds` WeakMap, which the renderer consults.
+ */
+export declare function scanChildrenForHyperlinks(children: readonly ParagraphChild[], out: Hyperlink[]): void;
+/** Collect all image rIds referenced in header/footer content. */
+export declare function collectImageRidsFromContent(content: HeaderFooterContent): Set<string>;
+/** Collect hyperlinks from header/footer content. */
+export declare function collectHyperlinksFromHeaderFooter(content: HeaderFooterContent): Hyperlink[];
+/** Collect all chart contents inside header/footer content. */
+export declare function collectChartsFromHeaderFooter(content: HeaderFooterContent, out: ChartContent[]): void;
+/** Collect image rIds and hyperlinks from a notes/comments collection. */
+export declare function collectImageRidsFromNotes(notes: readonly {
+    content: readonly Paragraph[];
+}[] | undefined): Set<string>;
+export declare function collectHyperlinksFromNotes(notes: readonly {
+    content: readonly Paragraph[];
+}[] | undefined): Hyperlink[];

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

@@ -0,0 +1,52 @@
+/**
+ * DOCX Module - Relationship Manager
+ *
+ * Manages OPC relationships for the DOCX package.
+ * Generates .rels files for package-level and part-level relationships.
+ *
+ * Provides both an object-oriented RelationshipsState interface and
+ * backward-compatible free functions (addRelationship, renderRelationships, etc.).
+ */
+import type { XmlSink } from "../../xml/types.js";
+/** A single OPC relationship. */
+export interface Relationship {
+    readonly id: string;
+    readonly type: string;
+    readonly target: string;
+    /**
+     * OPC TargetMode. Standard values are `"External"` and `"Internal"`
+     * (with `"Internal"` typically omitted on the wire). Internally we accept
+     * any string so that round-tripped relationships preserve non-standard
+     * values verbatim; new relationships emitted by the writer's own helpers
+     * still pass `"External"` or `undefined`.
+     */
+    readonly targetMode?: string;
+}
+/** Rich relationship set with validation and dedup capabilities. */
+export interface RelationshipsState {
+    readonly rels: readonly Relationship[];
+    /** Add a relationship. If a matching (type, target, targetMode) already exists, returns its ID. */
+    add(type: string, target: string, targetMode?: string): string;
+    /** Add with a specific ID. Throws if ID already exists. */
+    addWithId(id: string, type: string, target: string, targetMode?: string): void;
+    /** Find existing relationship by type and target. */
+    findByTypeAndTarget(type: string, target: string): Relationship | undefined;
+    /** Check if an rId is already used. */
+    hasId(id: string): boolean;
+    /** Get count. */
+    count(): number;
+    /** Validate all relationships. Returns error messages (empty = valid). */
+    validate(): string[];
+    /** Render to XML. */
+    render(sink: XmlSink): void;
+}
+/** Create a new empty RelationshipsState. */
+export declare function createRelationships(): RelationshipsState;
+/** Add a relationship and return its assigned rId (free function alias). */
+export declare function addRelationship(state: RelationshipsState, type: string, target: string, targetMode?: string): string;
+/** Add a relationship with a specific ID (free function alias). */
+export declare function addRelationshipWithId(state: RelationshipsState, id: string, type: string, target: string, targetMode?: string): void;
+/** Get the number of relationships (free function alias). */
+export declare function getRelationshipCount(state: RelationshipsState): number;
+/** Render the relationships XML to a sink (free function alias). */
+export declare function renderRelationships(state: RelationshipsState, xml: XmlSink): void;

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

@@ -0,0 +1,124 @@
+/**
+ * Unified rendering context for DOCX XML serialization.
+ * Passed to all writer functions to provide shared state.
+ */
+import type { WordSecurityPolicy } from "../security/policy.js";
+/**
+ * A fully-qualified part name within the package (e.g. "/word/document.xml").
+ * Type alias kept for documentation; functionally identical to `string`.
+ */
+type PartName = string;
+/** ID generators for various document elements. */
+export interface IdGenerators {
+    nextDrawingId(): number;
+    nextSdtId(): number;
+    nextBookmarkId(): number;
+    nextDocPrId(): number;
+    nextChartId(): number;
+    nextImagePartId(): number;
+}
+/**
+ * Lightweight, content-renderer-facing subset of WordRenderContext.
+ *
+ * Most leaf renderers (run/paragraph/table/image) only need the rId remap and
+ * the hyperlink rId map; passing the full WordRenderContext would couple them
+ * to chartRIds/securityPolicy/etc. They take this `RenderHelpers` instead.
+ */
+export interface RenderHelpers {
+    /** See WordRenderContext.imageRIdRemap. */
+    readonly imageRemap?: ReadonlyMap<string, string>;
+    /** See WordRenderContext.hyperlinkRIds. */
+    readonly hyperlinkRIds?: ReadonlyWeakMap<object, string>;
+    /**
+     * Raw XML output policy. Controls how preserved/opaque rawXml fragments
+     * (opaqueRun, opaqueParagraphChild, opaqueDrawing, _advancedFillXml, …)
+     * are emitted. Defaults to `"preserve"` when undefined for backwards
+     * compatibility with callers that built helpers without a context.
+     */
+    readonly rawXmlPolicy?: "preserve" | "strip" | "reject";
+}
+/**
+ * Apply the `rawXmlPolicy` to a single `xml.writeRaw(...)` operation.
+ *
+ * - `"preserve"` (or undefined): write the fragment verbatim.
+ * - `"strip"`: skip writing — the surrounding wrapper element (if any) is
+ *   left empty. This is intentionally conservative: it preserves ZIP/relationship
+ *   integrity even though it may produce a structurally-incomplete element.
+ * - `"reject"`: throw `DocxRawXmlPolicyError` so the caller learns about the
+ *   opaque content instead of silently producing degraded output.
+ *
+ * Importing the error class lazily would create an import cycle; callers that
+ * need to throw should do so themselves. This helper just resolves the action.
+ */
+export type RawXmlAction = "write" | "skip" | "throw";
+export declare function resolveRawXmlAction(policy: "preserve" | "strip" | "reject" | undefined): RawXmlAction;
+/**
+ * Read-only WeakMap projection.
+ * (TS lib doesn't ship one; we mirror the readonly subset of WeakMap.)
+ */
+interface ReadonlyWeakMap<K extends WeakKey, V> {
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+}
+/** Render context passed to all writer functions. */
+export interface WordRenderContext {
+    /** Current part being rendered. */
+    readonly partName: PartName;
+    /** Security policy controlling raw XML, external targets, etc. */
+    readonly securityPolicy: WordSecurityPolicy;
+    /** ID generators (shared across all parts for a single document render). */
+    readonly ids: IdGenerators;
+    /** Raw XML output policy. If "reject", opaque content throws instead of being written. */
+    readonly rawXmlPolicy: "preserve" | "strip" | "reject";
+    /** Chart/ChartEx object → rId mapping. Populated by packager before rendering. */
+    readonly chartRIds: Map<object, string>;
+    /**
+     * Optional remap for image relationship IDs that the packager had to rewrite
+     * (e.g. when the model's image rId collided with a non-image relationship in
+     * the same .rels file). Writers that emit `r:embed` look up this map first
+     * and fall back to the original rId stored on the model. The map is keyed by
+     * the original (model-side) rId.
+     */
+    readonly imageRIdRemap: Map<string, string>;
+    /**
+     * External hyperlink object → rId mapping. The packager registers a
+     * relationship for each hyperlink with a `url` and stores the assigned rId
+     * here, keyed by the hyperlink object identity. The paragraph writer reads
+     * this when emitting `<w:hyperlink r:id="...">` so the model itself is
+     * never mutated.
+     */
+    readonly hyperlinkRIds: WeakMap<object, string>;
+    /**
+     * AltChunk object → rId mapping. Populated by the packager when registering
+     * the relationship for each `w:altChunk`. Renderers prefer this map over
+     * `AltChunk.rId` so the caller's model is never mutated, including when
+     * the altChunk is nested inside a table cell or SDT and was therefore not
+     * cloned by the shallow body copy.
+     */
+    readonly altChunkRIds: WeakMap<object, string>;
+}
+/** Create ID generators with given starting values. */
+export declare function createIdGenerators(startValues?: {
+    drawingId?: number;
+    sdtId?: number;
+    bookmarkId?: number;
+    docPrId?: number;
+    chartId?: number;
+    imagePartId?: number;
+}): IdGenerators;
+/** Create a default render context. */
+export declare function createRenderContext(options?: {
+    partName?: PartName;
+    securityPolicy?: WordSecurityPolicy;
+    chartRIds?: Map<object, string>;
+    imageRIdRemap?: Map<string, string>;
+    hyperlinkRIds?: WeakMap<object, string>;
+    altChunkRIds?: WeakMap<object, string>;
+    /**
+     * Pre-built ID generators. When provided, the caller is responsible for
+     * seeding them (e.g. with the maximum existing SDT id in the document so
+     * auto-assigned IDs don't collide with author-supplied ones).
+     */
+    ids?: IdGenerators;
+}): WordRenderContext;
+export {};

package/dist/types/modules/word/{writers → writer}/run-writer.d.ts

@@ -5,11 +5,20 @@
  */
 import type { XmlSink } from "../../xml/types.js";
 import type { RunProperties, Run, Shading, Border } from "../types.js";
+import type { RenderHelpers } from "./render-context.js";
 /** Render a single border element. */
 export declare function renderBorderElement(xml: XmlSink, tagName: string, border: Border): void;
 /** Render w:rPr (run properties). Element order follows ECMA-376 CT_RPr schema. */
 export declare function renderRunProperties(xml: XmlSink, rPr: RunProperties, insidePropertyChange?: boolean): void;
+/**
+ * Render the **contents** of a w:rPr element (without the w:rPr wrapper).
+ *
+ * Use this when you need to inject additional siblings (like w:ins/w:del for
+ * paragraph mark revisions) into the same w:rPr element. Otherwise prefer
+ * {@link renderRunProperties} which manages the wrapper for you.
+ */
+export declare function renderRunPropertiesContents(xml: XmlSink, rPr: RunProperties, insidePropertyChange?: boolean): void;
 /** Render w:shd element. */
 export declare function renderShading(xml: XmlSink, shd: Shading): void;
 /** Render a w:r element. */
-export declare function renderRun(xml: XmlSink, run: Run): void;
+export declare function renderRun(xml: XmlSink, run: Run, helpers?: RenderHelpers): void;

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

@@ -0,0 +1,25 @@
+/**
+ * DOCX Writers - Structured Document Tag (SDT) Properties
+ *
+ * This file intentionally only renders `<w:sdtPr>` — the property block — so
+ * it has no dependency on the block-level renderers (paragraph/table/run/
+ * nested SDT). Callers are responsible for opening `<w:sdt>` and
+ * `<w:sdtContent>` themselves and for dispatching child blocks using their
+ * own render functions, which keeps the writer module graph acyclic.
+ */
+import type { XmlSink } from "../../xml/types.js";
+import type { StructuredDocumentTag } from "../types.js";
+import type { WordRenderContext } from "./render-context.js";
+/**
+ * Render the `<w:sdt>` ↦ `<w:sdtPr>` block for a given SDT.
+ *
+ * Does not emit `<w:sdt>` itself nor `<w:sdtContent>` — that is the caller's
+ * responsibility. Designed so block-level renderers (table cell, header/
+ * footer, document body) can share the property emission logic without
+ * forming an import cycle through child-block dispatch.
+ *
+ * `ctx` may be undefined when called from a renderer that only owns a
+ * `RenderHelpers`. In that case we cannot draw an auto-id from the document
+ * id generator and will simply omit `<w:id>` if the model didn't supply one.
+ */
+export declare function renderSdtPr(xml: XmlSink, sdt: StructuredDocumentTag, ctx?: WordRenderContext): void;

package/dist/types/modules/word/writer/stream-buf.d.ts

@@ -0,0 +1,37 @@
+/**
+ * StreamBuf - Minimal Event-Driven Stream Buffer for DOCX Streaming
+ *
+ * A lightweight stream buffer that emits data events when written to.
+ * This is specifically designed for the streaming DOCX writer's needs:
+ * - Write StringBuf or Uint8Array data
+ * - Emit "data" events with Uint8Array chunks
+ * - Emit "finish" on end()
+ * - Support custom event listeners (once/on/emit)
+ *
+ * This is a word-module-local implementation to avoid depending on @excel/utils.
+ */
+import { EventEmitter } from "../../../utils/event-emitter.js";
+import type { StringBuf } from "./string-buf.js";
+interface StreamBufOptions {
+    bufSize?: number;
+}
+/**
+ * Minimal streaming buffer for piping XML data to ZIP compression.
+ * Extends EventEmitter for event-driven data flow.
+ */
+declare class StreamBuf extends EventEmitter {
+    private _ended;
+    constructor(_options?: StreamBufOptions);
+    /** Returns true if the stream is writable (not ended). */
+    get writable(): boolean;
+    /**
+     * Write data to the stream. Emits a "data" event with the bytes.
+     */
+    write(data: Uint8Array | string | StringBuf | ArrayBuffer | ArrayBufferView, _encoding?: string | ((...args: unknown[]) => unknown), callback?: (...args: unknown[]) => unknown): void;
+    /**
+     * End the stream. Emits "finish" event.
+     */
+    end(chunk?: Uint8Array | string | StringBuf | ArrayBuffer | ArrayBufferView, _encoding?: string, callback?: (...args: unknown[]) => unknown): void;
+}
+export { StreamBuf };
+export type { StreamBufOptions };