@stll/folio-core 0.33.1 → 0.34.0

package/dist/server.d.ts

@@ -1,8 +1,8 @@
 import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditNormalization, FolioAIEditNormalizationCode, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSnapshot, FolioAIInlineFormatting, FolioAITextRangeHandle, FolioDocumentNavigationTarget, FolioDocumentOutline, FolioDocumentOutlineEntry, FolioDocumentSection, FolioDocumentSectionHandle, FolioDocumentSectionReadResult } from "./ai-edits/types.js";
 import { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch } from "./document-operations.js";
 import { FolioReviewChange, FolioReviewChangeKind } from "./ai-edits/read.js";
-import { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, FolioReviewChangeFilter, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView } from "./ai-edits/headless.js";
 import { createFolioAITextRangeHandle, hashFolioAIBlockText, isFolioAIContentBlock, normalizeFolioAIBlockText } from "./ai-edits/snapshot.js";
+import { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FolioApplyDocumentOperationsOptions, FolioApplyDocumentOperationsToStoryOptions, FolioApplyOperationsOptions, FolioDocumentStory, FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, FolioDocxReviewer, FolioDocxReviewerOptions, FolioEditableDocumentStoryHandle, FolioReadReviewedStoryOptions, FolioResolveReviewedStoryOptions, FolioResolvedReviewedView, FolioReviewChangeFilter, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, FolioReviewedStory, FolioReviewedView, UnsupportedFolioReviewedViewError, applyFolioAIEditsToBuffer, isFolioResolvedReviewedView, isFolioReviewedView } from "./ai-edits/headless.js";
 import { getFolioDocumentOutline, readFolioDocumentSection } from "./ai-edits/scoped-reading.js";
 import { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
 import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocumentPreset, DocumentStyleSet } from "./style-sets/types.js";

package/dist/types/block-id.d.ts

@@ -61,6 +61,17 @@ declare const isBlankFolioBlockId: (id: string) => boolean;
  * without an upfront brand check.
  */
 declare const getFolioParaIdFromBlockId: (id: string) => string | null;
+/**
+ * The id a block recorded earlier answers to in the document as parsed now.
+ *
+ * A paragraph id above the 31-bit bound the schema sets is brought into range
+ * on parse, so an id recorded from such a paragraph before that no longer
+ * names it. The mapping is a pure function of the id alone, so the recorded id
+ * resolves to the current one with no document in hand. Sequential and blank
+ * ids carry no paragraph id, and an id the parser would not have mapped is
+ * returned as it is.
+ */
+declare const currentFolioBlockId: (id: string) => string;
 /**
  * The 1-based document position encoded in a sequential fallback id
  * (`seq-0011` -> 11), or `null` for paraId-backed ids. The number is
@@ -76,4 +87,4 @@ declare const getSequentialFolioBlockIdIndex: (id: string) => number | null;
  */
 declare const isFolioBlockId: (value: unknown) => value is FolioBlockId;
 //#endregion
-export { DeriveBlockIdInput, FolioBlockId, deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId };
+export { DeriveBlockIdInput, FolioBlockId, currentFolioBlockId, deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId };

package/dist/types/block-id.js

@@ -1,3 +1,5 @@
+import { paraIdInRange } from "../docx/paraIdRangeNormalization.js";
+import { isValidHexId } from "../utils/hexId.js";
 //#region src/types/block-id.ts
 /**
 * Single source of truth for folio block ids.
@@ -91,6 +93,20 @@ const isBlankFolioBlockId = (id) => BLANK_BLOCK_ID_PATTERN.test(id);
 */
 const getFolioParaIdFromBlockId = (id) => isSequentialFolioBlockId(id) || isBlankFolioBlockId(id) ? null : id;
 /**
+* The id a block recorded earlier answers to in the document as parsed now.
+*
+* A paragraph id above the 31-bit bound the schema sets is brought into range
+* on parse, so an id recorded from such a paragraph before that no longer
+* names it. The mapping is a pure function of the id alone, so the recorded id
+* resolves to the current one with no document in hand. Sequential and blank
+* ids carry no paragraph id, and an id the parser would not have mapped is
+* returned as it is.
+*/
+const currentFolioBlockId = (id) => {
+	const paraId = getFolioParaIdFromBlockId(id);
+	return paraId !== null && isValidHexId(paraId) ? paraIdInRange(paraId) : id;
+};
+/**
 * The 1-based document position encoded in a sequential fallback id
 * (`seq-0011` -> 11), or `null` for paraId-backed ids. The number is
 * the block's position in the same non-empty-block walk both the
@@ -114,4 +130,4 @@ const isFolioBlockId = (value) => {
 	return true;
 };
 //#endregion
-export { deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId };
+export { currentFolioBlockId, deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId };

package/dist/utils/canonicalJson.d.ts

@@ -0,0 +1,14 @@
+//#region src/utils/canonicalJson.d.ts
+/**
+ * JSON with object keys in a fixed order, for comparing two values that were
+ * built by different code paths.
+ *
+ * `JSON.stringify` writes keys in insertion order, so two objects holding the
+ * same properties compare unequal whenever one was assembled in a different
+ * sequence — which is what happens whenever a parsed record is compared with a
+ * rebuilt one. `undefined` members are omitted, so an absent property and one
+ * explicitly set to `undefined` read alike.
+ */
+declare const canonicalJson: (value: unknown) => string;
+//#endregion
+export { canonicalJson };

package/dist/utils/canonicalJson.js

@@ -0,0 +1,19 @@
+//#region src/utils/canonicalJson.ts
+/**
+* JSON with object keys in a fixed order, for comparing two values that were
+* built by different code paths.
+*
+* `JSON.stringify` writes keys in insertion order, so two objects holding the
+* same properties compare unequal whenever one was assembled in a different
+* sequence — which is what happens whenever a parsed record is compared with a
+* rebuilt one. `undefined` members are omitted, so an absent property and one
+* explicitly set to `undefined` read alike.
+*/
+const canonicalJson = (value) => {
+	if (value === null || value === void 0) return "null";
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value !== "object") return JSON.stringify(value) ?? "null";
+	return `{${Object.entries(value).filter(([, entry]) => entry !== void 0).toSorted(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+};
+//#endregion
+export { canonicalJson };

package/dist/utils/fontResolver.js

@@ -191,6 +191,23 @@ const FONT_MAPPINGS = {
 			unitsPerEm: 2048
 		})
 	},
+	david: {
+		googleFont: "Noto Serif Hebrew",
+		category: "serif",
+		fallbackStack: [
+			"David",
+			"Noto Serif Hebrew",
+			"Times New Roman",
+			"serif"
+		],
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1505,
+			hheaDescent: -510,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
+	},
 	georgia: {
 		googleFont: "Tinos",
 		category: "serif",
@@ -628,6 +645,40 @@ const FONT_MAPPINGS = {
 			note: "Measured at 11pt against a 15.36pt reference-layout line pitch; the face ships with the office suite, not as a readable font file."
 		})
 	},
+	frankruehl: {
+		googleFont: "Frank Ruhl Libre",
+		category: "serif",
+		fallbackStack: [
+			"FrankRuehl",
+			"Frank Ruhl Libre",
+			"Times New Roman",
+			"serif"
+		],
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1462,
+			hheaDescent: -442,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
+	},
+	miriam: {
+		googleFont: "Miriam Libre",
+		category: "sans-serif",
+		fallbackStack: [
+			"Miriam",
+			"Miriam Libre",
+			"Arial",
+			"sans-serif"
+		],
+		singleLineRatio: singleLineRatioOf({
+			source: "hhea",
+			hheaAscent: 1546,
+			hheaDescent: -512,
+			hheaLineGap: 0,
+			unitsPerEm: 2048
+		})
+	},
 	"ms mincho": {
 		googleFont: "Noto Serif JP",
 		category: "serif",

package/dist/utils/formatToStyle.d.ts

@@ -1,5 +1,5 @@
-import { document_d_exports } from "../types/document.js";
 import { ColorValue } from "../types/colors.js";
+import { document_d_exports } from "../types/document.js";
 import { Properties } from "csstype";
 //#region src/utils/formatToStyle.d.ts
 type CSSProperties = Properties<string | number>;

package/dist/utils/formatToStyle.js

@@ -151,6 +151,33 @@ function borderToStyle(border, side = "", theme) {
 	});
 	return style;
 }
+const HALF_STEP_SHADING_PATTERNS = /* @__PURE__ */ new Set([
+	"pct12",
+	"pct37",
+	"pct62",
+	"pct87"
+]);
+const AUTO_PATTERN_COLOR = "000000";
+const AUTO_PATTERN_BACKGROUND = "FFFFFF";
+function percentageShadingRatio(pattern) {
+	if (!pattern?.startsWith("pct")) return;
+	const percentage = Number.parseInt(pattern.slice(3), 10);
+	if (!Number.isFinite(percentage)) return;
+	return (percentage + (HALF_STEP_SHADING_PATTERNS.has(pattern) ? .5 : 0)) / 100;
+}
+function resolvePatternHex({ color, fallback, theme }) {
+	const resolved = resolveShadingColor(color, theme);
+	return /^#(?<hex>[0-9A-F]{6})$/iu.exec(resolved)?.groups?.["hex"]?.toUpperCase() ?? fallback;
+}
+function blendShadingColors({ foreground, background, ratio }) {
+	const channels = [];
+	for (let offset = 0; offset < 6; offset += 2) {
+		const foregroundChannel = Number.parseInt(foreground.slice(offset, offset + 2), 16);
+		const backgroundChannel = Number.parseInt(background.slice(offset, offset + 2), 16);
+		channels.push(Math.round(foregroundChannel * ratio + backgroundChannel * (1 - ratio)).toString(16).padStart(2, "0"));
+	}
+	return `#${channels.join("").toUpperCase()}`;
+}
 /**
 * Convert ShadingProperties to background color
 *
@@ -161,13 +188,26 @@ function borderToStyle(border, side = "", theme) {
 function resolveShadingFill(shading, theme) {
 	if (!shading) return "";
 	if (shading.pattern === "nil") return "";
+	const percentageRatio = percentageShadingRatio(shading.pattern);
+	if (percentageRatio !== void 0) return blendShadingColors({
+		foreground: resolvePatternHex({
+			color: shading.color,
+			fallback: AUTO_PATTERN_COLOR,
+			theme
+		}),
+		background: resolvePatternHex({
+			color: shading.fill,
+			fallback: AUTO_PATTERN_BACKGROUND,
+			theme
+		}),
+		ratio: percentageRatio
+	});
 	if (shading.fill) {
 		if (shading.fill.auto) return "";
 		if (shading.fill.rgb === "auto" || shading.fill.rgb === "FFFFFF") return "";
 		return resolveShadingColor(shading.fill, theme);
 	}
 	if (shading.pattern === "solid" && shading.color) return resolveShadingColor(shading.color, theme);
-	if (shading.pattern && shading.pattern.startsWith("pct") && shading.color) return resolveShadingColor(shading.color, theme);
 	return "";
 }
 /**

package/dist/watermark/index.js

@@ -1,3 +1,4 @@
+import { isEmptyParagraph } from "../docx/paragraphParser.js";
 //#region src/watermark/index.ts
 /**
 * Schemes allowed for a picture watermark's external image target
@@ -42,6 +43,12 @@ function setDocumentWatermark(doc, watermark) {
 	const nextHeaders = /* @__PURE__ */ new Map();
 	if (headers) for (const [rId, header] of headers) {
 		const next = { ...header };
+		const retainedHostIndex = next.watermarkBlockIndex;
+		const retainedHost = next.rawWatermarkXml !== void 0 && retainedHostIndex !== void 0 ? next.content.at(retainedHostIndex) : void 0;
+		if (retainedHostIndex !== void 0 && retainedHost?.type === "paragraph" && isEmptyParagraph(retainedHost)) {
+			next.content = [...next.content];
+			next.content.splice(retainedHostIndex, 1);
+		}
 		if (watermark === void 0) {
 			delete next.watermark;
 			delete next.watermarkBlockIndex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -115,7 +115,7 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.19.0",
+    "@stll/docx-core": "^0.19.2",
     "@stll/docx-utils": "^0.1.0",
     "@stll/template-conditions": "^0.1.0",
     "better-result": "3.0.1",