@noy4/docserve 0.3.3 → 0.3.5

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 (79) hide show
  1. package/bin.mjs +8 -213
  2. package/dist/gallery/assets/index-CGV64tuk.css +1 -0
  3. package/dist/gallery/assets/index-Cf8Uf0vA.js +10 -0
  4. package/dist/gallery/assets/index-Cf8Uf0vA.js.map +1 -0
  5. package/dist/gallery/index.html +15 -0
  6. package/dist/node/cli.mjs +4095 -0
  7. package/dist/node/cli.mjs.map +7 -0
  8. package/dist/widget/index.js +3410 -2527
  9. package/package.json +15 -5
  10. package/src/node/cli.mjs +155 -0
  11. package/src/node/{files.mjs → docs/files.mjs} +1 -1
  12. package/src/node/{inject.mjs → docs/inject.mjs} +1 -1
  13. package/src/node/{meta.mjs → docs/meta.mjs} +1 -1
  14. package/src/node/http/app.mjs +20 -0
  15. package/src/node/{assets.mjs → http/assets.mjs} +3 -2
  16. package/src/node/http/gallery.mjs +45 -0
  17. package/src/node/http/response.mjs +31 -0
  18. package/src/node/http/routes.mjs +59 -0
  19. package/src/node/{serve-static.mjs → http/serve-static.mjs} +1 -1
  20. package/src/node/{server.mjs → http/server.mjs} +10 -10
  21. package/src/node/{state.mjs → instances/state.mjs} +9 -5
  22. package/src/node/instances/view.mjs +19 -0
  23. package/src/node/{watch.mjs → live/watch.mjs} +1 -1
  24. package/src/node/paths.mjs +10 -0
  25. package/src/node/rpc/files.mjs +5 -0
  26. package/src/node/rpc/index.mjs +39 -0
  27. package/src/node/rpc/route.mjs +34 -0
  28. package/src/node/rpc/servers.mjs +16 -0
  29. package/src/plugins/collapse/client.js +45 -0
  30. package/src/plugins/collapse/collapse.css +74 -0
  31. package/src/plugins/collapse/commands.ts +81 -0
  32. package/src/plugins/collapse/model.ts +123 -0
  33. package/src/plugins/collapse/sections.ts +105 -0
  34. package/src/plugins/collapse/view.ts +84 -0
  35. package/src/plugins/servers/client.js +77 -0
  36. package/src/plugins/servers/commands.ts +30 -0
  37. package/src/plugins/servers/model.ts +106 -0
  38. package/src/plugins/servers/servers.css +144 -0
  39. package/src/plugins/servers/ui/ServersPopover.tsx +71 -0
  40. package/src/plugins/sidebar/client.js +1 -0
  41. package/src/plugins/sidebar/icons.js +1 -1
  42. package/src/plugins/sidebar/ui/PageList.tsx +1 -1
  43. package/src/plugins/sidebar/ui/RadioMenu.tsx +1 -1
  44. package/src/plugins/sidebar/ui/Sidebar.tsx +3 -3
  45. package/src/plugins/sidebar/ui/TreeList.tsx +10 -3
  46. package/src/plugins/toc/client.js +55 -0
  47. package/src/plugins/toc/commands.ts +49 -0
  48. package/src/plugins/toc/heading-html.ts +40 -0
  49. package/src/plugins/toc/model.ts +178 -0
  50. package/src/plugins/toc/outline.js +94 -0
  51. package/src/plugins/toc/scroll-spy.ts +35 -0
  52. package/src/plugins/toc/toc.css +214 -0
  53. package/src/plugins/toc/ui/TocPanel.tsx +87 -0
  54. package/src/{plugins/sidebar/ui → shared/client}/preview-model.ts +18 -4
  55. package/src/{plugins/sidebar/ui/useModel.ts → shared/client/use-model.ts} +1 -8
  56. package/src/shared/types.d.ts +17 -1
  57. package/src/widget/{pages.js → api/pages.js} +4 -7
  58. package/src/widget/api/rpc-client.js +25 -0
  59. package/src/widget/api/servers.js +46 -0
  60. package/src/widget/host.js +10 -8
  61. package/src/widget/index.js +11 -1
  62. package/src/widget/lib/headings.js +132 -0
  63. package/src/widget/{docks.js → shell/docks.js} +2 -2
  64. package/src/widget/{palette.js → shell/palette.js} +3 -3
  65. package/src/widget/{placement.js → shell/placement.js} +1 -1
  66. package/src/widget/{ui.js → shell/ui.js} +1 -1
  67. package/src/widget/widget.css +15 -2
  68. package/index.html +0 -365
  69. package/src/node/adapter.mjs +0 -67
  70. package/src/node/gallery.mjs +0 -33
  71. package/src/node/routes.mjs +0 -105
  72. /package/src/node/{dates.mjs → docs/dates.mjs} +0 -0
  73. /package/src/node/{docs-info.mjs → docs/info.mjs} +0 -0
  74. /package/src/node/{scan.mjs → docs/scan.mjs} +0 -0
  75. /package/src/node/{websocket.mjs → live/websocket.mjs} +0 -0
  76. /package/src/widget/{live.js → api/live.js} +0 -0
  77. /package/src/widget/{rpc.js → api/rpc.js} +0 -0
  78. /package/src/widget/{palette.css → shell/palette.css} +0 -0
  79. /package/src/widget/{styles.js → shell/styles.js} +0 -0
@@ -1,6 +1,6 @@
1
1
  // Public contracts for the docserve widget and its plugins.
2
2
 
3
- /** One HTML page as returned by `GET /api/files`. */
3
+ /** One HTML page returned by `docserve:pages:list`. */
4
4
  interface DocPage {
5
5
  /** Title from `<title>`, else the file name. */
6
6
  title: string
@@ -16,6 +16,22 @@ interface DocPage {
16
16
  favicon?: string
17
17
  }
18
18
 
19
+ /** One live server returned by `docserve:servers:list`. */
20
+ interface DocServer {
21
+ /** Folder name. */
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
+ /** Origin URL, e.g. `http://localhost:4242/`. */
28
+ url: string
29
+ /** Bound port. */
30
+ port: number
31
+ /** True for the server handling this request. */
32
+ current: boolean
33
+ }
34
+
19
35
  /** Identity of the served folder, from the injected script's data attributes. */
20
36
  interface DocsInfo {
21
37
  /** Folder name, e.g. `reports`. */
@@ -1,5 +1,6 @@
1
- // Page listing for the widget: /api/files, cached until a change arrives.
2
- import { decoded, pageUrl } from "./lib/dom.js"
1
+ // Page listing for the widget: docserve:pages:list, cached until a change arrives.
2
+ import { decoded, pageUrl } from "../lib/dom.js"
3
+ import { callServer } from "./rpc-client.js"
3
4
 
4
5
  /**
5
6
  * @param {{ rpc: RpcContext }} options
@@ -35,11 +36,7 @@ export function createPages({ rpc }) {
35
36
  if (cache) return cache
36
37
  if (pending) return pending
37
38
 
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
- })
39
+ pending = callServer("docserve:pages:list")
43
40
  .then((data) => {
44
41
  const pages = Array.isArray(data) ? data : []
45
42
  cache = pages
@@ -0,0 +1,25 @@
1
+ /**
2
+ * @param {string} method
3
+ * @param {any[]} [args]
4
+ * @param {{ signal?: AbortSignal }} [options]
5
+ * @returns {Promise<any>}
6
+ */
7
+ export async function callServer(method, args = [], options = {}) {
8
+ const response = await fetch("/__docserve/rpc", {
9
+ method: "POST",
10
+ cache: "no-store",
11
+ headers: { "content-type": "application/json", accept: "application/json" },
12
+ body: JSON.stringify({ method, args }),
13
+ signal: options.signal,
14
+ })
15
+
16
+ let payload = null
17
+ try {
18
+ payload = await response.json()
19
+ } catch { }
20
+
21
+ const message = payload?.error?.message
22
+ if (!response.ok || message)
23
+ throw new Error(message ?? `/__docserve/rpc: ${response.status}`)
24
+ return payload?.result
25
+ }
@@ -0,0 +1,46 @@
1
+ import { callServer } from "./rpc-client.js"
2
+
3
+ /**
4
+ * @param {{ rpc: RpcContext }} options
5
+ */
6
+ export function createServers({ rpc }) {
7
+ /** @type {DocServer[] | null} */
8
+ let cache = null
9
+ /** @type {Promise<DocServer[]> | null} */
10
+ let pending = null
11
+
12
+ rpc.register("docserve:servers:list", list)
13
+
14
+ return {
15
+ list,
16
+ invalidate() {
17
+ cache = null
18
+ pending = null
19
+ },
20
+ }
21
+
22
+ /**
23
+ * @param {{ force?: boolean }} [options]
24
+ * @returns {Promise<DocServer[]>}
25
+ */
26
+ async function list({ force = false } = {}) {
27
+ if (force) {
28
+ cache = null
29
+ pending = null
30
+ }
31
+ if (cache) return cache
32
+ if (pending) return pending
33
+
34
+ pending = callServer("docserve:servers:list", force ? [true] : [])
35
+ .then((data) => {
36
+ const servers = Array.isArray(data) ? data : []
37
+ cache = servers
38
+ return servers
39
+ })
40
+ .finally(() => {
41
+ pending = null
42
+ })
43
+
44
+ return pending
45
+ }
46
+ }
@@ -1,16 +1,17 @@
1
1
  // Widget host
2
2
  import { createCommands } from "./commands.js"
3
- import { createDocks } from "./docks.js"
3
+ import { createDocks } from "./shell/docks.js"
4
4
  import { el } from "./lib/dom.js"
5
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"
6
+ import { connectLive } from "./api/live.js"
7
+ import { createPages } from "./api/pages.js"
8
+ import { createPalette } from "./shell/palette.js"
9
+ import { createPlacement } from "./shell/placement.js"
10
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"
11
+ import { createRpc } from "./api/rpc.js"
12
+ import { createServers } from "./api/servers.js"
13
+ import { reloadStyles, settled } from "./shell/styles.js"
14
+ import { createUi } from "./shell/ui.js"
14
15
 
15
16
  /**
16
17
  * Create the widget without mounting it.
@@ -32,6 +33,7 @@ export function createHost() {
32
33
  // transport
33
34
  const rpc = createRpc()
34
35
  const pages = createPages({ rpc })
36
+ createServers({ rpc })
35
37
  const events = createEventEmitter()
36
38
 
37
39
  // context is filled below, services resolve it when called
@@ -1,10 +1,20 @@
1
1
  // Widget entry: register the built-in plugins, then start.
2
+ import { collapsePlugin } from "../plugins/collapse/client.js"
2
3
  import { copyPlugin } from "../plugins/copy/client.js"
3
4
  import { homePlugin } from "../plugins/home/client.js"
5
+ import { serversPlugin } from "../plugins/servers/client.js"
4
6
  import { sidebarPlugin } from "../plugins/sidebar/client.js"
7
+ import { tocPlugin } from "../plugins/toc/client.js"
5
8
  import { createHost } from "./host.js"
6
9
 
7
- const PLUGINS = [sidebarPlugin, homePlugin, copyPlugin]
10
+ const PLUGINS = [
11
+ homePlugin,
12
+ collapsePlugin,
13
+ copyPlugin,
14
+ sidebarPlugin,
15
+ tocPlugin,
16
+ serversPlugin,
17
+ ]
8
18
 
9
19
  // The server skips iframe previews; this guard covers pages served some other way.
10
20
  if (window.self === window.top && !document.getElementById("docserve-dock-host")) {
@@ -0,0 +1,132 @@
1
+ const DEFAULT_ROOTS = ["main", "article", ".container"]
2
+ const DEFAULT_EXCLUDED = "nav, aside, header, footer"
3
+
4
+ /**
5
+ * @typedef {{ element: HTMLHeadingElement, level: number, children: TocNode[] }} TocNode
6
+ */
7
+
8
+ /**
9
+ * Content root: `data-*` root selector, else the first of main / article / .container, else body.
10
+ * @param {Document} [doc]
11
+ * @param {string} [attribute]
12
+ * @param {string[]} [selectors]
13
+ * @returns {HTMLElement | null}
14
+ */
15
+ export function findRoot(doc = document, attribute = "data-toc-root", selectors = DEFAULT_ROOTS) {
16
+ const source = doc.body ?? doc.documentElement
17
+ if (!source) return null
18
+
19
+ const selector = source.getAttribute(attribute)
20
+ if (selector) {
21
+ try {
22
+ const custom = doc.querySelector(selector)
23
+ if (custom) return /** @type {HTMLElement} */ (custom)
24
+ } catch {}
25
+ }
26
+
27
+ for (const candidate of selectors) {
28
+ const element = doc.querySelector(candidate)
29
+ if (element) return /** @type {HTMLElement} */ (element)
30
+ }
31
+
32
+ return doc.body
33
+ }
34
+
35
+ /**
36
+ * Headings inside `root` whose level falls in `range`, in document order.
37
+ * @param {HTMLElement | null} root
38
+ * @param {[number, number] | null} range
39
+ * @param {string} [excludedSelector]
40
+ * @returns {HTMLHeadingElement[]}
41
+ */
42
+ export function collectHeadings(root, range, excludedSelector = DEFAULT_EXCLUDED) {
43
+ if (!root || !range) return []
44
+
45
+ const [min, max] = range
46
+ const headings = [...root.querySelectorAll("h1, h2, h3, h4, h5, h6")].filter((element) => {
47
+ const level = Number(element.tagName[1])
48
+ if (level < min || level > max) return false
49
+ if (!element.textContent?.trim()) return false
50
+ if (isHidden(element)) return false
51
+
52
+ const excluded = excludedSelector ? element.closest(excludedSelector) : null
53
+ return !excluded || excluded === root || !root.contains(excluded)
54
+ })
55
+
56
+ return /** @type {HTMLHeadingElement[]} */ (headings)
57
+ }
58
+
59
+ /**
60
+ * Give every heading a stable, unique id; existing ids are kept.
61
+ * @param {HTMLHeadingElement[]} headings
62
+ * @param {Document} [doc]
63
+ */
64
+ export function ensureIds(headings, doc = document) {
65
+ const reserved = new Set()
66
+ for (const element of doc.querySelectorAll("[id]")) {
67
+ if (element.id) reserved.add(element.id)
68
+ }
69
+
70
+ for (const heading of headings) {
71
+ if (heading.id) continue
72
+
73
+ const base = slugify(heading.textContent ?? "")
74
+ let id = base
75
+ let index = 2
76
+ while (!id || reserved.has(id)) id = base ? `${base}-${index++}` : `section-${index++}`
77
+
78
+ heading.id = id
79
+ reserved.add(id)
80
+ }
81
+ }
82
+
83
+ /**
84
+ * `Hello, World!` → `hello-world`.
85
+ * @param {string} text
86
+ * @returns {string}
87
+ */
88
+ export function slugify(text) {
89
+ return text.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "")
90
+ }
91
+
92
+ /**
93
+ * Nest headings by level: a heading becomes a child while its level is greater
94
+ * than the previous one.
95
+ * @param {HTMLHeadingElement[]} headings
96
+ * @returns {TocNode[]}
97
+ */
98
+ export function buildTree(headings) {
99
+ /** @type {TocNode[]} */
100
+ const roots = []
101
+ /** @type {TocNode[]} */
102
+ const stack = []
103
+
104
+ for (const element of headings) {
105
+ const node = { element, level: Number(element.tagName[1]), children: [] }
106
+ while (stack.length && stack[stack.length - 1].level >= node.level) stack.pop()
107
+ if (stack.length) stack[stack.length - 1].children.push(node)
108
+ else roots.push(node)
109
+ stack.push(node)
110
+ }
111
+
112
+ return roots
113
+ }
114
+
115
+ /**
116
+ * @param {Element} element
117
+ * @returns {boolean}
118
+ */
119
+ function isHidden(element) {
120
+ if (element.hasAttribute("hidden") || element.getAttribute("aria-hidden") === "true") return true
121
+ if (element.closest("details:not([open])")) return true
122
+
123
+ const view = element.ownerDocument.defaultView
124
+ if (!view) return false
125
+
126
+ for (let node = element; node; node = node.parentElement) {
127
+ const style = view.getComputedStyle(node)
128
+ if (style.display === "none" || style.visibility === "hidden") return true
129
+ }
130
+
131
+ return false
132
+ }
@@ -1,7 +1,7 @@
1
1
  // The docks registry: one pill that every plugin registers items on. An item
2
2
  // either runs a command or is a link.
3
- import { formatKey } from "./commands.js"
4
- import { el } from "./lib/dom.js"
3
+ import { formatKey } from "../commands.js"
4
+ import { el } from "../lib/dom.js"
5
5
 
6
6
  /**
7
7
  * Build the dock and mount it into the shadow root.
@@ -1,7 +1,7 @@
1
1
  // Command palette overlay: filter, arrow keys and selection. It owns no
2
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"
3
+ import { formatKey } from "../commands.js"
4
+ import { el } from "../lib/dom.js"
5
5
 
6
6
  /**
7
7
  * @param {object} options
@@ -39,7 +39,7 @@ export function createPalette({ root, ui, commands, subscribe }) {
39
39
  const overlay = el("div", { class: "docserve-palette" }, [backdrop, dialog])
40
40
 
41
41
  root.append(overlay)
42
- ui.style("/__docserve/widget/palette.css")
42
+ ui.style("/__docserve/widget/shell/palette.css")
43
43
 
44
44
  /** @type {DocserveCommand[]} */
45
45
  let items = []
@@ -1,6 +1,6 @@
1
1
  // Placement: four viewport corners, drag the pill to move between them, and the
2
2
  // choice is remembered across loads.
3
- import { persisted } from "./lib/storage.js"
3
+ import { persisted } from "../lib/storage.js"
4
4
 
5
5
  const STORAGE_KEY = "docserve:dock-corner"
6
6
  /** Travel before a press counts as a drag, so clicks still click. */
@@ -1,5 +1,5 @@
1
1
  // UI helpers handed to plugins: mount points, stylesheets, announcements.
2
- import { el } from "./lib/dom.js"
2
+ import { el } from "../lib/dom.js"
3
3
 
4
4
  /**
5
5
  * @param {object} options
@@ -31,7 +31,12 @@
31
31
  /* Four corners: `data-corner` is persisted and rewritten by dragging. Left
32
32
  corners follow the sidebar so the pill never sits under an open panel. */
33
33
  :host([data-corner="bl"]) { right: auto; left: calc(var(--docserve-inset-l) + var(--docserve-panel-left, 0px)); }
34
- :host([data-corner="tr"]) { bottom: auto; top: var(--docserve-inset-t); }
34
+ :host([data-corner="br"]) { right: calc(var(--docserve-inset-r) + var(--docserve-panel-right, 0px)); }
35
+ :host([data-corner="tr"]) {
36
+ bottom: auto;
37
+ top: var(--docserve-inset-t);
38
+ right: calc(var(--docserve-inset-r) + var(--docserve-panel-right, 0px));
39
+ }
35
40
  :host([data-corner="tl"]) {
36
41
  right: auto;
37
42
  bottom: auto;
@@ -58,13 +63,21 @@
58
63
  }
59
64
 
60
65
  html[data-docserve-widget] body {
61
- transition: padding-left 0.18s ease;
66
+ transition: padding-left 0.18s ease, padding-right 0.18s ease;
62
67
  }
63
68
 
64
69
  html[data-docserve-panel-left] body {
65
70
  padding-left: var(--docserve-panel-left) !important;
66
71
  }
67
72
 
73
+ html[data-docserve-panel-right] {
74
+ --docserve-panel-right: 260px;
75
+ }
76
+
77
+ html[data-docserve-panel-right] body {
78
+ padding-right: var(--docserve-panel-right) !important;
79
+ }
80
+
68
81
  html[data-docserve-palette] {
69
82
  overflow: hidden;
70
83
  }