@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/section-partition-flatten.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Section partition (load) and flatten (save) for the single physical `w:body`.
+ *
+ * Evidence: ECMA-376-1 §11.3.10 (Main Document), §17.6 (section properties);
+ * transitional `wml.xsd` body / sectPr / CT_PPr.sectPr. Break paragraph belongs
+ * to the ending section. Non-final properties live on that paragraph; final
+ * properties are the trailing body-level `w:sectPr`.
+ *
+ * @private
+ */
+import { SectionPropertiesModel } from './section-properties-model';
+import { WordDocument } from './document';
+import { BlockContent, Paragraph } from './paragraph';
+import { OpenXmlElement } from '../../core/xml/index';
+/**
+ * One logical section after partition (internal blocks + page-setup source).
+ *
+ * @private
+ */
+export declare type SectionData = {
+    readonly items: BlockContent[];
+    /** Paragraph- or body-level section properties (XML or live model). */
+    readonly properties: SectionPropertiesModel | OpenXmlElement | undefined;
+    readonly isFinal: boolean;
+};
+/**
+ * Optional feature hook: materialize live section properties from `w:sectPr` XML.
+ * Installed by the sections feature so core never imports `SectionProperties`.
+ *
+ * @private
+ */
+export declare type SectionPropertiesParse = (element: OpenXmlElement) => SectionPropertiesModel | undefined;
+/**
+ * Optional feature hook: associate a live page-setup model with its owning document
+ * (headers/footers WeakMap bridges). Core never imports `SectionProperties`.
+ *
+ * @private
+ */
+export declare type SectionPropertiesAttached = (model: SectionPropertiesModel, document: WordDocument) => void;
+/**
+ * @private
+ */
+export declare function registerSectionPropertiesParse(parse: SectionPropertiesParse): void;
+/**
+ * @private
+ */
+export declare function resetSectionPropertiesParseForTests(): void;
+/**
+ * @private
+ */
+export declare function registerSectionPropertiesAttached(handler: SectionPropertiesAttached): void;
+/**
+ * @private
+ */
+export declare function resetSectionPropertiesAttachedForTests(): void;
+/**
+ * @private
+ * Notify the sections feature that a live page-setup model is attached to a document.
+ */
+export declare function notifySectionPropertiesAttached(model: SectionPropertiesModel | undefined, document: WordDocument): void;
+/**
+ * @private
+ * Materialize XML `w:sectPr` to a live model when the sections feature is registered.
+ */
+export declare function materializeSectionProperties(source: SectionPropertiesModel | OpenXmlElement | undefined): SectionPropertiesModel | OpenXmlElement | undefined;
+/**
+ * Resolve paragraph-level section break as model or preserved XML, if any.
+ *
+ * @private
+ */
+export declare function paragraphSectionBreakSource(paragraph: Paragraph): SectionPropertiesModel | OpenXmlElement | undefined;
+/**
+ * True when the paragraph closes a non-final section (has `w:pPr/w:sectPr`).
+ *
+ * @private
+ */
+export declare function paragraphClosesSection(paragraph: Paragraph): boolean;
+/**
+ * Partition ordered body blocks + trailing body-level sectPr into logical sections.
+ *
+ * Non-final sections close on a paragraph that carries section properties; that
+ * paragraph is included in the ending section. The final section uses
+ * `trailingSectPr` (may be undefined for an empty/default final).
+ *
+ * @private
+ */
+export declare function partitionBodyIntoSections(blocks: ReadonlyArray<BlockContent>, trailingSectPr: SectionPropertiesModel | OpenXmlElement | undefined): SectionData[];
+/**
+ * Attach page setup onto the last paragraph of a non-final section for serialize.
+ * Clears dual-hold on the paragraph so the section's pageSetup is the source.
+ *
+ * @private
+ */
+export declare function applyNonFinalSectionBreak(lastParagraph: Paragraph, pageSetup: SectionPropertiesModel | OpenXmlElement | undefined): void;
+/**
+ * Ensure a non-final section ends on a paragraph; append empty terminator if needed.
+ * Returns the paragraph that will carry section properties.
+ *
+ * @private
+ */
+export declare function ensureSectionTerminatorParagraph(items: BlockContent[]): Paragraph;
+/**
+ * Flatten logical sections into one ordered body-child list (no trailing body sectPr).
+ * Mutates non-final section stores only as needed to ensure terminator paragraphs and
+ * attach paragraph-level section properties from each section's pageSetup.
+ *
+ * Caller appends body-final sectPr from the last section separately.
+ *
+ * @private
+ */
+export declare function flattenSectionsToBodyBlocks(sections: ReadonlyArray<{
+    readonly listBlocks: () => ReadonlyArray<BlockContent>;
+    readonly pageSetup: SectionPropertiesModel | undefined;
+    /** Optional raw XML when pageSetup model is absent. */
+    readonly pageSetupXml?: OpenXmlElement | undefined;
+    readonly replaceItems?: (items: ReadonlyArray<BlockContent>) => void;
+    readonly isLast: boolean;
+}>): BlockContent[];
+/**
+ * Serialize page setup source to OpenXmlElement for body-final or paragraph sectPr.
+ *
+ * @private
+ */
+export declare function sectionPropertiesToOpenXml(source: SectionPropertiesModel | OpenXmlElement | undefined): OpenXmlElement | undefined;

package/src/features/document/section-partition-flatten.js

@@ -0,0 +1,217 @@
+import { Paragraph } from './paragraph';
+var sectionPropertiesParse;
+var sectionPropertiesAttached;
+/**
+ * @private
+ */
+export function registerSectionPropertiesParse(parse) {
+    sectionPropertiesParse = parse;
+}
+/**
+ * @private
+ */
+export function resetSectionPropertiesParseForTests() {
+    sectionPropertiesParse = undefined;
+}
+/**
+ * @private
+ */
+export function registerSectionPropertiesAttached(handler) {
+    sectionPropertiesAttached = handler;
+}
+/**
+ * @private
+ */
+export function resetSectionPropertiesAttachedForTests() {
+    sectionPropertiesAttached = undefined;
+}
+/**
+ * @private
+ * Notify the sections feature that a live page-setup model is attached to a document.
+ */
+export function notifySectionPropertiesAttached(model, document) {
+    if (model === undefined || sectionPropertiesAttached === undefined) {
+        return;
+    }
+    sectionPropertiesAttached(model, document);
+}
+/**
+ * @private
+ * Materialize XML `w:sectPr` to a live model when the sections feature is registered.
+ */
+export function materializeSectionProperties(source) {
+    if (source === undefined) {
+        return undefined;
+    }
+    if (typeof source.toOpenXml === 'function') {
+        return source;
+    }
+    if (sectionPropertiesParse === undefined) {
+        return source;
+    }
+    var parsed = sectionPropertiesParse(source);
+    return parsed !== undefined ? parsed : source;
+}
+/**
+ * Resolve paragraph-level section break as model or preserved XML, if any.
+ *
+ * @private
+ */
+export function paragraphSectionBreakSource(paragraph) {
+    var model = paragraph.sectionBreakPropertiesModel();
+    if (model !== undefined) {
+        return model;
+    }
+    return paragraph.sectionBreakSectPr();
+}
+/**
+ * True when the paragraph closes a non-final section (has `w:pPr/w:sectPr`).
+ *
+ * @private
+ */
+export function paragraphClosesSection(paragraph) {
+    return paragraphSectionBreakSource(paragraph) !== undefined;
+}
+/**
+ * Partition ordered body blocks + trailing body-level sectPr into logical sections.
+ *
+ * Non-final sections close on a paragraph that carries section properties; that
+ * paragraph is included in the ending section. The final section uses
+ * `trailingSectPr` (may be undefined for an empty/default final).
+ *
+ * @private
+ */
+export function partitionBodyIntoSections(blocks, trailingSectPr) {
+    var sections = [];
+    var current = [];
+    for (var i = 0; i < blocks.length; i += 1) {
+        var block = blocks[i];
+        current.push(block);
+        if (block.type === 'paragraph' && paragraphClosesSection(block.paragraph)) {
+            var props = paragraphSectionBreakSource(block.paragraph);
+            sections.push({
+                items: current,
+                properties: props,
+                isFinal: false,
+            });
+            current = [];
+        }
+    }
+    sections.push({
+        items: current,
+        properties: trailingSectPr,
+        isFinal: true,
+    });
+    // Invariant: at least one section (empty body → single final with optional props).
+    return sections;
+}
+/**
+ * Attach page setup onto the last paragraph of a non-final section for serialize.
+ * Clears dual-hold on the paragraph so the section's pageSetup is the source.
+ *
+ * @private
+ */
+export function applyNonFinalSectionBreak(lastParagraph, pageSetup) {
+    if (pageSetup === undefined) {
+        lastParagraph.replaceSectionBreakPropertiesModel(undefined);
+        lastParagraph.replaceSectionBreakSectPr(undefined);
+        return;
+    }
+    if (typeof pageSetup.toOpenXml === 'function') {
+        lastParagraph.replaceSectionBreakPropertiesModel(pageSetup);
+        return;
+    }
+    lastParagraph.replaceSectionBreakSectPr(pageSetup);
+}
+/**
+ * Ensure a non-final section ends on a paragraph; append empty terminator if needed.
+ * Returns the paragraph that will carry section properties.
+ *
+ * @private
+ */
+export function ensureSectionTerminatorParagraph(items) {
+    var last = items[items.length - 1];
+    if (last !== undefined && last.type === 'paragraph') {
+        return last.paragraph;
+    }
+    var paragraph = new Paragraph(undefined);
+    items.push({ type: 'paragraph', paragraph: paragraph });
+    return paragraph;
+}
+/**
+ * Flatten logical sections into one ordered body-child list (no trailing body sectPr).
+ * Mutates non-final section stores only as needed to ensure terminator paragraphs and
+ * attach paragraph-level section properties from each section's pageSetup.
+ *
+ * Caller appends body-final sectPr from the last section separately.
+ *
+ * @private
+ */
+export function flattenSectionsToBodyBlocks(sections) {
+    var out = [];
+    for (var i = 0; i < sections.length; i += 1) {
+        var section = sections[i];
+        var isFinal = section.isLast;
+        var raw = section.listBlocks().slice();
+        var setup = section.pageSetup !== undefined
+            ? section.pageSetup
+            : section.pageSetupXml;
+        if (!isFinal) {
+            var terminator = ensureSectionTerminatorParagraph(raw);
+            // When neither model nor XML page setup is available (sections feature
+            // not registered), leave existing paragraph-level sectPr dual-hold alone.
+            if (setup !== undefined || section.pageSetup !== undefined || section.pageSetupXml !== undefined) {
+                applyNonFinalSectionBreak(terminator, setup);
+            }
+            else if (!paragraphClosesSection(terminator)) {
+                // Terminator was just appended (section ended on non-paragraph) with
+                // no properties to attach — still a valid empty closer; properties
+                // remain absent (Word may treat as default section mark).
+            }
+            if (section.replaceItems !== undefined) {
+                section.replaceItems(raw);
+            }
+        }
+        else {
+            // Final section must not leave paragraph-level sectPr on its last paragraph
+            // from a prior dual-hold authoring path when pageSetup is body-level only.
+            // Leave any internal paragraph breaks that intentionally closed earlier
+            // non-final sections alone — those live in prior sections after partition.
+            // Clear break on last paragraph only if it still holds a break that mirrors
+            // final props (authoring via lastSection alone should not emit pPr sectPr).
+            // Spec: final properties are body-level only.
+            var last = raw[raw.length - 1];
+            if (last !== undefined && last.type === 'paragraph') {
+                // Do not strip if this paragraph was itself a mid-document break —
+                // final section items never include those after correct partition.
+                // Authoring bridge may still put sectionBreak on a final-section
+                // paragraph; strip so body-level sectPr is sole final source.
+                if (paragraphClosesSection(last.paragraph)) {
+                    last.paragraph.replaceSectionBreakPropertiesModel(undefined);
+                    last.paragraph.replaceSectionBreakSectPr(undefined);
+                }
+            }
+            if (section.replaceItems !== undefined) {
+                section.replaceItems(raw);
+            }
+        }
+        for (var j = 0; j < raw.length; j += 1) {
+            out.push(raw[j]);
+        }
+    }
+    return out;
+}
+/**
+ * Serialize page setup source to OpenXmlElement for body-final or paragraph sectPr.
+ *
+ * @private
+ */
+export function sectionPropertiesToOpenXml(source) {
+    if (source === undefined) {
+        return undefined;
+    }
+    if (typeof source.toOpenXml === 'function') {
+        return source.toOpenXml();
+    }
+    return source;
+}

package/src/features/document/section-properties-model.d.ts

@@ -0,0 +1,13 @@
+import { OpenXmlElement } from '../../core/xml/index';
+/**
+ * Duck-typed body-final / paragraph section-break model from the optional sections
+ * feature. Core stores the object without importing `PageSetup`.
+ *
+ * Internal serialization boundary only — never returned as the public type of
+ * {@link Section.pageSetup}.
+ *
+ * @private
+ */
+export interface SectionPropertiesModel {
+    toOpenXml(): OpenXmlElement;
+}

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

@@ -0,0 +1,93 @@
+import { Body } from './body';
+import { HeadersFooters } from './headers-footers';
+import { BlockContentControlCollection, ParagraphCollection, TableCollection } from './typed-body-collections';
+import { BlockContent } from './paragraph';
+import { PageSetup } from './page-setup';
+import { SectionPropertiesModel } from './section-properties-model';
+import { WordDocument } from './document';
+/**
+ * One document section: body story, page setup, and header/footer slots.
+ *
+ * Main-story entry is {@link Section.body}.{@link Body.items}. Typed views
+ * ({@link Section.paragraphs}, {@link Section.tables},
+ * {@link Section.blockContentControls}) filter the same collection.
+ *
+ * Public {@link pageSetup} is always a live {@link PageSetup} when the sections
+ * feature is registered. Core stores the value as
+ * {@link SectionPropertiesModel} without importing the feature class.
+ *
+ * @public
+ */
+export declare class Section {
+    private readonly bodyInstance;
+    private readonly paragraphsInstance;
+    private readonly tablesInstance;
+    private readonly blockContentControlsInstance;
+    private readonly headersFootersInstance;
+    private pageSetupModel;
+    private document;
+    /**
+     * @private
+     */
+    constructor(document: WordDocument | undefined, blocks?: ReadonlyArray<BlockContent>, pageSetup?: SectionPropertiesModel);
+    /**
+     * Section body — sole collection owner for this section's main-story items.
+     */
+    readonly body: Body;
+    /**
+     * Paragraphs in this section body (filtered view over {@link Body.items}).
+     */
+    readonly paragraphs: ParagraphCollection;
+    /**
+     * Tables in this section body (filtered view). Empty until the tables
+     * feature registers typed-collection hooks.
+     */
+    readonly tables: TableCollection;
+    /**
+     * Block content controls in this section body (filtered view).
+     */
+    readonly blockContentControls: BlockContentControlCollection;
+    /**
+     * Always-present header/footer slots for this section.
+     *
+     * Six getters never return `undefined`. Empty slots expose zero child items
+     * until content is written; package parts are created lazily.
+     */
+    readonly headersFooters: HeadersFooters;
+    /**
+     * Live section page setup (`w:sectPr` model).
+     *
+     * Always returns the same {@link PageSetup} instance while the sections
+     * feature is registered. Never typed as {@link SectionPropertiesModel}.
+     * Serialization stays on the internal model bridge
+     * ({@link internalPageSetupModel}).
+     *
+     * @public
+     */
+    readonly pageSetup: PageSetup;
+    /**
+     * @private
+     * Internal dual-hold / serialize model. Prefer {@link pageSetup} publicly.
+     */
+    internalPageSetupModel(): SectionPropertiesModel | undefined;
+    /**
+     * @private
+     * Attach or clear the live page-setup model. Clearing re-seeds a default
+     * when the sections feature seed hook is registered so `pageSetup` stays
+     * defined for always-on section properties.
+     */
+    setPageSetup(value: SectionPropertiesModel | undefined): void;
+    /**
+     * @private
+     */
+    owningDocument(): WordDocument;
+    /**
+     * @private
+     */
+    bindDocument(document: WordDocument): void;
+    /**
+     * @private
+     * Refresh typed collection index properties after raw-store load mutations.
+     */
+    syncCollections(): void;
+}

package/src/features/document/section.js

@@ -0,0 +1,178 @@
+import { Body } from './body';
+import { HeadersFooters } from './headers-footers';
+import { createBlockContentControlCollection, createTableCollection, ParagraphCollection, } from './typed-body-collections';
+import { Paragraph } from './paragraph';
+import { currentSectionPageSetupSeed } from './sections';
+import { notifySectionPropertiesAttached } from './section-partition-flatten';
+import { DetachedObjectError } from '../../core/errors/docx-error';
+/**
+ * One document section: body story, page setup, and header/footer slots.
+ *
+ * Main-story entry is {@link Section.body}.{@link Body.items}. Typed views
+ * ({@link Section.paragraphs}, {@link Section.tables},
+ * {@link Section.blockContentControls}) filter the same collection.
+ *
+ * Public {@link pageSetup} is always a live {@link PageSetup} when the sections
+ * feature is registered. Core stores the value as
+ * {@link SectionPropertiesModel} without importing the feature class.
+ *
+ * @public
+ */
+var Section = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function Section(document, blocks, pageSetup) {
+        if (blocks === void 0) { blocks = []; }
+        this.document = document;
+        this.bodyInstance = new Body(document, blocks, this);
+        this.pageSetupModel = pageSetup;
+        if (this.pageSetupModel === undefined) {
+            var seed = currentSectionPageSetupSeed();
+            if (seed !== undefined) {
+                this.pageSetupModel = seed();
+            }
+        }
+        this.headersFootersInstance = new HeadersFooters(this);
+        this.paragraphsInstance = new ParagraphCollection(this.bodyInstance.items, function () { return new Paragraph(undefined); });
+        this.tablesInstance = createTableCollection(this.bodyInstance.items);
+        this.blockContentControlsInstance = createBlockContentControlCollection(this.bodyInstance.items);
+    }
+    Object.defineProperty(Section.prototype, "body", {
+        /**
+         * Section body — sole collection owner for this section's main-story items.
+         */
+        get: function () {
+            return this.bodyInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Section.prototype, "paragraphs", {
+        /**
+         * Paragraphs in this section body (filtered view over {@link Body.items}).
+         */
+        get: function () {
+            return this.paragraphsInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Section.prototype, "tables", {
+        /**
+         * Tables in this section body (filtered view). Empty until the tables
+         * feature registers typed-collection hooks.
+         */
+        get: function () {
+            return this.tablesInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Section.prototype, "blockContentControls", {
+        /**
+         * Block content controls in this section body (filtered view).
+         */
+        get: function () {
+            return this.blockContentControlsInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Section.prototype, "headersFooters", {
+        /**
+         * Always-present header/footer slots for this section.
+         *
+         * Six getters never return `undefined`. Empty slots expose zero child items
+         * until content is written; package parts are created lazily.
+         */
+        get: function () {
+            return this.headersFootersInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Section.prototype, "pageSetup", {
+        /**
+         * Live section page setup (`w:sectPr` model).
+         *
+         * Always returns the same {@link PageSetup} instance while the sections
+         * feature is registered. Never typed as {@link SectionPropertiesModel}.
+         * Serialization stays on the internal model bridge
+         * ({@link internalPageSetupModel}).
+         *
+         * @public
+         */
+        get: function () {
+            if (this.pageSetupModel === undefined) {
+                var seed = currentSectionPageSetupSeed();
+                if (seed !== undefined) {
+                    this.pageSetupModel = seed();
+                }
+            }
+            if (this.pageSetupModel === undefined) {
+                throw new DetachedObjectError('Section.pageSetup requires the sections feature (import @syncfusion/ej2-docx or @syncfusion/ej2-docx/sections)');
+            }
+            // Feature PageSetup implements the public PageSetup contract and the
+            // internal SectionPropertiesModel serialization boundary. Core cannot
+            // import the feature class, so identity is asserted through unknown.
+            return this.pageSetupModel;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Internal dual-hold / serialize model. Prefer {@link pageSetup} publicly.
+     */
+    Section.prototype.internalPageSetupModel = function () {
+        return this.pageSetupModel;
+    };
+    /**
+     * @private
+     * Attach or clear the live page-setup model. Clearing re-seeds a default
+     * when the sections feature seed hook is registered so `pageSetup` stays
+     * defined for always-on section properties.
+     */
+    Section.prototype.setPageSetup = function (value) {
+        if (value !== undefined) {
+            this.pageSetupModel = value;
+            return;
+        }
+        var seed = currentSectionPageSetupSeed();
+        this.pageSetupModel = seed !== undefined ? seed() : undefined;
+    };
+    /**
+     * @private
+     */
+    Section.prototype.owningDocument = function () {
+        if (this.document === undefined) {
+            throw new DetachedObjectError('Section is not attached to a document');
+        }
+        return this.document;
+    };
+    /**
+     * @private
+     */
+    Section.prototype.bindDocument = function (document) {
+        this.headersFootersInstance.bindSection(this);
+        this.document = document;
+        this.bodyInstance.setOwningDocument(document);
+        this.bodyInstance.setOwningSection(this);
+        if (this.pageSetupModel !== undefined) {
+            notifySectionPropertiesAttached(this.pageSetupModel, document);
+        }
+    };
+    /**
+     * @private
+     * Refresh typed collection index properties after raw-store load mutations.
+     */
+    Section.prototype.syncCollections = function () {
+        this.bodyInstance.items.syncFromHost();
+        this.paragraphsInstance.syncFromHost();
+        this.tablesInstance.syncFromHost();
+        this.blockContentControlsInstance.syncFromHost();
+    };
+    return Section;
+}());
+export { Section };