@thedatagrid/docs-kit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +123 -2
  3. package/dist/code/demoFiles.d.ts +14 -0
  4. package/dist/code/demoFiles.d.ts.map +1 -0
  5. package/dist/code/demoFiles.js +46 -0
  6. package/dist/code/demoFiles.js.map +1 -0
  7. package/dist/code/heights.d.ts +17 -0
  8. package/dist/code/heights.d.ts.map +1 -0
  9. package/dist/code/heights.js +40 -0
  10. package/dist/code/heights.js.map +1 -0
  11. package/dist/code/highlightSpec.d.ts +34 -0
  12. package/dist/code/highlightSpec.d.ts.map +1 -0
  13. package/dist/code/highlightSpec.js +119 -0
  14. package/dist/code/highlightSpec.js.map +1 -0
  15. package/dist/code/imports.d.ts +5 -0
  16. package/dist/code/imports.d.ts.map +1 -0
  17. package/dist/code/imports.js +17 -0
  18. package/dist/code/imports.js.map +1 -0
  19. package/dist/code/index.d.ts +8 -0
  20. package/dist/code/index.d.ts.map +1 -0
  21. package/dist/code/index.js +8 -0
  22. package/dist/code/index.js.map +1 -0
  23. package/dist/code/lineRanges.d.ts +5 -0
  24. package/dist/code/lineRanges.d.ts.map +1 -0
  25. package/dist/code/lineRanges.js +35 -0
  26. package/dist/code/lineRanges.js.map +1 -0
  27. package/dist/code/regions.d.ts +53 -0
  28. package/dist/code/regions.d.ts.map +1 -0
  29. package/dist/code/regions.js +237 -0
  30. package/dist/code/regions.js.map +1 -0
  31. package/dist/code/shiki.d.ts +58 -0
  32. package/dist/code/shiki.d.ts.map +1 -0
  33. package/dist/code/shiki.js +244 -0
  34. package/dist/code/shiki.js.map +1 -0
  35. package/dist/demos/build.d.ts +17 -0
  36. package/dist/demos/build.d.ts.map +1 -0
  37. package/dist/demos/build.js +426 -0
  38. package/dist/demos/build.js.map +1 -0
  39. package/dist/demos/cli.d.ts +3 -0
  40. package/dist/demos/cli.d.ts.map +1 -0
  41. package/dist/demos/cli.js +68 -0
  42. package/dist/demos/cli.js.map +1 -0
  43. package/dist/demos/client.d.ts +27 -0
  44. package/dist/demos/client.d.ts.map +1 -0
  45. package/dist/demos/client.js +61 -0
  46. package/dist/demos/client.js.map +1 -0
  47. package/dist/demos/compile/core.d.ts +64 -0
  48. package/dist/demos/compile/core.d.ts.map +1 -0
  49. package/dist/demos/compile/core.js +174 -0
  50. package/dist/demos/compile/core.js.map +1 -0
  51. package/dist/demos/config.d.ts +108 -0
  52. package/dist/demos/config.d.ts.map +1 -0
  53. package/dist/demos/config.js +4 -0
  54. package/dist/demos/config.js.map +1 -0
  55. package/dist/demos/devEvents.d.ts +13 -0
  56. package/dist/demos/devEvents.d.ts.map +1 -0
  57. package/dist/demos/devEvents.js +45 -0
  58. package/dist/demos/devEvents.js.map +1 -0
  59. package/dist/demos/html.d.ts +21 -0
  60. package/dist/demos/html.d.ts.map +1 -0
  61. package/dist/demos/html.js +57 -0
  62. package/dist/demos/html.js.map +1 -0
  63. package/dist/demos/index.d.ts +8 -0
  64. package/dist/demos/index.d.ts.map +1 -0
  65. package/dist/demos/index.js +6 -0
  66. package/dist/demos/index.js.map +1 -0
  67. package/dist/demos/pages.d.ts +15 -0
  68. package/dist/demos/pages.d.ts.map +1 -0
  69. package/dist/demos/pages.js +71 -0
  70. package/dist/demos/pages.js.map +1 -0
  71. package/dist/demos/runtime/iframe.d.ts +50 -0
  72. package/dist/demos/runtime/iframe.d.ts.map +1 -0
  73. package/dist/demos/runtime/iframe.js +245 -0
  74. package/dist/demos/runtime/iframe.js.map +1 -0
  75. package/dist/demos/runtime/react.d.ts +3 -0
  76. package/dist/demos/runtime/react.d.ts.map +1 -0
  77. package/dist/demos/runtime/react.js +17 -0
  78. package/dist/demos/runtime/react.js.map +1 -0
  79. package/dist/demos/slug.d.ts +3 -0
  80. package/dist/demos/slug.d.ts.map +1 -0
  81. package/dist/demos/slug.js +11 -0
  82. package/dist/demos/slug.js.map +1 -0
  83. package/dist/demos/vendor.d.ts +32 -0
  84. package/dist/demos/vendor.d.ts.map +1 -0
  85. package/dist/demos/vendor.js +127 -0
  86. package/dist/demos/vendor.js.map +1 -0
  87. package/dist/demos/worker/compile.worker.d.ts +2 -0
  88. package/dist/demos/worker/compile.worker.d.ts.map +1 -0
  89. package/dist/demos/worker/compile.worker.js +27 -0
  90. package/dist/demos/worker/compile.worker.js.map +1 -0
  91. package/dist/fork/codesandbox.d.ts +39 -0
  92. package/dist/fork/codesandbox.d.ts.map +1 -0
  93. package/dist/fork/codesandbox.js +156 -0
  94. package/dist/fork/codesandbox.js.map +1 -0
  95. package/dist/fork/index.d.ts +2 -0
  96. package/dist/fork/index.d.ts.map +1 -0
  97. package/dist/fork/index.js +2 -0
  98. package/dist/fork/index.js.map +1 -0
  99. package/dist/react/Demo.d.ts +80 -0
  100. package/dist/react/Demo.d.ts.map +1 -0
  101. package/dist/react/Demo.js +156 -0
  102. package/dist/react/Demo.js.map +1 -0
  103. package/dist/react/DemoIframe.d.ts +22 -0
  104. package/dist/react/DemoIframe.d.ts.map +1 -0
  105. package/dist/react/DemoIframe.js +123 -0
  106. package/dist/react/DemoIframe.js.map +1 -0
  107. package/dist/react/DemoShell.d.ts +47 -0
  108. package/dist/react/DemoShell.d.ts.map +1 -0
  109. package/dist/react/DemoShell.js +341 -0
  110. package/dist/react/DemoShell.js.map +1 -0
  111. package/dist/react/devEvents.d.ts +17 -0
  112. package/dist/react/devEvents.d.ts.map +1 -0
  113. package/dist/react/devEvents.js +30 -0
  114. package/dist/react/devEvents.js.map +1 -0
  115. package/dist/react/editor.d.ts +8 -0
  116. package/dist/react/editor.d.ts.map +1 -0
  117. package/dist/react/editor.js +52 -0
  118. package/dist/react/editor.js.map +1 -0
  119. package/dist/react/fork.d.ts +10 -0
  120. package/dist/react/fork.d.ts.map +1 -0
  121. package/dist/react/fork.js +30 -0
  122. package/dist/react/fork.js.map +1 -0
  123. package/dist/react/index.d.ts +4 -0
  124. package/dist/react/index.d.ts.map +1 -0
  125. package/dist/react/index.js +4 -0
  126. package/dist/react/index.js.map +1 -0
  127. package/dist/react/styles.css +493 -0
  128. package/dist/remark/index.d.ts +3 -0
  129. package/dist/remark/index.d.ts.map +1 -0
  130. package/dist/remark/index.js +3 -0
  131. package/dist/remark/index.js.map +1 -0
  132. package/dist/remark/meta.d.ts +7 -0
  133. package/dist/remark/meta.d.ts.map +1 -0
  134. package/dist/remark/meta.js +20 -0
  135. package/dist/remark/meta.js.map +1 -0
  136. package/dist/remark/remarkDemoFences.d.ts +77 -0
  137. package/dist/remark/remarkDemoFences.d.ts.map +1 -0
  138. package/dist/remark/remarkDemoFences.js +259 -0
  139. package/dist/remark/remarkDemoFences.js.map +1 -0
  140. package/package.json +106 -4
  141. package/src/code/demoFiles.ts +54 -0
  142. package/src/code/heights.ts +47 -0
  143. package/src/code/highlightSpec.ts +139 -0
  144. package/src/code/imports.ts +18 -0
  145. package/src/code/index.ts +46 -0
  146. package/src/code/lineRanges.ts +31 -0
  147. package/src/code/regions.ts +270 -0
  148. package/src/code/shiki.ts +271 -0
  149. package/src/demos/build.ts +477 -0
  150. package/src/demos/cli.ts +64 -0
  151. package/src/demos/client.ts +82 -0
  152. package/src/demos/compile/core.ts +228 -0
  153. package/src/demos/config.ts +106 -0
  154. package/src/demos/devEvents.ts +45 -0
  155. package/src/demos/html.ts +74 -0
  156. package/src/demos/index.ts +25 -0
  157. package/src/demos/pages.ts +79 -0
  158. package/src/demos/runtime/iframe.ts +262 -0
  159. package/src/demos/runtime/react.ts +19 -0
  160. package/src/demos/slug.ts +10 -0
  161. package/src/demos/vendor.ts +142 -0
  162. package/src/demos/worker/compile.worker.ts +35 -0
  163. package/src/fork/codesandbox.ts +189 -0
  164. package/src/fork/index.ts +10 -0
  165. package/src/react/Demo.tsx +250 -0
  166. package/src/react/DemoIframe.tsx +165 -0
  167. package/src/react/DemoShell.tsx +592 -0
  168. package/src/react/devEvents.ts +34 -0
  169. package/src/react/editor.ts +61 -0
  170. package/src/react/fork.ts +31 -0
  171. package/src/react/index.ts +10 -0
  172. package/src/react/styles.css +493 -0
  173. package/src/remark/index.ts +2 -0
  174. package/src/remark/meta.ts +20 -0
  175. package/src/remark/remarkDemoFences.ts +330 -0
@@ -0,0 +1,592 @@
1
+ 'use client';
2
+
3
+ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
4
+ import { createPortal } from 'react-dom';
5
+
6
+ import type { DemoHeight, DemoHeights } from '../code/heights.ts';
7
+ import type { ForkConfig } from '../demos/config.ts';
8
+ import type { CompileOptions, Compiler, CompilerConfig } from '../demos/client.ts';
9
+ import { DemoIframe, type DemoIframeHandle } from './DemoIframe.tsx';
10
+ import { forkInCodeSandbox } from './fork.ts';
11
+
12
+ export type DemoShellFile = {
13
+ /** Tab name: path relative to the demo entry's folder. */
14
+ name: string;
15
+ /** Content-relative path (what rebuilds and forks use). Empty for code-only cards. */
16
+ path: string;
17
+ /** What copy copies: the shown code (region sliced) without marker comments. */
18
+ rawCode: string;
19
+ /** Whole file without marker comments: what editing and forks start from. */
20
+ fullCode?: string;
21
+ /** Server-highlighted HTML (shiki). */
22
+ html: string;
23
+ };
24
+
25
+ export type DemoShellProps = {
26
+ /** Prebuilt iframe page. Omitted for code-only cards. */
27
+ demoUrl?: string;
28
+ /** Preview pixels or `auto` (the card takes the code height); `null` when not specified. */
29
+ height: DemoHeight | null;
30
+ heights: DemoHeights;
31
+ initialTab?: 'preview' | 'code';
32
+ title: string;
33
+ /** Anchor: `#slug` (preview) or `#slug/file` (a code tab). Empty: no anchor. */
34
+ slug: string;
35
+ /** Entry first, then the files it imports. */
36
+ files: DemoShellFile[];
37
+ hideFiles?: boolean;
38
+ /** `<DemoTitle>` / `<DemoDescription>` card header. */
39
+ header?: ReactNode;
40
+ /** Present when the demo can be edited. */
41
+ editor?: { compiler: CompilerConfig; options: CompileOptions };
42
+ fork?: ForkConfig;
43
+ /** Dev-only SSE endpoint (`:port/path`). */
44
+ devEvents?: string;
45
+ };
46
+
47
+ const hashFragment = (hash: string) => decodeURIComponent(hash.replace(/^#/, ''));
48
+
49
+ function parseDemoHash(hash: string, slug: string): { matches: boolean; fileName: string | null } {
50
+ const raw = hashFragment(hash);
51
+ if (raw === slug) return { matches: true, fileName: null };
52
+ if (raw.startsWith(`${slug}/`)) return { matches: true, fileName: raw.slice(slug.length + 1) || null };
53
+ return { matches: false, fileName: null };
54
+ }
55
+
56
+ function replaceHash(hash: string) {
57
+ if (hashFragment(window.location.hash) === hash) return;
58
+ // Keep the history entry (and the router's state): a URL update, not a scrolling hash navigation.
59
+ history.replaceState(history.state, '', `#${hash}`);
60
+ }
61
+
62
+ function overlayMarker(state: unknown): { slug: string; id: number } | null {
63
+ const marker = (state as { demoOverlay?: { slug?: unknown; id?: unknown } } | null)?.demoOverlay;
64
+ if (!marker || typeof marker.slug !== 'string' || typeof marker.id !== 'number') return null;
65
+ return { slug: marker.slug, id: marker.id };
66
+ }
67
+
68
+ type CompileStatus = 'idle' | 'compiling' | 'ok' | 'error';
69
+
70
+ /**
71
+ * The demo card: Preview / Code tabs (one tab per source file), copy, reset,
72
+ * open, full screen, fork, and Edit — CodeMirror (loaded on first use) next
73
+ * to the preview, rebuilt in the browser on every change.
74
+ */
75
+ export function DemoShell(props: DemoShellProps) {
76
+ const { demoUrl, height, heights, initialTab, title, slug, files, hideFiles, header, editor } = props;
77
+ const [tab, setTab] = useState<'preview' | 'code'>(demoUrl ? (initialTab ?? 'preview') : 'code');
78
+ const [activeFile, setActiveFile] = useState(0);
79
+ const [copied, setCopied] = useState(false);
80
+ const rootRef = useRef<HTMLDivElement | null>(null);
81
+ const codeRef = useRef<HTMLDivElement | null>(null);
82
+ const iframeRef = useRef<DemoIframeHandle | null>(null);
83
+
84
+ // --- editing -------------------------------------------------------------
85
+ const [editing, setEditing] = useState(false);
86
+ /** Edited contents by file path; files never touched keep their original. */
87
+ const [edits, setEdits] = useState<Record<string, string>>({});
88
+ const [status, setStatus] = useState<CompileStatus>('idle');
89
+ const [errorCount, setErrorCount] = useState(0);
90
+ const compilerRef = useRef<Compiler | null>(null);
91
+ const lastUpdate = useRef<{ js: string; css: string } | null>(null);
92
+ const dirty = Object.keys(edits).length > 0;
93
+
94
+ const originalByPath = useMemo(
95
+ () => Object.fromEntries(files.map((file) => [file.path, file.fullCode ?? file.rawCode])),
96
+ [files],
97
+ );
98
+ const currentFiles = useCallback(
99
+ () => Object.fromEntries(files.map((file) => [file.path, edits[file.path] ?? originalByPath[file.path]])),
100
+ [files, edits, originalByPath],
101
+ );
102
+
103
+ useEffect(() => {
104
+ if (!editing || !dirty || !editor || !demoUrl) return;
105
+ let cancelled = false;
106
+ setStatus('compiling');
107
+ const timer = window.setTimeout(async () => {
108
+ if (!compilerRef.current) {
109
+ const { createCompiler } = await import('../demos/client.ts');
110
+ compilerRef.current = createCompiler(editor.compiler, editor.options);
111
+ }
112
+ const { formatCompileErrors } = await import('../demos/client.ts');
113
+ const result = await compilerRef.current.compile({ files: currentFiles(), entry: files[0].path });
114
+ if (cancelled) return;
115
+ if (result.ok) {
116
+ lastUpdate.current = { js: result.js, css: result.css };
117
+ iframeRef.current?.post({ type: 'demo-update', js: result.js, css: result.css });
118
+ setStatus('ok');
119
+ setErrorCount(0);
120
+ } else {
121
+ iframeRef.current?.post({ type: 'demo-compile-error', message: formatCompileErrors(result.errors) });
122
+ setStatus('error');
123
+ setErrorCount(result.errors.length);
124
+ }
125
+ }, 350);
126
+ return () => {
127
+ cancelled = true;
128
+ window.clearTimeout(timer);
129
+ };
130
+ }, [editing, dirty, edits, editor, demoUrl, currentFiles, files]);
131
+
132
+ const onIframeReady = useCallback(() => {
133
+ // the iframe reloaded (dev rebuild, theme bridge, reset) — re-apply the edited build
134
+ if (lastUpdate.current && editing && dirty) iframeRef.current?.post({ type: 'demo-update', ...lastUpdate.current });
135
+ }, [editing, dirty]);
136
+
137
+ const resetEdits = () => {
138
+ setEdits({});
139
+ lastUpdate.current = null;
140
+ setStatus('idle');
141
+ setErrorCount(0);
142
+ iframeRef.current?.reload();
143
+ };
144
+
145
+ const startEditing = () => {
146
+ setEditing(true);
147
+ setTab('code');
148
+ };
149
+
150
+ // --- height --------------------------------------------------------------
151
+ // height="auto": the code renders at its natural height and the preview
152
+ // reuses the measured code height, never less than heights.default.
153
+ const [measuredCodeHeight, setMeasuredCodeHeight] = useState<number | null>(null);
154
+ useLayoutEffect(() => {
155
+ if (height !== 'auto' || tab !== 'code' || editing) return;
156
+ const el = codeRef.current;
157
+ if (!el) return;
158
+ const measure = () => setMeasuredCodeHeight(el.offsetHeight);
159
+ measure();
160
+ const observer = new ResizeObserver(measure);
161
+ observer.observe(el);
162
+ return () => observer.disconnect();
163
+ }, [height, tab, editing]);
164
+ const previewHeight =
165
+ height === 'auto'
166
+ ? Math.max(measuredCodeHeight ?? heights.default, heights.default)
167
+ : (height ?? heights.default);
168
+
169
+ const current = files[activeFile] ?? files[0];
170
+
171
+ const showCode = (index: number) => {
172
+ setActiveFile(index);
173
+ setTab('code');
174
+ const file = files[index] ?? files[0];
175
+ if (slug && file?.name) replaceHash(`${slug}/${file.name}`);
176
+ };
177
+ const showPreview = () => {
178
+ setTab('preview');
179
+ if (slug) replaceHash(slug);
180
+ };
181
+
182
+ // --- full screen overlay (lives in the history stack, not the URL) --------
183
+ const [overlay, setOverlay] = useState(false);
184
+ const overlayRef = useRef(false);
185
+ overlayRef.current = overlay;
186
+ const overlayEntryId = useRef(0);
187
+ const nextOverlayId = useRef(0);
188
+ const closingOverlay = useRef(false);
189
+ const restoredFromHash = useRef(false);
190
+
191
+ const openOverlay = () => {
192
+ if (overlayRef.current) return;
193
+ nextOverlayId.current += 1;
194
+ overlayEntryId.current = nextOverlayId.current;
195
+ const prev = history.state && typeof history.state === 'object' ? history.state : null;
196
+ history.pushState({ ...prev, demoOverlay: { slug, id: overlayEntryId.current } }, '', `#${slug}`);
197
+ setOverlay(true);
198
+ };
199
+ const closeOverlay = useCallback(() => {
200
+ if (!overlayRef.current || closingOverlay.current) return;
201
+ closingOverlay.current = true;
202
+ history.back();
203
+ }, []);
204
+
205
+ // Reload / shared link: restore preview vs code from the hash, then scroll
206
+ // the card into view. Tab clicks only update the hash (no scrolling).
207
+ useLayoutEffect(() => {
208
+ if (restoredFromHash.current) return;
209
+ if (!slug) {
210
+ restoredFromHash.current = true;
211
+ return;
212
+ }
213
+ const parsed = parseDemoHash(window.location.hash, slug);
214
+ if (!parsed.matches) {
215
+ restoredFromHash.current = true;
216
+ return;
217
+ }
218
+ if (parsed.fileName) {
219
+ const index = files.findIndex((file) => file.name === parsed.fileName);
220
+ if (index < 0 || (hideFiles && index > 0)) {
221
+ restoredFromHash.current = true;
222
+ return;
223
+ }
224
+ if (tab !== 'code' || activeFile !== index) {
225
+ setActiveFile(index);
226
+ setTab('code');
227
+ return;
228
+ }
229
+ }
230
+ restoredFromHash.current = true;
231
+ const offset = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 80;
232
+ const top = window.scrollY + (rootRef.current?.getBoundingClientRect().top ?? 0) - offset;
233
+ window.scrollTo({ top: Math.max(0, top), behavior: 'instant' });
234
+ }, [slug, tab, activeFile, files, hideFiles]);
235
+
236
+ useEffect(() => {
237
+ const onPop = (event: PopStateEvent) => {
238
+ const marker = overlayMarker(event.state);
239
+ if (marker && marker.slug === slug && marker.id === overlayEntryId.current) {
240
+ setOverlay(true);
241
+ return;
242
+ }
243
+ if (overlayRef.current) setOverlay(false);
244
+ };
245
+ window.addEventListener('popstate', onPop);
246
+ return () => window.removeEventListener('popstate', onPop);
247
+ }, [slug]);
248
+
249
+ useEffect(() => {
250
+ if (!overlay) {
251
+ closingOverlay.current = false;
252
+ return;
253
+ }
254
+ const onKey = (event: KeyboardEvent) => {
255
+ if (event.key === 'Escape') closeOverlay();
256
+ };
257
+ const prevOverflow = document.body.style.overflow;
258
+ document.body.style.overflow = 'hidden';
259
+ document.addEventListener('keydown', onKey, true);
260
+ return () => {
261
+ document.body.style.overflow = prevOverflow;
262
+ document.removeEventListener('keydown', onKey, true);
263
+ };
264
+ }, [overlay, closeOverlay]);
265
+
266
+ const fork = () =>
267
+ forkInCodeSandbox({
268
+ title,
269
+ entry: files[0].path,
270
+ files: files.map((file) => ({ path: file.path, content: edits[file.path] ?? originalByPath[file.path] })),
271
+ config: props.fork,
272
+ });
273
+
274
+ const showFileTabs = !hideFiles && files.length > 1 && (tab === 'code' || editing);
275
+ // a plain snippet: no title, no file name — just the code and a floating copy button
276
+ const bare = !demoUrl && !header && !files[0].name;
277
+ const codeVisible = editing || tab === 'code';
278
+ const previewVisible = demoUrl && (editing || tab === 'preview') && !overlay;
279
+
280
+ return (
281
+ <div
282
+ ref={rootRef}
283
+ id={slug || undefined}
284
+ className={`dk-demo${editing ? ' dk-demo--editing' : ''}${demoUrl ? '' : ' dk-demo--code-only'}${bare ? ' dk-demo--bare' : ''}`}
285
+ >
286
+ {header ? (
287
+ <div className="dk-demo-header">
288
+ <a
289
+ href={`#${slug}`}
290
+ className="dk-demo-permalink"
291
+ aria-label="Link to this demo"
292
+ title="Link to this demo"
293
+ onClick={(event) => {
294
+ if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
295
+ event.preventDefault();
296
+ replaceHash(slug);
297
+ }}
298
+ >
299
+ #
300
+ </a>
301
+ {header}
302
+ </div>
303
+ ) : null}
304
+ <div className="dk-demo-toolbar">
305
+ {demoUrl && !editing ? (
306
+ <>
307
+ <TabButton active={tab === 'preview'} onClick={showPreview}>
308
+ Preview
309
+ </TabButton>
310
+ <TabButton active={tab === 'code'} onClick={() => showCode(activeFile)}>
311
+ Code
312
+ </TabButton>
313
+ </>
314
+ ) : null}
315
+ {editing ? <span className="dk-demo-badge">{dirty ? 'edited' : 'editing'}</span> : null}
316
+ {showFileTabs ? (
317
+ <span className="dk-demo-files">
318
+ {files.map((file, index) => (
319
+ <a
320
+ key={file.path || file.name}
321
+ href={`#${slug}/${file.name}`}
322
+ onClick={(event) => {
323
+ event.preventDefault();
324
+ showCode(index);
325
+ }}
326
+ className={`dk-demo-file${index === activeFile ? ' dk-demo-file--active' : ''}`}
327
+ >
328
+ {file.name}
329
+ {edits[file.path] != null ? ' •' : ''}
330
+ </a>
331
+ ))}
332
+ </span>
333
+ ) : !hideFiles && files[0].name && (tab === 'code' || editing) ? (
334
+ <span className="dk-demo-filename">{files[0].name}</span>
335
+ ) : null}
336
+ <span className="dk-demo-spacer" />
337
+ {editing ? (
338
+ <>
339
+ <CompileStatusLabel status={status} errorCount={errorCount} />
340
+ {dirty ? (
341
+ <ToolbarButton title="Discard your changes and restore the original demo" onClick={resetEdits}>
342
+ reset ↺
343
+ </ToolbarButton>
344
+ ) : null}
345
+ <ToolbarButton title={`Fork “${title}” in CodeSandbox (with your changes)`} onClick={fork}>
346
+ fork ⑂
347
+ </ToolbarButton>
348
+ <ToolbarButton title="Stop editing (your changes stay until you reset or leave the page)" onClick={() => setEditing(false)}>
349
+ done
350
+ </ToolbarButton>
351
+ </>
352
+ ) : tab === 'code' ? (
353
+ <>
354
+ <ToolbarButton
355
+ onClick={() => {
356
+ void navigator.clipboard.writeText(current.rawCode);
357
+ setCopied(true);
358
+ window.setTimeout(() => setCopied(false), 1200);
359
+ }}
360
+ >
361
+ {copied ? 'copied ✓' : 'copy'}
362
+ </ToolbarButton>
363
+ {editor && demoUrl ? (
364
+ <ToolbarButton title="Edit the code and see the preview update" onClick={startEditing}>
365
+ edit ✎
366
+ </ToolbarButton>
367
+ ) : null}
368
+ </>
369
+ ) : (
370
+ <>
371
+ {editor ? (
372
+ <ToolbarButton title="Edit the code and see the preview update" onClick={startEditing}>
373
+ edit ✎
374
+ </ToolbarButton>
375
+ ) : null}
376
+ <ToolbarButton
377
+ title={dirty ? 'Discard your changes and restore the original demo' : 'Reset the demo to its initial state'}
378
+ onClick={dirty ? resetEdits : () => iframeRef.current?.reset()}
379
+ >
380
+ reset ↺
381
+ </ToolbarButton>
382
+ <ToolbarButton title={`Fork “${title}” in CodeSandbox`} onClick={fork}>
383
+ fork ⑂
384
+ </ToolbarButton>
385
+ <OpenDemoLink demoUrl={demoUrl!} title={title} />
386
+ <IconButton title="Full screen" onClick={openOverlay}>
387
+ <ExpandIcon />
388
+ </IconButton>
389
+ </>
390
+ )}
391
+ </div>
392
+
393
+ <div className="dk-demo-body" style={editing ? { height: Math.max(previewHeight, 420) } : undefined}>
394
+ {demoUrl ? (
395
+ <div className="dk-demo-preview" style={{ display: previewVisible ? undefined : 'none' }}>
396
+ <DemoIframe
397
+ ref={iframeRef}
398
+ demoUrl={demoUrl}
399
+ height={editing ? undefined : previewHeight}
400
+ title={title}
401
+ devEvents={props.devEvents}
402
+ onReady={onIframeReady}
403
+ />
404
+ </div>
405
+ ) : null}
406
+ {codeVisible ? (
407
+ editing ? (
408
+ <div className="dk-demo-editor-pane">
409
+ <LazyEditor
410
+ key={current.path}
411
+ file={current}
412
+ value={edits[current.path] ?? originalByPath[current.path]}
413
+ onChange={(value) =>
414
+ setEdits((prev) => {
415
+ const next = { ...prev };
416
+ if (value === originalByPath[current.path]) delete next[current.path];
417
+ else next[current.path] = value;
418
+ return next;
419
+ })
420
+ }
421
+ />
422
+ </div>
423
+ ) : (
424
+ <div
425
+ ref={codeRef}
426
+ className={`dk-demo-code${!demoUrl && height == null ? ' dk-demo-code--capped' : ''}`}
427
+ style={
428
+ demoUrl && height !== 'auto'
429
+ ? { height: previewHeight }
430
+ : !demoUrl && typeof height === 'number'
431
+ ? { maxHeight: height }
432
+ : undefined
433
+ }
434
+ onClick={(event) => {
435
+ const el = (event.target as HTMLElement).closest('[data-demo-file]');
436
+ if (!el) return;
437
+ const index = files.findIndex((file) => file.name === el.getAttribute('data-demo-file'));
438
+ if (index >= 0) showCode(index);
439
+ }}
440
+ dangerouslySetInnerHTML={{ __html: current.html }}
441
+ />
442
+ )
443
+ ) : null}
444
+ </div>
445
+ {overlay && demoUrl
446
+ ? createPortal(<DemoOverlay title={title} demoUrl={demoUrl} onClose={closeOverlay} />, document.body)
447
+ : null}
448
+ </div>
449
+ );
450
+ }
451
+
452
+ function CompileStatusLabel({ status, errorCount }: { status: CompileStatus; errorCount: number }) {
453
+ if (status === 'idle') return <span className="dk-demo-status">type to update the preview</span>;
454
+ if (status === 'compiling') return <span className="dk-demo-status">building…</span>;
455
+ if (status === 'error') {
456
+ return (
457
+ <span className="dk-demo-status dk-demo-status--error">
458
+ {errorCount} error{errorCount === 1 ? '' : 's'}
459
+ </span>
460
+ );
461
+ }
462
+ return <span className="dk-demo-status dk-demo-status--ok">updated ✓</span>;
463
+ }
464
+
465
+ /** CodeMirror, imported only when someone starts editing. */
466
+ function LazyEditor(props: { file: DemoShellFile; value: string; onChange: (value: string) => void }) {
467
+ const hostRef = useRef<HTMLDivElement | null>(null);
468
+ const onChangeRef = useRef(props.onChange);
469
+ onChangeRef.current = props.onChange;
470
+ const [failed, setFailed] = useState<string | null>(null);
471
+ const initial = useRef(props.value);
472
+
473
+ useEffect(() => {
474
+ let disposed = false;
475
+ let destroy: (() => void) | null = null;
476
+ import('./editor.ts')
477
+ .then(({ createCodeEditor }) => {
478
+ if (disposed || !hostRef.current) return;
479
+ const view = createCodeEditor(hostRef.current, {
480
+ doc: initial.current,
481
+ fileName: props.file.name || props.file.path,
482
+ onChange: (value) => onChangeRef.current(value),
483
+ });
484
+ destroy = view.destroy;
485
+ })
486
+ .catch((error) => setFailed(String(error)));
487
+ return () => {
488
+ disposed = true;
489
+ destroy?.();
490
+ };
491
+ }, [props.file.name, props.file.path]);
492
+
493
+ if (failed) return <pre className="dk-demo-editor-error">The editor failed to load: {failed}</pre>;
494
+ return <div ref={hostRef} className="dk-demo-editor" />;
495
+ }
496
+
497
+ function TabButton(props: { active: boolean; onClick: () => void; children: ReactNode }) {
498
+ return (
499
+ <button type="button" onClick={props.onClick} className={`dk-demo-tab${props.active ? ' dk-demo-tab--active' : ''}`}>
500
+ {props.children}
501
+ </button>
502
+ );
503
+ }
504
+
505
+ function ToolbarButton(props: { title?: string; onClick: () => void; children: ReactNode }) {
506
+ return (
507
+ <button type="button" title={props.title} onClick={props.onClick} className="dk-demo-action">
508
+ {props.children}
509
+ </button>
510
+ );
511
+ }
512
+
513
+ function IconButton(props: { title: string; onClick: () => void; children: ReactNode }) {
514
+ return (
515
+ <button type="button" title={props.title} aria-label={props.title} onClick={props.onClick} className="dk-demo-icon">
516
+ {props.children}
517
+ </button>
518
+ );
519
+ }
520
+
521
+ function ExpandIcon() {
522
+ return (
523
+ <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
524
+ <path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7" />
525
+ </svg>
526
+ );
527
+ }
528
+
529
+ function CloseIcon() {
530
+ return (
531
+ <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round">
532
+ <path d="M6 6l12 12M18 6 6 18" />
533
+ </svg>
534
+ );
535
+ }
536
+
537
+ function DemoOverlay(props: { title: string; demoUrl: string; onClose: () => void }) {
538
+ const iframeRef = useRef<DemoIframeHandle | null>(null);
539
+ return (
540
+ <div
541
+ className="dk-demo-overlay"
542
+ onMouseDown={(event) => {
543
+ if (event.target === event.currentTarget) props.onClose();
544
+ }}
545
+ >
546
+ <div className="dk-demo-overlay-card">
547
+ <div className="dk-demo-toolbar">
548
+ <span className="dk-demo-overlay-title">{props.title}</span>
549
+ <span className="dk-demo-spacer" />
550
+ <ToolbarButton title="Reset the demo to its initial state" onClick={() => iframeRef.current?.reset()}>
551
+ reset ↺
552
+ </ToolbarButton>
553
+ <IconButton title="Close" onClick={props.onClose}>
554
+ <CloseIcon />
555
+ </IconButton>
556
+ </div>
557
+ <DemoIframe ref={iframeRef} demoUrl={props.demoUrl} title={props.title} onEscape={props.onClose} />
558
+ </div>
559
+ </div>
560
+ );
561
+ }
562
+
563
+ /** Standalone demo URL carrying the current docs theme. */
564
+ function themedDemoUrl(demoUrl: string) {
565
+ const theme = document.documentElement.getAttribute('data-theme') || 'light';
566
+ return `${demoUrl}?theme=${encodeURIComponent(theme)}`;
567
+ }
568
+
569
+ function OpenDemoLink({ demoUrl, title }: { demoUrl: string; title: string }) {
570
+ const [href, setHref] = useState(demoUrl);
571
+ useEffect(() => {
572
+ const update = () => setHref(themedDemoUrl(demoUrl));
573
+ update();
574
+ const observer = new MutationObserver(update);
575
+ observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
576
+ return () => observer.disconnect();
577
+ }, [demoUrl]);
578
+ return (
579
+ <a
580
+ href={href}
581
+ target="_blank"
582
+ rel="noreferrer"
583
+ title={`Open “${title}” in a new tab`}
584
+ onClick={(event) => {
585
+ event.currentTarget.href = themedDemoUrl(demoUrl);
586
+ }}
587
+ className="dk-demo-action"
588
+ >
589
+ open ↗
590
+ </a>
591
+ );
592
+ }
@@ -0,0 +1,34 @@
1
+ 'use client';
2
+
3
+ export type DevEvent = { type: 'demo'; id: string; url: string } | { type: 'build-error'; message: string };
4
+
5
+ type Listener = (event: DevEvent) => void;
6
+
7
+ const listeners = new Set<Listener>();
8
+ let source: EventSource | null = null;
9
+
10
+ /**
11
+ * Dev only: one shared connection to the demo watcher's SSE stream
12
+ * (`endpoint` is `:port/path`, resolved against the page's host). It closes
13
+ * with the last subscriber.
14
+ */
15
+ export function subscribeDevEvents(endpoint: string, listener: Listener): () => void {
16
+ listeners.add(listener);
17
+ if (!source) {
18
+ const url = endpoint.startsWith(':')
19
+ ? `${location.protocol}//${location.hostname}${endpoint}`
20
+ : new URL(endpoint, location.href).href;
21
+ source = new EventSource(url);
22
+ source.onmessage = (message) => {
23
+ const event = JSON.parse(message.data) as DevEvent;
24
+ for (const current of listeners) current(event);
25
+ };
26
+ }
27
+ return () => {
28
+ listeners.delete(listener);
29
+ if (!listeners.size && source) {
30
+ source.close();
31
+ source = null;
32
+ }
33
+ };
34
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * CodeMirror 6 for demo editing. Only imported (dynamically) when someone
3
+ * clicks Edit, so pages that are just read never download it. Colors come
4
+ * from `--dk-*` CSS variables (see styles.css): tokens get `tok-*` classes.
5
+ */
6
+ import { autocompletion, closeBrackets, closeBracketsKeymap } from '@codemirror/autocomplete';
7
+ import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
8
+ import { css } from '@codemirror/lang-css';
9
+ import { javascript } from '@codemirror/lang-javascript';
10
+ import { bracketMatching, indentOnInput, indentUnit, syntaxHighlighting } from '@codemirror/language';
11
+ import { highlightSelectionMatches, searchKeymap } from '@codemirror/search';
12
+ import { EditorState, type Extension } from '@codemirror/state';
13
+ import {
14
+ drawSelection,
15
+ EditorView,
16
+ highlightActiveLine,
17
+ highlightActiveLineGutter,
18
+ keymap,
19
+ lineNumbers,
20
+ } from '@codemirror/view';
21
+ import { classHighlighter } from '@lezer/highlight';
22
+
23
+ function languageFor(fileName: string): Extension {
24
+ if (/\.css$/.test(fileName)) return css();
25
+ const ts = /\.[cm]?tsx?$/.test(fileName);
26
+ const jsx = /x$/.test(fileName) || !/\.[cm]?[jt]s$/.test(fileName);
27
+ return javascript({ typescript: ts, jsx });
28
+ }
29
+
30
+ export function createCodeEditor(
31
+ parent: HTMLElement,
32
+ options: { doc: string; fileName: string; onChange: (value: string) => void },
33
+ ) {
34
+ const view = new EditorView({
35
+ parent,
36
+ state: EditorState.create({
37
+ doc: options.doc,
38
+ extensions: [
39
+ lineNumbers(),
40
+ highlightActiveLineGutter(),
41
+ highlightActiveLine(),
42
+ history(),
43
+ drawSelection(),
44
+ indentOnInput(),
45
+ indentUnit.of(' '),
46
+ bracketMatching(),
47
+ closeBrackets(),
48
+ autocompletion({ activateOnTyping: false }),
49
+ highlightSelectionMatches(),
50
+ syntaxHighlighting(classHighlighter),
51
+ languageFor(options.fileName),
52
+ keymap.of([...closeBracketsKeymap, ...defaultKeymap, ...searchKeymap, ...historyKeymap, indentWithTab]),
53
+ EditorView.updateListener.of((update) => {
54
+ if (update.docChanged) options.onChange(update.state.doc.toString());
55
+ }),
56
+ EditorView.contentAttributes.of({ 'aria-label': `Edit ${options.fileName}` }),
57
+ ],
58
+ }),
59
+ });
60
+ return { destroy: () => view.destroy() };
61
+ }