@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/notes/index.d.ts

@@ -0,0 +1,573 @@
+import { WordDocument } from '../document/document';
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { FeatureRunLeaf } from '../document/feature-run-leaf';
+import { BodyItem } from '../document/body-item';
+import { BlockContent, Paragraph } from '../document/paragraph';
+import { FeatureRunParagraphItem, ParagraphItem } from '../document/text-range';
+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 { Table as TableFeature } from '../tables/index';
+import { ContentControl, ContentControlType } from '../content-controls/index';
+/**
+ * @private
+ * Transitional footnotes relationship (ECMA-376-4 §9.2.6). */
+export declare const FOOTNOTES_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
+/**
+ * @private
+ * Transitional endnotes relationship (ECMA-376-4 §9.2.5). */
+export declare const ENDNOTES_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+/**
+ * @private
+ * Strict footnotes relationship. */
+export declare const STRICT_FOOTNOTES_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/footnotes";
+/**
+ * @private
+ * Strict endnotes relationship. */
+export declare const STRICT_ENDNOTES_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/endnotes";
+/**
+ * @private
+ */
+export declare const FOOTNOTES_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml";
+/**
+ * @private
+ */
+export declare const ENDNOTES_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml";
+declare type NoteKind = 'footnote' | 'endnote';
+/**
+ * @private
+ */
+export declare type FtnEdnType = 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
+/**
+ * Footnote reference run leaf (`w:footnoteReference`).
+ *
+ * @private
+ */
+export declare class FootnoteReference implements FeatureRunLeaf {
+    /**
+     * @private
+   * Stable id linking this reference to its footnote body. */
+    readonly noteId: number;
+    /**
+     * @private
+     */
+    constructor(noteId: number);
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Endnote reference run leaf (`w:endnoteReference`).
+ *
+ * @private
+ */
+export declare class EndnoteReference implements FeatureRunLeaf {
+    /**
+     * @private
+   * Stable id linking this reference to its endnote body. */
+    readonly noteId: number;
+    /**
+     * @private
+     */
+    constructor(noteId: number);
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * @private
+ */
+interface NoteEntry {
+    readonly noteId: number;
+    readonly noteType: FtnEdnType | undefined;
+    blocks: BlockContent[];
+    readonly preservedXml: OpenXmlElement | undefined;
+}
+/**
+ * @private
+ */
+interface NotePartState {
+    readonly partName: PartName;
+    readonly relationshipId: RelationshipId;
+    readonly relationshipType: string;
+    readonly kind: NoteKind;
+    readonly rootExtra: Pick<OpenXmlElement, 'attributes' | 'namespaceDeclarations'>;
+    entries: NoteEntry[];
+    dirty: boolean;
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * Footnotes and endnotes parts linked from the Main WordDocument.
+ *
+ * @private
+ */
+export declare class NotesCatalog implements FeatureMultiPackagePart {
+    private readonly parts;
+    private boundDocument;
+    /**
+     * @private
+     */
+    constructor(parts: Map<NoteKind, NotePartState>);
+    /**
+     * Bind this catalog to a live WordDocument so paragraph owners can resolve.
+     * Re-attaches existing modeled note body blocks to entry-scoped owners.
+     *
+     * @private
+     */
+    bindDocument(WordDocument: WordDocument): void;
+    private requireBoundDocument;
+    private markPartDirty;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    applyToPackage(pkg: OpcPackage, mainPartName: PartName): OpcPackage;
+    /**
+     * @private
+     */
+    ensurePart(kind: NoteKind, usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): NotePartState;
+    /**
+     * @private
+     */
+    addNormalEntry(kind: NoteKind, text: string): number;
+    /**
+     * @private
+     */
+    normalEntry(kind: NoteKind, noteId: number): NoteEntry | undefined;
+    private requireNormalEntry;
+    /**
+     * @private
+     */
+    textForNote(kind: NoteKind, noteId: number): string | undefined;
+    /**
+     * Ordered body children ({@link BodyItem}) for a normal note — paragraphs, tables,
+     * block content controls, and residuals, in WordDocument order (same model as Body.items).
+     *
+     * @private
+     */
+    itemsForNote(kind: NoteKind, noteId: number): ReadonlyArray<BodyItem>;
+    /**
+     * Body blocks of a normal note, when modeled (paragraphs, tables, content controls, residuals).
+     *
+     * @private
+     * Prefer {@link NotesCatalog.itemsForNote}.
+     */
+    blocksForNote(kind: NoteKind, noteId: number): ReadonlyArray<BodyItem>;
+    /**
+     * Body paragraphs of a normal note, when modeled.
+     *
+     * @private
+     * Prefer {@link NotesCatalog.itemsForNote} for mixed body content.
+     */
+    paragraphsForNote(kind: NoteKind, noteId: number): ReadonlyArray<Paragraph>;
+    /**
+     * Replace the body of a normal note with a single paragraph of plain text.
+     *
+     * @private
+     */
+    setTextForNote(kind: NoteKind, noteId: number, text: string): void;
+    /**
+     * Insert a body item at `index` in a normal note (`0…length` inclusive).
+     *
+     * Attaches paragraphs and feature blocks when the catalog is WordDocument-bound.
+     * Returns the same `item` reference for chaining.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError when the note is unknown or the catalog is unbound.
+     *
+     * @private
+     */
+    insertBodyItemAtForNote(kind: NoteKind, noteId: number, index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove the body item at `index` in a normal note (`0…length-1`).
+     * Paragraphs detach; feature blocks may release content.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DocxError when the note is unknown.
+     *
+     * @private
+     */
+    removeBodyItemAtForNote(kind: NoteKind, noteId: number, index: number): void;
+    /**
+     * Remove a body item from a normal note by collection or payload identity.
+     *
+     * @throws DetachedObjectError when the item is not in the note.
+     * @throws DocxError when the note is unknown.
+     *
+     * @private
+     */
+    removeBodyItemForNote(kind: NoteKind, noteId: number, item: BodyItem): void;
+    /**
+     * Append a paragraph to a normal note body.
+     *
+     * @throws DocxError when the note is unknown or the catalog is unbound.
+     *
+     * @private
+     */
+    appendParagraphToNote(kind: NoteKind, noteId: number, options?: {
+        readonly style?: string;
+        readonly text?: string;
+    }): Paragraph;
+    /**
+     * Append a table to a normal note body.
+     *
+     * @throws DocxError when the note is unknown or the catalog is unbound.
+     * @throws RangeError when dimensions are less than 1.
+     *
+     * @private
+     */
+    appendTableToNote(kind: NoteKind, noteId: number, rowCount: number, columnCount: number): TableFeature;
+    /**
+     * Append a block-level content control to a normal note body.
+     *
+     * @throws DocxError when the note is unknown or the catalog is unbound.
+     *
+     * @private
+     */
+    appendBlockContentControlToNote(kind: NoteKind, noteId: number, type?: ContentControlType): ContentControl;
+    /**
+ * @private
+ */
+    removeNormalEntry(kind: NoteKind, noteId: number): void;
+}
+/**
+ * Live view of a footnote body in the footnotes part.
+ *
+ * Bound to a WordDocument and note id; reads and writes go through
+ * {@link NotesCatalog}. Body content is the same R5.6
+ * {@link BodyItem} list as {@link Body} (`items` +
+ * insert/remove). Does not expose raw OOXML.
+ *
+ * @public
+ */
+export declare class Footnote {
+    private readonly WordDocument;
+    private readonly id;
+    /**
+     * @private
+     */
+    constructor(WordDocument: WordDocument, noteId: number);
+    /**
+     * @private
+   * Stable id matching the footnote reference and footnotes part entry. */
+    readonly noteId: number;
+    /**
+     * Ordered body children ({@link BodyItem}) for this footnote —
+     * paragraphs, tables, block content controls, and residuals, in
+     * WordDocument order (same model as {@link Body.items}).
+     *
+     * @public
+     */
+    readonly items: ReadonlyArray<BodyItem>;
+    /**
+     * Insert a body item at `index` in {@link Footnote.items}
+     * (`0…length` inclusive — insert-before / append).
+     *
+     * Attaches paragraphs and feature blocks to the owning WordDocument. Returns the
+     * same `item` reference for chaining (API-RULES R1.1).
+     *
+     * @param index - Index in {@link Footnote.items}.
+     * @param item - Paragraph, feature, or opaque body child.
+     * @returns The inserted {@link BodyItem}.
+     * @throws RangeError if `index` is out of range.
+     *
+     * @public
+     */
+    insertBodyItemAt(index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove the body item at `index` in {@link Footnote.items}
+     * (`0…length-1`). Paragraphs detach; feature blocks may release content.
+     *
+     * @param index - Index in {@link Footnote.items}.
+     * @throws RangeError if `index` is out of range.
+     *
+     * @public
+     */
+    removeBodyItemAt(index: number): void;
+    /**
+     * Remove a body item from {@link Footnote.items} by collection or payload identity.
+     *
+     * @param item - Entry from `items`, or an equivalent payload wrapper.
+     * @throws DetachedObjectError if `item` is not in this footnote.
+     *
+     * @public
+     */
+    removeBodyItem(item: BodyItem): void;
+}
+/**
+ * Live view of an endnote body in the endnotes part.
+ *
+ * Bound to a WordDocument and note id; reads and writes go through
+ * {@link NotesCatalog}. Body content is the same R5.6
+ * {@link BodyItem} list as {@link Body} (`items` +
+ * insert/remove). Does not expose raw OOXML.
+ *
+ * @public
+ */
+export declare class Endnote {
+    private readonly WordDocument;
+    private readonly id;
+    /**
+     * @private
+     */
+    constructor(WordDocument: WordDocument, noteId: number);
+    /**
+     * @private
+   * Stable id matching the endnote reference and endnotes part entry. */
+    readonly noteId: number;
+    /**
+     * Ordered body children ({@link BodyItem}) for this endnote —
+     * paragraphs, tables, block content controls, and residuals, in
+     * WordDocument order (same model as {@link Body.items}).
+     *
+     * @public
+     */
+    readonly items: ReadonlyArray<BodyItem>;
+    /**
+     * Insert a body item at `index` in {@link Endnote.items}
+     * (`0…length` inclusive — insert-before / append).
+     *
+     * Attaches paragraphs and feature blocks to the owning WordDocument. Returns the
+     * same `item` reference for chaining (API-RULES R1.1).
+     *
+     * @param index - Index in {@link Endnote.items}.
+     * @param item - Paragraph, feature, or opaque body child.
+     * @returns The inserted {@link BodyItem}.
+     * @throws RangeError if `index` is out of range.
+     *
+     * @public
+     */
+    insertBodyItemAt(index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove the body item at `index` in {@link Endnote.items}
+     * (`0…length-1`). Paragraphs detach; feature blocks may release content.
+     *
+     * @param index - Index in {@link Endnote.items}.
+     * @throws RangeError if `index` is out of range.
+     *
+     * @public
+     */
+    removeBodyItemAt(index: number): void;
+    /**
+     * Remove a body item from {@link Endnote.items} by collection or payload identity.
+     *
+     * @param item - Entry from `items`, or an equivalent payload wrapper.
+     * @throws DetachedObjectError if `item` is not in this endnote.
+     *
+     * @public
+     */
+    removeBodyItem(item: BodyItem): void;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetNotesFeatureForTests(): void;
+/**
+ * @private
+ * Register note reference and notes-part handlers. Idempotent. */
+export declare function registerNotesFeature(): void;
+/**
+ * Notes catalog for a WordDocument.
+ *
+ * On a loaded package this is the catalog built from footnotes/endnotes parts.
+ * On a newly authored WordDocument there may be no notes parts yet, so this function
+ * attaches an empty catalog on first use when the feature is registered.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not registered.
+ *
+ * @private
+ */
+export declare function notesFor(WordDocument: WordDocument): NotesCatalog;
+/**
+ * Interned live {@link Footnote} for `(document, noteId)`.
+ *
+ * @private
+ */
+export declare function footnoteInstanceFor(document: WordDocument, noteId: number): Footnote;
+/**
+ * Interned live {@link Endnote} for `(document, noteId)`.
+ *
+ * @private
+ */
+export declare function endnoteInstanceFor(document: WordDocument, noteId: number): Endnote;
+/**
+ * Live {@link Footnote} view for a reference in this WordDocument.
+ *
+ * @private
+ */
+export declare function footnoteFor(WordDocument: WordDocument, reference: FootnoteReference): Footnote;
+/**
+ * Live {@link Endnote} view for a reference in this WordDocument.
+ *
+ * @private
+ */
+export declare function endnoteFor(WordDocument: WordDocument, reference: EndnoteReference): Endnote;
+/**
+ * Footnote bodies referenced from the WordDocument body, in WordDocument order (first occurrence).
+ *
+ * @private
+ */
+export declare function footnotesInDocument(WordDocument: WordDocument): ReadonlyArray<Footnote>;
+/**
+ * Endnote bodies referenced from the WordDocument body, in WordDocument order (first occurrence).
+ *
+ * @private
+ */
+export declare function endnotesInDocument(WordDocument: WordDocument): ReadonlyArray<Endnote>;
+/**
+ * Document-level footnotes manager (`WordDocument.footnotes`).
+ *
+ * Stable per-document identity. Enumerates interned {@link Footnote} bodies
+ * referenced from the main story in document order. Named {@link Footnotes}
+ * (plural) so it does not collide with the per-note {@link Footnote} body class.
+ *
+ * @public
+ */
+export declare class Footnotes implements Iterable<Footnote> {
+    private readonly document;
+    private cachedLength;
+    /**
+     * @private
+     */
+    constructor(document: WordDocument);
+    /**
+     * Number of distinct footnote bodies referenced from the main story.
+     *
+     * @public
+     */
+    readonly count: number;
+    /**
+     * Footnote at zero-based `index`, or `undefined` when out of range.
+     *
+     * @public
+     */
+    itemAt(index: number): Footnote | undefined;
+    [Symbol.iterator](): Iterator<Footnote>;
+    /**
+     * @private
+     */
+    rebuildIndexProperties(): void;
+}
+export interface Footnotes {
+    readonly [index: number]: Footnote;
+}
+/**
+ * Document-level endnotes manager (`WordDocument.endnotes`).
+ *
+ * Stable per-document identity. Enumerates interned {@link Endnote} bodies
+ * referenced from the main story in document order. Named {@link Endnotes}
+ * (plural) so it does not collide with the per-note {@link Endnote} body class.
+ *
+ * @public
+ */
+export declare class Endnotes implements Iterable<Endnote> {
+    private readonly document;
+    private cachedLength;
+    /**
+     * @private
+     */
+    constructor(document: WordDocument);
+    /**
+     * Number of distinct endnote bodies referenced from the main story.
+     *
+     * @public
+     */
+    readonly count: number;
+    /**
+     * Endnote at zero-based `index`, or `undefined` when out of range.
+     *
+     * @public
+     */
+    itemAt(index: number): Endnote | undefined;
+    [Symbol.iterator](): Iterator<Endnote>;
+    /**
+     * @private
+     */
+    rebuildIndexProperties(): void;
+}
+export interface Endnotes {
+    readonly [index: number]: Endnote;
+}
+/**
+ * Stable {@link Footnotes} manager for `document`.
+ *
+ * @private
+ */
+export declare function footnotesFor(document: WordDocument): Footnotes;
+/**
+ * Stable {@link Endnotes} manager for `document`.
+ *
+ * @private
+ */
+export declare function endnotesFor(document: WordDocument): Endnotes;
+/**
+ * Footnote references in a paragraph, in WordDocument order.
+ *
+ * @private
+ */
+export declare function footnotesInParagraph(paragraph: Paragraph): ReadonlyArray<FootnoteReference>;
+/**
+ * Endnote references in a paragraph, in WordDocument order.
+ *
+ * @private
+ */
+export declare function endnotesInParagraph(paragraph: Paragraph): ReadonlyArray<EndnoteReference>;
+/**
+ * Visible text of a footnote body, when loaded.
+ *
+ * @private
+ */
+export declare function footnoteText(WordDocument: WordDocument, reference: FootnoteReference): string | undefined;
+/**
+ * Visible text of an endnote body, when loaded.
+ *
+ * @private
+ */
+export declare function endnoteText(WordDocument: WordDocument, reference: EndnoteReference): string | undefined;
+/**
+ * Insert a footnote reference and body at the end of a paragraph.
+ *
+ * @private
+ */
+export declare function insertFootnote(WordDocument: WordDocument, paragraph: Paragraph, text: string): FootnoteReference;
+/**
+ * Insert an endnote reference and body at the end of a paragraph.
+ *
+ * @private
+ */
+export declare function insertEndnote(WordDocument: WordDocument, paragraph: Paragraph, text: string): EndnoteReference;
+/**
+ * Remove a footnote reference and body from a WordDocument.
+ *
+ * @private
+ */
+export declare function removeFootnote(WordDocument: WordDocument, paragraph: Paragraph, reference: FootnoteReference): void;
+/**
+ * Remove an endnote reference and body from a WordDocument.
+ *
+ * @private
+ */
+export declare function removeEndnote(WordDocument: WordDocument, paragraph: Paragraph, reference: EndnoteReference): void;
+/**
+ * Whether a paragraph item is a modeled footnote reference from this module.
+ *
+ * @private
+ */
+export declare function isFootnoteReferenceLeaf(item: ParagraphItem): item is FeatureRunParagraphItem & {
+    value: FootnoteReference;
+};
+/**
+ * Whether a paragraph item is a modeled endnote reference from this module.
+ *
+ * @private
+ */
+export declare function isEndnoteReferenceLeaf(item: ParagraphItem): item is FeatureRunParagraphItem & {
+    value: EndnoteReference;
+};
+export {};