@mui/internal-docs-infra 0.13.1-canary.3 → 0.13.1-canary.31

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 (106) hide show
  1. package/ChunkProvider/types.d.mts +1 -1
  2. package/CodeControllerContext/CodeControllerContext.d.mts +1 -1
  3. package/CodeControllerContext/CodeControllerContext.mjs +1 -1
  4. package/CodeHighlighter/types.d.mts +3 -3
  5. package/CoordinatedLazy/CoordinatedContentContext.d.mts +1 -1
  6. package/CoordinatedLazy/CoordinatedContentContext.mjs +1 -1
  7. package/CoordinatedLazy/CoordinatedGateContext.d.mts +1 -1
  8. package/CoordinatedLazy/CoordinatedGateContext.mjs +1 -1
  9. package/CoordinatedLazy/createCoordinatedLazy.d.mts +1 -1
  10. package/CoordinatedLazy/createCoordinatedLazy.mjs +1 -1
  11. package/CoordinatedLazy/types.d.mts +5 -5
  12. package/abstractCreateStream/types.d.mts +1 -1
  13. package/abstractCreateTypes/abstractCreateTypes.d.mts +5 -0
  14. package/abstractCreateTypes/abstractCreateTypes.mjs +31 -87
  15. package/cli/index.d.mts +1 -0
  16. package/cli/index.mjs +1 -0
  17. package/createSitemap/createSitemap.d.mts +1 -1
  18. package/createSitemap/createSitemap.mjs +1 -1
  19. package/package.json +18 -18
  20. package/pipeline/enhanceCodeEmphasis/emphasisCommentUtils.mjs +3 -1
  21. package/pipeline/enhanceCodeInline/enhanceCodeInline.d.mts +1 -1
  22. package/pipeline/enhanceCodeInline/enhanceCodeInline.mjs +1 -1
  23. package/pipeline/enhanceCodeTypes/enhanceChildren.d.mts +8 -0
  24. package/pipeline/enhanceCodeTypes/enhanceChildren.mjs +51 -1
  25. package/pipeline/enhanceCodeTypes/enhanceCodeTypes.d.mts +9 -0
  26. package/pipeline/enhanceCodeTypes/enhanceCodeTypes.mjs +8 -8
  27. package/pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.d.mts +1 -1
  28. package/pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs +1 -1
  29. package/pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.d.mts +3 -3
  30. package/pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs +3 -3
  31. package/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.mjs +74 -9
  32. package/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.mjs +2 -1
  33. package/pipeline/loadServerPageIndex/extractPrefixAndTitle.d.mts +2 -2
  34. package/pipeline/loadServerPageIndex/extractPrefixAndTitle.mjs +2 -2
  35. package/pipeline/loadServerTypes/loadServerTypes.d.mts +5 -0
  36. package/pipeline/loadServerTypes/loadServerTypes.mjs +2 -1
  37. package/pipeline/loadServerTypesMeta/builtInTypes.d.mts +1 -1
  38. package/pipeline/loadServerTypesMeta/constantGroups.d.mts +2 -2
  39. package/pipeline/loadServerTypesMeta/constantGroups.mjs +15 -5
  40. package/pipeline/loadServerTypesMeta/constants.d.mts +1 -1
  41. package/pipeline/loadServerTypesMeta/createOptimizedProgram.mjs +0 -3
  42. package/pipeline/loadServerTypesMeta/dropTypeOnlyDuplicates.d.mts +11 -0
  43. package/pipeline/loadServerTypesMeta/dropTypeOnlyDuplicates.mjs +31 -0
  44. package/pipeline/loadServerTypesMeta/externalTypes.d.mts +24 -1
  45. package/pipeline/loadServerTypesMeta/externalTypes.mjs +52 -1
  46. package/pipeline/loadServerTypesMeta/format.d.mts +1 -1
  47. package/pipeline/loadServerTypesMeta/formatClass.d.mts +1 -1
  48. package/pipeline/loadServerTypesMeta/formatComponent.d.mts +1 -1
  49. package/pipeline/loadServerTypesMeta/formatFunction.d.mts +1 -1
  50. package/pipeline/loadServerTypesMeta/formatHook.d.mts +1 -1
  51. package/pipeline/loadServerTypesMeta/formatRaw.d.mts +1 -1
  52. package/pipeline/loadServerTypesMeta/formatType.d.mts +2 -2
  53. package/pipeline/loadServerTypesMeta/formatType.mjs +44 -13
  54. package/pipeline/loadServerTypesMeta/inheritedExternalProps.d.mts +1 -1
  55. package/pipeline/loadServerTypesMeta/inheritedExternalProps.mjs +1 -1
  56. package/pipeline/loadServerTypesMeta/loadServerTypesMeta.d.mts +5 -0
  57. package/pipeline/loadServerTypesMeta/loadServerTypesMeta.mjs +11 -0
  58. package/pipeline/loadServerTypesMeta/loadTypescriptConfig.d.mts +4 -0
  59. package/pipeline/loadServerTypesMeta/loadTypescriptConfig.mjs +41 -76
  60. package/pipeline/loadServerTypesMeta/mdnTypeLinks.d.mts +6 -0
  61. package/pipeline/loadServerTypesMeta/mdnTypeLinks.mjs +144 -0
  62. package/pipeline/loadServerTypesMeta/parseTestSources.d.mts +7 -2
  63. package/pipeline/loadServerTypesMeta/parseTestSources.mjs +7 -5
  64. package/pipeline/loadServerTypesMeta/performanceTracking.d.mts +0 -1
  65. package/pipeline/loadServerTypesMeta/performanceTracking.mjs +1 -4
  66. package/pipeline/loadServerTypesMeta/processTypes.d.mts +1 -1
  67. package/pipeline/loadServerTypesMeta/processTypes.mjs +3 -2
  68. package/pipeline/loadServerTypesMeta/rewriteTypes.d.mts +1 -1
  69. package/pipeline/loadServerTypesMeta/socketServer.mjs +0 -4
  70. package/pipeline/loadServerTypesMeta/templateLiteral.d.mts +1 -1
  71. package/pipeline/loadServerTypesMeta/typeGuards.d.mts +1 -1
  72. package/pipeline/loadServerTypesMeta/workerManager.mjs +8 -11
  73. package/pipeline/loadServerTypesText/loadServerTypesText.d.mts +2 -0
  74. package/pipeline/loadServerTypesText/normalizeTypesSourceDataForCache.mjs +1 -0
  75. package/pipeline/loadServerTypesText/parseTypesMarkdown.d.mts +1 -0
  76. package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs +12 -2
  77. package/pipeline/loaderUtils/getLanguageFromExtension.d.mts +3 -3
  78. package/pipeline/loaderUtils/getLanguageFromExtension.mjs +3 -3
  79. package/pipeline/loaderUtils/normalizeCommentContent.d.mts +5 -0
  80. package/pipeline/loaderUtils/normalizeCommentContent.mjs +13 -0
  81. package/pipeline/loaderUtils/parseImportsAndComments.mjs +5 -25
  82. package/pipeline/loaderUtils/processRelativeImports.d.mts +1 -1
  83. package/pipeline/loaderUtils/processRelativeImports.mjs +1 -1
  84. package/pipeline/loaderUtils/resolveModulePath.d.mts +1 -1
  85. package/pipeline/loaderUtils/resolveModulePath.mjs +1 -1
  86. package/pipeline/loaderUtils/stripRouteGroups.d.mts +5 -5
  87. package/pipeline/loaderUtils/stripRouteGroups.mjs +5 -5
  88. package/pipeline/parseSource/grammarMaps.d.mts +1 -1
  89. package/pipeline/parseSource/grammarMaps.mjs +1 -1
  90. package/pipeline/syncPageIndex/syncPageIndex.d.mts +2 -2
  91. package/pipeline/syncPageIndex/syncPageIndex.mjs +2 -2
  92. package/pipeline/syncTypes/generateTypesMarkdown.d.mts +2 -0
  93. package/pipeline/syncTypes/generateTypesMarkdown.mjs +11 -2
  94. package/pipeline/syncTypes/syncTypes.mjs +4 -0
  95. package/useCode/useCode.d.mts +1 -1
  96. package/useCoordinated/useCoordinated.d.mts +2 -2
  97. package/useCoordinated/useCoordinated.mjs +2 -2
  98. package/useCoordinated/useCoordinatedLazy.d.mts +1 -1
  99. package/useCoordinated/useCoordinatedLazy.mjs +1 -1
  100. package/useCopier/index.mjs +1 -2
  101. package/useDemo/exportVariant.d.mts +4 -3
  102. package/useDemo/exportVariant.mjs +13 -8
  103. package/useType/useType.d.mts +1 -1
  104. package/useType/useType.mjs +1 -1
  105. package/useType/useTypeProp.d.mts +2 -2
  106. package/useType/useTypeProp.mjs +2 -2
@@ -2,7 +2,7 @@ import type * as React from 'react';
2
2
  import type { StreamSource } from "../CoordinatedLazy/types.mjs";
3
3
  /**
4
4
  * Provided by a `ChunkProvider`: lazily resolve the client `StreamSource` for
5
- * descendant chunks. Called only when a chunk actually needs to load (i.e. it
5
+ * descendant chunks. Called only when a chunk actually needs to load (that is, it
6
6
  * was not preloaded), so the loader module stays out of the initial bundle and
7
7
  * is never imported when everything is precomputed.
8
8
  */
@@ -87,7 +87,7 @@ export type CodeControllerProps<T extends {} = {}> = {
87
87
  * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
88
88
  * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
89
89
  * such as `useDemoController`. Parameterize with `T` for the controller's own props
90
- * (e.g. `CodeController<UseDemoControllerOptions>`).
90
+ * (for example, `CodeController<UseDemoControllerOptions>`).
91
91
  */
92
92
  export type CodeController<T extends {} = {}> = React.ComponentType<CodeControllerProps<T>>;
93
93
  export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
@@ -20,7 +20,7 @@ import * as React from 'react';
20
20
  * A code-controller component — the counterpart to `DemoContent`. It wraps `children`
21
21
  * in a {@link CodeControllerContext} provider, typically sourcing the value from a hook
22
22
  * such as `useDemoController`. Parameterize with `T` for the controller's own props
23
- * (e.g. `CodeController<UseDemoControllerOptions>`).
23
+ * (for example, `CodeController<UseDemoControllerOptions>`).
24
24
  */
25
25
 
26
26
  export const CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
@@ -504,7 +504,7 @@ export interface CodeContentProps {
504
504
  code?: Code;
505
505
  /** React components for live preview alongside code */
506
506
  components?: Components;
507
- /** What type of variants are available (e.g., a type `packageManager` when variants `npm` and `yarn` are available) */
507
+ /** What type of variants are available (for example, a type `packageManager` when variants `npm` and `yarn` are available) */
508
508
  variantType?: string;
509
509
  /** Static variant names that should be fetched at runtime */
510
510
  variants?: string[];
@@ -512,7 +512,7 @@ export interface CodeContentProps {
512
512
  variant?: string;
513
513
  /** Currently selected file name */
514
514
  fileName?: string;
515
- /** Language for syntax highlighting (e.g., 'tsx', 'css'). When provided, fileName is not required for parsing. */
515
+ /** Language for syntax highlighting (for example, 'tsx', 'css'). When provided, fileName is not required for parsing. */
516
516
  language?: string;
517
517
  /** Default variant to show on first load */
518
518
  initialVariant?: string;
@@ -588,7 +588,7 @@ export interface CodeFunctionProps {
588
588
  loadVariantMeta?: LoadVariantMeta;
589
589
  /** Function to load raw source code and dependencies */
590
590
  loadSource?: LoadSource;
591
- /** Array of source transformers for code processing (e.g., TypeScript to JavaScript) */
591
+ /** Array of source transformers for code processing (for example, TypeScript to JavaScript) */
592
592
  sourceTransformers?: SourceTransformers;
593
593
  /** Promise resolving to a source parser for syntax highlighting */
594
594
  sourceParser?: Promise<ParseSource>;
@@ -8,7 +8,7 @@ import type { CoordinatedContentContextValue } from "./types.mjs";
8
8
  export declare const CoordinatedContentContext: React.Context<CoordinatedContentContextValue>;
9
9
  /**
10
10
  * Read the data the fallback hoisted, from inside the full content. Lets the
11
- * content use what the fallback fetched (e.g. a decompression dictionary)
11
+ * content use what the fallback fetched (for example, a decompression dictionary)
12
12
  * without the consumer threading it through props. Returns an empty map when
13
13
  * rendered outside a `CoordinatedLazy`.
14
14
  */
@@ -12,7 +12,7 @@ export const CoordinatedContentContext = /*#__PURE__*/React.createContext({
12
12
 
13
13
  /**
14
14
  * Read the data the fallback hoisted, from inside the full content. Lets the
15
- * content use what the fallback fetched (e.g. a decompression dictionary)
15
+ * content use what the fallback fetched (for example, a decompression dictionary)
16
16
  * without the consumer threading it through props. Returns an empty map when
17
17
  * rendered outside a `CoordinatedLazy`.
18
18
  */
@@ -2,7 +2,7 @@ import * as React from 'react';
2
2
  import type { SettleGate } from "../useCoordinated/createSettleGate.mjs";
3
3
  /**
4
4
  * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
5
- * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
5
+ * when it isn't given an explicit `gate` prop. A coordinator (for example, the
6
6
  * `useStream` controller) provides its gate here so every swap rendered beneath
7
7
  * it reports into the same gate - that is how a group's `loading` reflects each
8
8
  * piece's swap without threading a `gate` prop through every one. `null` outside
@@ -3,7 +3,7 @@
3
3
  import * as React from 'react';
4
4
  /**
5
5
  * The ambient settle gate that a {@link CoordinatedLazy} swap registers with
6
- * when it isn't given an explicit `gate` prop. A coordinator (e.g. the
6
+ * when it isn't given an explicit `gate` prop. A coordinator (for example, the
7
7
  * `useStream` controller) provides its gate here so every swap rendered beneath
8
8
  * it reports into the same gate - that is how a group's `loading` reflects each
9
9
  * piece's swap without threading a `gate` prop through every one. `null` outside
@@ -20,7 +20,7 @@ import type { ChunkComponentProps, CreateChunkConfig } from "./types.mjs";
20
20
  * The client-mode branch hands the (function-bearing) `config` to a `'use client'`
21
21
  * component, so a client-loaded chunk must render inside a client subtree - call
22
22
  * `createCoordinatedLazy` from a client module, or wrap it in a client provider
23
- * (e.g. `abstractCreateStream`'s `ClientProvider`). Server-loaded and
23
+ * (for example, `abstractCreateStream`'s `ClientProvider`). Server-loaded and
24
24
  * preloaded/precomputed chunks have no such constraint - they render entirely on
25
25
  * the server path.
26
26
  *
@@ -28,7 +28,7 @@ function RenderNull() {
28
28
  * The client-mode branch hands the (function-bearing) `config` to a `'use client'`
29
29
  * component, so a client-loaded chunk must render inside a client subtree - call
30
30
  * `createCoordinatedLazy` from a client module, or wrap it in a client provider
31
- * (e.g. `abstractCreateStream`'s `ClientProvider`). Server-loaded and
31
+ * (for example, `abstractCreateStream`'s `ClientProvider`). Server-loaded and
32
32
  * preloaded/precomputed chunks have no such constraint - they render entirely on
33
33
  * the server path.
34
34
  *
@@ -32,7 +32,7 @@ export interface CoordinatedFallbackContextValue {
32
32
  }
33
33
  /**
34
34
  * The data the fallback hoisted, handed down to the full content so it can use
35
- * what the fallback fetched (e.g. a DEFLATE dictionary). Read via
35
+ * what the fallback fetched (for example, a DEFLATE dictionary). Read via
36
36
  * {@link useCoordinatedContent}.
37
37
  */
38
38
  export interface CoordinatedContentContextValue {
@@ -88,7 +88,7 @@ export interface UseCoordinatedSwapOptions {
88
88
  awaitContent?: boolean;
89
89
  /**
90
90
  * Settle gate to register this swap with. When omitted, the ambient gate from
91
- * a surrounding coordinator (e.g. the `useStream` controller, via
91
+ * a surrounding coordinator (for example, the `useStream` controller, via
92
92
  * {@link CoordinatedGateContext}) is used instead. The page-global gate is
93
93
  * always registered on top of either, so a page-wide coordinated commit waits
94
94
  * for the swap regardless.
@@ -149,14 +149,14 @@ export interface CoordinatedLazyProps {
149
149
  requireHoist?: boolean;
150
150
  /**
151
151
  * Hold the swap until the content reports it has loaded, mounting the content
152
- * behind the fallback so a code-split (e.g. `LazyContent`) content can load in
152
+ * behind the fallback so a code-split (for example, `LazyContent`) content can load in
153
153
  * the background and reveal only once its chunk has arrived. See
154
154
  * {@link UseCoordinatedSwapOptions.awaitContent}.
155
155
  */
156
156
  awaitContent?: boolean;
157
157
  /**
158
158
  * Settle gate to register this swap with. When omitted, the ambient gate from
159
- * a surrounding coordinator (e.g. the `useStream` controller, via
159
+ * a surrounding coordinator (for example, the `useStream` controller, via
160
160
  * {@link CoordinatedGateContext}) is used instead. The page-global gate is
161
161
  * always registered on top of either, so a page-wide coordinated commit waits
162
162
  * for the swap regardless.
@@ -400,7 +400,7 @@ export interface LazyContentProps<T extends {} = {}> {
400
400
  fallback?: React.ReactNode;
401
401
  /**
402
402
  * Additional settle gate to report readiness to once the component has loaded
403
- * and mounted (e.g. a `useStream` controller gate). The page-global gate is
403
+ * and mounted (for example, a `useStream` controller gate). The page-global gate is
404
404
  * always registered too. Client path only - the server path streams via
405
405
  * Suspense and has no client gate to report to.
406
406
  */
@@ -2,7 +2,7 @@ import type * as React from 'react';
2
2
  import type { CreateChunkConfig } from "../CoordinatedLazy/types.mjs";
3
3
  /**
4
4
  * Options bound by {@link createStreamFactory}. Extends the chunk config with
5
- * an optional client provider (e.g. a `ChunkProvider` supplying client loaders,
5
+ * an optional client provider (for example, a `ChunkProvider` supplying client loaders,
6
6
  * or a `PreloadProvider`) wrapped around the chunk.
7
7
  *
8
8
  * All loader functions on the config are expected to be dynamically imported by
@@ -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/cli/index.d.mts CHANGED
@@ -1 +1,2 @@
1
+ #!/usr/bin/env node
1
2
  export {};
package/cli/index.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ #!/usr/bin/env node
1
2
  import { createRequire } from 'node:module';
2
3
  import yargs from 'yargs';
3
4
  import { hideBin } from 'yargs/helpers';
@@ -13,7 +13,7 @@ type CreateSitemapMeta = {
13
13
  * Returns a sitemap data object containing schema and page data.
14
14
  *
15
15
  * In Next.js builds, the webpack loader precomputes the sitemap data.
16
- * Outside Next.js (e.g., tests or scripts), use `loadServerSitemap()` for runtime loading.
16
+ * Outside Next.js (for example, tests or scripts), use `loadServerSitemap()` for runtime loading.
17
17
  *
18
18
  * @param sourceUrl Depends on `import.meta.url` to determine the source file location.
19
19
  * @param pages Record of page components indexed by path.
@@ -17,7 +17,7 @@ function isNextJsContext() {
17
17
  * Returns a sitemap data object containing schema and page data.
18
18
  *
19
19
  * In Next.js builds, the webpack loader precomputes the sitemap data.
20
- * Outside Next.js (e.g., tests or scripts), use `loadServerSitemap()` for runtime loading.
20
+ * Outside Next.js (for example, tests or scripts), use `loadServerSitemap()` for runtime loading.
21
21
  *
22
22
  * @param sourceUrl Depends on `import.meta.url` to determine the source file location.
23
23
  * @param pages Record of page components indexed by path.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mui/internal-docs-infra",
3
- "version": "0.13.1-canary.3",
3
+ "version": "0.13.1-canary.31",
4
4
  "author": "MUI Team",
5
5
  "description": "MUI Infra - internal documentation creation tools.",
6
6
  "license": "MIT",
@@ -29,29 +29,29 @@
29
29
  },
30
30
  "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
31
31
  "dependencies": {
32
- "@babel/runtime": "^8.0.5",
33
- "@csstools/postcss-light-dark-function": "^3.0.4",
34
- "@csstools/postcss-relative-color-syntax": "^4.0.11",
35
- "@csstools/postcss-stepped-value-functions": "^5.0.5",
32
+ "@babel/runtime": "^8.1.0",
33
+ "@csstools/postcss-light-dark-function": "^3.0.8",
34
+ "@csstools/postcss-relative-color-syntax": "^4.0.16",
35
+ "@csstools/postcss-stepped-value-functions": "^5.0.9",
36
+ "@mui/internal-typescript-api-extractor": "0.1.1-canary.2",
36
37
  "@orama/orama": "^3.1.18",
37
38
  "@orama/plugin-qps": "^3.1.18",
38
39
  "@orama/stemmers": "^3.1.18",
39
40
  "@wooorm/starry-night": "^3.11.0",
40
- "autoprefixer": "^10.6.0",
41
- "chalk": "^6.0.0",
42
- "clipboard-copy": "^4.0.1",
43
- "es-toolkit": "^1.52.0",
41
+ "autoprefixer": "^10.6.2",
42
+ "chalk": "^6.0.1",
43
+ "es-toolkit": "^1.53.2",
44
44
  "fflate": "^0.8.3",
45
- "hast-util-to-jsx-runtime": "^2.3.6",
46
- "hast-util-to-text": "^4.0.2",
45
+ "hast-util-to-jsx-runtime": "^2.3.7",
46
+ "hast-util-to-text": "^4.0.3",
47
47
  "icss-utils": "^5.1.0",
48
48
  "import-meta-resolve": "^4.2.0",
49
49
  "jiti": "^2.7.0",
50
- "jsondiffpatch": "^0.7.6",
50
+ "jsondiffpatch": "^0.7.7",
51
51
  "kebab-case": "^2.0.2",
52
52
  "lz-string": "^1.5.0",
53
53
  "path-module": "^0.1.2",
54
- "postcss": "^8.5.28",
54
+ "postcss": "^8.5.32",
55
55
  "postcss-modules-extract-imports": "^3.1.0",
56
56
  "postcss-modules-local-by-default": "^4.2.0",
57
57
  "postcss-modules-scope": "^3.2.1",
@@ -61,16 +61,16 @@
61
61
  "remark-gfm": "^4.0.1",
62
62
  "remark-mdx": "^3.1.1",
63
63
  "remark-parse": "^11.0.0",
64
+ "remark-rehype": "^11.1.2",
64
65
  "remark-stringify": "^11.0.0",
65
- "remark-typography": "^0.8.6",
66
+ "remark-typography": "^0.8.11",
66
67
  "sucrase": "^3.35.1",
67
68
  "typescript": "npm:@typescript/typescript6@6.0.2",
68
- "typescript-api-extractor": "1.0.0-beta.7",
69
69
  "uint8-to-base64": "^0.2.1",
70
70
  "unified": "^11.0.5",
71
- "unist-util-visit": "^5.1.0",
71
+ "unist-util-visit": "^5.2.0",
72
72
  "vscode-oniguruma": "^2.0.1",
73
- "yargs": "^18.1.0",
73
+ "yargs": "^18.2.0",
74
74
  "zx": "^8.8.5"
75
75
  },
76
76
  "peerDependencies": {
@@ -814,5 +814,5 @@
814
814
  "bin": {
815
815
  "docs-infra": "./cli/index.mjs"
816
816
  },
817
- "gitSha": "d81524e8f3c59df916d9e262bdad83961cb98512"
817
+ "gitSha": "fb999aabc9746b50f3cd915e236d646cf894eff4"
818
818
  }
@@ -1,3 +1,5 @@
1
+ import { normalizeCommentContent } from "../loaderUtils/normalizeCommentContent.mjs";
2
+
1
3
  /**
2
4
  * The prefix used to identify emphasis comments in source code.
3
5
  * Comments starting with this prefix will be processed for emphasis.
@@ -120,7 +122,7 @@ export function getUnquotedCommentTokens(comment) {
120
122
  * Returns whether a parsed comment contains a real focus directive.
121
123
  */
122
124
  export function hasFocusDirective(comment) {
123
- const tokens = getUnquotedCommentTokens(comment);
125
+ const tokens = getUnquotedCommentTokens(normalizeCommentContent(comment));
124
126
  const firstToken = tokens[0];
125
127
  if (firstToken === FOCUS_COMMENT_PREFIX || firstToken === `${FOCUS_COMMENT_PREFIX}-start` || firstToken === `${FOCUS_COMMENT_PREFIX}-end`) {
126
128
  return true;
@@ -9,7 +9,7 @@ import type { Root as HastRoot } from 'hast';
9
9
  * inside — no semantic information is destroyed.
10
10
  *
11
11
  * 2. **Token reclassification**: Corrects misidentified token classes,
12
- * e.g., `function` marked as `pl-en` is changed to `pl-k` (keyword).
12
+ * for example, `function` marked as `pl-en` is changed to `pl-k` (keyword).
13
13
  *
14
14
  * 3. **Built-in type enhancement** (TypeScript only): Reclassifies standalone
15
15
  * type keywords (`string`, `number`, `void`, etc.) from `pl-smi`/`pl-k`
@@ -350,7 +350,7 @@ function enhanceBuiltInTypes(children) {
350
350
  * inside — no semantic information is destroyed.
351
351
  *
352
352
  * 2. **Token reclassification**: Corrects misidentified token classes,
353
- * e.g., `function` marked as `pl-en` is changed to `pl-k` (keyword).
353
+ * for example, `function` marked as `pl-en` is changed to `pl-k` (keyword).
354
354
  *
355
355
  * 3. **Built-in type enhancement** (TypeScript only): Reclassifies standalone
356
356
  * type keywords (`string`, `number`, `void`, etc.) from `pl-smi`/`pl-k`
@@ -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,
@@ -8,7 +8,7 @@ import type { Code } from "../../CodeHighlighter/types.mjs";
8
8
  * Used primarily to determine when to show the full Content component instead of ContentLoading
9
9
  * fallback, ensuring a smooth user experience without rendering errors.
10
10
  *
11
- * @param variants - Array of variant names that must all be ready (e.g., ['javascript', 'typescript'])
11
+ * @param variants - Array of variant names that must all be ready (for example, `['javascript', 'typescript']`)
12
12
  * @param code - The code object containing variant data
13
13
  * @param needsHighlight - Whether all sources need to be syntax highlighted (hast nodes, not strings)
14
14
  * @returns True if all variants and their files are loaded and ready for full rendering
@@ -26,7 +26,7 @@ function isSourceLoaded(code, needsHighlight) {
26
26
  * Used primarily to determine when to show the full Content component instead of ContentLoading
27
27
  * fallback, ensuring a smooth user experience without rendering errors.
28
28
  *
29
- * @param variants - Array of variant names that must all be ready (e.g., ['javascript', 'typescript'])
29
+ * @param variants - Array of variant names that must all be ready (for example, `['javascript', 'typescript']`)
30
30
  * @param code - The code object containing variant data
31
31
  * @param needsHighlight - Whether all sources need to be syntax highlighted (hast nodes, not strings)
32
32
  * @returns True if all variants and their files are loaded and ready for full rendering