@thedatagrid/docs-kit 0.0.0-stage → 0.1.0

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 (175) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +123 -2
  3. package/dist/code/demoFiles.d.ts +14 -0
  4. package/dist/code/demoFiles.d.ts.map +1 -0
  5. package/dist/code/demoFiles.js +46 -0
  6. package/dist/code/demoFiles.js.map +1 -0
  7. package/dist/code/heights.d.ts +17 -0
  8. package/dist/code/heights.d.ts.map +1 -0
  9. package/dist/code/heights.js +40 -0
  10. package/dist/code/heights.js.map +1 -0
  11. package/dist/code/highlightSpec.d.ts +34 -0
  12. package/dist/code/highlightSpec.d.ts.map +1 -0
  13. package/dist/code/highlightSpec.js +119 -0
  14. package/dist/code/highlightSpec.js.map +1 -0
  15. package/dist/code/imports.d.ts +5 -0
  16. package/dist/code/imports.d.ts.map +1 -0
  17. package/dist/code/imports.js +17 -0
  18. package/dist/code/imports.js.map +1 -0
  19. package/dist/code/index.d.ts +8 -0
  20. package/dist/code/index.d.ts.map +1 -0
  21. package/dist/code/index.js +8 -0
  22. package/dist/code/index.js.map +1 -0
  23. package/dist/code/lineRanges.d.ts +5 -0
  24. package/dist/code/lineRanges.d.ts.map +1 -0
  25. package/dist/code/lineRanges.js +35 -0
  26. package/dist/code/lineRanges.js.map +1 -0
  27. package/dist/code/regions.d.ts +53 -0
  28. package/dist/code/regions.d.ts.map +1 -0
  29. package/dist/code/regions.js +237 -0
  30. package/dist/code/regions.js.map +1 -0
  31. package/dist/code/shiki.d.ts +58 -0
  32. package/dist/code/shiki.d.ts.map +1 -0
  33. package/dist/code/shiki.js +244 -0
  34. package/dist/code/shiki.js.map +1 -0
  35. package/dist/demos/build.d.ts +17 -0
  36. package/dist/demos/build.d.ts.map +1 -0
  37. package/dist/demos/build.js +426 -0
  38. package/dist/demos/build.js.map +1 -0
  39. package/dist/demos/cli.d.ts +3 -0
  40. package/dist/demos/cli.d.ts.map +1 -0
  41. package/dist/demos/cli.js +68 -0
  42. package/dist/demos/cli.js.map +1 -0
  43. package/dist/demos/client.d.ts +27 -0
  44. package/dist/demos/client.d.ts.map +1 -0
  45. package/dist/demos/client.js +61 -0
  46. package/dist/demos/client.js.map +1 -0
  47. package/dist/demos/compile/core.d.ts +64 -0
  48. package/dist/demos/compile/core.d.ts.map +1 -0
  49. package/dist/demos/compile/core.js +174 -0
  50. package/dist/demos/compile/core.js.map +1 -0
  51. package/dist/demos/config.d.ts +108 -0
  52. package/dist/demos/config.d.ts.map +1 -0
  53. package/dist/demos/config.js +4 -0
  54. package/dist/demos/config.js.map +1 -0
  55. package/dist/demos/devEvents.d.ts +13 -0
  56. package/dist/demos/devEvents.d.ts.map +1 -0
  57. package/dist/demos/devEvents.js +45 -0
  58. package/dist/demos/devEvents.js.map +1 -0
  59. package/dist/demos/html.d.ts +21 -0
  60. package/dist/demos/html.d.ts.map +1 -0
  61. package/dist/demos/html.js +57 -0
  62. package/dist/demos/html.js.map +1 -0
  63. package/dist/demos/index.d.ts +8 -0
  64. package/dist/demos/index.d.ts.map +1 -0
  65. package/dist/demos/index.js +6 -0
  66. package/dist/demos/index.js.map +1 -0
  67. package/dist/demos/pages.d.ts +15 -0
  68. package/dist/demos/pages.d.ts.map +1 -0
  69. package/dist/demos/pages.js +71 -0
  70. package/dist/demos/pages.js.map +1 -0
  71. package/dist/demos/runtime/iframe.d.ts +50 -0
  72. package/dist/demos/runtime/iframe.d.ts.map +1 -0
  73. package/dist/demos/runtime/iframe.js +245 -0
  74. package/dist/demos/runtime/iframe.js.map +1 -0
  75. package/dist/demos/runtime/react.d.ts +3 -0
  76. package/dist/demos/runtime/react.d.ts.map +1 -0
  77. package/dist/demos/runtime/react.js +17 -0
  78. package/dist/demos/runtime/react.js.map +1 -0
  79. package/dist/demos/slug.d.ts +3 -0
  80. package/dist/demos/slug.d.ts.map +1 -0
  81. package/dist/demos/slug.js +11 -0
  82. package/dist/demos/slug.js.map +1 -0
  83. package/dist/demos/vendor.d.ts +32 -0
  84. package/dist/demos/vendor.d.ts.map +1 -0
  85. package/dist/demos/vendor.js +127 -0
  86. package/dist/demos/vendor.js.map +1 -0
  87. package/dist/demos/worker/compile.worker.d.ts +2 -0
  88. package/dist/demos/worker/compile.worker.d.ts.map +1 -0
  89. package/dist/demos/worker/compile.worker.js +27 -0
  90. package/dist/demos/worker/compile.worker.js.map +1 -0
  91. package/dist/fork/codesandbox.d.ts +39 -0
  92. package/dist/fork/codesandbox.d.ts.map +1 -0
  93. package/dist/fork/codesandbox.js +156 -0
  94. package/dist/fork/codesandbox.js.map +1 -0
  95. package/dist/fork/index.d.ts +2 -0
  96. package/dist/fork/index.d.ts.map +1 -0
  97. package/dist/fork/index.js +2 -0
  98. package/dist/fork/index.js.map +1 -0
  99. package/dist/react/Demo.d.ts +80 -0
  100. package/dist/react/Demo.d.ts.map +1 -0
  101. package/dist/react/Demo.js +156 -0
  102. package/dist/react/Demo.js.map +1 -0
  103. package/dist/react/DemoIframe.d.ts +22 -0
  104. package/dist/react/DemoIframe.d.ts.map +1 -0
  105. package/dist/react/DemoIframe.js +123 -0
  106. package/dist/react/DemoIframe.js.map +1 -0
  107. package/dist/react/DemoShell.d.ts +47 -0
  108. package/dist/react/DemoShell.d.ts.map +1 -0
  109. package/dist/react/DemoShell.js +341 -0
  110. package/dist/react/DemoShell.js.map +1 -0
  111. package/dist/react/devEvents.d.ts +17 -0
  112. package/dist/react/devEvents.d.ts.map +1 -0
  113. package/dist/react/devEvents.js +30 -0
  114. package/dist/react/devEvents.js.map +1 -0
  115. package/dist/react/editor.d.ts +8 -0
  116. package/dist/react/editor.d.ts.map +1 -0
  117. package/dist/react/editor.js +52 -0
  118. package/dist/react/editor.js.map +1 -0
  119. package/dist/react/fork.d.ts +10 -0
  120. package/dist/react/fork.d.ts.map +1 -0
  121. package/dist/react/fork.js +30 -0
  122. package/dist/react/fork.js.map +1 -0
  123. package/dist/react/index.d.ts +4 -0
  124. package/dist/react/index.d.ts.map +1 -0
  125. package/dist/react/index.js +4 -0
  126. package/dist/react/index.js.map +1 -0
  127. package/dist/react/styles.css +493 -0
  128. package/dist/remark/index.d.ts +3 -0
  129. package/dist/remark/index.d.ts.map +1 -0
  130. package/dist/remark/index.js +3 -0
  131. package/dist/remark/index.js.map +1 -0
  132. package/dist/remark/meta.d.ts +7 -0
  133. package/dist/remark/meta.d.ts.map +1 -0
  134. package/dist/remark/meta.js +20 -0
  135. package/dist/remark/meta.js.map +1 -0
  136. package/dist/remark/remarkDemoFences.d.ts +77 -0
  137. package/dist/remark/remarkDemoFences.d.ts.map +1 -0
  138. package/dist/remark/remarkDemoFences.js +259 -0
  139. package/dist/remark/remarkDemoFences.js.map +1 -0
  140. package/package.json +106 -4
  141. package/src/code/demoFiles.ts +54 -0
  142. package/src/code/heights.ts +47 -0
  143. package/src/code/highlightSpec.ts +139 -0
  144. package/src/code/imports.ts +18 -0
  145. package/src/code/index.ts +46 -0
  146. package/src/code/lineRanges.ts +31 -0
  147. package/src/code/regions.ts +270 -0
  148. package/src/code/shiki.ts +271 -0
  149. package/src/demos/build.ts +477 -0
  150. package/src/demos/cli.ts +64 -0
  151. package/src/demos/client.ts +82 -0
  152. package/src/demos/compile/core.ts +228 -0
  153. package/src/demos/config.ts +106 -0
  154. package/src/demos/devEvents.ts +45 -0
  155. package/src/demos/html.ts +74 -0
  156. package/src/demos/index.ts +25 -0
  157. package/src/demos/pages.ts +79 -0
  158. package/src/demos/runtime/iframe.ts +262 -0
  159. package/src/demos/runtime/react.ts +19 -0
  160. package/src/demos/slug.ts +10 -0
  161. package/src/demos/vendor.ts +142 -0
  162. package/src/demos/worker/compile.worker.ts +35 -0
  163. package/src/fork/codesandbox.ts +189 -0
  164. package/src/fork/index.ts +10 -0
  165. package/src/react/Demo.tsx +250 -0
  166. package/src/react/DemoIframe.tsx +165 -0
  167. package/src/react/DemoShell.tsx +592 -0
  168. package/src/react/devEvents.ts +34 -0
  169. package/src/react/editor.ts +61 -0
  170. package/src/react/fork.ts +31 -0
  171. package/src/react/index.ts +10 -0
  172. package/src/react/styles.css +493 -0
  173. package/src/remark/index.ts +2 -0
  174. package/src/remark/meta.ts +20 -0
  175. package/src/remark/remarkDemoFences.ts +330 -0
@@ -0,0 +1,477 @@
1
+ /**
2
+ * Prebuilds every `content/**\/*.demo.tsx` into a static iframe page under
3
+ * `<outDir>/<content-relative id>/index.html`:
4
+ *
5
+ * - `_lib/`: the import map's targets. Each package the demos import (and the
6
+ * configured libraries, built from source) is an ESM entry; one split build,
7
+ * so shared code (React) exists once.
8
+ * - `_runtime/`: the iframe runtime + framework adapter + site bootstrap.
9
+ * - `<id>/demo-[hash].js`: the demo's own code, every bare import external.
10
+ * - `_editor/`: the compile worker and esbuild.wasm for in-browser rebuilds.
11
+ * - `manifest.json`: what the docs UI needs (import map, editor, demos).
12
+ *
13
+ * `watch: true` keeps esbuild contexts alive, rebuilds on content / library
14
+ * changes and streams `{ type: 'demo' }` events so open iframes reload.
15
+ */
16
+ import crypto from 'node:crypto';
17
+ import fs from 'node:fs';
18
+ import { createRequire } from 'node:module';
19
+ import path from 'node:path';
20
+ import { fileURLToPath } from 'node:url';
21
+ import * as esbuild from 'esbuild';
22
+
23
+ import { bareImports, collectDemoFiles } from '../code/demoFiles.ts';
24
+ import { demoBuildOptions, externalImportsPlugin, matchesStub } from './compile/core.ts';
25
+ import type { DemoManifest, DocsKitConfig, LibrarySource } from './config.ts';
26
+ import { startDevEvents } from './devEvents.ts';
27
+ import { demoPageHtml, themeInitScript } from './html.ts';
28
+ import { defaultRouteForPage, findDocsLinks, findFiles } from './pages.ts';
29
+ import { vendorResolvePlugin, writeVendorEntries, type VendorEntries } from './vendor.ts';
30
+
31
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
32
+ /** `.ts` when running from source (local development of the kit), `.js` from `dist`. */
33
+ const EXT = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
34
+ const kitFile = (rel: string) => path.join(HERE, `${rel}${EXT}`);
35
+
36
+ const FRAMEWORK_SPECIFIERS = { react: ['react', 'react/jsx-runtime', 'react-dom/client'] };
37
+
38
+ const ASSET_LOADERS: Record<string, esbuild.Loader> = {
39
+ '.png': 'file',
40
+ '.jpg': 'file',
41
+ '.jpeg': 'file',
42
+ '.gif': 'file',
43
+ '.svg': 'file',
44
+ '.webp': 'file',
45
+ '.woff': 'file',
46
+ '.woff2': 'file',
47
+ '.ttf': 'file',
48
+ };
49
+
50
+ const toPosix = (p: string) => p.split(path.sep).join('/');
51
+ const shortHash = (content: string | Buffer) => crypto.createHash('sha1').update(content).digest('hex').slice(0, 10);
52
+ const escapeRegExp = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
53
+
54
+ export type BuildDemosOptions = {
55
+ config: DocsKitConfig;
56
+ /** Folder of the config file; `config.root` resolves against it. */
57
+ configDir: string;
58
+ watch?: boolean;
59
+ log?: (message: string) => void;
60
+ };
61
+
62
+ export type BuildDemosResult = {
63
+ manifest: DemoManifest;
64
+ /** Ids whose page changed in the last build. */
65
+ changed: string[];
66
+ /** Watch mode: stops watching and disposes the esbuild contexts. */
67
+ close(): Promise<void>;
68
+ };
69
+
70
+ type Demo = { id: string; file: string };
71
+
72
+ type Settings = ReturnType<typeof resolveSettings>;
73
+
74
+ function resolveSettings(options: BuildDemosOptions) {
75
+ const { config } = options;
76
+ const root = path.resolve(options.configDir, config.root ?? '.');
77
+ const production = config.production ?? process.env.NODE_ENV === 'production';
78
+ const libraries: Record<string, LibrarySource> = {};
79
+ for (const [specifier, library] of Object.entries(config.libraries ?? {})) {
80
+ libraries[specifier] = { ...library, entry: path.resolve(root, library.entry) };
81
+ }
82
+ const stubImports = (config.stubImports ?? []).map((stub) =>
83
+ typeof stub === 'string' ? `^${escapeRegExp(stub)}$` : stub.source,
84
+ );
85
+ const define = {
86
+ 'process.env.NODE_ENV': JSON.stringify(production ? 'production' : 'development'),
87
+ ...config.define,
88
+ };
89
+ return {
90
+ root,
91
+ production,
92
+ contentDir: path.resolve(root, config.contentDir ?? 'content'),
93
+ outDir: path.resolve(root, config.outDir ?? 'public/gen/demos'),
94
+ urlRoot: (config.urlRoot ?? '/gen/demos').replace(/\/+$/, ''),
95
+ demoSuffix: config.demoSuffix ?? '.demo.tsx',
96
+ pageExtension: config.pageExtension ?? '.page.md',
97
+ routeForPage: config.routeForPage ?? defaultRouteForPage,
98
+ anchorPrefix: config.anchorPrefix ?? '',
99
+ framework: config.framework ?? 'react',
100
+ libraries,
101
+ stubImports,
102
+ define,
103
+ bootstrapDefine: { ...define, ...config.bootstrapDefine },
104
+ bootstrap: config.bootstrap ? path.resolve(root, config.bootstrap) : null,
105
+ extraCss: (config.css ?? []).map((file) => path.resolve(root, file)),
106
+ nodePaths: config.nodePaths?.map((p) => path.resolve(root, p)) ?? [path.join(root, 'node_modules')],
107
+ workDir: path.join(root, 'node_modules/.cache/docs-kit'),
108
+ themeClasses: config.themeClasses ?? {},
109
+ devEventsPort: config.devEventsPort ?? 4748,
110
+ };
111
+ }
112
+
113
+ function discover(settings: Settings) {
114
+ const demos: Demo[] = findFiles(settings.contentDir, settings.demoSuffix).map((file) => ({
115
+ file,
116
+ id: toPosix(path.relative(settings.contentDir, file)).slice(0, -settings.demoSuffix.length),
117
+ }));
118
+
119
+ const specifiers = new Set<string>(FRAMEWORK_SPECIFIERS[settings.framework]);
120
+ for (const specifier of Object.keys(settings.libraries)) specifiers.add(specifier);
121
+ const sources: string[] = [];
122
+ for (const demo of demos) {
123
+ for (const { source } of collectDemoFiles(demo.file)) sources.push(source);
124
+ }
125
+ if (settings.bootstrap) sources.push(fs.readFileSync(settings.bootstrap, 'utf8'));
126
+ for (const source of sources) for (const specifier of bareImports(source)) specifiers.add(specifier);
127
+ for (const specifier of [...specifiers]) {
128
+ if (matchesStub(specifier, settings.stubImports)) specifiers.delete(specifier);
129
+ }
130
+ return { demos, specifiers: [...specifiers].sort() };
131
+ }
132
+
133
+ function writeRuntimeEntry(settings: Settings, config: DocsKitConfig): string {
134
+ const entry = path.join(settings.workDir, 'runtime-entry.mjs');
135
+ const lines = [
136
+ `import { createRuntime } from ${JSON.stringify(kitFile('runtime/iframe'))};`,
137
+ `import { reactAdapter } from ${JSON.stringify(kitFile('runtime/react'))};`,
138
+ settings.bootstrap ? `import * as site from ${JSON.stringify(settings.bootstrap)};` : 'const site = {};',
139
+ `export const { mount, fail } = createRuntime({`,
140
+ ` adapter: reactAdapter,`,
141
+ ` site,`,
142
+ ` themeStorageKey: ${JSON.stringify(config.themeStorageKey ?? null)} ?? undefined,`,
143
+ ` defaultTheme: ${JSON.stringify(config.defaultTheme ?? 'light')},`,
144
+ ` themeClasses: ${JSON.stringify(config.themeClasses ?? {})},`,
145
+ `});`,
146
+ ];
147
+ fs.mkdirSync(settings.workDir, { recursive: true });
148
+ fs.writeFileSync(entry, `${lines.join('\n')}\n`);
149
+ return entry;
150
+ }
151
+
152
+ async function createContexts(settings: Settings, config: DocsKitConfig, demos: Demo[], vendor: VendorEntries) {
153
+ const libraryPlugins: esbuild.Plugin[] = [];
154
+ for (const library of Object.values(settings.libraries)) {
155
+ if (library.plugins) libraryPlugins.push(...(await library.plugins()));
156
+ }
157
+ const common = {
158
+ absWorkingDir: settings.root,
159
+ nodePaths: settings.nodePaths,
160
+ metafile: true,
161
+ logLevel: 'silent' as const,
162
+ loader: ASSET_LOADERS,
163
+ };
164
+
165
+ const vendorCtx = await esbuild.context({
166
+ ...common,
167
+ entryPoints: vendor.entryPoints,
168
+ bundle: true,
169
+ splitting: true,
170
+ format: 'esm',
171
+ platform: 'browser',
172
+ target: 'es2022',
173
+ jsx: 'automatic',
174
+ outdir: path.join(settings.outDir, '_lib'),
175
+ entryNames: '[name]-[hash]',
176
+ chunkNames: 'chunk-[hash]',
177
+ assetNames: 'asset-[name]-[hash]',
178
+ minify: settings.production,
179
+ sourcemap: !settings.production,
180
+ legalComments: 'none',
181
+ define: settings.define,
182
+ plugins: [
183
+ vendorResolvePlugin({
184
+ libraries: settings.libraries,
185
+ canonical: new Set(Object.values(vendor.specifierByEntry)),
186
+ stubImports: settings.stubImports,
187
+ root: settings.root,
188
+ }),
189
+ ...libraryPlugins,
190
+ ],
191
+ });
192
+
193
+ const runtimeCtx = await esbuild.context({
194
+ ...common,
195
+ ...demoBuildOptions({ define: settings.bootstrapDefine, minify: settings.production }),
196
+ entryPoints: { runtime: writeRuntimeEntry(settings, config) },
197
+ outdir: path.join(settings.outDir, '_runtime'),
198
+ entryNames: '[name]-[hash]',
199
+ plugins: [externalImportsPlugin(settings.stubImports)],
200
+ });
201
+
202
+ const demosCtx = await esbuild.context({
203
+ ...common,
204
+ ...demoBuildOptions({ define: settings.define, minify: settings.production }),
205
+ entryPoints: Object.fromEntries(demos.map((demo) => [`${demo.id}/demo`, demo.file])),
206
+ outdir: settings.outDir,
207
+ splitting: true,
208
+ entryNames: '[dir]/[name]-[hash]',
209
+ chunkNames: '_chunks/chunk-[hash]',
210
+ assetNames: '_assets/[name]-[hash]',
211
+ sourcemap: !settings.production,
212
+ plugins: [externalImportsPlugin(settings.stubImports)],
213
+ });
214
+
215
+ return { vendorCtx, runtimeCtx, demosCtx };
216
+ }
217
+
218
+ /** Builds the compile worker and copies esbuild.wasm (hashed: they're cached as immutable). */
219
+ async function buildEditorAssets(settings: Settings) {
220
+ const outDir = path.join(settings.outDir, '_editor');
221
+ const result = await esbuild.build({
222
+ entryPoints: { 'compile-worker': kitFile('worker/compile.worker') },
223
+ bundle: true,
224
+ format: 'esm',
225
+ platform: 'browser',
226
+ target: 'es2022',
227
+ outdir: outDir,
228
+ entryNames: '[name]-[hash]',
229
+ minify: true,
230
+ metafile: true,
231
+ logLevel: 'silent',
232
+ absWorkingDir: settings.root,
233
+ });
234
+ const workerOut = Object.keys(result.metafile.outputs).find((file) => file.endsWith('.js'))!;
235
+
236
+ const require = createRequire(import.meta.url);
237
+ const wasmPath = path.join(path.dirname(require.resolve('esbuild-wasm/package.json')), 'esbuild.wasm');
238
+ const wasm = fs.readFileSync(wasmPath);
239
+ const wasmName = `esbuild-${shortHash(wasm)}.wasm`;
240
+ fs.mkdirSync(outDir, { recursive: true });
241
+ fs.writeFileSync(path.join(outDir, wasmName), wasm);
242
+
243
+ return {
244
+ worker: `${settings.urlRoot}/${toPosix(path.relative(settings.outDir, path.resolve(settings.root, workerOut)))}`,
245
+ wasm: `${settings.urlRoot}/_editor/${wasmName}`,
246
+ };
247
+ }
248
+
249
+ function copyExtraCss(settings: Settings): string[] {
250
+ return settings.extraCss.map((file) => {
251
+ const css = fs.readFileSync(file);
252
+ const name = `${path.basename(file, '.css')}-${shortHash(css)}.css`;
253
+ const target = path.join(settings.outDir, '_lib', name);
254
+ fs.mkdirSync(path.dirname(target), { recursive: true });
255
+ fs.writeFileSync(target, css);
256
+ return `${settings.urlRoot}/_lib/${name}`;
257
+ });
258
+ }
259
+
260
+ export async function buildDemos(options: BuildDemosOptions): Promise<BuildDemosResult> {
261
+ const { config, watch = false } = options;
262
+ const log = options.log ?? ((message: string) => console.log(`[docs-kit] ${message}`));
263
+ const settings = resolveSettings(options);
264
+ const urlFor = (outFile: string) =>
265
+ `${settings.urlRoot}/${toPosix(path.relative(settings.outDir, path.resolve(settings.root, outFile)))}`;
266
+
267
+ // Output names are content-hashed and never pruned during a run, so start
268
+ // clean: a stale page could point at bundles from an older config.
269
+ fs.rmSync(settings.outDir, { recursive: true, force: true });
270
+ fs.mkdirSync(settings.outDir, { recursive: true });
271
+
272
+ const editorAssets = await buildEditorAssets(settings);
273
+
274
+ let state = discover(settings);
275
+ let vendor = await writeVendorEntries({
276
+ specifiers: state.specifiers,
277
+ libraries: settings.libraries,
278
+ root: settings.root,
279
+ nodePaths: settings.nodePaths,
280
+ workDir: path.join(settings.workDir, 'vendor'),
281
+ warn: (message) => log(`warning: ${message}`),
282
+ });
283
+ let contexts = await createContexts(settings, config, state.demos, vendor);
284
+ const devEvents = watch ? startDevEvents(settings.devEventsPort, log) : null;
285
+
286
+ let manifest: DemoManifest | null = null;
287
+
288
+ const runBuild = async (): Promise<string[]> => {
289
+ const started = Date.now();
290
+ const [vendorResult, runtimeResult, demosResult] = await Promise.all([
291
+ contexts.vendorCtx.rebuild(),
292
+ contexts.runtimeCtx.rebuild(),
293
+ contexts.demosCtx.rebuild(),
294
+ ]);
295
+
296
+ const specifierByWrapper = new Map(
297
+ Object.entries(vendor.entryPoints).map(([name, file]) => [path.resolve(file), vendor.specifierByEntry[name]]),
298
+ );
299
+ const imports: Record<string, string> = {};
300
+ const libCss: string[] = [];
301
+ for (const [outFile, meta] of Object.entries(vendorResult.metafile!.outputs)) {
302
+ if (!meta.entryPoint) continue;
303
+ const specifier = specifierByWrapper.get(path.resolve(settings.root, meta.entryPoint));
304
+ if (!specifier) continue;
305
+ imports[specifier] = urlFor(outFile);
306
+ if (meta.cssBundle) libCss.push(urlFor(meta.cssBundle));
307
+ }
308
+ const cssUrls = [...libCss.sort(), ...copyExtraCss(settings)];
309
+
310
+ const runtimeOut = Object.entries(runtimeResult.metafile!.outputs).find(([, meta]) => meta.entryPoint)!;
311
+ const runtimeUrl = urlFor(runtimeOut[0]);
312
+
313
+ const docsLinks = findDocsLinks(settings);
314
+ const themeScript = themeInitScript(config.themeStorageKey, config.defaultTheme ?? 'light', settings.themeClasses);
315
+ const demoByFile = new Map(state.demos.map((demo) => [path.resolve(demo.file), demo]));
316
+ const changed: string[] = [];
317
+ const demos: DemoManifest['demos'] = {};
318
+
319
+ for (const [outFile, meta] of Object.entries(demosResult.metafile!.outputs)) {
320
+ if (!meta.entryPoint) continue;
321
+ const demo = demoByFile.get(path.resolve(settings.root, meta.entryPoint));
322
+ if (!demo) continue;
323
+ const preload = new Set<string>([runtimeUrl]);
324
+ for (const imported of meta.imports) {
325
+ if (imported.external && imports[imported.path]) preload.add(imports[imported.path]);
326
+ }
327
+ const html = demoPageHtml({
328
+ title: demo.id,
329
+ importMap: { imports },
330
+ cssUrls,
331
+ demoCssUrls: meta.cssBundle ? [urlFor(meta.cssBundle)] : [],
332
+ preload: [...preload],
333
+ runtimeUrl,
334
+ moduleUrl: urlFor(outFile),
335
+ docsHref: docsLinks.get(demo.id) ?? null,
336
+ themeScript,
337
+ pageStyle: config.pageStyle,
338
+ });
339
+ const htmlFile = path.join(settings.outDir, demo.id, 'index.html');
340
+ fs.mkdirSync(path.dirname(htmlFile), { recursive: true });
341
+ if (!fs.existsSync(htmlFile) || fs.readFileSync(htmlFile, 'utf8') !== html) {
342
+ fs.writeFileSync(htmlFile, html);
343
+ changed.push(demo.id);
344
+ }
345
+ demos[demo.id] = { html: `${settings.urlRoot}/${demo.id}/index.html` };
346
+ }
347
+
348
+ manifest = {
349
+ version: 1,
350
+ framework: settings.framework,
351
+ urlRoot: settings.urlRoot,
352
+ demoSuffix: settings.demoSuffix,
353
+ importMap: { imports },
354
+ editor: {
355
+ compiler:
356
+ config.compiler?.kind === 'remote'
357
+ ? { kind: 'remote', endpoint: config.compiler.endpoint }
358
+ : { kind: 'browser', ...editorAssets },
359
+ options: { define: settings.define, stubImports: settings.stubImports, minify: false },
360
+ },
361
+ sourceReplacements: config.sourceReplacements ?? {},
362
+ fork: config.fork ?? {},
363
+ ...(watch ? { devEvents: `:${settings.devEventsPort}/events` } : null),
364
+ demos,
365
+ };
366
+ const manifestFile = path.join(settings.outDir, 'manifest.json');
367
+ const manifestJson = `${JSON.stringify(manifest, null, 2)}\n`;
368
+ if (!fs.existsSync(manifestFile) || fs.readFileSync(manifestFile, 'utf8') !== manifestJson) {
369
+ fs.writeFileSync(manifestFile, manifestJson);
370
+ }
371
+ log(
372
+ `built ${Object.keys(demos).length} demo(s), ${Object.keys(imports).length} import-map entries ` +
373
+ `in ${((Date.now() - started) / 1000).toFixed(1)}s`,
374
+ );
375
+ return changed;
376
+ };
377
+
378
+ const disposeContexts = async () => {
379
+ await Promise.all([contexts.vendorCtx.dispose(), contexts.runtimeCtx.dispose(), contexts.demosCtx.dispose()]);
380
+ };
381
+
382
+ let changed: string[];
383
+ try {
384
+ changed = await runBuild();
385
+ } catch (error) {
386
+ if (!watch) {
387
+ await disposeContexts();
388
+ throw error;
389
+ }
390
+ log(`initial build failed: ${(error as Error).message}`);
391
+ changed = [];
392
+ }
393
+
394
+ if (!watch) {
395
+ await disposeContexts();
396
+ return { manifest: manifest!, changed, close: async () => {} };
397
+ }
398
+
399
+ const chokidar = await import('chokidar');
400
+ const watchRoots = [
401
+ settings.contentDir,
402
+ ...Object.values(settings.libraries).flatMap((library) =>
403
+ (library.watch ?? [path.dirname(library.entry)]).map((dir) => path.resolve(settings.root, dir)),
404
+ ),
405
+ ...(settings.bootstrap ? [settings.bootstrap] : []),
406
+ ...settings.extraCss,
407
+ ];
408
+ const watcher = chokidar.watch(watchRoots, {
409
+ ignoreInitial: true,
410
+ ignored: (file: string) => file.includes(`${path.sep}node_modules${path.sep}`) || file.startsWith(settings.outDir),
411
+ });
412
+
413
+ let running = false;
414
+ let queued = false;
415
+ let timer: NodeJS.Timeout | null = null;
416
+
417
+ const rebuild = async () => {
418
+ if (running) {
419
+ queued = true;
420
+ return;
421
+ }
422
+ running = true;
423
+ try {
424
+ const next = discover(settings);
425
+ const structureChanged =
426
+ next.specifiers.join('\n') !== state.specifiers.join('\n') ||
427
+ next.demos.map((demo) => demo.id).join('\n') !== state.demos.map((demo) => demo.id).join('\n');
428
+ if (structureChanged) {
429
+ await disposeContexts();
430
+ state = next;
431
+ vendor = await writeVendorEntries({
432
+ specifiers: state.specifiers,
433
+ libraries: settings.libraries,
434
+ root: settings.root,
435
+ nodePaths: settings.nodePaths,
436
+ workDir: path.join(settings.workDir, 'vendor'),
437
+ warn: (message) => log(`warning: ${message}`),
438
+ });
439
+ contexts = await createContexts(settings, config, state.demos, vendor);
440
+ }
441
+ for (const id of await runBuild()) {
442
+ devEvents?.send({ type: 'demo', id, url: `${settings.urlRoot}/${id}/index.html` });
443
+ }
444
+ } catch (error) {
445
+ const message = (error as Error).message;
446
+ log(`build failed: ${message}`);
447
+ devEvents?.send({ type: 'build-error', message });
448
+ } finally {
449
+ running = false;
450
+ if (queued) {
451
+ queued = false;
452
+ void rebuild();
453
+ }
454
+ }
455
+ };
456
+
457
+ watcher.on('all', (_event, file) => {
458
+ if (timer) clearTimeout(timer);
459
+ timer = setTimeout(() => {
460
+ log(`change: ${path.relative(settings.root, file)}`);
461
+ void rebuild();
462
+ }, 120);
463
+ });
464
+ log('watching content and library sources…');
465
+
466
+ return {
467
+ get manifest() {
468
+ return manifest!;
469
+ },
470
+ changed,
471
+ async close() {
472
+ await watcher.close();
473
+ devEvents?.close();
474
+ await disposeContexts();
475
+ },
476
+ };
477
+ }
@@ -0,0 +1,64 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * `docs-kit demos [build] [--watch] [--config <file>]`
4
+ *
5
+ * Loads `docs-kit.config.{mjs,js,ts}` from the current folder (or `--config`)
6
+ * and prebuilds the demos. The config's default export is a `DocsKitConfig`
7
+ * or a (sync/async) function returning one.
8
+ */
9
+ import fs from 'node:fs';
10
+ import path from 'node:path';
11
+ import { pathToFileURL } from 'node:url';
12
+
13
+ import { buildDemos } from './build.ts';
14
+ import type { DocsKitConfig } from './config.ts';
15
+
16
+ const CONFIG_NAMES = ['docs-kit.config.mjs', 'docs-kit.config.js', 'docs-kit.config.ts'];
17
+
18
+ function usage(): never {
19
+ console.error('usage: docs-kit demos [build] [--watch] [--config <file>]');
20
+ process.exit(1);
21
+ }
22
+
23
+ async function main(argv: string[]) {
24
+ const args = [...argv];
25
+ const command = args.shift();
26
+ if (command !== 'demos') usage();
27
+ if (args[0] === 'build') args.shift();
28
+
29
+ let configFile: string | undefined;
30
+ let watch = false;
31
+ while (args.length) {
32
+ const arg = args.shift()!;
33
+ if (arg === '--watch' || arg === '-w') watch = true;
34
+ else if (arg === '--config' || arg === '-c') configFile = args.shift() ?? usage();
35
+ else usage();
36
+ }
37
+
38
+ configFile = configFile
39
+ ? path.resolve(configFile)
40
+ : CONFIG_NAMES.map((name) => path.resolve(name)).find((file) => fs.existsSync(file));
41
+ if (!configFile || !fs.existsSync(configFile)) {
42
+ console.error(`[docs-kit] no config found (looked for ${CONFIG_NAMES.join(', ')})`);
43
+ process.exit(1);
44
+ }
45
+
46
+ const loaded = (await import(pathToFileURL(configFile).href)) as { default?: unknown };
47
+ const exported = loaded.default;
48
+ const config = (typeof exported === 'function' ? await exported() : exported) as DocsKitConfig;
49
+
50
+ const result = await buildDemos({ config, configDir: path.dirname(configFile), watch });
51
+ if (watch) {
52
+ const stop = async () => {
53
+ await result.close();
54
+ process.exit(0);
55
+ };
56
+ process.on('SIGINT', stop);
57
+ process.on('SIGTERM', stop);
58
+ }
59
+ }
60
+
61
+ main(process.argv.slice(2)).catch((error) => {
62
+ console.error(error instanceof Error ? error.message : error);
63
+ process.exit(1);
64
+ });
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Browser-side compilers for edited demos. Picked from the manifest's
3
+ * `editor.compiler`: `browser` (esbuild-wasm in a worker, the default) or
4
+ * `remote` (POST to a server running `compileDemo` with native esbuild).
5
+ */
6
+ import type { CompileOptions, CompileRequest, CompileResult, Compiler } from './compile/core.ts';
7
+
8
+ export type {
9
+ CompileMessage,
10
+ CompileOptions,
11
+ CompileRequest,
12
+ CompileResult,
13
+ Compiler,
14
+ } from './compile/core.ts';
15
+ export { formatCompileErrors } from './compile/core.ts';
16
+
17
+ export type CompilerConfig =
18
+ | { kind: 'browser'; worker: string; wasm: string }
19
+ | { kind: 'remote'; endpoint: string };
20
+
21
+ const workers = new Map<string, { worker: Worker; nextId: number; pending: Map<number, (r: CompileResult) => void> }>();
22
+
23
+ function sharedWorker(workerUrl: string) {
24
+ let entry = workers.get(workerUrl);
25
+ if (!entry) {
26
+ const worker = new Worker(workerUrl, { type: 'module', name: 'docs-kit-compiler' });
27
+ const pending = new Map<number, (r: CompileResult) => void>();
28
+ worker.addEventListener('message', (event: MessageEvent<{ id: number; result: CompileResult }>) => {
29
+ pending.get(event.data.id)?.(event.data.result);
30
+ pending.delete(event.data.id);
31
+ });
32
+ worker.addEventListener('error', (event) => {
33
+ for (const resolve of pending.values()) {
34
+ resolve({ ok: false, errors: [{ text: `The editor's compiler crashed: ${event.message || 'unknown error'}` }] });
35
+ }
36
+ pending.clear();
37
+ });
38
+ entry = { worker, nextId: 0, pending };
39
+ workers.set(workerUrl, entry);
40
+ }
41
+ return entry;
42
+ }
43
+
44
+ /** esbuild-wasm in a (page-wide, shared) module worker. */
45
+ export function createBrowserCompiler(config: { worker: string; wasm: string }, options: CompileOptions): Compiler {
46
+ const wasmURL = new URL(config.wasm, location.href).href;
47
+ return {
48
+ compile(request: CompileRequest) {
49
+ const shared = sharedWorker(new URL(config.worker, location.href).href);
50
+ const id = ++shared.nextId;
51
+ return new Promise<CompileResult>((resolve) => {
52
+ shared.pending.set(id, resolve);
53
+ shared.worker.postMessage({ id, wasmURL, request, options });
54
+ });
55
+ },
56
+ };
57
+ }
58
+
59
+ /** POSTs `{ request, options }` as JSON; the endpoint answers with a `CompileResult`. */
60
+ export function createRemoteCompiler(config: { endpoint: string }, options: CompileOptions): Compiler {
61
+ return {
62
+ async compile(request: CompileRequest) {
63
+ try {
64
+ const response = await fetch(config.endpoint, {
65
+ method: 'POST',
66
+ headers: { 'content-type': 'application/json' },
67
+ body: JSON.stringify({ request, options }),
68
+ });
69
+ if (!response.ok) {
70
+ return { ok: false, errors: [{ text: `Compile server error ${response.status}: ${await response.text()}` }] };
71
+ }
72
+ return (await response.json()) as CompileResult;
73
+ } catch (error) {
74
+ return { ok: false, errors: [{ text: `Compile server unreachable: ${String(error)}` }] };
75
+ }
76
+ },
77
+ };
78
+ }
79
+
80
+ export function createCompiler(config: CompilerConfig, options: CompileOptions): Compiler {
81
+ return config.kind === 'remote' ? createRemoteCompiler(config, options) : createBrowserCompiler(config, options);
82
+ }