@aionbuilders/nabu 0.1.0-beta.0 → 0.1.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 (306) hide show
  1. package/CHANGELOG.md +523 -0
  2. package/LICENSE +21 -0
  3. package/README.md +72 -341
  4. package/dist/behaviors/text/RichText.svelte +24 -4
  5. package/dist/behaviors/text/markdown-shortcuts.extension.d.ts +3 -0
  6. package/dist/behaviors/text/markdown-shortcuts.extension.js +35 -10
  7. package/dist/behaviors/text/markdown-syntax.d.ts +42 -0
  8. package/dist/behaviors/text/markdown-syntax.js +81 -0
  9. package/dist/behaviors/text/rich-text.extension.d.ts +3 -0
  10. package/dist/behaviors/text/rich-text.extension.js +95 -38
  11. package/dist/behaviors/text/text.behavior.svelte.d.ts +199 -48
  12. package/dist/behaviors/text/text.behavior.svelte.js +549 -83
  13. package/dist/behaviors/text/typography.extension.d.ts +2 -1
  14. package/dist/behaviors/text/typography.extension.js +3 -2
  15. package/dist/blocks/BlockList.svelte +48 -0
  16. package/dist/blocks/BlockList.svelte.d.ts +17 -0
  17. package/dist/blocks/Nabu.svelte +169 -25
  18. package/dist/blocks/Nabu.svelte.d.ts +13 -0
  19. package/dist/blocks/block.extension.d.ts +3 -0
  20. package/dist/blocks/block.extension.js +4 -7
  21. package/dist/blocks/block.svelte.d.ts +350 -86
  22. package/dist/blocks/block.svelte.js +370 -59
  23. package/dist/blocks/blockquote/Blockquote.svelte +1 -2
  24. package/dist/blocks/blockquote/blockquote.extension.d.ts +4 -1
  25. package/dist/blocks/blockquote/blockquote.extension.js +14 -5
  26. package/dist/blocks/blockquote/blockquote.svelte.d.ts +19 -11
  27. package/dist/blocks/blockquote/blockquote.svelte.js +58 -13
  28. package/dist/blocks/callout/Callout.svelte +6 -8
  29. package/dist/blocks/callout/callout.extension.d.ts +4 -1
  30. package/dist/blocks/callout/callout.extension.js +19 -3
  31. package/dist/blocks/callout/callout.svelte.d.ts +5 -3
  32. package/dist/blocks/callout/callout.svelte.js +11 -6
  33. package/dist/blocks/chunks.d.ts +49 -0
  34. package/dist/blocks/chunks.js +90 -0
  35. package/dist/blocks/code/Code.svelte +7 -8
  36. package/dist/blocks/code/code.extension.d.ts +4 -1
  37. package/dist/blocks/code/code.extension.js +22 -2
  38. package/dist/blocks/code/code.svelte.d.ts +9 -2
  39. package/dist/blocks/code/code.svelte.js +49 -25
  40. package/dist/blocks/container.utils.d.ts +85 -13
  41. package/dist/blocks/container.utils.js +338 -178
  42. package/dist/blocks/dialogue/Dialogue.svelte +8 -4
  43. package/dist/blocks/dialogue/dialogue.svelte.d.ts +33 -2
  44. package/dist/blocks/dialogue/dialogue.svelte.js +58 -4
  45. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.d.ts +2 -2
  46. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.js +6 -4
  47. package/dist/blocks/dialogue/index.d.ts +12 -1
  48. package/dist/blocks/dialogue/index.js +51 -35
  49. package/dist/blocks/divider/divider.extension.d.ts +23 -1
  50. package/dist/blocks/divider/divider.extension.js +85 -19
  51. package/dist/blocks/divider/divider.svelte.d.ts +7 -2
  52. package/dist/blocks/divider/divider.svelte.js +9 -4
  53. package/dist/blocks/file/File.svelte +13 -6
  54. package/dist/blocks/file/file.extension.d.ts +4 -1
  55. package/dist/blocks/file/file.extension.js +9 -1
  56. package/dist/blocks/file/file.svelte.d.ts +3 -3
  57. package/dist/blocks/file/file.svelte.js +20 -14
  58. package/dist/blocks/heading/Heading.svelte +1 -2
  59. package/dist/blocks/heading/heading.svelte.d.ts +23 -11
  60. package/dist/blocks/heading/heading.svelte.js +68 -13
  61. package/dist/blocks/heading/hooks/onBeforeInput.hook.js +7 -5
  62. package/dist/blocks/heading/index.d.ts +2 -2
  63. package/dist/blocks/heading/index.js +33 -8
  64. package/dist/blocks/image/Image.svelte +5 -2
  65. package/dist/blocks/image/image.extension.d.ts +4 -1
  66. package/dist/blocks/image/image.extension.js +9 -1
  67. package/dist/blocks/image/image.svelte.d.ts +17 -6
  68. package/dist/blocks/image/image.svelte.js +33 -11
  69. package/dist/blocks/index.d.ts +1 -1
  70. package/dist/blocks/index.js +1 -1
  71. package/dist/blocks/list/List.svelte +1 -0
  72. package/dist/blocks/list/ListItem.svelte +1 -0
  73. package/dist/blocks/list/convert.d.ts +20 -0
  74. package/dist/blocks/list/convert.js +92 -0
  75. package/dist/blocks/list/hooks/onBeforeInput.hook.js +49 -28
  76. package/dist/blocks/list/html-flat.d.ts +78 -0
  77. package/dist/blocks/list/html-flat.js +244 -0
  78. package/dist/blocks/list/indent.d.ts +86 -0
  79. package/dist/blocks/list/indent.js +205 -0
  80. package/dist/blocks/list/index.d.ts +6 -3
  81. package/dist/blocks/list/index.js +42 -31
  82. package/dist/blocks/list/list-item.svelte.d.ts +31 -17
  83. package/dist/blocks/list/list-item.svelte.js +99 -100
  84. package/dist/blocks/list/list.behavior.svelte.d.ts +4 -1
  85. package/dist/blocks/list/list.behavior.svelte.js +6 -1
  86. package/dist/blocks/list/list.svelte.d.ts +89 -18
  87. package/dist/blocks/list/list.svelte.js +129 -125
  88. package/dist/blocks/list/markdown.d.ts +149 -0
  89. package/dist/blocks/list/markdown.js +442 -0
  90. package/dist/blocks/list/normalize.d.ts +11 -0
  91. package/dist/blocks/list/normalize.js +396 -0
  92. package/dist/blocks/list/paste.d.ts +45 -0
  93. package/dist/blocks/list/paste.js +242 -0
  94. package/dist/blocks/list/step-back.d.ts +24 -0
  95. package/dist/blocks/list/step-back.js +87 -0
  96. package/dist/blocks/list/to-list.d.ts +7 -0
  97. package/dist/blocks/list/to-list.js +44 -0
  98. package/dist/blocks/list/todos-toggle.d.ts +20 -0
  99. package/dist/blocks/list/todos-toggle.js +48 -0
  100. package/dist/blocks/media/markdown.d.ts +12 -0
  101. package/dist/blocks/media/markdown.js +26 -0
  102. package/dist/blocks/media/media-block.svelte.d.ts +77 -2
  103. package/dist/blocks/media/media-block.svelte.js +124 -12
  104. package/dist/blocks/media/media.helpers.d.ts +6 -1
  105. package/dist/blocks/media/media.helpers.js +43 -6
  106. package/dist/blocks/megablock.svelte.d.ts +50 -19
  107. package/dist/blocks/megablock.svelte.js +114 -74
  108. package/dist/blocks/move.d.ts +23 -0
  109. package/dist/blocks/move.js +92 -0
  110. package/dist/blocks/nabu.svelte.d.ts +764 -71
  111. package/dist/blocks/nabu.svelte.js +1746 -189
  112. package/dist/blocks/paragraph/Paragraph.svelte +1 -2
  113. package/dist/blocks/paragraph/index.d.ts +2 -2
  114. package/dist/blocks/paragraph/index.js +35 -13
  115. package/dist/blocks/paragraph/paragraph.svelte.d.ts +46 -14
  116. package/dist/blocks/paragraph/paragraph.svelte.js +77 -16
  117. package/dist/blocks/paragraph/table.html.d.ts +9 -0
  118. package/dist/blocks/paragraph/table.html.js +111 -0
  119. package/dist/blocks/paragraph/table.markdown.d.ts +32 -0
  120. package/dist/blocks/paragraph/table.markdown.js +90 -0
  121. package/dist/blocks/region/Region.svelte +264 -0
  122. package/dist/blocks/region/Region.svelte.d.ts +11 -0
  123. package/dist/blocks/region/actions.d.ts +135 -0
  124. package/dist/blocks/region/actions.js +402 -0
  125. package/dist/blocks/region/close.d.ts +35 -0
  126. package/dist/blocks/region/close.js +130 -0
  127. package/dist/blocks/region/commands.d.ts +6 -0
  128. package/dist/blocks/region/commands.js +277 -0
  129. package/dist/blocks/region/create.d.ts +72 -0
  130. package/dist/blocks/region/create.js +208 -0
  131. package/dist/blocks/region/end-marker.d.ts +35 -0
  132. package/dist/blocks/region/end-marker.js +51 -0
  133. package/dist/blocks/region/facts.d.ts +69 -0
  134. package/dist/blocks/region/facts.js +152 -0
  135. package/dist/blocks/region/format.d.ts +91 -0
  136. package/dist/blocks/region/format.js +260 -0
  137. package/dist/blocks/region/index.d.ts +14 -0
  138. package/dist/blocks/region/index.js +14 -0
  139. package/dist/blocks/region/insert.d.ts +59 -0
  140. package/dist/blocks/region/insert.js +102 -0
  141. package/dist/blocks/region/messages.d.ts +254 -0
  142. package/dist/blocks/region/messages.js +131 -0
  143. package/dist/blocks/region/normalize.d.ts +7 -0
  144. package/dist/blocks/region/normalize.js +170 -0
  145. package/dist/blocks/region/region.extension.d.ts +58 -0
  146. package/dist/blocks/region/region.extension.js +119 -0
  147. package/dist/blocks/region/region.svelte.d.ts +221 -0
  148. package/dist/blocks/region/region.svelte.js +582 -0
  149. package/dist/blocks/region/regions.svelte.d.ts +141 -0
  150. package/dist/blocks/region/regions.svelte.js +276 -0
  151. package/dist/blocks/region/serialize.d.ts +57 -0
  152. package/dist/blocks/region/serialize.js +112 -0
  153. package/dist/blocks/region/types.d.ts +255 -0
  154. package/dist/blocks/region/types.js +204 -0
  155. package/dist/blocks/selection.svelte.d.ts +106 -8
  156. package/dist/blocks/selection.svelte.js +622 -74
  157. package/dist/blocks/subthread.d.ts +80 -0
  158. package/dist/blocks/subthread.js +167 -0
  159. package/dist/blocks/text-block.svelte.d.ts +34 -13
  160. package/dist/blocks/text-block.svelte.js +42 -8
  161. package/dist/blocks/toggle/Toggle.svelte +4 -15
  162. package/dist/blocks/toggle/markdown.d.ts +20 -0
  163. package/dist/blocks/toggle/markdown.js +112 -0
  164. package/dist/blocks/toggle/toggle.extension.d.ts +4 -1
  165. package/dist/blocks/toggle/toggle.extension.js +6 -0
  166. package/dist/blocks/toggle/toggle.svelte.d.ts +54 -7
  167. package/dist/blocks/toggle/toggle.svelte.js +134 -34
  168. package/dist/blocks/undo-selection.d.ts +175 -0
  169. package/dist/blocks/undo-selection.js +360 -0
  170. package/dist/blocks/video/Video.svelte +5 -2
  171. package/dist/blocks/video/video.extension.d.ts +4 -1
  172. package/dist/blocks/video/video.extension.js +9 -1
  173. package/dist/blocks/video/video.svelte.d.ts +6 -5
  174. package/dist/blocks/video/video.svelte.js +18 -9
  175. package/dist/extend.d.ts +55 -0
  176. package/dist/extend.js +88 -0
  177. package/dist/files/assets.clipboard.d.ts +77 -0
  178. package/dist/files/assets.clipboard.js +152 -0
  179. package/dist/files/files.svelte.d.ts +321 -19
  180. package/dist/files/files.svelte.js +847 -43
  181. package/dist/files/index.d.ts +3 -1
  182. package/dist/files/index.js +3 -1
  183. package/dist/files/outbox.d.ts +69 -0
  184. package/dist/files/outbox.js +48 -0
  185. package/dist/files/status.d.ts +65 -0
  186. package/dist/files/status.js +87 -0
  187. package/dist/files/store.d.ts +97 -0
  188. package/dist/files/store.js +65 -0
  189. package/dist/files/uploads.svelte.d.ts +174 -0
  190. package/dist/files/uploads.svelte.js +504 -0
  191. package/dist/index.d.ts +68 -9
  192. package/dist/index.js +117 -10
  193. package/dist/nabu-theme.css +21 -1
  194. package/dist/paste/html.paste.d.ts +74 -3
  195. package/dist/paste/html.paste.js +550 -86
  196. package/dist/paste/markdown-inline.d.ts +86 -0
  197. package/dist/paste/markdown-inline.js +528 -0
  198. package/dist/paste/markdown.paste.d.ts +2 -8
  199. package/dist/paste/markdown.paste.js +78 -94
  200. package/dist/paste/nabu.paste.d.ts +3 -0
  201. package/dist/paste/nabu.paste.js +29 -3
  202. package/dist/paste/plain-text.paste.d.ts +2 -2
  203. package/dist/paste/plain-text.paste.js +3 -3
  204. package/dist/persistence/asset-store.d.ts +51 -0
  205. package/dist/persistence/asset-store.js +103 -0
  206. package/dist/persistence/autosave.d.ts +53 -0
  207. package/dist/persistence/autosave.js +62 -0
  208. package/dist/persistence/compact.d.ts +162 -0
  209. package/dist/persistence/compact.js +141 -0
  210. package/dist/persistence/history.d.ts +77 -0
  211. package/dist/persistence/history.js +176 -0
  212. package/dist/persistence/indexeddb.d.ts +190 -4
  213. package/dist/persistence/indexeddb.js +333 -29
  214. package/dist/persistence/merge.d.ts +38 -0
  215. package/dist/persistence/merge.js +36 -0
  216. package/dist/persistence/outbox.d.ts +25 -0
  217. package/dist/persistence/outbox.js +40 -0
  218. package/dist/persistence/persistence.d.ts +70 -9
  219. package/dist/persistence/persistence.js +507 -35
  220. package/dist/persistence/recovery.d.ts +79 -0
  221. package/dist/persistence/recovery.js +79 -0
  222. package/dist/persistence/release.d.ts +34 -0
  223. package/dist/persistence/release.js +64 -0
  224. package/dist/persistence/state.svelte.d.ts +53 -0
  225. package/dist/persistence/state.svelte.js +48 -0
  226. package/dist/persistence/sync.d.ts +39 -0
  227. package/dist/persistence/sync.js +138 -0
  228. package/dist/persistence/tail.d.ts +42 -0
  229. package/dist/persistence/tail.js +103 -0
  230. package/dist/presets.d.ts +29 -26
  231. package/dist/presets.js +35 -13
  232. package/dist/themes/atelier.css +318 -0
  233. package/dist/ui/CommandChooser.svelte +153 -0
  234. package/dist/ui/CommandChooser.svelte.d.ts +13 -0
  235. package/dist/ui/CommandInvite.svelte +99 -0
  236. package/dist/ui/CommandInvite.svelte.d.ts +12 -0
  237. package/dist/ui/DragHandle.svelte +97 -21
  238. package/dist/ui/FloatingToolbar.svelte +75 -27
  239. package/dist/ui/FloatingToolbar.svelte.d.ts +10 -0
  240. package/dist/ui/SlashMenu.svelte +147 -15
  241. package/dist/ui/SlashMenu.svelte.d.ts +20 -0
  242. package/dist/ui/anchor.d.ts +112 -0
  243. package/dist/ui/anchor.js +136 -0
  244. package/dist/ui/index.d.ts +7 -1
  245. package/dist/ui/index.js +12 -1
  246. package/dist/ui/slash-menu.svelte.d.ts +79 -7
  247. package/dist/ui/slash-menu.svelte.js +85 -51
  248. package/dist/utils/command-confirm.svelte.d.ts +349 -0
  249. package/dist/utils/command-confirm.svelte.js +673 -0
  250. package/dist/utils/commands.d.ts +328 -0
  251. package/dist/utils/commands.js +416 -0
  252. package/dist/utils/dom-scope.d.ts +14 -0
  253. package/dist/utils/dom-scope.js +20 -0
  254. package/dist/utils/drop.d.ts +160 -0
  255. package/dist/utils/drop.js +305 -0
  256. package/dist/utils/extensions.d.ts +439 -45
  257. package/dist/utils/extensions.js +271 -29
  258. package/dist/utils/html.d.ts +44 -0
  259. package/dist/utils/html.js +183 -0
  260. package/dist/utils/index.d.ts +3 -0
  261. package/dist/utils/index.js +3 -0
  262. package/dist/utils/keys.d.ts +120 -0
  263. package/dist/utils/keys.js +248 -0
  264. package/dist/utils/links.d.ts +22 -0
  265. package/dist/utils/links.js +34 -0
  266. package/dist/utils/placeholders.d.ts +81 -3
  267. package/dist/utils/placeholders.js +73 -3
  268. package/dist/utils/selection.svelte.d.ts +47 -19
  269. package/dist/utils/selection.svelte.js +60 -10
  270. package/dist/utils/spellcheck.d.ts +9 -0
  271. package/dist/utils/spellcheck.js +17 -0
  272. package/dist/utils/tab.d.ts +31 -0
  273. package/dist/utils/tab.js +117 -0
  274. package/dist/utils/words.d.ts +7 -0
  275. package/dist/utils/words.js +62 -0
  276. package/dist/vite.d.ts +9 -3
  277. package/dist/vite.js +19 -8
  278. package/package.json +54 -20
  279. package/dist/blocks/variable.svelte.d.ts +0 -47
  280. package/dist/blocks/variable.svelte.js +0 -51
  281. package/dist/blocks/zone/TemplateEditor.svelte +0 -308
  282. package/dist/blocks/zone/TemplateEditor.svelte.d.ts +0 -11
  283. package/dist/blocks/zone/Zone.svelte +0 -272
  284. package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
  285. package/dist/blocks/zone/ZoneEditor.svelte +0 -289
  286. package/dist/blocks/zone/ZoneEditor.svelte.d.ts +0 -11
  287. package/dist/blocks/zone/ZoneTemplatesList.svelte +0 -188
  288. package/dist/blocks/zone/ZoneTemplatesList.svelte.d.ts +0 -11
  289. package/dist/blocks/zone/hooks/onBeforeInput.hook.d.ts +0 -3
  290. package/dist/blocks/zone/hooks/onBeforeInput.hook.js +0 -30
  291. package/dist/blocks/zone/index.d.ts +0 -2
  292. package/dist/blocks/zone/index.js +0 -2
  293. package/dist/blocks/zone/zone.extension.d.ts +0 -2
  294. package/dist/blocks/zone/zone.extension.js +0 -237
  295. package/dist/blocks/zone/zone.svelte.d.ts +0 -221
  296. package/dist/blocks/zone/zone.svelte.js +0 -608
  297. package/dist/overlays/context/Context.svelte +0 -182
  298. package/dist/overlays/context/Context.svelte.d.ts +0 -17
  299. package/dist/overlays/context/collect.d.ts +0 -17
  300. package/dist/overlays/context/collect.js +0 -33
  301. package/dist/overlays/context/context.extension.d.ts +0 -2
  302. package/dist/overlays/context/context.extension.js +0 -8
  303. package/dist/overlays/context/context.svelte.d.ts +0 -82
  304. package/dist/overlays/context/context.svelte.js +0 -159
  305. package/dist/overlays/context/index.d.ts +0 -3
  306. package/dist/overlays/context/index.js +0 -3
@@ -1,102 +1,448 @@
1
+ export function isTransformInput(e: Event | {
2
+ inputType?: string;
3
+ }): boolean;
4
+ /**
5
+ * @typedef {Object} NabuInternals
6
+ * The engine machinery behind {@link Nabu#internals}. **Unstable**: may change in any version (see `docs/guides/extensions.md`,
7
+ * "Stability"). Methods are bound to the editor; their signatures are those of the `Nabu` methods of the same name.
8
+ * @property {Pulse} pulse The action bus behind `exec()`: `pulse.on(topic, handler)` observes or adds a topic at runtime.
9
+ * @property {CommandConfirmation} commandConfirm The confirmation controller of commands (hold / invite / choose): `start`, `stop`, `offer`, `choose`, `cancel`, `pending`.
10
+ * @property {Map<string, Array<(nabu: Nabu, ...args: any[]) => any>>} hooks Extension hooks by name, in registration order (the normalizers of `onBeforeTransaction`, the `onBeforeInput` handlers...).
11
+ * @property {WeakMap<Function, string>} hookOwners Hook function to the name of the extension that registered it.
12
+ * @property {import('../utils/extensions.js').InputRule[]} inputRules The input rules collected from the extensions.
13
+ * @property {import('../utils/extensions.js').PasteInterpreter[]} pasteInterpreters The paste interpreters collected from the extensions.
14
+ * @property {import('../utils/extensions.js').PasteFileHandler[]} pasteFileHandlers The paste file handlers, by priority.
15
+ * @property {UndoManager} undoManager The Loro undo manager (undo steps, merge window).
16
+ * @property {import('loro-crdt').LoroMap} content The free-form `content` map of the document.
17
+ * @property {import('../files/files.svelte.js').FilesConfig} fileConfig The resolved `files` option.
18
+ * @property {Record<string, boolean> | null} storedMarks Pending inline marks for the next typed character (reactive; assignable).
19
+ * @property {Nabu['toggleStoredMark']} toggleStoredMark
20
+ * @property {Nabu['clearStoredMarks']} clearStoredMarks
21
+ * @property {Nabu['noteTextChange']} noteTextChange
22
+ * @property {Nabu['captureUndoSelection']} captureUndoSelection Remember the selection for the undo step now being recorded.
23
+ * @property {Nabu['sealUndoEnd']} sealUndoEnd Close the "where did the last action end" mark of the undo history.
24
+ * @property {Nabu['updateRoots']} updateRoots Re-read the root blocks from the tree.
25
+ * @property {Nabu['deleteNode']} deleteNode Delete a block by node id (no commit).
26
+ * @property {Nabu['rearmTab']} rearmTab
27
+ * @property {string | undefined} tabDescription The `aria-description` the root carries while `tab` traps the focus.
28
+ * @property {Nabu['dispatchEventToSelection']} dispatchEventToSelection Route a native event to the block that holds the selection.
29
+ * @property {Nabu['handleKeydown']} handleKeydown The keydown pipeline (commands first, then hooks, then the block).
30
+ * @property {Nabu['handleBeforeinput']} handleBeforeinput
31
+ * @property {Nabu['beforeinput']} beforeinput
32
+ * @property {Nabu['handleCompositionStart']} handleCompositionStart
33
+ * @property {Nabu['handleCompositionUpdate']} handleCompositionUpdate
34
+ * @property {Nabu['handleCompositionEnd']} handleCompositionEnd
35
+ * @property {Nabu['handleMousedown']} handleMousedown
36
+ * @property {Nabu['handleCopy']} handleCopy Write the selection to a clipboard (every format).
37
+ * @property {Nabu['handleCut']} handleCut
38
+ * @property {Nabu['handlePaste']} handlePaste The paste pipeline (interpreters, files, `acceptPaste`).
39
+ * @property {Nabu['insertFragment']} insertFragment Insert a `PasteFragment` at the selection (what a paste does after interpreting).
40
+ * @property {Nabu['handleDragStart']} handleDragStart
41
+ * @property {Nabu['handleDragOver']} handleDragOver
42
+ * @property {Nabu['handleDragLeave']} handleDragLeave
43
+ * @property {Nabu['handleDragEnd']} handleDragEnd
44
+ * @property {Nabu['handleDrop']} handleDrop
45
+ * @property {Nabu['dropAt']} dropAt Drop a `DataTransfer` at a position, as the drag and drop does.
46
+ * @property {DropTarget | null} dropTarget The drop indicator being shown (reactive).
47
+ * @property {{ normalize: NabuSelection['normalize'], scheduleRepair: NabuSelection['scheduleRepair'], repairAfterRemoval: NabuSelection['repairAfterRemoval'], placements: number, attachRoot: NabuSelection['attachRoot'], owns: NabuSelection['owns'], scope: NabuSelection['scope'], root: HTMLElement | null }} selection The selection's own repair machinery, and the engine's root element: `attachRoot(el)` (what `Nabu.svelte` calls on mount, it returns the detach function), `root`, `owns(node)` (inside MY root, not in a nested editor) and `scope()` ('mine' | 'outside' | 'foreign': whose business the live DOM selection is).
48
+ */
49
+ /**
50
+ * The editor engine. It owns the document (a Loro CRDT), the block tree and its registry, the selection, the commands and the
51
+ * extensions, and runs the event, clipboard and drag and drop pipelines; `NabuEditor` renders it. Create one with `createEditor`
52
+ * (or a preset factory such as `createDocumentEditor`) rather than `new Nabu(...)`, then read and write the content through
53
+ * `serialize`, `importMarkdown`, `importJSON`, `exec` and `transact`. The members documented as public are the stable contract of
54
+ * `@aionbuilders/nabu/extend`; `internals` is the unstable door to the rest.
55
+ */
1
56
  export class Nabu {
2
- static BREAK: symbol;
3
- static CONTINUE: symbol;
57
+ /**
58
+ * What a hook or an `onBeforeInput` handler returns to stop the engine (and the hooks after it).
59
+ * @type {symbol}
60
+ * @public
61
+ */
62
+ public static BREAK: symbol;
63
+ /**
64
+ * What a hook returns to let the engine go on (same as returning nothing).
65
+ * @type {symbol}
66
+ * @public
67
+ */
68
+ public static CONTINUE: symbol;
4
69
  /** @param {NabuInit} init */
5
70
  constructor(init?: NabuInit);
6
- /** @type {LoroDoc} */
7
- doc: LoroDoc;
8
- selection: NabuSelection;
9
- tree: LoroTree<Record<string, NabuNode<{}>>>;
71
+ /**
72
+ * True during an IME composition: the browser owns the DOM, the caret must not be touched.
73
+ * @public
74
+ */
75
+ public get composing(): boolean;
76
+ /**
77
+ * The block holding the running composition, or null. Reactive.
78
+ * @public
79
+ */
80
+ public get composingBlock(): Block | null;
81
+ /**
82
+ * The Loro document behind the editor (public: connect it to a server with `doc.subscribeLocalUpdates` and `importRemote`).
83
+ * @type {LoroDoc}
84
+ * @public
85
+ */
86
+ public doc: LoroDoc;
87
+ /**
88
+ * The text selection of the editor (a reactive wrapper of the DOM selection, in terms of blocks).
89
+ * @type {NabuSelection}
90
+ * @public
91
+ */
92
+ public selection: NabuSelection;
93
+ /**
94
+ * The document tree (Loro): one node per block, `node.data` holds the block's `type` and props.
95
+ * @public
96
+ */
97
+ public tree: LoroTree<NabuNodeData>;
10
98
  content: import("loro-crdt").LoroMap<Record<string, unknown>>;
11
99
  undoManager: UndoManager;
12
- extensions: Extension[];
100
+ /**
101
+ * The extensions the editor was built with, in order.
102
+ * @type {Extension[]}
103
+ * @public
104
+ */
105
+ public extensions: Extension[];
13
106
  /** @type {import('../files/files.svelte.js').FilesConfig} */
14
107
  fileConfig: import("../files/files.svelte.js").FilesConfig;
15
- BREAK: symbol;
16
- CONTINUE: symbol;
17
- /** @type {SvelteMap<string, typeof Block>} */
18
- registry: SvelteMap<string, typeof Block>;
19
- /** @type {SvelteMap<string, Component>} */
20
- components: SvelteMap<string, Component>;
21
- /** @type {SvelteMap<string, Block>} */
22
- blocks: SvelteMap<string, Block>;
23
- /** @type {SvelteMap<string, SvelteSet<Block>>} */
24
- blocksByType: SvelteMap<string, SvelteSet<Block>>;
108
+ /**
109
+ * Resolved `placeholders` option (see NabuInit). Reassign to change it at runtime.
110
+ * @type {import('../utils/placeholders.js').ResolvedPlaceholders}
111
+ * @public
112
+ */
113
+ public placeholders: import("../utils/placeholders.js").ResolvedPlaceholders;
114
+ /**
115
+ * Resolved `spellcheck` option (see NabuInit). Reactive: assign to change it at runtime.
116
+ * @type {boolean}
117
+ * @public
118
+ */
119
+ public spellcheck: boolean;
120
+ public set lang(value: string | undefined);
121
+ /**
122
+ * Resolved `lang` option (see NabuInit): a valid BCP 47 tag, or `undefined` (inherit the page language).
123
+ * Reactive: assign to change it at runtime; an invalid value is ignored (warning) and leaves it unchanged.
124
+ * @type {string | undefined}
125
+ * @public
126
+ */
127
+ public get lang(): string | undefined;
128
+ public set readonly(value: boolean);
129
+ /**
130
+ * Read-only mode (see the `readonly` option of NabuInit). Reactive: assign to switch it on or off at runtime. While `true`
131
+ * the user cannot change the document: input, paste, cut, drop, drag moves and commands (shortcuts, `commands.run`,
132
+ * `exec` of a command, undo / redo) are ignored by the engine, and the UI components hide themselves. Programmatic
133
+ * edits by the host (`insert`, `importJSON`...) are not blocked. View state that is not part of the document (a toggle
134
+ * opened to read it) stays possible and is never written to the document.
135
+ * @type {boolean}
136
+ * @public
137
+ */
138
+ public get readonly(): boolean;
139
+ /** @param {unknown} value */
140
+ public set tab(value: unknown);
141
+ /**
142
+ * Resolved `tab` option (see NabuInit): what Tab / Shift+Tab do in a plain text block. Reactive: assign to change it at runtime;
143
+ * an unknown value warns and gives the default of the editor (its preset).
144
+ * @type {import('../utils/tab.js').TabMode}
145
+ * @public
146
+ */
147
+ public get tab(): import("../utils/tab.js").TabMode;
148
+ /**
149
+ * Announcement of the Escape-then-Tab way out (option `tabHint`), `false` for none. Reactive.
150
+ * @type {string | false}
151
+ * @public
152
+ */
153
+ public tabHint: string | false;
154
+ /**
155
+ * Commands and keyboard shortcuts (ADR 017): `list()`, `get(id)`, `run(id, data)`. A plain snapshot API, the set of
156
+ * commands is fixed once the editor is built.
157
+ */
158
+ commandConfirm: CommandConfirmation;
159
+ /**
160
+ * Commands and keyboard shortcuts (ADR 017): `list()`, `get(id)`, `has(id)`, `run(id, data)`, `offer(id)`. A plain
161
+ * snapshot API; the set of commands is fixed once the editor is built.
162
+ * @type {CommandRegistry}
163
+ * @public
164
+ */
165
+ public commands: CommandRegistry;
166
+ /**
167
+ * Type of the default text block (declared by an extension with `defaultBlock: true`): created by the
168
+ * engine when it needs an empty text block of its own, e.g. a caret after a trailing void block.
169
+ * @type {string | null}
170
+ * @public
171
+ */
172
+ public defaultBlockType: string | null;
173
+ /**
174
+ * `Nabu.BREAK`, reachable from the instance a hook receives.
175
+ * @type {symbol}
176
+ * @public
177
+ */
178
+ public BREAK: symbol;
179
+ /**
180
+ * `Nabu.CONTINUE`, reachable from the instance a hook receives.
181
+ * @type {symbol}
182
+ * @public
183
+ */
184
+ public CONTINUE: symbol;
185
+ /**
186
+ * The block classes registered by the loaded extensions, by block type.
187
+ * @type {SvelteMap<string, typeof Block>}
188
+ * @public
189
+ */
190
+ public registry: SvelteMap<string, typeof Block>;
191
+ /**
192
+ * The Svelte components registered by the loaded extensions, by block type.
193
+ * @type {SvelteMap<string, Component>}
194
+ * @public
195
+ */
196
+ public components: SvelteMap<string, Component>;
197
+ /**
198
+ * Every live block of the document, by tree id.
199
+ * @type {SvelteMap<string, Block>}
200
+ * @public
201
+ */
202
+ public blocks: SvelteMap<string, Block>;
203
+ /**
204
+ * The live blocks of each type (reactive sets, by block type).
205
+ * @type {SvelteMap<string, SvelteSet<Block>>}
206
+ * @public
207
+ */
208
+ public blocksByType: SvelteMap<string, SvelteSet<Block>>;
25
209
  /**
26
210
  * Registered subsystems. Each system should implement:
27
211
  * - `start(): void` — called when the editor mounts
28
212
  * - `stop(): void` — called when the editor unmounts
29
213
  * @type {SvelteMap<string, { start?: () => void, stop?: () => void, [key: string]: any }>}
214
+ * @public
30
215
  */
31
- systems: SvelteMap<string, {
216
+ public systems: SvelteMap<string, {
32
217
  start?: () => void;
33
218
  stop?: () => void;
34
219
  [key: string]: any;
35
220
  }>;
36
- hooks: Map<any, any>;
221
+ /**
222
+ * Extension hooks by name, in registration order (see `ExtensionHooks`).
223
+ * @type {Map<string, Array<(nabu: Nabu, ...args: any[]) => any>>}
224
+ */
225
+ hooks: Map<string, Array<(nabu: Nabu, ...args: any[]) => any>>;
226
+ /**
227
+ * Hook function -> name of the extension that registered it. Lets `Block#ascend` run the hooks of the
228
+ * extension that OWNS the block type before the generic ones (type-specific handler wins).
229
+ * @type {WeakMap<Function, string>}
230
+ */
231
+ hookOwners: WeakMap<Function, string>;
37
232
  /**
38
233
  * Declarative input rules collected from extensions, tested by TextBehavior
39
234
  * against the text before the cursor on matching beforeinput events.
40
235
  * @type {import('../utils/extensions.js').InputRule[]}
41
236
  */
42
237
  inputRules: import("../utils/extensions.js").InputRule[];
238
+ /**
239
+ * Slash-menu entries contributed by extensions (`Extension#slashCommands`); the slash menu lists ONLY these (plus the
240
+ * integrator's extras), sorted by `group` / `order`, keeping those whose `when(engine, block)` holds at the caret.
241
+ * @type {import('../ui/slash-menu.svelte.js').SlashCommand[]}
242
+ * @public
243
+ */
244
+ public slashCommands: import("../ui/slash-menu.svelte.js").SlashCommand[];
245
+ /** What the editor root exposes as `aria-description`: the hint, only while the mode keeps the focus in. */
246
+ get tabDescription(): string | undefined;
247
+ /** Close the Escape-then-Tab way out (any other key, a click, the focus leaving). */
248
+ rearmTab(): void;
43
249
  /**
44
250
  * Pending inline formatting for the next typed character (active marks at a
45
251
  * collapsed cursor). null = inherit from the span at the cursor.
46
252
  * @type {Record<string, boolean> | null}
47
253
  */
48
254
  storedMarks: Record<string, boolean> | null;
49
- debugging: boolean;
255
+ /**
256
+ * When true, `nabu.warn()` logs to the console (`[Nabu]`).
257
+ * @public
258
+ */
259
+ public debugging: boolean;
50
260
  /**
51
261
  * Root-level serializers. Each function receives the Nabu instance and returns the serialized document.
52
262
  * @type {Map<string, (nabu: Nabu) => any>}
263
+ * @public
53
264
  */
54
- serializers: Map<string, (nabu: Nabu) => any>;
55
- /** @type {Block[]} */
56
- children: Block[];
57
- positions: number;
58
- get isEmpty(): boolean;
59
- /** @param {string} format */
60
- serialize(format: string): any;
265
+ public serializers: Map<string, (nabu: Nabu) => any>;
266
+ /**
267
+ * The root blocks of the document, in order (reactive).
268
+ * @type {Block[]}
269
+ * @public
270
+ */
271
+ public children: Block[];
272
+ /**
273
+ * Number of caret positions in the document (the sum of the root blocks').
274
+ * @public
275
+ */
276
+ public positions: number;
277
+ /**
278
+ * True when the document has no block.
279
+ * @public
280
+ */
281
+ public get isEmpty(): boolean;
282
+ /**
283
+ * Serialize the document with the root serializer registered for `format` (`'markdown'`, `'json'`, or one an extension
284
+ * adds with `serializers`); `null` (and a warning) for an unknown format.
285
+ * @param {string} format
286
+ * @returns {any}
287
+ * @public
288
+ */
289
+ public serialize(format: string): any;
61
290
  init(): void;
62
- /** Rafraîchit les blocs racines de l'éditeur */
63
- updateRoots(): void;
291
+ /**
292
+ * Rafraîchit les blocs racines de l'éditeur. Les blocs déjà connus sont réutilisés tels quels : seul le type des nœuds
293
+ * listés dans `retyped` (ids dont le `type` vient de changer) est relu.
294
+ * @param {Set<string>} [retyped] without it, the type of every root is checked
295
+ */
296
+ updateRoots(retyped?: Set<string>): void;
64
297
  /**
65
298
  * Dispatch an action to all registered handlers for the given topic.
299
+ * Re-syncs the model selection from the DOM first: `selectionchange` is async, so right after a
300
+ * keyboard-only selection change (Shift+Arrow, Home/End, Ctrl+A) the model would be stale.
66
301
  * @param {string} topic
67
302
  * @param {any} [data]
68
303
  * @returns {Promise<import('@aionbuilders/pulse').PulseEvent>}
304
+ * @public
305
+ */
306
+ public exec(topic: string, data?: any): Promise<import("@aionbuilders/pulse").PulseEvent>;
307
+ /**
308
+ * The command waiting for the user's confirmation (ADR 017 §3.4), reactive; `null` when none:
309
+ * `{ id, strategy: 'hold' | 'invite' | 'choose', label, display, message, target?, progress, options?, selectedIndex }`.
310
+ * `progress` (hold, 0 → 1) and `selectedIndex` (choose) are reactive fields of that object.
311
+ * @returns {import('../utils/command-confirm.svelte.js').PendingCommand | null}
312
+ * @public
313
+ */
314
+ public get pendingCommand(): import("../utils/command-confirm.svelte.js").PendingCommand | null;
315
+ /**
316
+ * Cancel the pending confirmation, if any: nothing runs.
317
+ * @public
318
+ */
319
+ public cancelPendingCommand(): void;
320
+ /**
321
+ * The pending confirmation when it is ABOUT `target` (what `confirm.target(ctx)` returned: usually a block), else `null`.
322
+ * Reactive: a block that draws its own hold progress reads `nabu.pendingCommandOn(block)?.progress`.
323
+ * @param {any} target
324
+ * @returns {import('../utils/command-confirm.svelte.js').PendingCommand | null}
325
+ * @public
326
+ */
327
+ public pendingCommandOn(target: any): import("../utils/command-confirm.svelte.js").PendingCommand | null;
328
+ /**
329
+ * Text of the polite live region of the editor (prompts and outcomes of confirmations). Reactive.
330
+ * @returns {string}
331
+ * @public
69
332
  */
70
- exec(topic: string, data?: any): Promise<import("@aionbuilders/pulse").PulseEvent>;
71
- trigger(hookName: any, ...args: any[]): void;
72
- commit(): Promise<void>;
333
+ public get commandAnnouncement(): string;
334
+ /**
335
+ * Run the `hookName` hooks of every extension, in order, until one returns `BREAK`. Each is called as `hook(nabu, ...args)`.
336
+ * @param {string} hookName
337
+ * @param {...any} args
338
+ * @public
339
+ */
340
+ public trigger(hookName: string, ...args: any[]): void;
341
+ /**
342
+ * Commit the pending changes as one Loro transaction.
343
+ * @param {{ origin?: string }} [options] `origin` tags the transaction; an origin starting with `nabu:silent` is
344
+ * not recorded as an undo step (background completions that must not be undone on their own).
345
+ * @public
346
+ */
347
+ public commit({ origin }?: {
348
+ origin?: string;
349
+ }): Promise<void>;
350
+ /**
351
+ * Make the NEXT commit its own undo step (and the typing right after it another one), even though it
352
+ * holds no structural op: for a non-structural change that must undo on its own, e.g. a flag toggled
353
+ * from the keyboard, which would otherwise merge with the typing around it. Call it just before commit().
354
+ * @public
355
+ */
356
+ public isolateUndoStep(): void;
73
357
  /**
74
358
  * Run Loro mutations as a single transaction, then optionally restore the cursor.
75
359
  * Centralizes the "mutate → commit → setCursor" dance used by most actions.
76
360
  * @param {() => void} mutateFn - Mutations Loro ici. Ne PAS appeler commit() dedans.
77
361
  * @param {{ block: Block, offset: number } | null} [cursorIntent]
78
362
  * @returns {Promise<void>}
363
+ * @public
79
364
  */
80
- transact(mutateFn: () => void, cursorIntent?: {
365
+ public transact(mutateFn: () => void, cursorIntent?: {
81
366
  block: Block;
82
367
  offset: number;
83
368
  } | null): Promise<void>;
369
+ /**
370
+ * Apply a markdown BLOCK shortcut (`# `, `- `, `> `, `--- `…) so that undo gives back exactly what
371
+ * the user typed, trigger included: one Ctrl+Z after `# ` leaves a paragraph "# " with the caret
372
+ * after the space; a second one removes the typing as usual.
373
+ *
374
+ * 1. `trigger` (the swallowed space) is inserted at the caret and committed like normal typing;
375
+ * 2. `transform` runs (delete the prefix incl. the trigger, change/replace the block…) and is
376
+ * committed as its own structural undo step (see commit()), whose stored caret is right
377
+ * after the trigger.
378
+ * Both commits run in the same synchronous turn, so the intermediate "# " is never painted.
379
+ *
380
+ * For a trigger that is not text (``` + Enter), pass `trigger = ''`: nothing is inserted and
381
+ * undo restores the text typed before the key (the fence line, without the Enter).
382
+ * @param {Block} block the block the shortcut was typed in
383
+ * @param {string} trigger text of the trigger key, inserted before transforming ('' = none)
384
+ * @param {(behavior: any) => void} transform mutations only (it may commit itself, e.g. via transformTo)
385
+ * @returns {Promise<void>} resolves immediately, doing nothing, when `block.transformsEnabled === false`
386
+ * @public
387
+ */
388
+ public shortcut(block: Block, trigger: string, transform: (behavior: any) => void): Promise<void>;
84
389
  /**
85
390
  * True when every selected text run carries the given mark.
86
391
  * Reactive: reads block.selected and the behaviors' selections/deltas,
87
392
  * so it can be used directly in component templates (e.g. FloatingToolbar).
88
393
  * @param {string} markName
89
394
  * @returns {boolean}
395
+ * @public
396
+ */
397
+ public isMarkActive(markName: string): boolean;
398
+ /**
399
+ * Import changes made ELSEWHERE (another tab, a peer, a stored copy of the document: ADR 010 multi-tab sync). They are the
400
+ * document's own history, not the user's actions: Loro's UndoManager records local commits only, so an import is never an undo
401
+ * step (undoing the user's own edits afterwards still works, Loro transforms them). The DOM follows through the normal Loro
402
+ * events. The caret of the local user stays on the same CHARACTER: it is captured as Loro cursors before the import and put
403
+ * back after the render (a text node rewritten by Svelte would otherwise send it to the start of the block); the page is
404
+ * never scrolled for it. Idempotent (importing what the document already has changes nothing).
405
+ * Called DURING an IME composition it is applied at once (not held): the model is safe, because the composition anchor is a Loro
406
+ * cursor that follows the edit, and the caret restore is skipped meanwhile (the browser owns it). (`persistence/sync.js` still
407
+ * holds the updates it receives while composing, which keeps the composing text node untouched by the render.)
408
+ * @param {Uint8Array} bytes a Loro snapshot or update
409
+ * @returns {import('loro-crdt').ImportStatus}
410
+ * @public
411
+ */
412
+ public importRemote(bytes: Uint8Array): import("loro-crdt").ImportStatus;
413
+ /**
414
+ * Undo the last operation. The selection as it was before that operation comes back (see ADR 015).
415
+ * @public
90
416
  */
91
- isMarkActive(markName: string): boolean;
417
+ public undo(): void;
92
418
  /**
93
- * Undo the last operation
419
+ * Redo the last undone operation. The selection comes back where that operation ended.
420
+ * @public
94
421
  */
95
- undo(): void;
422
+ public redo(): void;
96
423
  /**
97
- * Redo the last undone operation
424
+ * The text of `block` just changed (a Loro event of its text container: local, programmatic or imported). When a selection end
425
+ * is in that block and the change is NOT the user's own typing (the handlers place their caret themselves), the selection is
426
+ * put back on the characters it was on once the render is done: Svelte rewrites the edited text node, which would send the end
427
+ * of the DOM range to offset 0 of it (P-109). The ends are the Loro cursors of the last selection captured while the model and
428
+ * the DOM agreed (`#undoSel`), so an insertion before them shifts them. O(1) when the block holds no selection end. Skipped
429
+ * during a composition and an undo / redo (which restore the selection themselves), and when the editor has placed the selection
430
+ * since that capture (an input handler puts its own caret after the render: it is the one that knows where the caret goes, and
431
+ * what it placed is captured again, `captureUndoSelection('settle')`).
432
+ * @param {Block} block
98
433
  */
99
- redo(): void;
434
+ noteTextChange(block: Block): void;
435
+ /**
436
+ * Remember the live selection as the one an undo step pushed from now on gives back (ADR 015). Called wherever the selection
437
+ * changes or an input starts (selection change, key down, programmatic caret placement), always while the model and the DOM
438
+ * agree: it does nothing during a composition, while a commit / undo is rendering, and while a transaction is pending (the
439
+ * Loro cursors have to bind to the text as it was BEFORE the change).
440
+ * @param {'user' | 'settle'} [source] 'settle' = the editor itself placed the selection after an action: it is where that
441
+ * action ended (what a redo gives back). 'user' = the user moved it.
442
+ */
443
+ captureUndoSelection(source?: "user" | "settle"): void;
444
+ /** A pointer interaction starts: the selection that follows is the user's, no longer where the last action ended. */
445
+ sealUndoEnd(): void;
100
446
  /** Clear the pending stored marks. */
101
447
  clearStoredMarks(): void;
102
448
  /**
@@ -104,28 +450,65 @@ export class Nabu {
104
450
  * @param {string} name
105
451
  */
106
452
  toggleStoredMark(name: string): void;
107
- /** @param {{from: {offset: number, block: Block}, to: {offset: number, block: Block}, offset?: number}} [options={}] */
108
- focus(options?: {
109
- from: {
110
- offset: number;
111
- block: Block;
453
+ /**
454
+ * Place the DOM + model selection. Asynchronous by nature: it waits for Svelte to flush pending state
455
+ * (`tick()`), because the target blocks' DOM may not be rendered yet (e.g. right after a commit/insert).
456
+ * The returned promise resolves once the selection has been set, i.e. once `nabu.selection` reflects it:
457
+ * `await nabu.focus(...)` before `exec(...)` / typing. Fire-and-forget callers are unaffected.
458
+ * @param {{from?: {offset?: number, block?: Block}, to?: {offset?: number, block?: Block}, offset?: number}} [options]
459
+ * @returns {Promise<void>}
460
+ * @public
461
+ */
462
+ public focus(options?: {
463
+ from?: {
464
+ offset?: number;
465
+ block?: Block;
112
466
  };
113
- to: {
114
- offset: number;
115
- block: Block;
467
+ to?: {
468
+ offset?: number;
469
+ block?: Block;
116
470
  };
117
471
  offset?: number;
118
- }): void;
472
+ }): Promise<void>;
119
473
  /**
120
- * Insère un nouveau bloc dans le document
121
- * @param {string} type - Le type du bloc (ex: 'paragraph')
122
- * @param {Object} [props={}] - Les propriétés initiales
123
- * @param {string|null} [parentId=null] - ID du parent (null pour racine)
124
- * @param {number|null} [index=null] - Position dans la liste des enfants
125
- */
126
- insert(type: string, props?: Object, parentId?: string | null, index?: number | null): Block;
127
- /** @param {Block} block */
128
- delete(block: Block): void;
474
+ * The deepest last block of the document that can hold a caret in the rendered document: follows
475
+ * the last child at each level, but never enters a block that hides its children.
476
+ * @returns {Block | null}
477
+ * @public
478
+ */
479
+ public get lastVisibleBlock(): Block | null;
480
+ /**
481
+ * The document must always offer a caret after its last block. Call it on user intent (ArrowDown /
482
+ * ArrowRight leaving the document, a click below the last block): when the last block holds text, the
483
+ * caret goes to its end; when it does not (a void block such as a divider / image, or a container
484
+ * whose end is not a text position), an empty default text block is appended at the root, in one
485
+ * undo step, and takes the caret. Never called eagerly on load.
486
+ * @returns {Promise<Block | null>} The block now holding the caret
487
+ * @public
488
+ */
489
+ public openTrailingCaret(): Promise<Block | null>;
490
+ /**
491
+ * Mouse down on the editor itself (not on a block): below the last block, that block is a void →
492
+ * put a caret after it (see `openTrailingCaret`).
493
+ * @param {MouseEvent} e
494
+ */
495
+ handleMousedown(e: MouseEvent): void;
496
+ /**
497
+ * Insert a new block of a registered type and commit (throws when the type is not registered).
498
+ * @param {string} type - Block type (`'paragraph'`, or the name of an extension that declares a `block`)
499
+ * @param {Record<string, any>} [props] - Initial props, read by the class's `static create` (`text`, `delta`...)
500
+ * @param {string | null} [parentId] - Id of the parent block (`null`: the document root)
501
+ * @param {number | null} [index] - Position among the siblings (`null`: last)
502
+ * @returns {Block} The created block
503
+ * @public
504
+ */
505
+ public insert(type: string, props?: Record<string, any>, parentId?: string | null, index?: number | null): Block;
506
+ /**
507
+ * Delete a block (and its children) from the tree. No commit: call `commit()` afterwards.
508
+ * @param {Block} block
509
+ * @public
510
+ */
511
+ public delete(block: Block): void;
129
512
  /**
130
513
  * @param {string} nodeId
131
514
  * @returns
@@ -169,60 +552,370 @@ export class Nabu {
169
552
  /** @param {ClipboardEvent} e */
170
553
  handlePaste(e: ClipboardEvent): void;
171
554
  /**
172
- * Insère un PasteFragment à la position du curseur courant.
555
+ * Where the drop would land while something is dragged over the editor, `null` otherwise (left, dropped, cancelled, or
556
+ * nothing the editor can take). Reactive state for a UI: Nabu itself draws nothing.
557
+ * - `block` / `offset` / `side`: a caret position in the text of `block` (`side: 'inside'`, `offset` in its text), or
558
+ * beside a block that holds no text (image, divider…: `side: 'before' | 'after'`, by the pointer's half).
559
+ * - `kind`: `'files'` (OS files → media blocks), `'content'` (text / HTML / markdown / Nabu fragment from outside, or a
560
+ * copy of the editor's own selection), `'move'` (the editor's own selection being moved). Decided from the drag's
561
+ * declared types: a drag that mixes files and text resolves as it does for a paste (files win) at the drop.
562
+ * @type {DropTarget | null}
563
+ */
564
+ dropTarget: DropTarget | null;
565
+ /**
566
+ * Start of a drag inside the editor. A drag of the TEXT SELECTION is serialized like a copy (internal fragment, plain text,
567
+ * HTML — so it can also be dropped in another editor or application) and remembered: dropped back in the editor it is a
568
+ * MOVE (see `dropAt`). Any other drag (an image, a link, a draggable element) is cancelled: the browser would hand a drop
569
+ * its own serialization of the DOM node.
570
+ * @param {DragEvent} e
571
+ */
572
+ handleDragStart(e: DragEvent): void;
573
+ /**
574
+ * `dragenter` / `dragover` over the editor: accept what it can take (cancelling the event is how a drop is allowed),
575
+ * announce move vs copy, and publish the position in `dropTarget`.
576
+ * @param {DragEvent} e
577
+ */
578
+ handleDragOver(e: DragEvent): void;
579
+ /** @param {DragEvent} e */
580
+ handleDragLeave(e: DragEvent): void;
581
+ /** The drag that started in this editor ended (dropped anywhere, or cancelled). @param {DragEvent} [e] */
582
+ handleDragEnd(e?: DragEvent): void;
583
+ /**
584
+ * `drop` on the editor: the browser's default (inserting DOM nodes behind Loro's back, or navigating to a dropped
585
+ * file) never happens. The position under the pointer is resolved, then {@link Nabu#dropAt} does the rest.
586
+ * @param {DragEvent} e
587
+ */
588
+ handleDrop(e: DragEvent): void;
589
+ /**
590
+ * Drop `dt` at `position`, as ONE undo step, through the paste pipeline (files → media blocks, `pasteInterpreters`:
591
+ * internal fragment, HTML, markdown, plain text; verbatim text into a `pastesAsPlainText` block).
592
+ * With `opts.source` (the editor's own dragged selection) it is a MOVE: the source range is deleted and the content
593
+ * inserted in the same transaction, the position corrected for the deletion; a position inside (or at the edge of) the
594
+ * source range does nothing. Without it, content from outside — or a copy of the selection — is simply inserted.
595
+ * @param {DataTransfer} dt
596
+ * @param {DropPosition} position
597
+ * @param {{ source?: { range: import('./container.utils.js').DeletionRange } | null }} [opts]
598
+ */
599
+ dropAt(dt: DataTransfer, position: DropPosition, opts?: {
600
+ source?: {
601
+ range: import("./container.utils.js").DeletionRange;
602
+ } | null;
603
+ }): void;
604
+ /**
605
+ * Insère un PasteFragment à la position du curseur courant — or at `opts.at` (a drop position: a caret position in a
606
+ * text block, or beside a block without text, where an empty text block receives the fragment), whatever the DOM selection is.
173
607
  * @param {import('../utils/extensions.js').PasteFragment} fragment
608
+ * @param {{ at?: DropPosition }} [opts]
174
609
  */
175
- insertFragment(fragment: import("../utils/extensions.js").PasteFragment): void;
610
+ insertFragment(fragment: import("../utils/extensions.js").PasteFragment, opts?: {
611
+ at?: DropPosition;
612
+ }): void;
613
+ /**
614
+ * Inserts a PasteBlock after `afterNode`. Handles both leaf blocks (wrapOrphan)
615
+ * and container blocks (creates container, recurses into children).
616
+ * Returns the outer node to use as the next prevNode. Public: part of the paste toolbox a block's
617
+ * `acceptPaste` hook builds on. No commit.
618
+ * @param {import('../utils/extensions.js').PasteBlock} pb
619
+ * @param {any} afterNode
620
+ * @returns {any}
621
+ * @public
622
+ */
623
+ public insertPasteBlock(pb: import("../utils/extensions.js").PasteBlock, afterNode: any): any;
624
+ /**
625
+ * Creates a block inside a container, recursively handling nested children. Public: part of the paste
626
+ * toolbox a block's `acceptPaste` hook builds on. No commit.
627
+ * @param {import('../utils/extensions.js').PasteBlock} pb
628
+ * @param {string} parentId
629
+ * @returns {Block | null} the created block
630
+ * @public
631
+ */
632
+ public createPasteBlock(pb: import("../utils/extensions.js").PasteBlock, parentId: string): Block | null;
176
633
  /**
177
634
  * Replace the entire document with the given PasteFragment.
178
635
  * Unlike insertFragment(), this does not depend on a live DOM selection:
179
636
  * blocks are created at the root through the same registry pipeline as paste.
180
637
  * @param {import('../utils/extensions.js').PasteFragment} fragment
181
638
  * @returns {Promise<void>}
639
+ * @public
182
640
  */
183
- importFragment(fragment: import("../utils/extensions.js").PasteFragment): Promise<void>;
641
+ public importFragment(fragment: import("../utils/extensions.js").PasteFragment): Promise<void>;
184
642
  /**
185
643
  * Replace the entire document with content parsed from a Markdown string.
186
644
  * Requires MarkdownPasteExtension (or any text/plain interpreter) to be loaded.
187
645
  * @param {string} markdown
188
646
  * @returns {Promise<void>}
647
+ * @public
189
648
  */
190
- importMarkdown(markdown: string): Promise<void>;
649
+ public importMarkdown(markdown: string): Promise<void>;
191
650
  /**
192
- * Replace the entire document with a `serialize('json')` export.
193
- * @param {{version?: string, blocks: any[]} | string} json
651
+ * Replace the entire document with a `serialize('json')` export. An export of a version this editor does not know
652
+ * is refused with a warning (the document is left untouched), like the clipboard does; a block type that is not
653
+ * registered is degraded to the default text block (`degradeUnknownBlocks`), nothing is dropped.
654
+ * @param {{version?: string | number, blocks: Parameters<typeof import('../utils/extensions.js').jsonToPasteBlocks>[0], assets?: Record<string, import('../files/files.svelte.js').EmbeddedAsset>} | string} json
194
655
  * @returns {Promise<void>}
656
+ * @public
195
657
  */
196
- importJSON(json: {
197
- version?: string;
198
- blocks: any[];
658
+ public importJSON(json: {
659
+ version?: string | number;
660
+ blocks: Parameters<typeof import("../utils/extensions.js").jsonToPasteBlocks>[0];
661
+ assets?: Record<string, import("../files/files.svelte.js").EmbeddedAsset>;
199
662
  } | string): Promise<void>;
200
- /** @param {number} globalOffset */
201
- resolveDocumentOffset(globalOffset: number): {
663
+ /**
664
+ * The block and local offset that hold a document-wide caret offset (`positions` counted from the start of the document).
665
+ * @param {number} globalOffset
666
+ * @returns {{ block: Block, offset: number } | null}
667
+ * @public
668
+ */
669
+ public resolveDocumentOffset(globalOffset: number): {
202
670
  block: Block;
203
671
  offset: number;
204
672
  } | null;
205
- /** @param {...any} args */
206
- warn(...args: any[]): void;
673
+ /**
674
+ * The door to everything the engine uses internally that the stable contract (the members tagged `public` in their JSDoc) does not cover: the
675
+ * command-confirm controller, the action bus, the hook and rule registries, the clipboard / drop / event pipelines, undo
676
+ * capture, stored marks, the selection's repair machinery. They are the same references the engine runs on, not copies.
677
+ *
678
+ * The door itself is part of the stable contract; **@unstable** is everything behind it: nothing reached through `internals` is a
679
+ * promise, it may change, move or disappear in ANY minor version.
680
+ * Prefer the stable members; use this when you must, and pin the version of the package. The set of keys is frozen by a
681
+ * test, so a change shows up in the changelog.
682
+ * @returns {NabuInternals}
683
+ * @public
684
+ * @unstable
685
+ */
686
+ public get internals(): NabuInternals;
687
+ /**
688
+ * Log a diagnostic to the console when `debugging` is on. Silent otherwise.
689
+ * @param {...any} args
690
+ * @returns {void}
691
+ * @public
692
+ */
693
+ public warn(...args: any[]): void;
207
694
  #private;
208
695
  }
696
+ /**
697
+ * The data map of a block's tree node: a `type` plus the block's own (open-ended) properties. Block classes narrow it
698
+ * with their own node typedef (`NabuNode<{text: LoroText}>`).
699
+ */
700
+ export type NabuNodeData = {
701
+ type: string;
702
+ } & Record<string, any>;
209
703
  export type NabuNode<T extends {
210
704
  [x: string]: any;
211
- } = {}> = LoroTreeNode<{
705
+ } = Record<string, any>> = LoroTreeNode<{
212
706
  type: string;
213
707
  } & T>;
708
+ /**
709
+ * The options of an editor: the extensions to load, an initial snapshot, files, placeholders, readonly, language, Tab behaviour, keymap and
710
+ * command confirmation. Accepted by `new Nabu(init)`, by `createEditor` and the preset factories, and by `createPersistedEditor`.
711
+ */
214
712
  export type NabuInit = {
215
713
  extensions?: Extension[] | undefined;
216
714
  snapshot?: Uint8Array<ArrayBufferLike> | undefined;
217
715
  files?: import("../files/files.svelte.js").FilesConfig | undefined;
716
+ /**
717
+ * - Hint text of empty blocks.
718
+ * `false`: none. `true` / omitted: defaults (shown on the empty block holding the cursor).
719
+ * Object: `{ show?: 'focus' | 'empty', text?: Record<blockType, string | false | ((block) => string | false)> }`.
720
+ */
721
+ placeholders?: import("../utils/placeholders.js").PlaceholdersOption | undefined;
722
+ /**
723
+ * - Browser spellcheck on the editor (default `true`). `false` turns it off and adds the opt-out
724
+ * hints of the Grammarly extension (`data-gramm="false"`, ...). Code blocks are never spellchecked. Reactive: `nabu.spellcheck`.
725
+ */
726
+ spellcheck?: boolean | undefined;
727
+ /**
728
+ * - Show the document without letting the user change it (default `false`). Reactive: `nabu.readonly`,
729
+ * assign to toggle live (`<NabuEditor readonly>` sets it). The editor root becomes `contenteditable="false"`; the engine ignores
730
+ * typing, paste, cut, drop, drag moves and every command / shortcut (undo and redo included). Copy, text selection and links
731
+ * keep working, and the floating UI (toolbar, slash menu, drag handle) hides itself. Code of the host is NOT restricted:
732
+ * `insert`, `importJSON`, `importMarkdown`, `importRemote`, `transact` still work, which is how a viewer loads its document.
733
+ */
734
+ readonly?: boolean | undefined;
735
+ /**
736
+ * - Language of the content, a BCP 47 tag (`'fr'`, `'en-GB'`). Set on the root as `lang`, so the browser's
737
+ * spellchecker, hyphenation and screen readers use it. Unset: inherits the page language. An invalid tag is ignored (warning).
738
+ * Reactive: `nabu.lang`.
739
+ */
740
+ lang?: string | undefined;
741
+ /**
742
+ * - What Tab / Shift+Tab do in a plain text block, where no block handles them
743
+ * structurally (list indent, code indentation and region titles keep their own meaning, whatever this says; P-41).
744
+ * `'focus'`: the browser default, Tab leaves the editor. `'stay'`: both keys are swallowed and the caret stays; Escape then Tab
745
+ * leaves (announced to screen readers, see `tabHint`). `'indent'`: Tab inserts a tab character at the caret (replacing a selection
746
+ * inside one block), Shift+Tab removes one right before it; several blocks selected: like `'stay'`. `'nest'` is planned, not
747
+ * implemented. Default: `tabDefault` (the factories of `presets.js` set it from the preset: Minimal / Text `'focus'`, Document /
748
+ * Full `'stay'`), else `'focus'`. An unknown value warns and uses the default. Reactive: `nabu.tab`.
749
+ */
750
+ tab?: "focus" | "stay" | "indent" | undefined;
751
+ /**
752
+ * - The mode used when `tab` is unset or invalid. Meant for the preset factories.
753
+ */
754
+ tabDefault?: "focus" | "stay" | "indent" | undefined;
755
+ /**
756
+ * - Text announced on the editor root (`aria-description`) while `tab` traps the focus
757
+ * (`'stay'`, `'indent'`): default `"Press Escape then Tab to leave the editor"`; translate it here, `false` for none.
758
+ * Reactive: `nabu.tabHint`.
759
+ */
760
+ tabHint?: string | false | undefined;
761
+ /**
762
+ * - Replaces the keyboard shortcuts of commands (ADR 017): `{ 'mark:bold': ['Mod-Alt-b'] }`;
763
+ * `[]` disables a command's keys. Chords: see `utils/keys.js`; the same checks as for a declared key apply (reserved chords,
764
+ * a key without modifier needs the command's `when`).
765
+ */
766
+ keymap?: Record<string, string[]> | undefined;
767
+ /**
768
+ * - Confirmation of commands asked by a
769
+ * key press (ADR 017 lot 2): `{ holdMs?: number (700), inviteMs?: number (5000), messages?: ConfirmMessages }`. `messages` are the
770
+ * texts of the prompts and outcomes announced to screen readers (English by default; each is a string or a function of the
771
+ * parameters, see `ConfirmMessages`); a command can override them with `confirm.messages`.
772
+ */
773
+ commandConfirm?: import("../utils/command-confirm.svelte.js").CommandConfirmOptions | undefined;
774
+ /**
775
+ * - Which platform's conventions `Mod` and the displayed shortcuts follow. Detected from the
776
+ * browser by default; set it for tests or server-side rendering.
777
+ */
778
+ platform?: "mac" | "other" | undefined;
218
779
  };
780
+ /**
781
+ * The engine machinery behind {@link Nabu#internals}. **Unstable**: may change in any version (see `docs/guides/extensions.md`,
782
+ * "Stability"). Methods are bound to the editor; their signatures are those of the `Nabu` methods of the same name.
783
+ */
784
+ export type NabuInternals = {
785
+ /**
786
+ * The action bus behind `exec()`: `pulse.on(topic, handler)` observes or adds a topic at runtime.
787
+ */
788
+ pulse: Pulse;
789
+ /**
790
+ * The confirmation controller of commands (hold / invite / choose): `start`, `stop`, `offer`, `choose`, `cancel`, `pending`.
791
+ */
792
+ commandConfirm: CommandConfirmation;
793
+ /**
794
+ * Extension hooks by name, in registration order (the normalizers of `onBeforeTransaction`, the `onBeforeInput` handlers...).
795
+ */
796
+ hooks: Map<string, Array<(nabu: Nabu, ...args: any[]) => any>>;
797
+ /**
798
+ * Hook function to the name of the extension that registered it.
799
+ */
800
+ hookOwners: WeakMap<Function, string>;
801
+ /**
802
+ * The input rules collected from the extensions.
803
+ */
804
+ inputRules: import("../utils/extensions.js").InputRule[];
805
+ /**
806
+ * The paste interpreters collected from the extensions.
807
+ */
808
+ pasteInterpreters: import("../utils/extensions.js").PasteInterpreter[];
809
+ /**
810
+ * The paste file handlers, by priority.
811
+ */
812
+ pasteFileHandlers: import("../utils/extensions.js").PasteFileHandler[];
813
+ /**
814
+ * The Loro undo manager (undo steps, merge window).
815
+ */
816
+ undoManager: UndoManager;
817
+ /**
818
+ * The free-form `content` map of the document.
819
+ */
820
+ content: import("loro-crdt").LoroMap;
821
+ /**
822
+ * The resolved `files` option.
823
+ */
824
+ fileConfig: import("../files/files.svelte.js").FilesConfig;
825
+ /**
826
+ * Pending inline marks for the next typed character (reactive; assignable).
827
+ */
828
+ storedMarks: Record<string, boolean> | null;
829
+ toggleStoredMark: Nabu["toggleStoredMark"];
830
+ clearStoredMarks: Nabu["clearStoredMarks"];
831
+ noteTextChange: Nabu["noteTextChange"];
832
+ /**
833
+ * Remember the selection for the undo step now being recorded.
834
+ */
835
+ captureUndoSelection: Nabu["captureUndoSelection"];
836
+ /**
837
+ * Close the "where did the last action end" mark of the undo history.
838
+ */
839
+ sealUndoEnd: Nabu["sealUndoEnd"];
840
+ /**
841
+ * Re-read the root blocks from the tree.
842
+ */
843
+ updateRoots: Nabu["updateRoots"];
844
+ /**
845
+ * Delete a block by node id (no commit).
846
+ */
847
+ deleteNode: Nabu["deleteNode"];
848
+ rearmTab: Nabu["rearmTab"];
849
+ /**
850
+ * The `aria-description` the root carries while `tab` traps the focus.
851
+ */
852
+ tabDescription: string | undefined;
853
+ /**
854
+ * Route a native event to the block that holds the selection.
855
+ */
856
+ dispatchEventToSelection: Nabu["dispatchEventToSelection"];
857
+ /**
858
+ * The keydown pipeline (commands first, then hooks, then the block).
859
+ */
860
+ handleKeydown: Nabu["handleKeydown"];
861
+ handleBeforeinput: Nabu["handleBeforeinput"];
862
+ beforeinput: Nabu["beforeinput"];
863
+ handleCompositionStart: Nabu["handleCompositionStart"];
864
+ handleCompositionUpdate: Nabu["handleCompositionUpdate"];
865
+ handleCompositionEnd: Nabu["handleCompositionEnd"];
866
+ handleMousedown: Nabu["handleMousedown"];
867
+ /**
868
+ * Write the selection to a clipboard (every format).
869
+ */
870
+ handleCopy: Nabu["handleCopy"];
871
+ handleCut: Nabu["handleCut"];
872
+ /**
873
+ * The paste pipeline (interpreters, files, `acceptPaste`).
874
+ */
875
+ handlePaste: Nabu["handlePaste"];
876
+ /**
877
+ * Insert a `PasteFragment` at the selection (what a paste does after interpreting).
878
+ */
879
+ insertFragment: Nabu["insertFragment"];
880
+ handleDragStart: Nabu["handleDragStart"];
881
+ handleDragOver: Nabu["handleDragOver"];
882
+ handleDragLeave: Nabu["handleDragLeave"];
883
+ handleDragEnd: Nabu["handleDragEnd"];
884
+ handleDrop: Nabu["handleDrop"];
885
+ /**
886
+ * Drop a `DataTransfer` at a position, as the drag and drop does.
887
+ */
888
+ dropAt: Nabu["dropAt"];
889
+ /**
890
+ * The drop indicator being shown (reactive).
891
+ */
892
+ dropTarget: DropTarget | null;
893
+ /**
894
+ * The selection's own repair machinery, and the engine's root element: `attachRoot(el)` (what `Nabu.svelte` calls on mount, it returns the detach function), `root`, `owns(node)` (inside MY root, not in a nested editor) and `scope()` ('mine' | 'outside' | 'foreign': whose business the live DOM selection is).
895
+ */
896
+ selection: {
897
+ normalize: NabuSelection["normalize"];
898
+ scheduleRepair: NabuSelection["scheduleRepair"];
899
+ repairAfterRemoval: NabuSelection["repairAfterRemoval"];
900
+ placements: number;
901
+ attachRoot: NabuSelection["attachRoot"];
902
+ owns: NabuSelection["owns"];
903
+ scope: NabuSelection["scope"];
904
+ root: HTMLElement | null;
905
+ };
906
+ };
907
+ import { Block } from './block.svelte.js';
219
908
  import { LoroDoc } from 'loro-crdt';
220
909
  import { NabuSelection } from './selection.svelte.js';
221
910
  import type { LoroTree } from "loro-crdt";
222
911
  import { UndoManager } from 'loro-crdt';
223
912
  import type { Extension } from '../utils/extensions.js';
913
+ import { CommandConfirmation } from '../utils/command-confirm.svelte.js';
914
+ import { CommandRegistry } from '../utils/commands.js';
224
915
  import { SvelteMap } from 'svelte/reactivity';
225
- import { Block } from './block.svelte.js';
226
916
  import type { Component } from "svelte";
227
917
  import { SvelteSet } from 'svelte/reactivity';
918
+ import type { DropTarget } from '../utils/drop.js';
919
+ import type { DropPosition } from '../utils/drop.js';
228
920
  import type { LoroTreeNode } from "loro-crdt";
921
+ import { Pulse } from '@aionbuilders/pulse';