@thedatagrid/docs-kit 0.3.0 → 0.5.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 (182) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +172 -4
  3. package/dist/code/demoFiles.d.ts.map +1 -1
  4. package/dist/code/demoFiles.js +2 -2
  5. package/dist/code/demoFiles.js.map +1 -1
  6. package/dist/code/index.d.ts +1 -0
  7. package/dist/code/index.d.ts.map +1 -1
  8. package/dist/code/index.js +1 -0
  9. package/dist/code/index.js.map +1 -1
  10. package/dist/code/regions.d.ts +2 -1
  11. package/dist/code/regions.d.ts.map +1 -1
  12. package/dist/code/regions.js +12 -8
  13. package/dist/code/regions.js.map +1 -1
  14. package/dist/code/vueBlocks.d.ts +3 -0
  15. package/dist/code/vueBlocks.d.ts.map +1 -0
  16. package/dist/code/vueBlocks.js +29 -0
  17. package/dist/code/vueBlocks.js.map +1 -0
  18. package/dist/demos/build.d.ts +5 -2
  19. package/dist/demos/build.d.ts.map +1 -1
  20. package/dist/demos/build.js +244 -85
  21. package/dist/demos/build.js.map +1 -1
  22. package/dist/demos/compile/core.d.ts +9 -1
  23. package/dist/demos/compile/core.d.ts.map +1 -1
  24. package/dist/demos/compile/core.js +19 -8
  25. package/dist/demos/compile/core.js.map +1 -1
  26. package/dist/demos/compile/vue.d.ts +107 -0
  27. package/dist/demos/compile/vue.d.ts.map +1 -0
  28. package/dist/demos/compile/vue.js +187 -0
  29. package/dist/demos/compile/vue.js.map +1 -0
  30. package/dist/demos/config.d.ts +41 -7
  31. package/dist/demos/config.d.ts.map +1 -1
  32. package/dist/demos/config.js.map +1 -1
  33. package/dist/demos/index.d.ts +3 -2
  34. package/dist/demos/index.d.ts.map +1 -1
  35. package/dist/demos/index.js +1 -0
  36. package/dist/demos/index.js.map +1 -1
  37. package/dist/demos/pages.d.ts +1 -1
  38. package/dist/demos/pages.d.ts.map +1 -1
  39. package/dist/demos/pages.js +4 -1
  40. package/dist/demos/pages.js.map +1 -1
  41. package/dist/demos/runtime/vue.d.ts +3 -0
  42. package/dist/demos/runtime/vue.d.ts.map +1 -0
  43. package/dist/demos/runtime/vue.js +15 -0
  44. package/dist/demos/runtime/vue.js.map +1 -0
  45. package/dist/demos/vendor.d.ts +5 -1
  46. package/dist/demos/vendor.d.ts.map +1 -1
  47. package/dist/demos/vendor.js +6 -2
  48. package/dist/demos/vendor.js.map +1 -1
  49. package/dist/demos/worker/compile.worker.js +3 -22
  50. package/dist/demos/worker/compile.worker.js.map +1 -1
  51. package/dist/demos/worker/compileVue.worker.d.ts +2 -0
  52. package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
  53. package/dist/demos/worker/compileVue.worker.js +11 -0
  54. package/dist/demos/worker/compileVue.worker.js.map +1 -0
  55. package/dist/demos/worker/start.d.ts +7 -0
  56. package/dist/demos/worker/start.d.ts.map +1 -0
  57. package/dist/demos/worker/start.js +27 -0
  58. package/dist/demos/worker/start.js.map +1 -0
  59. package/dist/fork/codesandbox.d.ts +19 -1
  60. package/dist/fork/codesandbox.d.ts.map +1 -1
  61. package/dist/fork/codesandbox.js +35 -22
  62. package/dist/fork/codesandbox.js.map +1 -1
  63. package/dist/fork/index.d.ts +30 -0
  64. package/dist/fork/index.d.ts.map +1 -1
  65. package/dist/fork/index.js +37 -0
  66. package/dist/fork/index.js.map +1 -1
  67. package/dist/fork/stackblitz.d.ts +18 -0
  68. package/dist/fork/stackblitz.d.ts.map +1 -0
  69. package/dist/fork/stackblitz.js +98 -0
  70. package/dist/fork/stackblitz.js.map +1 -0
  71. package/dist/frameworks/index.d.ts +4 -0
  72. package/dist/frameworks/index.d.ts.map +1 -0
  73. package/dist/frameworks/index.js +4 -0
  74. package/dist/frameworks/index.js.map +1 -0
  75. package/dist/frameworks/preference.d.ts +10 -0
  76. package/dist/frameworks/preference.d.ts.map +1 -0
  77. package/dist/frameworks/preference.js +34 -0
  78. package/dist/frameworks/preference.js.map +1 -0
  79. package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
  80. package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
  81. package/dist/frameworks/react/FrameworkBanner.js +50 -0
  82. package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
  83. package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
  84. package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
  85. package/dist/frameworks/react/FrameworkContent.js +25 -0
  86. package/dist/frameworks/react/FrameworkContent.js.map +1 -0
  87. package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
  88. package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
  89. package/dist/frameworks/react/FrameworkLinks.js +50 -0
  90. package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
  91. package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
  92. package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
  93. package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
  94. package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
  95. package/dist/frameworks/react/index.d.ts +6 -0
  96. package/dist/frameworks/react/index.d.ts.map +1 -0
  97. package/dist/frameworks/react/index.js +6 -0
  98. package/dist/frameworks/react/index.js.map +1 -0
  99. package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
  100. package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
  101. package/dist/frameworks/react/useFrameworkPreference.js +45 -0
  102. package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
  103. package/dist/frameworks/routeTree.d.ts +24 -0
  104. package/dist/frameworks/routeTree.d.ts.map +1 -0
  105. package/dist/frameworks/routeTree.js +31 -0
  106. package/dist/frameworks/routeTree.js.map +1 -0
  107. package/dist/frameworks/routing.d.ts +105 -0
  108. package/dist/frameworks/routing.d.ts.map +1 -0
  109. package/dist/frameworks/routing.js +142 -0
  110. package/dist/frameworks/routing.js.map +1 -0
  111. package/dist/frameworks/styles.css +104 -0
  112. package/dist/react/Demo.d.ts +12 -0
  113. package/dist/react/Demo.d.ts.map +1 -1
  114. package/dist/react/Demo.js +10 -4
  115. package/dist/react/Demo.js.map +1 -1
  116. package/dist/react/DemoShell.d.ts +5 -1
  117. package/dist/react/DemoShell.d.ts.map +1 -1
  118. package/dist/react/DemoShell.js +9 -6
  119. package/dist/react/DemoShell.js.map +1 -1
  120. package/dist/react/editor.d.ts.map +1 -1
  121. package/dist/react/editor.js +3 -0
  122. package/dist/react/editor.js.map +1 -1
  123. package/dist/react/fork.d.ts +4 -3
  124. package/dist/react/fork.d.ts.map +1 -1
  125. package/dist/react/fork.js +8 -6
  126. package/dist/react/fork.js.map +1 -1
  127. package/dist/react/styles.css +10 -0
  128. package/dist/remark/index.d.ts +2 -0
  129. package/dist/remark/index.d.ts.map +1 -1
  130. package/dist/remark/index.js +2 -0
  131. package/dist/remark/index.js.map +1 -1
  132. package/dist/remark/remarkDemoFences.d.ts +13 -0
  133. package/dist/remark/remarkDemoFences.d.ts.map +1 -1
  134. package/dist/remark/remarkDemoFences.js +48 -4
  135. package/dist/remark/remarkDemoFences.js.map +1 -1
  136. package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
  137. package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
  138. package/dist/remark/remarkFrameworkLinks.js +77 -0
  139. package/dist/remark/remarkFrameworkLinks.js.map +1 -0
  140. package/dist/remark/remarkFrameworkText.d.ts +16 -0
  141. package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
  142. package/dist/remark/remarkFrameworkText.js +39 -0
  143. package/dist/remark/remarkFrameworkText.js.map +1 -0
  144. package/package.json +29 -4
  145. package/src/code/demoFiles.ts +2 -2
  146. package/src/code/index.ts +1 -0
  147. package/src/code/regions.ts +14 -8
  148. package/src/code/vueBlocks.ts +25 -0
  149. package/src/demos/build.ts +293 -99
  150. package/src/demos/compile/core.ts +27 -7
  151. package/src/demos/compile/vue.ts +259 -0
  152. package/src/demos/config.ts +59 -7
  153. package/src/demos/index.ts +13 -0
  154. package/src/demos/pages.ts +4 -2
  155. package/src/demos/runtime/vue.ts +17 -0
  156. package/src/demos/vendor.ts +6 -2
  157. package/src/demos/worker/compile.worker.ts +3 -30
  158. package/src/demos/worker/compileVue.worker.ts +13 -0
  159. package/src/demos/worker/start.ts +35 -0
  160. package/src/fork/codesandbox.ts +51 -24
  161. package/src/fork/index.ts +56 -0
  162. package/src/fork/stackblitz.ts +108 -0
  163. package/src/frameworks/index.ts +21 -0
  164. package/src/frameworks/preference.ts +35 -0
  165. package/src/frameworks/react/FrameworkBanner.tsx +112 -0
  166. package/src/frameworks/react/FrameworkContent.tsx +33 -0
  167. package/src/frameworks/react/FrameworkLinks.tsx +52 -0
  168. package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
  169. package/src/frameworks/react/index.ts +10 -0
  170. package/src/frameworks/react/useFrameworkPreference.ts +91 -0
  171. package/src/frameworks/routeTree.ts +54 -0
  172. package/src/frameworks/routing.ts +194 -0
  173. package/src/frameworks/styles.css +104 -0
  174. package/src/react/Demo.tsx +21 -2
  175. package/src/react/DemoShell.tsx +15 -7
  176. package/src/react/editor.ts +2 -0
  177. package/src/react/fork.ts +14 -6
  178. package/src/react/styles.css +10 -0
  179. package/src/remark/index.ts +6 -0
  180. package/src/remark/remarkDemoFences.ts +58 -3
  181. package/src/remark/remarkFrameworkLinks.ts +96 -0
  182. package/src/remark/remarkFrameworkText.ts +44 -0
@@ -9,6 +9,8 @@
9
9
  */
10
10
  import type * as esbuildTypes from 'esbuild';
11
11
 
12
+ import { createVueModules, type VueModules, type VueSfcCompiler } from './vue.ts';
13
+
12
14
  export type EsbuildLike = Pick<typeof esbuildTypes, 'build'>;
13
15
 
14
16
  export type CompileRequest = {
@@ -26,6 +28,14 @@ export type CompileOptions = {
26
28
  minify?: boolean;
27
29
  /** Inline source maps, for readable stack traces of edited code. Default `true`. */
28
30
  sourcemap?: boolean;
31
+ /** Package of the automatic JSX runtime. Default `react`; the Vue adapter sets `vue`. */
32
+ jsxImportSource?: string;
33
+ };
34
+
35
+ /** What a compile needs besides esbuild; not serializable, so not part of `CompileOptions`. */
36
+ export type CompileTools = {
37
+ /** `@vue/compiler-sfc`, for demos with `.vue` files. */
38
+ vue?: VueSfcCompiler;
29
39
  };
30
40
 
31
41
  export type CompileMessage = {
@@ -46,7 +56,7 @@ export interface Compiler {
46
56
  }
47
57
 
48
58
  /** Extensions tried for extensionless relative imports, in order. */
49
- export const RESOLVE_EXTENSIONS = ['', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.css', '.json'];
59
+ export const RESOLVE_EXTENSIONS = ['', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.vue', '.css', '.json'];
50
60
 
51
61
  const VFS = 'docs-kit-vfs';
52
62
  const STUB = 'docs-kit-stub';
@@ -132,7 +142,7 @@ export function externalImportsPlugin(stubImports: string[] | undefined): esbuil
132
142
  };
133
143
  }
134
144
 
135
- function virtualFilesPlugin(request: CompileRequest): esbuildTypes.Plugin {
145
+ function virtualFilesPlugin(request: CompileRequest, vue: VueModules | null): esbuildTypes.Plugin {
136
146
  return {
137
147
  name: 'docs-kit:virtual-files',
138
148
  setup(build) {
@@ -154,10 +164,13 @@ function virtualFilesPlugin(request: CompileRequest): esbuildTypes.Plugin {
154
164
  }
155
165
  return { path: resolved, namespace: VFS };
156
166
  });
157
- build.onLoad({ filter: /.*/, namespace: VFS }, (args) => ({
158
- contents: request.files[args.path],
159
- loader: loaderForPath(args.path),
160
- }));
167
+ build.onLoad({ filter: /.*/, namespace: VFS }, (args) => {
168
+ if (/\.vue$/.test(args.path)) {
169
+ if (!vue) return { errors: [{ text: `${args.path}: this demo build has no Vue compiler` }] };
170
+ return vue.load(args.path, request.files[args.path]);
171
+ }
172
+ return { contents: request.files[args.path], loader: loaderForPath(args.path) };
173
+ });
161
174
  },
162
175
  };
163
176
  }
@@ -180,6 +193,7 @@ export function demoBuildOptions(options: CompileOptions): esbuildTypes.BuildOpt
180
193
  platform: 'browser',
181
194
  target: 'es2022',
182
195
  jsx: 'automatic',
196
+ jsxImportSource: options.jsxImportSource,
183
197
  define: options.define,
184
198
  minify: options.minify,
185
199
  legalComments: 'none',
@@ -191,7 +205,9 @@ export async function compileDemo(
191
205
  esbuild: EsbuildLike,
192
206
  request: CompileRequest,
193
207
  options: CompileOptions = {},
208
+ tools: CompileTools = {},
194
209
  ): Promise<CompileResult> {
210
+ const vue = tools.vue ? createVueModules(tools.vue, { production: options.minify }) : null;
195
211
  try {
196
212
  const result = await esbuild.build({
197
213
  ...demoBuildOptions(options),
@@ -200,7 +216,11 @@ export async function compileDemo(
200
216
  write: false,
201
217
  sourcemap: options.sourcemap === false ? false : 'inline',
202
218
  // Edited code may be mid-typing; keep going and report everything.
203
- plugins: [externalImportsPlugin(options.stubImports), virtualFilesPlugin(request)],
219
+ plugins: [
220
+ externalImportsPlugin(options.stubImports),
221
+ ...(vue ? [vue.plugin] : []),
222
+ virtualFilesPlugin(request, vue),
223
+ ],
204
224
  });
205
225
  let js = '';
206
226
  let css = '';
@@ -0,0 +1,259 @@
1
+ /**
2
+ * Vue single-file components for the demo builds, on top of
3
+ * `@vue/compiler-sfc`. The compiler is a parameter (like esbuild in `core.ts`):
4
+ * the prebuild loads it in Node with `import()`, the editor's worker bundles
5
+ * its browser build, so this module has no Node or DOM dependencies.
6
+ *
7
+ * An SFC becomes one module that imports its other blocks as virtual modules
8
+ * (`docs-kit-vue:<block>:<file>`): the template's render function when it
9
+ * can't be inlined, and one CSS module per `<style>`, which esbuild bundles
10
+ * into the demo's stylesheet.
11
+ *
12
+ * Supported: `<script>` / `<script setup>` in JS or TS, `<template>` (HTML),
13
+ * plain-CSS `<style>` with or without `scoped`. Preprocessors, `src=` blocks
14
+ * and CSS modules fail with a message naming the block.
15
+ */
16
+ import type * as esbuildTypes from 'esbuild';
17
+
18
+ import type { CompileMessage } from './core.ts';
19
+
20
+ type SfcBlock = {
21
+ content: string;
22
+ lang?: string;
23
+ src?: string;
24
+ attrs: Record<string, string | true>;
25
+ loc: { start: { line: number; column: number } };
26
+ };
27
+
28
+ type SfcDescriptor = {
29
+ filename: string;
30
+ template: (SfcBlock & { ast?: unknown }) | null;
31
+ script: SfcBlock | null;
32
+ scriptSetup: SfcBlock | null;
33
+ styles: (SfcBlock & { scoped?: boolean; module?: string | boolean })[];
34
+ customBlocks: SfcBlock[];
35
+ };
36
+
37
+ type SfcError = Error & { loc?: { start?: { line: number; column: number }; line?: number; column?: number } };
38
+
39
+ /** The part of `@vue/compiler-sfc` the demo builds use. */
40
+ export type VueSfcCompiler = {
41
+ parse(
42
+ source: string,
43
+ options?: { filename?: string; templateParseOptions?: Record<string, unknown> },
44
+ ): { descriptor: SfcDescriptor; errors: SfcError[] };
45
+ compileScript(descriptor: SfcDescriptor, options: Record<string, unknown>): { content: string; bindings?: unknown };
46
+ compileTemplate(options: Record<string, unknown>): { code: string; errors: (string | SfcError)[] };
47
+ compileStyleAsync(options: Record<string, unknown>): Promise<{ code: string; errors: SfcError[] }>;
48
+ };
49
+
50
+ export type VueModule = { contents: string; loader: esbuildTypes.Loader };
51
+
52
+ export class VueCompileError extends Error {
53
+ messages: CompileMessage[];
54
+
55
+ constructor(messages: CompileMessage[]) {
56
+ super(messages.map((message) => message.text).join('\n'));
57
+ this.name = 'VueCompileError';
58
+ this.messages = messages;
59
+ }
60
+ }
61
+
62
+ const VUE_SCHEME = 'docs-kit-vue:';
63
+ const VUE_NAMESPACE = 'docs-kit-vue';
64
+
65
+ const SCRIPT_LANGS = new Set(['js', 'ts', 'jsx', 'tsx']);
66
+
67
+ /** FNV-1a, as 8 hex digits: a stable scope id without `node:crypto`. */
68
+ function hashId(text: string): string {
69
+ let hash = 0x811c9dc5;
70
+ for (let i = 0; i < text.length; i++) {
71
+ hash ^= text.charCodeAt(i);
72
+ hash = Math.imul(hash, 0x01000193);
73
+ }
74
+ return (hash >>> 0).toString(16).padStart(8, '0');
75
+ }
76
+
77
+ function toMessage(error: string | SfcError, file: string, source: string, lineOffset = 0): CompileMessage {
78
+ if (typeof error === 'string') return { text: error, file };
79
+ const start = error.loc?.start ?? (error.loc?.line != null ? (error.loc as { line: number; column: number }) : null);
80
+ if (!start) return { text: error.message, file };
81
+ const line = start.line + lineOffset;
82
+ return {
83
+ // the compiler appends a code frame to some messages; the overlay shows `lineText` instead
84
+ text: error.message.split('\n')[0],
85
+ file,
86
+ line,
87
+ column: Math.max(0, start.column - 1),
88
+ lineText: source.split('\n')[line - 1],
89
+ };
90
+ }
91
+
92
+ function unsupported(block: string, what: string, file: string): never {
93
+ throw new VueCompileError([{ text: `<${block}> ${what} is not supported in docs demos`, file }]);
94
+ }
95
+
96
+ export type CompiledVueSfc = {
97
+ main: VueModule;
98
+ /** The other blocks, by the specifier the main module imports them with. */
99
+ parts: Record<string, VueModule>;
100
+ };
101
+
102
+ /** Compiles one SFC. Throws `VueCompileError` with one message per problem. */
103
+ export async function compileVueSfc(
104
+ sfc: VueSfcCompiler,
105
+ source: string,
106
+ filename: string,
107
+ options: { production?: boolean } = {},
108
+ ): Promise<CompiledVueSfc> {
109
+ // no comment nodes: `<!-- #highlight -->` markers are for the docs, not the demo
110
+ const { descriptor, errors } = sfc.parse(source, { filename, templateParseOptions: { comments: false } });
111
+ if (errors.length) throw new VueCompileError(errors.map((error) => toMessage(error, filename, source)));
112
+
113
+ const { template, script, scriptSetup, styles } = descriptor;
114
+ for (const [name, block] of [['template', template], ['script', script], ['script setup', scriptSetup]] as const) {
115
+ if (block?.src) unsupported(name, 'with `src`', filename);
116
+ }
117
+ if (template?.lang && template.lang !== 'html') unsupported('template', `lang="${template.lang}"`, filename);
118
+ for (const block of [script, scriptSetup]) {
119
+ if (block?.lang && !SCRIPT_LANGS.has(block.lang)) unsupported('script', `lang="${block.lang}"`, filename);
120
+ }
121
+ for (const style of styles) {
122
+ if (style.src) unsupported('style', 'with `src`', filename);
123
+ if (style.lang && style.lang !== 'css') unsupported('style', `lang="${style.lang}"`, filename);
124
+ if (style.module) unsupported('style', 'with `module`', filename);
125
+ }
126
+
127
+ const id = hashId(filename);
128
+ const scoped = styles.some((style) => style.scoped);
129
+ const lang = scriptSetup?.lang ?? script?.lang ?? 'js';
130
+ const isTS = lang === 'ts' || lang === 'tsx';
131
+ const loader = lang as esbuildTypes.Loader;
132
+ const compilerOptions = { comments: false, expressionPlugins: isTS ? ['typescript'] : undefined };
133
+ const production = options.production ?? false;
134
+ const parts: Record<string, VueModule> = {};
135
+ const lines: string[] = [];
136
+
137
+ for (const [index, style] of styles.entries()) {
138
+ const result = await sfc.compileStyleAsync({
139
+ source: style.content,
140
+ filename,
141
+ id,
142
+ scoped: !!style.scoped,
143
+ isProd: production,
144
+ });
145
+ if (result.errors.length) {
146
+ // positions are relative to the block
147
+ const offset = style.loc.start.line - 1;
148
+ throw new VueCompileError(result.errors.map((error) => toMessage(error, filename, source, offset)));
149
+ }
150
+ const specifier = `${VUE_SCHEME}style:${index}:${filename}`;
151
+ parts[specifier] = { contents: result.code, loader: 'css' };
152
+ lines.push(`import ${JSON.stringify(specifier)};`);
153
+ }
154
+
155
+ let bindings: unknown;
156
+ if (script || scriptSetup) {
157
+ try {
158
+ const compiled = sfc.compileScript(descriptor, {
159
+ id,
160
+ isProd: production,
161
+ // `<script setup>`: the render function is compiled into `setup()`
162
+ inlineTemplate: !!scriptSetup,
163
+ genDefaultAs: '__sfc__',
164
+ templateOptions: { transformAssetUrls: false, compilerOptions },
165
+ });
166
+ bindings = compiled.bindings;
167
+ lines.push(compiled.content);
168
+ } catch (error) {
169
+ // the position is relative to the block, but the message carries a code frame of the file
170
+ throw new VueCompileError([{ text: (error as Error).message, file: filename }]);
171
+ }
172
+ } else {
173
+ lines.push('const __sfc__ = {};');
174
+ }
175
+
176
+ if (template && !scriptSetup) {
177
+ const compiled = sfc.compileTemplate({
178
+ source: template.content,
179
+ ast: template.ast,
180
+ filename,
181
+ id,
182
+ scoped,
183
+ isProd: production,
184
+ transformAssetUrls: false,
185
+ compilerOptions: { ...compilerOptions, bindingMetadata: bindings },
186
+ });
187
+ if (compiled.errors.length) {
188
+ throw new VueCompileError(compiled.errors.map((error) => toMessage(error, filename, source)));
189
+ }
190
+ const specifier = `${VUE_SCHEME}template:${filename}`;
191
+ parts[specifier] = { contents: compiled.code, loader: isTS ? 'ts' : 'js' };
192
+ lines.push(`import { render as __sfc_render__ } from ${JSON.stringify(specifier)};`);
193
+ lines.push('__sfc__.render = __sfc_render__;');
194
+ }
195
+
196
+ if (scoped) lines.push(`__sfc__.__scopeId = ${JSON.stringify(`data-v-${id}`)};`);
197
+ if (!production) lines.push(`__sfc__.__file = ${JSON.stringify(filename)};`);
198
+ lines.push('export default __sfc__;');
199
+
200
+ return { main: { contents: lines.join('\n'), loader }, parts };
201
+ }
202
+
203
+ export type VueModules = {
204
+ /** Compiles an SFC and returns its main module; errors come back as esbuild messages. */
205
+ load(filename: string, source: string): Promise<esbuildTypes.OnLoadResult>;
206
+ /** Resolves and loads the virtual block modules. Must run before any catch-all resolver. */
207
+ plugin: esbuildTypes.Plugin;
208
+ };
209
+
210
+ /** The SFC compile step plus the plugin that serves each SFC's block modules. */
211
+ export function createVueModules(sfc: VueSfcCompiler, options: { production?: boolean } = {}): VueModules {
212
+ const parts = new Map<string, VueModule>();
213
+ return {
214
+ async load(filename, source) {
215
+ try {
216
+ const compiled = await compileVueSfc(sfc, source, filename, options);
217
+ for (const [specifier, part] of Object.entries(compiled.parts)) parts.set(specifier, part);
218
+ return compiled.main;
219
+ } catch (error) {
220
+ if (!(error instanceof VueCompileError)) throw error;
221
+ return {
222
+ errors: error.messages.map((message) => ({
223
+ text: message.text,
224
+ location:
225
+ message.line == null
226
+ ? { file: message.file }
227
+ : { file: message.file, line: message.line, column: message.column, lineText: message.lineText },
228
+ })),
229
+ };
230
+ }
231
+ },
232
+ plugin: {
233
+ name: 'docs-kit:vue-blocks',
234
+ setup(build) {
235
+ build.onResolve({ filter: /^docs-kit-vue:/ }, (args) => ({ path: args.path, namespace: VUE_NAMESPACE }));
236
+ build.onLoad({ filter: /.*/, namespace: VUE_NAMESPACE }, (args) => parts.get(args.path));
237
+ },
238
+ },
239
+ };
240
+ }
241
+
242
+ /** For builds that read `.vue` files from disk (the prebuild). */
243
+ export function vueFilesPlugin(
244
+ modules: VueModules,
245
+ readFile: (filePath: string) => string | Promise<string>,
246
+ /** The name shown in errors and used for the scope id. Default: the absolute path. */
247
+ displayName: (filePath: string) => string = (filePath) => filePath,
248
+ ): esbuildTypes.Plugin {
249
+ return {
250
+ name: 'docs-kit:vue-files',
251
+ setup(build) {
252
+ modules.plugin.setup(build);
253
+ build.onLoad({ filter: /\.vue$/, namespace: 'file' }, async (args) => {
254
+ const result = await modules.load(displayName(args.path), await readFile(args.path));
255
+ return { ...result, resolveDir: args.path.replace(/[\\/][^\\/]*$/, '') };
256
+ });
257
+ },
258
+ };
259
+ }
@@ -18,14 +18,55 @@ export type ForkConfig = {
18
18
  /** `dependencies` of the forked sandbox's package.json (the published versions to pin). */
19
19
  dependencies?: Record<string, string>;
20
20
  devDependencies?: Record<string, string>;
21
- /** Code placed at the top of the sandbox entry (`src/index.tsx`), e.g. CSS imports. */
21
+ /** Code placed at the top of the sandbox entry (`src/index.tsx` / `src/main.ts`), e.g. CSS imports. */
22
22
  entryPrelude?: string;
23
23
  /** Extra CSS for the sandbox (`src/styles.css`). */
24
24
  styles?: string;
25
25
  /** Literal replacements applied to forked files (on top of `sourceReplacements`). */
26
26
  sourceReplacements?: Record<string, string>;
27
+ /** HTML put in the `<head>` of the sandbox page (`index.html`), e.g. a `<script src>`. */
28
+ indexHtmlHead?: string;
29
+ /**
30
+ * Settings for some demos only, e.g. the ones that need Tailwind. A variant
31
+ * applies to a demo when `match` (a regular expression source) matches the
32
+ * path of its entry file. Its `dependencies`, `devDependencies` and
33
+ * `sourceReplacements` are merged over the ones above; its `entryPrelude`,
34
+ * `styles` and `indexHtmlHead` are added after them.
35
+ */
36
+ variants?: ForkVariant[];
27
37
  };
28
38
 
39
+ export type ForkVariant = Omit<ForkConfig, 'variants'> & {
40
+ /** Regular expression source, tested against the entry's path: `-tailwind\\.demo\\.tsx$`. */
41
+ match: string;
42
+ };
43
+
44
+ /** The frameworks demos can be written in. */
45
+ export type DemoFramework = 'react' | 'vue';
46
+
47
+ /**
48
+ * What a framework's build can set on its own. `libraries`, `include`,
49
+ * `stubImports`, `bootstrap`, `css` and `fork` are framework-specific by
50
+ * nature: a framework under `frameworks` starts without them. Everything
51
+ * else falls back to the top-level config.
52
+ */
53
+ export type FrameworkConfig = Pick<
54
+ DocsKitConfig,
55
+ | 'demoSuffix'
56
+ | 'routeForPage'
57
+ | 'libraries'
58
+ | 'include'
59
+ | 'stubImports'
60
+ | 'define'
61
+ | 'bootstrapDefine'
62
+ | 'sourceReplacements'
63
+ | 'bootstrap'
64
+ | 'css'
65
+ | 'pageStyle'
66
+ | 'themeClasses'
67
+ | 'fork'
68
+ >;
69
+
29
70
  export type DocsKitConfig = {
30
71
  /** Site root; relative paths below resolve against it. Default: the config file's folder. */
31
72
  root?: string;
@@ -35,7 +76,7 @@ export type DocsKitConfig = {
35
76
  outDir?: string;
36
77
  /** Public URL of `outDir`. Default `/gen/demos`. */
37
78
  urlRoot?: string;
38
- /** Demo entry suffix. Default `.demo.tsx`. */
79
+ /** Demo entry suffix. Default `.demo.tsx` for React, `.demo.vue` for Vue. */
39
80
  demoSuffix?: string;
40
81
  /** Page files (for the "see example in docs" link of a standalone demo). Default `.page.md`. */
41
82
  pageExtension?: string;
@@ -47,10 +88,21 @@ export type DocsKitConfig = {
47
88
  * "see in docs" links find the live demos.
48
89
  */
49
90
  fenceDefaults?: FenceDefaults;
50
- /** Content-relative page path (without extension) → route. Default: `/<path>`, `index` dropped. */
51
- routeForPage?: (pagePath: string) => string;
52
- /** Only `react` for now. */
53
- framework?: 'react';
91
+ /**
92
+ * Content-relative page path (without extension) → route, for the "see this
93
+ * example in the docs" link of a demo opened on its own; `null`: no link.
94
+ * Default: `/<path>`, `index` dropped.
95
+ */
96
+ routeForPage?: (pagePath: string) => string | null;
97
+ /** The framework of the top-level config. Default `react`. */
98
+ framework?: DemoFramework;
99
+ /**
100
+ * More frameworks, built next to the primary one: a sibling
101
+ * `foo.demo.vue` next to `foo.demo.tsx`. Each gets its own import map,
102
+ * runtime and manifest under `<outDir>/_<framework>` (the primary keeps
103
+ * `<outDir>`). Vue needs `vue` and `@vue/compiler-sfc` installed in the site.
104
+ */
105
+ frameworks?: Partial<Record<DemoFramework, FrameworkConfig>>;
54
106
  /** Packages built from source, keyed by import specifier. */
55
107
  libraries?: Record<string, LibrarySource>;
56
108
  /** Bare specifiers always put in the import map, on top of what demos import. */
@@ -93,7 +145,7 @@ export type DemoManifestEntry = {
93
145
  /** Written to `<outDir>/manifest.json`; the only thing the docs UI reads from the build. */
94
146
  export type DemoManifest = {
95
147
  version: 1;
96
- framework: 'react';
148
+ framework: DemoFramework;
97
149
  urlRoot: string;
98
150
  demoSuffix: string;
99
151
  importMap: { imports: Record<string, string> };
@@ -1,10 +1,12 @@
1
1
  export { buildDemos, type BuildDemosOptions, type BuildDemosResult } from './build.ts';
2
2
  export {
3
3
  defineConfig,
4
+ type DemoFramework,
4
5
  type DemoManifest,
5
6
  type DemoManifestEntry,
6
7
  type DocsKitConfig,
7
8
  type ForkConfig,
9
+ type FrameworkConfig,
8
10
  type LibrarySource,
9
11
  } from './config.ts';
10
12
  export {
@@ -16,9 +18,20 @@ export {
16
18
  type CompileOptions,
17
19
  type CompileRequest,
18
20
  type CompileResult,
21
+ type CompileTools,
19
22
  type Compiler,
20
23
  type EsbuildLike,
21
24
  } from './compile/core.ts';
25
+ export {
26
+ compileVueSfc,
27
+ createVueModules,
28
+ VueCompileError,
29
+ vueFilesPlugin,
30
+ type CompiledVueSfc,
31
+ type VueModule,
32
+ type VueModules,
33
+ type VueSfcCompiler,
34
+ } from './compile/vue.ts';
22
35
  export type { CompilerConfig } from './client.ts';
23
36
  export type { DemoAdapter, DocsTheme, SiteBootstrap } from './runtime/iframe.ts';
24
37
  export { slugifyDemoTitle } from './slug.ts';
@@ -56,7 +56,7 @@ export function findDocsLinks(options: {
56
56
  contentDir: string;
57
57
  pageExtension: string;
58
58
  demoSuffix: string;
59
- routeForPage: (pagePath: string) => string;
59
+ routeForPage: (pagePath: string) => string | null;
60
60
  anchorPrefix?: string;
61
61
  fenceDefaults?: FenceDefaults;
62
62
  }): Map<string, string> {
@@ -99,7 +99,9 @@ export function findDocsLinks(options: {
99
99
  const fenceTitle = /\btitle=(?:"([^"]*)"|'([^']*)')/.exec(info);
100
100
  title = fenceTitle?.[1] ?? fenceTitle?.[2] ?? `${path.basename(fileName)}`;
101
101
  }
102
- links.set(demoId, `${routeForPage(pagePath)}#${anchorPrefix}${slugifyDemoTitle(title)}`);
102
+ const route = routeForPage(pagePath);
103
+ if (route == null) continue;
104
+ links.set(demoId, `${route}#${anchorPrefix}${slugifyDemoTitle(title)}`);
103
105
  }
104
106
  }
105
107
  return links;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Vue adapter for the iframe runtime. `vue` stays a bare import: the builder
3
+ * externalizes it, so the iframe's import map hands the runtime, the library
4
+ * and the demo the same Vue instance.
5
+ */
6
+ import { createApp, type Component } from 'vue';
7
+
8
+ import type { DemoAdapter } from './iframe.ts';
9
+
10
+ export const vueAdapter: DemoAdapter = {
11
+ render(target, component, onError) {
12
+ const app = createApp(component as Component);
13
+ app.config.errorHandler = (error) => onError(error);
14
+ app.mount(target);
15
+ return { unmount: () => app.unmount() };
16
+ },
17
+ };
@@ -20,9 +20,13 @@ const RESERVED = new Set(
20
20
  ),
21
21
  );
22
22
 
23
- /** `@scope/pkg/sub` → `scope__pkg__sub`, safe as an output file name. */
23
+ /**
24
+ * `@scope/pkg/sub` → `scope__pkg__sub`, safe as a file name. Dots go too
25
+ * (`pkg/theme.css` → `pkg__theme_css`): the entry module is `<name>.mjs`, and
26
+ * a `….css.mjs` file is what vanilla-extract and similar plugins claim.
27
+ */
24
28
  export function entryNameFor(specifier: string): string {
25
- return specifier.replace(/^@/, '').replace(/\//g, '__').replace(/[^\w.-]/g, '_');
29
+ return specifier.replace(/^@/, '').replace(/\//g, '__').replace(/[^\w-]/g, '_');
26
30
  }
27
31
 
28
32
  type ExportShape = { names: string[]; hasDefault: boolean } | null;
@@ -1,35 +1,8 @@
1
1
  /// <reference lib="webworker" />
2
2
  /**
3
3
  * Module worker that rebuilds edited demo files with esbuild-wasm. Bundled by
4
- * the demo builder into `<outDir>/_editor/compile-worker-[hash].js`; the
5
- * wasm binary is passed in with the first request, so it's only downloaded
6
- * when someone edits a demo.
4
+ * the demo builder into `<outDir>/_editor/compile-worker-[hash].js`.
7
5
  */
8
- import * as esbuild from 'esbuild-wasm';
6
+ import { startCompileWorker } from './start.ts';
9
7
 
10
- import { compileDemo, type CompileOptions, type CompileRequest } from '../compile/core.ts';
11
-
12
- type WorkerRequest = {
13
- id: number;
14
- wasmURL: string;
15
- request: CompileRequest;
16
- options: CompileOptions;
17
- };
18
-
19
- let ready: Promise<void> | null = null;
20
-
21
- self.addEventListener('message', async (event: MessageEvent<WorkerRequest>) => {
22
- const { id, wasmURL, request, options } = event.data;
23
- try {
24
- ready ??= esbuild.initialize({ wasmURL, worker: false });
25
- await ready;
26
- const result = await compileDemo(esbuild, request, options);
27
- self.postMessage({ id, result });
28
- } catch (error) {
29
- ready = null;
30
- self.postMessage({
31
- id,
32
- result: { ok: false, errors: [{ text: `The editor's compiler failed to start: ${String(error)}` }] },
33
- });
34
- }
35
- });
8
+ startCompileWorker();
@@ -0,0 +1,13 @@
1
+ /// <reference lib="webworker" />
2
+ /**
3
+ * The compile worker for Vue demos: esbuild-wasm plus `@vue/compiler-sfc`
4
+ * (its browser build, resolved from the site). Bundled by the demo builder
5
+ * into `<outDir>/_editor/compile-worker-vue-[hash].js`, only for sites with a
6
+ * Vue framework.
7
+ */
8
+ import * as sfc from '@vue/compiler-sfc';
9
+
10
+ import type { VueSfcCompiler } from '../compile/vue.ts';
11
+ import { startCompileWorker } from './start.ts';
12
+
13
+ startCompileWorker({ vue: sfc as unknown as VueSfcCompiler });
@@ -0,0 +1,35 @@
1
+ /// <reference lib="webworker" />
2
+ import * as esbuild from 'esbuild-wasm';
3
+
4
+ import { compileDemo, type CompileOptions, type CompileRequest, type CompileTools } from '../compile/core.ts';
5
+
6
+ type WorkerRequest = {
7
+ id: number;
8
+ wasmURL: string;
9
+ request: CompileRequest;
10
+ options: CompileOptions;
11
+ };
12
+
13
+ /**
14
+ * Answers compile requests with esbuild-wasm. The wasm binary's URL comes
15
+ * with the first request, so it's only downloaded when someone edits a demo.
16
+ */
17
+ export function startCompileWorker(tools: CompileTools = {}) {
18
+ let ready: Promise<void> | null = null;
19
+
20
+ self.addEventListener('message', async (event: MessageEvent<WorkerRequest>) => {
21
+ const { id, wasmURL, request, options } = event.data;
22
+ try {
23
+ ready ??= esbuild.initialize({ wasmURL, worker: false });
24
+ await ready;
25
+ const result = await compileDemo(esbuild, request, options, tools);
26
+ self.postMessage({ id, result });
27
+ } catch (error) {
28
+ ready = null;
29
+ self.postMessage({
30
+ id,
31
+ result: { ok: false, errors: [{ text: `The editor's compiler failed to start: ${String(error)}` }] },
32
+ });
33
+ }
34
+ });
35
+ }