@stll/folio-core 0.42.0 → 0.44.0

package/dist/docx/styleParser.js

@@ -1,10 +1,13 @@
-import { isValidHexColor } from "../utils/colorResolver.js";
 import { parseHorizontalScalePercent } from "../utils/horizontalScale.js";
 import { mergeParagraphFormatting } from "../utils/paragraphFormattingMerge.js";
 import { mergeStyleTextFormatting } from "../utils/textFormattingMerge.js";
-import { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, ShadingPatternSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { parseBorderSpec } from "./borderParser.js";
+import { resolveDefaultParagraphStyle } from "./defaultParagraphStyle.js";
+import { ConditionalStyleTypeSchema, EmphasisMarkSchema, FontHintSchema, FontThemeSchema, HighlightColorSchema, LineSpacingRuleSchema, ParagraphAlignmentSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum } from "./parserEnums.js";
+import { parseShading } from "./shadingParser.js";
+import { parseTableLook } from "./tableParser.js";
 import { resolveThemeFontRef } from "./themeParser.js";
-import { findChild, findChildren, getAttribute, getLocalName, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXmlDocument } from "./xmlParser.js";
+import { findChild, findChildren, getAttribute, getLocalName, parseBooleanElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXmlDocument } from "./xmlParser.js";
 //#region src/docx/styleParser.ts
 const findLastRunToggle = (rPr, localName) => findChildren(rPr, "w", localName).at(-1) ?? null;
 /**
@@ -55,7 +58,7 @@ function parseRunProperties(rPr, theme) {
 	}
 	const shd = findChild(rPr, "w", "shd");
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult) formatting.shading = shadingResult;
 	}
 	const sz = findChild(rPr, "w", "sz");
@@ -189,50 +192,6 @@ function parseColorValue(rgb, themeColor, themeTint, themeShade) {
 	return color;
 }
 /**
-* Parse shading properties (w:shd)
-*/
-function parseShadingProperties(shd) {
-	if (!shd) return;
-	const props = {};
-	const color = getAttribute(shd, "w", "color");
-	if (color && color !== "auto" && isValidHexColor(color)) props.color = { rgb: color };
-	const fill = getAttribute(shd, "w", "fill");
-	if (fill && fill !== "auto" && isValidHexColor(fill)) props.fill = { rgb: fill };
-	const validatedThemeFill = narrowEnum(getAttribute(shd, "w", "themeFill"), ThemeColorSlotSchema);
-	if (validatedThemeFill) {
-		if (!props.fill) props.fill = {};
-		props.fill.themeColor = validatedThemeFill;
-	}
-	const themeFillTint = getAttribute(shd, "w", "themeFillTint");
-	if (themeFillTint && props.fill) props.fill.themeTint = themeFillTint;
-	const themeFillShade = getAttribute(shd, "w", "themeFillShade");
-	if (themeFillShade && props.fill) props.fill.themeShade = themeFillShade;
-	const pattern = narrowEnum(getAttribute(shd, "w", "val"), ShadingPatternSchema);
-	if (pattern) props.pattern = pattern;
-	return Object.keys(props).length > 0 ? props : void 0;
-}
-/**
-* Parse border specification
-*/
-function parseBorderSpec(border) {
-	if (!border) return;
-	const rawStyle = getAttribute(border, "w", "val");
-	if (!rawStyle) return;
-	const spec = { style: narrowEnum(rawStyle, BorderStyleSchema) ?? rawStyle };
-	const colorVal = getAttribute(border, "w", "color");
-	const themeColor = getAttribute(border, "w", "themeColor");
-	if (colorVal || themeColor) spec.color = parseColorValue(colorVal, themeColor, getAttribute(border, "w", "themeTint"), getAttribute(border, "w", "themeShade"));
-	const sz = parseNumericAttribute(border, "w", "sz");
-	if (sz !== void 0) spec.size = sz;
-	const space = parseNumericAttribute(border, "w", "space");
-	if (space !== void 0) spec.space = space;
-	const shadowAttr = getAttribute(border, "w", "shadow");
-	if (shadowAttr) spec.shadow = parseOnOffValue(shadowAttr) ?? false;
-	const frame = getAttribute(border, "w", "frame");
-	if (frame) spec.frame = parseOnOffValue(frame) ?? false;
-	return spec;
-}
-/**
 * Parse tab stops (w:tabs)
 */
 function parseTabStops(tabs) {
@@ -280,10 +239,10 @@ function parseParagraphProperties(pPr, theme) {
 		if (line !== void 0) formatting.lineSpacing = line;
 		const lineRule = narrowEnum(getAttribute(spacing, "w", "lineRule"), LineSpacingRuleSchema);
 		if (lineRule) formatting.lineSpacingRule = lineRule;
-		const beforeAuto = getAttribute(spacing, "w", "beforeAutospacing");
-		if (beforeAuto) formatting.beforeAutospacing = parseOnOffValue(beforeAuto) ?? false;
-		const afterAuto = getAttribute(spacing, "w", "afterAutospacing");
-		if (afterAuto) formatting.afterAutospacing = parseOnOffValue(afterAuto) ?? false;
+		const beforeAutospacing = parseOnOffAttribute(spacing, "w", "beforeAutospacing");
+		if (beforeAutospacing !== void 0) formatting.beforeAutospacing = beforeAutospacing;
+		const afterAutospacing = parseOnOffAttribute(spacing, "w", "afterAutospacing");
+		if (afterAutospacing !== void 0) formatting.afterAutospacing = afterAutospacing;
 	}
 	const ind = findChild(pPr, "w", "ind");
 	if (ind) {
@@ -318,7 +277,7 @@ function parseParagraphProperties(pPr, theme) {
 	}
 	const shd = findChild(pPr, "w", "shd");
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult) formatting.shading = shadingResult;
 	}
 	const tabs = findChild(pPr, "w", "tabs");
@@ -437,38 +396,6 @@ function parseCellMargins(tblCellMar) {
 	return Object.keys(margins).length > 0 ? margins : void 0;
 }
 /**
-* Parse table look flags
-*/
-function parseTableLook(tblLook) {
-	if (!tblLook) return;
-	const look = {};
-	const val = getAttribute(tblLook, "w", "val");
-	if (val) {
-		const num = Number.parseInt(val, 16);
-		if (!Number.isNaN(num)) {
-			look.firstRow = (num & 32) !== 0;
-			look.lastRow = (num & 64) !== 0;
-			look.firstColumn = (num & 128) !== 0;
-			look.lastColumn = (num & 256) !== 0;
-			look.noHBand = (num & 512) !== 0;
-			look.noVBand = (num & 1024) !== 0;
-		}
-	}
-	const firstColumn = getAttribute(tblLook, "w", "firstColumn");
-	if (firstColumn) look.firstColumn = parseOnOffValue(firstColumn) ?? false;
-	const firstRow = getAttribute(tblLook, "w", "firstRow");
-	if (firstRow) look.firstRow = parseOnOffValue(firstRow) ?? false;
-	const lastColumn = getAttribute(tblLook, "w", "lastColumn");
-	if (lastColumn) look.lastColumn = parseOnOffValue(lastColumn) ?? false;
-	const lastRow = getAttribute(tblLook, "w", "lastRow");
-	if (lastRow) look.lastRow = parseOnOffValue(lastRow) ?? false;
-	const noHBand = getAttribute(tblLook, "w", "noHBand");
-	if (noHBand) look.noHBand = parseOnOffValue(noHBand) ?? false;
-	const noVBand = getAttribute(tblLook, "w", "noVBand");
-	if (noVBand) look.noVBand = parseOnOffValue(noVBand) ?? false;
-	return Object.keys(look).length > 0 ? look : void 0;
-}
-/**
 * Parse table formatting properties (w:tblPr)
 */
 function parseTableProperties(tblPr, _theme) {
@@ -521,7 +448,7 @@ function parseTableProperties(tblPr, _theme) {
 	}
 	const shd = findChild(tblPr, "w", "shd");
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult) formatting.shading = shadingResult;
 	}
 	const bidiVisual = findChild(tblPr, "w", "bidiVisual");
@@ -577,7 +504,7 @@ function parseTableCellProperties(tcPr, _theme) {
 	}
 	const shd = findChild(tcPr, "w", "shd");
 	if (shd) {
-		const shadingResult = parseShadingProperties(shd);
+		const shadingResult = parseShading(shd);
 		if (shadingResult) formatting.shading = shadingResult;
 	}
 	const vAlign = findChild(tcPr, "w", "vAlign");
@@ -916,8 +843,7 @@ function getResolvedStyle(styleId, styleMap) {
 * Get the default paragraph style
 */
 function getDefaultParagraphStyle(styleMap) {
-	for (const style of styleMap.values()) if (style.type === "paragraph" && style.default) return style;
-	return styleMap.get("Normal");
+	return resolveDefaultParagraphStyle(styleMap.values());
 }
 /**
 * Get the default character style

package/dist/docx/styleReferenceResolution.d.ts

@@ -0,0 +1,36 @@
+//#region src/docx/styleReferenceResolution.d.ts
+/**
+ * Every style a package points at must be a style that package defines.
+ *
+ * A `w:pStyle`, `w:rStyle` or `w:tblStyle` naming an id `styles.xml` never
+ * declares is a dangling reference. Word tolerates one by falling back to the
+ * default style, which is exactly why it goes unnoticed: the document looks
+ * almost right, the paragraph silently loses its formatting, and a consumer
+ * that classifies by style — folio's own outline, TOC and AI snapshot included
+ * — sees nothing there. `w:basedOn`, `w:next` and `w:link` inside `styles.xml`
+ * dangle the same way.
+ *
+ * This is the "dangling by construction" bug class: a writer that hardcodes an
+ * English built-in id it does not also define produces it for *every* document
+ * it writes, not for some unlucky input. {@link danglingStyleReferences} is the
+ * shared check, so an authoring path can be held to it by a test rather than by
+ * the reviewer noticing.
+ */
+/** One reference that resolves to nothing, and the part it was written into. */
+type DanglingStyleReference = {
+  /** The `w:val` that names no defined style. */
+  styleId: string;
+  /** The package part the reference sits in, e.g. `word/document.xml`. */
+  part: string;
+};
+/**
+ * Collect the style references in `parts` that `stylesXml` does not define.
+ *
+ * `parts` maps a part name to its XML; pass every part that can carry a style
+ * reference (`word/document.xml`, the header/footer parts, `word/footnotes.xml`,
+ * `word/endnotes.xml`, `word/comments.xml`, and `word/styles.xml` itself for
+ * the `basedOn`/`next`/`link` graph).
+ */
+declare const danglingStyleReferences: (stylesXml: string | undefined, parts: ReadonlyMap<string, string>) => DanglingStyleReference[];
+//#endregion
+export { DanglingStyleReference, danglingStyleReferences };

package/dist/docx/styleReferenceResolution.js

@@ -0,0 +1,51 @@
+//#region src/docx/styleReferenceResolution.ts
+/**
+* Every style a package points at must be a style that package defines.
+*
+* A `w:pStyle`, `w:rStyle` or `w:tblStyle` naming an id `styles.xml` never
+* declares is a dangling reference. Word tolerates one by falling back to the
+* default style, which is exactly why it goes unnoticed: the document looks
+* almost right, the paragraph silently loses its formatting, and a consumer
+* that classifies by style — folio's own outline, TOC and AI snapshot included
+* — sees nothing there. `w:basedOn`, `w:next` and `w:link` inside `styles.xml`
+* dangle the same way.
+*
+* This is the "dangling by construction" bug class: a writer that hardcodes an
+* English built-in id it does not also define produces it for *every* document
+* it writes, not for some unlucky input. {@link danglingStyleReferences} is the
+* shared check, so an authoring path can be held to it by a test rather than by
+* the reviewer noticing.
+*/
+const STYLE_REFERENCE = /<w:(?:pStyle|rStyle|tblStyle)\b[^>]*\bw:val="(?<id>[^"]*)"/gu;
+const STYLE_LINK = /<w:(?:basedOn|next|link)\b[^>]*\bw:val="(?<id>[^"]*)"/gu;
+const STYLE_DEFINITION = /<w:style\b[^>]*\bw:styleId="(?<id>[^"]*)"/gu;
+const idsIn = (xml, pattern) => {
+	const ids = [];
+	for (const match of xml.matchAll(pattern)) {
+		const id = match.groups?.["id"];
+		if (id !== void 0 && id.length > 0) ids.push(id);
+	}
+	return ids;
+};
+/**
+* Collect the style references in `parts` that `stylesXml` does not define.
+*
+* `parts` maps a part name to its XML; pass every part that can carry a style
+* reference (`word/document.xml`, the header/footer parts, `word/footnotes.xml`,
+* `word/endnotes.xml`, `word/comments.xml`, and `word/styles.xml` itself for
+* the `basedOn`/`next`/`link` graph).
+*/
+const danglingStyleReferences = (stylesXml, parts) => {
+	const defined = new Set(idsIn(stylesXml ?? "", STYLE_DEFINITION));
+	const dangling = [];
+	for (const [part, xml] of parts) {
+		const references = part === "word/styles.xml" ? idsIn(xml, STYLE_LINK) : [...idsIn(xml, STYLE_REFERENCE), ...idsIn(xml, STYLE_LINK)];
+		for (const styleId of references) if (!defined.has(styleId)) dangling.push({
+			styleId,
+			part
+		});
+	}
+	return dangling;
+};
+//#endregion
+export { danglingStyleReferences };

package/dist/docx/tableLook.d.ts

@@ -0,0 +1,57 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/tableLook.d.ts
+/**
+ * Every flag, in the order `CT_TblLook` declares them.
+ *
+ * The reader and the serializer both walk this, so the attributes go back out
+ * in the order they came in.
+ */
+declare const TABLE_LOOK_FLAGS: readonly ["firstRow", "lastRow", "firstColumn", "lastColumn", "noHBand", "noVBand"];
+type TableLookFlag = (typeof TABLE_LOOK_FLAGS)[number];
+/** The bit of `w:val` each flag restates (ECMA-376 §17.4.57). */
+declare const TABLE_LOOK_BITS: {
+  readonly firstRow: 32;
+  readonly lastRow: 64;
+  readonly firstColumn: 128;
+  readonly lastColumn: 256;
+  readonly noHBand: 512;
+  readonly noVBand: 1024;
+};
+/**
+ * Every flag, decided.
+ *
+ * Binding the record to `TableLook`'s own keys is the totality gate: a flag
+ * added to the model that {@link TABLE_LOOK_FLAGS} does not list makes this
+ * alias fail its constraint, so the module stops compiling rather than letting
+ * a flag ship with no bit, no read order and no resolution.
+ */
+type ResolvedTableLook = document_d_exports.ExhaustiveFields<Record<TableLookFlag, boolean>, Exclude<keyof document_d_exports.TableLook, "val">>;
+/**
+ * Resolve a `w:tblLook` to the six answers a consumer can act on.
+ *
+ * Precedence is the flag the author stated, then the matching bit of `w:val`,
+ * then off. The attribute form wins because it is the later spelling of the
+ * same fact: a producer that writes both and disagrees means the flags, and a
+ * producer that writes only `w:val` still gets its banding and its header row.
+ */
+declare const resolveTableLook: (look: document_d_exports.TableLook | undefined) => ResolvedTableLook;
+type SetTableLookFlagsOptions = {
+  look: document_d_exports.TableLook | undefined;
+  /**
+   * The flags to state. A flag left out keeps whatever the author said, which
+   * may be nothing; this is a patch over the authored value, not a decision
+   * per flag, so `Partial` is the honest type.
+   */
+  flags: Readonly<Partial<ResolvedTableLook>>;
+};
+/**
+ * State flags on a `w:tblLook`, leaving `w:val` as the author wrote it.
+ *
+ * The attribute form is what {@link resolveTableLook} reads first, so stating a
+ * flag is enough to change the table. Re-encoding `w:val` instead would rewrite
+ * the bits outside the six modelled here — the bitmask is 16 bits wide and the
+ * format reserves the rest — and folio has nothing to put there.
+ */
+declare const setTableLookFlags: ({ look, flags }: SetTableLookFlagsOptions) => document_d_exports.TableLook;
+//#endregion
+export { ResolvedTableLook, TABLE_LOOK_BITS, TABLE_LOOK_FLAGS, TableLookFlag, resolveTableLook, setTableLookFlags };

package/dist/docx/tableLook.js

@@ -0,0 +1,63 @@
+//#region src/docx/tableLook.ts
+/**
+* Every flag, in the order `CT_TblLook` declares them.
+*
+* The reader and the serializer both walk this, so the attributes go back out
+* in the order they came in.
+*/
+const TABLE_LOOK_FLAGS = [
+	"firstRow",
+	"lastRow",
+	"firstColumn",
+	"lastColumn",
+	"noHBand",
+	"noVBand"
+];
+/** The bit of `w:val` each flag restates (ECMA-376 §17.4.57). */
+const TABLE_LOOK_BITS = {
+	firstRow: 32,
+	lastRow: 64,
+	firstColumn: 128,
+	lastColumn: 256,
+	noHBand: 512,
+	noVBand: 1024
+};
+const tableLookMask = (val) => {
+	if (val === void 0) return 0;
+	const bits = Number.parseInt(val, 16);
+	return Number.isNaN(bits) ? 0 : bits;
+};
+/**
+* Resolve a `w:tblLook` to the six answers a consumer can act on.
+*
+* Precedence is the flag the author stated, then the matching bit of `w:val`,
+* then off. The attribute form wins because it is the later spelling of the
+* same fact: a producer that writes both and disagrees means the flags, and a
+* producer that writes only `w:val` still gets its banding and its header row.
+*/
+const resolveTableLook = (look) => {
+	const mask = tableLookMask(look?.val);
+	const resolve = (flag) => look?.[flag] ?? (mask & TABLE_LOOK_BITS[flag]) !== 0;
+	return {
+		firstRow: resolve("firstRow"),
+		lastRow: resolve("lastRow"),
+		firstColumn: resolve("firstColumn"),
+		lastColumn: resolve("lastColumn"),
+		noHBand: resolve("noHBand"),
+		noVBand: resolve("noVBand")
+	};
+};
+/**
+* State flags on a `w:tblLook`, leaving `w:val` as the author wrote it.
+*
+* The attribute form is what {@link resolveTableLook} reads first, so stating a
+* flag is enough to change the table. Re-encoding `w:val` instead would rewrite
+* the bits outside the six modelled here — the bitmask is 16 bits wide and the
+* format reserves the rest — and folio has nothing to put there.
+*/
+const setTableLookFlags = ({ look, flags }) => ({
+	...look,
+	...flags
+});
+//#endregion
+export { TABLE_LOOK_BITS, TABLE_LOOK_FLAGS, resolveTableLook, setTableLookFlags };

package/dist/docx/tableParser.d.ts

@@ -23,7 +23,6 @@ declare function parseTableMeasurement(element: XmlElement | null): document_d_e
  * @param element - Border element (w:top, w:bottom, etc.)
  * @returns Parsed border or undefined
  */
-declare function parseBorderSpec(element: XmlElement | null): document_d_exports.BorderSpec | undefined;
 /**
  * Parse table borders (w:tblBorders or w:tcBorders)
  *
@@ -39,14 +38,13 @@ declare function parseTableBorders(bordersElement: XmlElement | null): document_
  */
 declare function parseCellMargins(marginsElement: XmlElement | null): document_d_exports.CellMargins | undefined;
 /**
- * Parse shading properties (w:shd)
+ * Read a `w:tblLook` (the only reader; `styleParser` calls this one).
  *
- * @param shdElement - The w:shd element
- * @returns Parsed shading or undefined
- */
-declare function parseShading(shdElement: XmlElement | null): document_d_exports.ShadingProperties | undefined;
-/**
- * Parse table look flags (w:tblLook)
+ * What the author wrote, and nothing more: `w:val` verbatim and each flag as
+ * stated, absent, `false` or `true`. Folding `w:val`'s bits into the flags here
+ * would forget which of the two the document said, and writing the result back
+ * would invent attributes the author never had. `resolveTableLook` owns the
+ * other direction.
  *
  * @param lookElement - The w:tblLook element
  * @returns Parsed table look or undefined
@@ -199,4 +197,4 @@ declare function getHeaderRows(table: document_d_exports.Table): document_d_expo
  */
 declare function isFloatingTable(table: document_d_exports.Table): boolean;
 //#endregion
-export { MAX_TABLE_COLUMNS, getHeaderRows, getTableColumnCount, getTableRowCount, getTableText, hasHeaderRow, isCellHorizontallyMerged, isCellMergeContinuation, isCellMergeStart, isFloatingTable, parseBorderSpec, parseCellMargins, parseConditionalFormatStyle, parseFloatingTableProperties, parseShading, parseTable, parseTableBorders, parseTableCell, parseTableCellProperties, parseTableGrid, parseTableLook, parseTableMeasurement, parseTableProperties, parseTableRow, parseTableRowProperties };
+export { MAX_TABLE_COLUMNS, getHeaderRows, getTableColumnCount, getTableRowCount, getTableText, hasHeaderRow, isCellHorizontallyMerged, isCellMergeContinuation, isCellMergeStart, isFloatingTable, parseCellMargins, parseConditionalFormatStyle, parseFloatingTableProperties, parseTable, parseTableBorders, parseTableCell, parseTableCellProperties, parseTableGrid, parseTableLook, parseTableMeasurement, parseTableProperties, parseTableRow, parseTableRowProperties };