@portone/docx-editor 0.2.0 → 0.3.0

package/dist/editor/plugins/lockedContent.d.ts

@@ -1,8 +1,8 @@
 /**
- * Rejects transactions disallowed by the guard in `schema/locks`, which answers for the locks the
- * document carries and for the protection the editor runs under (`schema/protection`) alike. A
- * rejected IME edit also ends the browser composition on the next frame so ProseMirror cannot
- * remain stuck in composing state.
+ * Rejects transactions no guard `schema/guards` registers would let through, the locks the document
+ * carries and the protection the editor runs under (`schema/protection`) among them. A rejected IME
+ * edit also ends the browser composition on the next frame so ProseMirror cannot remain stuck in
+ * composing state.
  */
 import { Plugin } from "prosemirror-state";
 export declare function lockedContent(): Plugin;

package/dist/editor/plugins/lockedContent.js

@@ -1,6 +1,6 @@
 // src/editor/plugins/lockedContent.ts
 import { Plugin } from "prosemirror-state";
-import { transactionAllowed } from "../../schema/locks.js";
+import { transactionAllowed } from "../../schema/guards.js";
 function endComposition(view) {
   if (!view.composing) return;
   const marks = view.state.storedMarks ?? view.state.selection.$from.marks();

package/dist/editor/plugins/numberingDecorations.d.ts

@@ -1,11 +1,12 @@
 /**
  * Draws list markers and inherited indentation as decorations so display-only values never create
- * new OOXML on export. The plugin also exposes numbering definitions to list commands.
+ * new OOXML on export. The definitions the markers are drawn from belong to the document
+ * snapshot, and the readers list commands ask stand here beside the drawing.
  */
 import type { Node as PMNode } from "prosemirror-model";
 import { type EditorState, Plugin } from "prosemirror-state";
 import { DecorationSet } from "prosemirror-view";
-import { type Numbering } from "../../numbering/parseNumbering";
+import type { Numbering } from "../../numbering/parseNumbering";
 /** A number to draw on screen and the paragraph position it attaches to */
 export interface PlacedMarker {
     from: number;
@@ -22,13 +23,6 @@ export interface PlacedMarker {
 /** Walks a document to find the paragraphs that get numbers and what those numbers are */
 export declare function paragraphMarkers(doc: PMNode, numbering: Numbering): PlacedMarker[];
 export declare function markerDecorations(doc: PMNode, numbering: Numbering): DecorationSet;
-/** What the plugin holds: the document's list definitions and the numbers to draw right now */
-interface NumberingState {
-    numbering: Numbering;
-    /** Whether the document has a place (numbering.xml) to write the definition of a new list */
-    canStartNewList: boolean;
-    decorations: DecorationSet;
-}
 /** This document's list definitions. Empty when the editor does not know them */
 export declare function documentNumbering(state: EditorState): Numbering;
 /**
@@ -38,5 +32,5 @@ export declare function documentNumbering(state: EditorState): Numbering;
  * in the first place.
  */
 export declare function canStartNewList(state: EditorState): boolean;
-export declare function numberingMarkers(numbering?: Numbering, canStartNewList?: boolean): Plugin<NumberingState>;
-export {};
+/** Draws the numbers this document's lists put in front of their paragraphs */
+export declare function numberingMarkers(): Plugin<DecorationSet>;

package/dist/editor/plugins/numberingDecorations.js

@@ -3,10 +3,8 @@ import { Plugin, PluginKey } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 import { toParagraphFormat } from "../../model/format.js";
 import { computeMarkers } from "../../numbering/markers.js";
-import {
-  EMPTY_NUMBERING
-} from "../../numbering/parseNumbering.js";
 import { editorAttributes, editorCssVariables } from "../../styles/classNames.js";
+import { documentOf } from "../editorDocument.js";
 var FALLBACK_MARKER_WIDTH_PT = 18;
 function paragraphSpots(doc) {
   const spots = [];
@@ -76,28 +74,20 @@ function markerDecorations(doc, numbering) {
 }
 var numberingKey = new PluginKey("docxEditorNumbering");
 function documentNumbering(state) {
-  return numberingKey.getState(state)?.numbering ?? EMPTY_NUMBERING;
+  return documentOf(state).formatting.numbering;
 }
 function canStartNewList(state) {
-  return numberingKey.getState(state)?.canStartNewList ?? true;
+  return documentOf(state).canStartNewList;
 }
-function numberingMarkers(numbering = EMPTY_NUMBERING, canStartNewList2 = true) {
+function numberingMarkers() {
   return new Plugin({
     key: numberingKey,
     state: {
-      init: (_config, state) => ({
-        numbering,
-        canStartNewList: canStartNewList2,
-        decorations: markerDecorations(state.doc, numbering)
-      }),
-      apply: (tr, current) => tr.docChanged ? {
-        numbering,
-        canStartNewList: canStartNewList2,
-        decorations: markerDecorations(tr.doc, numbering)
-      } : current
+      init: (_config, state) => markerDecorations(state.doc, documentOf(state).formatting.numbering),
+      apply: (tr, current, _old, state) => tr.docChanged ? markerDecorations(tr.doc, documentOf(state).formatting.numbering) : current
     },
     props: {
-      decorations: (state) => numberingKey.getState(state)?.decorations
+      decorations: (state) => numberingKey.getState(state)
     }
   });
 }

package/dist/editor/plugins/paragraphDisplay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The values a paragraph draws with, read out of the document's styles along the same path the
+ * import takes (`docx/formatting`), so that a paragraph an edit built, one it re-aligned and one
+ * the file arrived with all carry the same values for the same properties.
+ */
+import type { DocumentDeriver } from "./displayDerivation";
+export declare const paragraphDisplay: DocumentDeriver;

package/dist/editor/plugins/paragraphDisplay.js

@@ -0,0 +1,51 @@
+// src/editor/plugins/paragraphDisplay.ts
+import {
+  paragraphAttrsOf,
+  resolveParagraph,
+  resolveRun
+} from "../../docx/formatting.js";
+import { docxSchema } from "../../schema/index.js";
+import { paragraphPPr } from "../paragraphEdits.js";
+function carriesNothing(node) {
+  return node.attrs.format === null && node.attrs.styleRun === null;
+}
+function stands(node, previous) {
+  return previous !== null && previous.attrs.pPr === node.attrs.pPr && !carriesNothing(node);
+}
+function holdsComposition(node, pos, composing) {
+  return composing !== null && composing >= pos && composing <= pos + node.nodeSize;
+}
+var paragraphDisplay = {
+  name: "paragraph",
+  nodeTypes: ["paragraph"],
+  derive(node, pos, _doc, context, previous) {
+    if (stands(node, previous) || holdsComposition(node, pos, context.composingAt)) {
+      return [];
+    }
+    const formatting = context.document.formatting;
+    const paragraph = resolveParagraph(paragraphPPr(node), formatting);
+    const derived = [
+      { pos, attrs: paragraphAttrsOf(paragraph) }
+    ];
+    node.forEach((child, offset) => {
+      const mark = docxSchema.marks.run.isInSet(child.marks);
+      if (!mark) return;
+      const rPr = mark.attrs.rPr;
+      derived.push({
+        pos: pos + 1 + offset,
+        mark: { type: mark.type, to: pos + 1 + offset + child.nodeSize },
+        attrs: {
+          format: resolveRun(
+            typeof rPr === "string" ? rPr : null,
+            paragraph,
+            formatting
+          )
+        }
+      });
+    });
+    return derived;
+  }
+};
+export {
+  paragraphDisplay
+};

package/dist/editor/plugins/tabLayout.js

@@ -1,12 +1,12 @@
 // src/editor/plugins/tabLayout.ts
 import { Plugin } from "prosemirror-state";
 import { DEFAULT_TAB_STOP_PT } from "../../docx/documentSettings.js";
+import { PX_PER_PT } from "../../docx/pageGeometry.js";
 import { toParagraphFormat } from "../../model/format.js";
 import { docxSchema } from "../../schema/index.js";
 import { editorClassNames, editorCssVariables } from "../../styles/classNames.js";
 import { documentDefaultTabStopPt } from "../documentStyles.js";
 import { setTabWidths, tabWidths } from "./tabDecorations.js";
-var PX_PER_PT = 96 / 72;
 var POSITION_EPSILON_PT = 0.01;
 var WIDTH_EPSILON_PX = 0.1;
 var NATURAL_WIDTH_PX = 1e5;

package/dist/editor/plugins/tableDisplay.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The lines a table's cells draw because of where they sit in the grid (`table/gridBorders`),
+ * derived again once the grid or the border inputs of the table moved.
+ */
+import type { DocumentDeriver } from "./displayDerivation";
+export declare const tableDisplay: DocumentDeriver;

package/dist/editor/plugins/tableDisplay.js

@@ -0,0 +1,16 @@
+// src/editor/plugins/tableDisplay.ts
+import { cellFixes, sameFormattingInputs } from "../../table/gridBorders.js";
+var tableDisplay = {
+  name: "table",
+  nodeTypes: ["table"],
+  derive(table, pos, _doc, _context, previous) {
+    if (previous !== null && sameFormattingInputs(previous, table)) return [];
+    return cellFixes(table).map((fix) => ({
+      pos: pos + 1 + fix.pos,
+      attrs: fix.attrs
+    }));
+  }
+};
+export {
+  tableDisplay
+};

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { EditorView } from "prosemirror-view";
 export type { DocxEditorHandle, DocxEditorMode, DocxEditorProps, } from "./DocxEditor";
 export { DocxEditor } from "./DocxEditor";
 export type { DocxBytes, DocxSource } from "./docx/importDocx";
+/** What the handle and a `blocked` download report: each reason the document cannot be written, under the code `DocxExportError` would throw it with */
+export type { ExportProblem } from "./docx/invariants";
 export type { DownloadDocxOptions, DownloadDocxResult, } from "./download";
 export { downloadDocx } from "./download";
 export type { CommentAuthor } from "./editor/commands/commentCommands";

package/dist/model/format.d.ts

@@ -11,7 +11,7 @@
  * declaration, the checks that let through only the shapes the read functions produce
  * live here alongside them.
  */
-import type { TabStop } from "./tabStops";
+import { type TabStop } from "./tabStops";
 declare const ALIGNS: readonly ["left", "center", "right", "justify"];
 export type ParagraphAlign = (typeof ALIGNS)[number];
 declare const VERTICAL_ALIGNS: readonly ["superscript", "subscript"];
@@ -103,6 +103,11 @@ export interface ParagraphFormat {
      * page boundary guides
      */
     pageBreakBefore?: true;
+    /**
+     * Set when the document asks for this paragraph to stand on the same page as the start of the
+     * block after it (`w:keepNext`). Read by the page boundary guides
+     */
+    keepNext?: boolean;
     /** A CSS border in the form `1pt solid #000000` */
     borderTop?: string;
     borderBottom?: string;
@@ -110,15 +115,26 @@ export interface ParagraphFormat {
     borderRight?: string;
     background?: string;
 }
-/** The character formatting to render on screen */
+/**
+ * The character formatting to render on screen.
+ *
+ * A toggle the run switches off outright (`w:val="0"`) is false rather than absent: absent means
+ * the run says nothing and what the style laid down stands, false is the run beating that style.
+ */
 export interface RunFormat {
-    bold?: true;
-    italic?: true;
-    /** The underline kind. Absent entirely when there is no underline */
-    underline?: UnderlineKind;
-    strike?: true;
-    smallCaps?: true;
+    bold?: boolean;
+    italic?: boolean;
+    /** The underline kind, or `none` for an underline switched off outright. Absent when the run says nothing */
+    underline?: UnderlineKind | "none";
+    strike?: boolean;
+    /** Two lines through the text (`w:dstrike`). Read from the document and not drawn or edited yet */
+    doubleStrike?: boolean;
+    smallCaps?: boolean;
+    /** Every letter drawn as a capital (`w:caps`). Read from the document and not drawn or edited yet */
+    caps?: boolean;
     fontSizePt?: number;
+    /** The room added between characters (`w:spacing`), below zero where they are drawn closer. Read from the document and not drawn or edited yet */
+    characterSpacingPt?: number;
     /** A CSS font name list in the form `"맑은 고딕","Malgun Gothic"` */
     fontFamily?: string;
     color?: string;
@@ -133,6 +149,12 @@ export interface RunFormat {
      */
     lang?: string;
 }
+/**
+ * Every key of `RunFormat`, in the order a run's properties are read. The run property table
+ * (`docx/formatting/runProperties`) walks this list, which lives here because `model` imports
+ * nothing above it.
+ */
+export declare const RUN_FORMAT_KEYS: readonly ["bold", "italic", "strike", "doubleStrike", "smallCaps", "caps", "underline", "fontSizePt", "characterSpacingPt", "fontFamily", "color", "highlight", "background", "verticalAlign", "lang"];
 /**
  * The table formatting to render on screen. The inner lines between cells are folded
  * into the cell formatting

package/dist/model/format.js

@@ -1,4 +1,5 @@
 // src/model/format.ts
+import { TAB_LEADERS, TAB_STOP_ALIGNMENTS } from "./tabStops.js";
 var ALIGNS = ["left", "center", "right", "justify"];
 var VERTICAL_ALIGNS = ["superscript", "subscript"];
 var CELL_VERTICAL_ALIGNS = ["top", "center", "bottom"];
@@ -56,6 +57,23 @@ function withWidthNumber(width, value) {
   if (width.type === "pct") return { type: "pct", fiftieths: value };
   return width;
 }
+var RUN_FORMAT_KEYS = [
+  "bold",
+  "italic",
+  "strike",
+  "doubleStrike",
+  "smallCaps",
+  "caps",
+  "underline",
+  "fontSizePt",
+  "characterSpacingPt",
+  "fontFamily",
+  "color",
+  "highlight",
+  "background",
+  "verticalAlign",
+  "lang"
+];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -89,22 +107,6 @@ function toNumberingRef(value) {
   if (typeof numId !== "number" || typeof ilvl !== "number") return null;
   return { numId, ilvl };
 }
-var TAB_ALIGNMENTS = [
-  "start",
-  "center",
-  "end",
-  "decimal",
-  "num",
-  "bar"
-];
-var TAB_LEADERS = [
-  "none",
-  "dot",
-  "hyphen",
-  "underscore",
-  "heavy",
-  "middleDot"
-];
 function toTabStops(value) {
   if (!Array.isArray(value)) return null;
   const stops = [];
@@ -112,7 +114,9 @@ function toTabStops(value) {
     if (!isRecord(entry) || typeof entry.positionPt !== "number" || !Number.isFinite(entry.positionPt)) {
       continue;
     }
-    const align = TAB_ALIGNMENTS.find((candidate) => candidate === entry.align);
+    const align = TAB_STOP_ALIGNMENTS.find(
+      (candidate) => candidate === entry.align
+    );
     if (!align) continue;
     const leader = TAB_LEADERS.find((candidate) => candidate === entry.leader);
     stops.push({
@@ -150,6 +154,7 @@ function toParagraphFormat(value) {
   const tabStops = toTabStops(value.tabStops);
   if (tabStops) format.tabStops = tabStops;
   if (value.pageBreakBefore === true) format.pageBreakBefore = true;
+  if (typeof value.keepNext === "boolean") format.keepNext = value.keepNext;
   copyBorders(value, format);
   const background = matching(FILL, value.background);
   if (background) format.background = background;
@@ -158,13 +163,20 @@ function toParagraphFormat(value) {
 function toRunFormat(value) {
   if (!isRecord(value)) return null;
   const format = {};
-  if (value.bold === true) format.bold = true;
-  if (value.italic === true) format.italic = true;
-  if (value.strike === true) format.strike = true;
-  if (value.smallCaps === true) format.smallCaps = true;
-  if (isUnderlineKind(value.underline)) format.underline = value.underline;
+  if (typeof value.bold === "boolean") format.bold = value.bold;
+  if (typeof value.italic === "boolean") format.italic = value.italic;
+  if (typeof value.strike === "boolean") format.strike = value.strike;
+  if (typeof value.doubleStrike === "boolean")
+    format.doubleStrike = value.doubleStrike;
+  if (typeof value.smallCaps === "boolean") format.smallCaps = value.smallCaps;
+  if (typeof value.caps === "boolean") format.caps = value.caps;
+  if (isUnderlineKind(value.underline) || value.underline === "none") {
+    format.underline = value.underline;
+  }
   if (typeof value.fontSizePt === "number")
     format.fontSizePt = value.fontSizePt;
+  if (typeof value.characterSpacingPt === "number")
+    format.characterSpacingPt = value.characterSpacingPt;
   const fontFamily = matching(FONT_FAMILY, value.fontFamily);
   if (fontFamily) format.fontFamily = fontFamily;
   const color = matching(HEX_COLOR, value.color);
@@ -287,6 +299,7 @@ function spanCount(value) {
 }
 export {
   NO_FILL,
+  RUN_FORMAT_KEYS,
   isHighlightName,
   isUnderlineKind,
   spanCount,

package/dist/model/tabStops.d.ts

@@ -6,6 +6,15 @@ export interface TabStop {
     align: TabAlignment | "bar";
     leader?: TabLeader;
 }
+/**
+ * What a stop may be aligned to, and what it may draw the space it covers with.
+ *
+ * These are the members of the two unions above, listed so that a reader checking a value against
+ * them cannot fall out of step with the types. `ooxml/simpleTypes` builds `ST_TabJc` and
+ * `ST_TabTlc` on them, adding the spellings the document writes that the model does not keep.
+ */
+export declare const TAB_STOP_ALIGNMENTS: readonly TabStop["align"][];
+export declare const TAB_LEADERS: readonly TabLeader[];
 /** A tab entry before the paragraph-property hierarchy has been resolved. */
 export type TabStopDirective = TabStop | {
     positionPt: number;

package/dist/model/tabStops.js

@@ -1,4 +1,20 @@
 // src/model/tabStops.ts
+var TAB_STOP_ALIGNMENTS = [
+  "start",
+  "center",
+  "end",
+  "decimal",
+  "num",
+  "bar"
+];
+var TAB_LEADERS = [
+  "none",
+  "dot",
+  "hyphen",
+  "underscore",
+  "heavy",
+  "middleDot"
+];
 function layerTabStopDirectives(base, over) {
   const stops = /* @__PURE__ */ new Map();
   for (const stop of base) {
@@ -17,6 +33,8 @@ function mergeTabStops(base, over) {
   );
 }
 export {
+  TAB_LEADERS,
+  TAB_STOP_ALIGNMENTS,
   layerTabStopDirectives,
   mergeTabStops
 };

package/dist/numbering/listTemplate.js

@@ -1,4 +1,7 @@
 // src/numbering/listTemplate.ts
+import { elementXml } from "../ooxml/element.js";
+import { wName } from "../ooxml/names.js";
+import { orderedElement } from "../ooxml/props.js";
 var LEVEL_COUNT = 9;
 var MAX_ILVL = LEVEL_COUNT - 1;
 var NUMBER_CYCLE = [
@@ -51,25 +54,61 @@ function nextNumId(used, kind) {
   return listKindOf(from) === kind ? from : from + 1;
 }
 function indXml(indent) {
-  const attrs = [
-    ["w:left", indent?.startTwips],
-    ["w:right", indent?.endTwips],
-    ["w:hanging", indent?.hangingTwips],
-    ["w:firstLine", indent?.firstLineTwips]
-  ].filter((entry) => typeof entry[1] === "number").map(([name, value]) => `${name}="${value}"`).join(" ");
-  return attrs === "" ? "" : `<w:pPr><w:ind ${attrs}/></w:pPr>`;
+  const slots = [
+    ["left", indent?.startTwips ?? null],
+    ["right", indent?.endTwips ?? null],
+    ["hanging", indent?.hangingTwips ?? null],
+    ["firstLine", indent?.firstLineTwips ?? null]
+  ];
+  const attrs = slots.filter((slot) => slot[1] !== null).map(([name, twips]) => [wName(name), `${twips}`]);
+  if (attrs.length === 0) return "";
+  return orderedElement(
+    wName("pPr"),
+    [],
+    [{ name: "ind", xml: elementXml(wName("ind"), attrs) }]
+  );
 }
 function levelXml(ilvl, level) {
   const ind = indXml(level.indent);
-  return `<w:lvl w:ilvl="${ilvl}"><w:start w:val="${level.start}"/><w:numFmt w:val="${level.format}"/><w:lvlText w:val="${level.text}"/><w:lvlJc w:val="left"/>${ind}</w:lvl>`;
+  return orderedElement(
+    wName("lvl"),
+    [[wName("ilvl"), `${ilvl}`]],
+    [
+      {
+        name: "start",
+        xml: elementXml(wName("start"), [[wName("val"), `${level.start}`]])
+      },
+      {
+        name: "numFmt",
+        xml: elementXml(wName("numFmt"), [[wName("val"), level.format]])
+      },
+      {
+        name: "lvlText",
+        xml: elementXml(wName("lvlText"), [[wName("val"), level.text]])
+      },
+      {
+        name: "lvlJc",
+        xml: elementXml(wName("lvlJc"), [[wName("val"), "left"]])
+      },
+      ...ind === "" ? [] : [{ name: "pPr", xml: ind }]
+    ]
+  );
 }
 function abstractNumXml(abstractNumId, kind) {
   const levels = TEMPLATES[kind].levels;
   const body = Array.from(levels.entries()).map(([ilvl, level]) => levelXml(ilvl, level)).join("");
-  return `<w:abstractNum w:abstractNumId="${abstractNumId}">${body}</w:abstractNum>`;
+  return elementXml(
+    wName("abstractNum"),
+    [[wName("abstractNumId"), `${abstractNumId}`]],
+    [body]
+  );
 }
 function numXml(numId, abstractNumId) {
-  return `<w:num w:numId="${numId}"><w:abstractNumId w:val="${abstractNumId}"/></w:num>`;
+  return elementXml(
+    wName("num"),
+    [[wName("numId"), `${numId}`]],
+    [elementXml(wName("abstractNumId"), [[wName("val"), `${abstractNumId}`]])]
+  );
 }
 export {
   LEVEL_COUNT,

package/dist/numbering/parseNumbering.d.ts

@@ -6,6 +6,7 @@
  * disturbs the file.
  */
 import type { TabStopDirective } from "../model/tabStops";
+import { type XmlParser } from "../ooxml/xml";
 /** The number formats actually used across every fixture */
 declare const NUMBER_FORMATS: readonly ["decimal", "bullet", "lowerLetter", "upperLetter", "lowerRoman"];
 export type NumberFormat = (typeof NUMBER_FORMATS)[number];
@@ -61,5 +62,17 @@ export declare const NO_LEVEL_INDENT: LevelIndentPt;
  * OOXML rule).
  */
 export declare function levelIndentPt(indent: LevelIndent | null): LevelIndentPt;
-export declare function parseNumbering(xml: string | null): Numbering;
+/** What a caller may say about reading numbering beyond handing over the XML */
+export interface NumberingOptions {
+    /**
+     * The parser the numbering XML is read through. Left out, the `DOMParser` global is used, and a
+     * runtime carrying none refuses the read with `no-xml-parser`.
+     */
+    xmlParser?: XmlParser;
+}
+/**
+ * The lists this numbering XML defines. `null` is the document that has no numbering part, which
+ * defines none and asks nothing of a parser.
+ */
+export declare function parseNumbering(xml: string | null, options?: NumberingOptions): Numbering;
 export {};