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

package/dist/utils/createDocument.d.ts

@@ -0,0 +1,50 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/utils/createDocument.d.ts
+/**
+ * Options for creating an empty document
+ */
+type CreateEmptyDocumentOptions = {
+  /** Page width in twips (default: 12240 = 8.5 inches) */pageWidth?: number; /** Page height in twips (default: 15840 = 11 inches) */
+  pageHeight?: number; /** Page orientation (default: 'portrait') */
+  orientation?: "portrait" | "landscape"; /** Top margin in twips (default: 1440 = 1 inch) */
+  marginTop?: number; /** Bottom margin in twips (default: 1440 = 1 inch) */
+  marginBottom?: number; /** Left margin in twips (default: 1440 = 1 inch) */
+  marginLeft?: number; /** Right margin in twips (default: 1440 = 1 inch) */
+  marginRight?: number; /** Initial text content (default: empty string) */
+  initialText?: string;
+};
+/**
+ * Create an empty document with a single paragraph
+ *
+ * @param options - Optional configuration for the document
+ * @returns A new empty Document object
+ *
+ * @example
+ * ```ts
+ * // Create a blank document
+ * const doc = createEmptyDocument();
+ *
+ * // Create with custom margins
+ * const doc = createEmptyDocument({
+ *   marginTop: 720,  // 0.5 inch
+ *   marginBottom: 720,
+ * });
+ *
+ * // Create with initial text
+ * const doc = createEmptyDocument({
+ *   initialText: 'Hello, World!'
+ * });
+ * ```
+ */
+declare function createEmptyDocument(options?: CreateEmptyDocumentOptions): document_d_exports.Document;
+/**
+ * Create a document with a single paragraph containing the given text
+ *
+ * @param text - The text content for the document
+ * @param options - Optional configuration for the document
+ * @returns A new Document object with the specified text
+ */
+declare function createDocumentWithText(text: string, options?: Omit<CreateEmptyDocumentOptions, "initialText">): document_d_exports.Document;
+//#endregion
+export { CreateEmptyDocumentOptions, createDocumentWithText, createEmptyDocument };

package/dist/utils/createDocument.js

@@ -0,0 +1,262 @@
+//#region src/utils/createDocument.ts
+/**
+* Get default paragraph styles (matching Google Docs defaults)
+*
+* Font sizes are in half-points (e.g., 22 = 11pt, 40 = 20pt)
+* Colors are RGB hex without # prefix
+*/
+function getDefaultStyles() {
+	return [
+		{
+			styleId: "Normal",
+			type: "paragraph",
+			name: "Normal",
+			default: true,
+			qFormat: true,
+			uiPriority: 0,
+			rPr: {
+				fontSize: 22,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: { lineSpacing: 276 }
+		},
+		{
+			styleId: "Title",
+			type: "paragraph",
+			name: "Title",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 10,
+			rPr: {
+				fontSize: 52,
+				bold: true,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: { lineSpacing: 240 }
+		},
+		{
+			styleId: "Subtitle",
+			type: "paragraph",
+			name: "Subtitle",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 11,
+			rPr: {
+				fontSize: 30,
+				color: { rgb: "666666" },
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: { lineSpacing: 240 }
+		},
+		{
+			styleId: "Heading1",
+			type: "paragraph",
+			name: "Heading 1",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 9,
+			rPr: {
+				fontSize: 40,
+				bold: true,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: {
+				spaceBefore: 400,
+				spaceAfter: 120,
+				lineSpacing: 240
+			}
+		},
+		{
+			styleId: "Heading2",
+			type: "paragraph",
+			name: "Heading 2",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 9,
+			rPr: {
+				fontSize: 32,
+				bold: true,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: {
+				spaceBefore: 360,
+				spaceAfter: 80,
+				lineSpacing: 240
+			}
+		},
+		{
+			styleId: "Heading3",
+			type: "paragraph",
+			name: "Heading 3",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 9,
+			rPr: {
+				fontSize: 28,
+				bold: true,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: {
+				spaceBefore: 320,
+				spaceAfter: 80,
+				lineSpacing: 240
+			}
+		},
+		{
+			styleId: "Heading4",
+			type: "paragraph",
+			name: "Heading 4",
+			basedOn: "Normal",
+			next: "Normal",
+			qFormat: true,
+			uiPriority: 9,
+			rPr: {
+				fontSize: 24,
+				bold: true,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
+			},
+			pPr: {
+				spaceBefore: 280,
+				spaceAfter: 80,
+				lineSpacing: 240
+			}
+		}
+	];
+}
+/**
+* Get default section properties (US Letter, 1 inch margins)
+*/
+function getDefaultSectionProperties() {
+	return {
+		pageWidth: 12240,
+		pageHeight: 15840,
+		orientation: "portrait",
+		marginTop: 1440,
+		marginBottom: 1440,
+		marginLeft: 1440,
+		marginRight: 1440,
+		headerDistance: 720,
+		footerDistance: 720,
+		gutter: 0,
+		columnCount: 1,
+		columnSpace: 720,
+		equalWidth: true,
+		sectionStart: "nextPage",
+		verticalAlign: "top"
+	};
+}
+/**
+* Create an empty document with a single paragraph
+*
+* @param options - Optional configuration for the document
+* @returns A new empty Document object
+*
+* @example
+* ```ts
+* // Create a blank document
+* const doc = createEmptyDocument();
+*
+* // Create with custom margins
+* const doc = createEmptyDocument({
+*   marginTop: 720,  // 0.5 inch
+*   marginBottom: 720,
+* });
+*
+* // Create with initial text
+* const doc = createEmptyDocument({
+*   initialText: 'Hello, World!'
+* });
+* ```
+*/
+function createEmptyDocument(options = {}) {
+	const sectionProps = getDefaultSectionProperties();
+	if (options.pageWidth !== void 0) sectionProps.pageWidth = Math.round(options.pageWidth);
+	if (options.pageHeight !== void 0) sectionProps.pageHeight = Math.round(options.pageHeight);
+	if (options.orientation !== void 0) sectionProps.orientation = options.orientation;
+	if (options.marginTop !== void 0) sectionProps.marginTop = Math.round(options.marginTop);
+	if (options.marginBottom !== void 0) sectionProps.marginBottom = Math.round(options.marginBottom);
+	if (options.marginLeft !== void 0) sectionProps.marginLeft = Math.round(options.marginLeft);
+	if (options.marginRight !== void 0) sectionProps.marginRight = Math.round(options.marginRight);
+	const textContent = {
+		type: "text",
+		text: options.initialText || ""
+	};
+	return {
+		package: {
+			document: {
+				content: [{
+					type: "paragraph",
+					content: [{
+						type: "run",
+						content: options.initialText ? [textContent] : [],
+						formatting: {
+							fontSize: 22,
+							fontFamily: {
+								ascii: "Arial",
+								hAnsi: "Arial"
+							}
+						}
+					}],
+					formatting: { lineSpacing: 276 }
+				}],
+				finalSectionProperties: sectionProps
+			},
+			styles: {
+				docDefaults: {
+					rPr: {
+						fontSize: 22,
+						fontFamily: {
+							ascii: "Arial",
+							hAnsi: "Arial"
+						}
+					},
+					pPr: { lineSpacing: 276 }
+				},
+				styles: getDefaultStyles()
+			}
+		},
+		templateVariables: [],
+		warnings: []
+	};
+}
+/**
+* Create a document with a single paragraph containing the given text
+*
+* @param text - The text content for the document
+* @param options - Optional configuration for the document
+* @returns A new Document object with the specified text
+*/
+function createDocumentWithText(text, options = {}) {
+	return createEmptyDocument({
+		...options,
+		initialText: text
+	});
+}
+//#endregion
+export { createDocumentWithText, createEmptyDocument };

package/dist/utils/documentLoaderBehavior.d.ts

@@ -0,0 +1,22 @@
+import { document_d_exports } from "../types/document.js";
+import { DocxInput } from "./docxInput.js";
+
+//#region src/utils/documentLoaderBehavior.d.ts
+type DocumentLoadSource = {
+  type: "buffer";
+  buffer: DocxInput;
+} | {
+  type: "parsed-document";
+  document: document_d_exports.Document;
+} | {
+  type: "none";
+};
+declare const getDocumentLoadSource: ({
+  documentBuffer,
+  initialDocument
+}: {
+  documentBuffer: DocxInput | null | undefined;
+  initialDocument: document_d_exports.Document | null | undefined;
+}) => DocumentLoadSource;
+//#endregion
+export { DocumentLoadSource, getDocumentLoadSource };

package/dist/utils/documentLoaderBehavior.js

@@ -0,0 +1,14 @@
+//#region src/utils/documentLoaderBehavior.ts
+const getDocumentLoadSource = ({ documentBuffer, initialDocument }) => {
+	if (documentBuffer) return {
+		type: "buffer",
+		buffer: documentBuffer
+	};
+	if (initialDocument) return {
+		type: "parsed-document",
+		document: initialDocument
+	};
+	return { type: "none" };
+};
+//#endregion
+export { getDocumentLoadSource };

package/dist/utils/docxInput.d.ts

@@ -0,0 +1,22 @@
+//#region src/utils/docxInput.d.ts
+/**
+ * Flexible input types for DOCX documents.
+ *
+ * Accepts any common binary format so consumers don't need to manually
+ * convert before passing data to the editor or parser.
+ */
+/**
+ * Any binary representation of a DOCX file that the editor can consume.
+ *
+ * - `ArrayBuffer` — from `FileReader.readAsArrayBuffer()` or `fetch().arrayBuffer()`
+ * - `Uint8Array` — from Node.js `fs.readFile()` or streaming APIs
+ * - `Blob` — from drag-and-drop or `<input type="file">`
+ * - `File` — subclass of Blob, from `<input type="file">`
+ */
+type DocxInput = ArrayBuffer | Uint8Array | Blob | File;
+/**
+ * Normalize any {@link DocxInput} into an `ArrayBuffer` for internal use.
+ */
+declare function toArrayBuffer(input: DocxInput): Promise<ArrayBuffer>;
+//#endregion
+export { DocxInput, toArrayBuffer };

package/dist/utils/docxInput.js

@@ -0,0 +1,16 @@
+//#region src/utils/docxInput.ts
+/**
+* Normalize any {@link DocxInput} into an `ArrayBuffer` for internal use.
+*/
+function toArrayBuffer(input) {
+	if (input instanceof ArrayBuffer) return Promise.resolve(input);
+	if (input instanceof Uint8Array) {
+		const copy = new ArrayBuffer(input.byteLength);
+		new Uint8Array(copy).set(input);
+		return Promise.resolve(copy);
+	}
+	if (input instanceof Blob) return input.arrayBuffer();
+	return Promise.reject(/* @__PURE__ */ new TypeError(`Unsupported DocxInput type: ${typeof input}`));
+}
+//#endregion
+export { toArrayBuffer };

package/dist/utils/domGuards.d.ts

@@ -0,0 +1,59 @@
+//#region src/utils/domGuards.d.ts
+/**
+ * Runtime-checked DOM narrowing helpers.
+ *
+ * The folio editor frequently narrows DOM nodes from `Element` to
+ * `HTMLElement` (for `.dataset`, `.style`, `.closest()` callbacks)
+ * and from `Element | null` query results to specific subtypes.
+ * The native TS types are correct but conservative: these helpers
+ * replace ad-hoc `as HTMLElement` casts with `instanceof` checks
+ * so a mismatched runtime value is caught at the narrowing point
+ * instead of leaking through.
+ *
+ * Prefer these helpers over inline casts in folio DOM code.
+ */
+/**
+ * Find the first element in `elements` that is an HTMLElement and
+ * matches the predicate. Returns `null` if no match.
+ */
+declare const findHtmlElement: (elements: readonly Element[], predicate: (el: HTMLElement) => boolean) => HTMLElement | null;
+/**
+ * Query a single descendant element matching `selector` and return
+ * it only if it's an HTMLElement; null otherwise.
+ *
+ * Equivalent to `el.querySelector<HTMLElement>(selector)` but with
+ * a runtime instanceof check (querySelector's generic does not
+ * actually validate at runtime).
+ */
+declare const queryHtmlElement: (root: ParentNode, selector: string) => HTMLElement | null;
+/**
+ * Walk ancestors of `node` and return the nearest one matching
+ * `selector` that is an HTMLElement.
+ */
+declare const closestHtmlElement: (node: Element | null, selector: string) => HTMLElement | null;
+/**
+ * Return `el.children[index]` only if it is an HTMLElement;
+ * `undefined` otherwise.
+ */
+declare const childHtmlElement: (el: Element, index: number) => HTMLElement | undefined;
+/**
+ * `querySelectorAll` that returns only HTMLElements.
+ *
+ * Use at trusted DOM sources (layout containers rendered by
+ * `LayoutPainter`, our own `Toolbar`/`Sidebar` markup) where the
+ * matched nodes are guaranteed by construction to be HTMLElements.
+ * The instanceof filter runs once at the source so downstream
+ * iteration is statically-typed and pays zero per-element cost.
+ */
+declare const htmlQueryAll: (root: ParentNode, selector: string) => HTMLElement[];
+/**
+ * Assert that `node` is an HTMLElement, throwing if not.
+ *
+ * Use at a single trusted boundary where the surrounding code
+ * relies on the node being an HTMLElement (e.g., immediately
+ * after `pagesContainerRef.current` is null-checked). Downstream
+ * code reads from the asserted variable with zero runtime cost.
+ */
+declare const assertHtmlElement: (node: Node | null | undefined, description?: string) => HTMLElement;
+//#endregion
+export { assertHtmlElement, childHtmlElement, closestHtmlElement, findHtmlElement, htmlQueryAll, queryHtmlElement };

package/dist/utils/domGuards.js

@@ -0,0 +1,82 @@
+//#region src/utils/domGuards.ts
+/**
+* Runtime-checked DOM narrowing helpers.
+*
+* The folio editor frequently narrows DOM nodes from `Element` to
+* `HTMLElement` (for `.dataset`, `.style`, `.closest()` callbacks)
+* and from `Element | null` query results to specific subtypes.
+* The native TS types are correct but conservative: these helpers
+* replace ad-hoc `as HTMLElement` casts with `instanceof` checks
+* so a mismatched runtime value is caught at the narrowing point
+* instead of leaking through.
+*
+* Prefer these helpers over inline casts in folio DOM code.
+*/
+/**
+* Find the first element in `elements` that is an HTMLElement and
+* matches the predicate. Returns `null` if no match.
+*/
+const findHtmlElement = (elements, predicate) => {
+	for (const el of elements) if (el instanceof HTMLElement && predicate(el)) return el;
+	return null;
+};
+/**
+* Query a single descendant element matching `selector` and return
+* it only if it's an HTMLElement; null otherwise.
+*
+* Equivalent to `el.querySelector<HTMLElement>(selector)` but with
+* a runtime instanceof check (querySelector's generic does not
+* actually validate at runtime).
+*/
+const queryHtmlElement = (root, selector) => {
+	const found = root.querySelector(selector);
+	return found instanceof HTMLElement ? found : null;
+};
+/**
+* Walk ancestors of `node` and return the nearest one matching
+* `selector` that is an HTMLElement.
+*/
+const closestHtmlElement = (node, selector) => {
+	if (!node) return null;
+	const found = node.closest(selector);
+	return found instanceof HTMLElement ? found : null;
+};
+/**
+* Return `el.children[index]` only if it is an HTMLElement;
+* `undefined` otherwise.
+*/
+const childHtmlElement = (el, index) => {
+	const child = el.children[index];
+	return child instanceof HTMLElement ? child : void 0;
+};
+/**
+* `querySelectorAll` that returns only HTMLElements.
+*
+* Use at trusted DOM sources (layout containers rendered by
+* `LayoutPainter`, our own `Toolbar`/`Sidebar` markup) where the
+* matched nodes are guaranteed by construction to be HTMLElements.
+* The instanceof filter runs once at the source so downstream
+* iteration is statically-typed and pays zero per-element cost.
+*/
+const htmlQueryAll = (root, selector) => {
+	const out = [];
+	for (const el of root.querySelectorAll(selector)) if (el instanceof HTMLElement) out.push(el);
+	return out;
+};
+/**
+* Assert that `node` is an HTMLElement, throwing if not.
+*
+* Use at a single trusted boundary where the surrounding code
+* relies on the node being an HTMLElement (e.g., immediately
+* after `pagesContainerRef.current` is null-checked). Downstream
+* code reads from the asserted variable with zero runtime cost.
+*/
+const assertHtmlElement = (node, description) => {
+	if (!(node instanceof HTMLElement)) {
+		const where = description ? ` (${description})` : "";
+		throw new TypeError(`Expected HTMLElement${where}`);
+	}
+	return node;
+};
+//#endregion
+export { assertHtmlElement, childHtmlElement, closestHtmlElement, findHtmlElement, htmlQueryAll, queryHtmlElement };

package/dist/utils/fontFamilyMerge.d.ts

@@ -0,0 +1,7 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/utils/fontFamilyMerge.d.ts
+type FontFamily = NonNullable<document_d_exports.TextFormatting["fontFamily"]>;
+declare function mergeFontFamily(target: FontFamily | undefined, source: FontFamily): FontFamily;
+//#endregion
+export { mergeFontFamily };

package/dist/utils/fontFamilyMerge.js

@@ -0,0 +1,31 @@
+//#region src/utils/fontFamilyMerge.ts
+function mergeFontFamily(target, source) {
+	const result = {};
+	const src = source;
+	const replacesAscii = source.ascii !== void 0 || source.asciiTheme !== void 0;
+	const replacesHAnsi = source.hAnsi !== void 0 || source.hAnsiTheme !== void 0;
+	const replacesEastAsia = source.eastAsia !== void 0 || source.eastAsiaTheme !== void 0;
+	const replacesCs = source.cs !== void 0 || source.csTheme !== void 0;
+	if (target) for (const key of Object.keys(target)) {
+		if (replacesAscii && (key === "ascii" || key === "asciiTheme") || replacesHAnsi && (key === "hAnsi" || key === "hAnsiTheme") || replacesEastAsia && (key === "eastAsia" || key === "eastAsiaTheme") || replacesCs && (key === "cs" || key === "csTheme")) continue;
+		result[key] = target[key];
+	}
+	const pairs = [
+		["ascii", "asciiTheme"],
+		["hAnsi", "hAnsiTheme"],
+		["eastAsia", "eastAsiaTheme"],
+		["cs", "csTheme"]
+	];
+	const pairKeys = /* @__PURE__ */ new Set();
+	for (const [explicit, theme] of pairs) {
+		pairKeys.add(explicit);
+		pairKeys.add(theme);
+		if (src[explicit] === void 0 && src[theme] === void 0) continue;
+		if (src[explicit] !== void 0) result[explicit] = src[explicit];
+		if (src[theme] !== void 0) result[theme] = src[theme];
+	}
+	for (const key of Object.keys(src)) if (!pairKeys.has(key) && src[key] !== void 0) result[key] = src[key];
+	return result;
+}
+//#endregion
+export { mergeFontFamily };

package/dist/utils/fontLoader.d.ts

@@ -0,0 +1,50 @@
+//#region src/utils/fontLoader.d.ts
+/**
+ * Font Loader
+ *
+ * Manages font availability for the DOCX editor. Fonts are bundled via
+ * fontsource packages (WOFF2, no external requests). This module
+ * tracks which fonts are loaded and provides callbacks for re-rendering
+ * when fonts become available.
+ */
+/**
+ * Mapping from common Office/system fonts to bundled Croscore equivalents.
+ * The CSS @font-face aliases in font-aliases.css handle the visual mapping;
+ * this map is used for font availability checks and preloading.
+ */
+declare const FONT_MAPPING: Record<string, string>;
+/**
+ * Mark a font as loaded. For bundled fonts this is immediate;
+ * for others it checks CSS Font Loading API.
+ */
+declare function loadFont(fontFamily: string): Promise<boolean>;
+/**
+ * Load multiple fonts.
+ */
+declare function loadFonts(families: string[]): Promise<void>;
+/**
+ * Load fonts with mapping: maps Office font names to bundled equivalents
+ * and marks them as loaded.
+ */
+declare function loadFontsWithMapping(families: string[] | undefined): Promise<void>;
+declare function isFontLoaded(fontFamily: string): boolean;
+declare function isLoading(): boolean;
+declare function getLoadedFonts(): string[];
+declare function onFontsLoaded(callback: (fonts: string[]) => void): () => void;
+/**
+ * Check if a font is available using canvas measurement.
+ */
+declare function canRenderFont(fontFamily: string, fallbackFont?: string): boolean;
+/**
+ * Load a font from a raw buffer (e.g., embedded in DOCX).
+ */
+declare function loadFontFromBuffer(fontFamily: string, buffer: ArrayBuffer, options?: {
+  weight?: number | string;
+  style?: "normal" | "italic";
+}): Promise<boolean>;
+/**
+ * Preload common document fonts (no-op now since fonts are bundled).
+ */
+declare function preloadCommonFonts(): void;
+//#endregion
+export { FONT_MAPPING, canRenderFont, getLoadedFonts, isFontLoaded, isLoading, loadFont, loadFontFromBuffer, loadFonts, loadFontsWithMapping, onFontsLoaded, preloadCommonFonts };