@thedatagrid/docs-kit 0.4.0 → 0.5.1
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 +18 -0
- package/README.md +23 -0
- package/dist/code/shiki.d.ts +4 -3
- package/dist/code/shiki.d.ts.map +1 -1
- package/dist/code/shiki.js +4 -3
- package/dist/code/shiki.js.map +1 -1
- package/dist/demos/config.d.ts +14 -0
- package/dist/demos/config.d.ts.map +1 -1
- package/dist/demos/config.js.map +1 -1
- 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/fork/codesandbox.d.ts +4 -0
- package/dist/fork/codesandbox.d.ts.map +1 -1
- package/dist/fork/codesandbox.js +5 -3
- package/dist/fork/codesandbox.js.map +1 -1
- package/dist/fork/index.d.ts +12 -0
- package/dist/fork/index.d.ts.map +1 -1
- package/dist/fork/index.js +19 -0
- package/dist/fork/index.js.map +1 -1
- package/dist/fork/stackblitz.d.ts.map +1 -1
- package/dist/fork/stackblitz.js +4 -4
- package/dist/fork/stackblitz.js.map +1 -1
- package/dist/react/Demo.d.ts.map +1 -1
- package/dist/react/Demo.js +2 -1
- package/dist/react/Demo.js.map +1 -1
- package/dist/react/DemoShell.d.ts.map +1 -1
- package/dist/react/DemoShell.js +33 -6
- package/dist/react/DemoShell.js.map +1 -1
- package/dist/react/fork.d.ts.map +1 -1
- package/dist/react/fork.js +3 -2
- package/dist/react/fork.js.map +1 -1
- package/dist/react/styles.css +69 -0
- package/dist/remark/remarkDemoFences.d.ts +2 -1
- package/dist/remark/remarkDemoFences.d.ts.map +1 -1
- package/dist/remark/remarkDemoFences.js +2 -8
- package/dist/remark/remarkDemoFences.js.map +1 -1
- package/package.json +1 -1
- package/src/code/shiki.ts +4 -3
- package/src/demos/config.ts +15 -0
- package/src/demos/vendor.ts +6 -2
- package/src/fork/codesandbox.ts +8 -3
- package/src/fork/index.ts +31 -0
- package/src/fork/stackblitz.ts +4 -3
- package/src/react/Demo.tsx +2 -1
- package/src/react/DemoShell.tsx +54 -6
- package/src/react/fork.ts +3 -2
- package/src/react/styles.css +69 -0
- package/src/remark/remarkDemoFences.ts +2 -6
package/src/react/Demo.tsx
CHANGED
|
@@ -223,7 +223,8 @@ export async function Demo(props: DemoProps & { context: DemoContext }) {
|
|
|
223
223
|
: langForFile(filePath),
|
|
224
224
|
themes,
|
|
225
225
|
highlight: marked.highlight,
|
|
226
|
-
|
|
226
|
+
// a region is numbered from 1: the reader never sees the rest of the file
|
|
227
|
+
lineNumbers: showLines ? true : null,
|
|
227
228
|
importLinks: filesHidden ? null : { fromFile: name, fileNames: names },
|
|
228
229
|
});
|
|
229
230
|
return {
|
package/src/react/DemoShell.tsx
CHANGED
|
@@ -70,7 +70,12 @@ function overlayMarker(state: unknown): { slug: string; id: number } | null {
|
|
|
70
70
|
return { slug: marker.slug, id: marker.id };
|
|
71
71
|
}
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
/**
|
|
74
|
+
* `error`: the code has compile errors (shown in the preview). `failed`: the
|
|
75
|
+
* build itself didn't run — the compiler didn't load (a chunk that failed to
|
|
76
|
+
* download, e.g. right after a deploy) or threw.
|
|
77
|
+
*/
|
|
78
|
+
type CompileStatus = 'idle' | 'compiling' | 'ok' | 'error' | 'failed';
|
|
74
79
|
|
|
75
80
|
/**
|
|
76
81
|
* The demo card: Preview / Code tabs (one tab per source file), copy, reset,
|
|
@@ -92,6 +97,7 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
92
97
|
const [edits, setEdits] = useState<Record<string, string>>({});
|
|
93
98
|
const [status, setStatus] = useState<CompileStatus>('idle');
|
|
94
99
|
const [errorCount, setErrorCount] = useState(0);
|
|
100
|
+
const [failure, setFailure] = useState<string | null>(null);
|
|
95
101
|
const compilerRef = useRef<Compiler | null>(null);
|
|
96
102
|
const lastUpdate = useRef<{ js: string; css: string } | null>(null);
|
|
97
103
|
const dirty = Object.keys(edits).length > 0;
|
|
@@ -110,13 +116,27 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
110
116
|
let cancelled = false;
|
|
111
117
|
setStatus('compiling');
|
|
112
118
|
const timer = window.setTimeout(async () => {
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
119
|
+
let result: Awaited<ReturnType<Compiler['compile']>>;
|
|
120
|
+
let formatCompileErrors: (typeof import('../demos/client.ts'))['formatCompileErrors'];
|
|
121
|
+
try {
|
|
122
|
+
const client = await import('../demos/client.ts');
|
|
123
|
+
formatCompileErrors = client.formatCompileErrors;
|
|
124
|
+
if (!compilerRef.current) {
|
|
125
|
+
compilerRef.current = client.createCompiler(editor.compiler, editor.options);
|
|
126
|
+
}
|
|
127
|
+
result = await compilerRef.current.compile({ files: currentFiles(), entry: files[0].path });
|
|
128
|
+
} catch (error) {
|
|
129
|
+
// the next edit tries again, with a new compiler. (A chunk that failed
|
|
130
|
+
// to load stays failed in Next.js until the page is reloaded.)
|
|
131
|
+
compilerRef.current = null;
|
|
132
|
+
if (cancelled) return;
|
|
133
|
+
console.error('[docs-kit] the demo could not be rebuilt', error);
|
|
134
|
+
setFailure(error instanceof Error ? error.message : String(error));
|
|
135
|
+
setStatus('failed');
|
|
136
|
+
return;
|
|
116
137
|
}
|
|
117
|
-
const { formatCompileErrors } = await import('../demos/client.ts');
|
|
118
|
-
const result = await compilerRef.current.compile({ files: currentFiles(), entry: files[0].path });
|
|
119
138
|
if (cancelled) return;
|
|
139
|
+
setFailure(null);
|
|
120
140
|
if (result.ok) {
|
|
121
141
|
lastUpdate.current = { js: result.js, css: result.css };
|
|
122
142
|
iframeRef.current?.post({ type: 'demo-update', js: result.js, css: result.css });
|
|
@@ -144,6 +164,7 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
144
164
|
lastUpdate.current = null;
|
|
145
165
|
setStatus('idle');
|
|
146
166
|
setErrorCount(0);
|
|
167
|
+
setFailure(null);
|
|
147
168
|
iframeRef.current?.reload();
|
|
148
169
|
};
|
|
149
170
|
|
|
@@ -401,6 +422,9 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
401
422
|
<div className="dk-demo-body" style={editing ? { height: Math.max(previewHeight, 420) } : undefined}>
|
|
402
423
|
{demoUrl ? (
|
|
403
424
|
<div className="dk-demo-preview" style={{ display: previewVisible ? undefined : 'none' }}>
|
|
425
|
+
{editing && (status === 'compiling' || status === 'failed') ? (
|
|
426
|
+
<PreviewMask failure={status === 'failed' ? failure : null} />
|
|
427
|
+
) : null}
|
|
404
428
|
<DemoIframe
|
|
405
429
|
ref={iframeRef}
|
|
406
430
|
demoUrl={demoUrl}
|
|
@@ -460,6 +484,7 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
460
484
|
function CompileStatusLabel({ status, errorCount }: { status: CompileStatus; errorCount: number }) {
|
|
461
485
|
if (status === 'idle') return <span className="dk-demo-status">type to update the preview</span>;
|
|
462
486
|
if (status === 'compiling') return <span className="dk-demo-status">building…</span>;
|
|
487
|
+
if (status === 'failed') return <span className="dk-demo-status dk-demo-status--error">build failed</span>;
|
|
463
488
|
if (status === 'error') {
|
|
464
489
|
return (
|
|
465
490
|
<span className="dk-demo-status dk-demo-status--error">
|
|
@@ -470,6 +495,29 @@ function CompileStatusLabel({ status, errorCount }: { status: CompileStatus; err
|
|
|
470
495
|
return <span className="dk-demo-status dk-demo-status--ok">updated ✓</span>;
|
|
471
496
|
}
|
|
472
497
|
|
|
498
|
+
/**
|
|
499
|
+
* Over the preview while it is out of date: "building…" (after a short delay,
|
|
500
|
+
* so a quick rebuild doesn't flash), or why the build didn't run.
|
|
501
|
+
*/
|
|
502
|
+
function PreviewMask({ failure }: { failure: string | null }) {
|
|
503
|
+
return (
|
|
504
|
+
<div className={`dk-demo-mask${failure != null ? ' dk-demo-mask--failed' : ''}`} role="status">
|
|
505
|
+
{failure != null ? (
|
|
506
|
+
<div className="dk-demo-mask-message">
|
|
507
|
+
<strong>The preview could not be rebuilt.</strong>
|
|
508
|
+
<span>Reload the page to try again. Reloading discards your changes: fork keeps them.</span>
|
|
509
|
+
<code>{failure}</code>
|
|
510
|
+
<button type="button" className="dk-demo-mask-button" onClick={() => window.location.reload()}>
|
|
511
|
+
reload the page
|
|
512
|
+
</button>
|
|
513
|
+
</div>
|
|
514
|
+
) : (
|
|
515
|
+
<div className="dk-demo-mask-message">building…</div>
|
|
516
|
+
)}
|
|
517
|
+
</div>
|
|
518
|
+
);
|
|
519
|
+
}
|
|
520
|
+
|
|
473
521
|
/** CodeMirror, imported only when someone starts editing. */
|
|
474
522
|
function LazyEditor(props: { file: DemoShellFile; value: string; onChange: (value: string) => void }) {
|
|
475
523
|
const hostRef = useRef<HTMLDivElement | null>(null);
|
package/src/react/fork.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ForkConfig } from '../demos/config.ts';
|
|
2
|
-
import { forkForm, type ForkFile, type ForkFramework } from '../fork/index.ts';
|
|
2
|
+
import { forkForm, resolveForkSettings, type ForkFile, type ForkFramework } from '../fork/index.ts';
|
|
3
3
|
|
|
4
4
|
/** Posts the demo (with any edits) to its fork target (CodeSandbox, or StackBlitz for Vue) in a new tab. */
|
|
5
5
|
export function forkDemo(options: {
|
|
@@ -9,7 +9,7 @@ export function forkDemo(options: {
|
|
|
9
9
|
config?: ForkConfig;
|
|
10
10
|
framework?: ForkFramework;
|
|
11
11
|
}) {
|
|
12
|
-
const
|
|
12
|
+
const config = resolveForkSettings(options.config ?? {}, options.entry);
|
|
13
13
|
const form = forkForm(options.files, {
|
|
14
14
|
framework: options.framework,
|
|
15
15
|
title: options.title,
|
|
@@ -19,6 +19,7 @@ export function forkDemo(options: {
|
|
|
19
19
|
entryPrelude: config.entryPrelude,
|
|
20
20
|
styles: config.styles,
|
|
21
21
|
sourceReplacements: config.sourceReplacements,
|
|
22
|
+
indexHtmlHead: config.indexHtmlHead,
|
|
22
23
|
});
|
|
23
24
|
const el = document.createElement('form');
|
|
24
25
|
el.action = form.action;
|
package/src/react/styles.css
CHANGED
|
@@ -429,10 +429,79 @@
|
|
|
429
429
|
border-right: 1px solid var(--dk-border);
|
|
430
430
|
}
|
|
431
431
|
.dk-demo--editing .dk-demo-preview {
|
|
432
|
+
position: relative;
|
|
432
433
|
display: flex;
|
|
433
434
|
flex-direction: column;
|
|
434
435
|
min-height: 0;
|
|
435
436
|
}
|
|
437
|
+
/* over the preview while it is rebuilt, or when the build failed */
|
|
438
|
+
.dk-demo-mask {
|
|
439
|
+
position: absolute;
|
|
440
|
+
inset: 0;
|
|
441
|
+
z-index: 1;
|
|
442
|
+
display: flex;
|
|
443
|
+
align-items: center;
|
|
444
|
+
justify-content: center;
|
|
445
|
+
padding: 16px;
|
|
446
|
+
background: color-mix(in srgb, var(--dk-surface) 70%, transparent);
|
|
447
|
+
color: var(--dk-muted);
|
|
448
|
+
font-family: var(--dk-font-mono);
|
|
449
|
+
font-size: 12px;
|
|
450
|
+
opacity: 0;
|
|
451
|
+
animation: dk-demo-mask-in 150ms ease-out 400ms forwards;
|
|
452
|
+
}
|
|
453
|
+
.dk-demo-mask--failed {
|
|
454
|
+
animation-delay: 0ms;
|
|
455
|
+
background: color-mix(in srgb, var(--dk-surface) 88%, transparent);
|
|
456
|
+
}
|
|
457
|
+
.dk-demo-mask-message {
|
|
458
|
+
display: flex;
|
|
459
|
+
flex-direction: column;
|
|
460
|
+
align-items: center;
|
|
461
|
+
gap: 6px;
|
|
462
|
+
max-width: 440px;
|
|
463
|
+
padding: 4px 12px;
|
|
464
|
+
border: 1px solid var(--dk-border);
|
|
465
|
+
border-radius: 999px;
|
|
466
|
+
background: var(--dk-surface);
|
|
467
|
+
text-align: center;
|
|
468
|
+
}
|
|
469
|
+
.dk-demo-mask--failed .dk-demo-mask-message {
|
|
470
|
+
padding: 14px 16px;
|
|
471
|
+
border-radius: var(--dk-radius);
|
|
472
|
+
font-family: var(--dk-font-sans);
|
|
473
|
+
font-size: 13px;
|
|
474
|
+
line-height: 1.45;
|
|
475
|
+
color: var(--dk-fg);
|
|
476
|
+
}
|
|
477
|
+
.dk-demo-mask-message code {
|
|
478
|
+
line-height: 1.4;
|
|
479
|
+
}
|
|
480
|
+
.dk-demo-mask-button {
|
|
481
|
+
margin-top: 4px;
|
|
482
|
+
padding: 4px 10px;
|
|
483
|
+
border: 1px solid var(--dk-border);
|
|
484
|
+
border-radius: 999px;
|
|
485
|
+
background: transparent;
|
|
486
|
+
color: var(--dk-fg);
|
|
487
|
+
font: inherit;
|
|
488
|
+
font-size: 12px;
|
|
489
|
+
cursor: pointer;
|
|
490
|
+
}
|
|
491
|
+
.dk-demo-mask-button:hover {
|
|
492
|
+
background: var(--dk-accent-soft);
|
|
493
|
+
}
|
|
494
|
+
.dk-demo-mask-message code {
|
|
495
|
+
font-family: var(--dk-font-mono);
|
|
496
|
+
font-size: 11.5px;
|
|
497
|
+
color: var(--dk-error);
|
|
498
|
+
overflow-wrap: anywhere;
|
|
499
|
+
}
|
|
500
|
+
@keyframes dk-demo-mask-in {
|
|
501
|
+
to {
|
|
502
|
+
opacity: 1;
|
|
503
|
+
}
|
|
504
|
+
}
|
|
436
505
|
@container dk-demo (max-width: 820px) {
|
|
437
506
|
.dk-demo--editing .dk-demo-body {
|
|
438
507
|
grid-template-columns: minmax(0, 1fr);
|
|
@@ -5,7 +5,6 @@ import { visit } from 'unist-util-visit';
|
|
|
5
5
|
import { collectDemoFiles } from '../code/demoFiles.ts';
|
|
6
6
|
import { formatHighlightSpec } from '../code/highlightSpec.ts';
|
|
7
7
|
import { parseDemoHeight } from '../code/heights.ts';
|
|
8
|
-
import { formatLineRanges } from '../code/lineRanges.ts';
|
|
9
8
|
import { applySourceReplacements, extractCodeMarkers, sliceRegion, stripCodeMarkers } from '../code/regions.ts';
|
|
10
9
|
import { vueBlockLang } from '../code/vueBlocks.ts';
|
|
11
10
|
import { applyFenceDefaults, parseFenceMeta, type FenceDefaults, type FenceProps } from './meta.ts';
|
|
@@ -116,7 +115,8 @@ type MdxElement = {
|
|
|
116
115
|
* `// #highlight label` … `// #endhighlight`, or a trailing
|
|
117
116
|
* `code // #highlight label` (`{/* #highlight *\/}` in JSX children).
|
|
118
117
|
* `{1-3}` meta highlights are rejected.
|
|
119
|
-
* - `lines` adds a line-number gutter
|
|
118
|
+
* - `lines` adds a line-number gutter. A `region` is numbered from 1, like any
|
|
119
|
+
* other snippet: the reader never sees the file it was cut from.
|
|
120
120
|
* - `files=off` hides the file names and tabs of the files the entry imports.
|
|
121
121
|
* - `title="..."` renders a card with the title as the snippet name.
|
|
122
122
|
* - `height="small|default|large|auto|<px>"`; a live fence defaults to
|
|
@@ -265,10 +265,8 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
|
265
265
|
const marked = extractCodeMarkers(source, context, originalLines);
|
|
266
266
|
source = marked.source;
|
|
267
267
|
if (stripped !== source) copyCode = stripped;
|
|
268
|
-
if (originalLines) originalLines = marked.originalLines;
|
|
269
268
|
if (marked.highlight.lines.length) highlight = formatHighlightSpec(marked.highlight);
|
|
270
269
|
}
|
|
271
|
-
const originalLinesAttr = originalLines ? formatLineRanges(originalLines) || null : null;
|
|
272
270
|
|
|
273
271
|
if (props.live) {
|
|
274
272
|
if (props.live !== true && props.live !== 'off') {
|
|
@@ -316,7 +314,6 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
|
316
314
|
if (typeof props.height === 'string') attrs.height = props.height;
|
|
317
315
|
if (highlight) attrs.highlight = highlight;
|
|
318
316
|
if (props.lines) attrs.lines = 'true';
|
|
319
|
-
if (originalLinesAttr) attrs.originalLines = originalLinesAttr;
|
|
320
317
|
if (fallback) attrs.fallback = 'true';
|
|
321
318
|
return attrs;
|
|
322
319
|
};
|
|
@@ -350,7 +347,6 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
|
350
347
|
[
|
|
351
348
|
highlight ? `{${highlight}}` : null,
|
|
352
349
|
props.lines ? 'lines' : null,
|
|
353
|
-
originalLinesAttr ? `originalLines="${originalLinesAttr}"` : null,
|
|
354
350
|
typeof props.height === 'string' ? `height="${props.height}"` : null,
|
|
355
351
|
]
|
|
356
352
|
.filter(Boolean)
|