@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

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

@@ -0,0 +1,579 @@
+export * from './comment-extensions';
+import { WordDocument } from '../document/document';
+import { FeatureInline } from '../document/feature-inline';
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { FeatureRunLeaf } from '../document/feature-run-leaf';
+import { BlockContent, Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, FeatureRunParagraphItem, InlineContent, ParagraphItem, TextRange, WireRunGroup } 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 { CommentExtensionParts } from './comment-extensions';
+/**
+ * @private Transitional comments relationship (ECMA-376-4). */
+export declare const COMMENTS_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+/**
+ * @private Strict comments relationship. */
+export declare const STRICT_COMMENTS_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/comments";
+/** @private */
+export declare const COMMENTS_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+/**
+ * Comment range start marker (`w:commentRangeStart`).
+ *
+ * @public
+ */
+export declare class CommentRangeStart implements FeatureInline {
+    /**
+     * `w:commentRangeStart/@w:id` shared with the Comments part entry and end marker.
+     *
+     * @private
+     */
+    readonly commentId: number;
+    /** @private */
+    constructor(commentId: number);
+    /** @private */
+    releaseContent(): void;
+    /** @private */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Comment range end marker (`w:commentRangeEnd`).
+ *
+ * @public
+ */
+export declare class CommentRangeEnd implements FeatureInline {
+    /**
+     * `w:commentRangeEnd/@w:id` shared with the Comments part entry and start marker.
+     *
+     * @private
+     */
+    readonly commentId: number;
+    /** @private */
+    constructor(commentId: number);
+    /** @private */
+    releaseContent(): void;
+    /** @private */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Comment reference run leaf (`w:commentReference`).
+ *
+ * @private
+ */
+export declare class CommentReference implements FeatureRunLeaf {
+    /**
+     * `w:commentReference/@w:id` shared with range markers and the Comments part entry.
+     *
+     * @private
+     */
+    readonly commentId: number;
+    /** @private */
+    constructor(commentId: number);
+    /** @private */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * A comment anchor in a paragraph linked to a Comments part entry.
+ *
+ * Range markers and the reference leaf share the same internal comment id with the
+ * matching {@link Comment} body in the Comments part.
+ *
+ * @private
+ */
+export declare class CommentAnchor {
+    /**
+     * Comments part id shared with range markers and {@link CommentReference}.
+     *
+     * @private
+     */
+    readonly commentId: number;
+    /**
+     * Author from the linked Comments part entry (`w:comment/@w:author`), or the
+     * authoring author when the entry is not yet joined.
+     */
+    readonly author: string;
+    /**
+     * Optional comment timestamp from `w:comment/@w:date` (ST_DateTime), parsed as
+     * a `Date` when present and parseable.
+     */
+    readonly date: Date | undefined;
+    /**
+     * Text ranges between the matching range start and end markers for this anchor.
+     *
+     * @private
+     */
+    readonly anchorRuns: ReadonlyArray<TextRange>;
+    /**
+     * Synthetic or residual {@link CommentReference} paired with this anchor.
+     *
+     * @private
+     */
+    readonly reference: CommentReference;
+    /** @private */
+    constructor(commentId: number, author: string, date: string | Date | undefined, anchorRuns: ReadonlyArray<TextRange>, reference: CommentReference);
+}
+/**
+ * Live view of a comment body in the Comments part (`w:comment`).
+ *
+ * Bound to a WordDocument and comment id; reads go through {@link CommentsCollection}.
+ * Does not expose raw OOXML. Opaque/`preservedXml` entries yield empty paragraphs
+ * until a later modeling slice.
+ *
+ * After main-story elevation (TASK-8055), the same interned instance may also
+ * appear in `paragraph.items` as a feature inline at the former
+ * `w:commentReference` position. Serialize emits one `w:r` + optional `w:rPr` +
+ * `w:commentReference` (ECMA-376-1 §17.13.4.5 / `CT_Markup` in `EG_RunInnerContent`).
+ *
+ * **Identity:** {@link commentFor}, {@link commentForAnchor},
+ * {@link CommentsCollection.comments}, {@link Comment.ancestor}, and elevated
+ * `paragraph.items` slots return the same interned instance per modeled
+ * `(WordDocument, commentId)` for the lifetime of that collection entry (`===` holds).
+ *
+ * @public
+ */
+export declare class Comment implements FeatureInline {
+    private readonly WordDocument;
+    private readonly id;
+    /**
+     * Supported `w:rPr` from the elevated reference run (or authoring default).
+     * Not a public wrapper — serialization metadata only (D5/D6).
+     */
+    private referenceRunFormatting;
+    /** @private */
+    constructor(WordDocument: WordDocument, commentId: number);
+    /**
+     * Comment id matching range markers and {@link CommentReference.commentId}.
+     *
+     * @private
+     */
+    readonly commentId: number;
+    /**
+     * Author of this comment (`w:comment/@w:author`).
+     *
+     * Returns the modeled attribute value when the Comments part entry is known;
+     * empty string when the entry is missing or opaque.
+     * Read-only — set author at insert via {@link appendComment} / {@link insertComment}.
+     */
+    readonly author: string;
+    /**
+     * Optional `w:comment/@w:initials` (`ST_String`) when present on a modeled entry.
+     *
+     * Undefined when the attribute is absent or the entry is opaque/preserved.
+     * Empty-string values are treated as absent on serialize.
+     */
+    readonly initials: string | undefined;
+    /**
+     * Optional comment timestamp (`w:comment/@w:date`, ST_DateTime) as a `Date`.
+     *
+     * `undefined` when the attribute is absent, the entry is opaque, or the stored
+     * value is not parseable. Package storage remains the original ST_DateTime
+     * string for round-trip; this getter does not expose the raw attribute.
+     * Read-only — supply `date` on {@link AppendCommentOptions} when authoring.
+     */
+    readonly date: Date | undefined;
+    /**
+     * Modeled body paragraphs for this comment (`EG_BlockLevelElts` paragraph children).
+     *
+     * Empty when the entry is missing or preserved as opaque XML. Paragraph content
+     * is live — mutate via {@link Paragraph} APIs on the returned instances; there is
+     * no separate setter on this property.
+     */
+    readonly paragraphs: ReadonlyArray<Paragraph>;
+    /**
+     * Parent comment when this comment is a reply (`commentsExtended` / `commentEx/@paraIdParent`).
+     *
+     * Top-level comments and replies whose parent cannot be resolved return `undefined`.
+     * Read-only; DocIO-aligned (`WComment.Ancestor`). The returned instance is the
+     * collection-interned {@link Comment} for the parent id when resolved.
+     */
+    readonly ancestor: Comment | undefined;
+    /**
+     * Whether this comment is marked done (`commentsExtended` / `commentEx/@done`).
+     *
+     * Joined from `[MS-DOCX]` `CT_CommentEx/@done` (`ST_OnOff`) onto the same interned
+     * {@link Comment} used by {@link commentFor}. After join: attribute absent or `"0"` →
+     * `false`; other present values → `true`. No matching `commentEx` row → `false`
+     * (MS default 0). Read-only in this slice; mutation is `comments-resolved-state`.
+     */
+    readonly done: boolean;
+    /**
+     * Capture `w:rPr` from the wire group of the featureRun being elevated.
+     *
+     * @private
+     */
+    captureReferenceRunFormatting(group: WireRunGroup): void;
+    /**
+     * Default character style for newly authored elevated references.
+     *
+     * @private
+     */
+    applyDefaultReferenceRunStyle(): void;
+    /** @private */
+    releaseContent(): void;
+    /**
+     * @private
+     * Serialize as `w:r` + modeled `w:rPr` + `w:commentReference` (D6). Does not emit a
+     * dual legacy leaf for the same elevated occurrence (D10).
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/** @private */
+interface CommentEntry {
+    readonly commentId: number;
+    author: string;
+    /** Optional `w:initials` when modeled; undefined when absent or empty. */
+    initials: string | undefined;
+    date: string | undefined;
+    blocks: BlockContent[];
+    readonly preservedXml: OpenXmlElement | undefined;
+    /**
+     * Last body paragraph `w14:paraId` when known (from the Comments part body).
+     * Used to join `commentsExtended` `commentEx/@paraId`.
+     */
+    lastParaId: string | undefined;
+    /**
+     * Parent comment last-body-paragraph paraId from `commentEx/@paraIdParent` after extension join.
+     */
+    parentParaId: string | undefined;
+    /**
+     * Joined `commentEx/@done` after extension join.
+     *
+     * `undefined` until a matching extended row is joined. After join, absent/`"0"` map to
+     * `false` and other present values to `true` for the read API (MS default 0).
+     */
+    done: boolean | undefined;
+}
+/** @private */
+interface CommentsPartState {
+    readonly partName: PartName;
+    readonly relationshipId: RelationshipId;
+    readonly relationshipType: string;
+    readonly rootExtra: Pick<OpenXmlElement, 'attributes' | 'namespaceDeclarations'>;
+    entries: CommentEntry[];
+    dirty: boolean;
+    pendingRelationship: OpcRelationship | undefined;
+}
+/**
+ * Elevate modeled comment references across the main story.
+ *
+ * @private
+ */
+export declare function elevateCommentReferencesInDocument(WordDocument: WordDocument): void;
+/**
+ * Type guard: paragraph feature-inline value is an elevated {@link Comment}.
+ *
+ * @private
+ */
+export declare function isCommentInline(inline: InlineContent): inline is FeatureInlineParagraphItem & {
+    value: Comment;
+};
+/**
+ * Comments part linked from the Main WordDocument.
+ *
+ * @private
+ */
+export declare class CommentsCollection implements FeatureMultiPackagePart {
+    private state;
+    private readonly extensionParts;
+    /** Interned live Comment views keyed by comment id (per collection / WordDocument). */
+    private readonly commentViews;
+    /** @private */
+    constructor(state: CommentsPartState | undefined, extensionParts: CommentExtensionParts);
+    /**
+     * MS-DOCX comment extension metadata discovered from Main WordDocument relationships.
+     *
+     * @private
+     */
+    extensions(): CommentExtensionParts;
+    /**
+     * Main-story `commentReference` → elevated {@link Comment} (TASK-8055 / D14).
+     *
+     * Invoked from {@link WordDocument.fromPackage} via duck-typed `afterMainDocumentLoad`
+     * so core/document does not value-import this module (avoids Paragraph TDZ cycles).
+     *
+     * @private
+     */
+    elevateMainStoryReferences(WordDocument: WordDocument): void;
+    /**
+     * Post-load hook for {@link WordDocument.fromPackage} (duck-typed on feature parts).
+     *
+     * @private
+     */
+    afterMainDocumentLoad(WordDocument: WordDocument): void;
+    /**
+     * Interned live {@link Comment} for a modeled comment id.
+     *
+     * @private
+     */
+    commentInstanceFor(WordDocument: WordDocument, commentId: number): Comment;
+    /** @private */
+    isDirty(): boolean;
+    /** @private */
+    applyToPackage(pkg: OpcPackage, mainPartName: PartName): OpcPackage;
+    /** @private */
+    ensurePart(usedRelIds: ReadonlySet<string>, usedPartNames: ReadonlySet<string>): CommentsPartState;
+    /**
+     * Allocate a new modeled comment entry (unique id) and mark the part dirty.
+     *
+     * @param WordDocument - Owning WordDocument (id allocation scans main-story markers).
+     * @param author - `w:author` (may be empty string).
+     * @param commentText - Initial body text (first paragraph / first run).
+     * @param date - Optional `w:date` (ST_DateTime string); empty/omitted → attribute absent.
+     * @param initials - Optional `w:initials`; empty/omitted → attribute absent.
+     * @private
+     */
+    addEntry(WordDocument: WordDocument, author: string, commentText: string, date?: string, initials?: string): number;
+    /** @private */
+    entryFor(commentId: number): CommentEntry | undefined;
+    /**
+     * Resolve parent comment via DocIO-aligned reverse scan on prior Comments part entries.
+     *
+     * @private
+     */
+    ancestorFor(WordDocument: WordDocument, commentId: number): Comment | undefined;
+    /**
+     * Modeled comment ids in Comments part order (opaque preserved entries omitted).
+     *
+     * @private
+     */
+    commentIds(): ReadonlyArray<number>;
+    /**
+     * Live {@link Comment} views for every modeled Comments part entry, in part order.
+     *
+     * Each id is interned: repeated collection / lookup APIs return the same instance.
+     *
+     * @private
+     */
+    comments(WordDocument: WordDocument): ReadonlyArray<Comment>;
+    /**
+     * Body paragraphs of a modeled comment, when present.
+     *
+     * @private
+     */
+    paragraphsFor(commentId: number): ReadonlyArray<Paragraph>;
+    /** @private */
+    textFor(commentId: number): string | undefined;
+    /** @private */
+    removeEntry(commentId: number): void;
+}
+/** @private Test hook */
+export declare function resetCommentsFeatureForTests(): void;
+/** @private Register comment inline, run-leaf, and comments-part handlers. Idempotent. */
+export declare function registerCommentsFeature(): void;
+/**
+ * Public comments collection for a {@link WordDocument}.
+ *
+ * Stable per-document identity. Members are the same interned {@link Comment}
+ * instances returned from {@link Paragraph.appendComment} and the internal
+ * comments catalog.
+ *
+ * Supports `count`, numeric index access, and iteration.
+ *
+ * @public
+ */
+export declare class CommentCollection implements Iterable<Comment> {
+    private readonly document;
+    private cachedLength;
+    /**
+     * @private
+     */
+    constructor(document: WordDocument);
+    /**
+     * Number of modeled comment bodies in the Comments part.
+     *
+     * @public
+     */
+    readonly count: number;
+    /**
+     * Comment at zero-based `index`, or `undefined` when out of range.
+     *
+     * @public
+     */
+    itemAt(index: number): Comment | undefined;
+    [Symbol.iterator](): Iterator<Comment>;
+    /**
+     * Refresh numeric index properties from the catalog (part order).
+     *
+     * @private
+     */
+    rebuildIndexProperties(): void;
+}
+export interface CommentCollection {
+    readonly [index: number]: Comment;
+}
+/**
+ * Stable public {@link CommentCollection} for `document`.
+ *
+ * @private
+ */
+export declare function commentCollectionFor(document: WordDocument): CommentCollection;
+/**
+ * Comments collection for a WordDocument.
+ *
+ * On a loaded package this is the collection built from the Main WordDocument comments
+ * relationship when the feature was registered before load. On
+ * {@link WordDocument.create} (or a package with no comments part) attaches an empty
+ * collection on first use when the feature is registered.
+ *
+ * The returned {@link CommentsCollection} surface is internal; public callers use
+ * {@link commentsInDocument}, {@link commentFor}, and related helpers.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not registered
+ *   or feature state was replaced with an unexpected part type.
+ *
+ * @private
+ */
+export declare function commentsFor(WordDocument: WordDocument): CommentsCollection;
+/**
+ * MS-DOCX comment extension metadata for a loaded WordDocument.
+ *
+ * @private
+ */
+export declare function commentExtensionsFor(WordDocument: WordDocument): CommentExtensionParts;
+/**
+ * Live {@link Comment} body for a Comments part id.
+ *
+ * Returns the catalog-interned instance for `(WordDocument, commentId)` so repeated
+ * lookups share object identity (`===`).
+ *
+ * @private
+ */
+export declare function commentFor(WordDocument: WordDocument, commentId: number): Comment;
+/**
+ * Live {@link Comment} body linked from a paragraph anchor.
+ *
+ * Same interned instance as {@link commentFor} for `anchor.commentId`.
+ *
+ * @private
+ */
+export declare function commentForAnchor(WordDocument: WordDocument, anchor: CommentAnchor): Comment;
+/**
+ * Modeled comment bodies in the Comments part, in part order.
+ *
+ * Opaque preserved entries are omitted. Prefer this for a full catalog list;
+ * {@link commentsInParagraph} lists anchors in the main story.
+ *
+ * @private
+ */
+export declare function commentsInDocument(WordDocument: WordDocument): ReadonlyArray<Comment>;
+/**
+ * Comment anchors in a paragraph, in WordDocument order.
+ *
+ * @private
+ */
+export declare function commentsInParagraph(WordDocument: WordDocument, paragraph: Paragraph): ReadonlyArray<CommentAnchor>;
+/**
+ * Visible text of a comment body, when loaded (first non-empty run of the first paragraph).
+ *
+ * @private
+ */
+export declare function commentBody(WordDocument: WordDocument, anchor: CommentAnchor): string | undefined;
+/**
+ * Modeled body paragraphs of a comment linked from an anchor.
+ *
+ * @private
+ */
+export declare function commentParagraphs(WordDocument: WordDocument, anchor: CommentAnchor): ReadonlyArray<Paragraph>;
+/**
+ * Metadata for {@link appendComment} when body text is passed separately.
+ * Same fields as {@link AppendCommentOptions} except `text` (TS 3.3 has no `Omit`).
+ *
+ * @public
+ */
+export interface AppendCommentMetadata {
+    /**
+     * `w:author`. When omitted, uses an empty string (WordDocument-empty default).
+     */
+    readonly author?: string;
+    /** `w:initials` when provided (empty string omitted on serialize). */
+    readonly initials?: string;
+    /**
+     * `w:date` (ST_DateTime). `Date` values are written as ISO UTC (`Date.toISOString()`).
+     * When omitted on append, the library writes ISO UTC now for scratch packages.
+     */
+    readonly date?: Date | string;
+    /**
+     * Inclusive start index into `paragraph.items` for `CommentRangeStart`
+     * insertion **before** that item. Optional; see {@link appendComment}.
+     */
+    readonly rangeStart?: number;
+    /**
+     * Exclusive end index into `paragraph.items` for `CommentRangeEnd`
+     * insertion **before** that item (or after the last included item). Optional.
+     * When both `rangeStart` and `rangeEnd` are omitted, a collapsed range is
+     * placed at the end of current content before the elevated `Comment` (D15).
+     */
+    readonly rangeEnd?: number;
+}
+/**
+ * Options for {@link Paragraph.appendComment} / {@link appendComment}.
+ *
+ * @public
+ */
+export interface AppendCommentOptions extends AppendCommentMetadata {
+    /** Initial comment body text (first body paragraph / primary text). */
+    readonly text: string;
+}
+/**
+ * Append a new comment to a paragraph (range markers + elevated {@link Comment}).
+ *
+ * Primary shape: `appendComment(paragraph, text, options?)`. Options-only overload
+ * accepts {@link AppendCommentOptions} with required `text`.
+ *
+ * Behavior (locked D7/D8/D15/D16):
+ * - Comments feature must be registered (`feature/not-registered` otherwise).
+ * - Paragraph must be attached (`DetachedObjectError` via {@link Paragraph.owningDocument}).
+ * - Range indices validated **before** mutation (`RangeError` when invalid/reversed).
+ * - New unique comment id; one catalog entry; one elevated `Comment` after end marker.
+ * - When both range indices omitted: collapsed markers at append point (still emitted).
+ * - Public DOM has no empty sole-purpose `CommentReference` Run.
+ *
+ * @param paragraph - Host paragraph in the main story.
+ * @param textOrOptions - Body text, or full options object.
+ * @param options - Optional metadata / range when the first argument is text.
+ * @returns Interned {@link Comment} (`===` content slot and {@link commentFor}).
+ * @public
+ */
+export declare function appendComment(paragraph: Paragraph, textOrOptions: string | AppendCommentOptions, options?: AppendCommentMetadata): Comment;
+/**
+ * Insert a comment with optional anchor text at the end of a paragraph.
+ *
+ * Places an elevated {@link Comment} feature-inline (not a public empty
+ * CommentReference Run). When `anchorText` is non-empty, range markers wrap the
+ * new anchor run before the Comment. When empty, only the elevated Comment is
+ * appended (legacy insert path; prefer {@link appendComment} for D15 markers).
+ *
+ * @private
+ */
+export declare function insertComment(WordDocument: WordDocument, paragraph: Paragraph, author: string, commentText: string, anchorText?: string): CommentAnchor;
+/**
+ * Remove a comment anchor, range markers, and comments part entry.
+ *
+ * @private
+ */
+export declare function removeComment(WordDocument: WordDocument, paragraph: Paragraph, anchor: CommentAnchor): void;
+/**
+ * Whether paragraph inline content is a modeled comment range start from this module.
+ *
+ * @private
+ */
+export declare function isCommentRangeStartInline(inline: InlineContent): inline is FeatureInlineParagraphItem & {
+    value: CommentRangeStart;
+};
+/**
+ * Whether paragraph inline content is a modeled comment range end from this module.
+ *
+ * @private
+ */
+export declare function isCommentRangeEndInline(inline: InlineContent): inline is FeatureInlineParagraphItem & {
+    value: CommentRangeEnd;
+};
+/**
+ * Whether a paragraph item is a residual modeled comment reference featureRun.
+ *
+ * @private
+ */
+export declare function isCommentReferenceLeaf(leaf: ParagraphItem): leaf is FeatureRunParagraphItem & {
+    value: CommentReference;
+};