@stll/folio-core 0.45.0 → 0.47.0

package/dist/docx/previewBudget.js

@@ -1,49 +1,80 @@
 //#region src/docx/previewBudget.ts
-const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
-const MEBIBYTE = 1024 * 1024;
+/** Both SVG producers encode their drawing into the URL rather than base64. */
+const SVG_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
+/**
+* Eight times what a producer may spend on one drawing, which is a package
+* holding a handful of the largest previews folio will build.
+*/
+const SVG_PREVIEW_PACKAGE_CHARACTERS = 8 * (1024 * 1024);
 const PREVIEW_KINDS = {
 	/** A VML shape folio renders rather than projects (`v:shape`, `v:rect`, ...). */
 	vmlShape: {
+		backing: "source",
 		mimeType: "image/svg+xml",
 		filename: "vml-shape-preview.svg",
-		srcPrefix: VML_PREVIEW_DATA_URL_PREFIX,
-		maxPackageCharacters: 8 * MEBIBYTE
+		srcPrefix: SVG_PREVIEW_DATA_URL_PREFIX,
+		maxPackageCharacters: SVG_PREVIEW_PACKAGE_CHARACTERS
 	},
 	/**
-	* A SmartArt diagram: its extent filled with one flat rectangle per shape.
+	* A WordprocessingGroup (`wpg:wgp`) folio renders rather than projects.
 	*
-	* A raster rather than a vector because the display list decodes only base64
-	* PNG and JPEG, so a vector preview would be missing from every display-list
-	* backend (PDF among them) while still showing in the DOM. That is what
-	* makes this preview expensive: one of them is 7.3 MB of data URL whatever
-	* the package weighs, because its cost follows the extent the author chose
-	* rather than anything the drawing contains.
+	* The group's shapes, their text and any picture they carry are drawn into
+	* one SVG, so a package with many groups retains as much generated text as a
+	* package of VML shapes does, from a producer bounded per drawing the same
+	* way. It was missing from this table, which is not a preview with a generous
+	* cap but a preview with none: the matcher below never named it, so no
+	* package was ever charged for one.
+	*/
+	wpGroup: {
+		backing: "source",
+		mimeType: "image/svg+xml",
+		filename: "wordprocessing-group.svg",
+		srcPrefix: SVG_PREVIEW_DATA_URL_PREFIX,
+		maxPackageCharacters: SVG_PREVIEW_PACKAGE_CHARACTERS
+	},
+	/**
+	* A SmartArt diagram: its extent filled with one flat rectangle per shape.
 	*
-	* Across the public corpus, the fifty packages that produce one retain a
-	* median of 7.3 MB and a maximum of 51.3 MB (ten previews, from a package
-	* under a megabyte). The cap is set above that maximum: it refuses no
-	* legitimate file in the corpus while bounding what had no bound at all, and
-	* it is a ceiling rather than a fix. The fix is for the preview to be a
-	* descriptor the renderer rasterizes, which needs the display-list contract
-	* to carry one.
+	* It used to be a raster in `src`, because the display list decoded only
+	* base64 PNG and JPEG and a vector preview would have been missing from
+	* every backend but the DOM. That cost 7.3 MB of data URL per diagram
+	* whatever the package weighed, up to 51.3 MB in one corpus package, because
+	* it followed the extent the author chose rather than anything the drawing
+	* contained. It is a `PreviewDescriptor` now, which both backends draw, and
+	* the bound on it is the shape cap the parse applies to the description.
 	*/
-	smartArt: {
-		mimeType: "image/png",
-		filename: "smartart-preview.png",
-		srcPrefix: "data:image/png;base64,",
-		maxPackageCharacters: 64 * MEBIBYTE
-	}
+	smartArt: { backing: "descriptor" }
 };
 const KIND_NAMES = Object.keys(PREVIEW_KINDS);
 /**
+* Whether a package charges this kind, narrowing the name to a source-backed
+* one: the predicate reads the same field `SourceBackedKindName` selects on.
+*/
+const isSourceBacked = (name) => {
+	const kind = PREVIEW_KINDS[name];
+	switch (kind.backing) {
+		case "source": return true;
+		case "descriptor": return false;
+		default: return kind;
+	}
+};
+const SOURCE_BACKED_KIND_NAMES = KIND_NAMES.filter(isSourceBacked);
+/**
 * The kind a model image was generated as, or `undefined` for one the package
-* actually carries. A generated preview has no relationship behind it, so
-* `rId` is empty; the filename and data-URL prefix name which producer made it.
+* actually carries. A generated preview has no relationship behind it; the
+* filename and data-URL prefix name which producer made it.
+*
+* "No relationship" is read as the one spelling `RelationshipId` leaves: a
+* field that is absent or `undefined`. The walk takes an unvalidated object,
+* so the check stays, but it no longer has a second spelling to accept.
+*
+* Only a source-backed kind can be named this way. A descriptor-backed preview
+* has no `src` to match, so no image the model carries can be charged to it.
 */
 const previewKindOf = (value) => {
-	if (!("type" in value) || value.type !== "image" || !("rId" in value) || value.rId !== "" || !("src" in value) || typeof value.src !== "string" || !("mimeType" in value) || !("filename" in value)) return;
+	if (!("type" in value) || value.type !== "image" || "rId" in value && value.rId !== void 0 || !("src" in value) || typeof value.src !== "string" || !("mimeType" in value) || !("filename" in value)) return;
 	const { src, mimeType, filename } = value;
-	return KIND_NAMES.find((name) => {
+	return SOURCE_BACKED_KIND_NAMES.find((name) => {
 		const kind = PREVIEW_KINDS[name];
 		return mimeType === kind.mimeType && filename === kind.filename && src.startsWith(kind.srcPrefix);
 	});
@@ -55,7 +86,7 @@ const previewKindOf = (value) => {
 * and never touches the preserved XML the package saves from.
 */
 const enforcePackagePreviewBudget = (root, overrides = {}) => {
-	const remaining = new Map(KIND_NAMES.map((name) => [name, Math.max(0, overrides[name] ?? PREVIEW_KINDS[name].maxPackageCharacters)]));
+	const remaining = new Map(SOURCE_BACKED_KIND_NAMES.map((name) => [name, Math.max(0, overrides[name] ?? PREVIEW_KINDS[name].maxPackageCharacters)]));
 	const visited = /* @__PURE__ */ new WeakSet();
 	const visit = (value) => {
 		if (value === null || typeof value !== "object" || visited.has(value)) return;
@@ -85,4 +116,4 @@ const enforcePackagePreviewBudget = (root, overrides = {}) => {
 	visit(root);
 };
 //#endregion
-export { PREVIEW_KINDS, VML_PREVIEW_DATA_URL_PREFIX, enforcePackagePreviewBudget };
+export { PREVIEW_KINDS, enforcePackagePreviewBudget };

package/dist/docx/propertyElementAttributes.d.ts

@@ -0,0 +1,178 @@
+//#region src/docx/propertyElementAttributes.d.ts
+/**
+ * Which attributes of a property element the model has a field for.
+ *
+ * A property element is an attribute bag: `w:ind`, `w:spacing`, `w:framePr`,
+ * `w:tab`, a `w:pBdr` side, `w:shd`. The child dispatcher decides them whole —
+ * a handler either reads the element or hands back its bytes — and that is
+ * exactly as far as it goes. `<w:ind w:leftChars="100"/>` is kept entire
+ * because the reader took nothing from it, and `<w:ind w:left="720"
+ * w:leftChars="100"/>` is modelled and loses the character unit, because the
+ * reader took something. The census measures one attribute at a time, so the
+ * second case reported as surviving.
+ *
+ * The fix is the attribute remainder that `w:p`'s `w:rsid*` attributes already
+ * ride, applied one level down: every attribute with no model field is kept on
+ * the record, decided on the resolved local name, written back by
+ * `serializePreservedAttributes`. The remainder predicate has to be derived
+ * from the model rather than hand-listed, or it is a mirror of the reader and
+ * drifts the first time a field is added — so each table below is
+ * `as const satisfies ModelledAttributes<…>` over the record's own fields, and
+ * a field that gains no entry does not compile.
+ *
+ * The tables live together, in a module with no runtime dependencies, because
+ * three callers consult them: the reader (to compute the remainder), and the
+ * container-survival census (to state a subject attribute beside a modelled
+ * sibling, which is what catches a whole-or-nothing reader at all). The writer
+ * needs no copy: it hands the fragments it is about to emit to
+ * `serializePreservedAttributes`, which drops a remainder entry that would
+ * spell one of them again.
+ *
+ * A field may name more than one attribute. `ParagraphFormatting.indentLeft`
+ * is filled from `w:left` or from the Strict `w:start`, and both have to be
+ * out of the remainder or a save writes the same indent twice under two
+ * spellings.
+ */
+/**
+ * The attributes one record's fields are read from, keyed by field.
+ *
+ * `Record`, never `Partial<Record>`: the key set is the record's own fields,
+ * so a field that has no attribute to name has to say so with an empty list
+ * rather than by being absent.
+ */
+type ModelledAttributes<Field extends string> = Readonly<Record<Field, string | readonly string[]>>;
+/**
+ * `w:ind`. `hangingIndent` is the sign of `indentFirstLine` rather than a
+ * value of its own, so both name the attribute pair that carries it.
+ */
+declare const INDENTATION_ATTRIBUTES: {
+  readonly indentLeft: readonly ["left", "start"];
+  readonly indentRight: readonly ["right", "end"];
+  readonly indentFirstLine: readonly ["firstLine", "hanging"];
+  readonly hangingIndent: "hanging";
+};
+/**
+ * `w:spacing`. `spacingExplicit` records which of the two sides the paragraph
+ * stated itself; it is derived from them and reads no attribute of its own.
+ */
+declare const SPACING_ATTRIBUTES: {
+  readonly spaceBefore: "before";
+  readonly spaceAfter: "after";
+  readonly lineSpacing: "line";
+  readonly lineSpacingRule: "lineRule";
+  readonly beforeAutospacing: "beforeAutospacing";
+  readonly afterAutospacing: "afterAutospacing";
+  readonly spacingExplicit: readonly [];
+};
+declare const FRAME_ATTRIBUTES: {
+  readonly dropCap: "dropCap";
+  readonly lines: "lines";
+  readonly width: "w";
+  readonly height: "h";
+  readonly hSpace: "hSpace";
+  readonly vSpace: "vSpace";
+  readonly hAnchor: "hAnchor";
+  readonly vAnchor: "vAnchor";
+  readonly x: "x";
+  readonly y: "y";
+  readonly xAlign: "xAlign";
+  readonly yAlign: "yAlign";
+  readonly wrap: "wrap";
+};
+declare const TAB_STOP_ATTRIBUTES: {
+  readonly position: "pos";
+  readonly alignment: "val";
+  readonly leader: "leader";
+};
+/**
+ * `CT_Border`. The five art relationship ids are in the relationships
+ * namespace; the remainder decides on the local name, so naming them here
+ * keeps a `r:topLeft` out of it.
+ */
+declare const BORDER_ATTRIBUTES: {
+  readonly style: "val";
+  readonly color: readonly ["color", "themeColor", "themeTint", "themeShade"];
+  readonly size: "sz";
+  readonly space: "space";
+  readonly shadow: "shadow";
+  readonly frame: "frame";
+  readonly artRelationshipId: "id";
+  readonly topLeftArtRelationshipId: "topLeft";
+  readonly topRightArtRelationshipId: "topRight";
+  readonly bottomLeftArtRelationshipId: "bottomLeft";
+  readonly bottomRightArtRelationshipId: "bottomRight";
+};
+/** `CT_Shd`: direct, theme, modifier, and pattern attributes all have model fields. */
+declare const SHADING_ATTRIBUTES: {
+  readonly color: readonly ["color", "themeColor", "themeTint", "themeShade"];
+  readonly fill: readonly ["fill", "themeFill", "themeFillTint", "themeFillShade"];
+  readonly pattern: "val";
+};
+/**
+ * The same tables by the complex type whose attributes they answer for, in
+ * the order the model declares the fields.
+ *
+ * The census reads this: to catch a whole-or-nothing reader it has to state
+ * the subject attribute *beside* one the element models, and which one that
+ * is has to come from the model rather than from a list in the census. The
+ * first entry is the one it picks.
+ */
+declare const PROPERTY_ELEMENT_ATTRIBUTES: {
+  readonly CT_Ind: {
+    readonly indentLeft: readonly ["left", "start"];
+    readonly indentRight: readonly ["right", "end"];
+    readonly indentFirstLine: readonly ["firstLine", "hanging"];
+    readonly hangingIndent: "hanging";
+  };
+  readonly CT_Spacing: {
+    readonly spaceBefore: "before";
+    readonly spaceAfter: "after";
+    readonly lineSpacing: "line";
+    readonly lineSpacingRule: "lineRule";
+    readonly beforeAutospacing: "beforeAutospacing";
+    readonly afterAutospacing: "afterAutospacing";
+    readonly spacingExplicit: readonly [];
+  };
+  readonly CT_FramePr: {
+    readonly dropCap: "dropCap";
+    readonly lines: "lines";
+    readonly width: "w";
+    readonly height: "h";
+    readonly hSpace: "hSpace";
+    readonly vSpace: "vSpace";
+    readonly hAnchor: "hAnchor";
+    readonly vAnchor: "vAnchor";
+    readonly x: "x";
+    readonly y: "y";
+    readonly xAlign: "xAlign";
+    readonly yAlign: "yAlign";
+    readonly wrap: "wrap";
+  };
+  readonly CT_TabStop: {
+    readonly position: "pos";
+    readonly alignment: "val";
+    readonly leader: "leader";
+  };
+  readonly CT_Border: {
+    readonly style: "val";
+    readonly color: readonly ["color", "themeColor", "themeTint", "themeShade"];
+    readonly size: "sz";
+    readonly space: "space";
+    readonly shadow: "shadow";
+    readonly frame: "frame";
+    readonly artRelationshipId: "id";
+    readonly topLeftArtRelationshipId: "topLeft";
+    readonly topRightArtRelationshipId: "topRight";
+    readonly bottomLeftArtRelationshipId: "bottomLeft";
+    readonly bottomRightArtRelationshipId: "bottomRight";
+  };
+  readonly CT_Shd: {
+    readonly color: readonly ["color", "themeColor", "themeTint", "themeShade"];
+    readonly fill: readonly ["fill", "themeFill", "themeFillTint", "themeFillShade"];
+    readonly pattern: "val";
+  };
+};
+/** Every attribute local name a table names, flattened, in field order. */
+declare const modelledAttributeNames: (modelled: ModelledAttributes<string>) => readonly string[];
+//#endregion
+export { BORDER_ATTRIBUTES, FRAME_ATTRIBUTES, INDENTATION_ATTRIBUTES, ModelledAttributes, PROPERTY_ELEMENT_ATTRIBUTES, SHADING_ATTRIBUTES, SPACING_ATTRIBUTES, TAB_STOP_ATTRIBUTES, modelledAttributeNames };

package/dist/docx/propertyElementAttributes.js

@@ -0,0 +1,114 @@
+//#region src/docx/propertyElementAttributes.ts
+/**
+* `w:ind`. `hangingIndent` is the sign of `indentFirstLine` rather than a
+* value of its own, so both name the attribute pair that carries it.
+*/
+const INDENTATION_ATTRIBUTES = {
+	indentLeft: ["left", "start"],
+	indentRight: ["right", "end"],
+	indentFirstLine: ["firstLine", "hanging"],
+	hangingIndent: "hanging"
+};
+/**
+* `w:spacing`. `spacingExplicit` records which of the two sides the paragraph
+* stated itself; it is derived from them and reads no attribute of its own.
+*/
+const SPACING_ATTRIBUTES = {
+	spaceBefore: "before",
+	spaceAfter: "after",
+	lineSpacing: "line",
+	lineSpacingRule: "lineRule",
+	beforeAutospacing: "beforeAutospacing",
+	afterAutospacing: "afterAutospacing",
+	spacingExplicit: []
+};
+const FRAME_ATTRIBUTES = {
+	dropCap: "dropCap",
+	lines: "lines",
+	width: "w",
+	height: "h",
+	hSpace: "hSpace",
+	vSpace: "vSpace",
+	hAnchor: "hAnchor",
+	vAnchor: "vAnchor",
+	x: "x",
+	y: "y",
+	xAlign: "xAlign",
+	yAlign: "yAlign",
+	wrap: "wrap"
+};
+const TAB_STOP_ATTRIBUTES = {
+	position: "pos",
+	alignment: "val",
+	leader: "leader"
+};
+/**
+* `CT_Border`. The five art relationship ids are in the relationships
+* namespace; the remainder decides on the local name, so naming them here
+* keeps a `r:topLeft` out of it.
+*/
+const BORDER_ATTRIBUTES = {
+	style: "val",
+	color: [
+		"color",
+		"themeColor",
+		"themeTint",
+		"themeShade"
+	],
+	size: "sz",
+	space: "space",
+	shadow: "shadow",
+	frame: "frame",
+	artRelationshipId: "id",
+	topLeftArtRelationshipId: "topLeft",
+	topRightArtRelationshipId: "topRight",
+	bottomLeftArtRelationshipId: "bottomLeft",
+	bottomRightArtRelationshipId: "bottomRight"
+};
+/** `CT_Shd`: direct, theme, modifier, and pattern attributes all have model fields. */
+const SHADING_ATTRIBUTES = {
+	color: [
+		"color",
+		"themeColor",
+		"themeTint",
+		"themeShade"
+	],
+	fill: [
+		"fill",
+		"themeFill",
+		"themeFillTint",
+		"themeFillShade"
+	],
+	pattern: "val"
+};
+/**
+* The same tables by the complex type whose attributes they answer for, in
+* the order the model declares the fields.
+*
+* The census reads this: to catch a whole-or-nothing reader it has to state
+* the subject attribute *beside* one the element models, and which one that
+* is has to come from the model rather than from a list in the census. The
+* first entry is the one it picks.
+*/
+const PROPERTY_ELEMENT_ATTRIBUTES = {
+	CT_Ind: INDENTATION_ATTRIBUTES,
+	CT_Spacing: SPACING_ATTRIBUTES,
+	CT_FramePr: FRAME_ATTRIBUTES,
+	CT_TabStop: TAB_STOP_ATTRIBUTES,
+	CT_Border: BORDER_ATTRIBUTES,
+	CT_Shd: SHADING_ATTRIBUTES
+};
+/** Every attribute local name a table names, flattened, in field order. */
+const modelledAttributeNames = (modelled) => {
+	const names = [];
+	for (const declared of Object.values(modelled)) {
+		if (typeof declared === "string") {
+			names.push(declared);
+			continue;
+		}
+		names.push(...declared);
+	}
+	return names;
+};
+//#endregion
+export { BORDER_ATTRIBUTES, FRAME_ATTRIBUTES, INDENTATION_ATTRIBUTES, PROPERTY_ELEMENT_ATTRIBUTES, SHADING_ATTRIBUTES, SPACING_ATTRIBUTES, TAB_STOP_ATTRIBUTES, modelledAttributeNames };

package/dist/docx/renderedPageBreakNormalization.js

@@ -30,16 +30,14 @@ const scanRun = (run, scan) => {
 };
 const scanHyperlink = (hyperlink, scan) => {
 	for (const child of hyperlink.children) {
-		if (child.type !== "run") continue;
-		const result = scanRun(child, scan);
+		if (child.type !== "run" && child.type !== "inlineWrapper") continue;
+		const result = child.type === "run" ? scanRun(child, scan) : scanParagraphContent(child, scan);
 		if (result !== void 0) return result;
 	}
 };
 const scanInlineContent = (content, scan) => {
 	for (const child of content) {
-		let result;
-		if (child.type === "run") result = scanRun(child, scan);
-		else if (child.type === "hyperlink") result = scanHyperlink(child, scan);
+		const result = scanParagraphContent(child, scan);
 		if (result !== void 0) return result;
 	}
 };
@@ -48,7 +46,7 @@ const scanParagraphContent = (content, scan) => {
 	if (content.type === "hyperlink") return scanHyperlink(content, scan);
 	if (content.type === "simpleField") return scanInlineContent(content.content, scan);
 	if (content.type === "insertion" || content.type === "deletion" || content.type === "moveFrom" || content.type === "moveTo") return scanInlineContent(content.content, scan);
-	if (content.type === "inlineSdt") {
+	if (content.type === "inlineSdt" || content.type === "inlineWrapper") {
 		for (const child of content.content) {
 			const result = scanParagraphContent(child, scan);
 			if (result !== void 0) return result;

package/dist/docx/rezip.d.ts

@@ -3,9 +3,35 @@ import { BlockContent, Hyperlink } from "../types/content.js";
 import { RawDocxContent } from "./unzip.js";
 import JSZip from "jszip";
 //#region src/docx/rezip.d.ts
-declare class DocxPackageFidelityError extends Error {
+declare const DocxPackageFidelityError_base: import("better-result").TaggedErrorClass<"DocxPackageFidelityError">;
+declare class DocxPackageFidelityError extends DocxPackageFidelityError_base<{
+  message: string;
+}> {
   constructor(message: string);
 }
+/**
+ * Raised when a save would write a section the editor never authored.
+ *
+ * Two paragraphs holding the *same* `SectionProperties` object are one
+ * section's two halves, not two sections: ProseMirror copies a node's attrs
+ * when a command splits it, and the object is passed through by reference and
+ * never cloned, so identity is what tells a copy from a second authored break.
+ * The paragraph is named because the count alone does not say which of them the
+ * save invented.
+ */
+declare class DocxDuplicateSectionCarrierError extends DocxPackageFidelityError {
+  /** The `w:paraId` of the duplicate carrier, when the package gave it one. */
+  readonly paraId: string | null;
+  /** Its position among the paragraph-level carriers, in document order. */
+  readonly carrierIndex: number;
+  /** The position of the carrier it duplicates. */
+  readonly duplicatesCarrierIndex: number;
+  constructor(options: {
+    paraId: string | null;
+    carrierIndex: number;
+    duplicatesCarrierIndex: number;
+  });
+}
 /**
  * Find the highest rId number in a relationships XML string.
  */
@@ -216,4 +242,4 @@ declare function createEmptyDocx(properties?: DocumentPropertiesOptions): Promis
  */
 declare function createDocx(doc: document_d_exports.Document, properties?: DocumentPropertiesOptions): Promise<ArrayBuffer>;
 //#endregion
-export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocumentPropertiesOptions, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };
+export { COMMENTS_CONTENT_TYPE, COMMENTS_EXTENDED_CONTENT_TYPE, COMMENTS_EXTENDED_PART, COMMENTS_EXTENDED_PART_LOWER, DocumentPropertiesOptions, DocxDuplicateSectionCarrierError, DocxPackageFidelityError, RepackOptions, addCommentsExtendedOverride, addCommentsExtendedRelationship, addMedia, addRelationship, applyUpdatesToZip, collectHeaderFooterUpdates, collectHyperlinksWithoutRId, createDocx, createEmptyDocx, findMaxRId, hasModelDrivenPictureWatermark, hasUnmaterializedHeaderFooter, hasUnmaterializedInlineResources, isDocxBuffer, notePartRelsPath, removeCommentsExtendedOverride, removeCommentsExtendedRelationship, repackDocx, repackDocxFromRaw, updateCoreProperties, updateDocumentXml, updateMultipleFiles, updateXmlFile, validateDocx, withoutAttachedTemplate };