@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,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
+ }