@portone/docx-editor 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @portone/docx-editor
 
+## 0.6.2
+
+### Patch Changes
+
+- [#143](https://github.com/portone-io/docx-editor/pull/143) [`2238131`](https://github.com/portone-io/docx-editor/commit/2238131792ecab86ad544545bc28eae24841cbca) Thanks [@Deea222](https://github.com/Deea222)! - Say which content blocks an export, and where it stands.
+  
+  Every entry `exportProblems`, `documentExportProblems` and a `blocked` `downloadDocx` report now carries a `reason`: a discriminated union naming the situation met and the content it is about, such as `unwritten-story-change` with the story and what was done to it, or `missing-content-types` with the part. It tells apart the situations one code covers, so a host can write the sentence its own user reads instead of matching an English message. The codes and messages are unchanged, so a `switch` over `code` keeps working.
+  
+  A problem about a footnote or an endnote now carries `pos` as well, the first reference to that note in the body, since the note's own text stands nowhere there. A note nothing refers to still has no position.
+  
+  `DocxExportError` carries the entry it was raised for as `problem`, so a `catch` reads the same `reason` and `pos` without asking again. A refusal met while writing that the invariants did not predict leaves it absent.
+  
+  The checks are now asked of every side story an edit reached - a footnote, an endnote, a header, a footer, a comment body - as well as of the body, so an unmatched bookmark, a vertical merge past its table, a placeholder that lost its XML or a paragraph in an undefined list is refused wherever it stands instead of going into the file unchecked. Each such reason carries a `story` saying where, `null` for the body. A story nobody touched goes out as it arrived and is not asked about.
+  
+  Since 0.6.1, `exportBytes` and `exportDocx` refuse a document holding a change nothing writes back - a header or footer story added or removed, an edited footnote or endnote separator - instead of saving the file without it. Check `exportProblems` before writing, or catch `DocxExportError`.
+
 ## 0.6.1
 
 ### Patch Changes

package/dist/core.d.ts

@@ -19,9 +19,10 @@ export type { ParagraphStyleOption } from "./docx/formatting";
 export type { DocxBytes, ImportOptions } from "./docx/importDocx";
 /**
  * What the writer would refuse the document over, asked ahead of the write. The first entry is
- * what `exportDocx` throws, so the two cannot disagree.
+ * what `exportDocx` throws, so the two cannot disagree. `reason` tells the situations one code
+ * covers apart and names the content each is about.
  */
-export type { ExportProblem } from "./docx/invariants";
+export type { ExportPartName, ExportProblem, ExportProblemReason, ExportProblemStory, ExportStoryKind, } from "./docx/invariants";
 export { exportProblems } from "./docx/invariants";
 export type { DocxSession } from "./docx/session";
 export { documentNumbering, documentPartPath } from "./docx/session";
@@ -29,7 +30,7 @@ export type { CellFormat, CellVerticalAlign, DocumentDefaults, HighlightName, Li
 export { toCellFormat, toParagraphFormat, toRowFormat, toRunFormat, toTableFormat, toTableWidth, } from "./model/format";
 export type { LevelAlign, LevelIndent, LevelSuffix, NewList, NewListLevel, NumberFormat, Numbering, NumberingLevel, NumberingList, NumberingOptions, NumberingStyleLinks, ReadLevelRun, } from "./numbering/parseNumbering";
 export { parseNumbering } from "./numbering/parseNumbering";
-export type { DocxExportErrorCode, DocxImportErrorCode, } from "./ooxml/errors";
+export type { DocxExportErrorCode, DocxExportErrorOptions, DocxImportErrorCode, } from "./ooxml/errors";
 export { DocxExportError, DocxImportError } from "./ooxml/errors";
 /**
  * An image node's size is written in EMU, the unit the document itself uses. A builder

package/dist/docx/exportDocx.d.ts

@@ -36,7 +36,7 @@ export declare function exportDocx(doc: PMNode, session: DocxSession, options?:
  *
  * The first problem `exportProblems` reports is thrown before anything is written, so a refusal a
  * caller could have asked about ahead of time arrives with the same code and message it would
- * have read there.
+ * have read there, and carries that entry as the error's `problem`.
  */
 export declare function exportDocxReport(doc: PMNode, session: DocxSession, options?: ExportOptions): {
     bytes: Uint8Array;

package/dist/docx/exportDocx.js

@@ -116,7 +116,9 @@ function reportThrough(planners, doc, session, options) {
   return withXmlParser(options?.xmlParser, () => {
     const store = sessionOf(session);
     const problem = problemsOf(doc, store)[0];
-    if (problem) throw new DocxExportError(problem.code, problem.message);
+    if (problem) {
+      throw new DocxExportError(problem.code, problem.message, { problem });
+    }
     const approximated = [];
     const bytes = writeDocx(
       doc,

package/dist/docx/identities.d.ts

@@ -61,6 +61,8 @@ export declare const IDENTITY_RULES: readonly IdentityRule[];
 export interface IdentityProblem {
     readonly code: DocxExportErrorCode;
     readonly message: string;
+    /** The node type standing twice, which `docx/invariants` names in the problem's reason */
+    readonly node: string;
     readonly pos: number;
 }
 /** The document with every later claimant of a name released, in document order */

package/dist/docx/identities.js

@@ -103,6 +103,7 @@ function refusalOf(block, pos) {
   return {
     code: "unsupported-content",
     message: `a preserved block stands in two places (${block.type.name})`,
+    node: block.type.name,
     pos
   };
 }

package/dist/docx/invariants.d.ts

@@ -5,27 +5,30 @@
  * would throw, so a screen can ask at edit time what `exportDocx` would say. The list is walked in
  * order and `exportDocx` throws its first entry, which is what keeps the two from disagreeing.
  *
+ * A code covers several situations, so each entry also carries the `ExportProblemReason`
+ * (`ooxml/errors`) naming the one that was met and the content it is about. Every place a problem
+ * is built names its own, rather than a reader telling them apart by the message.
+ *
+ * What the writer puts out block by block is the body and every side story a part writer rewrites
+ * (`exportScopes`), so the invariants over content are asked of each of those in turn: markup
+ * refused in the body is refused just the same out of a footnote or a header.
+ *
  * The checks inspect model attrs and preserved XML without running the writers. Bookmark
  * fragments and list definitions use the export parser. `assertBookmarkPairs` in `./exportDocx`
  * and `assertPartsParse` in `./partPlan` remain the final checks over the parts as actually written.
  */
 import type { Node as PMNode } from "prosemirror-model";
-import type { DocxExportErrorCode } from "../ooxml/errors";
+import type { ExportProblem } from "../ooxml/errors";
 import type { ExportOptions } from "./exportDocx";
 import { type DocxSession, type SessionStore } from "./session";
-/** One reason the document cannot be written back, with the code `exportDocx` would throw it under */
-export interface ExportProblem {
-    readonly code: DocxExportErrorCode;
-    readonly message: string;
-    /** Where the problem stands in the document. Absent for a problem of the package, of the session, or of a side story */
-    readonly pos?: number;
-}
+export type { ExportPartName, ExportProblem, ExportProblemReason, ExportProblemStory, ExportStoryKind, } from "../ooxml/errors";
 /** The problems as the writer sees them, for a caller already inside the writer's parser scope */
 export declare function problemsOf(doc: PMNode, session: SessionStore): readonly ExportProblem[];
 /**
  * Known reasons writing this document back would be refused, in the order `exportDocx` would
- * raise them. An empty list does not rule out failures while writing. Each entry carries the code and message the
- * `DocxExportError` would carry, and the position in the document where there is one.
+ * raise them. An empty list does not rule out failures while writing. Each entry carries the code
+ * and message the `DocxExportError` would carry, the `reason` naming what the refusal is about,
+ * and the position in the document where there is one.
  *
  * The list definitions are read to tell a new list from one the document already had, so this
  * needs an XML parser the way `exportDocx` does and takes the same option.