@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/drawingUtils.js

@@ -0,0 +1,305 @@
+import { findByFullName, getAttribute, getChildElements, getTextContent, parseNumericAttribute } from "./xmlParser.js";
+import { ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, ShapeOutlineStyleSchema, narrowEnum } from "./parserEnums.js";
+//#region src/docx/drawingUtils.ts
+/**
+* Map OOXML scheme names to standard theme color slots.
+* Used when parsing a:schemeClr elements in DrawingML.
+*/
+const SCHEME_TO_THEME_COLOR = {
+	accent1: "accent1",
+	accent2: "accent2",
+	accent3: "accent3",
+	accent4: "accent4",
+	accent5: "accent5",
+	accent6: "accent6",
+	dk1: "dk1",
+	lt1: "lt1",
+	dk2: "dk2",
+	lt2: "lt2",
+	tx1: "text1",
+	tx2: "text2",
+	bg1: "background1",
+	bg2: "background2",
+	hlink: "hlink",
+	folHlink: "folHlink"
+};
+/**
+* sRGB hex per OOXML (ST_HexColorRGB): exactly six hex digits, case-insensitive.
+* Anything else is rejected so untrusted DOCX input cannot smuggle markup through
+* downstream renderers that interpolate the value into HTML/SVG.
+*/
+const HEX_COLOR_RE = /^[0-9A-Fa-f]{6}$/u;
+function isHexColor(val) {
+	return typeof val === "string" && HEX_COLOR_RE.test(val);
+}
+/**
+* Common preset color names to RGB hex values.
+*/
+const PRESET_COLORS = {
+	black: "000000",
+	white: "FFFFFF",
+	red: "FF0000",
+	green: "00FF00",
+	blue: "0000FF",
+	yellow: "FFFF00",
+	cyan: "00FFFF",
+	magenta: "FF00FF"
+};
+/**
+* Apply color modifiers (shade, tint) from child elements of a color element.
+* Converts DrawingML 100000ths-scale values to hex (0-FF) for OOXML compatibility.
+*/
+function applyColorModifiers(color, element) {
+	const children = getChildElements(element);
+	const shade = children.find((el) => el.name === "a:shade");
+	if (shade) {
+		const val = getAttribute(shade, null, "val");
+		if (val) color.themeShade = Math.round(Number.parseInt(val, 10) / 1e5 * 255).toString(16).padStart(2, "0").toUpperCase();
+	}
+	const tint = children.find((el) => el.name === "a:tint");
+	if (tint) {
+		const val = getAttribute(tint, null, "val");
+		if (val) color.themeTint = Math.round(Number.parseInt(val, 10) / 1e5 * 255).toString(16).padStart(2, "0").toUpperCase();
+	}
+	return color;
+}
+/**
+* Parse a color value from a DrawingML element.
+* Handles: a:srgbClr, a:schemeClr, a:sysClr, a:prstClr
+* Applies shade/tint modifiers when present.
+*/
+function parseColorElement(element) {
+	if (!element) return;
+	const children = getChildElements(element);
+	const srgbClr = children.find((el) => el.name === "a:srgbClr");
+	if (srgbClr) {
+		const val = getAttribute(srgbClr, null, "val");
+		if (isHexColor(val)) return applyColorModifiers({ rgb: val.toUpperCase() }, srgbClr);
+	}
+	const schemeClr = children.find((el) => el.name === "a:schemeClr");
+	if (schemeClr) {
+		const val = getAttribute(schemeClr, null, "val");
+		if (val) return applyColorModifiers({ themeColor: SCHEME_TO_THEME_COLOR[val] ?? "dk1" }, schemeClr);
+	}
+	const sysClr = children.find((el) => el.name === "a:sysClr");
+	if (sysClr) {
+		const lastClr = getAttribute(sysClr, null, "lastClr");
+		return { rgb: isHexColor(lastClr) ? lastClr.toUpperCase() : "000000" };
+	}
+	const prstClr = children.find((el) => el.name === "a:prstClr");
+	if (prstClr) {
+		const val = getAttribute(prstClr, null, "val");
+		if (val && PRESET_COLORS[val]) return { rgb: PRESET_COLORS[val] };
+	}
+}
+/**
+* Parse fill from shape properties (a:solidFill, a:noFill, a:gradFill).
+*/
+function parseFill(spPr) {
+	if (!spPr) return;
+	const children = getChildElements(spPr);
+	if (children.some((el) => el.name === "a:noFill")) return { type: "none" };
+	const solidFill = children.find((el) => el.name === "a:solidFill");
+	if (solidFill) {
+		const color = parseColorElement(solidFill);
+		return color !== void 0 ? {
+			type: "solid",
+			color
+		} : { type: "solid" };
+	}
+	if (children.some((el) => el.name === "a:gradFill")) return { type: "gradient" };
+}
+/**
+* Parse outline from shape properties (a:ln).
+*/
+function parseOutline(spPr) {
+	const ln = spPr ? findByFullName(spPr, "a:ln") : null;
+	if (!ln) return;
+	const children = getChildElements(ln);
+	if (children.some((el) => el.name === "a:noFill")) return;
+	const outline = {};
+	const w = getAttribute(ln, null, "w");
+	if (w) outline.width = Number.parseInt(w, 10);
+	const solidFill = children.find((el) => el.name === "a:solidFill");
+	if (solidFill) {
+		const color = parseColorElement(solidFill);
+		if (color !== void 0) outline.color = color;
+	}
+	const prstDash = children.find((el) => el.name === "a:prstDash");
+	if (prstDash) {
+		const val = narrowEnum(getAttribute(prstDash, null, "val"), ShapeOutlineStyleSchema);
+		if (val) outline.style = val;
+	}
+	return outline;
+}
+/**
+* Parse horizontal position from wp:positionH element.
+*/
+function parsePositionH(posH) {
+	if (!posH) return;
+	const relativeTo = narrowEnum(getAttribute(posH, null, "relativeFrom"), ImageHorizontalRelativeToSchema) ?? "column";
+	const alignEl = findByFullName(posH, "wp:align");
+	if (alignEl) {
+		const text = getTextContent(alignEl);
+		const result = { relativeTo };
+		const alignment = narrowEnum(text, ImageHorizontalAlignmentSchema);
+		if (alignment) result.alignment = alignment;
+		return result;
+	}
+	const posOffsetEl = findByFullName(posH, "wp:posOffset");
+	if (posOffsetEl) {
+		const text = getTextContent(posOffsetEl);
+		const posOffset = Number.parseInt(text, 10);
+		return {
+			relativeTo,
+			posOffset: Number.isNaN(posOffset) ? 0 : posOffset
+		};
+	}
+	return { relativeTo };
+}
+/**
+* Parse vertical position from wp:positionV element.
+*/
+function parsePositionV(posV) {
+	if (!posV) return;
+	const relativeTo = narrowEnum(getAttribute(posV, null, "relativeFrom"), ImageVerticalRelativeToSchema) ?? "paragraph";
+	const alignEl = findByFullName(posV, "wp:align");
+	if (alignEl) {
+		const text = getTextContent(alignEl);
+		const result = { relativeTo };
+		const alignment = narrowEnum(text, ImageVerticalAlignmentSchema);
+		if (alignment) result.alignment = alignment;
+		return result;
+	}
+	const posOffsetEl = findByFullName(posV, "wp:posOffset");
+	if (posOffsetEl) {
+		const text = getTextContent(posOffsetEl);
+		const posOffset = Number.parseInt(text, 10);
+		return {
+			relativeTo,
+			posOffset: Number.isNaN(posOffset) ? 0 : posOffset
+		};
+	}
+	return { relativeTo };
+}
+/**
+* Parse position for anchored drawings (combines positionH + positionV).
+*/
+function parseAnchorPosition(anchor) {
+	const positionH = findByFullName(anchor, "wp:positionH");
+	const positionV = findByFullName(anchor, "wp:positionV");
+	if (!positionH && !positionV) return;
+	return {
+		horizontal: parsePositionH(positionH) ?? { relativeTo: "column" },
+		vertical: parsePositionV(positionV) ?? { relativeTo: "paragraph" }
+	};
+}
+/** Known wrap element names */
+const WRAP_ELEMENT_NAMES = [
+	"wp:wrapNone",
+	"wp:wrapSquare",
+	"wp:wrapTight",
+	"wp:wrapThrough",
+	"wp:wrapTopAndBottom"
+];
+/**
+* Parse wrap settings from a wrap element.
+*
+* Distance attributes (distT/distB/distL/distR) can appear on both
+* the anchor element and the wrap child. Wrap child values take priority;
+* anchor-level values are used as fallbacks.
+*/
+function parseWrapElement(wrapEl, behindDoc, anchorDistances) {
+	if (!wrapEl) {
+		const wrap = { type: behindDoc ? "behind" : "inFront" };
+		if (anchorDistances?.distT !== void 0) wrap.distT = anchorDistances.distT;
+		if (anchorDistances?.distB !== void 0) wrap.distB = anchorDistances.distB;
+		if (anchorDistances?.distL !== void 0) wrap.distL = anchorDistances.distL;
+		if (anchorDistances?.distR !== void 0) wrap.distR = anchorDistances.distR;
+		return wrap;
+	}
+	const wrapType = (wrapEl.name || "").replace("wp:", "");
+	let type;
+	switch (wrapType) {
+		case "wrapNone":
+			type = behindDoc ? "behind" : "inFront";
+			break;
+		case "wrapSquare":
+			type = "square";
+			break;
+		case "wrapTight":
+			type = "tight";
+			break;
+		case "wrapThrough":
+			type = "through";
+			break;
+		case "wrapTopAndBottom":
+			type = "topAndBottom";
+			break;
+		default: type = "square";
+	}
+	const wrap = { type };
+	const wrapText = narrowEnum(getAttribute(wrapEl, null, "wrapText"), ImageWrapTextSchema);
+	if (wrapText) wrap.wrapText = wrapText;
+	const distT = parseNumericAttribute(wrapEl, null, "distT") ?? anchorDistances?.distT;
+	const distB = parseNumericAttribute(wrapEl, null, "distB") ?? anchorDistances?.distB;
+	const distL = parseNumericAttribute(wrapEl, null, "distL") ?? anchorDistances?.distL;
+	const distR = parseNumericAttribute(wrapEl, null, "distR") ?? anchorDistances?.distR;
+	if (distT !== void 0) wrap.distT = distT;
+	if (distB !== void 0) wrap.distB = distB;
+	if (distL !== void 0) wrap.distL = distL;
+	if (distR !== void 0) wrap.distR = distR;
+	return wrap;
+}
+/**
+* Parse wrap from an anchor element (finds wrap child internally).
+*/
+function parseAnchorWrap(anchor) {
+	const children = getChildElements(anchor);
+	const behindDoc = getAttribute(anchor, null, "behindDoc") === "1";
+	const wrapEl = children.find((el) => WRAP_ELEMENT_NAMES.includes(el.name ?? ""));
+	const distT = parseNumericAttribute(anchor, null, "distT");
+	const distB = parseNumericAttribute(anchor, null, "distB");
+	const distL = parseNumericAttribute(anchor, null, "distL");
+	const distR = parseNumericAttribute(anchor, null, "distR");
+	const anchorDistances = {
+		...distT != null ? { distT } : {},
+		...distB != null ? { distB } : {},
+		...distL != null ? { distL } : {},
+		...distR != null ? { distR } : {}
+	};
+	return parseWrapElement(wrapEl ?? null, behindDoc, anchorDistances);
+}
+/**
+* Default theme color fallbacks (Office 2016 defaults).
+* Used when resolving theme colors without a Theme object.
+*/
+const DEFAULT_THEME_COLOR_HEX = {
+	accent1: "5B9BD5",
+	accent2: "ED7D31",
+	accent3: "A5A5A5",
+	accent4: "FFC000",
+	accent5: "4472C4",
+	accent6: "70AD47",
+	dk1: "000000",
+	lt1: "FFFFFF",
+	dk2: "1F497D",
+	lt2: "EEECE1",
+	text1: "000000",
+	text2: "1F497D",
+	background1: "FFFFFF",
+	background2: "EEECE1",
+	hlink: "0563C1",
+	folHlink: "954F72"
+};
+/**
+* Resolve a ColorValue to a CSS hex string using default theme colors.
+* For use when no Theme object is available (e.g., shape/text box parsing).
+*/
+function resolveColorValueToHex(color) {
+	if (!color) return;
+	if (color.rgb) return `#${color.rgb}`;
+	if (color.themeColor) return `#${DEFAULT_THEME_COLOR_HEX[color.themeColor] ?? "000000"}`;
+}
+//#endregion
+export { WRAP_ELEMENT_NAMES, parseAnchorPosition, parseAnchorWrap, parseColorElement, parseFill, parseOutline, parsePositionH, parsePositionV, parseWrapElement, resolveColorValueToHex };

package/dist/docx/fieldParser.d.ts

@@ -0,0 +1,228 @@
+import { document_d_exports } from "../types/document.js";
+import { StyleMap } from "./styleParser.js";
+import { XmlElement } from "./xmlParser.js";
+
+//#region src/docx/fieldParser.d.ts
+/**
+ * All known field types from OOXML specification
+ */
+declare const KNOWN_FIELD_TYPES: readonly document_d_exports.FieldType[];
+/**
+ * Parse field type from instruction string
+ *
+ * Field instructions follow the format: FIELDNAME [arguments] [switches]
+ * Examples:
+ * - "PAGE \\* MERGEFORMAT"
+ * - "DATE \\@ \"MMMM d, yyyy\""
+ * - "MERGEFIELD client_name \\* Upper"
+ * - "REF _Ref123456 \\h"
+ *
+ * @param instruction - The field instruction string
+ * @returns The detected field type
+ */
+declare function parseFieldType(instruction: string): document_d_exports.FieldType;
+/**
+ * Check if a field type is a known type. The sentinel "UNKNOWN" value
+ * is not considered a "known" type even though it belongs to FieldType.
+ *
+ * @param type - Field type string to check
+ * @returns true if it's a known field type
+ */
+declare function isKnownFieldType(type: string): type is document_d_exports.FieldType;
+/**
+ * Parsed field instruction with arguments and switches
+ */
+type ParsedFieldInstruction = {
+  /** Field type */type: document_d_exports.FieldType; /** Raw instruction string */
+  raw: string; /** Field argument (e.g., property name for DOCPROPERTY, bookmark name for REF) */
+  argument?: string; /** Field switches (e.g., \* MERGEFORMAT, \@ "date format") */
+  switches: FieldSwitch[];
+};
+/**
+ * Field switch parsed from instruction
+ */
+type FieldSwitch = {
+  /** Switch character (e.g., '*', '@', '#', 'h', 'p') */switch: string; /** Switch value if any */
+  value?: string;
+};
+/**
+ * Parse a complete field instruction into structured data
+ *
+ * @param instruction - Raw instruction string
+ * @returns Parsed instruction object
+ */
+declare function parseFieldInstruction(instruction: string): ParsedFieldInstruction;
+/**
+ * Get the format switch value (\* or \@)
+ *
+ * @param instruction - Parsed instruction
+ * @returns Format string or undefined
+ */
+declare function getFormatSwitch(instruction: ParsedFieldInstruction): string | undefined;
+/**
+ * Check if field has MERGEFORMAT switch (preserve formatting)
+ *
+ * @param instruction - Parsed instruction
+ * @returns true if MERGEFORMAT is present
+ */
+declare function hasMergeFormat(instruction: ParsedFieldInstruction): boolean;
+/**
+ * Parse a simple field element (w:fldSimple)
+ *
+ * @param node - The w:fldSimple XML element
+ * @param styles - Style definitions for parsing content runs
+ * @param theme - Theme for color/font resolution
+ * @returns Parsed SimpleField object
+ */
+declare function parseSimpleField(node: XmlElement, styles: StyleMap | null, theme: document_d_exports.Theme | null): document_d_exports.SimpleField;
+/**
+ * State machine for tracking complex field parsing
+ */
+type ComplexFieldState = "outside" | "code" | "result";
+/**
+ * Complex field parsing context
+ */
+type ComplexFieldContext = {
+  /** Current state */state: ComplexFieldState; /** Accumulated instruction text */
+  instruction: string; /** Runs in the field code section */
+  codeRuns: document_d_exports.Run[]; /** Runs in the result section */
+  resultRuns: document_d_exports.Run[]; /** Whether field is locked */
+  fldLock: boolean; /** Whether field needs update */
+  dirty: boolean; /** Nesting level (for nested fields) */
+  nestingLevel: number;
+};
+/**
+ * Create a new complex field context
+ */
+declare function createComplexFieldContext(): ComplexFieldContext;
+/**
+ * Reset the context for a new field
+ */
+declare function resetComplexFieldContext(ctx: ComplexFieldContext): void;
+/**
+ * Finalize a complex field from its context
+ *
+ * @param ctx - The field context
+ * @returns The parsed ComplexField
+ */
+declare function finalizeComplexField(ctx: ComplexFieldContext): document_d_exports.ComplexField;
+/**
+ * Get the current display value of a field
+ *
+ * @param field - The field (simple or complex)
+ * @returns The display text
+ */
+declare function getFieldDisplayValue(field: document_d_exports.Field): string;
+/**
+ * Check if field represents a page number
+ *
+ * @param field - The field to check
+ * @returns true if this is a page number field
+ */
+declare function isPageNumberField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field represents total page count
+ *
+ * @param field - The field to check
+ * @returns true if this is a total pages field
+ */
+declare function isTotalPagesField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a date/time field
+ *
+ * @param field - The field to check
+ * @returns true if this is a date/time field
+ */
+declare function isDateTimeField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a document property field
+ *
+ * @param field - The field to check
+ * @returns true if this is a document property field
+ */
+declare function isDocPropertyField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a cross-reference field
+ *
+ * @param field - The field to check
+ * @returns true if this is a cross-reference field
+ */
+declare function isReferenceField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a mail merge field
+ *
+ * @param field - The field to check
+ * @returns true if this is a mail merge field
+ */
+declare function isMergeField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a hyperlink field
+ *
+ * @param field - The field to check
+ * @returns true if this is a hyperlink field
+ */
+declare function isHyperlinkField(field: document_d_exports.Field): boolean;
+/**
+ * Check if field is a TOC/Index field
+ *
+ * @param field - The field to check
+ * @returns true if this is a TOC or index field
+ */
+declare function isTocField(field: document_d_exports.Field): boolean;
+/**
+ * Compute the value for a page number field
+ *
+ * @param pageNumber - Current page number
+ * @param instruction - Parsed instruction for format switches
+ * @returns Formatted page number string
+ */
+declare function computePageNumber(pageNumber: number, instruction?: ParsedFieldInstruction): string;
+/**
+ * Format a date according to a format string
+ *
+ * Supports common OOXML date format codes:
+ * - M, MM, MMM, MMMM - Month
+ * - d, dd, ddd, dddd - Day
+ * - yy, yyyy - Year
+ * - h, hh, H, HH - Hour
+ * - m, mm - Minute (in time context)
+ * - s, ss - Second
+ * - AM/PM, am/pm - AM/PM indicator
+ *
+ * @param date - The date to format
+ * @param format - The format string
+ * @returns Formatted date string
+ */
+declare function formatDate(date: Date, format: string): string;
+declare function collectFields(content: unknown[]): document_d_exports.Field[];
+/**
+ * Get all fields of a specific type
+ *
+ * @param fields - Array of fields
+ * @param fieldType - The field type to filter by
+ * @returns Filtered array of fields
+ */
+declare function getFieldsByType(fields: document_d_exports.Field[], fieldType: document_d_exports.FieldType): document_d_exports.Field[];
+/**
+ * Find all page number fields
+ *
+ * @param fields - Array of fields
+ * @returns Array of PAGE fields
+ */
+declare function getPageNumberFields(fields: document_d_exports.Field[]): document_d_exports.Field[];
+/**
+ * Find all merge fields
+ *
+ * @param fields - Array of fields
+ * @returns Array of MERGEFIELD fields
+ */
+declare function getMergeFields(fields: document_d_exports.Field[]): document_d_exports.Field[];
+/**
+ * Extract merge field names from fields
+ *
+ * @param fields - Array of fields
+ * @returns Array of merge field names
+ */
+declare function getMergeFieldNames(fields: document_d_exports.Field[]): string[];
+//#endregion
+export { ComplexFieldContext, ComplexFieldState, FieldSwitch, KNOWN_FIELD_TYPES, ParsedFieldInstruction, collectFields, computePageNumber, createComplexFieldContext, finalizeComplexField, formatDate, getFieldDisplayValue, getFieldsByType, getFormatSwitch, getMergeFieldNames, getMergeFields, getPageNumberFields, hasMergeFormat, isDateTimeField, isDocPropertyField, isHyperlinkField, isKnownFieldType, isMergeField, isPageNumberField, isReferenceField, isTocField, isTotalPagesField, parseFieldInstruction, parseFieldType, parseSimpleField, resetComplexFieldContext };