@stll/folio-core 0.43.0 → 0.45.0

package/dist/prosemirror/schema/nodes.d.ts

@@ -27,9 +27,11 @@ type BookmarkBoundaryAttrs = {
   name: string;
   colFirst?: number;
   colLast?: number;
+  displacedByCustomXml?: document_d_exports.DisplacedByCustomXml;
 } | {
   type: "end";
   id: number;
+  displacedByCustomXml?: document_d_exports.DisplacedByCustomXml;
 };
 /**
  * Paragraph node attributes - maps to ParagraphFormatting
@@ -189,6 +191,19 @@ type ParagraphAttrs = {
   /** Original inline paragraph formatting from DOCX (pre-style-resolution).
    *  Used by fromProseDoc for lossless round-trip serialization. */
   _originalFormatting?: document_d_exports.ParagraphFormatting;
+  /**
+   * The `w:pPr` the style cascade resolves to for this paragraph: document
+   * defaults, the enclosing table style, then the `w:pStyle` chain. PM-only;
+   * never serialized.
+   *
+   * The formatting attrs above hold the EFFECTIVE value, because that is what
+   * the editor renders with. A save must write only what the paragraph states
+   * itself, so it needs this companion to tell an inherited value from an
+   * authored one — writing an inherited value back as direct `w:pPr` outranks
+   * the style it came from, and a later edit to that style stops reaching the
+   * paragraph. `TableCellAttrs._resolvedBorders` is the same device.
+   */
+  _resolvedFormatting?: document_d_exports.ParagraphFormatting;
   /** Import-effective spacing baseline for HTML auto-spacing detection.
    *  PM-only; never serialized back into DOCX formatting. */
   _autospacingBase?: {
@@ -249,6 +264,25 @@ type ImagePositionAttrs = {
     align?: NonNullable<document_d_exports.ImagePosition["vertical"]["alignment"]>;
   };
 };
+/**
+ * The EMUs a drawing's pixel attributes were projected from, keyed by the
+ * pixel attribute each one became.
+ *
+ * EMU → px → EMU does not land back on the same number: a size rounds to whole
+ * pixels, a stroke or an inset to two. Without the authored value beside the
+ * projected one, opening a document and saving it again moved every drawing
+ * off the number its author wrote. `fromProseDoc` writes the authored EMU back
+ * while the pixel attribute still projects from it, and converts the pixel
+ * attribute once an editor command has moved it.
+ *
+ * A key carries `undefined` when the source authored no such value, so an
+ * absent value stays absent rather than acquiring one the document never had.
+ */
+type AuthoredEmuAttrs<Key extends string> = { readonly [K in Key]?: number | undefined; };
+/** The pixel attributes a drawing's `wp:wrap*` insets are projected into. */
+type WrapDistanceAttr = "distTop" | "distBottom" | "distLeft" | "distRight";
+/** The pixel attributes a text box's internal margins are projected into. */
+type TextBoxMarginAttr = "marginTop" | "marginBottom" | "marginLeft" | "marginRight";
 /**
  * Image node attributes
  */
@@ -305,6 +339,16 @@ type ImageAttrs = {
   position?: ImagePositionAttrs;
   /** Use the containing table cell as the anchor's positioning scope (the OOXML default). */
   layoutInCell?: boolean;
+  /**
+   * The image carries no information, so assistive technology skips it
+   * (`wp:docPr`'s decorative extension). Not {@link hidden}: a decorative
+   * image is still displayed.
+   */
+  decorative?: boolean;
+  /** `wp:docPr @hidden`: the drawing is not displayed. */
+  hidden?: boolean;
+  /** `wp:docPr` extensions folio does not model, carried through verbatim. */
+  docPrExtensions?: string[];
   /**
    * Authored `a:graphicFrameLocks`. Carried through the editor so a resize,
    * which forces the serializer to regenerate DrawingML, cannot silently
@@ -313,6 +357,8 @@ type ImageAttrs = {
   frameLocks?: document_d_exports.ImageFrameLocks;
   /** Border width in pixels */
   borderWidth?: number;
+  /** The EMUs behind `width`, `height`, `borderWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "borderWidth" | WrapDistanceAttr>;
   /** Border color as CSS color string */
   borderColor?: string;
   /** Border style (CSS border-style value) */
@@ -334,6 +380,14 @@ type ImageAttrs = {
   _docxRawImageFingerprint?: string;
   /** Embedded-object previews use their authored box as the exact line height. */
   _docxObjectPreview?: boolean;
+  /**
+   * The `w:rPr` of the run this atom came from. Inline atoms do not carry the
+   * run's formatting marks (see `withRunBoundaryMarks`), so without this the
+   * run properties of an embedded object, picture or shape are lost on save
+   * (`content[].content[].formatting: object became absent` in the corpus
+   * census).
+   */
+  _docxRunFormatting?: document_d_exports.TextFormatting;
 };
 /**
  * Field node attributes
@@ -445,6 +499,12 @@ type ShapeAttrs = {
   geometryAdjustments?: string;
   /** Unique identifier */
   shapeId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  shapeName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Width in pixels */
   width?: number;
   /** Height in pixels */
@@ -471,6 +531,8 @@ type ShapeAttrs = {
   outlineStyle?: OutlineStyleAttr;
   /** Line cap */
   outlineCap?: NonNullable<document_d_exports.ShapeOutline["cap"]>;
+  /** Line join */
+  outlineJoin?: NonNullable<document_d_exports.ShapeOutline["join"]>;
   /** Head arrow/end marker */
   outlineHeadEnd?: NonNullable<document_d_exports.ShapeOutline["headEnd"]>;
   /** Tail arrow/end marker */
@@ -507,6 +569,16 @@ type ShapeAttrs = {
   glowColor?: string;
   /** Glow radius in pixels */
   glowRadius?: number;
+  /**
+   * The `w:rPr` of the run this atom came from. Inline atoms do not carry the
+   * run's formatting marks (see `withRunBoundaryMarks`), so without this the
+   * run properties of an embedded object, picture or shape are lost on save
+   * (`content[].content[].formatting: object became absent` in the corpus
+   * census).
+   */
+  _docxRunFormatting?: document_d_exports.TextFormatting;
+  /** The EMUs behind `width`, `height`, `outlineWidth` and the wrap insets. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr>;
 };
 /**
  * Text box node attributes
@@ -520,6 +592,8 @@ type TextBoxAttrs = {
   width?: number;
   /** Height in pixels */
   height?: number;
+  /** The EMUs behind the size, `outlineWidth`, the wrap insets and the margins. */
+  _docxAuthoredEmu?: AuthoredEmuAttrs<"width" | "height" | "outlineWidth" | WrapDistanceAttr | TextBoxMarginAttr>;
   /** Text fitting behavior */
   autoFit?: document_d_exports.ShapeTextBody["autoFit"];
   /** Authored DrawingML WordArt metadata. */
@@ -528,6 +602,12 @@ type TextBoxAttrs = {
   textWrap?: document_d_exports.ShapeTextBody["textWrap"];
   /** Unique identifier */
   textBoxId?: string;
+  /** Authored non-visual drawing name (`wp:docPr@name` / `wps:cNvPr@name`) */
+  textBoxName?: string;
+  /** Alt text for accessibility (`wp:docPr@descr`) */
+  alt?: string;
+  /** Authored non-visual drawing title (`wp:docPr@title`) */
+  title?: string;
   /** Fill color as CSS color */
   fillColor?: string;
   /** Outline width in pixels */
@@ -805,4 +885,4 @@ type TableCellAttrs = {
   _docxVMergeContinuationCells?: unknown;
 };
 //#endregion
-export { BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };
+export { AuthoredEmuAttrs, BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };

package/dist/prosemirror/styles/resolvedStyleAttrs.js

@@ -4,6 +4,7 @@ import { tableOfContentsStyleLevel } from "../../utils/tableOfContentsStyle.js";
 import { setAutospacingBaseValue } from "../autospacingBase.js";
 import { CLEARED_LIST_RENDERING_ATTRS } from "../listMarker.js";
 import { listRenderingAttrPatch } from "../listRenderingAttrs.js";
+import { styleResolvedParagraphFormatting } from "../paragraphFormattingProvenance.js";
 //#region src/prosemirror/styles/resolvedStyleAttrs.ts
 /**
 * Shared helper for projecting a resolved paragraph style onto ProseMirror
@@ -45,6 +46,7 @@ function paragraphAttrsFromResolvedStyle(resolved, identity) {
 		outlineLevel: ppr?.outlineLevel ?? null,
 		borders: ppr?.borders ?? null,
 		defaultTextFormatting: hasRunFormatting ? runFormatting : null,
+		_resolvedFormatting: styleResolvedParagraphFormatting(ppr),
 		_autospacingBase: autospacingBaseFromResolvedParagraphFormatting(ppr),
 		_tableOfContentsLevel: tableOfContentsStyleLevel(identity) ?? null
 	};

package/dist/prosemirror/styles/styleResolver.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
+import { BuiltInStyleIndex } from "../../docx/builtInStyles.js";
 //#region src/prosemirror/styles/styleResolver.d.ts
 /**
  * Resolved style properties ready for rendering
@@ -27,6 +28,7 @@ type TableCellParagraphSpacingOverlay = Pick<document_d_exports.ParagraphFormatt
  */
 declare class StyleResolver {
   private readonly stylesById;
+  private builtInStyleIndex;
   private readonly docDefaults;
   private readonly defaultParagraphStyle;
   private readonly defaultCharacterStyle;
@@ -36,6 +38,13 @@ declare class StyleResolver {
    * Get a style by ID
    */
   getStyle(styleId: string): document_d_exports.Style | undefined;
+  /**
+   * This document's styles indexed by the built-in they are, so a consumer can
+   * ask whether a paragraph is a heading without matching an English style id.
+   * Built on first use and kept: the resolver outlives a single query, and the
+   * outline sidebar rebuilds its heading list on every transaction.
+   */
+  get builtInStyles(): BuiltInStyleIndex;
   /**
    * Get all available paragraph styles (for toolbar dropdown)
    */

package/dist/prosemirror/styles/styleResolver.js

@@ -1,3 +1,4 @@
+import { createBuiltInStyleIndex } from "../../docx/builtInStyles.js";
 import { BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING, resolveDefaultParagraphStyle } from "../../docx/defaultParagraphStyle.js";
 import { mergeParagraphFormatting } from "../../utils/paragraphFormattingMerge.js";
 import { cascadeStyleTextFormatting } from "./styleToggleCascade.js";
@@ -27,6 +28,7 @@ const BUILTIN_NORMAL_STYLE = {
 */
 var StyleResolver = class {
 	stylesById;
+	builtInStyleIndex;
 	docDefaults;
 	defaultParagraphStyle;
 	defaultCharacterStyle;
@@ -48,6 +50,16 @@ var StyleResolver = class {
 		return this.stylesById.get(styleId);
 	}
 	/**
+	* This document's styles indexed by the built-in they are, so a consumer can
+	* ask whether a paragraph is a heading without matching an English style id.
+	* Built on first use and kept: the resolver outlives a single query, and the
+	* outline sidebar rebuilds its heading list on every transaction.
+	*/
+	get builtInStyles() {
+		this.builtInStyleIndex ??= createBuiltInStyleIndex(this.stylesById.values(), this.docDefaults);
+		return this.builtInStyleIndex;
+	}
+	/**
 	* Get all available paragraph styles (for toolbar dropdown)
 	*/
 	getParagraphStyles() {

package/dist/style-engine/styleEngine.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { BuiltInStyleIndex } from "../docx/builtInStyles.js";
 import { ResolvedParagraphStyle, TableCellParagraphSpacingOverlay } from "../prosemirror/styles/styleResolver.js";
 //#region src/style-engine/styleEngine.d.ts
 /** Engine construction options. */
@@ -44,6 +45,8 @@ type StyleEngine = {
   getParagraphStyles: () => document_d_exports.Style[];
   /** All visible table styles, sorted for the table-style gallery. */
   getTableStyles: () => document_d_exports.Style[];
+  /** The document's styles indexed by the built-in they are — see {@link StyleResolver.builtInStyles}. */
+  builtInStyles: BuiltInStyleIndex;
   /**
    * Resolve the full paragraph cascade for a given styleId.
    * Returned object is cached and must not be mutated.

package/dist/style-engine/styleEngine.js

@@ -62,6 +62,9 @@ function createStyleEngine(styleDefinitions, options) {
 		getDefaultTableStyle: () => resolver.getDefaultTableStyle(),
 		getParagraphStyles: () => resolver.getParagraphStyles(),
 		getTableStyles: () => resolver.getTableStyles(),
+		get builtInStyles() {
+			return resolver.builtInStyles;
+		},
 		resolveParagraphStyle: (styleId) => memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyle(styleId)),
 		resolveParagraphStyleInTable: (styleId, tableParagraphOverlay) => tableParagraphOverlay === void 0 ? memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyleInTable(styleId, void 0)) : memoizeInTable(styleId, tableParagraphOverlay),
 		resolveRunStyle: (styleId) => memoize(runCache, cacheKey(styleId), () => resolver.resolveRunStyle(styleId)),

package/dist/style-sets/extract.js

@@ -1,4 +1,4 @@
-import { BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID, BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, resolveDefaultParagraphStyle } from "../docx/defaultParagraphStyle.js";
+import { mintDefaultParagraphStyle, resolveDefaultParagraphStyle } from "../docx/defaultParagraphStyle.js";
 import { getCachedNumberingMap } from "../docx/numberingParser.js";
 import { isNumberingReference } from "../docx/numberingReference.js";
 import { normalizeStyleNumberingReferences } from "../docx/numberingReferenceNormalization.js";
@@ -83,28 +83,6 @@ const ensureInitialParagraphStyle = ({ styles, requested, hasDocDefaults }) => {
 	styles.push(minted);
 	return minted.styleId;
 };
-/**
-* The default paragraph style a set needs when its source declared none.
-*
-* The id only has to be free, because the set is what defines it. The
-* formatting has to be the built-in template's whenever the source had no
-* `w:docDefaults`, because that is what the source itself rendered as: a
-* consumer applies its built-in Normal only where no default paragraph style
-* exists, and this minted style is one. Where the source did declare
-* `w:docDefaults`, the set carries them and they remain authoritative, so the
-* minted style states nothing.
-*/
-const mintDefaultParagraphStyle = ({ takenStyleIds, hasDocDefaults }) => {
-	let styleId = BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID;
-	for (let suffix = 1; takenStyleIds.has(styleId); suffix += 1) styleId = `${BUILT_IN_DEFAULT_PARAGRAPH_STYLE_ID}${suffix}`;
-	return {
-		styleId,
-		type: "paragraph",
-		name: BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME,
-		default: true,
-		...hasDocDefaults ? {} : { pPr: { ...BUILT_IN_DEFAULT_PARAGRAPH_FORMATTING } }
-	};
-};
 const collectStyleDependencyClosure = (stylesById, requestedStyleIds) => {
 	const selected = /* @__PURE__ */ new Set();
 	const pending = [...requestedStyleIds];

package/dist/style-sets/stellaStyle.js

@@ -1,3 +1,4 @@
+import { BUILT_IN_STYLE_NAME, builtInHeadingStyleName, builtInTableOfContentsStyleName } from "../docx/builtInStyles.js";
 import "./types.js";
 //#region src/style-sets/stellaStyle.ts
 const CLAUSE_NUMBERING_ID = 1;
@@ -43,7 +44,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Normal",
 				type: "paragraph",
-				name: "Normal",
+				name: BUILT_IN_STYLE_NAME.normal,
 				default: true,
 				qFormat: true,
 				uiPriority: 0,
@@ -64,7 +65,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "DefaultParagraphFont",
 				type: "character",
-				name: "Default Paragraph Font",
+				name: BUILT_IN_STYLE_NAME.defaultParagraphFont,
 				default: true,
 				semiHidden: true,
 				unhideWhenUsed: true
@@ -72,7 +73,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "BodyText",
 				type: "paragraph",
-				name: "Body Text",
+				name: BUILT_IN_STYLE_NAME.bodyText,
 				basedOn: "Normal",
 				qFormat: true,
 				uiPriority: 1
@@ -80,7 +81,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Title",
 				type: "paragraph",
-				name: "Title",
+				name: BUILT_IN_STYLE_NAME.title,
 				basedOn: "BodyText",
 				next: "BodyText",
 				qFormat: true,
@@ -109,7 +110,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Subtitle",
 				type: "paragraph",
-				name: "Subtitle",
+				name: BUILT_IN_STYLE_NAME.subtitle,
 				basedOn: "Title",
 				next: "BodyText",
 				qFormat: true,
@@ -131,7 +132,10 @@ const createStellaStyleSet = () => ({
 				next: "Recital",
 				qFormat: true,
 				uiPriority: 5,
-				pPr: { keepNext: true },
+				pPr: {
+					keepNext: true,
+					outlineLevel: 0
+				},
 				rPr: { bold: true }
 			},
 			{
@@ -179,7 +183,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "ListParagraph",
 				type: "paragraph",
-				name: "List Paragraph",
+				name: BUILT_IN_STYLE_NAME.listParagraph,
 				basedOn: "BodyText",
 				qFormat: true,
 				uiPriority: 31,
@@ -208,13 +212,14 @@ const createStellaStyleSet = () => ({
 				pPr: {
 					pageBreakBefore: true,
 					keepNext: true,
-					spaceAfter: 240
+					spaceAfter: 240,
+					outlineLevel: 0
 				}
 			},
 			{
 				styleId: "FootnoteText",
 				type: "paragraph",
-				name: "Footnote Text",
+				name: BUILT_IN_STYLE_NAME.footnoteText,
 				basedOn: "Normal",
 				link: "FootnoteTextChar",
 				semiHidden: true,
@@ -229,7 +234,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "FootnoteTextChar",
 				type: "character",
-				name: "Footnote Text Char",
+				name: BUILT_IN_STYLE_NAME.footnoteTextChar,
 				basedOn: "DefaultParagraphFont",
 				link: "FootnoteText",
 				semiHidden: true,
@@ -243,7 +248,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "FootnoteReference",
 				type: "character",
-				name: "Footnote Reference",
+				name: BUILT_IN_STYLE_NAME.footnoteReference,
 				basedOn: "DefaultParagraphFont",
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -253,7 +258,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteText",
 				type: "paragraph",
-				name: "Endnote Text",
+				name: BUILT_IN_STYLE_NAME.endnoteText,
 				basedOn: "Normal",
 				link: "EndnoteTextChar",
 				semiHidden: true,
@@ -268,7 +273,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteTextChar",
 				type: "character",
-				name: "Endnote Text Char",
+				name: BUILT_IN_STYLE_NAME.endnoteTextChar,
 				basedOn: "DefaultParagraphFont",
 				link: "EndnoteText",
 				semiHidden: true,
@@ -282,7 +287,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "EndnoteReference",
 				type: "character",
-				name: "Endnote Reference",
+				name: BUILT_IN_STYLE_NAME.endnoteReference,
 				basedOn: "DefaultParagraphFont",
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -292,7 +297,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Footer",
 				type: "paragraph",
-				name: "Footer",
+				name: BUILT_IN_STYLE_NAME.footer,
 				basedOn: "Normal",
 				pPr: {
 					alignment: "right",
@@ -307,7 +312,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "Hyperlink",
 				type: "character",
-				name: "Hyperlink",
+				name: BUILT_IN_STYLE_NAME.hyperlink,
 				basedOn: "DefaultParagraphFont",
 				unhideWhenUsed: true,
 				uiPriority: 99,
@@ -319,7 +324,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "TableNormal",
 				type: "table",
-				name: "Normal Table",
+				name: BUILT_IN_STYLE_NAME.normalTable,
 				default: true,
 				semiHidden: true,
 				unhideWhenUsed: true,
@@ -328,7 +333,7 @@ const createStellaStyleSet = () => ({
 			{
 				styleId: "TableGrid",
 				type: "table",
-				name: "Table Grid",
+				name: BUILT_IN_STYLE_NAME.tableGrid,
 				basedOn: "TableNormal",
 				qFormat: true,
 				uiPriority: 59,
@@ -399,37 +404,37 @@ const createHeadingStyles = () => {
 	return [
 		{
 			styleId: "Heading1",
-			name: "heading 1",
+			name: builtInHeadingStyleName(0),
 			fontSize: 28,
 			spaceBefore: 360
 		},
 		{
 			styleId: "Heading2",
-			name: "heading 2",
+			name: builtInHeadingStyleName(1),
 			fontSize: 24,
 			spaceBefore: 240
 		},
 		{
 			styleId: "Heading3",
-			name: "heading 3",
+			name: builtInHeadingStyleName(2),
 			fontSize: 22,
 			spaceBefore: 240
 		},
 		{
 			styleId: "Heading4",
-			name: "heading 4",
+			name: builtInHeadingStyleName(3),
 			fontSize: 20,
 			spaceBefore: 120
 		},
 		{
 			styleId: "Heading5",
-			name: "heading 5",
+			name: builtInHeadingStyleName(4),
 			fontSize: 20,
 			spaceBefore: 120
 		},
 		{
 			styleId: "Heading6",
-			name: "heading 6",
+			name: builtInHeadingStyleName(5),
 			fontSize: 20,
 			spaceBefore: 120
 		}
@@ -457,32 +462,33 @@ const createHeadingStyles = () => {
 };
 /** `TOCHeading` plus `TOC1`..`TOC3`, the styles a `TOC \o "1-3"` field fills. */
 const createTableOfContentsStyles = () => {
-	return [{
-		styleId: "TOCHeading",
-		type: "paragraph",
-		name: "TOC Heading",
-		basedOn: "Heading1",
-		next: "BodyText",
-		unhideWhenUsed: true,
-		uiPriority: 39,
-		pPr: { outlineLevel: 9 }
-	}, ...[
+	const levels = [
 		{
 			styleId: "TOC1",
-			name: "toc 1",
+			name: builtInTableOfContentsStyleName(1),
 			indent: 0
 		},
 		{
 			styleId: "TOC2",
-			name: "toc 2",
+			name: builtInTableOfContentsStyleName(2),
 			indent: 220
 		},
 		{
 			styleId: "TOC3",
-			name: "toc 3",
+			name: builtInTableOfContentsStyleName(3),
 			indent: 440
 		}
-	].map(({ styleId, name, indent }) => ({
+	];
+	return [{
+		styleId: "TOCHeading",
+		type: "paragraph",
+		name: BUILT_IN_STYLE_NAME.tocHeading,
+		basedOn: "Heading1",
+		next: "BodyText",
+		unhideWhenUsed: true,
+		uiPriority: 39,
+		pPr: { outlineLevel: 9 }
+	}, ...levels.map(({ styleId, name, indent }) => ({
 		styleId,
 		type: "paragraph",
 		name,
@@ -548,7 +554,8 @@ const createClauseStyles = () => {
 					ilvl: level
 				},
 				keepNext: level < 2,
-				spaceBefore: clauseSpaceBefore(level)
+				spaceBefore: clauseSpaceBefore(level),
+				outlineLevel: level === 0 ? 0 : 9
 			}
 		};
 		if (bold) return Object.assign(style, { rPr: { bold: true } });

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

@@ -0,0 +1,19 @@
+import { DocumentStyleSet } from "./types.js";
+import { ParseContext } from "../docx/parseContext.js";
+//#region src/style-sets/styleSetNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const DUPLICATE_STYLE_ID_WARNING: "style-set-duplicate-style-id";
+declare const INITIAL_PARAGRAPH_STYLE_WARNING: "style-set-initial-style-missing";
+declare const UNNUMBERED_STYLE_SET_STYLE_WARNING: "unnumbered-style";
+/** The part a style-set normalisation names: the set itself, not a package. */
+declare const STYLE_SET_PART = "style-set";
+/**
+ * A normalised copy of the set, leaving the caller's value untouched.
+ *
+ * The version is the one thing still refused rather than repaired: a value
+ * folio has no reader for is programmer misuse, not a document defect, and
+ * guessing at its meaning would be worse than saying so.
+ */
+declare const normalizeDocumentStyleSet: (styleSet: DocumentStyleSet, context?: ParseContext) => DocumentStyleSet;
+//#endregion
+export { DUPLICATE_STYLE_ID_WARNING, INITIAL_PARAGRAPH_STYLE_WARNING, STYLE_SET_PART, UNNUMBERED_STYLE_SET_STYLE_WARNING, normalizeDocumentStyleSet };

package/dist/style-sets/styleSetNormalization.js

@@ -0,0 +1,99 @@
+import { mintDefaultParagraphStyle, resolveDefaultParagraphStyle } from "../docx/defaultParagraphStyle.js";
+import { getCachedNumberingMap } from "../docx/numberingParser.js";
+import { normalizeStyleNumberingReferences } from "../docx/numberingReferenceNormalization.js";
+import "./types.js";
+import { panic } from "better-result";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
+//#region src/style-sets/styleSetNormalization.ts
+/**
+* The boundary an external `DocumentStyleSet` crosses to become a document.
+*
+* A style set is portable by design: hosts persist one as JSON, ship it
+* between workspaces, and hand it back months later. That makes it untrusted
+* input on the same footing as a `.docx`, and it can carry the same defects a
+* package can: a style numbering the set never defines, two styles under one
+* id, an initial paragraph style that is not in the set. A set written before
+* folio learned to normalise those still carries them.
+*
+* So it is normalised here, once, on the way in, through the same owners the
+* parser and the extractor use, rather than at a third call site with its own
+* rules. `createEmptyDocument` is the only door, so this is the only place
+* that has to run.
+*
+* `DOCUMENT_STYLE_SET_VERSION` does not move: the shape is unchanged and a v1
+* value is still a v1 value. What changed is that folio repairs one instead of
+* trusting it.
+*/
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+const DUPLICATE_STYLE_ID_WARNING = PARSE_WARNING_CODES.styleSetDuplicateStyleId;
+const INITIAL_PARAGRAPH_STYLE_WARNING = PARSE_WARNING_CODES.styleSetInitialStyleMissing;
+const UNNUMBERED_STYLE_SET_STYLE_WARNING = PARSE_WARNING_CODES.unnumberedStyle;
+/** The part a style-set normalisation names: the set itself, not a package. */
+const STYLE_SET_PART = "style-set";
+/**
+* A normalised copy of the set, leaving the caller's value untouched.
+*
+* The version is the one thing still refused rather than repaired: a value
+* folio has no reader for is programmer misuse, not a document defect, and
+* guessing at its meaning would be worse than saying so.
+*/
+const normalizeDocumentStyleSet = (styleSet, context) => {
+	if (styleSet.version !== 1) return panic(`Unsupported document style set version: ${String(styleSet.version)}`);
+	if (styleSet.name.trim().length === 0) return panic("Document style set name cannot be empty");
+	const scoped = context?.scoped({ part: STYLE_SET_PART });
+	const normalized = structuredClone(styleSet);
+	const styles = dropDuplicateStyleIds(normalized.styles.styles, scoped);
+	normalized.styles.styles = styles;
+	const unnumbered = normalizeStyleNumberingReferences({
+		styles,
+		numbering: normalized.numbering ? getCachedNumberingMap(normalized.numbering) : void 0
+	});
+	for (const styleId of unnumbered.unnumberedStyleIds) scoped?.warn({
+		code: UNNUMBERED_STYLE_SET_STYLE_WARNING,
+		value: styleId,
+		at: `style "${styleId}"`
+	});
+	normalized.initialParagraphStyleId = resolveInitialParagraphStyleId({
+		styles,
+		requested: styleSet.initialParagraphStyleId,
+		hasDocDefaults: normalized.styles.docDefaults !== void 0,
+		context: scoped
+	});
+	return normalized;
+};
+const dropDuplicateStyleIds = (styles, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	const kept = [];
+	for (const style of styles) {
+		if (seen.has(style.styleId)) {
+			context?.warn({
+				code: DUPLICATE_STYLE_ID_WARNING,
+				value: style.styleId,
+				at: `style "${style.styleId}"`
+			});
+			continue;
+		}
+		seen.add(style.styleId);
+		kept.push(style);
+	}
+	return kept;
+};
+const resolveInitialParagraphStyleId = ({ styles, requested, hasDocDefaults, context }) => {
+	if (styles.find((style) => style.styleId === requested && style.type === "paragraph")) return requested;
+	const replacement = resolveDefaultParagraphStyle(styles) ?? (() => {
+		const minted = mintDefaultParagraphStyle({
+			takenStyleIds: new Set(styles.map((style) => style.styleId)),
+			hasDocDefaults
+		});
+		styles.push(minted);
+		return minted;
+	})();
+	context?.warn({
+		code: INITIAL_PARAGRAPH_STYLE_WARNING,
+		value: requested,
+		at: `style "${replacement.styleId}"`
+	});
+	return replacement.styleId;
+};
+//#endregion
+export { DUPLICATE_STYLE_ID_WARNING, INITIAL_PARAGRAPH_STYLE_WARNING, STYLE_SET_PART, UNNUMBERED_STYLE_SET_STYLE_WARNING, normalizeDocumentStyleSet };