API Referencev1.3.3

@eigenpal/docx-editor-core/utils/comments

Framework-agnostic comment + tracked-change helpers shared by the React and Vue adapters. The data shapes and string-formatting rules here are part of the visible UI (avatar colors, date strings) so keep this file as the single source of truth — both adapters import from here. CSS-property factories live in adapter-specific files (sidebar/cardUtils.ts in React, sidebar/sidebarUtils.ts in Vue).

Functions(5)

formatDate

packages/core/src/docx/fieldParser.ts:618

declare function formatDate(dateStr?: string): string;

getAvatarColor

packages/core/src/utils/comments.ts:63

declare function getAvatarColor(name: string): string;

getCommentText

packages/core/src/utils/comments.ts:14

Extract plain text from a Comment's paragraph content.

declare function getCommentText(paragraphs?: Paragraph[]): string;

getInitials

packages/core/src/utils/comments.ts:38

declare function getInitials(name: string): string;

truncateText

packages/core/src/utils/comments.ts:71

declare function truncateText(text: string, maxLength?: number): string;

Interfaces(1)

interface

TrackedChangeEntry

packages/core/src/utils/comments.ts:84

One tracked change surfaced by `extractTrackedChanges`. Each entry groups all sites of one revision into a single row that the sidebar renders as one card. Resolve via [acceptChangeById](acceptChangeById) / [rejectChangeById](rejectChangeById) for any type — the by-id resolver walks every site sharing the id so coalesced edits clear in one click.

interface TrackedChangeEntry

Member	Type	Summary
author	`string`	Author that minted the revision (`w:author`).
coalescedRevisionIds?	`number[]`	Extra `w:id`s that map to the same logical revision as this card. Populated when the extractor coalesces a burst of distinct ids by (author, date) — e.g. a foreign document where the source editor minted a fresh id per atomic edit. Accept/reject handlers must resolve every id in this list in addition to [revisionId](revisionId).
date?	`string`	ISO timestamp the revision was minted (`w:date`). May be undefined for legacy imports.
deletedText?	`string`	Only set when `type === 'replacement'` — the text the user removed. The inserted text lives in [TrackedChangeEntry.text](TrackedChangeEntry.text).
from	`number`	Document position where the revision starts. For inline types this is the start of the marked text run; for structural types it's the containing paragraph / row / cell / table node's start position. Used by the sidebar to anchor the card at the correct vertical offset.
insertionRevisionId?	`number`	Only set when `type === 'replacement'` — the insertion half carries a DIFFERENT `w:id` from the deletion (sharing would trip the OOXML move-pair serializer). Card Accept handlers dispatch BOTH ids to clear the deletion and the insertion + any coalesced paragraph-marks.
revisionId	`number`	The `w:id` of the revision. Pass to [acceptChangeById](acceptChangeById) / [rejectChangeById](rejectChangeById) to resolve every site sharing this id — including pPrIns paragraph attrs and subsequent typed runs in the same editing session.
text	`string`	Affected text. For inline types this is the run's text; for structural types it's the surrounding paragraph / cell content (truncated by the sidebar before display).
to	`number`	Document position where the revision ends. For inline coalesced runs that span multiple paragraphs, this is the END position of the LAST run in the group; the intervening structural positions are not preserved.
type	`'insertion' \| 'deletion' \| 'replacement' \| 'paragraphMarkInsertion' \| 'paragraphMarkDeletion' \| 'paragraphPropertiesChanged' \| 'rowInserted' \| 'rowDeleted' \| 'rowPropertiesChanged' \| 'cellInserted' \| 'cellDeleted' \| 'cellMerged' \| 'cellPropertiesChanged' \| 'tableInserted' \| 'tableDeleted' \| 'tablePropertiesChanged'`	Revision shape. Inline shapes (`insertion`, `deletion`, `replacement`) wrap text runs; the rest are structural revisions on node attrs.