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

package/dist/docx/fieldParser.js

@@ -0,0 +1,559 @@
+import { findChildren, getAttribute } from "./xmlParser.js";
+import { FieldTypeSchema, narrowEnum } from "./parserEnums.js";
+import { parseRun } from "./runParser.js";
+//#region src/docx/fieldParser.ts
+/**
+* All known field types from OOXML specification
+*/
+const KNOWN_FIELD_TYPES = [
+	"PAGE",
+	"NUMPAGES",
+	"NUMWORDS",
+	"NUMCHARS",
+	"DATE",
+	"TIME",
+	"CREATEDATE",
+	"SAVEDATE",
+	"PRINTDATE",
+	"EDITTIME",
+	"AUTHOR",
+	"TITLE",
+	"SUBJECT",
+	"KEYWORDS",
+	"COMMENTS",
+	"FILENAME",
+	"FILESIZE",
+	"TEMPLATE",
+	"REVNUM",
+	"DOCPROPERTY",
+	"DOCVARIABLE",
+	"REF",
+	"PAGEREF",
+	"NOTEREF",
+	"HYPERLINK",
+	"TOC",
+	"TOA",
+	"INDEX",
+	"SEQ",
+	"STYLEREF",
+	"AUTONUM",
+	"AUTONUMLGL",
+	"AUTONUMOUT",
+	"LISTNUM",
+	"SECTION",
+	"SECTIONPAGES",
+	"USERADDRESS",
+	"USERNAME",
+	"USERINITIALS",
+	"IF",
+	"MERGEFIELD",
+	"NEXT",
+	"NEXTIF",
+	"ASK",
+	"SET",
+	"QUOTE",
+	"INCLUDETEXT",
+	"INCLUDEPICTURE",
+	"SYMBOL",
+	"ADVANCE"
+];
+/**
+* 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
+*/
+function parseFieldType(instruction) {
+	if (!instruction) return "UNKNOWN";
+	const trimmed = instruction.trim();
+	const match = /^\\?(?<name>[A-Z][A-Z0-9]*)/iu.exec(trimmed);
+	if (!match) return "UNKNOWN";
+	return narrowEnum(match.groups["name"].toUpperCase(), FieldTypeSchema) ?? "UNKNOWN";
+}
+/**
+* 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
+*/
+function isKnownFieldType(type) {
+	const narrowed = narrowEnum(type, FieldTypeSchema);
+	return narrowed !== void 0 && narrowed !== "UNKNOWN";
+}
+/**
+* Parse a complete field instruction into structured data
+*
+* @param instruction - Raw instruction string
+* @returns Parsed instruction object
+*/
+function parseFieldInstruction(instruction) {
+	const type = parseFieldType(instruction);
+	const trimmed = instruction.trim();
+	const switches = [];
+	const nameMatch = /^\\?(?:[A-Z][A-Z0-9]*)/iu.exec(trimmed);
+	const fieldNameEnd = nameMatch ? nameMatch[0].length : 0;
+	const remaining = trimmed.slice(fieldNameEnd).trim();
+	const switchRegex = /\\(?<switch>\*|@|#|!|[a-z])\s*(?:"(?<quoted>[^"]*)"|(?<unquoted>[\S]*))?/giu;
+	let switchMatch;
+	const switchPositions = [];
+	while ((switchMatch = switchRegex.exec(remaining)) !== null) {
+		const groups = switchMatch.groups;
+		const sw = { switch: groups["switch"] };
+		if (groups["quoted"]) sw.value = groups["quoted"];
+		else if (groups["unquoted"]) sw.value = groups["unquoted"];
+		switches.push(sw);
+		switchPositions.push({
+			start: switchMatch.index,
+			end: switchMatch.index + switchMatch[0].length
+		});
+	}
+	let argument;
+	if (remaining.length > 0) {
+		const firstSwitchPos = switchPositions.length > 0 ? switchPositions[0].start : remaining.length;
+		const beforeSwitch = remaining.slice(0, firstSwitchPos).trim();
+		if (beforeSwitch.startsWith("\"") && beforeSwitch.endsWith("\"")) argument = beforeSwitch.slice(1, -1);
+		else if (beforeSwitch) argument = beforeSwitch;
+	}
+	return {
+		type,
+		raw: instruction,
+		...argument !== void 0 ? { argument } : {},
+		switches
+	};
+}
+/**
+* Get the format switch value (\* or \@)
+*
+* @param instruction - Parsed instruction
+* @returns Format string or undefined
+*/
+function getFormatSwitch(instruction) {
+	return instruction.switches.find((s) => s.switch === "*" || s.switch === "@")?.value;
+}
+/**
+* Check if field has MERGEFORMAT switch (preserve formatting)
+*
+* @param instruction - Parsed instruction
+* @returns true if MERGEFORMAT is present
+*/
+function hasMergeFormat(instruction) {
+	return instruction.switches.find((s) => s.switch === "*")?.value?.toUpperCase() === "MERGEFORMAT";
+}
+/**
+* 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
+*/
+function parseSimpleField(node, styles, theme) {
+	const instruction = getAttribute(node, "w", "instr") ?? "";
+	const field = {
+		type: "simpleField",
+		instruction,
+		fieldType: parseFieldType(instruction),
+		content: []
+	};
+	const fldLock = getAttribute(node, "w", "fldLock");
+	if (fldLock === "1" || fldLock === "true") field.fldLock = true;
+	const dirty = getAttribute(node, "w", "dirty");
+	if (dirty === "1" || dirty === "true") field.dirty = true;
+	const children = findChildren(node, "w", "r");
+	for (const child of children) {
+		const run = parseRun(child, styles, theme);
+		field.content.push(run);
+	}
+	return field;
+}
+/**
+* Create a new complex field context
+*/
+function createComplexFieldContext() {
+	return {
+		state: "outside",
+		instruction: "",
+		codeRuns: [],
+		resultRuns: [],
+		fldLock: false,
+		dirty: false,
+		nestingLevel: 0
+	};
+}
+/**
+* Reset the context for a new field
+*/
+function resetComplexFieldContext(ctx) {
+	ctx.state = "code";
+	ctx.instruction = "";
+	ctx.codeRuns = [];
+	ctx.resultRuns = [];
+	ctx.fldLock = false;
+	ctx.dirty = false;
+}
+/**
+* Finalize a complex field from its context
+*
+* @param ctx - The field context
+* @returns The parsed ComplexField
+*/
+function finalizeComplexField(ctx) {
+	return {
+		type: "complexField",
+		instruction: ctx.instruction.trim(),
+		fieldType: parseFieldType(ctx.instruction),
+		fieldCode: ctx.codeRuns,
+		fieldResult: ctx.resultRuns,
+		...ctx.fldLock && { fldLock: true },
+		...ctx.dirty && { dirty: true }
+	};
+}
+/**
+* Get the current display value of a field
+*
+* @param field - The field (simple or complex)
+* @returns The display text
+*/
+function getFieldDisplayValue(field) {
+	if (field.type === "simpleField") return field.content.filter((c) => "content" in c).map((run) => getRunText(run)).join("");
+	return field.fieldResult.map((run) => getRunText(run)).join("");
+}
+/**
+* Helper to get text from a run (simplified)
+*/
+function getRunText(run) {
+	return run.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+}
+/**
+* Check if field represents a page number
+*
+* @param field - The field to check
+* @returns true if this is a page number field
+*/
+function isPageNumberField(field) {
+	return field.fieldType === "PAGE";
+}
+/**
+* Check if field represents total page count
+*
+* @param field - The field to check
+* @returns true if this is a total pages field
+*/
+function isTotalPagesField(field) {
+	return field.fieldType === "NUMPAGES";
+}
+/**
+* Check if field is a date/time field
+*
+* @param field - The field to check
+* @returns true if this is a date/time field
+*/
+function isDateTimeField(field) {
+	return [
+		"DATE",
+		"TIME",
+		"CREATEDATE",
+		"SAVEDATE",
+		"PRINTDATE",
+		"EDITTIME"
+	].includes(field.fieldType);
+}
+/**
+* Check if field is a document property field
+*
+* @param field - The field to check
+* @returns true if this is a document property field
+*/
+function isDocPropertyField(field) {
+	return [
+		"AUTHOR",
+		"TITLE",
+		"SUBJECT",
+		"KEYWORDS",
+		"COMMENTS",
+		"FILENAME",
+		"FILESIZE",
+		"TEMPLATE",
+		"REVNUM",
+		"DOCPROPERTY",
+		"DOCVARIABLE"
+	].includes(field.fieldType);
+}
+/**
+* Check if field is a cross-reference field
+*
+* @param field - The field to check
+* @returns true if this is a cross-reference field
+*/
+function isReferenceField(field) {
+	return [
+		"REF",
+		"PAGEREF",
+		"NOTEREF"
+	].includes(field.fieldType);
+}
+/**
+* Check if field is a mail merge field
+*
+* @param field - The field to check
+* @returns true if this is a mail merge field
+*/
+function isMergeField(field) {
+	return [
+		"MERGEFIELD",
+		"IF",
+		"NEXT",
+		"NEXTIF",
+		"ASK",
+		"SET"
+	].includes(field.fieldType);
+}
+/**
+* Check if field is a hyperlink field
+*
+* @param field - The field to check
+* @returns true if this is a hyperlink field
+*/
+function isHyperlinkField(field) {
+	return field.fieldType === "HYPERLINK";
+}
+/**
+* Check if field is a TOC/Index field
+*
+* @param field - The field to check
+* @returns true if this is a TOC or index field
+*/
+function isTocField(field) {
+	return [
+		"TOC",
+		"TOA",
+		"INDEX"
+	].includes(field.fieldType);
+}
+/**
+* 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
+*/
+function computePageNumber(pageNumber, instruction) {
+	if (!instruction) return String(pageNumber);
+	const format = getFormatSwitch(instruction);
+	if (!format) return String(pageNumber);
+	switch (format.toUpperCase()) {
+		case "ROMAN": return toRoman(pageNumber);
+		case "ALPHABETIC": return toLetter(pageNumber);
+		default: return String(pageNumber);
+	}
+}
+/**
+* Convert number to uppercase Roman numerals
+*/
+function toRoman(num) {
+	if (num <= 0 || num > 3999) return String(num);
+	const values = [
+		1e3,
+		900,
+		500,
+		400,
+		100,
+		90,
+		50,
+		40,
+		10,
+		9,
+		5,
+		4,
+		1
+	];
+	const symbols = [
+		"M",
+		"CM",
+		"D",
+		"CD",
+		"C",
+		"XC",
+		"L",
+		"XL",
+		"X",
+		"IX",
+		"V",
+		"IV",
+		"I"
+	];
+	let result = "";
+	let remaining = num;
+	for (let i = 0; i < values.length; i++) while (remaining >= values[i]) {
+		result += symbols[i];
+		remaining -= values[i];
+	}
+	return result;
+}
+/**
+* Convert number to letter (A, B, ... Z, AA, AB, ...)
+*/
+function toLetter(num) {
+	if (num <= 0) return String(num);
+	let result = "";
+	let n = num;
+	while (n > 0) {
+		n--;
+		result = String.fromCodePoint(65 + n % 26) + result;
+		n = Math.floor(n / 26);
+	}
+	return result;
+}
+/**
+* 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
+*/
+function formatDate(date, format) {
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December"
+	];
+	const shortMonths = [
+		"Jan",
+		"Feb",
+		"Mar",
+		"Apr",
+		"May",
+		"Jun",
+		"Jul",
+		"Aug",
+		"Sep",
+		"Oct",
+		"Nov",
+		"Dec"
+	];
+	const days = [
+		"Sunday",
+		"Monday",
+		"Tuesday",
+		"Wednesday",
+		"Thursday",
+		"Friday",
+		"Saturday"
+	];
+	const shortDays = [
+		"Sun",
+		"Mon",
+		"Tue",
+		"Wed",
+		"Thu",
+		"Fri",
+		"Sat"
+	];
+	const pad = (n) => n.toString().padStart(2, "0");
+	const hour12 = date.getHours() % 12 || 12;
+	const ampm = date.getHours() >= 12 ? "PM" : "AM";
+	return format.replace(/AM\/PM|am\/pm|yyyy|yy|MMMM|MMM|MM|M|dddd|ddd|dd|d|hh|h|HH|H|mm|m|ss|s/gu, (token) => {
+		switch (token) {
+			case "yyyy": return date.getFullYear().toString();
+			case "yy": return (date.getFullYear() % 100).toString().padStart(2, "0");
+			case "MMMM": return months[date.getMonth()];
+			case "MMM": return shortMonths[date.getMonth()];
+			case "MM": return pad(date.getMonth() + 1);
+			case "M": return (date.getMonth() + 1).toString();
+			case "dddd": return days[date.getDay()];
+			case "ddd": return shortDays[date.getDay()];
+			case "dd": return pad(date.getDate());
+			case "d": return date.getDate().toString();
+			case "hh": return pad(hour12);
+			case "h": return hour12.toString();
+			case "HH": return pad(date.getHours());
+			case "H": return date.getHours().toString();
+			case "mm": return pad(date.getMinutes());
+			case "m": return date.getMinutes().toString();
+			case "ss": return pad(date.getSeconds());
+			case "s": return date.getSeconds().toString();
+			case "AM/PM": return ampm;
+			case "am/pm": return ampm.toLowerCase();
+			default: return token;
+		}
+	});
+}
+/**
+* Collect all fields from a document content array
+*
+* @param content - Array of paragraph content items
+* @returns Array of all fields found
+*/
+function isField(item) {
+	return item !== null && typeof item === "object" && "type" in item && (item.type === "simpleField" || item.type === "complexField");
+}
+function collectFields(content) {
+	return content.filter(isField);
+}
+/**
+* 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
+*/
+function getFieldsByType(fields, fieldType) {
+	return fields.filter((f) => f.fieldType === fieldType);
+}
+/**
+* Find all page number fields
+*
+* @param fields - Array of fields
+* @returns Array of PAGE fields
+*/
+function getPageNumberFields(fields) {
+	return getFieldsByType(fields, "PAGE");
+}
+/**
+* Find all merge fields
+*
+* @param fields - Array of fields
+* @returns Array of MERGEFIELD fields
+*/
+function getMergeFields(fields) {
+	return getFieldsByType(fields, "MERGEFIELD");
+}
+/**
+* Extract merge field names from fields
+*
+* @param fields - Array of fields
+* @returns Array of merge field names
+*/
+function getMergeFieldNames(fields) {
+	return getMergeFields(fields).map((f) => {
+		return parseFieldInstruction(f.instruction).argument;
+	}).filter((name) => !!name);
+}
+//#endregion
+export { KNOWN_FIELD_TYPES, 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 };

package/dist/docx/footnoteParser.d.ts

@@ -0,0 +1,109 @@
+import { document_d_exports } from "../types/document.js";
+import { NumberingMap } from "./numberingParser.js";
+import { StyleMap } from "./styleParser.js";
+import { parseEndnoteProperties, parseFootnoteProperties } from "./notePropertiesParser.js";
+
+//#region src/docx/footnoteParser.d.ts
+/**
+ * Footnote map returned by parseFootnotes
+ */
+type FootnoteMap = {
+  /** All footnotes indexed by ID */byId: Map<number, document_d_exports.Footnote>; /** Array of all footnotes in document order */
+  footnotes: document_d_exports.Footnote[]; /** Get footnote by ID */
+  getFootnote: (id: number) => document_d_exports.Footnote | undefined; /** Check if footnote exists */
+  hasFootnote: (id: number) => boolean; /** Get all normal (non-separator) footnotes */
+  getNormalFootnotes: () => document_d_exports.Footnote[]; /** Get separator footnote if exists */
+  getSeparator: () => document_d_exports.Footnote | undefined; /** Get continuation separator if exists */
+  getContinuationSeparator: () => document_d_exports.Footnote | undefined;
+};
+/**
+ * Endnote map returned by parseEndnotes
+ */
+type EndnoteMap = {
+  /** All endnotes indexed by ID */byId: Map<number, document_d_exports.Endnote>; /** Array of all endnotes in document order */
+  endnotes: document_d_exports.Endnote[]; /** Get endnote by ID */
+  getEndnote: (id: number) => document_d_exports.Endnote | undefined; /** Check if endnote exists */
+  hasEndnote: (id: number) => boolean; /** Get all normal (non-separator) endnotes */
+  getNormalEndnotes: () => document_d_exports.Endnote[]; /** Get separator endnote if exists */
+  getSeparator: () => document_d_exports.Endnote | undefined; /** Get continuation separator if exists */
+  getContinuationSeparator: () => document_d_exports.Endnote | undefined;
+};
+/**
+ * Parse footnotes.xml
+ *
+ * @param footnotesXml - The raw XML content of word/footnotes.xml
+ * @param styles - Parsed style map for applying styles
+ * @param theme - Parsed theme for color resolution
+ * @param numbering - Parsed numbering definitions for lists
+ * @param rels - Relationships for resolving hyperlinks
+ * @param media - Media files for images
+ * @returns FootnoteMap with all footnotes
+ */
+declare function parseFootnotes(footnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): FootnoteMap;
+/**
+ * Parse endnotes.xml
+ *
+ * @param endnotesXml - The raw XML content of word/endnotes.xml
+ * @param styles - Parsed style map for applying styles
+ * @param theme - Parsed theme for color resolution
+ * @param numbering - Parsed numbering definitions for lists
+ * @param rels - Relationships for resolving hyperlinks
+ * @param media - Media files for images
+ * @returns EndnoteMap with all endnotes
+ */
+declare function parseEndnotes(endnotesXml: string | null, styles?: StyleMap | null, theme?: document_d_exports.Theme | null, numbering?: NumberingMap | null, rels?: document_d_exports.RelationshipMap | null, media?: Map<string, document_d_exports.MediaFile> | null): EndnoteMap;
+/**
+ * Get plain text content of a footnote.
+ *
+ * Recurses into block-level SDTs so a citation slot inside a note still
+ * contributes its text; without recursion, the BlockSdt addition from
+ * the previous commit would silently hide the slot's body from this
+ * helper.
+ */
+declare function getFootnoteText(footnote: document_d_exports.Footnote): string;
+/**
+ * Get plain text content of an endnote.
+ */
+declare function getEndnoteText(endnote: document_d_exports.Endnote): string;
+/**
+ * Check if a footnote is a separator (not regular content)
+ */
+declare function isSeparatorFootnote(footnote: document_d_exports.Footnote): boolean;
+/**
+ * Check if an endnote is a separator (not regular content)
+ */
+declare function isSeparatorEndnote(endnote: document_d_exports.Endnote): boolean;
+/**
+ * Get footnote number for display (excluding separators)
+ * @param footnote - The footnote to get the number for
+ * @param footnoteMap - The footnote map
+ * @param startNumber - Starting number (default 1)
+ * @returns The display number, or null for separator footnotes
+ */
+declare function getFootnoteDisplayNumber(footnote: document_d_exports.Footnote, footnoteMap: FootnoteMap, startNumber?: number): number | null;
+/**
+ * Get endnote number for display (excluding separators)
+ * @param endnote - The endnote to get the number for
+ * @param endnoteMap - The endnote map
+ * @param startNumber - Starting number (default 1)
+ * @returns The display number, or null for separator endnotes
+ */
+declare function getEndnoteDisplayNumber(endnote: document_d_exports.Endnote, endnoteMap: EndnoteMap, startNumber?: number): number | null;
+/**
+ * Create an empty footnote map
+ */
+declare function createEmptyFootnoteMap(): FootnoteMap;
+/**
+ * Create an empty endnote map
+ */
+declare function createEmptyEndnoteMap(): EndnoteMap;
+/**
+ * Merge multiple footnote maps (e.g., from different documents)
+ */
+declare function mergeFootnoteMaps(...maps: FootnoteMap[]): FootnoteMap;
+/**
+ * Merge multiple endnote maps (e.g., from different documents)
+ */
+declare function mergeEndnoteMaps(...maps: EndnoteMap[]): EndnoteMap;
+//#endregion
+export { EndnoteMap, FootnoteMap, createEmptyEndnoteMap, createEmptyFootnoteMap, getEndnoteDisplayNumber, getEndnoteText, getFootnoteDisplayNumber, getFootnoteText, isSeparatorEndnote, isSeparatorFootnote, mergeEndnoteMaps, mergeFootnoteMaps, parseEndnoteProperties, parseEndnotes, parseFootnoteProperties, parseFootnotes };