@thedatagrid/docs-kit 0.3.0 → 0.5.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 (182) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +172 -4
  3. package/dist/code/demoFiles.d.ts.map +1 -1
  4. package/dist/code/demoFiles.js +2 -2
  5. package/dist/code/demoFiles.js.map +1 -1
  6. package/dist/code/index.d.ts +1 -0
  7. package/dist/code/index.d.ts.map +1 -1
  8. package/dist/code/index.js +1 -0
  9. package/dist/code/index.js.map +1 -1
  10. package/dist/code/regions.d.ts +2 -1
  11. package/dist/code/regions.d.ts.map +1 -1
  12. package/dist/code/regions.js +12 -8
  13. package/dist/code/regions.js.map +1 -1
  14. package/dist/code/vueBlocks.d.ts +3 -0
  15. package/dist/code/vueBlocks.d.ts.map +1 -0
  16. package/dist/code/vueBlocks.js +29 -0
  17. package/dist/code/vueBlocks.js.map +1 -0
  18. package/dist/demos/build.d.ts +5 -2
  19. package/dist/demos/build.d.ts.map +1 -1
  20. package/dist/demos/build.js +244 -85
  21. package/dist/demos/build.js.map +1 -1
  22. package/dist/demos/compile/core.d.ts +9 -1
  23. package/dist/demos/compile/core.d.ts.map +1 -1
  24. package/dist/demos/compile/core.js +19 -8
  25. package/dist/demos/compile/core.js.map +1 -1
  26. package/dist/demos/compile/vue.d.ts +107 -0
  27. package/dist/demos/compile/vue.d.ts.map +1 -0
  28. package/dist/demos/compile/vue.js +187 -0
  29. package/dist/demos/compile/vue.js.map +1 -0
  30. package/dist/demos/config.d.ts +41 -7
  31. package/dist/demos/config.d.ts.map +1 -1
  32. package/dist/demos/config.js.map +1 -1
  33. package/dist/demos/index.d.ts +3 -2
  34. package/dist/demos/index.d.ts.map +1 -1
  35. package/dist/demos/index.js +1 -0
  36. package/dist/demos/index.js.map +1 -1
  37. package/dist/demos/pages.d.ts +1 -1
  38. package/dist/demos/pages.d.ts.map +1 -1
  39. package/dist/demos/pages.js +4 -1
  40. package/dist/demos/pages.js.map +1 -1
  41. package/dist/demos/runtime/vue.d.ts +3 -0
  42. package/dist/demos/runtime/vue.d.ts.map +1 -0
  43. package/dist/demos/runtime/vue.js +15 -0
  44. package/dist/demos/runtime/vue.js.map +1 -0
  45. package/dist/demos/vendor.d.ts +5 -1
  46. package/dist/demos/vendor.d.ts.map +1 -1
  47. package/dist/demos/vendor.js +6 -2
  48. package/dist/demos/vendor.js.map +1 -1
  49. package/dist/demos/worker/compile.worker.js +3 -22
  50. package/dist/demos/worker/compile.worker.js.map +1 -1
  51. package/dist/demos/worker/compileVue.worker.d.ts +2 -0
  52. package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
  53. package/dist/demos/worker/compileVue.worker.js +11 -0
  54. package/dist/demos/worker/compileVue.worker.js.map +1 -0
  55. package/dist/demos/worker/start.d.ts +7 -0
  56. package/dist/demos/worker/start.d.ts.map +1 -0
  57. package/dist/demos/worker/start.js +27 -0
  58. package/dist/demos/worker/start.js.map +1 -0
  59. package/dist/fork/codesandbox.d.ts +19 -1
  60. package/dist/fork/codesandbox.d.ts.map +1 -1
  61. package/dist/fork/codesandbox.js +35 -22
  62. package/dist/fork/codesandbox.js.map +1 -1
  63. package/dist/fork/index.d.ts +30 -0
  64. package/dist/fork/index.d.ts.map +1 -1
  65. package/dist/fork/index.js +37 -0
  66. package/dist/fork/index.js.map +1 -1
  67. package/dist/fork/stackblitz.d.ts +18 -0
  68. package/dist/fork/stackblitz.d.ts.map +1 -0
  69. package/dist/fork/stackblitz.js +98 -0
  70. package/dist/fork/stackblitz.js.map +1 -0
  71. package/dist/frameworks/index.d.ts +4 -0
  72. package/dist/frameworks/index.d.ts.map +1 -0
  73. package/dist/frameworks/index.js +4 -0
  74. package/dist/frameworks/index.js.map +1 -0
  75. package/dist/frameworks/preference.d.ts +10 -0
  76. package/dist/frameworks/preference.d.ts.map +1 -0
  77. package/dist/frameworks/preference.js +34 -0
  78. package/dist/frameworks/preference.js.map +1 -0
  79. package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
  80. package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
  81. package/dist/frameworks/react/FrameworkBanner.js +50 -0
  82. package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
  83. package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
  84. package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
  85. package/dist/frameworks/react/FrameworkContent.js +25 -0
  86. package/dist/frameworks/react/FrameworkContent.js.map +1 -0
  87. package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
  88. package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
  89. package/dist/frameworks/react/FrameworkLinks.js +50 -0
  90. package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
  91. package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
  92. package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
  93. package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
  94. package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
  95. package/dist/frameworks/react/index.d.ts +6 -0
  96. package/dist/frameworks/react/index.d.ts.map +1 -0
  97. package/dist/frameworks/react/index.js +6 -0
  98. package/dist/frameworks/react/index.js.map +1 -0
  99. package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
  100. package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
  101. package/dist/frameworks/react/useFrameworkPreference.js +45 -0
  102. package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
  103. package/dist/frameworks/routeTree.d.ts +24 -0
  104. package/dist/frameworks/routeTree.d.ts.map +1 -0
  105. package/dist/frameworks/routeTree.js +31 -0
  106. package/dist/frameworks/routeTree.js.map +1 -0
  107. package/dist/frameworks/routing.d.ts +105 -0
  108. package/dist/frameworks/routing.d.ts.map +1 -0
  109. package/dist/frameworks/routing.js +142 -0
  110. package/dist/frameworks/routing.js.map +1 -0
  111. package/dist/frameworks/styles.css +104 -0
  112. package/dist/react/Demo.d.ts +12 -0
  113. package/dist/react/Demo.d.ts.map +1 -1
  114. package/dist/react/Demo.js +10 -4
  115. package/dist/react/Demo.js.map +1 -1
  116. package/dist/react/DemoShell.d.ts +5 -1
  117. package/dist/react/DemoShell.d.ts.map +1 -1
  118. package/dist/react/DemoShell.js +9 -6
  119. package/dist/react/DemoShell.js.map +1 -1
  120. package/dist/react/editor.d.ts.map +1 -1
  121. package/dist/react/editor.js +3 -0
  122. package/dist/react/editor.js.map +1 -1
  123. package/dist/react/fork.d.ts +4 -3
  124. package/dist/react/fork.d.ts.map +1 -1
  125. package/dist/react/fork.js +8 -6
  126. package/dist/react/fork.js.map +1 -1
  127. package/dist/react/styles.css +10 -0
  128. package/dist/remark/index.d.ts +2 -0
  129. package/dist/remark/index.d.ts.map +1 -1
  130. package/dist/remark/index.js +2 -0
  131. package/dist/remark/index.js.map +1 -1
  132. package/dist/remark/remarkDemoFences.d.ts +13 -0
  133. package/dist/remark/remarkDemoFences.d.ts.map +1 -1
  134. package/dist/remark/remarkDemoFences.js +48 -4
  135. package/dist/remark/remarkDemoFences.js.map +1 -1
  136. package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
  137. package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
  138. package/dist/remark/remarkFrameworkLinks.js +77 -0
  139. package/dist/remark/remarkFrameworkLinks.js.map +1 -0
  140. package/dist/remark/remarkFrameworkText.d.ts +16 -0
  141. package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
  142. package/dist/remark/remarkFrameworkText.js +39 -0
  143. package/dist/remark/remarkFrameworkText.js.map +1 -0
  144. package/package.json +29 -4
  145. package/src/code/demoFiles.ts +2 -2
  146. package/src/code/index.ts +1 -0
  147. package/src/code/regions.ts +14 -8
  148. package/src/code/vueBlocks.ts +25 -0
  149. package/src/demos/build.ts +293 -99
  150. package/src/demos/compile/core.ts +27 -7
  151. package/src/demos/compile/vue.ts +259 -0
  152. package/src/demos/config.ts +59 -7
  153. package/src/demos/index.ts +13 -0
  154. package/src/demos/pages.ts +4 -2
  155. package/src/demos/runtime/vue.ts +17 -0
  156. package/src/demos/vendor.ts +6 -2
  157. package/src/demos/worker/compile.worker.ts +3 -30
  158. package/src/demos/worker/compileVue.worker.ts +13 -0
  159. package/src/demos/worker/start.ts +35 -0
  160. package/src/fork/codesandbox.ts +51 -24
  161. package/src/fork/index.ts +56 -0
  162. package/src/fork/stackblitz.ts +108 -0
  163. package/src/frameworks/index.ts +21 -0
  164. package/src/frameworks/preference.ts +35 -0
  165. package/src/frameworks/react/FrameworkBanner.tsx +112 -0
  166. package/src/frameworks/react/FrameworkContent.tsx +33 -0
  167. package/src/frameworks/react/FrameworkLinks.tsx +52 -0
  168. package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
  169. package/src/frameworks/react/index.ts +10 -0
  170. package/src/frameworks/react/useFrameworkPreference.ts +91 -0
  171. package/src/frameworks/routeTree.ts +54 -0
  172. package/src/frameworks/routing.ts +194 -0
  173. package/src/frameworks/styles.css +104 -0
  174. package/src/react/Demo.tsx +21 -2
  175. package/src/react/DemoShell.tsx +15 -7
  176. package/src/react/editor.ts +2 -0
  177. package/src/react/fork.ts +14 -6
  178. package/src/react/styles.css +10 -0
  179. package/src/remark/index.ts +6 -0
  180. package/src/remark/remarkDemoFences.ts +58 -3
  181. package/src/remark/remarkFrameworkLinks.ts +96 -0
  182. package/src/remark/remarkFrameworkText.ts +44 -0
@@ -252,6 +252,16 @@
252
252
  font-family: var(--dk-font-mono);
253
253
  font-size: 11.5px;
254
254
  }
255
+ /* e.g. "React only for now": the demo has no version for the page's framework */
256
+ .dk-demo-notice {
257
+ padding: 2px 8px;
258
+ border: 1px solid var(--dk-border);
259
+ border-radius: 999px;
260
+ color: var(--dk-muted);
261
+ font-family: var(--dk-font-sans);
262
+ font-size: 11.5px;
263
+ white-space: nowrap;
264
+ }
255
265
  .dk-demo-status {
256
266
  padding: 0 6px;
257
267
  font-family: var(--dk-font-mono);
@@ -1,2 +1,8 @@
1
1
  export { remarkDemoFences, type FenceInfo, type RemarkDemoFencesOptions } from './remarkDemoFences.ts';
2
2
  export { applyFenceDefaults, parseFenceMeta, type FenceDefaults, type FenceProps } from './meta.ts';
3
+ export {
4
+ FALLBACK_LINK_ATTRIBUTE,
5
+ remarkFrameworkLinks,
6
+ type RemarkFrameworkLinksOptions,
7
+ } from './remarkFrameworkLinks.ts';
8
+ export { remarkFrameworkText, type RemarkFrameworkTextOptions } from './remarkFrameworkText.ts';
@@ -7,6 +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 { vueBlockLang } from '../code/vueBlocks.ts';
10
11
  import { applyFenceDefaults, parseFenceMeta, type FenceDefaults, type FenceProps } from './meta.ts';
11
12
 
12
13
  export type FenceInfo = {
@@ -62,8 +63,30 @@ export type RemarkDemoFencesOptions = {
62
63
  fenceDefaults?: FenceDefaults;
63
64
  /** `height` of a live fence that sets none (and no `fenceDefaults.demos.height`). Default `auto`. */
64
65
  liveHeight?: string;
66
+ /**
67
+ * For a page rendered in another framework than the one its fences name:
68
+ * `foo.demo.tsx` → the sibling `foo.demo.vue`. Maps the suffix a fence
69
+ * names to the sibling suffixes to try, in order, e.g.
70
+ * `{ '.demo.tsx': '.demo.vue', '.snippet.tsx': ['.snippet.vue', '.snippet.vue.ts'] }`.
71
+ *
72
+ * A fence with a sibling shows it (the sibling suffixes of demo entries
73
+ * count as demo suffixes). One without keeps its file and is marked as a
74
+ * fallback: `<Demo fallback="true">`, which shows the page's notice
75
+ * ("React only for now"). A fence whose code is the same for every
76
+ * framework opts out with `neutral`.
77
+ */
78
+ siblings?: Record<string, string | string[]>;
65
79
  };
66
80
 
81
+ const asList = (value: string | string[]) => (Array.isArray(value) ? value : [value]);
82
+
83
+ /** Shiki language of a sibling file; a region of a `.vue` file is highlighted as its block. */
84
+ function siblingLang(file: string, source: string, firstLine: number | undefined): string | null {
85
+ if (/\.vue$/.test(file)) return firstLine == null ? 'vue' : vueBlockLang(source, firstLine);
86
+ const ext = /\.([cm]?[jt]sx?)$/.exec(file)?.[1];
87
+ return ext ? ext.replace(/^[cm]/, '') : null;
88
+ }
89
+
67
90
  const TYPECHECKED_LANGS = new Set(['ts', 'tsx', 'js', 'jsx', 'typescript', 'javascript']);
68
91
 
69
92
  type MdxAttribute = { type: 'mdxJsxAttribute'; name: string; value: string };
@@ -126,7 +149,12 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
126
149
  sourceReplacements,
127
150
  fenceDefaults,
128
151
  liveHeight = 'auto',
152
+ siblings,
129
153
  } = options;
154
+ const liveSuffixes = [...demoSuffixes];
155
+ for (const suffix of demoSuffixes) {
156
+ for (const sibling of asList(siblings?.[suffix] ?? [])) if (!liveSuffixes.includes(sibling)) liveSuffixes.push(sibling);
157
+ }
130
158
  const folder = options.folder.replace(/^\/+|\/+$/g, '');
131
159
  const pageDir = path.join(contentDir, folder);
132
160
  /** `/docs/x.tsx` is relative to the content root, anything else to the page. */
@@ -158,6 +186,27 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
158
186
  );
159
187
  }
160
188
 
189
+ // the page's framework: show the sibling file, or mark the fence as a fallback
190
+ let fallback = false;
191
+ let isSibling = false;
192
+ const named = props.file;
193
+ const siblingOf = typeof named === 'string' && siblings && !props.neutral
194
+ ? Object.keys(siblings).find((suffix) => named.endsWith(suffix))
195
+ : undefined;
196
+ if (typeof named === 'string' && siblingOf) {
197
+ const stem = named.slice(0, -siblingOf.length);
198
+ const found = asList(siblings![siblingOf]).find((suffix) => {
199
+ const candidate = resolveFile(stem + suffix);
200
+ return fs.existsSync(candidate) && fs.statSync(candidate).isFile();
201
+ });
202
+ if (found) {
203
+ props.file = stem + found;
204
+ isSibling = true;
205
+ } else {
206
+ fallback = true;
207
+ }
208
+ }
209
+
161
210
  const file = props.file;
162
211
  if (props.live && !('height' in props)) props.height = liveHeight;
163
212
  if ('range' in props) {
@@ -196,12 +245,16 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
196
245
  }
197
246
 
198
247
  let originalLines: number[] | undefined;
248
+ const fullSource = source;
199
249
  if (typeof props.region === 'string') {
200
250
  if (typeof file !== 'string') throw new Error(`${context}: \`region\` requires \`file="..."\``);
201
251
  const sliced = sliceRegion(source, props.region, context);
202
252
  source = sliced.source;
203
253
  originalLines = sliced.originalLines;
204
254
  }
255
+ if (isSibling && typeof file === 'string') {
256
+ node.lang = siblingLang(file, fullSource, originalLines?.[0]) ?? node.lang;
257
+ }
205
258
 
206
259
  // Live demos strip markers per file in <Demo>.
207
260
  let highlight: string | null = null;
@@ -224,11 +277,11 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
224
277
  `\`live=off\` (preview available, code shown first)`,
225
278
  );
226
279
  }
227
- const suffix = typeof file === 'string' ? demoSuffixes.find((s) => file.endsWith(s)) : undefined;
280
+ const suffix = typeof file === 'string' ? liveSuffixes.find((s) => file.endsWith(s)) : undefined;
228
281
  const fromRoot = typeof file === 'string' ? path.relative(contentDir, resolveFile(file)) : '..';
229
282
  if (typeof file !== 'string' || !suffix || fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) {
230
283
  throw new Error(
231
- `${context}: live demos must reference a ${demoSuffixes.map((s) => `*${s}`).join(' / ')} ` +
284
+ `${context}: live demos must reference a ${liveSuffixes.map((s) => `*${s}`).join(' / ')} ` +
232
285
  `file inside the content folder (it has to match a prebuilt demo bundle)`,
233
286
  );
234
287
  }
@@ -243,6 +296,7 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
243
296
  else if (typeof props.title === 'string') attrs.title = props.title;
244
297
  if (props.lines) attrs.lines = 'true';
245
298
  if (props.edit === 'off') attrs.editable = 'false';
299
+ if (fallback) attrs.fallback = 'true';
246
300
 
247
301
  if (inDemo) {
248
302
  assertSingleSnippet(parent, context);
@@ -263,6 +317,7 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
263
317
  if (highlight) attrs.highlight = highlight;
264
318
  if (props.lines) attrs.lines = 'true';
265
319
  if (originalLinesAttr) attrs.originalLines = originalLinesAttr;
320
+ if (fallback) attrs.fallback = 'true';
266
321
  return attrs;
267
322
  };
268
323
 
@@ -300,7 +355,7 @@ export function remarkDemoFences(options: RemarkDemoFencesOptions) {
300
355
  ]
301
356
  .filter(Boolean)
302
357
  .join(' ') || null;
303
- node.data = { ...node.data, docsKit: true };
358
+ node.data = { ...node.data, docsKit: true, ...(fallback ? { docsKitFallback: true } : null) };
304
359
  });
305
360
  };
306
361
  }
@@ -0,0 +1,96 @@
1
+ import { visit } from 'unist-util-visit';
2
+
3
+ import { resolveFrameworkLink, splitHref, type Frameworks, type HasPage } from '../frameworks/routing.ts';
4
+
5
+ export type RemarkFrameworkLinksOptions<Id extends string = string> = {
6
+ frameworks: Frameworks<Id>;
7
+ /** The framework the page is rendered for. */
8
+ framework: Id;
9
+ hasPage: HasPage<Id>;
10
+ /**
11
+ * Internal links outside the framework roots (`/pricing`, `/blog/x`,
12
+ * `/logo.svg`): return `false` to fail the build. Default: accepted.
13
+ */
14
+ isValidSharedLink?: (pathname: string) => boolean;
15
+ /**
16
+ * JSX attributes that hold links, by component: `{ Card: ['path'] }`. A
17
+ * fallback sets `frameworkFallback="<framework>"` on the element.
18
+ */
19
+ jsxAttributes?: Record<string, string[]>;
20
+ /** The page's file, for error messages. */
21
+ file?: string;
22
+ };
23
+
24
+ /** The attribute a fallback link carries: the framework it goes to instead. */
25
+ export const FALLBACK_LINK_ATTRIBUTE = 'data-framework-fallback';
26
+
27
+ /**
28
+ * Links in the docs are written once, in the default framework's form
29
+ * (`/docs/learn/sorting`). This plugin points them at the page's framework:
30
+ *
31
+ * - the page exists there: `/vue/docs/learn/sorting`;
32
+ * - it doesn't: the link goes to a framework that has it and is marked with
33
+ * `data-framework-fallback="react"`, so the site can show a badge
34
+ * ("React only for now");
35
+ * - no framework has it: the build fails.
36
+ *
37
+ * Covers markdown links, link definitions and the configured JSX attributes.
38
+ * External links and `#hash` links are left alone.
39
+ */
40
+ export function remarkFrameworkLinks<Id extends string>(options: RemarkFrameworkLinksOptions<Id>) {
41
+ const { frameworks, framework, hasPage, isValidSharedLink, jsxAttributes = {}, file } = options;
42
+ const where = file ? `, found in ${file}` : '';
43
+
44
+ /** The rewritten URL and, for a fallback, its framework. `null`: not an internal link. */
45
+ const resolve = (url: unknown): { url: string; fallback: Id | null } | null => {
46
+ if (typeof url !== 'string' || !url.startsWith('/') || url.startsWith('//')) return null;
47
+ const link = resolveFrameworkLink(frameworks, url, framework, hasPage);
48
+ switch (link.kind) {
49
+ case 'shared':
50
+ if (isValidSharedLink && !isValidSharedLink(splitHref(url)[0])) {
51
+ throw new Error(`Link not valid: "${url}"${where}.`);
52
+ }
53
+ return null;
54
+ case 'page':
55
+ return { url: link.href, fallback: null };
56
+ case 'fallback':
57
+ return { url: link.href, fallback: link.framework };
58
+ case 'missing':
59
+ throw new Error(
60
+ `Link not valid: "${url}"${where}: no page at "${link.neutralPath}" in any framework ` +
61
+ `(${frameworks.ids.join(', ')}).`,
62
+ );
63
+ }
64
+ };
65
+
66
+ return () => (tree: any) => {
67
+ visit(tree, (node: any) => {
68
+ if (node.type === 'link' || node.type === 'definition') {
69
+ const resolved = resolve(node.url);
70
+ if (!resolved) return;
71
+ node.url = resolved.url;
72
+ if (resolved.fallback && node.type === 'link') {
73
+ node.data = {
74
+ ...node.data,
75
+ hProperties: { ...node.data?.hProperties, [FALLBACK_LINK_ATTRIBUTE]: resolved.fallback },
76
+ };
77
+ }
78
+ return;
79
+ }
80
+ if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement') return;
81
+ const names = node.name ? jsxAttributes[node.name] : undefined;
82
+ if (!names) return;
83
+ let fallback: Id | null = null;
84
+ for (const attribute of node.attributes ?? []) {
85
+ if (attribute.type !== 'mdxJsxAttribute' || !names.includes(attribute.name)) continue;
86
+ const resolved = resolve(attribute.value);
87
+ if (!resolved) continue;
88
+ attribute.value = resolved.url;
89
+ fallback ??= resolved.fallback;
90
+ }
91
+ if (fallback && !node.attributes.some((attribute: any) => attribute.name === 'frameworkFallback')) {
92
+ node.attributes.push({ type: 'mdxJsxAttribute', name: 'frameworkFallback', value: fallback });
93
+ }
94
+ });
95
+ };
96
+ }
@@ -0,0 +1,44 @@
1
+ import { visit } from 'unist-util-visit';
2
+
3
+ export type RemarkFrameworkTextOptions = {
4
+ /**
5
+ * Literal replacements for a page rendered in another framework than it
6
+ * was written for, e.g. `{ '@acme/grid-react': '@acme/grid-vue' }`.
7
+ */
8
+ replacements: Record<string, string>;
9
+ };
10
+
11
+ /**
12
+ * Applies literal replacements to a page's prose: text, inline code, fenced
13
+ * code written in the page, and link URLs. The package name in
14
+ * `npm i @acme/grid-react` is right on the Vue page without a second copy of
15
+ * the sentence. Fences that show a file (`file="…"`) are left alone: their
16
+ * code comes from that file, or its sibling.
17
+ */
18
+ export function remarkFrameworkText(options: RemarkFrameworkTextOptions) {
19
+ const pairs = Object.entries(options.replacements).filter(([search]) => search);
20
+ const replace = (value: string) => {
21
+ let result = value;
22
+ for (const [search, replacement] of pairs) result = result.split(search).join(replacement);
23
+ return result;
24
+ };
25
+
26
+ return () => (tree: any) => {
27
+ if (!pairs.length) return;
28
+ visit(tree, (node: any) => {
29
+ switch (node.type) {
30
+ case 'text':
31
+ case 'inlineCode':
32
+ node.value = replace(node.value);
33
+ break;
34
+ case 'code':
35
+ if (!/\bfile=/.test(node.meta ?? '')) node.value = replace(node.value);
36
+ break;
37
+ case 'link':
38
+ case 'definition':
39
+ if (typeof node.url === 'string') node.url = replace(node.url);
40
+ break;
41
+ }
42
+ });
43
+ };
44
+ }