@thedatagrid/docs-kit 0.2.2 → 0.4.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 (204) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +206 -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 +27 -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/worker/compile.worker.js +3 -22
  46. package/dist/demos/worker/compile.worker.js.map +1 -1
  47. package/dist/demos/worker/compileVue.worker.d.ts +2 -0
  48. package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
  49. package/dist/demos/worker/compileVue.worker.js +11 -0
  50. package/dist/demos/worker/compileVue.worker.js.map +1 -0
  51. package/dist/demos/worker/start.d.ts +7 -0
  52. package/dist/demos/worker/start.d.ts.map +1 -0
  53. package/dist/demos/worker/start.js +27 -0
  54. package/dist/demos/worker/start.js.map +1 -0
  55. package/dist/fork/codesandbox.d.ts +15 -1
  56. package/dist/fork/codesandbox.d.ts.map +1 -1
  57. package/dist/fork/codesandbox.js +30 -19
  58. package/dist/fork/codesandbox.js.map +1 -1
  59. package/dist/fork/index.d.ts +18 -0
  60. package/dist/fork/index.d.ts.map +1 -1
  61. package/dist/fork/index.js +18 -0
  62. package/dist/fork/index.js.map +1 -1
  63. package/dist/fork/stackblitz.d.ts +18 -0
  64. package/dist/fork/stackblitz.d.ts.map +1 -0
  65. package/dist/fork/stackblitz.js +98 -0
  66. package/dist/fork/stackblitz.js.map +1 -0
  67. package/dist/frameworks/index.d.ts +4 -0
  68. package/dist/frameworks/index.d.ts.map +1 -0
  69. package/dist/frameworks/index.js +4 -0
  70. package/dist/frameworks/index.js.map +1 -0
  71. package/dist/frameworks/preference.d.ts +10 -0
  72. package/dist/frameworks/preference.d.ts.map +1 -0
  73. package/dist/frameworks/preference.js +34 -0
  74. package/dist/frameworks/preference.js.map +1 -0
  75. package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
  76. package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
  77. package/dist/frameworks/react/FrameworkBanner.js +50 -0
  78. package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
  79. package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
  80. package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
  81. package/dist/frameworks/react/FrameworkContent.js +25 -0
  82. package/dist/frameworks/react/FrameworkContent.js.map +1 -0
  83. package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
  84. package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
  85. package/dist/frameworks/react/FrameworkLinks.js +50 -0
  86. package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
  87. package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
  88. package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
  89. package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
  90. package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
  91. package/dist/frameworks/react/index.d.ts +6 -0
  92. package/dist/frameworks/react/index.d.ts.map +1 -0
  93. package/dist/frameworks/react/index.js +6 -0
  94. package/dist/frameworks/react/index.js.map +1 -0
  95. package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
  96. package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
  97. package/dist/frameworks/react/useFrameworkPreference.js +45 -0
  98. package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
  99. package/dist/frameworks/routeTree.d.ts +24 -0
  100. package/dist/frameworks/routeTree.d.ts.map +1 -0
  101. package/dist/frameworks/routeTree.js +31 -0
  102. package/dist/frameworks/routeTree.js.map +1 -0
  103. package/dist/frameworks/routing.d.ts +105 -0
  104. package/dist/frameworks/routing.d.ts.map +1 -0
  105. package/dist/frameworks/routing.js +142 -0
  106. package/dist/frameworks/routing.js.map +1 -0
  107. package/dist/frameworks/styles.css +104 -0
  108. package/dist/react/Demo.d.ts +12 -0
  109. package/dist/react/Demo.d.ts.map +1 -1
  110. package/dist/react/Demo.js +10 -4
  111. package/dist/react/Demo.js.map +1 -1
  112. package/dist/react/DemoShell.d.ts +5 -1
  113. package/dist/react/DemoShell.d.ts.map +1 -1
  114. package/dist/react/DemoShell.js +9 -6
  115. package/dist/react/DemoShell.js.map +1 -1
  116. package/dist/react/editor.d.ts.map +1 -1
  117. package/dist/react/editor.js +3 -0
  118. package/dist/react/editor.js.map +1 -1
  119. package/dist/react/fork.d.ts +4 -3
  120. package/dist/react/fork.d.ts.map +1 -1
  121. package/dist/react/fork.js +6 -5
  122. package/dist/react/fork.js.map +1 -1
  123. package/dist/react/styles.css +10 -0
  124. package/dist/remark/index.d.ts +2 -0
  125. package/dist/remark/index.d.ts.map +1 -1
  126. package/dist/remark/index.js +2 -0
  127. package/dist/remark/index.js.map +1 -1
  128. package/dist/remark/remarkDemoFences.d.ts +13 -0
  129. package/dist/remark/remarkDemoFences.d.ts.map +1 -1
  130. package/dist/remark/remarkDemoFences.js +48 -4
  131. package/dist/remark/remarkDemoFences.js.map +1 -1
  132. package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
  133. package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
  134. package/dist/remark/remarkFrameworkLinks.js +77 -0
  135. package/dist/remark/remarkFrameworkLinks.js.map +1 -0
  136. package/dist/remark/remarkFrameworkText.d.ts +16 -0
  137. package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
  138. package/dist/remark/remarkFrameworkText.js +39 -0
  139. package/dist/remark/remarkFrameworkText.js.map +1 -0
  140. package/dist/showcase/AutomatedDemo.d.ts +46 -0
  141. package/dist/showcase/AutomatedDemo.d.ts.map +1 -0
  142. package/dist/showcase/AutomatedDemo.js +169 -0
  143. package/dist/showcase/AutomatedDemo.js.map +1 -0
  144. package/dist/showcase/LazyShowcase.d.ts +31 -0
  145. package/dist/showcase/LazyShowcase.d.ts.map +1 -0
  146. package/dist/showcase/LazyShowcase.js +51 -0
  147. package/dist/showcase/LazyShowcase.js.map +1 -0
  148. package/dist/showcase/hooks.d.ts +19 -0
  149. package/dist/showcase/hooks.d.ts.map +1 -0
  150. package/dist/showcase/hooks.js +63 -0
  151. package/dist/showcase/hooks.js.map +1 -0
  152. package/dist/showcase/index.d.ts +17 -0
  153. package/dist/showcase/index.d.ts.map +1 -0
  154. package/dist/showcase/index.js +15 -0
  155. package/dist/showcase/index.js.map +1 -0
  156. package/dist/showcase/scripted.d.ts +100 -0
  157. package/dist/showcase/scripted.d.ts.map +1 -0
  158. package/dist/showcase/scripted.js +381 -0
  159. package/dist/showcase/scripted.js.map +1 -0
  160. package/dist/showcase/styles.css +174 -0
  161. package/package.json +34 -4
  162. package/src/code/demoFiles.ts +2 -2
  163. package/src/code/index.ts +1 -0
  164. package/src/code/regions.ts +14 -8
  165. package/src/code/vueBlocks.ts +25 -0
  166. package/src/demos/build.ts +293 -99
  167. package/src/demos/compile/core.ts +27 -7
  168. package/src/demos/compile/vue.ts +259 -0
  169. package/src/demos/config.ts +44 -7
  170. package/src/demos/index.ts +13 -0
  171. package/src/demos/pages.ts +4 -2
  172. package/src/demos/runtime/vue.ts +17 -0
  173. package/src/demos/worker/compile.worker.ts +3 -30
  174. package/src/demos/worker/compileVue.worker.ts +13 -0
  175. package/src/demos/worker/start.ts +35 -0
  176. package/src/fork/codesandbox.ts +43 -21
  177. package/src/fork/index.ts +25 -0
  178. package/src/fork/stackblitz.ts +107 -0
  179. package/src/frameworks/index.ts +21 -0
  180. package/src/frameworks/preference.ts +35 -0
  181. package/src/frameworks/react/FrameworkBanner.tsx +112 -0
  182. package/src/frameworks/react/FrameworkContent.tsx +33 -0
  183. package/src/frameworks/react/FrameworkLinks.tsx +52 -0
  184. package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
  185. package/src/frameworks/react/index.ts +10 -0
  186. package/src/frameworks/react/useFrameworkPreference.ts +91 -0
  187. package/src/frameworks/routeTree.ts +54 -0
  188. package/src/frameworks/routing.ts +194 -0
  189. package/src/frameworks/styles.css +104 -0
  190. package/src/react/Demo.tsx +21 -2
  191. package/src/react/DemoShell.tsx +15 -7
  192. package/src/react/editor.ts +2 -0
  193. package/src/react/fork.ts +12 -5
  194. package/src/react/styles.css +10 -0
  195. package/src/remark/index.ts +6 -0
  196. package/src/remark/remarkDemoFences.ts +58 -3
  197. package/src/remark/remarkFrameworkLinks.ts +96 -0
  198. package/src/remark/remarkFrameworkText.ts +44 -0
  199. package/src/showcase/AutomatedDemo.tsx +266 -0
  200. package/src/showcase/LazyShowcase.tsx +111 -0
  201. package/src/showcase/hooks.ts +84 -0
  202. package/src/showcase/index.ts +23 -0
  203. package/src/showcase/scripted.ts +533 -0
  204. package/src/showcase/styles.css +174 -0
@@ -4,8 +4,11 @@
4
4
  *
5
5
  * The demo's files keep their folder structure: they are placed under `src/`
6
6
  * relative to their common ancestor folder, so imports that leave the demo's
7
- * folder (`../shared/data`) still resolve. The entry (`src/index.tsx`) imports
8
- * the demo by its relative path.
7
+ * folder (`../shared/data`) still resolve. The sandbox entry (`src/index.tsx`)
8
+ * imports the demo by its relative path.
9
+ *
10
+ * React demos fork to CodeSandbox (create-react-app + TypeScript, in its
11
+ * browser bundler). Vue demos fork to StackBlitz: see `stackblitz.ts`.
9
12
  */
10
13
  import LZString from 'lz-string';
11
14
 
@@ -29,7 +32,7 @@ export type ForkTemplateOptions = {
29
32
  */
30
33
  dependencies?: Record<string, string>;
31
34
  devDependencies?: Record<string, string>;
32
- /** Top of `src/index.tsx`, e.g. `import '@pkg/index.css';`. */
35
+ /** Top of the entry (`src/index.tsx` / `src/main.ts`), e.g. `import '@pkg/index.css';`. */
33
36
  entryPrelude?: string;
34
37
  /** Appended to `src/styles.css`. */
35
38
  styles?: string;
@@ -58,14 +61,14 @@ export function commonDir(paths: string[]): string {
58
61
  return common.join('/');
59
62
  }
60
63
 
61
- function replaceAll(source: string, replacements: Record<string, string> | undefined): string {
64
+ export function replaceAll(source: string, replacements: Record<string, string> | undefined): string {
62
65
  if (!replacements) return source;
63
66
  let result = source;
64
67
  for (const [search, replacement] of Object.entries(replacements)) result = result.split(search).join(replacement);
65
68
  return result;
66
69
  }
67
70
 
68
- const BASE_STYLES = `html,
71
+ export const BASE_STYLES = `html,
69
72
  body,
70
73
  #root {
71
74
  height: 100%;
@@ -100,16 +103,21 @@ const INDEX_HTML = (title: string) => `<!DOCTYPE html>
100
103
  </html>
101
104
  `;
102
105
 
103
- /** The sandbox file tree for a React demo (create-react-app + TypeScript). */
104
- export function reactSandboxFiles(files: ForkFile[], options: ForkTemplateOptions): SandboxFiles {
106
+ export type PlacedFiles = {
107
+ /** Path of a demo file inside the sandbox. */
108
+ inSrc(filePath: string): string;
109
+ /** The entry, as imported from a module in `src/` (extension included). */
110
+ entryImport: string;
111
+ /** Every package the files import, at its pinned version or `latest`. */
112
+ imported: Record<string, string>;
113
+ };
114
+
115
+ export function placeFiles(files: ForkFile[], options: ForkTemplateOptions): PlacedFiles {
105
116
  if (!files.some((file) => file.path === options.entry)) {
106
117
  throw new Error(`fork: the entry "${options.entry}" is not one of the files`);
107
118
  }
108
119
  const root = commonDir(files.map((file) => file.path));
109
120
  const inSrc = (filePath: string) => `src/${root ? filePath.slice(root.length + 1) : filePath}`;
110
- const entryInSrc = inSrc(options.entry);
111
- const entryImport = `./${entryInSrc.slice('src/'.length).replace(/\.[cm]?[jt]sx?$/, '')}`;
112
-
113
121
  const imported: Record<string, string> = {};
114
122
  for (const file of files) {
115
123
  for (const specifier of bareImports(file.content)) {
@@ -117,7 +125,27 @@ export function reactSandboxFiles(files: ForkFile[], options: ForkTemplateOption
117
125
  imported[name] = options.dependencies?.[name] ?? 'latest';
118
126
  }
119
127
  }
128
+ return { inSrc, entryImport: `./${inSrc(options.entry).slice('src/'.length)}`, imported };
129
+ }
130
+
131
+ function addDemoFiles(sandbox: SandboxFiles, files: ForkFile[], placed: PlacedFiles, options: ForkTemplateOptions) {
132
+ for (const file of files) {
133
+ const target = placed.inSrc(file.path);
134
+ if (sandbox[target]) throw new Error(`fork: "${target}" clashes with a template file`);
135
+ sandbox[target] = { content: replaceAll(file.content, options.sourceReplacements) };
136
+ }
137
+ return sandbox;
138
+ }
139
+
140
+ /** `src/styles.css`: the page layout, then the site's own rules. */
141
+ export const forkStyles = (options: ForkTemplateOptions) =>
142
+ `${BASE_STYLES}${options.styles ? `\n${options.styles}\n` : ''}`;
120
143
 
144
+ export const forkPrelude = (options: ForkTemplateOptions) => (options.entryPrelude ? `${options.entryPrelude.trim()}\n` : '');
145
+
146
+ /** The sandbox file tree for a React demo (create-react-app + TypeScript). */
147
+ export function reactSandboxFiles(files: ForkFile[], options: ForkTemplateOptions): SandboxFiles {
148
+ const placed = placeFiles(files, options);
121
149
  const sandbox: SandboxFiles = {
122
150
  'package.json': {
123
151
  content: {
@@ -125,7 +153,7 @@ export function reactSandboxFiles(files: ForkFile[], options: ForkTemplateOption
125
153
  description: options.title,
126
154
  main: 'src/index.tsx',
127
155
  dependencies: {
128
- ...imported,
156
+ ...placed.imported,
129
157
  react: '^19.0.0',
130
158
  'react-dom': '^19.0.0',
131
159
  'react-scripts': '^5.0.1',
@@ -143,13 +171,13 @@ export function reactSandboxFiles(files: ForkFile[], options: ForkTemplateOption
143
171
  },
144
172
  'public/index.html': { content: INDEX_HTML(options.title) },
145
173
  'sandbox.config.json': { content: { infiniteLoopProtection: true } },
146
- 'src/styles.css': { content: `${BASE_STYLES}${options.styles ? `\n${options.styles}\n` : ''}` },
174
+ 'src/styles.css': { content: forkStyles(options) },
147
175
  'src/index.tsx': {
148
176
  content: `import { StrictMode } from 'react';
149
177
  import { createRoot } from 'react-dom/client';
150
- ${options.entryPrelude ? `${options.entryPrelude.trim()}\n` : ''}
178
+ ${forkPrelude(options)}
151
179
  import './styles.css';
152
- import App from ${JSON.stringify(entryImport)};
180
+ import App from ${JSON.stringify(placed.entryImport.replace(/\.[cm]?[jt]sx?$/, ''))};
153
181
 
154
182
  createRoot(document.getElementById('root')!).render(
155
183
  <StrictMode>
@@ -159,13 +187,7 @@ createRoot(document.getElementById('root')!).render(
159
187
  `,
160
188
  },
161
189
  };
162
-
163
- for (const file of files) {
164
- const target = inSrc(file.path);
165
- if (sandbox[target]) throw new Error(`fork: "${target}" clashes with a template file`);
166
- sandbox[target] = { content: replaceAll(file.content, options.sourceReplacements) };
167
- }
168
- return sandbox;
190
+ return addDemoFiles(sandbox, files, placed, options);
169
191
  }
170
192
 
171
193
  /** lz-string base64, URL-safe — the encoding the define API expects. */
package/src/fork/index.ts CHANGED
@@ -1,3 +1,6 @@
1
+ import { codeSandboxForm, type ForkFile, type ForkTemplateOptions } from './codesandbox.ts';
2
+ import { stackBlitzForm } from './stackblitz.ts';
3
+
1
4
  export {
2
5
  CODESANDBOX_DEFINE_URL,
3
6
  codeSandboxForm,
@@ -8,3 +11,25 @@ export {
8
11
  type ForkTemplateOptions,
9
12
  type SandboxFiles,
10
13
  } from './codesandbox.ts';
14
+ export { STACKBLITZ_RUN_URL, stackBlitzForm, vueProjectFiles } from './stackblitz.ts';
15
+
16
+ export type ForkFramework = 'react' | 'vue';
17
+
18
+ /** Where a framework's demos fork to. */
19
+ export const FORK_TARGETS: Record<ForkFramework, { id: 'codesandbox' | 'stackblitz'; name: string }> = {
20
+ react: { id: 'codesandbox', name: 'CodeSandbox' },
21
+ vue: { id: 'stackblitz', name: 'StackBlitz' },
22
+ };
23
+
24
+ /**
25
+ * The form that forks a demo: `action` and hidden `fields` for a POST in a
26
+ * new tab. React demos go to CodeSandbox, Vue demos to StackBlitz.
27
+ */
28
+ export function forkForm(
29
+ files: ForkFile[],
30
+ options: ForkTemplateOptions & { framework?: ForkFramework },
31
+ ): { action: string; fields: Record<string, string> } {
32
+ if (options.framework === 'vue') return stackBlitzForm(files, options);
33
+ const form = codeSandboxForm(files, options);
34
+ return { action: form.action, fields: { parameters: form.parameters, query: form.query } };
35
+ }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * StackBlitz fork payloads, for Vue demos: a Vite + Vue + TypeScript project,
3
+ * posted to StackBlitz's `run` endpoint and started in the browser
4
+ * (WebContainers), with no sign-in.
5
+ *
6
+ * Like the CodeSandbox payload, the demo's files keep their folder structure
7
+ * under `src/`, and `src/main.ts` imports the entry by its relative path.
8
+ */
9
+ import {
10
+ forkPrelude,
11
+ forkStyles,
12
+ placeFiles,
13
+ replaceAll,
14
+ type ForkFile,
15
+ type ForkTemplateOptions,
16
+ } from './codesandbox.ts';
17
+
18
+ export const STACKBLITZ_RUN_URL = 'https://stackblitz.com/run';
19
+
20
+ const INDEX_HTML = (title: string) => `<!DOCTYPE html>
21
+ <html lang="en">
22
+ <head>
23
+ <meta charset="UTF-8" />
24
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
25
+ <title>${title.replace(/</g, '&lt;')}</title>
26
+ </head>
27
+ <body>
28
+ <div id="root"></div>
29
+ <script type="module" src="/src/main.ts"></script>
30
+ </body>
31
+ </html>
32
+ `;
33
+
34
+ const json = (value: unknown) => `${JSON.stringify(value, null, 2)}\n`;
35
+
36
+ /** The project's files (path → contents) for a Vue demo: Vite, `@vitejs/plugin-vue`, TypeScript. */
37
+ export function vueProjectFiles(files: ForkFile[], options: ForkTemplateOptions): Record<string, string> {
38
+ const placed = placeFiles(files, options);
39
+ const project: Record<string, string> = {
40
+ 'package.json': json({
41
+ name: 'docs-demo',
42
+ description: options.title,
43
+ private: true,
44
+ type: 'module',
45
+ scripts: { dev: 'vite', build: 'vite build' },
46
+ dependencies: {
47
+ ...placed.imported,
48
+ vue: '^3.5.0',
49
+ ...options.dependencies,
50
+ },
51
+ devDependencies: {
52
+ '@vitejs/plugin-vue': '^6.0.0',
53
+ typescript: '^5.4.0',
54
+ vite: '^8.0.0',
55
+ ...options.devDependencies,
56
+ },
57
+ }),
58
+ 'index.html': INDEX_HTML(options.title),
59
+ 'vite.config.ts': `import { defineConfig } from 'vite';
60
+ import vue from '@vitejs/plugin-vue';
61
+
62
+ export default defineConfig({ plugins: [vue()] });
63
+ `,
64
+ 'tsconfig.json': json({
65
+ compilerOptions: {
66
+ target: 'ESNext',
67
+ module: 'ESNext',
68
+ moduleResolution: 'Bundler',
69
+ strict: true,
70
+ jsx: 'preserve',
71
+ jsxImportSource: 'vue',
72
+ skipLibCheck: true,
73
+ lib: ['ESNext', 'DOM', 'DOM.Iterable'],
74
+ },
75
+ include: ['src'],
76
+ }),
77
+ 'src/vite-env.d.ts': '/// <reference types="vite/client" />\n',
78
+ 'src/styles.css': forkStyles(options),
79
+ 'src/main.ts': `import { createApp } from 'vue';
80
+ ${forkPrelude(options)}
81
+ import './styles.css';
82
+ import App from ${JSON.stringify(placed.entryImport)};
83
+
84
+ createApp(App).mount('#root');
85
+ `,
86
+ };
87
+ for (const file of files) {
88
+ const target = placed.inSrc(file.path);
89
+ if (project[target] != null) throw new Error(`fork: "${target}" clashes with a template file`);
90
+ project[target] = replaceAll(file.content, options.sourceReplacements);
91
+ }
92
+ return project;
93
+ }
94
+
95
+ /** Form action and fields for a POST to StackBlitz; the entry file opens in the editor. */
96
+ export function stackBlitzForm(files: ForkFile[], options: ForkTemplateOptions) {
97
+ const project = vueProjectFiles(files, options);
98
+ const entry = placeFiles(files, options).inSrc(options.entry);
99
+ const fields: Record<string, string> = {
100
+ 'project[title]': options.title,
101
+ 'project[description]': options.title,
102
+ // WebContainers: `npm install`, then the `dev` script
103
+ 'project[template]': 'node',
104
+ };
105
+ for (const [filePath, content] of Object.entries(project)) fields[`project[files][${filePath}]`] = content;
106
+ return { action: `${STACKBLITZ_RUN_URL}?file=${encodeURIComponent(entry)}`, fields };
107
+ }
@@ -0,0 +1,21 @@
1
+ export {
2
+ createHasPage,
3
+ defineFrameworks,
4
+ resolveFrameworkLink,
5
+ resolveNavigation,
6
+ resolveSwitchTarget,
7
+ splitHref,
8
+ type FrameworkDefinition,
9
+ type Frameworks,
10
+ type FrameworksConfig,
11
+ type HasPage,
12
+ type ResolvedLink,
13
+ } from './routing.ts';
14
+ export { mapRouteTree, type MapRouteTreeOptions, type RouteNode } from './routeTree.ts';
15
+ export {
16
+ DEFAULT_FRAMEWORK_STORAGE_KEY,
17
+ FRAMEWORK_CHANGE_EVENT,
18
+ frameworkStorageKey,
19
+ readFrameworkPreference,
20
+ writeFrameworkPreference,
21
+ } from './preference.ts';
@@ -0,0 +1,35 @@
1
+ import type { Frameworks } from './routing.ts';
2
+
3
+ /** Fired on `window` when the stored framework changes in this tab. */
4
+ export const FRAMEWORK_CHANGE_EVENT = 'docs-kit:framework';
5
+
6
+ export const DEFAULT_FRAMEWORK_STORAGE_KEY = 'docs-framework';
7
+
8
+ export const frameworkStorageKey = (frameworks: Frameworks) =>
9
+ frameworks.config.storageKey ?? DEFAULT_FRAMEWORK_STORAGE_KEY;
10
+
11
+ /** The visitor's stored choice, or `null` (none, an unknown value, or storage is blocked). */
12
+ export function readFrameworkPreference<Id extends string>(frameworks: Frameworks<Id>): Id | null {
13
+ try {
14
+ const stored = localStorage.getItem(frameworkStorageKey(frameworks));
15
+ return stored != null && frameworks.ids.includes(stored as Id) ? (stored as Id) : null;
16
+ } catch {
17
+ return null;
18
+ }
19
+ }
20
+
21
+ /** Stores the visitor's choice (`null` clears it) and tells the components on the page. */
22
+ export function writeFrameworkPreference<Id extends string>(frameworks: Frameworks<Id>, framework: Id | null) {
23
+ try {
24
+ const key = frameworkStorageKey(frameworks);
25
+ if (framework == null) localStorage.removeItem(key);
26
+ else localStorage.setItem(key, framework);
27
+ } catch {
28
+ // storage blocked: the choice lasts for this page
29
+ }
30
+ try {
31
+ window.dispatchEvent(new CustomEvent(FRAMEWORK_CHANGE_EVENT, { detail: framework }));
32
+ } catch {
33
+ // not in a browser
34
+ }
35
+ }
@@ -0,0 +1,112 @@
1
+ 'use client';
2
+
3
+ import { useEffect, useState, type MouseEvent, type ReactNode } from 'react';
4
+
5
+ import { splitHref } from '../routing.ts';
6
+ import {
7
+ EXPLICIT_LINK_ATTRIBUTE,
8
+ isPlainClick,
9
+ useFrameworkPreference,
10
+ useFrameworks,
11
+ usePagePath,
12
+ type FrameworkProps,
13
+ } from './useFrameworkPreference.ts';
14
+
15
+ export type FrameworkBannerLabels = {
16
+ /** The page exists in the preferred framework. `{preferred}` and `{page}` are framework labels. */
17
+ available?: string;
18
+ /** The link to it. */
19
+ view?: string;
20
+ /** Keeps the page's framework from now on. */
21
+ keep?: string;
22
+ /** The page doesn't exist in the preferred framework. */
23
+ missing?: string;
24
+ dismiss?: string;
25
+ };
26
+
27
+ const DEFAULT_LABELS: Required<FrameworkBannerLabels> = {
28
+ available: 'You are reading the {page} docs.',
29
+ view: 'View this page for {preferred}',
30
+ keep: 'Stay with {page}',
31
+ missing: '{page} only for now: this page is not available for {preferred} yet.',
32
+ dismiss: 'Dismiss',
33
+ };
34
+
35
+ export type FrameworkBannerProps<Id extends string = string> = FrameworkProps<Id> & {
36
+ /** The page's path, from the site's router. Default: `location.pathname`. */
37
+ pathname?: string | null;
38
+ /** Client-side navigation (`router.push`). Default: a normal link. */
39
+ navigate?: (href: string) => void;
40
+ labels?: FrameworkBannerLabels;
41
+ className?: string;
42
+ };
43
+
44
+ const fill = (text: string, values: Record<string, string>) =>
45
+ text.replace(/\{(\w+)\}/g, (match, name: string) => values[name] ?? match);
46
+
47
+ /**
48
+ * Shown on a docs page whose framework is not the one the visitor chose:
49
+ * a shared link, a search result, or a page their framework doesn't have yet.
50
+ * It never redirects, so links stay stable and crawlers see one page per URL.
51
+ *
52
+ * - The page exists in the preferred framework: a link to it, and a way to
53
+ * keep the page's framework from now on.
54
+ * - It doesn't: a notice ("React only for now").
55
+ *
56
+ * Renders nothing without a stored preference, and until hydration.
57
+ */
58
+ export function FrameworkBanner<Id extends string>(props: FrameworkBannerProps<Id>): ReactNode {
59
+ const { navigate, className } = props;
60
+ const labels = { ...DEFAULT_LABELS, ...props.labels };
61
+ const { frameworks, hasPage } = useFrameworks(props);
62
+ const [preference, setPreference] = useFrameworkPreference(frameworks);
63
+ const pathname = usePagePath(props.pathname);
64
+ const [dismissedFor, setDismissedFor] = useState<string | null>(null);
65
+ // a dismissal lasts until the next page
66
+ useEffect(() => setDismissedFor(null), [pathname]);
67
+
68
+ const pageFramework = pathname ? frameworks.frameworkOf(pathname) : null;
69
+ if (!pathname || !preference || !pageFramework || pageFramework === preference || dismissedFor === pathname) {
70
+ return null;
71
+ }
72
+
73
+ const neutral = frameworks.neutralPath(pathname);
74
+ const available = hasPage(splitHref(neutral)[0], preference);
75
+ const href = frameworks.pathFor(neutral, preference);
76
+ const names = { preferred: frameworks.label(preference), page: frameworks.label(pageFramework) };
77
+ const onView = (event: MouseEvent<HTMLAnchorElement>) => {
78
+ if (!navigate || !isPlainClick(event)) return;
79
+ event.preventDefault();
80
+ navigate(href);
81
+ };
82
+
83
+ return (
84
+ <div
85
+ className={`dk-framework-banner${className ? ` ${className}` : ''}`}
86
+ role="status"
87
+ data-framework={preference}
88
+ data-available={available ? 'true' : 'false'}
89
+ >
90
+ <span className="dk-framework-banner-text">{fill(available ? labels.available : labels.missing, names)}</span>
91
+ {available ? (
92
+ <>
93
+ <a className="dk-framework-banner-link" href={href} onClick={onView} {...{ [EXPLICIT_LINK_ATTRIBUTE]: '' }}>
94
+ {fill(labels.view, names)}
95
+ </a>
96
+ <button type="button" className="dk-framework-banner-action" onClick={() => setPreference(pageFramework)}>
97
+ {fill(labels.keep, names)}
98
+ </button>
99
+ </>
100
+ ) : null}
101
+ <button
102
+ type="button"
103
+ className="dk-framework-banner-dismiss"
104
+ aria-label={labels.dismiss}
105
+ title={labels.dismiss}
106
+ onClick={() => setDismissedFor(pathname)}
107
+ >
108
+ ×
109
+ </button>
110
+ </div>
111
+ );
112
+ }
@@ -0,0 +1,33 @@
1
+ import type { ReactNode } from 'react';
2
+
3
+ export type FrameworkContentProps = {
4
+ /** Shown for this framework, or one of a comma-separated list: `framework="vue"`, `framework="react,vue"`. */
5
+ framework?: string | string[];
6
+ /** Shown for every framework but this one (or these). */
7
+ not?: string | string[];
8
+ children?: ReactNode;
9
+ };
10
+
11
+ const asList = (value: string | string[] | undefined) =>
12
+ (Array.isArray(value) ? value : (value ?? '').split(',')).map((item) => item.trim()).filter(Boolean);
13
+
14
+ /**
15
+ * The MDX component for the parts of a page that differ per framework:
16
+ *
17
+ * <FrameworkContent framework="vue">
18
+ * Bind it with `v-model`.
19
+ * </FrameworkContent>
20
+ *
21
+ * Each framework has its own page, so this is decided when the page is
22
+ * built: the other frameworks' blocks aren't in the HTML at all. Create one
23
+ * per page with the framework it is rendered for.
24
+ */
25
+ export function createFrameworkContent(pageFramework: string) {
26
+ return function FrameworkContent(props: FrameworkContentProps): ReactNode {
27
+ const only = asList(props.framework);
28
+ const except = asList(props.not);
29
+ if (only.length && !only.includes(pageFramework)) return null;
30
+ if (except.includes(pageFramework)) return null;
31
+ return <>{props.children}</>;
32
+ };
33
+ }
@@ -0,0 +1,52 @@
1
+ 'use client';
2
+
3
+ import { useEffect } from 'react';
4
+
5
+ import { readFrameworkPreference } from '../preference.ts';
6
+ import { resolveNavigation } from '../routing.ts';
7
+ import { EXPLICIT_LINK_ATTRIBUTE, isPlainClick, useFrameworks, type FrameworkProps } from './useFrameworkPreference.ts';
8
+
9
+ export type FrameworkLinksProps<Id extends string = string> = FrameworkProps<Id> & {
10
+ /** Client-side navigation (`router.push`). Default: `location.assign`. */
11
+ navigate?: (href: string) => void;
12
+ };
13
+
14
+ /**
15
+ * Makes in-site navigation follow the visitor's framework: a click on a docs
16
+ * link of another framework goes to the same page in theirs, when it exists
17
+ * (see `resolveNavigation`). Mount it once, anywhere in the layout; it
18
+ * renders nothing.
19
+ *
20
+ * Only plain left clicks on same-origin links are taken over. Links marked
21
+ * with `data-framework-explicit` (the switcher, the banner) are left alone.
22
+ */
23
+ export function FrameworkLinks<Id extends string>(props: FrameworkLinksProps<Id>) {
24
+ const { navigate } = props;
25
+ const { frameworks, hasPage } = useFrameworks(props);
26
+
27
+ useEffect(() => {
28
+ const onClick = (event: MouseEvent) => {
29
+ if (event.defaultPrevented || !isPlainClick(event)) return;
30
+ const anchor = (event.target as Element | null)?.closest?.('a[href]') as HTMLAnchorElement | null;
31
+ if (!anchor || anchor.hasAttribute(EXPLICIT_LINK_ATTRIBUTE) || anchor.hasAttribute('download')) return;
32
+ if (anchor.target && anchor.target !== '_self') return;
33
+ if (anchor.origin !== window.location.origin) return;
34
+ const href = resolveNavigation(frameworks, {
35
+ href: `${anchor.pathname}${anchor.search}${anchor.hash}`,
36
+ pagePath: window.location.pathname,
37
+ preference: readFrameworkPreference(frameworks),
38
+ hasPage,
39
+ });
40
+ if (!href) return;
41
+ // before the site's own link handling (a router's click handler on the same element)
42
+ event.preventDefault();
43
+ event.stopPropagation();
44
+ if (navigate) navigate(href);
45
+ else window.location.assign(href);
46
+ };
47
+ document.addEventListener('click', onClick, true);
48
+ return () => document.removeEventListener('click', onClick, true);
49
+ }, [frameworks, hasPage, navigate]);
50
+
51
+ return null;
52
+ }
@@ -0,0 +1,78 @@
1
+ 'use client';
2
+
3
+ import type { MouseEvent } from 'react';
4
+
5
+ import { resolveSwitchTarget } from '../routing.ts';
6
+ import {
7
+ EXPLICIT_LINK_ATTRIBUTE,
8
+ isPlainClick,
9
+ useFrameworkPreference,
10
+ useFrameworks,
11
+ usePagePath,
12
+ type FrameworkProps,
13
+ } from './useFrameworkPreference.ts';
14
+
15
+ export type FrameworkSwitcherProps<Id extends string = string> = FrameworkProps<Id> & {
16
+ /** The page's path, from the site's router. Default: `location.pathname`, after hydration. */
17
+ pathname?: string | null;
18
+ /** Client-side navigation (`router.push`). Default: a normal link. */
19
+ navigate?: (href: string) => void;
20
+ /**
21
+ * Where a framework's option goes from a page outside the framework roots
22
+ * (blog, pricing), e.g. `{ react: '/docs', vue: '/vue' }`. Without it the
23
+ * option only stores the choice there.
24
+ */
25
+ home?: Partial<Record<Id, string>>;
26
+ /** Accessible name of the group. Default `Framework`. */
27
+ label?: string;
28
+ className?: string;
29
+ };
30
+
31
+ /**
32
+ * Picks the docs framework. Each option is a link to the same page in that
33
+ * framework (or the nearest parent that exists there), so it works without
34
+ * JavaScript and for crawlers; clicking it also stores the choice, which the
35
+ * rest of the site follows (`FrameworkLinks`, `FrameworkBanner`).
36
+ *
37
+ * Self-contained, with a minimal look (`frameworks/styles.css`): restyle
38
+ * `.dk-framework-switcher` / `.dk-framework-option`, or the `--dk-*` variables.
39
+ */
40
+ export function FrameworkSwitcher<Id extends string>(props: FrameworkSwitcherProps<Id>) {
41
+ const { navigate, home, label = 'Framework', className } = props;
42
+ const { frameworks, hasPage } = useFrameworks(props);
43
+ const [preference, setPreference] = useFrameworkPreference(frameworks);
44
+ const pathname = usePagePath(props.pathname);
45
+ // on a docs page the URL says which framework is shown; elsewhere the stored choice does
46
+ const current = (pathname ? frameworks.frameworkOf(pathname) : null) ?? preference ?? frameworks.default;
47
+
48
+ return (
49
+ <div className={`dk-framework-switcher${className ? ` ${className}` : ''}`} role="group" aria-label={label}>
50
+ {frameworks.ids.map((id) => {
51
+ const target = pathname ? resolveSwitchTarget(frameworks, pathname, id, hasPage) : null;
52
+ const href = target?.href ?? (pathname && frameworks.frameworkOf(pathname) == null ? home?.[id] : undefined);
53
+ const active = id === current;
54
+ const onClick = (event: MouseEvent<HTMLElement>) => {
55
+ setPreference(id);
56
+ if (!href || !navigate || !isPlainClick(event)) return;
57
+ event.preventDefault();
58
+ if (!active || pathname !== href) navigate(href);
59
+ };
60
+ const shared = {
61
+ className: `dk-framework-option${active ? ' dk-framework-option--active' : ''}`,
62
+ 'data-framework': id,
63
+ 'aria-current': active ? ('true' as const) : undefined,
64
+ onClick,
65
+ };
66
+ return href ? (
67
+ <a key={id} href={href} {...{ [EXPLICIT_LINK_ATTRIBUTE]: '' }} {...shared}>
68
+ {frameworks.label(id)}
69
+ </a>
70
+ ) : (
71
+ <button key={id} type="button" {...shared}>
72
+ {frameworks.label(id)}
73
+ </button>
74
+ );
75
+ })}
76
+ </div>
77
+ );
78
+ }
@@ -0,0 +1,10 @@
1
+ export { createFrameworkContent, type FrameworkContentProps } from './FrameworkContent.tsx';
2
+ export { FrameworkBanner, type FrameworkBannerLabels, type FrameworkBannerProps } from './FrameworkBanner.tsx';
3
+ export { FrameworkLinks, type FrameworkLinksProps } from './FrameworkLinks.tsx';
4
+ export { FrameworkSwitcher, type FrameworkSwitcherProps } from './FrameworkSwitcher.tsx';
5
+ export {
6
+ EXPLICIT_LINK_ATTRIBUTE,
7
+ useFrameworkPreference,
8
+ useFrameworks,
9
+ type FrameworkProps,
10
+ } from './useFrameworkPreference.ts';