@noy4/docserve 0.3.1 → 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.
- package/bin.mjs +2 -2
- package/dist/widget/index.js +11155 -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/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 +105 -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/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 +14 -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/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 +193 -0
- package/server/files.mjs +0 -233
- package/server/index.mjs +0 -189
- 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,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
|
+
}
|