@aionbuilders/nabu 0.1.0-beta.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +531 -0
- package/LICENSE +21 -0
- package/README.md +72 -341
- package/dist/behaviors/text/RichText.svelte +24 -4
- package/dist/behaviors/text/markdown-shortcuts.extension.d.ts +3 -0
- package/dist/behaviors/text/markdown-shortcuts.extension.js +35 -10
- package/dist/behaviors/text/markdown-syntax.d.ts +42 -0
- package/dist/behaviors/text/markdown-syntax.js +81 -0
- package/dist/behaviors/text/rich-text.extension.d.ts +3 -0
- package/dist/behaviors/text/rich-text.extension.js +95 -38
- package/dist/behaviors/text/text.behavior.svelte.d.ts +195 -55
- package/dist/behaviors/text/text.behavior.svelte.js +531 -103
- package/dist/behaviors/text/typography.extension.d.ts +2 -1
- package/dist/behaviors/text/typography.extension.js +3 -2
- package/dist/blocks/BlockList.svelte +48 -0
- package/dist/blocks/BlockList.svelte.d.ts +17 -0
- package/dist/blocks/Nabu.svelte +169 -25
- package/dist/blocks/Nabu.svelte.d.ts +13 -0
- package/dist/blocks/block.extension.d.ts +3 -0
- package/dist/blocks/block.extension.js +4 -7
- package/dist/blocks/block.svelte.d.ts +350 -86
- package/dist/blocks/block.svelte.js +370 -59
- package/dist/blocks/blockquote/Blockquote.svelte +1 -2
- package/dist/blocks/blockquote/blockquote.extension.d.ts +4 -1
- package/dist/blocks/blockquote/blockquote.extension.js +14 -5
- package/dist/blocks/blockquote/blockquote.svelte.d.ts +19 -11
- package/dist/blocks/blockquote/blockquote.svelte.js +58 -13
- package/dist/blocks/callout/Callout.svelte +6 -8
- package/dist/blocks/callout/callout.extension.d.ts +4 -1
- package/dist/blocks/callout/callout.extension.js +19 -3
- package/dist/blocks/callout/callout.svelte.d.ts +5 -3
- package/dist/blocks/callout/callout.svelte.js +11 -6
- package/dist/blocks/chunks.d.ts +49 -0
- package/dist/blocks/chunks.js +90 -0
- package/dist/blocks/code/Code.svelte +7 -8
- package/dist/blocks/code/code.extension.d.ts +4 -1
- package/dist/blocks/code/code.extension.js +22 -2
- package/dist/blocks/code/code.svelte.d.ts +9 -2
- package/dist/blocks/code/code.svelte.js +49 -25
- package/dist/blocks/container.utils.d.ts +85 -13
- package/dist/blocks/container.utils.js +338 -178
- package/dist/blocks/dialogue/Dialogue.svelte +8 -4
- package/dist/blocks/dialogue/dialogue.svelte.d.ts +33 -2
- package/dist/blocks/dialogue/dialogue.svelte.js +58 -4
- package/dist/blocks/dialogue/hooks/onBeforeInput.hook.d.ts +2 -2
- package/dist/blocks/dialogue/hooks/onBeforeInput.hook.js +6 -4
- package/dist/blocks/dialogue/index.d.ts +12 -1
- package/dist/blocks/dialogue/index.js +51 -35
- package/dist/blocks/divider/divider.extension.d.ts +23 -1
- package/dist/blocks/divider/divider.extension.js +85 -19
- package/dist/blocks/divider/divider.svelte.d.ts +7 -2
- package/dist/blocks/divider/divider.svelte.js +9 -4
- package/dist/blocks/file/File.svelte +13 -6
- package/dist/blocks/file/file.extension.d.ts +4 -1
- package/dist/blocks/file/file.extension.js +9 -1
- package/dist/blocks/file/file.svelte.d.ts +3 -3
- package/dist/blocks/file/file.svelte.js +20 -14
- package/dist/blocks/heading/Heading.svelte +1 -2
- package/dist/blocks/heading/heading.svelte.d.ts +23 -11
- package/dist/blocks/heading/heading.svelte.js +68 -13
- package/dist/blocks/heading/hooks/onBeforeInput.hook.js +7 -5
- package/dist/blocks/heading/index.d.ts +2 -2
- package/dist/blocks/heading/index.js +33 -8
- package/dist/blocks/image/Image.svelte +5 -2
- package/dist/blocks/image/image.extension.d.ts +4 -1
- package/dist/blocks/image/image.extension.js +9 -1
- package/dist/blocks/image/image.svelte.d.ts +17 -6
- package/dist/blocks/image/image.svelte.js +33 -11
- package/dist/blocks/index.d.ts +1 -1
- package/dist/blocks/index.js +1 -1
- package/dist/blocks/list/List.svelte +1 -0
- package/dist/blocks/list/ListItem.svelte +1 -0
- package/dist/blocks/list/convert.d.ts +20 -0
- package/dist/blocks/list/convert.js +92 -0
- package/dist/blocks/list/hooks/onBeforeInput.hook.js +49 -28
- package/dist/blocks/list/html-flat.d.ts +78 -0
- package/dist/blocks/list/html-flat.js +244 -0
- package/dist/blocks/list/indent.d.ts +86 -0
- package/dist/blocks/list/indent.js +205 -0
- package/dist/blocks/list/index.d.ts +6 -3
- package/dist/blocks/list/index.js +42 -31
- package/dist/blocks/list/list-item.svelte.d.ts +32 -18
- package/dist/blocks/list/list-item.svelte.js +99 -100
- package/dist/blocks/list/list.behavior.svelte.d.ts +4 -1
- package/dist/blocks/list/list.behavior.svelte.js +6 -1
- package/dist/blocks/list/list.svelte.d.ts +89 -18
- package/dist/blocks/list/list.svelte.js +129 -125
- package/dist/blocks/list/markdown.d.ts +149 -0
- package/dist/blocks/list/markdown.js +442 -0
- package/dist/blocks/list/normalize.d.ts +11 -0
- package/dist/blocks/list/normalize.js +396 -0
- package/dist/blocks/list/paste.d.ts +45 -0
- package/dist/blocks/list/paste.js +242 -0
- package/dist/blocks/list/step-back.d.ts +24 -0
- package/dist/blocks/list/step-back.js +87 -0
- package/dist/blocks/list/to-list.d.ts +7 -0
- package/dist/blocks/list/to-list.js +44 -0
- package/dist/blocks/list/todos-toggle.d.ts +20 -0
- package/dist/blocks/list/todos-toggle.js +48 -0
- package/dist/blocks/media/markdown.d.ts +12 -0
- package/dist/blocks/media/markdown.js +26 -0
- package/dist/blocks/media/media-block.svelte.d.ts +77 -2
- package/dist/blocks/media/media-block.svelte.js +124 -12
- package/dist/blocks/media/media.helpers.d.ts +6 -1
- package/dist/blocks/media/media.helpers.js +43 -6
- package/dist/blocks/megablock.svelte.d.ts +50 -19
- package/dist/blocks/megablock.svelte.js +114 -74
- package/dist/blocks/move.d.ts +23 -0
- package/dist/blocks/move.js +92 -0
- package/dist/blocks/nabu.svelte.d.ts +764 -71
- package/dist/blocks/nabu.svelte.js +1753 -189
- package/dist/blocks/paragraph/Paragraph.svelte +1 -2
- package/dist/blocks/paragraph/index.d.ts +2 -2
- package/dist/blocks/paragraph/index.js +35 -13
- package/dist/blocks/paragraph/paragraph.svelte.d.ts +46 -14
- package/dist/blocks/paragraph/paragraph.svelte.js +77 -16
- package/dist/blocks/paragraph/table.html.d.ts +9 -0
- package/dist/blocks/paragraph/table.html.js +111 -0
- package/dist/blocks/paragraph/table.markdown.d.ts +32 -0
- package/dist/blocks/paragraph/table.markdown.js +90 -0
- package/dist/blocks/region/Region.svelte +264 -0
- package/dist/blocks/region/Region.svelte.d.ts +11 -0
- package/dist/blocks/region/actions.d.ts +135 -0
- package/dist/blocks/region/actions.js +402 -0
- package/dist/blocks/region/close.d.ts +35 -0
- package/dist/blocks/region/close.js +130 -0
- package/dist/blocks/region/commands.d.ts +6 -0
- package/dist/blocks/region/commands.js +277 -0
- package/dist/blocks/region/create.d.ts +72 -0
- package/dist/blocks/region/create.js +208 -0
- package/dist/blocks/region/end-marker.d.ts +35 -0
- package/dist/blocks/region/end-marker.js +51 -0
- package/dist/blocks/region/facts.d.ts +69 -0
- package/dist/blocks/region/facts.js +152 -0
- package/dist/blocks/region/format.d.ts +91 -0
- package/dist/blocks/region/format.js +260 -0
- package/dist/blocks/region/index.d.ts +14 -0
- package/dist/blocks/region/index.js +14 -0
- package/dist/blocks/region/insert.d.ts +59 -0
- package/dist/blocks/region/insert.js +102 -0
- package/dist/blocks/region/messages.d.ts +254 -0
- package/dist/blocks/region/messages.js +131 -0
- package/dist/blocks/region/normalize.d.ts +7 -0
- package/dist/blocks/region/normalize.js +170 -0
- package/dist/blocks/region/region.extension.d.ts +58 -0
- package/dist/blocks/region/region.extension.js +119 -0
- package/dist/blocks/region/region.svelte.d.ts +221 -0
- package/dist/blocks/region/region.svelte.js +582 -0
- package/dist/blocks/region/regions.svelte.d.ts +141 -0
- package/dist/blocks/region/regions.svelte.js +276 -0
- package/dist/blocks/region/serialize.d.ts +57 -0
- package/dist/blocks/region/serialize.js +112 -0
- package/dist/blocks/region/types.d.ts +255 -0
- package/dist/blocks/region/types.js +204 -0
- package/dist/blocks/selection.svelte.d.ts +106 -8
- package/dist/blocks/selection.svelte.js +622 -74
- package/dist/blocks/subthread.d.ts +80 -0
- package/dist/blocks/subthread.js +167 -0
- package/dist/blocks/text-block.svelte.d.ts +35 -14
- package/dist/blocks/text-block.svelte.js +42 -8
- package/dist/blocks/toggle/Toggle.svelte +4 -15
- package/dist/blocks/toggle/markdown.d.ts +20 -0
- package/dist/blocks/toggle/markdown.js +112 -0
- package/dist/blocks/toggle/toggle.extension.d.ts +4 -1
- package/dist/blocks/toggle/toggle.extension.js +6 -0
- package/dist/blocks/toggle/toggle.svelte.d.ts +55 -8
- package/dist/blocks/toggle/toggle.svelte.js +134 -34
- package/dist/blocks/undo-selection.d.ts +175 -0
- package/dist/blocks/undo-selection.js +360 -0
- package/dist/blocks/video/Video.svelte +5 -2
- package/dist/blocks/video/video.extension.d.ts +4 -1
- package/dist/blocks/video/video.extension.js +9 -1
- package/dist/blocks/video/video.svelte.d.ts +6 -5
- package/dist/blocks/video/video.svelte.js +18 -9
- package/dist/extend.d.ts +55 -0
- package/dist/extend.js +88 -0
- package/dist/files/assets.clipboard.d.ts +77 -0
- package/dist/files/assets.clipboard.js +152 -0
- package/dist/files/files.svelte.d.ts +321 -19
- package/dist/files/files.svelte.js +847 -43
- package/dist/files/index.d.ts +3 -1
- package/dist/files/index.js +3 -1
- package/dist/files/outbox.d.ts +69 -0
- package/dist/files/outbox.js +48 -0
- package/dist/files/status.d.ts +65 -0
- package/dist/files/status.js +87 -0
- package/dist/files/store.d.ts +97 -0
- package/dist/files/store.js +65 -0
- package/dist/files/uploads.svelte.d.ts +174 -0
- package/dist/files/uploads.svelte.js +504 -0
- package/dist/index.d.ts +68 -9
- package/dist/index.js +117 -10
- package/dist/nabu-theme.css +21 -1
- package/dist/paste/html.paste.d.ts +74 -3
- package/dist/paste/html.paste.js +550 -86
- package/dist/paste/markdown-inline.d.ts +86 -0
- package/dist/paste/markdown-inline.js +528 -0
- package/dist/paste/markdown.paste.d.ts +2 -8
- package/dist/paste/markdown.paste.js +78 -94
- package/dist/paste/nabu.paste.d.ts +3 -0
- package/dist/paste/nabu.paste.js +29 -3
- package/dist/paste/plain-text.paste.d.ts +2 -2
- package/dist/paste/plain-text.paste.js +3 -3
- package/dist/persistence/asset-store.d.ts +51 -0
- package/dist/persistence/asset-store.js +103 -0
- package/dist/persistence/autosave.d.ts +53 -0
- package/dist/persistence/autosave.js +62 -0
- package/dist/persistence/compact.d.ts +162 -0
- package/dist/persistence/compact.js +141 -0
- package/dist/persistence/history.d.ts +77 -0
- package/dist/persistence/history.js +176 -0
- package/dist/persistence/indexeddb.d.ts +190 -4
- package/dist/persistence/indexeddb.js +333 -29
- package/dist/persistence/merge.d.ts +38 -0
- package/dist/persistence/merge.js +36 -0
- package/dist/persistence/outbox.d.ts +25 -0
- package/dist/persistence/outbox.js +40 -0
- package/dist/persistence/persistence.d.ts +70 -9
- package/dist/persistence/persistence.js +507 -35
- package/dist/persistence/recovery.d.ts +79 -0
- package/dist/persistence/recovery.js +79 -0
- package/dist/persistence/release.d.ts +34 -0
- package/dist/persistence/release.js +64 -0
- package/dist/persistence/state.svelte.d.ts +53 -0
- package/dist/persistence/state.svelte.js +48 -0
- package/dist/persistence/sync.d.ts +39 -0
- package/dist/persistence/sync.js +138 -0
- package/dist/persistence/tail.d.ts +42 -0
- package/dist/persistence/tail.js +103 -0
- package/dist/presets.d.ts +29 -26
- package/dist/presets.js +35 -13
- package/dist/themes/atelier.css +318 -0
- package/dist/ui/CommandChooser.svelte +153 -0
- package/dist/ui/CommandChooser.svelte.d.ts +13 -0
- package/dist/ui/CommandInvite.svelte +99 -0
- package/dist/ui/CommandInvite.svelte.d.ts +12 -0
- package/dist/ui/DragHandle.svelte +97 -21
- package/dist/ui/FloatingToolbar.svelte +75 -27
- package/dist/ui/FloatingToolbar.svelte.d.ts +10 -0
- package/dist/ui/SlashMenu.svelte +147 -15
- package/dist/ui/SlashMenu.svelte.d.ts +20 -0
- package/dist/ui/anchor.d.ts +112 -0
- package/dist/ui/anchor.js +136 -0
- package/dist/ui/index.d.ts +7 -1
- package/dist/ui/index.js +12 -1
- package/dist/ui/slash-menu.svelte.d.ts +79 -7
- package/dist/ui/slash-menu.svelte.js +85 -51
- package/dist/utils/command-confirm.svelte.d.ts +349 -0
- package/dist/utils/command-confirm.svelte.js +673 -0
- package/dist/utils/commands.d.ts +328 -0
- package/dist/utils/commands.js +416 -0
- package/dist/utils/composition.d.ts +28 -0
- package/dist/utils/composition.js +51 -0
- package/dist/utils/dom-scope.d.ts +14 -0
- package/dist/utils/dom-scope.js +20 -0
- package/dist/utils/drop.d.ts +160 -0
- package/dist/utils/drop.js +305 -0
- package/dist/utils/extensions.d.ts +439 -45
- package/dist/utils/extensions.js +271 -29
- package/dist/utils/html.d.ts +44 -0
- package/dist/utils/html.js +183 -0
- package/dist/utils/index.d.ts +3 -0
- package/dist/utils/index.js +3 -0
- package/dist/utils/keys.d.ts +120 -0
- package/dist/utils/keys.js +248 -0
- package/dist/utils/links.d.ts +22 -0
- package/dist/utils/links.js +34 -0
- package/dist/utils/placeholders.d.ts +81 -3
- package/dist/utils/placeholders.js +73 -3
- package/dist/utils/selection.svelte.d.ts +48 -20
- package/dist/utils/selection.svelte.js +60 -10
- package/dist/utils/spellcheck.d.ts +9 -0
- package/dist/utils/spellcheck.js +17 -0
- package/dist/utils/tab.d.ts +31 -0
- package/dist/utils/tab.js +117 -0
- package/dist/utils/words.d.ts +42 -0
- package/dist/utils/words.js +147 -0
- package/dist/vite.d.ts +9 -3
- package/dist/vite.js +19 -8
- package/package.json +56 -20
- package/dist/blocks/variable.svelte.d.ts +0 -47
- package/dist/blocks/variable.svelte.js +0 -51
- package/dist/blocks/zone/TemplateEditor.svelte +0 -308
- package/dist/blocks/zone/TemplateEditor.svelte.d.ts +0 -11
- package/dist/blocks/zone/Zone.svelte +0 -272
- package/dist/blocks/zone/Zone.svelte.d.ts +0 -11
- package/dist/blocks/zone/ZoneEditor.svelte +0 -289
- package/dist/blocks/zone/ZoneEditor.svelte.d.ts +0 -11
- package/dist/blocks/zone/ZoneTemplatesList.svelte +0 -188
- package/dist/blocks/zone/ZoneTemplatesList.svelte.d.ts +0 -11
- package/dist/blocks/zone/hooks/onBeforeInput.hook.d.ts +0 -3
- package/dist/blocks/zone/hooks/onBeforeInput.hook.js +0 -30
- package/dist/blocks/zone/index.d.ts +0 -2
- package/dist/blocks/zone/index.js +0 -2
- package/dist/blocks/zone/zone.extension.d.ts +0 -2
- package/dist/blocks/zone/zone.extension.js +0 -237
- package/dist/blocks/zone/zone.svelte.d.ts +0 -221
- package/dist/blocks/zone/zone.svelte.js +0 -608
- package/dist/overlays/context/Context.svelte +0 -182
- package/dist/overlays/context/Context.svelte.d.ts +0 -17
- package/dist/overlays/context/collect.d.ts +0 -17
- package/dist/overlays/context/collect.js +0 -33
- package/dist/overlays/context/context.extension.d.ts +0 -2
- package/dist/overlays/context/context.extension.js +0 -8
- package/dist/overlays/context/context.svelte.d.ts +0 -82
- package/dist/overlays/context/context.svelte.js +0 -159
- package/dist/overlays/context/index.d.ts +0 -3
- package/dist/overlays/context/index.js +0 -3
|
@@ -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
|
+
}
|
|
@@ -1,10 +1,88 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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`.
|
|
5
59
|
*
|
|
6
60
|
* @param {string} type
|
|
7
61
|
* @param {number} [level] - Heading level (1–6)
|
|
8
62
|
* @returns {string}
|
|
9
63
|
*/
|
|
10
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
|
+
};
|
|
@@ -1,7 +1,77 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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`.
|
|
5
75
|
*
|
|
6
76
|
* @param {string} type
|
|
7
77
|
* @param {number} [level] - Heading level (1–6)
|