@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.
- package/CHANGELOG.md +7 -0
- package/README.md +123 -2
- package/dist/code/demoFiles.d.ts +14 -0
- package/dist/code/demoFiles.d.ts.map +1 -0
- package/dist/code/demoFiles.js +46 -0
- package/dist/code/demoFiles.js.map +1 -0
- package/dist/code/heights.d.ts +17 -0
- package/dist/code/heights.d.ts.map +1 -0
- package/dist/code/heights.js +40 -0
- package/dist/code/heights.js.map +1 -0
- package/dist/code/highlightSpec.d.ts +34 -0
- package/dist/code/highlightSpec.d.ts.map +1 -0
- package/dist/code/highlightSpec.js +119 -0
- package/dist/code/highlightSpec.js.map +1 -0
- package/dist/code/imports.d.ts +5 -0
- package/dist/code/imports.d.ts.map +1 -0
- package/dist/code/imports.js +17 -0
- package/dist/code/imports.js.map +1 -0
- package/dist/code/index.d.ts +8 -0
- package/dist/code/index.d.ts.map +1 -0
- package/dist/code/index.js +8 -0
- package/dist/code/index.js.map +1 -0
- package/dist/code/lineRanges.d.ts +5 -0
- package/dist/code/lineRanges.d.ts.map +1 -0
- package/dist/code/lineRanges.js +35 -0
- package/dist/code/lineRanges.js.map +1 -0
- package/dist/code/regions.d.ts +53 -0
- package/dist/code/regions.d.ts.map +1 -0
- package/dist/code/regions.js +237 -0
- package/dist/code/regions.js.map +1 -0
- package/dist/code/shiki.d.ts +58 -0
- package/dist/code/shiki.d.ts.map +1 -0
- package/dist/code/shiki.js +244 -0
- package/dist/code/shiki.js.map +1 -0
- package/dist/demos/build.d.ts +17 -0
- package/dist/demos/build.d.ts.map +1 -0
- package/dist/demos/build.js +426 -0
- package/dist/demos/build.js.map +1 -0
- package/dist/demos/cli.d.ts +3 -0
- package/dist/demos/cli.d.ts.map +1 -0
- package/dist/demos/cli.js +68 -0
- package/dist/demos/cli.js.map +1 -0
- package/dist/demos/client.d.ts +27 -0
- package/dist/demos/client.d.ts.map +1 -0
- package/dist/demos/client.js +61 -0
- package/dist/demos/client.js.map +1 -0
- package/dist/demos/compile/core.d.ts +64 -0
- package/dist/demos/compile/core.d.ts.map +1 -0
- package/dist/demos/compile/core.js +174 -0
- package/dist/demos/compile/core.js.map +1 -0
- package/dist/demos/config.d.ts +108 -0
- package/dist/demos/config.d.ts.map +1 -0
- package/dist/demos/config.js +4 -0
- package/dist/demos/config.js.map +1 -0
- package/dist/demos/devEvents.d.ts +13 -0
- package/dist/demos/devEvents.d.ts.map +1 -0
- package/dist/demos/devEvents.js +45 -0
- package/dist/demos/devEvents.js.map +1 -0
- package/dist/demos/html.d.ts +21 -0
- package/dist/demos/html.d.ts.map +1 -0
- package/dist/demos/html.js +57 -0
- package/dist/demos/html.js.map +1 -0
- package/dist/demos/index.d.ts +8 -0
- package/dist/demos/index.d.ts.map +1 -0
- package/dist/demos/index.js +6 -0
- package/dist/demos/index.js.map +1 -0
- package/dist/demos/pages.d.ts +15 -0
- package/dist/demos/pages.d.ts.map +1 -0
- package/dist/demos/pages.js +71 -0
- package/dist/demos/pages.js.map +1 -0
- package/dist/demos/runtime/iframe.d.ts +50 -0
- package/dist/demos/runtime/iframe.d.ts.map +1 -0
- package/dist/demos/runtime/iframe.js +245 -0
- package/dist/demos/runtime/iframe.js.map +1 -0
- package/dist/demos/runtime/react.d.ts +3 -0
- package/dist/demos/runtime/react.d.ts.map +1 -0
- package/dist/demos/runtime/react.js +17 -0
- package/dist/demos/runtime/react.js.map +1 -0
- package/dist/demos/slug.d.ts +3 -0
- package/dist/demos/slug.d.ts.map +1 -0
- package/dist/demos/slug.js +11 -0
- package/dist/demos/slug.js.map +1 -0
- package/dist/demos/vendor.d.ts +32 -0
- package/dist/demos/vendor.d.ts.map +1 -0
- package/dist/demos/vendor.js +127 -0
- package/dist/demos/vendor.js.map +1 -0
- package/dist/demos/worker/compile.worker.d.ts +2 -0
- package/dist/demos/worker/compile.worker.d.ts.map +1 -0
- package/dist/demos/worker/compile.worker.js +27 -0
- package/dist/demos/worker/compile.worker.js.map +1 -0
- package/dist/fork/codesandbox.d.ts +39 -0
- package/dist/fork/codesandbox.d.ts.map +1 -0
- package/dist/fork/codesandbox.js +156 -0
- package/dist/fork/codesandbox.js.map +1 -0
- package/dist/fork/index.d.ts +2 -0
- package/dist/fork/index.d.ts.map +1 -0
- package/dist/fork/index.js +2 -0
- package/dist/fork/index.js.map +1 -0
- package/dist/react/Demo.d.ts +80 -0
- package/dist/react/Demo.d.ts.map +1 -0
- package/dist/react/Demo.js +156 -0
- package/dist/react/Demo.js.map +1 -0
- package/dist/react/DemoIframe.d.ts +22 -0
- package/dist/react/DemoIframe.d.ts.map +1 -0
- package/dist/react/DemoIframe.js +123 -0
- package/dist/react/DemoIframe.js.map +1 -0
- package/dist/react/DemoShell.d.ts +47 -0
- package/dist/react/DemoShell.d.ts.map +1 -0
- package/dist/react/DemoShell.js +341 -0
- package/dist/react/DemoShell.js.map +1 -0
- package/dist/react/devEvents.d.ts +17 -0
- package/dist/react/devEvents.d.ts.map +1 -0
- package/dist/react/devEvents.js +30 -0
- package/dist/react/devEvents.js.map +1 -0
- package/dist/react/editor.d.ts +8 -0
- package/dist/react/editor.d.ts.map +1 -0
- package/dist/react/editor.js +52 -0
- package/dist/react/editor.js.map +1 -0
- package/dist/react/fork.d.ts +10 -0
- package/dist/react/fork.d.ts.map +1 -0
- package/dist/react/fork.js +30 -0
- package/dist/react/fork.js.map +1 -0
- package/dist/react/index.d.ts +4 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/index.js +4 -0
- package/dist/react/index.js.map +1 -0
- package/dist/react/styles.css +493 -0
- package/dist/remark/index.d.ts +3 -0
- package/dist/remark/index.d.ts.map +1 -0
- package/dist/remark/index.js +3 -0
- package/dist/remark/index.js.map +1 -0
- package/dist/remark/meta.d.ts +7 -0
- package/dist/remark/meta.d.ts.map +1 -0
- package/dist/remark/meta.js +20 -0
- package/dist/remark/meta.js.map +1 -0
- package/dist/remark/remarkDemoFences.d.ts +77 -0
- package/dist/remark/remarkDemoFences.d.ts.map +1 -0
- package/dist/remark/remarkDemoFences.js +259 -0
- package/dist/remark/remarkDemoFences.js.map +1 -0
- package/package.json +106 -4
- package/src/code/demoFiles.ts +54 -0
- package/src/code/heights.ts +47 -0
- package/src/code/highlightSpec.ts +139 -0
- package/src/code/imports.ts +18 -0
- package/src/code/index.ts +46 -0
- package/src/code/lineRanges.ts +31 -0
- package/src/code/regions.ts +270 -0
- package/src/code/shiki.ts +271 -0
- package/src/demos/build.ts +477 -0
- package/src/demos/cli.ts +64 -0
- package/src/demos/client.ts +82 -0
- package/src/demos/compile/core.ts +228 -0
- package/src/demos/config.ts +106 -0
- package/src/demos/devEvents.ts +45 -0
- package/src/demos/html.ts +74 -0
- package/src/demos/index.ts +25 -0
- package/src/demos/pages.ts +79 -0
- package/src/demos/runtime/iframe.ts +262 -0
- package/src/demos/runtime/react.ts +19 -0
- package/src/demos/slug.ts +10 -0
- package/src/demos/vendor.ts +142 -0
- package/src/demos/worker/compile.worker.ts +35 -0
- package/src/fork/codesandbox.ts +189 -0
- package/src/fork/index.ts +10 -0
- package/src/react/Demo.tsx +250 -0
- package/src/react/DemoIframe.tsx +165 -0
- package/src/react/DemoShell.tsx +592 -0
- package/src/react/devEvents.ts +34 -0
- package/src/react/editor.ts +61 -0
- package/src/react/fork.ts +31 -0
- package/src/react/index.ts +10 -0
- package/src/react/styles.css +493 -0
- package/src/remark/index.ts +2 -0
- package/src/remark/meta.ts +20 -0
- package/src/remark/remarkDemoFences.ts +330 -0
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { visit } from 'unist-util-visit';
|
|
4
|
+
|
|
5
|
+
import { collectDemoFiles } from '../code/demoFiles.ts';
|
|
6
|
+
import { formatHighlightSpec } from '../code/highlightSpec.ts';
|
|
7
|
+
import { parseDemoHeight } from '../code/heights.ts';
|
|
8
|
+
import { formatLineRanges } from '../code/lineRanges.ts';
|
|
9
|
+
import { applySourceReplacements, extractCodeMarkers, sliceRegion, stripCodeMarkers } from '../code/regions.ts';
|
|
10
|
+
import { parseFenceMeta, type FenceProps } from './meta.ts';
|
|
11
|
+
|
|
12
|
+
export type FenceInfo = {
|
|
13
|
+
lang: string | null;
|
|
14
|
+
meta: string;
|
|
15
|
+
props: FenceProps;
|
|
16
|
+
/** The fence sits inside a `<Demo>` element. */
|
|
17
|
+
inDemo: boolean;
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
export type RemarkDemoFencesOptions = {
|
|
21
|
+
/** Absolute path of the content root. */
|
|
22
|
+
contentDir: string;
|
|
23
|
+
/** Content-relative folder of the page being compiled, e.g. `docs/learn/sorting` (slashes are trimmed). */
|
|
24
|
+
folder: string;
|
|
25
|
+
/**
|
|
26
|
+
* Collects the content-relative paths of every source file the page shows
|
|
27
|
+
* (snippets, live demos and their relative imports), for dev reloads.
|
|
28
|
+
*/
|
|
29
|
+
dependencies?: Set<string>;
|
|
30
|
+
/**
|
|
31
|
+
* Which fences this plugin owns. Unclaimed fences are left untouched for
|
|
32
|
+
* other plugins (e.g. a legacy pipeline running after this one). Fences
|
|
33
|
+
* inside `<Demo>` are always claimed. Default: every fence.
|
|
34
|
+
*/
|
|
35
|
+
claim?: (fence: FenceInfo) => boolean;
|
|
36
|
+
/**
|
|
37
|
+
* `ts`/`tsx`/`js`/`jsx` fences must use `file="..."` so every snippet is
|
|
38
|
+
* type-checked; inline code in those languages throws. Default `true`.
|
|
39
|
+
*/
|
|
40
|
+
banInlineCode?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* How a claimed, non-live, untitled `file=` fence renders:
|
|
43
|
+
* - `shiki-meta` (default): the file's source is inlined into the code node
|
|
44
|
+
* and the highlight/line-number meta is rewritten for `@shikijs/rehype`
|
|
45
|
+
* with `fenceTransformers()` from `/code`;
|
|
46
|
+
* - `card`: a code-only `<Demo>` card (no markdown-level shiki needed).
|
|
47
|
+
*/
|
|
48
|
+
staticFences?: 'shiki-meta' | 'card';
|
|
49
|
+
/** File suffixes of live demo entries. Default `['.demo.tsx']`. */
|
|
50
|
+
demoSuffixes?: string[];
|
|
51
|
+
/** MDX component the live/card fences become. Default `Demo`. */
|
|
52
|
+
componentName?: string;
|
|
53
|
+
/** Literal replacements applied to inlined source (see `applySourceReplacements`). */
|
|
54
|
+
sourceReplacements?: Record<string, string>;
|
|
55
|
+
/** `height` of a live fence that doesn't set one. Default `auto` (the card takes the code's height). */
|
|
56
|
+
liveHeight?: string;
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
const TYPECHECKED_LANGS = new Set(['ts', 'tsx', 'js', 'jsx', 'typescript', 'javascript']);
|
|
60
|
+
|
|
61
|
+
type MdxAttribute = { type: 'mdxJsxAttribute'; name: string; value: string };
|
|
62
|
+
type MdxElement = {
|
|
63
|
+
type: 'mdxJsxFlowElement';
|
|
64
|
+
name: string;
|
|
65
|
+
attributes: MdxAttribute[];
|
|
66
|
+
children: unknown[];
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Remark plugin for file-based fences.
|
|
71
|
+
*
|
|
72
|
+
* ```tsx file="basic.demo.tsx" live height="large" title="Basic grid"
|
|
73
|
+
* ```
|
|
74
|
+
*
|
|
75
|
+
* - `file="..."` is relative to the page's folder; `file="/docs/x.tsx"` to the
|
|
76
|
+
* content root. A missing file throws at compile time, so a bad reference
|
|
77
|
+
* fails the build.
|
|
78
|
+
* - `live` replaces the fence with `<Demo name="…">` (prebuilt iframe preview
|
|
79
|
+
* + code tabs). The file must be a demo entry (`*.demo.tsx`) inside the
|
|
80
|
+
* content folder. `live=off` shows the code tab first.
|
|
81
|
+
* - `region="name"` shows a `#region name` … `#endregion` slice (dedented).
|
|
82
|
+
* With `live`, the preview runs the whole demo and only the entry's code tab
|
|
83
|
+
* shows the region; editing and forking use full files.
|
|
84
|
+
* - Highlights live in the source as comments, stripped from the shown code:
|
|
85
|
+
* `// #highlight label` … `// #endhighlight`, or a trailing
|
|
86
|
+
* `code // #highlight label` (`{/* #highlight *\/}` in JSX children).
|
|
87
|
+
* `{1-3}` meta highlights are rejected.
|
|
88
|
+
* - `lines` adds a line-number gutter (original line numbers with `region`).
|
|
89
|
+
* - `files=off` hides the file names and tabs of the files the entry imports.
|
|
90
|
+
* - `title="..."` renders a card with the title as the snippet name.
|
|
91
|
+
* - `height="small|default|large|auto|<px>"`; a live fence defaults to
|
|
92
|
+
* `liveHeight` (`auto`).
|
|
93
|
+
*
|
|
94
|
+
* Fences can also live inside `<Demo>`, next to `<DemoTitle>` /
|
|
95
|
+
* `<DemoDescription>`, which render as the card header; the fence's props are
|
|
96
|
+
* hoisted onto the `<Demo>`. A fence without `live` there makes a code-only card.
|
|
97
|
+
*/
|
|
98
|
+
export function remarkDemoFences(options: RemarkDemoFencesOptions) {
|
|
99
|
+
const {
|
|
100
|
+
contentDir,
|
|
101
|
+
dependencies,
|
|
102
|
+
claim,
|
|
103
|
+
banInlineCode = true,
|
|
104
|
+
staticFences = 'shiki-meta',
|
|
105
|
+
demoSuffixes = ['.demo.tsx'],
|
|
106
|
+
componentName = 'Demo',
|
|
107
|
+
sourceReplacements,
|
|
108
|
+
liveHeight = 'auto',
|
|
109
|
+
} = options;
|
|
110
|
+
const folder = options.folder.replace(/^\/+|\/+$/g, '');
|
|
111
|
+
const pageDir = path.join(contentDir, folder);
|
|
112
|
+
/** `/docs/x.tsx` is relative to the content root, anything else to the page. */
|
|
113
|
+
const resolveFile = (file: string) =>
|
|
114
|
+
file.startsWith('/') ? path.join(contentDir, file) : path.resolve(pageDir, file);
|
|
115
|
+
const addDependency = (absPath: string) => {
|
|
116
|
+
dependencies?.add(path.relative(contentDir, absPath).split(path.sep).join('/'));
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
return () => (tree: any) => {
|
|
120
|
+
visit(tree, 'code', (node: any, index: number | undefined, parent: any) => {
|
|
121
|
+
if (index == null || !parent) return;
|
|
122
|
+
|
|
123
|
+
const inDemo = parent.type === 'mdxJsxFlowElement' && parent.name === componentName;
|
|
124
|
+
const meta: string = node.meta || '';
|
|
125
|
+
const props = parseFenceMeta(meta);
|
|
126
|
+
if (!inDemo && claim && !claim({ lang: node.lang ?? null, meta, props, inDemo })) return;
|
|
127
|
+
|
|
128
|
+
const context = `\`\`\`${node.lang ?? ''} ${meta} in "${path.join(path.basename(contentDir), folder)}"`;
|
|
129
|
+
|
|
130
|
+
if (/\{[^}]*\}/.test(meta.replace(/"[^"]*"/g, '""'))) {
|
|
131
|
+
throw new Error(
|
|
132
|
+
`${context}: \`{…}\` line highlights are not supported — mark the lines in the ` +
|
|
133
|
+
`source file with \`// #highlight label\` … \`// #endhighlight\`, or a trailing ` +
|
|
134
|
+
`\`// #highlight label\` on a single line`,
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const file = props.file;
|
|
139
|
+
if (props.live && !('height' in props)) props.height = liveHeight;
|
|
140
|
+
if ('range' in props) {
|
|
141
|
+
throw new Error(`${context}: \`range\` was renamed to \`region="region-name"\``);
|
|
142
|
+
}
|
|
143
|
+
if (banInlineCode && TYPECHECKED_LANGS.has(node.lang ?? '') && typeof file !== 'string') {
|
|
144
|
+
throw new Error(
|
|
145
|
+
`${context}: inline ${node.lang} snippets are not allowed — put the code in a ` +
|
|
146
|
+
`co-located *.snippet.tsx (type-checked by tsc) and reference it with ` +
|
|
147
|
+
`\`file="x.snippet.tsx" region="region-name"\``,
|
|
148
|
+
);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
if (!inDemo && typeof file !== 'string' && typeof props.title !== 'string') return;
|
|
152
|
+
|
|
153
|
+
if ('height' in props) {
|
|
154
|
+
try {
|
|
155
|
+
parseDemoHeight(typeof props.height === 'string' ? props.height : '');
|
|
156
|
+
} catch (error) {
|
|
157
|
+
throw new Error(`${context}: ${error instanceof Error ? error.message : String(error)}`);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
let source: string = node.value ?? '';
|
|
162
|
+
if (typeof file === 'string') {
|
|
163
|
+
const absPath = resolveFile(file);
|
|
164
|
+
if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
|
|
165
|
+
throw new Error(`${context}: file not found: ${path.relative(contentDir, absPath)}`);
|
|
166
|
+
}
|
|
167
|
+
source = applySourceReplacements(fs.readFileSync(absPath, 'utf8').trimEnd(), sourceReplacements);
|
|
168
|
+
if (props.live) {
|
|
169
|
+
for (const { filePath } of collectDemoFiles(absPath)) addDependency(filePath);
|
|
170
|
+
} else {
|
|
171
|
+
addDependency(absPath);
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
let originalLines: number[] | undefined;
|
|
176
|
+
if (typeof props.region === 'string') {
|
|
177
|
+
if (typeof file !== 'string') throw new Error(`${context}: \`region\` requires \`file="..."\``);
|
|
178
|
+
const sliced = sliceRegion(source, props.region, context);
|
|
179
|
+
source = sliced.source;
|
|
180
|
+
originalLines = sliced.originalLines;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// Live demos strip markers per file in <Demo>.
|
|
184
|
+
let highlight: string | null = null;
|
|
185
|
+
// without `#highlight label` rows: what a card's copy button copies
|
|
186
|
+
let copyCode: string | null = null;
|
|
187
|
+
if (typeof file === 'string' && !props.live) {
|
|
188
|
+
const stripped = stripCodeMarkers(source);
|
|
189
|
+
const marked = extractCodeMarkers(source, context, originalLines);
|
|
190
|
+
source = marked.source;
|
|
191
|
+
if (stripped !== source) copyCode = stripped;
|
|
192
|
+
if (originalLines) originalLines = marked.originalLines;
|
|
193
|
+
if (marked.highlight.lines.length) highlight = formatHighlightSpec(marked.highlight);
|
|
194
|
+
}
|
|
195
|
+
const originalLinesAttr = originalLines ? formatLineRanges(originalLines) || null : null;
|
|
196
|
+
|
|
197
|
+
if (props.live) {
|
|
198
|
+
if (props.live !== true && props.live !== 'off') {
|
|
199
|
+
throw new Error(
|
|
200
|
+
`${context}: \`live\` accepts no value (preview shown first) or ` +
|
|
201
|
+
`\`live=off\` (preview available, code shown first)`,
|
|
202
|
+
);
|
|
203
|
+
}
|
|
204
|
+
const suffix = typeof file === 'string' ? demoSuffixes.find((s) => file.endsWith(s)) : undefined;
|
|
205
|
+
const fromRoot = typeof file === 'string' ? path.relative(contentDir, resolveFile(file)) : '..';
|
|
206
|
+
if (typeof file !== 'string' || !suffix || fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) {
|
|
207
|
+
throw new Error(
|
|
208
|
+
`${context}: live demos must reference a ${demoSuffixes.map((s) => `*${s}`).join(' / ')} ` +
|
|
209
|
+
`file inside the content folder (it has to match a prebuilt demo bundle)`,
|
|
210
|
+
);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
const attrs: Record<string, string> = { name: file.slice(0, -suffix.length) };
|
|
214
|
+
if (props.live === 'off') attrs.startTab = 'code';
|
|
215
|
+
if (props.files === 'off') attrs.hideFiles = 'true';
|
|
216
|
+
if (typeof props.region === 'string') attrs.region = props.region;
|
|
217
|
+
if (typeof props.height === 'string') attrs.height = props.height;
|
|
218
|
+
const heading = inDemo ? demoTitleFromElement(parent) : null;
|
|
219
|
+
if (heading) attrs.title = heading;
|
|
220
|
+
else if (typeof props.title === 'string') attrs.title = props.title;
|
|
221
|
+
if (props.lines) attrs.lines = 'true';
|
|
222
|
+
if (props.edit === 'off') attrs.editable = 'false';
|
|
223
|
+
|
|
224
|
+
if (inDemo) {
|
|
225
|
+
assertSingleSnippet(parent, context);
|
|
226
|
+
for (const [attrName, value] of Object.entries(attrs)) setAttribute(parent, attrName, value);
|
|
227
|
+
parent.children.splice(index, 1);
|
|
228
|
+
return index;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
parent.children[index] = element(componentName, attrs);
|
|
232
|
+
return;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
const cardAttrs = (snippetTitle: string | null): Record<string, string> => {
|
|
236
|
+
const attrs: Record<string, string> = { code: source, lang: node.lang || 'tsx' };
|
|
237
|
+
if (snippetTitle) attrs.codeTitle = snippetTitle;
|
|
238
|
+
if (copyCode) attrs.copyCode = copyCode;
|
|
239
|
+
if (typeof props.height === 'string') attrs.height = props.height;
|
|
240
|
+
if (highlight) attrs.highlight = highlight;
|
|
241
|
+
if (props.lines) attrs.lines = 'true';
|
|
242
|
+
if (originalLinesAttr) attrs.originalLines = originalLinesAttr;
|
|
243
|
+
return attrs;
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
if (inDemo) {
|
|
247
|
+
// Code-only demo: hand the snippet to <Demo> and drop the fence.
|
|
248
|
+
assertSingleSnippet(parent, context);
|
|
249
|
+
const snippetTitle =
|
|
250
|
+
typeof props.title === 'string' ? props.title : props.files === 'off' ? null : (file ?? null);
|
|
251
|
+
const attrs = cardAttrs(typeof snippetTitle === 'string' ? snippetTitle : null);
|
|
252
|
+
const heading = demoTitleFromElement(parent);
|
|
253
|
+
if (heading) attrs.title = heading;
|
|
254
|
+
else if (typeof props.title === 'string') attrs.title = props.title;
|
|
255
|
+
for (const [attrName, value] of Object.entries(attrs)) setAttribute(parent, attrName, value);
|
|
256
|
+
parent.children.splice(index, 1);
|
|
257
|
+
return index;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (typeof props.title === 'string' || staticFences === 'card') {
|
|
261
|
+
parent.children[index] = element(
|
|
262
|
+
componentName,
|
|
263
|
+
cardAttrs(typeof props.title === 'string' ? props.title : null),
|
|
264
|
+
);
|
|
265
|
+
return;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
// Standalone static snippet: inline the referenced file's source; a
|
|
269
|
+
// markdown-level shiki pipeline highlights it like any code block.
|
|
270
|
+
node.value = source;
|
|
271
|
+
node.meta =
|
|
272
|
+
[
|
|
273
|
+
highlight ? `{${highlight}}` : null,
|
|
274
|
+
props.lines ? 'lines' : null,
|
|
275
|
+
originalLinesAttr ? `originalLines="${originalLinesAttr}"` : null,
|
|
276
|
+
typeof props.height === 'string' ? `height="${props.height}"` : null,
|
|
277
|
+
]
|
|
278
|
+
.filter(Boolean)
|
|
279
|
+
.join(' ') || null;
|
|
280
|
+
node.data = { ...node.data, docsKit: true };
|
|
281
|
+
});
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function element(name: string, attrs: Record<string, string>): MdxElement {
|
|
286
|
+
return {
|
|
287
|
+
type: 'mdxJsxFlowElement',
|
|
288
|
+
name,
|
|
289
|
+
attributes: Object.entries(attrs).map(([attrName, value]) => ({
|
|
290
|
+
type: 'mdxJsxAttribute',
|
|
291
|
+
name: attrName,
|
|
292
|
+
value,
|
|
293
|
+
})),
|
|
294
|
+
children: [],
|
|
295
|
+
};
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
function hasAttribute(el: any, name: string): boolean {
|
|
299
|
+
return (el.attributes || []).some((attr: any) => attr.type === 'mdxJsxAttribute' && attr.name === name);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/** Adds an attribute unless it's already set on the element in the markdown. */
|
|
303
|
+
function setAttribute(el: any, name: string, value: string) {
|
|
304
|
+
if (hasAttribute(el, name)) return;
|
|
305
|
+
el.attributes = el.attributes || [];
|
|
306
|
+
el.attributes.push({ type: 'mdxJsxAttribute', name, value });
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
function assertSingleSnippet(demoElement: any, context: string) {
|
|
310
|
+
if (hasAttribute(demoElement, 'name') || hasAttribute(demoElement, 'code')) {
|
|
311
|
+
throw new Error(`${context}: a <Demo> can contain only one code block`);
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function jsxText(node: any): string {
|
|
316
|
+
if (!node) return '';
|
|
317
|
+
if (node.type === 'text' || node.type === 'mdxTextExpression') return node.value || '';
|
|
318
|
+
return (node.children || []).map(jsxText).join('');
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** Plain text of a wrapping `<DemoTitle>`, if the fence lives inside `<Demo>`. */
|
|
322
|
+
function demoTitleFromElement(demoElement: any): string | null {
|
|
323
|
+
for (const child of demoElement.children || []) {
|
|
324
|
+
if (child.type === 'mdxJsxFlowElement' && child.name === 'DemoTitle') {
|
|
325
|
+
const text = jsxText(child).trim();
|
|
326
|
+
if (text) return text;
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
return null;
|
|
330
|
+
}
|