@thedatagrid/docs-kit 0.0.0-stage → 0.2.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 (184) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +224 -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 +102 -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/editor/install.d.ts +15 -0
  92. package/dist/editor/install.d.ts.map +1 -0
  93. package/dist/editor/install.js +71 -0
  94. package/dist/editor/install.js.map +1 -0
  95. package/dist/fork/codesandbox.d.ts +39 -0
  96. package/dist/fork/codesandbox.d.ts.map +1 -0
  97. package/dist/fork/codesandbox.js +156 -0
  98. package/dist/fork/codesandbox.js.map +1 -0
  99. package/dist/fork/index.d.ts +2 -0
  100. package/dist/fork/index.d.ts.map +1 -0
  101. package/dist/fork/index.js +2 -0
  102. package/dist/fork/index.js.map +1 -0
  103. package/dist/react/Demo.d.ts +80 -0
  104. package/dist/react/Demo.d.ts.map +1 -0
  105. package/dist/react/Demo.js +156 -0
  106. package/dist/react/Demo.js.map +1 -0
  107. package/dist/react/DemoIframe.d.ts +22 -0
  108. package/dist/react/DemoIframe.d.ts.map +1 -0
  109. package/dist/react/DemoIframe.js +123 -0
  110. package/dist/react/DemoIframe.js.map +1 -0
  111. package/dist/react/DemoShell.d.ts +47 -0
  112. package/dist/react/DemoShell.d.ts.map +1 -0
  113. package/dist/react/DemoShell.js +341 -0
  114. package/dist/react/DemoShell.js.map +1 -0
  115. package/dist/react/devEvents.d.ts +17 -0
  116. package/dist/react/devEvents.d.ts.map +1 -0
  117. package/dist/react/devEvents.js +30 -0
  118. package/dist/react/devEvents.js.map +1 -0
  119. package/dist/react/editor.d.ts +17 -0
  120. package/dist/react/editor.d.ts.map +1 -0
  121. package/dist/react/editor.js +158 -0
  122. package/dist/react/editor.js.map +1 -0
  123. package/dist/react/fork.d.ts +10 -0
  124. package/dist/react/fork.d.ts.map +1 -0
  125. package/dist/react/fork.js +30 -0
  126. package/dist/react/fork.js.map +1 -0
  127. package/dist/react/index.d.ts +4 -0
  128. package/dist/react/index.d.ts.map +1 -0
  129. package/dist/react/index.js +4 -0
  130. package/dist/react/index.js.map +1 -0
  131. package/dist/react/styles.css +471 -0
  132. package/dist/remark/index.d.ts +3 -0
  133. package/dist/remark/index.d.ts.map +1 -0
  134. package/dist/remark/index.js +3 -0
  135. package/dist/remark/index.js.map +1 -0
  136. package/dist/remark/meta.d.ts +7 -0
  137. package/dist/remark/meta.d.ts.map +1 -0
  138. package/dist/remark/meta.js +20 -0
  139. package/dist/remark/meta.js.map +1 -0
  140. package/dist/remark/remarkDemoFences.d.ts +77 -0
  141. package/dist/remark/remarkDemoFences.d.ts.map +1 -0
  142. package/dist/remark/remarkDemoFences.js +259 -0
  143. package/dist/remark/remarkDemoFences.js.map +1 -0
  144. package/editor-extension/README.md +23 -0
  145. package/editor-extension/extension.js +40 -0
  146. package/editor-extension/links.js +137 -0
  147. package/editor-extension/package.json +19 -0
  148. package/package.json +107 -4
  149. package/src/code/demoFiles.ts +54 -0
  150. package/src/code/heights.ts +47 -0
  151. package/src/code/highlightSpec.ts +139 -0
  152. package/src/code/imports.ts +18 -0
  153. package/src/code/index.ts +46 -0
  154. package/src/code/lineRanges.ts +31 -0
  155. package/src/code/regions.ts +270 -0
  156. package/src/code/shiki.ts +271 -0
  157. package/src/demos/build.ts +477 -0
  158. package/src/demos/cli.ts +97 -0
  159. package/src/demos/client.ts +82 -0
  160. package/src/demos/compile/core.ts +228 -0
  161. package/src/demos/config.ts +106 -0
  162. package/src/demos/devEvents.ts +45 -0
  163. package/src/demos/html.ts +74 -0
  164. package/src/demos/index.ts +25 -0
  165. package/src/demos/pages.ts +79 -0
  166. package/src/demos/runtime/iframe.ts +262 -0
  167. package/src/demos/runtime/react.ts +19 -0
  168. package/src/demos/slug.ts +10 -0
  169. package/src/demos/vendor.ts +142 -0
  170. package/src/demos/worker/compile.worker.ts +35 -0
  171. package/src/editor/install.ts +85 -0
  172. package/src/fork/codesandbox.ts +189 -0
  173. package/src/fork/index.ts +10 -0
  174. package/src/react/Demo.tsx +250 -0
  175. package/src/react/DemoIframe.tsx +165 -0
  176. package/src/react/DemoShell.tsx +592 -0
  177. package/src/react/devEvents.ts +34 -0
  178. package/src/react/editor.ts +178 -0
  179. package/src/react/fork.ts +31 -0
  180. package/src/react/index.ts +10 -0
  181. package/src/react/styles.css +471 -0
  182. package/src/remark/index.ts +2 -0
  183. package/src/remark/meta.ts +20 -0
  184. package/src/remark/remarkDemoFences.ts +330 -0
@@ -0,0 +1,271 @@
1
+ import { codeToHtml, type ShikiTransformer } from 'shiki';
2
+
3
+ import {
4
+ HEIGHT_META_RE,
5
+ HIGHLIGHT_META_RE,
6
+ LINES_META_RE,
7
+ ORIGINAL_LINES_META_RE,
8
+ parseHighlightSpec,
9
+ type HighlightSpec,
10
+ } from './highlightSpec.ts';
11
+ import { parseDemoHeight } from './heights.ts';
12
+ import { parseLineRanges } from './lineRanges.ts';
13
+
14
+ /** Light + dark shiki themes; output uses CSS variables (`defaultColor: false`). */
15
+ export type CodeThemes = { light: string; dark: string };
16
+
17
+ export const DEFAULT_CODE_THEMES: CodeThemes = { light: 'github-light', dark: 'tokyo-night' };
18
+
19
+ type Meta = Record<string, unknown>;
20
+ const metaOf = (ctx: { meta: unknown }) => ctx.meta as Meta;
21
+ const rawMeta = (ctx: { options: { meta?: { __raw?: unknown } } }) =>
22
+ (ctx.options.meta?.__raw as string) || '';
23
+
24
+ /** Shiki language for a file name. */
25
+ export function langForFile(fileName: string): string {
26
+ const ext = /\.([a-z0-9]+)$/i.exec(fileName)?.[1]?.toLowerCase() ?? '';
27
+ switch (ext) {
28
+ case 'ts':
29
+ case 'mts':
30
+ case 'cts':
31
+ return 'ts';
32
+ case 'js':
33
+ case 'mjs':
34
+ case 'cjs':
35
+ return 'js';
36
+ case 'jsx':
37
+ return 'jsx';
38
+ case 'css':
39
+ return 'css';
40
+ case 'json':
41
+ return 'json';
42
+ case 'vue':
43
+ return 'vue';
44
+ case 'html':
45
+ return 'html';
46
+ case 'md':
47
+ case 'mdx':
48
+ return 'mdx';
49
+ default:
50
+ return 'tsx';
51
+ }
52
+ }
53
+
54
+ /**
55
+ * Caps standalone code blocks whose meta carries `height` at that many pixels,
56
+ * scrolling inside. `auto` (the natural height) is a no-op.
57
+ */
58
+ export function transformerHeightMeta(): ShikiTransformer {
59
+ return {
60
+ name: 'docs-kit:height-meta',
61
+ pre(node) {
62
+ const match = rawMeta(this).match(HEIGHT_META_RE);
63
+ if (!match) return;
64
+ const heightPx = parseDemoHeight(match[1]);
65
+ if (heightPx === 'auto') return;
66
+ const prev = node.properties.style ? `${String(node.properties.style).replace(/;\s*$/, '')};` : '';
67
+ node.properties.style = `${prev}max-height:${heightPx}px;overflow:auto`;
68
+ },
69
+ };
70
+ }
71
+
72
+ /** Whole quoted specifier, optionally with the space shiki leaves on the token. */
73
+ const QUOTED_RELATIVE_IMPORT_RE = /^(\s*)(['"])(\.\.?\/[^'"]+)\2(\s*)$/;
74
+ /** Path only — dual-theme highlighting splits quotes into their own spans. */
75
+ const BARE_RELATIVE_IMPORT_RE = /^\.\.?\/[^'"]+$/;
76
+
77
+ /** POSIX `join` + normalize, enough for relative import specifiers. */
78
+ export function joinPath(...parts: string[]): string {
79
+ const out: string[] = [];
80
+ for (const segment of parts.join('/').split('/')) {
81
+ if (!segment || segment === '.') continue;
82
+ if (segment === '..') {
83
+ if (out.length && out[out.length - 1] !== '..') out.pop();
84
+ else out.push('..');
85
+ } else {
86
+ out.push(segment);
87
+ }
88
+ }
89
+ return out.join('/');
90
+ }
91
+
92
+ export function dirnameOf(filePath: string): string {
93
+ const index = filePath.lastIndexOf('/');
94
+ return index === -1 ? '' : filePath.slice(0, index);
95
+ }
96
+
97
+ /**
98
+ * Finds the demo file an import specifier points to. `fromFile` and
99
+ * `fileNames` share one root (e.g. paths relative to the demo's folder).
100
+ */
101
+ export function matchImportedFile(
102
+ specifier: string,
103
+ fromFile: string,
104
+ fileNames: string[],
105
+ ): string | undefined {
106
+ const target = joinPath(dirnameOf(fromFile), specifier);
107
+ return (
108
+ fileNames.find((name) => name === target) ??
109
+ fileNames.find((name) => name.startsWith(`${target}.`) && !name.slice(target.length + 1).includes('/')) ??
110
+ fileNames.find((name) => name.startsWith(`${target}/index.`))
111
+ );
112
+ }
113
+
114
+ /**
115
+ * Turns relative import specifiers into buttons (`data-demo-file`) that the
116
+ * demo shell uses to switch the active file tab.
117
+ */
118
+ export function transformerImportFileLinks(fromFile: string, fileNames: string[]): ShikiTransformer {
119
+ return {
120
+ name: 'docs-kit:import-file-links',
121
+ span(hast, _line, _col, _lineEl, token) {
122
+ const content = token?.content;
123
+ if (!content) return;
124
+ const quoted = content.match(QUOTED_RELATIVE_IMPORT_RE);
125
+ const specifier = quoted ? quoted[3] : BARE_RELATIVE_IMPORT_RE.test(content) ? content : null;
126
+ if (!specifier) return;
127
+ const file = matchImportedFile(specifier, fromFile, fileNames.filter((name) => name !== fromFile));
128
+ if (!file) return;
129
+
130
+ // Dual-theme output (and quoted tokens with no extra space): the whole
131
+ // span *is* the specifier, so retag it. Quoted tokens that still include
132
+ // a leading space wrap only the path so the underline doesn't cover it.
133
+ const lead = quoted?.[1];
134
+ const trail = quoted?.[4];
135
+ if (quoted && (lead || trail)) {
136
+ const quotedPath = `${quoted[2]}${specifier}${quoted[2]}`;
137
+ const children: typeof hast.children = [];
138
+ if (lead) children.push({ type: 'text', value: lead });
139
+ children.push({
140
+ type: 'element',
141
+ tagName: 'button',
142
+ properties: { type: 'button', class: 'dk-file-link', 'data-demo-file': file, title: `Open ${file}` },
143
+ children: [{ type: 'text', value: quotedPath }],
144
+ });
145
+ if (trail) children.push({ type: 'text', value: trail });
146
+ hast.children = children;
147
+ return;
148
+ }
149
+
150
+ hast.tagName = 'button';
151
+ hast.properties.type = 'button';
152
+ hast.properties['data-demo-file'] = file;
153
+ hast.properties.title = `Open ${file}`;
154
+ this.addClassToHast(hast, 'dk-file-link');
155
+ },
156
+ };
157
+ }
158
+
159
+ type HastNode = { type: string; value?: string; children?: HastNode[] };
160
+
161
+ function hastText(node: HastNode): string {
162
+ return node.type === 'text' ? (node.value ?? '') : (node.children ?? []).map(hastText).join('');
163
+ }
164
+
165
+ /**
166
+ * Adds a `highlighted` class to the given lines. `#highlight label` labels are
167
+ * appended as `.line-label` on the first line of each block. Without an
168
+ * explicit spec it reads the `{…}` that the remark plugin wrote into the
169
+ * fence meta (for `@shikijs/rehype` pipelines).
170
+ */
171
+ export function transformerLineHighlight(spec?: number[] | HighlightSpec): ShikiTransformer {
172
+ return {
173
+ name: 'docs-kit:line-highlight',
174
+ preprocess() {
175
+ const meta = metaOf(this);
176
+ if (spec) {
177
+ meta.__dkHighlight = Array.isArray(spec) ? spec : spec.lines;
178
+ meta.__dkHighlightLabels = Array.isArray(spec) ? {} : spec.labels;
179
+ return;
180
+ }
181
+ const match = rawMeta(this).match(HIGHLIGHT_META_RE);
182
+ const parsed = match ? parseHighlightSpec(match[1]) : { lines: [], labels: {} };
183
+ meta.__dkHighlight = parsed.lines;
184
+ meta.__dkHighlightLabels = parsed.labels;
185
+ },
186
+ line(node, line) {
187
+ const meta = metaOf(this);
188
+ if ((meta.__dkHighlight as number[]).includes(line)) this.addClassToHast(node, 'highlighted');
189
+ const label = (meta.__dkHighlightLabels as Record<number, string>)[line];
190
+ if (!label) return;
191
+ this.addClassToHast(node, 'has-label');
192
+ if (!hastText(node as HastNode).trim()) this.addClassToHast(node, 'label-only');
193
+ node.children = [
194
+ { type: 'element', tagName: 'span', properties: { class: 'line-code' }, children: node.children },
195
+ {
196
+ type: 'element',
197
+ tagName: 'span',
198
+ properties: { class: 'line-label' },
199
+ children: [{ type: 'text', value: label }],
200
+ },
201
+ ];
202
+ },
203
+ };
204
+ }
205
+
206
+ /**
207
+ * Gutter line numbers on every line (the `lines` fence flag). With
208
+ * `originalLines` (or `originalLines="12-14"` in the fence meta, written for
209
+ * `region` fences) the gutter shows those file line numbers.
210
+ */
211
+ export function transformerLineNumbers(originalLines?: number[] | true): ShikiTransformer {
212
+ return {
213
+ name: 'docs-kit:line-numbers',
214
+ preprocess() {
215
+ const meta = metaOf(this);
216
+ if (originalLines) {
217
+ meta.__dkLineNumbers = originalLines;
218
+ return;
219
+ }
220
+ const raw = rawMeta(this);
221
+ if (!LINES_META_RE.test(raw)) {
222
+ meta.__dkLineNumbers = null;
223
+ return;
224
+ }
225
+ const original = raw.match(ORIGINAL_LINES_META_RE);
226
+ meta.__dkLineNumbers = original ? parseLineRanges(original[1]) : true;
227
+ },
228
+ pre(node) {
229
+ if (metaOf(this).__dkLineNumbers == null) return;
230
+ this.addClassToHast(node, 'has-line-numbers');
231
+ },
232
+ line(node, line) {
233
+ const nums = metaOf(this).__dkLineNumbers as number[] | true | null;
234
+ if (nums == null) return;
235
+ const n = Array.isArray(nums) ? nums[line - 1] : line;
236
+ if (n == null) return;
237
+ node.properties['data-line'] = String(n);
238
+ },
239
+ };
240
+ }
241
+
242
+ /** The transformers a markdown-level `@shikijs/rehype` pipeline needs for remark-processed fences. */
243
+ export function fenceTransformers(): ShikiTransformer[] {
244
+ return [transformerLineHighlight(), transformerLineNumbers(), transformerHeightMeta()];
245
+ }
246
+
247
+ export type HighlightOptions = {
248
+ lang: string;
249
+ themes?: CodeThemes;
250
+ highlight?: HighlightSpec | null;
251
+ /** `true` for 1-based numbers, an array for original file line numbers. */
252
+ lineNumbers?: number[] | true | null;
253
+ /** Relative-import buttons: the current file and the other files of the demo. */
254
+ importLinks?: { fromFile: string; fileNames: string[] } | null;
255
+ };
256
+
257
+ /** Highlights code to HTML with dual themes (CSS variables) and the docs transformers. */
258
+ export async function highlightCode(code: string, options: HighlightOptions): Promise<string> {
259
+ const transformers: ShikiTransformer[] = [];
260
+ if (options.highlight?.lines.length) transformers.push(transformerLineHighlight(options.highlight));
261
+ if (options.lineNumbers) transformers.push(transformerLineNumbers(options.lineNumbers));
262
+ if (options.importLinks?.fileNames.length) {
263
+ transformers.push(transformerImportFileLinks(options.importLinks.fromFile, options.importLinks.fileNames));
264
+ }
265
+ return codeToHtml(code, {
266
+ lang: options.lang,
267
+ themes: options.themes ?? DEFAULT_CODE_THEMES,
268
+ defaultColor: false,
269
+ transformers,
270
+ });
271
+ }