@mui/internal-docs-infra 0.2.0-alpha.1 → 0.2.0

package/esm/pipeline/transformMarkdownCode/transformMarkdownCode.js

@@ -1,8 +1,9 @@
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import { visit } from 'unist-util-visit';
 /**
- * Remark plugin that transforms code blocks with variants into HTML pre/code structures.
+ * Remark plugin that transforms code blocks with variants into semantic HTML structures.
  *
  * Transforms consecutive code blocks with variant metadata like:
  *
@@ -37,19 +38,86 @@ import { visit } from 'unist-util-visit';
  * console.log('test' as const)
  * ```
  *
- * Into HTML that the existing rehype plugin can process:
- * <pre>
- *   <code data-variant="npm">npm install @mui/internal-docs-infra</code>
- *   <code data-variant="pnpm">pnpm install @mui/internal-docs-infra</code>
- *   <code data-variant="yarn">yarn add @mui/internal-docs-infra</code>
- * </pre>
+ * Into semantic HTML that the existing rehype plugin can process:
+ * <section>
+ *   <figure>
+ *     <figcaption>npm variant</figcaption>
+ *     <dl>
+ *       <dt><code>index.js</code></dt>
+ *       <dd>
+ *         <pre><code class="language-bash">npm install @mui/internal-docs-infra</code></pre>
+ *       </dd>
+ *     </dl>
+ *   </figure>
+ *   <figure>
+ *     <figcaption>pnpm variant</figcaption>
+ *     <dl>
+ *       <dt><code>index.js</code></dt>
+ *       <dd>
+ *         <pre><code class="language-bash">pnpm install @mui/internal-docs-infra</code></pre>
+ *       </dd>
+ *     </dl>
+ *   </figure>
+ * </section>
  *
- * Or for individual blocks:
- * <pre>
- *   <code data-transform="true">console.log('test' as const)</code>
- * </pre>
+ * Or for individual blocks (no figure/figcaption needed):
+ * <dl>
+ *   <dt><code>index.ts</code></dt>
+ *   <dd>
+ *     <pre><code class="language-ts" data-transform="true">console.log('test' as const)</code></pre>
+ *   </dd>
+ * </dl>
  */
 
+/**
+ * Maps common language names to file extensions
+ */
+var LANGUAGE_TO_EXTENSION = {
+  // JavaScript
+  javascript: 'js',
+  js: 'js',
+  // TypeScript
+  typescript: 'ts',
+  ts: 'ts',
+  // TSX/JSX
+  tsx: 'tsx',
+  jsx: 'jsx',
+  // JSON
+  json: 'json',
+  // Markdown
+  markdown: 'md',
+  md: 'md',
+  // MDX
+  mdx: 'mdx',
+  // HTML
+  html: 'html',
+  // CSS
+  css: 'css',
+  // Shell
+  shell: 'sh',
+  bash: 'sh',
+  sh: 'sh',
+  // YAML
+  yaml: 'yaml',
+  yml: 'yaml'
+};
+
+/**
+ * Gets filename from language or explicit filename prop
+ */
+function getFileName(language, props) {
+  // Check for explicit filename
+  if (props.filename) {
+    return props.filename;
+  }
+
+  // Derive from language
+  if (language && LANGUAGE_TO_EXTENSION[language]) {
+    return "index.".concat(LANGUAGE_TO_EXTENSION[language]);
+  }
+  return null;
+}
+
 /**
  * Parse meta string to extract variant and other properties
  */
@@ -162,12 +230,12 @@ export var transformMarkdownCode = function transformMarkdownCode() {
 
         // Handle individual code blocks with options (but no variants)
         if (!metaData.variant && !metaData.variantType && Object.keys(allProps).length > 0) {
-          // Create a simple pre/code element for individual blocks with options
-          var hProperties = {};
+          // Create a dl element for individual blocks with options
+          var codeHProperties = {};
 
           // Add language class if available
           if (langFromMeta) {
-            hProperties.className = "language-".concat(langFromMeta);
+            codeHProperties.className = "language-".concat(langFromMeta);
           }
 
           // Add all props as data attributes (in camelCase)
@@ -179,31 +247,67 @@ export var transformMarkdownCode = function transformMarkdownCode() {
             var camelKey = key.includes('-') ? "data".concat(key.split('-').map(function (part) {
               return part.charAt(0).toUpperCase() + part.slice(1);
             }).join('')) : "data".concat(key.charAt(0).toUpperCase() + key.slice(1));
-            hProperties[camelKey] = value;
+            codeHProperties[camelKey] = value;
           });
-          var preElement = {
+          var fileName = getFileName(langFromMeta, allProps);
+          var dlElement = {
             type: 'element',
-            tagName: 'pre',
+            tagName: 'dl',
             data: {
-              hName: 'pre',
+              hName: 'dl',
               hProperties: {}
             },
-            children: [{
+            children: [].concat(_toConsumableArray(fileName ? [{
               type: 'element',
-              tagName: 'code',
+              tagName: 'dt',
               data: {
-                hName: 'code',
-                hProperties: hProperties
+                hName: 'dt',
+                hProperties: {}
               },
               children: [{
-                type: 'text',
-                value: codeNode.value
+                type: 'element',
+                tagName: 'code',
+                data: {
+                  hName: 'code',
+                  hProperties: {}
+                },
+                children: [{
+                  type: 'text',
+                  value: fileName
+                }]
               }]
-            }]
+            }] : []), [{
+              type: 'element',
+              tagName: 'dd',
+              data: {
+                hName: 'dd',
+                hProperties: {}
+              },
+              children: [{
+                type: 'element',
+                tagName: 'pre',
+                data: {
+                  hName: 'pre',
+                  hProperties: {}
+                },
+                children: [{
+                  type: 'element',
+                  tagName: 'code',
+                  data: {
+                    hName: 'code',
+                    hProperties: codeHProperties
+                  },
+                  children: [{
+                    type: 'text',
+                    value: codeNode.value
+                  }]
+                }]
+              }]
+            }])
           };
 
           // Replace this individual code block immediately
-          parentNode.children[index] = preElement;
+          parentNode.children[index] = dlElement;
           processedIndices.add(index);
           return;
         }
@@ -383,23 +487,21 @@ export var transformMarkdownCode = function transformMarkdownCode() {
 
           // Only process if we have multiple blocks
           if (codeBlocks.length > 1) {
-            // Create proper HTML elements with hProperties for remark-rehype compatibility
-            var _preElement = {
+            // Create section with figure elements for each variant
+            var sectionElement = {
               type: 'element',
-              tagName: 'pre',
+              tagName: 'section',
               data: {
-                hName: 'pre',
+                hName: 'section',
                 hProperties: {}
               },
               children: codeBlocks.map(function (block) {
                 // Build hProperties for HTML attributes
-                var hProperties = {
-                  dataVariant: block.variant
-                };
+                var codeHProperties = {};
 
                 // Add language class if available
                 if (block.actualLang) {
-                  hProperties.className = "language-".concat(block.actualLang);
+                  codeHProperties.className = "language-".concat(block.actualLang);
                 }
 
                 // Add additional props as data attributes (in camelCase)
@@ -411,31 +513,97 @@ export var transformMarkdownCode = function transformMarkdownCode() {
                   var camelKey = key.includes('-') ? "data".concat(key.split('-').map(function (part) {
                     return part.charAt(0).toUpperCase() + part.slice(1);
                   }).join('')) : "data".concat(key.charAt(0).toUpperCase() + key.slice(1));
-                  hProperties[camelKey] = value;
+                  codeHProperties[camelKey] = value;
                 });
+
+                // Add data-variant to track the variant
+                codeHProperties.dataVariant = block.variant;
+                var fileName = getFileName(block.actualLang, block.props);
                 return {
                   type: 'element',
-                  tagName: 'code',
+                  tagName: 'figure',
                   data: {
-                    hName: 'code',
-                    hProperties: hProperties,
-                    meta: "variant=".concat(block.variant).concat(Object.entries(block.props).map(function (_ref7) {
-                      var _ref8 = _slicedToArray(_ref7, 2),
-                        key = _ref8[0],
-                        value = _ref8[1];
-                      return " ".concat(key, "=").concat(value);
-                    }).join(''))
+                    hName: 'figure',
+                    hProperties: {}
                   },
                   children: [{
-                    type: 'text',
-                    value: block.node.value
+                    type: 'element',
+                    tagName: 'figcaption',
+                    data: {
+                      hName: 'figcaption',
+                      hProperties: {}
+                    },
+                    children: [{
+                      type: 'text',
+                      value: "".concat(block.variant, " variant")
+                    }]
+                  }, {
+                    type: 'element',
+                    tagName: 'dl',
+                    data: {
+                      hName: 'dl',
+                      hProperties: {}
+                    },
+                    children: [].concat(_toConsumableArray(fileName ? [{
+                      type: 'element',
+                      tagName: 'dt',
+                      data: {
+                        hName: 'dt',
+                        hProperties: {}
+                      },
+                      children: [{
+                        type: 'element',
+                        tagName: 'code',
+                        data: {
+                          hName: 'code',
+                          hProperties: {}
+                        },
+                        children: [{
+                          type: 'text',
+                          value: fileName
+                        }]
+                      }]
+                    }] : []), [{
+                      type: 'element',
+                      tagName: 'dd',
+                      data: {
+                        hName: 'dd',
+                        hProperties: {}
+                      },
+                      children: [{
+                        type: 'element',
+                        tagName: 'pre',
+                        data: {
+                          hName: 'pre',
+                          hProperties: {}
+                        },
+                        children: [{
+                          type: 'element',
+                          tagName: 'code',
+                          data: {
+                            hName: 'code',
+                            hProperties: codeHProperties,
+                            meta: "variant=".concat(block.variant).concat(Object.entries(block.props).map(function (_ref7) {
+                              var _ref8 = _slicedToArray(_ref7, 2),
+                                key = _ref8[0],
+                                value = _ref8[1];
+                              return " ".concat(key, "=").concat(value);
+                            }).join(''))
+                          },
+                          children: [{
+                            type: 'text',
+                            value: block.node.value
+                          }]
+                        }]
+                      }]
+                    }])
                   }]
                 };
               })
             };
 
             // Replace the first block with the group and mark others for removal
-            parentNode.children[codeBlocks[0].index] = _preElement;
+            parentNode.children[codeBlocks[0].index] = sectionElement;
 
             // Remove all other code blocks and their labels (in reverse order to maintain indices)
             var indicesToRemove = codeBlocks.slice(1).map(function (block) {
@@ -506,6 +674,95 @@ export var transformMarkdownCode = function transformMarkdownCode() {
                 });
               }
             }
+          } else if (codeBlocks.length === 1) {
+            // Single code block with variant - create a simple dl without figure wrapper
+            var block = codeBlocks[0];
+            var _codeHProperties = {};
+
+            // Add language class if available
+            if (block.actualLang) {
+              _codeHProperties.className = "language-".concat(block.actualLang);
+            }
+
+            // Add additional props as data attributes (in camelCase)
+            Object.entries(block.props).forEach(function (_ref9) {
+              var _ref0 = _slicedToArray(_ref9, 2),
+                key = _ref0[0],
+                value = _ref0[1];
+              // Convert kebab-case to camelCase for data attributes
+              var camelKey = key.includes('-') ? "data".concat(key.split('-').map(function (part) {
+                return part.charAt(0).toUpperCase() + part.slice(1);
+              }).join('')) : "data".concat(key.charAt(0).toUpperCase() + key.slice(1));
+              _codeHProperties[camelKey] = value;
+            });
+
+            // Add data-variant to track the variant
+            _codeHProperties.dataVariant = block.variant;
+            var _fileName = getFileName(block.actualLang, block.props);
+            var _dlElement = {
+              type: 'element',
+              tagName: 'dl',
+              data: {
+                hName: 'dl',
+                hProperties: {}
+              },
+              children: [].concat(_toConsumableArray(_fileName ? [{
+                type: 'element',
+                tagName: 'dt',
+                data: {
+                  hName: 'dt',
+                  hProperties: {}
+                },
+                children: [{
+                  type: 'element',
+                  tagName: 'code',
+                  data: {
+                    hName: 'code',
+                    hProperties: {}
+                  },
+                  children: [{
+                    type: 'text',
+                    value: _fileName
+                  }]
+                }]
+              }] : []), [{
+                type: 'element',
+                tagName: 'dd',
+                data: {
+                  hName: 'dd',
+                  hProperties: {}
+                },
+                children: [{
+                  type: 'element',
+                  tagName: 'pre',
+                  data: {
+                    hName: 'pre',
+                    hProperties: {}
+                  },
+                  children: [{
+                    type: 'element',
+                    tagName: 'code',
+                    data: {
+                      hName: 'code',
+                      hProperties: _codeHProperties,
+                      meta: "variant=".concat(block.variant).concat(Object.entries(block.props).map(function (_ref1) {
+                        var _ref10 = _slicedToArray(_ref1, 2),
+                          key = _ref10[0],
+                          value = _ref10[1];
+                        return " ".concat(key, "=").concat(value);
+                      }).join(''))
+                    },
+                    children: [{
+                      type: 'text',
+                      value: block.node.value
+                    }]
+                  }]
+                }]
+              }])
+            };
+
+            // Replace this single code block
+            parentNode.children[codeBlocks[0].index] = _dlElement;
           }
         }
       }

package/esm/useCode/Pre.js

@@ -5,6 +5,8 @@ import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import * as React from 'react';
 import { toText } from 'hast-util-to-text';
+import { decompressSync, strFromU8 } from 'fflate';
+import { decode } from 'uint8-to-base64';
 import { hastToJsx } from "../pipeline/hastUtils/index.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 export function Pre(_ref) {
@@ -21,6 +23,9 @@ export function Pre(_ref) {
     if ('hastJson' in children) {
       return JSON.parse(children.hastJson);
     }
+    if ('hastGzip' in children) {
+      return JSON.parse(strFromU8(decompressSync(decode(children.hastGzip))));
+    }
     return children;
   }, [children]);
   var _React$useState = React.useState(_defineProperty({}, 0, true)),

package/esm/useCode/useFileNavigation.js

@@ -2,6 +2,8 @@ import _typeof from "@babel/runtime/helpers/esm/typeof";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import * as React from 'react';
+import { decompressSync, strFromU8 } from 'fflate';
+import { decode } from 'uint8-to-base64';
 import { useUrlHashState } from "../useUrlHashState/index.js";
 import { countLines } from "../pipeline/parseSource/addLineGutters.js";
 import { Pre } from "./Pre.js";
@@ -311,6 +313,8 @@ export function useFileNavigation(_ref) {
       var hastSelectedFile;
       if ('hastJson' in selectedFile) {
         hastSelectedFile = JSON.parse(selectedFile.hastJson);
+      } else if ('hastGzip' in selectedFile) {
+        hastSelectedFile = JSON.parse(strFromU8(decompressSync(decode(selectedFile.hastGzip))));
       } else {
         hastSelectedFile = selectedFile;
       }

package/esm/withDocsInfra/withDocsInfra.d.ts

@@ -4,7 +4,10 @@ export interface NextConfig {
   output?: 'export' | 'standalone' | undefined;
   turbopack?: {
     rules?: Record<string, {
-      loaders: string[];
+      loaders: {
+        loader: string;
+        options: Record<string, unknown>;
+      }[] | string[];
     }>;
   };
   webpack?: (config: WebpackConfig, options: WebpackOptions) => WebpackConfig;
@@ -57,6 +60,14 @@ export interface WithDocsInfraOptions {
   additionalTurbopackRules?: Record<string, {
     loaders: string[];
   }>;
+  /**
+   * Defer AST parsing option for code highlighter output.
+   * 'gzip' - Default, outputs gzipped HAST for best performance.
+   * 'json' - Outputs JSON HAST, requires client-side parsing.
+   * 'none' - Outputs raw HAST, requires client-side parsing and is largest size.
+   * @default 'gzip'
+   */
+  deferCodeParsing?: 'gzip' | 'json' | 'none';
 }
 export interface DocsInfraMdxOptions {
   remarkPlugins?: Array<string | [string, ...any[]]>;

package/esm/withDocsInfra/withDocsInfra.js

@@ -12,7 +12,7 @@ export function getDocsInfraMdxOptions() {
   var _customOptions$remark, _customOptions$additi, _customOptions$rehype, _customOptions$additi2;
   var customOptions = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
   var defaultRemarkPlugins = [['remark-gfm'], ['@mui/internal-docs-infra/pipeline/transformMarkdownCode']];
-  var defaultRehypePlugins = [['@mui/internal-docs-infra/pipeline/transformHtmlCode']];
+  var defaultRehypePlugins = [['@mui/internal-docs-infra/pipeline/transformHtmlCodePrecomputed']];
 
   // Build final plugin arrays
   var remarkPlugins = (_customOptions$remark = customOptions.remarkPlugins) != null ? _customOptions$remark : [].concat(defaultRemarkPlugins, _toConsumableArray((_customOptions$additi = customOptions.additionalRemarkPlugins) != null ? _customOptions$additi : []));
@@ -41,7 +41,15 @@ export function withDocsInfra() {
     _options$additionalDe = options.additionalDemoPatterns,
     additionalDemoPatterns = _options$additionalDe === void 0 ? {} : _options$additionalDe,
     _options$additionalTu = options.additionalTurbopackRules,
-    additionalTurbopackRules = _options$additionalTu === void 0 ? {} : _options$additionalTu;
+    additionalTurbopackRules = _options$additionalTu === void 0 ? {} : _options$additionalTu,
+    _options$deferCodePar = options.deferCodeParsing,
+    deferCodeParsing = _options$deferCodePar === void 0 ? 'gzip' : _options$deferCodePar;
+  var output = 'hastGzip';
+  if (deferCodeParsing === 'json') {
+    output = 'hastJson';
+  } else if (deferCodeParsing === 'none') {
+    output = 'hast';
+  }
   return function () {
     var _nextConfig$turbopack;
     var nextConfig = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
@@ -50,7 +58,12 @@ export function withDocsInfra() {
 
     // Build Turbopack rules
     var turbopackRules = _defineProperty(_defineProperty({}, demoPathPattern, {
-      loaders: ['@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter']
+      loaders: [{
+        loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter',
+        options: {
+          output: output
+        }
+      }]
     }), clientDemoPathPattern, {
       loaders: ['@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighterClient']
     });
@@ -59,7 +72,12 @@ export function withDocsInfra() {
     if (additionalDemoPatterns.index) {
       additionalDemoPatterns.index.forEach(function (pattern) {
         turbopackRules[pattern] = {
-          loaders: ['@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter']
+          loaders: [{
+            loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter',
+            options: {
+              output: output
+            }
+          }]
         };
       });
     }
@@ -99,7 +117,12 @@ export function withDocsInfra() {
         // Add loader for demo index files
         webpackConfig.module.rules.push({
           test: new RegExp('/demos/[^/]+/index\\.ts$'),
-          use: [defaultLoaders.babel, '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter']
+          use: [defaultLoaders.babel, {
+            loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter',
+            options: {
+              output: output
+            }
+          }]
         });
 
         // Client files for live demos - processes externals
@@ -120,7 +143,12 @@ export function withDocsInfra() {
 
             webpackConfig.module.rules.push({
               test: new RegExp("".concat(regexPattern, "$")),
-              use: [defaultLoaders.babel, '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter']
+              use: [defaultLoaders.babel, {
+                loader: '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter',
+                options: {
+                  output: output
+                }
+              }]
             });
           });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "keywords": [
@@ -25,6 +25,7 @@
     "@babel/standalone": "^7.28.4",
     "@wooorm/starry-night": "^3.8.0",
     "clipboard-copy": "^4.0.1",
+    "fflate": "^0.8.2",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-text": "^4.0.2",
     "jsondiffpatch": "^0.7.3",
@@ -32,6 +33,7 @@
     "lz-string": "^1.5.0",
     "path-module": "^0.1.2",
     "prettier": "^3.5.3",
+    "uint8-to-base64": "^0.2.1",
     "unist-util-visit": "^5.0.0",
     "vscode-oniguruma": "^2.0.1"
   },
@@ -204,10 +206,10 @@
         "default": "./esm/pipeline/parseSource/index.js"
       }
     },
-    "./pipeline/transformHtmlCode": {
+    "./pipeline/transformHtmlCodePrecomputed": {
       "default": {
-        "types": "./esm/pipeline/transformHtmlCode/index.d.ts",
-        "default": "./esm/pipeline/transformHtmlCode/index.js"
+        "types": "./esm/pipeline/transformHtmlCodePrecomputed/index.d.ts",
+        "default": "./esm/pipeline/transformHtmlCodePrecomputed/index.js"
       }
     },
     "./pipeline/transformMarkdownCode": {

package/esm/pipeline/loaderUtils/parseImports.d.ts

@@ -1,19 +0,0 @@
-export interface ImportName {
-  name: string;
-  alias?: string;
-  type: 'default' | 'named' | 'namespace';
-  isType?: boolean;
-}
-export interface RelativeImport {
-  path: string;
-  names: ImportName[];
-  includeTypeDefs?: true;
-}
-export interface ExternalImport {
-  names: ImportName[];
-}
-export interface ParseImportsResult {
-  relative: Record<string, RelativeImport>;
-  externals: Record<string, ExternalImport>;
-}
-export declare function parseImports(code: string, _filePath: string): Promise<ParseImportsResult>;