@docx4j/core-ts 0.2.1 → 0.3.0

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

@@ -44,6 +44,54 @@ export type TrackedChangeTarget =
     owner: Element[];
     value: wml.CTTrackChange;
     inner: TrackedChange[];
+}
+/**
+ * Touching insertions, deletions or formatting changes by one author - `w:ins` or `w:del` around
+ * runs and inserted or deleted paragraph marks, or runs' `w:rPrChange`, with nothing unrevised
+ * between them - which Office JS lists as one change (CR-002 section 29, checks 22, 23 and 28): a
+ * deleted paragraph's text and mark, a deletion across a mark, bold put on two runs of different
+ * formatting. `pieces` are the single changes, in document order; `value` is the first's.
+ */
+ | {
+    kind: 'group';
+    revision: 'ins' | 'del' | 'format';
+    pieces: TrackedChange[];
+    value: wml.CTTrackChange;
+}
+/**
+ * A table's property records - `w:tblPrChange`, `w:tblGridChange`, `w:tblPrExChange`, and every
+ * `w:trPrChange` and `w:tcPrChange` in it - which Word writes as one set for one change and Office
+ * JS lists as one `Formatted` change (CR-002 section 35, checks 27 and 28). `value` is the table's
+ * record, else the first row's or cell's.
+ */
+ | {
+    kind: 'tableProperties';
+    tbl: Element<wml.Tbl>;
+    value: wml.CTTrackChange;
+}
+/** `w:tcPr/w:cellIns` or `w:tcPr/w:cellDel`: an inserted or deleted cell (section 35, check 27). */
+ | {
+    kind: 'cell';
+    cell: 'ins' | 'del';
+    tc: Element<wml.Tc>;
+    owner: Element[];
+    tr: wml.Tr;
+    value: wml.CTTrackChange;
+}
+/** `w:pPr/w:rPr/w:rPrChange`: a paragraph mark's formatting, which groups with its runs' (check 27). */
+ | {
+    kind: 'markProperties';
+    value: wml.ParaRPrChange;
+}
+/**
+ * `w:sectPr/w:sectPrChange`: a section's properties, at a paragraph's section break or the body's
+ * last section. `text` is the section's, as Office JS reports it (check 27: the text, then `\f`).
+ */
+ | {
+    kind: 'sectionProperties';
+    sectPr: wml.SectPr;
+    value: wml.CTSectPrChange;
+    text: string;
 };
 /**
  * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
@@ -60,19 +108,29 @@ export declare class TrackedChange {
     /** Office JS `Word.ChangeTrackingState`. */
     get type(): TrackedChangeType;
     get author(): string;
-    /** `w:date`, when the markup carries one. */
+    /**
+     * When the change was made: `w16du:dateUtc` if the markup has it, else `w:date` read as Word writes
+     * it, local wall-clock time (`revisionDateOf`, CR-002 section 29); a group's is its first piece's,
+     * as Office JS reports it.
+     */
     get date(): Date | undefined;
     /** The annotation id (`w:id`; an extension). */
     get id(): number;
     /** The markup this change is over (an extension): the `w:ins` element, the `w:rPrChange`, ... */
     get element(): object;
-    /** The text the change covers; '' for a paragraph mark, whose range is the paragraph. */
+    /** The text the change covers; `\r` for a paragraph mark, as Office JS gives it (check 22). */
     get text(): string;
     /** The range the change covers; a deletion is a collapsed range where it sits in the accepted text. */
     getRange(): Range | undefined;
-    /** Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs. */
+    /**
+     * 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).
+     */
     accept(): void;
-    /** Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied. */
+    /**
+     * 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 requireParagraph;
 }
@@ -86,11 +144,50 @@ export declare class TrackedChange {
  * with: the paragraph then goes, its content joining the one before. With neither neighbour the
  * mark is simply dropped.
  */
-export declare function joinWithNext(paragraph: Paragraph, fallbackToPrevious?: boolean): void;
-/** The tracked changes of one paragraph, in document order. */
+export declare function joinWithNext(paragraph: Pick<Paragraph, 'container' | 'element' | 'p'>, fallbackToPrevious?: boolean): void;
+/**
+ * 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):
+ * pieces that carry on a change from the paragraph before - its inserted or deleted mark - are left
+ * to that paragraph, and a change running on into the next is cut at this paragraph's end.
+ */
 export declare function trackedChangesOfParagraph(paragraph: Paragraph): TrackedChange[];
+/** 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;
+/**
+ * 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[];
+/**
+ * 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
+ * and 28: text and marks alike, dates regardless, formatting whatever it recorded; another author, or
+ * one kind against another, starts a new one). A change that does not group - a paragraph's
+ * properties, a move - is listed where it stands and does not break a group. A group of one piece is
+ * that piece.
+ */
+export declare function groupTouching(tokens: TrackedChangeToken[]): TrackedChange[];
 /**
  * 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[]): 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;
+/** 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;
+/**
+ * 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).
+ */
+export declare function resolveUnlisted(items: Element[], what: 'accept' | 'reject'): void;