@aionbuilders/nabu 0.1.0-alpha.9 → 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 (319) hide show
  1. package/CHANGELOG.md +523 -0
  2. package/LICENSE +21 -0
  3. package/README.md +82 -144
  4. package/dist/behaviors/text/RichText.svelte +25 -2
  5. package/dist/behaviors/text/index.d.ts +2 -0
  6. package/dist/behaviors/text/index.js +2 -0
  7. package/dist/behaviors/text/markdown-shortcuts.extension.d.ts +5 -0
  8. package/dist/behaviors/text/markdown-shortcuts.extension.js +79 -0
  9. package/dist/behaviors/text/markdown-syntax.d.ts +42 -0
  10. package/dist/behaviors/text/markdown-syntax.js +81 -0
  11. package/dist/behaviors/text/rich-text.extension.d.ts +3 -0
  12. package/dist/behaviors/text/rich-text.extension.js +135 -53
  13. package/dist/behaviors/text/text.behavior.svelte.d.ts +217 -42
  14. package/dist/behaviors/text/text.behavior.svelte.js +657 -55
  15. package/dist/behaviors/text/typography.extension.d.ts +7 -0
  16. package/dist/behaviors/text/typography.extension.js +25 -0
  17. package/dist/blocks/Block.svelte +5 -2
  18. package/dist/blocks/BlockList.svelte +48 -0
  19. package/dist/blocks/BlockList.svelte.d.ts +17 -0
  20. package/dist/blocks/Nabu.svelte +180 -14
  21. package/dist/blocks/Nabu.svelte.d.ts +13 -0
  22. package/dist/blocks/block.extension.d.ts +3 -0
  23. package/dist/blocks/block.extension.js +8 -9
  24. package/dist/blocks/block.svelte.d.ts +356 -68
  25. package/dist/blocks/block.svelte.js +388 -42
  26. package/dist/blocks/blockquote/Blockquote.svelte +39 -0
  27. package/dist/blocks/blockquote/Blockquote.svelte.d.ts +11 -0
  28. package/dist/blocks/blockquote/blockquote.extension.d.ts +4 -0
  29. package/dist/blocks/blockquote/blockquote.extension.js +80 -0
  30. package/dist/blocks/blockquote/blockquote.svelte.d.ts +63 -0
  31. package/dist/blocks/blockquote/blockquote.svelte.js +136 -0
  32. package/dist/blocks/blockquote/index.d.ts +3 -0
  33. package/dist/blocks/blockquote/index.js +3 -0
  34. package/dist/blocks/callout/Callout.svelte +67 -0
  35. package/dist/blocks/callout/Callout.svelte.d.ts +11 -0
  36. package/dist/blocks/callout/callout.extension.d.ts +4 -0
  37. package/dist/blocks/callout/callout.extension.js +84 -0
  38. package/dist/blocks/callout/callout.svelte.d.ts +80 -0
  39. package/dist/blocks/callout/callout.svelte.js +189 -0
  40. package/dist/blocks/callout/index.d.ts +3 -0
  41. package/dist/blocks/callout/index.js +3 -0
  42. package/dist/blocks/chunks.d.ts +49 -0
  43. package/dist/blocks/chunks.js +90 -0
  44. package/dist/blocks/code/Code.svelte +84 -0
  45. package/dist/blocks/code/Code.svelte.d.ts +11 -0
  46. package/dist/blocks/code/code.extension.d.ts +4 -0
  47. package/dist/blocks/code/code.extension.js +88 -0
  48. package/dist/blocks/code/code.svelte.d.ts +68 -0
  49. package/dist/blocks/code/code.svelte.js +245 -0
  50. package/dist/blocks/code/index.d.ts +3 -0
  51. package/dist/blocks/code/index.js +3 -0
  52. package/dist/blocks/container.utils.d.ts +85 -13
  53. package/dist/blocks/container.utils.js +338 -178
  54. package/dist/blocks/dialogue/Dialogue.svelte +8 -2
  55. package/dist/blocks/dialogue/dialogue.svelte.d.ts +36 -23
  56. package/dist/blocks/dialogue/dialogue.svelte.js +51 -45
  57. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.d.ts +2 -2
  58. package/dist/blocks/dialogue/hooks/onBeforeInput.hook.js +6 -4
  59. package/dist/blocks/dialogue/index.d.ts +12 -1
  60. package/dist/blocks/dialogue/index.js +51 -35
  61. package/dist/blocks/divider/Divider.svelte +28 -0
  62. package/dist/blocks/divider/Divider.svelte.d.ts +11 -0
  63. package/dist/blocks/divider/divider.extension.d.ts +23 -0
  64. package/dist/blocks/divider/divider.extension.js +153 -0
  65. package/dist/blocks/divider/divider.svelte.d.ts +54 -0
  66. package/dist/blocks/divider/divider.svelte.js +89 -0
  67. package/dist/blocks/divider/index.d.ts +3 -0
  68. package/dist/blocks/divider/index.js +3 -0
  69. package/dist/blocks/file/File.svelte +56 -0
  70. package/dist/blocks/file/File.svelte.d.ts +11 -0
  71. package/dist/blocks/file/file.extension.d.ts +4 -0
  72. package/dist/blocks/file/file.extension.js +27 -0
  73. package/dist/blocks/file/file.svelte.d.ts +29 -0
  74. package/dist/blocks/file/file.svelte.js +77 -0
  75. package/dist/blocks/file/index.d.ts +3 -0
  76. package/dist/blocks/file/index.js +3 -0
  77. package/dist/blocks/heading/Heading.svelte +2 -1
  78. package/dist/blocks/heading/heading.svelte.d.ts +27 -34
  79. package/dist/blocks/heading/heading.svelte.js +72 -60
  80. package/dist/blocks/heading/hooks/onBeforeInput.hook.js +7 -5
  81. package/dist/blocks/heading/index.d.ts +2 -2
  82. package/dist/blocks/heading/index.js +33 -8
  83. package/dist/blocks/image/Image.svelte +41 -0
  84. package/dist/blocks/image/Image.svelte.d.ts +11 -0
  85. package/dist/blocks/image/image.extension.d.ts +5 -0
  86. package/dist/blocks/image/image.extension.js +34 -0
  87. package/dist/blocks/image/image.svelte.d.ts +61 -0
  88. package/dist/blocks/image/image.svelte.js +114 -0
  89. package/dist/blocks/image/index.d.ts +3 -0
  90. package/dist/blocks/image/index.js +3 -0
  91. package/dist/blocks/index.d.ts +11 -1
  92. package/dist/blocks/index.js +11 -1
  93. package/dist/blocks/list/List.svelte +9 -2
  94. package/dist/blocks/list/ListItem.svelte +44 -7
  95. package/dist/blocks/list/convert.d.ts +20 -0
  96. package/dist/blocks/list/convert.js +92 -0
  97. package/dist/blocks/list/hooks/onBeforeInput.hook.js +60 -26
  98. package/dist/blocks/list/html-flat.d.ts +78 -0
  99. package/dist/blocks/list/html-flat.js +244 -0
  100. package/dist/blocks/list/indent.d.ts +86 -0
  101. package/dist/blocks/list/indent.js +205 -0
  102. package/dist/blocks/list/index.d.ts +7 -3
  103. package/dist/blocks/list/index.js +43 -31
  104. package/dist/blocks/list/list-item.svelte.d.ts +43 -17
  105. package/dist/blocks/list/list-item.svelte.js +143 -93
  106. package/dist/blocks/list/list.behavior.svelte.d.ts +7 -4
  107. package/dist/blocks/list/list.behavior.svelte.js +10 -5
  108. package/dist/blocks/list/list.svelte.d.ts +101 -23
  109. package/dist/blocks/list/list.svelte.js +136 -114
  110. package/dist/blocks/list/markdown.d.ts +149 -0
  111. package/dist/blocks/list/markdown.js +442 -0
  112. package/dist/blocks/list/normalize.d.ts +11 -0
  113. package/dist/blocks/list/normalize.js +396 -0
  114. package/dist/blocks/list/paste.d.ts +45 -0
  115. package/dist/blocks/list/paste.js +242 -0
  116. package/dist/blocks/list/step-back.d.ts +24 -0
  117. package/dist/blocks/list/step-back.js +87 -0
  118. package/dist/blocks/list/to-list.d.ts +7 -0
  119. package/dist/blocks/list/to-list.js +44 -0
  120. package/dist/blocks/list/todos-toggle.d.ts +20 -0
  121. package/dist/blocks/list/todos-toggle.js +48 -0
  122. package/dist/blocks/list/todos.svelte.d.ts +35 -0
  123. package/dist/blocks/list/todos.svelte.js +76 -0
  124. package/dist/blocks/media/index.d.ts +2 -0
  125. package/dist/blocks/media/index.js +2 -0
  126. package/dist/blocks/media/markdown.d.ts +12 -0
  127. package/dist/blocks/media/markdown.js +26 -0
  128. package/dist/blocks/media/media-block.svelte.d.ts +107 -0
  129. package/dist/blocks/media/media-block.svelte.js +181 -0
  130. package/dist/blocks/media/media.helpers.d.ts +24 -0
  131. package/dist/blocks/media/media.helpers.js +88 -0
  132. package/dist/blocks/megablock.svelte.d.ts +50 -19
  133. package/dist/blocks/megablock.svelte.js +115 -74
  134. package/dist/blocks/move.d.ts +23 -0
  135. package/dist/blocks/move.js +92 -0
  136. package/dist/blocks/nabu.svelte.d.ts +846 -75
  137. package/dist/blocks/nabu.svelte.js +1990 -182
  138. package/dist/blocks/paragraph/Paragraph.svelte +1 -0
  139. package/dist/blocks/paragraph/index.d.ts +2 -2
  140. package/dist/blocks/paragraph/index.js +35 -16
  141. package/dist/blocks/paragraph/paragraph.svelte.d.ts +49 -35
  142. package/dist/blocks/paragraph/paragraph.svelte.js +81 -69
  143. package/dist/blocks/paragraph/table.html.d.ts +9 -0
  144. package/dist/blocks/paragraph/table.html.js +111 -0
  145. package/dist/blocks/paragraph/table.markdown.d.ts +32 -0
  146. package/dist/blocks/paragraph/table.markdown.js +90 -0
  147. package/dist/blocks/region/Region.svelte +264 -0
  148. package/dist/blocks/region/Region.svelte.d.ts +11 -0
  149. package/dist/blocks/region/actions.d.ts +135 -0
  150. package/dist/blocks/region/actions.js +402 -0
  151. package/dist/blocks/region/close.d.ts +35 -0
  152. package/dist/blocks/region/close.js +130 -0
  153. package/dist/blocks/region/commands.d.ts +6 -0
  154. package/dist/blocks/region/commands.js +277 -0
  155. package/dist/blocks/region/create.d.ts +72 -0
  156. package/dist/blocks/region/create.js +208 -0
  157. package/dist/blocks/region/end-marker.d.ts +35 -0
  158. package/dist/blocks/region/end-marker.js +51 -0
  159. package/dist/blocks/region/facts.d.ts +69 -0
  160. package/dist/blocks/region/facts.js +152 -0
  161. package/dist/blocks/region/format.d.ts +91 -0
  162. package/dist/blocks/region/format.js +260 -0
  163. package/dist/blocks/region/index.d.ts +14 -0
  164. package/dist/blocks/region/index.js +14 -0
  165. package/dist/blocks/region/insert.d.ts +59 -0
  166. package/dist/blocks/region/insert.js +102 -0
  167. package/dist/blocks/region/messages.d.ts +254 -0
  168. package/dist/blocks/region/messages.js +131 -0
  169. package/dist/blocks/region/normalize.d.ts +7 -0
  170. package/dist/blocks/region/normalize.js +170 -0
  171. package/dist/blocks/region/region.extension.d.ts +58 -0
  172. package/dist/blocks/region/region.extension.js +119 -0
  173. package/dist/blocks/region/region.svelte.d.ts +221 -0
  174. package/dist/blocks/region/region.svelte.js +582 -0
  175. package/dist/blocks/region/regions.svelte.d.ts +141 -0
  176. package/dist/blocks/region/regions.svelte.js +276 -0
  177. package/dist/blocks/region/serialize.d.ts +57 -0
  178. package/dist/blocks/region/serialize.js +112 -0
  179. package/dist/blocks/region/types.d.ts +255 -0
  180. package/dist/blocks/region/types.js +204 -0
  181. package/dist/blocks/selection.svelte.d.ts +106 -8
  182. package/dist/blocks/selection.svelte.js +632 -74
  183. package/dist/blocks/subthread.d.ts +80 -0
  184. package/dist/blocks/subthread.js +167 -0
  185. package/dist/blocks/text-block.svelte.d.ts +70 -0
  186. package/dist/blocks/text-block.svelte.js +108 -0
  187. package/dist/blocks/toggle/Toggle.svelte +73 -0
  188. package/dist/blocks/toggle/Toggle.svelte.d.ts +11 -0
  189. package/dist/blocks/toggle/index.d.ts +3 -0
  190. package/dist/blocks/toggle/index.js +3 -0
  191. package/dist/blocks/toggle/markdown.d.ts +20 -0
  192. package/dist/blocks/toggle/markdown.js +112 -0
  193. package/dist/blocks/toggle/toggle.extension.d.ts +4 -0
  194. package/dist/blocks/toggle/toggle.extension.js +18 -0
  195. package/dist/blocks/toggle/toggle.svelte.d.ts +135 -0
  196. package/dist/blocks/toggle/toggle.svelte.js +352 -0
  197. package/dist/blocks/undo-selection.d.ts +175 -0
  198. package/dist/blocks/undo-selection.js +360 -0
  199. package/dist/blocks/video/Video.svelte +42 -0
  200. package/dist/blocks/video/Video.svelte.d.ts +11 -0
  201. package/dist/blocks/video/index.d.ts +3 -0
  202. package/dist/blocks/video/index.js +3 -0
  203. package/dist/blocks/video/video.extension.d.ts +4 -0
  204. package/dist/blocks/video/video.extension.js +27 -0
  205. package/dist/blocks/video/video.svelte.d.ts +29 -0
  206. package/dist/blocks/video/video.svelte.js +80 -0
  207. package/dist/extend.d.ts +55 -0
  208. package/dist/extend.js +88 -0
  209. package/dist/files/assets.clipboard.d.ts +77 -0
  210. package/dist/files/assets.clipboard.js +152 -0
  211. package/dist/files/files.svelte.d.ts +363 -0
  212. package/dist/files/files.svelte.js +897 -0
  213. package/dist/files/index.d.ts +3 -0
  214. package/dist/files/index.js +3 -0
  215. package/dist/files/outbox.d.ts +69 -0
  216. package/dist/files/outbox.js +48 -0
  217. package/dist/files/status.d.ts +65 -0
  218. package/dist/files/status.js +87 -0
  219. package/dist/files/store.d.ts +97 -0
  220. package/dist/files/store.js +65 -0
  221. package/dist/files/uploads.svelte.d.ts +174 -0
  222. package/dist/files/uploads.svelte.js +504 -0
  223. package/dist/index.d.ts +68 -6
  224. package/dist/index.js +117 -7
  225. package/dist/nabu-theme.css +112 -0
  226. package/dist/paste/html.paste.d.ts +74 -3
  227. package/dist/paste/html.paste.js +555 -83
  228. package/dist/paste/markdown-inline.d.ts +86 -0
  229. package/dist/paste/markdown-inline.js +528 -0
  230. package/dist/paste/markdown.paste.d.ts +2 -8
  231. package/dist/paste/markdown.paste.js +78 -94
  232. package/dist/paste/nabu.paste.d.ts +3 -0
  233. package/dist/paste/nabu.paste.js +29 -3
  234. package/dist/paste/plain-text.paste.d.ts +2 -2
  235. package/dist/paste/plain-text.paste.js +3 -3
  236. package/dist/persistence/asset-store.d.ts +51 -0
  237. package/dist/persistence/asset-store.js +103 -0
  238. package/dist/persistence/autosave.d.ts +53 -0
  239. package/dist/persistence/autosave.js +62 -0
  240. package/dist/persistence/compact.d.ts +162 -0
  241. package/dist/persistence/compact.js +141 -0
  242. package/dist/persistence/history.d.ts +77 -0
  243. package/dist/persistence/history.js +176 -0
  244. package/dist/persistence/indexeddb.d.ts +190 -4
  245. package/dist/persistence/indexeddb.js +333 -29
  246. package/dist/persistence/merge.d.ts +38 -0
  247. package/dist/persistence/merge.js +36 -0
  248. package/dist/persistence/outbox.d.ts +25 -0
  249. package/dist/persistence/outbox.js +40 -0
  250. package/dist/persistence/persistence.d.ts +70 -9
  251. package/dist/persistence/persistence.js +507 -35
  252. package/dist/persistence/recovery.d.ts +79 -0
  253. package/dist/persistence/recovery.js +79 -0
  254. package/dist/persistence/release.d.ts +34 -0
  255. package/dist/persistence/release.js +64 -0
  256. package/dist/persistence/state.svelte.d.ts +53 -0
  257. package/dist/persistence/state.svelte.js +48 -0
  258. package/dist/persistence/sync.d.ts +39 -0
  259. package/dist/persistence/sync.js +138 -0
  260. package/dist/persistence/tail.d.ts +42 -0
  261. package/dist/persistence/tail.js +103 -0
  262. package/dist/presets.d.ts +29 -24
  263. package/dist/presets.js +51 -14
  264. package/dist/themes/atelier.css +318 -0
  265. package/dist/ui/CommandChooser.svelte +153 -0
  266. package/dist/ui/CommandChooser.svelte.d.ts +13 -0
  267. package/dist/ui/CommandInvite.svelte +99 -0
  268. package/dist/ui/CommandInvite.svelte.d.ts +12 -0
  269. package/dist/ui/DragHandle.svelte +217 -0
  270. package/dist/ui/DragHandle.svelte.d.ts +11 -0
  271. package/dist/ui/FloatingToolbar.svelte +165 -0
  272. package/dist/ui/FloatingToolbar.svelte.d.ts +27 -0
  273. package/dist/ui/SlashMenu.svelte +215 -0
  274. package/dist/ui/SlashMenu.svelte.d.ts +33 -0
  275. package/dist/ui/anchor.d.ts +112 -0
  276. package/dist/ui/anchor.js +136 -0
  277. package/dist/ui/index.d.ts +10 -0
  278. package/dist/ui/index.js +15 -0
  279. package/dist/ui/slash-menu.svelte.d.ts +112 -0
  280. package/dist/ui/slash-menu.svelte.js +150 -0
  281. package/dist/utils/command-confirm.svelte.d.ts +349 -0
  282. package/dist/utils/command-confirm.svelte.js +673 -0
  283. package/dist/utils/commands.d.ts +328 -0
  284. package/dist/utils/commands.js +416 -0
  285. package/dist/utils/dom-scope.d.ts +14 -0
  286. package/dist/utils/dom-scope.js +20 -0
  287. package/dist/utils/drop.d.ts +160 -0
  288. package/dist/utils/drop.js +305 -0
  289. package/dist/utils/extensions.d.ts +488 -40
  290. package/dist/utils/extensions.js +300 -19
  291. package/dist/utils/html.d.ts +44 -0
  292. package/dist/utils/html.js +183 -0
  293. package/dist/utils/index.d.ts +4 -0
  294. package/dist/utils/index.js +4 -0
  295. package/dist/utils/keys.d.ts +120 -0
  296. package/dist/utils/keys.js +248 -0
  297. package/dist/utils/links.d.ts +22 -0
  298. package/dist/utils/links.js +34 -0
  299. package/dist/utils/placeholders.d.ts +88 -0
  300. package/dist/utils/placeholders.js +91 -0
  301. package/dist/utils/selection.svelte.d.ts +47 -19
  302. package/dist/utils/selection.svelte.js +60 -10
  303. package/dist/utils/spellcheck.d.ts +9 -0
  304. package/dist/utils/spellcheck.js +17 -0
  305. package/dist/utils/tab.d.ts +31 -0
  306. package/dist/utils/tab.js +117 -0
  307. package/dist/utils/words.d.ts +7 -0
  308. package/dist/utils/words.js +62 -0
  309. package/dist/vite.d.ts +22 -0
  310. package/dist/vite.js +34 -0
  311. package/package.json +61 -22
  312. package/dist/blocks/zone/Zone.svelte +0 -258
  313. package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
  314. package/dist/blocks/zone/index.d.ts +0 -2
  315. package/dist/blocks/zone/index.js +0 -2
  316. package/dist/blocks/zone/zone.extension.d.ts +0 -2
  317. package/dist/blocks/zone/zone.extension.js +0 -221
  318. package/dist/blocks/zone/zone.svelte.d.ts +0 -112
  319. package/dist/blocks/zone/zone.svelte.js +0 -321
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Key chords (ADR 017): parse `"Mod-Shift-Enter"`, normalize a `KeyboardEvent` to the same canonical form, format for display.
3
+ * Pure: no DOM access besides the (injectable) platform detection.
4
+ *
5
+ * ## Chord syntax
6
+ * `[Modifier-]*Key`, modifiers joined by `-`, case-insensitive:
7
+ * - `Mod`: Cmd (Meta) on macOS, Ctrl elsewhere. Use it for the "main" shortcut modifier.
8
+ * - `Ctrl` / `Control`, `Alt` / `Option`, `Shift`, `Meta` / `Cmd` / `Command`: the explicit keys.
9
+ * - `Key`: a `KeyboardEvent.key` name (`Enter`, `Backspace`, `ArrowUp`, `F2`…, aliases `Esc`, `Return`, `Del`, `Space`,
10
+ * `Up`/`Down`/`Left`/`Right`), or one printable character (`k`, `/`, `-`, `?`).
11
+ *
12
+ * ## Canonical form
13
+ * `Ctrl-Alt-Shift-Meta-<key>` (fixed modifier order, `Mod` already resolved for the platform), e.g. `Ctrl-Shift-Enter`.
14
+ * Normalization rules (applied identically to chord strings and keyboard events):
15
+ * - **Letters** are lower-cased: the key is the letter, Shift is a separate modifier (`Mod-Shift-x` -> `Ctrl-Shift-x`).
16
+ * Caps Lock therefore never changes a match.
17
+ * - **Other printable characters** (digits, symbols) are matched by the character the keystroke PRODUCES (`event.key`), and
18
+ * Shift is NOT part of the chord (it is already in the character: Shift+1 is `!` on a US layout). A chord string with
19
+ * `Shift` on such a key (`Mod-Shift-1`) is invalid: write the character (`Mod-!`).
20
+ * - **Named keys** (`Enter`, `Tab`, `ArrowUp`, `F2`…) keep Shift, which is a real modifier for them.
21
+ * - **Non-Latin layouts / dead keys**: when `event.key` is not an ASCII character (a Cyrillic letter, the `∫` produced by
22
+ * Option+B on macOS, `Dead`), `event.code` is used instead (`KeyB` -> `b`, `Digit1` -> `1`), so `Mod-b` works on any layout.
23
+ * - Pure modifier presses (`Shift`, `Control`, `Alt`, `Meta`) and AltGraph keystrokes (they type a character) have no chord.
24
+ *
25
+ * @typedef {'mac' | 'other'} Platform
26
+ * The platform whose conventions `Mod` and the displayed shortcuts follow: `'mac'` (Cmd) or `'other'` (Ctrl).
27
+ * @typedef {{ key: string, ctrl: boolean, alt: boolean, shift: boolean, meta: boolean }} Chord
28
+ * A parsed key chord: a key and its four modifiers (`Mod` is resolved to `ctrl` or `meta` for the platform).
29
+ */
30
+ /**
31
+ * Detect the platform whose conventions `Mod` and the displayed shortcuts follow: Cmd on macOS and iOS, Ctrl everywhere else.
32
+ * @returns {Platform} `'mac'` on macOS / iOS (Cmd is the main modifier), `'other'` everywhere else (and server-side). */
33
+ export function detectPlatform(): Platform;
34
+ /**
35
+ * Parse a chord string. Returns `null` for anything invalid: empty, unknown key name, unknown/duplicated modifier, or
36
+ * `Shift` on a digit/symbol (see the module doc).
37
+ * @param {string} text
38
+ * @param {{ platform?: Platform }} [options]
39
+ * @returns {Chord | null}
40
+ */
41
+ export function parseChord(text: string, { platform }?: {
42
+ platform?: Platform;
43
+ }): Chord | null;
44
+ /**
45
+ * The canonical string of a chord: `Ctrl-Alt-Shift-Meta-<key>`.
46
+ * @param {Chord} chord
47
+ * @returns {string}
48
+ */
49
+ export function chordId(chord: Chord): string;
50
+ /**
51
+ * Parse then canonicalize a chord string.
52
+ * @param {string} text
53
+ * @param {{ platform?: Platform }} [options]
54
+ * @returns {string | null} null when invalid
55
+ */
56
+ export function canonicalChord(text: string, options?: {
57
+ platform?: Platform;
58
+ }): string | null;
59
+ /**
60
+ * Normalize a keyboard event to a chord, with the rules of the module doc.
61
+ * @param {Pick<KeyboardEvent, 'key'> & Partial<KeyboardEvent>} event
62
+ * @returns {Chord | null} null for a pure modifier press, an AltGraph keystroke, or an event with no usable key
63
+ */
64
+ export function eventChord(event: Pick<KeyboardEvent, "key"> & Partial<KeyboardEvent>): Chord | null;
65
+ /**
66
+ * The canonical string of a keyboard event (see {@link eventChord}), or `null`.
67
+ * @param {Pick<KeyboardEvent, 'key'> & Partial<KeyboardEvent>} event
68
+ * @returns {string | null}
69
+ */
70
+ export function eventChordId(event: Pick<KeyboardEvent, "key"> & Partial<KeyboardEvent>): string | null;
71
+ /**
72
+ * Whether the chord carries a modifier that makes it a shortcut rather than typing: Ctrl, Alt or Meta. `Shift` alone does
73
+ * not (Shift+letter is a capital letter).
74
+ * @param {Chord} chord
75
+ * @returns {boolean}
76
+ */
77
+ export function hasCommandModifier(chord: Chord): boolean;
78
+ /**
79
+ * Format a chord for display, per platform. macOS: `⌃⌥⇧⌘` + key, no separator (`⌘⇧Z`, `⌘↩`). Elsewhere: `Ctrl+Alt+Shift+Meta+Key`
80
+ * (`Ctrl+Shift+Z`, `Ctrl+Enter`).
81
+ * @param {string | Chord} chord a chord string (parsed with `platform`) or a parsed chord
82
+ * @param {{ platform?: Platform }} [options]
83
+ * @returns {string} '' for an invalid chord string
84
+ */
85
+ export function formatChord(chord: string | Chord, { platform }?: {
86
+ platform?: Platform;
87
+ }): string;
88
+ /**
89
+ * The canonical ids of {@link RESERVED_CHORDS} on a platform.
90
+ * @param {Platform} platform
91
+ * @returns {Set<string>}
92
+ */
93
+ export function reservedChords(platform: Platform): Set<string>;
94
+ /**
95
+ * Whether a chord is reserved by the browser or the OS (close tab, reload, quit...) and so refused when a command declares it.
96
+ * @param {Chord} chord
97
+ * @param {Platform} platform
98
+ * @returns {boolean} whether the browser / OS owns this chord
99
+ */
100
+ export function isReservedChord(chord: Chord, platform: Platform): boolean;
101
+ /**
102
+ * Chords the browser or the OS keeps for itself (tabs, windows, quit, reload, address bar, devtools, zoom, tab switching):
103
+ * a page often cannot intercept them, and stealing them would be hostile anyway. Commands cannot bind them (refused at
104
+ * registration with a warning). Written with `Mod`, resolved per platform by {@link reservedChords}.
105
+ */
106
+ export const RESERVED_CHORDS: string[];
107
+ /**
108
+ * The platform whose conventions `Mod` and the displayed shortcuts follow: `'mac'` (Cmd) or `'other'` (Ctrl).
109
+ */
110
+ export type Platform = "mac" | "other";
111
+ /**
112
+ * A parsed key chord: a key and its four modifiers (`Mod` is resolved to `ctrl` or `meta` for the platform).
113
+ */
114
+ export type Chord = {
115
+ key: string;
116
+ ctrl: boolean;
117
+ alt: boolean;
118
+ shift: boolean;
119
+ meta: boolean;
120
+ };
@@ -0,0 +1,248 @@
1
+ /**
2
+ * Key chords (ADR 017): parse `"Mod-Shift-Enter"`, normalize a `KeyboardEvent` to the same canonical form, format for display.
3
+ * Pure: no DOM access besides the (injectable) platform detection.
4
+ *
5
+ * ## Chord syntax
6
+ * `[Modifier-]*Key`, modifiers joined by `-`, case-insensitive:
7
+ * - `Mod`: Cmd (Meta) on macOS, Ctrl elsewhere. Use it for the "main" shortcut modifier.
8
+ * - `Ctrl` / `Control`, `Alt` / `Option`, `Shift`, `Meta` / `Cmd` / `Command`: the explicit keys.
9
+ * - `Key`: a `KeyboardEvent.key` name (`Enter`, `Backspace`, `ArrowUp`, `F2`…, aliases `Esc`, `Return`, `Del`, `Space`,
10
+ * `Up`/`Down`/`Left`/`Right`), or one printable character (`k`, `/`, `-`, `?`).
11
+ *
12
+ * ## Canonical form
13
+ * `Ctrl-Alt-Shift-Meta-<key>` (fixed modifier order, `Mod` already resolved for the platform), e.g. `Ctrl-Shift-Enter`.
14
+ * Normalization rules (applied identically to chord strings and keyboard events):
15
+ * - **Letters** are lower-cased: the key is the letter, Shift is a separate modifier (`Mod-Shift-x` -> `Ctrl-Shift-x`).
16
+ * Caps Lock therefore never changes a match.
17
+ * - **Other printable characters** (digits, symbols) are matched by the character the keystroke PRODUCES (`event.key`), and
18
+ * Shift is NOT part of the chord (it is already in the character: Shift+1 is `!` on a US layout). A chord string with
19
+ * `Shift` on such a key (`Mod-Shift-1`) is invalid: write the character (`Mod-!`).
20
+ * - **Named keys** (`Enter`, `Tab`, `ArrowUp`, `F2`…) keep Shift, which is a real modifier for them.
21
+ * - **Non-Latin layouts / dead keys**: when `event.key` is not an ASCII character (a Cyrillic letter, the `∫` produced by
22
+ * Option+B on macOS, `Dead`), `event.code` is used instead (`KeyB` -> `b`, `Digit1` -> `1`), so `Mod-b` works on any layout.
23
+ * - Pure modifier presses (`Shift`, `Control`, `Alt`, `Meta`) and AltGraph keystrokes (they type a character) have no chord.
24
+ *
25
+ * @typedef {'mac' | 'other'} Platform
26
+ * The platform whose conventions `Mod` and the displayed shortcuts follow: `'mac'` (Cmd) or `'other'` (Ctrl).
27
+ * @typedef {{ key: string, ctrl: boolean, alt: boolean, shift: boolean, meta: boolean }} Chord
28
+ * A parsed key chord: a key and its four modifiers (`Mod` is resolved to `ctrl` or `meta` for the platform).
29
+ */
30
+
31
+ /**
32
+ * Detect the platform whose conventions `Mod` and the displayed shortcuts follow: Cmd on macOS and iOS, Ctrl everywhere else.
33
+ * @returns {Platform} `'mac'` on macOS / iOS (Cmd is the main modifier), `'other'` everywhere else (and server-side). */
34
+ export function detectPlatform() {
35
+ if (typeof navigator === 'undefined') return 'other';
36
+ const nav = /** @type {any} */ (navigator);
37
+ const id = nav.userAgentData?.platform || nav.platform || nav.userAgent || '';
38
+ return /mac|iphone|ipad|ipod/i.test(id) ? 'mac' : 'other';
39
+ }
40
+
41
+ /** Named keys a chord may use (the `KeyboardEvent.key` values), lower-cased -> canonical. */
42
+ const NAMED_KEYS = new Map([
43
+ 'Enter', 'Tab', 'Backspace', 'Delete', 'Escape', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight',
44
+ 'Home', 'End', 'PageUp', 'PageDown', 'Insert', 'ContextMenu',
45
+ ...Array.from({ length: 24 }, (_, i) => `F${i + 1}`),
46
+ ].map((name) => [name.toLowerCase(), name]));
47
+
48
+ /** Accepted spellings -> canonical name. */
49
+ const KEY_ALIASES = new Map([
50
+ ['esc', 'Escape'], ['return', 'Enter'], ['del', 'Delete'], ['space', ' '], ['spacebar', ' '],
51
+ ['up', 'ArrowUp'], ['down', 'ArrowDown'], ['left', 'ArrowLeft'], ['right', 'ArrowRight'],
52
+ ['pgup', 'PageUp'], ['pgdn', 'PageDown'],
53
+ ]);
54
+
55
+ const MODIFIER_NAMES = new Map([
56
+ ['mod', 'mod'], ['ctrl', 'ctrl'], ['control', 'ctrl'], ['alt', 'alt'], ['option', 'alt'], ['opt', 'alt'],
57
+ ['shift', 'shift'], ['meta', 'meta'], ['cmd', 'meta'], ['command', 'meta'],
58
+ ]);
59
+
60
+ /** @param {string} key a single character @returns {boolean} */
61
+ const isLetter = (key) => key.length === 1 && key.toLowerCase() !== key.toUpperCase();
62
+
63
+ /**
64
+ * Parse a chord string. Returns `null` for anything invalid: empty, unknown key name, unknown/duplicated modifier, or
65
+ * `Shift` on a digit/symbol (see the module doc).
66
+ * @param {string} text
67
+ * @param {{ platform?: Platform }} [options]
68
+ * @returns {Chord | null}
69
+ */
70
+ export function parseChord(text, { platform = detectPlatform() } = {}) {
71
+ if (typeof text !== 'string' || !text.trim()) return null;
72
+ let rest = text.trim();
73
+ /** @type {Set<string>} */
74
+ const mods = new Set();
75
+ // Modifiers are read greedily from the left, so a trailing "-" (the minus key) stays a key: "Mod--".
76
+ for (;;) {
77
+ const m = /^([A-Za-z]+)-(?=.)/.exec(rest);
78
+ if (!m) break;
79
+ const mod = MODIFIER_NAMES.get(m[1].toLowerCase());
80
+ if (!mod) return null;
81
+ const resolved = mod === 'mod' ? (platform === 'mac' ? 'meta' : 'ctrl') : mod;
82
+ if (mods.has(resolved)) return null; // "Ctrl-Mod-…" on a non-mac platform, "Shift-Shift-…"
83
+ mods.add(resolved);
84
+ rest = rest.slice(m[0].length);
85
+ }
86
+ /** @type {string} */
87
+ let key;
88
+ if (rest.length === 1) {
89
+ key = isLetter(rest) ? rest.toLowerCase() : rest;
90
+ } else {
91
+ const lower = rest.toLowerCase();
92
+ const named = NAMED_KEYS.get(lower) ?? KEY_ALIASES.get(lower);
93
+ if (!named) return null;
94
+ key = named;
95
+ }
96
+ const shift = mods.has('shift');
97
+ if (shift && key.length === 1 && !isLetter(key) && key !== ' ') return null;
98
+ return { key, ctrl: mods.has('ctrl'), alt: mods.has('alt'), shift, meta: mods.has('meta') };
99
+ }
100
+
101
+ /**
102
+ * The canonical string of a chord: `Ctrl-Alt-Shift-Meta-<key>`.
103
+ * @param {Chord} chord
104
+ * @returns {string}
105
+ */
106
+ export function chordId(chord) {
107
+ return (chord.ctrl ? 'Ctrl-' : '') + (chord.alt ? 'Alt-' : '') + (chord.shift ? 'Shift-' : '') + (chord.meta ? 'Meta-' : '') + chord.key;
108
+ }
109
+
110
+ /**
111
+ * Parse then canonicalize a chord string.
112
+ * @param {string} text
113
+ * @param {{ platform?: Platform }} [options]
114
+ * @returns {string | null} null when invalid
115
+ */
116
+ export function canonicalChord(text, options) {
117
+ const chord = parseChord(text, options);
118
+ return chord ? chordId(chord) : null;
119
+ }
120
+
121
+ /**
122
+ * Normalize a keyboard event to a chord, with the rules of the module doc.
123
+ * @param {Pick<KeyboardEvent, 'key'> & Partial<KeyboardEvent>} event
124
+ * @returns {Chord | null} null for a pure modifier press, an AltGraph keystroke, or an event with no usable key
125
+ */
126
+ export function eventChord(event) {
127
+ let key = event?.key;
128
+ if (typeof key !== 'string' || !key) return null;
129
+ if (key === 'Shift' || key === 'Control' || key === 'Alt' || key === 'Meta' || key === 'AltGraph' || key === 'OS') return null;
130
+ if (event.getModifierState?.('AltGraph')) return null; // AltGr+x TYPES a character: never a shortcut
131
+ // Non-ASCII character or dead key: fall back on the physical key (Latin letter / digit) so shortcuts survive any layout.
132
+ if ((key === 'Dead' || (key.length === 1 && key.charCodeAt(0) > 127) || key === 'Unidentified') && typeof event.code === 'string') {
133
+ const letter = /^Key([A-Z])$/.exec(event.code);
134
+ const digit = /^Digit([0-9])$/.exec(event.code);
135
+ if (letter) key = letter[1].toLowerCase();
136
+ else if (digit) key = digit[1];
137
+ else if (key === 'Dead' || key === 'Unidentified') return null;
138
+ } else if (key === 'Dead' || key === 'Unidentified') {
139
+ return null;
140
+ }
141
+ if (key.length === 1) {
142
+ if (isLetter(key)) key = key.toLowerCase();
143
+ } else {
144
+ const lower = key.toLowerCase();
145
+ key = NAMED_KEYS.get(lower) ?? KEY_ALIASES.get(lower) ?? key;
146
+ }
147
+ const printableSymbol = key.length === 1 && !isLetter(key) && key !== ' ';
148
+ return {
149
+ key,
150
+ ctrl: !!event.ctrlKey,
151
+ alt: !!event.altKey,
152
+ shift: !!event.shiftKey && !printableSymbol,
153
+ meta: !!event.metaKey,
154
+ };
155
+ }
156
+
157
+ /**
158
+ * The canonical string of a keyboard event (see {@link eventChord}), or `null`.
159
+ * @param {Pick<KeyboardEvent, 'key'> & Partial<KeyboardEvent>} event
160
+ * @returns {string | null}
161
+ */
162
+ export function eventChordId(event) {
163
+ const chord = eventChord(event);
164
+ return chord ? chordId(chord) : null;
165
+ }
166
+
167
+ /**
168
+ * Whether the chord carries a modifier that makes it a shortcut rather than typing: Ctrl, Alt or Meta. `Shift` alone does
169
+ * not (Shift+letter is a capital letter).
170
+ * @param {Chord} chord
171
+ * @returns {boolean}
172
+ */
173
+ export function hasCommandModifier(chord) {
174
+ return chord.ctrl || chord.alt || chord.meta;
175
+ }
176
+
177
+ const MAC_KEYS = /** @type {Record<string, string>} */ ({
178
+ Enter: '↩', Backspace: '⌫', Delete: '⌦', Tab: '⇥', Escape: '⎋', ' ': 'Space',
179
+ ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→', PageUp: '⇞', PageDown: '⇟', Home: '↖', End: '↘',
180
+ });
181
+ const OTHER_KEYS = /** @type {Record<string, string>} */ ({
182
+ Escape: 'Esc', ' ': 'Space', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right',
183
+ });
184
+
185
+ /**
186
+ * Format a chord for display, per platform. macOS: `⌃⌥⇧⌘` + key, no separator (`⌘⇧Z`, `⌘↩`). Elsewhere: `Ctrl+Alt+Shift+Meta+Key`
187
+ * (`Ctrl+Shift+Z`, `Ctrl+Enter`).
188
+ * @param {string | Chord} chord a chord string (parsed with `platform`) or a parsed chord
189
+ * @param {{ platform?: Platform }} [options]
190
+ * @returns {string} '' for an invalid chord string
191
+ */
192
+ export function formatChord(chord, { platform = detectPlatform() } = {}) {
193
+ const parsed = typeof chord === 'string' ? parseChord(chord, { platform }) : chord;
194
+ if (!parsed) return '';
195
+ if (platform === 'mac') {
196
+ const key = MAC_KEYS[parsed.key] ?? (parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key);
197
+ return (parsed.ctrl ? '⌃' : '') + (parsed.alt ? '⌥' : '') + (parsed.shift ? '⇧' : '') + (parsed.meta ? '⌘' : '') + key;
198
+ }
199
+ const key = OTHER_KEYS[parsed.key] ?? (parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key);
200
+ return [parsed.ctrl && 'Ctrl', parsed.alt && 'Alt', parsed.shift && 'Shift', parsed.meta && 'Meta', key].filter(Boolean).join('+');
201
+ }
202
+
203
+ /**
204
+ * Chords the browser or the OS keeps for itself (tabs, windows, quit, reload, address bar, devtools, zoom, tab switching):
205
+ * a page often cannot intercept them, and stealing them would be hostile anyway. Commands cannot bind them (refused at
206
+ * registration with a warning). Written with `Mod`, resolved per platform by {@link reservedChords}.
207
+ */
208
+ export const RESERVED_CHORDS = [
209
+ 'Mod-w', 'Mod-t', 'Mod-n', 'Mod-q', 'Mod-Shift-w', 'Mod-Shift-t', 'Mod-Shift-n', // window / tab / quit
210
+ 'Mod-Tab', 'Mod-Shift-Tab', 'Ctrl-Tab', 'Ctrl-Shift-Tab', 'Alt-Tab', 'Alt-F4', // switching, closing
211
+ 'Mod-PageUp', 'Mod-PageDown', // tab switching
212
+ ...Array.from({ length: 9 }, (_, i) => `Mod-${i + 1}`), // jump to tab N
213
+ 'F5', 'Mod-F5', 'Mod-r', 'Mod-Shift-r', // reload
214
+ 'Mod-l', 'F6', 'Mod-d', 'Mod-h', // address bar, bookmark, history
215
+ 'Mod-0', 'Mod-=', 'Mod-+', 'Mod--', // zoom
216
+ 'F11', 'F12', 'Mod-Shift-i', 'Mod-Shift-j', 'Mod-Alt-i', // fullscreen, devtools
217
+ ];
218
+
219
+ /** @type {Map<Platform, Set<string>>} */
220
+ const reservedCache = new Map();
221
+
222
+ /**
223
+ * The canonical ids of {@link RESERVED_CHORDS} on a platform.
224
+ * @param {Platform} platform
225
+ * @returns {Set<string>}
226
+ */
227
+ export function reservedChords(platform) {
228
+ let set = reservedCache.get(platform);
229
+ if (!set) {
230
+ set = new Set();
231
+ for (const text of RESERVED_CHORDS) {
232
+ const id = canonicalChord(text, { platform });
233
+ if (id) set.add(id);
234
+ }
235
+ reservedCache.set(platform, set);
236
+ }
237
+ return set;
238
+ }
239
+
240
+ /**
241
+ * Whether a chord is reserved by the browser or the OS (close tab, reload, quit...) and so refused when a command declares it.
242
+ * @param {Chord} chord
243
+ * @param {Platform} platform
244
+ * @returns {boolean} whether the browser / OS owns this chord
245
+ */
246
+ export function isReservedChord(chord, platform) {
247
+ return reservedChords(platform).has(chordId(chord));
248
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Whether a link leaves the site it is shown on. Only such a link is opened in a new tab (`target="_blank"`): a relative link, a
3
+ * `#anchor`, a link to the same origin, `mailto:` and `tel:` all open in place.
4
+ *
5
+ * External means an absolute `http(s)://` (or protocol-relative `//`) URL whose origin is not `origin`. Without an `origin` (rendering
6
+ * on the server, where the page's origin is not known) every such absolute URL counts as external, which is the safe side.
7
+ * @param {string | null | undefined} href
8
+ * @param {string} [origin] The origin of the current page, e.g. `location.origin`.
9
+ * @returns {boolean}
10
+ */
11
+ export function isExternalLink(href: string | null | undefined, origin?: string): boolean;
12
+ /**
13
+ * The attributes a rendered link takes: `target="_blank"` and `rel="noopener noreferrer"` for an external link, nothing otherwise
14
+ * (`undefined` removes the attribute).
15
+ * @param {string | null | undefined} href
16
+ * @param {string} [origin]
17
+ * @returns {{ target: '_blank' | undefined, rel: 'noopener noreferrer' | undefined }}
18
+ */
19
+ export function linkAttributes(href: string | null | undefined, origin?: string): {
20
+ target: "_blank" | undefined;
21
+ rel: "noopener noreferrer" | undefined;
22
+ };
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Whether a link leaves the site it is shown on. Only such a link is opened in a new tab (`target="_blank"`): a relative link, a
3
+ * `#anchor`, a link to the same origin, `mailto:` and `tel:` all open in place.
4
+ *
5
+ * External means an absolute `http(s)://` (or protocol-relative `//`) URL whose origin is not `origin`. Without an `origin` (rendering
6
+ * on the server, where the page's origin is not known) every such absolute URL counts as external, which is the safe side.
7
+ * @param {string | null | undefined} href
8
+ * @param {string} [origin] The origin of the current page, e.g. `location.origin`.
9
+ * @returns {boolean}
10
+ */
11
+ export function isExternalLink(href, origin) {
12
+ if (typeof href !== 'string') return false;
13
+ const url = href.trim();
14
+ if (!/^(?:https?:)?\/\//i.test(url)) return false;
15
+ if (!origin) return true;
16
+ try {
17
+ return new URL(url, origin).origin !== origin;
18
+ } catch {
19
+ return false;
20
+ }
21
+ }
22
+
23
+ /**
24
+ * The attributes a rendered link takes: `target="_blank"` and `rel="noopener noreferrer"` for an external link, nothing otherwise
25
+ * (`undefined` removes the attribute).
26
+ * @param {string | null | undefined} href
27
+ * @param {string} [origin]
28
+ * @returns {{ target: '_blank' | undefined, rel: 'noopener noreferrer' | undefined }}
29
+ */
30
+ export function linkAttributes(href, origin) {
31
+ return isExternalLink(href, origin)
32
+ ? { target: '_blank', rel: 'noopener noreferrer' }
33
+ : { target: undefined, rel: undefined };
34
+ }
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Placeholders — hint text displayed in empty blocks.
3
+ *
4
+ * Defaults are declared by each block class (`static placeholder`), the editor
5
+ * option `placeholders` (see {@link PlaceholdersOption}) switches them on/off,
6
+ * chooses when they show, and overrides them per block type. The resolved value
7
+ * is exposed reactively as `block.placeholder` and rendered by a CSS rule in
8
+ * Nabu.svelte through the `data-placeholder` attribute.
9
+ */
10
+ /**
11
+ * @typedef {string | false | ((block: any) => string | false)} PlaceholderText
12
+ * A string, `false` (no placeholder) or a function of the block returning one of those.
13
+ */
14
+ /**
15
+ * @typedef {Object} PlaceholdersConfig
16
+ * @property {'focus' | 'empty'} [show] - `'focus'` (default): only the empty block holding the collapsed cursor
17
+ * shows its placeholder. `'empty'`: every empty block shows it.
18
+ * @property {Record<string, PlaceholderText>} [text] - Per block type overrides (`false` disables that type).
19
+ */
20
+ /**
21
+ * `false`: no placeholders. `true` / omitted: defaults. Object: see {@link PlaceholdersConfig}.
22
+ * @typedef {boolean | PlaceholdersConfig} PlaceholdersOption
23
+ */
24
+ /**
25
+ * @typedef {Object} ResolvedPlaceholders
26
+ * @property {boolean} enabled
27
+ * @property {'focus' | 'empty'} show
28
+ * @property {Record<string, PlaceholderText>} text
29
+ */
30
+ /**
31
+ * Normalizes the `placeholders` editor option.
32
+ * @param {PlaceholdersOption} [option]
33
+ * @returns {ResolvedPlaceholders}
34
+ */
35
+ export function normalizePlaceholders(option?: PlaceholdersOption): ResolvedPlaceholders;
36
+ /**
37
+ * Resolves the placeholder text of a block: the per-type override from the
38
+ * editor option if any, else the block class default (`static placeholder`).
39
+ * Returns '' when there is nothing to show (no default, or disabled with `false`).
40
+ * It does not look at emptiness / focus — that is `block.placeholder`'s job.
41
+ *
42
+ * @param {{ type: string, constructor: { placeholder?: PlaceholderText } }} block
43
+ * @param {Record<string, PlaceholderText>} [overrides]
44
+ * @returns {string}
45
+ */
46
+ export function resolvePlaceholderText(block: {
47
+ type: string;
48
+ constructor: {
49
+ placeholder?: PlaceholderText;
50
+ };
51
+ }, overrides?: Record<string, PlaceholderText>): string;
52
+ /**
53
+ * Built-in default placeholder text, keyed by block type.
54
+ *
55
+ * @deprecated Kept for backward compatibility only. It ignores the editor
56
+ * `placeholders` option and custom block types; blocks now declare their own
57
+ * default through `static placeholder` and expose the resolved value as
58
+ * `block.placeholder`.
59
+ *
60
+ * @param {string} type
61
+ * @param {number} [level] - Heading level (1–6)
62
+ * @returns {string}
63
+ */
64
+ export function getPlaceholder(type: string, level?: number): string;
65
+ /**
66
+ * A string, `false` (no placeholder) or a function of the block returning one of those.
67
+ */
68
+ export type PlaceholderText = string | false | ((block: any) => string | false);
69
+ export type PlaceholdersConfig = {
70
+ /**
71
+ * - `'focus'` (default): only the empty block holding the collapsed cursor
72
+ * shows its placeholder. `'empty'`: every empty block shows it.
73
+ */
74
+ show?: "focus" | "empty" | undefined;
75
+ /**
76
+ * - Per block type overrides (`false` disables that type).
77
+ */
78
+ text?: Record<string, PlaceholderText> | undefined;
79
+ };
80
+ /**
81
+ * `false`: no placeholders. `true` / omitted: defaults. Object: see {@link PlaceholdersConfig}.
82
+ */
83
+ export type PlaceholdersOption = boolean | PlaceholdersConfig;
84
+ export type ResolvedPlaceholders = {
85
+ enabled: boolean;
86
+ show: "focus" | "empty";
87
+ text: Record<string, PlaceholderText>;
88
+ };
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Placeholders — hint text displayed in empty blocks.
3
+ *
4
+ * Defaults are declared by each block class (`static placeholder`), the editor
5
+ * option `placeholders` (see {@link PlaceholdersOption}) switches them on/off,
6
+ * chooses when they show, and overrides them per block type. The resolved value
7
+ * is exposed reactively as `block.placeholder` and rendered by a CSS rule in
8
+ * Nabu.svelte through the `data-placeholder` attribute.
9
+ */
10
+
11
+ /**
12
+ * @typedef {string | false | ((block: any) => string | false)} PlaceholderText
13
+ * A string, `false` (no placeholder) or a function of the block returning one of those.
14
+ */
15
+
16
+ /**
17
+ * @typedef {Object} PlaceholdersConfig
18
+ * @property {'focus' | 'empty'} [show] - `'focus'` (default): only the empty block holding the collapsed cursor
19
+ * shows its placeholder. `'empty'`: every empty block shows it.
20
+ * @property {Record<string, PlaceholderText>} [text] - Per block type overrides (`false` disables that type).
21
+ */
22
+
23
+ /**
24
+ * `false`: no placeholders. `true` / omitted: defaults. Object: see {@link PlaceholdersConfig}.
25
+ * @typedef {boolean | PlaceholdersConfig} PlaceholdersOption
26
+ */
27
+
28
+ /**
29
+ * @typedef {Object} ResolvedPlaceholders
30
+ * @property {boolean} enabled
31
+ * @property {'focus' | 'empty'} show
32
+ * @property {Record<string, PlaceholderText>} text
33
+ */
34
+
35
+ /**
36
+ * Normalizes the `placeholders` editor option.
37
+ * @param {PlaceholdersOption} [option]
38
+ * @returns {ResolvedPlaceholders}
39
+ */
40
+ export function normalizePlaceholders(option = true) {
41
+ if (option === false) return { enabled: false, show: 'focus', text: {} };
42
+ const config = option && typeof option === 'object' ? option : {};
43
+ return {
44
+ enabled: true,
45
+ show: config.show === 'empty' ? 'empty' : 'focus',
46
+ text: config.text ?? {},
47
+ };
48
+ }
49
+
50
+ /**
51
+ * Resolves the placeholder text of a block: the per-type override from the
52
+ * editor option if any, else the block class default (`static placeholder`).
53
+ * Returns '' when there is nothing to show (no default, or disabled with `false`).
54
+ * It does not look at emptiness / focus — that is `block.placeholder`'s job.
55
+ *
56
+ * @param {{ type: string, constructor: { placeholder?: PlaceholderText } }} block
57
+ * @param {Record<string, PlaceholderText>} [overrides]
58
+ * @returns {string}
59
+ */
60
+ export function resolvePlaceholderText(block, overrides = {}) {
61
+ const override = overrides[block.type];
62
+ /** @type {PlaceholderText | undefined} */
63
+ let value = override !== undefined ? override : block.constructor.placeholder;
64
+ if (typeof value === 'function') value = value(block);
65
+ return typeof value === 'string' ? value : '';
66
+ }
67
+
68
+ /**
69
+ * Built-in default placeholder text, keyed by block type.
70
+ *
71
+ * @deprecated Kept for backward compatibility only. It ignores the editor
72
+ * `placeholders` option and custom block types; blocks now declare their own
73
+ * default through `static placeholder` and expose the resolved value as
74
+ * `block.placeholder`.
75
+ *
76
+ * @param {string} type
77
+ * @param {number} [level] - Heading level (1–6)
78
+ * @returns {string}
79
+ */
80
+ export function getPlaceholder(type, level = 1) {
81
+ switch (type) {
82
+ case 'paragraph': return 'Start writing...';
83
+ case 'heading': return `Heading ${level}`;
84
+ case 'dialogue': return 'Dialogue...';
85
+ case 'blockquote': return 'Quote...';
86
+ case 'code': return 'Code…';
87
+ case 'callout': return 'Callout…';
88
+ case 'toggle': return 'Toggle…';
89
+ default: return '';
90
+ }
91
+ }