@portone/docx-editor 0.6.1 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/dist/DocxEditor.js +2 -2
  3. package/dist/core.d.ts +4 -3
  4. package/dist/docx/exportDocx.d.ts +1 -1
  5. package/dist/docx/exportDocx.js +3 -1
  6. package/dist/docx/headersFooters.js +4 -14
  7. package/dist/docx/identities.d.ts +10 -2
  8. package/dist/docx/identities.js +32 -11
  9. package/dist/docx/importPolicy.d.ts +2 -2
  10. package/dist/docx/importPolicy.js +12 -5
  11. package/dist/docx/importPreserved.d.ts +3 -3
  12. package/dist/docx/importSdtBlock.d.ts +24 -0
  13. package/dist/docx/importSdtBlock.js +42 -0
  14. package/dist/docx/importTable.js +35 -24
  15. package/dist/docx/invariants.d.ts +13 -10
  16. package/dist/docx/invariants.js +269 -126
  17. package/dist/docx/newLists.js +12 -3
  18. package/dist/docx/notes/numbering.js +5 -12
  19. package/dist/docx/notes/references.d.ts +31 -0
  20. package/dist/docx/notes/references.js +32 -0
  21. package/dist/docx/notes/writing.js +5 -6
  22. package/dist/docx/sdt.d.ts +52 -9
  23. package/dist/docx/sdt.js +108 -26
  24. package/dist/docx/sections.d.ts +13 -13
  25. package/dist/docx/sections.js +34 -20
  26. package/dist/docx/serializeBlock.js +9 -1
  27. package/dist/docx/serializePreserved.d.ts +5 -1
  28. package/dist/docx/serializePreserved.js +24 -7
  29. package/dist/docx/serializeSdtBlock.d.ts +24 -0
  30. package/dist/docx/serializeSdtBlock.js +15 -0
  31. package/dist/docx/serializeTable.d.ts +8 -2
  32. package/dist/docx/serializeTable.js +14 -20
  33. package/dist/docx/story.d.ts +10 -4
  34. package/dist/docx/story.js +25 -20
  35. package/dist/docx/storyBlocks.d.ts +32 -0
  36. package/dist/docx/storyBlocks.js +65 -0
  37. package/dist/docx/storyParts.d.ts +29 -8
  38. package/dist/docx/storyParts.js +40 -15
  39. package/dist/docx/wrappers.d.ts +10 -7
  40. package/dist/docx/wrappers.js +15 -27
  41. package/dist/editor/blockControlEdits.d.ts +15 -0
  42. package/dist/editor/blockControlEdits.js +79 -0
  43. package/dist/editor/clipboard/normalizers.js +1 -1
  44. package/dist/editor/commands/exportQueries.d.ts +4 -3
  45. package/dist/editor/commands/index.d.ts +1 -1
  46. package/dist/editor/commands/lockCommands.d.ts +5 -1
  47. package/dist/editor/commands/lockCommands.js +27 -19
  48. package/dist/editor/createEditor.js +4 -0
  49. package/dist/editor/notes/noteSurface.js +4 -3
  50. package/dist/editor/plugins/controlLifecycle.d.ts +18 -0
  51. package/dist/editor/plugins/controlLifecycle.js +130 -0
  52. package/dist/editor/plugins/keymap.js +23 -5
  53. package/dist/editor/plugins/rowResize.js +2 -4
  54. package/dist/editor/stories/storyState.d.ts +2 -0
  55. package/dist/editor/stories/storyState.js +2 -0
  56. package/dist/index.d.ts +2 -2
  57. package/dist/ooxml/errors.d.ts +135 -2
  58. package/dist/ooxml/errors.js +6 -0
  59. package/dist/page/blockKinds.d.ts +24 -2
  60. package/dist/page/blockKinds.js +6 -1
  61. package/dist/page/kinds/index.d.ts +5 -0
  62. package/dist/page/kinds/index.js +2 -0
  63. package/dist/page/kinds/sdtBlockKind.d.ts +14 -0
  64. package/dist/page/kinds/sdtBlockKind.js +143 -0
  65. package/dist/page/measureBlocks.js +4 -2
  66. package/dist/page/pageDecorations.js +3 -2
  67. package/dist/page/pageLayout.d.ts +16 -15
  68. package/dist/page/pageLayout.js +134 -67
  69. package/dist/page/usePageLayout.d.ts +2 -2
  70. package/dist/page/usePageLayout.js +5 -5
  71. package/dist/schema/attrRoles.js +45 -1
  72. package/dist/schema/clipboard.js +9 -0
  73. package/dist/schema/controlAttrs.d.ts +105 -0
  74. package/dist/schema/controlAttrs.js +129 -0
  75. package/dist/schema/controlEdges.d.ts +22 -0
  76. package/dist/schema/controlEdges.js +50 -0
  77. package/dist/schema/docxSchema.d.ts +1 -1
  78. package/dist/schema/docxSchema.js +180 -37
  79. package/dist/schema/editGuard.d.ts +1 -1
  80. package/dist/schema/guards.js +2 -0
  81. package/dist/schema/locks.d.ts +22 -6
  82. package/dist/schema/locks.js +88 -47
  83. package/dist/schema/stories.d.ts +11 -3
  84. package/dist/schema/stories.js +9 -3
  85. package/dist/styles/classNames.d.ts +8 -0
  86. package/dist/styles/classNames.js +8 -0
  87. package/dist/styles.css +31 -2
  88. package/dist/table/merge.js +11 -3
  89. package/dist/table/rowResize.d.ts +9 -0
  90. package/dist/table/rowResize.js +9 -5
  91. package/dist/ui/TextMenu.js +2 -0
  92. package/package.json +3 -3
@@ -23,6 +23,12 @@ export interface BreakCandidate {
23
23
  offset: number;
24
24
  /** A forced candidate always cuts; an optional one cuts only when the piece after it would overflow */
25
25
  forced: boolean;
26
+ /**
27
+ * The document asks for the pieces either side to stand on one page (`w:keepNext`, §17.3.1.14),
28
+ * so the layout cuts here only when no page can hold what is kept together. A kind whose
29
+ * candidates never are leaves it out
30
+ */
31
+ kept?: boolean;
26
32
  /** Height the continued piece carries onto the next page ahead of its own content (a repeated header) */
27
33
  repeatHeight: number;
28
34
  }
@@ -62,6 +68,8 @@ export interface MeasureTarget {
62
68
  node: PMNode;
63
69
  pos: number;
64
70
  dom: HTMLElement;
71
+ /** The kinds the editor was built with, which a container measures what it holds by */
72
+ kinds: readonly BlockKind[];
65
73
  /**
66
74
  * Sheet coordinates from viewport coordinates: the visual scale taken out, and everything the
67
75
  * engine has opened up above this block taken back off
@@ -79,6 +87,13 @@ export interface KindMeasure {
79
87
  minFirstPiece: number;
80
88
  /** The block holds a break it could not open a space at, so the next block starts a page */
81
89
  breakAfter: boolean;
90
+ /**
91
+ * The block opens a page because what it starts with says so, which the sheet cannot read off
92
+ * the block's own element: a container draws no properties of its own, so a control whose first
93
+ * block asks for a page is the one place this is not the block's own attribute
94
+ * (`page/measureBlocks`). A kind whose blocks never do leaves it out
95
+ */
96
+ breakBefore?: boolean;
82
97
  /** Height the engine's own marks add inside this block, taken off its measured bottom */
83
98
  appliedHeight: number;
84
99
  /**
@@ -110,13 +125,20 @@ export interface BlockKind {
110
125
  matches(node: PMNode): boolean;
111
126
  measure(target: MeasureTarget): KindMeasure;
112
127
  /** Whether `at` still names a place this kind can cut at in `doc`; a false drops the cut */
113
- holdsCut(doc: PMNode, at: number): boolean;
128
+ holdsCut(doc: PMNode, at: number, kinds: readonly BlockKind[]): boolean;
114
129
  /**
115
130
  * The decorations one block of this kind carries: the cuts the layout gave it, plus whatever it
116
131
  * needs before any measurement (a paragraph puts an empty space on every page `br`, so the
117
132
  * measurement has an element to read it off).
118
133
  */
119
- decorate(pos: number, node: PMNode, cuts: readonly PageCut[], into: Decoration[]): void;
134
+ decorate(pos: number, node: PMNode, cuts: readonly PageCut[], into: Decoration[], kinds: readonly BlockKind[]): void;
120
135
  }
136
+ /**
137
+ * Whether a block opens a page of its own: what it wrote onto its own element, or what its kind
138
+ * had to answer for it. A container draws none of the paragraph properties of the blocks it
139
+ * holds, so a control whose first block asks for a page is the one place the sheet cannot read
140
+ * the break off the element, and both halves of the rule are needed at every level of nesting.
141
+ */
142
+ export declare function opensPage(dom: HTMLElement, measured: KindMeasure): boolean;
121
143
  /** The first kind whose `matches` answers. The kind registered last has to match every block */
122
144
  export declare function blockKindFor(kinds: readonly BlockKind[], node: PMNode): BlockKind;
@@ -1,4 +1,8 @@
1
1
  // src/page/blockKinds.ts
2
+ import { editorAttributes } from "../styles/classNames.js";
3
+ function opensPage(dom, measured) {
4
+ return dom.hasAttribute(editorAttributes.pageBreakBefore) || measured.breakBefore === true;
5
+ }
2
6
  function blockKindFor(kinds, node) {
3
7
  const found = kinds.find((kind) => kind.matches(node));
4
8
  if (!found) {
@@ -7,5 +11,6 @@ function blockKindFor(kinds, node) {
7
11
  return found;
8
12
  }
9
13
  export {
10
- blockKindFor
14
+ blockKindFor,
15
+ opensPage
11
16
  };
@@ -2,5 +2,10 @@ import type { BlockKind } from "../blockKinds";
2
2
  /**
3
3
  * The block shapes the editor pages, in the order they are asked. A new kind goes ahead of the
4
4
  * kinds it is narrower than, and the last one claims every block none of the others did.
5
+ *
6
+ * A content control is a container of blocks, and pages what it holds by the very list the editor
7
+ * was built with (`page/pageDecorations`), which is handed to it with the block: a kind a consumer
8
+ * registered ahead of these claims a block standing inside a control exactly as it claims the same
9
+ * block standing under the body.
5
10
  */
6
11
  export declare const DEFAULT_BLOCK_KINDS: readonly BlockKind[];
@@ -1,7 +1,9 @@
1
1
  // src/page/kinds/index.ts
2
2
  import { paragraphKind } from "./paragraphKind.js";
3
+ import { sdtBlockKind } from "./sdtBlockKind.js";
3
4
  import { tableKind } from "./tableKind.js";
4
5
  var DEFAULT_BLOCK_KINDS = [
6
+ sdtBlockKind,
5
7
  tableKind,
6
8
  paragraphKind
7
9
  ];
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The kind of a block-level content control: it is parted wherever the blocks it holds are.
3
+ *
4
+ * The container draws no box of its own - no padding, no border, no margin, and what a shut
5
+ * control wears is an outline and a background, which take no room (`styles/editor.css`) - so the
6
+ * control stands exactly as tall as the blocks inside it and a child's offset within it needs
7
+ * nothing subtracted for chrome.
8
+ *
9
+ * Nothing therefore has to be drawn at a cut. The outline is one box around everything the control
10
+ * holds, so it runs down both pieces and closes under the last of them, and only the background a
11
+ * shut control paints has to be broken, which the space opened at the cut does.
12
+ */
13
+ import { type BlockKind } from "../blockKinds";
14
+ export declare const sdtBlockKind: BlockKind;
@@ -0,0 +1,143 @@
1
+ // src/page/kinds/sdtBlockKind.ts
2
+ import { Decoration } from "prosemirror-view";
3
+ import { isBlockControl } from "../../schema/controlAttrs.js";
4
+ import { editorAttributes } from "../../styles/classNames.js";
5
+ import {
6
+ blockKindFor,
7
+ opensPage
8
+ } from "../blockKinds.js";
9
+ var CONTAINER_SPACE = editorAttributes.containerPageSpace;
10
+ function spaceAbove(dom, scale) {
11
+ let total = 0;
12
+ let sibling = dom.previousElementSibling;
13
+ while (sibling instanceof HTMLElement && sibling.hasAttribute(CONTAINER_SPACE)) {
14
+ total += sibling.getBoundingClientRect().height / scale;
15
+ sibling = sibling.previousElementSibling;
16
+ }
17
+ return total;
18
+ }
19
+ function heldBlocks(view, node, pos) {
20
+ const found = [];
21
+ node.forEach((child, offset, index) => {
22
+ const dom = view.nodeDOM(pos + 1 + offset);
23
+ if (dom instanceof HTMLElement) {
24
+ found.push({ node: child, pos: pos + 1 + offset, dom, index });
25
+ }
26
+ });
27
+ return found;
28
+ }
29
+ function containerSpace(height) {
30
+ const space = document.createElement("div");
31
+ space.setAttribute(CONTAINER_SPACE, `${height}`);
32
+ space.setAttribute("aria-hidden", "true");
33
+ space.setAttribute("contenteditable", "false");
34
+ space.style.height = `${height}px`;
35
+ return space;
36
+ }
37
+ function heldCut(container, containerPos, doc, at, kinds) {
38
+ let holds = false;
39
+ container.forEach((child, offset, index) => {
40
+ if (holds) return;
41
+ const childPos = containerPos + 1 + offset;
42
+ if (at === childPos) holds = index > 0;
43
+ else if (at > childPos && at < childPos + child.nodeSize) {
44
+ holds = isBlockControl(child) ? heldCut(child, childPos, doc, at, kinds) : blockKindFor(kinds, child).holdsCut(doc, at, kinds);
45
+ }
46
+ });
47
+ return holds;
48
+ }
49
+ var sdtBlockKind = {
50
+ name: "sdtBlock",
51
+ matches: isBlockControl,
52
+ measure({ view, node, pos, dom, kinds, sheetY, top, scale }) {
53
+ const candidates = [];
54
+ const opened = /* @__PURE__ */ new Map();
55
+ let appliedHeight = 0;
56
+ let minFirstPiece = dom.getBoundingClientRect().height / scale;
57
+ let keepWithNext = false;
58
+ let breakBefore = false;
59
+ let breakAfter = false;
60
+ for (const held of heldBlocks(view, node, pos)) {
61
+ const space = spaceAbove(held.dom, scale);
62
+ appliedHeight += space;
63
+ const above = appliedHeight;
64
+ const heldY = (viewportY) => sheetY(viewportY) - above;
65
+ const heldTop = heldY(held.dom.getBoundingClientRect().top);
66
+ const measured = blockKindFor(kinds, held.node).measure({
67
+ view,
68
+ node: held.node,
69
+ pos: held.pos,
70
+ dom: held.dom,
71
+ kinds,
72
+ sheetY: heldY,
73
+ top: heldTop,
74
+ scale
75
+ });
76
+ const forced = breakAfter || opensPage(held.dom, measured);
77
+ if (held.index === 0) {
78
+ breakBefore = forced;
79
+ minFirstPiece = heldTop - top + measured.minFirstPiece;
80
+ } else {
81
+ candidates.push({
82
+ at: held.pos,
83
+ offset: heldTop - top,
84
+ forced,
85
+ // A keep the block above asks for (§17.3.1.14) closes the boundary under it unless no
86
+ // page can hold what is kept, which is the layout's to decide (`page/pageLayout`)
87
+ ...!forced && keepWithNext ? { kept: true } : {},
88
+ repeatHeight: 0
89
+ });
90
+ if (space > 0) opened.set(held.pos, space);
91
+ }
92
+ for (const candidate of measured.candidates) {
93
+ candidates.push({
94
+ ...candidate,
95
+ offset: heldTop - top + candidate.offset
96
+ });
97
+ }
98
+ for (const [at, height] of measured.opened ?? []) opened.set(at, height);
99
+ appliedHeight += measured.appliedHeight;
100
+ breakAfter = measured.breakAfter;
101
+ keepWithNext = measured.keepWithNext ?? false;
102
+ }
103
+ return {
104
+ candidates,
105
+ opened,
106
+ minFirstPiece,
107
+ breakAfter,
108
+ breakBefore,
109
+ appliedHeight,
110
+ keepWithNext
111
+ };
112
+ },
113
+ // Only the kind of the block a cut stands in is asked (`page/pageDecorations`), so the control
114
+ // asked here is the top-level one and the walk goes down from it rather than up from the cut
115
+ holdsCut(doc, at, kinds) {
116
+ const $at = doc.resolve(at);
117
+ if ($at.depth === 0) return false;
118
+ const container = $at.node(1);
119
+ return isBlockControl(container) && heldCut(container, $at.before(1), doc, at, kinds);
120
+ },
121
+ decorate(pos, node, cuts, into, kinds) {
122
+ node.forEach((child, offset, index) => {
123
+ const childPos = pos + 1 + offset;
124
+ const inside = [];
125
+ for (const cut of cuts) {
126
+ if (cut.at === childPos && index > 0) {
127
+ into.push(
128
+ Decoration.widget(childPos, () => containerSpace(cut.height), {
129
+ key: `container-page-space-${childPos}-${cut.height}`,
130
+ side: -100
131
+ })
132
+ );
133
+ } else if (cut.at > childPos && cut.at < childPos + child.nodeSize) {
134
+ inside.push(cut);
135
+ }
136
+ }
137
+ blockKindFor(kinds, child).decorate(childPos, child, inside, into, kinds);
138
+ });
139
+ }
140
+ };
141
+ export {
142
+ sdtBlockKind
143
+ };
@@ -2,7 +2,8 @@
2
2
  import { editorAttributes } from "../styles/classNames.js";
3
3
  import { visualScaleOf } from "../styles/visualScale.js";
4
4
  import {
5
- blockKindFor
5
+ blockKindFor,
6
+ opensPage
6
7
  } from "./blockKinds.js";
7
8
  import { blockKindsOf, demandSourcesOf } from "./pageDecorations.js";
8
9
  var NOTHING_OPENED = /* @__PURE__ */ new Map();
@@ -59,6 +60,7 @@ function measureSheet(view, layer) {
59
60
  node,
60
61
  pos,
61
62
  dom,
63
+ kinds,
62
64
  sheetY: blockY,
63
65
  top,
64
66
  scale
@@ -70,7 +72,7 @@ function measureSheet(view, layer) {
70
72
  pos,
71
73
  gap: top - previousBottom,
72
74
  height: bottom - top,
73
- breakBefore: dom.hasAttribute(editorAttributes.pageBreakBefore),
75
+ breakBefore: opensPage(dom, measured),
74
76
  breakAfter: measured.breakAfter,
75
77
  candidates: measured.candidates,
76
78
  minFirstPiece: measured.minFirstPiece,
@@ -42,7 +42,8 @@ function decorationsFor(doc, kinds, pushes, cuts) {
42
42
  offset,
43
43
  node,
44
44
  byBlock.get(offset) ?? [],
45
- decorations
45
+ decorations,
46
+ kinds
46
47
  );
47
48
  });
48
49
  return DecorationSet.create(doc, decorations);
@@ -60,7 +61,7 @@ function stillCuts(kinds, doc, at) {
60
61
  const $at = doc.resolve(at);
61
62
  if ($at.depth === 0) return false;
62
63
  const block = doc.nodeAt($at.before(1));
63
- return block !== null && blockKindFor(kinds, block).holdsCut(doc, at);
64
+ return block !== null && blockKindFor(kinds, block).holdsCut(doc, at, kinds);
64
65
  }
65
66
  function retainsContent(tr, at, mapped) {
66
67
  const node = tr.before.nodeAt(at);
@@ -8,9 +8,11 @@
8
8
  *
9
9
  * The size of a page is the document's own (`docx/pageGeometry`), not a fixed A4: a Letter
10
10
  * document breaks at Letter's height and fits its tables to Letter's width. A document written in
11
- * several sections breaks each block at the height of the section that block sits in
11
+ * several sections breaks each piece of a block at the height of the section that piece sits in
12
12
  * (`docx/sections`), and a section opens a page of its own unless it declares `continuous`, which
13
- * carries it on down the page the section before it ends on.
13
+ * carries it on down the page the section before it ends on. A section ending inside a content
14
+ * control parts the control there, so what it holds after that paragraph stands on the next
15
+ * section's paper while the control stays one block.
14
16
  *
15
17
  * The width is the exception: one sheet is drawn at one width (`styles/editor.css`), which is the
16
18
  * first section's, so a section on wider paper is paginated on its own height but drawn on the
@@ -72,11 +74,8 @@ export declare const A4_SECTION_PIXELS: readonly SectionPixels[];
72
74
  * rather than once per measurement.
73
75
  */
74
76
  export declare function sectionPixels(sections: readonly DocumentSection[]): SectionPixels[];
75
- /**
76
- * The paper the block at this position is laid out on, which is the paper of every page that
77
- * block stands on. A4 where the list names no section at all.
78
- */
79
- export declare function sectionPaperAt(sections: readonly SectionPixels[], pos: number): PagePixels;
77
+ /** The paper of the section at this index (`PageStart.section`), A4 where the list names none */
78
+ export declare function sectionPaper(sections: readonly SectionPixels[], index: number): PagePixels;
80
79
  /**
81
80
  * The paper the document names, as the CSS variables the sheet is drawn from.
82
81
  *
@@ -113,10 +112,11 @@ export interface PageStart {
113
112
  /** Where this page's body starts, measured from the top of the body */
114
113
  bodyStart: number;
115
114
  /**
116
- * The position of the block this page opens with, which is the block the text crossing into it
117
- * belongs to. 0 for a document holding no block at all
115
+ * The index of the section this page opens in, which is the one its header and footer come
116
+ * from. A page opened inside a block belongs to the section of the piece it opens with, so two
117
+ * pages opening inside one content control can belong to two sections
118
118
  */
119
- pos: number;
119
+ section: number;
120
120
  /**
121
121
  * The place this page takes within its own section, counted from 1 again at every section it
122
122
  * opens. A document read with no section table at all is one section, so this counts the whole
@@ -198,9 +198,9 @@ export interface PageLayout {
198
198
  export interface PageLayoutInput {
199
199
  blocks: readonly MeasuredBlock[];
200
200
  /**
201
- * The paper of each section in document order (`sectionPixels`). A block is laid out on the
202
- * paper of the section it sits in, and the section a block opens starts a page of its own
203
- * unless that section is `continuous`.
201
+ * The paper of each section in document order (`sectionPixels`). Each piece of a block is laid
202
+ * out on the paper of the section it sits in, and the section a piece opens starts a page of its
203
+ * own unless that section is `continuous`.
204
204
  */
205
205
  sections: readonly SectionPixels[];
206
206
  /**
@@ -227,8 +227,9 @@ export interface PageLayoutInput {
227
227
  * a row boundary in a table - is taken only where the piece after it would run off the page.
228
228
  * A block kept with the next one is pushed together with what it is kept with: the blocks kept
229
229
  * after it and the first piece of the block the keeps end at.
230
- * Each block is measured against the paper of its own section, and the first block of a section
231
- * opens a page of its own unless the section it opens declares `continuous`.
230
+ * Each piece of a block is measured against the paper of its own section, and the first piece of a
231
+ * section opens a page of its own unless the section it opens declares `continuous`. A section
232
+ * that ends inside a block, at a paragraph a content control holds, parts the block there.
232
233
  *
233
234
  * A demand (`page/demands`) asks the page its place lands on for room at the foot, and that page's
234
235
  * body ends above the room: whatever would stand in it is pushed, parted or crossed onto the next