@stll/folio-core 0.32.1 → 0.33.0

package/dist/compare/formatting.d.ts

@@ -0,0 +1,29 @@
+import { FolioAIBlock, FolioAIInlineFormatting } from "../ai-edits/types.js";
+//#region src/compare/formatting.d.ts
+/** One run of characters whose supported inline formatting differs. */
+type InlineFormattingSegment = {
+  /** Zero-based UTF-16 offset into the block's visible text. */
+  startOffset: number;
+  endOffset: number;
+  /** Only the properties that differ, set to the target document's value. */
+  formatting: FolioAIInlineFormatting;
+};
+type InlineFormattingSegmentsOptions = {
+  baseBlock: FolioAIBlock;
+  targetBlock: FolioAIBlock;
+  /** Refuse (return `null`) rather than build more segments than this. */
+  maxSegments: number;
+};
+/**
+ * Segments where `targetBlock`'s bold / italic / underline / strike differs from
+ * `baseBlock`'s, for two blocks that carry the same text. Returns `null` only
+ * when the diff would exceed `maxSegments`.
+ *
+ * A block whose runs cannot be aligned to its text reports no segments rather
+ * than guessing: attributing formatting to the wrong characters is worse than
+ * missing a formatting-only change, and the caller has no offset it could
+ * trust instead.
+ */
+declare const inlineFormattingSegments: ({ baseBlock, targetBlock, maxSegments }: InlineFormattingSegmentsOptions) => InlineFormattingSegment[] | null;
+//#endregion
+export { InlineFormattingSegment, inlineFormattingSegments };

package/dist/compare/formatting.js

@@ -0,0 +1,84 @@
+//#region src/compare/formatting.ts
+const changedSupportedFormatting = (base, target) => ({
+	...Boolean(base.bold) !== Boolean(target.bold) && { bold: Boolean(target.bold) },
+	...Boolean(base.italic) !== Boolean(target.italic) && { italic: Boolean(target.italic) },
+	...Boolean(base.underline) !== Boolean(target.underline) && { underline: Boolean(target.underline) },
+	...Boolean(base.strike) !== Boolean(target.strike) && { strike: Boolean(target.strike) }
+});
+const sameInlineFormatting = (left, right) => left.bold === right.bold && left.italic === right.italic && left.underline === right.underline && left.strike === right.strike;
+const hasInlineFormatting = (formatting) => formatting.bold !== void 0 || formatting.italic !== void 0 || formatting.underline !== void 0 || formatting.strike !== void 0;
+/**
+* A block's runs, or `null` when they cannot describe the block's text.
+* Non-text inline content (a field, an image) leaves the concatenated run text
+* shorter than the block text; attributing formatting by offset would then
+* point at the wrong characters, so the caller must back off instead.
+*/
+const previewRunsForBlock = (block) => {
+	const runs = block.previewRuns ?? [{ text: block.text }];
+	return runs.map(({ text }) => text).join("") === block.text ? runs : null;
+};
+/**
+* Segments where `targetBlock`'s bold / italic / underline / strike differs from
+* `baseBlock`'s, for two blocks that carry the same text. Returns `null` only
+* when the diff would exceed `maxSegments`.
+*
+* A block whose runs cannot be aligned to its text reports no segments rather
+* than guessing: attributing formatting to the wrong characters is worse than
+* missing a formatting-only change, and the caller has no offset it could
+* trust instead.
+*/
+const inlineFormattingSegments = ({ baseBlock, targetBlock, maxSegments }) => {
+	const baseRuns = previewRunsForBlock(baseBlock);
+	const targetRuns = previewRunsForBlock(targetBlock);
+	if (!baseRuns || !targetRuns || baseBlock.text.length === 0) return [];
+	const segments = [];
+	let baseRunIndex = 0;
+	let targetRunIndex = 0;
+	let baseRunOffset = 0;
+	let targetRunOffset = 0;
+	let textOffset = 0;
+	while (baseRunIndex < baseRuns.length && targetRunIndex < targetRuns.length) {
+		const baseRun = baseRuns[baseRunIndex];
+		const targetRun = targetRuns[targetRunIndex];
+		if (!baseRun || !targetRun) break;
+		const length = Math.min(baseRun.text.length - baseRunOffset, targetRun.text.length - targetRunOffset);
+		if (length <= 0) {
+			if (baseRunOffset >= baseRun.text.length) {
+				baseRunIndex++;
+				baseRunOffset = 0;
+			}
+			if (targetRunOffset >= targetRun.text.length) {
+				targetRunIndex++;
+				targetRunOffset = 0;
+			}
+			continue;
+		}
+		const formatting = changedSupportedFormatting(baseRun, targetRun);
+		if (hasInlineFormatting(formatting)) {
+			const previous = segments.at(-1);
+			if (previous && previous.endOffset === textOffset && sameInlineFormatting(previous.formatting, formatting)) previous.endOffset += length;
+			else {
+				if (segments.length >= maxSegments) return null;
+				segments.push({
+					startOffset: textOffset,
+					endOffset: textOffset + length,
+					formatting
+				});
+			}
+		}
+		textOffset += length;
+		baseRunOffset += length;
+		targetRunOffset += length;
+		if (baseRunOffset >= baseRun.text.length) {
+			baseRunIndex++;
+			baseRunOffset = 0;
+		}
+		if (targetRunOffset >= targetRun.text.length) {
+			targetRunIndex++;
+			targetRunOffset = 0;
+		}
+	}
+	return segments;
+};
+//#endregion
+export { inlineFormattingSegments };

package/dist/compare/plan.d.ts

@@ -0,0 +1,22 @@
+import { FolioAIEditOperation, FolioAIEditSnapshot } from "../ai-edits/types.js";
+import { FolioDocumentStoryHandle } from "../ai-edits/headless.js";
+import { CompareChange } from "./types.js";
+//#region src/compare/plan.d.ts
+type CompareStoryPlan = {
+  changes: CompareChange[];
+  operations: FolioAIEditOperation[];
+};
+type PlanStoryCompareOptions = {
+  story: FolioDocumentStoryHandle;
+  baseSnapshot: FolioAIEditSnapshot;
+  targetSnapshot: FolioAIEditSnapshot;
+  /** Cap on generated operations; the caller turns `null` into its own error. */
+  maxOperations: number;
+};
+/**
+ * Plan one story's comparison, or `null` when it needs more operations than
+ * `maxOperations`.
+ */
+declare const planStoryCompare: ({ story, baseSnapshot, targetSnapshot, maxOperations }: PlanStoryCompareOptions) => CompareStoryPlan | null;
+//#endregion
+export { CompareStoryPlan, PlanStoryCompareOptions, planStoryCompare };