@thedatagrid/docs-kit 0.1.0 → 0.2.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.
@@ -91,9 +91,20 @@ type MdxElement = {
91
91
  * - `height="small|default|large|auto|<px>"`; a live fence defaults to
92
92
  * `liveHeight` (`auto`).
93
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.
94
+ * A `<DemoTitle>` and/or `<DemoDescription>` right before a fence become that
95
+ * fence's card header:
96
+ *
97
+ * <DemoDescription>
98
+ * What the demo shows.
99
+ * </DemoDescription>
100
+ *
101
+ * ```tsx file="basic.demo.tsx" live
102
+ * ```
103
+ *
104
+ * That's the same as wrapping the three in `<Demo>`, which also works. The
105
+ * fence's props are hoisted onto the `<Demo>`; a fence without `live` there
106
+ * makes a code-only card. A `<DemoTitle>` / `<DemoDescription>` with no fence
107
+ * after it fails the build.
97
108
  */
98
109
  export function remarkDemoFences(options: RemarkDemoFencesOptions) {
99
110
  const {
@@ -117,6 +128,7 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
117
128
  };
118
129
 
119
130
  return () => (tree: any) => {
131
+ wrapLooseHeaders(tree, componentName, folder);
120
132
  visit(tree, 'code', (node: any, index: number | undefined, parent: any) => {
121
133
  if (index == null || !parent) return;
122
134
 
@@ -282,6 +294,51 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
282
294
  };
283
295
  }
284
296
 
297
+ const HEADER_PARTS = new Set(['DemoTitle', 'DemoDescription']);
298
+ const isHeaderPart = (node: any) => node?.type === 'mdxJsxFlowElement' && HEADER_PARTS.has(node.name);
299
+
300
+ /**
301
+ * Wraps each run of `<DemoTitle>` / `<DemoDescription>` (outside `<Demo>`)
302
+ * and the fence right after it in a `<Demo>`, so the fence handling below
303
+ * sees the same tree as for an explicit wrapper.
304
+ */
305
+ function wrapLooseHeaders(tree: any, componentName: string, folder: string) {
306
+ visit(tree, (node: any) => {
307
+ if (!Array.isArray(node.children)) return;
308
+ if (node.type === 'mdxJsxFlowElement' && node.name === componentName) return 'skip';
309
+ const children: any[] = node.children;
310
+ for (let index = 0; index < children.length; index++) {
311
+ if (!isHeaderPart(children[index])) continue;
312
+ let end = index;
313
+ while (isHeaderPart(children[end])) end++;
314
+ const parts = children.slice(index, end);
315
+ const where = `"${folder}"${parts[0].position ? ` line ${parts[0].position.start.line}` : ''}`;
316
+ const names = parts.map((part) => part.name as string);
317
+ const repeated = names.find((name, i) => names.indexOf(name) !== i);
318
+ if (repeated) {
319
+ throw new Error(`<${repeated}> in ${where}: one per demo (each fence gets its own title and description)`);
320
+ }
321
+ const fence = children[end];
322
+ if (fence?.type !== 'code') {
323
+ throw new Error(
324
+ `<${names[0]}> in ${where} must come right before the code fence it describes ` +
325
+ `(or sit inside <${componentName}> with it)`,
326
+ );
327
+ }
328
+ const demo: MdxElement & { position?: unknown } = {
329
+ type: 'mdxJsxFlowElement',
330
+ name: componentName,
331
+ attributes: [],
332
+ children: [...parts, fence],
333
+ };
334
+ if (parts[0].position && fence.position) {
335
+ demo.position = { start: parts[0].position.start, end: fence.position.end };
336
+ }
337
+ children.splice(index, end - index + 1, demo);
338
+ }
339
+ });
340
+ }
341
+
285
342
  function element(name: string, attrs: Record<string, string>): MdxElement {
286
343
  return {
287
344
  type: 'mdxJsxFlowElement',