@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
@@ -0,0 +1,673 @@
1
+ /**
2
+ * Confirmation strategies of commands (ADR 017, lot 2): `hold`, `invite`, `choose`.
3
+ *
4
+ * The registry (`commands.js`) resolves the keys; when the winning command declares a `confirm` (or when several commands tie),
5
+ * it hands the key press to this controller, which owns the whole life of the confirmation:
6
+ *
7
+ * - `nabu.pendingCommand` (reactive) describes what is waiting for the user: see {@link PendingCommand};
8
+ * - while something is pending, EVERY key press goes through {@link CommandConfirmation#handleKeydown} first;
9
+ * - the document listeners (key release, selection, click, focus) are attached by {@link CommandConfirmation#start}, which the
10
+ * editor component calls through `nabu.systems`;
11
+ * - a polite live region (`nabu.commandAnnouncement`, rendered by `Nabu.svelte`) announces prompts and outcomes.
12
+ *
13
+ * The controller names no block type. The look of a confirmation belongs to the integrator: `hold` is drawn by its TARGET
14
+ * (`Nabu.svelte` marks the target element with `data-command-target` and `--nb-command-progress`; a block may read
15
+ * `nabu.pendingCommandOn(block)` and draw its own), `invite` and `choose` by the `CommandInvite` / `CommandChooser` components.
16
+ *
17
+ * @import { Nabu } from '../blocks/nabu.svelte.js'
18
+ * @import { CommandEntry, CommandContext } from './commands.js'
19
+ */
20
+
21
+ import { eventChord, chordId, formatChord, parseChord } from './keys.js';
22
+
23
+ /** Default duration of a `hold`, in milliseconds. */
24
+ export const DEFAULT_HOLD_MS = 700;
25
+ /** Default time an `invite` waits for its second press, in milliseconds. */
26
+ export const DEFAULT_INVITE_MS = 5000;
27
+
28
+ /**
29
+ * Time source of the controller (injectable, so that tests drive a fake clock).
30
+ * @typedef {Object} ConfirmClock
31
+ * @property {() => number} now monotonic milliseconds
32
+ * @property {(fn: () => void, ms: number) => () => void} timeout run `fn` once after `ms`; returns the canceller
33
+ * @property {(fn: () => void) => () => void} frame run `fn` before the next paint (animation frame); returns the canceller
34
+ */
35
+
36
+ /** @type {ConfirmClock} */
37
+ export const REAL_CLOCK = {
38
+ now: () => (typeof performance !== 'undefined' ? performance.now() : Date.now()),
39
+ timeout: (fn, ms) => { const id = setTimeout(fn, ms); return () => clearTimeout(id); },
40
+ frame: (fn) => {
41
+ if (typeof requestAnimationFrame === 'function') { const id = requestAnimationFrame(() => fn()); return () => cancelAnimationFrame(id); }
42
+ const id = setTimeout(fn, 16);
43
+ return () => clearTimeout(id);
44
+ },
45
+ };
46
+
47
+ /**
48
+ * What is waiting for the user, as `nabu.pendingCommand`. The reference changes when a confirmation starts or ends; `progress`
49
+ * and `selectedIndex` are reactive fields of it.
50
+ *
51
+ * @typedef {Object} PendingOption
52
+ * @property {string} id the command id (a tie) or the variant id (explicit `choose`)
53
+ * @property {string} label
54
+ * @property {string} display shortcut (a tie) or hint (explicit `choose`) to show next to the label; may be empty
55
+ * @property {string} [group] explicit `choose` only: the title of the group the option belongs to. Consecutive options with the
56
+ * same `group` are shown under one small header; options without one stay ungrouped.
57
+ * @property {string} [detail] explicit `choose` only: a short muted text shown right-aligned in the option (a number, a hint)
58
+ */
59
+ export class PendingCommand {
60
+ /**
61
+ * @param {Object} init
62
+ * @param {string} init.id
63
+ * @param {'hold' | 'invite' | 'choose'} init.strategy
64
+ * @param {string} init.label
65
+ * @param {string} init.display
66
+ * @param {string} init.message
67
+ * @param {any} [init.target]
68
+ * @param {PendingOption[]} [init.options]
69
+ * @param {string} [init.footer]
70
+ */
71
+ constructor({ id, strategy, label, display, message, target, options, footer }) {
72
+ /** command id (`choose:<chord>` for a tie) */
73
+ this.id = id;
74
+ this.strategy = strategy;
75
+ /** label of the command (resolved with the context of the key press) */
76
+ this.label = label;
77
+ /** the shortcut that started it, formatted for the platform (`'Ctrl+Shift+Backspace'`, `'⇧⌘⌫'`) */
78
+ this.display = display;
79
+ /** the prompt, i18n-resolved: the text of the live region and of the default hint */
80
+ this.message = message;
81
+ /** what the confirmation is about (`hold`: `confirm.target(ctx)`, usually a block); `undefined` when none */
82
+ this.target = target;
83
+ /** `choose` only */
84
+ this.options = options;
85
+ /** `choose` only: a short hint shown under the options (`confirm.footer`); empty when none */
86
+ this.footer = footer ?? '';
87
+ /** `hold`: 0 → 1 over `holdMs` */
88
+ this.progress = $state(0);
89
+ /** `choose`: the highlighted option */
90
+ this.selectedIndex = $state(0);
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Texts of the prompts and the outcomes. Each value is a string or a function of the given parameters; override them for all
96
+ * commands with the `commandConfirm.messages` init option, or per command with `confirm.messages` (partial objects).
97
+ * @typedef {Object} ConfirmMessages
98
+ * @property {string | ((p: { keys: string, label: string }) => string)} [hold] prompt of a hold
99
+ * @property {string | ((p: { keys: string, label: string }) => string)} [invite] prompt of an invite
100
+ * @property {string | ((p: { keys: string, label: string, options: PendingOption[] }) => string)} [choose] prompt of a chooser
101
+ * @property {string | ((p: { option: PendingOption, index: number, count: number }) => string)} [option] the highlighted option
102
+ * @property {string | ((p: { label: string }) => string)} [done] after the command ran
103
+ * @property {string | ((p: { label: string }) => string)} [cancelled] after a release / Escape / timeout
104
+ */
105
+
106
+ /** @type {Required<ConfirmMessages>} */
107
+ export const DEFAULT_MESSAGES = {
108
+ hold: ({ keys, label }) => `Hold ${keys} to confirm: ${label}`,
109
+ invite: ({ keys, label }) => `Press ${keys} again to confirm: ${label}. Escape cancels.`,
110
+ choose: ({ options }) => `${options.length} actions apply here. Arrow keys and Enter, or a number, to choose. Escape cancels.`,
111
+ option: ({ option, index, count }) => `${index + 1} of ${count}: ${option.label}`,
112
+ done: ({ label }) => `${label}: done`,
113
+ cancelled: () => 'Cancelled',
114
+ };
115
+
116
+ /**
117
+ * @typedef {Object} CommandConfirmOptions
118
+ * @property {number} [holdMs] default duration of a `hold` (700)
119
+ * @property {number} [inviteMs] default time an `invite` waits (5000)
120
+ * @property {ConfirmMessages} [messages] texts, see {@link ConfirmMessages}
121
+ * @property {ConfirmClock} [clock] time source (tests)
122
+ */
123
+
124
+ /** Cancellation reasons that are worth announcing: the user asked for it, or the invite expired. */
125
+ const ANNOUNCED_CANCELS = new Set(['release', 'escape', 'timeout']);
126
+
127
+ /** Keys that are only modifiers: they never cancel nor confirm anything. */
128
+ const isModifierKey = (/** @type {string} */ key) => key === 'Shift' || key === 'Control' || key === 'Alt' || key === 'Meta' || key === 'AltGraph' || key === 'OS';
129
+
130
+ /**
131
+ * The DOM element standing for a confirmation target: a block (its `element`) or an element. `null` when it has none (yet).
132
+ * @param {any} target
133
+ * @returns {HTMLElement | null}
134
+ */
135
+ export function commandTargetElement(target) {
136
+ if (!target || typeof target !== 'object') return null;
137
+ const el = typeof Node !== 'undefined' && target instanceof Node ? target : target.element;
138
+ return el && typeof el === 'object' && el.nodeType === 1 && el.isConnected ? /** @type {HTMLElement} */ (el) : null;
139
+ }
140
+
141
+ /**
142
+ * @typedef {Object} Session
143
+ * @property {PendingCommand} pending
144
+ * @property {'hold' | 'invite' | 'choose'} strategy
145
+ * @property {CommandEntry | null} entry the command (a tie / `choose` with variants: the explicit command or `null`)
146
+ * @property {CommandContext} ctx context of the key press that started it
147
+ * @property {string} chord canonical id of the chord that started it
148
+ * @property {ReturnType<typeof eventChord>} chordInfo
149
+ * @property {string} code physical key of the press (`event.code`)
150
+ * @property {boolean} [waiting] `hold` opened from code: nobody holds the key yet; the count starts at the user's press
151
+ * @property {number} startedAt
152
+ * @property {number} ms `hold`: duration; `invite`: timeout
153
+ * @property {(() => void) | null} stopTimer
154
+ * @property {Array<{ id: string, label: string, display: string, group?: string, detail?: string, run: () => void }>} [choices] `choose`
155
+ * @property {{ selection: [Node | null, number, Node | null, number] } | null} dom selection when it started
156
+ */
157
+
158
+ export class CommandConfirmation {
159
+ /** @type {Nabu} */
160
+ #nabu;
161
+ /** @type {ConfirmClock} */
162
+ #clock;
163
+ #holdMs;
164
+ #inviteMs;
165
+ /** @type {ConfirmMessages} */
166
+ #messages;
167
+ /** @type {PendingCommand | null} */
168
+ #pending = $state.raw(null);
169
+ /** @type {Session | null} */
170
+ #session = null;
171
+ /** The chord of a hold that completed: its key is still down, so its repeats are swallowed until it is released. @type {{ chord: string, chordInfo: ReturnType<typeof eventChord>, code: string } | null} */
172
+ #spent = null;
173
+ #announcement = $state('');
174
+ #flip = false;
175
+ /** @type {(() => void) | null} */
176
+ #detach = null;
177
+
178
+ /** @param {Nabu} nabu @param {CommandConfirmOptions} [options] */
179
+ constructor(nabu, { holdMs, inviteMs, messages, clock } = {}) {
180
+ this.#nabu = nabu;
181
+ this.#clock = clock ?? REAL_CLOCK;
182
+ this.#holdMs = Number.isFinite(holdMs) && /** @type {number} */ (holdMs) > 0 ? /** @type {number} */ (holdMs) : DEFAULT_HOLD_MS;
183
+ this.#inviteMs = Number.isFinite(inviteMs) && /** @type {number} */ (inviteMs) > 0 ? /** @type {number} */ (inviteMs) : DEFAULT_INVITE_MS;
184
+ this.#messages = messages && typeof messages === 'object' ? messages : {};
185
+ }
186
+
187
+ /** What is waiting for the user (`nabu.pendingCommand`), reactive; `null` when nothing is. @returns {PendingCommand | null} */
188
+ get pending() { return this.#pending; }
189
+
190
+ /** Whether the keys must go through {@link CommandConfirmation#handleKeydown}: something is pending, or the key of a completed hold is still down. */
191
+ get busy() { return this.#session !== null || this.#spent !== null; }
192
+
193
+ /** The text of the polite live region: the last prompt or outcome (reactive). */
194
+ get announcement() { return this.#announcement; }
195
+
196
+ /** The pending confirmation when it is about `target` (reactive), else `null`. @param {any} target @returns {PendingCommand | null} */
197
+ pendingOn(target) {
198
+ const pending = this.#pending;
199
+ return pending && target !== undefined && target !== null && pending.target === target ? pending : null;
200
+ }
201
+
202
+ // ── texts ───────────────────────────────────────────────────────────────
203
+
204
+ /**
205
+ * @template {keyof ConfirmMessages} K
206
+ * @param {K} key @param {any} params @param {ConfirmMessages | undefined} [local]
207
+ * @returns {string}
208
+ */
209
+ #text(key, params, local) {
210
+ const value = local?.[key] ?? this.#messages[key] ?? DEFAULT_MESSAGES[key];
211
+ try { return String(typeof value === 'function' ? /** @type {Function} */ (value)(params) : value); }
212
+ catch (error) { this.#nabu.warn(`commands: message "${key}" failed: ${error}`); return String(typeof DEFAULT_MESSAGES[key] === 'function' ? /** @type {Function} */ (DEFAULT_MESSAGES[key])(params) : DEFAULT_MESSAGES[key]); }
213
+ }
214
+
215
+ /** Announce `text` in the live region (a change is needed for a screen reader to speak: alternate an invisible suffix). @param {string} text */
216
+ #announce(text) {
217
+ this.#flip = !this.#flip;
218
+ this.#announcement = text + (this.#flip ? '​' : '');
219
+ }
220
+
221
+ // ── starting ────────────────────────────────────────────────────────────
222
+
223
+ /**
224
+ * A key press selected `entry`, which has a `confirm` strategy. Returns whether the key was consumed (it always is, unless
225
+ * the strategy cannot start). The registry has already checked `when`.
226
+ * @param {CommandEntry} entry
227
+ * @param {CommandContext} ctx
228
+ * @param {KeyboardEvent} event
229
+ * @returns {boolean}
230
+ */
231
+ begin(entry, ctx, event) {
232
+ const confirm = /** @type {any} */ (entry.def.confirm);
233
+ const info = eventChord(event);
234
+ if (!info) return false;
235
+ const chord = chordId(info);
236
+ // A key held before the context was entered (or kept down after a hold completed) never starts nor confirms anything:
237
+ // its repeats are swallowed here, so a user who erases text with Backspace held stops at the boundary.
238
+ if (event.repeat) { event.preventDefault(); return true; }
239
+ this.#spent = null;
240
+ this.cancel('restart');
241
+
242
+ if (confirm.strategy === 'choose') return this.#beginVariants(entry, ctx, event, info, chord);
243
+
244
+ return this.#beginSingle(entry, ctx, event, info, chord);
245
+ }
246
+
247
+ /**
248
+ * `hold` / `invite` of a command. `event` is the key press that starts it, or `null` when {@link CommandConfirmation#offer}
249
+ * opens it from code: nothing is held yet, so a `hold` waits for the user to press its key (the count starts then), and an
250
+ * `invite` waits for its second press; both give up after the `invite` timeout.
251
+ * @param {CommandEntry} entry @param {CommandContext} ctx @param {KeyboardEvent | null} event
252
+ * @param {NonNullable<ReturnType<typeof eventChord>>} info @param {string} chord
253
+ */
254
+ #beginSingle(entry, ctx, event, info, chord) {
255
+ const confirm = /** @type {any} */ (entry.def.confirm);
256
+ const display = formatChord(info, { platform: this.#nabu.commands.platform });
257
+ const label = this.#labelOf(entry, ctx);
258
+ const hold = confirm.strategy === 'hold';
259
+ const ms = this.#duration(hold ? confirm.holdMs : confirm.inviteMs, hold ? this.#holdMs : this.#inviteMs);
260
+ let target;
261
+ if (typeof confirm.target === 'function') {
262
+ try { target = confirm.target(ctx) ?? undefined; } catch (error) { this.#nabu.warn(`commands: confirm.target of "${entry.id}" failed: ${error}`); }
263
+ }
264
+ const message = this.#text(hold ? 'hold' : 'invite', { keys: display, label }, confirm.messages);
265
+ const pending = new PendingCommand({ id: entry.id, strategy: hold ? 'hold' : 'invite', label, display, message, target });
266
+ const session = this.#open(pending, entry, ctx, chord, info, event);
267
+ session.ms = ms;
268
+ this.#announce(message);
269
+ if (!event) {
270
+ // From code: no key is down. A hold counts from the user's press (see `handleKeydown`); until then, and for an invite, a timeout cancels.
271
+ session.waiting = hold;
272
+ session.stopTimer = this.#clock.timeout(() => this.cancel('timeout'), hold ? this.#inviteMs : ms);
273
+ } else if (hold) this.#tick();
274
+ else session.stopTimer = this.#clock.timeout(() => this.cancel('timeout'), ms);
275
+ event?.preventDefault();
276
+ return true;
277
+ }
278
+
279
+ /**
280
+ * Several commands apply to the key: let the user pick (§3.4c).
281
+ * @param {CommandEntry[]} ties
282
+ * @param {CommandContext} ctx
283
+ * @param {KeyboardEvent} event
284
+ * @returns {boolean}
285
+ */
286
+ beginTie(ties, ctx, event) {
287
+ const info = eventChord(event);
288
+ if (!info) return false;
289
+ if (event.repeat) { event.preventDefault(); return true; }
290
+ this.#spent = null;
291
+ this.cancel('restart');
292
+ const chord = chordId(info);
293
+ const display = formatChord(info, { platform: this.#nabu.commands.platform });
294
+ const choices = ties.map((entry) => ({
295
+ id: entry.id,
296
+ label: this.#labelOf(entry, ctx),
297
+ display,
298
+ run: () => this.#runEntry(entry, ctx, event),
299
+ }));
300
+ return this.#openChooser(`choose:${chord}`, choices, ctx, event, info, chord, display, undefined, undefined);
301
+ }
302
+
303
+ /**
304
+ * Open the confirmation of a command WITHOUT a key press (a typed trigger, a menu, a button, an input rule): the same
305
+ * prompt a key would open (`nabu.pendingCommand`, the `CommandInvite` / `CommandChooser` components, the keyboard handling,
306
+ * the cancellations). The command's `when` is checked. Prefer the public `nabu.commands.offer(id)`, which also runs a command
307
+ * that has no confirmation.
308
+ *
309
+ * - `choose`: the options come from `confirm.options(ctx)`, the choice runs `run(nabu, ctx, option)`;
310
+ * - `invite`: asks to press the command's first key again (`invite` timeout);
311
+ * - `hold`: asks to hold the command's first key; the count starts at the user's press and the confirmation lapses after the
312
+ * `invite` timeout when no key comes.
313
+ *
314
+ * `hold` and `invite` need a key to confirm with: a command with no key (disabled by the `keymap`) opens nothing.
315
+ * Returns false (nothing opens) when the command does not exist, has no confirmation, does not apply, or offers no option.
316
+ * @param {string} id command id
317
+ * @param {CommandContext} [context] default: the current context
318
+ * @returns {boolean}
319
+ */
320
+ offer(id, context) {
321
+ const entry = this.#nabu.commands.entries.get(id);
322
+ const strategy = /** @type {any} */ (entry?.def.confirm)?.strategy;
323
+ if (!entry || (strategy !== 'choose' && strategy !== 'hold' && strategy !== 'invite')) return false;
324
+ const ctx = context ?? this.#nabu.commands.context(null);
325
+ if (typeof entry.def.when === 'function') {
326
+ let ok = false;
327
+ try { ok = !!entry.def.when(ctx); } catch (error) { this.#nabu.warn(`commands: when() of "${id}" failed: ${error}`); }
328
+ if (!ok) return false;
329
+ }
330
+ if (strategy === 'choose') {
331
+ this.#spent = null;
332
+ this.cancel('restart');
333
+ return this.#beginVariants(entry, ctx, null, null, '');
334
+ }
335
+ const platform = this.#nabu.commands.platform;
336
+ /** @type {ReturnType<typeof eventChord>} */
337
+ let info = null;
338
+ for (const key of entry.keys) { info = parseChord(key, { platform }); if (info) break; }
339
+ if (!info) { this.#nabu.warn(`commands: "${id}" has no key to confirm with: ${strategy} not opened`); return false; }
340
+ this.#spent = null;
341
+ this.cancel('restart');
342
+ return this.#beginSingle(entry, ctx, null, info, chordId(info));
343
+ }
344
+
345
+ /** `confirm: { strategy: 'choose', options(ctx) }`: the command offers variants; `run(nabu, ctx, option)` receives the chosen one. `event` / `info` are null when {@link CommandConfirmation#offer} opens it. */
346
+ #beginVariants(/** @type {CommandEntry} */ entry, /** @type {CommandContext} */ ctx, /** @type {KeyboardEvent | null} */ event, /** @type {any} */ info, /** @type {string} */ chord) {
347
+ const confirm = /** @type {any} */ (entry.def.confirm);
348
+ let list;
349
+ try { list = typeof confirm.options === 'function' ? confirm.options(ctx) : confirm.options; }
350
+ catch (error) { this.#nabu.warn(`commands: confirm.options of "${entry.id}" failed: ${error}`); return false; }
351
+ if (!Array.isArray(list) || !list.length) return false;
352
+ const display = info ? formatChord(info, { platform: this.#nabu.commands.platform }) : '';
353
+ const choices = list.map((option, i) => ({
354
+ id: String(option?.id ?? i),
355
+ label: String(option?.label ?? option?.id ?? i),
356
+ display: typeof option?.display === 'string' ? option.display : '',
357
+ group: typeof option?.group === 'string' && option.group ? option.group : undefined,
358
+ detail: typeof option?.detail === 'string' && option.detail ? option.detail : undefined,
359
+ run: () => this.#runEntry(entry, ctx, event, option),
360
+ }));
361
+ let footer = '';
362
+ try { footer = String(typeof confirm.footer === 'function' ? confirm.footer(ctx) ?? '' : confirm.footer ?? ''); }
363
+ catch (error) { this.#nabu.warn(`commands: confirm.footer of "${entry.id}" failed: ${error}`); }
364
+ return this.#openChooser(entry.id, choices, ctx, event, info, chord, display, entry, this.#labelOf(entry, ctx), footer);
365
+ }
366
+
367
+ #openChooser(/** @type {string} */ id, /** @type {Session['choices']} */ choices, /** @type {CommandContext} */ ctx, /** @type {KeyboardEvent | null} */ event, /** @type {any} */ info, /** @type {string} */ chord, /** @type {string} */ display, /** @type {CommandEntry | undefined} */ entry, /** @type {string | undefined} */ label, /** @type {string} */ footer = '') {
368
+ const options = /** @type {NonNullable<Session['choices']>} */ (choices).map(({ id, label, display, group, detail }) => ({ id, label, display, ...(group ? { group } : {}), ...(detail ? { detail } : {}) }));
369
+ const local = /** @type {any} */ (entry?.def.confirm)?.messages;
370
+ const message = this.#text('choose', { keys: display, label: label ?? '', options }, local);
371
+ const pending = new PendingCommand({ id, strategy: 'choose', label: label ?? message, display, message, options, footer });
372
+ const session = this.#open(pending, entry ?? null, ctx, chord, info, event);
373
+ session.choices = choices;
374
+ session.ms = this.#inviteMs;
375
+ session.stopTimer = null; // a chooser has no timeout: it is a safety net the user is looking at
376
+ this.#announce(`${message} ${this.#text('option', { option: options[0], index: 0, count: options.length }, local)}`);
377
+ event?.preventDefault();
378
+ return true;
379
+ }
380
+
381
+ /** @returns {Session} */
382
+ #open(/** @type {PendingCommand} */ pending, /** @type {CommandEntry | null} */ entry, /** @type {CommandContext} */ ctx, /** @type {string} */ chord, /** @type {any} */ info, /** @type {KeyboardEvent | null} */ event) {
383
+ /** @type {Session} */
384
+ const session = {
385
+ pending, strategy: pending.strategy, entry, ctx, chord, chordInfo: info, code: event?.code ?? '',
386
+ startedAt: this.#clock.now(), ms: 0, stopTimer: null, dom: this.#domSelection(),
387
+ };
388
+ this.#session = session;
389
+ this.#pending = pending;
390
+ return session;
391
+ }
392
+
393
+ #labelOf(/** @type {CommandEntry} */ entry, /** @type {CommandContext} */ ctx) {
394
+ const label = entry.def.label;
395
+ if (typeof label === 'string') return label;
396
+ if (typeof label === 'function') { try { return String(label(ctx)); } catch (error) { this.#nabu.warn(`commands: label of "${entry.id}" failed: ${error}`); } }
397
+ return entry.id;
398
+ }
399
+
400
+ /** @param {unknown} value @param {number} fallback */
401
+ #duration(value, fallback) { return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback; }
402
+
403
+ // ── hold ────────────────────────────────────────────────────────────────
404
+
405
+ #tick = () => {
406
+ const session = this.#session;
407
+ if (!session || session.strategy !== 'hold') return;
408
+ session.stopTimer = null;
409
+ const progress = Math.min(1, Math.max(0, (this.#clock.now() - session.startedAt) / session.ms));
410
+ session.pending.progress = progress;
411
+ if (progress >= 1) this.#completeHold(session);
412
+ else session.stopTimer = this.#clock.frame(this.#tick);
413
+ };
414
+
415
+ /** @param {Session} session */
416
+ #completeHold(session) {
417
+ // The key is still down: its repeats must not do anything (typing, a second run) until it is released.
418
+ this.#spent = { chord: session.chord, chordInfo: session.chordInfo, code: session.code };
419
+ this.#end();
420
+ this.#runConfirmed(session);
421
+ }
422
+
423
+ // ── running ─────────────────────────────────────────────────────────────
424
+
425
+ /** Re-check that the command still applies, then run it and announce the outcome. @param {Session} session @param {KeyboardEvent | null} [event] */
426
+ #runConfirmed(session, event = null) {
427
+ const entry = session.entry;
428
+ if (!entry) return;
429
+ const ctx = this.#nabu.commands.context(event ?? session.ctx.event);
430
+ const when = entry.def.when;
431
+ if (typeof when === 'function') {
432
+ let ok = false;
433
+ try { ok = !!when(ctx); } catch (error) { this.#nabu.warn(`commands: when() of "${entry.id}" failed: ${error}`); }
434
+ if (!ok) return;
435
+ }
436
+ this.#runEntry(entry, ctx, event ?? session.ctx.event);
437
+ }
438
+
439
+ /** @param {CommandEntry} entry @param {CommandContext} ctx @param {KeyboardEvent | null} event @param {any} [data] */
440
+ #runEntry(entry, ctx, event, data) {
441
+ const label = this.#labelOf(entry, ctx);
442
+ const local = /** @type {any} */ (entry.def.confirm)?.messages;
443
+ try {
444
+ const result = entry.def.run(this.#nabu, ctx, data);
445
+ if (result && typeof result.then === 'function') result.then(undefined, (/** @type {unknown} */ error) => console.error(`[Nabu] command "${entry.id}" failed`, error));
446
+ } catch (error) {
447
+ console.error(`[Nabu] command "${entry.id}" failed`, error);
448
+ return;
449
+ }
450
+ this.#announce(this.#text('done', { label }, local));
451
+ }
452
+
453
+ // ── keys ────────────────────────────────────────────────────────────────
454
+
455
+ /**
456
+ * Every key press goes through here before the command resolution, while a confirmation is pending (or the key of a completed
457
+ * hold is still down). Returns `true` when the key is consumed (`preventDefault` already called); `false` lets the registry go
458
+ * on, which is what an unrelated key must get after it cancelled the confirmation ("the key acts normally").
459
+ * @param {KeyboardEvent} event
460
+ * @returns {boolean}
461
+ */
462
+ handleKeydown(event) {
463
+ const info = eventChord(event);
464
+ if (!info || isModifierKey(event.key)) return false; // a lone modifier changes nothing
465
+ const chord = chordId(info);
466
+
467
+ const spent = this.#spent;
468
+ if (spent && !this.#session) {
469
+ if (spent.chord === chord && event.repeat) { event.preventDefault(); return true; }
470
+ if (spent.chord === chord) this.#spent = null; // a fresh press of the same chord: the release was missed
471
+ }
472
+
473
+ const session = this.#session;
474
+ if (!session) return false;
475
+ const same = chord === session.chord;
476
+
477
+ if (session.strategy === 'hold') {
478
+ if (same) {
479
+ event.preventDefault(); // the held key repeating (or pressed twice): nothing to do…
480
+ if (session.waiting && !event.repeat) { // …except for a hold opened from code, which counts from the user's fresh press
481
+ session.waiting = false;
482
+ session.code = event.code ?? '';
483
+ session.stopTimer?.();
484
+ session.startedAt = this.#clock.now();
485
+ this.#tick();
486
+ }
487
+ return true;
488
+ }
489
+ this.cancel('key');
490
+ return false;
491
+ }
492
+
493
+ if (session.strategy === 'invite') {
494
+ if (same) {
495
+ event.preventDefault();
496
+ if (event.repeat) return true; // a repeat never confirms
497
+ this.#end();
498
+ this.#runConfirmed(session, event);
499
+ return true;
500
+ }
501
+ if (event.key === 'Escape') { event.preventDefault(); this.cancel('escape'); return true; }
502
+ this.cancel('key');
503
+ return false;
504
+ }
505
+
506
+ // choose
507
+ const choices = /** @type {NonNullable<Session['choices']>} */ (session.choices);
508
+ const plain = !event.ctrlKey && !event.metaKey && !event.altKey;
509
+ if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
510
+ event.preventDefault();
511
+ this.#moveSelection(event.key === 'ArrowDown' ? 1 : -1);
512
+ return true;
513
+ }
514
+ if (event.key === 'Enter' && plain && event.repeat) { event.preventDefault(); return true; } // a repeat never confirms (a held Enter that opened the chooser)
515
+ if (event.key === 'Enter' && plain) { event.preventDefault(); this.choose(session.pending.selectedIndex); return true; }
516
+ if (event.key === 'Escape') { event.preventDefault(); this.cancel('escape'); return true; }
517
+ if (plain && /^[1-9]$/.test(event.key) && Number(event.key) <= choices.length) { event.preventDefault(); this.choose(Number(event.key) - 1); return true; }
518
+ this.cancel('key');
519
+ return false;
520
+ }
521
+
522
+ /** @param {number} delta */
523
+ #moveSelection(delta) {
524
+ const session = this.#session;
525
+ if (!session?.choices) return;
526
+ const count = session.choices.length;
527
+ const index = (session.pending.selectedIndex + delta + count) % count;
528
+ session.pending.selectedIndex = index;
529
+ const local = /** @type {any} */ (session.entry?.def.confirm)?.messages;
530
+ const option = /** @type {PendingOption} */ (session.pending.options?.[index]);
531
+ this.#announce(this.#text('option', { option, index, count }, local));
532
+ }
533
+
534
+ /**
535
+ * Move the highlight of a pending `choose` (the chooser component calls it on hover).
536
+ * @param {number} index
537
+ */
538
+ highlight(index) {
539
+ const session = this.#session;
540
+ if (session?.strategy !== 'choose' || !session.choices || index < 0 || index >= session.choices.length || index === session.pending.selectedIndex) return;
541
+ this.#moveSelection(index - session.pending.selectedIndex);
542
+ }
543
+
544
+ /**
545
+ * Run option `index` of a pending `choose` (Enter, a digit, a click).
546
+ * @param {number} index
547
+ * @returns {boolean} whether something ran
548
+ */
549
+ choose(index) {
550
+ const session = this.#session;
551
+ if (session?.strategy !== 'choose' || !session.choices?.[index]) return false;
552
+ const choice = session.choices[index];
553
+ this.#end();
554
+ choice.run();
555
+ return true;
556
+ }
557
+
558
+ // ── ending ──────────────────────────────────────────────────────────────
559
+
560
+ /** Clear the session without running anything. */
561
+ #end() {
562
+ const session = this.#session;
563
+ session?.stopTimer?.();
564
+ this.#session = null;
565
+ this.#pending = null;
566
+ }
567
+
568
+ /**
569
+ * Cancel what is pending (`nabu.cancelPendingCommand()`): nothing runs, no undo step exists. No-op when nothing is pending.
570
+ * @param {string} [reason] `'api'` (default), `'release'`, `'escape'`, `'key'`, `'selection'`, `'click'`, `'blur'`, `'timeout'`
571
+ */
572
+ cancel(reason = 'api') {
573
+ const session = this.#session;
574
+ if (!session) return;
575
+ this.#end();
576
+ if (ANNOUNCED_CANCELS.has(reason)) {
577
+ const local = /** @type {any} */ (session.entry?.def.confirm)?.messages;
578
+ this.#announce(this.#text('cancelled', { label: session.pending.label }, local));
579
+ }
580
+ }
581
+
582
+ // ── document listeners ──────────────────────────────────────────────────
583
+
584
+ /** @returns {{ selection: [Node | null, number, Node | null, number] } | null} */
585
+ #domSelection() {
586
+ const sel = typeof window !== 'undefined' && typeof window.getSelection === 'function' ? window.getSelection() : null;
587
+ return sel ? { selection: [sel.anchorNode, sel.anchorOffset, sel.focusNode, sel.focusOffset] } : null;
588
+ }
589
+
590
+ /**
591
+ * The key of the chord went up: a hold that is not finished is cancelled; the key of a completed hold is free again.
592
+ * Releasing a modifier of the chord counts like releasing its key.
593
+ * @param {KeyboardEvent} event
594
+ */
595
+ onKeyup(event) {
596
+ const releases = (/** @type {NonNullable<ReturnType<typeof eventChord>>} */ info, /** @type {string} */ code) => {
597
+ if (event.key === 'Control') return info.ctrl;
598
+ if (event.key === 'Alt') return info.alt;
599
+ if (event.key === 'Shift') return info.shift;
600
+ if (event.key === 'Meta') return info.meta;
601
+ if (code && event.code) return event.code === code;
602
+ return eventChord({ key: event.key })?.key === info.key;
603
+ };
604
+ const spent = this.#spent;
605
+ if (spent?.chordInfo && releases(spent.chordInfo, spent.code)) this.#spent = null;
606
+ const session = this.#session;
607
+ if (session?.strategy === 'hold' && !session.waiting && session.chordInfo && releases(session.chordInfo, session.code)) this.cancel('release');
608
+ }
609
+
610
+ /** The DOM selection moved away from where the confirmation started. */
611
+ onSelectionChange() {
612
+ const session = this.#session;
613
+ if (!session?.dom) return;
614
+ const now = this.#domSelection();
615
+ if (!now) return;
616
+ const [a, ao, f, fo] = session.dom.selection;
617
+ const [na, nao, nf, nfo] = now.selection;
618
+ if (a !== na || ao !== nao || f !== nf || fo !== nfo) this.cancel('selection');
619
+ }
620
+
621
+ /** A click outside the confirmation's own UI cancels it. @param {Event} event */
622
+ onPointerDown(event) {
623
+ if (!this.#session) return;
624
+ const target = /** @type {any} */ (event.target);
625
+ if (target?.closest?.('[data-nabu-ui]')) return;
626
+ this.cancel('click');
627
+ }
628
+
629
+ /** Focus left the editor (window blur, tab switch, a click elsewhere): nothing can be confirmed any more. */
630
+ onBlur() {
631
+ this.#spent = null; // the release will not be seen
632
+ this.cancel('blur');
633
+ }
634
+
635
+ /** Attach the document listeners (the editor component calls it through `nabu.systems`). Idempotent. */
636
+ start() {
637
+ if (this.#detach || typeof document === 'undefined') return;
638
+ const keyup = (/** @type {KeyboardEvent} */ e) => this.onKeyup(e);
639
+ const selectionchange = () => this.onSelectionChange();
640
+ const pointerdown = (/** @type {Event} */ e) => this.onPointerDown(e);
641
+ const blur = () => this.onBlur();
642
+ const focusout = (/** @type {FocusEvent} */ e) => {
643
+ const next = /** @type {any} */ (e.relatedTarget);
644
+ const selection = this.#nabu.selection;
645
+ // Focus leaving ANOTHER editor is none of my business; focus moving to my own root or UI (or to a UI island on the
646
+ // page, outside every editor) is not a blur. Moving to another editor IS one.
647
+ if (selection.kindOf(e.target instanceof Node ? e.target : null) === 'foreign') return;
648
+ const where = next instanceof Node ? selection.kindOf(next) : 'none';
649
+ if (where === 'mine' || (where === 'none' && next?.closest?.('[data-nabu-ui]'))) return;
650
+ this.onBlur();
651
+ };
652
+ document.addEventListener('keyup', keyup, true);
653
+ document.addEventListener('selectionchange', selectionchange);
654
+ document.addEventListener('mousedown', pointerdown, true);
655
+ document.addEventListener('focusout', focusout, true);
656
+ window.addEventListener('blur', blur);
657
+ this.#detach = () => {
658
+ document.removeEventListener('keyup', keyup, true);
659
+ document.removeEventListener('selectionchange', selectionchange);
660
+ document.removeEventListener('mousedown', pointerdown, true);
661
+ document.removeEventListener('focusout', focusout, true);
662
+ window.removeEventListener('blur', blur);
663
+ };
664
+ }
665
+
666
+ /** Detach the listeners and drop what is pending. */
667
+ stop() {
668
+ this.#detach?.();
669
+ this.#detach = null;
670
+ this.#spent = null;
671
+ this.cancel('api');
672
+ }
673
+ }