@mui/internal-docs-infra 0.13.1-canary.26 → 0.13.1-canary.28
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/abstractCreateTypes/abstractCreateTypes.d.mts +5 -0
- package/abstractCreateTypes/abstractCreateTypes.mjs +31 -87
- package/package.json +2 -2
- package/pipeline/enhanceCodeTypes/enhanceChildren.d.mts +8 -0
- package/pipeline/enhanceCodeTypes/enhanceChildren.mjs +51 -1
- package/pipeline/enhanceCodeTypes/enhanceCodeTypes.d.mts +9 -0
- package/pipeline/enhanceCodeTypes/enhanceCodeTypes.mjs +8 -8
- package/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.mjs +74 -9
- package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.mjs +2 -1
- package/pipeline/loadServerTypes/loadServerTypes.d.mts +5 -0
- package/pipeline/loadServerTypes/loadServerTypes.mjs +2 -1
- package/pipeline/loadServerTypesMeta/externalTypes.d.mts +23 -0
- package/pipeline/loadServerTypesMeta/externalTypes.mjs +52 -1
- package/pipeline/loadServerTypesMeta/formatType.d.mts +1 -1
- package/pipeline/loadServerTypesMeta/formatType.mjs +44 -13
- package/pipeline/loadServerTypesMeta/loadServerTypesMeta.d.mts +5 -0
- package/pipeline/loadServerTypesMeta/loadServerTypesMeta.mjs +11 -0
- package/pipeline/loadServerTypesMeta/mdnTypeLinks.d.mts +6 -0
- package/pipeline/loadServerTypesMeta/mdnTypeLinks.mjs +144 -0
- package/pipeline/loadServerTypesMeta/parseTestSources.d.mts +6 -1
- package/pipeline/loadServerTypesMeta/parseTestSources.mjs +6 -4
- package/pipeline/loadServerTypesText/loadServerTypesText.d.mts +2 -0
- package/pipeline/loadServerTypesText/normalizeTypesSourceDataForCache.mjs +1 -0
- package/pipeline/loadServerTypesText/parseTypesMarkdown.d.mts +1 -0
- package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs +12 -2
- package/pipeline/syncTypes/generateTypesMarkdown.d.mts +2 -0
- package/pipeline/syncTypes/generateTypesMarkdown.mjs +9 -0
- package/pipeline/syncTypes/syncTypes.mjs +4 -0
- package/useDemo/exportVariant.d.mts +4 -3
- package/useDemo/exportVariant.mjs +13 -8
|
@@ -47,6 +47,11 @@ export type TypesTableMeta = {
|
|
|
47
47
|
js?: Record<string, string>;
|
|
48
48
|
css?: Record<string, string>;
|
|
49
49
|
};
|
|
50
|
+
/**
|
|
51
|
+
* Links for the built-in types on the page, such as `HTMLElement` to its MDN page,
|
|
52
|
+
* keyed by the name they are printed as. Used by enhanceCodeTypes.
|
|
53
|
+
*/
|
|
54
|
+
externalTypeLinks?: Record<string, string>;
|
|
50
55
|
};
|
|
51
56
|
name?: string;
|
|
52
57
|
displayName?: string;
|
|
@@ -5,7 +5,8 @@ import { typeToJsx, additionalTypesToJsx } from "./typesToJsx.mjs";
|
|
|
5
5
|
import { jsx as _jsx } from "react/jsx-runtime";
|
|
6
6
|
/**
|
|
7
7
|
* Default enhancers applied when no enhancers are specified.
|
|
8
|
-
* Note: enhanceCodeTypes is added dynamically when
|
|
8
|
+
* Note: enhanceCodeTypes is added dynamically when the page has anchors to link, or external
|
|
9
|
+
* types to link to their docs.
|
|
9
10
|
*/
|
|
10
11
|
const DEFAULT_ENHANCERS = [enhanceCodeInline];
|
|
11
12
|
|
|
@@ -21,6 +22,33 @@ const DEFAULT_ENHANCERS_INLINE = [enhanceCodeInline];
|
|
|
21
22
|
* Used in the precompute field for structured type data.
|
|
22
23
|
*/
|
|
23
24
|
|
|
25
|
+
/**
|
|
26
|
+
* Resolves the enhancers for type fields: `meta.enhancers`, `options.enhancers`, or the
|
|
27
|
+
* defaults, followed by `enhanceCodeTypes` when the page has anchors or external type links.
|
|
28
|
+
* Meta settings override factory options.
|
|
29
|
+
*/
|
|
30
|
+
function resolveEnhancers(options, meta) {
|
|
31
|
+
const enhancers = meta.enhancers ?? options.enhancers ?? DEFAULT_ENHANCERS;
|
|
32
|
+
const anchorMap = meta.precompute?.anchorMap;
|
|
33
|
+
const externalLinks = meta.precompute?.externalTypeLinks;
|
|
34
|
+
const hasAnchors = Object.keys(anchorMap?.js ?? {}).length > 0 || Object.keys(anchorMap?.css ?? {}).length > 0;
|
|
35
|
+
if (!hasAnchors && Object.keys(externalLinks ?? {}).length === 0) {
|
|
36
|
+
return enhancers;
|
|
37
|
+
}
|
|
38
|
+
const enhanceCodeTypesOptions = {
|
|
39
|
+
linkMap: anchorMap ?? {},
|
|
40
|
+
externalLinks,
|
|
41
|
+
typeRefComponent: meta.typeRefComponent ?? options.typeRefComponent,
|
|
42
|
+
typePropRefComponent: meta.typePropRefComponent ?? options.typePropRefComponent,
|
|
43
|
+
typeParamRefComponent: meta.typeParamRefComponent ?? options.typeParamRefComponent,
|
|
44
|
+
linkProps: meta.linkProps ?? options.linkProps,
|
|
45
|
+
linkParams: meta.linkParams ?? options.linkParams,
|
|
46
|
+
linkScope: meta.linkScope ?? options.linkScope,
|
|
47
|
+
moduleLinkMap: meta.moduleLinkMap ?? options.moduleLinkMap,
|
|
48
|
+
defaultImportSlug: meta.defaultImportSlug ?? options.defaultImportSlug
|
|
49
|
+
};
|
|
50
|
+
return [...enhancers, [enhanceCodeTypes, enhanceCodeTypesOptions]];
|
|
51
|
+
}
|
|
24
52
|
export function abstractCreateTypes(options, url, meta, exportName) {
|
|
25
53
|
if (!url.startsWith('file:')) {
|
|
26
54
|
throw new Error('abstractCreateTypes() requires the `url` parameter to be a file URL. Use `import.meta.url` to get the current file URL.');
|
|
@@ -44,49 +72,7 @@ export function abstractCreateTypes(options, url, meta, exportName) {
|
|
|
44
72
|
const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
|
|
45
73
|
const RawTypePre = meta.RawTypePre ?? options.RawTypePre;
|
|
46
74
|
const highlightAt = meta.highlightAt ?? options.highlightAt;
|
|
47
|
-
|
|
48
|
-
// Enhancers from meta completely override options.enhancers if set
|
|
49
|
-
// Use DEFAULT_ENHANCERS if neither meta nor options specify enhancers
|
|
50
|
-
// Then append enhanceCodeTypes if anchorMap is available
|
|
51
|
-
let enhancers = meta.enhancers ?? options.enhancers ?? DEFAULT_ENHANCERS;
|
|
52
|
-
if (meta.precompute.anchorMap && (Object.keys(meta.precompute.anchorMap.js ?? {}).length > 0 || Object.keys(meta.precompute.anchorMap.css ?? {}).length > 0)) {
|
|
53
|
-
const typeRefComponent = meta.typeRefComponent ?? options.typeRefComponent;
|
|
54
|
-
const typePropRefComponent = meta.typePropRefComponent ?? options.typePropRefComponent;
|
|
55
|
-
const typeParamRefComponent = meta.typeParamRefComponent ?? options.typeParamRefComponent;
|
|
56
|
-
const linkProps = meta.linkProps ?? options.linkProps;
|
|
57
|
-
const linkParams = meta.linkParams ?? options.linkParams;
|
|
58
|
-
const linkScope = meta.linkScope ?? options.linkScope;
|
|
59
|
-
const moduleLinkMap = meta.moduleLinkMap ?? options.moduleLinkMap;
|
|
60
|
-
const defaultImportSlug = meta.defaultImportSlug ?? options.defaultImportSlug;
|
|
61
|
-
const exportLinksOptions = {
|
|
62
|
-
linkMap: meta.precompute.anchorMap
|
|
63
|
-
};
|
|
64
|
-
if (typeRefComponent) {
|
|
65
|
-
exportLinksOptions.typeRefComponent = typeRefComponent;
|
|
66
|
-
}
|
|
67
|
-
if (typePropRefComponent) {
|
|
68
|
-
exportLinksOptions.typePropRefComponent = typePropRefComponent;
|
|
69
|
-
}
|
|
70
|
-
if (typeParamRefComponent) {
|
|
71
|
-
exportLinksOptions.typeParamRefComponent = typeParamRefComponent;
|
|
72
|
-
}
|
|
73
|
-
if (linkProps) {
|
|
74
|
-
exportLinksOptions.linkProps = linkProps;
|
|
75
|
-
}
|
|
76
|
-
if (linkParams) {
|
|
77
|
-
exportLinksOptions.linkParams = linkParams;
|
|
78
|
-
}
|
|
79
|
-
if (linkScope) {
|
|
80
|
-
exportLinksOptions.linkScope = linkScope;
|
|
81
|
-
}
|
|
82
|
-
if (moduleLinkMap) {
|
|
83
|
-
exportLinksOptions.moduleLinkMap = moduleLinkMap;
|
|
84
|
-
}
|
|
85
|
-
if (defaultImportSlug) {
|
|
86
|
-
exportLinksOptions.defaultImportSlug = defaultImportSlug;
|
|
87
|
-
}
|
|
88
|
-
enhancers = [...enhancers, [enhanceCodeTypes, exportLinksOptions]];
|
|
89
|
-
}
|
|
75
|
+
const enhancers = resolveEnhancers(options, meta);
|
|
90
76
|
|
|
91
77
|
// Inline enhancers for shortType and default fields
|
|
92
78
|
const enhancersInline = meta.enhancersInline ?? options.enhancersInline ?? DEFAULT_ENHANCERS_INLINE;
|
|
@@ -219,49 +205,7 @@ function createAdditionalTypesComponent(options, url, meta) {
|
|
|
219
205
|
const DefaultCode = meta.DefaultCode ?? options.DefaultCode;
|
|
220
206
|
const RawTypePre = meta.RawTypePre ?? options.RawTypePre;
|
|
221
207
|
const highlightAt = meta.highlightAt ?? options.highlightAt;
|
|
222
|
-
|
|
223
|
-
// Enhancers from meta completely override options.enhancers if set
|
|
224
|
-
// Use DEFAULT_ENHANCERS if neither meta nor options specify enhancers
|
|
225
|
-
// Then append enhanceCodeTypes if anchorMap is available
|
|
226
|
-
let enhancers = meta.enhancers ?? options.enhancers ?? DEFAULT_ENHANCERS;
|
|
227
|
-
if (meta.precompute.anchorMap && (Object.keys(meta.precompute.anchorMap.js ?? {}).length > 0 || Object.keys(meta.precompute.anchorMap.css ?? {}).length > 0)) {
|
|
228
|
-
const typeRefComponent = meta.typeRefComponent ?? options.typeRefComponent;
|
|
229
|
-
const typePropRefComponent = meta.typePropRefComponent ?? options.typePropRefComponent;
|
|
230
|
-
const typeParamRefComponent = meta.typeParamRefComponent ?? options.typeParamRefComponent;
|
|
231
|
-
const linkProps = meta.linkProps ?? options.linkProps;
|
|
232
|
-
const linkParams = meta.linkParams ?? options.linkParams;
|
|
233
|
-
const linkScope = meta.linkScope ?? options.linkScope;
|
|
234
|
-
const moduleLinkMap = meta.moduleLinkMap ?? options.moduleLinkMap;
|
|
235
|
-
const defaultImportSlug = meta.defaultImportSlug ?? options.defaultImportSlug;
|
|
236
|
-
const exportLinksOptions = {
|
|
237
|
-
linkMap: meta.precompute.anchorMap
|
|
238
|
-
};
|
|
239
|
-
if (typeRefComponent) {
|
|
240
|
-
exportLinksOptions.typeRefComponent = typeRefComponent;
|
|
241
|
-
}
|
|
242
|
-
if (typePropRefComponent) {
|
|
243
|
-
exportLinksOptions.typePropRefComponent = typePropRefComponent;
|
|
244
|
-
}
|
|
245
|
-
if (typeParamRefComponent) {
|
|
246
|
-
exportLinksOptions.typeParamRefComponent = typeParamRefComponent;
|
|
247
|
-
}
|
|
248
|
-
if (linkProps) {
|
|
249
|
-
exportLinksOptions.linkProps = linkProps;
|
|
250
|
-
}
|
|
251
|
-
if (linkParams) {
|
|
252
|
-
exportLinksOptions.linkParams = linkParams;
|
|
253
|
-
}
|
|
254
|
-
if (linkScope) {
|
|
255
|
-
exportLinksOptions.linkScope = linkScope;
|
|
256
|
-
}
|
|
257
|
-
if (moduleLinkMap) {
|
|
258
|
-
exportLinksOptions.moduleLinkMap = moduleLinkMap;
|
|
259
|
-
}
|
|
260
|
-
if (defaultImportSlug) {
|
|
261
|
-
exportLinksOptions.defaultImportSlug = defaultImportSlug;
|
|
262
|
-
}
|
|
263
|
-
enhancers = [...enhancers, [enhanceCodeTypes, exportLinksOptions]];
|
|
264
|
-
}
|
|
208
|
+
const enhancers = resolveEnhancers(options, meta);
|
|
265
209
|
|
|
266
210
|
// Inline enhancers for shortType and default fields
|
|
267
211
|
const enhancersInline = meta.enhancersInline ?? options.enhancersInline ?? DEFAULT_ENHANCERS_INLINE;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mui/internal-docs-infra",
|
|
3
|
-
"version": "0.13.1-canary.
|
|
3
|
+
"version": "0.13.1-canary.28",
|
|
4
4
|
"author": "MUI Team",
|
|
5
5
|
"description": "MUI Infra - internal documentation creation tools.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -813,5 +813,5 @@
|
|
|
813
813
|
"bin": {
|
|
814
814
|
"docs-infra": "./cli/index.mjs"
|
|
815
815
|
},
|
|
816
|
-
"gitSha": "
|
|
816
|
+
"gitSha": "5ada69268ff795656026874c514429285e0dba31"
|
|
817
817
|
}
|
|
@@ -6,6 +6,9 @@ import type { ScanState, ModuleLinkMapEntry } from "./scanState.mjs";
|
|
|
6
6
|
*/
|
|
7
7
|
export interface EnhanceOptions {
|
|
8
8
|
linkMap: Record<string, string>;
|
|
9
|
+
externalLinks?: Record<string, string>;
|
|
10
|
+
/** Names the code block declares, which `externalLinks` never applies to. */
|
|
11
|
+
declaredNames?: Set<string>;
|
|
9
12
|
typeRefComponent?: string;
|
|
10
13
|
typePropRefComponent?: string;
|
|
11
14
|
typeParamRefComponent?: string;
|
|
@@ -29,6 +32,11 @@ export interface EnhanceOptions {
|
|
|
29
32
|
* nested frame/line elements.
|
|
30
33
|
*/
|
|
31
34
|
export declare function enhanceChildren(children: ElementContent[], options: EnhanceOptions, state: ScanState): ElementContent[];
|
|
35
|
+
/**
|
|
36
|
+
* The names a code block declares, such as `Theme` in `interface Theme {}`. They refer to the
|
|
37
|
+
* block's own code wherever they appear in it, before the declaration as well as after.
|
|
38
|
+
*/
|
|
39
|
+
export declare function collectDeclaredNames(children: ElementContent[]): Set<string>;
|
|
32
40
|
/**
|
|
33
41
|
* Resets all import-related state flags.
|
|
34
42
|
*/
|
|
@@ -575,6 +575,56 @@ function resolveTypeHref(identifier, linkMap, state) {
|
|
|
575
575
|
}
|
|
576
576
|
return undefined;
|
|
577
577
|
}
|
|
578
|
+
const DECLARATION_KEYWORDS = new Set(['class', 'const', 'enum', 'function', 'interface', 'let', 'type', 'var']);
|
|
579
|
+
|
|
580
|
+
/**
|
|
581
|
+
* Whether the span at `index` is the name a declaration introduces, such as `Theme` in
|
|
582
|
+
* `interface Theme {}`: the highlighter puts only whitespace between the keyword and the name.
|
|
583
|
+
* Anonymous forms such as `class extends Base` put another token there, so `Base` is not one.
|
|
584
|
+
*/
|
|
585
|
+
function isDeclarationName(children, index) {
|
|
586
|
+
const between = children[index - 1];
|
|
587
|
+
const keyword = children[index - 2];
|
|
588
|
+
return between?.type === 'text' && between.value.trim() === '' && keyword?.type === 'element' && isKeywordSpan(keyword) && DECLARATION_KEYWORDS.has(getTextContent(keyword));
|
|
589
|
+
}
|
|
590
|
+
|
|
591
|
+
/**
|
|
592
|
+
* The names a code block declares, such as `Theme` in `interface Theme {}`. They refer to the
|
|
593
|
+
* block's own code wherever they appear in it, before the declaration as well as after.
|
|
594
|
+
*/
|
|
595
|
+
export function collectDeclaredNames(children) {
|
|
596
|
+
const names = new Set();
|
|
597
|
+
const visitChildren = nodes => {
|
|
598
|
+
nodes.forEach((node, index) => {
|
|
599
|
+
if (node.type !== 'element') {
|
|
600
|
+
return;
|
|
601
|
+
}
|
|
602
|
+
if (isLinkableSpan(node) && isDeclarationName(nodes, index)) {
|
|
603
|
+
names.add(getTextContent(node));
|
|
604
|
+
} else {
|
|
605
|
+
visitChildren(node.children);
|
|
606
|
+
}
|
|
607
|
+
});
|
|
608
|
+
};
|
|
609
|
+
visitChildren(children);
|
|
610
|
+
return names;
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
/**
|
|
614
|
+
* Looks up a name the link map does not know in `externalLinks`. A name the block declares or
|
|
615
|
+
* a name bound in scope refers to local code, so it is left unlinked. External links only link
|
|
616
|
+
* the name; owner tracking keeps using `linkMap`.
|
|
617
|
+
*/
|
|
618
|
+
function resolveExternalHref(identifier, options, state) {
|
|
619
|
+
const {
|
|
620
|
+
externalLinks,
|
|
621
|
+
declaredNames
|
|
622
|
+
} = options;
|
|
623
|
+
if (!externalLinks || !Object.hasOwn(externalLinks, identifier) || declaredNames?.has(identifier) || state.scopeStack.some(scope => scope.bindings.has(identifier))) {
|
|
624
|
+
return undefined;
|
|
625
|
+
}
|
|
626
|
+
return externalLinks[identifier];
|
|
627
|
+
}
|
|
578
628
|
|
|
579
629
|
/**
|
|
580
630
|
* Handles a linkable span (pl-c1 or pl-en).
|
|
@@ -641,7 +691,7 @@ function handleLinkableSpan(children, startIndex, options, state) {
|
|
|
641
691
|
}
|
|
642
692
|
}
|
|
643
693
|
}
|
|
644
|
-
const href = cssClassHref ?? resolveTypeHref(identifier, linkMap, state);
|
|
694
|
+
const href = cssClassHref ?? resolveTypeHref(identifier, linkMap, state) ?? resolveExternalHref(identifier, options, state);
|
|
645
695
|
const nodes = [];
|
|
646
696
|
if (isBareCssClass) {
|
|
647
697
|
const exportName = getCssClassExportName(identifier);
|
|
@@ -19,6 +19,15 @@ export interface EnhanceCodeTypesOptions {
|
|
|
19
19
|
/** Anchors for CSS-family languages (css, scss, less, sass). */
|
|
20
20
|
css?: Record<string, string>;
|
|
21
21
|
};
|
|
22
|
+
/**
|
|
23
|
+
* Links for types documented elsewhere, keyed by the name they are printed as in
|
|
24
|
+
* JavaScript and TypeScript code, such as `HTMLElement` →
|
|
25
|
+
* `https://developer.mozilla.org/docs/Web/API/HTMLElement`. Consulted after `linkMap`.
|
|
26
|
+
*
|
|
27
|
+
* Only the type name itself is linked. External links never act as owners for
|
|
28
|
+
* property or parameter anchors.
|
|
29
|
+
*/
|
|
30
|
+
externalLinks?: Record<string, string>;
|
|
22
31
|
/**
|
|
23
32
|
* When set, the plugin emits a custom component element instead of an `<a>` tag
|
|
24
33
|
* for type/export name references.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { visit } from 'unist-util-visit';
|
|
2
2
|
import { getLanguageCapabilities } from "./getLanguageCapabilities.mjs";
|
|
3
3
|
import { createScanState, finalizePendingDefaultExport, resetExportState } from "./scanState.mjs";
|
|
4
|
-
import { enhanceChildren, wrapExpressionNodes } from "./enhanceChildren.mjs";
|
|
4
|
+
import { collectDeclaredNames, enhanceChildren, wrapExpressionNodes } from "./enhanceChildren.mjs";
|
|
5
5
|
import { flushLiteralCandidate, flushPendingExpression } from "./processTextNode.mjs";
|
|
6
6
|
|
|
7
7
|
/**
|
|
@@ -46,18 +46,18 @@ export default function enhanceCodeTypes(options) {
|
|
|
46
46
|
return;
|
|
47
47
|
}
|
|
48
48
|
const lang = getLanguageCapabilities(node);
|
|
49
|
-
|
|
49
|
+
// Without a prototype, names such as `toString` or `constructor` are not found in the map.
|
|
50
|
+
const linkMap = Object.create(null);
|
|
50
51
|
if (lang.semantics === 'js') {
|
|
51
|
-
linkMap
|
|
52
|
-
...(options.linkMap.js ?? {})
|
|
53
|
-
};
|
|
52
|
+
Object.assign(linkMap, options.linkMap.js);
|
|
54
53
|
} else if (lang.semantics === 'css') {
|
|
55
|
-
linkMap
|
|
56
|
-
...(options.linkMap.css ?? {})
|
|
57
|
-
};
|
|
54
|
+
Object.assign(linkMap, options.linkMap.css);
|
|
58
55
|
}
|
|
59
56
|
const enhanceOptions = {
|
|
60
57
|
linkMap,
|
|
58
|
+
// Type names only occur in JS-family code; CSS values such as `Highlight` are not types.
|
|
59
|
+
externalLinks: lang.semantics === 'js' ? options.externalLinks : undefined,
|
|
60
|
+
declaredNames: lang.semantics === 'js' && options.externalLinks ? collectDeclaredNames(node.children) : undefined,
|
|
61
61
|
typeRefComponent: options.typeRefComponent,
|
|
62
62
|
typePropRefComponent: options.typePropRefComponent,
|
|
63
63
|
typeParamRefComponent: options.typeParamRefComponent,
|
|
@@ -14,6 +14,63 @@ import { createLoadServerCodeSource } from "../loadServerCodeSource/index.mjs";
|
|
|
14
14
|
import { getFileNameFromUrl, IGNORE_COMMENT_PREFIXES } from "../loaderUtils/index.mjs";
|
|
15
15
|
import { createPerformanceLogger, logPerformance, performanceMeasure } from "./performanceLogger.mjs";
|
|
16
16
|
import { fallbackToHast } from "../../CodeHighlighter/fallbackFormat.mjs";
|
|
17
|
+
// Compilation identity prevents reuse across compilers and watch rebuilds.
|
|
18
|
+
const deferredCaches = new WeakMap();
|
|
19
|
+
|
|
20
|
+
/** Rejects options whose behavior would be lost in a JSON cache key. */
|
|
21
|
+
function isSerializable(value, ancestors = new Set()) {
|
|
22
|
+
if (value === null || typeof value === 'string' || typeof value === 'boolean') {
|
|
23
|
+
return true;
|
|
24
|
+
}
|
|
25
|
+
if (typeof value === 'number') {
|
|
26
|
+
return Number.isFinite(value);
|
|
27
|
+
}
|
|
28
|
+
if (typeof value !== 'object' || ancestors.has(value) || Object.getOwnPropertySymbols(value).length) {
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
const prototype = Object.getPrototypeOf(value);
|
|
32
|
+
if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
ancestors.add(value);
|
|
36
|
+
const supported = Object.entries(Object.getOwnPropertyDescriptors(value)).every(([name, descriptor]) => {
|
|
37
|
+
if (Array.isArray(value) && name === 'length') {
|
|
38
|
+
return true;
|
|
39
|
+
}
|
|
40
|
+
return descriptor.enumerable && 'value' in descriptor && (
|
|
41
|
+
// JSON drops undefined properties, matching how the loader treats absent options.
|
|
42
|
+
// Arrays serialize undefined as null, so elements still have to be serializable.
|
|
43
|
+
descriptor.value === undefined && !Array.isArray(value) || isSerializable(descriptor.value, ancestors));
|
|
44
|
+
});
|
|
45
|
+
ancestors.delete(value);
|
|
46
|
+
return supported;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Shares completed source only when webpack provides a compilation boundary. */
|
|
50
|
+
function getDeferredCache(context, source, options) {
|
|
51
|
+
const {
|
|
52
|
+
_compilation: compilation
|
|
53
|
+
} = context;
|
|
54
|
+
if (!options.deferPrecompute || !compilation || !isSerializable(options)) {
|
|
55
|
+
return undefined;
|
|
56
|
+
}
|
|
57
|
+
let entries = deferredCaches.get(compilation);
|
|
58
|
+
if (!entries) {
|
|
59
|
+
entries = new Map();
|
|
60
|
+
deferredCaches.set(compilation, entries);
|
|
61
|
+
}
|
|
62
|
+
return {
|
|
63
|
+
entries,
|
|
64
|
+
key: JSON.stringify([context.resourcePath, source, options])
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Both the shell and deferred module must invalidate when imported source changes. */
|
|
69
|
+
function registerDependencies(context, dependencies) {
|
|
70
|
+
dependencies.forEach(dependency => {
|
|
71
|
+
context.addDependency(dependency.startsWith('file://') ? fileURLToPath(dependency) : dependency);
|
|
72
|
+
});
|
|
73
|
+
}
|
|
17
74
|
|
|
18
75
|
/**
|
|
19
76
|
* Extracts a string array from structured options data.
|
|
@@ -115,6 +172,14 @@ export async function loadPrecomputedCodeHighlighter(source) {
|
|
|
115
172
|
const callback = this.async();
|
|
116
173
|
this.cacheable();
|
|
117
174
|
const options = this.getOptions();
|
|
175
|
+
const isDeferredRequest = this.resourceQuery === '?mui-deferred-precompute';
|
|
176
|
+
const deferredCache = getDeferredCache(this, source, options);
|
|
177
|
+
const cached = isDeferredRequest ? deferredCache?.entries.get(deferredCache.key) : undefined;
|
|
178
|
+
if (cached) {
|
|
179
|
+
registerDependencies(this, cached.dependencies);
|
|
180
|
+
callback(null, cached.source);
|
|
181
|
+
return;
|
|
182
|
+
}
|
|
118
183
|
const performanceNotableMs = options.performance?.notableMs ?? 100;
|
|
119
184
|
const performanceShowWrapperMeasures = options.performance?.showWrapperMeasures ?? false;
|
|
120
185
|
const relativePath = path.relative(this.rootContext || process.cwd(), this.resourcePath);
|
|
@@ -276,9 +341,16 @@ export async function loadPrecomputedCodeHighlighter(source) {
|
|
|
276
341
|
measure: 'Complete Variants Loading'
|
|
277
342
|
}, [functionName, relativePath], true);
|
|
278
343
|
const deferredRequest = `./${path.basename(this.resourcePath)}?mui-deferred-precompute`;
|
|
279
|
-
const
|
|
344
|
+
const deferredSource = isDeferredRequest || deferredCache ? `export default ${JSON.stringify(variantData)};` : undefined;
|
|
345
|
+
registerDependencies(this, allDependencies);
|
|
346
|
+
if (deferredCache && deferredSource) {
|
|
347
|
+
deferredCache.entries.set(deferredCache.key, {
|
|
348
|
+
source: deferredSource,
|
|
349
|
+
dependencies: allDependencies
|
|
350
|
+
});
|
|
351
|
+
}
|
|
280
352
|
if (isDeferredRequest) {
|
|
281
|
-
callback(null,
|
|
353
|
+
callback(null, deferredSource);
|
|
282
354
|
return;
|
|
283
355
|
}
|
|
284
356
|
|
|
@@ -293,13 +365,6 @@ export async function loadPrecomputedCodeHighlighter(source) {
|
|
|
293
365
|
measure: 'Precompute Replacement'
|
|
294
366
|
}, [functionName, relativePath]);
|
|
295
367
|
|
|
296
|
-
// Add all dependencies to webpack's watch list
|
|
297
|
-
allDependencies.forEach(dep => {
|
|
298
|
-
// Convert file:// URLs to proper file system paths for webpack's dependency tracking
|
|
299
|
-
// Using fileURLToPath handles Windows drive letters correctly (e.g., file:///C:/... → C:\...)
|
|
300
|
-
this.addDependency(dep.startsWith('file://') ? fileURLToPath(dep) : dep);
|
|
301
|
-
});
|
|
302
|
-
|
|
303
368
|
// log any pending performance entries before completing
|
|
304
369
|
observer?.takeRecords()?.forEach(entry => logPerformance(entry, performanceNotableMs, performanceShowWrapperMeasures, relativePath));
|
|
305
370
|
observer?.disconnect();
|
|
@@ -109,7 +109,8 @@ export async function loadPrecomputedTypes(source) {
|
|
|
109
109
|
variantOnlyAdditionalTypes: result.variantOnlyAdditionalTypes,
|
|
110
110
|
variantTypeNames: result.variantTypeNames,
|
|
111
111
|
singleComponentName,
|
|
112
|
-
anchorMap: result.anchorMap
|
|
112
|
+
anchorMap: result.anchorMap,
|
|
113
|
+
externalTypeLinks: result.externalTypeLinks
|
|
113
114
|
};
|
|
114
115
|
|
|
115
116
|
// Replace the component reference with an empty object to avoid importing actual component code.
|
|
@@ -59,6 +59,11 @@ export interface LoadServerTypesResult {
|
|
|
59
59
|
js?: Record<string, string>;
|
|
60
60
|
css?: Record<string, string>;
|
|
61
61
|
};
|
|
62
|
+
/**
|
|
63
|
+
* Links for the built-in types referenced on the page, such as `HTMLElement` to its MDN
|
|
64
|
+
* page, keyed by the name they are printed as.
|
|
65
|
+
*/
|
|
66
|
+
externalTypeLinks: Record<string, string>;
|
|
62
67
|
}
|
|
63
68
|
/**
|
|
64
69
|
* Server-side function for loading and processing TypeScript types.
|
|
@@ -18,6 +18,11 @@ export interface ExternalTypeMeta {
|
|
|
18
18
|
export interface ExternalTypesCollector {
|
|
19
19
|
/** Map to accumulate results (type name -> ExternalTypeMeta) */
|
|
20
20
|
collected: Map<string, ExternalTypeMeta>;
|
|
21
|
+
/**
|
|
22
|
+
* Where the external types in the formatted output are declared, keyed by the name they are
|
|
23
|
+
* printed as. `null` marks a name printed for types from different declarations.
|
|
24
|
+
*/
|
|
25
|
+
sources: Map<string, tae.ExternalTypeSource | null>;
|
|
21
26
|
/** All exports in the module, used to identify own types */
|
|
22
27
|
allExports: tae.ExportNode[];
|
|
23
28
|
/** Optional pattern to filter which external types to include */
|
|
@@ -25,6 +30,24 @@ export interface ExternalTypesCollector {
|
|
|
25
30
|
/** Map of original export names to dotted display names, used to identify renamed own types */
|
|
26
31
|
typeNameMap?: Record<string, string>;
|
|
27
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* Records where an external type printed as `printedName` is declared, so the name can be
|
|
35
|
+
* linked to that declaration's docs. A name printed for two different declarations, such as
|
|
36
|
+
* the DOM `Range` and a package's `Range`, cannot tell them apart and is marked ambiguous.
|
|
37
|
+
*/
|
|
38
|
+
export declare function collectExternalTypeSource(printedName: string, source: tae.ExternalTypeSource | undefined, collector: ExternalTypesCollector): void;
|
|
39
|
+
/**
|
|
40
|
+
* Records that a project's own type is printed as `printedName`. The occurrences of a name
|
|
41
|
+
* cannot be told apart, so an external type printed the same way is left unlinked too.
|
|
42
|
+
*/
|
|
43
|
+
export declare function collectOwnTypeName(printedName: string, collector: ExternalTypesCollector): void;
|
|
44
|
+
/**
|
|
45
|
+
* The source of a union named after the one external type it adds `undefined` or `null` to,
|
|
46
|
+
* as the extractor names optional props of an external type: `Intl.NumberFormat | undefined`
|
|
47
|
+
* keeps the name `Intl.NumberFormat`. An alias of its own, such as
|
|
48
|
+
* `type MaybeElement = HTMLElement | null`, is not that type and has no source.
|
|
49
|
+
*/
|
|
50
|
+
export declare function getNamedUnionSource(type: tae.UnionNode): tae.ExternalTypeSource | undefined;
|
|
28
51
|
/**
|
|
29
52
|
* Checks whether a type name belongs to one of the module's own exports.
|
|
30
53
|
* Matches both direct export names (e.g., `AlertDialogRootChangeEventReason`)
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { uniq } from 'es-toolkit';
|
|
2
|
-
import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType, isTemplateLiteralType, isTypeOperatorType, isTypeQueryType } from "./typeGuards.mjs";
|
|
2
|
+
import { isExternalType, isIntrinsicType, isUnionType, isObjectType, isLiteralType, isTemplateLiteralType, isTypeOperatorType, isTypeQueryType, isArrayType } from "./typeGuards.mjs";
|
|
3
3
|
import { isBuiltInTypeName } from "./builtInTypes.mjs";
|
|
4
4
|
import { groupType, UNION_OR_INTERSECTION } from "./precedence.mjs";
|
|
5
5
|
import { formatTemplateLiteral } from "./templateLiteral.mjs";
|
|
@@ -16,6 +16,53 @@ import { formatTemplateLiteral } from "./templateLiteral.mjs";
|
|
|
16
16
|
* external types as they are encountered in the formatted output.
|
|
17
17
|
*/
|
|
18
18
|
|
|
19
|
+
function withoutTypeArguments(printedName) {
|
|
20
|
+
const typeArgumentsStart = printedName.indexOf('<');
|
|
21
|
+
return typeArgumentsStart === -1 ? printedName : printedName.slice(0, typeArgumentsStart);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Records where an external type printed as `printedName` is declared, so the name can be
|
|
26
|
+
* linked to that declaration's docs. A name printed for two different declarations, such as
|
|
27
|
+
* the DOM `Range` and a package's `Range`, cannot tell them apart and is marked ambiguous.
|
|
28
|
+
*/
|
|
29
|
+
export function collectExternalTypeSource(printedName, source, collector) {
|
|
30
|
+
if (!source) {
|
|
31
|
+
return;
|
|
32
|
+
}
|
|
33
|
+
const name = withoutTypeArguments(printedName);
|
|
34
|
+
const existing = collector.sources.get(name);
|
|
35
|
+
if (existing === undefined) {
|
|
36
|
+
collector.sources.set(name, source);
|
|
37
|
+
} else if (existing !== null && JSON.stringify(existing) !== JSON.stringify(source)) {
|
|
38
|
+
collector.sources.set(name, null);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Records that a project's own type is printed as `printedName`. The occurrences of a name
|
|
44
|
+
* cannot be told apart, so an external type printed the same way is left unlinked too.
|
|
45
|
+
*/
|
|
46
|
+
export function collectOwnTypeName(printedName, collector) {
|
|
47
|
+
collector.sources.set(withoutTypeArguments(printedName), null);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* The source of a union named after the one external type it adds `undefined` or `null` to,
|
|
52
|
+
* as the extractor names optional props of an external type: `Intl.NumberFormat | undefined`
|
|
53
|
+
* keeps the name `Intl.NumberFormat`. An alias of its own, such as
|
|
54
|
+
* `type MaybeElement = HTMLElement | null`, is not that type and has no source.
|
|
55
|
+
*/
|
|
56
|
+
export function getNamedUnionSource(type) {
|
|
57
|
+
const members = type.types.filter(member => !(isIntrinsicType(member) && (member.intrinsic === 'undefined' || member.intrinsic === 'null')));
|
|
58
|
+
const [member] = members;
|
|
59
|
+
if (members.length !== 1 || !isExternalType(member) || !type.typeName) {
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
const sameName = member.typeName.name === type.typeName.name && (member.typeName.namespaces ?? []).join('.') === (type.typeName.namespaces ?? []).join('.');
|
|
63
|
+
return sameName ? member.source : undefined;
|
|
64
|
+
}
|
|
65
|
+
|
|
19
66
|
/**
|
|
20
67
|
* Checks whether a type name belongs to one of the module's own exports.
|
|
21
68
|
* Matches both direct export names (e.g., `AlertDialogRootChangeEventReason`)
|
|
@@ -103,6 +150,10 @@ export function formatExternalTypeDefinition(type) {
|
|
|
103
150
|
if (isExternalType(type)) {
|
|
104
151
|
return type.typeName.name;
|
|
105
152
|
}
|
|
153
|
+
if (isArrayType(type)) {
|
|
154
|
+
const elementType = formatExternalTypeDefinition(type.elementType);
|
|
155
|
+
return elementType.includes(' ') ? `(${elementType})[]` : `${elementType}[]`;
|
|
156
|
+
}
|
|
106
157
|
if (isObjectType(type)) {
|
|
107
158
|
const props = (type.properties || []).map(p => {
|
|
108
159
|
const propType = formatExternalTypeDefinition(p.type);
|
|
@@ -20,7 +20,7 @@ export declare function formatType(type: tae.AnyType, options: FormatTypeOptions
|
|
|
20
20
|
* processing, then runs the output through `prettyFormat()` for consistent styling.
|
|
21
21
|
*/
|
|
22
22
|
export declare function prettyFormatType(type: tae.AnyType, options: FormatTypeOptions): Promise<string>;
|
|
23
|
-
export declare function getFullyQualifiedName(typeName: tae.TypeName, exportNames: string[], typeNameMap: Record<string, string>, preserveTypeParameters?: boolean): string;
|
|
23
|
+
export declare function getFullyQualifiedName(typeName: tae.TypeName, exportNames: string[], typeNameMap: Record<string, string>, preserveTypeParameters?: boolean, externalTypesCollector?: ExternalTypesCollector): string;
|
|
24
24
|
/**
|
|
25
25
|
* Formats a JSDoc comment block from property documentation.
|
|
26
26
|
* Returns undefined if no meaningful content to document.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { uniq } from 'es-toolkit';
|
|
2
2
|
import { isExternalType, isIntrinsicType, isUnionType, isIntersectionType, isObjectType, isAnonymousObjectType, isArrayType, isFunctionType, isLiteralType, isTemplateLiteralType, isTupleType, isTypeParameterType, isTypeOperatorType, isTypeQueryType, isInternalTypeName } from "./typeGuards.mjs";
|
|
3
|
-
import { isOwnTypeName, maybeCollectExternalUnion, maybeCollectExternalTemplateLiteral, maybeCollectExternalFunction, maybeCollectExternalReference } from "./externalTypes.mjs";
|
|
3
|
+
import { isOwnTypeName, maybeCollectExternalUnion, maybeCollectExternalTemplateLiteral, maybeCollectExternalFunction, maybeCollectExternalReference, collectExternalTypeSource, collectOwnTypeName, getNamedUnionSource } from "./externalTypes.mjs";
|
|
4
4
|
import { isBuiltInTypeReference } from "./builtInTypes.mjs";
|
|
5
5
|
import { prettyFormat } from "./format.mjs";
|
|
6
6
|
import { groupType, UNION, UNION_OR_INTERSECTION } from "./precedence.mjs";
|
|
@@ -48,6 +48,18 @@ export function formatType(type, options) {
|
|
|
48
48
|
preserveTypeParameters
|
|
49
49
|
} = options;
|
|
50
50
|
|
|
51
|
+
/**
|
|
52
|
+
* Prints the name of a type that is not external. Lib types are always external, so a name
|
|
53
|
+
* printed here is the project's own, and a lib type that shares it is left unlinked.
|
|
54
|
+
*/
|
|
55
|
+
function printOwnTypeName(typeName) {
|
|
56
|
+
const qualifiedName = getFullyQualifiedName(typeName, exportNames, typeNameMap, preserveTypeParameters, externalTypesCollector);
|
|
57
|
+
if (externalTypesCollector) {
|
|
58
|
+
collectOwnTypeName(qualifiedName, externalTypesCollector);
|
|
59
|
+
}
|
|
60
|
+
return qualifiedName;
|
|
61
|
+
}
|
|
62
|
+
|
|
51
63
|
/**
|
|
52
64
|
* Checks if a qualified type name matches the selfName (type being defined).
|
|
53
65
|
* Strips type arguments before comparing to handle generic instances.
|
|
@@ -72,22 +84,30 @@ export function formatType(type, options) {
|
|
|
72
84
|
}
|
|
73
85
|
if (isExternalType(type)) {
|
|
74
86
|
if (/^ReactElement(<.*>)?/.test(type.typeName.name || '')) {
|
|
87
|
+
if (externalTypesCollector) {
|
|
88
|
+
collectExternalTypeSource('ReactElement', type.source, externalTypesCollector);
|
|
89
|
+
}
|
|
75
90
|
return 'ReactElement';
|
|
76
91
|
}
|
|
77
92
|
if (type.typeName.namespaces?.length === 1 && type.typeName.namespaces[0] === 'React') {
|
|
78
|
-
|
|
93
|
+
const reactName = createNameWithTypeArguments(type.typeName, exportNames, typeNameMap, externalTypesCollector, preserveTypeParameters);
|
|
94
|
+
if (externalTypesCollector) {
|
|
95
|
+
collectExternalTypeSource(reactName, type.source, externalTypesCollector);
|
|
96
|
+
}
|
|
97
|
+
return reactName;
|
|
79
98
|
}
|
|
80
|
-
const qualifiedName = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
|
|
99
|
+
const qualifiedName = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters, externalTypesCollector);
|
|
81
100
|
if (externalTypesCollector) {
|
|
82
101
|
// Only collect as external if the qualified name wasn't rewritten to an own type.
|
|
83
102
|
if (qualifiedName === type.typeName.name || !isOwnTypeName(qualifiedName, externalTypesCollector)) {
|
|
84
103
|
maybeCollectExternalReference(type, externalTypesCollector);
|
|
104
|
+
collectExternalTypeSource(qualifiedName, type.source, externalTypesCollector);
|
|
85
105
|
}
|
|
86
106
|
}
|
|
87
107
|
return qualifiedName;
|
|
88
108
|
}
|
|
89
109
|
if (isIntrinsicType(type)) {
|
|
90
|
-
return type.typeName ?
|
|
110
|
+
return type.typeName ? printOwnTypeName(type.typeName) : type.intrinsic;
|
|
91
111
|
}
|
|
92
112
|
if (isUnionType(type)) {
|
|
93
113
|
// For union types with a type alias name, always prefer showing the alias name
|
|
@@ -95,7 +115,7 @@ export function formatType(type, options) {
|
|
|
95
115
|
// The expandObjects flag is primarily for object types where showing the structure is valuable
|
|
96
116
|
// But skip if the type name matches selfName to avoid circular references like `type Foo = Foo`
|
|
97
117
|
if (type.typeName) {
|
|
98
|
-
const qualifiedName = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
|
|
118
|
+
const qualifiedName = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters, externalTypesCollector);
|
|
99
119
|
// Check both the simple name AND the fully qualified name against selfName
|
|
100
120
|
// selfName can be either format depending on context
|
|
101
121
|
// Also strip type arguments to catch cases like `type Foo = Foo<Args>`
|
|
@@ -106,6 +126,12 @@ export function formatType(type, options) {
|
|
|
106
126
|
// not an external type that should appear in the External Types section.
|
|
107
127
|
if (qualifiedName === type.typeName.name || !isOwnTypeName(qualifiedName, externalTypesCollector)) {
|
|
108
128
|
maybeCollectExternalUnion(type, externalTypesCollector);
|
|
129
|
+
const source = getNamedUnionSource(type);
|
|
130
|
+
if (source) {
|
|
131
|
+
collectExternalTypeSource(qualifiedName, source, externalTypesCollector);
|
|
132
|
+
} else {
|
|
133
|
+
collectOwnTypeName(qualifiedName, externalTypesCollector);
|
|
134
|
+
}
|
|
109
135
|
}
|
|
110
136
|
}
|
|
111
137
|
return qualifiedName;
|
|
@@ -167,7 +193,7 @@ export function formatType(type, options) {
|
|
|
167
193
|
// The expandObjects flag is primarily for object types where showing the structure is valuable
|
|
168
194
|
// But skip if the type name matches selfName to avoid circular references like `type Foo = Foo`
|
|
169
195
|
if (type.typeName) {
|
|
170
|
-
const qualifiedName =
|
|
196
|
+
const qualifiedName = printOwnTypeName(type.typeName);
|
|
171
197
|
// Check both the simple name AND the fully qualified name against selfName
|
|
172
198
|
// selfName can be either format depending on context
|
|
173
199
|
// Also strip type arguments to catch cases like `type Foo = Foo<Args>`
|
|
@@ -255,7 +281,7 @@ export function formatType(type, options) {
|
|
|
255
281
|
// BUT if the type name matches selfName, we need to expand to avoid circular references
|
|
256
282
|
// like `type ToastManager = ToastManager`
|
|
257
283
|
if (hasValidTypeName && !expandObjects) {
|
|
258
|
-
const qualifiedName =
|
|
284
|
+
const qualifiedName = printOwnTypeName(type.typeName);
|
|
259
285
|
if (!matchesSelfName(qualifiedName, type.typeName.name)) {
|
|
260
286
|
return qualifiedName;
|
|
261
287
|
}
|
|
@@ -266,7 +292,7 @@ export function formatType(type, options) {
|
|
|
266
292
|
// This ensures types like `DialogHandle<Payload>` are shown instead of `{}`
|
|
267
293
|
if (isObjectEmpty(type.properties) && !indexSignature) {
|
|
268
294
|
if (hasValidTypeName) {
|
|
269
|
-
const qualifiedName =
|
|
295
|
+
const qualifiedName = printOwnTypeName(type.typeName);
|
|
270
296
|
if (!matchesSelfName(qualifiedName, type.typeName.name)) {
|
|
271
297
|
return qualifiedName;
|
|
272
298
|
}
|
|
@@ -334,7 +360,7 @@ export function formatType(type, options) {
|
|
|
334
360
|
// A reference to a template literal alias keeps its name, like the other named types.
|
|
335
361
|
// But skip if the type name matches selfName to avoid circular references like `type Foo = Foo`
|
|
336
362
|
if (type.typeName) {
|
|
337
|
-
const qualifiedName =
|
|
363
|
+
const qualifiedName = printOwnTypeName(type.typeName);
|
|
338
364
|
if (!matchesSelfName(qualifiedName, type.typeName.name)) {
|
|
339
365
|
if (externalTypesCollector) {
|
|
340
366
|
// Only collect as external if the qualified name wasn't rewritten to an own type.
|
|
@@ -376,7 +402,7 @@ export function formatType(type, options) {
|
|
|
376
402
|
// Exception: When expandObjects is true (for detailed type view), always expand.
|
|
377
403
|
const hasNamedTypeAlias = type.typeName?.name && !type.typeName.name.startsWith('ComponentRenderFn');
|
|
378
404
|
if (hasNamedTypeAlias && !expandObjects) {
|
|
379
|
-
const qualifiedName =
|
|
405
|
+
const qualifiedName = printOwnTypeName(type.typeName);
|
|
380
406
|
if (externalTypesCollector) {
|
|
381
407
|
// Only collect as external if the qualified name wasn't rewritten to an own type.
|
|
382
408
|
if (qualifiedName === type.typeName.name || !isOwnTypeName(qualifiedName, externalTypesCollector)) {
|
|
@@ -465,7 +491,7 @@ export function formatType(type, options) {
|
|
|
465
491
|
}
|
|
466
492
|
if (isTupleType(type)) {
|
|
467
493
|
if (type.typeName) {
|
|
468
|
-
return
|
|
494
|
+
return printOwnTypeName(type.typeName);
|
|
469
495
|
}
|
|
470
496
|
|
|
471
497
|
// Use expandObjects=false for tuple members to prevent deep expansion (one level only)
|
|
@@ -545,8 +571,13 @@ export function formatType(type, options) {
|
|
|
545
571
|
export async function prettyFormatType(type, options) {
|
|
546
572
|
return prettyFormat(formatType(type, options), type.kind === 'object' ? type.typeName?.name : undefined);
|
|
547
573
|
}
|
|
548
|
-
export function getFullyQualifiedName(typeName, exportNames, typeNameMap, preserveTypeParameters) {
|
|
549
|
-
|
|
574
|
+
export function getFullyQualifiedName(typeName, exportNames, typeNameMap, preserveTypeParameters, externalTypesCollector) {
|
|
575
|
+
// Type arguments only record where their external types are declared: the External Types
|
|
576
|
+
// section describes the types a page references directly, not every type argument.
|
|
577
|
+
const nameWithTypeArgs = createNameWithTypeArguments(typeName, exportNames, typeNameMap, externalTypesCollector && typeName.typeArguments?.length ? {
|
|
578
|
+
...externalTypesCollector,
|
|
579
|
+
collected: new Map()
|
|
580
|
+
} : externalTypesCollector, preserveTypeParameters);
|
|
550
581
|
|
|
551
582
|
// Construct the flat name (what parseExports would have created)
|
|
552
583
|
const flatName = typeName.namespaces && typeName.namespaces.length > 0 ? typeName.namespaces.join('') + typeName.name : typeName.name;
|
|
@@ -110,6 +110,11 @@ export interface LoadServerTypesMetaResult extends OrganizeTypesResult<TypesMeta
|
|
|
110
110
|
* Map from type name to its definition string.
|
|
111
111
|
*/
|
|
112
112
|
externalTypes: Record<string, string>;
|
|
113
|
+
/**
|
|
114
|
+
* Links for the built-in types in the formatted output, keyed by the name they are printed
|
|
115
|
+
* as, such as `HTMLElement` to its MDN page.
|
|
116
|
+
*/
|
|
117
|
+
externalTypeLinks: Record<string, string>;
|
|
113
118
|
/** Resource name derived from the types path */
|
|
114
119
|
resourceName: string;
|
|
115
120
|
}
|
|
@@ -11,6 +11,7 @@ import { formatHookData, isPublicHook } from "./formatHook.mjs";
|
|
|
11
11
|
import { formatFunctionData, isPublicFunction } from "./formatFunction.mjs";
|
|
12
12
|
import { formatRawData } from "./formatRaw.mjs";
|
|
13
13
|
import { prettyFormat } from "./format.mjs";
|
|
14
|
+
import { getMdnTypeLink } from "./mdnTypeLinks.mjs";
|
|
14
15
|
import { buildTypeCompatibilityMap } from "./rewriteTypes.mjs";
|
|
15
16
|
import { matchConstantGroups } from "./constantGroups.mjs";
|
|
16
17
|
import { getWorkerManager } from "./workerManager.mjs";
|
|
@@ -109,6 +110,7 @@ export async function loadServerTypesMeta(options) {
|
|
|
109
110
|
// External types are collected during formatting as type names are encountered
|
|
110
111
|
// in the formatted output, eliminating the need for a separate tree walk + filtering step.
|
|
111
112
|
const collectedExternalTypes = new Map();
|
|
113
|
+
const collectedExternalTypeSources = new Map();
|
|
112
114
|
|
|
113
115
|
// Parse external types pattern once if provided
|
|
114
116
|
const externalTypesPatternRegex = options.externalTypesPattern ? new RegExp(options.externalTypesPattern) : undefined;
|
|
@@ -139,6 +141,7 @@ export async function loadServerTypesMeta(options) {
|
|
|
139
141
|
// Each variant shares the same collected map so types are deduplicated automatically.
|
|
140
142
|
const externalTypesCollector = {
|
|
141
143
|
collected: collectedExternalTypes,
|
|
144
|
+
sources: collectedExternalTypeSources,
|
|
142
145
|
allExports: variantResult.exports,
|
|
143
146
|
pattern: externalTypesPatternRegex,
|
|
144
147
|
typeNameMap: variantResult.typeNameMap
|
|
@@ -457,6 +460,13 @@ export async function loadServerTypesMeta(options) {
|
|
|
457
460
|
const formatted = await prettyFormat(meta.definition, name);
|
|
458
461
|
externalTypes[name] = formatted.trimEnd();
|
|
459
462
|
}));
|
|
463
|
+
const externalTypeLinks = {};
|
|
464
|
+
for (const [name, source] of [...collectedExternalTypeSources].sort(([left], [right]) => left.localeCompare(right))) {
|
|
465
|
+
const link = source ? getMdnTypeLink(name, source) : undefined;
|
|
466
|
+
if (link) {
|
|
467
|
+
externalTypeLinks[name] = link;
|
|
468
|
+
}
|
|
469
|
+
}
|
|
460
470
|
performanceMeasure(currentMark, {
|
|
461
471
|
mark: 'complete',
|
|
462
472
|
measure: 'total processing'
|
|
@@ -468,6 +478,7 @@ export async function loadServerTypesMeta(options) {
|
|
|
468
478
|
allDependencies,
|
|
469
479
|
typeNameMap,
|
|
470
480
|
externalTypes,
|
|
481
|
+
externalTypeLinks,
|
|
471
482
|
resourceName,
|
|
472
483
|
exports: organized.exports,
|
|
473
484
|
additionalTypes: organized.additionalTypes,
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { ExternalTypeSource } from '@mui/internal-typescript-api-extractor';
|
|
2
|
+
/**
|
|
3
|
+
* Returns the MDN page for a type declared in one of the TypeScript lib files MDN documents,
|
|
4
|
+
* or `undefined`. A package type with the same name as a built-in type is not linked.
|
|
5
|
+
*/
|
|
6
|
+
export declare function getMdnTypeLink(name: string, source: ExternalTypeSource): string | undefined;
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TypeScript lib files whose globals MDN documents: the DOM, JavaScript, and workers.
|
|
3
|
+
*/
|
|
4
|
+
const MDN_DOCUMENTED_LIBS = ['lib.dom', 'lib.es', 'lib.webworker'];
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Maps built-in types (e.g. `HTMLElement`, `Intl.NumberFormatOptions`) to their MDN page.
|
|
8
|
+
*
|
|
9
|
+
* Hand-picked: the types MUI libraries use in their public APIs, not every type MDN documents.
|
|
10
|
+
* Add an entry here when a library's API starts using another built-in type.
|
|
11
|
+
*/
|
|
12
|
+
const MDN_TYPE_LINKS = {
|
|
13
|
+
// DOM nodes
|
|
14
|
+
Node: 'https://developer.mozilla.org/docs/Web/API/Node',
|
|
15
|
+
Element: 'https://developer.mozilla.org/docs/Web/API/Element',
|
|
16
|
+
HTMLElement: 'https://developer.mozilla.org/docs/Web/API/HTMLElement',
|
|
17
|
+
SVGElement: 'https://developer.mozilla.org/docs/Web/API/SVGElement',
|
|
18
|
+
Document: 'https://developer.mozilla.org/docs/Web/API/Document',
|
|
19
|
+
DocumentFragment: 'https://developer.mozilla.org/docs/Web/API/DocumentFragment',
|
|
20
|
+
ShadowRoot: 'https://developer.mozilla.org/docs/Web/API/ShadowRoot',
|
|
21
|
+
Window: 'https://developer.mozilla.org/docs/Web/API/Window',
|
|
22
|
+
EventTarget: 'https://developer.mozilla.org/docs/Web/API/EventTarget',
|
|
23
|
+
Text: 'https://developer.mozilla.org/docs/Web/API/Text',
|
|
24
|
+
// HTML elements
|
|
25
|
+
HTMLAnchorElement: 'https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement',
|
|
26
|
+
HTMLButtonElement: 'https://developer.mozilla.org/docs/Web/API/HTMLButtonElement',
|
|
27
|
+
HTMLCanvasElement: 'https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement',
|
|
28
|
+
HTMLDetailsElement: 'https://developer.mozilla.org/docs/Web/API/HTMLDetailsElement',
|
|
29
|
+
HTMLDialogElement: 'https://developer.mozilla.org/docs/Web/API/HTMLDialogElement',
|
|
30
|
+
HTMLDivElement: 'https://developer.mozilla.org/docs/Web/API/HTMLDivElement',
|
|
31
|
+
HTMLFieldSetElement: 'https://developer.mozilla.org/docs/Web/API/HTMLFieldSetElement',
|
|
32
|
+
HTMLFormElement: 'https://developer.mozilla.org/docs/Web/API/HTMLFormElement',
|
|
33
|
+
HTMLHeadingElement: 'https://developer.mozilla.org/docs/Web/API/HTMLHeadingElement',
|
|
34
|
+
HTMLIFrameElement: 'https://developer.mozilla.org/docs/Web/API/HTMLIFrameElement',
|
|
35
|
+
HTMLImageElement: 'https://developer.mozilla.org/docs/Web/API/HTMLImageElement',
|
|
36
|
+
HTMLInputElement: 'https://developer.mozilla.org/docs/Web/API/HTMLInputElement',
|
|
37
|
+
HTMLLabelElement: 'https://developer.mozilla.org/docs/Web/API/HTMLLabelElement',
|
|
38
|
+
HTMLLIElement: 'https://developer.mozilla.org/docs/Web/API/HTMLLIElement',
|
|
39
|
+
HTMLOListElement: 'https://developer.mozilla.org/docs/Web/API/HTMLOListElement',
|
|
40
|
+
HTMLOptionElement: 'https://developer.mozilla.org/docs/Web/API/HTMLOptionElement',
|
|
41
|
+
HTMLOutputElement: 'https://developer.mozilla.org/docs/Web/API/HTMLOutputElement',
|
|
42
|
+
HTMLParagraphElement: 'https://developer.mozilla.org/docs/Web/API/HTMLParagraphElement',
|
|
43
|
+
HTMLSelectElement: 'https://developer.mozilla.org/docs/Web/API/HTMLSelectElement',
|
|
44
|
+
HTMLSlotElement: 'https://developer.mozilla.org/docs/Web/API/HTMLSlotElement',
|
|
45
|
+
HTMLSpanElement: 'https://developer.mozilla.org/docs/Web/API/HTMLSpanElement',
|
|
46
|
+
HTMLTableCellElement: 'https://developer.mozilla.org/docs/Web/API/HTMLTableCellElement',
|
|
47
|
+
HTMLTableElement: 'https://developer.mozilla.org/docs/Web/API/HTMLTableElement',
|
|
48
|
+
HTMLTableRowElement: 'https://developer.mozilla.org/docs/Web/API/HTMLTableRowElement',
|
|
49
|
+
HTMLTableSectionElement: 'https://developer.mozilla.org/docs/Web/API/HTMLTableSectionElement',
|
|
50
|
+
HTMLTextAreaElement: 'https://developer.mozilla.org/docs/Web/API/HTMLTextAreaElement',
|
|
51
|
+
HTMLUListElement: 'https://developer.mozilla.org/docs/Web/API/HTMLUListElement',
|
|
52
|
+
HTMLVideoElement: 'https://developer.mozilla.org/docs/Web/API/HTMLVideoElement',
|
|
53
|
+
// SVG elements
|
|
54
|
+
SVGSVGElement: 'https://developer.mozilla.org/docs/Web/API/SVGSVGElement',
|
|
55
|
+
SVGGElement: 'https://developer.mozilla.org/docs/Web/API/SVGGElement',
|
|
56
|
+
SVGPathElement: 'https://developer.mozilla.org/docs/Web/API/SVGPathElement',
|
|
57
|
+
SVGRectElement: 'https://developer.mozilla.org/docs/Web/API/SVGRectElement',
|
|
58
|
+
SVGCircleElement: 'https://developer.mozilla.org/docs/Web/API/SVGCircleElement',
|
|
59
|
+
SVGLineElement: 'https://developer.mozilla.org/docs/Web/API/SVGLineElement',
|
|
60
|
+
SVGTextElement: 'https://developer.mozilla.org/docs/Web/API/SVGTextElement',
|
|
61
|
+
SVGPatternElement: 'https://developer.mozilla.org/docs/Web/API/SVGPatternElement',
|
|
62
|
+
SVGForeignObjectElement: 'https://developer.mozilla.org/docs/Web/API/SVGForeignObjectElement',
|
|
63
|
+
// Events
|
|
64
|
+
Event: 'https://developer.mozilla.org/docs/Web/API/Event',
|
|
65
|
+
UIEvent: 'https://developer.mozilla.org/docs/Web/API/UIEvent',
|
|
66
|
+
MouseEvent: 'https://developer.mozilla.org/docs/Web/API/MouseEvent',
|
|
67
|
+
PointerEvent: 'https://developer.mozilla.org/docs/Web/API/PointerEvent',
|
|
68
|
+
KeyboardEvent: 'https://developer.mozilla.org/docs/Web/API/KeyboardEvent',
|
|
69
|
+
FocusEvent: 'https://developer.mozilla.org/docs/Web/API/FocusEvent',
|
|
70
|
+
InputEvent: 'https://developer.mozilla.org/docs/Web/API/InputEvent',
|
|
71
|
+
CompositionEvent: 'https://developer.mozilla.org/docs/Web/API/CompositionEvent',
|
|
72
|
+
TouchEvent: 'https://developer.mozilla.org/docs/Web/API/TouchEvent',
|
|
73
|
+
WheelEvent: 'https://developer.mozilla.org/docs/Web/API/WheelEvent',
|
|
74
|
+
DragEvent: 'https://developer.mozilla.org/docs/Web/API/DragEvent',
|
|
75
|
+
ClipboardEvent: 'https://developer.mozilla.org/docs/Web/API/ClipboardEvent',
|
|
76
|
+
SubmitEvent: 'https://developer.mozilla.org/docs/Web/API/SubmitEvent',
|
|
77
|
+
ToggleEvent: 'https://developer.mozilla.org/docs/Web/API/ToggleEvent',
|
|
78
|
+
AnimationEvent: 'https://developer.mozilla.org/docs/Web/API/AnimationEvent',
|
|
79
|
+
TransitionEvent: 'https://developer.mozilla.org/docs/Web/API/TransitionEvent',
|
|
80
|
+
CustomEvent: 'https://developer.mozilla.org/docs/Web/API/CustomEvent',
|
|
81
|
+
// Other web APIs
|
|
82
|
+
AbortController: 'https://developer.mozilla.org/docs/Web/API/AbortController',
|
|
83
|
+
AbortSignal: 'https://developer.mozilla.org/docs/Web/API/AbortSignal',
|
|
84
|
+
CSSStyleDeclaration: 'https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration',
|
|
85
|
+
DataTransfer: 'https://developer.mozilla.org/docs/Web/API/DataTransfer',
|
|
86
|
+
DOMRect: 'https://developer.mozilla.org/docs/Web/API/DOMRect',
|
|
87
|
+
DOMRectReadOnly: 'https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly',
|
|
88
|
+
File: 'https://developer.mozilla.org/docs/Web/API/File',
|
|
89
|
+
FileList: 'https://developer.mozilla.org/docs/Web/API/FileList',
|
|
90
|
+
Blob: 'https://developer.mozilla.org/docs/Web/API/Blob',
|
|
91
|
+
FormData: 'https://developer.mozilla.org/docs/Web/API/FormData',
|
|
92
|
+
IntersectionObserver: 'https://developer.mozilla.org/docs/Web/API/IntersectionObserver',
|
|
93
|
+
IntersectionObserverEntry: 'https://developer.mozilla.org/docs/Web/API/IntersectionObserverEntry',
|
|
94
|
+
MediaQueryList: 'https://developer.mozilla.org/docs/Web/API/MediaQueryList',
|
|
95
|
+
MutationObserver: 'https://developer.mozilla.org/docs/Web/API/MutationObserver',
|
|
96
|
+
MutationRecord: 'https://developer.mozilla.org/docs/Web/API/MutationRecord',
|
|
97
|
+
Range: 'https://developer.mozilla.org/docs/Web/API/Range',
|
|
98
|
+
ResizeObserver: 'https://developer.mozilla.org/docs/Web/API/ResizeObserver',
|
|
99
|
+
ResizeObserverEntry: 'https://developer.mozilla.org/docs/Web/API/ResizeObserverEntry',
|
|
100
|
+
Selection: 'https://developer.mozilla.org/docs/Web/API/Selection',
|
|
101
|
+
URL: 'https://developer.mozilla.org/docs/Web/API/URL',
|
|
102
|
+
URLSearchParams: 'https://developer.mozilla.org/docs/Web/API/URLSearchParams',
|
|
103
|
+
ValidityState: 'https://developer.mozilla.org/docs/Web/API/ValidityState',
|
|
104
|
+
VisualViewport: 'https://developer.mozilla.org/docs/Web/API/VisualViewport',
|
|
105
|
+
// JavaScript
|
|
106
|
+
Array: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array',
|
|
107
|
+
Date: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date',
|
|
108
|
+
Error: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error',
|
|
109
|
+
Map: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map',
|
|
110
|
+
Set: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set',
|
|
111
|
+
WeakMap: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap',
|
|
112
|
+
WeakSet: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakSet',
|
|
113
|
+
WeakRef: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakRef',
|
|
114
|
+
Promise: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise',
|
|
115
|
+
RegExp: 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp',
|
|
116
|
+
'Intl.Collator': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator',
|
|
117
|
+
'Intl.CollatorOptions': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options',
|
|
118
|
+
'Intl.DateTimeFormat': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat',
|
|
119
|
+
'Intl.DateTimeFormatOptions': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options',
|
|
120
|
+
'Intl.ListFormat': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat',
|
|
121
|
+
'Intl.Locale': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale',
|
|
122
|
+
'Intl.LocalesArgument': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument',
|
|
123
|
+
'Intl.NumberFormat': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat',
|
|
124
|
+
'Intl.NumberFormatOptions': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options',
|
|
125
|
+
'Intl.PluralRules': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules',
|
|
126
|
+
'Intl.RelativeTimeFormat': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat',
|
|
127
|
+
'Temporal.Duration': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration',
|
|
128
|
+
'Temporal.Instant': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant',
|
|
129
|
+
'Temporal.PlainDate': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate',
|
|
130
|
+
'Temporal.PlainDateTime': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDateTime',
|
|
131
|
+
'Temporal.PlainTime': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime',
|
|
132
|
+
'Temporal.ZonedDateTime': 'https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime'
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Returns the MDN page for a type declared in one of the TypeScript lib files MDN documents,
|
|
137
|
+
* or `undefined`. A package type with the same name as a built-in type is not linked.
|
|
138
|
+
*/
|
|
139
|
+
export function getMdnTypeLink(name, source) {
|
|
140
|
+
if (source.kind !== 'lib' || !source.files.some(file => MDN_DOCUMENTED_LIBS.some(lib => file.startsWith(lib)))) {
|
|
141
|
+
return undefined;
|
|
142
|
+
}
|
|
143
|
+
return Object.hasOwn(MDN_TYPE_LINKS, name) ? MDN_TYPE_LINKS[name] : undefined;
|
|
144
|
+
}
|
|
@@ -8,6 +8,11 @@ export interface ParseTestSourcesOptions {
|
|
|
8
8
|
* Omit to parse without a standard library at all.
|
|
9
9
|
*/
|
|
10
10
|
lib?: string;
|
|
11
|
+
/**
|
|
12
|
+
* Places `lib` where TypeScript installs its libraries, under `node_modules`, so the parser
|
|
13
|
+
* treats its types as external with a declaration source, as it does a real build's lib types.
|
|
14
|
+
*/
|
|
15
|
+
installedLib?: boolean;
|
|
11
16
|
/** Overrides merged over the pipeline's own extraction policy. */
|
|
12
17
|
parserOptions?: tae.ParserOptions;
|
|
13
18
|
}
|
|
@@ -28,7 +33,7 @@ export declare function parseTestSources(sources: Record<string, string>, option
|
|
|
28
33
|
* itself rather than parsed exports. Sources are keyed and resolved as in
|
|
29
34
|
* `parseTestSources`, and `entrypoint` is the path of the first one.
|
|
30
35
|
*/
|
|
31
|
-
export declare function createTestProgram(sources: Record<string, string>, lib?: string): {
|
|
36
|
+
export declare function createTestProgram(sources: Record<string, string>, lib?: string, installedLib?: boolean): {
|
|
32
37
|
program: ts.Program;
|
|
33
38
|
entrypoint: string;
|
|
34
39
|
};
|
|
@@ -3,6 +3,7 @@ import { parseFromProgram } from '@mui/internal-typescript-api-extractor';
|
|
|
3
3
|
import { PARSER_OPTIONS } from "./constants.mjs";
|
|
4
4
|
const ROOT = '/virtual';
|
|
5
5
|
const LIB_PATH = `${ROOT}/lib.d.ts`;
|
|
6
|
+
const INSTALLED_LIB_PATH = `${ROOT}/node_modules/typescript/lib/lib.d.ts`;
|
|
6
7
|
/**
|
|
7
8
|
* Parses TypeScript sources the way the pipeline does, without touching the filesystem.
|
|
8
9
|
*
|
|
@@ -18,7 +19,7 @@ export function parseTestSources(sources, options = {}) {
|
|
|
18
19
|
const {
|
|
19
20
|
program,
|
|
20
21
|
entrypoint
|
|
21
|
-
} = createTestProgram(sources, options.lib);
|
|
22
|
+
} = createTestProgram(sources, options.lib, options.installedLib);
|
|
22
23
|
return parseFromProgram(entrypoint, program, {
|
|
23
24
|
...PARSER_OPTIONS,
|
|
24
25
|
...options.parserOptions
|
|
@@ -30,10 +31,11 @@ export function parseTestSources(sources, options = {}) {
|
|
|
30
31
|
* itself rather than parsed exports. Sources are keyed and resolved as in
|
|
31
32
|
* `parseTestSources`, and `entrypoint` is the path of the first one.
|
|
32
33
|
*/
|
|
33
|
-
export function createTestProgram(sources, lib) {
|
|
34
|
+
export function createTestProgram(sources, lib, installedLib = false) {
|
|
34
35
|
const sourceFiles = new Map();
|
|
36
|
+
const libPath = installedLib ? INSTALLED_LIB_PATH : LIB_PATH;
|
|
35
37
|
if (lib !== undefined) {
|
|
36
|
-
sourceFiles.set(
|
|
38
|
+
sourceFiles.set(libPath, ts.createSourceFile(libPath, lib, ts.ScriptTarget.ESNext, true));
|
|
37
39
|
}
|
|
38
40
|
const entryPaths = [];
|
|
39
41
|
for (const [name, text] of Object.entries(sources)) {
|
|
@@ -43,7 +45,7 @@ export function createTestProgram(sources, lib) {
|
|
|
43
45
|
}
|
|
44
46
|
const host = {
|
|
45
47
|
getSourceFile: fileName => sourceFiles.get(fileName),
|
|
46
|
-
getDefaultLibFileName: () =>
|
|
48
|
+
getDefaultLibFileName: () => libPath,
|
|
47
49
|
writeFile: () => {},
|
|
48
50
|
getCurrentDirectory: () => ROOT,
|
|
49
51
|
getCanonicalFileName: fileName => fileName,
|
|
@@ -8,6 +8,8 @@ import type { OrderingConfig } from "./order.mjs";
|
|
|
8
8
|
export interface TypesSourceData extends OrganizeTypesResult<TypesMeta> {
|
|
9
9
|
/** External types discovered in the file */
|
|
10
10
|
externalTypes: Record<string, string>;
|
|
11
|
+
/** Links for the built-in types referenced in the file, keyed by printed name */
|
|
12
|
+
externalTypeLinks: Record<string, string>;
|
|
11
13
|
/**
|
|
12
14
|
* Type name map (merged across all variants).
|
|
13
15
|
* Maps flat names (like "AccordionTriggerState") to dotted names (like "Accordion.Trigger.State").
|
|
@@ -135,6 +135,7 @@ export function normalizeTypesSourceDataForCache(data) {
|
|
|
135
135
|
additionalTypes: data.additionalTypes.map(normalizeTypeMetaForCache),
|
|
136
136
|
variantOnlyAdditionalTypes: normalizeVariantOnlyTypesForCache(data.variantOnlyAdditionalTypes),
|
|
137
137
|
externalTypes: data.externalTypes,
|
|
138
|
+
externalTypeLinks: data.externalTypeLinks,
|
|
138
139
|
typeNameMap: data.typeNameMap,
|
|
139
140
|
variantTypeNameMaps: data.variantTypeNameMaps,
|
|
140
141
|
variantTypeNames: data.variantTypeNames,
|
|
@@ -11,6 +11,7 @@ export declare function parseTypesMarkdown(content: string, ordering?: OrderingC
|
|
|
11
11
|
additionalTypes: TypesMeta[];
|
|
12
12
|
variantOnlyAdditionalTypes: Record<string, TypesMeta[]>;
|
|
13
13
|
externalTypes: Record<string, string>;
|
|
14
|
+
externalTypeLinks: Record<string, string>;
|
|
14
15
|
typeNameMap: Record<string, string>;
|
|
15
16
|
variantTypeNameMaps: Record<string, Record<string, string>>;
|
|
16
17
|
variantTypeNames: Record<string, string[]>;
|
|
@@ -543,6 +543,7 @@ export async function parseTypesMarkdown(content, ordering) {
|
|
|
543
543
|
const allTypes = [];
|
|
544
544
|
const descriptionTargets = [];
|
|
545
545
|
const externalTypes = {};
|
|
546
|
+
const externalTypeLinks = {};
|
|
546
547
|
const parsedVariantTypes = {};
|
|
547
548
|
const typeNameMap = {};
|
|
548
549
|
const parsedVariantTypeNameMapKeys = {};
|
|
@@ -716,12 +717,14 @@ export async function parseTypesMarkdown(content, ordering) {
|
|
|
716
717
|
metadataSection = 'export-groups';
|
|
717
718
|
} else if (text === 'Canonical Types') {
|
|
718
719
|
metadataSection = 'canonical-types';
|
|
720
|
+
} else if (text === 'External Type Links') {
|
|
721
|
+
metadataSection = 'external-type-links';
|
|
719
722
|
}
|
|
720
723
|
if (text === 'External Types') {
|
|
721
724
|
inExternalTypes = true;
|
|
722
725
|
} else if (text === 'Additional Types') {
|
|
723
726
|
inExternalTypes = false;
|
|
724
|
-
} else if (text === 'Export Groups' || text === 'Canonical Types') {
|
|
727
|
+
} else if (text === 'Export Groups' || text === 'Canonical Types' || text === 'External Type Links') {
|
|
725
728
|
// Skip metadata sections - they are parsed separately
|
|
726
729
|
inExternalTypes = false;
|
|
727
730
|
}
|
|
@@ -750,7 +753,13 @@ export async function parseTypesMarkdown(content, ordering) {
|
|
|
750
753
|
const separatorIndex = children.findIndex(child => child.type === 'text' && child.value.includes(':'));
|
|
751
754
|
const namesBeforeSeparator = extractInlineCodeValues(children.slice(0, separatorIndex === -1 ? children.length : separatorIndex));
|
|
752
755
|
const namesAfterSeparator = separatorIndex === -1 ? [] : extractInlineCodeValues(children.slice(separatorIndex + 1));
|
|
753
|
-
if (metadataSection === '
|
|
756
|
+
if (metadataSection === 'external-type-links') {
|
|
757
|
+
const typeName = namesBeforeSeparator[0];
|
|
758
|
+
const link = children.find(child => child.type === 'link');
|
|
759
|
+
if (typeName && link) {
|
|
760
|
+
externalTypeLinks[typeName] = link.url;
|
|
761
|
+
}
|
|
762
|
+
} else if (metadataSection === 'export-groups') {
|
|
754
763
|
const variantName = namesBeforeSeparator[0];
|
|
755
764
|
if (variantName) {
|
|
756
765
|
parsedVariantTypes[variantName] = separatorIndex === -1 ? [variantName] : namesAfterSeparator;
|
|
@@ -950,6 +959,7 @@ export async function parseTypesMarkdown(content, ordering) {
|
|
|
950
959
|
additionalTypes: organized.additionalTypes,
|
|
951
960
|
variantOnlyAdditionalTypes: organized.variantOnlyAdditionalTypes,
|
|
952
961
|
externalTypes,
|
|
962
|
+
externalTypeLinks,
|
|
953
963
|
typeNameMap,
|
|
954
964
|
variantTypeNameMaps: organized.variantTypeNameMaps,
|
|
955
965
|
variantTypeNames: organized.variantTypeNames
|
|
@@ -12,6 +12,8 @@ export interface GenerateTypesMarkdownOptions {
|
|
|
12
12
|
typeNameMap?: Record<string, string>;
|
|
13
13
|
/** External types referenced in props/params but not publicly exported */
|
|
14
14
|
externalTypes?: Record<string, string>;
|
|
15
|
+
/** Links for the built-in types referenced on the page, keyed by printed name */
|
|
16
|
+
externalTypeLinks?: Record<string, string>;
|
|
15
17
|
/**
|
|
16
18
|
* Relative path to the types file (e.g., "react/components/accordion/types.mdx").
|
|
17
19
|
* Used to generate a helpful hint in the autogenerated comment pointing users
|
|
@@ -133,6 +133,7 @@ export async function generateTypesMarkdown(options) {
|
|
|
133
133
|
organized,
|
|
134
134
|
typeNameMap = {},
|
|
135
135
|
externalTypes = {},
|
|
136
|
+
externalTypeLinks = {},
|
|
136
137
|
path: filePath
|
|
137
138
|
} = options;
|
|
138
139
|
|
|
@@ -753,6 +754,14 @@ export async function generateTypesMarkdown(options) {
|
|
|
753
754
|
metadataChunks.push(markdownChunk([md.list(canonicalTypesItems)]));
|
|
754
755
|
}
|
|
755
756
|
|
|
757
|
+
// Build External Type Links section: the docs page of each built-in type the page prints
|
|
758
|
+
if (Object.keys(externalTypeLinks).length > 0) {
|
|
759
|
+
const linkItems = Object.entries(externalTypeLinks).map(([typeName, url]) => md.listItem([md.inlineCode(typeName), md.text(': '), md.link(url, md.text(url))]));
|
|
760
|
+
metadataChunks.push(headingChunk(2, 'External Type Links'));
|
|
761
|
+
metadataChunks.push(markdownChunk([md.paragraph([md.text('Maps '), md.inlineCode('Type'), md.text(': '), md.inlineCode('URL'), md.text(' — the docs of a built-in type the page references.')])]));
|
|
762
|
+
metadataChunks.push(markdownChunk([md.list(linkItems)]));
|
|
763
|
+
}
|
|
764
|
+
|
|
756
765
|
// Flatten all chunks and format with prettier where needed
|
|
757
766
|
const allChunks = [headerChunk, ...exportChunksArrays.flat(), ...additionalTypesChunks, ...externalTypesChunks, ...metadataChunks];
|
|
758
767
|
const formattedChunks = await Promise.all(allChunks.map(async chunk => {
|
|
@@ -204,6 +204,7 @@ export async function syncTypes(options) {
|
|
|
204
204
|
allDependencies,
|
|
205
205
|
typeNameMap,
|
|
206
206
|
externalTypes,
|
|
207
|
+
externalTypeLinks,
|
|
207
208
|
resourceName,
|
|
208
209
|
exports: organizedExports,
|
|
209
210
|
additionalTypes: organizedAdditionalTypes,
|
|
@@ -229,6 +230,7 @@ export async function syncTypes(options) {
|
|
|
229
230
|
},
|
|
230
231
|
typeNameMap,
|
|
231
232
|
externalTypes,
|
|
233
|
+
externalTypeLinks,
|
|
232
234
|
path: relativePath
|
|
233
235
|
});
|
|
234
236
|
const markdownEnd = performance.now();
|
|
@@ -259,6 +261,7 @@ export async function syncTypes(options) {
|
|
|
259
261
|
additionalTypes: organizedAdditionalTypes,
|
|
260
262
|
variantOnlyAdditionalTypes: organizedVariantOnlyAdditionalTypes,
|
|
261
263
|
externalTypes,
|
|
264
|
+
externalTypeLinks,
|
|
262
265
|
typeNameMap: typeNameMap ?? {},
|
|
263
266
|
variantTypeNames,
|
|
264
267
|
variantTypeNameMaps,
|
|
@@ -329,6 +332,7 @@ export async function syncTypes(options) {
|
|
|
329
332
|
additionalTypes: organizedAdditionalTypes,
|
|
330
333
|
variantOnlyAdditionalTypes: organizedVariantOnlyAdditionalTypes,
|
|
331
334
|
externalTypes,
|
|
335
|
+
externalTypeLinks,
|
|
332
336
|
allDependencies: dependencies,
|
|
333
337
|
typeNameMap: typeNameMap ?? {},
|
|
334
338
|
variantTypeNames,
|
|
@@ -160,7 +160,7 @@ export interface ExportConfig {
|
|
|
160
160
|
globals?: VariantExtraFiles;
|
|
161
161
|
} | undefined;
|
|
162
162
|
/**
|
|
163
|
-
* Version overrides for
|
|
163
|
+
* Version overrides for exported packages, including React and its type packages.
|
|
164
164
|
* @example
|
|
165
165
|
* versions: {
|
|
166
166
|
* '@types/react': '^19',
|
|
@@ -171,7 +171,8 @@ export interface ExportConfig {
|
|
|
171
171
|
*/
|
|
172
172
|
versions?: Record<string, string>;
|
|
173
173
|
/**
|
|
174
|
-
*
|
|
174
|
+
* Resolves imported packages and their peers, including packages pinned in `versions`.
|
|
175
|
+
* `importedModules` contains the complete imports belonging to each package.
|
|
175
176
|
* @example
|
|
176
177
|
* resolveDependencies: (packageName, envVars) => {
|
|
177
178
|
* if (packageName === '@mui/material') {
|
|
@@ -180,7 +181,7 @@ export interface ExportConfig {
|
|
|
180
181
|
* return { [packageName]: 'latest' };
|
|
181
182
|
* }
|
|
182
183
|
*/
|
|
183
|
-
resolveDependencies?: (packageName: string, envVars?: Record<string, string
|
|
184
|
+
resolveDependencies?: (packageName: string, envVars?: Record<string, string>, importedModules?: string[]) => Record<string, string>;
|
|
184
185
|
}
|
|
185
186
|
/**
|
|
186
187
|
* Export a variant as a standalone project with metadata files properly scoped
|
|
@@ -286,20 +286,25 @@ export function exportVariant(variantCode, config = {}) {
|
|
|
286
286
|
|
|
287
287
|
// Check if they're providing their own framework
|
|
288
288
|
const isFramework = 'frameworkFiles' in config;
|
|
289
|
-
const
|
|
289
|
+
const importedModules = processedVariantCode.externals || [];
|
|
290
|
+
const externalPackages = externalsToPackages(importedModules);
|
|
290
291
|
const variantDeps = Object.keys(externalPackages).reduce((acc, pkg) => {
|
|
291
|
-
|
|
292
|
-
if (
|
|
293
|
-
acc
|
|
294
|
-
} else if (resolveDependencies) {
|
|
295
|
-
const resolvedDeps = resolveDependencies(pkg);
|
|
296
|
-
Object.assign(acc, resolvedDeps);
|
|
292
|
+
const packageImports = importedModules.filter(name => name === pkg || name.startsWith(`${pkg}/`));
|
|
293
|
+
if (resolveDependencies) {
|
|
294
|
+
Object.assign(acc, resolveDependencies(pkg, undefined, packageImports));
|
|
297
295
|
} else {
|
|
298
|
-
// Simple fallback: just use 'latest' for each package
|
|
299
296
|
acc[pkg] = 'latest';
|
|
300
297
|
}
|
|
298
|
+
if (versions[pkg] !== undefined) {
|
|
299
|
+
acc[pkg] = versions[pkg];
|
|
300
|
+
}
|
|
301
301
|
return acc;
|
|
302
302
|
}, {});
|
|
303
|
+
for (const pkg of Object.keys(variantDeps)) {
|
|
304
|
+
if (versions[pkg] !== undefined) {
|
|
305
|
+
variantDeps[pkg] = versions[pkg];
|
|
306
|
+
}
|
|
307
|
+
}
|
|
303
308
|
|
|
304
309
|
// Collect metadata files to be generated
|
|
305
310
|
const metadataFiles = {};
|