@aionbuilders/nabu 0.1.0-beta.0 → 0.1.1

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 (308) hide show
  1. package/CHANGELOG.md +531 -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 +195 -55
  12. package/dist/behaviors/text/text.behavior.svelte.js +531 -103
  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 +32 -18
  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 +1753 -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 +35 -14
  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 +55 -8
  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/composition.d.ts +28 -0
  253. package/dist/utils/composition.js +51 -0
  254. package/dist/utils/dom-scope.d.ts +14 -0
  255. package/dist/utils/dom-scope.js +20 -0
  256. package/dist/utils/drop.d.ts +160 -0
  257. package/dist/utils/drop.js +305 -0
  258. package/dist/utils/extensions.d.ts +439 -45
  259. package/dist/utils/extensions.js +271 -29
  260. package/dist/utils/html.d.ts +44 -0
  261. package/dist/utils/html.js +183 -0
  262. package/dist/utils/index.d.ts +3 -0
  263. package/dist/utils/index.js +3 -0
  264. package/dist/utils/keys.d.ts +120 -0
  265. package/dist/utils/keys.js +248 -0
  266. package/dist/utils/links.d.ts +22 -0
  267. package/dist/utils/links.js +34 -0
  268. package/dist/utils/placeholders.d.ts +81 -3
  269. package/dist/utils/placeholders.js +73 -3
  270. package/dist/utils/selection.svelte.d.ts +48 -20
  271. package/dist/utils/selection.svelte.js +60 -10
  272. package/dist/utils/spellcheck.d.ts +9 -0
  273. package/dist/utils/spellcheck.js +17 -0
  274. package/dist/utils/tab.d.ts +31 -0
  275. package/dist/utils/tab.js +117 -0
  276. package/dist/utils/words.d.ts +42 -0
  277. package/dist/utils/words.js +147 -0
  278. package/dist/vite.d.ts +9 -3
  279. package/dist/vite.js +19 -8
  280. package/package.json +56 -20
  281. package/dist/blocks/variable.svelte.d.ts +0 -47
  282. package/dist/blocks/variable.svelte.js +0 -51
  283. package/dist/blocks/zone/TemplateEditor.svelte +0 -308
  284. package/dist/blocks/zone/TemplateEditor.svelte.d.ts +0 -11
  285. package/dist/blocks/zone/Zone.svelte +0 -272
  286. package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
  287. package/dist/blocks/zone/ZoneEditor.svelte +0 -289
  288. package/dist/blocks/zone/ZoneEditor.svelte.d.ts +0 -11
  289. package/dist/blocks/zone/ZoneTemplatesList.svelte +0 -188
  290. package/dist/blocks/zone/ZoneTemplatesList.svelte.d.ts +0 -11
  291. package/dist/blocks/zone/hooks/onBeforeInput.hook.d.ts +0 -3
  292. package/dist/blocks/zone/hooks/onBeforeInput.hook.js +0 -30
  293. package/dist/blocks/zone/index.d.ts +0 -2
  294. package/dist/blocks/zone/index.js +0 -2
  295. package/dist/blocks/zone/zone.extension.d.ts +0 -2
  296. package/dist/blocks/zone/zone.extension.js +0 -237
  297. package/dist/blocks/zone/zone.svelte.d.ts +0 -221
  298. package/dist/blocks/zone/zone.svelte.js +0 -608
  299. package/dist/overlays/context/Context.svelte +0 -182
  300. package/dist/overlays/context/Context.svelte.d.ts +0 -17
  301. package/dist/overlays/context/collect.d.ts +0 -17
  302. package/dist/overlays/context/collect.js +0 -33
  303. package/dist/overlays/context/context.extension.d.ts +0 -2
  304. package/dist/overlays/context/context.extension.js +0 -8
  305. package/dist/overlays/context/context.svelte.d.ts +0 -82
  306. package/dist/overlays/context/context.svelte.js +0 -159
  307. package/dist/overlays/context/index.d.ts +0 -3
  308. package/dist/overlays/context/index.js +0 -3
@@ -1,20 +1,115 @@
1
1
  <script>
2
- import { SlashMenuController, DEFAULT_SLASH_COMMANDS } from './slash-menu.svelte.js';
3
- /** @type {{ engine: import('../blocks/nabu.svelte.js').Nabu, commands?: import('./slash-menu.svelte.js').SlashCommand[] }} */
4
- let { engine, commands = DEFAULT_SLASH_COMMANDS } = $props();
2
+ import { SlashMenuController } from './slash-menu.svelte.js';
3
+ import { anchorRect, placeNear, clipBounds, isOutside } from './anchor.js';
4
+
5
+ /**
6
+ * The texts the menu exposes to assistive technology (the visible titles come from the entries themselves):
7
+ * - `label`: the accessible name of the listbox, default "Insert block";
8
+ * - `groups`: the name of each group of entries (`role="group"`), by `group` id; an unknown id is used as it is;
9
+ * - `option`: the sentence announced for the active entry, `({ title, subtitle, index, count }) => string` (`index` from 1),
10
+ * default "Heading 1, Large section heading, 2 of 15".
11
+ * @typedef {Object} SlashMenuMessages
12
+ * @property {string} [label]
13
+ * @property {Record<string, string>} [groups]
14
+ * @property {(info: { title: string, subtitle?: string, index: number, count: number }) => string} [option]
15
+ */
16
+
17
+ /** @type {{ engine: import('../blocks/nabu.svelte.js').Nabu, commands?: import('./slash-menu.svelte.js').SlashCommand[], messages?: SlashMenuMessages }} */
18
+ let { engine, commands = [], messages = {} } = $props();
5
19
  const ctrl = new SlashMenuController(engine, commands);
6
- let pos = $state({ top: 0, left: 0 });
20
+ const uid = $props.id();
21
+ const listId = `${uid}-list`;
22
+ const optionId = (/** @type {number} */ i) => `${uid}-opt-${i}`;
23
+
24
+ const GROUP_NAMES = { text: 'Text', lists: 'Lists', blocks: 'Blocks', media: 'Media', structure: 'Structure' };
25
+ const label = $derived(messages.label ?? 'Insert block');
26
+ const groupName = (/** @type {string} */ id) => messages.groups?.[id] ?? /** @type {Record<string, string>} */ (GROUP_NAMES)[id] ?? id;
27
+
28
+ // Consecutive entries of the same group share one `role="group"` (the entries are already sorted by group). The group is not
29
+ // drawn: the menu looks as before, the grouping is for assistive technology. `i` is the position in the whole list.
30
+ const sections = $derived.by(() => {
31
+ /** @type {{ group: string | null, items: Array<{ item: import('./slash-menu.svelte.js').SlashCommand, i: number }> }[]} */
32
+ const out = [];
33
+ ctrl.filteredItems.forEach((item, i) => {
34
+ const group = item.group || null;
35
+ const last = out[out.length - 1];
36
+ if (last && last.group === group) last.items.push({ item, i });
37
+ else out.push({ group, items: [{ item, i }] });
38
+ });
39
+ return out;
40
+ });
41
+ /** @type {HTMLElement | null} */
42
+ let menuEl = $state(null);
43
+ /** Viewport coordinates (the menu is `position: fixed`): anchored by `top` (below the caret) or `bottom` (above it). */
44
+ /** @type {import('./anchor.js').Placement} */
45
+ let pos = $state({ top: 0, bottom: null, left: 0, maxHeight: 320 });
46
+
47
+ /**
48
+ * `true` while the caret line is entirely scrolled out of its visible scroll container (or off the viewport): the menu is then
49
+ * NOT rendered (it would float over the page at a stale anchor) — the slash command stays pending, and the menu is back as
50
+ * soon as the caret line is visible again. Keyboard navigation (arrows / Enter / Tab) is not captured while it is hidden.
51
+ */
52
+ let hidden = $state(false);
53
+
54
+ const MAX_HEIGHT = 320; // keep in sync with the CSS max-height
55
+ const MIN_HEIGHT = 100; // never squash the menu below this, even in a tiny viewport
56
+
57
+ // What a screen reader hears when the active entry changes. The caret stays in the editor (a contenteditable host: focus can
58
+ // never move to the menu), so the menu cannot rely on focus; a polite live region says the active entry, and the editor root
59
+ // points at it with aria-activedescendant (below) for the assistive technologies that follow it.
60
+ const announcement = $derived.by(() => {
61
+ if (!ctrl.open || hidden) return '';
62
+ const item = ctrl.filteredItems[ctrl.selectedIndex];
63
+ if (!item) return '';
64
+ const info = { title: item.title, subtitle: item.subtitle, index: ctrl.selectedIndex + 1, count: ctrl.filteredItems.length };
65
+ return messages.option ? messages.option(info) : `${info.title}${info.subtitle ? `, ${info.subtitle}` : ''}, ${info.index} of ${info.count}`;
66
+ });
67
+
68
+ // The editor root is the element that has the focus: while the menu is open it owns the list (aria-controls) and names the
69
+ // active entry (aria-activedescendant), like the combobox pattern but without changing the role of the host (which would
70
+ // flatten the headings inside it). Both are removed when the menu closes.
71
+ $effect(() => {
72
+ if (!ctrl.open || hidden || !menuEl) return;
73
+ const root = ctrl.match?.block?.element?.closest?.('[data-nabu-root]');
74
+ if (!root) return;
75
+ root.setAttribute('aria-controls', listId);
76
+ root.setAttribute('aria-activedescendant', optionId(ctrl.selectedIndex));
77
+ return () => { root.removeAttribute('aria-controls'); root.removeAttribute('aria-activedescendant'); };
78
+ });
7
79
 
8
80
  // Reset the highlighted item whenever the query changes.
9
81
  $effect(() => { ctrl.query; ctrl.selectedIndex = 0; });
10
82
 
11
- // Position the popup just below the caret when open.
83
+ // Place the popup next to the caret, in viewport coordinates, inside the viewport (shared rules: anchor.js):
84
+ // below the caret line, or flipped above it when there is no room below; clamped horizontally. Hidden while the caret
85
+ // line is out of the visible area of its scroll container.
86
+ function place() {
87
+ const rect = anchorRect(engine, ctrl.match?.block?.element ?? null);
88
+ if (!rect) return;
89
+ hidden = isOutside(rect, clipBounds(engine.selection?.firstRange?.commonAncestorContainer ?? ctrl.match?.block?.element));
90
+ if (hidden || !menuEl) return;
91
+ pos = placeNear(rect, menuEl, { maxHeight: MAX_HEIGHT, minHeight: MIN_HEIGHT });
92
+ }
93
+
94
+ $effect(() => {
95
+ if (!ctrl.open) return;
96
+ ctrl.filteredItems.length; // the menu height depends on it
97
+ menuEl; // re-run once the element is mounted
98
+ engine.selection?.firstRange;
99
+ place();
100
+ });
101
+
102
+ // The menu is fixed: follow the caret when the page (or a scroll container) scrolls / resizes while it is open.
12
103
  $effect(() => {
13
104
  if (!ctrl.open) return;
14
- const range = engine.selection?.firstRange;
15
- if (!range) return;
16
- const r = range.getBoundingClientRect();
17
- pos = { top: r.bottom + window.scrollY + 4, left: r.left + window.scrollX };
105
+ /** @param {Event} e */
106
+ const onScroll = (e) => { if (e.target !== menuEl) place(); }; // not the menu's own list scrolling
107
+ window.addEventListener('scroll', onScroll, true);
108
+ window.addEventListener('resize', place);
109
+ return () => {
110
+ window.removeEventListener('scroll', onScroll, true);
111
+ window.removeEventListener('resize', place);
112
+ };
18
113
  });
19
114
 
20
115
  // Capture keyboard navigation ONLY while the menu is open (capture phase so it
@@ -23,6 +118,9 @@
23
118
  if (!ctrl.open) return;
24
119
  /** @param {KeyboardEvent} ev */
25
120
  const onKey = (ev) => {
121
+ // A key typed in ANOTHER editor of the page is not for this menu (it stays open until its own editor's selection moves).
122
+ if (engine.selection.kindOf(ev.target instanceof Node ? ev.target : null) === 'foreign') return;
123
+ if (hidden && ev.key !== 'Escape') return; // not on screen: the keys keep their normal meaning
26
124
  if (ev.key === 'ArrowDown') { ev.preventDefault(); ev.stopImmediatePropagation(); ctrl.moveSelection(1); }
27
125
  else if (ev.key === 'ArrowUp') { ev.preventDefault(); ev.stopImmediatePropagation(); ctrl.moveSelection(-1); }
28
126
  else if (ev.key === 'Enter' || ev.key === 'Tab') { ev.preventDefault(); ev.stopImmediatePropagation(); ctrl.select(); }
@@ -33,23 +131,53 @@
33
131
  });
34
132
  </script>
35
133
 
36
- {#if ctrl.open}
37
- <div class="nabu-slash" data-nabu-ui contenteditable="false" style="top: {pos.top}px; left: {pos.left}px;">
38
- {#each ctrl.filteredItems as item, i (item.title)}
134
+ {#snippet row(/** @type {import('./slash-menu.svelte.js').SlashCommand} */ item, /** @type {number} */ i)}
39
135
  <button
136
+ id={optionId(i)}
137
+ type="button"
138
+ role="option"
139
+ tabindex="-1"
140
+ aria-selected={i === ctrl.selectedIndex}
40
141
  class="nabu-slash-item"
41
142
  class:active={i === ctrl.selectedIndex}
42
143
  onmousedown={(e) => { e.preventDefault(); ctrl.select(i); }}
43
144
  onmouseenter={() => ctrl.selectedIndex = i}
44
145
  >
45
- <span class="nabu-slash-icon">{item.icon ?? ''}</span>
146
+ <span class="nabu-slash-icon" aria-hidden="true">{item.icon ?? ''}</span>
46
147
  <span class="nabu-slash-title">{item.title}</span>
47
148
  {#if item.subtitle}<span class="nabu-slash-sub">{item.subtitle}</span>{/if}
48
149
  </button>
150
+ {/snippet}
151
+
152
+ {#if ctrl.open && !hidden}
153
+ <div
154
+ bind:this={menuEl}
155
+ id={listId}
156
+ class="nabu-slash"
157
+ role="listbox"
158
+ aria-label={label}
159
+ data-nabu-ui
160
+ contenteditable="false"
161
+ style:top={pos.top === null ? null : `${pos.top}px`}
162
+ style:bottom={pos.bottom === null ? null : `${pos.bottom}px`}
163
+ style:left="{pos.left}px"
164
+ style:max-height="{pos.maxHeight}px"
165
+ >
166
+ {#each sections as section, s (s)}
167
+ {#if section.group}
168
+ <div class="nabu-slash-group" role="group" aria-label={groupName(section.group)}>
169
+ {#each section.items as { item, i } (item.title)}{@render row(item, i)}{/each}
170
+ </div>
171
+ {:else}
172
+ {#each section.items as { item, i } (item.title)}{@render row(item, i)}{/each}
173
+ {/if}
49
174
  {/each}
50
175
  </div>
51
176
  {/if}
52
177
 
178
+ <!-- Always mounted (a live region must exist before its text changes). Visually hidden. -->
179
+ <div class="nabu-slash-live" role="status" aria-live="polite" aria-atomic="true" data-nabu-ui>{announcement}</div>
180
+
53
181
  <style>
54
182
  .nabu-slash {
55
183
  position: fixed;
@@ -60,10 +188,14 @@
60
188
  padding: 4px;
61
189
  background: var(--nb-bg-surface, #1a1a1a);
62
190
  border: 1px solid var(--nb-border, rgba(255,255,255,0.12));
63
- border-radius: 8px;
64
- box-shadow: 0 8px 24px rgba(0,0,0,0.35);
191
+ border-radius: var(--nb-floating-radius, 8px);
192
+ box-shadow: var(--nb-floating-shadow, 0 8px 24px rgba(0,0,0,0.35));
65
193
  pointer-events: all;
66
194
  }
195
+ .nabu-slash-live {
196
+ position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0;
197
+ overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0;
198
+ }
67
199
  .nabu-slash-item {
68
200
  display: flex; align-items: center; gap: 8px;
69
201
  width: 100%; padding: 6px 8px; border: none; background: transparent;
@@ -6,8 +6,28 @@ type SlashMenu = {
6
6
  declare const SlashMenu: import("svelte").Component<{
7
7
  engine: import("../blocks/nabu.svelte.js").Nabu;
8
8
  commands?: import("./slash-menu.svelte.js").SlashCommand[];
9
+ messages?: {
10
+ label?: string | undefined;
11
+ groups?: Record<string, string> | undefined;
12
+ option?: ((info: {
13
+ title: string;
14
+ subtitle?: string;
15
+ index: number;
16
+ count: number;
17
+ }) => string) | undefined;
18
+ };
9
19
  }, {}, "">;
10
20
  type $$ComponentProps = {
11
21
  engine: import("../blocks/nabu.svelte.js").Nabu;
12
22
  commands?: import("./slash-menu.svelte.js").SlashCommand[];
23
+ messages?: {
24
+ label?: string | undefined;
25
+ groups?: Record<string, string> | undefined;
26
+ option?: ((info: {
27
+ title: string;
28
+ subtitle?: string;
29
+ index: number;
30
+ count: number;
31
+ }) => string) | undefined;
32
+ };
13
33
  };
@@ -0,0 +1,112 @@
1
+ /**
2
+ * The viewport rectangle the element hangs from: the caret, else the block holding it, else `fallback`.
3
+ * @param {import('../blocks/nabu.svelte.js').Nabu} engine
4
+ * @param {Element | null} [fallback]
5
+ * @returns {DOMRect | null}
6
+ */
7
+ export function anchorRect(engine: import("../blocks/nabu.svelte.js").Nabu, fallback?: Element | null): DOMRect | null;
8
+ /**
9
+ * @typedef {Object} Placement
10
+ * @property {number | null} top distance from the viewport top (placed below the caret), else `null`
11
+ * @property {number | null} bottom distance from the viewport bottom (placed above the caret), else `null`
12
+ * @property {number} left
13
+ * @property {number} maxHeight
14
+ */
15
+ /**
16
+ * @param {DOMRect} rect the anchor
17
+ * @param {HTMLElement} el the floating element (measured)
18
+ * @param {{ maxHeight?: number, minHeight?: number }} [options]
19
+ * @returns {Placement}
20
+ */
21
+ export function placeNear(rect: DOMRect, el: HTMLElement, { maxHeight, minHeight }?: {
22
+ maxHeight?: number;
23
+ minHeight?: number;
24
+ }): Placement;
25
+ /**
26
+ * @typedef {Object} Bounds a viewport-coordinates box
27
+ * @property {number} top
28
+ * @property {number} bottom
29
+ * @property {number} left
30
+ * @property {number} right
31
+ */
32
+ /**
33
+ * The part of the viewport in which `el` is actually visible: the viewport (the documentElement's client box) intersected with
34
+ * the client box of every ancestor that clips its content (`overflow` other than `visible` on either axis — scroll containers
35
+ * and `overflow: hidden` wrappers; `<html>` / `<body>` are the viewport itself). `topInset` shrinks it from the top, for a
36
+ * host's sticky / fixed header that covers the top of the viewport (see `--nb-toolbar-inset-top` in FloatingToolbar).
37
+ *
38
+ * A floating element is `position: fixed`, so it is never clipped by those ancestors itself: this is what tells where the
39
+ * anchor can still be SEEN, hence where the element may sit and whether it should be shown at all.
40
+ *
41
+ * @param {Node | null | undefined} node the anchor (an element, or a node inside one)
42
+ * @param {{ topInset?: number }} [options]
43
+ * @returns {Bounds}
44
+ */
45
+ export function clipBounds(node: Node | null | undefined, { topInset }?: {
46
+ topInset?: number;
47
+ }): Bounds;
48
+ /**
49
+ * `true` when `rect` lies entirely outside `bounds` (scrolled out of its container / off the viewport): there is nothing to
50
+ * point at any more. A rect that is only partly clipped is still visible.
51
+ * @param {{ top: number, bottom: number, left: number, right: number }} rect
52
+ * @param {Bounds} bounds
53
+ */
54
+ export function isOutside(rect: {
55
+ top: number;
56
+ bottom: number;
57
+ left: number;
58
+ right: number;
59
+ }, bounds: Bounds): boolean;
60
+ /**
61
+ * Placement of a floating element centred ABOVE a (selection) rectangle, `position: fixed` with `top` / `left`: above when it
62
+ * fits between the top of the visible area and the rect, else flipped BELOW the rect, else (the rect fills the visible area)
63
+ * pinned to the top of the visible area. Clamped horizontally inside the viewport and, when it is wide enough to hold the
64
+ * element, inside the clipping container.
65
+ *
66
+ * @param {{ top: number, bottom: number, left: number, width: number }} rect the anchor
67
+ * @param {HTMLElement} el the floating element (measured)
68
+ * @param {Bounds} bounds from `clipBounds`
69
+ * @param {{ gap?: number, margin?: number }} [options]
70
+ * @returns {{ top: number, left: number, placement: 'above' | 'below' | 'inside' }}
71
+ */
72
+ export function placeAround(rect: {
73
+ top: number;
74
+ bottom: number;
75
+ left: number;
76
+ width: number;
77
+ }, el: HTMLElement, bounds: Bounds, { gap, margin }?: {
78
+ gap?: number;
79
+ margin?: number;
80
+ }): {
81
+ top: number;
82
+ left: number;
83
+ placement: "above" | "below" | "inside";
84
+ };
85
+ /**
86
+ * Placement of a floating element (`position: fixed`) next to the caret, shared by the command components
87
+ * (`CommandInvite`, `CommandChooser`). Same rules as the slash menu: below the caret line, flipped above it when there is
88
+ * no room, clamped inside the viewport.
89
+ */
90
+ export const ANCHOR_GAP: 4;
91
+ export const ANCHOR_MARGIN: 8;
92
+ export type Placement = {
93
+ /**
94
+ * distance from the viewport top (placed below the caret), else `null`
95
+ */
96
+ top: number | null;
97
+ /**
98
+ * distance from the viewport bottom (placed above the caret), else `null`
99
+ */
100
+ bottom: number | null;
101
+ left: number;
102
+ maxHeight: number;
103
+ };
104
+ /**
105
+ * a viewport-coordinates box
106
+ */
107
+ export type Bounds = {
108
+ top: number;
109
+ bottom: number;
110
+ left: number;
111
+ right: number;
112
+ };
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Placement of a floating element (`position: fixed`) next to the caret, shared by the command components
3
+ * (`CommandInvite`, `CommandChooser`). Same rules as the slash menu: below the caret line, flipped above it when there is
4
+ * no room, clamped inside the viewport.
5
+ */
6
+
7
+ export const ANCHOR_GAP = 4; // space between the caret line and the element
8
+ export const ANCHOR_MARGIN = 8; // minimum distance to the viewport edges
9
+
10
+ /**
11
+ * The viewport rectangle the element hangs from: the caret, else the block holding it, else `fallback`.
12
+ * @param {import('../blocks/nabu.svelte.js').Nabu} engine
13
+ * @param {Element | null} [fallback]
14
+ * @returns {DOMRect | null}
15
+ */
16
+ export function anchorRect(engine, fallback = null) {
17
+ const range = engine.selection?.firstRange;
18
+ /** @type {DOMRect | undefined} */
19
+ let rect = range?.getBoundingClientRect?.();
20
+ // A collapsed range on an empty line can report a zero-size rect: fall back to the block.
21
+ if (!rect || (!rect.width && !rect.height)) {
22
+ const el = /** @type {HTMLElement | null | undefined} */ (engine.selection?.anchorBlock?.element) ?? fallback;
23
+ rect = el?.getBoundingClientRect?.();
24
+ }
25
+ return rect ?? null;
26
+ }
27
+
28
+ /**
29
+ * @typedef {Object} Placement
30
+ * @property {number | null} top distance from the viewport top (placed below the caret), else `null`
31
+ * @property {number | null} bottom distance from the viewport bottom (placed above the caret), else `null`
32
+ * @property {number} left
33
+ * @property {number} maxHeight
34
+ */
35
+
36
+ /**
37
+ * @param {DOMRect} rect the anchor
38
+ * @param {HTMLElement} el the floating element (measured)
39
+ * @param {{ maxHeight?: number, minHeight?: number }} [options]
40
+ * @returns {Placement}
41
+ */
42
+ export function placeNear(rect, el, { maxHeight = 320, minHeight = 60 } = {}) {
43
+ const vw = document.documentElement.clientWidth;
44
+ const vh = document.documentElement.clientHeight;
45
+ const full = el.scrollHeight + (el.offsetHeight - el.clientHeight);
46
+ const natural = Math.min(maxHeight, full);
47
+ const spaceBelow = vh - rect.bottom - ANCHOR_GAP - ANCHOR_MARGIN;
48
+ const spaceAbove = rect.top - ANCHOR_GAP - ANCHOR_MARGIN;
49
+ const left = Math.max(ANCHOR_MARGIN, Math.min(rect.left, vw - ANCHOR_MARGIN - el.offsetWidth));
50
+ if (natural <= spaceBelow || spaceBelow >= spaceAbove) {
51
+ return { top: rect.bottom + ANCHOR_GAP, bottom: null, left, maxHeight: Math.max(minHeight, Math.min(maxHeight, spaceBelow)) };
52
+ }
53
+ return { top: null, bottom: vh - rect.top + ANCHOR_GAP, left, maxHeight: Math.max(minHeight, Math.min(maxHeight, spaceAbove)) };
54
+ }
55
+
56
+ /**
57
+ * @typedef {Object} Bounds a viewport-coordinates box
58
+ * @property {number} top
59
+ * @property {number} bottom
60
+ * @property {number} left
61
+ * @property {number} right
62
+ */
63
+
64
+ /**
65
+ * The part of the viewport in which `el` is actually visible: the viewport (the documentElement's client box) intersected with
66
+ * the client box of every ancestor that clips its content (`overflow` other than `visible` on either axis — scroll containers
67
+ * and `overflow: hidden` wrappers; `<html>` / `<body>` are the viewport itself). `topInset` shrinks it from the top, for a
68
+ * host's sticky / fixed header that covers the top of the viewport (see `--nb-toolbar-inset-top` in FloatingToolbar).
69
+ *
70
+ * A floating element is `position: fixed`, so it is never clipped by those ancestors itself: this is what tells where the
71
+ * anchor can still be SEEN, hence where the element may sit and whether it should be shown at all.
72
+ *
73
+ * @param {Node | null | undefined} node the anchor (an element, or a node inside one)
74
+ * @param {{ topInset?: number }} [options]
75
+ * @returns {Bounds}
76
+ */
77
+ export function clipBounds(node, { topInset = 0 } = {}) {
78
+ const doc = document.documentElement;
79
+ /** @type {Bounds} */
80
+ const b = { top: Math.max(0, topInset), bottom: doc.clientHeight, left: 0, right: doc.clientWidth };
81
+ let el = node && node.nodeType === 1 ? /** @type {HTMLElement} */ (node) : (node?.parentElement ?? null);
82
+ for (; el && el !== document.body && el !== doc; el = el.parentElement) {
83
+ const cs = getComputedStyle(el);
84
+ if (cs.overflowX === 'visible' && cs.overflowY === 'visible') continue;
85
+ if (!el.clientWidth && !el.clientHeight) continue; // an inline box does not clip anything
86
+ const r = el.getBoundingClientRect();
87
+ const left = r.left + el.clientLeft;
88
+ const top = r.top + el.clientTop;
89
+ b.left = Math.max(b.left, left);
90
+ b.top = Math.max(b.top, top);
91
+ b.right = Math.min(b.right, left + el.clientWidth);
92
+ b.bottom = Math.min(b.bottom, top + el.clientHeight);
93
+ }
94
+ return b;
95
+ }
96
+
97
+ /**
98
+ * `true` when `rect` lies entirely outside `bounds` (scrolled out of its container / off the viewport): there is nothing to
99
+ * point at any more. A rect that is only partly clipped is still visible.
100
+ * @param {{ top: number, bottom: number, left: number, right: number }} rect
101
+ * @param {Bounds} bounds
102
+ */
103
+ export function isOutside(rect, bounds) {
104
+ return rect.bottom <= bounds.top || rect.top >= bounds.bottom || rect.right <= bounds.left || rect.left >= bounds.right;
105
+ }
106
+
107
+ /**
108
+ * Placement of a floating element centred ABOVE a (selection) rectangle, `position: fixed` with `top` / `left`: above when it
109
+ * fits between the top of the visible area and the rect, else flipped BELOW the rect, else (the rect fills the visible area)
110
+ * pinned to the top of the visible area. Clamped horizontally inside the viewport and, when it is wide enough to hold the
111
+ * element, inside the clipping container.
112
+ *
113
+ * @param {{ top: number, bottom: number, left: number, width: number }} rect the anchor
114
+ * @param {HTMLElement} el the floating element (measured)
115
+ * @param {Bounds} bounds from `clipBounds`
116
+ * @param {{ gap?: number, margin?: number }} [options]
117
+ * @returns {{ top: number, left: number, placement: 'above' | 'below' | 'inside' }}
118
+ */
119
+ export function placeAround(rect, el, bounds, { gap = 8, margin = ANCHOR_MARGIN } = {}) {
120
+ const vw = document.documentElement.clientWidth;
121
+ const w = el.offsetWidth;
122
+ const h = el.offsetHeight;
123
+ // horizontal: the container's width when it can hold the element, else the viewport's
124
+ let minX = Math.max(margin, bounds.left);
125
+ let maxX = Math.min(vw - margin, bounds.right);
126
+ if (maxX - minX < w) { minX = margin; maxX = vw - margin; }
127
+ const left = Math.max(minX, Math.min(rect.left + rect.width / 2 - w / 2, maxX - w));
128
+ // vertical
129
+ const minY = Math.max(bounds.top, margin);
130
+ const maxY = Math.min(bounds.bottom, document.documentElement.clientHeight - margin);
131
+ const above = rect.top - gap - h;
132
+ if (above >= minY) return { top: above, left, placement: 'above' };
133
+ const below = rect.bottom + gap;
134
+ if (below + h <= maxY) return { top: below, left, placement: 'below' };
135
+ return { top: Math.max(minY, Math.min(above, maxY - h)), left, placement: 'inside' };
136
+ }
@@ -1,4 +1,10 @@
1
1
  export { default as FloatingToolbar } from "./FloatingToolbar.svelte";
2
2
  export { default as SlashMenu } from "./SlashMenu.svelte";
3
3
  export { default as DragHandle } from "./DragHandle.svelte";
4
- export { SlashMenuController, DEFAULT_SLASH_COMMANDS } from "./slash-menu.svelte.js";
4
+ export { default as CommandInvite } from "./CommandInvite.svelte";
5
+ export { default as CommandChooser } from "./CommandChooser.svelte";
6
+ export { SlashMenuController } from "./slash-menu.svelte.js";
7
+ /**
8
+ * An entry of the slash menu.
9
+ */
10
+ export type SlashCommand = import("./slash-menu.svelte.js").SlashCommand;
package/dist/ui/index.js CHANGED
@@ -1,4 +1,15 @@
1
+ /**
2
+ * @module @aionbuilders/nabu/ui
3
+ *
4
+ * The optional UI components, to mount next to `<NabuEditor {engine} />`: formatting toolbar, slash menu, drag handle and the
5
+ * two command-confirmation surfaces (`CommandInvite`, `CommandChooser`). None is required: the editor works without them.
6
+ */
7
+
1
8
  export { default as FloatingToolbar } from './FloatingToolbar.svelte';
2
9
  export { default as SlashMenu } from './SlashMenu.svelte';
3
10
  export { default as DragHandle } from './DragHandle.svelte';
4
- export { SlashMenuController, DEFAULT_SLASH_COMMANDS } from './slash-menu.svelte.js';
11
+ export { default as CommandInvite } from './CommandInvite.svelte';
12
+ export { default as CommandChooser } from './CommandChooser.svelte';
13
+ export { SlashMenuController } from './slash-menu.svelte.js';
14
+
15
+ /** @typedef {import('./slash-menu.svelte.js').SlashCommand} SlashCommand An entry of the slash menu. */
@@ -1,29 +1,78 @@
1
1
  /**
2
2
  * @typedef {Object} SlashCommand
3
+ * An entry of the slash menu: a title, optional subtitle, icon and aliases to filter on, a group and order for sorting, an optional
4
+ * `when` to limit where it is offered, and the action to run. Extensions contribute theirs with `slashCommands`.
3
5
  * @property {string} title
4
6
  * @property {string} [subtitle]
5
- * @property {string} [icon]
7
+ * @property {string} [icon] A short text glyph (no emoji in the library's own entries). A theme or an integrator overrides an
8
+ * entry's icon by providing its own entry (`commands` of `SlashMenu`, or `slashCommands` of an extension).
6
9
  * @property {string[]} [aliases]
10
+ * @property {'text' | 'lists' | 'blocks' | 'media' | 'structure' | (string & {})} [group] Where the entry is listed. Known
11
+ * groups, in display order: `text`, `lists`, `blocks`, `media`, `structure`; any other string is a group of its own listed
12
+ * after them; no group = last.
13
+ * @property {number} [order] Position inside the group (ascending, default 0); ties keep the declaration order. The menu's
14
+ * order never depends on the load order of the extensions.
15
+ * @property {(engine: import('../blocks/nabu.svelte.js').Nabu, block: any) => boolean} [when]
16
+ * Where the entry applies; `block` is the block holding the caret. Without it the entry is always offered.
7
17
  * @property {(engine: import('../blocks/nabu.svelte.js').Nabu) => void} run
8
18
  */
9
- /** @type {SlashCommand[]} */
10
- export const DEFAULT_SLASH_COMMANDS: SlashCommand[];
19
+ /**
20
+ * Stable sort of slash entries: group (known order, then other groups by first appearance, then ungrouped), then `order`, then
21
+ * declaration order. Returns a new array.
22
+ * @param {SlashCommand[]} commands
23
+ * @returns {SlashCommand[]}
24
+ */
25
+ export function sortSlashCommands(commands: SlashCommand[]): SlashCommand[];
26
+ /**
27
+ * Filter slash commands by a query. Titles match by SUBSTRING (`/head` -> "Heading 1"), aliases
28
+ * by PREFIX (`/bul` -> "Bulleted list" via "bullet"); a substring alias match would make `/ul`
29
+ * also hit Divider through its "r-ul-e" alias. Case-insensitive; an empty query keeps everything.
30
+ * @param {SlashCommand[]} commands @param {string} query
31
+ * @returns {SlashCommand[]}
32
+ */
33
+ export function filterSlashCommands(commands: SlashCommand[], query: string): SlashCommand[];
34
+ /**
35
+ * The known groups of the slash menu, in display order. A group is a free string: an unknown one is listed after these (in the
36
+ * order its first entry is met), and an entry without a group comes last.
37
+ * @type {readonly string[]}
38
+ */
39
+ export const SLASH_GROUP_ORDER: readonly string[];
40
+ /**
41
+ * The state of the "/" menu for one editor: whether it is open, the query typed after the slash, the filtered and sorted entries
42
+ * and the selected one. `SlashMenu` is its default rendering; use it directly to build your own menu.
43
+ */
11
44
  export class SlashMenuController {
12
- /** @param {import('../blocks/nabu.svelte.js').Nabu} engine @param {SlashCommand[]} commands */
13
- constructor(engine: import("../blocks/nabu.svelte.js").Nabu, commands: SlashCommand[]);
45
+ /**
46
+ * @param {import('../blocks/nabu.svelte.js').Nabu} engine
47
+ * @param {SlashCommand[]} [commands] EXTRA entries of the integrator, added to the ones the loaded extensions contribute
48
+ * (`Extension#slashCommands`, collected in `engine.slashCommands`) and sorted with them. The menu has no entry of its own.
49
+ */
50
+ constructor(engine: import("../blocks/nabu.svelte.js").Nabu, commands?: SlashCommand[]);
14
51
  commands: SlashCommand[];
15
- /** @type {{ block: any, slashStart: number, cursor: number, query: string } | null} */
52
+ /**
53
+ * The pending slash trigger at the caret: its block, where the slash starts, the caret and the query typed after it; `null` when there is none.
54
+ * @type {{ block: any, slashStart: number, cursor: number, query: string } | null}
55
+ */
16
56
  match: {
17
57
  block: any;
18
58
  slashStart: number;
19
59
  cursor: number;
20
60
  query: string;
21
61
  } | null;
62
+ /** The text typed after the slash (empty when no trigger). */
22
63
  query: string;
64
+ /**
65
+ * The entries of the loaded extensions plus the integrator's extras that apply at the caret (`when`), in the documented
66
+ * order (group, `order`, declaration order).
67
+ */
68
+ available: SlashCommand[];
69
+ /** The available entries matching the query: titles by substring, aliases by prefix. */
23
70
  filteredItems: SlashCommand[];
71
+ /** Whether the menu should be shown: a trigger at the caret, at least one match, not dismissed, not read-only. */
24
72
  open: boolean;
73
+ /** Index of the highlighted entry in `filteredItems`. */
25
74
  selectedIndex: number;
26
- /** @param {number} delta */
75
+ /** Move the highlight by `delta` entries, wrapping around. @param {number} delta */
27
76
  moveSelection(delta: number): void;
28
77
  /** Run the command at the given index (default: the selected one). @param {number} [index] */
29
78
  select(index?: number): Promise<void>;
@@ -31,10 +80,33 @@ export class SlashMenuController {
31
80
  close(): void;
32
81
  #private;
33
82
  }
83
+ /**
84
+ * An entry of the slash menu: a title, optional subtitle, icon and aliases to filter on, a group and order for sorting, an optional
85
+ * `when` to limit where it is offered, and the action to run. Extensions contribute theirs with `slashCommands`.
86
+ */
34
87
  export type SlashCommand = {
35
88
  title: string;
36
89
  subtitle?: string | undefined;
90
+ /**
91
+ * A short text glyph (no emoji in the library's own entries). A theme or an integrator overrides an
92
+ * entry's icon by providing its own entry (`commands` of `SlashMenu`, or `slashCommands` of an extension).
93
+ */
37
94
  icon?: string | undefined;
38
95
  aliases?: string[] | undefined;
96
+ /**
97
+ * Where the entry is listed. Known
98
+ * groups, in display order: `text`, `lists`, `blocks`, `media`, `structure`; any other string is a group of its own listed
99
+ * after them; no group = last.
100
+ */
101
+ group?: "text" | "lists" | "blocks" | "media" | "structure" | (string & {}) | undefined;
102
+ /**
103
+ * Position inside the group (ascending, default 0); ties keep the declaration order. The menu's
104
+ * order never depends on the load order of the extensions.
105
+ */
106
+ order?: number | undefined;
107
+ /**
108
+ * Where the entry applies; `block` is the block holding the caret. Without it the entry is always offered.
109
+ */
110
+ when?: ((engine: import("../blocks/nabu.svelte.js").Nabu, block: any) => boolean) | undefined;
39
111
  run: (engine: import("../blocks/nabu.svelte.js").Nabu) => void;
40
112
  };