@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/headers-footers/index.d.ts

@@ -0,0 +1,506 @@
+import { BodyItem } from '../document/body-item';
+import { WordDocument } from '../document/document';
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { BlockContent, Paragraph } from '../document/paragraph';
+import { OpcRelationship, RelationshipId } from '../../core/opc/relationships';
+import { OpcPackage } from '../../core/opc/package';
+import { PartName } from '../../core/opc/part-name';
+import { OpenXmlElement } from '../../core/xml/index';
+import { HeaderFooterReferenceType, PageSetup } from '../sections/index';
+import { HeaderFooter, HeaderFooterKind } from '../document/headers-footers';
+/** @public Compat alias — prefer HeaderFooter. */
+export declare type Header = HeaderFooter;
+/** @public Compat alias — prefer HeaderFooter. */
+export declare type Footer = HeaderFooter;
+/** @public Compat value alias for instanceof / legacy callers. */
+export declare const Header: typeof HeaderFooter;
+/** @public Compat value alias for instanceof / legacy callers. */
+export declare const Footer: typeof HeaderFooter;
+export { HeaderFooter, HeaderFooterKind };
+/**
+ * @private
+ * Transitional header relationship (ECMA-376-4 §9.2.8). */
+export declare const HEADER_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+/**
+ * @private
+ * Transitional footer relationship (ECMA-376-4 §9.2.7). */
+export declare const FOOTER_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+/**
+ * @private
+ * Strict header relationship (ECMA-376-1 §11.3.6). */
+export declare const STRICT_HEADER_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/header";
+/**
+ * @private
+ * Strict footer relationship (ECMA-376-1 §11.3.9). */
+export declare const STRICT_FOOTER_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/footer";
+/**
+ * @private
+ * ECMA-376-1 §11.3.6 Header part content type. */
+export declare const HEADER_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml";
+/**
+ * @private
+ * ECMA-376-1 §11.3.9 Footer part content type. */
+export declare const FOOTER_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml";
+/** Header vs footer part kind for catalog listing.
+ */
+export declare type HeaderFooterType = 'header' | 'footer';
+interface LoadedPart {
+    readonly partName: PartName;
+    readonly relationshipId: RelationshipId;
+    readonly relationshipType: string;
+    readonly kind: HeaderFooterType;
+    readonly rootExtra: Pick<OpenXmlElement, 'attributes' | 'namespaceDeclarations'>;
+    blocks: BlockContent[];
+    dirty: boolean;
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * In-memory header and footer parts linked from the Main Document.
+ * @private
+ */
+export declare class HeadersFootersCatalog implements FeatureMultiPackagePart {
+    private readonly entries;
+    private readonly byRelationshipId;
+    private catalogDirty;
+    private boundDocument;
+    /**
+     * @private
+     */
+    constructor(entries: Map<PartName, LoadedPart>);
+    /**
+     * Bind this catalog to a live document so paragraph owners can resolve.
+     * Re-attaches existing paragraph blocks to entry-scoped owners.
+     * @private
+     */
+    bindDocument(document: WordDocument): void;
+    /**
+     * @private
+     */
+    entryForRelationship(relationshipId: string): LoadedPart | undefined;
+    private requireBoundDocument;
+    private requireEntry;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    applyToPackage(pkg: OpcPackage, mainPartName: PartName): OpcPackage;
+    /**
+     * @private
+     */
+    ensureDefaultPart(kind: HeaderFooterType, section: PageSetup, usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): {
+        entry: LoadedPart;
+        relationshipId: string;
+    };
+    /**
+     * @private
+     */
+    ensurePart(kind: HeaderFooterType, section: PageSetup, refType: HeaderFooterReferenceType, usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): {
+        entry: LoadedPart;
+        relationshipId: string;
+    };
+    /**
+     * @private
+   * Whether a header or footer relationship id is loaded in this catalog. */
+    hasRelationship(relationshipId: string): boolean;
+    /**
+     * Relationship ids for loaded parts of the given kind, in catalog order.
+     * @private
+     */
+    relationshipIds(kind: HeaderFooterType): ReadonlyArray<string>;
+    /**
+     * Body items for a header/footer part by relationship id (paragraphs, tables,
+     * block content controls, residuals), in document order.
+     *
+     * Empty when the relationship is missing. When the catalog is document-bound,
+     * paragraphs and feature blocks are attached for mutation.
+     * @private
+     */
+    itemsForRelationship(relationshipId: string): ReadonlyArray<BodyItem>;
+    /**
+     * Modeled paragraphs for a header/footer part by relationship id.
+     *
+     * Empty when the relationship is missing or has no paragraph blocks.
+     * When the catalog is document-bound, paragraphs are attached for mutation.
+     * @private
+     */
+    paragraphsForRelationship(relationshipId: string): ReadonlyArray<Paragraph>;
+    /**
+     * @private
+     */
+    setSimpleText(entry: LoadedPart, text: string): void;
+    /**
+     * Replace the body of a loaded part with a single plain-text paragraph.
+     *
+     * Clears any prior rich body (multiple paragraphs, tables, opaque blocks).
+     *
+     * @throws DocxError `content/invalid-header-footer-reference` when the id is unknown.
+     * @private
+     */
+    setSimpleTextForRelationship(relationshipId: string, text: string): void;
+    /**
+     * Insert a body item at `index` in a header/footer part (`0…length` inclusive).
+     *
+     * Attaches paragraphs and feature blocks when the catalog is document-bound.
+     * Returns the same `item` reference for chaining.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError when the relationship id is unknown or the catalog is unbound.
+     * @private
+     */
+    insertBodyItemAtForRelationship(relationshipId: string, index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove the body item at `index` in a header/footer part (`0…length-1`).
+     * Paragraphs detach; feature blocks may release content.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError when the relationship id is unknown.
+     * @private
+     */
+    removeBodyItemAtForRelationship(relationshipId: string, index: number): void;
+    /**
+     * Remove a body item from a header/footer part by collection or payload identity.
+     *
+     * @throws DetachedObjectError when the item is not in the part.
+     * @throws DocxError when the relationship id is unknown.
+     * @private
+     */
+    removeBodyItemForRelationship(relationshipId: string, item: BodyItem): void;
+    /**
+     * Append a paragraph to a header/footer part body.
+     *
+     * @param options - Optional style id and/or initial text (mirrors {@link Body.appendParagraph}).
+     * @throws DocxError when the relationship id is unknown or the catalog is unbound.
+     * @private
+     */
+    appendParagraphForRelationship(relationshipId: string, options?: {
+        readonly style?: string;
+        readonly text?: string;
+    }): Paragraph;
+    /**
+     * Insert an empty paragraph among existing paragraphs of a part.
+     * Opaque / non-paragraph siblings keep their relative places.
+     *
+     * @param index - Index in the paragraph list, `0…length` inclusive.
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError when the relationship id is unknown or the catalog is unbound.
+     * @private
+     */
+    insertParagraphForRelationship(relationshipId: string, index: number): Paragraph;
+    /**
+     * Remove a paragraph from a header/footer part. Further mutation throws {@link DetachedObjectError}.
+     *
+     * @throws DetachedObjectError when the paragraph is not in the part.
+     * @throws DocxError when the relationship id is unknown.
+     * @private
+     */
+    removeParagraphForRelationship(relationshipId: string, paragraph: Paragraph): void;
+    /**
+     * Remove all body blocks from a header/footer part (empty `w:hdr` / `w:ftr`).
+     *
+     * @throws DocxError when the relationship id is unknown.
+     * @private
+     */
+    clearForRelationship(relationshipId: string): void;
+    /**
+     * @private
+     */
+    textForRelationship(relationshipId: string | undefined): string | undefined;
+    /**
+     * True when two body items refer to the same payload
+     * (paragraph instance, feature value, or opaque XML node).
+     */
+    private publicBodyItemsEqual;
+    private storeBlocksEqual;
+}
+/**
+ * Headers and footers catalog for a document.
+ *
+ * On a loaded package this is the catalog built from header/footer parts.
+ * On a newly authored document there may be no header/footer parts yet, so this
+ * function attaches an empty catalog on first use when the feature is registered.
+ *
+ * Accepts catalogs from either the main entry graph or `@syncfusion/ej2-docx/headers-footers`
+ * (duplicate class identity across published chunks).
+ *
+ * @throws DocxError `feature/not-registered` when the module was not registered.
+ * @private
+ */
+export declare function headersFootersFor(document: WordDocument): HeadersFootersCatalog;
+/**
+ * Live {@link HeaderFooter} views for every loaded header part, in catalog order.
+ * @private
+ */
+export declare function headersInDocument(document: WordDocument): ReadonlyArray<HeaderFooter>;
+/**
+ * Live {@link HeaderFooter} views for every loaded footer part, in catalog order.
+ * @private
+ */
+export declare function footersInDocument(document: WordDocument): ReadonlyArray<HeaderFooter>;
+/**
+ * Live header linked from a section's `w:headerReference`, when present and loaded.
+ * @private
+ */
+export declare function headerForSection(document: WordDocument, section: PageSetup, refType?: HeaderFooterReferenceType): HeaderFooter | undefined;
+/**
+ * Live footer linked from a section's `w:footerReference`, when present and loaded.
+ * @private
+ */
+export declare function footerForSection(document: WordDocument, section: PageSetup, refType?: HeaderFooterReferenceType): HeaderFooter | undefined;
+/**
+ * Default header for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function defaultHeader(document: WordDocument): HeaderFooter | undefined;
+/**
+ * Default footer for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function defaultFooter(document: WordDocument): HeaderFooter | undefined;
+/**
+ * First-page header for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function firstHeader(document: WordDocument): HeaderFooter | undefined;
+/**
+ * Even-page header for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function evenHeader(document: WordDocument): HeaderFooter | undefined;
+/**
+ * First-page footer for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function firstFooter(document: WordDocument): HeaderFooter | undefined;
+/**
+ * Even-page footer for the body-final section, when linked and loaded.
+ * @private
+ */
+export declare function evenFooter(document: WordDocument): HeaderFooter | undefined;
+/**
+ * @private
+ * Test hook */
+export declare function resetHeadersFootersFeatureForTests(): void;
+/**
+ * @private
+ * Register the headers/footers multi-part handler. Idempotent. */
+export declare function registerHeadersFootersFeature(): void;
+/**
+ * Text from the default header part, when linked from body-final `sectPr`.
+ * @private
+ */
+export declare function defaultHeaderText(document: WordDocument): string | undefined;
+/**
+ * Text from the default footer part, when linked from body-final `sectPr`.
+ * @private
+ */
+export declare function defaultFooterText(document: WordDocument): string | undefined;
+/**
+ * Set default header text, creating the part and `sectPr` reference when needed.
+ * @private
+ */
+export declare function setDefaultHeader(document: WordDocument, text: string): void;
+/**
+ * Set default footer text, creating the part and `sectPr` reference when needed.
+ * @private
+ */
+export declare function setDefaultFooter(document: WordDocument, text: string): void;
+/**
+ * Header text linked from a section's `sectPr`.
+ * @private
+ */
+export declare function headerTextForSection(document: WordDocument, section: PageSetup, refType?: HeaderFooterReferenceType): string | undefined;
+/**
+ * Footer text linked from a section's `sectPr`.
+ * @private
+ */
+export declare function footerTextForSection(document: WordDocument, section: PageSetup, refType?: HeaderFooterReferenceType): string | undefined;
+/**
+ * Set header text on a section, reusing an existing linked part when present.
+ * @private
+ */
+export declare function setSectionHeader(document: WordDocument, section: PageSetup, text: string, refType?: HeaderFooterReferenceType): void;
+/**
+ * Set footer text on a section, reusing an existing linked part when present.
+ * @private
+ */
+export declare function setSectionFooter(document: WordDocument, section: PageSetup, text: string, refType?: HeaderFooterReferenceType): void;
+/**
+ * Link an existing header part to a section without creating a duplicate part.
+ * @private
+ */
+export declare function linkSectionHeader(document: WordDocument, section: PageSetup, relationshipId: string, refType?: HeaderFooterReferenceType): void;
+/**
+ * Link an existing footer part to a section without creating a duplicate part.
+ * @private
+ */
+export declare function linkSectionFooter(document: WordDocument, section: PageSetup, relationshipId: string, refType?: HeaderFooterReferenceType): void;
+declare module '../sections/index' {
+    interface PageSetup {
+        /**
+         * Live odd/default-page header for this section (OOXML `w:type="default"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * Declared as a property (not get/set accessors) for TS 3.3.1 module
+         * augmentation compatibility. Runtime still uses defineProperty getters/setters.
+         *
+         * @public
+         */
+        oddHeader: HeaderFooter | undefined;
+        /**
+         * Live odd/default-page footer for this section (OOXML `w:type="default"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @public
+         */
+        oddFooter: HeaderFooter | undefined;
+        /**
+         * Live first-page header for this section (OOXML `w:type="first"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @public
+         */
+        firstPageHeader: HeaderFooter | undefined;
+        /**
+         * Live first-page footer for this section (OOXML `w:type="first"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @public
+         */
+        firstPageFooter: HeaderFooter | undefined;
+        /**
+         * Live even-page header for this section (OOXML `w:type="even"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @public
+         */
+        evenHeader: HeaderFooter | undefined;
+        /**
+         * Live even-page footer for this section (OOXML `w:type="even"`).
+         * Get creates the part + reference when missing without wiping body content.
+         * Set an existing {@link HeaderFooter} to share a part, or `undefined` to drop the reference.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @public
+         */
+        evenFooter: HeaderFooter | undefined;
+        /**
+         * Live header linked from this section for `refType`, when present and loaded.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Header slot (`default` | `first` | `even`). Defaults to `default`.
+         * @returns {@link HeaderFooter} view, or `undefined` when no reference or part is missing.
+         *
+
+         * or {@link PageSetup.evenHeader}.
+         * @public
+         */
+        header(refType?: HeaderFooterReferenceType): HeaderFooter | undefined;
+        /**
+         * Live footer linked from this section for `refType`, when present and loaded.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Footer slot (`default` | `first` | `even`). Defaults to `default`.
+         * @returns {@link HeaderFooter} view, or `undefined` when no reference or part is missing.
+         *
+
+         * or {@link PageSetup.evenFooter}.
+         * @public
+         */
+        footer(refType?: HeaderFooterReferenceType): HeaderFooter | undefined;
+        /**
+         * Return the header for this section slot, creating part + relationship +
+         * `w:headerReference` when missing. Does not replace existing body content.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Header slot. Defaults to `default`.
+         * @returns Live {@link HeaderFooter} view.
+         *
+/ `firstPageHeader` / `evenHeader`).
+         * @public
+         */
+        getOrCreateHeader(refType?: HeaderFooterReferenceType): HeaderFooter;
+        /**
+         * Return the footer for this section slot, creating part + relationship +
+         * `w:footerReference` when missing. Does not replace existing body content.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Footer slot. Defaults to `default`.
+         * @returns Live {@link HeaderFooter} view.
+         *
+/ `firstPageFooter` / `evenFooter`).
+         * @public
+         */
+        getOrCreateFooter(refType?: HeaderFooterReferenceType): HeaderFooter;
+        /**
+         * Point this section's header slot at an existing {@link HeaderFooter} part
+         * (share across sections). Validates the part is in this document's catalog.
+         *
+         * @param header - Header from this document (e.g. from another section).
+         * @param refType - Header slot. Defaults to `default`.
+         * @throws DocxError `content/invalid-header-footer-reference` when the
+         * relationship is not loaded in this document.
+         *
+/even).
+         * @public
+         */
+        linkHeader(header: HeaderFooter, refType?: HeaderFooterReferenceType): void;
+        /**
+         * Point this section's footer slot at an existing {@link HeaderFooter} part
+         * (share across sections). Validates the part is in this document's catalog.
+         *
+         * @param footer - Footer from this document (e.g. from another section).
+         * @param refType - Footer slot. Defaults to `default`.
+         * @throws DocxError `content/invalid-header-footer-reference` when the
+         * relationship is not loaded in this document.
+         *
+/even).
+         * @public
+         */
+        linkFooter(footer: HeaderFooter, refType?: HeaderFooterReferenceType): void;
+        /**
+         * Remove this section's header reference for `refType` (inherit / none).
+         * Does not delete the OPC part if still referenced elsewhere.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Header slot. Defaults to `default`.
+         *
+/even).
+         * @public
+         */
+        removeHeader(refType?: HeaderFooterReferenceType): void;
+        /**
+         * Remove this section's footer reference for `refType` (inherit / none).
+         * Does not delete the OPC part if still referenced elsewhere.
+         * Requires document association (`section.pageSetup` on a document section).
+         *
+         * @param refType - Footer slot. Defaults to `default`.
+         *
+/even).
+         * @public
+         */
+        removeFooter(refType?: HeaderFooterReferenceType): void;
+    }
+}
+/**
+ * Set header text on a paragraph section break (`w:pPr/w:sectPr`).
+ * @private
+ */
+export declare function setParagraphSectionHeader(document: WordDocument, paragraph: Paragraph, text: string, refType?: HeaderFooterReferenceType): void;
+/**
+ * Set footer text on a paragraph section break (`w:pPr/w:sectPr`).
+ * @private
+ */
+export declare function setParagraphSectionFooter(document: WordDocument, paragraph: Paragraph, text: string, refType?: HeaderFooterReferenceType): void;