@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.
- package/bin.mjs +2 -2
- package/dist/widget/index.js +11803 -0
- package/package.json +24 -3
- package/src/node/adapter.mjs +67 -0
- package/src/node/assets.mjs +36 -0
- package/src/node/dates.mjs +73 -0
- package/src/node/docs-info.mjs +39 -0
- package/src/node/files.mjs +43 -0
- package/src/node/gallery.mjs +33 -0
- package/src/node/inject.mjs +43 -0
- package/src/node/meta.mjs +137 -0
- package/src/node/routes.mjs +105 -0
- package/src/node/scan.mjs +87 -0
- package/src/node/serve-static.mjs +158 -0
- package/src/node/server.mjs +69 -0
- package/src/node/watch.mjs +119 -0
- package/src/plugins/collapse/client.js +45 -0
- package/src/plugins/collapse/collapse.css +74 -0
- package/src/plugins/collapse/commands.ts +81 -0
- package/src/plugins/collapse/model.ts +123 -0
- package/src/plugins/collapse/sections.ts +105 -0
- package/src/plugins/collapse/view.ts +84 -0
- package/src/plugins/copy/client.js +72 -0
- package/src/plugins/copy/copy.css +21 -0
- package/src/plugins/home/client.js +24 -0
- package/src/plugins/sidebar/client.js +106 -0
- package/src/plugins/sidebar/grouping.js +108 -0
- package/src/plugins/sidebar/icons.js +25 -0
- package/src/plugins/sidebar/model.ts +91 -0
- package/src/plugins/sidebar/resize-model.ts +47 -0
- package/src/plugins/sidebar/sidebar.css +663 -0
- package/src/plugins/sidebar/tree-model.ts +23 -0
- package/src/plugins/sidebar/tree.ts +69 -0
- package/src/plugins/sidebar/ui/PageList.tsx +153 -0
- package/src/plugins/sidebar/ui/RadioMenu.tsx +201 -0
- package/src/plugins/sidebar/ui/Sidebar.tsx +95 -0
- package/src/plugins/sidebar/ui/SidebarHeader.tsx +87 -0
- package/src/plugins/sidebar/ui/TreeList.tsx +121 -0
- package/src/plugins/sidebar/ui/preview-model.ts +134 -0
- package/src/plugins/sidebar/ui/useModel.ts +25 -0
- package/src/plugins/toc/client.js +55 -0
- package/src/plugins/toc/commands.ts +49 -0
- package/src/plugins/toc/heading-html.ts +40 -0
- package/src/plugins/toc/model.ts +178 -0
- package/src/plugins/toc/outline.js +94 -0
- package/src/plugins/toc/scroll-spy.ts +35 -0
- package/src/plugins/toc/toc.css +214 -0
- package/src/plugins/toc/ui/TocPanel.tsx +87 -0
- package/src/shared/types.d.ts +193 -0
- package/src/widget/commands.js +214 -0
- package/src/widget/docks.js +127 -0
- package/src/widget/host.js +187 -0
- package/src/widget/index.js +22 -0
- package/src/widget/lib/disposables.js +44 -0
- package/src/widget/lib/dom.js +106 -0
- package/src/widget/lib/events.js +65 -0
- package/src/widget/lib/headings.js +132 -0
- package/src/widget/lib/persisted-signal.js +40 -0
- package/src/widget/lib/storage.js +70 -0
- package/src/widget/live.js +86 -0
- package/src/widget/pages.js +65 -0
- package/src/widget/palette.css +162 -0
- package/src/widget/palette.js +259 -0
- package/src/widget/placement.js +204 -0
- package/src/widget/plugins.js +39 -0
- package/src/widget/rpc.js +32 -0
- package/src/widget/styles.js +31 -0
- package/src/widget/ui.js +50 -0
- package/src/widget/widget.css +206 -0
- package/server/files.mjs +0 -261
- package/server/index.mjs +0 -198
- package/server/inject.html +0 -88
- package/server/inject.mjs +0 -28
- package/server/watch.mjs +0 -104
- /package/{server → src/node}/state.mjs +0 -0
- /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
|
+
}
|