@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
@@ -1,5 +1,5 @@
1
1
  import type { DocumentSettings, FoliDocumentV2 } from "../document.js";
2
- import { type Attrs, type Node, Slice } from "../model/index.js";
2
+ import { type Attrs, type Node, type Schema, Slice } from "../model/index.js";
3
3
  import type { Alignment } from "../schema.js";
4
4
  import {
5
5
  createDocument,
@@ -8,6 +8,7 @@ import {
8
8
  parseDocument,
9
9
  type SectionJSON,
10
10
  } from "../v3/document.js";
11
+ import { type Extension, schemaWith, writeCustom } from "../v3/extensions.js";
11
12
  import { twipsToMm as mm } from "../v3/units.js";
12
13
  import {
13
14
  baseKeymap,
@@ -63,8 +64,8 @@ import {
63
64
  } from "./review.js";
64
65
  import type { StorySide, StoryVariant } from "./sections.js";
65
66
  import { Selection, TextSelection } from "./selection.js";
66
- import { type Command, EditorState, type Plugin, type Transaction } from "./state.js";
67
- import { StoryEditing } from "./stories.js";
67
+ import { type Command, EditorState, Plugin, PluginKey, type Transaction } from "./state.js";
68
+ import { callListener, StoryEditing } from "./stories.js";
68
69
  import { tableKeymap } from "./tables.js";
69
70
  import {
70
71
  type ReviewView,
@@ -75,7 +76,14 @@ import {
75
76
  trackState,
76
77
  trackTransaction,
77
78
  } from "./track.js";
78
- import { storyBody, type WordContext, type WordEnvelope, wordContext, wordPlugin } from "./word.js";
79
+ import {
80
+ documentJSON,
81
+ storyBody,
82
+ type WordContext,
83
+ type WordEnvelope,
84
+ wordContext,
85
+ wordPlugin,
86
+ } from "./word.js";
79
87
  import type { ListKind } from "./wordformat.js";
80
88
 
81
89
  /**
@@ -89,6 +97,12 @@ export interface EditorOptions {
89
97
  document?: EditorDocument;
90
98
  /** Run before the built-in plugins, so their keymaps take precedence. */
91
99
  plugins?: readonly Plugin[];
100
+ /**
101
+ * Custom node and mark types and their plugins (ADR-0008), added to the Word schema. Their
102
+ * plugins run after `plugins`, before the built-ins. Content of types none of them declares is
103
+ * kept as foreign nodes and marks and saved back unchanged.
104
+ */
105
+ extensions?: readonly Extension[];
92
106
  /** Who edits: tracked changes are made in this name. Default "Author". */
93
107
  author?: string;
94
108
  /**
@@ -168,6 +182,85 @@ export interface StoryView {
168
182
  focus(): void;
169
183
  }
170
184
 
185
+ /** The built-in commands on `editor.commands`. */
186
+ export interface BuiltInCommands {
187
+ insertText(text: string): boolean;
188
+ deleteSelection(): boolean;
189
+ deleteBackward(unit?: DeleteUnit): boolean;
190
+ deleteForward(unit?: DeleteUnit): boolean;
191
+ joinBackward(): boolean;
192
+ joinForward(): boolean;
193
+ splitBlock(): boolean;
194
+ insertHardBreak(): boolean;
195
+ insertPageBreak(): boolean;
196
+ toggleMark(type: string, attrs?: Attrs | null): boolean;
197
+ setBlockType(type: string, attrs?: Attrs | null): boolean;
198
+ selectAll(): boolean;
199
+ undo(): boolean;
200
+ redo(): boolean;
201
+ /** Numbers the selected paragraphs as a list ("bulletList" or "orderedList"). */
202
+ wrapInList(kind: ListKind): boolean;
203
+ /** The list buttons: removes the selection's numbering when it is a list of `kind`, else numbers it. */
204
+ toggleList(kind: ListKind): boolean;
205
+ /** Tab in a list: one level deeper. */
206
+ indentListItem(): boolean;
207
+ /** Shift+Tab in a list: one level up (out of the list at the top). */
208
+ outdentListItem(): boolean;
209
+ /**
210
+ * Links the selection to `href` (normalized, then validated: unsafe hrefs do not apply); at
211
+ * a caret in a link, changes it; elsewhere inserts the href as linked text.
212
+ */
213
+ setLink(href: string): boolean;
214
+ /** Removes the links in the selection, or the link around the caret. */
215
+ removeLink(): boolean;
216
+ /** Aligns the selected paragraphs and headings ("start", "center", "end", "justify"). */
217
+ setAlign(align: Alignment): boolean;
218
+ /** Text color (lowercase `#rrggbb`) of the selected or next typed text; null removes it. */
219
+ setTextColor(color: string | null): boolean;
220
+ /** Highlight (`#rrggbb`) of the selected or next typed text; null removes it. */
221
+ setHighlight(color: string | null): boolean;
222
+ /** Turns tracked changes on or off (`author` changes who makes them). */
223
+ setTrackChanges(on: boolean, author?: string): boolean;
224
+ /** How the editor's views show tracked changes. */
225
+ setReviewView(view: ReviewView): boolean;
226
+ /** Accepts the change at the caret, or the changes in the selection. */
227
+ acceptChange(): boolean;
228
+ /** Rejects the change at the caret, or the changes in the selection. */
229
+ rejectChange(): boolean;
230
+ /** Accepts every change, or every change of `author`. */
231
+ acceptAllChanges(author?: string): boolean;
232
+ /** Rejects every change, or every change of `author`. */
233
+ rejectAllChanges(author?: string): boolean;
234
+ /** Selects the next change after the selection. */
235
+ nextChange(): boolean;
236
+ /** Selects the previous change before the selection. */
237
+ previousChange(): boolean;
238
+ /** Comments the selection (at a caret, the point there). */
239
+ addComment(content: CommentContent, options?: CommentOptions): boolean;
240
+ /** Replies to a comment's thread. */
241
+ replyToComment(id: number, content: CommentContent, options?: CommentOptions): boolean;
242
+ /** Replaces a comment's content. */
243
+ editComment(id: number, content: CommentContent): boolean;
244
+ /** Resolves (`done` false: reopens) a comment's thread. */
245
+ resolveComment(id: number, done?: boolean): boolean;
246
+ /** Deletes a comment, its replies and their anchors. */
247
+ deleteComment(id: number): boolean;
248
+ /** Deletes every comment. */
249
+ deleteAllComments(): boolean;
250
+ /**
251
+ * Fills the content controls with this id or tag, here and in the stories (from the body's
252
+ * editor): one undo step, tracked when tracking is on. False when none could take it.
253
+ */
254
+ setControlValue(target: string, value: ControlValueInput): boolean;
255
+ }
256
+
257
+ /**
258
+ * The commands on `editor.commands`: the built-in ones and those plugins add. Apps add the names
259
+ * of their plugins' commands by augmenting it:
260
+ * `declare module "@folijs/core" { interface FoliCommands { insertMention(id: string): boolean } }`.
261
+ */
262
+ export interface FoliCommands extends BuiltInCommands {}
263
+
171
264
  /** A headless editor: state, commands, history and change notifications, no DOM. */
172
265
  export interface Editor {
173
266
  readonly state: EditorState;
@@ -185,76 +278,11 @@ export interface Editor {
185
278
  handleKey(key: string): boolean;
186
279
  /** Places a text selection (positions are clamped into the document). */
187
280
  select(anchor: number, head?: number): void;
188
- readonly commands: {
189
- insertText(text: string): boolean;
190
- deleteSelection(): boolean;
191
- deleteBackward(unit?: DeleteUnit): boolean;
192
- deleteForward(unit?: DeleteUnit): boolean;
193
- joinBackward(): boolean;
194
- joinForward(): boolean;
195
- splitBlock(): boolean;
196
- insertHardBreak(): boolean;
197
- insertPageBreak(): boolean;
198
- toggleMark(type: string, attrs?: Attrs | null): boolean;
199
- setBlockType(type: string, attrs?: Attrs | null): boolean;
200
- selectAll(): boolean;
201
- undo(): boolean;
202
- redo(): boolean;
203
- /** Numbers the selected paragraphs as a list ("bulletList" or "orderedList"). */
204
- wrapInList(kind: ListKind): boolean;
205
- /** The list buttons: removes the selection's numbering when it is a list of `kind`, else numbers it. */
206
- toggleList(kind: ListKind): boolean;
207
- /** Tab in a list: one level deeper. */
208
- indentListItem(): boolean;
209
- /** Shift+Tab in a list: one level up (out of the list at the top). */
210
- outdentListItem(): boolean;
211
- /**
212
- * Links the selection to `href` (normalized, then validated: unsafe hrefs do not apply); at
213
- * a caret in a link, changes it; elsewhere inserts the href as linked text.
214
- */
215
- setLink(href: string): boolean;
216
- /** Removes the links in the selection, or the link around the caret. */
217
- removeLink(): boolean;
218
- /** Aligns the selected paragraphs and headings ("start", "center", "end", "justify"). */
219
- setAlign(align: Alignment): boolean;
220
- /** Text color (lowercase `#rrggbb`) of the selected or next typed text; null removes it. */
221
- setTextColor(color: string | null): boolean;
222
- /** Highlight (`#rrggbb`) of the selected or next typed text; null removes it. */
223
- setHighlight(color: string | null): boolean;
224
- /** Turns tracked changes on or off (`author` changes who makes them). */
225
- setTrackChanges(on: boolean, author?: string): boolean;
226
- /** How the editor's views show tracked changes. */
227
- setReviewView(view: ReviewView): boolean;
228
- /** Accepts the change at the caret, or the changes in the selection. */
229
- acceptChange(): boolean;
230
- /** Rejects the change at the caret, or the changes in the selection. */
231
- rejectChange(): boolean;
232
- /** Accepts every change, or every change of `author`. */
233
- acceptAllChanges(author?: string): boolean;
234
- /** Rejects every change, or every change of `author`. */
235
- rejectAllChanges(author?: string): boolean;
236
- /** Selects the next change after the selection. */
237
- nextChange(): boolean;
238
- /** Selects the previous change before the selection. */
239
- previousChange(): boolean;
240
- /** Comments the selection (at a caret, the point there). */
241
- addComment(content: CommentContent, options?: CommentOptions): boolean;
242
- /** Replies to a comment's thread. */
243
- replyToComment(id: number, content: CommentContent, options?: CommentOptions): boolean;
244
- /** Replaces a comment's content. */
245
- editComment(id: number, content: CommentContent): boolean;
246
- /** Resolves (`done` false: reopens) a comment's thread. */
247
- resolveComment(id: number, done?: boolean): boolean;
248
- /** Deletes a comment, its replies and their anchors. */
249
- deleteComment(id: number): boolean;
250
- /** Deletes every comment. */
251
- deleteAllComments(): boolean;
252
- /**
253
- * Fills the content controls with this id or tag, here and in the stories (from the body's
254
- * editor): one undo step, tracked when tracking is on. False when none could take it.
255
- */
256
- setControlValue(target: string, value: ControlValueInput): boolean;
257
- };
281
+ /**
282
+ * The named commands: the built-in ones and those plugins add (`PluginSpec.commands`), each
283
+ * run on this editor; whether it applied.
284
+ */
285
+ readonly commands: FoliCommands;
258
286
  /** The content controls' values, the stories' after the body's (from the body's editor). */
259
287
  controlValues(): ControlValue[];
260
288
  /** Whether edits are recorded as tracked changes. */
@@ -281,6 +309,11 @@ export interface Editor {
281
309
  * a key to the browser when it answers false, or when there is none.
282
310
  */
283
311
  navigation: ((request: NavigationRequest) => boolean) | null;
312
+ /**
313
+ * The extensions it was made with (`EditorOptions.extensions`), the same list on its stories'
314
+ * editors: a view reads its view hooks from them (`ViewExtension` in `@folijs/view`).
315
+ */
316
+ readonly extensions: readonly Extension[];
284
317
  }
285
318
 
286
319
  /** Word's page when a section leaves it out: Letter, 1 inch margins. */
@@ -310,9 +343,17 @@ interface Loaded {
310
343
  }
311
344
 
312
345
  /** Validates (and migrates) a document and reads what the editor keeps of it. */
313
- function load(document: EditorDocument): Loaded {
314
- const { content, ...envelope } = parseDocument(document);
315
- return { doc: parseContent(content), settings: sectionSettings(envelope.section), envelope };
346
+ function loadDocument(
347
+ document: EditorDocument,
348
+ extensions: readonly Extension[],
349
+ schema: Schema,
350
+ ): Loaded {
351
+ const { content, ...envelope } = parseDocument(document, { extensions });
352
+ return {
353
+ doc: parseContent(content, { schema }),
354
+ settings: sectionSettings(envelope.section),
355
+ envelope,
356
+ };
316
357
  }
317
358
 
318
359
  /** What differs between the editor of the body and of a story. */
@@ -327,6 +368,9 @@ interface EditorParts {
327
368
  /** The view opening stories, and the navigation UI: one for the body and its stories. */
328
369
  views: { current: StoryView | null; navigation: Editor["navigation"] };
329
370
  storyChanged(): void;
371
+ extensions: readonly Extension[];
372
+ /** The user's and extensions' plugins: their `commands` join the built-in ones. */
373
+ plugins: readonly Plugin[];
330
374
  }
331
375
 
332
376
  function makeEditor(parts: EditorParts): Editor {
@@ -345,6 +389,58 @@ function makeEditor(parts: EditorParts): Editor {
345
389
  }),
346
390
  ];
347
391
  };
392
+ // Each named command as a factory, so `editorCommand` can give it for a dry run.
393
+ const factories = withPluginFactories(parts.plugins, {
394
+ insertText: (text) => insertText(text),
395
+ deleteSelection: () => deleteSelection,
396
+ deleteBackward: (unit) => deleteBackward(unit),
397
+ deleteForward: (unit) => deleteForward(unit),
398
+ joinBackward: () => joinBackward,
399
+ joinForward: () => joinForward,
400
+ splitBlock: () => splitBlock,
401
+ insertHardBreak: () => insertHardBreak,
402
+ insertPageBreak: () => insertPageBreak,
403
+ toggleMark: (type, attrs) => toggleMark(type, attrs),
404
+ setBlockType: (type, attrs) => setBlockType(type, attrs),
405
+ selectAll: () => selectAll,
406
+ undo: () => undo,
407
+ redo: () => redo,
408
+ wrapInList: (kind) => wrapInList(kind),
409
+ toggleList: (kind) => toggleList(kind),
410
+ indentListItem: () => sinkListItem,
411
+ outdentListItem: () => liftListItem,
412
+ setLink: (href) => setLink(href),
413
+ removeLink: () => removeLink,
414
+ setAlign: (align) => setAlign(align),
415
+ setTextColor: (color) => setTextColor(color),
416
+ setHighlight: (color) => setHighlight(color),
417
+ setTrackChanges: (on, name) => setTrackChanges(on, name),
418
+ setReviewView: (view) => setReviewView(view),
419
+ acceptChange: () => acceptChange,
420
+ rejectChange: () => rejectChange,
421
+ acceptAllChanges: (name) => acceptAllChanges(name),
422
+ rejectAllChanges: (name) => rejectAllChanges(name),
423
+ nextChange: () => nextChange,
424
+ previousChange: () => previousChange,
425
+ addComment: (content, options) => addComment(content, options),
426
+ replyToComment: (id, content, options) => replyToComment(id, content, options),
427
+ editComment: (id, content) => editComment(id, content),
428
+ resolveComment: (id, done) => resolveComment(id, done),
429
+ deleteComment: (id) => deleteComment(id),
430
+ deleteAllComments: () => deleteAllComments,
431
+ // Across the body and its stories: `state` is the body's; a dry run asks each editor.
432
+ setControlValue: (target, value) => (_state, dispatch) => {
433
+ let done = false;
434
+ for (const { editor } of withStories())
435
+ if (
436
+ dispatch
437
+ ? editor.run(setControlValue(target, value, done))
438
+ : editor.can(setControlValue(target, value, done))
439
+ )
440
+ done = true;
441
+ return done;
442
+ },
443
+ });
348
444
  const self: Editor = {
349
445
  get settings() {
350
446
  return parts.settings();
@@ -368,51 +464,7 @@ function makeEditor(parts: EditorParts): Editor {
368
464
  const clamp = (pos: number) => Math.max(0, Math.min(pos, size));
369
465
  dispatch(state.tr.setSelection(TextSelection.create(state.doc, clamp(anchor), clamp(head))));
370
466
  },
371
- commands: {
372
- insertText: (text) => run(insertText(text)),
373
- deleteSelection: () => run(deleteSelection),
374
- deleteBackward: (unit) => run(deleteBackward(unit)),
375
- deleteForward: (unit) => run(deleteForward(unit)),
376
- joinBackward: () => run(joinBackward),
377
- joinForward: () => run(joinForward),
378
- splitBlock: () => run(splitBlock),
379
- insertHardBreak: () => run(insertHardBreak),
380
- insertPageBreak: () => run(insertPageBreak),
381
- toggleMark: (type, attrs) => run(toggleMark(type, attrs)),
382
- setBlockType: (type, attrs) => run(setBlockType(type, attrs)),
383
- selectAll: () => run(selectAll),
384
- undo: () => run(undo),
385
- redo: () => run(redo),
386
- wrapInList: (kind) => run(wrapInList(kind)),
387
- toggleList: (kind) => run(toggleList(kind)),
388
- indentListItem: () => run(sinkListItem),
389
- outdentListItem: () => run(liftListItem),
390
- setLink: (href) => run(setLink(href)),
391
- removeLink: () => run(removeLink),
392
- setAlign: (align) => run(setAlign(align)),
393
- setTextColor: (color) => run(setTextColor(color)),
394
- setHighlight: (color) => run(setHighlight(color)),
395
- setTrackChanges: (on, name) => run(setTrackChanges(on, name)),
396
- setReviewView: (view) => run(setReviewView(view)),
397
- acceptChange: () => run(acceptChange),
398
- rejectChange: () => run(rejectChange),
399
- acceptAllChanges: (name) => run(acceptAllChanges(name)),
400
- rejectAllChanges: (name) => run(rejectAllChanges(name)),
401
- nextChange: () => run(nextChange),
402
- previousChange: () => run(previousChange),
403
- addComment: (content, options) => run(addComment(content, options)),
404
- replyToComment: (id, content, options) => run(replyToComment(id, content, options)),
405
- editComment: (id, content) => run(editComment(id, content)),
406
- resolveComment: (id, done) => run(resolveComment(id, done)),
407
- deleteComment: (id) => run(deleteComment(id)),
408
- deleteAllComments: () => run(deleteAllComments),
409
- setControlValue(target, value) {
410
- let done = false;
411
- for (const { editor } of withStories())
412
- if (editor.run(setControlValue(target, value, done))) done = true;
413
- return done;
414
- },
415
- },
467
+ commands: commandsOf(factories, run),
416
468
  controlValues: () =>
417
469
  withStories().flatMap(({ editor, story }) =>
418
470
  controlValues(editor.state).map((value) => (story ? { ...value, story } : value)),
@@ -432,6 +484,7 @@ function makeEditor(parts: EditorParts): Editor {
432
484
  parts.views.current = view;
433
485
  },
434
486
  storyChanged: parts.storyChanged,
487
+ extensions: parts.extensions,
435
488
  get navigation() {
436
489
  return parts.views.navigation;
437
490
  },
@@ -439,20 +492,85 @@ function makeEditor(parts: EditorParts): Editor {
439
492
  parts.views.navigation = handler;
440
493
  },
441
494
  };
495
+ commandFactories.set(self, factories);
442
496
  return self;
443
497
  }
444
498
 
499
+ /** The built-in commands as factories of the commands they run. */
500
+ type BuiltInFactories = {
501
+ [K in keyof BuiltInCommands]: (...args: Parameters<BuiltInCommands[K]>) => Command;
502
+ };
503
+ type Factories = Record<string, (...args: never[]) => Command>;
504
+
505
+ /**
506
+ * Adds the command factories `plugins` name (`PluginSpec.commands`) to the built-in ones. A name
507
+ * taken twice, or by a built-in command, throws.
508
+ */
509
+ function withPluginFactories(plugins: readonly Plugin[], builtIns: BuiltInFactories): Factories {
510
+ const factories: Factories = { ...builtIns };
511
+ for (const plugin of plugins)
512
+ for (const [name, factory] of Object.entries(plugin.spec.commands ?? {})) {
513
+ if (Object.hasOwn(factories, name))
514
+ throw new RangeError(
515
+ `Command "${name}" is already defined: plugin commands need names of their own`,
516
+ );
517
+ if (typeof factory !== "function")
518
+ throw new TypeError(`Command "${name}" is not a function returning a command`);
519
+ // defineProperty: a name such as "__proto__" is a command, not the object's prototype.
520
+ Object.defineProperty(factories, name, { value: factory, enumerable: true });
521
+ }
522
+ return factories;
523
+ }
524
+
525
+ /** `editor.commands`: each factory's command run on the editor. */
526
+ function commandsOf(factories: Factories, run: (command: Command) => boolean): FoliCommands {
527
+ const commands = {};
528
+ for (const [name, factory] of Object.entries(factories))
529
+ Object.defineProperty(commands, name, {
530
+ value: (...args: never[]) => run(factory(...args)),
531
+ enumerable: true,
532
+ });
533
+ return commands as FoliCommands;
534
+ }
535
+
536
+ const commandFactories = new WeakMap<Editor, Factories>();
537
+
538
+ /**
539
+ * The command `editor.commands[name](...args)` would run, for a dry run (`editor.can`): built-in
540
+ * or a plugin's; undefined when the editor has no command of that name.
541
+ */
542
+ export function editorCommand(
543
+ editor: Editor,
544
+ name: string,
545
+ args: readonly unknown[],
546
+ ): Command | undefined {
547
+ const factories = commandFactories.get(editor);
548
+ const factory = factories && Object.hasOwn(factories, name) ? factories[name] : undefined;
549
+ return factory?.(...(args as never[]));
550
+ }
551
+
552
+ /**
553
+ * Where the view's own overridable keys run (ADR-0008, `docs/keyboard.md`): a plugin
554
+ * with no keymap placed after the user's plugins and before the built-in ones.
555
+ */
556
+ export const viewKeys = new PluginKey<never>("viewKeys");
557
+
445
558
  export function createEditor({
446
559
  document = createDocument(),
447
560
  plugins = [],
561
+ extensions = [],
448
562
  author = "Author",
449
563
  trackChanges = false,
450
564
  reviewView = "markup",
451
565
  }: EditorOptions = {}): Editor {
566
+ const schema = schemaWith(extensions);
567
+ const own = [...plugins, ...extensions.flatMap((e) => e.plugins ?? [])];
568
+ const load = (next: EditorDocument) => loadDocument(next, extensions, schema);
452
569
  let loaded = load(document);
453
570
  let track: TrackState = { on: trackChanges, author, view: reviewView };
454
571
  const pluginsFor = ({ envelope }: Loaded) => [
455
- ...plugins,
572
+ ...own,
573
+ new Plugin({ key: viewKeys }),
456
574
  history(),
457
575
  wordPlugin(envelope),
458
576
  trackPlugin(track),
@@ -471,7 +589,7 @@ export function createEditor({
471
589
  const stories = new Map<string, { editing: StoryEditing; editor: Editor }>();
472
590
 
473
591
  const notify = (transactions: readonly Transaction[]) => {
474
- for (const listener of listeners) listener(state, transactions);
592
+ for (const listener of listeners) callListener(listener, state, transactions);
475
593
  };
476
594
  const storyChanged = () => notify([]);
477
595
  const dispatch = (tr: Transaction) => {
@@ -496,10 +614,8 @@ export function createEditor({
496
614
  if (section !== current.section) current = { section, settings: sectionSettings(section) };
497
615
  return current.settings;
498
616
  };
499
- const getDocument = (): FoliDocument => ({
500
- ...structuredClone(wordContext(state)?.envelope ?? loaded.envelope),
501
- content: state.doc.toJSON(),
502
- });
617
+ const getDocument = (): FoliDocument =>
618
+ documentJSON(wordContext(state)?.envelope ?? loaded.envelope, state.doc);
503
619
 
504
620
  const storyEditor = (id: string): Editor => {
505
621
  const editing = new StoryEditing(id, {
@@ -510,7 +626,8 @@ export function createEditor({
510
626
  can: (command) => command(state),
511
627
  dispatch,
512
628
  plugins: (context: WordContext, value) => [
513
- ...plugins,
629
+ ...own,
630
+ new Plugin({ key: viewKeys }),
514
631
  wordPlugin(context.envelope, context),
515
632
  trackPlugin(value ?? track),
516
633
  fieldsPlugin(),
@@ -525,7 +642,7 @@ export function createEditor({
525
642
  state: () => editing.state,
526
643
  dispatch: editing.dispatch,
527
644
  settings,
528
- getDocument: () => ({ ...getDocument(), content: editing.state.doc.toJSON() }),
645
+ getDocument: () => ({ ...getDocument(), content: writeCustom(editing.state.doc.toJSON()) }),
529
646
  setDocument(next) {
530
647
  const { doc } = load(next);
531
648
  const tr = editing.state.tr.replace(
@@ -542,6 +659,8 @@ export function createEditor({
542
659
  story,
543
660
  views,
544
661
  storyChanged,
662
+ extensions,
663
+ plugins: own,
545
664
  });
546
665
  stories.set(id, { editing, editor });
547
666
  return editor;
@@ -569,5 +688,7 @@ export function createEditor({
569
688
  story,
570
689
  views,
571
690
  storyChanged,
691
+ extensions,
692
+ plugins: own,
572
693
  });
573
694
  }
@@ -163,7 +163,10 @@ export function fieldAround(tree: Node, pos: number): Field | null {
163
163
  return found;
164
164
  }
165
165
 
166
- /** The innermost field holding the node at `pos`: the field a marker there belongs to. */
166
+ /**
167
+ * The innermost field holding the node at `pos`: the field a marker there belongs to.
168
+ * @internal
169
+ */
167
170
  export function fieldOfPart(tree: Node, pos: number): Field | null {
168
171
  let found: Field | null = null;
169
172
  for (const field of fieldsIn(tree)) {
@@ -173,7 +176,10 @@ export function fieldOfPart(tree: Node, pos: number): Field | null {
173
176
  return found;
174
177
  }
175
178
 
176
- /** Field markers a caret walking over a paragraph meets. */
179
+ /**
180
+ * Field markers a caret walking over a paragraph meets.
181
+ * @internal
182
+ */
177
183
  export const isFieldPart = (node: Node | null | undefined): boolean =>
178
184
  !!node && FIELD_PARTS.has(node.type.name);
179
185
  const FIELD_PARTS = new Set(["fieldStart", "fieldCode", "fieldSeparator", "fieldEnd"]);
@@ -406,7 +412,10 @@ export function caretStop(state: EditorState, pos: number, forward: boolean): nu
406
412
  }
407
413
  }
408
414
 
409
- /** The fields' state, and the selection kept to their rules. */
415
+ /**
416
+ * The fields' state, and the selection kept to their rules.
417
+ * @internal
418
+ */
410
419
  export function fieldsPlugin(): Plugin<boolean> {
411
420
  return new Plugin({
412
421
  key,
@@ -427,6 +436,9 @@ export function fieldsPlugin(): Plugin<boolean> {
427
436
  });
428
437
  }
429
438
 
430
- /** The whole of `field` as a selection. */
439
+ /**
440
+ * The whole of `field` as a selection.
441
+ * @internal
442
+ */
431
443
  export const fieldSelection = (tree: Node, field: Field): Selection =>
432
444
  TextSelection.create(tree, field.from, field.to);
@@ -475,6 +475,7 @@ function resultMarks(field: Field, instruction: FieldInstruction): readonly Mark
475
475
  * What a bookmark holds, as inline nodes. Field codes and markers stay behind.
476
476
  * shortcut: a paragraph end inside the bookmark becomes a line break, where Word's result has the
477
477
  * paragraph; make it a slice when a document needs it.
478
+ * @internal
478
479
  */
479
480
  export function bookmarkContent(tree: Node, mark: Bookmark): Node[] {
480
481
  const schema = tree.type.schema;
package/src/state/find.ts CHANGED
@@ -41,7 +41,7 @@ export interface FindMatch {
41
41
 
42
42
  /** Why a match was left as it is. */
43
43
  export type ReplaceRefusal =
44
- /** In a content control that is locked or filled from bound data. */
44
+ /** In a content control that is locked or filled from bound data, or in a custom node. */
45
45
  | "locked"
46
46
  /** A control's kind does not take it, or the match runs over a control's edge. */
47
47
  | "control"
@@ -168,7 +168,7 @@ interface Piece {
168
168
  at: number;
169
169
  length: number;
170
170
  pos: number;
171
- /** A field code: one node, however long its text. */
171
+ /** A field code or a custom node: one node, however long its text. */
172
172
  code: boolean;
173
173
  }
174
174
 
@@ -265,6 +265,8 @@ function linesOf(tree: Node, scope: Scope, story: boolean): Line[] {
265
265
  else if (name === "tab") add("\t", at);
266
266
  else if (name === "hardBreak") add("\n", at);
267
267
  else if (name === "fieldCode" && scope.codes) add(String(child.attrs.text ?? ""), at, true);
268
+ // A custom or foreign node (ADR-0008): found by its text, one position, never replaced.
269
+ else if (child.type.spec.text) add(child.type.spec.text(child.attrs), at, true);
268
270
  else if (!isUnseen(child)) text += BARRIER;
269
271
  });
270
272
  if (text) lines.push({ text, pieces });
@@ -380,7 +382,10 @@ function applyHit(tr: Transaction, { parts }: Hit, text: string): number {
380
382
  function refusalOf(state: EditorState, scope: Scope, hit: Hit, text: string) {
381
383
  const tree = state.doc;
382
384
  const { parts, match } = hit;
383
- if (parts.some((part) => part.code)) return "field-code";
385
+ if (parts.some((part) => part.code))
386
+ return parts.some((part) => part.code && tree.nodeAt(part.from)?.type.spec.text)
387
+ ? "locked"
388
+ : "field-code";
384
389
  if (parts.some((part) => tree.nodeAt(part.from)?.marks.some((m) => m.type.name === "deletion")))
385
390
  return "deleted";
386
391
  const first = parts[0] as Hit["parts"][number];
@@ -473,7 +478,10 @@ export function replaceAll(
473
478
  return replaceHits(editor, hits, text, options.matchCase === true, false);
474
479
  }
475
480
 
476
- /** The story `editor` edits; null for the body's. */
481
+ /**
482
+ * The story `editor` edits; null for the body's.
483
+ * @internal
484
+ */
477
485
  export function storyOfEditor(editor: Editor): string | null {
478
486
  const body = storyBody(editor.state)?.state;
479
487
  return body ? storyIdOf(body, editor.state.doc) : null;
@@ -45,8 +45,10 @@ export const joinHistory = "joinHistory";
45
45
  /**
46
46
  * On a body transaction carrying a story's change: the story's id and its own transaction, which
47
47
  * decides what typing joins, as the body's does for body typing.
48
+ * @internal
48
49
  */
49
50
  export const storyEdit = "storyEdit";
51
+ /** @internal */
50
52
  export interface StoryEdit {
51
53
  id: string;
52
54
  tr: Transaction;