@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/document.d.ts

@@ -0,0 +1,410 @@
+import { OpcPackage } from '../../core/opc/index';
+import { OpenXmlElement } from '../../core/xml/index';
+import { FeatureId } from '../../core/registry/feature-registry';
+import { FeaturePackagePart } from './feature-package-part';
+import { FeaturePackageLevelPart } from './feature-package-level-part';
+import { FeatureMultiPackagePart } from './feature-multi-package-part';
+import { ResourceLimitOverrides } from '../../core/security/limits';
+import { AltChunkAnchor } from './alt-chunk';
+import { Body } from './body';
+import { LoadOptions } from './load-options';
+import { BlockContent, Paragraph } from './paragraph';
+import { Section } from './section';
+import { Sections } from './sections';
+import { SectionPropertiesModel } from './section-properties-model';
+/**
+ * @private
+ * Feature-owned package part state (single-, multi-, or package-level).
+ */
+export declare type FeaturePartState = FeaturePackagePart | FeatureMultiPackagePart | FeaturePackageLevelPart;
+/**
+ * In-memory WordprocessingML document backed by an OPC package.
+ *
+ * Load via {@link WordDocument.open} / {@link WordDocument.openSync} from bytes or base64,
+ * or {@link WordDocument.openAsync} from a browser `File` / `Blob`. There is no filesystem-path open.
+ * Serialize with {@link WordDocument.save} / {@link WordDocument.saveSync} to bytes, a browser
+ * download file name, or base64. There is no Node.js filesystem write.
+ *
+ * Main-story entry is {@link Document.sections} (each {@link Section.body}).
+ *
+ * @public
+ */
+export declare class WordDocument {
+    private pkg;
+    private rootExtra;
+    private background;
+    /** Ordered sections — sole main-story owners (TASK-8074). */
+    private readonly sectionsInstance;
+    /**
+     * Body-final `w:sectPr` as preserved OOXML when the sections feature has not
+     * attached a live {@link SectionPropertiesModel}.
+     */
+    private sectPr;
+    /**
+     * Live body-final section properties when the sections feature owns the model.
+     * Preferred over {@link sectPr} when both would otherwise be present.
+     */
+    private finalSectionModel;
+    private featureParts;
+    private constructor();
+    /**
+     * Minimal Transitional package with one empty paragraph (`w:p` in `w:body`).
+     *
+     * Builds the in-memory document and package scaffold directly — does not
+     * serialize then re-parse as the sole create path.
+     */
+    static create(): WordDocument;
+    /**
+     * @private
+     */
+    static fromPackage(pkg: OpcPackage, limits?: ResourceLimitOverrides): WordDocument;
+    /**
+     * @private
+     * Partition body blocks into logical sections and attach them (TASK-8075).
+     * Non-final section properties stay dual-held internally on the closing
+     * paragraph and {@link Section.pageSetup} for flatten/serialize; final
+     * properties dual-hold body-final model / last pageSetup.
+     *
+     * Also used after dual-hold authoring (`setParagraphSectionBreak`) so
+     * `Document.sections` matches paragraph break topology before save.
+     */
+    private hydratePartitionedSections;
+    /**
+     * @private
+     * Rebuild {@link Document.sections} from current body blocks + dual-hold
+     * paragraph/body section properties (TASK-8075/8076 authoring path).
+     *
+     * Call after `setParagraphSectionBreak` so non-final pageSetup lives on its
+     * own section and flatten emits paragraph-level + body-final `w:sectPr`.
+     */
+    repartitionFromBodyBlocks(): void;
+    /**
+     * Load a `.docx` package from bytes.
+     *
+     * Reuses {@link WordDocument.openSync} parsing — returns `WordDocument` directly
+     * (not a `Promise`). Prefer {@link WordDocument.openAsync} when a Promise is required.
+     *
+     * @param data - OPC ZIP payload (`Uint8Array` or `ArrayBuffer`).
+     * @param options - Optional {@link LoadOptions.limits} overrides.
+     * @throws {@link PackageError} for ZIP/OPC failures.
+     * @throws {@link SecurityError} when a resource limit is exceeded.
+     * @throws {@link XmlError} for malformed Main Document XML.
+     */
+    static open(data: Uint8Array | ArrayBuffer, options?: LoadOptions): WordDocument;
+    /**
+     * Open a `.docx` package from a base64 string. Requires `options.format: 'base64'`.
+     *
+     * Optional `data:...;base64,` prefixes are stripped.
+     *
+     * @param base64 - Base64-encoded OPC ZIP payload.
+     * @param options - Load options including `format: 'base64'`.
+     * @throws {@link InvalidArgumentError} when the payload is not valid base64
+     */
+    static open(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): WordDocument;
+    /**
+     * Open a `.docx` package asynchronously (Promise form of {@link WordDocument.open}).
+     *
+     * Parsing still runs via {@link WordDocument.openSync}; the Promise only wraps
+     * completion / rejection. Use this when call sites require a Promise API.
+     *
+     * @public
+     */
+    static openAsync(data: Uint8Array | ArrayBuffer, options?: LoadOptions): Promise<WordDocument>;
+    /**
+     * Open a browser `File` or `Blob` (file-input / drag-drop). Same input shape the
+     * PDF library uses for an existing document: bytes the page already has, not a
+     * filesystem path.
+     *
+     * @public
+     */
+    static openAsync(file: {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }, options?: LoadOptions): Promise<WordDocument>;
+    /**
+     * @public
+     */
+    static openAsync(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): Promise<WordDocument>;
+    /**
+     * Open a `.docx` package from bytes synchronously.
+     *
+     * @param data - OPC ZIP payload (`Uint8Array` or `ArrayBuffer`).
+     * @param options - Optional {@link LoadOptions.limits} overrides.
+     */
+    static openSync(data: Uint8Array | ArrayBuffer, options?: LoadOptions): WordDocument;
+    /**
+     * Open a `.docx` package from a base64 string synchronously. Requires `options.format: 'base64'`.
+     *
+     * @param base64 - Base64-encoded OPC ZIP payload.
+     * @param options - Load options including `format: 'base64'`.
+     */
+    static openSync(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): WordDocument;
+    /**
+     * Alias of {@link WordDocument.open} (legacy / DocIO-aligned `load` naming).
+     *
+     * @public
+     */
+    static load(data: Uint8Array | ArrayBuffer, options?: LoadOptions): WordDocument;
+    /**
+     * @public
+     */
+    static load(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): WordDocument;
+    /**
+     * Alias of {@link WordDocument.openAsync}. Browser file input: pass the picked `File`.
+     * There is no filesystem-path overload.
+     *
+     * @public
+     */
+    static loadAsync(data: Uint8Array | ArrayBuffer, options?: LoadOptions): Promise<WordDocument>;
+    /**
+     * @public
+     */
+    static loadAsync(file: {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    }, options?: LoadOptions): Promise<WordDocument>;
+    /**
+     * @public
+     */
+    static loadAsync(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): Promise<WordDocument>;
+    /**
+     * Alias of {@link WordDocument.openSync} (legacy / DocIO-aligned `loadSync` naming).
+     *
+     * @public
+     */
+    static loadSync(data: Uint8Array | ArrayBuffer, options?: LoadOptions): WordDocument;
+    /**
+     * @public
+     */
+    static loadSync(base64: string, options: LoadOptions & {
+        format: 'base64';
+    }): WordDocument;
+    /**
+     * Ordered document sections. Sole main-story entry (API-RULES / TASK-8074).
+     *
+     * @public
+     */
+    readonly sections: Sections;
+    /**
+     * Last section in {@link WordDocument.sections}.
+     *
+     * Equivalent to `sections[sections.count - 1]`. The document always has at
+     * least one section.
+     *
+     * @public
+     */
+    readonly lastSection: Section;
+    /**
+     * Last block-level paragraph of {@link WordDocument.lastSection}.
+     *
+     * Does not walk paragraphs nested in tables or text boxes. Authored
+     * documents always have at least one body paragraph per section.
+     *
+     * @throws DetachedObjectError when the last section has no block-level
+     * paragraph (malformed loaded package).
+     *
+     * @public
+     */
+    readonly lastParagraph: Paragraph;
+    /**
+     * First section body — convenience bridge matching create-path documents
+     * (single section) and public samples that use `doc.body`.
+     *
+     * Prefer {@link WordDocument.sections} for multi-section documents.
+     *
+     * @public
+     */
+    readonly body: Body;
+    /**
+     * Appends a paragraph to {@link WordDocument.body}.
+     *
+     * Style ids route through {@link Paragraph.applyStyle} so built-in catalog
+     * resolution and validation run on assignment.
+     *
+     * @param options - Optional paragraph style id and/or initial text.
+     * @returns The appended {@link Paragraph}.
+     *
+     * @public
+     */
+    appendParagraph(options?: {
+        readonly style?: string;
+        readonly text?: string;
+    }): Paragraph;
+    /**
+     * Appends a new section after the current last section.
+     *
+     * Thin delegate over {@link Sections.add}. Clones page setup from the
+     * previous last section when the sections feature has registered a clone
+     * hook; otherwise seeds a default letter page setup when a seed hook is
+     * registered.
+     *
+     * @returns The new {@link Section}.
+     *
+     * @public
+     */
+    addSection(): Section;
+    /**
+     * @private
+     */
+    assertAttachedParagraph(target: Paragraph): void;
+    /**
+     * @private
+     */
+    owningDocument(): this;
+    /**
+     * Modeled `w:altChunk` anchors in the Main Document body.
+     *
+     * @private
+     */
+    readonly altChunks: ReadonlyArray<AltChunkAnchor>;
+    /**
+     * @private
+     * First section body (internal feature/load bridges).
+     */
+    firstSectionBody(): Body;
+    /**
+     * @private
+     */
+    listParagraphs(): ReadonlyArray<Paragraph>;
+    /**
+     * @private
+     * Flattened internal store across sections.
+     */
+    listBlocks(): ReadonlyArray<BlockContent>;
+    /**
+     * @private
+     */
+    appendBlock(block: BlockContent): void;
+    /**
+     * Inserts a body item at index (`0…count` inclusive) on the first section body.
+     *
+     * @private
+     */
+    insertBlockAt(index: number, block: BlockContent): void;
+    /**
+     * Inserts an empty paragraph at a body item index (`0…count` inclusive).
+     *
+     * @private
+     */
+    insertParagraphAtBlockIndex(index: number): Paragraph;
+    /**
+     * @private
+     */
+    insertParagraph(index: number): Paragraph;
+    /**
+     * @private
+     */
+    removeParagraph(paragraph: Paragraph): void;
+    /**
+     * Removes the body item at `index` (`0…count-1`) on the first section body.
+     *
+     * @private
+     */
+    removeBlockAt(index: number): void;
+    /**
+     * Advanced L3 hatch: Main Document `w:document` tree (API-RULES R5.4).
+     * Unstable; prefer semantic properties and `save` / `saveSync`.
+     *
+     * Always flattens section bodies into one physical `w:body` (TASK-8075/8076).
+     *
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+    /**
+     * Preserved `w:document/w:background` subtree from load, if any.
+     *
+     * @private
+     */
+    preservedBackground(): OpenXmlElement | undefined;
+    /**
+     * @private
+     * Body-final `w:sectPr`, when present.
+     * Serializes a live section-properties model when the sections feature owns it;
+     * otherwise returns preserved OOXML from load / XML write-back.
+     */
+    bodySectPr(): OpenXmlElement | undefined;
+    /**
+     * @private
+     * Replace body-final `w:sectPr` as preserved OOXML.
+     * Clears any live section-properties model (XML becomes source of truth again).
+     */
+    replaceBodySectPr(value: OpenXmlElement | undefined): void;
+    /**
+     * @private
+     * Live body-final section properties model (sections feature), if any.
+     */
+    finalSectionPropertiesModel(): SectionPropertiesModel | undefined;
+    /**
+     * @private
+     * Attach or clear the live body-final section properties model.
+     * When set, clears preserved `w:sectPr` XML so the model is the sole source of truth.
+     * Also seeds {@link Section.pageSetup} on the last section (TASK-8074 dual-hold).
+     */
+    replaceFinalSectionPropertiesModel(value: SectionPropertiesModel | undefined): void;
+    /**
+     * @private
+     */
+    featurePart(id: FeatureId): FeaturePartState | undefined;
+    /**
+     * @private
+     */
+    setFeaturePart(id: FeatureId, part: FeaturePartState): void;
+    /**
+     * @private
+     */
+    opcPackage(): OpcPackage;
+    /**
+     * Serialize the OPC package to `.docx` bytes. Unmodified extra parts keep their payload bytes.
+     */
+    saveSync(): Uint8Array;
+    /**
+     * Serialize the OPC package to a base64 string.
+     *
+     * @param options - Must include `format: 'base64'`.
+     */
+    saveSync(options: {
+        format: 'base64';
+    }): string;
+    /**
+     * @private
+     * Shared package serialization used by `saveSync` overloads and async `save`.
+     */
+    private saveSyncBytes;
+    /**
+     * Serialize the package to bytes. Resolves with the same result as {@link WordDocument.saveSync}.
+     */
+    save(): Promise<Uint8Array>;
+    /**
+     * Save the document under a file name by triggering a browser download.
+     *
+     * Matches the PDF library `save(filename)` pattern (`Blob` + anchor click).
+     * Directory segments are stripped (`./out/report.docx` → `report.docx`).
+     * This method does not import Node.js `fs` — a browser bundle must not
+     * touch the filesystem. In Node.js, call parameterless {@link WordDocument.save}
+     * or {@link WordDocument.saveSync} and write the bytes with the host's own I/O.
+     *
+     * @param fileName - Browser download file name (for example `Output.docx`).
+     * @throws InvalidArgumentError when `fileName` is missing or empty
+     * @throws IoError when no browser document is available to start the download
+     */
+    save(filePath: string): Promise<void>;
+    /**
+     * Serialize the package to a base64 string.
+     *
+     * @param options - Must include `format: 'base64'`.
+     */
+    save(options: {
+        format: 'base64';
+    }): Promise<string>;
+}
+export { Body } from './body';
+/** @public Compatibility alias for {@link WordDocument}. */
+export declare type Document = WordDocument;