@folijs/core 0.6.0 → 1.0.0

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 (190) hide show
  1. package/CHANGELOG.md +159 -0
  2. package/README.md +1 -1
  3. package/dist/document.d.ts +0 -7
  4. package/dist/document.d.ts.map +1 -1
  5. package/dist/document.js +5 -1
  6. package/dist/document.js.map +1 -1
  7. package/dist/index.d.ts +4 -4
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +8 -4
  10. package/dist/index.js.map +1 -1
  11. package/dist/internal.d.ts +5 -0
  12. package/dist/internal.d.ts.map +1 -0
  13. package/dist/internal.js +7 -0
  14. package/dist/internal.js.map +1 -0
  15. package/dist/model/attrs.d.ts +0 -10
  16. package/dist/model/attrs.d.ts.map +1 -1
  17. package/dist/model/attrs.js +10 -2
  18. package/dist/model/attrs.js.map +1 -1
  19. package/dist/model/content.d.ts +1 -1
  20. package/dist/model/content.d.ts.map +1 -1
  21. package/dist/model/content.js +1 -1
  22. package/dist/model/content.js.map +1 -1
  23. package/dist/model/errors.d.ts +0 -2
  24. package/dist/model/errors.d.ts.map +1 -1
  25. package/dist/model/errors.js +4 -1
  26. package/dist/model/errors.js.map +1 -1
  27. package/dist/model/fragment.d.ts +1 -1
  28. package/dist/model/fragment.d.ts.map +1 -1
  29. package/dist/model/fragment.js +3 -1
  30. package/dist/model/fragment.js.map +1 -1
  31. package/dist/model/mark.d.ts +1 -1
  32. package/dist/model/mark.d.ts.map +1 -1
  33. package/dist/model/mark.js +1 -1
  34. package/dist/model/mark.js.map +1 -1
  35. package/dist/model/node.d.ts +4 -4
  36. package/dist/model/node.d.ts.map +1 -1
  37. package/dist/model/node.js +8 -4
  38. package/dist/model/node.js.map +1 -1
  39. package/dist/model/schema.d.ts +8 -8
  40. package/dist/model/schema.d.ts.map +1 -1
  41. package/dist/model/schema.js +4 -3
  42. package/dist/model/schema.js.map +1 -1
  43. package/dist/schema.d.ts +0 -11
  44. package/dist/schema.d.ts.map +1 -1
  45. package/dist/schema.js +2 -0
  46. package/dist/schema.js.map +1 -1
  47. package/dist/state/attempt.d.ts +1 -3
  48. package/dist/state/attempt.d.ts.map +1 -1
  49. package/dist/state/comments.d.ts +1 -7
  50. package/dist/state/comments.d.ts.map +1 -1
  51. package/dist/state/comments.js +1 -0
  52. package/dist/state/comments.js.map +1 -1
  53. package/dist/state/controls.d.ts +1 -19
  54. package/dist/state/controls.d.ts.map +1 -1
  55. package/dist/state/controls.js +21 -7
  56. package/dist/state/controls.js.map +1 -1
  57. package/dist/state/editor.d.ts +107 -72
  58. package/dist/state/editor.d.ts.map +1 -1
  59. package/dist/state/editor.js +121 -61
  60. package/dist/state/editor.js.map +1 -1
  61. package/dist/state/fields.d.ts +1 -12
  62. package/dist/state/fields.d.ts.map +1 -1
  63. package/dist/state/fields.js +16 -4
  64. package/dist/state/fields.js.map +1 -1
  65. package/dist/state/fieldupdate.d.ts +1 -47
  66. package/dist/state/fieldupdate.d.ts.map +1 -1
  67. package/dist/state/fieldupdate.js +1 -0
  68. package/dist/state/fieldupdate.js.map +1 -1
  69. package/dist/state/find.d.ts +1 -3
  70. package/dist/state/find.d.ts.map +1 -1
  71. package/dist/state/find.js +10 -2
  72. package/dist/state/find.js.map +1 -1
  73. package/dist/state/history.d.ts +1 -10
  74. package/dist/state/history.d.ts.map +1 -1
  75. package/dist/state/history.js +1 -0
  76. package/dist/state/history.js.map +1 -1
  77. package/dist/state/index.d.ts +4 -4
  78. package/dist/state/index.d.ts.map +1 -1
  79. package/dist/state/index.js +4 -4
  80. package/dist/state/index.js.map +1 -1
  81. package/dist/state/lists.d.ts +3 -3
  82. package/dist/state/lists.d.ts.map +1 -1
  83. package/dist/state/lists.js.map +1 -1
  84. package/dist/state/mark.d.ts +1 -17
  85. package/dist/state/mark.d.ts.map +1 -1
  86. package/dist/state/mark.js +2 -0
  87. package/dist/state/mark.js.map +1 -1
  88. package/dist/state/notes.d.ts +2 -12
  89. package/dist/state/notes.d.ts.map +1 -1
  90. package/dist/state/notes.js +10 -3
  91. package/dist/state/notes.js.map +1 -1
  92. package/dist/state/review.d.ts +1 -6
  93. package/dist/state/review.d.ts.map +1 -1
  94. package/dist/state/review.js +1 -0
  95. package/dist/state/review.js.map +1 -1
  96. package/dist/state/sections.d.ts +1 -11
  97. package/dist/state/sections.d.ts.map +1 -1
  98. package/dist/state/sections.js +10 -3
  99. package/dist/state/sections.js.map +1 -1
  100. package/dist/state/state.d.ts +13 -9
  101. package/dist/state/state.d.ts.map +1 -1
  102. package/dist/state/state.js +5 -2
  103. package/dist/state/state.js.map +1 -1
  104. package/dist/state/stories.d.ts +1 -40
  105. package/dist/state/stories.d.ts.map +1 -1
  106. package/dist/state/stories.js +18 -2
  107. package/dist/state/stories.js.map +1 -1
  108. package/dist/state/tables.d.ts +1 -36
  109. package/dist/state/tables.d.ts.map +1 -1
  110. package/dist/state/tables.js +23 -5
  111. package/dist/state/tables.js.map +1 -1
  112. package/dist/state/track.d.ts +1 -29
  113. package/dist/state/track.d.ts.map +1 -1
  114. package/dist/state/track.js +9 -2
  115. package/dist/state/track.js.map +1 -1
  116. package/dist/state/word.d.ts +8 -78
  117. package/dist/state/word.d.ts.map +1 -1
  118. package/dist/state/word.js +95 -28
  119. package/dist/state/word.js.map +1 -1
  120. package/dist/state/wordclip.d.ts +3 -1
  121. package/dist/state/wordclip.d.ts.map +1 -1
  122. package/dist/state/wordclip.js +67 -8
  123. package/dist/state/wordclip.js.map +1 -1
  124. package/dist/state/wordformat.d.ts +1 -86
  125. package/dist/state/wordformat.d.ts.map +1 -1
  126. package/dist/state/wordformat.js +54 -11
  127. package/dist/state/wordformat.js.map +1 -1
  128. package/dist/transform/stepmap.d.ts +0 -2
  129. package/dist/transform/stepmap.d.ts.map +1 -1
  130. package/dist/v3/check.d.ts +0 -25
  131. package/dist/v3/check.d.ts.map +1 -1
  132. package/dist/v3/check.js +35 -7
  133. package/dist/v3/check.js.map +1 -1
  134. package/dist/v3/document.d.ts +8 -6
  135. package/dist/v3/document.d.ts.map +1 -1
  136. package/dist/v3/document.js +28 -16
  137. package/dist/v3/document.js.map +1 -1
  138. package/dist/v3/extensions.d.ts +43 -0
  139. package/dist/v3/extensions.d.ts.map +1 -0
  140. package/dist/v3/extensions.js +154 -0
  141. package/dist/v3/extensions.js.map +1 -0
  142. package/dist/v3/index.d.ts +2 -1
  143. package/dist/v3/index.d.ts.map +1 -1
  144. package/dist/v3/index.js +2 -1
  145. package/dist/v3/index.js.map +1 -1
  146. package/dist/v3/resolve.d.ts.map +1 -1
  147. package/dist/v3/resolve.js +6 -0
  148. package/dist/v3/resolve.js.map +1 -1
  149. package/dist/v3/schema.d.ts +5 -18
  150. package/dist/v3/schema.d.ts.map +1 -1
  151. package/dist/v3/schema.js +79 -5
  152. package/dist/v3/schema.js.map +1 -1
  153. package/package.json +5 -1
  154. package/src/document.ts +5 -1
  155. package/src/index.ts +330 -4
  156. package/src/internal.ts +50 -0
  157. package/src/model/attrs.ts +10 -2
  158. package/src/model/content.ts +1 -1
  159. package/src/model/errors.ts +4 -1
  160. package/src/model/fragment.ts +2 -1
  161. package/src/model/mark.ts +1 -1
  162. package/src/model/node.ts +6 -4
  163. package/src/model/schema.ts +9 -3
  164. package/src/schema.ts +2 -0
  165. package/src/state/comments.ts +1 -0
  166. package/src/state/controls.ts +25 -9
  167. package/src/state/editor.ts +251 -130
  168. package/src/state/fields.ts +16 -4
  169. package/src/state/fieldupdate.ts +1 -0
  170. package/src/state/find.ts +12 -4
  171. package/src/state/history.ts +2 -0
  172. package/src/state/index.ts +5 -4
  173. package/src/state/lists.ts +2 -2
  174. package/src/state/mark.ts +2 -0
  175. package/src/state/notes.ts +27 -17
  176. package/src/state/review.ts +1 -0
  177. package/src/state/sections.ts +10 -3
  178. package/src/state/state.ts +16 -3
  179. package/src/state/stories.ts +32 -5
  180. package/src/state/tables.ts +27 -6
  181. package/src/state/track.ts +9 -2
  182. package/src/state/word.ts +105 -32
  183. package/src/state/wordclip.ts +76 -8
  184. package/src/state/wordformat.ts +55 -11
  185. package/src/v3/check.ts +35 -7
  186. package/src/v3/document.ts +39 -16
  187. package/src/v3/extensions.ts +201 -0
  188. package/src/v3/index.ts +9 -0
  189. package/src/v3/resolve.ts +5 -0
  190. package/src/v3/schema.ts +83 -5
package/src/state/word.ts CHANGED
@@ -10,10 +10,11 @@
10
10
  * become the commands themselves.
11
11
  */
12
12
  import { deepEqual } from "../model/attrs.js";
13
- import type { Attrs, Mark, MarkType, Node } from "../model/index.js";
13
+ import type { Attrs, Mark, MarkType, Node, Schema } from "../model/index.js";
14
14
  import { Step, StepResult } from "../transform/steps.js";
15
15
  import type { CommentJSON, FoliDocument, StoryJSON } from "../v3/document.js";
16
16
  import { parseContent } from "../v3/document.js";
17
+ import { writeCustom } from "../v3/extensions.js";
17
18
  import { Resolver, type RunFormat } from "../v3/resolve.js";
18
19
  import { MARK_ATTRS } from "./mark.js";
19
20
  import { NodeSelection, type SelectionJSON, TextSelection } from "./selection.js";
@@ -22,6 +23,24 @@ import { type Command, EditorState, Plugin, PluginKey, type Transaction } from "
22
23
  /** A v3 document without its content: what the editor keeps beside the edited tree. */
23
24
  export type WordEnvelope = Omit<FoliDocument, "content">;
24
25
 
26
+ /**
27
+ * The document of an editor's `envelope` and tree `doc`, as apps get it (`getDocument`, React's
28
+ * `onChange`): a copy, foreign nodes and marks written back as the custom types they stand for.
29
+ */
30
+ export function documentJSON(envelope: WordEnvelope, doc: Node): FoliDocument {
31
+ const { stories, comments, ...rest } = structuredClone(envelope);
32
+ return {
33
+ ...rest,
34
+ comments: comments.map((c) => ({ ...c, content: c.content.map(writeCustom) })),
35
+ ...(stories && {
36
+ stories: Object.fromEntries(
37
+ Object.entries(stories).map(([id, s]) => [id, { ...s, content: writeCustom(s.content) }]),
38
+ ),
39
+ }),
40
+ content: writeCustom(doc.toJSON()),
41
+ };
42
+ }
43
+
25
44
  /** A story as the editor holds it: its tree, and what the envelope says beside it. */
26
45
  export interface Story extends Omit<StoryJSON, "content"> {
27
46
  readonly doc: Node;
@@ -70,7 +89,10 @@ export class CommentStep extends Step {
70
89
  }
71
90
  }
72
91
 
73
- /** `comments` after the comment steps among `steps`. */
92
+ /**
93
+ * `comments` after the comment steps among `steps`.
94
+ * @internal
95
+ */
74
96
  export function applyCommentSteps(
75
97
  comments: readonly CommentJSON[],
76
98
  steps: readonly Step[],
@@ -194,7 +216,10 @@ export class StoryStep extends Step {
194
216
  }
195
217
  }
196
218
 
197
- /** Whether two stories are the same: identical trees are the usual case. */
219
+ /**
220
+ * Whether two stories are the same: identical trees are the usual case.
221
+ * @internal
222
+ */
198
223
  export function sameStory(a: Story | null | undefined, b: Story | null | undefined): boolean {
199
224
  if (a === b || (!a && !b)) return true;
200
225
  return (
@@ -224,7 +249,10 @@ function afterEnvelopeSteps<K extends EnvelopeKey>(
224
249
  return current;
225
250
  }
226
251
 
227
- /** Makes `tr` set the envelope's `key` to `value`, from what it holds after `tr` so far. */
252
+ /**
253
+ * Makes `tr` set the envelope's `key` to `value`, from what it holds after `tr` so far.
254
+ * @internal
255
+ */
228
256
  export function setEnvelopeValue<K extends EnvelopeKey>(
229
257
  state: EditorState,
230
258
  tr: Transaction,
@@ -239,6 +267,7 @@ export function setEnvelopeValue<K extends EnvelopeKey>(
239
267
  /**
240
268
  * Whether stored `steps` can apply to `context`: every `EnvelopeStep` and `StoryStep` finds what
241
269
  * it expects, given the ones before it. A change made outside history makes them stale.
270
+ * @internal
242
271
  */
243
272
  export function storedStepsApply(context: WordContext, steps: readonly Step[]): boolean {
244
273
  const values = new Map<EnvelopeKey, unknown>();
@@ -260,14 +289,20 @@ export function storedStepsApply(context: WordContext, steps: readonly Step[]):
260
289
  return true;
261
290
  }
262
291
 
263
- /** The story as `tr` leaves it (`state`'s, after the story steps `tr` already has). */
292
+ /**
293
+ * The story as `tr` leaves it (`state`'s, after the story steps `tr` already has).
294
+ * @internal
295
+ */
264
296
  export function storyAfter(state: EditorState, tr: Transaction, id: string): Story | null {
265
297
  let story = wordContext(state)?.stories.get(id) ?? null;
266
298
  for (const step of tr.steps) if (step instanceof StoryStep && step.id === id) story = step.after;
267
299
  return story;
268
300
  }
269
301
 
270
- /** What a story's editor knows of the body's: undo, and the trees it allocates ids across. */
302
+ /**
303
+ * What a story's editor knows of the body's: undo, and the trees it allocates ids across.
304
+ * @internal
305
+ */
271
306
  export interface StoryBody {
272
307
  readonly state: EditorState;
273
308
  dispatch(tr: Transaction): void;
@@ -275,33 +310,48 @@ export interface StoryBody {
275
310
  can(command: Command): boolean;
276
311
  }
277
312
 
278
- /** On the state of a story's editor: the body it belongs to. */
313
+ /**
314
+ * On the state of a story's editor: the body it belongs to.
315
+ * @internal
316
+ */
279
317
  export const storyBodyKey = new PluginKey<StoryBody>("storyBody");
280
318
 
281
- /** The body of the story `state` edits; null when `state` is the body's. */
319
+ /**
320
+ * The body of the story `state` edits; null when `state` is the body's.
321
+ * @internal
322
+ */
282
323
  export const storyBody = (state: EditorState): StoryBody | null =>
283
324
  storyBodyKey.getState(state) ?? null;
284
325
 
285
- /** A state over a story's `doc` for working on it, with `state`'s word context (and `envelope`). */
326
+ /**
327
+ * A state over a story's `doc` for working on it, with `state`'s word context (and `envelope`).
328
+ * @internal
329
+ */
286
330
  export function storyState(state: EditorState, doc: Node, envelope?: WordEnvelope): EditorState {
287
331
  const context = wordContext(state) as WordContext;
288
332
  const given = envelope ? { ...context, envelope } : context;
289
333
  return EditorState.create({ doc, plugins: [wordPlugin(given.envelope, given)] });
290
334
  }
291
335
 
292
- /** Every tree of the document but `state`'s own: ids are allocated across them (ADR-0007). */
336
+ /**
337
+ * Every tree of the document but `state`'s own: ids are allocated across them (ADR-0007).
338
+ * @internal
339
+ */
293
340
  export function otherTrees(state: EditorState): Node[] {
294
341
  const trees = [...(wordContext(state)?.stories.values() ?? [])].map((story) => story.doc);
295
342
  const body = storyBody(state)?.state.doc;
296
343
  return (body ? [body, ...trees] : trees).filter((tree) => tree !== state.doc);
297
344
  }
298
345
 
299
- /** The trees of `envelope`'s stories. */
300
- function storyTrees(envelope: WordEnvelope): Map<string, Story> {
346
+ /** The trees of `envelope`'s stories, in the editor's `schema`. */
347
+ function storyTrees(envelope: WordEnvelope, schema: Schema): Map<string, Story> {
301
348
  return new Map(
302
349
  Object.entries(envelope.stories ?? {}).map(([id, { content, ...rest }]) => [
303
350
  id,
304
- { ...rest, doc: parseContent(content, `stories[${JSON.stringify(id)}].content`) },
351
+ {
352
+ ...rest,
353
+ doc: parseContent(content, { path: `stories[${JSON.stringify(id)}].content`, schema }),
354
+ },
305
355
  ]),
306
356
  );
307
357
  }
@@ -313,20 +363,21 @@ function storyTrees(envelope: WordEnvelope): Map<string, Story> {
313
363
  * properties through `EnvelopeStep`s and stories through `StoryStep`s, which undo takes back (a
314
364
  * paste adds the properties of the controls it copies with `withEnvelope`). A story's editor is
315
365
  * given its body's `context` as it stands.
366
+ * @internal
316
367
  */
317
368
  export function wordPlugin(envelope: WordEnvelope, context?: WordContext): Plugin<WordContext> {
318
369
  // Not a secret: only tells documents apart.
319
370
  const id = `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
320
- const initial: WordContext = context ?? {
321
- envelope,
322
- resolver: new Resolver(envelope),
323
- stories: storyTrees(envelope),
324
- id,
325
- };
326
371
  return new Plugin({
327
372
  key,
328
373
  state: {
329
- init: () => initial,
374
+ init: (state) =>
375
+ context ?? {
376
+ envelope,
377
+ resolver: new Resolver(envelope),
378
+ stories: storyTrees(envelope, state.schema),
379
+ id,
380
+ },
330
381
  apply: (tr, value) => {
331
382
  const adopted = tr.getMeta(ADOPT) as WordContext | undefined;
332
383
  if (adopted) return adopted;
@@ -388,11 +439,17 @@ export function withEnvelope(tr: Transaction, envelope: WordEnvelope): Transacti
388
439
 
389
440
  const ADOPT = "adoptWordContext";
390
441
 
391
- /** Makes `tr` give a story's state the body's context as it now is. */
442
+ /**
443
+ * Makes `tr` give a story's state the body's context as it now is.
444
+ * @internal
445
+ */
392
446
  export const withContext = (tr: Transaction, context: WordContext): Transaction =>
393
447
  tr.setMeta(ADOPT, context);
394
448
 
395
- /** The envelope `tr` gives the document through `withEnvelope`, if any. */
449
+ /**
450
+ * The envelope `tr` gives the document through `withEnvelope`, if any.
451
+ * @internal
452
+ */
396
453
  export const envelopeChange = (tr: Transaction): WordEnvelope | undefined =>
397
454
  tr.getMeta(key) as WordEnvelope | undefined;
398
455
 
@@ -420,6 +477,7 @@ function defaultParagraphStyle(envelope: WordEnvelope): string | undefined {
420
477
  * with the same properties; the second keeps the original mark. At the end of a paragraph whose
421
478
  * style names another as the next (a heading: Normal), the second paragraph is in that style,
422
479
  * without the first's direct formatting. `before` is null when the first keeps every attribute.
480
+ * @internal
423
481
  */
424
482
  export function splitAttrs(
425
483
  context: WordContext,
@@ -451,7 +509,10 @@ const TOGGLES: Record<string, (run: RunFormat) => boolean> = {
451
509
  hidden: (run) => run.hidden,
452
510
  };
453
511
 
454
- /** Whether `type` is a run property the toggles handle on a v3 document. */
512
+ /**
513
+ * Whether `type` is a run property the toggles handle on a v3 document.
514
+ * @internal
515
+ */
455
516
  export function isWordToggle(context: WordContext | null, type: MarkType): boolean {
456
517
  return context !== null && Object.hasOwn(TOGGLES, type.name);
457
518
  }
@@ -498,7 +559,10 @@ function inlineIn(state: EditorState, from: number, to: number, type: MarkType)
498
559
  return text.length ? { all: found, judged: text } : { all: found, judged: found };
499
560
  }
500
561
 
501
- /** Whether all the selected text (or the text typed at a caret) shows the toggle `type`. */
562
+ /**
563
+ * Whether all the selected text (or the text typed at a caret) shows the toggle `type`.
564
+ * @internal
565
+ */
502
566
  export function wordToggleActive(
503
567
  context: WordContext,
504
568
  state: EditorState,
@@ -514,6 +578,7 @@ export function wordToggleActive(
514
578
  /**
515
579
  * The stored marks for a toggle at a caret: what makes the next typed text show the opposite of
516
580
  * what text typed there would show now.
581
+ * @internal
517
582
  */
518
583
  export function toggledCaretMarks(
519
584
  context: WordContext,
@@ -531,6 +596,7 @@ export function toggledCaretMarks(
531
596
  /**
532
597
  * The mark changes that make every inline node in `from..to` show the toggle `type` as `on`:
533
598
  * per node, a direct mark where its style does not already give that, none where it does.
599
+ * @internal
534
600
  */
535
601
  export function toggleRanges(
536
602
  context: WordContext,
@@ -570,21 +636,28 @@ const MARKERS = new Set([
570
636
  "commentReference",
571
637
  ]);
572
638
 
573
- /** Whether `node` is an invisible marker of a v3 document. */
639
+ /**
640
+ * Whether `node` is an invisible marker of a v3 document.
641
+ * @internal
642
+ */
574
643
  export function isMarker(context: WordContext | null, node: Node | null | undefined): boolean {
575
644
  return context !== null && !!node && MARKERS.has(node.type.name);
576
645
  }
577
646
 
578
- /** Opaque content: deleted only once selected, as Word selects a field before deleting it. */
647
+ const OPAQUE = new Set(["opaqueInline", "opaqueBlock", "foreignInline", "foreignBlock"]);
648
+
649
+ /**
650
+ * Opaque content (and foreign nodes, ADR-0008): deleted only once selected, as Word selects a field before deleting it.
651
+ * @internal
652
+ */
579
653
  export function isOpaque(context: WordContext | null, node: Node | null | undefined): boolean {
580
- return (
581
- context !== null &&
582
- !!node &&
583
- (node.type.name === "opaqueInline" || node.type.name === "opaqueBlock")
584
- );
654
+ return context !== null && !!node && OPAQUE.has(node.type.name);
585
655
  }
586
656
 
587
- /** A node selection of the node at `pos`, or a text selection when it cannot be selected. */
657
+ /**
658
+ * A node selection of the node at `pos`, or a text selection when it cannot be selected.
659
+ * @internal
660
+ */
588
661
  export function selectionAt(state: EditorState, pos: number): NodeSelection | TextSelection {
589
662
  const node = state.doc.nodeAt(pos);
590
663
  return node && NodeSelection.isSelectable(node)
@@ -37,6 +37,7 @@ import {
37
37
  type ParagraphPropertiesJSON,
38
38
  parseContent,
39
39
  parseDocument,
40
+ type ResourceJSON,
40
41
  SCHEMA_VERSION,
41
42
  type StoryJSON,
42
43
  type StyleJSON,
@@ -65,6 +66,8 @@ export interface WordDefinitions {
65
66
  comments: CommentJSON[];
66
67
  /** The notes the content refers to, by story id. */
67
68
  notes?: Record<string, StoryJSON>;
69
+ /** The resources (pictures' images) the content uses, by key. */
70
+ resources?: Record<string, ResourceJSON>;
68
71
  }
69
72
 
70
73
  /** What a paste brings: the content, the envelope it needs, and new notes. */
@@ -95,8 +98,9 @@ type Properties = Pick<ParagraphPropertiesJSON, "style" | "numbering" | "markFor
95
98
  * comments; with the document's id.
96
99
  */
97
100
  export function copiedDefinitions(context: WordContext, content: Node): WordDefinitions {
98
- const { styles, numbering, comments, stories } = context.envelope;
101
+ const { styles, numbering, comments, stories, resources } = context.envelope;
99
102
  const noteStories = new Set<string>();
103
+ const resourceKeys = new Set<string>();
100
104
  const styleIds = new Set<string>();
101
105
  const numberingIds = new Set<number>();
102
106
  const commentIds = new Set<number>();
@@ -123,6 +127,7 @@ export function copiedDefinitions(context: WordContext, content: Node): WordDefi
123
127
  if (node.type === "tableRow") properties((attrs as { exceptions?: Properties }).exceptions);
124
128
  if (COMMENT_ANCHORS.has(node.type)) commentIds.add(attrs.id as number);
125
129
  if (node.type === "noteReference") noteStories.add(String(node.attrs?.story));
130
+ if (node.type === "picture") resourceKeys.add(String(node.attrs?.resource));
126
131
  marks(node.marks);
127
132
  };
128
133
  visit([content.toJSON()], references);
@@ -166,12 +171,18 @@ export function copiedDefinitions(context: WordContext, content: Node): WordDefi
166
171
  for (const o of instance.overrides ?? [])
167
172
  if (o.definition?.style) styleIds.add(o.definition.style);
168
173
  }
174
+ const used = Object.fromEntries(
175
+ [...resourceKeys].flatMap((key) =>
176
+ resources && Object.hasOwn(resources, key) ? [[key, resources[key] as ResourceJSON]] : [],
177
+ ),
178
+ );
169
179
  return {
170
180
  document: context.id,
171
181
  styles: styles.filter((s) => styleIds.has(s.id)),
172
182
  numbering: { abstracts: abstracts(), instances: instances() },
173
183
  comments: copied,
174
184
  ...(Object.keys(notes).length ? { notes } : {}),
185
+ ...(Object.keys(used).length ? { resources: used } : {}),
175
186
  };
176
187
  }
177
188
 
@@ -230,7 +241,7 @@ export function fitPastedV2(
230
241
  else delete child.marks;
231
242
  }
232
243
  }
233
- return { doc: parseContent(json), envelope: fitted.envelope };
244
+ return { doc: parseContent(json, { schema: state.schema }), envelope: fitted.envelope };
234
245
  }
235
246
 
236
247
  const equal = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
@@ -257,8 +268,14 @@ export function fitPaste(state: EditorState, content: unknown, definitions?: unk
257
268
  const target = context.envelope;
258
269
  // Taken as this document's own, but it cannot be told to be: no unsafe link comes in.
259
270
  if (definitions === undefined || definitions === null)
260
- return fit(state, target, safeLinks(parseContent(content, "content", true).toJSON()), true);
261
- const { document, styles, numbering, comments, notes } = definitions as Partial<WordDefinitions>;
271
+ return fit(
272
+ state,
273
+ target,
274
+ safeLinks(parseContent(content, { fragment: true, schema: state.schema }).toJSON()),
275
+ true,
276
+ );
277
+ const { document, styles, numbering, comments, notes, resources } =
278
+ definitions as Partial<WordDefinitions>;
262
279
  // Validated as a document's envelope: types, ranges, no style based on itself; the content
263
280
  // as content to paste (a table may end it).
264
281
  const checked = parseDocument({
@@ -269,14 +286,16 @@ export function fitPaste(state: EditorState, content: unknown, definitions?: unk
269
286
  numbering,
270
287
  comments,
271
288
  ...(notes ? { stories: notes } : {}),
289
+ ...(resources ? { resources } : {}),
272
290
  content: { type: "doc", content: [{ type: "paragraph" }] },
273
291
  });
274
- const json = parseContent(content, "content", true).toJSON();
292
+ const json = parseContent(content, { fragment: true, schema: state.schema }).toJSON();
275
293
  const source: WordDefinitions = {
276
294
  styles: checked.styles,
277
295
  numbering: checked.numbering,
278
296
  comments: checked.comments,
279
297
  ...(checked.stories ? { notes: checked.stories } : {}),
298
+ ...(checked.resources ? { resources: checked.resources } : {}),
280
299
  };
281
300
  return fit(state, source, json, document === context.id);
282
301
  }
@@ -491,6 +510,45 @@ function fit(
491
510
  }
492
511
  return copy;
493
512
  };
513
+ // Pictures from another document bring their images: under a key of their own here (the same
514
+ // image already here is reused), as bytes or a web URL only. A package part's name would name
515
+ // this document's part of that name, and a blob: URL dies with the page it was made in: such a
516
+ // picture comes without its image, under a key no resource has (drawn as a box, as Word shows
517
+ // a missing image; refused by `.docx` export until an image is given).
518
+ let resources = target.resources;
519
+ const resourceKeys = new Map<string, string>();
520
+ const takenKeys = new Set<string>();
521
+ const freeKey = (key: string) => {
522
+ let next = key;
523
+ for (let i = 2; (resources && Object.hasOwn(resources, next)) || takenKeys.has(next); i++)
524
+ next = `${key}-${i}`;
525
+ takenKeys.add(next);
526
+ return next;
527
+ };
528
+ const mapResource = (key: string): string => {
529
+ if (same) return key;
530
+ const known = resourceKeys.get(key);
531
+ if (known !== undefined) return known;
532
+ const carried =
533
+ source.resources && Object.hasOwn(source.resources, key) ? source.resources[key] : undefined;
534
+ const { part: _part, size, url, ...rest } = carried ?? { contentType: "" };
535
+ const web = url !== undefined && !/^\s*blob:/i.test(url) ? url : undefined;
536
+ let next: string;
537
+ if (!carried || (rest.data === undefined && web === undefined))
538
+ next = freeKey(`${key}-missing`);
539
+ else {
540
+ const resource: ResourceJSON = {
541
+ ...rest,
542
+ ...(web === undefined ? {} : { url: web }),
543
+ ...(rest.data === undefined && size !== undefined ? { size } : {}),
544
+ };
545
+ const existing = Object.entries(resources ?? {}).find(([, r]) => equal(r, resource))?.[0];
546
+ next = existing ?? freeKey(key);
547
+ if (!existing) resources = { ...resources, [next]: resource };
548
+ }
549
+ resourceKeys.set(key, next);
550
+ return next;
551
+ };
494
552
  // A note has one reference: one still in the document keeps it (cut and paste moves it).
495
553
  const referredTo = new Set<string>();
496
554
  state.doc.descendants((node, pos) => {
@@ -541,6 +599,8 @@ function fit(
541
599
  if (Object.keys(rest).length) next.attributes = rest;
542
600
  else delete next.attributes;
543
601
  }
602
+ } else if (node.type === "picture" && attrs) {
603
+ next = { ...attrs, resource: mapResource(String(attrs.resource)) };
544
604
  } else if (node.type === "table" && attrs?.style) {
545
605
  next = { ...attrs, style: mapStyle(String(attrs.style)) };
546
606
  } else if (node.type === "tableRow" && attrs) {
@@ -599,10 +659,16 @@ function fit(
599
659
  }),
600
660
  }
601
661
  : mapped;
602
- const doc = parseContent(inPlace, "content", true);
662
+ const doc = parseContent(inPlace, { fragment: true, schema: state.schema });
603
663
  const notes = [...pastedNotes].map(([from, id]) => {
604
664
  const note = carried(from) as StoryJSON;
605
- return { id, story: { kind: note.kind, doc: parseContent(mapNode(note.content)) } };
665
+ return {
666
+ id,
667
+ story: {
668
+ kind: note.kind,
669
+ doc: parseContent(mapNode(note.content), { schema: state.schema }),
670
+ },
671
+ };
606
672
  });
607
673
  let comments = target.comments;
608
674
  const copiedComments = source.comments.filter((c) => commentIds.has(c.id));
@@ -627,7 +693,8 @@ function fit(
627
693
  abstracts !== target.numbering.abstracts ||
628
694
  instances !== target.numbering.instances ||
629
695
  comments !== target.comments ||
630
- controls !== target.controls;
696
+ controls !== target.controls ||
697
+ resources !== target.resources;
631
698
  return {
632
699
  doc,
633
700
  envelope: changed
@@ -637,6 +704,7 @@ function fit(
637
704
  numbering: { abstracts, instances },
638
705
  comments,
639
706
  ...(controls ? { controls } : {}),
707
+ ...(resources ? { resources } : {}),
640
708
  }
641
709
  : target,
642
710
  ...(notes.length ? { notes } : {}),
@@ -76,9 +76,13 @@ function common<T>(values: readonly T[]): T | null {
76
76
 
77
77
  // ---------- paragraph styles ----------
78
78
 
79
+ /** @internal */
79
80
  export type HasEnvelope = Pick<WordContext, "envelope">;
80
81
 
81
- /** The id of the document's style of `type` named `name` (Word's names: "heading 1"), if any. */
82
+ /**
83
+ * The id of the document's style of `type` named `name` (Word's names: "heading 1"), if any.
84
+ * @internal
85
+ */
82
86
  export function styleNamed(
83
87
  context: HasEnvelope,
84
88
  name: string,
@@ -91,7 +95,10 @@ export function styleNamed(
91
95
  );
92
96
  }
93
97
 
94
- /** The id of the default style of `type` (Normal, Default Paragraph Font), if the document has one. */
98
+ /**
99
+ * The id of the default style of `type` (Normal, Default Paragraph Font), if the document has one.
100
+ * @internal
101
+ */
95
102
  export function defaultParagraphStyleOf(
96
103
  context: HasEnvelope,
97
104
  type: StyleJSON["type"] = "paragraph",
@@ -113,6 +120,7 @@ const builtinName = (id: string) =>
113
120
  * Word's definition of built-in style `name` ("heading 1"–"heading 9", "List Paragraph",
114
121
  * "Hyperlink", "Placeholder Text"), as Word adds it to a document the first time it is used (the Word 2013–2019
115
122
  * template's values; not checked against newer Word).
123
+ * @internal
116
124
  */
117
125
  export function builtinStyle(context: HasEnvelope, name: string): StyleJSON | null {
118
126
  const normal = defaultParagraphStyleOf(context);
@@ -267,6 +275,7 @@ export function builtinStyle(context: HasEnvelope, name: string): StyleJSON | nu
267
275
  /**
268
276
  * The id of the document's style named `name`, adding Word's built-in definition when the
269
277
  * document does not have it yet (with the envelope that has it; unchanged if it was there).
278
+ * @internal
270
279
  */
271
280
  export function ensureStyle(
272
281
  context: HasEnvelope,
@@ -337,6 +346,7 @@ export function setParagraphStyle(id: string): Command {
337
346
  /**
338
347
  * Puts the selected paragraphs in the paragraph style named `name` ("heading 2"), adding Word's
339
348
  * definition of a built-in one the document does not have yet.
349
+ * @internal
340
350
  */
341
351
  export function setStyleNamed(name: string): Command {
342
352
  return (state, dispatch) => {
@@ -523,6 +533,7 @@ export const HIGHLIGHT_HEX: Readonly<Record<string, string>> = {
523
533
  /**
524
534
  * Text color on a v3 document (`#rrggbb`); null is Word's "Automatic": no direct color, or an
525
535
  * explicit `auto` where a style colors the text.
536
+ * @internal
526
537
  */
527
538
  export function setWordTextColor(color: string | null): Command {
528
539
  return setRunMark("color", (_existing, inherited, type) => {
@@ -536,6 +547,7 @@ export function setWordTextColor(color: string | null): Command {
536
547
  * other as shading; null removes the highlight (an explicit `none` where a style highlights)
537
548
  * and a plain shading fill, the kind a color outside Word's highlights gives. Patterned shading
538
549
  * stays, and picking a highlight keeps any shading (Word's highlight and shading are apart).
550
+ * @internal
539
551
  */
540
552
  export function setWordHighlight(color: string | null): Command {
541
553
  return (state, dispatch) => {
@@ -593,12 +605,18 @@ function chain(
593
605
  return true;
594
606
  }
595
607
 
596
- /** The text color the selection shows (`#rrggbb`; null: automatic, or mixed). */
608
+ /**
609
+ * The text color the selection shows (`#rrggbb`; null: automatic, or mixed).
610
+ * @internal
611
+ */
597
612
  export function wordTextColorAt(state: EditorState): string | null {
598
613
  return runValueAt(state, (run) => (run.color ? `#${run.color.toLowerCase()}` : null));
599
614
  }
600
615
 
601
- /** The highlight (or shading) the selection shows (`#rrggbb`), or null. */
616
+ /**
617
+ * The highlight (or shading) the selection shows (`#rrggbb`), or null.
618
+ * @internal
619
+ */
602
620
  export function wordHighlightAt(state: EditorState): string | null {
603
621
  return runValueAt(state, (run) =>
604
622
  run.highlight
@@ -644,7 +662,10 @@ function direct(
644
662
  return shows(inherited) ? without : { ...node.attrs, [key]: value };
645
663
  }
646
664
 
647
- /** Aligns the selected paragraphs (`setAlign` on a v3 document). */
665
+ /**
666
+ * Aligns the selected paragraphs (`setAlign` on a v3 document).
667
+ * @internal
668
+ */
648
669
  export function setWordAlign(align: Alignment): Command {
649
670
  return (state, dispatch) => {
650
671
  const context = wordContext(state);
@@ -661,7 +682,10 @@ export function setWordAlign(align: Alignment): Command {
661
682
  };
662
683
  }
663
684
 
664
- /** The alignment all selected paragraphs show (`alignAt` on a v3 document). */
685
+ /**
686
+ * The alignment all selected paragraphs show (`alignAt` on a v3 document).
687
+ * @internal
688
+ */
665
689
  export function wordAlignAt(state: EditorState): Alignment | null {
666
690
  const context = wordContext(state);
667
691
  if (!context) return null;
@@ -800,7 +824,10 @@ function kindOf(context: WordContext, attrs: Attrs): ListKind | null {
800
824
  return format === "bullet" ? "bulletList" : "orderedList";
801
825
  }
802
826
 
803
- /** The kind of list all selected paragraphs are in, or null (none, or mixed). */
827
+ /**
828
+ * The kind of list all selected paragraphs are in, or null (none, or mixed).
829
+ * @internal
830
+ */
804
831
  export function wordListKindAt(state: EditorState): ListKind | null {
805
832
  const context = wordContext(state);
806
833
  if (!context) return null;
@@ -817,7 +844,10 @@ function withoutNumbering(context: WordContext, node: Node): Attrs {
817
844
  return { ...base, style, numbering: styled ? { id: 0 } : null };
818
845
  }
819
846
 
820
- /** Word's levels for a new list: bullets (Symbol, Courier New, Wingdings) or numbers. */
847
+ /**
848
+ * Word's levels for a new list: bullets (Symbol, Courier New, Wingdings) or numbers.
849
+ * @internal
850
+ */
821
851
  export function levels(kind: ListKind): NumberingLevelJSON[] {
822
852
  const bullets = [
823
853
  ["", "Symbol"],
@@ -921,6 +951,7 @@ function newList(envelope: WordEnvelope, kind: ListKind): { id: number; envelope
921
951
  * them out; otherwise numbers them as `kind` (a numbered paragraph keeps its level). A list of
922
952
  * that kind right before the selection goes on; otherwise a new one starts. Paragraphs in the
923
953
  * default style go to "List Paragraph" where the document has it, as in Word.
954
+ * @internal
924
955
  */
925
956
  export function toggleWordList(kind: ListKind): Command {
926
957
  return (state, dispatch) => {
@@ -932,7 +963,10 @@ export function toggleWordList(kind: ListKind): Command {
932
963
  };
933
964
  }
934
965
 
935
- /** Numbers the selected paragraphs as a list of `kind` (`wrapInList` on a v3 document). */
966
+ /**
967
+ * Numbers the selected paragraphs as a list of `kind` (`wrapInList` on a v3 document).
968
+ * @internal
969
+ */
936
970
  export function wrapInWordList(kind: ListKind): Command {
937
971
  return (state, dispatch) => {
938
972
  const context = wordContext(state);
@@ -990,6 +1024,7 @@ function caretInList(state: EditorState, context: WordContext, atStart: boolean)
990
1024
  * Tab on a v3 document: at the start of a numbered paragraph, one level deeper; over several
991
1025
  * paragraphs, indents them (list levels, half-inch stops), as Word does. Elsewhere it does not
992
1026
  * apply (Tab types a tab).
1027
+ * @internal
993
1028
  */
994
1029
  export const sinkWordList: Command = (state, dispatch) => {
995
1030
  const context = wordContext(state);
@@ -998,7 +1033,10 @@ export const sinkWordList: Command = (state, dispatch) => {
998
1033
  return changeIndent(1)(state, dispatch);
999
1034
  };
1000
1035
 
1001
- /** Shift+Tab in a list on a v3 document: one level up (out of the list at the top). */
1036
+ /**
1037
+ * Shift+Tab in a list on a v3 document: one level up (out of the list at the top).
1038
+ * @internal
1039
+ */
1002
1040
  export const liftWordList: Command = (state, dispatch) => {
1003
1041
  const context = wordContext(state);
1004
1042
  if (!context) return false;
@@ -1011,6 +1049,7 @@ export const liftWordList: Command = (state, dispatch) => {
1011
1049
  /**
1012
1050
  * Enter in an empty numbered paragraph on a v3 document: one level up, or at the top level ends
1013
1051
  * the list there, as in Word.
1052
+ * @internal
1014
1053
  */
1015
1054
  export const endWordList: Command = (state, dispatch) => {
1016
1055
  const context = wordContext(state);
@@ -1022,6 +1061,7 @@ export const endWordList: Command = (state, dispatch) => {
1022
1061
  /**
1023
1062
  * Backspace at the start of a numbered paragraph on a v3 document: removes its number, keeping
1024
1063
  * the text where it was (the level's indent as the paragraph's own); the next Backspace joins.
1064
+ * @internal
1025
1065
  */
1026
1066
  export const removeWordListNumber: Command = (state, dispatch) => {
1027
1067
  const context = wordContext(state);
@@ -1041,6 +1081,7 @@ export const removeWordListNumber: Command = (state, dispatch) => {
1041
1081
  /**
1042
1082
  * Gives newly linked text Word's "Hyperlink" character style (blue, underlined), adding Word's
1043
1083
  * definition where the document does not have it yet.
1084
+ * @internal
1044
1085
  */
1045
1086
  export function styleLink(tr: Transaction, state: EditorState, from: number, to: number): void {
1046
1087
  const context = wordContext(state);
@@ -1051,7 +1092,10 @@ export function styleLink(tr: Transaction, state: EditorState, from: number, to:
1051
1092
  if (style.envelope !== context.envelope) withEnvelope(tr, style.envelope);
1052
1093
  }
1053
1094
 
1054
- /** Takes the "Hyperlink" character style off text whose link is removed. */
1095
+ /**
1096
+ * Takes the "Hyperlink" character style off text whose link is removed.
1097
+ * @internal
1098
+ */
1055
1099
  export function unstyleLink(tr: Transaction, state: EditorState, from: number, to: number): void {
1056
1100
  const context = wordContext(state);
1057
1101
  const type = state.schema.marks.characterStyle;