@docx4j/core-ts 0.3.2 → 0.5.0

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

@@ -1,7 +1,11 @@
 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 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 RelationshipRemovals } from './relationships.mjs';
 /** Office JS `Word.ChangeTrackingState` (`Unknown` is not produced here). */
 export type TrackedChangeType = 'Added' | 'Deleted' | 'Formatted' | 'None' | 'Unknown';
 /** Which piece of revision markup a `TrackedChange` is over (an extension: Office JS has no such member). */
@@ -112,6 +116,51 @@ export type TrackedChangeTarget =
     outer: [Element, Element];
     inner: [Element, Element];
     value: wml.CTTrackChange;
+}
+/**
+ * A field Word inserted under tracking, in its own form: a `w:ins` around the field's begin and
+ * instruction runs and another around its end, the separator and the result between them plain
+ * (check 30, `field-inserted`). Office JS lists it as one `Added` change whose text is the result's,
+ * and Word's Reject All took the whole field away, the result with it (CR-002 section 44). `span` is
+ * the items of `owner` from the first `w:ins` to the last.
+ */
+ | {
+    kind: 'field';
+    span: Element[];
+    owner: Element[];
+    value: wml.CTTrackChange;
+}
+/**
+ * A `w:ins` or `w:del` inside an `m:r`, which is where Word writes an equation's text inserted or
+ * deleted (`m:r` > `w:ins` > `m:rPr`, `w:rPr`, `m:t`; docx4j's `tracked-changes-equations.docx`).
+ * `item` is the `w:ins` or `w:del` in the run's content, `run` the `m:r` and `runOwner` its list.
+ * Kept, its content takes its place in the run; not kept, it goes, and a run left with no text with it
+ * (CR-002 section 51). `equation` is the `m:oMath` or `m:oMathPara` in the paragraph that holds it.
+ */
+ | {
+    kind: 'mathRun';
+    revision: 'ins' | 'del';
+    item: Element;
+    run: Element<math.CTR>;
+    runOwner: Element[];
+    value: wml.CTMathRunTrackChange;
+    equation?: Element;
+}
+/**
+ * A `w:ins` or `w:del` in an equation structure's `m:ctrlPr`, Word's mark of an `m:sSup`, an `m:acc`,
+ * ... inserted or deleted as a whole. `structure` is that element and `owner` its list, two up from
+ * the `m:ctrlPr`; undefined for an argument's own `m:ctrlPr` (an `m:e`'s), which marks no structure.
+ * Kept, the marker goes and the run properties it recorded become the control's; not kept, the
+ * structure goes whole, as Word's Accept All and Reject All did (CR-002 section 51).
+ */
+ | {
+    kind: 'mathStructure';
+    revision: 'ins' | 'del';
+    ctrlPr: math.CTCtrlPr;
+    structure?: Element;
+    owner?: Element[];
+    value: wml.CTRPrChange;
+    equation?: Element;
 };
 /**
  * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
@@ -122,9 +171,13 @@ export declare class TrackedChange {
     readonly target: TrackedChangeTarget;
     /** The paragraph the change is in; undefined for a row revision. */
     readonly paragraph: Paragraph | undefined;
+    /** The body a change without a paragraph (a row, a cell) is in, for the notes it may take away. */
+    readonly body?: Body | undefined;
     constructor(target: TrackedChangeTarget, 
     /** The paragraph the change is in; undefined for a row revision. */
-    paragraph: Paragraph | undefined);
+    paragraph: Paragraph | undefined, 
+    /** The body a change without a paragraph (a row, a cell) is in, for the notes it may take away. */
+    body?: Body | undefined);
     /** Office JS `Word.ChangeTrackingState`. */
     get type(): TrackedChangeType;
     get author(): string;
@@ -147,13 +200,76 @@ export declare class TrackedChange {
      * Either half of a move keeps the whole move, as Word's Review tab does (CR-002 section 29).
      */
     accept(): void;
+    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).
      */
     reject(): void;
+    private rejectHere;
+    /** The body the change is in. */
+    private get body_();
+    /** The package the change is in, which keeps the notes whose references it took away. */
+    private get package_();
     private requireParagraph;
 }
+/** The ids of the footnotes and endnotes whose references removed content took with it. */
+export interface NoteRemovals {
+    footnote: Set<number>;
+    endnote: Set<number>;
+}
+/**
+ * Runs `resolve`, then takes away what went with the content it removed:
+ * - **Notes**: Word took a footnote from the notes part when its reference went with the content
+ *   around it, accepting a deletion and rejecting an insertion alike (the editor's `review-for-word`
+ *   saves, Word 15 and Word 2010); the entries go when the package is saved
+ *   (`WordprocessingMLPackage.pendingNoteRemovals`).
+ * - **Bookmarks**: Word removed a bookmark whole when its end went with a deletion it accepted, and
+ *   when the insertion it was put around went with a reject (docx4j CR-043's probe, C11 and C11b, Word
+ *   16.0.20326). docx4j's rule from the two (its CR-043 section 3.2) is followed here: a bookmark with a
+ *   marker in removed content goes whole, its other marker too, even with content left beside it; so
+ *   does one with content between its markers that is left with none, a deletion it was around accepted
+ *   among them (U15); and one that was empty before, as `_GoBack` is, stays. Those three are not measured.
+ * - **Relationships and parts**: Word's saves kept no part the resolved content alone referenced. A
+ *   picture deleted and accepted, or inserted and rejected, took its image part (docx4j CR-043's probe,
+ *   C05 and C04), and a section break deleted and accepted took the headers and footers of the section
+ *   it ended (C06: six of each became three). docx4j's rule (its CR-043 section 3.2, D7) is followed: a
+ *   relationship of the change's part that the removed content referenced, through any `r:` attribute,
+ *   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.
+ * 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;
+/** What `flushPendingNoteRemovals` needs of the main document part. */
+interface NotesHost {
+    getContents(): Promise<unknown>;
+    footnotesPart?: Part & {
+        getContents(): Promise<wml.CTFootnotes>;
+    };
+    endnotesPart?: Part & {
+        getContents(): Promise<wml.CTEndnotes>;
+    };
+}
+/** Where a removed note's own content goes on to: the package's queues (`WordprocessingMLPackage`). */
+interface NoteRemovalHost {
+    pendingCommentRemovals?: Set<number>;
+    pendingRelationshipRemovals?: RelationshipRemovals;
+}
+/**
+ * The notes `pending` holds taken out of the notes parts, each unless a reference to it still stands in
+ * the main document (an accepted move keeps the reference its source had, say); then `pending` is
+ * empty. A note's entry goes, Word's separators never: their ids are never referenced. The notes parts
+ * are read only when something is pending, so a save with none leaves them untouched. Word's own save
+ * also renumbers the notes left (the editor's `review-for-word` saves); their ids stay here.
+ *
+ * What a removed note held goes on with it, as docx4j's `Removals.flush` takes it (CR-002 section 50,
+ * docx4j's reading, not measured): the relationships its content referenced (a picture's image) are
+ * queued on `host` for the notes part, to go when nothing else uses them, and a comment whose reference
+ * was in it is queued for removal, its anchor being gone.
+ */
+export declare function flushPendingNoteRemovals(main: NotesHost, pending: NoteRemovals, host?: NoteRemovalHost): Promise<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
@@ -161,6 +277,15 @@ export declare class TrackedChange {
  * one's end right after the element. 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;
+/**
+ * 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
+ * markers, then a `w:ins` by the same author in which that field ends (check 30, `field-inserted`:
+ * begin and instruction in one, the end run in the other). Another revision, a run whose formatting
+ * changed, a run holder, or a field that ends in a plain run is not this form, and is listed as before.
+ * A field wholly inside one `w:ins` needs nothing of this: that `w:ins` already takes it whole.
+ */
+export declare function insertedFieldAt(items: Element[], i: number, paragraph: Paragraph | undefined): TrackedChange | undefined;
 /**
  * docx4j AcceptTrackedChanges: the paragraph takes the next one's content and properties, so the
  * mark that survives is the next one's. Called when a deleted mark is accepted and when an
@@ -200,11 +325,11 @@ export declare function groupTouching(tokens: TrackedChangeToken[]): TrackedChan
  * The `w:trPr/w:ins` and `w:trPr/w:del` revisions of a table row. `inner` is the revision markup
  * of the row's own cells, which the row's change owns rather than reporting separately.
  */
-export declare function trackedChangesOfRow(tr: Element<wml.Tr>, owner: Element[], inner?: TrackedChange[], table?: Located<wml.Tbl>): TrackedChange[];
+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;
 /** 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): TrackedChange | 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[];
@@ -219,3 +344,4 @@ export declare function bodySectionChangeOf(container: {
  * the form `holderInsertionAt` lists marks nothing that can be found, and goes either way.
  */
 export declare function resolveUnlisted(items: Element[], what: 'accept' | 'reject'): void;
+export {};