@mui/internal-docs-infra 0.13.1-canary.25 → 0.13.1-canary.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/abstractCreateTypes/abstractCreateTypes.d.mts +5 -0
  2. package/abstractCreateTypes/abstractCreateTypes.mjs +31 -87
  3. package/package.json +2 -2
  4. package/pipeline/enhanceCodeTypes/enhanceChildren.d.mts +8 -0
  5. package/pipeline/enhanceCodeTypes/enhanceChildren.mjs +51 -1
  6. package/pipeline/enhanceCodeTypes/enhanceCodeTypes.d.mts +9 -0
  7. package/pipeline/enhanceCodeTypes/enhanceCodeTypes.mjs +8 -8
  8. package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.mjs +2 -1
  9. package/pipeline/loadServerTypes/loadServerTypes.d.mts +5 -0
  10. package/pipeline/loadServerTypes/loadServerTypes.mjs +2 -1
  11. package/pipeline/loadServerTypesMeta/constantGroups.d.mts +1 -1
  12. package/pipeline/loadServerTypesMeta/constantGroups.mjs +7 -3
  13. package/pipeline/loadServerTypesMeta/externalTypes.d.mts +23 -0
  14. package/pipeline/loadServerTypesMeta/externalTypes.mjs +52 -1
  15. package/pipeline/loadServerTypesMeta/formatType.d.mts +1 -1
  16. package/pipeline/loadServerTypesMeta/formatType.mjs +44 -13
  17. package/pipeline/loadServerTypesMeta/loadServerTypesMeta.d.mts +5 -0
  18. package/pipeline/loadServerTypesMeta/loadServerTypesMeta.mjs +11 -0
  19. package/pipeline/loadServerTypesMeta/mdnTypeLinks.d.mts +6 -0
  20. package/pipeline/loadServerTypesMeta/mdnTypeLinks.mjs +144 -0
  21. package/pipeline/loadServerTypesMeta/parseTestSources.d.mts +6 -1
  22. package/pipeline/loadServerTypesMeta/parseTestSources.mjs +6 -4
  23. package/pipeline/loadServerTypesText/loadServerTypesText.d.mts +2 -0
  24. package/pipeline/loadServerTypesText/normalizeTypesSourceDataForCache.mjs +1 -0
  25. package/pipeline/loadServerTypesText/parseTypesMarkdown.d.mts +1 -0
  26. package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs +12 -2
  27. package/pipeline/syncTypes/generateTypesMarkdown.d.mts +2 -0
  28. package/pipeline/syncTypes/generateTypesMarkdown.mjs +9 -0
  29. package/pipeline/syncTypes/syncTypes.mjs +4 -0
@@ -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 anchorMap is available.
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.25",
3
+ "version": "0.13.1-canary.27",
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": "14af67ff2d43511e6f866e18b25a41ae856409eb"
816
+ "gitSha": "b6d33f09a4ab6edc8e98f07f595bc7bc7580d250"
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
- let linkMap = {};
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,
@@ -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.
@@ -332,6 +332,7 @@ async function enhanceTypes(syncResult, {
332
332
  typeNameMap: syncResult.typeNameMap,
333
333
  anchorMap: {
334
334
  js: anchorMap
335
- }
335
+ },
336
+ externalTypeLinks: syncResult.externalTypeLinks ?? {}
336
337
  };
337
338
  }
@@ -12,7 +12,7 @@ export type ComponentConstantGroups = Partial<Record<ConstantGroupKind, tae.Enum
12
12
  /** The value of a constant in a constant group. */
13
13
  type ConstantValue = string | number;
14
14
  /**
15
- * Finds the entrypoint's namespace exports whose module holds nothing but literal constants,
15
+ * Finds the entrypoint's namespace exports whose module's value exports are all literal constants,
16
16
  * e.g. `export * as ButtonDataAttributes from './ButtonDataAttributes'`, with their values.
17
17
  * Namespaces nested in other namespace exports are found too, under their dotted path
18
18
  * (`Toolbar.ButtonDataAttributes`).
@@ -41,11 +41,15 @@ function readLiteralConstant(symbol, checker) {
41
41
  }
42
42
 
43
43
  /**
44
- * Reads a module's exports as constant values, when it exports nothing but literal constants.
44
+ * Reads a module's exports as constant values, when its value exports are nothing but literal
45
+ * constants. Type-only exports, such as a union of the constants, are typing helpers and are
46
+ * skipped rather than disqualifying the module.
45
47
  */
46
48
  function readConstantModule(moduleSymbol, checker) {
47
49
  const values = new Map();
48
- const members = checker.getExportsOfModule(moduleSymbol);
50
+ const members = checker.getExportsOfModule(moduleSymbol)
51
+ // eslint-disable-next-line no-bitwise -- TypeScript symbol flags are a bitmask
52
+ .filter(member => resolveAlias(member, checker).flags & ts.SymbolFlags.Value);
49
53
  const isConstantModule = members.length > 0 && members.every(member => {
50
54
  const value = readLiteralConstant(resolveAlias(member, checker), checker);
51
55
  if (value === undefined) {
@@ -58,7 +62,7 @@ function readConstantModule(moduleSymbol, checker) {
58
62
  }
59
63
 
60
64
  /**
61
- * Finds the entrypoint's namespace exports whose module holds nothing but literal constants,
65
+ * Finds the entrypoint's namespace exports whose module's value exports are all literal constants,
62
66
  * e.g. `export * as ButtonDataAttributes from './ButtonDataAttributes'`, with their values.
63
67
  * Namespaces nested in other namespace exports are found too, under their dotted path
64
68
  * (`Toolbar.ButtonDataAttributes`).
@@ -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
- return createNameWithTypeArguments(type.typeName, exportNames, typeNameMap, externalTypesCollector, preserveTypeParameters);
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 ? getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters) : type.intrinsic;
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 = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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 = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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 = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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 = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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 = getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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 getFullyQualifiedName(type.typeName, exportNames, typeNameMap, preserveTypeParameters);
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
- const nameWithTypeArgs = createNameWithTypeArguments(typeName, exportNames, typeNameMap, undefined, preserveTypeParameters); // Note: externalTypesCollector not threaded here since getFullyQualifiedName is name-only lookup
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(LIB_PATH, ts.createSourceFile(LIB_PATH, lib, ts.ScriptTarget.ESNext, true));
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: () => LIB_PATH,
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 === 'export-groups') {
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,