@noy4/docserve 0.3.2 → 0.3.3

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 (61) hide show
  1. package/bin.mjs +2 -2
  2. package/dist/widget/index.js +11155 -0
  3. package/package.json +24 -3
  4. package/src/node/adapter.mjs +67 -0
  5. package/src/node/assets.mjs +36 -0
  6. package/src/node/dates.mjs +73 -0
  7. package/src/node/docs-info.mjs +39 -0
  8. package/src/node/files.mjs +43 -0
  9. package/src/node/gallery.mjs +33 -0
  10. package/src/node/inject.mjs +43 -0
  11. package/src/node/meta.mjs +137 -0
  12. package/src/node/routes.mjs +105 -0
  13. package/src/node/scan.mjs +87 -0
  14. package/src/node/serve-static.mjs +158 -0
  15. package/src/node/server.mjs +69 -0
  16. package/src/node/watch.mjs +119 -0
  17. package/src/plugins/copy/client.js +72 -0
  18. package/src/plugins/copy/copy.css +21 -0
  19. package/src/plugins/home/client.js +24 -0
  20. package/src/plugins/sidebar/client.js +105 -0
  21. package/src/plugins/sidebar/grouping.js +108 -0
  22. package/src/plugins/sidebar/icons.js +25 -0
  23. package/src/plugins/sidebar/model.ts +91 -0
  24. package/src/plugins/sidebar/resize-model.ts +47 -0
  25. package/src/plugins/sidebar/sidebar.css +663 -0
  26. package/src/plugins/sidebar/tree-model.ts +23 -0
  27. package/src/plugins/sidebar/tree.ts +69 -0
  28. package/src/plugins/sidebar/ui/PageList.tsx +153 -0
  29. package/src/plugins/sidebar/ui/RadioMenu.tsx +201 -0
  30. package/src/plugins/sidebar/ui/Sidebar.tsx +95 -0
  31. package/src/plugins/sidebar/ui/SidebarHeader.tsx +87 -0
  32. package/src/plugins/sidebar/ui/TreeList.tsx +121 -0
  33. package/src/plugins/sidebar/ui/preview-model.ts +134 -0
  34. package/src/plugins/sidebar/ui/useModel.ts +25 -0
  35. package/src/shared/types.d.ts +193 -0
  36. package/src/widget/commands.js +214 -0
  37. package/src/widget/docks.js +127 -0
  38. package/src/widget/host.js +187 -0
  39. package/src/widget/index.js +14 -0
  40. package/src/widget/lib/disposables.js +44 -0
  41. package/src/widget/lib/dom.js +106 -0
  42. package/src/widget/lib/events.js +65 -0
  43. package/src/widget/lib/persisted-signal.js +40 -0
  44. package/src/widget/lib/storage.js +70 -0
  45. package/src/widget/live.js +86 -0
  46. package/src/widget/pages.js +65 -0
  47. package/src/widget/palette.css +162 -0
  48. package/src/widget/palette.js +259 -0
  49. package/src/widget/placement.js +204 -0
  50. package/src/widget/plugins.js +39 -0
  51. package/src/widget/rpc.js +32 -0
  52. package/src/widget/styles.js +31 -0
  53. package/src/widget/ui.js +50 -0
  54. package/src/widget/widget.css +193 -0
  55. package/server/files.mjs +0 -261
  56. package/server/index.mjs +0 -198
  57. package/server/inject.html +0 -88
  58. package/server/inject.mjs +0 -28
  59. package/server/watch.mjs +0 -104
  60. /package/{server → src/node}/state.mjs +0 -0
  61. /package/{server → src/node}/websocket.mjs +0 -0
@@ -0,0 +1,121 @@
1
+ import { decoded, pageUrl } from "../../../widget/lib/dom.js"
2
+ import type { CSSProperties } from "react"
3
+ import { ICON_CHEVRON, ICON_FILE } from "../icons.js"
4
+ import type { TreeModel } from "../tree-model.js"
5
+ import type { TreeNode } from "../tree.js"
6
+ import { Favicon } from "./PageList.js"
7
+
8
+ export interface TreeListProps {
9
+ model: TreeModel
10
+ currentPage: string
11
+ }
12
+
13
+ export function TreeList({ model, currentPage }: TreeListProps) {
14
+ const nodes = model.nodes.value
15
+ const collapsed = new Set(model.collapsed.value)
16
+ const target = pageUrl(currentPage)
17
+
18
+ if (!nodes.length)
19
+ return <p className="docserve-sidebar__empty">No pages</p>
20
+
21
+ return (
22
+ <div className="docserve-sidebar__tree" role="tree" aria-label="Pages">
23
+ {nodes.map((node) => (
24
+ <TreeRow
25
+ key={node.path}
26
+ node={node}
27
+ depth={0}
28
+ collapsed={collapsed}
29
+ model={model}
30
+ target={target}
31
+ currentPage={currentPage}
32
+ />
33
+ ))}
34
+ </div>
35
+ )
36
+ }
37
+
38
+ interface TreeRowProps {
39
+ node: TreeNode<DocPage>
40
+ depth: number
41
+ collapsed: Set<string>
42
+ model: TreeModel
43
+ target: string
44
+ currentPage: string
45
+ }
46
+
47
+ function TreeRow({ node, depth, collapsed, model, target, currentPage }: TreeRowProps) {
48
+ // One 16px slot per row: a chevron for folders, an icon for pages. Both
49
+ // start at the same offset, so every label lines up column for column.
50
+ const style = { paddingLeft: `${8 + depth * 14}px` }
51
+
52
+ if (node.isFolder) {
53
+ const open = !collapsed.has(node.path)
54
+
55
+ return (
56
+ <div className="docserve-sidebar__tree-branch" role="none">
57
+ <button
58
+ type="button"
59
+ className="docserve-sidebar__tree-row docserve-sidebar__tree-row--folder"
60
+ role="treeitem"
61
+ aria-expanded={open}
62
+ aria-level={depth + 1}
63
+ style={style}
64
+ onClick={() => model.toggleFolder(node.path)}
65
+ >
66
+ <span
67
+ className="docserve-sidebar__tree-slot docserve-sidebar__tree-caret"
68
+ data-open={open ? "" : undefined}
69
+ dangerouslySetInnerHTML={{ __html: ICON_CHEVRON }}
70
+ />
71
+ <span className="docserve-sidebar__tree-label">{node.name}</span>
72
+ </button>
73
+ {open && (
74
+ <div
75
+ className="docserve-sidebar__tree-group"
76
+ role="group"
77
+ style={{ "--docserve-tree-guide": `${16 + depth * 14}px` } as CSSProperties}
78
+ >
79
+ {node.children.map((child) => (
80
+ <TreeRow
81
+ key={child.path}
82
+ node={child}
83
+ depth={depth + 1}
84
+ collapsed={collapsed}
85
+ model={model}
86
+ target={target}
87
+ currentPage={currentPage}
88
+ />
89
+ ))}
90
+ </div>
91
+ )}
92
+ </div>
93
+ )
94
+ }
95
+
96
+ const page = node.data
97
+ if (!page) return null
98
+
99
+ const active = isActive(page, target, currentPage)
100
+
101
+ return (
102
+ <a
103
+ className="docserve-sidebar__tree-row docserve-sidebar__tree-row--page"
104
+ role="treeitem"
105
+ aria-level={depth + 1}
106
+ aria-current={active ? "page" : undefined}
107
+ href={page.url}
108
+ title={page.title}
109
+ style={style}
110
+ >
111
+ <span className="docserve-sidebar__tree-slot docserve-sidebar__tree-icon">
112
+ {page.favicon ? <Favicon src={page.favicon} /> : <span dangerouslySetInnerHTML={{ __html: ICON_FILE }} />}
113
+ </span>
114
+ <span className="docserve-sidebar__tree-label">{node.name}</span>
115
+ </a>
116
+ )
117
+ }
118
+
119
+ function isActive(page: DocPage, target: string, currentPage: string): boolean {
120
+ return page.url === target || decoded(page.url) === `/${currentPage}`
121
+ }
@@ -0,0 +1,134 @@
1
+ import { effect, signal } from "@preact/signals-react"
2
+
3
+ export const THUMB_W = 960
4
+ const MAX_PREVIEWS = 2
5
+
6
+ interface QueueItem {
7
+ iframe: HTMLIFrameElement
8
+ src: string
9
+ }
10
+
11
+ export class PreviewModel {
12
+ #root = signal<HTMLElement | null>(null)
13
+
14
+ readonly setRoot = (element: HTMLElement | null): void => {
15
+ this.#root.value = element
16
+ }
17
+
18
+ get element(): HTMLElement | null {
19
+ return this.#root.value
20
+ }
21
+
22
+ #thumbs = new Set<HTMLElement>()
23
+ #observer: IntersectionObserver | null = null
24
+ #resize: ResizeObserver | null = null
25
+ #queue: QueueItem[] = []
26
+ #loads = new Map<HTMLIFrameElement, () => void>()
27
+ #active = 0
28
+
29
+ subscribe(): () => void {
30
+ const stop = effect(() => {
31
+ const root = this.#root.value
32
+ if (!root) return
33
+
34
+ const observer = new IntersectionObserver((entries) => {
35
+ for (const entry of entries) {
36
+ if (!entry.isIntersecting) continue
37
+ observer.unobserve(entry.target)
38
+ const iframe = entry.target.querySelector("iframe")
39
+ const src = iframe?.getAttribute("data-src")
40
+ if (!iframe || !src || iframe.hasAttribute("src")) continue
41
+ this.#queue.push({ iframe, src })
42
+ this.#pump()
43
+ }
44
+ }, { root, rootMargin: "150px" })
45
+
46
+ const resize = new ResizeObserver((entries) => {
47
+ for (const entry of entries) {
48
+ if (entry.target instanceof HTMLElement) this.#fit(entry.target)
49
+ }
50
+ })
51
+
52
+ this.#observer = observer
53
+ this.#resize = resize
54
+ for (const thumb of this.#thumbs) {
55
+ observer.observe(thumb)
56
+ resize.observe(thumb)
57
+ }
58
+
59
+ return () => {
60
+ observer.disconnect()
61
+ resize.disconnect()
62
+ this.#observer = null
63
+ this.#resize = null
64
+ this.#reset()
65
+ }
66
+ })
67
+
68
+ return () => {
69
+ stop()
70
+ this.#thumbs.clear()
71
+ }
72
+ }
73
+
74
+ watch(thumb: HTMLElement | null): void | (() => void) {
75
+ if (!thumb) return
76
+
77
+ this.#thumbs.add(thumb)
78
+ this.#observer?.observe(thumb)
79
+ this.#resize?.observe(thumb)
80
+ this.#fit(thumb)
81
+
82
+ return () => {
83
+ this.#thumbs.delete(thumb)
84
+ this.#observer?.unobserve(thumb)
85
+ this.#resize?.unobserve(thumb)
86
+
87
+ const iframe = thumb.querySelector("iframe")
88
+ if (!iframe) return
89
+ this.#queue = this.#queue.filter((item) => item.iframe !== iframe)
90
+ const load = this.#loads.get(iframe)
91
+ if (!load) return
92
+ iframe.removeEventListener("load", load)
93
+ this.#loads.delete(iframe)
94
+ this.#active = Math.max(0, this.#active - 1)
95
+ this.#pump()
96
+ }
97
+ }
98
+
99
+ #pump(): void {
100
+ while (this.#active < MAX_PREVIEWS && this.#queue.length) {
101
+ const item = this.#queue.shift()
102
+ if (!item || !item.iframe.isConnected) continue
103
+ this.#active++
104
+
105
+ const load = () => {
106
+ this.#loads.delete(item.iframe)
107
+ this.#active = Math.max(0, this.#active - 1)
108
+ this.#pump()
109
+ }
110
+
111
+ this.#loads.set(item.iframe, load)
112
+ item.iframe.addEventListener("load", load, { once: true })
113
+ item.iframe.src = item.src
114
+ }
115
+ }
116
+
117
+ #fit(thumb: HTMLElement): void {
118
+ const iframe = thumb.querySelector("iframe")
119
+ if (!iframe || !thumb.clientWidth) return
120
+
121
+ const scale = thumb.clientWidth / THUMB_W
122
+ iframe.style.width = `${THUMB_W}px`
123
+ iframe.style.height = `${Math.round(thumb.clientHeight / scale)}px`
124
+ iframe.style.transform = `scale(${scale})`
125
+ }
126
+
127
+ #reset(): void {
128
+ this.#queue.length = 0
129
+ this.#active = 0
130
+ for (const [iframe, load] of this.#loads)
131
+ iframe.removeEventListener("load", load)
132
+ this.#loads.clear()
133
+ }
134
+ }
@@ -0,0 +1,25 @@
1
+ import { useEffect, useLayoutEffect, useState } from "react"
2
+
3
+ export interface Subscribable {
4
+ subscribe(): (() => void) | void
5
+ }
6
+
7
+ /** Create a model once and run its `subscribe()`. */
8
+ export function useModel<T extends object>(create: () => T): T {
9
+ const [model] = useState(create)
10
+ useEffect(() => subscribe(model), [model])
11
+ return model
12
+ }
13
+
14
+ /** Create a model once and run its `subscribe()` before paint. */
15
+ export function useLayoutModel<T extends object>(create: () => T): T {
16
+ const [model] = useState(create)
17
+ useLayoutEffect(() => subscribe(model), [model])
18
+ return model
19
+ }
20
+
21
+ function subscribe(model: object): (() => void) | void {
22
+ const subscribable = model as Partial<Subscribable>
23
+ if (typeof subscribable.subscribe !== "function") return
24
+ return subscribable.subscribe()
25
+ }
@@ -0,0 +1,193 @@
1
+ // Public contracts for the docserve widget and its plugins.
2
+
3
+ /** One HTML page as returned by `GET /api/files`. */
4
+ interface DocPage {
5
+ /** Title from `<title>`, else the file name. */
6
+ title: string
7
+ /** Root-absolute URL, e.g. `/guides/intro.html`. */
8
+ url: string
9
+ /** Absolute path on disk. */
10
+ filePath: string
11
+ /** Unix seconds. */
12
+ created: number
13
+ /** Unix seconds. */
14
+ modified?: number
15
+ /** Data URL or absolute URL. */
16
+ favicon?: string
17
+ }
18
+
19
+ /** Identity of the served folder, from the injected script's data attributes. */
20
+ interface DocsInfo {
21
+ /** Folder name, e.g. `reports`. */
22
+ name: string
23
+ /** Display path with the home directory collapsed to `~`. */
24
+ path: string
25
+ /** Deterministic hue (0-359) shared with the gallery favicon. */
26
+ hue: number
27
+ }
28
+
29
+ /** Websocket message from `/__reload` describing file changes. */
30
+ interface ChangeMessage {
31
+ type: 'change'
32
+ /** Changed page paths relative to the docs root. */
33
+ pages: string[]
34
+ /** True when a page was added or removed. */
35
+ contentSetChanged: boolean
36
+ /** True when the gallery template changed. */
37
+ templateChanged: boolean
38
+ }
39
+
40
+ /** Websocket message from `/__reload` describing stylesheet changes. */
41
+ interface CssMessage {
42
+ type: 'css'
43
+ /** Changed stylesheet paths relative to the docs root. */
44
+ files: string[]
45
+ }
46
+
47
+ type LiveMessage = ChangeMessage | CssMessage
48
+
49
+ /** Event map: event name in keys, listener signature in values. */
50
+ interface EventsMap {
51
+ [event: string]: any
52
+ }
53
+
54
+ interface EventUnsubscribe {
55
+ (): void
56
+ }
57
+
58
+ /** Typed event emitter, ported from devframe's `utils/events.ts`. */
59
+ interface EventEmitter<Events extends EventsMap> {
60
+ emit: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void
61
+ emitOnce: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void
62
+ /** @internal */
63
+ _listeners: Partial<{ [E in keyof Events]: Events[E][] }>
64
+ on: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe
65
+ once: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe
66
+ }
67
+
68
+ /** Events a plugin can observe. Values are listener signatures. */
69
+ interface DocserveEvents {
70
+ 'pages:changed': (message: ChangeMessage) => void
71
+ 'live:connected': () => void
72
+ 'host:started': () => void
73
+ }
74
+
75
+ /** A button (or link) in a dock. */
76
+ interface DockItem {
77
+ /** Unique within the dock; also `data-action`. */
78
+ id: string
79
+ /** Used for the button `title` and `aria-label`. */
80
+ title: string
81
+ /** Inline SVG markup. */
82
+ icon?: string
83
+ /** Ascending; default 0. */
84
+ order?: number
85
+ /** Items in different categories get a divider between them. */
86
+ category?: string
87
+ /** Command id run through `ctx.commands`; exactly one of `command` / `href`. */
88
+ command?: string
89
+ /** Rendered as `<a href>` instead of a command button. */
90
+ href?: string
91
+ /** Mirrors `aria-pressed`. */
92
+ isActive?: () => boolean
93
+ }
94
+
95
+ interface DocksItemHandle {
96
+ /** Null until the dock is rendered. */
97
+ element: HTMLElement | null
98
+ /** Re-evaluate `isActive`. */
99
+ update: () => void
100
+ dispose: () => void
101
+ }
102
+
103
+ /** One command, reachable from a shortcut and from the palette. */
104
+ interface DocserveCommand {
105
+ /** Unique; core ids start with `docserve:`, plugins use `plugin:<id>:<name>`. */
106
+ id: string
107
+ /** Palette row text and dock `title`. */
108
+ title: string
109
+ /** Optional palette subtitle. */
110
+ description?: string
111
+ /** Optional palette section heading. */
112
+ category?: string
113
+ /** Inline SVG markup, shared with dock items. */
114
+ icon?: string
115
+ /** Normalized shortcuts: `"Mod+K"`, `"Alt+B"`, `"Shift+C"`, `"["`. */
116
+ keys?: string[]
117
+ /** Default true; `false` keeps it out of the palette. */
118
+ showInPalette?: boolean
119
+ /** False when the command cannot run right now. */
120
+ when?: () => boolean
121
+ /** Runs on shortcut or palette selection. */
122
+ run: (ctx: DocserveContext) => void | Promise<void>
123
+ }
124
+
125
+ /** Command registry plus the palette it feeds. */
126
+ interface CommandsContext {
127
+ /** Throws on a duplicate id; the result unregisters. */
128
+ register: (command: DocserveCommand) => () => void
129
+ /** Rejects when the id is unknown or `when()` is false. */
130
+ run: (id: string) => Promise<void>
131
+ /** Available commands, in registration order. */
132
+ list: () => DocserveCommand[]
133
+ palette: {
134
+ open: () => void
135
+ close: () => void
136
+ toggle: () => void
137
+ isOpen: () => boolean
138
+ }
139
+ }
140
+
141
+ /** The single dock. Plugins register and remove items; only core owns the container. */
142
+ interface DocksContext {
143
+ element: HTMLElement
144
+ /** Throws on a duplicate id; the returned handle can update or dispose the item. */
145
+ register: (item: DockItem) => DocksItemHandle
146
+ /** Removes a single item by id. */
147
+ remove: (id: string) => void
148
+ /** Items currently mounted, in render order. */
149
+ items: () => DockItem[]
150
+ }
151
+
152
+ /**
153
+ * In-page method bus. Plugins never import each other; they talk through this.
154
+ * `docserve:` is reserved for core methods, plugins use `plugin:<id>:<method>`.
155
+ */
156
+ interface RpcContext {
157
+ /** Throws on a duplicate name. */
158
+ register: (name: string, handler: (...args: any[]) => any) => () => void
159
+ has: (name: string) => boolean
160
+ /** Rejects on an unknown name. */
161
+ call: (name: string, ...args: any[]) => Promise<any>
162
+ }
163
+
164
+ interface UiContext {
165
+ /** Appends a layout-neutral host (`display: contents`) to the shadow root. */
166
+ mountPoint: () => HTMLElement
167
+ /** Adds a `<link>` inside the shadow root once. */
168
+ style: (href: string) => void
169
+ /** Writes to the live region. */
170
+ announce: (message: string) => void
171
+ }
172
+
173
+ /** The only object a plugin receives. */
174
+ interface DocserveContext {
175
+ /** Current page path from `data-page`. */
176
+ page: string
177
+ /** Served folder identity from `data-docs-*`; undefined when unset. */
178
+ docs?: DocsInfo
179
+ rpc: RpcContext
180
+ /** The one dock every plugin contributes items to. */
181
+ docks: DocksContext
182
+ /** Shortcut and palette registry. */
183
+ commands: CommandsContext
184
+ ui: UiContext
185
+ /** Event bus; subscribe with `events.on`. */
186
+ events: EventEmitter<DocserveEvents>
187
+ }
188
+
189
+ /** A plugin. `setup` runs once; its return value runs on teardown. */
190
+ interface DocservePlugin {
191
+ id: string
192
+ setup?: (ctx: DocserveContext) => void | (() => void)
193
+ }
@@ -0,0 +1,214 @@
1
+ // Command registry, key matching and palette state. Every user action is
2
+ // registered once, then reached from a shortcut, the palette or a dock item.
3
+ import { isTyping } from "./lib/dom.js"
4
+
5
+ /** The palette's own command: the only one that fires while the palette is open. */
6
+ export const PALETTE_COMMAND = "docserve:palette"
7
+
8
+ const isMac = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent)
9
+
10
+ /**
11
+ * @param {object} options
12
+ * @param {() => DocserveContext} options.getContext Resolved when a command runs.
13
+ * @returns {{ api: CommandsContext, onChange: (listener: () => void) => () => void, destroy: () => void }}
14
+ */
15
+ export function createCommands({ getContext }) {
16
+ /** @type {Map<string, DocserveCommand>} */
17
+ const commands = new Map()
18
+ /** @type {Set<() => void>} */
19
+ const listeners = new Set()
20
+ let open = false
21
+
22
+ window.addEventListener("keydown", onKeydown, { capture: true })
23
+
24
+ const api = {
25
+ register,
26
+ run,
27
+ list,
28
+ palette: {
29
+ open: openPalette,
30
+ close: closePalette,
31
+ toggle: togglePalette,
32
+ isOpen: () => open,
33
+ },
34
+ }
35
+
36
+ // The palette state and its exclusivity guard live here, so its toggle is
37
+ // registered with them.
38
+ register({
39
+ id: PALETTE_COMMAND,
40
+ title: "Command palette",
41
+ keys: ["Mod+K"],
42
+ showInPalette: false,
43
+ run: () => api.palette.toggle(),
44
+ })
45
+
46
+ return { api, onChange, destroy }
47
+
48
+ /**
49
+ * @param {() => void} listener
50
+ * @returns {() => void}
51
+ */
52
+ function onChange(listener) {
53
+ if (!listener) return () => { }
54
+ listeners.add(listener)
55
+ return () => listeners.delete(listener)
56
+ }
57
+
58
+ /**
59
+ * @param {DocserveCommand} command
60
+ * @returns {() => void}
61
+ */
62
+ function register(command) {
63
+ if (typeof command?.id !== "string" || !command.id) throw new TypeError("commands.register expects an id")
64
+ if (typeof command.title !== "string" || !command.title)
65
+ throw new TypeError(`command ${command.id} expects a title`)
66
+ if (typeof command.run !== "function") throw new TypeError(`command ${command.id} expects run()`)
67
+ if (commands.has(command.id)) throw new Error(`command already registered: ${command.id}`)
68
+
69
+ commands.set(command.id, command)
70
+ notify()
71
+ return () => {
72
+ if (commands.get(command.id) !== command) return
73
+ commands.delete(command.id)
74
+ notify()
75
+ }
76
+ }
77
+
78
+ /**
79
+ * @param {string} id
80
+ * @returns {Promise<void>}
81
+ */
82
+ async function run(id) {
83
+ const command = commands.get(id)
84
+ if (!command) throw new Error(`unknown command: ${id}`)
85
+ if (command.when && !command.when()) throw new Error(`command unavailable: ${id}`)
86
+ await command.run(getContext())
87
+ }
88
+
89
+ /**
90
+ * Commands that can run right now, in registration order.
91
+ * @returns {DocserveCommand[]}
92
+ */
93
+ function list() {
94
+ return [...commands.values()].filter((command) => !command.when || command.when())
95
+ }
96
+
97
+ function notify() {
98
+ for (const listener of listeners) {
99
+ try {
100
+ listener()
101
+ } catch (error) {
102
+ console.error("[docserve] command listener failed", error)
103
+ }
104
+ }
105
+ }
106
+
107
+ function openPalette() {
108
+ if (open) return
109
+ open = true
110
+ notify()
111
+ }
112
+
113
+ function closePalette() {
114
+ if (!open) return
115
+ open = false
116
+ notify()
117
+ }
118
+
119
+ function togglePalette() {
120
+ if (open) closePalette()
121
+ else openPalette()
122
+ }
123
+
124
+ /**
125
+ * @param {KeyboardEvent} event
126
+ */
127
+ function onKeydown(event) {
128
+ if (event.defaultPrevented || event.isComposing) return
129
+
130
+ // While the palette is up it owns every key except its own toggle.
131
+ const pressed = normalizeKey(event)
132
+ if (!pressed) return
133
+ if (open && !sameKey(pressed, toggleKey())) return
134
+
135
+ // A bare letter belongs to the page unless it is typing into a field.
136
+ if (isTyping(event.target) && !pressed.includes("+")) return
137
+
138
+ for (const command of list()) {
139
+ if (!command.keys?.some((key) => sameKey(key, pressed))) continue
140
+ event.preventDefault()
141
+ event.stopPropagation()
142
+ run(command.id).catch((error) => console.error(`[docserve] command failed: ${command.id}`, error))
143
+ return
144
+ }
145
+ }
146
+
147
+ function toggleKey() {
148
+ const command = commands.get(PALETTE_COMMAND)
149
+ return command?.keys?.[0] ?? ""
150
+ }
151
+
152
+ // Events report letters uppercased (`C`); bindings are written naturally (`c`).
153
+ /**
154
+ * @param {string} a
155
+ * @param {string} b
156
+ * @returns {boolean}
157
+ */
158
+ function sameKey(a, b) {
159
+ return a.toUpperCase() === b.toUpperCase()
160
+ }
161
+
162
+ function destroy() {
163
+ window.removeEventListener("keydown", onKeydown, { capture: true })
164
+ commands.clear()
165
+ listeners.clear()
166
+ open = false
167
+ }
168
+ }
169
+
170
+ /**
171
+ * Shortcut string for a keyboard event: `Mod+K`, `Alt+B`, `Shift+C`, `[`.
172
+ * Letters come from `event.code`, so Option-modified keys on macOS (where
173
+ * `event.key` becomes `∫`) still match their physical key.
174
+ * @param {KeyboardEvent} event
175
+ * @returns {string} empty for modifier-only presses
176
+ */
177
+ export function normalizeKey(event) {
178
+ /** @type {string[]} */
179
+ const parts = []
180
+ if (isMac ? event.metaKey : event.ctrlKey) parts.push("Mod")
181
+ if (event.altKey) parts.push("Alt")
182
+ if (event.shiftKey) parts.push("Shift")
183
+
184
+ const key = mainKey(event)
185
+ if (!key) return ""
186
+ parts.push(key)
187
+ return parts.join("+")
188
+ }
189
+
190
+ /**
191
+ * @param {KeyboardEvent} event
192
+ * @returns {string}
193
+ */
194
+ function mainKey(event) {
195
+ const key = event.key ?? ""
196
+ if (key.length === 1 && /[ -~]/.test(key)) return /[a-z]/i.test(key) ? key.toUpperCase() : key
197
+
198
+ const code = event.code ?? ""
199
+ const letter = /^Key([A-Z])$/.exec(code)
200
+ if (letter) return letter[1]
201
+ const digit = /^Digit([0-9])$/.exec(code)
202
+ if (digit) return digit[1]
203
+
204
+ return ["Control", "Meta", "Alt", "Shift", "Unidentified"].includes(key) ? "" : key
205
+ }
206
+
207
+ /** `Mod+K` → `⌘K` on macOS, `Ctrl+K` elsewhere. */
208
+ export function formatKey(key) {
209
+ const names = isMac ? { Mod: "\u2318", Shift: "\u21e7", Alt: "\u2325" } : { Mod: "Ctrl+", Shift: "Shift+", Alt: "Alt+" }
210
+ return key
211
+ .split("+")
212
+ .map((part) => /** @type {Record<string,string>} */(names)[part] ?? part)
213
+ .join(isMac ? "" : "")
214
+ }