@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/content/search.mjs

@@ -1,4 +1,5 @@
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { NotSupportedError } from '../../office-js/errors.mjs';
 /** A regular expression for a search text under the options; global so it can iterate matches. */
 export function searchPattern(text, options = {}) {
     if (options.matchRegExp && options.matchWildcards) {
@@ -19,10 +20,17 @@ export function searchPattern(text, options = {}) {
         source = '';
         for (let i = 0; i < text.length; i++) {
             const c = text[i];
+            // a code point, a surrogate pair whole, as Word's ? matches an emoji (check 58 case 13; CR-002 section 32, K4);
+            // ? and * cross a paragraph's mark where a search reads one (`wildcardMatchesAcross`, check 59, K7)
             if (c === '?')
-                source += '.';
+                source += '(?:[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]|[\\s\\S])';
             else if (c === '*')
-                source += '.*?';
+                source += '[\\s\\S]*?';
+            // ^13, Word's wildcard code for a paragraph mark (check 59)
+            else if (c === '^' && text.startsWith('13', i + 1)) {
+                source += '\\r';
+                i += 2;
+            }
             else if (c === '<')
                 source += '\\b(?=\\w)';
             else if (c === '>')
@@ -143,3 +151,197 @@ export function expandReplacement(replacement, match, options = {}) {
     }
     return replacement;
 }
+/** The object replacement character: a picture's place in the text `search` reads, which `^g` matches. */
+const OBJECT = '';
+/**
+ * Word's Find codes a plain query may hold (check 48: each matched its character in Office JS's text):
+ * `^f` a footnote reference, `^e` an endnote reference, `^l` a line break, `^m` a page break, `^t` a tab,
+ * `^~` a non-breaking hyphen, `^-` an optional hyphen, `^g` a picture, `^^` a caret.
+ */
+const FIND_CODES = { f: '\u0002', e: '\u0002', l: '\u000B', m: '\u000C', t: '\t', '~': '\u001E', '-': '\u001F', g: OBJECT, '^': '^' };
+/**
+ * Every match of a query in a paragraph's text by Office JS's rules (check 48, Word's default view): the
+ * text is `Paragraph.text` (hidden text left out, so a query matches across it and never in it), where a
+ * picture is a place of no text that a plain query doesn't match across and `^g` matches, and an optional
+ * hyphen is passed over unless the query names it (`^-`). A plain query takes Word's Find codes
+ * (`FIND_CODES`), and its `-` matches a non-breaking hyphen too. Wildcards read the same text, the codes
+ * not translated; a regular expression (`matchRegExp`, this package's extension) reads `Paragraph.text`
+ * itself. Only text in [from, to) is read: a range's search.
+ */
+export function officeMatches(segments, query, options = {}, from = 0, to = Number.POSITIVE_INFINITY) {
+    const plain = !options.matchRegExp && !options.matchWildcards;
+    const keepSoftHyphens = !plain || /\^-/.test(query.replace(/\^\^/g, ''));
+    let pattern;
+    let tokens = [];
+    if (plain) {
+        const translated = plainQuery(query);
+        tokens = translated.tokens;
+        pattern = patternOf(translated.source, options);
+    }
+    else {
+        pattern = searchPattern(query, options);
+    }
+    // the usual paragraph: nothing but text, no optional hyphen to pass over, no reference a code must tell
+    // apart, so the text searched is Paragraph.text's own [from, to), each offset itself
+    if (segments.every((seg) => !seg.object && !seg.hidden) && tokens.every((kind) => kind === undefined)) {
+        const whole = segments.map((seg) => seg.text).join('');
+        const start = Math.max(0, from);
+        const span = whole.substring(start, Math.min(whole.length, to));
+        if (keepSoftHyphens || !span.includes('\u001F')) {
+            return matchesOf(span, pattern).map((match) => ({ start: start + match.index, end: start + match.index + match[0].length, match }));
+        }
+    }
+    let text = '';
+    const starts = [];
+    const ends = [];
+    const notes = [];
+    for (const seg of segments) {
+        if (seg.hidden)
+            continue;
+        if (seg.object) {
+            if (!options.matchRegExp && from < seg.start && seg.start < to) {
+                text += OBJECT;
+                starts.push(seg.start);
+                ends.push(seg.start);
+                notes.push(undefined);
+            }
+            continue;
+        }
+        for (let i = 0; i < seg.text.length; i++) {
+            const at = seg.start + i;
+            if (at < from || at >= to)
+                continue;
+            const c = seg.text[i];
+            if (c === '\u001F' && !keepSoftHyphens)
+                continue;
+            text += c;
+            starts.push(at);
+            ends.push(at + 1);
+            notes.push(c === '\u0002' ? seg.item.name.localPart : undefined);
+        }
+    }
+    const out = [];
+    for (const match of matchesOf(text, pattern)) {
+        const a = match.index;
+        const b = a + match[0].length;
+        // ^f and ^e both read U+0002: each matches only its own kind of reference
+        if (tokens.some((kind, i) => { var _a; return kind !== undefined && !((_a = notes[a + i]) !== null && _a !== void 0 ? _a : '').startsWith(kind); }))
+            continue;
+        out.push({ start: starts[a], end: ends[b - 1], match });
+    }
+    return out;
+}
+/**
+ * A wildcard query's hits over consecutive paragraphs, each followed by its mark where `mark` says, as Word's wildcards
+ * match a paragraph mark (check 59; CR-002 section 32, K7): `?`, `*` and a class cross one, `^13` is one. The text read
+ * in each paragraph is `officeMatches`' for wildcards; the caller gives only paragraphs a hit may span (one cell's, or
+ * none's) and only the marks it may hold (a paragraph's own, never a cell's or a row's end).
+ */
+export function wildcardMatchesAcross(pieces, query, options) {
+    const pattern = searchPattern(query, { ...options, matchWildcards: true });
+    let text = '';
+    const starts = [];
+    const ends = [];
+    const marks = [];
+    const put = (c, k, start, end, mark) => { text += c; starts.push([k, start]); ends.push([k, end]); marks.push(mark); };
+    pieces.forEach((piece, k) => {
+        for (const seg of piece.segments) {
+            if (seg.hidden)
+                continue;
+            if (seg.object) {
+                if (piece.from < seg.start && seg.start < piece.to)
+                    put(OBJECT, k, seg.start, seg.start, false);
+                continue;
+            }
+            for (let i = 0; i < seg.text.length; i++) {
+                const at = seg.start + i;
+                if (at >= piece.from && at < piece.to)
+                    put(seg.text[i], k, at, at + 1, false);
+            }
+        }
+        if (piece.mark)
+            put('\r', k, piece.length, piece.length, true);
+    });
+    return matchesOf(text, pattern).map((match) => {
+        const a = match.index;
+        const b = a + match[0].length;
+        return { first: starts[a][0], start: starts[a][1], last: ends[b - 1][0], end: ends[b - 1][1], mark: marks[b - 1], match };
+    });
+}
+/**
+ * Refuses a wildcard replacement where a hit holds a paragraph mark (CR-002 section 32, K7): `search` finds it, as
+ * Word's does (check 59), but what replacing a mark leaves isn't measured, as for a plain `^p` (`refuseMarkReplacement`).
+ */
+export function refuseWildcardMarkReplacement(className, hits) {
+    if (!hits.some((hit) => hit.spansParagraphs || hit.holdsEndMark))
+        return;
+    throw new NotSupportedError(className, 'replaceText', "a hit holds a paragraph mark, which Word's wildcards match (check 59), and what replacing "
+        + 'one does isn\'t measured (CR-002 section 32); search for the hits and edit their ranges');
+}
+/**
+ * A plain query split at Word's paragraph mark code, `^p`: its pieces, one more than the marks, each a plain
+ * query of its own (`^^` stays an escaped caret); undefined where the query holds no `^p`. What a `Range`'s search
+ * across paragraphs matches piece by piece (CR-014 phase 3).
+ */
+export function paragraphMarkPieces(query) {
+    const pieces = [];
+    let piece = '';
+    for (let i = 0; i < query.length; i++) {
+        const c = query[i];
+        if (c === '^' && query[i + 1] === 'p') {
+            pieces.push(piece);
+            piece = '';
+            i++;
+            continue;
+        }
+        if (c === '^' && i + 1 < query.length) {
+            piece += c + query[i + 1];
+            i++;
+            continue;
+        }
+        piece += c;
+    }
+    if (pieces.length === 0)
+        return undefined;
+    pieces.push(piece);
+    return pieces;
+}
+/**
+ * Refuses a replacement whose query holds `^p` (CR-014 phase 3): `search` finds such a hit, but what Office JS's
+ * replacement of a paragraph mark leaves isn't measured, and `insertText('Replace')` keeps a last mark (check 52).
+ * Until phase 3 such a query matched the two characters `^p`, where Word matches a mark.
+ */
+export function refuseMarkReplacement(className, find, options) {
+    if ((options === null || options === void 0 ? void 0 : options.matchWildcards) || (options === null || options === void 0 ? void 0 : options.matchRegExp) || !paragraphMarkPieces(find))
+        return;
+    throw new NotSupportedError(className, 'replaceText', "the query holds ^p, Word's paragraph mark, and what replacing one does isn't "
+        + "measured (CR-014 phase 3); search for the hits and edit their ranges");
+}
+/** A plain query as an expression over `officeMatches`' text, and which of its characters are `^f` or `^e`. */
+function plainQuery(query) {
+    let source = '';
+    const tokens = [];
+    for (let i = 0; i < query.length; i++) {
+        const c = query[i];
+        const code = c === '^' ? query[i + 1] : undefined;
+        if (code !== undefined && FIND_CODES[code] !== undefined) {
+            source += escapeRegExp(FIND_CODES[code]);
+            tokens.push(code === 'f' ? 'footnote' : code === 'e' ? 'endnote' : undefined);
+            i++;
+        }
+        else if (c === '-') {
+            source += '[-\\u001E]'; // a non-breaking hyphen is a hyphen to a plain query
+            tokens.push(undefined);
+        }
+        else {
+            source += escapeRegExp(c);
+            tokens.push(undefined);
+        }
+    }
+    return { source, tokens };
+}
+/** `searchPattern`'s flags and whole-word guard over a source already written as an expression. */
+function patternOf(source, options) {
+    const guarded = options.matchWholeWord ? `(?<![\\w])${source}(?![\\w])` : source;
+    return new RegExp(guarded, options.matchCase ? 'g' : 'gi');
+}

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

@@ -0,0 +1,159 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type RunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { type Element } from './tree.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+/** What a write needs of the `Range` it writes: its two ends, and whether it holds its last paragraph's mark. */
+export interface Span {
+    readonly paragraph: Paragraph;
+    readonly endParagraph: Paragraph;
+    readonly start: number;
+    readonly end: number;
+    readonly whole: boolean;
+    /** The range holds its last paragraph's mark (a 'Whole' range), or a table's end in its place. */
+    readonly holdsEndMark: boolean;
+}
+/**
+ * Where a range's two ends stand in the innermost list of blocks holding both: the block holding the start and
+ * the block holding the end, each the end's paragraph itself, or a table or content control the range holds
+ * whole (a table's 'Whole' range, a body's that starts with a table).
+ */
+export interface Extent {
+    list: Element[];
+    first: number;
+    last: number;
+    /** The start's paragraph, where it is the first block itself (or in `headInside`); else that block goes whole. */
+    head?: Paragraph;
+    /** The end's paragraph, where it is the last block itself (or in `tailInside`); else that block goes whole. */
+    tail?: Paragraph;
+    /** Where the range starts inside a block content control at `first`: the control's list holding `head` (check 54 case 20). */
+    headInside?: Element[];
+    /** Where the range ends inside a block content control at `last`: the control's list holding `tail` (check 54 case 18). */
+    tailInside?: Element[];
+}
+/** Where a deletion closed up: the paragraph, and the offset in it a replacement's text goes at. */
+export interface Landing {
+    paragraph: Paragraph;
+    offset: number;
+}
+/**
+ * The extent of a range, refusing one that starts or ends inside a block it doesn't hold whole. Inside a table
+ * that is Word's own refusal (check 52: `delete()` and `Replace` on a range from a cell to a paragraph after the
+ * table, or from a paragraph into a cell, threw `GeneralException` and changed nothing, tracked or not; D3).
+ * Inside a block content control, `crossControls` lets a range end in the control's own paragraphs, one level
+ * down, as `delete()` takes one (check 54 cases 18 to 20); anything else there is `NotSupportedError`.
+ */
+export declare function extentOf(span: Span, member: string, crossControls?: boolean): Extent;
+/**
+ * Deletes a range across paragraphs, or one holding its last paragraph's mark, as Word does (check 52, cases 3 to
+ * 28; check 54, cases 5 to 20): the start's paragraph loses its text from the start, every block between goes whole
+ * (a table too), the end's paragraph loses its text to the end, and the two join in the end paragraph's properties,
+ * each run keeping its own formatting. A mark the range holds goes (`dropMark`): its paragraph joins the paragraph
+ * after it, in that one's properties (W1, W2; after a whole table the range took, case 5), or, with no paragraph
+ * after it, goes itself where its text went with the range (before a table, at a control's end: cases 8 and 12),
+ * a cell's last paragraph and a story's last kept (case 10). `keepLastMark` is `Replace`'s, which keeps it.
+ *
+ * A range ending (or starting) in a block content control's own paragraph, the other end outside it, joins
+ * nothing across the control's edge: the texts go, and the start's paragraph takes the end's paragraph properties
+ * (cases 18 to 20). A comment whose reference goes with the range goes too (case 27).
+ *
+ * Tracked, nothing is joined: the text is a `w:del`, every mark in the range is marked deleted but a last one the
+ * range doesn't hold, or that can't go (a cell's last), and a table's rows and its cells' marks are deleted, with no
+ * `w:pPrChange` (Word's markup in its save after check 52's run). Accepting gives the untracked answer.
+ */
+export declare function deleteSpan(span: Span, extent: Extent, keepLastMark: boolean): Landing | undefined;
+/**
+ * Refuses, before anything changes, a tracked deletion of a range holding a whole `w:altChunk` or kept
+ * `mc:AlternateContent`: neither has a deleted form, and Accept All would leave it where the untracked deletion
+ * takes it, the paragraphs either side unjoined. A content control or custom XML element held whole is deleted as
+ * Word deletes one (check 54 cases 15 and 17: `markHolderDeleted`).
+ */
+export declare function assertTrackable(extent: Extent, member: string): void;
+/** The first replaced character's run properties and where it stood, read before anything is deleted. */
+export interface FirstCharacter {
+    rPr: wml.RPr | undefined;
+    pPr: wml.PPr | undefined;
+    p: wml.P;
+}
+/** The character at a range's start: its run's properties, or its paragraph's mark's where the range starts at the mark. */
+export declare function firstCharacterOf(span: Span): FirstCharacter;
+/**
+ * The run properties that give text in `into` the look the first replaced character had (check 52, cases 29 to
+ * 38): its run's own properties, and each property its paragraph's style gave it that `into`'s doesn't, written
+ * direct - a heading's font, size, colour and bold in a body paragraph (case 29), and a body paragraph's
+ * `w:b w:val="0"` and automatic colour in a heading (case 30). A property no style sets anywhere and `into`'s does
+ * is written as its neutral value where it has one (`NEUTRAL`).
+ */
+export declare function lookOf(first: FirstCharacter, into: Paragraph): wml.RPr | undefined;
+/** The text of an untracked `Replace`, put where the deletion closed up, in the first replaced character's look. */
+export declare function placeReplacement(landing: Landing, first: FirstCharacter, text: string): {
+    first: Paragraph;
+    last: Paragraph;
+    start: number;
+    end: number;
+};
+/**
+ * A paragraph of `text` put at `offset` in `p`, as Word puts one where a range across paragraphs starts
+ * ('Before') or ends ('After') (check 52, cases 57 to 70): at the paragraph's start it goes before it and at its
+ * end after it, in its properties (`Paragraph.insertParagraph`); inside it `p` is split there (`splitParagraph`)
+ * and the new paragraph goes between the halves, its mark and its text in the formatting of the run before the
+ * split (case 63's italic). Tracked, the new paragraph and the first half's mark are inserted (cases 69 and 70).
+ * Returns the new paragraph, and the first half where `p` was split.
+ */
+export declare function insertParagraphAt(p: Paragraph, offset: number, text: string): {
+    inserted: Paragraph;
+    firstHalf?: Paragraph;
+};
+/**
+ * Paragraph breaks put into `p` at `offsets` (ascending, in its text), as Word's insertText writes a line feed or
+ * carriage return (CR-002 section 60 E1, check 55): at a split (`splitParagraph`), in the formatting of the run before
+ * it; at the paragraph's end an empty paragraph after it, at its start one before it, in its properties. Tracked, each
+ * new mark is inserted. Returns the first paragraph and the last, which holds what followed the last break.
+ */
+export declare function breakParagraphAt(p: Paragraph, offsets: readonly number[]): {
+    first: Paragraph;
+    last: Paragraph;
+};
+/**
+ * Splits `p` at `offset`, inside its text: what is before it becomes a new paragraph in front of `p`, in a copy of
+ * its properties with a mark of its own in `rPr`'s formatting, and `p` keeps the rest with its own mark, its
+ * section break and its identity, as Word keeps them (check 52 cases 57 and 63). A link, a revision or a smart tag
+ * the offset is inside is split into two of the same; a complex field's result is split, the field running across the
+ * two, and a `w:fldSimple` is made a complex field first, as Word makes it (check 57, CR-002 section 62.2 D1); a content
+ * control or a kept `mc:AlternateContent` there is refused, since its two halves would be two of it. Tracked, the new
+ * mark is inserted, as Word marks the first half's (cases 69 and 70). Returns the first half.
+ */
+export declare function splitParagraph(p: Paragraph, offset: number, rPr: wml.RPr | undefined): Paragraph;
+/**
+ * Word's form of a table put after the paragraph a table cell ends with (check 52, cases 86 and 87; CR-002 section 55.6):
+ * that paragraph is split at its end, as a paragraph break there splits it (`splitAtEnd`), the table between the halves,
+ * so the cell's mark stays last. The paragraph keeps its text and becomes the first half, whose new mark takes the
+ * formatting of the text before it and, tracked, is the inserted one; its properties as they were go after the table, in
+ * an empty paragraph, unmarked. The paragraph keeps its text, not its mark, so that a view of it (a `Range`) still holds it.
+ */
+export declare function keepCellMarkLast(p: Paragraph, cellContent: Element[]): void;
+/** The run holders a paragraph split may cut in two: each half is a whole one of the same. */
+export declare const SPLITTABLE: Set<string>;
+/** The run holders a paragraph break may be made inside: those it cuts in two, and a `w:fldSimple`, made a complex field first (D1). */
+export declare const BREAKABLE: ReadonlySet<string>;
+/**
+ * Every `w:fldSimple` a run is inside, below the paragraph, made a complex field, the innermost first: what Word does
+ * before a paragraph break inside a simple field's result (check 57 cases 2 and 4, CR-002 section 62.2 D1). The caller
+ * has checked that every other holder there can be cut in two.
+ */
+export declare function unfoldSimpleFieldsAround(run: object, p: object): void;
+/** A piece of a range in one paragraph: its runs, and whether the range holds the paragraph's mark. */
+export interface FontPiece {
+    paragraph: Paragraph;
+    start: number;
+    end: number;
+    runs: () => Element<wml.R>[];
+    holdsMark: boolean;
+}
+/**
+ * A `font` write over a range across paragraphs (check 52, cases 49 to 56): every run in the range, a table's
+ * cells' too, split at the range's ends, and each mark the range holds, as Word formats them. A property goes only
+ * where a run or mark doesn't read the value already (`reads`): Word wrote `w:b` on none of a heading's runs, bold
+ * through its style, and tracked no change there; nor `w:sz` on a heading's 14-point runs (check 54). Tracked, each
+ * run and mark changed has its `w:rPrChange` (case 56: the body paragraph's mark's).
+ */
+export declare function formatSpan(pieces: FontPiece[], opts: RunOptions): void;