ooxml.js 2.0.4 → 2.1.1

package/README.md

@@ -167,12 +167,12 @@ The package is layered from a lossless core outward to lossy convenience views:
 - **`src/package-io/`** — `read.ts` and `write.ts` sit between the zip and XML layers: unzip a package into path -> bytes, classify each entry as XML or binary (`looksLikeXml` sniffs the leading non-whitespace byte for `<`), and parse/serialize accordingly.
 - **`src/codec.ts`** — the public round-trip surface: `packageCodec`/`xmlCodec` are `z.codec()` pairs, and `decodePackage`/`encodePackage` are the ergonomic wrappers around them.
 - **`src/compact.ts`** — the ooxml.js format: `compactCodec` (`z.codec(PackageSchema, CompactPackageSchema, …)`) maps `Package ⇄ CompactPackage`, with `toCompact`/`fromCompact` as the ergonomic wrappers. `compactPackageCodec` composes `packageCodec` and `compactCodec` into a direct bytes ⇄ `CompactPackage` codec (`decodeCompactPackage`/`encodeCompactPackage`), so all three format pairs — bytes/`Package`, `Package`/`CompactPackage`, bytes/`CompactPackage` — have a named codec rather than requiring callers to chain two.
-- **`src/typed/`** — one-way, lossy projections that read the generic `Package` into ergonomic document/presentation/workbook models. `docx/` and `pptx/` share one block content model (`typed/shared/content.ts`'s `ContentParagraph`/`ContentTable`/`ContentImageBlock`/`ContentPageBreak`, discriminated as `ContentBlock`) instead of each keeping its own, disjoint shape: `readDocx` resolves the full WordprocessingML style cascade (`docx/styles.ts`: `docDefaults` → named-style `basedOn` chains → paragraph-mark run properties → character styles → direct formatting) into ordered `sections` of paragraphs/tables/page-breaks (document order preserved, including inside tables), plus `comments`, `footnotes`, and `headers`/`footers`; `readPptx` resolves the placeholder → layout → master → theme inheritance cascade (`pptx/inherit.ts`) into `slides` of positioned, styled `shapes` (geometry, run/paragraph formatting, embedded images, tables, speaker notes) in presentation order (`p:sldIdLst`, never slide filename order); `readXlsx` covers cell values and formulas, merged ranges and defined names. `typed/shared/` holds the primitives both `docx/` and `pptx/` build on: `content.ts` (the block model), `drawingml.ts` (DrawingML `a:xfrm` geometry, theme/colour resolution, group-transform composition), `geometry.ts`/`units.ts`/`color.ts`/`style.ts` (points-based geometry, OOXML unit conversions, sRGB colour + DrawingML shade/tint/lumMod/lumOff transforms, alignment), and `metadata.ts` (`docProps/core.xml` + `docProps/app.xml` → `DocumentMetadata`, shared verbatim across docx/pptx/xlsx). `src/image/sniff.ts` (magic-byte PNG/JPEG detection) supports `readPptx`'s picture-shape reading. None of this can be encoded back to a `Package` — round-tripping always goes through `decodePackage`/`encodePackage`, never through a typed view. `typed/util.ts` holds the shared XML-walking helpers (`walk`, `elementsWithTag`, `childrenWithTag`, `attr`, `rootElement`, `textContent`, entity decoding, `resolveRelationships`) every typed reader builds on.
+- **`src/typed/`** — one-way, lossy projections that read the generic `Package` into ergonomic document/presentation/workbook models. `docx/` and `pptx/` share one block content model — `ContentParagraph`/`ContentTable`/`ContentImageBlock`/`ContentPageBreak`, discriminated as `ContentBlock`, imported from the sibling [`document-content-model`](https://github.com/ExaDev/document-content-model) package rather than defined here (see below) — instead of each keeping its own, disjoint shape: `readDocx` resolves the full WordprocessingML style cascade (`docx/styles.ts`: `docDefaults` → named-style `basedOn` chains → paragraph-mark run properties → character styles → direct formatting) into ordered `sections` of paragraphs/tables/page-breaks (document order preserved, including inside tables), plus `comments`, `footnotes`, and `headers`/`footers`; `readPptx` resolves the placeholder → layout → master → theme inheritance cascade (`pptx/inherit.ts`) into `slides` of positioned, styled `shapes` (geometry, run/paragraph formatting, embedded images, tables, speaker notes) in presentation order (`p:sldIdLst`, never slide filename order); `readXlsx` covers cell values and formulas, merged ranges and defined names. `typed/shared/` holds the OOXML-specific primitives both `docx/` and `pptx/` build on: `drawingml.ts` (DrawingML `a:xfrm` geometry, theme/colour resolution, group-transform composition — including `ColorTransform`/`applyColorTransforms`, the shade/tint/lumMod/lumOff cascade maths, which stays here rather than in `document-content-model` since it's OOXML-cascade-resolution logic, not a content-model shape), `units.ts` (OOXML unit conversions — EMU/twip/half-point), `metadata.ts` (`docProps/core.xml` + `docProps/app.xml` → `DocumentMetadata`, shared verbatim across docx/pptx/xlsx), and `source-path.ts` (stamps a deterministic, document-order path like `sections[0].blocks[2].runs[1]` onto every `ContentRun`/`ContentBlock`/`ContentShape`, so a downstream consumer can trace a rendered item back to where it came from — see `document-content-model`'s own `sourcePath` field). Geometry (`Box`/`PageSize`/`Margins`), colour (`Color`/`ColorSchema`), and alignment (`Alignment`) types are imported from `document-content-model`, not defined locally. `src/image/sniff.ts` (magic-byte PNG/JPEG detection) supports `readPptx`'s picture-shape reading. None of this can be encoded back to a `Package` — round-tripping always goes through `decodePackage`/`encodePackage`, never through a typed view. `typed/util.ts` holds the shared XML-walking helpers (`walk`, `elementsWithTag`, `childrenWithTag`, `attr`, `rootElement`, `textContent`, entity decoding, `resolveRelationships`) every typed reader builds on.
 
 ## Conventions
 
 - **Zod-first schema/type/guard.** Every model type is inferred from its Zod schema (`z.infer<typeof XSchema>`), not hand-written — schema, type, and validator stay in lockstep.
-- **`XmlNode` uses a recursive structural guard, not `z.lazy`.** `z.lazy` collapses to `unknown` for the element-children case in the Zod version this project pins, so `XmlElementSchema` validates `children` via `z.custom<XmlNode>(isXmlNode)`, a hand-written recursive type guard in `model/node.ts`. Any change to `XmlNode`'s shape must update `isXmlNode` in step. `src/compact.ts`'s `CompactXmlNode` (`isCompactXmlNode` + `z.custom`) and `typed/shared/content.ts`'s `ContentBlock` (`isContentBlock` + `z.custom`, since a table cell's blocks can themselves contain a table) reuse the same pattern for the same reason.
+- **`XmlNode` uses a recursive structural guard, not `z.lazy`.** `z.lazy` collapses to `unknown` for the element-children case in the Zod version this project pins, so `XmlElementSchema` validates `children` via `z.custom<XmlNode>(isXmlNode)`, a hand-written recursive type guard in `model/node.ts`. Any change to `XmlNode`'s shape must update `isXmlNode` in step. `src/compact.ts`'s `CompactXmlNode` (`isCompactXmlNode` + `z.custom`) reuses the same pattern for the same reason; `document-content-model`'s own `ContentBlock` (`isContentBlock` + `z.custom`, since a table cell's blocks can themselves contain a table) does too, one level up the dependency graph.
 - **Lossless core vs. lossy views is a hard boundary.** `decodePackage`/`encodePackage` (and the underlying codecs) must stay byte/part faithful — every part round-trips unchanged. `src/typed/*` readers are explicitly one-way and are allowed to drop information (documented per-reader, e.g. `readDocx` resolves cached field-result text rather than re-evaluating live `PAGE`/`NUMPAGES` fields, docx's own `w:themeColor` references aren't resolved, and `readXlsx` drops cell styles, formats and charts). Don't blur this line by adding write-back support to a typed reader; a full round-trip always goes through the generic `Package`.
 - **XML entities stay raw in the lossless layer.** `parseXml` runs with `processEntities: false` so encoded entities (e.g. `&amp;`) are preserved verbatim for round-trip fidelity; typed readers decode the five standard entities (`decodeEntities` in `typed/util.ts`) only in their own lossy projection, never in the core model.
 - **No type assertions.** `eslint.config.ts` runs `@typescript-eslint/consistent-type-assertions` with `assertionStyle: "never"`, banning `as` and angle-bracket casts outright, with `linterOptions.noInlineConfig: true` so there is no `eslint-disable` escape hatch either — narrow with a guard or parse with Zod. An exception would have to be scoped structurally, as a `files`-matched override block in `eslint.config.ts`, not an inline comment.
@@ -203,6 +203,12 @@ Whether that release actually published a new version is detected by diffing `pa
 
 Commits follow Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`, …), enforced by commitlint (`commitlint.config.ts`) via a husky `commit-msg` hook and a CI `commitlint` job — semantic-release's version bump depends on these being well-formed, not just style. A husky `pre-commit` hook runs `lint-staged` (`eslint --fix` on staged `*.ts` files) and `pre-push` runs the test suite. There is a single `main` branch and no open pull request workflow established so far.
 
+## References
+
+- [document-content-model](https://github.com/ExaDev/document-content-model) — the canonical `ContentBlock`/`ContentSection`/`ContentSlide`/geometry/colour/alignment schemas `readDocx`/`readPptx` return, imported here rather than defined locally.
+- [odf.js](https://github.com/ExaDev/odf.js) — a sibling package doing the equivalent job for the OpenDocument Format (odt/ods/odp/odg/…), also built on `document-content-model`.
+- [documents.js](https://github.com/ExaDev/documents.js) — depends on this package for lossless OOXML handling and its cascade-resolved typed readers, adding PDF conversion and a read-and-write docx/pptx editor on top.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -874,6 +874,22 @@ function applyGroupTransform(group, childFrame) {
 	};
 }
 //#endregion
+//#region src/typed/shared/source-path.ts
+function assignSourcePaths(blocks, prefix) {
+	blocks.forEach((block, blockIndex) => {
+		const blockPath = `${prefix}.blocks[${blockIndex}]`;
+		block.sourcePath = blockPath;
+		if (block.kind === "paragraph") block.runs.forEach((run, runIndex) => {
+			run.sourcePath = `${blockPath}.runs[${runIndex}]`;
+		});
+		else if (block.kind === "table") block.rows.forEach((row, rowIndex) => {
+			row.cells.forEach((cell, cellIndex) => {
+				assignSourcePaths(cell.blocks, `${blockPath}.rows[${rowIndex}].cells[${cellIndex}]`);
+			});
+		});
+	});
+}
+//#endregion
 //#region src/typed/docx/styles.ts
 function mergeParagraphLayer(base, layer) {
 	return {
@@ -1267,6 +1283,7 @@ function readSections(body, context, rels) {
 		margins: DEFAULT_MARGINS,
 		blocks: currentBlocks
 	});
+	sections.forEach((section, sectionIndex) => assignSourcePaths(section.blocks, `sections[${sectionIndex}]`));
 	return sections;
 }
 function readDocumentTheme(pkg, docRels) {
@@ -1758,6 +1775,13 @@ function readPptx(pkg) {
 	const presentationRoot = rootElement(pkg.parts[PRESENTATION_PATH]);
 	const size = readSlideSize(presentationRoot);
 	const slides = readSlidePathsInOrder(pkg, presentationRoot).map((slidePath) => readSlide(pkg, slidePath, size));
+	slides.forEach((slide, slideIndex) => {
+		slide.shapes.forEach((shape, shapeIndex) => {
+			const shapePath = `slides[${slideIndex}].shapes[${shapeIndex}]`;
+			shape.sourcePath = shapePath;
+			assignSourcePaths(shape.blocks, shapePath);
+		});
+	});
 	return {
 		metadata: readCoreProperties(pkg),
 		slides

package/dist/index.d.cts

@@ -463,6 +463,7 @@ declare const PptxDocumentSchema: z.ZodObject<{
       insetBottomPt: z.ZodNumber;
       fontScale: z.ZodOptional<z.ZodNumber>;
       lineSpacingReduction: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
       blocks: z.ZodArray<z.ZodCustom<ContentBlock$1, ContentBlock$1>>;
     }, z.core.$strip>>;
     notes: z.ZodString;

package/dist/index.d.ts

@@ -463,6 +463,7 @@ declare const PptxDocumentSchema: z.ZodObject<{
       insetBottomPt: z.ZodNumber;
       fontScale: z.ZodOptional<z.ZodNumber>;
       lineSpacingReduction: z.ZodOptional<z.ZodNumber>;
+      sourcePath: z.ZodOptional<z.ZodString>;
       blocks: z.ZodArray<z.ZodCustom<ContentBlock$1, ContentBlock$1>>;
     }, z.core.$strip>>;
     notes: z.ZodString;

package/dist/index.js

@@ -873,6 +873,22 @@ function applyGroupTransform(group, childFrame) {
 	};
 }
 //#endregion
+//#region src/typed/shared/source-path.ts
+function assignSourcePaths(blocks, prefix) {
+	blocks.forEach((block, blockIndex) => {
+		const blockPath = `${prefix}.blocks[${blockIndex}]`;
+		block.sourcePath = blockPath;
+		if (block.kind === "paragraph") block.runs.forEach((run, runIndex) => {
+			run.sourcePath = `${blockPath}.runs[${runIndex}]`;
+		});
+		else if (block.kind === "table") block.rows.forEach((row, rowIndex) => {
+			row.cells.forEach((cell, cellIndex) => {
+				assignSourcePaths(cell.blocks, `${blockPath}.rows[${rowIndex}].cells[${cellIndex}]`);
+			});
+		});
+	});
+}
+//#endregion
 //#region src/typed/docx/styles.ts
 function mergeParagraphLayer(base, layer) {
 	return {
@@ -1266,6 +1282,7 @@ function readSections(body, context, rels) {
 		margins: DEFAULT_MARGINS,
 		blocks: currentBlocks
 	});
+	sections.forEach((section, sectionIndex) => assignSourcePaths(section.blocks, `sections[${sectionIndex}]`));
 	return sections;
 }
 function readDocumentTheme(pkg, docRels) {
@@ -1757,6 +1774,13 @@ function readPptx(pkg) {
 	const presentationRoot = rootElement(pkg.parts[PRESENTATION_PATH]);
 	const size = readSlideSize(presentationRoot);
 	const slides = readSlidePathsInOrder(pkg, presentationRoot).map((slidePath) => readSlide(pkg, slidePath, size));
+	slides.forEach((slide, slideIndex) => {
+		slide.shapes.forEach((shape, shapeIndex) => {
+			const shapePath = `slides[${slideIndex}].shapes[${shapeIndex}]`;
+			shape.sourcePath = shapePath;
+			assignSourcePaths(shape.blocks, shapePath);
+		});
+	});
 	return {
 		metadata: readCoreProperties(pkg),
 		slides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ooxml.js",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "Type-safe, lossless round-trip conversion between OOXML packages (docx, pptx, xlsx) and JSON, built on Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -61,7 +61,7 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "document-content-model": "^1.0.0",
+    "document-content-model": "^1.1.0",
     "fast-xml-parser": "^5.10.1",
     "fflate": "^0.8.3",
     "zod": "^4.4.3"