@stll/folio-core 0.45.0 → 0.47.0

package/dist/display-list/build/strokes.js

@@ -1,58 +1,164 @@
 import { resolveCssBorderStroke } from "../../layout-painter/borderStroke.js";
 import { parseDisplayColor } from "./colors.js";
+import "./textDecorations.js";
 //#region src/display-list/build/strokes.ts
 /**
-* Border and rule strokes.
+* Every CSS `border-style` folio paints, as a display-list pattern.
 *
-* One deliberate divergence from `layout-painter/borderStroke.ts`: that helper
-* encodes a sub-pixel border width as a `color-mix` alpha because CSS quantizes
-* a fractional border to one device pixel. A display list has no device pixel,
-* and a PDF strokes 0.4pt natively, so the authored fractional width and the
-* plain colour survive here. Everything else (colour/style/width defaults) is
-* taken from the painter's helper so the two cannot drift.
+* The bevelled keywords have no display-list pattern, and Word draws
+* `threeDEmboss`/`threeDEngrave` as a plain line where the shading is
+* unavailable, so they stroke solid.
 */
-/**
-* CSS `border-style` and the raw OOXML `w:val` names both reach
-* `BorderStyle.style` (the bridge maps most, `renderParagraph` maps the rest),
-* so both vocabularies are resolved here. Everything decorative that folio does
-* not draw degrades to a plain line, matching how Word degrades on a platform
-* without the specialised glyphs.
-*/
-const STROKE_PATTERN_BY_STYLE = {
+const CSS_BORDER_STROKE_PATTERNS = {
 	none: "none",
-	nil: "none",
-	hidden: "none",
 	solid: "solid",
-	single: "solid",
-	thick: "solid",
-	inset: "solid",
-	outset: "solid",
-	ridge: "solid",
-	groove: "solid",
 	double: "double",
 	dotted: "dotted",
-	dotdash: "dashed",
-	dotdotdash: "dashed",
 	dashed: "dashed",
-	dash: "dashed",
-	dashsmallgap: "dashed",
-	dashlong: "dashed",
-	wavy: "wavy",
-	wave: "wavy",
-	wavydouble: "double"
+	groove: "solid",
+	ridge: "solid",
+	inset: "solid",
+	outset: "solid"
 };
-const DEFAULT_PATTERN = "solid";
-const strokePatternForStyle = (style) => {
-	if (style === void 0) return DEFAULT_PATTERN;
-	return STROKE_PATTERN_BY_STYLE[style.trim().toLowerCase()] ?? DEFAULT_PATTERN;
+/**
+* Every `ST_PresetLineDashVal` member, as a display-list pattern.
+*
+* DrawingML distinguishes dash length (`lgDash`) and the system patterns
+* (`sysDash`) from the plain ones; a display list has three periodic patterns,
+* so the distinction collapses to dotted or dashed. It collapses here, once,
+* rather than at whichever consumer happened to know the spelling.
+*/
+const PRESET_DASH_STROKE_PATTERNS = {
+	solid: "solid",
+	dot: "dotted",
+	dash: "dashed",
+	lgDash: "dashed",
+	dashDot: "dashed",
+	lgDashDot: "dashed",
+	lgDashDotDot: "dashed",
+	sysDash: "dashed",
+	sysDot: "dotted",
+	sysDashDot: "dashed",
+	sysDashDotDot: "dashed"
 };
 /**
-* Turn an authored border into a paintable stroke. `undefined` stroke means
-* "draw nothing": an explicit `none`/`nil` style, a non-positive width, or a
-* colour this producer cannot resolve.
+* Every `ST_Underline` member the model carries, one row per member.
+*
+* The three fields are one decision and belong on one line: `wavyDouble` is
+* Word's two waves, which is the `wavy` pattern drawn twice rather than the
+* `double` pattern, so a reader who has the pattern without the count has half
+* the member. `double` is one stroke, because the display list's `double`
+* pattern already carries the second rule and the gap between them. CSS can
+* draw neither two waves nor `words`, so the editor approximates them; the page
+* and the PDF do not have to.
+*
+* Word draws `thick` and the seven `*Heavy` members at twice the rule the font
+* asks for, and the rest at the plain rule. Without the weight the display list
+* strokes every member at the plain thickness, so `dottedHeavy` and `dotted`
+* come out as the same line on the page and in the PDF while the editor draws
+* them apart. The DOM spells this same weight as a
+* `text-decoration-thickness` length (`utils/formatToStyle.ts`), so which
+* members are heavy is decided here and nowhere else.
+*
+* `none` states no decoration: a run whose underline says so paints nothing,
+* and its weight and stroke count are the plain ones by default rather than by
+* decision.
 */
-const resolveBorderStroke = (border) => {
-	const pattern = strokePatternForStyle(border.style);
+const UNDERLINE_STROKES = {
+	none: {
+		pattern: "none",
+		weight: 1,
+		strokes: 1
+	},
+	single: {
+		pattern: "solid",
+		weight: 1,
+		strokes: 1
+	},
+	words: {
+		pattern: "solid",
+		weight: 1,
+		strokes: 1
+	},
+	double: {
+		pattern: "double",
+		weight: 1,
+		strokes: 1
+	},
+	thick: {
+		pattern: "solid",
+		weight: 2,
+		strokes: 1
+	},
+	dotted: {
+		pattern: "dotted",
+		weight: 1,
+		strokes: 1
+	},
+	dottedHeavy: {
+		pattern: "dotted",
+		weight: 2,
+		strokes: 1
+	},
+	dash: {
+		pattern: "dashed",
+		weight: 1,
+		strokes: 1
+	},
+	dashedHeavy: {
+		pattern: "dashed",
+		weight: 2,
+		strokes: 1
+	},
+	dashLong: {
+		pattern: "dashed",
+		weight: 1,
+		strokes: 1
+	},
+	dashLongHeavy: {
+		pattern: "dashed",
+		weight: 2,
+		strokes: 1
+	},
+	dotDash: {
+		pattern: "dashed",
+		weight: 1,
+		strokes: 1
+	},
+	dashDotHeavy: {
+		pattern: "dashed",
+		weight: 2,
+		strokes: 1
+	},
+	dotDotDash: {
+		pattern: "dashed",
+		weight: 1,
+		strokes: 1
+	},
+	dashDotDotHeavy: {
+		pattern: "dashed",
+		weight: 2,
+		strokes: 1
+	},
+	wave: {
+		pattern: "wavy",
+		weight: 1,
+		strokes: 1
+	},
+	wavyHeavy: {
+		pattern: "wavy",
+		weight: 2,
+		strokes: 1
+	},
+	wavyDouble: {
+		pattern: "wavy",
+		weight: 1,
+		strokes: 2
+	}
+};
+/** What a border with a width but no style paints: the CSS initial. */
+const DEFAULT_PATTERN = "solid";
+const strokeWith = (border, pattern) => {
 	if (pattern === "none") return {};
 	const css = resolveCssBorderStroke(border);
 	const isSubPixelEncoded = css.color.startsWith("color-mix");
@@ -68,11 +174,25 @@ const resolveBorderStroke = (border) => {
 		pattern
 	} };
 };
-/** CSS `text-decoration-style` → the display list's stroke patterns. */
-const decorationPatternForStyle = (style) => {
-	if (style === void 0) return DEFAULT_PATTERN;
-	const pattern = STROKE_PATTERN_BY_STYLE[style.trim().toLowerCase()];
-	return pattern === void 0 || pattern === "none" ? DEFAULT_PATTERN : pattern;
-};
+/**
+* Turn an authored CSS border into a paintable stroke. `undefined` stroke means
+* "draw nothing": an explicit `none` style, a non-positive width, or a colour
+* this producer cannot resolve.
+*/
+const resolveBorderStroke = (border) => strokeWith(border, border.style === void 0 ? DEFAULT_PATTERN : CSS_BORDER_STROKE_PATTERNS[border.style]);
+/** Turn a shape or text-box outline into a paintable stroke. */
+const resolveOutlineStroke = (outline) => strokeWith({
+	color: outline.color,
+	width: outline.width
+}, outline.dash === void 0 ? DEFAULT_PATTERN : PRESET_DASH_STROKE_PATTERNS[outline.dash]);
+/**
+* An authored underline's row. An undefined member is a `w:u` with no `w:val`,
+* which Word draws as the plain single rule, so it resolves to that member's
+* row rather than to a default per field.
+*/
+const underlineStrokes = (style) => style === void 0 ? UNDERLINE_STROKES.single : UNDERLINE_STROKES[style];
+const underlinePattern = (style) => underlineStrokes(style).pattern;
+const underlineWeight = (style) => underlineStrokes(style).weight;
+const underlineStrokeCount = (style) => underlineStrokes(style).strokes;
 //#endregion
-export { decorationPatternForStyle, resolveBorderStroke };
+export { CSS_BORDER_STROKE_PATTERNS, PRESET_DASH_STROKE_PATTERNS, UNDERLINE_STROKES, resolveBorderStroke, resolveOutlineStroke, underlinePattern, underlineStrokeCount, underlineWeight };

package/dist/display-list/build/tablePrimitives.js

@@ -2,6 +2,8 @@ import { createTableCellFlowState, placeTableCellBlock } from "../../layout-engi
 import { buildTableCellGrid, buildTableCellPlacements, getSourceCellAt } from "../../layout-engine/measure/tableCellGrid.js";
 import { tableFragmentBottomBorders } from "../../layout-engine/measure/tableFragmentBorderGeometry.js";
 import { resolveTableCellPadding } from "../../layout-engine/types.js";
+import { cellTextRotationDegrees } from "../../layout-painter/renderTable.js";
+import { paintsCssBorder } from "../../utils/borderCss.js";
 import { HIT_REGION_KINDS } from "../primitives.js";
 import { parseDisplayColor } from "./colors.js";
 import { paintImageFragment } from "./imagePrimitives.js";
@@ -25,7 +27,7 @@ import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
 * engineering a gradient.
 */
 /** A cell edge is "visible" for collapse purposes on style alone, as the painter decides it. */
-const hasVisibleBorder = (border) => border !== void 0 && border.style !== "none" && border.style !== "nil";
+const hasVisibleBorder = (border) => border !== void 0 && paintsCssBorder(border.style);
 const strokeFor = (border, context, label) => {
 	if (!hasVisibleBorder(border) || !border) return;
 	const { stroke, unresolvedColor } = resolveBorderStroke(border);
@@ -97,7 +99,7 @@ const paintCell = ({ composer, cell, cellMeasure, box, context, paintTextBox, si
 	const contentXPx = box.xPx + widths.left + padding.left;
 	const contentYPx = box.yPx + widths.top + padding.top;
 	const contentWidthPx = Math.max(0, cellMeasure.width - padding.left - padding.right);
-	if (cell.textDirection === "btLr" || cell.textDirection === "tbRl") context.unsupported.report(UNSUPPORTED_CONSTRUCT.verticalCellText, context.pageIndex, `w:textDirection ${cell.textDirection} paints horizontally`);
+	if (cellTextRotationDegrees(cell.textDirection) !== 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.verticalCellText, context.pageIndex, `w:textDirection ${cell.textDirection} paints horizontally`);
 	composer.push(primitives);
 	primitives.length = 0;
 	paintCellBlocks({

package/dist/display-list/build/textBoxPrimitives.js

@@ -1,11 +1,12 @@
 import { layoutTextBoxContent } from "../../layout-engine/measure/textBoxParagraphLayout.js";
 import { DEFAULT_TEXTBOX_MARGINS } from "../../layout-engine/types.js";
+import { presetDashForOutlineAttr } from "../../types/documentEnumValues.js";
 import { hasHorizontalFlip, hasVerticalFlip, parseRotationDegrees } from "../../utils/rotationBoundingBox.js";
 import { HIT_REGION_KINDS } from "../primitives.js";
 import { parseDisplayColor } from "./colors.js";
 import { paintParagraphFragment } from "./paragraphPrimitives.js";
 import { blockRegion, createPageComposer } from "./regions.js";
-import { resolveBorderStroke } from "./strokes.js";
+import { resolveOutlineStroke } from "./strokes.js";
 import { paintTableBlock } from "./tablePrimitives.js";
 import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
 //#region src/display-list/build/textBoxPrimitives.ts
@@ -65,10 +66,11 @@ const paintUnrotatedTextBoxFragment = ({ composer, fragment, block, measure, con
 		else context.unsupported.report(UNSUPPORTED_CONSTRUCT.unresolvedColor, context.pageIndex, `text box fill ${block.fillColor}`);
 	}
 	let outlineWidthPx = 0;
-	if (block.outlineWidth !== void 0 && block.outlineWidth > 0) {
-		const { stroke, unresolvedColor } = resolveBorderStroke({
+	const outlineDash = presetDashForOutlineAttr(block.outlineStyle) ?? "solid";
+	if (block.outlineWidth !== void 0 && block.outlineWidth > 0 && outlineDash !== "none") {
+		const { stroke, unresolvedColor } = resolveOutlineStroke({
 			width: block.outlineWidth,
-			style: block.outlineStyle ?? "solid",
+			dash: outlineDash,
 			color: block.outlineColor ?? "#000000"
 		});
 		if (unresolvedColor !== void 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.unresolvedColor, context.pageIndex, `text box outline ${unresolvedColor}`);

package/dist/display-list/build/textDecorations.d.ts

@@ -20,10 +20,24 @@ declare const UNDERLINE_OFFSET_RATIO = 0.1;
 /** Underline thickness as a fraction of the em, floored so a hairline stays visible. */
 declare const UNDERLINE_THICKNESS_RATIO: number;
 declare const MIN_DECORATION_THICKNESS_PX = 1;
+/**
+ * What an underline member's thickness is a multiple of the plain one.
+ *
+ * `thick` and the `*Heavy` members differ from their plain counterparts in
+ * weight only, and Word draws that weight as twice the plain rule. The number
+ * lives here rather than at either renderer because both read it: a member's
+ * row states it (`strokes.ts:UNDERLINE_STROKES`), the display list multiplies
+ * the stroke by it and the DOM spells the same row's weight as a
+ * `text-decoration-thickness` length
+ * (`formatToStyle.ts:underlineDecorationCss`). Two copies would let the page
+ * and the editor draw the same member at two weights.
+ */
+declare const PLAIN_UNDERLINE_WEIGHT = 1;
+declare const HEAVY_UNDERLINE_WEIGHT = 2;
 /** Distance above the baseline to the centre of the strikethrough, as a fraction of the em. */
 declare const STRIKETHROUGH_OFFSET_RATIO = 0.28;
 declare const underlineThicknessPx: (fontSizePx: number) => number;
 declare const underlineCenterYPx: (baselineYPx: number, fontSizePx: number) => number;
 declare const strikethroughCenterYPx: (baselineYPx: number, fontSizePx: number) => number;
 //#endregion
-export { MIN_DECORATION_THICKNESS_PX, STRIKETHROUGH_OFFSET_RATIO, UNDERLINE_OFFSET_RATIO, UNDERLINE_THICKNESS_RATIO, strikethroughCenterYPx, underlineCenterYPx, underlineThicknessPx };
+export { HEAVY_UNDERLINE_WEIGHT, MIN_DECORATION_THICKNESS_PX, PLAIN_UNDERLINE_WEIGHT, STRIKETHROUGH_OFFSET_RATIO, UNDERLINE_OFFSET_RATIO, UNDERLINE_THICKNESS_RATIO, strikethroughCenterYPx, underlineCenterYPx, underlineThicknessPx };

package/dist/display-list/build/textDecorations.js

@@ -20,10 +20,24 @@ const UNDERLINE_OFFSET_RATIO = .1;
 /** Underline thickness as a fraction of the em, floored so a hairline stays visible. */
 const UNDERLINE_THICKNESS_RATIO = 1 / 14;
 const MIN_DECORATION_THICKNESS_PX = 1;
+/**
+* What an underline member's thickness is a multiple of the plain one.
+*
+* `thick` and the `*Heavy` members differ from their plain counterparts in
+* weight only, and Word draws that weight as twice the plain rule. The number
+* lives here rather than at either renderer because both read it: a member's
+* row states it (`strokes.ts:UNDERLINE_STROKES`), the display list multiplies
+* the stroke by it and the DOM spells the same row's weight as a
+* `text-decoration-thickness` length
+* (`formatToStyle.ts:underlineDecorationCss`). Two copies would let the page
+* and the editor draw the same member at two weights.
+*/
+const PLAIN_UNDERLINE_WEIGHT = 1;
+const HEAVY_UNDERLINE_WEIGHT = 2;
 /** Distance above the baseline to the centre of the strikethrough, as a fraction of the em. */
 const STRIKETHROUGH_OFFSET_RATIO = .28;
 const underlineThicknessPx = (fontSizePx) => Math.max(1, fontSizePx * UNDERLINE_THICKNESS_RATIO);
 const underlineCenterYPx = (baselineYPx, fontSizePx) => baselineYPx + fontSizePx * UNDERLINE_OFFSET_RATIO;
 const strikethroughCenterYPx = (baselineYPx, fontSizePx) => baselineYPx - fontSizePx * STRIKETHROUGH_OFFSET_RATIO;
 //#endregion
-export { MIN_DECORATION_THICKNESS_PX, STRIKETHROUGH_OFFSET_RATIO, UNDERLINE_OFFSET_RATIO, UNDERLINE_THICKNESS_RATIO, strikethroughCenterYPx, underlineCenterYPx, underlineThicknessPx };
+export { HEAVY_UNDERLINE_WEIGHT, MIN_DECORATION_THICKNESS_PX, PLAIN_UNDERLINE_WEIGHT, STRIKETHROUGH_OFFSET_RATIO, UNDERLINE_OFFSET_RATIO, UNDERLINE_THICKNESS_RATIO, strikethroughCenterYPx, underlineCenterYPx, underlineThicknessPx };

package/dist/display-list/dom/renderDisplayListToDom.js

@@ -1,6 +1,8 @@
+import { writeCommentAnchorIds } from "../../render-dom/commentAnchorAttributes.js";
 import { bytesToDataUrl } from "../../utils/base64.js";
+import { imageLuminanceFilter } from "../../utils/imageLuminance.js";
 import { anchorTargetAttrs } from "../../utils/urlSecurity.js";
-import { STROKE_DASH_FACTORS, walkRegions } from "../primitives.js";
+import { STROKE_DASH_FACTORS, strokeCrossExtentPx, walkRegions } from "../primitives.js";
 import { panic } from "better-result";
 //#region src/display-list/dom/renderDisplayListToDom.ts
 /**
@@ -160,24 +162,6 @@ const VERTICAL_BAR_AXES = {
 	main: "to bottom",
 	cross: "to right"
 };
-/**
-* How far a stroke reaches across its path. A dash pattern stays within the
-* thickness; `double` spans two lines plus the shared gap, and `wavy` the peak
-* to peak amplitude plus the thickness the curve itself is drawn with.
-*/
-const strokeCrossExtentPx = (stroke) => {
-	switch (stroke.pattern) {
-		case "solid":
-		case "dashed":
-		case "dotted": return stroke.thicknessPx;
-		case "double": return stroke.thicknessPx * 3;
-		case "wavy": return stroke.thicknessPx * 3;
-		default: {
-			const unreachable = stroke.pattern;
-			panic(`renderDisplayListToDom: unhandled stroke pattern ${JSON.stringify(unreachable)}`);
-		}
-	}
-};
 const repeatingBars = (color, axis, barPx, gapPx) => `repeating-linear-gradient(${axis}, ${color} 0px, ${color} ${barPx}px, transparent ${barPx}px, transparent ${barPx + gapPx}px)`;
 const strokeBackground = (stroke, axes) => {
 	const color = cssColor(stroke.color);
@@ -310,6 +294,7 @@ const paintGlyphRun = (run, context) => {
 	span.style.fontStyle = face.italic ? "italic" : "normal";
 	span.style.color = cssColor(run.color);
 	span.style.direction = run.direction;
+	if (run.unicodeBidi !== void 0) span.style.unicodeBidi = run.unicodeBidi;
 	if (run.stroke !== void 0) span.style.webkitTextStroke = `${px(run.stroke.thicknessPx)} ${cssColor(run.stroke.color)}`;
 	span.style.fontKerning = run.kerning ? "normal" : "none";
 	if (run.smallCaps) span.style.fontVariant = "small-caps";
@@ -387,13 +372,18 @@ const paintRect = ({ rect, fill, stroke }, context) => {
 		default: panic(`renderDisplayListToDom: unhandled rect stroke painter ${JSON.stringify(painter)}`);
 	}
 };
-const paintImage = ({ image, rect, crop, opacity }, context) => {
+const paintImage = ({ image, rect, crop, opacity, brightness, contrast }, context) => {
 	const source = resolveImage(image, context.images);
 	const clip = createAbsoluteDiv(context, rect);
 	clip.style.overflow = "hidden";
 	const element = context.doc.createElement("img");
 	element.style.position = "absolute";
 	element.style.opacity = String(opacity);
+	const filter = imageLuminanceFilter({
+		...brightness === void 0 ? {} : { brightness },
+		...contrast === void 0 ? {} : { contrast }
+	});
+	if (filter !== void 0) element.style.filter = filter;
 	element.style.left = "0px";
 	element.style.top = "0px";
 	element.style.width = px(rect.widthPx);
@@ -549,7 +539,7 @@ const applyRegionModel = (element, region) => {
 		element.dataset["pmEnd"] = String(model.pmRange.end);
 	}
 	if (model.blockId !== void 0) element.dataset["blockId"] = model.blockId;
-	if (model.commentIds !== void 0 && model.commentIds.length > 0) element.dataset["commentId"] = String(model.commentIds[0]);
+	if (model.commentIds !== void 0) writeCommentAnchorIds(element, model.commentIds);
 	if (model.rowIndex !== void 0) element.dataset["rowIndex"] = String(model.rowIndex);
 	if (model.columnIndex !== void 0) element.dataset["columnIndex"] = String(model.columnIndex);
 	const story = model.story ?? model.pmRange?.story;

package/dist/display-list/primitives.d.ts

@@ -1,4 +1,4 @@
-import { DisplayColor, DisplayGlyphRun, DisplayHitRegion, DisplayPrimitive } from "./types.js";
+import { DisplayColor, DisplayGlyphRun, DisplayHitRegion, DisplayPrimitive, DisplayStroke } from "./types.js";
 import { hasCursiveLetter, joinsAcrossBoundary } from "../utils/cursiveJoining.js";
 import { hasComplexScript, isComplexScriptCodePoint } from "../utils/scriptSegments.js";
 //#region src/display-list/primitives.d.ts
@@ -56,6 +56,17 @@ declare const DOUBLE_STROKE_GAP_FACTOR = 1;
  */
 declare const WAVY_STROKE_PERIOD_FACTOR = 6;
 declare const WAVY_STROKE_AMPLITUDE_FACTOR = 2;
+/**
+ * How far a stroke reaches across its path: the band it occupies, centred on
+ * the path. A dash pattern stays within the thickness; `double` spans two rules
+ * plus the gap between them, and `wavy` the peak-to-peak amplitude plus the
+ * thickness the curve itself is drawn with.
+ *
+ * The DOM backend sizes an element with it and the producer stacks `wavyDouble`
+ * with it, so two strokes meant to clear each other are pushed apart by exactly
+ * the band the backend then paints.
+ */
+declare const strokeCrossExtentPx: (stroke: DisplayStroke) => number;
 declare const BLACK: DisplayColor;
 declare const WHITE: DisplayColor;
 /**
@@ -93,4 +104,4 @@ type RegionVisitor = {
 };
 declare const walkRegions: (primitives: readonly DisplayPrimitive[], regions: readonly DisplayHitRegion[], visitor: RegionVisitor) => void;
 //#endregion
-export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, RegionVisitor, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, walkRegions };
+export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, RegionVisitor, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, strokeCrossExtentPx, walkRegions };

package/dist/display-list/primitives.js

@@ -1,7 +1,19 @@
 import { hasCursiveLetter, joinsAcrossBoundary } from "../utils/cursiveJoining.js";
 import { hasComplexScript, isComplexScriptCodePoint } from "../utils/scriptSegments.js";
+import { panic } from "better-result";
 //#region src/display-list/primitives.ts
 /**
+* Runtime companions of the paint IR.
+*
+* `types.ts` is pure data by rule, so what a backend needs at runtime lives
+* here instead: the discriminator list a coverage test enumerates, the two
+* colours every producer resolves a theme variable to, the stroke geometry
+* both backends draw from, and the rule that turns a run's advances into a
+* position per code point. A rule two backends must agree on belongs in one
+* module, not in one copy each. Nothing here carries a layout fact, which is
+* why a backend may take a runtime edge to it and not to `types.ts`.
+*/
+/**
 * Left edge of every code point of a run, as an offset from the run's `xPx`.
 *
 * One implementation for both backends. The ordering rule is prose in
@@ -71,6 +83,29 @@ const DOUBLE_STROKE_GAP_FACTOR = 1;
 */
 const WAVY_STROKE_PERIOD_FACTOR = 6;
 const WAVY_STROKE_AMPLITUDE_FACTOR = 2;
+/**
+* How far a stroke reaches across its path: the band it occupies, centred on
+* the path. A dash pattern stays within the thickness; `double` spans two rules
+* plus the gap between them, and `wavy` the peak-to-peak amplitude plus the
+* thickness the curve itself is drawn with.
+*
+* The DOM backend sizes an element with it and the producer stacks `wavyDouble`
+* with it, so two strokes meant to clear each other are pushed apart by exactly
+* the band the backend then paints.
+*/
+const strokeCrossExtentPx = (stroke) => {
+	switch (stroke.pattern) {
+		case "solid":
+		case "dashed":
+		case "dotted": return stroke.thicknessPx;
+		case "double": return stroke.thicknessPx * 3;
+		case "wavy": return stroke.thicknessPx * 3;
+		default: {
+			const unreachable = stroke.pattern;
+			panic(`strokeCrossExtentPx: unhandled stroke pattern ${JSON.stringify(unreachable)}`);
+		}
+	}
+};
 const BLACK = {
 	r: 0,
 	g: 0,
@@ -124,4 +159,4 @@ const walkRegions = (primitives, regions, visitor) => {
 	visit(0, primitives.length, regions);
 };
 //#endregion
-export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, walkRegions };
+export { BLACK, DISPLAY_PRIMITIVE_KINDS, DOUBLE_STROKE_GAP_FACTOR, HIT_REGION_KINDS, STROKE_DASH_FACTORS, WAVY_STROKE_AMPLITUDE_FACTOR, WAVY_STROKE_PERIOD_FACTOR, WHITE, glyphCellOffsetsPx, hasComplexScript, hasCursiveLetter, isComplexScriptCodePoint, joinsAcrossBoundary, strokeCrossExtentPx, walkRegions };

package/dist/display-list/types.d.ts

@@ -215,6 +215,19 @@ type DisplayGlyphRun = {
   readonly text: string;
   readonly advancesPx: readonly number[];
   readonly direction: "ltr" | "rtl";
+  /**
+   * How a backend that resolves bidirectional text itself must treat the run.
+   *
+   * `direction` alone is the base direction, and a backend that hands the text
+   * to such a resolver gets the ordinary algorithm: a Latin word inside an
+   * `rtl` run reads forwards. That is an embedding, and it is wrong for the
+   * run the author wrapped in an override (`w:bdo`), where every character is
+   * laid out in `direction` whatever its own script. Absent is the ordinary
+   * run, whose base direction the paragraph or the run itself decided; a
+   * backend that positions every glyph from `advancesPx` reorders nothing and
+   * ignores this.
+   */
+  readonly unicodeBidi?: "embed" | "bidi-override";
   /**
    * Whether the glyphs kern.
    *
@@ -299,6 +312,10 @@ type DisplayImagePrimitive = {
     readonly b: number;
   };
   readonly opacity: number;
+  /** DrawingML picture brightness as a signed percentage. */
+  readonly brightness?: number;
+  /** DrawingML picture contrast as a signed percentage. */
+  readonly contrast?: number;
 };
 /** Clips its children to `rect`. Used for cropped images and cell overflow. */
 type DisplayClipGroup = {

package/dist/document-operations.js

@@ -1,4 +1,5 @@
 import { applyFolioAIEditOperations, previewFolioAIEditOperations } from "./ai-edits/apply.js";
+import { isNumberingReference } from "./docx/numberingReference.js";
 import { LINE_SPACING_RULE_VALUES, PARAGRAPH_ALIGNMENT_VALUES } from "./types/documentEnumValues.js";
 import { TaggedError } from "better-result";
 import { sanitizeXmlCharacters } from "@stll/docx-core";
@@ -299,7 +300,7 @@ const readClearableNumbering = ({ value, key, path }) => {
 	if (!isPlainObject(candidate)) return invalidBatch(numberingPath, "expected an object or null when provided");
 	assertAllowedKeys(candidate, numberingPath, ["numId", "level"]);
 	const numId = readNonNegativeInteger(candidate, "numId", numberingPath);
-	if (numId === 0) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
+	if (!isNumberingReference(numId)) return invalidBatch(`${numberingPath}.numId`, "expected a positive integer");
 	return {
 		numId,
 		level: readNonNegativeInteger(candidate, "level", numberingPath)

package/dist/docx/attributeRemainder.d.ts

@@ -0,0 +1,76 @@
+import { ModelledAttributes } from "./propertyElementAttributes.js";
+import { XmlElement } from "./xmlParser.js";
+import { PreservedAttribute } from "@stll/docx-core/model";
+//#region src/docx/attributeRemainder.d.ts
+declare const InvalidPreservedAttributeError_base: import("better-result").TaggedErrorClass<"InvalidPreservedAttributeError">;
+declare class InvalidPreservedAttributeError extends InvalidPreservedAttributeError_base<{
+  message: string;
+  name: string;
+}> {}
+/** Whether an attribute remainder can be emitted under a bound canonical name. */
+declare const isSerializablePreservedAttribute: ({ namespace, name }: Pick<PreservedAttribute, "namespace" | "name">) => boolean;
+/**
+ * The modelled set of an element whose serializer writes no attribute at all.
+ *
+ * `w:r`, `w:tr` and `w:sectPr` are rebuilt as bare start tags, so everything
+ * their source wrote is the remainder. Named rather than spelled `new Set()`
+ * at each call site, so the claim is visible and one place has to change when
+ * one of them gains a modelled attribute.
+ */
+declare const NO_MODELLED_ATTRIBUTES: ReadonlySet<string>;
+/**
+ * What a part's root element states rather than carries, so the remainder skips it.
+ *
+ * `mc:Ignorable` is a projection of the root's own `xmlns:*` bindings — it
+ * lists which of them a consumer may skip — and `serializePartElement` derives
+ * both from the prefixes the rebuilt body actually uses. Replaying the
+ * source's would name prefixes the rebuilt root does not bind, which no
+ * consumer accepts, and the writer appends its own, so the part would carry
+ * the attribute twice. This is the same rule namespace declarations already
+ * follow, one attribute further on.
+ */
+declare const DERIVED_PART_ROOT_ATTRIBUTES: ReadonlySet<string>;
+type AttributeRemainderOptions = {
+  /** The element, as the source wrote it. */
+  element: XmlElement;
+  /**
+   * Local names this element's own parser reads.
+   *
+   * Local names rather than qualified ones, because folio's attribute readers
+   * fall back to a local-name match across prefixes: an attribute the parser
+   * would read under any binding has to be out of the remainder, or the save
+   * writes the value twice under two spellings.
+   */
+  modelled: ReadonlySet<string>;
+};
+/**
+ * Every attribute on the element the model has no field for.
+ *
+ * @returns the remainder, or `undefined` when the parser read them all — an
+ *   empty list is never written, so a fully modelled element stays identical
+ *   in the model.
+ */
+declare const attributeRemainder: ({ element, modelled }: AttributeRemainderOptions) => PreservedAttribute[] | undefined;
+/**
+ * The remainder of an attribute bag, with the modelled set derived from the
+ * record's own fields.
+ *
+ * `w:ind`, `w:spacing`, `w:framePr`, `w:tab`, a border side and `w:shd` are
+ * bags rather than containers: the child dispatcher decides each of them
+ * whole, so an attribute the record has no field for is kept only while the
+ * reader takes nothing from the element at all. Passing the record's table
+ * from `propertyElementAttributes.ts` rather than a set spelled at the call
+ * site is what keeps the predicate derived from the model: a field added
+ * without an attribute to name does not compile.
+ */
+declare const readAttributeBag: (element: XmlElement, modelled: ModelledAttributes<string>) => PreservedAttribute[] | undefined;
+/**
+ * The element's attributes, modelled first and the remainder after them.
+ *
+ * @param modelled the fragments the serializer is about to emit, already
+ *   spelled — they win a collision, because the model is the editable copy
+ * @returns the fragments to write, so an element with neither writes nothing
+ */
+declare const serializePreservedAttributes: (modelled: readonly string[], preserved: readonly PreservedAttribute[] | undefined) => string[];
+//#endregion
+export { DERIVED_PART_ROOT_ATTRIBUTES, InvalidPreservedAttributeError, NO_MODELLED_ATTRIBUTES, attributeRemainder, isSerializablePreservedAttribute, readAttributeBag, serializePreservedAttributes };