@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,35 @@
|
|
|
1
|
+
import type { TocModel } from "./model.js"
|
|
2
|
+
import { HEADING_OFFSET } from "./model.js"
|
|
3
|
+
|
|
4
|
+
export function startScrollSpy(model: TocModel, offset = HEADING_OFFSET): () => void {
|
|
5
|
+
const controller = new AbortController()
|
|
6
|
+
let frame = 0
|
|
7
|
+
|
|
8
|
+
window.addEventListener("scroll", schedule, { passive: true, signal: controller.signal })
|
|
9
|
+
window.addEventListener("resize", schedule, { passive: true, signal: controller.signal })
|
|
10
|
+
|
|
11
|
+
schedule()
|
|
12
|
+
|
|
13
|
+
return () => {
|
|
14
|
+
controller.abort()
|
|
15
|
+
if (frame) cancelAnimationFrame(frame)
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function schedule(): void {
|
|
19
|
+
if (frame) return
|
|
20
|
+
frame = requestAnimationFrame(() => {
|
|
21
|
+
frame = 0
|
|
22
|
+
update()
|
|
23
|
+
})
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function update(): void {
|
|
27
|
+
const headings = model.headings.value
|
|
28
|
+
let current = headings[0] ?? null
|
|
29
|
+
for (const heading of headings) {
|
|
30
|
+
if (heading.getBoundingClientRect().top > offset) break
|
|
31
|
+
current = heading
|
|
32
|
+
}
|
|
33
|
+
model.setActive(current?.id ?? null)
|
|
34
|
+
}
|
|
35
|
+
}
|
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
.docserve-toc,
|
|
2
|
+
.docserve-toc * {
|
|
3
|
+
box-sizing: border-box;
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
.docserve-toc {
|
|
7
|
+
position: fixed;
|
|
8
|
+
top: 96px;
|
|
9
|
+
left: max(16px, calc(100% - var(--docserve-panel-right, 0px)));
|
|
10
|
+
z-index: 1;
|
|
11
|
+
display: flex;
|
|
12
|
+
flex-direction: column;
|
|
13
|
+
width: 200px;
|
|
14
|
+
max-height: calc(100vh - 128px);
|
|
15
|
+
color: var(--docserve-panel-text);
|
|
16
|
+
font-size: 12px;
|
|
17
|
+
line-height: 1.5;
|
|
18
|
+
opacity: 0;
|
|
19
|
+
visibility: hidden;
|
|
20
|
+
transform: translateX(12px);
|
|
21
|
+
transition:
|
|
22
|
+
opacity 0.18s ease,
|
|
23
|
+
transform 0.18s ease,
|
|
24
|
+
visibility 0.18s ease;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
.docserve-toc[data-open] {
|
|
28
|
+
opacity: 1;
|
|
29
|
+
visibility: visible;
|
|
30
|
+
transform: translateX(0);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
.docserve-toc__head {
|
|
34
|
+
display: flex;
|
|
35
|
+
flex-shrink: 0;
|
|
36
|
+
align-items: center;
|
|
37
|
+
justify-content: space-between;
|
|
38
|
+
gap: 8px;
|
|
39
|
+
padding: 0 0 8px;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
.docserve-toc__title {
|
|
43
|
+
min-width: 0;
|
|
44
|
+
overflow: hidden;
|
|
45
|
+
color: var(--docserve-panel-text);
|
|
46
|
+
font-size: 14px;
|
|
47
|
+
font-weight: 600;
|
|
48
|
+
text-overflow: ellipsis;
|
|
49
|
+
white-space: nowrap;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
.docserve-toc__close {
|
|
53
|
+
display: grid;
|
|
54
|
+
flex-shrink: 0;
|
|
55
|
+
place-items: center;
|
|
56
|
+
width: 22px;
|
|
57
|
+
height: 22px;
|
|
58
|
+
padding: 0;
|
|
59
|
+
border: 0;
|
|
60
|
+
border-radius: 6px;
|
|
61
|
+
background: transparent;
|
|
62
|
+
color: var(--docserve-panel-muted);
|
|
63
|
+
font: inherit;
|
|
64
|
+
line-height: 0;
|
|
65
|
+
opacity: 0;
|
|
66
|
+
visibility: hidden;
|
|
67
|
+
appearance: none;
|
|
68
|
+
transition:
|
|
69
|
+
opacity 0.15s ease,
|
|
70
|
+
visibility 0.15s ease,
|
|
71
|
+
background-color 0.15s ease,
|
|
72
|
+
color 0.15s ease;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
.docserve-toc:hover .docserve-toc__close,
|
|
76
|
+
.docserve-toc:focus-within .docserve-toc__close {
|
|
77
|
+
opacity: 1;
|
|
78
|
+
visibility: visible;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
.docserve-toc__close svg {
|
|
82
|
+
width: 14px;
|
|
83
|
+
height: 14px;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
.docserve-toc__close:hover {
|
|
87
|
+
background: color-mix(in srgb, var(--docserve-panel-text) 8%, transparent);
|
|
88
|
+
color: var(--docserve-panel-text);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
.docserve-toc__close:focus-visible {
|
|
92
|
+
outline: 2px solid var(--docserve-dock-accent);
|
|
93
|
+
outline-offset: 2px;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
.docserve-toc__scroll {
|
|
97
|
+
flex: 1;
|
|
98
|
+
min-height: 0;
|
|
99
|
+
padding: 0 4px 4px 0;
|
|
100
|
+
overflow-x: hidden;
|
|
101
|
+
overflow-y: auto;
|
|
102
|
+
overscroll-behavior: contain;
|
|
103
|
+
scrollbar-width: thin;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
.docserve-toc__scroll::-webkit-scrollbar {
|
|
107
|
+
width: 8px;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
.docserve-toc__scroll::-webkit-scrollbar-thumb {
|
|
111
|
+
border: 2px solid transparent;
|
|
112
|
+
border-radius: 999px;
|
|
113
|
+
background: color-mix(in srgb, var(--docserve-panel-muted) 40%, transparent);
|
|
114
|
+
background-clip: content-box;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
.docserve-toc__content {
|
|
118
|
+
position: relative;
|
|
119
|
+
border-left: 1px solid var(--docserve-panel-border);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
.docserve-toc__marker {
|
|
123
|
+
position: absolute;
|
|
124
|
+
top: 0;
|
|
125
|
+
left: -1px;
|
|
126
|
+
width: 2px;
|
|
127
|
+
height: 18px;
|
|
128
|
+
border-radius: 2px;
|
|
129
|
+
background: var(--docserve-dock-accent);
|
|
130
|
+
opacity: 0;
|
|
131
|
+
pointer-events: none;
|
|
132
|
+
transition:
|
|
133
|
+
transform 0.25s cubic-bezier(0, 1, 0.5, 1),
|
|
134
|
+
opacity 0.15s ease;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
.docserve-toc__list {
|
|
138
|
+
margin: 0;
|
|
139
|
+
padding: 0;
|
|
140
|
+
list-style: none;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
.docserve-toc__list .docserve-toc__list {
|
|
144
|
+
padding-left: 12px;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
.docserve-toc__link {
|
|
148
|
+
display: block;
|
|
149
|
+
padding: 3px 8px 3px 11px;
|
|
150
|
+
overflow-wrap: anywhere;
|
|
151
|
+
border-radius: 0 5px 5px 0;
|
|
152
|
+
color: var(--docserve-panel-muted);
|
|
153
|
+
font-size: 12px;
|
|
154
|
+
line-height: 1.5;
|
|
155
|
+
text-decoration: none;
|
|
156
|
+
transition: background-color 0.15s ease, color 0.15s ease;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
.docserve-toc__link[data-level="2"] {
|
|
160
|
+
font-size: 12.5px;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
.docserve-toc__link[data-level="3"] {
|
|
164
|
+
font-size: 11.5px;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
.docserve-toc__link[data-level="4"],
|
|
168
|
+
.docserve-toc__link[data-level="5"],
|
|
169
|
+
.docserve-toc__link[data-level="6"] {
|
|
170
|
+
font-size: 11px;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
.docserve-toc__link iconify-icon,
|
|
174
|
+
.docserve-toc__link svg,
|
|
175
|
+
.docserve-toc__link img {
|
|
176
|
+
display: inline-block;
|
|
177
|
+
width: 13px;
|
|
178
|
+
height: 13px;
|
|
179
|
+
margin-right: 5px;
|
|
180
|
+
vertical-align: -2px;
|
|
181
|
+
color: inherit;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
.docserve-toc__link:hover {
|
|
185
|
+
background: color-mix(in srgb, var(--docserve-panel-text) 6%, transparent);
|
|
186
|
+
color: var(--docserve-panel-text);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
.docserve-toc__link.is-active {
|
|
190
|
+
background: color-mix(in srgb, var(--docserve-dock-accent) 10%, transparent);
|
|
191
|
+
color: var(--docserve-dock-accent);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
.docserve-toc__link:focus-visible {
|
|
195
|
+
outline: 2px solid var(--docserve-dock-accent);
|
|
196
|
+
outline-offset: -1px;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
.docserve-toc__empty {
|
|
200
|
+
margin: 0;
|
|
201
|
+
padding: 4px 0;
|
|
202
|
+
color: var(--docserve-panel-muted);
|
|
203
|
+
font-size: 12px;
|
|
204
|
+
line-height: 1.5;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
@media (prefers-reduced-motion: reduce) {
|
|
208
|
+
.docserve-toc,
|
|
209
|
+
.docserve-toc__marker,
|
|
210
|
+
.docserve-toc__link,
|
|
211
|
+
.docserve-toc__close {
|
|
212
|
+
transition: none;
|
|
213
|
+
}
|
|
214
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import ICON_CLOSE_RAW from "~icons/lucide/x?raw&width=16&height=16"
|
|
2
|
+
import { iconSvg } from "../../../widget/lib/dom.js"
|
|
3
|
+
import type { TocEntry, TocModel } from "../model.js"
|
|
4
|
+
|
|
5
|
+
const ICON_CLOSE = iconSvg(ICON_CLOSE_RAW)
|
|
6
|
+
|
|
7
|
+
export interface TocPanelProps {
|
|
8
|
+
model: TocModel
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export function TocPanel({ model }: TocPanelProps) {
|
|
12
|
+
const open = model.open.value
|
|
13
|
+
const tree = model.tree.value
|
|
14
|
+
const active = model.activeId.value
|
|
15
|
+
|
|
16
|
+
return (
|
|
17
|
+
<aside className="docserve-toc" data-open={open ? "" : undefined} aria-label="Table of contents">
|
|
18
|
+
<header className="docserve-toc__head">
|
|
19
|
+
<span className="docserve-toc__title">On this page</span>
|
|
20
|
+
<button
|
|
21
|
+
type="button"
|
|
22
|
+
className="docserve-toc__close"
|
|
23
|
+
title="Close table of contents"
|
|
24
|
+
aria-label="Close table of contents"
|
|
25
|
+
onClick={() => model.close()}
|
|
26
|
+
dangerouslySetInnerHTML={{ __html: ICON_CLOSE }}
|
|
27
|
+
/>
|
|
28
|
+
</header>
|
|
29
|
+
<nav className="docserve-toc__scroll" ref={model.setScroll} aria-label="On this page">
|
|
30
|
+
<div className="docserve-toc__content">
|
|
31
|
+
<div className="docserve-toc__marker" ref={model.setMarker} aria-hidden="true" />
|
|
32
|
+
{tree.length
|
|
33
|
+
? <TocList model={model} nodes={tree} active={active} />
|
|
34
|
+
: <p className="docserve-toc__empty">No headings on this page</p>}
|
|
35
|
+
</div>
|
|
36
|
+
</nav>
|
|
37
|
+
</aside>
|
|
38
|
+
)
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
interface TocListProps {
|
|
42
|
+
model: TocModel
|
|
43
|
+
nodes: TocEntry[]
|
|
44
|
+
active: string | null
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function TocList({ model, nodes, active }: TocListProps) {
|
|
48
|
+
return (
|
|
49
|
+
<ul className="docserve-toc__list">
|
|
50
|
+
{nodes.map((node, index) => (
|
|
51
|
+
<TocItem
|
|
52
|
+
key={`${node.id}:${index}`}
|
|
53
|
+
model={model}
|
|
54
|
+
entry={node}
|
|
55
|
+
active={active}
|
|
56
|
+
/>
|
|
57
|
+
))}
|
|
58
|
+
</ul>
|
|
59
|
+
)
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
interface TocItemProps {
|
|
63
|
+
model: TocModel
|
|
64
|
+
entry: TocEntry
|
|
65
|
+
active: string | null
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function TocItem({ model, entry, active }: TocItemProps) {
|
|
69
|
+
const isActive = entry.id === active
|
|
70
|
+
|
|
71
|
+
return (
|
|
72
|
+
<li className="docserve-toc__item">
|
|
73
|
+
<a
|
|
74
|
+
ref={model.linkRef(entry.id)}
|
|
75
|
+
className={isActive ? "docserve-toc__link is-active" : "docserve-toc__link"}
|
|
76
|
+
href={`#${entry.id}`}
|
|
77
|
+
data-level={entry.level}
|
|
78
|
+
aria-current={isActive ? "location" : undefined}
|
|
79
|
+
onClick={(event) => model.navigate(event, entry.element)}
|
|
80
|
+
dangerouslySetInnerHTML={{ __html: entry.html }}
|
|
81
|
+
/>
|
|
82
|
+
{entry.children.length
|
|
83
|
+
? <TocList model={model} nodes={entry.children} active={active} />
|
|
84
|
+
: null}
|
|
85
|
+
</li>
|
|
86
|
+
)
|
|
87
|
+
}
|
|
@@ -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
|
+
}
|