@stll/folio-core 0.44.0 → 0.45.0

package/dist/prosemirror/schema/nodes.d.ts

@@ -264,6 +264,25 @@ type ImagePositionAttrs = {
     align?: NonNullable<document_d_exports.ImagePosition["vertical"]["alignment"]>;
   };
 };
+/**
+ * The EMUs a drawing's pixel attributes were projected from, keyed by the
+ * pixel attribute each one became.
+ *
+ * EMU → px → EMU does not land back on the same number: a size rounds to whole
+ * pixels, a stroke or an inset to two. Without the authored value beside the
+ * projected one, opening a document and saving it again moved every drawing
+ * off the number its author wrote. `fromProseDoc` writes the authored EMU back
+ * while the pixel attribute still projects from it, and converts the pixel
+ * attribute once an editor command has moved it.
+ *
+ * A key carries `undefined` when the source authored no such value, so an
+ * absent value stays absent rather than acquiring one the document never had.
+ */
+type AuthoredEmuAttrs<Key extends string> = { readonly [K in Key]?: number | undefined; };
+/** The pixel attributes a drawing's `wp:wrap*` insets are projected into. */
+type WrapDistanceAttr = "distTop" | "distBottom" | "distLeft" | "distRight";
+/** The pixel attributes a text box's internal margins are projected into. */
+type TextBoxMarginAttr = "marginTop" | "marginBottom" | "marginLeft" | "marginRight";
 /**
  * Image node attributes
  */
@@ -320,6 +339,16 @@ type ImageAttrs = {
   position?: ImagePositionAttrs;
   /** Use the containing table cell as the anchor's positioning scope (the OOXML default). */
   layoutInCell?: boolean;
+  /**
+   * The image carries no information, so assistive technology skips it
+   * (`wp:docPr`'s decorative extension). Not {@link hidden}: a decorative
+   * image is still displayed.
+   */
+  decorative?: boolean;
+  /** `wp:docPr @hidden`: the drawing is not displayed. */
+  hidden?: boolean;
+  /** `wp:docPr` extensions folio does not model, carried through verbatim. */
+  docPrExtensions?: string[];
   /**
    * Authored `a:graphicFrameLocks`. Carried through the editor so a resize,
    * which forces the serializer to regenerate DrawingML, cannot silently
@@ -328,6 +357,8 @@ type ImageAttrs = {
   frameLocks?: document_d_exports.ImageFrameLocks;
   /** Border width in pixels */
   borderWidth?: number;
+  /** The EMUs behind `width`, `height`, `borderWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "borderWidth" | WrapDistanceAttr>;
   /** Border color as CSS color string */
   borderColor?: string;
   /** Border style (CSS border-style value) */
@@ -468,6 +499,12 @@ type ShapeAttrs = {
   geometryAdjustments?: string;
   /** Unique identifier */
   shapeId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  shapeName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Width in pixels */
   width?: number;
   /** Height in pixels */
@@ -494,6 +531,8 @@ type ShapeAttrs = {
   outlineStyle?: OutlineStyleAttr;
   /** Line cap */
   outlineCap?: NonNullable<document_d_exports.ShapeOutline["cap"]>;
+  /** Line join */
+  outlineJoin?: NonNullable<document_d_exports.ShapeOutline["join"]>;
   /** Head arrow/end marker */
   outlineHeadEnd?: NonNullable<document_d_exports.ShapeOutline["headEnd"]>;
   /** Tail arrow/end marker */
@@ -538,6 +577,8 @@ type ShapeAttrs = {
    * census).
    */
   _docxRunFormatting?: document_d_exports.TextFormatting;
+  /** The EMUs behind `width`, `height`, `outlineWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr>;
 };
 /**
  * Text box node attributes
@@ -551,6 +592,8 @@ type TextBoxAttrs = {
   width?: number;
   /** Height in pixels */
   height?: number;
+  /** The EMUs behind the size, `outlineWidth`, the wrap insets and the margins. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr | TextBoxMarginAttr>;
   /** Text fitting behavior */
   autoFit?: document_d_exports.ShapeTextBody["autoFit"];
   /** Authored DrawingML WordArt metadata. */
@@ -559,6 +602,12 @@ type TextBoxAttrs = {
   textWrap?: document_d_exports.ShapeTextBody["textWrap"];
   /** Unique identifier */
   textBoxId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  textBoxName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Fill color as CSS color */
   fillColor?: string;
   /** Outline width in pixels */
@@ -836,4 +885,4 @@ type TableCellAttrs = {
   _docxVMergeContinuationCells?: unknown;
 };
 //#endregion
-export { BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };
+export { AuthoredEmuAttrs, BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };

package/dist/utils/base64.d.ts

@@ -0,0 +1,36 @@
+//#region src/utils/base64.d.ts
+/**
+ * The package's one bytes-to-base64 encoder.
+ *
+ * Every call site that spelled this itself got a different answer to the same
+ * two questions, and one of them got the first question wrong:
+ *
+ * - `btoa(new TextDecoder("latin1").decode(bytes))` is not a binary string.
+ *   The Encoding standard maps the `latin1` label to windows-1252, so bytes
+ *   0x80-0x9F decode to characters outside Latin-1 and `btoa` throws
+ *   `InvalidCharacterError` on them. Ordinary image bytes contain those values,
+ *   so the browser path of that spelling fails on real input.
+ * - `String.fromCharCode(...chunk)` is correct but spreads a chunk's worth of
+ *   arguments per call, and the intermediate binary string is as large as the
+ *   input.
+ *
+ * Neither question has to be asked per call site, so it is asked here once.
+ * The runtime's own encoder answers it when the runtime has one, and the
+ * portable encoder below answers it when not; both produce canonical base64,
+ * so the choice is invisible in the output.
+ */
+/**
+ * Encode into exactly one intermediate buffer: ASCII codes are written into a
+ * single array and decoded once, so a megabyte-scale input leaves the output
+ * string and nothing else.
+ *
+ * Exported because the runtimes the tests run on all carry a native encoder,
+ * and the fallback is the branch the browsers that lack one take.
+ */
+declare const encodeBase64Portable: (bytes: Uint8Array) => string;
+/** Encode bytes as canonical, padded, standard-alphabet base64. */
+declare const bytesToBase64: (bytes: Uint8Array) => string;
+/** Encode bytes as a `data:` URL with the given media type. */
+declare const bytesToDataUrl: (bytes: Uint8Array, mimeType: string) => string;
+//#endregion
+export { bytesToBase64, bytesToDataUrl, encodeBase64Portable };

package/dist/utils/base64.js

@@ -0,0 +1,40 @@
+//#region src/utils/base64.ts
+const BASE64_CODES = Uint8Array.from("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", (character) => character.charCodeAt(0));
+const BASE64_PAD = 61;
+/**
+* Encode into exactly one intermediate buffer: ASCII codes are written into a
+* single array and decoded once, so a megabyte-scale input leaves the output
+* string and nothing else.
+*
+* Exported because the runtimes the tests run on all carry a native encoder,
+* and the fallback is the branch the browsers that lack one take.
+*/
+const encodeBase64Portable = (bytes) => {
+	const groups = Math.ceil(bytes.length / 3);
+	const encoded = new Uint8Array(groups * 4);
+	let read = 0;
+	let write = 0;
+	for (; read + 2 < bytes.length; read += 3) {
+		const triple = bytes[read] << 16 | bytes[read + 1] << 8 | bytes[read + 2];
+		encoded[write] = BASE64_CODES[triple >> 18 & 63];
+		encoded[write + 1] = BASE64_CODES[triple >> 12 & 63];
+		encoded[write + 2] = BASE64_CODES[triple >> 6 & 63];
+		encoded[write + 3] = BASE64_CODES[triple & 63];
+		write += 4;
+	}
+	const remaining = bytes.length - read;
+	if (remaining > 0) {
+		const tail = bytes[read] << 16 | (remaining === 2 ? bytes[read + 1] << 8 : 0);
+		encoded[write] = BASE64_CODES[tail >> 18 & 63];
+		encoded[write + 1] = BASE64_CODES[tail >> 12 & 63];
+		encoded[write + 2] = remaining === 2 ? BASE64_CODES[tail >> 6 & 63] : BASE64_PAD;
+		encoded[write + 3] = BASE64_PAD;
+	}
+	return new TextDecoder().decode(encoded);
+};
+/** Encode bytes as canonical, padded, standard-alphabet base64. */
+const bytesToBase64 = ("toBase64" in Uint8Array.prototype ? (bytes) => bytes.toBase64() : void 0) ?? encodeBase64Portable;
+/** Encode bytes as a `data:` URL with the given media type. */
+const bytesToDataUrl = (bytes, mimeType) => `data:${mimeType};base64,${bytesToBase64(bytes)}`;
+//#endregion
+export { bytesToBase64, bytesToDataUrl, encodeBase64Portable };

package/dist/utils/clipboard.js

@@ -1,5 +1,6 @@
 import { htmlCommentEnd } from "./htmlComments.js";
 import { stripXmlDeclarations } from "./stripXmlDeclarations.js";
+import { sanitizeXmlCharacters } from "@stll/docx-core";
 import createDOMPurify from "dompurify";
 //#region src/utils/clipboard.ts
 /**
@@ -567,7 +568,7 @@ function createTextRun(text, formatting) {
 		...formatting !== void 0 ? { formatting } : {},
 		content: [{
 			type: "text",
-			text
+			text: sanitizeXmlCharacters(text)
 		}]
 	};
 }

package/dist/utils/units.d.ts

@@ -48,6 +48,15 @@ declare function emuToPixels(emu: number | undefined | null): number;
  * floating-point drift (e.g. 52 px → 495299.99999999994) out of the document.
  */
 declare function pixelsToEmu(px: number): number;
+/**
+ * Convert EMUs to pixels for a stroke width.
+ *
+ * Strokes are sub-pixel, so unlike a box size they keep two decimals rather
+ * than rounding to whole pixels. The projection is still lossy: a consumer that
+ * has to write the document's own number back carries the authored EMU beside
+ * the pixels rather than converting these back.
+ */
+declare function emuToStrokePixels(emu: number): number;
 /**
  * Convert EMUs to twips. Twips are integer-typed in OOXML; round here.
  */
@@ -96,4 +105,4 @@ declare function clamp(value: number, min: number, max: number): number;
  */
 declare function formatPx(px: number): string;
 //#endregion
-export { AUTO_PARAGRAPH_SPACING_PX, PIXELS_PER_INCH, TWIPS_PER_INCH, clamp, eighthsToPixels, emuToPixels, emuToTwips, formatPx, halfPointsToPixels, halfPointsToPoints, pixelsToEmu, pixelsToTwips, pointsToHalfPoints, pointsToPixels, roundPixels, twipsToEmu, twipsToPixels };
+export { AUTO_PARAGRAPH_SPACING_PX, PIXELS_PER_INCH, TWIPS_PER_INCH, clamp, eighthsToPixels, emuToPixels, emuToStrokePixels, emuToTwips, formatPx, halfPointsToPixels, halfPointsToPoints, pixelsToEmu, pixelsToTwips, pointsToHalfPoints, pointsToPixels, roundPixels, twipsToEmu, twipsToPixels };

package/dist/utils/units.js

@@ -68,6 +68,17 @@ function pixelsToEmu(px) {
 	return Math.round(px / 96 * EMUS_PER_INCH);
 }
 /**
+* Convert EMUs to pixels for a stroke width.
+*
+* Strokes are sub-pixel, so unlike a box size they keep two decimals rather
+* than rounding to whole pixels. The projection is still lossy: a consumer that
+* has to write the document's own number back carries the authored EMU beside
+* the pixels rather than converting these back.
+*/
+function emuToStrokePixels(emu) {
+	return roundPixels(emu / EMUS_PER_INCH * 96);
+}
+/**
 * Convert EMUs to twips. Twips are integer-typed in OOXML; round here.
 */
 function emuToTwips(emu) {
@@ -136,4 +147,4 @@ function formatPx(px) {
 	return `${roundPixels(px)}px`;
 }
 //#endregion
-export { AUTO_PARAGRAPH_SPACING_PX, PIXELS_PER_INCH, TWIPS_PER_INCH, clamp, eighthsToPixels, emuToPixels, emuToTwips, formatPx, halfPointsToPixels, halfPointsToPoints, pixelsToEmu, pixelsToTwips, pointsToHalfPoints, pointsToPixels, roundPixels, twipsToEmu, twipsToPixels };
+export { AUTO_PARAGRAPH_SPACING_PX, PIXELS_PER_INCH, TWIPS_PER_INCH, clamp, eighthsToPixels, emuToPixels, emuToStrokePixels, emuToTwips, formatPx, halfPointsToPixels, halfPointsToPoints, pixelsToEmu, pixelsToTwips, pointsToHalfPoints, pointsToPixels, roundPixels, twipsToEmu, twipsToPixels };

package/dist/utils/urlSecurity.d.ts

@@ -2,6 +2,12 @@ import { sanitizeExternalUrl } from "@stll/docx-core";
 //#region src/utils/urlSecurity.d.ts
 declare function normalizeUserUrl(rawUrl: string): string;
 declare function isAllowedUserUrl(rawUrl: string): boolean;
-declare function sanitizeLinkTarget(target: string | undefined): string;
+type AnchorTargetAttrs = {
+  target: string;
+  rel: string;
+};
+declare function anchorTargetAttrs(authoredFrame: string | undefined): AnchorTargetAttrs;
+/** `window.open` features carrying the same guarantees as {@link ANCHOR_REL}. */
+declare function windowFeaturesFor({ rel }: AnchorTargetAttrs): string;
 //#endregion
-export { isAllowedUserUrl, normalizeUserUrl, sanitizeExternalUrl, sanitizeLinkTarget };
+export { AnchorTargetAttrs, anchorTargetAttrs, isAllowedUserUrl, normalizeUserUrl, sanitizeExternalUrl, windowFeaturesFor };

package/dist/utils/urlSecurity.js

@@ -23,8 +23,26 @@ function normalizeUserUrl(rawUrl) {
 function isAllowedUserUrl(rawUrl) {
 	return normalizeUserUrl(rawUrl) !== "";
 }
-function sanitizeLinkTarget(target) {
-	return target && ALLOWED_TARGETS.has(target) ? target : "_blank";
+/**
+* The `target` and `rel` one authored frame may produce on a DOM anchor.
+*
+* A `w:tgtFrame` is a frame name, and a named frame addresses another browsing
+* context: honouring an arbitrary one would let a document reach a frame it did
+* not create. Every anchor and every navigation folio produces goes through
+* here, so the clamp and the `rel` that must accompany `_blank` are decided
+* once. The authored name itself stays in the model and is written back on
+* save; clamping it at parse rewrote the document.
+*/
+const ANCHOR_REL = "noopener noreferrer";
+function anchorTargetAttrs(authoredFrame) {
+	return {
+		target: authoredFrame && ALLOWED_TARGETS.has(authoredFrame) ? authoredFrame : "_blank",
+		rel: ANCHOR_REL
+	};
+}
+/** `window.open` features carrying the same guarantees as {@link ANCHOR_REL}. */
+function windowFeaturesFor({ rel }) {
+	return rel.replaceAll(" ", ",");
 }
 function findFirstPathSeparatorIndex(value) {
 	return [
@@ -44,4 +62,4 @@ function startsWithPortSuffix(value) {
 	return index > 0 && (index === value.length || "/?#".includes(value[index]));
 }
 //#endregion
-export { isAllowedUserUrl, normalizeUserUrl, sanitizeExternalUrl, sanitizeLinkTarget };
+export { anchorTargetAttrs, isAllowedUserUrl, normalizeUserUrl, sanitizeExternalUrl, windowFeaturesFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.44.0",
+  "version": "0.45.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",
@@ -121,7 +121,7 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.22.0",
+    "@stll/docx-core": "^0.23.0",
     "@stll/docx-utils": "^0.1.0",
     "@stll/template-conditions": ">=0.4.0 <1.0.0",
     "better-result": "3.0.1",