@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,86 @@
1
+ // Live reload over the server's /__reload websocket, with reconnect backoff.
2
+
3
+ /**
4
+ * @typedef {object} LiveHandle
5
+ * @property {() => void} close
6
+ * @property {() => boolean} isOpen
7
+ */
8
+
9
+ /**
10
+ * Subscribe to reload events. Reconnects with exponential backoff; a dropped
11
+ * socket never reloads the page by itself.
12
+ * @param {object} options
13
+ * @param {string} [options.path]
14
+ * @param {(message: LiveMessage) => void} options.onMessage
15
+ * @param {() => void} [options.onOpen]
16
+ * @returns {LiveHandle}
17
+ */
18
+ export function connectLive({ path = "/__reload", onMessage, onOpen }) {
19
+ const MIN_DELAY = 500
20
+ const MAX_DELAY = 10000
21
+
22
+ /** @type {WebSocket | null} */
23
+ let socket = null
24
+ let delay = MIN_DELAY
25
+ /** @type {ReturnType<typeof setTimeout> | null} */
26
+ let timer = null
27
+ let closed = false
28
+
29
+ open()
30
+
31
+ return {
32
+ close() {
33
+ closed = true
34
+ if (timer) clearTimeout(timer)
35
+ timer = null
36
+ socket?.close()
37
+ socket = null
38
+ },
39
+ isOpen() {
40
+ return socket?.readyState === WebSocket.OPEN
41
+ },
42
+ }
43
+
44
+ function open() {
45
+ if (closed) return
46
+ const proto = location.protocol === "https:" ? "wss:" : "ws:"
47
+ const ws = new WebSocket(`${proto}//${location.host}${path}`)
48
+ socket = ws
49
+
50
+ ws.addEventListener("open", () => {
51
+ if (closed) return
52
+ delay = MIN_DELAY
53
+ onOpen?.()
54
+ })
55
+
56
+ ws.addEventListener("message", (event) => {
57
+ if (closed) return
58
+ let message
59
+ try {
60
+ message = JSON.parse(event.data)
61
+ } catch {
62
+ return
63
+ }
64
+ if (message && typeof message === "object") onMessage(message)
65
+ })
66
+
67
+ ws.addEventListener("close", () => {
68
+ if (closed || socket !== ws) return
69
+ socket = null
70
+ schedule()
71
+ })
72
+
73
+ ws.addEventListener("error", () => {
74
+ // A failed connect also fires close; nothing to do here.
75
+ })
76
+ }
77
+
78
+ function schedule() {
79
+ if (closed || timer) return
80
+ timer = setTimeout(() => {
81
+ timer = null
82
+ open()
83
+ }, delay)
84
+ delay = Math.min(delay * 2, MAX_DELAY)
85
+ }
86
+ }
@@ -0,0 +1,65 @@
1
+ // Page listing for the widget: /api/files, cached until a change arrives.
2
+ import { decoded, pageUrl } from "./lib/dom.js"
3
+
4
+ /**
5
+ * @param {{ rpc: RpcContext }} options
6
+ */
7
+ export function createPages({ rpc }) {
8
+ /** @type {DocPage[] | null} */
9
+ let cache = null
10
+ /** @type {Promise<DocPage[]> | null} */
11
+ let pending = null
12
+
13
+ rpc.register("docserve:pages:list", list)
14
+ rpc.register("docserve:pages:resolve", resolve)
15
+
16
+ return {
17
+ list,
18
+ resolve,
19
+ /** Drop the cache so the next read refetches. */
20
+ invalidate() {
21
+ cache = null
22
+ pending = null
23
+ },
24
+ }
25
+
26
+ /**
27
+ * @param {{ force?: boolean }} [options]
28
+ * @returns {Promise<DocPage[]>}
29
+ */
30
+ async function list({ force = false } = {}) {
31
+ if (force) {
32
+ cache = null
33
+ pending = null
34
+ }
35
+ if (cache) return cache
36
+ if (pending) return pending
37
+
38
+ pending = fetch("/api/files", { headers: { accept: "application/json" } })
39
+ .then((response) => {
40
+ if (!response.ok) throw new Error(`/api/files: ${response.status}`)
41
+ return response.json()
42
+ })
43
+ .then((data) => {
44
+ const pages = Array.isArray(data) ? data : []
45
+ cache = pages
46
+ return pages
47
+ })
48
+ .finally(() => {
49
+ pending = null
50
+ })
51
+
52
+ return pending
53
+ }
54
+
55
+ /**
56
+ * Find the page a docs-relative path points at.
57
+ * @param {string} page e.g. `guides/intro.html`
58
+ * @returns {Promise<DocPage | null>}
59
+ */
60
+ async function resolve(page) {
61
+ const target = pageUrl(page)
62
+ const pages = await list()
63
+ return pages.find((entry) => entry.url === target || decoded(entry.url) === `/${page}`) ?? null
64
+ }
65
+ }
@@ -0,0 +1,162 @@
1
+ /* Command palette. Colours come from the host's variables in widget.css. */
2
+
3
+ .docserve-palette {
4
+ display: none;
5
+ position: fixed;
6
+ inset: 0;
7
+ z-index: 2;
8
+ }
9
+
10
+ .docserve-palette[data-open] {
11
+ display: block;
12
+ }
13
+
14
+ .docserve-palette__backdrop {
15
+ position: absolute;
16
+ inset: 0;
17
+ background: rgba(15, 23, 42, 0.28);
18
+ backdrop-filter: blur(2px);
19
+ }
20
+
21
+ .docserve-palette__dialog {
22
+ position: absolute;
23
+ left: 50%;
24
+ top: 18vh;
25
+ transform: translateX(-50%);
26
+ display: flex;
27
+ flex-direction: column;
28
+ width: min(560px, 92vw);
29
+ max-height: 60vh;
30
+ overflow: hidden;
31
+ border: 1px solid var(--docserve-panel-border);
32
+ border-radius: 14px;
33
+ background: var(--docserve-panel-bg);
34
+ color: var(--docserve-panel-text);
35
+ box-shadow: 0 24px 60px rgba(0, 0, 0, 0.28);
36
+ font-size: 14px;
37
+ line-height: 1.45;
38
+ }
39
+
40
+ .docserve-palette__input {
41
+ flex: none;
42
+ width: 100%;
43
+ padding: 14px 16px;
44
+ border: 0;
45
+ border-bottom: 1px solid var(--docserve-panel-border);
46
+ background: transparent;
47
+ color: inherit;
48
+ font: inherit;
49
+ font-size: 15px;
50
+ outline: none;
51
+ }
52
+
53
+ .docserve-palette__list {
54
+ flex: 1;
55
+ margin: 0;
56
+ padding: 6px;
57
+ overflow-y: auto;
58
+ list-style: none;
59
+ }
60
+
61
+ .docserve-palette__row {
62
+ display: flex;
63
+ align-items: center;
64
+ gap: 10px;
65
+ padding: 8px 10px;
66
+ border-radius: 8px;
67
+ cursor: pointer;
68
+ }
69
+
70
+ .docserve-palette__row[aria-selected="true"] {
71
+ background: var(--docserve-dock-accent-soft);
72
+ }
73
+
74
+ .docserve-palette__icon {
75
+ display: grid;
76
+ place-items: center;
77
+ flex: none;
78
+ color: var(--docserve-dock-muted);
79
+ }
80
+
81
+ .docserve-palette__row[aria-selected="true"] .docserve-palette__icon {
82
+ color: var(--docserve-dock-accent);
83
+ }
84
+
85
+ .docserve-palette__icon svg {
86
+ width: 16px;
87
+ height: 16px;
88
+ }
89
+
90
+ .docserve-palette__text {
91
+ display: flex;
92
+ flex: 1;
93
+ flex-direction: column;
94
+ min-width: 0;
95
+ }
96
+
97
+ .docserve-palette__title {
98
+ overflow: hidden;
99
+ white-space: nowrap;
100
+ text-overflow: ellipsis;
101
+ }
102
+
103
+ .docserve-palette__hint {
104
+ overflow: hidden;
105
+ white-space: nowrap;
106
+ text-overflow: ellipsis;
107
+ color: var(--docserve-panel-muted);
108
+ font-size: 12px;
109
+ }
110
+
111
+ .docserve-palette__keys {
112
+ display: flex;
113
+ flex: none;
114
+ gap: 4px;
115
+ }
116
+
117
+ .docserve-palette__key {
118
+ flex: none;
119
+ padding: 0 5px;
120
+ border: 1px solid var(--docserve-panel-border);
121
+ border-radius: 5px;
122
+ color: var(--docserve-dock-muted);
123
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
124
+ font-size: 11px;
125
+ }
126
+
127
+ .docserve-palette__empty {
128
+ display: none;
129
+ margin: 0;
130
+ padding: 24px 16px;
131
+ color: var(--docserve-panel-muted);
132
+ font-size: 13px;
133
+ text-align: center;
134
+ }
135
+
136
+ .docserve-palette__empty[data-visible] {
137
+ display: block;
138
+ }
139
+
140
+ .docserve-palette__footer {
141
+ display: flex;
142
+ flex: none;
143
+ gap: 16px;
144
+ padding: 8px 14px;
145
+ border-top: 1px solid var(--docserve-panel-border);
146
+ color: var(--docserve-panel-muted);
147
+ font-size: 11px;
148
+ }
149
+
150
+ .docserve-palette__legend {
151
+ display: flex;
152
+ align-items: center;
153
+ gap: 4px;
154
+ }
155
+
156
+ .docserve-palette__legend kbd {
157
+ padding: 0 4px;
158
+ border: 1px solid var(--docserve-panel-border);
159
+ border-radius: 4px;
160
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
161
+ font-size: 11px;
162
+ }
@@ -0,0 +1,259 @@
1
+ // Command palette overlay: filter, arrow keys and selection. It owns no
2
+ // state — both the open flag and the registry live in `commands.js`.
3
+ import { formatKey } from "./commands.js"
4
+ import { el } from "./lib/dom.js"
5
+
6
+ /**
7
+ * @param {object} options
8
+ * @param {ShadowRoot} options.root Where the overlay is mounted.
9
+ * @param {UiContext} options.ui
10
+ * @param {CommandsContext} options.commands
11
+ * @param {(listener: () => void) => () => void} options.subscribe
12
+ * @returns {{ open: () => void, close: () => void, destroy: () => void }}
13
+ */
14
+ export function createPalette({ root, ui, commands, subscribe }) {
15
+ const input = /** @type {HTMLInputElement} */ (el("input", {
16
+ class: "docserve-palette__input",
17
+ type: "text",
18
+ role: "combobox",
19
+ "aria-expanded": "true",
20
+ "aria-controls": "docserve-palette-list",
21
+ "aria-autocomplete": "list",
22
+ placeholder: "Type a command…",
23
+ autocomplete: "off",
24
+ spellcheck: "false",
25
+ }))
26
+ const list = el("ul", { class: "docserve-palette__list", id: "docserve-palette-list", role: "listbox" })
27
+ const empty = el("p", { class: "docserve-palette__empty", text: "No matching commands" })
28
+ const dialog = el("div", { class: "docserve-palette__dialog", role: "dialog", "aria-modal": "true", "aria-label": "Commands" }, [
29
+ input,
30
+ list,
31
+ empty,
32
+ el("footer", { class: "docserve-palette__footer" }, [
33
+ hint("↑↓", "select"),
34
+ hint("↵", "run"),
35
+ hint("esc", "close"),
36
+ ]),
37
+ ])
38
+ const backdrop = el("div", { class: "docserve-palette__backdrop" })
39
+ const overlay = el("div", { class: "docserve-palette" }, [backdrop, dialog])
40
+
41
+ root.append(overlay)
42
+ ui.style("/__docserve/widget/palette.css")
43
+
44
+ /** @type {DocserveCommand[]} */
45
+ let items = []
46
+ let index = 0
47
+ let shown = false
48
+ /** @type {Element | null} */
49
+ let previous = null
50
+
51
+ input.addEventListener("input", filter)
52
+ input.addEventListener("keydown", onKeydown)
53
+ backdrop.addEventListener("click", close)
54
+ list.addEventListener("click", (event) => {
55
+ const row = /** @type {HTMLElement | null} */ (/** @type {HTMLElement} */ (event.target).closest("[data-command]"))
56
+ if (row?.dataset.command) activate(row.dataset.command)
57
+ })
58
+
59
+ const off = subscribe(sync)
60
+
61
+ return { destroy, open: openPalette, close }
62
+
63
+ function openPalette() {
64
+ commands.palette.open()
65
+ }
66
+
67
+ function close() {
68
+ commands.palette.close()
69
+ }
70
+
71
+ // Rebuild on any registry change and follow the open flag.
72
+ function sync() {
73
+ const open = commands.palette.isOpen()
74
+ if (open === shown) {
75
+ if (open) filter()
76
+ return
77
+ }
78
+ shown = open
79
+ overlay.toggleAttribute("data-open", open)
80
+ document.documentElement.toggleAttribute("data-docserve-palette", open)
81
+
82
+ if (open) {
83
+ previous = document.activeElement
84
+ input.value = ""
85
+ filter()
86
+ requestAnimationFrame(() => input.focus())
87
+ } else {
88
+ input.value = ""
89
+ restoreFocus()
90
+ previous = null
91
+ }
92
+ }
93
+
94
+ function restoreFocus() {
95
+ if (!(previous instanceof HTMLElement) || !document.contains(previous)) return
96
+ try {
97
+ previous.focus()
98
+ } catch {}
99
+ }
100
+
101
+ function filter() {
102
+ const query = input.value.trim().toLowerCase()
103
+ items = commands
104
+ .list()
105
+ .filter((command) => command.showInPalette !== false)
106
+ .map((command) => ({ command, score: score(command, query) }))
107
+ .filter((entry) => entry.score > 0)
108
+ .sort((a, b) => b.score - a.score)
109
+ .map((entry) => entry.command)
110
+
111
+ index = 0
112
+ render()
113
+ }
114
+
115
+ function render() {
116
+ list.replaceChildren(...items.map(row))
117
+ empty.toggleAttribute("data-visible", items.length === 0)
118
+ mark()
119
+ }
120
+
121
+ /**
122
+ * @param {DocserveCommand} command
123
+ * @returns {HTMLElement}
124
+ */
125
+ function row(command) {
126
+ const keys = command.keys ?? []
127
+ const node = el("li", {
128
+ class: "docserve-palette__row",
129
+ role: "option",
130
+ id: rowId(command.id),
131
+ "data-command": command.id,
132
+ "aria-selected": "false",
133
+ }, [
134
+ command.icon ? el("span", { class: "docserve-palette__icon", html: command.icon }) : null,
135
+ el("span", { class: "docserve-palette__text" }, [
136
+ el("span", { class: "docserve-palette__title", text: command.title }),
137
+ command.description ? el("span", { class: "docserve-palette__hint", text: command.description }) : null,
138
+ ]),
139
+ keys.length
140
+ ? el("span", { class: "docserve-palette__keys" }, keys.map((key) => el("kbd", { class: "docserve-palette__key", text: formatKey(key) })))
141
+ : null,
142
+ ])
143
+ node.addEventListener("pointermove", () => {
144
+ index = items.indexOf(command)
145
+ mark()
146
+ })
147
+ return node
148
+ }
149
+
150
+ function mark() {
151
+ const rows = list.children
152
+ for (let i = 0; i < rows.length; i++) rows[i].setAttribute("aria-selected", String(i === index))
153
+ input.setAttribute("aria-activedescendant", items[index] ? rowId(items[index].id) : "")
154
+ if (items[index]) select(items[index])
155
+ }
156
+
157
+ /**
158
+ * @param {DocserveCommand} command
159
+ */
160
+ function select(command) {
161
+ const node = list.querySelector(`#${CSS.escape(rowId(command.id))}`)
162
+ node?.scrollIntoView({ block: "nearest" })
163
+ }
164
+
165
+ /**
166
+ * @param {KeyboardEvent} event
167
+ */
168
+ function onKeydown(event) {
169
+ if (event.key === "Escape") {
170
+ event.preventDefault()
171
+ event.stopPropagation()
172
+ close()
173
+ return
174
+ }
175
+ if (event.key === "Enter") {
176
+ event.preventDefault()
177
+ const command = items[index]
178
+ if (command) activate(command.id)
179
+ return
180
+ }
181
+
182
+ const step =
183
+ event.key === "ArrowDown" ? 1
184
+ : event.key === "ArrowUp" ? -1
185
+ : event.key === "Home" ? -items.length
186
+ : event.key === "End" ? items.length
187
+ : 0
188
+ if (!step || !items.length) return
189
+ event.preventDefault()
190
+ index = (index + step + items.length) % items.length
191
+ mark()
192
+ }
193
+
194
+ /**
195
+ * @param {string} id
196
+ */
197
+ function activate(id) {
198
+ close()
199
+ commands.run(id).catch((error) => console.error(`[docserve] command failed: ${id}`, error))
200
+ }
201
+
202
+ function destroy() {
203
+ off()
204
+ overlay.remove()
205
+ document.documentElement.removeAttribute("data-docserve-palette")
206
+ }
207
+ }
208
+
209
+ /**
210
+ * Rank a command against the query: title prefix beats word prefix beats
211
+ * substring beats a hint/group match beats a scattered subsequence.
212
+ * @param {DocserveCommand} command
213
+ * @param {string} query
214
+ * @returns {number}
215
+ */
216
+ function score(command, query) {
217
+ if (!query) return 1
218
+ const title = command.title.toLowerCase()
219
+ if (title.startsWith(query)) return 100
220
+ if (title.split(/[\s:/_-]+/).some((word) => word.startsWith(query))) return 80
221
+ if (title.includes(query)) return 60
222
+ if (`${command.description ?? ""} ${command.category ?? ""}`.toLowerCase().includes(query)) return 40
223
+ return subsequence(query, title) ? 20 : 0
224
+ }
225
+
226
+ /**
227
+ * @param {string} needle
228
+ * @param {string} haystack
229
+ * @returns {boolean}
230
+ */
231
+ function subsequence(needle, haystack) {
232
+ let at = 0
233
+ for (const char of needle) {
234
+ at = haystack.indexOf(char, at)
235
+ if (at === -1) return false
236
+ at += 1
237
+ }
238
+ return true
239
+ }
240
+
241
+ /**
242
+ * @param {string} id
243
+ * @returns {string}
244
+ */
245
+ function rowId(id) {
246
+ return `docserve-cmd-${id.replace(/[^\w-]/g, "_")}`
247
+ }
248
+
249
+ /**
250
+ * @param {string} key
251
+ * @param {string} label
252
+ * @returns {HTMLElement}
253
+ */
254
+ function hint(key, label) {
255
+ return el("span", { class: "docserve-palette__legend" }, [
256
+ el("kbd", { text: key }),
257
+ el("span", { text: label }),
258
+ ])
259
+ }