@json-to-office/core-docx 0.38.0 → 1.0.0

package/dist/ir/compiler.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Compile a processed document into DocxIR.
+ *
+ * The input is the authoring tree after schema validation, custom-component
+ * expansion, theme resolution and component defaults (`ProcessedDocument`),
+ * paired with the section and column plan (`LayoutPlan`). What remains, and
+ * what this module does, is the last mile: the inline mini-language becomes
+ * inline nodes, points become twips and half-points, theme colour tokens become
+ * hex, and a font weight becomes the family alias it resolves to.
+ *
+ * No renderer is imported here, and none may be. The output is plain data.
+ *
+ * Scope: this is the first vertical slice — document metadata and settings,
+ * sections and page setup, headers and footers, paragraphs and headings with
+ * their runs, bookmarks, inline images and simple tables. Anything outside it
+ * is reported through `unsupported`, so a caller can tell "not yet compiled"
+ * from "compiled to nothing", and the default pipeline stays on the pre-IR path
+ * until the gap closes.
+ */
+import { type FeatureRequirement } from '@json-to-office/shared/rendering';
+import type { GenerationWarning } from '@json-to-office/shared';
+import type { LayoutPlan } from '../core/layout';
+import type { ProcessedDocument } from '../core/structure';
+import type { ImageResources } from '../core/imageResources';
+import type { DocxFeature } from './features';
+import { type DocxIR } from './types';
+/** A component the compiler does not yet lower into IR. */
+export interface UnsupportedComponent {
+    name: string;
+    path: string;
+    /** What about it is not handled, when the component itself is. */
+    detail?: string;
+}
+export interface DocxCompileResult {
+    ir: DocxIR;
+    /** Backend capabilities the IR needs, with the IR path that needs them. */
+    required: readonly FeatureRequirement<DocxFeature>[];
+    warnings: GenerationWarning[];
+    /**
+     * What the compiler could not lower. Empty once the migration is complete;
+     * until then this is what keeps the pre-IR path authoritative instead of
+     * silently dropping content.
+     */
+    unsupported: UnsupportedComponent[];
+}
+export declare function compileDocument(structure: ProcessedDocument, layout: LayoutPlan, warnings?: GenerationWarning[], images?: ImageResources, options?: {
+    echoWarnings?: boolean;
+}): DocxCompileResult;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/ir/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/ir/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA8B3D,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,wBAAwB,CAAC;AAuC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAEL,KAAK,MAAM,EA8BZ,MAAM,SAAS,CAAC;AAejB,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,QAAQ,EAAE,SAAS,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;IACrD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;;OAIG;IACH,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACrC;AAsFD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,UAAU,EAClB,QAAQ,GAAE,iBAAiB,EAAO,EAClC,MAAM,GAAE,cAA0B,EAClC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,iBAAiB,CAmGnB"}

package/dist/ir/debug.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Stable debug snapshots of DocxIR.
+ *
+ * A snapshot is the IR with every binary resource replaced by its content hash
+ * and byte length, and object keys in a fixed order — diffable in a test,
+ * readable in a bug report, and free of the megabytes of image data that a
+ * base64 dump would carry.
+ */
+import type { DocxIR } from './types';
+/** A JSON-safe view of the IR, suitable for `toMatchSnapshot`. */
+export type DocxIrSnapshot = Record<string, unknown>;
+export declare function snapshotDocxIr(ir: DocxIR): DocxIrSnapshot;
+/** Render a snapshot as stable, pretty-printed JSON. */
+export declare function formatDocxIr(ir: DocxIR): string;
+//# sourceMappingURL=debug.d.ts.map

package/dist/ir/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/ir/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,SAAS,CAAC;AAEtD,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAKzD;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/ir/features.d.ts

@@ -0,0 +1,19 @@
+/**
+ * DOCX renderer features.
+ *
+ * A feature is a capability a *backend* must have, not an authoring concept.
+ * The compiler records one requirement per IR node that needs one; a renderer
+ * declares the set it can satisfy. Anything required but not declared fails
+ * before rendering, with the IR path attached.
+ *
+ * The boundaries are drawn where backends actually differ. `toc` and
+ * `cached-toc` are separate because writing the field is easy and baking its
+ * entries is not; `footnotes` and `endnotes` are separate because a backend can
+ * plausibly have one and not the other.
+ */
+export declare const DOCX_FEATURES: readonly ["paragraphs", "styles", "numbering", "sections", "columns", "headers-footers", "tables", "table-merged-cells", "floating-tables", "images", "floating-images", "svg-images", "text-frames", "text-boxes", "toc", "cached-toc", "fields", "cached-fields", "hyperlinks", "bookmarks", "cross-references", "comments", "comment-threads", "footnotes", "endnotes", "revisions", "breaks", "shading", "borders", "tab-stops", "proofing-language", "custom-properties", "rtl"];
+export type DocxFeature = (typeof DOCX_FEATURES)[number];
+/** Every feature, for an adapter that claims the full surface. */
+export declare const ALL_DOCX_FEATURES: ReadonlySet<DocxFeature>;
+export declare function isDocxFeature(value: string): value is DocxFeature;
+//# sourceMappingURL=features.d.ts.map

package/dist/ir/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../src/ir/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,aAAa,udA6DhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,WAAW,CAEtD,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE"}

package/dist/ir/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DocxIR — internal to `@json-to-office/core-docx` for this release.
+ *
+ * Deliberately not re-exported from `packages/core-docx/src/index.ts`: the IR
+ * shape is expected to move while the rest of the DOCX migration lands, and
+ * publishing it now would freeze it. See
+ * `docs/architecture/office-renderer-ir.md`.
+ */
+export * from './types';
+export * from './features';
+export * from './units';
+export { assertValidDocxIr, validateDocxIr } from './validation';
+export type { IrViolation } from './validation';
+export { formatDocxIr, snapshotDocxIr } from './debug';
+export type { DocxIrSnapshot } from './debug';
+//# sourceMappingURL=index.d.ts.map

package/dist/ir/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ir/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/ir/inline.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The inline text mini-language, parsed into IR nodes.
+ *
+ * Authoring writes `**bold**`, `\n`, `\t` and friends inside a single string.
+ * By the time DocxIR exists none of that is markup any more: it is text runs,
+ * line breaks and tab runs, each carrying resolved formatting.
+ *
+ * This is deliberately a separate module from `compiler.ts`. The mini-language
+ * is the one piece of DOCX authoring with its own grammar, and it is where the
+ * subtle rules live — a decorator pair may straddle a newline, a tab has to
+ * become a real tab run because a tab character inside `<w:t>` is dropped, and
+ * a no-proof word has to be its own run so the flag can sit on it alone.
+ *
+ * Scope: decorators, line breaks, tabs, no-proof words, `[text](target)` links
+ * and `{PLACEHOLDER}` tokens. Cross-references and note markers are recognised
+ * only so the compiler can refuse them explicitly rather than render them as
+ * the literal characters an author wrote as markup — see
+ * `containsUnsupportedSyntax`.
+ */
+import type { DocxIrInline, DocxIrRunFormatting } from './types';
+/**
+ * A matcher for the known-words allowlist, or null when there is nothing to
+ * match.
+ *
+ * Each word matches as a whole token — no letter or digit directly either side
+ * — so `Wiseair` does not match inside `Wiseairy`, while internal punctuation
+ * like `json-to-office` matches literally.
+ */
+export declare function buildNoProofWordsRegex(noProofWords?: string[]): RegExp | null;
+/** True when the text carries a `{PLACEHOLDER}` token. */
+export declare function containsPlaceholder(text: string): boolean;
+/** True when the text carries a `[@id]` cross-reference. */
+export declare function containsCrossReference(text: string): boolean;
+/** True when the text carries a `[text](target)` link. */
+export declare function containsLink(text: string): boolean;
+/**
+ * Name the first piece of syntax in `text` this parser cannot lower.
+ *
+ * The compiler calls this before parsing so an unsupported construct is
+ * reported rather than silently rendered as the literal characters an author
+ * wrote as markup.
+ */
+export declare function containsUnsupportedSyntax(text: string): string | undefined;
+export interface ParseInlineOptions {
+    /** Formatting every run starts from. */
+    base: DocxIrRunFormatting;
+    /**
+     * Lower `[text](target)` into hyperlink nodes.
+     *
+     * Off by default: a component that does not accept links renders the
+     * brackets as the literal characters the author typed, which is what the
+     * pipeline has always done.
+     */
+    hyperlinks?: boolean;
+    /**
+     * Colour applied to a run only because a decorator made it bold.
+     *
+     * A separate colour for emphasised text is an authoring feature, so it is
+     * resolved here rather than left for a renderer to infer from `bold`.
+     */
+    boldColor?: {
+        hex: string;
+    };
+    /** Words to mark `noProof`, each split into a run of its own. */
+    noProofWords?: string[];
+    /**
+     * Resolve a `{NAME}` token. Returning nothing leaves it as literal text.
+     *
+     * A placeholder's meaning is document state — the generation date, the page
+     * being drawn — so the compiler supplies it rather than this module knowing
+     * any of it.
+     */
+    resolvePlaceholder?: (name: string) => PlaceholderResolution | undefined;
+    /**
+     * Resolve a `[^id]` marker to a note. Returning nothing leaves it literal.
+     *
+     * Resolution happens at the leaf, after decorators: a marker inside
+     * `**bold[^n]**` keeps the surrounding emphasis, which splitting earlier
+     * would break by cutting the `**` pair across segments.
+     */
+    resolveNote?: (id: string) => {
+        id: number;
+        noteKind: 'footnote' | 'endnote';
+    } | undefined;
+    /**
+     * Resolve a `[@id]` token to a field, or to nothing to leave it literal.
+     *
+     * The target may appear later in the document, so only a pre-pass over the
+     * whole outline can answer this — which is why the compiler supplies it.
+     */
+    resolveCrossReference?: (id: string, format: CrossReferenceFormat, token: string) => DocxIrInline | undefined;
+}
+/** The `\r`-style switches a `[@id:format]` token may ask for. */
+export type CrossReferenceFormat = 'relative' | 'no_context' | 'full_context' | 'none';
+/**
+ * Parse authored text into inline IR nodes.
+ *
+ * The shape of the output mirrors what the format needs rather than what the
+ * grammar looked like: a decorated span becomes runs with `bold`/`italic` set,
+ * a `\n` becomes a `lineBreak` node, a `\t` becomes a `tab` node.
+ */
+export declare function parseInline(text: string, options: ParseInlineOptions): DocxIrInline[];
+/**
+ * A placeholder resolved to something concrete.
+ *
+ * `field` is a live field Word recomputes (a page number); `text` is resolved
+ * once, at generation time (a date). An unknown name resolves to nothing and
+ * the token stays as the characters the author typed.
+ */
+export type PlaceholderResolution = {
+    kind: 'field';
+    instruction: string;
+} | {
+    kind: 'text';
+    text: string;
+};
+/**
+ * Text with no mini-language at all.
+ *
+ * A heading with no decorators and no cross-reference is rendered character for
+ * character: brackets stay brackets, and a newline stays inside the text rather
+ * than breaking the line. Only no-proof words are still split out, because the
+ * flag has to sit on exactly those runs.
+ */
+export declare function parseLiteral(text: string, options: ParseInlineOptions): DocxIrInline[];
+//# sourceMappingURL=inline.d.ts.map

package/dist/ir/inline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../src/ir/inline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAMjE;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAY7E;AAmDD,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK1E;AAED,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,qBAAqB,GAAG,SAAS,CAAC;IACzE;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CACZ,EAAE,EAAE,MAAM,KACP;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;IAClE;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,CACtB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,KACV,YAAY,GAAG,SAAS,CAAC;CAC/B;AAED,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAC5B,UAAU,GACV,YAAY,GACZ,cAAc,GACd,MAAM,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,YAAY,EAAE,CAehB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA8FnC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,YAAY,EAAE,CAShB"}