@stll/folio-core 0.7.0 → 0.9.0

package/dist/style-sets/types.d.ts

@@ -0,0 +1,31 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/style-sets/types.d.ts
+declare const DOCUMENT_STYLE_SET_VERSION: 1;
+declare const DOCUMENT_PRESET_VERSION: 1;
+/**
+ * A content-free, portable set of DOCX formatting resources.
+ *
+ * Source document content, properties, relationships, media, comments, and
+ * revision data are deliberately excluded. Numbering and theme resources live
+ * beside styles because paragraph styles can depend on them for their meaning.
+ */
+type DocumentStyleSet = {
+  version: typeof DOCUMENT_STYLE_SET_VERSION;
+  name: string;
+  initialParagraphStyleId: string;
+  styles: document_d_exports.StyleDefinitions;
+  numbering?: document_d_exports.NumberingDefinitions;
+  theme?: document_d_exports.Theme;
+  fontTable?: document_d_exports.FontTable;
+  settings?: document_d_exports.DocumentSettings;
+};
+/** Page-level choices are separate from reusable style resources. */
+type DocumentPreset = {
+  version: typeof DOCUMENT_PRESET_VERSION;
+  name: string;
+  styleSet: DocumentStyleSet;
+  sectionProperties: document_d_exports.SectionProperties;
+};
+//#endregion
+export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocumentPreset, DocumentStyleSet };

package/dist/style-sets/types.js

@@ -0,0 +1,5 @@
+//#region src/style-sets/types.ts
+const DOCUMENT_STYLE_SET_VERSION = 1;
+const DOCUMENT_PRESET_VERSION = 1;
+//#endregion
+export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION };

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ type ConditionalFormatStyle = document_d_exports.ConditionalFormatStyle;
 type DocDefaults = document_d_exports.DocDefaults;
 type Document = document_d_exports.Document;
 type DocumentBody = document_d_exports.DocumentBody;
+type DocxConformanceClass = document_d_exports.DocxConformanceClass;
 type DocxPackage = document_d_exports.DocxPackage;
 type DrawingContent = document_d_exports.DrawingContent;
 type EmphasisMark = document_d_exports.EmphasisMark;
@@ -104,4 +105,4 @@ type ThemeFont = document_d_exports.ThemeFont;
 type ThemeFontScheme = document_d_exports.ThemeFontScheme;
 type UnderlineStyle = document_d_exports.UnderlineStyle;
 type VerticalAlign = document_d_exports.VerticalAlign;
-export type { AbstractNumbering, BlockContent, BookmarkEnd, BookmarkStart, BorderSpec, BreakContent, CellMargins, ColorValue, Column, ComplexField, ConditionalFormatStyle, DocDefaults, Document, DocumentBody, DocxPackage, DrawingContent, EmphasisMark, Endnote, EndnotePosition, EndnoteProperties, Field, FieldCharContent, FieldType, FloatingTableProperties, FontInfo, FontTable, FooterReference, Footnote, FootnotePosition, FootnoteProperties, HeaderFooter, HeaderFooterType, HeaderReference, Hyperlink, Image, ImageCrop, ImagePadding, ImagePosition, ImageSize, ImageTransform, ImageWrap, InstrTextContent, LevelSuffix, LineNumberRestart, LineSpacingRule, ListLevel, ListRendering, MediaFile, NoBreakHyphenContent, NoteNumberRestart, NoteReferenceContent, NumberFormat, NumberingDefinitions, NumberingInstance, PageOrientation, Paragraph, ParagraphAlignment, ParagraphContent, ParagraphFormatting, Relationship, RelationshipMap, RelationshipType, Run, RunContent, Section, SectionProperties, SectionStart, ShadingProperties, Shape, ShapeContent, ShapeFill, ShapeOutline, ShapeTextBody, ShapeType, SimpleField, SoftHyphenContent, Style, StyleDefinitions, StyleType, SymbolContent, TabContent, TabLeader, TabStop, TabStopAlignment, Table, TableBorders, TableCell, TableCellFormatting, TableFormatting, TableLook, TableMeasurement, TableRow, TableRowFormatting, TableWidthType, TextBox, TextContent, TextEffect, TextFormatting, Theme, ThemeColorScheme, ThemeColorSlot, ThemeFont, ThemeFontScheme, UnderlineStyle, VerticalAlign };
+export type { AbstractNumbering, BlockContent, BookmarkEnd, BookmarkStart, BorderSpec, BreakContent, CellMargins, ColorValue, Column, ComplexField, ConditionalFormatStyle, DocDefaults, Document, DocumentBody, DocxConformanceClass, DocxPackage, DrawingContent, EmphasisMark, Endnote, EndnotePosition, EndnoteProperties, Field, FieldCharContent, FieldType, FloatingTableProperties, FontInfo, FontTable, FooterReference, Footnote, FootnotePosition, FootnoteProperties, HeaderFooter, HeaderFooterType, HeaderReference, Hyperlink, Image, ImageCrop, ImagePadding, ImagePosition, ImageSize, ImageTransform, ImageWrap, InstrTextContent, LevelSuffix, LineNumberRestart, LineSpacingRule, ListLevel, ListRendering, MediaFile, NoBreakHyphenContent, NoteNumberRestart, NoteReferenceContent, NumberFormat, NumberingDefinitions, NumberingInstance, PageOrientation, Paragraph, ParagraphAlignment, ParagraphContent, ParagraphFormatting, Relationship, RelationshipMap, RelationshipType, Run, RunContent, Section, SectionProperties, SectionStart, ShadingProperties, Shape, ShapeContent, ShapeFill, ShapeOutline, ShapeTextBody, ShapeType, SimpleField, SoftHyphenContent, Style, StyleDefinitions, StyleType, SymbolContent, TabContent, TabLeader, TabStop, TabStopAlignment, Table, TableBorders, TableCell, TableCellFormatting, TableFormatting, TableLook, TableMeasurement, TableRow, TableRowFormatting, TableWidthType, TextBox, TextContent, TextEffect, TextFormatting, Theme, ThemeColorScheme, ThemeColorSlot, ThemeFont, ThemeFontScheme, UnderlineStyle, VerticalAlign };

package/dist/utils/createDocument.d.ts

@@ -1,10 +1,11 @@
 import { document_d_exports } from "../types/document.js";
+import { DocumentPreset, DocumentStyleSet } from "../style-sets/types.js";
 
 //#region src/utils/createDocument.d.ts
 /**
  * Options for creating an empty document
  */
-type CreateEmptyDocumentOptions = {
+type CreateEmptyDocumentBaseOptions = {
   /** 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) */
@@ -14,6 +15,15 @@ type CreateEmptyDocumentOptions = {
   marginRight?: number; /** Initial text content (default: empty string) */
   initialText?: string;
 };
+type CreateEmptyDocumentStyleOptions = {
+  /** Reusable formatting resources for the new document. */styleSet?: DocumentStyleSet;
+  preset?: never;
+} | {
+  /** Style resources plus page-level defaults for the new document. */preset: DocumentPreset;
+  styleSet?: never;
+};
+type CreateEmptyDocumentOptions = CreateEmptyDocumentBaseOptions & CreateEmptyDocumentStyleOptions;
+type CreateDocumentWithTextOptions = Omit<CreateEmptyDocumentBaseOptions, "initialText"> & CreateEmptyDocumentStyleOptions;
 /**
  * Create an empty document with a single paragraph
  *
@@ -45,6 +55,6 @@ declare function createEmptyDocument(options?: CreateEmptyDocumentOptions): docu
  * @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;
+declare function createDocumentWithText(text: string, options?: CreateDocumentWithTextOptions): document_d_exports.Document;
 //#endregion
 export { CreateEmptyDocumentOptions, createDocumentWithText, createEmptyDocument };

package/dist/utils/createDocument.js

@@ -1,5 +1,13 @@
+import "../style-sets/types.js";
+import { panic } from "better-result";
+import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/utils/createDocument.ts
 /**
+* Create Document Utility
+*
+* Provides functions to create new documents programmatically.
+*/
+/**
 * Get default paragraph styles (matching Google Docs defaults)
 *
 * Font sizes are in half-points (e.g., 22 = 11pt, 40 = 20pt)
@@ -195,7 +203,10 @@ function getDefaultSectionProperties() {
 * ```
 */
 function createEmptyDocument(options = {}) {
-	const sectionProps = getDefaultSectionProperties();
+	const styleSet = options.preset?.styleSet ?? options.styleSet;
+	validateDocumentStyleSet(styleSet);
+	if (options.preset?.version !== void 0 && options.preset.version !== 1) return panic(`Unsupported document preset version: ${options.preset.version}`);
+	const sectionProps = structuredClone(options.preset?.sectionProperties ?? 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;
@@ -203,48 +214,56 @@ function createEmptyDocument(options = {}) {
 	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 || ""
+	const initialText = options.initialText ?? "";
+	const documentBody = {
+		content: [{
+			type: "paragraph",
+			content: [{
+				type: "run",
+				content: initialText ? [{
+					type: "text",
+					text: initialText
+				}] : [],
+				formatting: {}
+			}],
+			formatting: { styleId: styleSet?.initialParagraphStyleId ?? "Normal" }
+		}],
+		finalSectionProperties: sectionProps
 	};
-	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
+	const defaultStyleDefinitions = {
+		docDefaults: {
+			rPr: {
+				fontSize: 22,
+				fontFamily: {
+					ascii: "Arial",
+					hAnsi: "Arial"
+				}
 			},
-			styles: {
-				docDefaults: {
-					rPr: {
-						fontSize: 22,
-						fontFamily: {
-							ascii: "Arial",
-							hAnsi: "Arial"
-						}
-					},
-					pPr: { lineSpacing: 276 }
-				},
-				styles: getDefaultStyles()
-			}
+			pPr: { lineSpacing: 276 }
 		},
+		styles: getDefaultStyles()
+	};
+	const docxPackage = {
+		conformanceClass: DOCX_CONFORMANCE_CLASSES.TRANSITIONAL,
+		document: documentBody,
+		styles: structuredClone(styleSet?.styles ?? defaultStyleDefinitions)
+	};
+	if (styleSet?.numbering) docxPackage.numbering = structuredClone(styleSet.numbering);
+	if (styleSet?.theme) docxPackage.theme = structuredClone(styleSet.theme);
+	if (styleSet?.fontTable) docxPackage.fontTable = structuredClone(styleSet.fontTable);
+	if (styleSet?.settings) docxPackage.settings = structuredClone(styleSet.settings);
+	return {
+		package: docxPackage,
 		templateVariables: [],
 		warnings: []
 	};
 }
+const validateDocumentStyleSet = (styleSet) => {
+	if (!styleSet) return;
+	if (styleSet.version !== 1) return panic(`Unsupported document style set version: ${styleSet.version}`);
+	if (styleSet.name.trim().length === 0) return panic("Document style set name cannot be empty");
+	if (styleSet.styles.styles.find((style) => style.styleId === styleSet.initialParagraphStyleId)?.type !== "paragraph") return panic(`Initial paragraph style "${styleSet.initialParagraphStyleId}" is missing from style set "${styleSet.name}"`);
+};
 /**
 * Create a document with a single paragraph containing the given text
 *

package/dist/utils/fontResolver.js

@@ -59,9 +59,9 @@ const APTOS_MEASURED_LINE_HEIGHT = {
 * font's `FontLineHeight`, never hand-written. For "hhea" entries the raw
 * `hheaAscent`/`hheaDescent`/`hheaLineGap`/`unitsPerEm` fields below are read
 * directly from the real font files' `hhea` table; the ratio is whatever
-* falls out of the formula in `singleLineRatioOf`. "legacy" entries (e.g.
-* garamond, lucida sans, lucida console) are unverified hand-transcribed
-* ratios carried over unchanged, pending measurement.
+* falls out of the formula in `singleLineRatioOf`. The remaining "legacy"
+* entry (lucida sans) is an unverified hand-transcribed ratio carried over
+* unchanged, pending measurement.
 */
 const FONT_MAPPINGS = {
 	aptos: {
@@ -355,9 +355,9 @@ const FONT_MAPPINGS = {
 			"serif"
 		],
 		singleLineRatio: singleLineRatioOf({
-			source: "legacy",
-			ratio: 1.068,
-			note: "Unverified hand-transcribed ratio; not yet measured against real Word output."
+			source: "measured",
+			ratio: 1.1273,
+			note: "Measured at 11pt against a 12.4pt reference-layout line pitch."
 		})
 	},
 	"century gothic": {

package/dist/utils/formatToStyle.js

@@ -1,6 +1,6 @@
 import { AUTO_PARAGRAPH_SPACING_PX, eighthsToPixels, formatPx, halfPointsToPixels, halfPointsToPoints, twipsToPixels } from "./units.js";
-import { resolveFontFamily, resolveThemeFont } from "./fontResolver.js";
 import { resolveColor, resolveHighlightToCss, resolveShadingColor } from "./colorResolver.js";
+import { resolveFontFamily, resolveThemeFont } from "./fontResolver.js";
 //#region src/utils/formatToStyle.ts
 /**
 * Convert TextFormatting to CSS properties for a run/span

package/dist/utils/hexId.d.ts

@@ -3,6 +3,8 @@
  * Lifted from
  * https://github.com/eigenpal/docx-editor/blob/main/packages/core/src/utils/hexId.ts
  * (Apache-2.0). Keep the bound and the comments in sync upstream.
+ * folio divergence: `00000000` is excluded from both generators — Word
+ * treats a zero `w14:paraId` as unassigned, so it must never be minted.
  */
 /**
  * Strictest OOXML `ST_LongHexNumber` upper bound (exclusive) across the
@@ -17,7 +19,8 @@ declare const MAX_HEX_ID_EXCLUSIVE = 2147483647;
  * Random 8-char uppercase hex id, matching Microsoft's `w14:paraId`
  * extension format (also reused for comment `paraId` / `durableId`).
  *
- * Range is `[0, MAX_HEX_ID_EXCLUSIVE)` = `[0, 0x7FFFFFFE]`.
+ * Range is `[1, MAX_HEX_ID_EXCLUSIVE)` = `[1, 0x7FFFFFFE]` — zero is
+ * excluded because Word reads `w14:paraId="00000000"` as "no id".
  *
  * Uses `Math.random()` rather than `crypto.randomUUID()` so the
  * generator works in non-secure contexts (file://, web workers).
@@ -27,6 +30,10 @@ declare const generateHexId: () => string;
  * Deterministic 8-char uppercase hex id (FNV-1a over `seed`), `< 0x7FFFFFFF`.
  * Re-deriving from the same seed mints the same id, so content/position-derived
  * ids (block paraIds, comment thread keys) are stable across saves.
+ *
+ * A hash of exactly zero is remapped to `1`: `00000000` is Word's "no id"
+ * sentinel, and remapping only that one (already invalid) output keeps every
+ * previously shipped deterministic id unchanged.
  */
 declare const deterministicHexId: (seed: string) => string;
 //#endregion

package/dist/utils/hexId.js

@@ -3,6 +3,8 @@
 * Lifted from
 * https://github.com/eigenpal/docx-editor/blob/main/packages/core/src/utils/hexId.ts
 * (Apache-2.0). Keep the bound and the comments in sync upstream.
+* folio divergence: `00000000` is excluded from both generators — Word
+* treats a zero `w14:paraId` as unassigned, so it must never be minted.
 */
 /**
 * Strictest OOXML `ST_LongHexNumber` upper bound (exclusive) across the
@@ -17,21 +19,27 @@ const MAX_HEX_ID_EXCLUSIVE = 2147483647;
 * Random 8-char uppercase hex id, matching Microsoft's `w14:paraId`
 * extension format (also reused for comment `paraId` / `durableId`).
 *
-* Range is `[0, MAX_HEX_ID_EXCLUSIVE)` = `[0, 0x7FFFFFFE]`.
+* Range is `[1, MAX_HEX_ID_EXCLUSIVE)` = `[1, 0x7FFFFFFE]` — zero is
+* excluded because Word reads `w14:paraId="00000000"` as "no id".
 *
 * Uses `Math.random()` rather than `crypto.randomUUID()` so the
 * generator works in non-secure contexts (file://, web workers).
 */
-const generateHexId = () => Math.floor(Math.random() * MAX_HEX_ID_EXCLUSIVE).toString(16).toUpperCase().padStart(8, "0");
+const generateHexId = () => (Math.floor(Math.random() * (MAX_HEX_ID_EXCLUSIVE - 1)) + 1).toString(16).toUpperCase().padStart(8, "0");
 /**
 * Deterministic 8-char uppercase hex id (FNV-1a over `seed`), `< 0x7FFFFFFF`.
 * Re-deriving from the same seed mints the same id, so content/position-derived
 * ids (block paraIds, comment thread keys) are stable across saves.
+*
+* A hash of exactly zero is remapped to `1`: `00000000` is Word's "no id"
+* sentinel, and remapping only that one (already invalid) output keeps every
+* previously shipped deterministic id unchanged.
 */
 const deterministicHexId = (seed) => {
 	let hash = 2166136261;
 	for (const character of seed) hash = Math.imul(hash ^ (character.codePointAt(0) ?? 0), 16777619) >>> 0;
-	return (hash % MAX_HEX_ID_EXCLUSIVE).toString(16).toUpperCase().padStart(8, "0");
+	const value = hash % MAX_HEX_ID_EXCLUSIVE;
+	return (value === 0 ? 1 : value).toString(16).toUpperCase().padStart(8, "0");
 };
 //#endregion
 export { MAX_HEX_ID_EXCLUSIVE, deterministicHexId, generateHexId };

package/dist/utils/paragraphFormattingMerge.d.ts

@@ -1,14 +1,25 @@
 import { document_d_exports } from "../types/document.js";
 
 //#region src/utils/paragraphFormattingMerge.d.ts
+/**
+ * Merge custom tab stops across OOXML paragraph-property layers.
+ *
+ * Tabs cascade by position rather than replacing the inherited collection:
+ * a higher-priority stop supersedes the stop at the same position, while a
+ * `clear` stop removes that inherited position during layout. Keeping the
+ * clear entry also lets the tab calculator suppress an automatic stop at the
+ * same position.
+ */
+declare function mergeParagraphTabStops(inherited: document_d_exports.TabStop[] | undefined, direct: document_d_exports.TabStop[]): document_d_exports.TabStop[];
+declare function mergeParagraphTabStops(inherited: document_d_exports.TabStop[] | undefined, direct: document_d_exports.TabStop[] | undefined): document_d_exports.TabStop[] | undefined;
 /**
  * Merge paragraph properties for OOXML style cascade resolution.
  *
  * The source is the higher-priority layer. Most `w:pPr` properties replace an
  * inherited value when present; nested child containers merge by child field;
- * tabs replace as a complete ordered collection; paragraph mark `w:rPr` uses
- * the run-formatting merge rules.
+ * tabs merge by position; paragraph mark `w:rPr` uses the run-formatting
+ * merge rules.
  */
 declare function mergeParagraphFormatting(target: document_d_exports.ParagraphFormatting | undefined, source: document_d_exports.ParagraphFormatting | undefined): document_d_exports.ParagraphFormatting | undefined;
 //#endregion
-export { mergeParagraphFormatting };
+export { mergeParagraphFormatting, mergeParagraphTabStops };

package/dist/utils/paragraphFormattingMerge.js

@@ -3,6 +3,8 @@ import { mergeTextFormatting } from "./textFormattingMerge.js";
 const PARAGRAPH_REPLACE_KEYS = [
 	"alignment",
 	"bidi",
+	"kinsoku",
+	"overflowPunctuation",
 	"spaceBefore",
 	"spaceAfter",
 	"lineSpacing",
@@ -30,13 +32,20 @@ const copyDefinedParagraphProperty = (target, source, key) => {
 	const value = source[key];
 	if (value !== void 0) target[key] = value;
 };
+function mergeParagraphTabStops(inherited, direct) {
+	if (direct === void 0) return inherited === void 0 ? void 0 : [...inherited];
+	const stopsByPosition = /* @__PURE__ */ new Map();
+	for (const stop of inherited ?? []) stopsByPosition.set(stop.position, stop);
+	for (const stop of direct) stopsByPosition.set(stop.position, stop);
+	return [...stopsByPosition.values()].toSorted((a, b) => a.position - b.position);
+}
 /**
 * Merge paragraph properties for OOXML style cascade resolution.
 *
 * The source is the higher-priority layer. Most `w:pPr` properties replace an
 * inherited value when present; nested child containers merge by child field;
-* tabs replace as a complete ordered collection; paragraph mark `w:rPr` uses
-* the run-formatting merge rules.
+* tabs merge by position; paragraph mark `w:rPr` uses the run-formatting
+* merge rules.
 */
 function mergeParagraphFormatting(target, source) {
 	if (!source) return target;
@@ -47,6 +56,7 @@ function mergeParagraphFormatting(target, source) {
 	}
 	const result = { ...target };
 	for (const key of PARAGRAPH_REPLACE_KEYS) copyDefinedParagraphProperty(result, source, key);
+	if (source.indentFirstLine !== void 0) result.hangingIndent = source.hangingIndent === true;
 	const mergedRunProperties = mergeTextFormatting(result.runProperties, source.runProperties);
 	if (mergedRunProperties) result.runProperties = mergedRunProperties;
 	if (source.borders !== void 0) result.borders = {
@@ -61,8 +71,8 @@ function mergeParagraphFormatting(target, source) {
 		...result.frame,
 		...source.frame
 	};
-	if (source.tabs !== void 0) result.tabs = [...source.tabs];
+	if (source.tabs !== void 0) result.tabs = mergeParagraphTabStops(result.tabs, source.tabs);
 	return result;
 }
 //#endregion
-export { mergeParagraphFormatting };
+export { mergeParagraphFormatting, mergeParagraphTabStops };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -113,6 +113,7 @@
     "better-result": "2.9.2",
     "csstype": "^3.1.3",
     "fast-xml-parser": "^5.9.3",
+    "hyphen": "1.14.1",
     "jszip": "3.10.1",
     "marked": "^18.0.5",
     "prosemirror-commands": "^1.7.1",
@@ -130,6 +131,9 @@
     "y-prosemirror": "^1.3.7",
     "yjs": "^13.6.31"
   },
+  "devDependencies": {
+    "@types/hyphen": "1.14.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [