@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/content/TrackedChange.d.mts

@@ -1,13 +1,21 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type * as math from '@docx4j/generated-objects-ts/modules/org_docx4j_math';
+import type * as mce from '@docx4j/generated-objects-ts/modules/org_docx4j_mce';
 import { type Element, type Located, type RevisionKind } from './tree.mjs';
 import { Range } from './Range.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 import type { Body } from './Body.mjs';
 import type { Part } from '../../parts/Part.mjs';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
 import { type RelationshipRemovals } from './relationships.mjs';
 /** Office JS `Word.ChangeTrackingState` (`Unknown` is not produced here). */
 export type TrackedChangeType = 'Added' | 'Deleted' | 'Formatted' | 'None' | 'Unknown';
+/**
+ * docx4j's finer kind of change (its `TrackedChange.Kind`, CR-043), the names verbatim, as data values
+ * a filter written for docx4j or passed as JSON carries over in (CR-011 D3). `INSERTION`, `DELETION` and
+ * `FORMATTING` are a group's whose pieces are of more than one kind.
+ */
+export type TrackedChangeKind = 'RUN_INSERTION' | 'RUN_DELETION' | 'MOVE' | 'PARAGRAPH_MARK_INSERTION' | 'PARAGRAPH_MARK_DELETION' | 'RUN_PROPERTIES' | 'PARAGRAPH_MARK_PROPERTIES' | 'PARAGRAPH_PROPERTIES' | 'ROW_INSERTION' | 'ROW_DELETION' | 'FIELD_INSERTION' | 'CONTENT_CONTROL_INSERTION' | 'CONTENT_CONTROL_DELETION' | 'MATH_STRUCTURE_INSERTION' | 'MATH_STRUCTURE_DELETION' | 'INSERTION' | 'DELETION' | 'FORMATTING' | 'TABLE_PROPERTIES' | 'SECTION_PROPERTIES' | 'CELL_INSERTION' | 'CELL_DELETION';
 /** Which piece of revision markup a `TrackedChange` is over (an extension: Office JS has no such member). */
 export type TrackedChangeTarget = 
 /** `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` around runs. */
@@ -107,10 +115,13 @@ export type TrackedChangeTarget =
  * `w:sdt` or `w:customXml`, `owner` the list holding it, `outer` the pair in that list and `inner`
  * the pair in its content. Rejecting takes the element away and leaves its content where it
  * stood; accepting takes the markers away. Its text is its content's, which the pieces inside
- * report.
+ * report. Or a deletion, `revision` `del`: the same form with `w:customXmlDelRangeStart` and `End`,
+ * Word's for a control a tracked deletion took (check 54 cases 15 and 17; CR-014 section 12), which
+ * groups with the deletions around and inside it; accepting takes the element away, rejecting the markers.
  */
  | {
     kind: 'holder';
+    revision: 'ins' | 'del';
     holder: Element;
     owner: Element[];
     outer: [Element, Element];
@@ -164,8 +175,9 @@ export type TrackedChangeTarget =
 };
 /**
  * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
- * `reject()` and `getRange()`, plus `element`, `id` and `target` as extensions. A view, like
- * `Paragraph` and `Range`: it holds the markup it is over, nothing is cached.
+ * `reject()` and `getRange()`, plus `element`, `id`, `target`, and docx4j's `kind`, `part` and
+ * `pieces` (CR-011) as extensions. A view, like `Paragraph` and `Range`: it holds the markup it is
+ * over, nothing is cached.
  */
 export declare class TrackedChange {
     readonly target: TrackedChangeTarget;
@@ -189,6 +201,24 @@ export declare class TrackedChange {
     get date(): Date | undefined;
     /** The annotation id (`w:id`; an extension). */
     get id(): number;
+    /**
+     * docx4j's kind of change (an extension; its `TrackedChange.getKind()`, CR-011): `target.kind` in
+     * docx4j's names, an equation's runs as runs. A group's is its pieces' when they are all of one kind,
+     * else `INSERTION`, `DELETION` or `FORMATTING`.
+     */
+    get kind(): TrackedChangeKind;
+    /**
+     * The part the change's story is in (an extension; docx4j's `getPart()`, CR-011): the main document
+     * part, a header or footer part, the footnotes, endnotes or comments part. A text box's change gives
+     * the part the text box is in.
+     */
+    get part(): XmlPart<unknown> | undefined;
+    /**
+     * The single changes this one groups, in document order (an extension; docx4j's `getPieces()`,
+     * CR-011); a change that is no group is its own one piece. A filter's conditions are met or not by
+     * each piece, and each can be accepted or rejected on its own.
+     */
+    get pieces(): readonly TrackedChange[];
     /** The markup this change is over (an extension): the `w:ins` element, the `w:rPrChange`, ... */
     get element(): object;
     /** The text the change covers; `\r` for a paragraph mark, as Office JS gives it (check 22). */
@@ -198,14 +228,34 @@ export declare class TrackedChange {
     /**
      * Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs.
      * Either half of a move keeps the whole move, as Word's Review tab does (CR-002 section 29).
+     *
+     * Returns whether it acted: false, changing nothing, when the change has been resolved since it was
+     * listed (CR-002 section 53). An extension: Office JS's `accept()` returns nothing.
+     */
+    accept(): boolean;
+    /**
+     * The change's twins resolved the same way: the changes in the other branches of the kept
+     * `mc:AlternateContent` this one was listed from, paired with it by kind and position (`pairTwins`,
+     * docx4j's; CR-013 phase 3), each with its own twins. A group's twins are its pieces', which its
+     * pieces resolve. A twin resolved since it was listed is passed over.
      */
-    accept(): void;
+    private resolveTwins;
     private acceptHere;
     /**
      * Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied.
      * Either half of a move rejects the whole move, as Word's Review tab does (CR-002 section 29).
+     *
+     * Returns whether it acted, as `accept()` does.
      */
-    reject(): void;
+    reject(): boolean;
+    /**
+     * Whether the record this view was listed for, `target.value`, is still where it was listed. A view
+     * whose change has been resolved since, by itself or by another verb, does nothing; otherwise it
+     * would act on what stands there now (CR-002 section 53). The record is compared by identity. docx4j's
+     * views throw instead, once any change on the package has been resolved since they were listed; that
+     * would stop a loop resolving one listing last first, as `Body.acceptAll` does.
+     */
+    private isCurrent;
     private rejectHere;
     /** The body the change is in. */
     private get body_();
@@ -213,6 +263,12 @@ export declare class TrackedChange {
     private get package_();
     private requireParagraph;
 }
+/**
+ * A group's pieces resolved: its runs last first, then its marks last first, so that a paragraph join
+ * never strands a piece still to do. Office JS and Word's Review tab resolve the group as one (checks
+ * 22 and 23), and so, piece by piece, does this.
+ */
+export declare function resolvePieces(pieces: readonly TrackedChange[], what: 'accept' | 'reject'): void;
 /** The ids of the footnotes and endnotes whose references removed content took with it. */
 export interface NoteRemovals {
     footnote: Set<number>;
@@ -238,10 +294,26 @@ export interface NoteRemovals {
  *   goes when nothing left in the part references it; its part goes when no relationship in the package
  *   targets it any more, and what that part alone related to goes with it. The kinds beyond pictures,
  *   headers and footers (charts, OLE objects, `v:imagedata`) are docx4j's reading, not measured.
+ * - **Comments**: a comment `removeRevision` left with its range's start and end in different paragraphs
+ *   goes whole when the joins have brought them into one list with nothing with text between
+ *   (`settleSpanningComments`; CR-002 section 54).
  * A change resolved inside another's (a row's cells, a group's pieces, `acceptAll`'s changes) shares the
  * outer resolution, so the bookmarks are read twice for the lot, and not at all when nothing is removed.
  */
 export declare function resolving(pkg: unknown, body: Body | undefined, resolve: () => void): void;
+/**
+ * Queues the notes whose references `removed` holds to go when the package is saved, as a resolution's
+ * removals go: what a range deleted untracked takes with it (CR-014 phase 2; check 52 case 12, where Word took
+ * the footnote out of `footnotes.xml` with its reference). A note goes only where no reference to it stands
+ * by then (`flushPendingNoteRemovals`), so content queued and then kept costs nothing.
+ */
+export declare function queueNoteRemovals(pkg: unknown, removed: unknown): void;
+/**
+ * The notes `pending` holds that `flushPendingNoteRemovals` will take away: those whose reference no
+ * longer stands in the main document's tree. A listing of every story leaves them out, as docx4j's,
+ * which removes them when its resolution ends, does (CR-011).
+ */
+export declare function notesGoing(mainTree: unknown, pending: NoteRemovals): NoteRemovals;
 /** What `flushPendingNoteRemovals` needs of the main document part. */
 interface NotesHost {
     getContents(): Promise<unknown>;
@@ -270,13 +342,16 @@ interface NoteRemovalHost {
  * was in it is queued for removal, its anchor being gone.
  */
 export declare function flushPendingNoteRemovals(main: NotesHost, pending: NoteRemovals, host?: NoteRemovalHost): Promise<void>;
+/** Adds the ids of the `w:commentReference` elements anywhere in a tree to `into`. */
+export declare function commentReferencesIn(tree: unknown, into: Set<number>): void;
 /**
  * The insertion of a content control or custom XML element, when `items[i]` is a
  * `w:customXmlInsRangeStart` and what follows is Word's form for one (check 30): the element, whose
  * content starts with that marker's `w:customXmlInsRangeEnd` and ends with a second start, and that
- * one's end right after the element. Anything else is not one (a marker on its own is left alone).
+ * one's end right after the element; or its deletion, the same form of `w:customXmlDelRangeStart` and
+ * `End` (check 54). Anything else is not one (a marker on its own is left alone).
  */
-export declare function holderInsertionAt(items: Element[], i: number, paragraph: Paragraph | undefined): TrackedChange | undefined;
+export declare function holderChangeAt(items: Element[], i: number, paragraph: Paragraph | undefined, body?: Body): TrackedChange | undefined;
 /**
  * Word's form for a field inserted under tracking, when `items[i]` starts it: a `w:ins` that opens a
  * field (a `w:fldChar` begin it does not end), then plain runs - the separator and the result - and
@@ -293,10 +368,64 @@ export declare function insertedFieldAt(items: Element[], i: number, paragraph:
  *
  * `fallbackToPrevious` is for the second case at the end of a container, where this package's
  * inserted paragraph carries its own mark (section 13) and there is nothing after it to join
- * with: the paragraph then goes, its content joining the one before. With neither neighbour the
- * mark is simply dropped.
+ * with: the paragraph then goes, its content joining the one before. Otherwise, with no paragraph
+ * next, a join never crosses a container's edge, and Word 365's Accept All (check 54 and the text-left
+ * probe, docx4j CR-043 section 17) does one of four things: an emptied paragraph with a table or a
+ * block control next goes; text left with a table next joins the table's first cell's first paragraph,
+ * which keeps its properties; with a block control next it takes the control's first paragraph's
+ * properties, nothing joined; a control's last paragraph keeps a bare mark. Else the mark is only dropped.
  */
 export declare function joinWithNext(paragraph: Pick<Paragraph, 'container' | 'element' | 'p'>, fallbackToPrevious?: boolean): void;
+/** The first paragraph of a table's first cell, where a paragraph joining into the table lands; docx4j's `firstCellParagraph`. */
+export declare function firstCellParagraphOf(tbl: wml.Tbl): wml.P | undefined;
+/**
+ * One piece of a move's markup, in document order: a range marker, a run-level half (`w:moveFrom`
+ * or `w:moveTo` around runs), or a moved paragraph's mark (`w:pPr/w:rPr/w:moveFrom` or `w:moveTo`).
+ */
+export type MovePiece = {
+    kind: 'start';
+    side: 'from' | 'to';
+    id: number;
+    name: string;
+    element: Element;
+    owner: Element[];
+} | {
+    kind: 'end';
+    side: 'from' | 'to';
+    id: number;
+    element: Element;
+    owner: Element[];
+} | {
+    kind: 'half';
+    side: 'from' | 'to';
+    element: Element;
+    owner: Element[];
+    names: string[];
+} | {
+    kind: 'mark';
+    side: 'from' | 'to';
+    paragraph: Element<wml.P>;
+    container: Element[];
+    names: string[];
+}
+/** Anything else directly in a paragraph while a range is open: text typed into moved text, say. */
+ | {
+    kind: 'inner';
+    side: 'from' | 'to';
+    element: Element;
+    owner: Element[];
+    names: string[];
+};
+/**
+ * The story a paragraph is in, for its moves: the outermost array of block content above it (a body, a
+ * header, a note). A kept `mc:AlternateContent`'s selected branch is part of the story it stands in, as
+ * Word reads it; another branch is a story of its own, its list (docx4j's twin stories, its CR-051 phase
+ * 2; CR-013 phase 3), so a move is paired within the branch. `value` may be the paragraph or anything in
+ * it, a run-level branch's revision among them.
+ */
+export declare function storyOf(value: object): Element[];
+/** Every piece of move markup in a story, in document order, each half and mark with the names of the ranges open over it. */
+export declare function movePiecesOf(story: Element[]): MovePiece[];
 /**
  * The tracked changes of one paragraph, in document order, touching pieces grouped as Office JS
  * groups them (`groupTouching`). Office JS lists the changes that start in the paragraph (check 22):
@@ -307,11 +436,40 @@ export declare function trackedChangesOfParagraph(paragraph: Paragraph): Tracked
 /** Between two tracked changes: something unrevised - text, a paragraph mark, a table - that keeps them apart. */
 export declare const BREAK: "break";
 export type TrackedChangeToken = TrackedChange | typeof BREAK;
+/**
+ * How a listing takes the branches of a kept `mc:AlternateContent` (CR-013 phase 3), docx4j's two
+ * `Lister`s: `'listed'`, the public listing, lists the selected branch's changes where the element stands
+ * and pairs each other branch's with them as twins (`pairTwins`), so that resolving a listed change
+ * resolves its twins; `'every'`, resolve-all's, lists every other branch's changes on their own, into
+ * `extra`, which the caller puts after the story's, so that each is resolved, matched by a filter on its
+ * own, and the selected branch's grouping is the public listing's.
+ */
+export interface Listing {
+    mode: 'listed' | 'every';
+    extra: TrackedChangeToken[];
+}
+/** The public listing's (`Listing`). */
+export declare function listedListing(): Listing;
+/**
+ * A kept `mc:AlternateContent`'s changes: its selected branch's into `into`, as Word reads them, keeping
+ * nothing apart (CR-013 phase 2); each other branch's paired with them as twins or, resolve-all's,
+ * listed on their own after the story's (`Listing`). `visit` lists one branch's items, at the element's
+ * level (blocks, rows, cells or runs).
+ */
+export declare function alternateTokens(ac: mce.AlternateContent, visit: (items: Element[], into: TrackedChangeToken[]) => void, into: TrackedChangeToken[], listing: Listing): void;
+/**
+ * Another branch's changes attached to the listed branch's as twins, piece by piece: the n-th single
+ * change of a kind with the n-th of that kind, never by id, as docx4j pairs a text box's `mc:Fallback`
+ * changes and a branch's (its `Lister.pairTwins`; Word gives twins different ids). docx4j pairs the
+ * listed changes, groups included; pieces are paired here, since this listing groups the selected
+ * branch's with what touches the element, so a piece resolved on its own resolves its twin too.
+ */
+export declare function pairTwins(primary: readonly TrackedChangeToken[], twins: readonly TrackedChangeToken[]): void;
 /**
  * A paragraph's single changes in document order, its mark last, with a `BREAK` wherever unrevised
  * content stands between two of them: `groupTouching` makes the groups from these.
  */
-export declare function trackedChangeTokensOfParagraph(paragraph: Paragraph): TrackedChangeToken[];
+export declare function trackedChangeTokensOfParagraph(paragraph: Paragraph, listing?: Listing): TrackedChangeToken[];
 /**
  * Tokens made into the changes Office JS lists: consecutive pieces of one kind (inserted, deleted, or
  * a run's formatting) by one author, nothing unrevised between them, are one change (checks 22, 23
@@ -327,21 +485,22 @@ export declare function groupTouching(tokens: TrackedChangeToken[]): TrackedChan
  */
 export declare function trackedChangesOfRow(tr: Element<wml.Tr>, owner: Element[], inner?: TrackedChange[], table?: Located<wml.Tbl>, body?: Body): TrackedChange[];
 /** The change a table's property records make, one per table, or undefined when they make none. */
-export declare function tablePropertiesChangeOf(tbl: Element<wml.Tbl>): TrackedChange | undefined;
+export declare function tablePropertiesChangeOf(tbl: Element<wml.Tbl>, body?: Body): TrackedChange | undefined;
 /** A cell's own revision, `w:cellIns` or `w:cellDel`, or undefined. */
 export declare function cellChangeOf(tc: Element<wml.Tc>, owner: Element[], tr: wml.Tr, body?: Body): TrackedChange | undefined;
 /** The change to the body's last section (`w:body/w:sectPr/w:sectPrChange`), its text the section's paragraphs'. */
 export declare function bodySectionChangeOf(container: {
     content?: Element[];
     sectPr?: wml.SectPr;
-}): TrackedChange | undefined;
+}, body?: Body): TrackedChange | undefined;
 /**
  * What `acceptAll` and `rejectAll` resolve that is never listed: a `w:cellMerge`, which Office JS
  * cannot list (check 27: `getTrackedChanges` throws); a `w:numberingChange`, which Word no longer
  * writes and drops when one is put in, and whose record is the old number's text, so that a reject
  * too can only drop it; and a table's records that change nothing. A merge rejected gets the merge it
  * recorded back (docx4j's reading; unmeasured). A `w:customXmlInsRangeStart` or `End` left without
- * the form `holderInsertionAt` lists marks nothing that can be found, and goes either way.
+ * the form `holderChangeAt` lists marks nothing that can be found, and goes either way. Every branch
+ * of a kept `mc:AlternateContent` at block, row and cell level is swept (CR-013 phase 3).
  */
 export declare function resolveUnlisted(items: Element[], what: 'accept' | 'reject'): void;
 export {};