@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.
- package/CHANGELOG.md +27 -0
- package/README.md +172 -4
- package/dist/code/demoFiles.d.ts.map +1 -1
- package/dist/code/demoFiles.js +2 -2
- package/dist/code/demoFiles.js.map +1 -1
- package/dist/code/index.d.ts +1 -0
- package/dist/code/index.d.ts.map +1 -1
- package/dist/code/index.js +1 -0
- package/dist/code/index.js.map +1 -1
- package/dist/code/regions.d.ts +2 -1
- package/dist/code/regions.d.ts.map +1 -1
- package/dist/code/regions.js +12 -8
- package/dist/code/regions.js.map +1 -1
- package/dist/code/vueBlocks.d.ts +3 -0
- package/dist/code/vueBlocks.d.ts.map +1 -0
- package/dist/code/vueBlocks.js +29 -0
- package/dist/code/vueBlocks.js.map +1 -0
- package/dist/demos/build.d.ts +5 -2
- package/dist/demos/build.d.ts.map +1 -1
- package/dist/demos/build.js +244 -85
- package/dist/demos/build.js.map +1 -1
- package/dist/demos/compile/core.d.ts +9 -1
- package/dist/demos/compile/core.d.ts.map +1 -1
- package/dist/demos/compile/core.js +19 -8
- package/dist/demos/compile/core.js.map +1 -1
- package/dist/demos/compile/vue.d.ts +107 -0
- package/dist/demos/compile/vue.d.ts.map +1 -0
- package/dist/demos/compile/vue.js +187 -0
- package/dist/demos/compile/vue.js.map +1 -0
- package/dist/demos/config.d.ts +41 -7
- package/dist/demos/config.d.ts.map +1 -1
- package/dist/demos/config.js.map +1 -1
- package/dist/demos/index.d.ts +3 -2
- package/dist/demos/index.d.ts.map +1 -1
- package/dist/demos/index.js +1 -0
- package/dist/demos/index.js.map +1 -1
- package/dist/demos/pages.d.ts +1 -1
- package/dist/demos/pages.d.ts.map +1 -1
- package/dist/demos/pages.js +4 -1
- package/dist/demos/pages.js.map +1 -1
- package/dist/demos/runtime/vue.d.ts +3 -0
- package/dist/demos/runtime/vue.d.ts.map +1 -0
- package/dist/demos/runtime/vue.js +15 -0
- package/dist/demos/runtime/vue.js.map +1 -0
- package/dist/demos/vendor.d.ts +5 -1
- package/dist/demos/vendor.d.ts.map +1 -1
- package/dist/demos/vendor.js +6 -2
- package/dist/demos/vendor.js.map +1 -1
- package/dist/demos/worker/compile.worker.js +3 -22
- package/dist/demos/worker/compile.worker.js.map +1 -1
- package/dist/demos/worker/compileVue.worker.d.ts +2 -0
- package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
- package/dist/demos/worker/compileVue.worker.js +11 -0
- package/dist/demos/worker/compileVue.worker.js.map +1 -0
- package/dist/demos/worker/start.d.ts +7 -0
- package/dist/demos/worker/start.d.ts.map +1 -0
- package/dist/demos/worker/start.js +27 -0
- package/dist/demos/worker/start.js.map +1 -0
- package/dist/fork/codesandbox.d.ts +19 -1
- package/dist/fork/codesandbox.d.ts.map +1 -1
- package/dist/fork/codesandbox.js +35 -22
- package/dist/fork/codesandbox.js.map +1 -1
- package/dist/fork/index.d.ts +30 -0
- package/dist/fork/index.d.ts.map +1 -1
- package/dist/fork/index.js +37 -0
- package/dist/fork/index.js.map +1 -1
- package/dist/fork/stackblitz.d.ts +18 -0
- package/dist/fork/stackblitz.d.ts.map +1 -0
- package/dist/fork/stackblitz.js +98 -0
- package/dist/fork/stackblitz.js.map +1 -0
- package/dist/frameworks/index.d.ts +4 -0
- package/dist/frameworks/index.d.ts.map +1 -0
- package/dist/frameworks/index.js +4 -0
- package/dist/frameworks/index.js.map +1 -0
- package/dist/frameworks/preference.d.ts +10 -0
- package/dist/frameworks/preference.d.ts.map +1 -0
- package/dist/frameworks/preference.js +34 -0
- package/dist/frameworks/preference.js.map +1 -0
- package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
- package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkBanner.js +50 -0
- package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
- package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
- package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkContent.js +25 -0
- package/dist/frameworks/react/FrameworkContent.js.map +1 -0
- package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
- package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkLinks.js +50 -0
- package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
- package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
- package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
- package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
- package/dist/frameworks/react/index.d.ts +6 -0
- package/dist/frameworks/react/index.d.ts.map +1 -0
- package/dist/frameworks/react/index.js +6 -0
- package/dist/frameworks/react/index.js.map +1 -0
- package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
- package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
- package/dist/frameworks/react/useFrameworkPreference.js +45 -0
- package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
- package/dist/frameworks/routeTree.d.ts +24 -0
- package/dist/frameworks/routeTree.d.ts.map +1 -0
- package/dist/frameworks/routeTree.js +31 -0
- package/dist/frameworks/routeTree.js.map +1 -0
- package/dist/frameworks/routing.d.ts +105 -0
- package/dist/frameworks/routing.d.ts.map +1 -0
- package/dist/frameworks/routing.js +142 -0
- package/dist/frameworks/routing.js.map +1 -0
- package/dist/frameworks/styles.css +104 -0
- package/dist/react/Demo.d.ts +12 -0
- package/dist/react/Demo.d.ts.map +1 -1
- package/dist/react/Demo.js +10 -4
- package/dist/react/Demo.js.map +1 -1
- package/dist/react/DemoShell.d.ts +5 -1
- package/dist/react/DemoShell.d.ts.map +1 -1
- package/dist/react/DemoShell.js +9 -6
- package/dist/react/DemoShell.js.map +1 -1
- package/dist/react/editor.d.ts.map +1 -1
- package/dist/react/editor.js +3 -0
- package/dist/react/editor.js.map +1 -1
- package/dist/react/fork.d.ts +4 -3
- package/dist/react/fork.d.ts.map +1 -1
- package/dist/react/fork.js +8 -6
- package/dist/react/fork.js.map +1 -1
- package/dist/react/styles.css +10 -0
- package/dist/remark/index.d.ts +2 -0
- package/dist/remark/index.d.ts.map +1 -1
- package/dist/remark/index.js +2 -0
- package/dist/remark/index.js.map +1 -1
- package/dist/remark/remarkDemoFences.d.ts +13 -0
- package/dist/remark/remarkDemoFences.d.ts.map +1 -1
- package/dist/remark/remarkDemoFences.js +48 -4
- package/dist/remark/remarkDemoFences.js.map +1 -1
- package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
- package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
- package/dist/remark/remarkFrameworkLinks.js +77 -0
- package/dist/remark/remarkFrameworkLinks.js.map +1 -0
- package/dist/remark/remarkFrameworkText.d.ts +16 -0
- package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
- package/dist/remark/remarkFrameworkText.js +39 -0
- package/dist/remark/remarkFrameworkText.js.map +1 -0
- package/package.json +29 -4
- package/src/code/demoFiles.ts +2 -2
- package/src/code/index.ts +1 -0
- package/src/code/regions.ts +14 -8
- package/src/code/vueBlocks.ts +25 -0
- package/src/demos/build.ts +293 -99
- package/src/demos/compile/core.ts +27 -7
- package/src/demos/compile/vue.ts +259 -0
- package/src/demos/config.ts +59 -7
- package/src/demos/index.ts +13 -0
- package/src/demos/pages.ts +4 -2
- package/src/demos/runtime/vue.ts +17 -0
- package/src/demos/vendor.ts +6 -2
- package/src/demos/worker/compile.worker.ts +3 -30
- package/src/demos/worker/compileVue.worker.ts +13 -0
- package/src/demos/worker/start.ts +35 -0
- package/src/fork/codesandbox.ts +51 -24
- package/src/fork/index.ts +56 -0
- package/src/fork/stackblitz.ts +108 -0
- package/src/frameworks/index.ts +21 -0
- package/src/frameworks/preference.ts +35 -0
- package/src/frameworks/react/FrameworkBanner.tsx +112 -0
- package/src/frameworks/react/FrameworkContent.tsx +33 -0
- package/src/frameworks/react/FrameworkLinks.tsx +52 -0
- package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
- package/src/frameworks/react/index.ts +10 -0
- package/src/frameworks/react/useFrameworkPreference.ts +91 -0
- package/src/frameworks/routeTree.ts +54 -0
- package/src/frameworks/routing.ts +194 -0
- package/src/frameworks/styles.css +104 -0
- package/src/react/Demo.tsx +21 -2
- package/src/react/DemoShell.tsx +15 -7
- package/src/react/editor.ts +2 -0
- package/src/react/fork.ts +14 -6
- package/src/react/styles.css +10 -0
- package/src/remark/index.ts +6 -0
- package/src/remark/remarkDemoFences.ts +58 -3
- package/src/remark/remarkFrameworkLinks.ts +96 -0
- 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
|
-
|
|
159
|
-
|
|
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: [
|
|
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
|
+
}
|
package/src/demos/config.ts
CHANGED
|
@@ -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
|
-
/**
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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:
|
|
148
|
+
framework: DemoFramework;
|
|
97
149
|
urlRoot: string;
|
|
98
150
|
demoSuffix: string;
|
|
99
151
|
importMap: { imports: Record<string, string> };
|
package/src/demos/index.ts
CHANGED
|
@@ -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';
|
package/src/demos/pages.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
+
};
|
package/src/demos/vendor.ts
CHANGED
|
@@ -20,9 +20,13 @@ const RESERVED = new Set(
|
|
|
20
20
|
),
|
|
21
21
|
);
|
|
22
22
|
|
|
23
|
-
/**
|
|
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
|
|
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
|
|
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
|
|
6
|
+
import { startCompileWorker } from './start.ts';
|
|
9
7
|
|
|
10
|
-
|
|
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
|
+
}
|