@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.
Files changed (50) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +23 -0
  3. package/dist/code/shiki.d.ts +4 -3
  4. package/dist/code/shiki.d.ts.map +1 -1
  5. package/dist/code/shiki.js +4 -3
  6. package/dist/code/shiki.js.map +1 -1
  7. package/dist/demos/config.d.ts +14 -0
  8. package/dist/demos/config.d.ts.map +1 -1
  9. package/dist/demos/config.js.map +1 -1
  10. package/dist/demos/vendor.d.ts +5 -1
  11. package/dist/demos/vendor.d.ts.map +1 -1
  12. package/dist/demos/vendor.js +6 -2
  13. package/dist/demos/vendor.js.map +1 -1
  14. package/dist/fork/codesandbox.d.ts +4 -0
  15. package/dist/fork/codesandbox.d.ts.map +1 -1
  16. package/dist/fork/codesandbox.js +5 -3
  17. package/dist/fork/codesandbox.js.map +1 -1
  18. package/dist/fork/index.d.ts +12 -0
  19. package/dist/fork/index.d.ts.map +1 -1
  20. package/dist/fork/index.js +19 -0
  21. package/dist/fork/index.js.map +1 -1
  22. package/dist/fork/stackblitz.d.ts.map +1 -1
  23. package/dist/fork/stackblitz.js +4 -4
  24. package/dist/fork/stackblitz.js.map +1 -1
  25. package/dist/react/Demo.d.ts.map +1 -1
  26. package/dist/react/Demo.js +2 -1
  27. package/dist/react/Demo.js.map +1 -1
  28. package/dist/react/DemoShell.d.ts.map +1 -1
  29. package/dist/react/DemoShell.js +33 -6
  30. package/dist/react/DemoShell.js.map +1 -1
  31. package/dist/react/fork.d.ts.map +1 -1
  32. package/dist/react/fork.js +3 -2
  33. package/dist/react/fork.js.map +1 -1
  34. package/dist/react/styles.css +69 -0
  35. package/dist/remark/remarkDemoFences.d.ts +2 -1
  36. package/dist/remark/remarkDemoFences.d.ts.map +1 -1
  37. package/dist/remark/remarkDemoFences.js +2 -8
  38. package/dist/remark/remarkDemoFences.js.map +1 -1
  39. package/package.json +1 -1
  40. package/src/code/shiki.ts +4 -3
  41. package/src/demos/config.ts +15 -0
  42. package/src/demos/vendor.ts +6 -2
  43. package/src/fork/codesandbox.ts +8 -3
  44. package/src/fork/index.ts +31 -0
  45. package/src/fork/stackblitz.ts +4 -3
  46. package/src/react/Demo.tsx +2 -1
  47. package/src/react/DemoShell.tsx +54 -6
  48. package/src/react/fork.ts +3 -2
  49. package/src/react/styles.css +69 -0
  50. package/src/remark/remarkDemoFences.ts +2 -6
@@ -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
- lineNumbers: showLines ? (sliced ? marked.originalLines : true) : null,
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 {
@@ -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
- type CompileStatus = 'idle' | 'compiling' | 'ok' | 'error';
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
- if (!compilerRef.current) {
114
- const { createCompiler } = await import('../demos/client.ts');
115
- compilerRef.current = createCompiler(editor.compiler, editor.options);
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 { config = {} } = options;
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;
@@ -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 (original line numbers with `region`).
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)