@noy4/docserve 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/bin.mjs +2 -2
  2. package/dist/widget/index.js +11803 -0
  3. package/package.json +24 -3
  4. package/src/node/adapter.mjs +67 -0
  5. package/src/node/assets.mjs +36 -0
  6. package/src/node/dates.mjs +73 -0
  7. package/src/node/docs-info.mjs +39 -0
  8. package/src/node/files.mjs +43 -0
  9. package/src/node/gallery.mjs +33 -0
  10. package/src/node/inject.mjs +43 -0
  11. package/src/node/meta.mjs +137 -0
  12. package/src/node/routes.mjs +105 -0
  13. package/src/node/scan.mjs +87 -0
  14. package/src/node/serve-static.mjs +158 -0
  15. package/src/node/server.mjs +69 -0
  16. package/src/node/watch.mjs +119 -0
  17. package/src/plugins/collapse/client.js +45 -0
  18. package/src/plugins/collapse/collapse.css +74 -0
  19. package/src/plugins/collapse/commands.ts +81 -0
  20. package/src/plugins/collapse/model.ts +123 -0
  21. package/src/plugins/collapse/sections.ts +105 -0
  22. package/src/plugins/collapse/view.ts +84 -0
  23. package/src/plugins/copy/client.js +72 -0
  24. package/src/plugins/copy/copy.css +21 -0
  25. package/src/plugins/home/client.js +24 -0
  26. package/src/plugins/sidebar/client.js +106 -0
  27. package/src/plugins/sidebar/grouping.js +108 -0
  28. package/src/plugins/sidebar/icons.js +25 -0
  29. package/src/plugins/sidebar/model.ts +91 -0
  30. package/src/plugins/sidebar/resize-model.ts +47 -0
  31. package/src/plugins/sidebar/sidebar.css +663 -0
  32. package/src/plugins/sidebar/tree-model.ts +23 -0
  33. package/src/plugins/sidebar/tree.ts +69 -0
  34. package/src/plugins/sidebar/ui/PageList.tsx +153 -0
  35. package/src/plugins/sidebar/ui/RadioMenu.tsx +201 -0
  36. package/src/plugins/sidebar/ui/Sidebar.tsx +95 -0
  37. package/src/plugins/sidebar/ui/SidebarHeader.tsx +87 -0
  38. package/src/plugins/sidebar/ui/TreeList.tsx +121 -0
  39. package/src/plugins/sidebar/ui/preview-model.ts +134 -0
  40. package/src/plugins/sidebar/ui/useModel.ts +25 -0
  41. package/src/plugins/toc/client.js +55 -0
  42. package/src/plugins/toc/commands.ts +49 -0
  43. package/src/plugins/toc/heading-html.ts +40 -0
  44. package/src/plugins/toc/model.ts +178 -0
  45. package/src/plugins/toc/outline.js +94 -0
  46. package/src/plugins/toc/scroll-spy.ts +35 -0
  47. package/src/plugins/toc/toc.css +214 -0
  48. package/src/plugins/toc/ui/TocPanel.tsx +87 -0
  49. package/src/shared/types.d.ts +193 -0
  50. package/src/widget/commands.js +214 -0
  51. package/src/widget/docks.js +127 -0
  52. package/src/widget/host.js +187 -0
  53. package/src/widget/index.js +22 -0
  54. package/src/widget/lib/disposables.js +44 -0
  55. package/src/widget/lib/dom.js +106 -0
  56. package/src/widget/lib/events.js +65 -0
  57. package/src/widget/lib/headings.js +132 -0
  58. package/src/widget/lib/persisted-signal.js +40 -0
  59. package/src/widget/lib/storage.js +70 -0
  60. package/src/widget/live.js +86 -0
  61. package/src/widget/pages.js +65 -0
  62. package/src/widget/palette.css +162 -0
  63. package/src/widget/palette.js +259 -0
  64. package/src/widget/placement.js +204 -0
  65. package/src/widget/plugins.js +39 -0
  66. package/src/widget/rpc.js +32 -0
  67. package/src/widget/styles.js +31 -0
  68. package/src/widget/ui.js +50 -0
  69. package/src/widget/widget.css +206 -0
  70. package/server/files.mjs +0 -261
  71. package/server/index.mjs +0 -198
  72. package/server/inject.html +0 -88
  73. package/server/inject.mjs +0 -28
  74. package/server/watch.mjs +0 -104
  75. /package/{server → src/node}/state.mjs +0 -0
  76. /package/{server → src/node}/websocket.mjs +0 -0
@@ -0,0 +1,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
+ }