@docx4j/core-ts 0.2.2 → 0.3.1

package/dist/model/content/ContentControl.mjs

@@ -7,8 +7,8 @@ import { marshalString, deepCopy } from '@docx4j/generated-objects-ts';
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKBOX_FONT, } from '../customxml/kinds.mjs';
 import { runsForValue, updateFromControl, PLACEHOLDER_TEXT } from '../customxml/bindings.mjs';
-import { sdtProperty, sdtKindOf } from '@docx4j/generated-objects-ts/builders/wml';
-import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, SDT_TYPES } from './tree.mjs';
+import { sdtProperty, sdtKindOf, t as textItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, runOf, SDT_TYPES } from './tree.mjs';
 import { Range } from './Range.mjs';
 import { Table } from './Table.mjs';
 /** The namespaces of the Word 2010 and 2012 content-control properties. */
@@ -128,6 +128,8 @@ export class ContentControl {
         if (!span)
             throw new Docx4JException('This content control is not in a paragraph');
         const { paragraph, start, end } = span;
+        if (span.empty)
+            return this.insertIntoEmpty(paragraph, text);
         if (location === 'Start')
             return paragraph.splice(start, start, text);
         if (location === 'End')
@@ -251,7 +253,8 @@ export class ContentControl {
         };
         let start;
         let end = 0;
-        for (const seg of segmentsOf(paragraph.p)) {
+        const segs = segmentsOf(paragraph.p);
+        for (const seg of segs) {
             if (!inside(seg.run))
                 continue;
             if (start === undefined)
@@ -259,11 +262,54 @@ export class ContentControl {
             end = seg.end;
         }
         if (start === undefined) {
-            // an empty control: its position is where its runs would be
-            return { paragraph, start: 0, end: 0 };
+            // a control holding no text: its position is the end of the last text before it in the
+            // paragraph (before, it was reported at 0, and text put into it went to the paragraph's start)
+            let pos = 0;
+            let found = false;
+            const visit = (items) => {
+                for (const el of items !== null && items !== void 0 ? items : []) {
+                    if (found)
+                        return;
+                    if (el === this.element) {
+                        found = true;
+                        return;
+                    }
+                    const v = el.value;
+                    if (typeof v !== 'object' || v === null)
+                        continue;
+                    if (typeNameOf(el) === 'org_docx4j_wml.R') {
+                        const last = segs.filter((seg) => seg.run === v).pop();
+                        if (last)
+                            pos = last.end;
+                    }
+                    else
+                        visit(runItemsOf(v));
+                }
+            };
+            visit(paragraph.p.content);
+            return { paragraph, start: pos, end: pos, empty: true };
         }
         return { paragraph, start, end };
     }
+    /**
+     * Text into a run control that holds no run: a new run in its content, in a `w:ins` under
+     * tracking (Word: check 30, new-control-typed), placed before the control's trailing insertion
+     * marker when it is itself an insertion.
+     */
+    insertIntoEmpty(paragraph, text) {
+        var _a, _b;
+        var _c;
+        const sdt = this.sdt;
+        const items = ((_b = (_c = ((_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {}))).content) !== null && _b !== void 0 ? _b : (_c.content = []));
+        const run = runOf([textItem(text)]);
+        const tracker = paragraph.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
+        const at = items.findIndex((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'customXmlInsRangeStart'; });
+        items.splice(at < 0 ? items.length : at, 0, item);
+        linkParents(item, sdt.sdtContent);
+        const span = this.runSpan();
+        return new Range(paragraph, span.start, span.end);
+    }
     // --- CR-002 phase E: the XML mapping, the typed kinds and the w:sdtPr properties ---
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping() {

package/dist/model/content/Font.mjs

@@ -49,6 +49,8 @@ export class Font {
             if (tracking && !tracking.ownInsertions.has(h))
                 tracking.tracker.recordRPrChange(h.rPr);
             applyRunOptions(h.rPr, opts);
+            if (tracking)
+                tracking.tracker.settleRPrChange(h);
         }
     }
     get bold() { return this.read().bold; }

package/dist/model/content/List.mjs

@@ -511,6 +511,7 @@ export class ListItem {
         }
         numPr.ilvl = f.createPPrBaseNumPrIlvl({ val: value });
         linkParents(numPr.ilvl, numPr);
+        this.paragraph.settleFormatting();
     }
     /**
      * Office JS `listItem.listString`: the label Word paints in front of the paragraph.
@@ -628,6 +629,7 @@ export function attachToList(paragraph, listId, level = 0) {
     numPr.numId = f.createPPrBaseNumPrNumId({ val: Number(listId) });
     numPr.ilvl = f.createPPrBaseNumPrIlvl({ val: level });
     linkParents(numPr, paragraph.p.pPr);
+    paragraph.settleFormatting();
     return new List(String(listId), paragraph.parentBody);
 }
 /**
@@ -640,12 +642,13 @@ export function detachFromList(paragraph) {
     if (((_a = paragraph.p.pPr) === null || _a === void 0 ? void 0 : _a.numPr) !== undefined) {
         delete paragraph.pPr().numPr;
     }
-    if (!isListItem(paragraph))
-        return;
-    const numPr = paragraph.numPr();
-    numPr.numId = f.createPPrBaseNumPrNumId({ val: 0 });
-    linkParents(numPr.numId, numPr);
-    delete numPr.ilvl;
+    if (isListItem(paragraph)) {
+        const numPr = paragraph.numPr();
+        numPr.numId = f.createPPrBaseNumPrNumId({ val: 0 });
+        linkParents(numPr.numId, numPr);
+        delete numPr.ilvl;
+    }
+    paragraph.settleFormatting();
 }
 /**
  * Office JS `paragraph.startNewList()`: a `w:abstractNum` copied from docx4j's default

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

@@ -9,7 +9,7 @@ import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
 import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
-import { type ChangeTracker } from './tracking.mjs';
+import { ChangeTracker } from './tracking.mjs';
 import { TrackedChange } from './TrackedChange.mjs';
 import { type List, type ListItem, type StartListOptions } from './List.mjs';
 /**
@@ -106,6 +106,15 @@ export declare class Paragraph {
     /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     get alignment(): Alignment;
     set alignment(v: AlignmentOrUnknown);
+    /**
+     * The alignment the paragraph resolves to with no `w:jc` of its own: its style's, else the
+     * defaults'. Word's Ctrl+L on a centred paragraph whose style is left-aligned removes the `w:jc`
+     * rather than writing `w:jc="left"`, with tracking on (check 26) and off (the editor's
+     * `measure-word2010.docx` and `measure-word15.docx`, 2026-09-30; CR-002 section 38), so a value the
+     * paragraph already inherits is not written. Measured for left over a left-aligned style; taken to
+     * hold for any value. Undefined without a resolver, where the value is written as asked.
+     */
+    private inheritedAlignment;
     /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent(): number;
     set leftIndent(pt: number);
@@ -186,6 +195,17 @@ export declare class Paragraph {
      */
     delete(): void;
     private trackedDelete;
+    /**
+     * A paragraph mark deleted under tracking gives the next paragraph this paragraph's properties,
+     * as a `w:pPrChange` on it recording its own: Word, at Delete at the end of a Heading 2 with a
+     * Normal paragraph after it, wrote the next paragraph `w:pStyle Heading2` with
+     * `<w:pPrChange><w:pPr/></w:pPrChange>`, and No Markup reads the joined line as a heading
+     * throughout (the editor's `measure-word15.docx`, 2026-09-30; CR-002 section 38). The Delete
+     * counterpart of check 29's Enter. Nothing where the two paragraphs' properties are the same
+     * (check 22's deleted marks). Accepting the mark then joins into a paragraph with these
+     * properties, and rejecting puts the next paragraph's back.
+     */
+    private giveMarkPropertiesToNext;
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
      * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word
@@ -206,6 +226,20 @@ export declare class Paragraph {
      * @internal public so that the list views (CR-002 phase H) write `w:numPr` the same way.
      */
     pPr(): wml.PPr;
+    /**
+     * After a tracked write of the paragraph's properties: when the paragraph is as it was, its
+     * recorded properties go back as they were and the `w:pPrChange` goes, since Word keeps no
+     * formatting change that changes nothing, whoever changed it back (`test/README.md` check 26:
+     * centred then left again, by the same author and by another; Increase Indent then Decrease
+     * Indent; each left no `w:pPr`; CR-002 section 29). "As it was" is Office JS's paragraph
+     * formatting (alignment, indents, spacing, outline level) read resolved from both, the rest of the
+     * properties - the style, the list - written the same: Word's Ctrl+L and Decrease Indent removed
+     * the direct values where this package's setters write `w:jc="left"` and `w:ind w:left="0"`.
+     * Without the package's `PropertyResolver` only properties written the same count.
+     *
+     * @internal public so that the list views (CR-002 phase H) settle their `w:numPr` writes.
+     */
+    settleFormatting(): void;
     /**
      * The paragraph's `w:numPr`, created when absent, through {@link pPr} so that a tracked
      * write records `w:pPrChange` first.
@@ -227,7 +261,7 @@ export declare class Paragraph {
      * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
      * else into a new run with the formatting of the nearest run.
      */
-    splice(start: number, end: number, text: string): Range;
+    splice(start: number, end: number, text: string, prefer?: 'before' | 'after'): Range;
     /**
      * Inserts run-level items (runs, hyperlinks, content controls) at a text offset, splitting the
      * run there when the offset falls inside one. PARENT is linked on what is inserted.
@@ -286,12 +320,47 @@ export declare class Paragraph {
      * Returns the `w:del` elements it made, in document order.
      */
     private deleteText;
+    /**
+     * Splits the revision that holds the text at `at` into two - the second half a copy of its
+     * attributes under a new `w:id` - and puts `item` between them. Word splits a revision so when
+     * text is typed inside it: around the typist's `w:ins` with tracking on, around plain text with it
+     * off (`test/README.md` checks 20 and 21). False, with nothing changed but a run split at `at`,
+     * where the text there is not directly in the revision (in a hyperlink inside it, say): the caller
+     * then does what it did before.
+     */
+    private insertBetweenHalves;
+    /**
+     * Moves a revision's items from `index` on into a copy of it - its attributes, a new `w:id` - and
+     * puts `item` between the two; with nothing from `index` on, `item` just goes after the revision.
+     * False, with nothing changed, where the revision's items cannot be told apart from its attributes.
+     * Internal: `Range.insertContentControl` uses it to put a new control between the halves of the
+     * insertion it wraps part of (check 30).
+     */
+    splitHolderAround(holder: RevisionHolderOf, index: number, item: Element | Element[], nextId: () => number): boolean;
+    /**
+     * Puts `item` beside a revision rather than in it: after it, or before it - and then before the
+     * range start of a move whose range opens just there, so that text typed at the start of moved
+     * text is not inside the move (`test/README.md` check 20 case 03).
+     */
+    private insertBesideRevision;
+    /**
+     * A fresh annotation id for markup this paragraph writes itself: the package's counter when there
+     * is a package that keeps one, since a document has one id space; else one above every id in the
+     * story.
+     */
+    /** @internal `Comment` uses it to split an insertion at a comment's end. */
+    nextAnnotationId(): number;
     /**
      * Text inserted at `at` as a `w:ins`. A run of this author's own that is already inside a
      * `w:ins` is extended rather than nested in another one, as Word does. `anchor` is the `w:del`
      * of a replacement, which the insertion must follow.
      */
     private insertTracked;
+    /**
+     * An insertion put at `at`, `before` and `after` being the segments either side of it once the runs
+     * are split there: never inside another's revision.
+     */
+    private placeInsertion;
     /**
      * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
      * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
@@ -303,4 +372,5 @@ export declare class Paragraph {
     /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
     private splitRunAfter;
 }
+type RevisionHolderOf = NonNullable<TextSegment['revision']>;
 export { W_NS };