@thedatagrid/docs-kit 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.md +75 -1
- package/dist/demos/build.d.ts.map +1 -1
- package/dist/demos/build.js +1 -0
- package/dist/demos/build.js.map +1 -1
- package/dist/demos/config.d.ts +7 -0
- package/dist/demos/config.d.ts.map +1 -1
- package/dist/demos/config.js.map +1 -1
- package/dist/demos/pages.d.ts +2 -0
- package/dist/demos/pages.d.ts.map +1 -1
- package/dist/demos/pages.js +6 -2
- package/dist/demos/pages.js.map +1 -1
- package/dist/react/DemoShell.js +21 -5
- package/dist/react/DemoShell.js.map +1 -1
- package/dist/react/styles.css +8 -0
- package/dist/remark/index.d.ts +1 -1
- package/dist/remark/index.d.ts.map +1 -1
- package/dist/remark/index.js +1 -1
- package/dist/remark/index.js.map +1 -1
- package/dist/remark/meta.d.ts +13 -0
- package/dist/remark/meta.d.ts.map +1 -1
- package/dist/remark/meta.js +13 -0
- package/dist/remark/meta.js.map +1 -1
- package/dist/remark/remarkDemoFences.d.ts +10 -2
- package/dist/remark/remarkDemoFences.d.ts.map +1 -1
- package/dist/remark/remarkDemoFences.js +6 -4
- package/dist/remark/remarkDemoFences.js.map +1 -1
- package/dist/showcase/AutomatedDemo.d.ts +46 -0
- package/dist/showcase/AutomatedDemo.d.ts.map +1 -0
- package/dist/showcase/AutomatedDemo.js +169 -0
- package/dist/showcase/AutomatedDemo.js.map +1 -0
- package/dist/showcase/LazyShowcase.d.ts +31 -0
- package/dist/showcase/LazyShowcase.d.ts.map +1 -0
- package/dist/showcase/LazyShowcase.js +51 -0
- package/dist/showcase/LazyShowcase.js.map +1 -0
- package/dist/showcase/hooks.d.ts +19 -0
- package/dist/showcase/hooks.d.ts.map +1 -0
- package/dist/showcase/hooks.js +63 -0
- package/dist/showcase/hooks.js.map +1 -0
- package/dist/showcase/index.d.ts +17 -0
- package/dist/showcase/index.d.ts.map +1 -0
- package/dist/showcase/index.js +15 -0
- package/dist/showcase/index.js.map +1 -0
- package/dist/showcase/scripted.d.ts +100 -0
- package/dist/showcase/scripted.d.ts.map +1 -0
- package/dist/showcase/scripted.js +381 -0
- package/dist/showcase/scripted.js.map +1 -0
- package/dist/showcase/styles.css +174 -0
- package/package.json +7 -2
- package/src/demos/build.ts +1 -0
- package/src/demos/config.ts +7 -0
- package/src/demos/pages.ts +6 -2
- package/src/react/DemoShell.tsx +64 -8
- package/src/react/styles.css +8 -0
- package/src/remark/index.ts +1 -1
- package/src/remark/meta.ts +26 -0
- package/src/remark/remarkDemoFences.ts +15 -4
- package/src/showcase/AutomatedDemo.tsx +266 -0
- package/src/showcase/LazyShowcase.tsx +111 -0
- package/src/showcase/hooks.ts +84 -0
- package/src/showcase/index.ts +23 -0
- package/src/showcase/scripted.ts +533 -0
- package/src/showcase/styles.css +174 -0
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thedatagrid/docs-kit",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Docs tooling: type-checked file snippets with regions and highlights, prebuilt and editable live demos, CodeSandbox forks",
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Docs tooling: type-checked file snippets with regions and highlights, prebuilt and editable live demos, CodeSandbox forks, scripted showcase demos",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "TheDataGrid",
|
|
@@ -40,6 +40,11 @@
|
|
|
40
40
|
"types": "./dist/fork/index.d.ts",
|
|
41
41
|
"default": "./dist/fork/index.js"
|
|
42
42
|
},
|
|
43
|
+
"./showcase": {
|
|
44
|
+
"types": "./dist/showcase/index.d.ts",
|
|
45
|
+
"default": "./dist/showcase/index.js"
|
|
46
|
+
},
|
|
47
|
+
"./showcase/styles.css": "./dist/showcase/styles.css",
|
|
43
48
|
"./package.json": "./package.json"
|
|
44
49
|
},
|
|
45
50
|
"typesVersions": {
|
package/src/demos/build.ts
CHANGED
|
@@ -96,6 +96,7 @@ function resolveSettings(options: BuildDemosOptions) {
|
|
|
96
96
|
pageExtension: config.pageExtension ?? '.page.md',
|
|
97
97
|
routeForPage: config.routeForPage ?? defaultRouteForPage,
|
|
98
98
|
anchorPrefix: config.anchorPrefix ?? '',
|
|
99
|
+
fenceDefaults: config.fenceDefaults,
|
|
99
100
|
framework: config.framework ?? 'react',
|
|
100
101
|
libraries,
|
|
101
102
|
stubImports,
|
package/src/demos/config.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Plugin } from 'esbuild';
|
|
2
2
|
|
|
3
3
|
import type { CompilerConfig } from './client.ts';
|
|
4
|
+
import type { FenceDefaults } from '../remark/meta.ts';
|
|
4
5
|
import type { CompileOptions } from './compile/core.ts';
|
|
5
6
|
|
|
6
7
|
/** A package the demos import that is built from source instead of `node_modules`. */
|
|
@@ -40,6 +41,12 @@ export type DocsKitConfig = {
|
|
|
40
41
|
pageExtension?: string;
|
|
41
42
|
/** Prefix of the docs card anchors (the `<Demo>` context's `anchorPrefix`). Default `''`. */
|
|
42
43
|
anchorPrefix?: string;
|
|
44
|
+
/**
|
|
45
|
+
* The site's fence defaults, the same object passed to `remarkDemoFences`
|
|
46
|
+
* (e.g. `{ demos: { live: true } }` makes every demo fence live), so the
|
|
47
|
+
* "see in docs" links find the live demos.
|
|
48
|
+
*/
|
|
49
|
+
fenceDefaults?: FenceDefaults;
|
|
43
50
|
/** Content-relative page path (without extension) → route. Default: `/<path>`, `index` dropped. */
|
|
44
51
|
routeForPage?: (pagePath: string) => string;
|
|
45
52
|
/** Only `react` for now. */
|
package/src/demos/pages.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import fs from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
|
|
4
|
+
import { applyFenceDefaults, parseFenceMeta, type FenceDefaults } from '../remark/meta.ts';
|
|
4
5
|
import { slugifyDemoTitle } from './slug.ts';
|
|
5
6
|
|
|
6
7
|
function walk(dir: string, accept: (file: string) => boolean, out: string[] = []): string[] {
|
|
@@ -57,8 +58,9 @@ export function findDocsLinks(options: {
|
|
|
57
58
|
demoSuffix: string;
|
|
58
59
|
routeForPage: (pagePath: string) => string;
|
|
59
60
|
anchorPrefix?: string;
|
|
61
|
+
fenceDefaults?: FenceDefaults;
|
|
60
62
|
}): Map<string, string> {
|
|
61
|
-
const { contentDir, pageExtension, demoSuffix, routeForPage, anchorPrefix = '' } = options;
|
|
63
|
+
const { contentDir, pageExtension, demoSuffix, routeForPage, anchorPrefix = '', fenceDefaults } = options;
|
|
62
64
|
const links = new Map<string, string>();
|
|
63
65
|
const fenceRe = /^```[^\n]*$/gm;
|
|
64
66
|
|
|
@@ -71,7 +73,9 @@ export function findDocsLinks(options: {
|
|
|
71
73
|
const info = match[0];
|
|
72
74
|
const file = /\bfile=(?:"([^"]+)"|'([^']+)')/.exec(info);
|
|
73
75
|
const fileName = file?.[1] ?? file?.[2];
|
|
74
|
-
if (!fileName || !fileName.endsWith(demoSuffix)
|
|
76
|
+
if (!fileName || !fileName.endsWith(demoSuffix)) continue;
|
|
77
|
+
const meta = info.replace(/^```\S*\s*/, '');
|
|
78
|
+
if (!applyFenceDefaults(parseFenceMeta(meta), fenceDefaults, true).live) continue;
|
|
75
79
|
const absPath = fileName.startsWith('/') ? path.join(contentDir, fileName) : path.resolve(pageDir, fileName);
|
|
76
80
|
const demoId = toPosix(path.relative(contentDir, absPath)).slice(0, -demoSuffix.length);
|
|
77
81
|
if (links.has(demoId)) continue;
|
package/src/react/DemoShell.tsx
CHANGED
|
@@ -339,11 +339,11 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
339
339
|
<CompileStatusLabel status={status} errorCount={errorCount} />
|
|
340
340
|
{dirty ? (
|
|
341
341
|
<ToolbarButton title="Discard your changes and restore the original demo" onClick={resetEdits}>
|
|
342
|
-
reset
|
|
342
|
+
reset<ResetIcon />
|
|
343
343
|
</ToolbarButton>
|
|
344
344
|
) : null}
|
|
345
345
|
<ToolbarButton title={`Fork “${title}” in CodeSandbox (with your changes)`} onClick={fork}>
|
|
346
|
-
fork
|
|
346
|
+
fork<ForkIcon />
|
|
347
347
|
</ToolbarButton>
|
|
348
348
|
<ToolbarButton title="Stop editing (your changes stay until you reset or leave the page)" onClick={() => setEditing(false)}>
|
|
349
349
|
done
|
|
@@ -362,7 +362,7 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
362
362
|
</ToolbarButton>
|
|
363
363
|
{editor && demoUrl ? (
|
|
364
364
|
<ToolbarButton title="Edit the code and see the preview update" onClick={startEditing}>
|
|
365
|
-
edit
|
|
365
|
+
edit<EditIcon />
|
|
366
366
|
</ToolbarButton>
|
|
367
367
|
) : null}
|
|
368
368
|
</>
|
|
@@ -370,17 +370,17 @@ export function DemoShell(props: DemoShellProps) {
|
|
|
370
370
|
<>
|
|
371
371
|
{editor ? (
|
|
372
372
|
<ToolbarButton title="Edit the code and see the preview update" onClick={startEditing}>
|
|
373
|
-
edit
|
|
373
|
+
edit<EditIcon />
|
|
374
374
|
</ToolbarButton>
|
|
375
375
|
) : null}
|
|
376
376
|
<ToolbarButton
|
|
377
377
|
title={dirty ? 'Discard your changes and restore the original demo' : 'Reset the demo to its initial state'}
|
|
378
378
|
onClick={dirty ? resetEdits : () => iframeRef.current?.reset()}
|
|
379
379
|
>
|
|
380
|
-
reset
|
|
380
|
+
reset<ResetIcon />
|
|
381
381
|
</ToolbarButton>
|
|
382
382
|
<ToolbarButton title={`Fork “${title}” in CodeSandbox`} onClick={fork}>
|
|
383
|
-
fork
|
|
383
|
+
fork<ForkIcon />
|
|
384
384
|
</ToolbarButton>
|
|
385
385
|
<OpenDemoLink demoUrl={demoUrl!} title={title} />
|
|
386
386
|
<IconButton title="Full screen" onClick={openOverlay}>
|
|
@@ -518,6 +518,62 @@ function IconButton(props: { title: string; onClick: () => void; children: React
|
|
|
518
518
|
);
|
|
519
519
|
}
|
|
520
520
|
|
|
521
|
+
/** Toolbar icons: sized by CSS (`--dk-action-icon-size`), drawn in the text color. */
|
|
522
|
+
function ActionIcon({ children }: { children: ReactNode }) {
|
|
523
|
+
return (
|
|
524
|
+
<svg
|
|
525
|
+
className="dk-demo-action-icon"
|
|
526
|
+
viewBox="0 0 24 24"
|
|
527
|
+
fill="none"
|
|
528
|
+
stroke="currentColor"
|
|
529
|
+
strokeWidth="2"
|
|
530
|
+
strokeLinecap="round"
|
|
531
|
+
strokeLinejoin="round"
|
|
532
|
+
aria-hidden="true"
|
|
533
|
+
>
|
|
534
|
+
{children}
|
|
535
|
+
</svg>
|
|
536
|
+
);
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
function EditIcon() {
|
|
540
|
+
return (
|
|
541
|
+
<ActionIcon>
|
|
542
|
+
<path d="M12 20h9" />
|
|
543
|
+
<path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z" />
|
|
544
|
+
</ActionIcon>
|
|
545
|
+
);
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
function ResetIcon() {
|
|
549
|
+
return (
|
|
550
|
+
<ActionIcon>
|
|
551
|
+
<path d="M3 12a9 9 0 1 0 3-6.7L3 8" />
|
|
552
|
+
<path d="M3 3v5h5" />
|
|
553
|
+
</ActionIcon>
|
|
554
|
+
);
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
function ForkIcon() {
|
|
558
|
+
return (
|
|
559
|
+
<ActionIcon>
|
|
560
|
+
<circle cx="6" cy="5" r="2" />
|
|
561
|
+
<circle cx="18" cy="5" r="2" />
|
|
562
|
+
<circle cx="12" cy="19" r="2" />
|
|
563
|
+
<path d="M6 7v1a4 4 0 0 0 4 4h4a4 4 0 0 0 4-4V7M12 12v5" />
|
|
564
|
+
</ActionIcon>
|
|
565
|
+
);
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
function OpenIcon() {
|
|
569
|
+
return (
|
|
570
|
+
<ActionIcon>
|
|
571
|
+
<path d="M14 4h6v6M20 4l-9 9" />
|
|
572
|
+
<path d="M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5" />
|
|
573
|
+
</ActionIcon>
|
|
574
|
+
);
|
|
575
|
+
}
|
|
576
|
+
|
|
521
577
|
function ExpandIcon() {
|
|
522
578
|
return (
|
|
523
579
|
<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
|
|
@@ -548,7 +604,7 @@ function DemoOverlay(props: { title: string; demoUrl: string; onClose: () => voi
|
|
|
548
604
|
<span className="dk-demo-overlay-title">{props.title}</span>
|
|
549
605
|
<span className="dk-demo-spacer" />
|
|
550
606
|
<ToolbarButton title="Reset the demo to its initial state" onClick={() => iframeRef.current?.reset()}>
|
|
551
|
-
reset
|
|
607
|
+
reset<ResetIcon />
|
|
552
608
|
</ToolbarButton>
|
|
553
609
|
<IconButton title="Close" onClick={props.onClose}>
|
|
554
610
|
<CloseIcon />
|
|
@@ -586,7 +642,7 @@ function OpenDemoLink({ demoUrl, title }: { demoUrl: string; title: string }) {
|
|
|
586
642
|
}}
|
|
587
643
|
className="dk-demo-action"
|
|
588
644
|
>
|
|
589
|
-
open
|
|
645
|
+
open<OpenIcon />
|
|
590
646
|
</a>
|
|
591
647
|
);
|
|
592
648
|
}
|
package/src/react/styles.css
CHANGED
|
@@ -197,10 +197,18 @@
|
|
|
197
197
|
font-weight: 500;
|
|
198
198
|
}
|
|
199
199
|
.dk-demo-action {
|
|
200
|
+
display: inline-flex;
|
|
201
|
+
align-items: center;
|
|
202
|
+
gap: 5px;
|
|
200
203
|
padding: 4px 8px;
|
|
201
204
|
font-family: var(--dk-font-mono);
|
|
202
205
|
font-size: 12.5px;
|
|
203
206
|
}
|
|
207
|
+
.dk-demo-action-icon {
|
|
208
|
+
flex: none;
|
|
209
|
+
width: var(--dk-action-icon-size, 14px);
|
|
210
|
+
height: var(--dk-action-icon-size, 14px);
|
|
211
|
+
}
|
|
204
212
|
.dk-demo-icon {
|
|
205
213
|
display: inline-flex;
|
|
206
214
|
align-items: center;
|
package/src/remark/index.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
export { remarkDemoFences, type FenceInfo, type RemarkDemoFencesOptions } from './remarkDemoFences.ts';
|
|
2
|
-
export { parseFenceMeta, type FenceProps } from './meta.ts';
|
|
2
|
+
export { applyFenceDefaults, parseFenceMeta, type FenceDefaults, type FenceProps } from './meta.ts';
|
package/src/remark/meta.ts
CHANGED
|
@@ -18,3 +18,29 @@ export function parseFenceMeta(meta: string): FenceProps {
|
|
|
18
18
|
}
|
|
19
19
|
return props;
|
|
20
20
|
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Site-wide fence props, under each fence's own meta. Values are written as in
|
|
24
|
+
* the meta (`true` for a bare flag, strings otherwise); `false` leaves a prop
|
|
25
|
+
* unset. A fence turns a default off with `<prop>=false` (or `lines=off`).
|
|
26
|
+
*/
|
|
27
|
+
export type FenceDefaults = {
|
|
28
|
+
/** Every docs-kit fence, e.g. `{ lines: true }`. */
|
|
29
|
+
all?: Record<string, string | boolean>;
|
|
30
|
+
/** Fences of demo entries (`*.demo.tsx`), e.g. `{ live: true, height: 'default' }`. */
|
|
31
|
+
demos?: Record<string, string | boolean>;
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
/** Flags that `=false` / `=off` switch off. (`live=off` stays "live, code tab first".) */
|
|
35
|
+
const OFF_VALUES: Record<string, string[]> = { lines: ['false', 'off'], live: ['false'] };
|
|
36
|
+
|
|
37
|
+
/** The fence's props over the defaults, with switched-off flags removed. */
|
|
38
|
+
export function applyFenceDefaults(props: FenceProps, defaults: FenceDefaults | undefined, isDemo: boolean): FenceProps {
|
|
39
|
+
const merged: Record<string, string | boolean> = { ...defaults?.all, ...(isDemo ? defaults?.demos : undefined), ...props };
|
|
40
|
+
const result: FenceProps = {};
|
|
41
|
+
for (const [name, value] of Object.entries(merged)) {
|
|
42
|
+
if (value === false || (typeof value === 'string' && OFF_VALUES[name]?.includes(value))) continue;
|
|
43
|
+
result[name] = value;
|
|
44
|
+
}
|
|
45
|
+
return result;
|
|
46
|
+
}
|
|
@@ -7,7 +7,7 @@ import { formatHighlightSpec } from '../code/highlightSpec.ts';
|
|
|
7
7
|
import { parseDemoHeight } from '../code/heights.ts';
|
|
8
8
|
import { formatLineRanges } from '../code/lineRanges.ts';
|
|
9
9
|
import { applySourceReplacements, extractCodeMarkers, sliceRegion, stripCodeMarkers } from '../code/regions.ts';
|
|
10
|
-
import { parseFenceMeta, type FenceProps } from './meta.ts';
|
|
10
|
+
import { applyFenceDefaults, parseFenceMeta, type FenceDefaults, type FenceProps } from './meta.ts';
|
|
11
11
|
|
|
12
12
|
export type FenceInfo = {
|
|
13
13
|
lang: string | null;
|
|
@@ -52,7 +52,15 @@ export type RemarkDemoFencesOptions = {
|
|
|
52
52
|
componentName?: string;
|
|
53
53
|
/** Literal replacements applied to inlined source (see `applySourceReplacements`). */
|
|
54
54
|
sourceReplacements?: Record<string, string>;
|
|
55
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* Site-wide fence props, so pages don't repeat them: `all` applies to every
|
|
57
|
+
* claimed fence, `demos` to fences of demo entries. E.g.
|
|
58
|
+
* `{ all: { lines: true }, demos: { live: true, height: 'default' } }`.
|
|
59
|
+
* A fence's own meta wins; `lines=false` / `live=false` turn a default off.
|
|
60
|
+
* Pass the same object to the demo builder (`DocsKitConfig.fenceDefaults`).
|
|
61
|
+
*/
|
|
62
|
+
fenceDefaults?: FenceDefaults;
|
|
63
|
+
/** `height` of a live fence that sets none (and no `fenceDefaults.demos.height`). Default `auto`. */
|
|
56
64
|
liveHeight?: string;
|
|
57
65
|
};
|
|
58
66
|
|
|
@@ -116,6 +124,7 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
|
116
124
|
demoSuffixes = ['.demo.tsx'],
|
|
117
125
|
componentName = 'Demo',
|
|
118
126
|
sourceReplacements,
|
|
127
|
+
fenceDefaults,
|
|
119
128
|
liveHeight = 'auto',
|
|
120
129
|
} = options;
|
|
121
130
|
const folder = options.folder.replace(/^\/+|\/+$/g, '');
|
|
@@ -134,8 +143,10 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
|
134
143
|
|
|
135
144
|
const inDemo = parent.type === 'mdxJsxFlowElement' && parent.name === componentName;
|
|
136
145
|
const meta: string = node.meta || '';
|
|
137
|
-
const
|
|
138
|
-
if (!inDemo && claim && !claim({ lang: node.lang ?? null, meta, props, inDemo })) return;
|
|
146
|
+
const ownProps = parseFenceMeta(meta);
|
|
147
|
+
if (!inDemo && claim && !claim({ lang: node.lang ?? null, meta, props: ownProps, inDemo })) return;
|
|
148
|
+
const isDemoFile = typeof ownProps.file === 'string' && demoSuffixes.some((s) => (ownProps.file as string).endsWith(s));
|
|
149
|
+
const props = applyFenceDefaults(ownProps, fenceDefaults, isDemoFile);
|
|
139
150
|
|
|
140
151
|
const context = `\`\`\`${node.lang ?? ''} ${meta} in "${path.join(path.basename(contentDir), folder)}"`;
|
|
141
152
|
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
useCallback,
|
|
5
|
+
useEffect,
|
|
6
|
+
useRef,
|
|
7
|
+
useState,
|
|
8
|
+
type CSSProperties,
|
|
9
|
+
type ReactNode,
|
|
10
|
+
} from 'react';
|
|
11
|
+
|
|
12
|
+
import { canRunScriptedShow } from './hooks.ts';
|
|
13
|
+
import {
|
|
14
|
+
createScriptedCursor,
|
|
15
|
+
ScriptCancelled,
|
|
16
|
+
sleep,
|
|
17
|
+
waitFor,
|
|
18
|
+
type ScriptedCursor,
|
|
19
|
+
} from './scripted.ts';
|
|
20
|
+
|
|
21
|
+
export type AutomatedDemoStatus =
|
|
22
|
+
/** Not animating: offscreen, before ready, or unsupported device. */
|
|
23
|
+
| 'idle'
|
|
24
|
+
/** The show is running (fake cursor visible). */
|
|
25
|
+
| 'running'
|
|
26
|
+
/** The user interacted — the demo is theirs until they hit replay. */
|
|
27
|
+
| 'user';
|
|
28
|
+
|
|
29
|
+
export type ShowcaseScriptContext = {
|
|
30
|
+
/** Wrapper element containing the live demo (and its in-demo portals). */
|
|
31
|
+
root: HTMLElement;
|
|
32
|
+
cursor: ScriptedCursor;
|
|
33
|
+
signal: AbortSignal;
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
export type AutomatedDemoProps = {
|
|
37
|
+
children: ReactNode;
|
|
38
|
+
/** The product demo is mounted and can be driven. */
|
|
39
|
+
ready: boolean;
|
|
40
|
+
/** One full pass of the show. Must honour `signal` (use the toolkit helpers). */
|
|
41
|
+
run: (context: ShowcaseScriptContext) => Promise<void>;
|
|
42
|
+
/** Put the demo back to its initial state; called before every pass. */
|
|
43
|
+
reset?: (context: ShowcaseScriptContext) => void | Promise<void>;
|
|
44
|
+
/** Wait for this selector inside the root before the first pass. */
|
|
45
|
+
waitForSelector?: string;
|
|
46
|
+
/** Pause between passes, in ms. */
|
|
47
|
+
loopPause?: number;
|
|
48
|
+
/** No show below this viewport width (and never on touch / reduced motion). */
|
|
49
|
+
minViewportWidth?: number;
|
|
50
|
+
/** IntersectionObserver threshold for "in view". */
|
|
51
|
+
threshold?: number;
|
|
52
|
+
runningLabel?: ReactNode;
|
|
53
|
+
userLabel?: ReactNode;
|
|
54
|
+
className?: string;
|
|
55
|
+
style?: CSSProperties;
|
|
56
|
+
onStatusChange?: (status: AutomatedDemoStatus) => void;
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Wraps a live demo in an automated show: a scripted cursor drives the LIVE
|
|
61
|
+
* component while it's in view, and the first real interaction (click /
|
|
62
|
+
* wheel / touch / key) hands control to the user instantly, leaving the demo
|
|
63
|
+
* where the script left it. A broken script ends quietly — it must never
|
|
64
|
+
* break the page.
|
|
65
|
+
*/
|
|
66
|
+
export function AutomatedDemo({
|
|
67
|
+
children,
|
|
68
|
+
ready,
|
|
69
|
+
run,
|
|
70
|
+
reset,
|
|
71
|
+
waitForSelector,
|
|
72
|
+
loopPause = 2600,
|
|
73
|
+
minViewportWidth = 768,
|
|
74
|
+
threshold = 0.35,
|
|
75
|
+
runningLabel = 'live demo — click anywhere to take over',
|
|
76
|
+
userLabel = 'you’re in control — replay demo ↻',
|
|
77
|
+
className,
|
|
78
|
+
style,
|
|
79
|
+
onStatusChange,
|
|
80
|
+
}: AutomatedDemoProps) {
|
|
81
|
+
const wrapperRef = useRef<HTMLDivElement | null>(null);
|
|
82
|
+
const overlayRef = useRef<HTMLDivElement | null>(null);
|
|
83
|
+
const cursorRef = useRef<ScriptedCursor | null>(null);
|
|
84
|
+
const abortRef = useRef<AbortController | null>(null);
|
|
85
|
+
const intersectingRef = useRef(false);
|
|
86
|
+
const readyRef = useRef(ready);
|
|
87
|
+
const statusRef = useRef<AutomatedDemoStatus>('idle');
|
|
88
|
+
const [status, setStatusState] = useState<AutomatedDemoStatus>('idle');
|
|
89
|
+
|
|
90
|
+
// latest callbacks without restarting the observers
|
|
91
|
+
const runRef = useRef(run);
|
|
92
|
+
const resetRef = useRef(reset);
|
|
93
|
+
const onStatusChangeRef = useRef(onStatusChange);
|
|
94
|
+
runRef.current = run;
|
|
95
|
+
resetRef.current = reset;
|
|
96
|
+
onStatusChangeRef.current = onStatusChange;
|
|
97
|
+
|
|
98
|
+
const setStatus = useCallback((next: AutomatedDemoStatus) => {
|
|
99
|
+
statusRef.current = next;
|
|
100
|
+
setStatusState(next);
|
|
101
|
+
onStatusChangeRef.current?.(next);
|
|
102
|
+
}, []);
|
|
103
|
+
|
|
104
|
+
const stop = useCallback(
|
|
105
|
+
(next: AutomatedDemoStatus) => {
|
|
106
|
+
abortRef.current?.abort();
|
|
107
|
+
abortRef.current = null;
|
|
108
|
+
cursorRef.current?.hide();
|
|
109
|
+
setStatus(next);
|
|
110
|
+
},
|
|
111
|
+
[setStatus],
|
|
112
|
+
);
|
|
113
|
+
|
|
114
|
+
const tryStart = useCallback(() => {
|
|
115
|
+
if (statusRef.current !== 'idle') return;
|
|
116
|
+
if (!intersectingRef.current || !readyRef.current) return;
|
|
117
|
+
if (document.visibilityState === 'hidden') return;
|
|
118
|
+
const root = wrapperRef.current;
|
|
119
|
+
const overlay = overlayRef.current;
|
|
120
|
+
if (!root || !overlay) return;
|
|
121
|
+
// the show is pointless (and annoying) on touch / small / reduced-motion
|
|
122
|
+
if (!canRunScriptedShow(minViewportWidth)) return;
|
|
123
|
+
|
|
124
|
+
if (!cursorRef.current) cursorRef.current = createScriptedCursor(overlay);
|
|
125
|
+
const cursor = cursorRef.current;
|
|
126
|
+
const controller = new AbortController();
|
|
127
|
+
abortRef.current = controller;
|
|
128
|
+
setStatus('running');
|
|
129
|
+
|
|
130
|
+
void (async () => {
|
|
131
|
+
const { signal } = controller;
|
|
132
|
+
const context: ShowcaseScriptContext = { root, cursor, signal };
|
|
133
|
+
try {
|
|
134
|
+
if (waitForSelector) {
|
|
135
|
+
const found = await waitFor(
|
|
136
|
+
() => root.querySelector(waitForSelector),
|
|
137
|
+
signal,
|
|
138
|
+
{
|
|
139
|
+
timeout: 20000,
|
|
140
|
+
},
|
|
141
|
+
);
|
|
142
|
+
if (!found) throw new ScriptCancelled();
|
|
143
|
+
}
|
|
144
|
+
for (;;) {
|
|
145
|
+
await resetRef.current?.(context);
|
|
146
|
+
await sleep(700, signal);
|
|
147
|
+
await runRef.current(context);
|
|
148
|
+
cursor.hide();
|
|
149
|
+
await sleep(loopPause, signal);
|
|
150
|
+
}
|
|
151
|
+
} catch (error) {
|
|
152
|
+
cursor.hide();
|
|
153
|
+
if (!(error instanceof ScriptCancelled)) {
|
|
154
|
+
// a broken show must never break the page — just end it quietly
|
|
155
|
+
console.warn('[automated-demo]', error);
|
|
156
|
+
if (statusRef.current === 'running') stop('user');
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
})();
|
|
160
|
+
}, [loopPause, minViewportWidth, setStatus, stop, waitForSelector]);
|
|
161
|
+
|
|
162
|
+
useEffect(() => {
|
|
163
|
+
readyRef.current = ready;
|
|
164
|
+
if (ready) tryStart();
|
|
165
|
+
else if (statusRef.current === 'running') stop('idle');
|
|
166
|
+
}, [ready, tryStart, stop]);
|
|
167
|
+
|
|
168
|
+
// start/pause with viewport visibility
|
|
169
|
+
useEffect(() => {
|
|
170
|
+
const root = wrapperRef.current;
|
|
171
|
+
if (!root) return;
|
|
172
|
+
const observer = new IntersectionObserver(
|
|
173
|
+
(entries) => {
|
|
174
|
+
const isIntersecting = entries.some((entry) => entry.isIntersecting);
|
|
175
|
+
intersectingRef.current = isIntersecting;
|
|
176
|
+
if (isIntersecting) tryStart();
|
|
177
|
+
else if (statusRef.current === 'running') stop('idle');
|
|
178
|
+
},
|
|
179
|
+
{ threshold },
|
|
180
|
+
);
|
|
181
|
+
observer.observe(root);
|
|
182
|
+
return () => observer.disconnect();
|
|
183
|
+
}, [threshold, tryStart, stop]);
|
|
184
|
+
|
|
185
|
+
// a hidden tab is as good as off-screen
|
|
186
|
+
useEffect(() => {
|
|
187
|
+
const onVisibility = () => {
|
|
188
|
+
if (document.visibilityState === 'hidden') {
|
|
189
|
+
if (statusRef.current === 'running') stop('idle');
|
|
190
|
+
} else {
|
|
191
|
+
tryStart();
|
|
192
|
+
}
|
|
193
|
+
};
|
|
194
|
+
document.addEventListener('visibilitychange', onVisibility);
|
|
195
|
+
return () => document.removeEventListener('visibilitychange', onVisibility);
|
|
196
|
+
}, [tryStart, stop]);
|
|
197
|
+
|
|
198
|
+
// first REAL interaction anywhere on the demo = takeover. The script's own
|
|
199
|
+
// dispatched events are untrusted, which is how we tell them apart.
|
|
200
|
+
useEffect(() => {
|
|
201
|
+
const root = wrapperRef.current;
|
|
202
|
+
if (!root) return;
|
|
203
|
+
const onInteract = (event: Event) => {
|
|
204
|
+
if (!event.isTrusted) return;
|
|
205
|
+
if (statusRef.current === 'running') stop('user');
|
|
206
|
+
// touched before the show got going: don't start it under the user
|
|
207
|
+
else if (
|
|
208
|
+
statusRef.current === 'idle' &&
|
|
209
|
+
canRunScriptedShow(minViewportWidth)
|
|
210
|
+
) {
|
|
211
|
+
stop('user');
|
|
212
|
+
}
|
|
213
|
+
};
|
|
214
|
+
const events = ['pointerdown', 'wheel', 'touchstart', 'keydown'] as const;
|
|
215
|
+
for (const type of events) {
|
|
216
|
+
root.addEventListener(type, onInteract, { capture: true, passive: true });
|
|
217
|
+
}
|
|
218
|
+
return () => {
|
|
219
|
+
for (const type of events)
|
|
220
|
+
root.removeEventListener(type, onInteract, { capture: true });
|
|
221
|
+
};
|
|
222
|
+
}, [stop, minViewportWidth]);
|
|
223
|
+
|
|
224
|
+
useEffect(() => {
|
|
225
|
+
return () => {
|
|
226
|
+
abortRef.current?.abort();
|
|
227
|
+
cursorRef.current?.destroy();
|
|
228
|
+
cursorRef.current = null;
|
|
229
|
+
};
|
|
230
|
+
}, []);
|
|
231
|
+
|
|
232
|
+
const replay = useCallback(() => {
|
|
233
|
+
if (statusRef.current === 'running') return;
|
|
234
|
+
setStatus('idle');
|
|
235
|
+
// let the status flip settle before the loop re-checks it
|
|
236
|
+
requestAnimationFrame(() => tryStart());
|
|
237
|
+
}, [setStatus, tryStart]);
|
|
238
|
+
|
|
239
|
+
return (
|
|
240
|
+
<div
|
|
241
|
+
ref={wrapperRef}
|
|
242
|
+
className={['showcase-demo', className].filter(Boolean).join(' ')}
|
|
243
|
+
data-showcase-status={status}
|
|
244
|
+
style={style}
|
|
245
|
+
>
|
|
246
|
+
{children}
|
|
247
|
+
{/* cursor layer: above the demo AND its in-demo popups, but transparent to input */}
|
|
248
|
+
<div ref={overlayRef} aria-hidden className="showcase-demo__overlay" />
|
|
249
|
+
{status === 'running' ? (
|
|
250
|
+
<div className="showcase-pill showcase-pill--running" role="status">
|
|
251
|
+
<span className="showcase-pill__dot" />
|
|
252
|
+
{runningLabel}
|
|
253
|
+
</div>
|
|
254
|
+
) : null}
|
|
255
|
+
{status === 'user' ? (
|
|
256
|
+
<button
|
|
257
|
+
type="button"
|
|
258
|
+
onClick={replay}
|
|
259
|
+
className="showcase-pill showcase-pill--user"
|
|
260
|
+
>
|
|
261
|
+
{userLabel}
|
|
262
|
+
</button>
|
|
263
|
+
) : null}
|
|
264
|
+
</div>
|
|
265
|
+
);
|
|
266
|
+
}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
useEffect,
|
|
5
|
+
useRef,
|
|
6
|
+
useState,
|
|
7
|
+
type ComponentType,
|
|
8
|
+
type CSSProperties,
|
|
9
|
+
type ReactNode,
|
|
10
|
+
} from 'react';
|
|
11
|
+
|
|
12
|
+
import { whenIdle } from './hooks.ts';
|
|
13
|
+
|
|
14
|
+
export type LazyShowcaseLoadedProps = {
|
|
15
|
+
/** Call once the live demo has painted its real content. */
|
|
16
|
+
onReady?: () => void;
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
export type LazyShowcaseProps<P extends object> = {
|
|
20
|
+
/** Dynamic import of the live demo, e.g. `() => import('./HeroDemo')`. */
|
|
21
|
+
load: () => Promise<{ default: ComponentType<P & LazyShowcaseLoadedProps> }>;
|
|
22
|
+
props: P;
|
|
23
|
+
/** Static first paint (an <img> screenshot, a skeleton…). Fades out once live. */
|
|
24
|
+
poster: ReactNode;
|
|
25
|
+
/**
|
|
26
|
+
* Fixed height, so swapping poster → live never shifts layout. Omit it when
|
|
27
|
+
* `className` sets a (responsive) height instead.
|
|
28
|
+
*/
|
|
29
|
+
height?: number | string;
|
|
30
|
+
/** Start loading this far before the container scrolls into view. */
|
|
31
|
+
rootMargin?: string;
|
|
32
|
+
className?: string;
|
|
33
|
+
style?: CSSProperties;
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Poster first, live demo later: the import starts when the container is
|
|
38
|
+
* near the viewport AND the main thread is idle, and the live demo cross-fades
|
|
39
|
+
* in over the poster once it reports `onReady`. Height is fixed up front, so
|
|
40
|
+
* there is no layout shift.
|
|
41
|
+
*/
|
|
42
|
+
export function LazyShowcase<P extends object>({
|
|
43
|
+
load,
|
|
44
|
+
props,
|
|
45
|
+
poster,
|
|
46
|
+
height,
|
|
47
|
+
rootMargin = '200px',
|
|
48
|
+
className,
|
|
49
|
+
style,
|
|
50
|
+
}: LazyShowcaseProps<P>) {
|
|
51
|
+
const ref = useRef<HTMLDivElement | null>(null);
|
|
52
|
+
const loadRef = useRef(load);
|
|
53
|
+
loadRef.current = load;
|
|
54
|
+
const [Live, setLive] = useState<ComponentType<
|
|
55
|
+
P & LazyShowcaseLoadedProps
|
|
56
|
+
> | null>(null);
|
|
57
|
+
const [ready, setReady] = useState(false);
|
|
58
|
+
const [failed, setFailed] = useState(false);
|
|
59
|
+
|
|
60
|
+
useEffect(() => {
|
|
61
|
+
const node = ref.current;
|
|
62
|
+
if (!node) return;
|
|
63
|
+
let cancelIdle: (() => void) | undefined;
|
|
64
|
+
let disposed = false;
|
|
65
|
+
const observer = new IntersectionObserver(
|
|
66
|
+
(entries) => {
|
|
67
|
+
if (!entries.some((entry) => entry.isIntersecting)) return;
|
|
68
|
+
observer.disconnect();
|
|
69
|
+
cancelIdle = whenIdle(() => {
|
|
70
|
+
loadRef
|
|
71
|
+
.current()
|
|
72
|
+
.then((mod) => {
|
|
73
|
+
if (!disposed) setLive(() => mod.default);
|
|
74
|
+
})
|
|
75
|
+
.catch((error) => {
|
|
76
|
+
console.warn(
|
|
77
|
+
'[lazy-showcase] failed to load the live demo',
|
|
78
|
+
error,
|
|
79
|
+
);
|
|
80
|
+
if (!disposed) setFailed(true);
|
|
81
|
+
});
|
|
82
|
+
});
|
|
83
|
+
},
|
|
84
|
+
{ rootMargin },
|
|
85
|
+
);
|
|
86
|
+
observer.observe(node);
|
|
87
|
+
return () => {
|
|
88
|
+
disposed = true;
|
|
89
|
+
observer.disconnect();
|
|
90
|
+
cancelIdle?.();
|
|
91
|
+
};
|
|
92
|
+
}, [rootMargin]);
|
|
93
|
+
|
|
94
|
+
return (
|
|
95
|
+
<div
|
|
96
|
+
ref={ref}
|
|
97
|
+
className={['showcase-lazy', className].filter(Boolean).join(' ')}
|
|
98
|
+
style={{ height, ...style }}
|
|
99
|
+
data-showcase-ready={ready ? 'true' : 'false'}
|
|
100
|
+
>
|
|
101
|
+
<div className="showcase-lazy__poster" aria-hidden={ready}>
|
|
102
|
+
{poster}
|
|
103
|
+
</div>
|
|
104
|
+
{Live && !failed ? (
|
|
105
|
+
<div className="showcase-lazy__live">
|
|
106
|
+
<Live {...props} onReady={() => setReady(true)} />
|
|
107
|
+
</div>
|
|
108
|
+
) : null}
|
|
109
|
+
</div>
|
|
110
|
+
);
|
|
111
|
+
}
|