document-schema.js 2.7.17 → 3.1.0

package/README.md

@@ -48,7 +48,7 @@ graph TD
     style schema fill:#f9a825,stroke:#333,stroke-width:3px
 ```
 
-`ContentDocument` (the semantic pivot) is a discriminated union of five kinds: `wordprocessing` (docx/odt sections of paragraphs/runs/tables/images), `presentation` (pptx/odp slides of shapes), `spreadsheet` (xlsx/ods sheets of cells, columns, rows, print settings), `drawing` (odg pages of shapes plus vector primitives — rect/ellipse/line/path), and `formula` (an equation carrying its own MathML node tree plus StarMath source when the producing format had one). `ContentEmbeddedObjectSchema` lets any of the five embed another whole `ContentDocument`. `LayoutDocument` (the PDF-rendering pivot) is pages of positioned `LayoutItem`s (`text`/`image`/`rect`/`line`/`ellipse`/`path`/`link`) in PDF user-space coordinates. `DocumentPackageSchema` pairs the two: `content` required, `layout` optional (derived, absent until something lays content out); the schema does not keep them in sync or detect staleness.
+`ContentDocument` (the semantic pivot) is a discriminated union of five kinds: `wordprocessing` (docx/odt sections of paragraphs/runs/tables/images), `presentation` (pptx/odp slides of shapes), `spreadsheet` (xlsx/ods sheets of cells, columns, rows, print settings), `drawing` (odg pages of shapes plus vector primitives — rect/ellipse/line/path), and `formula` (an equation carrying its own MathML node tree plus StarMath source when the producing format had one). `ContentEmbeddedObjectSchema` lets any of the five embed another whole `ContentDocument`. Every paragraph/run/image/table/shape/vector/spreadsheet-cell leaf also carries its own canonical `headingLevel`-or-position fields directly: a `ContentParagraph`'s optional `headingLevel` (1 = the outermost heading, independent of the round-trip-only `styleId`), and every such leaf's optional `frames: LayoutFrame[]` — that node's own rendered page position(s) (`pageIndex` plus PDF user-space `xPt`/`yPt`/`widthPt`/`heightPt`), fused directly onto the content tree once a layout pass has run. `LayoutDocument` (the PDF-rendering pivot pdf-codec's `readPdf`/`writePdf` operate on directly, independent of any `ContentDocument`) is pages of positioned `LayoutItem`s (`text`/`image`/`rect`/`line`/`ellipse`/`path`/`link`) in PDF user-space coordinates. `DocumentPackageSchema` wraps `content` (required) with `pages` (optional, derived: each rendered page's own size, indexed to match every node's own `frames[].pageIndex`) — a single fused tree rather than a second, independent `LayoutDocument` correlated back to `content` only by matching `sourcePath` strings; the schema does not keep `content`'s populated `frames` fields and `pages` in sync or detect staleness.
 
 The package contains only [Zod](https://zod.dev) schemas, their inferred types, trivial schema-attached helpers (hex-colour conversion, recursive structural type guards), and two small structural interfaces (`ContentCodec`/`LayoutCodec`, see [Codecs](#codecs)). No XML, ZIP, PDF, or binary handling; the sole dependency is `zod`.
 
@@ -60,8 +60,16 @@ Two format-agnostic helpers live here because they operate on the content model
 import { ContentDocumentSchema, DocumentPackageSchema, LayoutDocumentSchema } from 'document-schema.js';
 
 const content = ContentDocumentSchema.parse(someWordprocessingOrPresentationValue);
-const layout = LayoutDocumentSchema.parse(somePageLayoutValue);
-const pkg = DocumentPackageSchema.parse({ formatVersion: 1, content, layout });
+// A content-only package -- no layout pass has run yet, so no node carries `frames` and `pages` stays absent.
+const pkg = DocumentPackageSchema.parse({ formatVersion: 2, content });
+
+// Once a layout pass has fused rendered positions onto content's own nodes (each via its own `frames` array)
+// and reported each page's own size, `pages` is populated to match:
+const laidOut = DocumentPackageSchema.parse({ formatVersion: 2, content: someAlreadyPositionedContent, pages: [{ widthPt: 612, heightPt: 792 }] });
+
+// LayoutDocumentSchema is unrelated to DocumentPackageSchema -- it is the standalone PDF-rendering pivot
+// pdf-codec's own readPdf/writePdf read and write directly, with no ContentDocument in the loop at all.
+const layout = LayoutDocumentSchema.parse(somePdfPageLayoutValue);
 ```
 
 Every module is also importable directly — `tsdown` builds one file per source module, and `package.json`'s `"./*"` export makes each individually resolvable:
@@ -138,7 +146,7 @@ export const MathMlNodeSchema: z.ZodType<MathMlNode> = z.discriminatedUnion('typ
 import { documentPackageWithSchema } from 'document-schema.js';
 
 const tagged = documentPackageWithSchema(pkg);
-// { $schema: 'https://cdn.jsdelivr.net/npm/document-schema.js@1.6.1/schemas/document-package.schema.json', formatVersion: 1, content: {...}, layout: {...} }
+// { $schema: 'https://cdn.jsdelivr.net/npm/document-schema.js@2.0.0/schemas/document-package.schema.json', formatVersion: 2, content: {...}, pages: [...] }
 writeFileSync('package.json.doc', JSON.stringify(tagged, null, 2));
 ```
 

package/dist/content-json-schema-defs.cjs

@@ -59,6 +59,34 @@ const CONTENT_DEFS = {
 		],
 		additionalProperties: false
 	},
+	LayoutFrame: {
+		type: "object",
+		properties: {
+			pageIndex: {
+				type: "integer",
+				minimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
+			xPt: { type: "number" },
+			yPt: { type: "number" },
+			widthPt: {
+				type: "number",
+				minimum: 0
+			},
+			heightPt: {
+				type: "number",
+				minimum: 0
+			}
+		},
+		required: [
+			"pageIndex",
+			"xPt",
+			"yPt",
+			"widthPt",
+			"heightPt"
+		],
+		additionalProperties: false
+	},
 	Alignment: {
 		type: "string",
 		enum: [
@@ -128,7 +156,11 @@ const CONTENT_DEFS = {
 			},
 			color: { $ref: "#/$defs/Color" },
 			hyperlink: { type: "string" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["text"],
 		additionalProperties: false
@@ -145,6 +177,11 @@ const CONTENT_DEFS = {
 				items: { $ref: "#/$defs/ContentRun" }
 			},
 			styleId: { type: "string" },
+			headingLevel: {
+				type: "integer",
+				exclusiveMinimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
 			alignment: { $ref: "#/$defs/Alignment" },
 			list: { $ref: "#/$defs/ContentListMembership" },
 			spacingBeforePt: { type: "number" },
@@ -155,7 +192,11 @@ const CONTENT_DEFS = {
 			},
 			indentLeftPt: { type: "number" },
 			indentFirstLinePt: { type: "number" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["kind", "runs"],
 		additionalProperties: false
@@ -181,7 +222,11 @@ const CONTENT_DEFS = {
 				exclusiveMinimum: 0
 			},
 			altText: { type: "string" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: [
 			"kind",
@@ -199,7 +244,11 @@ const CONTENT_DEFS = {
 				type: "string",
 				const: "pageBreak"
 			},
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["kind"],
 		additionalProperties: false
@@ -223,7 +272,11 @@ const CONTENT_DEFS = {
 			},
 			background: { $ref: "#/$defs/Color" },
 			borders: { $ref: "#/$defs/ContentCellBorders" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["blocks"],
 		additionalProperties: false
@@ -261,7 +314,11 @@ const CONTENT_DEFS = {
 					exclusiveMinimum: 0
 				}
 			},
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: [
 			"kind",
@@ -284,6 +341,10 @@ const CONTENT_DEFS = {
 			document: { $ref: CONTENT_DOCUMENT_URI },
 			frame: { $ref: "#/$defs/Box" },
 			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			},
 			anchorRow: {
 				type: "integer",
 				minimum: 0,

package/dist/content-json-schema-defs.js

@@ -58,6 +58,34 @@ const CONTENT_DEFS = {
 		],
 		additionalProperties: false
 	},
+	LayoutFrame: {
+		type: "object",
+		properties: {
+			pageIndex: {
+				type: "integer",
+				minimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
+			xPt: { type: "number" },
+			yPt: { type: "number" },
+			widthPt: {
+				type: "number",
+				minimum: 0
+			},
+			heightPt: {
+				type: "number",
+				minimum: 0
+			}
+		},
+		required: [
+			"pageIndex",
+			"xPt",
+			"yPt",
+			"widthPt",
+			"heightPt"
+		],
+		additionalProperties: false
+	},
 	Alignment: {
 		type: "string",
 		enum: [
@@ -127,7 +155,11 @@ const CONTENT_DEFS = {
 			},
 			color: { $ref: "#/$defs/Color" },
 			hyperlink: { type: "string" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["text"],
 		additionalProperties: false
@@ -144,6 +176,11 @@ const CONTENT_DEFS = {
 				items: { $ref: "#/$defs/ContentRun" }
 			},
 			styleId: { type: "string" },
+			headingLevel: {
+				type: "integer",
+				exclusiveMinimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
 			alignment: { $ref: "#/$defs/Alignment" },
 			list: { $ref: "#/$defs/ContentListMembership" },
 			spacingBeforePt: { type: "number" },
@@ -154,7 +191,11 @@ const CONTENT_DEFS = {
 			},
 			indentLeftPt: { type: "number" },
 			indentFirstLinePt: { type: "number" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["kind", "runs"],
 		additionalProperties: false
@@ -180,7 +221,11 @@ const CONTENT_DEFS = {
 				exclusiveMinimum: 0
 			},
 			altText: { type: "string" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: [
 			"kind",
@@ -198,7 +243,11 @@ const CONTENT_DEFS = {
 				type: "string",
 				const: "pageBreak"
 			},
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["kind"],
 		additionalProperties: false
@@ -222,7 +271,11 @@ const CONTENT_DEFS = {
 			},
 			background: { $ref: "#/$defs/Color" },
 			borders: { $ref: "#/$defs/ContentCellBorders" },
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: ["blocks"],
 		additionalProperties: false
@@ -260,7 +313,11 @@ const CONTENT_DEFS = {
 					exclusiveMinimum: 0
 				}
 			},
-			sourcePath: { type: "string" }
+			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			}
 		},
 		required: [
 			"kind",
@@ -283,6 +340,10 @@ const CONTENT_DEFS = {
 			document: { $ref: CONTENT_DOCUMENT_URI },
 			frame: { $ref: "#/$defs/Box" },
 			sourcePath: { type: "string" },
+			frames: {
+				type: "array",
+				items: { $ref: "#/$defs/LayoutFrame" }
+			},
 			anchorRow: {
 				type: "integer",
 				minimum: 0,

package/dist/content.cjs

@@ -16,7 +16,8 @@ const ContentRunSchema = zod.z.object({
 	sizePt: zod.z.number().positive().optional(),
 	color: require_color.ColorSchema.optional(),
 	hyperlink: zod.z.string().optional(),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 const ContentListMembershipSchema = zod.z.object({
 	numId: zod.z.string(),
@@ -26,6 +27,7 @@ const ContentParagraphSchema = zod.z.object({
 	kind: zod.z.literal("paragraph"),
 	runs: zod.z.array(ContentRunSchema),
 	styleId: zod.z.string().optional(),
+	headingLevel: zod.z.number().int().positive().optional(),
 	alignment: require_style.AlignmentSchema.optional(),
 	list: ContentListMembershipSchema.optional(),
 	spacingBeforePt: zod.z.number().optional(),
@@ -33,8 +35,12 @@ const ContentParagraphSchema = zod.z.object({
 	lineSpacing: zod.z.number().positive().optional(),
 	indentLeftPt: zod.z.number().optional(),
 	indentFirstLinePt: zod.z.number().optional(),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
+function clampHeadingLevel(level) {
+	return Math.min(6, Math.max(1, Math.round(level)));
+}
 const ContentImageBlockSchema = zod.z.object({
 	kind: zod.z.literal("image"),
 	format: zod.z.enum(["png", "jpeg"]),
@@ -42,11 +48,13 @@ const ContentImageBlockSchema = zod.z.object({
 	widthPt: zod.z.number().positive(),
 	heightPt: zod.z.number().positive(),
 	altText: zod.z.string().optional(),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 const ContentPageBreakSchema = zod.z.object({
 	kind: zod.z.literal("pageBreak"),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -105,7 +113,8 @@ const ContentTableCellSchema = zod.z.object({
 	rowSpan: zod.z.number().int().positive().optional(),
 	background: require_color.ColorSchema.optional(),
 	borders: ContentCellBordersSchema.optional(),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 const ContentTableRowSchema = zod.z.object({
 	cells: zod.z.array(ContentTableCellSchema),
@@ -115,7 +124,8 @@ const ContentTableSchema = zod.z.object({
 	kind: zod.z.literal("table"),
 	rows: zod.z.array(ContentTableRowSchema),
 	columnWidthsPt: zod.z.array(zod.z.number().positive()),
-	sourcePath: zod.z.string().optional()
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 const ContentSectionSchema = zod.z.object({
 	pageSize: require_geometry.PageSizeSchema,
@@ -134,6 +144,7 @@ const ContentShapeSchema = zod.z.object({
 	lineSpacingReduction: zod.z.number().nonnegative().optional(),
 	paintOrder: zod.z.number().optional(),
 	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional(),
 	blocks: zod.z.array(ContentBlockSchema)
 });
 const ContentSlideSchema = zod.z.object({
@@ -185,6 +196,15 @@ const ContentCellValueSchema = zod.z.discriminatedUnion("kind", [
 	}),
 	zod.z.object({ kind: zod.z.literal("empty") })
 ]);
+const ContentSheetCellCommentSchema = zod.z.object({
+	text: zod.z.string(),
+	author: zod.z.string().optional(),
+	createdAt: zod.z.string().optional(),
+	replies: zod.z.array(zod.z.object({
+		text: zod.z.string(),
+		author: zod.z.string().optional()
+	})).optional()
+});
 const ContentSheetCellSchema = zod.z.object({
 	row: zod.z.number().int().nonnegative(),
 	column: zod.z.number().int().nonnegative(),
@@ -202,7 +222,9 @@ const ContentSheetCellSchema = zod.z.object({
 		"middle",
 		"bottom"
 	]).optional(),
-	sourcePath: zod.z.string().optional()
+	comment: ContentSheetCellCommentSchema.optional(),
+	sourcePath: zod.z.string().optional(),
+	frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 });
 const ContentSheetColumnSchema = zod.z.object({
 	index: zod.z.number().int().nonnegative(),
@@ -289,7 +311,8 @@ const ContentVectorSchema = zod.z.discriminatedUnion("kind", [
 		fill: require_color.ColorSchema.optional(),
 		stroke: ContentStrokeSchema.optional(),
 		paintOrder: zod.z.number().optional(),
-		sourcePath: zod.z.string().optional()
+		sourcePath: zod.z.string().optional(),
+		frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 	}),
 	zod.z.object({
 		kind: zod.z.literal("ellipse"),
@@ -298,7 +321,8 @@ const ContentVectorSchema = zod.z.discriminatedUnion("kind", [
 		fill: require_color.ColorSchema.optional(),
 		stroke: ContentStrokeSchema.optional(),
 		paintOrder: zod.z.number().optional(),
-		sourcePath: zod.z.string().optional()
+		sourcePath: zod.z.string().optional(),
+		frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 	}),
 	zod.z.object({
 		kind: zod.z.literal("line"),
@@ -306,7 +330,8 @@ const ContentVectorSchema = zod.z.discriminatedUnion("kind", [
 		to: ContentPathPointSchema,
 		stroke: ContentStrokeSchema,
 		paintOrder: zod.z.number().optional(),
-		sourcePath: zod.z.string().optional()
+		sourcePath: zod.z.string().optional(),
+		frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 	}),
 	zod.z.object({
 		kind: zod.z.literal("path"),
@@ -317,7 +342,8 @@ const ContentVectorSchema = zod.z.discriminatedUnion("kind", [
 		fillRule: zod.z.enum(["nonzero", "evenodd"]).optional(),
 		stroke: ContentStrokeSchema.optional(),
 		paintOrder: zod.z.number().optional(),
-		sourcePath: zod.z.string().optional()
+		sourcePath: zod.z.string().optional(),
+		frames: zod.z.array(require_geometry.LayoutFrameSchema).optional()
 	})
 ]);
 const ContentDrawPageSchema = zod.z.object({
@@ -329,35 +355,35 @@ const ContentFormulaSchema = zod.z.object({
 	mathml: zod.z.array(require_mathml.MathMlNodeSchema),
 	starMath: zod.z.string().optional()
 });
-const CONTENT_FORMAT_VERSION = 2;
+const CONTENT_FORMAT_VERSION = 3;
 const ContentDocumentSchema = zod.z.discriminatedUnion("kind", [
 	zod.z.object({
 		kind: zod.z.literal("wordprocessing"),
-		formatVersion: zod.z.literal(2),
+		formatVersion: zod.z.literal(3),
 		metadata: require_metadata.LayoutMetadataSchema,
 		sections: zod.z.array(ContentSectionSchema)
 	}),
 	zod.z.object({
 		kind: zod.z.literal("presentation"),
-		formatVersion: zod.z.literal(2),
+		formatVersion: zod.z.literal(3),
 		metadata: require_metadata.LayoutMetadataSchema,
 		slides: zod.z.array(ContentSlideSchema)
 	}),
 	zod.z.object({
 		kind: zod.z.literal("spreadsheet"),
-		formatVersion: zod.z.literal(2),
+		formatVersion: zod.z.literal(3),
 		metadata: require_metadata.LayoutMetadataSchema,
 		sheets: zod.z.array(ContentSheetSchema)
 	}),
 	zod.z.object({
 		kind: zod.z.literal("drawing"),
-		formatVersion: zod.z.literal(2),
+		formatVersion: zod.z.literal(3),
 		metadata: require_metadata.LayoutMetadataSchema,
 		pages: zod.z.array(ContentDrawPageSchema)
 	}),
 	zod.z.object({
 		kind: zod.z.literal("formula"),
-		formatVersion: zod.z.literal(2),
+		formatVersion: zod.z.literal(3),
 		metadata: require_metadata.LayoutMetadataSchema,
 		formula: ContentFormulaSchema
 	})
@@ -382,6 +408,7 @@ exports.ContentPathSegmentSchema = ContentPathSegmentSchema;
 exports.ContentRunSchema = ContentRunSchema;
 exports.ContentSectionSchema = ContentSectionSchema;
 exports.ContentShapeSchema = ContentShapeSchema;
+exports.ContentSheetCellCommentSchema = ContentSheetCellCommentSchema;
 exports.ContentSheetCellSchema = ContentSheetCellSchema;
 exports.ContentSheetColumnSchema = ContentSheetColumnSchema;
 exports.ContentSheetImageSchema = ContentSheetImageSchema;
@@ -399,4 +426,5 @@ exports.ContentTableRowSchema = ContentTableRowSchema;
 exports.ContentTableSchema = ContentTableSchema;
 exports.ContentVectorSchema = ContentVectorSchema;
 exports.DecimalStringSchema = DecimalStringSchema;
+exports.clampHeadingLevel = clampHeadingLevel;
 exports.isContentBlock = isContentBlock;