@noy4/docserve 0.3.2 → 0.3.4

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 (76) hide show
  1. package/bin.mjs +2 -2
  2. package/dist/widget/index.js +11803 -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/collapse/client.js +45 -0
  18. package/src/plugins/collapse/collapse.css +74 -0
  19. package/src/plugins/collapse/commands.ts +81 -0
  20. package/src/plugins/collapse/model.ts +123 -0
  21. package/src/plugins/collapse/sections.ts +105 -0
  22. package/src/plugins/collapse/view.ts +84 -0
  23. package/src/plugins/copy/client.js +72 -0
  24. package/src/plugins/copy/copy.css +21 -0
  25. package/src/plugins/home/client.js +24 -0
  26. package/src/plugins/sidebar/client.js +106 -0
  27. package/src/plugins/sidebar/grouping.js +108 -0
  28. package/src/plugins/sidebar/icons.js +25 -0
  29. package/src/plugins/sidebar/model.ts +91 -0
  30. package/src/plugins/sidebar/resize-model.ts +47 -0
  31. package/src/plugins/sidebar/sidebar.css +663 -0
  32. package/src/plugins/sidebar/tree-model.ts +23 -0
  33. package/src/plugins/sidebar/tree.ts +69 -0
  34. package/src/plugins/sidebar/ui/PageList.tsx +153 -0
  35. package/src/plugins/sidebar/ui/RadioMenu.tsx +201 -0
  36. package/src/plugins/sidebar/ui/Sidebar.tsx +95 -0
  37. package/src/plugins/sidebar/ui/SidebarHeader.tsx +87 -0
  38. package/src/plugins/sidebar/ui/TreeList.tsx +121 -0
  39. package/src/plugins/sidebar/ui/preview-model.ts +134 -0
  40. package/src/plugins/sidebar/ui/useModel.ts +25 -0
  41. package/src/plugins/toc/client.js +55 -0
  42. package/src/plugins/toc/commands.ts +49 -0
  43. package/src/plugins/toc/heading-html.ts +40 -0
  44. package/src/plugins/toc/model.ts +178 -0
  45. package/src/plugins/toc/outline.js +94 -0
  46. package/src/plugins/toc/scroll-spy.ts +35 -0
  47. package/src/plugins/toc/toc.css +214 -0
  48. package/src/plugins/toc/ui/TocPanel.tsx +87 -0
  49. package/src/shared/types.d.ts +193 -0
  50. package/src/widget/commands.js +214 -0
  51. package/src/widget/docks.js +127 -0
  52. package/src/widget/host.js +187 -0
  53. package/src/widget/index.js +22 -0
  54. package/src/widget/lib/disposables.js +44 -0
  55. package/src/widget/lib/dom.js +106 -0
  56. package/src/widget/lib/events.js +65 -0
  57. package/src/widget/lib/headings.js +132 -0
  58. package/src/widget/lib/persisted-signal.js +40 -0
  59. package/src/widget/lib/storage.js +70 -0
  60. package/src/widget/live.js +86 -0
  61. package/src/widget/pages.js +65 -0
  62. package/src/widget/palette.css +162 -0
  63. package/src/widget/palette.js +259 -0
  64. package/src/widget/placement.js +204 -0
  65. package/src/widget/plugins.js +39 -0
  66. package/src/widget/rpc.js +32 -0
  67. package/src/widget/styles.js +31 -0
  68. package/src/widget/ui.js +50 -0
  69. package/src/widget/widget.css +206 -0
  70. package/server/files.mjs +0 -261
  71. package/server/index.mjs +0 -198
  72. package/server/inject.html +0 -88
  73. package/server/inject.mjs +0 -28
  74. package/server/watch.mjs +0 -104
  75. /package/{server → src/node}/state.mjs +0 -0
  76. /package/{server → src/node}/websocket.mjs +0 -0
@@ -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
+ }
@@ -0,0 +1,127 @@
1
+ // The docks registry: one pill that every plugin registers items on. An item
2
+ // either runs a command or is a link.
3
+ import { formatKey } from "./commands.js"
4
+ import { el } from "./lib/dom.js"
5
+
6
+ /**
7
+ * Build the dock and mount it into the shadow root.
8
+ * @param {object} options
9
+ * @param {ShadowRoot} options.root
10
+ * @param {() => DocserveContext} options.getContext Resolved when an item is clicked.
11
+ * @returns {DocksContext}
12
+ */
13
+ export function createDocks({ root, getContext }) {
14
+ /** @type {DockItem[]} */
15
+ const items = []
16
+ const element = el("div", { class: "docserve-dock", role: "toolbar", "aria-label": "docserve" })
17
+ /** @type {Map<string, DocksItemHandle>} */
18
+ const handles = new Map()
19
+
20
+ root.append(element)
21
+ render()
22
+
23
+ return {
24
+ element,
25
+ register,
26
+ remove,
27
+ items() {
28
+ return [...items]
29
+ },
30
+ }
31
+
32
+ /**
33
+ * @param {DockItem} item
34
+ * @returns {DocksItemHandle}
35
+ */
36
+ function register(item) {
37
+ if (typeof item?.id !== "string" || !item.id) throw new TypeError("docks.register expects an item with an id")
38
+ if (handles.has(item.id)) throw new Error(`dock item already added: ${item.id}`)
39
+ if (!item.command === !item.href) throw new TypeError(`dock item ${item.id} needs exactly one of command or href`)
40
+
41
+ const handle = {
42
+ /** @type {HTMLElement | null} */
43
+ element: null,
44
+ update() {
45
+ syncDockItem(handle.element, item)
46
+ },
47
+ dispose() {
48
+ remove(item.id)
49
+ },
50
+ }
51
+ handles.set(item.id, handle)
52
+ items.push(item)
53
+ render()
54
+ return handle
55
+ }
56
+
57
+ /**
58
+ * @param {string} id
59
+ */
60
+ function remove(id) {
61
+ const index = items.findIndex((item) => item.id === id)
62
+ if (index === -1) return
63
+ items.splice(index, 1)
64
+ handles.delete(id)
65
+ render()
66
+ }
67
+
68
+ function render() {
69
+ element.replaceChildren()
70
+ let previousCategory
71
+ let first = true
72
+
73
+ for (const item of sorted()) {
74
+ if (!first && item.category != null && previousCategory != null && item.category !== previousCategory)
75
+ element.append(el("span", { class: "docserve-dock__divider", "aria-hidden": "true" }))
76
+ first = false
77
+ previousCategory = item.category
78
+
79
+ const node = createDockItem(item, getContext())
80
+ const handle = handles.get(item.id)
81
+ if (handle) handle.element = node
82
+ element.append(node)
83
+ }
84
+ }
85
+
86
+ function sorted() {
87
+ return [...items].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
88
+ }
89
+ }
90
+
91
+ /**
92
+ * Build one dock item: a command button, or a link when `href` is set.
93
+ * @param {DockItem} item
94
+ * @param {DocserveContext} ctx
95
+ * @returns {HTMLElement}
96
+ */
97
+ function createDockItem(item, ctx) {
98
+ const keys = item.command ? ctx.commands.list().find((command) => command.id === item.command)?.keys ?? [] : []
99
+ const props = {
100
+ class: "docserve-dock__button",
101
+ title: keys.length ? `${item.title} (${keys.map(formatKey).join(" / ")})` : item.title,
102
+ "aria-label": item.title,
103
+ "data-action": item.id,
104
+ html: item.icon ?? "",
105
+ }
106
+ const node = item.href
107
+ ? el("a", { ...props, href: item.href })
108
+ : el("button", { ...props, type: "button" })
109
+
110
+ syncDockItem(node, item)
111
+ if (!item.href) {
112
+ node.addEventListener("click", () => {
113
+ ctx.commands.run(/** @type {string} */ (item.command)).catch((error) => console.error(`[docserve] dock command failed: ${item.command}`, error))
114
+ })
115
+ }
116
+ return node
117
+ }
118
+
119
+ /**
120
+ * Reflect `isActive` onto `aria-pressed`.
121
+ * @param {HTMLElement | null} node
122
+ * @param {DockItem} item
123
+ */
124
+ function syncDockItem(node, item) {
125
+ if (!node || !item.isActive) return
126
+ node.setAttribute("aria-pressed", String(Boolean(item.isActive())))
127
+ }
@@ -0,0 +1,187 @@
1
+ // Widget host
2
+ import { createCommands } from "./commands.js"
3
+ import { createDocks } from "./docks.js"
4
+ import { el } from "./lib/dom.js"
5
+ import { createEventEmitter } from "./lib/events.js"
6
+ import { connectLive } from "./live.js"
7
+ import { createPages } from "./pages.js"
8
+ import { createPalette } from "./palette.js"
9
+ import { createPlacement } from "./placement.js"
10
+ import { createPlugins } from "./plugins.js"
11
+ import { createRpc } from "./rpc.js"
12
+ import { reloadStyles, settled } from "./styles.js"
13
+ import { createUi } from "./ui.js"
14
+
15
+ /**
16
+ * Create the widget without mounting it.
17
+ * @returns {{ ctx: DocserveContext, start: () => DocserveContext, stop: () => void, use: (plugin: DocservePlugin) => DocserveContext }}
18
+ */
19
+ export function createHost() {
20
+ const script = injectedScript()
21
+ const page = resolvePage(script)
22
+ const docs = resolveDocs(script)
23
+
24
+ // element
25
+ const { host, root, status, reveal } = mount()
26
+
27
+ // lifecycle state
28
+ /** @type {ReturnType<typeof connectLive> | null} */
29
+ let live = null
30
+ let mounted = false
31
+
32
+ // transport
33
+ const rpc = createRpc()
34
+ const pages = createPages({ rpc })
35
+ const events = createEventEmitter()
36
+
37
+ // context is filled below, services resolve it when called
38
+ const getContext = () => ctx
39
+
40
+ // commands
41
+ const commands = createCommands({ getContext })
42
+
43
+ // interface
44
+ const ui = createUi({ root, status })
45
+ const docks = createDocks({ root, getContext })
46
+ const placement = createPlacement({ host, handle: docks.element })
47
+ const palette = createPalette({
48
+ root,
49
+ ui,
50
+ commands: commands.api,
51
+ subscribe: commands.onChange,
52
+ })
53
+
54
+ // plugins
55
+ const { use, dispose } = createPlugins(getContext)
56
+
57
+ // context
58
+ /** @type {DocserveContext} */
59
+ const ctx = {
60
+ page,
61
+ docs,
62
+ rpc,
63
+ docks,
64
+ commands: commands.api,
65
+ ui,
66
+ events,
67
+ }
68
+
69
+ return { ctx, start, stop, use }
70
+
71
+ // ---
72
+
73
+ function start() {
74
+ if (mounted) return ctx
75
+ mounted = true
76
+
77
+ document.documentElement.toggleAttribute("data-docserve-widget", true)
78
+ document.body.append(host)
79
+ reveal()
80
+ events.emit("host:started")
81
+
82
+ live = connectLive({
83
+ onOpen() {
84
+ pages.invalidate()
85
+ events.emit("live:connected")
86
+ },
87
+ onMessage: onLiveMessage,
88
+ })
89
+ return ctx
90
+ }
91
+
92
+ function stop() {
93
+ live?.close()
94
+ live = null
95
+ if (mounted) {
96
+ // reverse order
97
+ placement.destroy()
98
+ palette.destroy()
99
+ commands.destroy()
100
+ document.documentElement.toggleAttribute("data-docserve-widget", false)
101
+ host.toggleAttribute("data-ready", false)
102
+ host.remove()
103
+ mounted = false
104
+ }
105
+ dispose()
106
+ }
107
+
108
+ /**
109
+ * @param {LiveMessage} message
110
+ */
111
+ function onLiveMessage(message) {
112
+ switch (message.type) {
113
+ case "css":
114
+ reloadStyles([document, root])
115
+ return
116
+ case "change":
117
+ onContentChange(message)
118
+ return
119
+ }
120
+ }
121
+
122
+ /**
123
+ * @param {ChangeMessage} message
124
+ */
125
+ function onContentChange(message) {
126
+ if (message.contentSetChanged || message.pages.length)
127
+ pages.invalidate()
128
+ events.emit("pages:changed", message)
129
+
130
+ // only reload when this page or the gallery template changed
131
+ if (message.pages.includes(page) || message.templateChanged)
132
+ location.reload()
133
+ }
134
+ }
135
+
136
+ // Inline `<style>` in the shadow root: keeps the host out of the layout and
137
+ // hidden until `reveal()` sets `data-ready`. The rules after it are only a
138
+ // fallback for a stylesheet that never loads.
139
+ const CRITICAL_CSS = [
140
+ ":host{display:none;position:fixed;right:16px;bottom:16px;z-index:2147483647;margin:0;padding:0;line-height:0}",
141
+ ":host([data-ready]){display:block}",
142
+ ".docserve-dock{display:flex;align-items:center}",
143
+ ".docserve-dock__button{display:grid;place-items:center;width:30px;height:30px;padding:0;border:0;background:none;color:inherit}",
144
+ ".docserve-dock__status{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}",
145
+ ].join("")
146
+
147
+ /** Shadow host, its root, the live region and the reveal hook. */
148
+ function mount() {
149
+ const host = el("div", { id: "docserve-dock-host", "data-docserve-widget": "" })
150
+ const root = host.attachShadow({ mode: "open" })
151
+ root.append(el("style", { text: CRITICAL_CSS }))
152
+ const status = el("span", { class: "docserve-dock__status", role: "status", "aria-live": "polite" })
153
+ root.append(status)
154
+ return { host, root, status, reveal }
155
+
156
+ // Show the widget only once its stylesheets are applied, so nothing appears
157
+ // unstyled. The timeout covers a stylesheet that never settles.
158
+ function reveal() {
159
+ const done = () => host.toggleAttribute("data-ready", true)
160
+ const links = [...root.querySelectorAll('link[rel~="stylesheet"]')]
161
+ Promise.all(links.map(settled)).then(done)
162
+ setTimeout(done, 500)
163
+ }
164
+ }
165
+
166
+ /** The injected module script, when the page was served by docserve. */
167
+ function injectedScript() {
168
+ return /** @type {HTMLScriptElement | null} */ (
169
+ document.querySelector('script[src="/__docserve/widget/index.js"]')
170
+ )
171
+ }
172
+
173
+ /** docs-relative path of the page being viewed */
174
+ function resolvePage(script) {
175
+ const page = script?.getAttribute("data-page")
176
+ if (page) return page
177
+ return location.pathname.replace(/^\//, "")
178
+ }
179
+
180
+ /** Served folder identity from `data-docs-*`; undefined outside docserve. */
181
+ function resolveDocs(script) {
182
+ const name = script?.getAttribute("data-docs-name") || ""
183
+ const path = script?.getAttribute("data-docs-path") || ""
184
+ if (!name && !path) return undefined
185
+ const hue = Number(script?.getAttribute("data-docs-hue"))
186
+ return { name: name || path, path: path || name, hue: Number.isFinite(hue) ? hue : 0 }
187
+ }
@@ -0,0 +1,22 @@
1
+ // Widget entry: register the built-in plugins, then start.
2
+ import { collapsePlugin } from "../plugins/collapse/client.js"
3
+ import { copyPlugin } from "../plugins/copy/client.js"
4
+ import { homePlugin } from "../plugins/home/client.js"
5
+ import { sidebarPlugin } from "../plugins/sidebar/client.js"
6
+ import { tocPlugin } from "../plugins/toc/client.js"
7
+ import { createHost } from "./host.js"
8
+
9
+ const PLUGINS = [
10
+ homePlugin,
11
+ collapsePlugin,
12
+ copyPlugin,
13
+ sidebarPlugin,
14
+ tocPlugin,
15
+ ]
16
+
17
+ // The server skips iframe previews; this guard covers pages served some other way.
18
+ if (window.self === window.top && !document.getElementById("docserve-dock-host")) {
19
+ const widget = createHost()
20
+ for (const plugin of PLUGINS) widget.use(plugin())
21
+ widget.start()
22
+ }
@@ -0,0 +1,44 @@
1
+ // Collect teardown callbacks so a setup can close everything in one place.
2
+
3
+ /**
4
+ * @typedef {object} Disposables
5
+ * @property {(dispose: () => void) => void} add Run immediately when already disposed.
6
+ * @property {() => void} dispose Idempotent; newest callback first.
7
+ */
8
+
9
+ /**
10
+ * @returns {Disposables}
11
+ */
12
+ export function createDisposables() {
13
+ /** @type {(() => void)[]} */
14
+ const callbacks = []
15
+ let done = false
16
+
17
+ return {
18
+ add(dispose) {
19
+ if (typeof dispose !== "function") throw new TypeError("disposables.add expects a function")
20
+ if (done) {
21
+ safeRun(dispose)
22
+ return
23
+ }
24
+ callbacks.push(dispose)
25
+ },
26
+ dispose() {
27
+ if (done) return
28
+ done = true
29
+ for (let i = callbacks.length - 1; i >= 0; i--) safeRun(callbacks[i])
30
+ callbacks.length = 0
31
+ },
32
+ }
33
+ }
34
+
35
+ /**
36
+ * @param {() => void} dispose
37
+ */
38
+ function safeRun(dispose) {
39
+ try {
40
+ dispose()
41
+ } catch (err) {
42
+ console.error(err)
43
+ }
44
+ }
@@ -0,0 +1,106 @@
1
+ // DOM helpers
2
+
3
+ /**
4
+ * Create an element. `class`, `text`, `html` and object `style` are special;
5
+ * `on*` keys attach listeners; anything else becomes an attribute.
6
+ * @param {string} tag
7
+ * @param {Record<string, any>} [props]
8
+ * @param {Node | string | null | false | (Node | string | null | false)[]} [children]
9
+ * @returns {HTMLElement}
10
+ */
11
+ export function el(tag, props = {}, children = []) {
12
+ const node = document.createElement(tag)
13
+ for (const [key, value] of Object.entries(props)) {
14
+ if (value == null || value === false) continue
15
+ if (key === "class") node.className = value
16
+ else if (key === "text") node.textContent = value
17
+ else if (key === "html") node.innerHTML = value
18
+ else if (key === "style" && typeof value === "object") Object.assign(node.style, value)
19
+ else if (key.startsWith("on") && typeof value === "function")
20
+ node.addEventListener(key.slice(2).toLowerCase(), value)
21
+ else node.setAttribute(key, value === true ? "" : String(value))
22
+ }
23
+ for (const child of Array.isArray(children) ? children : [children]) {
24
+ if (child == null || child === false) continue
25
+ node.append(child)
26
+ }
27
+ return /** @type {HTMLElement} */ (node)
28
+ }
29
+
30
+ /**
31
+ * Mark inline SVG as decorative and optionally add a class.
32
+ * @param {string} svg `<svg …>…</svg>` markup.
33
+ * @param {string} [name]
34
+ * @returns {string}
35
+ */
36
+ export function iconSvg(svg, name = "") {
37
+ const cls = name ? ` class="${name}"` : ""
38
+ return svg.replace("<svg ", `<svg aria-hidden="true"${cls} `)
39
+ }
40
+
41
+ /**
42
+ * Unix seconds or a parseable date → `YYYY/MM/DD`, or `""` when invalid.
43
+ * @param {number | string} value
44
+ * @returns {string}
45
+ */
46
+ export function displayDate(value) {
47
+ const date = new Date(typeof value === "number" ? value * 1000 : value)
48
+ if (Number.isNaN(date.getTime())) return ""
49
+ const y = date.getFullYear()
50
+ const m = String(date.getMonth() + 1).padStart(2, "0")
51
+ const d = String(date.getDate()).padStart(2, "0")
52
+ return `${y}/${m}/${d}`
53
+ }
54
+
55
+ /**
56
+ * Docs-relative path → root-absolute URL, encoding each segment.
57
+ * @param {string} path e.g. `guides/intro.html`
58
+ * @returns {string}
59
+ */
60
+ export function pageUrl(path) {
61
+ return `/${path.split("/").map(encodeURIComponent).join("/")}`
62
+ }
63
+
64
+ /**
65
+ * Decode a URL, falling back to the input when it is malformed.
66
+ * @param {string} url
67
+ * @returns {string}
68
+ */
69
+ export function decoded(url) {
70
+ try {
71
+ return decodeURIComponent(url)
72
+ } catch {
73
+ return url
74
+ }
75
+ }
76
+
77
+ /**
78
+ * True when the event target takes text input, so shortcuts must stay out.
79
+ * @param {EventTarget | null} target
80
+ * @returns {boolean}
81
+ */
82
+ export function isTyping(target) {
83
+ if (!(target instanceof HTMLElement)) return false
84
+ return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName)
85
+ }
86
+
87
+ /**
88
+ * Copy text to the clipboard, falling back to a hidden textarea.
89
+ * @param {string} text
90
+ * @returns {Promise<void>}
91
+ */
92
+ export async function writeClipboard(text) {
93
+ if (navigator.clipboard?.writeText) {
94
+ await navigator.clipboard.writeText(text)
95
+ return
96
+ }
97
+ const area = /** @type {HTMLTextAreaElement} */ (el("textarea", { readonly: "" }))
98
+ area.style.position = "fixed"
99
+ area.style.top = "-9999px"
100
+ area.value = text
101
+ document.body.append(area)
102
+ area.select()
103
+ const ok = document.execCommand("copy")
104
+ area.remove()
105
+ if (!ok) throw new Error("copy failed")
106
+ }