@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,8 +1,32 @@
1
+ /**
2
+ * Degrades the blocks whose type is NOT registered in the receiving editor (a fragment copied from a richer
3
+ * editor, an old document, a third-party extension that is not loaded): nothing is dropped.
4
+ * - the block becomes a block of `fallbackType` (the editor's default text block) with its text (`delta`) and
5
+ * `partial` kept; its props are dropped (they belong to the unknown type);
6
+ * - its children are kept as normal blocks RIGHT AFTER it, at the same level (an unknown container has no
7
+ * body to hold them), recursively degraded;
8
+ * - the children of a known block are degraded in place.
9
+ * Pure: returns new objects, never mutates the input; the engine names no block type (`isKnown` and
10
+ * `fallbackType` come from the registry / `defaultBlockType`).
11
+ * @param {PasteBlock[]} blocks
12
+ * @param {(type: string) => boolean} isKnown
13
+ * @param {string | null | undefined} fallbackType the default text block type; falsy = nothing to degrade to
14
+ * @returns {PasteBlock[]}
15
+ */
16
+ export function degradeUnknownBlocks(blocks: PasteBlock[], isKnown: (type: string) => boolean, fallbackType: string | null | undefined): PasteBlock[];
17
+ /**
18
+ * Whether `importJSON` can read a document export of this `version` (see {@link JSON_FORMAT_VERSION}). A missing version is
19
+ * read as the current one; the number `1` and the string `'1'` are the same version.
20
+ * @param {unknown} version
21
+ * @returns {boolean}
22
+ */
23
+ export function isSupportedJsonVersion(version: unknown): boolean;
1
24
  /**
2
25
  * Convert a `serialize('json')` document export back into PasteBlocks.
3
- * The json format stores text as Slate-like runs (`{text, ...marks}`);
4
- * PasteBlocks store Loro deltas (`{insert, attributes}`).
5
- * @param {Array<{type: string, props?: Record<string, any>, content?: Array<{text: string, [mark: string]: any}>, children?: any[]}>} blocks
26
+ * The json format stores text as Slate-like runs (`{text, ...marks}`) or, for a code block, as a plain string;
27
+ * PasteBlocks store Loro deltas (`{insert, attributes}`). Top-level keys other than `id` / `type` / `props` / `content` /
28
+ * `children` are read as props (the `checked` of a to-do item in the first exports sat next to `type`).
29
+ * @param {Array<{type: string, props?: Record<string, any>, content?: Array<{text: string, [mark: string]: any}> | string, children?: any[], [key: string]: any}>} blocks
6
30
  * @returns {PasteBlock[]}
7
31
  */
8
32
  export function jsonToPasteBlocks(blocks: Array<{
@@ -11,8 +35,9 @@ export function jsonToPasteBlocks(blocks: Array<{
11
35
  content?: Array<{
12
36
  text: string;
13
37
  [mark: string]: any;
14
- }>;
38
+ }> | string;
15
39
  children?: any[];
40
+ [key: string]: any;
16
41
  }>): PasteBlock[];
17
42
  /**
18
43
  * @import { Nabu, Block } from '../blocks'
@@ -20,90 +45,283 @@ export function jsonToPasteBlocks(blocks: Array<{
20
45
  /**
21
46
  * @typedef {Object} PasteBlock
22
47
  * @property {string} type
23
- * @property {'start' | 'end' | 'both' | false} partial
48
+ * @property {'start' | 'end' | 'both' | false} [partial] absent = false (a whole block)
24
49
  * @property {Record<string, any>} [props]
25
50
  * @property {import('loro-crdt').Delta<string>[]} [delta]
26
51
  * @property {PasteBlock[]} [children]
27
52
  */
28
53
  /**
29
54
  * @typedef {Object} PasteFragment
55
+ * @property {boolean} [external] the content comes from outside the editor (the HTML of a web page, Docs…) rather than from
56
+ * Nabu itself: `files.importRemote` applies to its remote media URLs
30
57
  * @property {PasteBlock[]} blocks
58
+ * @property {Record<string, import('../files/files.svelte.js').EmbeddedAsset>} [assets] bytes (base64) of the
59
+ * `nabu-asset:` refs used by `blocks` (see docs/design/clipboard-format.md)
31
60
  */
32
61
  /**
33
62
  * @typedef {Object} PasteInterpreter
34
63
  * @property {string} format - MIME type géré ('application/x-nabu+json', 'text/html', 'text/plain')
35
64
  * @property {number} [priority] - Plus haut = appelé en premier (default: 0)
36
- * @property {(raw: string, nabu: Nabu) => PasteFragment | null} interpret
65
+ * @property {(raw: string, nabu: Nabu, options?: PasteInterpretOptions) => PasteFragment | null} interpret
66
+ * @property {(raw: string) => boolean} [outranksFiles] - Files on the clipboard normally win over the text payloads. Return
67
+ * true when THIS payload is worth more than the files that come with it (a spreadsheet range is put on the clipboard as
68
+ * a table AND as an image of it).
69
+ */
70
+ /**
71
+ * @typedef {Object} PasteFileHandler
72
+ * What an extension does with a FILE pasted from the clipboard (a screenshot, a file copied from the OS): it makes a block
73
+ * of it. The engine reads the bytes, stores them through `Files` (in the document, or sent to `files.onBeforePersist` with the
74
+ * optimistic `pending` block) and inserts the blocks at the caret, in the order of the files, as ONE undo step. The engine
75
+ * names no block type: whatever an extension accepts is its own business.
76
+ * @property {number} [priority] - Higher is asked first (default 0). The first handler that accepts a file takes it.
77
+ * @property {(file: File, nabu: Nabu) => boolean} accepts - Whether this handler takes `file` (by MIME type, name…)
78
+ * @property {(file: File, nabu: Nabu) => PasteBlock | null} block - The block the file becomes: `type` and the props other
79
+ * than `ref` (`name`, `alt`…), which the engine sets to the stored file. `null` declines the file.
80
+ */
81
+ /**
82
+ * A rule of a block class's `static htmlRules`: which HTML elements the block reads on paste. The rules of every registered
83
+ * block form one ruleset, tried by descending `priority` (default 0); the first whose `selector` (and `filter`) matches wins and
84
+ * its class's `static fromHTML(el, helpers, rule, siblings)` makes the block. Extra fields are the rule's own: the class reads them
85
+ * back from `rule`.
86
+ * @typedef {{
87
+ * selector: string,
88
+ * priority?: number,
89
+ * filter?: (el: Element) => boolean,
90
+ * embed?: boolean,
91
+ * props?: Record<string, any>,
92
+ * [field: string]: any,
93
+ * }} HtmlRule
94
+ * `selector` is a CSS selector tested with `el.matches()`. `priority`: higher is tried first (a specific block beats a generic
95
+ * fallback). `filter`: an extra test once the selector matches. `embed`: the element may sit inside the inline content of another
96
+ * block and is then lifted out as a block of its own. `props`: props the rule asks `fromHTML` to set.
97
+ */
98
+ /**
99
+ * What a block's `static fromHTML` receives to read an element.
100
+ * @typedef {Object} HtmlHelpers
101
+ * @property {(el: Element) => import('loro-crdt').Delta<string>[]} parseInline - The inline content of an element, as a Loro delta
102
+ * @property {(el: Element) => PasteBlock | null} parseBlock - The first block an element makes
103
+ * @property {(el: Element) => PasteBlock[]} parseBlocks - Every block an element makes
104
+ * @property {(el: Element) => PasteBlock[]} parseChildren - The blocks made by each child of an element
105
+ */
106
+ /**
107
+ * What a block's `static fromMarkdown` receives to read its lines (and what `markdownRules` callbacks receive).
108
+ * @typedef {Object} MarkdownHelpers
109
+ * @property {(text: string) => import('loro-crdt').Delta<string>[]} parseInline - Inline markdown to a Loro delta
110
+ * @property {(text: string) => any[]} parseInlineSegments - Inline markdown to segments (text, images...)
111
+ * @property {boolean} joinLines - CommonMark semantics: consecutive lines join into one paragraph (`importMarkdown`); false on paste
112
+ * @property {string} [softBreak] - What replaces a soft line break in a nested parse
113
+ * @property {(lines: string[], index: number) => boolean} interrupts - Whether the line at `index` starts a block that ends the paragraph above it
114
+ * @property {(lines: string[], overrides?: { joinLines?: boolean, softBreak?: string }) => PasteBlock[]} [parseBlocks] - Parse lines as a document of their own (the body of a quote...)
115
+ */
116
+ /**
117
+ * A rule of a block class's `static markdownRules`: how a block starts and how many lines it takes. The rules of every registered
118
+ * block form one ruleset, tried by descending `priority` (default 0) at each line; the first whose `detect` matches and whose class's
119
+ * `static fromMarkdown(lines, helpers, rule)` returns a block (or several) takes the lines `consume` counted. Extra fields are the
120
+ * rule's own.
121
+ * @typedef {{
122
+ * detect: RegExp | ((line: string, lines: string[], index: number, helpers: MarkdownHelpers) => boolean),
123
+ * consume: (lines: string[], index: number, helpers: MarkdownHelpers) => number,
124
+ * priority?: number,
125
+ * interruptsParagraph?: boolean | ((line: string, lines: string[], index: number, helpers: MarkdownHelpers) => boolean),
126
+ * [field: string]: any,
127
+ * }} MarkdownRule
128
+ * `detect`: does the block start at this line. `consume`: how many lines it takes from `index` (at least 1). `priority`: higher is
129
+ * tried first. `interruptsParagraph`: the block may start in the middle of a paragraph (a fence, a heading, a quote...); `true`
130
+ * means "whenever `detect` matches".
131
+ */
132
+ /**
133
+ * The second argument of a block's `static toMarkdown(pb, ctx)` / `static toHtml(pb, ctx)`: the clipboard and `serialize` call it
134
+ * once per block, with helpers to serialize children without knowing their type. Other fields are the caller's own (a list passes its `listType`, `index`...).
135
+ * @typedef {{
136
+ * recurse: (child: PasteBlock, ctx?: Record<string, any>) => string,
137
+ * recurseAll?: (children: PasteBlock[], ctx?: Record<string, any>) => string[],
138
+ * before?: PasteBlock[],
139
+ * after?: PasteBlock[],
140
+ * [field: string]: any,
141
+ * }} SerializeContext
142
+ * `recurse`: serialize one child block. `recurseAll` (markdown only): serialize siblings in order, telling each its neighbours.
143
+ * `before` / `after` (markdown only): the siblings around this block.
144
+ */
145
+ /**
146
+ * @typedef {Object} PasteInterpretOptions
147
+ * @property {boolean} [joinLines] - false/absent (paste): one non-blank line = one block.
148
+ * true (`importMarkdown`): CommonMark semantics, consecutive lines join into one paragraph.
149
+ * Forwarded to block markdown rules as `helpers.joinLines` (and 3rd arg of `consume`).
37
150
  */
38
151
  /**
39
152
  * @typedef {Object} InputRule
153
+ * A declarative text-replacement rule applied while typing: when the text before the caret matches `pattern`, `handler` runs
154
+ * (the markdown shortcuts and the typography substitutions are input rules).
40
155
  * @property {RegExp} pattern - Testé sur le texte AVANT le curseur (avec l'inputType "insertText")
41
156
  * @property {string} [inputType] - Défaut: "insertText"
42
157
  * @property {(nabu: Nabu, block: Block, match: RegExpMatchArray, sel: {from: number, to: number, isCollapsed: boolean, data: string}) => boolean | void} handler
43
158
  * - `sel.data` est le texte en cours d'insertion (event.data).
44
159
  * - Retourne true pour BREAK. NE PAS appeler commit() dans le handler.
45
160
  */
161
+ /**
162
+ * @typedef {Object} SplitData
163
+ * What `onSplit` receives besides the block: where the text is cut, and the tail that moves to the new block.
164
+ * @property {number} offset caret offset in the block's text
165
+ * @property {import('loro-crdt').Delta<string>[]} delta the text from `offset` to the end, as a Loro delta
166
+ */
46
167
  /**
47
168
  * @typedef {{
48
- * onInit: function(Nabu): void,
49
- * onBlockCreate: function(Nabu, Block): void,
50
- * onBlockDelete: function(Nabu, Block): void,
51
- * onBlockUpdate: function(Nabu, Block): void,
52
- * onBeforeTransaction: function(Nabu, Array<{type: string, block: Block}>): void,
53
- * onAfterTransaction: function(Nabu, Array<{type: string, block: Block}>): void,
54
- * onSplit: function(Nabu, Block, Event, {offset: number, delta: import('loro-crdt').Delta<string>}): {block: Block},
55
- * onBeforeInput: function(Nabu, InputEvent, Block): void,
56
- * onInput: function(Nabu, InputEvent, Block): void,
57
- * } & Object<string, function>} ExtensionHooks
169
+ * onInit(nabu: Nabu): void,
170
+ * onBlockCreate(nabu: Nabu, block: Block): void,
171
+ * onBlockDelete(nabu: Nabu, block: Block): void,
172
+ * onBlockUpdate(nabu: Nabu, block: Block): void,
173
+ * onBeforeTransaction(nabu: Nabu, ...args: any[]): void,
174
+ * onAfterTransaction(nabu: Nabu, ...args: any[]): void,
175
+ * onSplit(nabu: Nabu, block: Block, event: Event | null, data: SplitData): { block: Block } | void,
176
+ * onBeforeInput(nabu: Nabu, event: InputEvent, block: Block): symbol | boolean | void,
177
+ * onKeyDown(nabu: Nabu, event: KeyboardEvent, block: Block): symbol | boolean | void,
178
+ * onBeforeMerge(nabu: Nabu, survivor: Block, victim: Block): symbol | void,
179
+ * onInput(nabu: Nabu, event: InputEvent, block: Block): void,
180
+ * [hook: string]: (nabu: Nabu, ...args: any[]) => any,
181
+ * }} ExtensionHooks
182
+ * The hooks an extension can register (`ExtensionInit.hooks`). A hook returns `nabu.BREAK` (or, for `onSplit`, an object)
183
+ * to stop the engine from going on; the others return nothing. Any other name is a custom hook, run with `nabu.trigger(name, ...args)`.
184
+ * Declared as methods, so a handler may narrow the block parameter (`(nabu, block: Paragraph) => ...`).
185
+ *
186
+ * `onBlockCreate`, `onBlockDelete`, `onBlockUpdate`, `onAfterTransaction` and `onInput` are declared for forward compatibility:
187
+ * the engine does not call them yet.
58
188
  */
59
189
  /**
60
190
  * @typedef {Object} ExtensionInit
191
+ * What an extension is made of: a block class and its component, hooks, serializers, actions, commands, paste interpreters and
192
+ * file handlers, input rules, slash menu entries and Loro text styles. Every field is optional; pass it to `extension(name, init)`.
61
193
  * @property {string} [name]
62
194
  * @property {import('svelte').Component} [component]
63
195
  * @property {typeof Block} [block]
196
+ * @property {boolean} [defaultBlock]
197
+ * Marks `block` as the editor's DEFAULT text block (the one created when the engine needs an
198
+ * empty text block of its own: a caret below a trailing void block, …). Last one wins.
64
199
  * @property {Partial<ExtensionHooks>} [hooks]
65
200
  * @property {Record<string, (nabu: Nabu) => any>} [serializers]
66
201
  * @property {Record<string, (nabu: Nabu, data: any, topic: string) => any>} [actions]
202
+ * Handlers of the action bus, by topic (`nabu.exec(topic, data)`). COLLISION RULE: several extensions may declare the same topic and
203
+ * ALL their handlers run (that is how an extension observes another one's topic), so give a topic of your own a distinctive name
204
+ * (`namespace:verb`): two extensions that each mean something different by `code` would both fire. Built-in topics: `mark:*`, `block:*`, `list:*`...
205
+ * @property {Record<string, import('./commands.js').CommandDef>} [commands]
206
+ * Commands (ADR 017): `{ [id]: { label, keys?, when?, scope?, run(nabu, ctx, data?), confirm? } }`. Each one is also an action of the
207
+ * bus (`nabu.exec(id, data)`); the engine resolves their `keys` at keydown, before the legacy `onKeyDown` hooks.
208
+ * @property {(nabu: Nabu, ctx: import('./commands.js').CommandContext) => Record<string, any> | void} [commandContext]
209
+ * Contributes FACTS to the context given to the `when` / `run` / `label` of commands (e.g. `{ atStartOfRegion: true }`).
210
+ * Called once per candidate key press; keep it cheap. It cannot replace the engine's own fields.
67
211
  * @property {PasteInterpreter[]} [pasteInterpreters]
212
+ * @property {PasteFileHandler[]} [pasteFileHandlers]
213
+ * Make a block of a file pasted from the clipboard (see {@link PasteFileHandler}).
68
214
  * @property {InputRule[]} [inputRules]
69
215
  * Declarative text-replacement rules applied while typing (e.g. markdown
70
216
  * shortcuts, smart typography). Tested against the text before the cursor.
217
+ * @property {import('../ui/slash-menu.svelte.js').SlashCommand[]} [slashCommands]
218
+ * Entries this extension adds to the slash menu (collected in `nabu.slashCommands`; the menu has no entry of its own, so a
219
+ * block type absent from the editor is never offered). The menu sorts them by `group`, `order`, then declaration order,
220
+ * whatever the load order of the extensions. A `when(engine, block)` limits an entry to the places where it applies (the
221
+ * block holding the caret); without it the entry is always offered.
71
222
  * @property {Record<string, { expand: 'after' | 'before' | 'both' | 'none' }>} [loroTextStyles]
72
223
  * Loro text style configuration required by this extension.
73
224
  * Passed to `LoroDoc.configTextStyle()` during Nabu initialization so that
74
225
  * `applyDelta` with these attributes works correctly.
75
226
  */
227
+ /**
228
+ * A named bundle of editor behaviour (see {@link ExtensionInit}); the built-in blocks and behaviours are extensions. Build one with
229
+ * `extension(name, init)` and pass it to `createEditor({ extensions })`.
230
+ */
76
231
  export class Extension {
77
232
  /** @param {string} name @param {ExtensionInit} init */
78
233
  constructor(name: string, init?: ExtensionInit);
234
+ /** The extension's name (unique in an editor). */
79
235
  name: string;
236
+ /** The Svelte component that renders the extension's block. */
80
237
  component: import("svelte").Component<any, any, string> | undefined;
238
+ /** The block class this extension registers. */
81
239
  block: typeof Block | undefined;
82
- /** @type {Partial<ExtensionHooks>} */
240
+ /** Whether `block` is the editor's default text block. */
241
+ defaultBlock: boolean;
242
+ /**
243
+ * The hooks of the extension, by name (see {@link ExtensionHooks}).
244
+ * @type {Partial<ExtensionHooks>}
245
+ */
83
246
  hooks: Partial<ExtensionHooks>;
84
- /** @type {Record<string, (nabu: Nabu) => any>} */
247
+ /**
248
+ * Serializers by format name, run by `nabu.serialize(format)`.
249
+ * @type {Record<string, (nabu: Nabu) => any>}
250
+ */
85
251
  serializers: Record<string, (nabu: Nabu) => any>;
86
- /** @type {Record<string, (nabu: Nabu, data: any, topic: string) => any>} */
252
+ /**
253
+ * Handlers of the action bus by topic (`nabu.exec(topic, data)`); several extensions may declare the same topic and all run.
254
+ * @type {Record<string, (nabu: Nabu, data: any, topic: string) => any>}
255
+ */
87
256
  actions: Record<string, (nabu: Nabu, data: any, topic: string) => any>;
88
- /** @type {PasteInterpreter[]} */
257
+ /**
258
+ * The commands this extension declares, by id (see {@link CommandDef}).
259
+ * @type {Record<string, import('./commands.js').CommandDef>}
260
+ */
261
+ commands: Record<string, import("./commands.js").CommandDef>;
262
+ /**
263
+ * Contributes facts to the context given to command `when` / `run` functions.
264
+ * @type {ExtensionInit['commandContext']}
265
+ */
266
+ commandContext: ExtensionInit["commandContext"];
267
+ /**
268
+ * Interpreters of clipboard formats (see {@link PasteInterpreter}).
269
+ * @type {PasteInterpreter[]}
270
+ */
89
271
  pasteInterpreters: PasteInterpreter[];
90
- /** @type {InputRule[]} */
272
+ /**
273
+ * Handlers that make a block of a pasted file (see {@link PasteFileHandler}).
274
+ * @type {PasteFileHandler[]}
275
+ */
276
+ pasteFileHandlers: PasteFileHandler[];
277
+ /**
278
+ * Text-replacement rules applied while typing (see {@link InputRule}).
279
+ * @type {InputRule[]}
280
+ */
91
281
  inputRules: InputRule[];
92
- /** @type {Record<string, { expand: 'after' | 'before' | 'both' | 'none' }>} */
282
+ /**
283
+ * Entries this extension adds to the slash menu.
284
+ * @type {import('../ui/slash-menu.svelte.js').SlashCommand[]}
285
+ */
286
+ slashCommands: import("../ui/slash-menu.svelte.js").SlashCommand[];
287
+ /**
288
+ * Loro text style configuration this extension needs for its marks.
289
+ * @type {Record<string, { expand: 'after' | 'before' | 'both' | 'none' }>}
290
+ */
93
291
  loroTextStyles: Record<string, {
94
292
  expand: "after" | "before" | "both" | "none";
95
293
  }>;
96
294
  }
97
295
  export function extension(name: string, init: ExtensionInit): Extension;
296
+ /**
297
+ * Current version of the `application/x-nabu+json` clipboard format (see docs/design/clipboard-format.md).
298
+ * Written on copy as `version`; the Nabu paste interpreter accepts it (and fragments without a version).
299
+ */
300
+ export const CLIPBOARD_FORMAT_VERSION: 1;
301
+ /** Version written by `serialize('json')` (document export). `importJSON` reads this one (a missing version is read as it). */
302
+ export const JSON_FORMAT_VERSION: "1";
98
303
  export type PasteBlock = {
99
304
  type: string;
100
- partial: "start" | "end" | "both" | false;
305
+ /**
306
+ * absent = false (a whole block)
307
+ */
308
+ partial?: false | "start" | "end" | "both" | undefined;
101
309
  props?: Record<string, any> | undefined;
102
310
  delta?: import("loro-crdt").Delta<string>[] | undefined;
103
311
  children?: PasteBlock[] | undefined;
104
312
  };
105
313
  export type PasteFragment = {
314
+ /**
315
+ * the content comes from outside the editor (the HTML of a web page, Docs…) rather than from
316
+ * Nabu itself: `files.importRemote` applies to its remote media URLs
317
+ */
318
+ external?: boolean | undefined;
106
319
  blocks: PasteBlock[];
320
+ /**
321
+ * bytes (base64) of the
322
+ * `nabu-asset:` refs used by `blocks` (see docs/design/clipboard-format.md)
323
+ */
324
+ assets?: Record<string, import("../files/files.svelte.js").EmbeddedAsset> | undefined;
107
325
  };
108
326
  export type PasteInterpreter = {
109
327
  /**
@@ -114,8 +332,136 @@ export type PasteInterpreter = {
114
332
  * - Plus haut = appelé en premier (default: 0)
115
333
  */
116
334
  priority?: number | undefined;
117
- interpret: (raw: string, nabu: Nabu) => PasteFragment | null;
335
+ interpret: (raw: string, nabu: Nabu, options?: PasteInterpretOptions) => PasteFragment | null;
336
+ /**
337
+ * - Files on the clipboard normally win over the text payloads. Return
338
+ * true when THIS payload is worth more than the files that come with it (a spreadsheet range is put on the clipboard as
339
+ * a table AND as an image of it).
340
+ */
341
+ outranksFiles?: ((raw: string) => boolean) | undefined;
342
+ };
343
+ /**
344
+ * What an extension does with a FILE pasted from the clipboard (a screenshot, a file copied from the OS): it makes a block
345
+ * of it. The engine reads the bytes, stores them through `Files` (in the document, or sent to `files.onBeforePersist` with the
346
+ * optimistic `pending` block) and inserts the blocks at the caret, in the order of the files, as ONE undo step. The engine
347
+ * names no block type: whatever an extension accepts is its own business.
348
+ */
349
+ export type PasteFileHandler = {
350
+ /**
351
+ * - Higher is asked first (default 0). The first handler that accepts a file takes it.
352
+ */
353
+ priority?: number | undefined;
354
+ /**
355
+ * - Whether this handler takes `file` (by MIME type, name…)
356
+ */
357
+ accepts: (file: File, nabu: Nabu) => boolean;
358
+ /**
359
+ * - The block the file becomes: `type` and the props other
360
+ * than `ref` (`name`, `alt`…), which the engine sets to the stored file. `null` declines the file.
361
+ */
362
+ block: (file: File, nabu: Nabu) => PasteBlock | null;
118
363
  };
364
+ /**
365
+ * `selector` is a CSS selector tested with `el.matches()`. `priority`: higher is tried first (a specific block beats a generic
366
+ * fallback). `filter`: an extra test once the selector matches. `embed`: the element may sit inside the inline content of another
367
+ * block and is then lifted out as a block of its own. `props`: props the rule asks `fromHTML` to set.
368
+ */
369
+ export type HtmlRule = {
370
+ selector: string;
371
+ priority?: number;
372
+ filter?: (el: Element) => boolean;
373
+ embed?: boolean;
374
+ props?: Record<string, any>;
375
+ [field: string]: any;
376
+ };
377
+ /**
378
+ * What a block's `static fromHTML` receives to read an element.
379
+ */
380
+ export type HtmlHelpers = {
381
+ /**
382
+ * - The inline content of an element, as a Loro delta
383
+ */
384
+ parseInline: (el: Element) => import("loro-crdt").Delta<string>[];
385
+ /**
386
+ * - The first block an element makes
387
+ */
388
+ parseBlock: (el: Element) => PasteBlock | null;
389
+ /**
390
+ * - Every block an element makes
391
+ */
392
+ parseBlocks: (el: Element) => PasteBlock[];
393
+ /**
394
+ * - The blocks made by each child of an element
395
+ */
396
+ parseChildren: (el: Element) => PasteBlock[];
397
+ };
398
+ /**
399
+ * What a block's `static fromMarkdown` receives to read its lines (and what `markdownRules` callbacks receive).
400
+ */
401
+ export type MarkdownHelpers = {
402
+ /**
403
+ * - Inline markdown to a Loro delta
404
+ */
405
+ parseInline: (text: string) => import("loro-crdt").Delta<string>[];
406
+ /**
407
+ * - Inline markdown to segments (text, images...)
408
+ */
409
+ parseInlineSegments: (text: string) => any[];
410
+ /**
411
+ * - CommonMark semantics: consecutive lines join into one paragraph (`importMarkdown`); false on paste
412
+ */
413
+ joinLines: boolean;
414
+ /**
415
+ * - What replaces a soft line break in a nested parse
416
+ */
417
+ softBreak?: string | undefined;
418
+ /**
419
+ * - Whether the line at `index` starts a block that ends the paragraph above it
420
+ */
421
+ interrupts: (lines: string[], index: number) => boolean;
422
+ /**
423
+ * - Parse lines as a document of their own (the body of a quote...)
424
+ */
425
+ parseBlocks?: ((lines: string[], overrides?: {
426
+ joinLines?: boolean;
427
+ softBreak?: string;
428
+ }) => PasteBlock[]) | undefined;
429
+ };
430
+ /**
431
+ * `detect`: does the block start at this line. `consume`: how many lines it takes from `index` (at least 1). `priority`: higher is
432
+ * tried first. `interruptsParagraph`: the block may start in the middle of a paragraph (a fence, a heading, a quote...); `true`
433
+ * means "whenever `detect` matches".
434
+ */
435
+ export type MarkdownRule = {
436
+ detect: RegExp | ((line: string, lines: string[], index: number, helpers: MarkdownHelpers) => boolean);
437
+ consume: (lines: string[], index: number, helpers: MarkdownHelpers) => number;
438
+ priority?: number;
439
+ interruptsParagraph?: boolean | ((line: string, lines: string[], index: number, helpers: MarkdownHelpers) => boolean);
440
+ [field: string]: any;
441
+ };
442
+ /**
443
+ * `recurse`: serialize one child block. `recurseAll` (markdown only): serialize siblings in order, telling each its neighbours.
444
+ * `before` / `after` (markdown only): the siblings around this block.
445
+ */
446
+ export type SerializeContext = {
447
+ recurse: (child: PasteBlock, ctx?: Record<string, any>) => string;
448
+ recurseAll?: (children: PasteBlock[], ctx?: Record<string, any>) => string[];
449
+ before?: PasteBlock[];
450
+ after?: PasteBlock[];
451
+ [field: string]: any;
452
+ };
453
+ export type PasteInterpretOptions = {
454
+ /**
455
+ * - false/absent (paste): one non-blank line = one block.
456
+ * true (`importMarkdown`): CommonMark semantics, consecutive lines join into one paragraph.
457
+ * Forwarded to block markdown rules as `helpers.joinLines` (and 3rd arg of `consume`).
458
+ */
459
+ joinLines?: boolean | undefined;
460
+ };
461
+ /**
462
+ * A declarative text-replacement rule applied while typing: when the text before the caret matches `pattern`, `handler` runs
463
+ * (the markdown shortcuts and the typography substitutions are input rules).
464
+ */
119
465
  export type InputRule = {
120
466
  /**
121
467
  * - Testé sur le texte AVANT le curseur (avec l'inputType "insertText")
@@ -136,43 +482,91 @@ export type InputRule = {
136
482
  data: string;
137
483
  }) => boolean | void;
138
484
  };
485
+ /**
486
+ * What `onSplit` receives besides the block: where the text is cut, and the tail that moves to the new block.
487
+ */
488
+ export type SplitData = {
489
+ /**
490
+ * caret offset in the block's text
491
+ */
492
+ offset: number;
493
+ /**
494
+ * the text from `offset` to the end, as a Loro delta
495
+ */
496
+ delta: import("loro-crdt").Delta<string>[];
497
+ };
498
+ /**
499
+ * The hooks an extension can register (`ExtensionInit.hooks`). A hook returns `nabu.BREAK` (or, for `onSplit`, an object)
500
+ * to stop the engine from going on; the others return nothing. Any other name is a custom hook, run with `nabu.trigger(name, ...args)`.
501
+ * Declared as methods, so a handler may narrow the block parameter (`(nabu, block: Paragraph) => ...`).
502
+ *
503
+ * `onBlockCreate`, `onBlockDelete`, `onBlockUpdate`, `onAfterTransaction` and `onInput` are declared for forward compatibility:
504
+ * the engine does not call them yet.
505
+ */
139
506
  export type ExtensionHooks = {
140
- onInit: (arg0: Nabu) => void;
141
- onBlockCreate: (arg0: Nabu, arg1: Block) => void;
142
- onBlockDelete: (arg0: Nabu, arg1: Block) => void;
143
- onBlockUpdate: (arg0: Nabu, arg1: Block) => void;
144
- onBeforeTransaction: (arg0: Nabu, arg1: Array<{
145
- type: string;
507
+ onInit(nabu: Nabu): void;
508
+ onBlockCreate(nabu: Nabu, block: Block): void;
509
+ onBlockDelete(nabu: Nabu, block: Block): void;
510
+ onBlockUpdate(nabu: Nabu, block: Block): void;
511
+ onBeforeTransaction(nabu: Nabu, ...args: any[]): void;
512
+ onAfterTransaction(nabu: Nabu, ...args: any[]): void;
513
+ onSplit(nabu: Nabu, block: Block, event: Event | null, data: SplitData): {
146
514
  block: Block;
147
- }>) => void;
148
- onAfterTransaction: (arg0: Nabu, arg1: Array<{
149
- type: string;
150
- block: Block;
151
- }>) => void;
152
- onSplit: (arg0: Nabu, arg1: Block, arg2: Event, arg3: {
153
- offset: number;
154
- delta: import("loro-crdt").Delta<string>;
155
- }) => {
156
- block: Block;
157
- };
158
- onBeforeInput: (arg0: Nabu, arg1: InputEvent, arg2: Block) => void;
159
- onInput: (arg0: Nabu, arg1: InputEvent, arg2: Block) => void;
160
- } & {
161
- [x: string]: Function;
515
+ } | void;
516
+ onBeforeInput(nabu: Nabu, event: InputEvent, block: Block): symbol | boolean | void;
517
+ onKeyDown(nabu: Nabu, event: KeyboardEvent, block: Block): symbol | boolean | void;
518
+ onBeforeMerge(nabu: Nabu, survivor: Block, victim: Block): symbol | void;
519
+ onInput(nabu: Nabu, event: InputEvent, block: Block): void;
520
+ [hook: string]: (nabu: Nabu, ...args: any[]) => any;
162
521
  };
522
+ /**
523
+ * What an extension is made of: a block class and its component, hooks, serializers, actions, commands, paste interpreters and
524
+ * file handlers, input rules, slash menu entries and Loro text styles. Every field is optional; pass it to `extension(name, init)`.
525
+ */
163
526
  export type ExtensionInit = {
164
527
  name?: string | undefined;
165
528
  component?: import("svelte").Component<any, any, string> | undefined;
166
529
  block?: typeof Block | undefined;
530
+ /**
531
+ * Marks `block` as the editor's DEFAULT text block (the one created when the engine needs an
532
+ * empty text block of its own: a caret below a trailing void block, …). Last one wins.
533
+ */
534
+ defaultBlock?: boolean | undefined;
167
535
  hooks?: Partial<ExtensionHooks> | undefined;
168
536
  serializers?: Record<string, (nabu: Nabu) => any> | undefined;
537
+ /**
538
+ * Handlers of the action bus, by topic (`nabu.exec(topic, data)`). COLLISION RULE: several extensions may declare the same topic and
539
+ * ALL their handlers run (that is how an extension observes another one's topic), so give a topic of your own a distinctive name
540
+ * (`namespace:verb`): two extensions that each mean something different by `code` would both fire. Built-in topics: `mark:*`, `block:*`, `list:*`...
541
+ */
169
542
  actions?: Record<string, (nabu: Nabu, data: any, topic: string) => any> | undefined;
543
+ /**
544
+ * Commands (ADR 017): `{ [id]: { label, keys?, when?, scope?, run(nabu, ctx, data?), confirm? } }`. Each one is also an action of the
545
+ * bus (`nabu.exec(id, data)`); the engine resolves their `keys` at keydown, before the legacy `onKeyDown` hooks.
546
+ */
547
+ commands?: Record<string, import("./commands.js").CommandDef> | undefined;
548
+ /**
549
+ * Contributes FACTS to the context given to the `when` / `run` / `label` of commands (e.g. `{ atStartOfRegion: true }`).
550
+ * Called once per candidate key press; keep it cheap. It cannot replace the engine's own fields.
551
+ */
552
+ commandContext?: ((nabu: Nabu, ctx: import("./commands.js").CommandContext) => Record<string, any> | void) | undefined;
170
553
  pasteInterpreters?: PasteInterpreter[] | undefined;
554
+ /**
555
+ * Make a block of a file pasted from the clipboard (see {@link PasteFileHandler}).
556
+ */
557
+ pasteFileHandlers?: PasteFileHandler[] | undefined;
171
558
  /**
172
559
  * Declarative text-replacement rules applied while typing (e.g. markdown
173
560
  * shortcuts, smart typography). Tested against the text before the cursor.
174
561
  */
175
562
  inputRules?: InputRule[] | undefined;
563
+ /**
564
+ * Entries this extension adds to the slash menu (collected in `nabu.slashCommands`; the menu has no entry of its own, so a
565
+ * block type absent from the editor is never offered). The menu sorts them by `group`, `order`, then declaration order,
566
+ * whatever the load order of the extensions. A `when(engine, block)` limits an entry to the places where it applies (the
567
+ * block holding the caret); without it the entry is always offered.
568
+ */
569
+ slashCommands?: import("../ui/slash-menu.svelte.js").SlashCommand[] | undefined;
176
570
  /**
177
571
  * Loro text style configuration required by this extension.
178
572
  * Passed to `LoroDoc.configTextStyle()` during Nabu initialization so that