doc-model.js 1.10.1 → 2.0.0

package/README.md

@@ -39,9 +39,9 @@ graph TD
     style schema fill:#f9a825,stroke:#333,stroke-width:3px
 ```
 
-`ContentDocument` (the semantic pivot) is a discriminated union of four kinds: `wordprocessing` (docx/odt-style sections of paragraphs/runs/tables/images), `presentation` (pptx/odp-style slides of shapes), `spreadsheet` (xlsx/ods-style sheets of cells, columns, rows, and print settings), and `drawing` (odg-style pages of shapes plus vector primitives -- rect/ellipse/line/path). `ContentEmbeddedObjectSchema` lets any of the four 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, with `LayoutPathSchema` modelling a general vector path rather than only axis-aligned rectangles. `DocumentPackageSchema` is a small envelope pairing the two: `content` required, `layout` optional (it's a derived artifact, absent until something lays the content out), correlated via each item's own `sourcePath` when both are present -- a pairing this schema does not itself keep in sync or detect as stale.
+`ContentDocument` (the semantic pivot) is a discriminated union of five kinds: `wordprocessing` (docx/odt-style sections of paragraphs/runs/tables/images), `presentation` (pptx/odp-style slides of shapes), `spreadsheet` (xlsx/ods-style sheets of cells, columns, rows, and print settings), `drawing` (odg-style pages of shapes plus vector primitives -- rect/ellipse/line/path), and `formula` (an equation, carrying its own MathML presentation-layer node tree plus the StarMath source when the producing format had one). `ContentEmbeddedObjectSchema` lets any of the five embed another whole `ContentDocument` -- including a `formula` one, which is what an embedded equation inside a document or slide now carries. `LayoutDocument` (the PDF-rendering pivot) is pages of positioned `LayoutItem`s -- `text`/`image`/`rect`/`line`/`ellipse`/`path`/`link` -- in PDF user-space coordinates, with `LayoutPathSchema` modelling a general vector path rather than only axis-aligned rectangles. `DocumentPackageSchema` is a small envelope pairing the two: `content` required, `layout` optional (it's a derived artifact, absent until something lays the content out), correlated via each item's own `sourcePath` when both are present -- a pairing this schema does not itself keep in sync or detect as stale.
 
-It contains only [Zod](https://zod.dev) schemas, their inferred types, and a handful of trivial schema-attached helpers (hex-colour conversion, a recursive structural type guard for the mutually-recursive table/block/embedded-object types). There is no XML, ZIP, PDF, or other binary handling here, and no `zod` dependency other than `zod` itself.
+It contains only [Zod](https://zod.dev) schemas, their inferred types, and a handful of trivial schema-attached helpers (hex-colour conversion, recursive structural type guards for the mutually-recursive table/block/embedded-object types and for the MathML node tree). There is no XML, ZIP, PDF, or other binary handling here, and no `zod` dependency other than `zod` itself.
 
 The GitHub repository is [`ExaDev/document-schema.js`](https://github.com/ExaDev/document-schema.js), matching the published npm package name.
 
@@ -80,7 +80,31 @@ node_modules/document-schema.js/schemas/content-document.schema.json
 node_modules/document-schema.js/schemas/layout-document.schema.json
 ```
 
-Each file's `$id` is a `https://cdn.jsdelivr.net/npm/document-schema.js@<version>/schemas/<file>` URL, pinned to the exact npm version that generated it -- immutable (jsdelivr serves each version's own published tarball contents forever, with an immutable cache header) and genuinely live the moment that version is published, unlike a commit-SHA-pinned raw GitHub URL would be: a gitignored, generated file can never actually be committed at the commit whose SHA it would need to embed, since committing it changes the tree and thus the hash. The three files are cross-referenced via real `$ref`s (e.g. `document-package.schema.json`'s `content`/`layout` properties `$ref` the other two files directly, at that same version), so a JSON Schema validator that resolves `$ref`s over HTTP (or against local copies of all three files) can validate a whole `DocumentPackage` value. `content-document.schema.json` additionally carries a `$defs` block for the recursive paragraph/table/embedded-object block model, which Zod's own converter can't express directly (see that script's own top-of-file comment for why).
+Each file's `$id` is a `https://cdn.jsdelivr.net/npm/document-schema.js@<version>/schemas/<file>` URL, pinned to the exact npm version that generated it -- immutable (jsdelivr serves each version's own published tarball contents forever, with an immutable cache header) and genuinely live the moment that version is published, unlike a commit-SHA-pinned raw GitHub URL would be: a gitignored, generated file can never actually be committed at the commit whose SHA it would need to embed, since committing it changes the tree and thus the hash. The three files are cross-referenced via real `$ref`s (e.g. `document-package.schema.json`'s `content`/`layout` properties `$ref` the other two files directly, at that same version), so a JSON Schema validator that resolves `$ref`s over HTTP (or against local copies of all three files) can validate a whole `DocumentPackage` value. `content-document.schema.json` additionally carries a `$defs` block for the recursive paragraph/table/embedded-object block model and for the recursive MathML node tree the `formula` kind carries, neither of which Zod's own converter can express directly (see that script's own top-of-file comment for why). `content-json-schema-defs.ts` (a normal, fully typechecked/linted `src/` module, not part of the `scripts/` build step) is where those hand-authored `$defs` fragments actually live; a regression test (`content-json-schema-defs.test.ts`) holds every fragment with a real, non-recursive, non-`z.custom()` exported Zod schema counterpart (`Color`, `Box`, `Alignment`, `ContentStrokeStyle`, `ContentBorder`, `ContentCellBorders`, `ContentListMembership`, `ContentRun`, `ContentParagraph`, `ContentImageBlock`, `ContentPageBreak`) to a live `z.toJSONSchema()` comparison against that real schema, so a field added to (or removed from) one of those schemas without updating its hand-authored `$defs` fragment now fails a test rather than silently drifting. The remaining fragments (`ContentBlock`, `ContentTable`/`ContentTableRow`/`ContentTableCell`, `ContentEmbeddedObjectBlock`, `MathMlNode`/`MathMlElement`/`MathMlAttribute`) sit downstream of one of the three genuinely un-representable `z.custom()` nodes and still need re-verifying by hand against `src/content.ts`/`src/mathml.ts` whenever those files change -- see the `z.lazy()` investigation immediately below for why those three nodes are `z.custom()` in the first place, and whether that still has to be true.
+
+### `z.custom()` vs `z.lazy()` for recursive schemas
+
+`ContentBlockSchema`, `ContentEmbeddedObjectSchema` (`src/content.ts`), and `MathMlNodeSchema` (`src/mathml.ts`) are all `z.custom()` type-guard predicates rather than real Zod schemas, because -- per each file's own long-standing code comment -- `z.lazy()` was believed to "collapse to `unknown`" for recursive children in the pinned Zod version. That belief was re-tested directly against the version actually installed today (`zod@4.4.3`, confirmed via `node_modules/zod/package.json`) by converting `MathMlNodeSchema`/`MathMlElementSchema` (the simplest of the three -- a self-recursive discriminated union, not `ContentBlock`'s mutual table/cell recursion or the cross-cutting `ContentDocument` cycle `ContentEmbeddedObject` carries) to a genuine `z.lazy()`-based pair, as a throwaway spike later reverted in full (`git diff -- src/mathml.ts` shows no changes on the commit this note was added in).
+
+**Finding: `zod@4.4.3`'s `z.lazy()` genuinely supports this now, with one real constructional gotcha.** The naive rewrite --
+
+```ts
+export const MathMlElementSchema: z.ZodType<MathMlElement> = z.object({
+  type: z.literal('element'),
+  tag: z.string(),
+  attributes: z.array(MathMlAttributeSchema),
+  children: z.lazy(() => z.array(MathMlNodeSchema)),
+});
+export const MathMlNodeSchema: z.ZodType<MathMlNode> = z.discriminatedUnion('type', [
+  MathMlTextSchema, MathMlCdataSchema, MathMlCommentSchema, MathMlDeclarationSchema, MathMlPiSchema, MathMlElementSchema,
+]);
+```
+
+fails to typecheck: annotating `MathMlElementSchema` itself as `z.ZodType<MathMlElement>` widens it enough that `z.discriminatedUnion` (which needs each member's own internal `propValues` metadata to dispatch on the discriminant) rejects it with a real, correct type error (`Types of property '_zod.propValues' are incompatible ... Type 'undefined' is not assignable to type 'PropValues'`) -- not a Zod bug, but a genuine consequence of erasing a `ZodObject`'s specific shape down to the generic `ZodType` interface. Dropping the annotation entirely instead produces TypeScript's own classic circular-inference error (`'MathMlElementSchema' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer`) -- this is the failure the original "collapses to `unknown`" comment was almost certainly describing. The fix that actually works: annotate **only the outer union's own binding** (`MathMlNodeSchema: z.ZodType<MathMlNode> = z.discriminatedUnion(...)`), leaving every member schema, `MathMlElementSchema` included, unannotated and fully inferred. That one annotation breaks the circularity for the type-checker without erasing any member's own internal shape, since the erasure only ever applies to the final union result, not to what's passed into `z.discriminatedUnion`'s own argument list.
+
+With that one change, every existing test in `mathml.test.ts` passed unmodified -- including the four-level-deep nested-element test and the exact-failure-at-the-deepest-level negative test -- proving recursion genuinely terminates and validates correctly at runtime, not just at the type level. `z.toJSONSchema(MathMlNodeSchema, { unrepresentable: 'any' })`, called on its own (no registry, no `override()`), produced a fully real, standard `oneOf`-based JSON Schema with a genuine `{ "$ref": "#" }` at the exact recursion point (`element.children.items`) -- no empty `{}` degenerate node anywhere, and `unrepresentable: 'any'` never actually had to activate for it.
+
+**What this means, and what it doesn't (yet):** this is a confirmed, empirically-verified capability upgrade in the currently-pinned Zod version for the *simplest* of the three `z.custom()` cases in this package. It was **not** implemented as a real change in this task -- it's flagged here as a scoped, tracked follow-up, not carried out speculatively alongside unrelated work. Converting `MathMlNodeSchema` for real would let `scripts/generate-json-schemas.mjs` drop its `MathMlNode`/`MathMlElement`/`MathMlAttribute` hand-authored `$defs` entries (and the `override()` branch for `MathMlNodeSchema`) entirely, replacing them with Zod's own native recursive output. `ContentBlockSchema`/`ContentEmbeddedObjectSchema` are meaningfully harder (mutual recursion across `ContentBlock ↔ ContentTableCell ↔ ContentTableRow ↔ ContentTable`, plus `ContentEmbeddedObject`'s cycle back through a whole five-variant `ContentDocument` union) and were not spiked at all -- the same "annotate only the outermost binding" technique is the natural starting point, but the actual mutual-recursion shape needs its own from-scratch verification before assuming it generalises.
 
 ### Self-describing JSON
 
@@ -109,7 +133,7 @@ try {
 }
 ```
 
-`documentSchemaKindOf(value)` is the lower-level building block `documentFromJson` uses internally -- exported on its own for a caller that only wants to know which kind a value claims to be (version-agnostically: a `$schema` from an older or newer installed version still resolves), without also parsing it. `schemaUriFor(kind)` is the URL builder itself, also exported directly. Deliberately not added: a JSON-Schema-validator dependency (e.g. `ajv`) for ingest -- the generated `.schema.json` files are already a strictly *weaker* approximation of the real Zod schemas (see the two hand-authored `$defs` fragments above), so re-validating against them on ingest would be a fidelity regression, not an improvement.
+`documentSchemaKindOf(value)` is the lower-level building block `documentFromJson` uses internally -- exported on its own for a caller that only wants to know which kind a value claims to be (version-agnostically: a `$schema` from an older or newer installed version still resolves), without also parsing it. `schemaUriFor(kind)` is the URL builder itself, also exported directly. Deliberately not added: a JSON-Schema-validator dependency (e.g. `ajv`) for ingest -- the generated `.schema.json` files are already a strictly *weaker* approximation of the real Zod schemas (see the hand-authored `$defs` fragments above), so re-validating against them on ingest would be a fidelity regression, not an improvement.
 
 ## Used by
 

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

@@ -0,0 +1,413 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_schema_io = require("./schema-io.cjs");
+//#region src/content-json-schema-defs.ts
+const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+const EMBEDDED_OBJECT_KINDS = [
+	"formula",
+	"wordprocessing",
+	"presentation",
+	"spreadsheet",
+	"drawing"
+];
+const CONTENT_DOCUMENT_URI = require_schema_io.schemaUriFor("ContentDocument");
+const CONTENT_DEFS = {
+	Color: {
+		type: "object",
+		properties: {
+			r: {
+				type: "number",
+				minimum: 0,
+				maximum: 1
+			},
+			g: {
+				type: "number",
+				minimum: 0,
+				maximum: 1
+			},
+			b: {
+				type: "number",
+				minimum: 0,
+				maximum: 1
+			}
+		},
+		required: [
+			"r",
+			"g",
+			"b"
+		],
+		additionalProperties: false
+	},
+	Box: {
+		type: "object",
+		properties: {
+			xPt: { type: "number" },
+			yPt: { type: "number" },
+			widthPt: {
+				type: "number",
+				minimum: 0
+			},
+			heightPt: {
+				type: "number",
+				minimum: 0
+			}
+		},
+		required: [
+			"xPt",
+			"yPt",
+			"widthPt",
+			"heightPt"
+		],
+		additionalProperties: false
+	},
+	Alignment: {
+		type: "string",
+		enum: [
+			"left",
+			"center",
+			"right",
+			"justify"
+		]
+	},
+	ContentStrokeStyle: {
+		type: "string",
+		enum: [
+			"solid",
+			"dashed",
+			"dotted",
+			"double"
+		]
+	},
+	ContentBorder: {
+		type: "object",
+		properties: {
+			color: { $ref: "#/$defs/Color" },
+			widthPt: {
+				type: "number",
+				exclusiveMinimum: 0
+			},
+			style: { $ref: "#/$defs/ContentStrokeStyle" }
+		},
+		required: ["color", "widthPt"],
+		additionalProperties: false
+	},
+	ContentCellBorders: {
+		type: "object",
+		properties: {
+			left: { $ref: "#/$defs/ContentBorder" },
+			right: { $ref: "#/$defs/ContentBorder" },
+			top: { $ref: "#/$defs/ContentBorder" },
+			bottom: { $ref: "#/$defs/ContentBorder" }
+		},
+		additionalProperties: false
+	},
+	ContentListMembership: {
+		type: "object",
+		properties: {
+			numId: { type: "string" },
+			level: {
+				type: "integer",
+				minimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			}
+		},
+		required: ["numId", "level"],
+		additionalProperties: false
+	},
+	ContentRun: {
+		type: "object",
+		properties: {
+			text: { type: "string" },
+			bold: { type: "boolean" },
+			italic: { type: "boolean" },
+			underline: { type: "boolean" },
+			strike: { type: "boolean" },
+			fontFamily: { type: "string" },
+			sizePt: {
+				type: "number",
+				exclusiveMinimum: 0
+			},
+			color: { $ref: "#/$defs/Color" },
+			hyperlink: { type: "string" },
+			sourcePath: { type: "string" }
+		},
+		required: ["text"],
+		additionalProperties: false
+	},
+	ContentParagraph: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "paragraph"
+			},
+			runs: {
+				type: "array",
+				items: { $ref: "#/$defs/ContentRun" }
+			},
+			styleId: { type: "string" },
+			alignment: { $ref: "#/$defs/Alignment" },
+			list: { $ref: "#/$defs/ContentListMembership" },
+			spacingBeforePt: { type: "number" },
+			spacingAfterPt: { type: "number" },
+			lineSpacing: {
+				type: "number",
+				exclusiveMinimum: 0
+			},
+			indentLeftPt: { type: "number" },
+			indentFirstLinePt: { type: "number" },
+			sourcePath: { type: "string" }
+		},
+		required: ["kind", "runs"],
+		additionalProperties: false
+	},
+	ContentImageBlock: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "image"
+			},
+			format: {
+				type: "string",
+				enum: ["png", "jpeg"]
+			},
+			base64: { type: "string" },
+			widthPt: {
+				type: "number",
+				exclusiveMinimum: 0
+			},
+			heightPt: {
+				type: "number",
+				exclusiveMinimum: 0
+			},
+			altText: { type: "string" },
+			sourcePath: { type: "string" }
+		},
+		required: [
+			"kind",
+			"format",
+			"base64",
+			"widthPt",
+			"heightPt"
+		],
+		additionalProperties: false
+	},
+	ContentPageBreak: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "pageBreak"
+			},
+			sourcePath: { type: "string" }
+		},
+		required: ["kind"],
+		additionalProperties: false
+	},
+	ContentTableCell: {
+		type: "object",
+		properties: {
+			blocks: {
+				type: "array",
+				items: { $ref: "#/$defs/ContentBlock" }
+			},
+			colSpan: {
+				type: "integer",
+				exclusiveMinimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
+			rowSpan: {
+				type: "integer",
+				exclusiveMinimum: 0,
+				maximum: MAX_SAFE_INTEGER
+			},
+			background: { $ref: "#/$defs/Color" },
+			borders: { $ref: "#/$defs/ContentCellBorders" },
+			sourcePath: { type: "string" }
+		},
+		required: ["blocks"],
+		additionalProperties: false
+	},
+	ContentTableRow: {
+		type: "object",
+		properties: {
+			cells: {
+				type: "array",
+				items: { $ref: "#/$defs/ContentTableCell" }
+			},
+			heightPt: {
+				type: "number",
+				exclusiveMinimum: 0
+			}
+		},
+		required: ["cells"],
+		additionalProperties: false
+	},
+	ContentTable: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "table"
+			},
+			rows: {
+				type: "array",
+				items: { $ref: "#/$defs/ContentTableRow" }
+			},
+			columnWidthsPt: {
+				type: "array",
+				items: {
+					type: "number",
+					exclusiveMinimum: 0
+				}
+			},
+			sourcePath: { type: "string" }
+		},
+		required: [
+			"kind",
+			"rows",
+			"columnWidthsPt"
+		],
+		additionalProperties: false
+	},
+	ContentEmbeddedObjectBlock: {
+		type: "object",
+		properties: {
+			kind: {
+				type: "string",
+				const: "embeddedObject"
+			},
+			objectKind: {
+				type: "string",
+				enum: EMBEDDED_OBJECT_KINDS
+			},
+			document: { $ref: CONTENT_DOCUMENT_URI },
+			frame: { $ref: "#/$defs/Box" },
+			sourcePath: { type: "string" }
+		},
+		required: [
+			"kind",
+			"objectKind",
+			"document",
+			"frame"
+		],
+		additionalProperties: false
+	},
+	ContentBlock: { oneOf: [
+		{ $ref: "#/$defs/ContentParagraph" },
+		{ $ref: "#/$defs/ContentTable" },
+		{ $ref: "#/$defs/ContentImageBlock" },
+		{ $ref: "#/$defs/ContentPageBreak" },
+		{ $ref: "#/$defs/ContentEmbeddedObjectBlock" }
+	] },
+	MathMlAttribute: {
+		type: "object",
+		properties: {
+			name: { type: "string" },
+			value: { type: "string" }
+		},
+		required: ["name", "value"],
+		additionalProperties: false
+	},
+	MathMlElement: {
+		type: "object",
+		properties: {
+			type: {
+				type: "string",
+				const: "element"
+			},
+			tag: { type: "string" },
+			attributes: {
+				type: "array",
+				items: { $ref: "#/$defs/MathMlAttribute" }
+			},
+			children: {
+				type: "array",
+				items: { $ref: "#/$defs/MathMlNode" }
+			}
+		},
+		required: [
+			"type",
+			"tag",
+			"attributes",
+			"children"
+		],
+		additionalProperties: false
+	},
+	MathMlNode: { oneOf: [
+		{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					const: "text"
+				},
+				value: { type: "string" }
+			},
+			required: ["type", "value"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					const: "cdata"
+				},
+				value: { type: "string" }
+			},
+			required: ["type", "value"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					const: "comment"
+				},
+				value: { type: "string" }
+			},
+			required: ["type", "value"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					const: "declaration"
+				},
+				attributes: {
+					type: "array",
+					items: { $ref: "#/$defs/MathMlAttribute" }
+				}
+			},
+			required: ["type", "attributes"],
+			additionalProperties: false
+		},
+		{
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					const: "pi"
+				},
+				target: { type: "string" },
+				content: { type: "string" }
+			},
+			required: [
+				"type",
+				"target",
+				"content"
+			],
+			additionalProperties: false
+		},
+		{ $ref: "#/$defs/MathMlElement" }
+	] }
+};
+//#endregion
+exports.CONTENT_DEFS = CONTENT_DEFS;
+exports.CONTENT_DOCUMENT_URI = CONTENT_DOCUMENT_URI;
+exports.EMBEDDED_OBJECT_KINDS = EMBEDDED_OBJECT_KINDS;
+exports.MAX_SAFE_INTEGER = MAX_SAFE_INTEGER;

package/dist/content-json-schema-defs.d.cts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/content-json-schema-defs.d.ts
+type JsonSchema = z.core.JSONSchema.JSONSchema;
+declare const MAX_SAFE_INTEGER: number;
+declare const EMBEDDED_OBJECT_KINDS: string[];
+declare const CONTENT_DOCUMENT_URI: string;
+declare const CONTENT_DEFS: Record<string, JsonSchema>;
+//#endregion
+export { CONTENT_DEFS, CONTENT_DOCUMENT_URI, EMBEDDED_OBJECT_KINDS, MAX_SAFE_INTEGER };

package/dist/content-json-schema-defs.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/content-json-schema-defs.d.ts
+type JsonSchema = z.core.JSONSchema.JSONSchema;
+declare const MAX_SAFE_INTEGER: number;
+declare const EMBEDDED_OBJECT_KINDS: string[];
+declare const CONTENT_DOCUMENT_URI: string;
+declare const CONTENT_DEFS: Record<string, JsonSchema>;
+//#endregion
+export { CONTENT_DEFS, CONTENT_DOCUMENT_URI, EMBEDDED_OBJECT_KINDS, MAX_SAFE_INTEGER };