@stll/folio-core 0.61.0 → 0.62.0

package/dist/utils/findReplace.js

@@ -1,5 +1,18 @@
+import { parseFieldType } from "../docx/fieldParser.js";
+import { HYPHEN_TEXT_CARRIERS } from "../prosemirror/conversion/hyphenTextCarriers.js";
+import { isTableCellRetainedInReviewView } from "../prosemirror/tableCellRevisionVisibility.js";
+import { decodeOoxmlSymbolCharacter } from "./ooxmlSymbol.js";
 import { panic } from "better-result";
+import { documentStories, sameStory, storyBody } from "@stll/docx-core/ops";
 //#region src/utils/findReplace.ts
+/** One replacement policy for every host; searchability does not imply editability. */
+const replaceEligibility = (match) => {
+	if (match.story !== void 0 && match.story !== "main" || match.textBoxIndex !== void 0 || match.commentId !== void 0) return {
+		status: "blocked",
+		reason: "non-body-story"
+	};
+	return match.replacement;
+};
 const createDefaultFindOptions = () => ({
 	matchCase: false,
 	matchWholeWord: false,
@@ -10,7 +23,7 @@ const createSearchPattern = (searchText, options) => {
 	if (!searchText) return null;
 	try {
 		const source = options.useRegex ? searchText : escapeRegexString(searchText);
-		const pattern = options.matchWholeWord ? `\\b${source}\\b` : source;
+		const pattern = options.matchWholeWord ? `\\b(?:${source})\\b` : source;
 		return new RegExp(pattern, options.matchCase ? "gu" : "giu");
 	} catch {
 		return null;
@@ -18,98 +31,385 @@ const createSearchPattern = (searchText, options) => {
 };
 const findAllMatches = (content, searchText, options) => {
 	if (!content || !searchText) return [];
-	const searchFor = options.matchCase ? searchText : searchText.toLowerCase();
-	const source = escapeRegexString(searchFor);
-	const pattern = new RegExp(options.matchWholeWord ? `\\b${source}\\b` : source, options.matchCase ? "gu" : "giu");
+	const pattern = createSearchPattern(searchText, options);
+	if (!pattern) return [];
 	const matches = [];
 	let match;
 	while ((match = pattern.exec(content)) !== null) {
+		if (match[0].length === 0) {
+			const codePoint = content.codePointAt(pattern.lastIndex);
+			pattern.lastIndex += codePoint !== void 0 && codePoint > 65535 ? 2 : 1;
+			continue;
+		}
 		matches.push({
 			start: match.index,
 			end: match.index + match[0].length
 		});
-		if (match[0].length === 0) pattern.lastIndex++;
 	}
 	return matches;
 };
-const findInDocument = (document, searchText, options) => {
+const findInDocument = (document, searchText, options, context) => {
 	if (!document || !searchText) return [];
 	const body = document.package.document;
 	if (!isRecord(body) || !Array.isArray(body.content)) return [];
 	const matches = [];
-	forEachParagraph(body.content, (paragraph, paragraphIndex) => {
-		matches.push(...findInParagraph(paragraph, searchText, options, paragraphIndex));
+	for (const story of orderedSearchStories(document)) {
+		if (story !== "main" && (story.kind === "header" || story.kind === "footer") && context?.renderedStories && !context.renderedStories.some((rendered) => sameStory(rendered, story))) continue;
+		const blocks = storyBody(document, story).content;
+		if (story !== "main" && (story.kind === "footnote" || story.kind === "endnote")) {
+			const noteType = (story.kind === "footnote" ? document.package.footnotes : document.package.endnotes)?.find(({ id }) => id === story.id)?.noteType;
+			if (noteType && noteType !== "normal") continue;
+		}
+		let textBoxIndex = 0;
+		const searchBlocks = (items, shapeAddress, visible = true) => {
+			forEachParagraph(items, (paragraph, paragraphIndex, structureVisible) => {
+				const paragraphVisible = visible && structureVisible;
+				if (paragraphVisible) for (const match of findInParagraph(paragraph, searchText, options, paragraphIndex)) if (shapeAddress) matches.push({
+					...match,
+					story,
+					textBoxIndex: shapeAddress.textBoxIndex,
+					anchorParagraphIndex: shapeAddress.anchorParagraphIndex
+				});
+				else matches.push({
+					...match,
+					story
+				});
+				for (const { shape, visible: shapeVisible } of paragraphShapes(paragraph.content, options.displayMode)) {
+					if (!shape.textBody) continue;
+					searchBlocks(shape.textBody.content, {
+						textBoxIndex: textBoxIndex++,
+						anchorParagraphIndex: shapeAddress?.anchorParagraphIndex ?? paragraphIndex
+					}, paragraphVisible && shapeVisible);
+				}
+			}, options.displayMode);
+		};
+		searchBlocks(blocks);
+	}
+	if (options.includeComments) for (const comment of document.package.document.comments ?? []) forEachParagraph(comment.content, (paragraph, paragraphIndex, visible) => {
+		if (!visible) return;
+		for (const match of findInParagraph(paragraph, searchText, {
+			...options,
+			displayMode: "all-markup"
+		}, paragraphIndex)) matches.push({
+			...match,
+			story: "main",
+			commentId: comment.id
+		});
 	});
+	for (const match of matches) match.replacement = replaceEligibility(match);
 	return matches;
 };
+const orderedSearchStories = (document) => {
+	const stories = documentStories(document);
+	const ordered = ["main"];
+	const seen = /* @__PURE__ */ new Set();
+	for (const kind of ["header", "footer"]) {
+		const add = (rId) => {
+			const key = `${kind}:${rId}`;
+			const parts = kind === "header" ? document.package.headers : document.package.footers;
+			if (seen.has(key) || !parts?.has(rId)) return;
+			seen.add(key);
+			ordered.push({
+				kind,
+				rId
+			});
+		};
+		for (const section of document.package.document.sections ?? []) {
+			const refs = kind === "header" ? section.properties.headerReferences : section.properties.footerReferences;
+			for (const variant of [
+				"default",
+				"first",
+				"even"
+			]) for (const ref of refs ?? []) if (ref.type === variant) add(ref.rId);
+		}
+		for (const story of stories) if (story !== "main" && story.kind === kind) add(story.rId);
+	}
+	for (const story of stories) if (story !== "main" && (story.kind === "footnote" || story.kind === "endnote")) ordered.push(story);
+	return ordered;
+};
+const isHiddenRevision = (type, mode) => {
+	if (mode === "original") return type === "insertion" || type === "moveTo";
+	if (mode === "no-markup" || mode === "simple-markup") return type === "deletion" || type === "moveFrom";
+	return false;
+};
+const paragraphShapes = (content, mode) => {
+	const shapes = [];
+	const visit = (items, visible = true) => {
+		for (const item of items) {
+			const itemVisible = visible && !isHiddenRevision(item.type, mode);
+			if (item.type === "run") {
+				for (const child of item.content) if (child.type === "shape") shapes.push({
+					shape: child.shape,
+					visible: itemVisible
+				});
+			} else if (item.type === "hyperlink") visit(item.children, itemVisible);
+			else if (item.type === "complexField") visit(item.fieldResult, itemVisible);
+			else if ("content" in item) visit(item.content, itemVisible);
+		}
+	};
+	visit(content);
+	return shapes;
+};
+/** Visible characters retain offsets in the authored paragraph, including hidden revisions. */
+const getVisibleParagraphProjection = (paragraph, mode) => {
+	if (mode === void 0 || mode === "all-markup") return {
+		...joinSearchProjections(paragraph.content.map(getParagraphContentSearchProjection)),
+		offsets: [],
+		hiddenContentBarriers: []
+	};
+	let text = "";
+	let authoredOffset = 0;
+	const offsets = [];
+	const hiddenContentBarriers = [];
+	const replacementBarriers = [];
+	const atomicContentRanges = [];
+	const fieldTextRanges = [];
+	const excludedTextRanges = [];
+	const pageBreakOffsets = [];
+	const visit = (items) => {
+		for (const item of items) {
+			if (isHiddenRevision(item.type, mode)) {
+				hiddenContentBarriers.push(text.length);
+				authoredOffset += getParagraphContentSearchProjection(item).text.length;
+				continue;
+			}
+			if (item.type === "hyperlink") {
+				visit(item.children);
+				continue;
+			}
+			if (item.type === "complexField" || item.type === "simpleField") {
+				const start = text.length;
+				visit(item.type === "complexField" ? item.fieldResult : item.content);
+				fieldTextRanges.push({
+					start,
+					end: text.length
+				});
+				if (isPageDependentSearchField(item.instruction)) excludedTextRanges.push({
+					start,
+					end: text.length
+				});
+				continue;
+			}
+			if (item.type !== "run" && "content" in item) {
+				visit(item.content);
+				continue;
+			}
+			const part = getParagraphContentSearchProjection(item);
+			for (const offset of part.replacementBarriers ?? []) replacementBarriers.push(text.length + offset);
+			for (const range of part.atomicContentRanges ?? []) atomicContentRanges.push({
+				start: text.length + range.start,
+				end: text.length + range.end
+			});
+			for (const range of part.fieldTextRanges ?? []) fieldTextRanges.push({
+				start: text.length + range.start,
+				end: text.length + range.end
+			});
+			for (const range of part.excludedTextRanges ?? []) excludedTextRanges.push({
+				start: text.length + range.start,
+				end: text.length + range.end
+			});
+			for (const offset of part.pageBreakOffsets) pageBreakOffsets.push(text.length + offset);
+			for (let index = 0; index < part.text.length; index++) offsets.push(authoredOffset + index);
+			text += part.text;
+			authoredOffset += part.text.length;
+		}
+	};
+	visit(paragraph.content);
+	return {
+		text,
+		offsets,
+		hiddenContentBarriers,
+		pageBreakOffsets,
+		excludedTextRanges,
+		fieldTextRanges,
+		atomicContentRanges,
+		replacementBarriers
+	};
+};
+/** Authored paragraph text displayed by comment UI, using the search owner. */
+const getFindParagraphText = (paragraph) => getVisibleParagraphProjection(paragraph, void 0).text;
 const findInParagraph = (paragraph, searchText, options, paragraphIndex) => {
-	const projection = getParagraphSearchProjection(paragraph);
+	const projection = getVisibleParagraphProjection(paragraph, options.displayMode);
 	if (!projection.text) return [];
-	return findAllMatches(projection.text, searchText, options).filter(({ start, end }) => !projection.pageBreakOffsets.some((offset) => offset > start && offset < end)).map(({ start, end }) => ({
+	return findAllMatches(projection.text, searchText, options).filter(({ start, end }) => !projection.pageBreakOffsets.some((offset) => offset > start && offset < end) && !(projection.excludedTextRanges ?? []).some((range) => range.start < end && range.end > start)).map(({ start, end }) => ({
 		paragraphIndex,
-		contentIndex: findContentIndexAtOffset(paragraph, start),
-		startOffset: start,
-		endOffset: end,
+		replacement: replacementForProjection({
+			projection,
+			start,
+			end
+		}),
+		contentIndex: findContentIndexAtOffset(paragraph, projection.offsets.at(start) ?? start),
+		startOffset: projection.offsets.at(start) ?? start,
+		endOffset: (projection.offsets.at(end - 1) ?? end - 1) + 1,
 		text: projection.text.slice(start, end)
 	}));
 };
-const forEachParagraph = (blocks, visit) => {
+const replacementForProjection = ({ projection, start, end }) => {
+	if (projection.hiddenContentBarriers.some((offset) => offset > start && offset < end)) return {
+		status: "blocked",
+		reason: "hidden-content"
+	};
+	if ((projection.fieldTextRanges ?? []).some((range) => range.start < end && range.end > start)) return {
+		status: "blocked",
+		reason: "field-result"
+	};
+	if ((projection.atomicContentRanges ?? []).some((range) => range.start < end && range.end > start)) return {
+		status: "blocked",
+		reason: "atomic-content"
+	};
+	if ((projection.replacementBarriers ?? []).some((offset) => offset > start && offset < end)) return {
+		status: "blocked",
+		reason: "atomic-content"
+	};
+	for (let offset = start + 1; offset < end; offset++) if ((projection.offsets.at(offset) ?? offset) !== (projection.offsets.at(offset - 1) ?? offset - 1) + 1) return {
+		status: "blocked",
+		reason: "hidden-content"
+	};
+	return { status: "allowed" };
+};
+const forEachParagraph = (blocks, visit, displayMode) => {
 	let paragraphIndex = 0;
-	const walkBlocks = (items) => {
+	const walkBlocks = (items, visible = true) => {
 		for (const block of items) {
 			if (isParagraph(block)) {
-				visit(block, paragraphIndex);
+				visit(block, paragraphIndex, visible);
 				paragraphIndex++;
 				continue;
 			}
 			if (isTable(block)) {
-				walkTable(block);
+				walkTable(block, visible);
 				continue;
 			}
-			if (isBlockContainer(block)) walkBlocks(block.content);
+			if (isBlockContainer(block)) walkBlocks(block.content, visible);
 		}
 	};
-	const walkTable = (table) => {
+	const walkTable = (table, visible) => {
 		for (const row of table.rows) {
 			if (!isTableRow(row)) continue;
-			for (const cell of row.cells) if (isTableCell(cell)) walkBlocks(cell.content);
+			for (const cell of row.cells) if (isTableCell(cell)) walkBlocks(cell.content, visible && isVisibleStructure(row.structuralChange, displayMode) && isVisibleStructure(cell.structuralChange, displayMode));
 		}
 	};
 	walkBlocks(blocks);
 };
+const isVisibleStructure = (change, mode) => {
+	if (mode === void 0 || mode === "all-markup" || !change) return true;
+	let kind;
+	switch (change.type) {
+		case "tableRowInsertion":
+		case "tableCellInsertion":
+			kind = "ins";
+			break;
+		case "tableRowDeletion":
+		case "tableCellDeletion":
+			kind = "del";
+			break;
+		case "tableCellMerge":
+			kind = "merge";
+			break;
+		default: return change;
+	}
+	return isTableCellRetainedInReviewView(kind, mode === "original" ? "original" : "final");
+};
+const PAGE_DEPENDENT_SEARCH_FIELDS = /* @__PURE__ */ new Set([
+	"PAGE",
+	"NUMPAGES",
+	"SECTIONPAGES",
+	"PAGEREF"
+]);
+const isPageDependentSearchField = (instruction) => PAGE_DEPENDENT_SEARCH_FIELDS.has(parseFieldType(instruction));
 const joinSearchProjections = (parts) => {
 	let text = "";
 	const pageBreakOffsets = [];
+	const replacementBarriers = [];
+	const atomicContentRanges = [];
+	const fieldTextRanges = [];
+	const excludedTextRanges = [];
 	for (const part of parts) {
 		const baseOffset = text.length;
 		text += part.text;
+		for (const offset of part.replacementBarriers ?? []) replacementBarriers.push(baseOffset + offset);
+		for (const range of part.atomicContentRanges ?? []) atomicContentRanges.push({
+			start: baseOffset + range.start,
+			end: baseOffset + range.end
+		});
+		for (const range of part.fieldTextRanges ?? []) fieldTextRanges.push({
+			start: baseOffset + range.start,
+			end: baseOffset + range.end
+		});
+		for (const range of part.excludedTextRanges ?? []) excludedTextRanges.push({
+			start: baseOffset + range.start,
+			end: baseOffset + range.end
+		});
 		for (const offset of part.pageBreakOffsets) pageBreakOffsets.push(baseOffset + offset);
 	}
 	return {
 		text,
-		pageBreakOffsets
+		pageBreakOffsets,
+		excludedTextRanges,
+		fieldTextRanges,
+		atomicContentRanges,
+		replacementBarriers
 	};
 };
 const getRunSearchProjection = (run) => {
 	let text = "";
 	const pageBreakOffsets = [];
-	for (const item of run.content) if (item.type === "text") text += item.text;
-	else if (item.type === "tab") text += "	";
-	else if (item.type === "break" && (item.breakType === void 0 || item.breakType === "textWrapping")) text += "\n";
-	else if (item.type === "break" && item.breakType === "page") pageBreakOffsets.push(text.length);
+	const replacementBarriers = [];
+	const atomicContentRanges = [];
+	for (const item of run.content) switch (item.type) {
+		case "preservedXml":
+			if (!item.text) replacementBarriers.push(text.length);
+			atomicContentRanges.push({
+				start: text.length,
+				end: text.length + item.text.length
+			});
+			text += item.text;
+			break;
+		case "text":
+			text += item.text;
+			break;
+		case "symbol": {
+			const character = decodeOoxmlSymbolCharacter(item.char);
+			if (character) text += character;
+			else replacementBarriers.push(text.length);
+			break;
+		}
+		case "tab":
+			text += "	";
+			break;
+		case "softHyphen":
+		case "noBreakHyphen":
+			text += HYPHEN_TEXT_CARRIERS[item.type];
+			break;
+		case "break":
+			if (item.breakType === "page") pageBreakOffsets.push(text.length);
+			else text += "\n";
+			break;
+		case "footnoteRef":
+		case "endnoteRef":
+		case "drawing":
+		case "shape":
+		case "noteMarker":
+		case "fieldChar":
+		case "instrText":
+		case "renderedPageBreak":
+			replacementBarriers.push(text.length);
+			break;
+		default: panic(`Unsupported run content: ${JSON.stringify(item)}`);
+	}
 	return {
 		text,
-		pageBreakOffsets
+		pageBreakOffsets,
+		atomicContentRanges,
+		replacementBarriers
 	};
 };
-const getHyperlinkSearchProjection = (hyperlink) => joinSearchProjections(hyperlink.children.flatMap((child) => {
-	if (child.type === "run") return [getRunSearchProjection(child)];
-	return child.type === "inlineWrapper" ? [getParagraphContentSearchProjection(child)] : [];
-}));
+const getHyperlinkSearchProjection = (hyperlink) => joinSearchProjections(hyperlink.children.map(getParagraphContentSearchProjection));
 /** Nothing on the line: a marker, or markup with no text under it. */
 const noSearchText = () => ({
 	text: "",
-	pageBreakOffsets: []
+	pageBreakOffsets: [],
+	replacementBarriers: [0]
 });
 /**
 * The text one paragraph content item puts on the line, for searching.
@@ -134,13 +434,37 @@ const getParagraphContentSearchProjection = (content) => {
 		case "run": return getRunSearchProjection(content);
 		case "hyperlink": return getHyperlinkSearchProjection(content);
 		case "inlineSdt":
-		case "simpleField":
 		case "inlineWrapper":
 		case "insertion":
 		case "deletion":
 		case "moveFrom":
 		case "moveTo": return joinSearchProjections(content.content.map(getParagraphContentSearchProjection));
-		case "complexField": return joinSearchProjections(content.fieldResult.map(getRunSearchProjection));
+		case "simpleField":
+		case "complexField": {
+			const projection = joinSearchProjections(content.type === "simpleField" ? content.content.map(getParagraphContentSearchProjection) : content.fieldResult.map(getRunSearchProjection));
+			const part = {
+				...projection,
+				fieldTextRanges: [{
+					start: 0,
+					end: projection.text.length
+				}]
+			};
+			return isPageDependentSearchField(content.instruction) ? {
+				...part,
+				excludedTextRanges: [{
+					start: 0,
+					end: part.text.length
+				}]
+			} : part;
+		}
+		case "preservedInline": return {
+			text: content.text,
+			pageBreakOffsets: [],
+			atomicContentRanges: [{
+				start: 0,
+				end: content.text.length
+			}]
+		};
 		case "bookmarkStart":
 		case "bookmarkEnd":
 		case "commentRangeStart":
@@ -150,12 +474,10 @@ const getParagraphContentSearchProjection = (content) => {
 		case "moveFromRangeEnd":
 		case "moveToRangeStart":
 		case "moveToRangeEnd":
-		case "mathEquation":
-		case "preservedInline": return noSearchText();
+		case "mathEquation": return noSearchText();
 		default: panic(`Unsupported paragraph content: ${JSON.stringify(content)}`);
 	}
 };
-const getParagraphSearchProjection = (paragraph) => joinSearchProjections(paragraph.content.map(getParagraphContentSearchProjection));
 const findContentIndexAtOffset = (paragraph, offset) => {
 	let currentOffset = 0;
 	for (let contentIndex = 0; contentIndex < paragraph.content.length; contentIndex++) {
@@ -174,4 +496,4 @@ const isTableRow = (value) => isRecord(value) && Array.isArray(value["cells"]);
 const isTableCell = (value) => isRecord(value) && Array.isArray(value["content"]);
 const isBlockContainer = (value) => isRecord(value) && (value["type"] === "blockSdt" || value["type"] === "blockCustomXml") && Array.isArray(value["content"]);
 //#endregion
-export { createDefaultFindOptions, createSearchPattern, escapeRegexString, findAllMatches, findInDocument, findInParagraph };
+export { createDefaultFindOptions, createSearchPattern, escapeRegexString, findAllMatches, findInDocument, findInParagraph, getFindParagraphText, isPageDependentSearchField, replaceEligibility };

package/dist/utils/findSearchKey.d.ts

@@ -0,0 +1,29 @@
+import { document_d_exports } from "../types/document.js";
+import { FindOptions, FindSearchContext } from "./findReplace.js";
+//#region src/utils/findSearchKey.d.ts
+/** Every matching option must make an explicit decision in the search key. */
+declare const createFindQueryKey: (query: string, options: FindOptions) => string;
+type FindSearchKeyOptions = {
+  query: string;
+  options: FindOptions;
+  document: document_d_exports.Document;
+  /** Immutable editor document identity, changed by every body transaction. */
+  bodyVersion?: object;
+  context?: FindSearchContext;
+};
+/**
+ * Getters can return fresh model clones. Keep the immutable body version and
+ * snapshot package stories separately: secondary edits do not change that body.
+ * Story enumeration also binds this snapshot to the package's story resolver.
+ */
+declare const createFindSearchKey: ({ query, options, document, bodyVersion, context }: FindSearchKeyOptions) => {
+  query: string;
+  bodyVersion: string | object;
+  documentVersion: string;
+  storyScope: string;
+};
+declare const sameFindSearchKey: (previous: ReturnType<typeof createFindSearchKey> | null, current: ReturnType<typeof createFindSearchKey>) => boolean;
+/** Secondary edits cannot acknowledge a pending body replacement. */
+declare const sameFindBodyVersion: (previous: ReturnType<typeof createFindSearchKey>, current: ReturnType<typeof createFindSearchKey>) => boolean;
+//#endregion
+export { createFindQueryKey, createFindSearchKey, sameFindBodyVersion, sameFindSearchKey };

package/dist/utils/findSearchKey.js

@@ -0,0 +1,34 @@
+import { documentStories, storyBody } from "@stll/docx-core/ops";
+//#region src/utils/findSearchKey.ts
+/** Every matching option must make an explicit decision in the search key. */
+const createFindQueryKey = (query, options) => {
+	const matchingOptions = {
+		matchCase: options.matchCase,
+		matchWholeWord: options.matchWholeWord,
+		useRegex: options.useRegex ?? false,
+		displayMode: options.displayMode ?? "all-markup",
+		includeComments: options.includeComments ?? false
+	};
+	return JSON.stringify([query, matchingOptions]);
+};
+/**
+* Getters can return fresh model clones. Keep the immutable body version and
+* snapshot package stories separately: secondary edits do not change that body.
+* Story enumeration also binds this snapshot to the package's story resolver.
+*/
+const createFindSearchKey = ({ query, options, document, bodyVersion, context }) => ({
+	query: createFindQueryKey(query, options),
+	bodyVersion: bodyVersion ?? JSON.stringify(document.package.document.content),
+	documentVersion: JSON.stringify([
+		documentStories(document).filter((story) => story !== "main").map((story) => [story, storyBody(document, story)]),
+		document.package.document.comments ?? [],
+		document.package.document.sections?.map(({ properties }) => properties) ?? []
+	]),
+	storyScope: JSON.stringify(context?.renderedStories?.map((story) => JSON.stringify(story)).toSorted() ?? null)
+});
+const sameFindSearchKey = (previous, current) => previous !== null && previous.query === current.query && sameFindDocumentVersion(previous, current) && previous.storyScope === current.storyScope;
+const sameFindDocumentVersion = (previous, current) => sameFindBodyVersion(previous, current) && previous.documentVersion === current.documentVersion;
+/** Secondary edits cannot acknowledge a pending body replacement. */
+const sameFindBodyVersion = (previous, current) => previous.bodyVersion === current.bodyVersion;
+//#endregion
+export { createFindQueryKey, createFindSearchKey, sameFindBodyVersion, sameFindSearchKey };