@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.
- package/CHANGELOG.md +27 -0
- package/README.md +172 -4
- package/dist/code/demoFiles.d.ts.map +1 -1
- package/dist/code/demoFiles.js +2 -2
- package/dist/code/demoFiles.js.map +1 -1
- package/dist/code/index.d.ts +1 -0
- package/dist/code/index.d.ts.map +1 -1
- package/dist/code/index.js +1 -0
- package/dist/code/index.js.map +1 -1
- package/dist/code/regions.d.ts +2 -1
- package/dist/code/regions.d.ts.map +1 -1
- package/dist/code/regions.js +12 -8
- package/dist/code/regions.js.map +1 -1
- package/dist/code/vueBlocks.d.ts +3 -0
- package/dist/code/vueBlocks.d.ts.map +1 -0
- package/dist/code/vueBlocks.js +29 -0
- package/dist/code/vueBlocks.js.map +1 -0
- package/dist/demos/build.d.ts +5 -2
- package/dist/demos/build.d.ts.map +1 -1
- package/dist/demos/build.js +244 -85
- package/dist/demos/build.js.map +1 -1
- package/dist/demos/compile/core.d.ts +9 -1
- package/dist/demos/compile/core.d.ts.map +1 -1
- package/dist/demos/compile/core.js +19 -8
- package/dist/demos/compile/core.js.map +1 -1
- package/dist/demos/compile/vue.d.ts +107 -0
- package/dist/demos/compile/vue.d.ts.map +1 -0
- package/dist/demos/compile/vue.js +187 -0
- package/dist/demos/compile/vue.js.map +1 -0
- package/dist/demos/config.d.ts +41 -7
- package/dist/demos/config.d.ts.map +1 -1
- package/dist/demos/config.js.map +1 -1
- package/dist/demos/index.d.ts +3 -2
- package/dist/demos/index.d.ts.map +1 -1
- package/dist/demos/index.js +1 -0
- package/dist/demos/index.js.map +1 -1
- package/dist/demos/pages.d.ts +1 -1
- package/dist/demos/pages.d.ts.map +1 -1
- package/dist/demos/pages.js +4 -1
- package/dist/demos/pages.js.map +1 -1
- package/dist/demos/runtime/vue.d.ts +3 -0
- package/dist/demos/runtime/vue.d.ts.map +1 -0
- package/dist/demos/runtime/vue.js +15 -0
- package/dist/demos/runtime/vue.js.map +1 -0
- package/dist/demos/vendor.d.ts +5 -1
- package/dist/demos/vendor.d.ts.map +1 -1
- package/dist/demos/vendor.js +6 -2
- package/dist/demos/vendor.js.map +1 -1
- package/dist/demos/worker/compile.worker.js +3 -22
- package/dist/demos/worker/compile.worker.js.map +1 -1
- package/dist/demos/worker/compileVue.worker.d.ts +2 -0
- package/dist/demos/worker/compileVue.worker.d.ts.map +1 -0
- package/dist/demos/worker/compileVue.worker.js +11 -0
- package/dist/demos/worker/compileVue.worker.js.map +1 -0
- package/dist/demos/worker/start.d.ts +7 -0
- package/dist/demos/worker/start.d.ts.map +1 -0
- package/dist/demos/worker/start.js +27 -0
- package/dist/demos/worker/start.js.map +1 -0
- package/dist/fork/codesandbox.d.ts +19 -1
- package/dist/fork/codesandbox.d.ts.map +1 -1
- package/dist/fork/codesandbox.js +35 -22
- package/dist/fork/codesandbox.js.map +1 -1
- package/dist/fork/index.d.ts +30 -0
- package/dist/fork/index.d.ts.map +1 -1
- package/dist/fork/index.js +37 -0
- package/dist/fork/index.js.map +1 -1
- package/dist/fork/stackblitz.d.ts +18 -0
- package/dist/fork/stackblitz.d.ts.map +1 -0
- package/dist/fork/stackblitz.js +98 -0
- package/dist/fork/stackblitz.js.map +1 -0
- package/dist/frameworks/index.d.ts +4 -0
- package/dist/frameworks/index.d.ts.map +1 -0
- package/dist/frameworks/index.js +4 -0
- package/dist/frameworks/index.js.map +1 -0
- package/dist/frameworks/preference.d.ts +10 -0
- package/dist/frameworks/preference.d.ts.map +1 -0
- package/dist/frameworks/preference.js +34 -0
- package/dist/frameworks/preference.js.map +1 -0
- package/dist/frameworks/react/FrameworkBanner.d.ts +34 -0
- package/dist/frameworks/react/FrameworkBanner.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkBanner.js +50 -0
- package/dist/frameworks/react/FrameworkBanner.js.map +1 -0
- package/dist/frameworks/react/FrameworkContent.d.ts +21 -0
- package/dist/frameworks/react/FrameworkContent.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkContent.js +25 -0
- package/dist/frameworks/react/FrameworkContent.js.map +1 -0
- package/dist/frameworks/react/FrameworkLinks.d.ts +16 -0
- package/dist/frameworks/react/FrameworkLinks.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkLinks.js +50 -0
- package/dist/frameworks/react/FrameworkLinks.js.map +1 -0
- package/dist/frameworks/react/FrameworkSwitcher.d.ts +27 -0
- package/dist/frameworks/react/FrameworkSwitcher.d.ts.map +1 -0
- package/dist/frameworks/react/FrameworkSwitcher.js +42 -0
- package/dist/frameworks/react/FrameworkSwitcher.js.map +1 -0
- package/dist/frameworks/react/index.d.ts +6 -0
- package/dist/frameworks/react/index.d.ts.map +1 -0
- package/dist/frameworks/react/index.js +6 -0
- package/dist/frameworks/react/index.js.map +1 -0
- package/dist/frameworks/react/useFrameworkPreference.d.ts +32 -0
- package/dist/frameworks/react/useFrameworkPreference.d.ts.map +1 -0
- package/dist/frameworks/react/useFrameworkPreference.js +45 -0
- package/dist/frameworks/react/useFrameworkPreference.js.map +1 -0
- package/dist/frameworks/routeTree.d.ts +24 -0
- package/dist/frameworks/routeTree.d.ts.map +1 -0
- package/dist/frameworks/routeTree.js +31 -0
- package/dist/frameworks/routeTree.js.map +1 -0
- package/dist/frameworks/routing.d.ts +105 -0
- package/dist/frameworks/routing.d.ts.map +1 -0
- package/dist/frameworks/routing.js +142 -0
- package/dist/frameworks/routing.js.map +1 -0
- package/dist/frameworks/styles.css +104 -0
- package/dist/react/Demo.d.ts +12 -0
- package/dist/react/Demo.d.ts.map +1 -1
- package/dist/react/Demo.js +10 -4
- package/dist/react/Demo.js.map +1 -1
- package/dist/react/DemoShell.d.ts +5 -1
- package/dist/react/DemoShell.d.ts.map +1 -1
- package/dist/react/DemoShell.js +9 -6
- package/dist/react/DemoShell.js.map +1 -1
- package/dist/react/editor.d.ts.map +1 -1
- package/dist/react/editor.js +3 -0
- package/dist/react/editor.js.map +1 -1
- package/dist/react/fork.d.ts +4 -3
- package/dist/react/fork.d.ts.map +1 -1
- package/dist/react/fork.js +8 -6
- package/dist/react/fork.js.map +1 -1
- package/dist/react/styles.css +10 -0
- package/dist/remark/index.d.ts +2 -0
- package/dist/remark/index.d.ts.map +1 -1
- package/dist/remark/index.js +2 -0
- package/dist/remark/index.js.map +1 -1
- package/dist/remark/remarkDemoFences.d.ts +13 -0
- package/dist/remark/remarkDemoFences.d.ts.map +1 -1
- package/dist/remark/remarkDemoFences.js +48 -4
- package/dist/remark/remarkDemoFences.js.map +1 -1
- package/dist/remark/remarkFrameworkLinks.d.ts +36 -0
- package/dist/remark/remarkFrameworkLinks.d.ts.map +1 -0
- package/dist/remark/remarkFrameworkLinks.js +77 -0
- package/dist/remark/remarkFrameworkLinks.js.map +1 -0
- package/dist/remark/remarkFrameworkText.d.ts +16 -0
- package/dist/remark/remarkFrameworkText.d.ts.map +1 -0
- package/dist/remark/remarkFrameworkText.js +39 -0
- package/dist/remark/remarkFrameworkText.js.map +1 -0
- package/package.json +29 -4
- package/src/code/demoFiles.ts +2 -2
- package/src/code/index.ts +1 -0
- package/src/code/regions.ts +14 -8
- package/src/code/vueBlocks.ts +25 -0
- package/src/demos/build.ts +293 -99
- package/src/demos/compile/core.ts +27 -7
- package/src/demos/compile/vue.ts +259 -0
- package/src/demos/config.ts +59 -7
- package/src/demos/index.ts +13 -0
- package/src/demos/pages.ts +4 -2
- package/src/demos/runtime/vue.ts +17 -0
- package/src/demos/vendor.ts +6 -2
- package/src/demos/worker/compile.worker.ts +3 -30
- package/src/demos/worker/compileVue.worker.ts +13 -0
- package/src/demos/worker/start.ts +35 -0
- package/src/fork/codesandbox.ts +51 -24
- package/src/fork/index.ts +56 -0
- package/src/fork/stackblitz.ts +108 -0
- package/src/frameworks/index.ts +21 -0
- package/src/frameworks/preference.ts +35 -0
- package/src/frameworks/react/FrameworkBanner.tsx +112 -0
- package/src/frameworks/react/FrameworkContent.tsx +33 -0
- package/src/frameworks/react/FrameworkLinks.tsx +52 -0
- package/src/frameworks/react/FrameworkSwitcher.tsx +78 -0
- package/src/frameworks/react/index.ts +10 -0
- package/src/frameworks/react/useFrameworkPreference.ts +91 -0
- package/src/frameworks/routeTree.ts +54 -0
- package/src/frameworks/routing.ts +194 -0
- package/src/frameworks/styles.css +104 -0
- package/src/react/Demo.tsx +21 -2
- package/src/react/DemoShell.tsx +15 -7
- package/src/react/editor.ts +2 -0
- package/src/react/fork.ts +14 -6
- package/src/react/styles.css +10 -0
- package/src/remark/index.ts +6 -0
- package/src/remark/remarkDemoFences.ts +58 -3
- package/src/remark/remarkFrameworkLinks.ts +96 -0
- package/src/remark/remarkFrameworkText.ts +44 -0
package/src/react/styles.css
CHANGED
|
@@ -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);
|
package/src/remark/index.ts
CHANGED
|
@@ -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' ?
|
|
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 ${
|
|
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
|
+
}
|