@mui/internal-docs-infra 0.3.1-canary.2 → 0.3.1-canary.3

package/esm/pipeline/parseSource/parseSource.js

@@ -1,16 +1,25 @@
 import _regenerator from "@babel/runtime/helpers/esm/regenerator";
 import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import { createStarryNight } from '@wooorm/starry-night';
-import { grammars, extensionMap } from "./grammars.js";
+import { grammars, extensionMap, getGrammarFromLanguage } from "./grammars.js";
 import { starryNightGutter } from "./addLineGutters.js";
 var STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
-export var parseSource = function parseSource(source, fileName) {
+export var parseSource = function parseSource(source, fileName, language) {
   var starryNight = globalThis[STARRY_NIGHT_KEY];
   if (!starryNight) {
     throw new Error('Starry Night not initialized. Use createParseSource to create an initialized parseSource function.');
   }
-  var fileType = fileName.slice(fileName.lastIndexOf('.'));
-  if (!extensionMap[fileType]) {
+
+  // Determine the grammar scope: prefer explicit language, then fall back to file extension
+  var grammarScope;
+  if (language) {
+    grammarScope = getGrammarFromLanguage(language);
+  }
+  if (!grammarScope && fileName) {
+    var fileType = fileName.slice(fileName.lastIndexOf('.'));
+    grammarScope = extensionMap[fileType];
+  }
+  if (!grammarScope) {
     // Return a basic HAST root node with the source text for unsupported file types
     // TODO: should we split and add line gutters?
     return {
@@ -21,7 +30,7 @@ export var parseSource = function parseSource(source, fileName) {
       }]
     };
   }
-  var highlighted = starryNight.highlight(source, extensionMap[fileType]);
+  var highlighted = starryNight.highlight(source, grammarScope);
   var sourceLines = source.split(/\r?\n|\r/);
   starryNightGutter(highlighted, sourceLines); // mutates the tree to add line gutters
 

package/esm/pipeline/transformHtmlCodePrecomputed/transformHtmlCodePrecomputed.js

@@ -1,85 +1,106 @@
 import _regenerator from "@babel/runtime/helpers/esm/regenerator";
 import _typeof from "@babel/runtime/helpers/esm/typeof";
-import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import { visit } from 'unist-util-visit';
 import { loadCodeVariant } from "../loadCodeVariant/loadCodeVariant.js";
 import { createParseSource } from "../parseSource/index.js";
 import { TypescriptToJavascriptTransformer } from "../transformTypescriptToJavascript/index.js";
 /**
- * Maps common language class names to file extensions
- * Only includes languages that have corresponding grammars in parseSource/grammars.ts
+ * Reserved data properties that are handled internally and should not be passed to userProps.
+ * These are either processed by the transform pipeline or have special meaning.
  */
-var LANGUAGE_TO_EXTENSION = {
-  // JavaScript
-  javascript: 'js',
-  js: 'js',
-  // TypeScript
-  typescript: 'ts',
-  ts: 'ts',
-  // TSX/JSX
-  tsx: 'tsx',
-  jsx: 'jsx',
-  // Maps to .jsx but uses tsx grammar
-
-  // 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'
-};
+var RESERVED_DATA_PROPS = new Set(['dataFilename',
+// Used for fileName
+'dataVariant',
+// Used for variant name
+'dataTransform',
+// Used for skipTransforms
+'dataPrecompute',
+// The precomputed output itself
+'dataContentProps',
+// The serialized user props output
+'dataName',
+// Used for demo name
+'dataSlug' // Used for demo slug/URL
+]);
 
 /**
- * Extracts the language from className attribute
+ * Extracts user-defined data properties from a code element.
+ * Filters out reserved properties and returns remaining data-* attributes.
+ * Converts from camelCase (dataTitle) to kebab-case keys (title).
  */
-function extractLanguageFromClassName(className) {
-  if (!className) {
-    return null;
+function extractUserProps(codeElement) {
+  var props = codeElement.properties;
+  if (!props) {
+    return undefined;
   }
-
-  // Handle array of class names (HAST format)
-  var classString = Array.isArray(className) ? className.join(' ') : className;
-  var match = classString.match(/(?:^|\s)language-(\w+)(?:\s|$)/);
-  return match ? match[1] : null;
+  var userProps = {};
+  for (var _i = 0, _Object$entries = Object.entries(props); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      value = _Object$entries$_i[1];
+    // Only process data-* attributes (in camelCase form: dataXxx)
+    if (key.startsWith('data') && key.length > 4 && !RESERVED_DATA_PROPS.has(key)) {
+      // Convert dataTitle -> title, dataHighlight -> highlight
+      var propName = key.charAt(4).toLowerCase() + key.slice(5);
+      // Convert value to string
+      userProps[propName] = String(value);
+    }
+  }
+  return Object.keys(userProps).length > 0 ? userProps : undefined;
 }
 
 /**
- * Gets the filename from data-filename attribute or derives it from language
- * Returns undefined if no explicit filename and no recognizable language
+ * Gets the filename from data-filename attribute only
+ * Returns undefined if no explicit filename is provided
  */
 function getFileName(codeElement) {
-  var _codeElement$properti, _codeElement$properti2;
+  var _codeElement$properti;
   // Check for explicit data-filename attribute
   var dataFilename = (_codeElement$properti = codeElement.properties) == null ? void 0 : _codeElement$properti.dataFilename;
   if (dataFilename && typeof dataFilename === 'string') {
     return dataFilename;
   }
+  return undefined;
+}
 
-  // Extract language from className
-  var className = (_codeElement$properti2 = codeElement.properties) == null ? void 0 : _codeElement$properti2.className;
-  var language = extractLanguageFromClassName(className);
-  if (language && LANGUAGE_TO_EXTENSION[language]) {
-    return "index.".concat(LANGUAGE_TO_EXTENSION[language]);
+/**
+ * Extracts language from a className like "language-typescript" or "language-js"
+ * Returns the language portion after "language-" prefix
+ */
+function extractLanguageFromClassName(className) {
+  if (!className) {
+    return undefined;
+  }
+  var classes = Array.isArray(className) ? className : [className];
+  var _iterator = _createForOfIteratorHelper(classes),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var cls = _step.value;
+      if (typeof cls === 'string' && cls.startsWith('language-')) {
+        return cls.slice('language-'.length);
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
   }
-
-  // Return undefined instead of a fallback - let the system handle gracefully
   return undefined;
 }
 
+/**
+ * Gets the language from class="language-*" attribute
+ */
+function getLanguage(codeElement) {
+  var _codeElement$properti2;
+  var className = (_codeElement$properti2 = codeElement.properties) == null ? void 0 : _codeElement$properti2.className;
+  return extractLanguageFromClassName(className);
+}
+
 /**
  * Extracts text content from HAST nodes
  */
@@ -106,11 +127,11 @@ function extractCodeFromSemanticStructure(element) {
     var figures = element.children.filter(function (child) {
       return child.type === 'element' && child.tagName === 'figure';
     });
-    var _iterator = _createForOfIteratorHelper(figures),
-      _step;
+    var _iterator2 = _createForOfIteratorHelper(figures),
+      _step2;
     try {
-      for (_iterator.s(); !(_step = _iterator.n()).done;) {
-        var figure = _step.value;
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        var figure = _step2.value;
         // Extract variant name from figcaption
         var variantName = void 0;
         var figcaption = figure.children.find(function (child) {
@@ -130,15 +151,16 @@ function extractCodeFromSemanticStructure(element) {
             results.push({
               codeElement: extracted.codeElement,
               filename: extracted.filename,
+              language: extracted.language,
               variantName: variantName || extracted.variantName
             });
           }
         }
       }
     } catch (err) {
-      _iterator.e(err);
+      _iterator2.e(err);
     } finally {
-      _iterator.f();
+      _iterator2.f();
     }
   } else if (element.tagName === 'dl') {
     // Handle standalone dl
@@ -157,11 +179,11 @@ function extractFromDl(dl) {
   // Find dt for filename and dd for code
   var filename;
   var codeElement;
-  var _iterator2 = _createForOfIteratorHelper(dl.children),
-    _step2;
+  var _iterator3 = _createForOfIteratorHelper(dl.children),
+    _step3;
   try {
-    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-      var child = _step2.value;
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var child = _step3.value;
       if (child.type === 'element') {
         if (child.tagName === 'dt') {
           // Extract filename from dt > code
@@ -188,17 +210,20 @@ function extractFromDl(dl) {
       }
     }
   } catch (err) {
-    _iterator2.e(err);
+    _iterator3.e(err);
   } finally {
-    _iterator2.f();
+    _iterator3.f();
   }
   if (codeElement) {
     var _codeElement$properti3;
     // Extract variant name from data-variant if available
     var variantName = (_codeElement$properti3 = codeElement.properties) == null ? void 0 : _codeElement$properti3.dataVariant;
+    // Extract language from className
+    var language = getLanguage(codeElement);
     return {
       codeElement: codeElement,
       filename: filename,
+      language: language,
       variantName: variantName
     };
   }
@@ -238,11 +263,14 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                   return child.type === 'element' && child.tagName === 'code';
                 });
                 if (codeElement) {
-                  // Extract filename from data-filename or derive from language class
+                  // Extract filename from data-filename attribute (explicit only)
                   var filename = getFileName(codeElement);
+                  // Extract language from className
+                  var language = getLanguage(codeElement);
                   extractedElements = [{
                     codeElement: codeElement,
                     filename: filename,
+                    language: language,
                     variantName: undefined // Basic pre > code doesn't have variants
                   }];
                 }
@@ -254,7 +282,7 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
               }
               if (extractedElements.length > 0) {
                 var transformPromise = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
-                  var variants, _codeElement$properti4, _extractedElements$, _codeElement, _filename, sourceCode, variant, derivedFilename, processedCode, variantPromises, variantResults, _iterator3, _step3, result, _t;
+                  var _firstCodeElement$pro, _firstCodeElement$pro2, variants, _codeElement$properti4, _extractedElements$, _codeElement, _filename, _language, sourceCode, variant, processedCode, variantPromises, variantResults, _iterator4, _step4, result, userProps, firstCodeElement, _t;
                   return _regenerator().w(function (_context2) {
                     while (1) switch (_context2.p = _context2.n) {
                       case 0:
@@ -263,19 +291,19 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                         variants = {};
                         if (extractedElements.length === 1) {
                           // Single element - use "Default" as variant name
-                          _extractedElements$ = extractedElements[0], _codeElement = _extractedElements$.codeElement, _filename = _extractedElements$.filename;
+                          _extractedElements$ = extractedElements[0], _codeElement = _extractedElements$.codeElement, _filename = _extractedElements$.filename, _language = _extractedElements$.language;
                           sourceCode = extractTextContent(_codeElement);
                           variant = {
                             source: sourceCode,
                             skipTransforms: !((_codeElement$properti4 = _codeElement.properties) != null && _codeElement$properti4.dataTransform)
-                          }; // Add filename if available (prefer explicit filename over derived)
+                          }; // Add filename if explicitly provided
                           if (_filename) {
                             variant.fileName = _filename;
-                          } else {
-                            derivedFilename = getFileName(_codeElement);
-                            if (derivedFilename) {
-                              variant.fileName = derivedFilename;
-                            }
+                          }
+
+                          // Add language if available (from className)
+                          if (_language) {
+                            variant.language = _language;
                           }
                           variants.Default = variant;
                         } else {
@@ -284,6 +312,7 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                             var _codeElement$properti5;
                             var codeElement = _ref3.codeElement,
                               filename = _ref3.filename,
+                              language = _ref3.language,
                               variantName = _ref3.variantName;
                             var sourceCode = extractTextContent(codeElement);
 
@@ -294,14 +323,14 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                               skipTransforms: !((_codeElement$properti5 = codeElement.properties) != null && _codeElement$properti5.dataTransform)
                             };
 
-                            // Add filename if available (prefer explicit filename over derived)
+                            // Add filename if explicitly provided
                             if (filename) {
                               variant.fileName = filename;
-                            } else {
-                              var _derivedFilename = getFileName(codeElement);
-                              if (_derivedFilename) {
-                                variant.fileName = _derivedFilename;
-                              }
+                            }
+
+                            // Add language if available (from className)
+                            if (language) {
+                              variant.language = language;
                             }
                             variants[finalVariantName] = variant;
                           });
@@ -353,21 +382,22 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                         return Promise.all(variantPromises);
                       case 1:
                         variantResults = _context2.v;
-                        _iterator3 = _createForOfIteratorHelper(variantResults);
+                        _iterator4 = _createForOfIteratorHelper(variantResults);
                         try {
-                          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
-                            result = _step3.value;
+                          for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+                            result = _step4.value;
                             if (result) {
                               processedCode[result.variantName] = result.processedVariant;
                             }
                           }
 
-                          // Clear all code element contents
+                          // Extract user props from the first code element (they should be the same for all variants)
                         } catch (err) {
-                          _iterator3.e(err);
+                          _iterator4.e(err);
                         } finally {
-                          _iterator3.f();
+                          _iterator4.f();
                         }
+                        userProps = extractUserProps(extractedElements[0].codeElement); // Clear all code element contents
                         extractedElements.forEach(function (_ref7) {
                           var codeElement = _ref7.codeElement;
                           codeElement.children = [];
@@ -385,6 +415,20 @@ export var transformHtmlCodePrecomputed = function transformHtmlCodePrecomputed(
                           node.properties = {};
                         }
                         node.properties.dataPrecompute = JSON.stringify(processedCode);
+
+                        // Pass through name and slug if provided on the code element
+                        firstCodeElement = extractedElements[0].codeElement;
+                        if ((_firstCodeElement$pro = firstCodeElement.properties) != null && _firstCodeElement$pro.dataName) {
+                          node.properties.dataName = firstCodeElement.properties.dataName;
+                        }
+                        if ((_firstCodeElement$pro2 = firstCodeElement.properties) != null && _firstCodeElement$pro2.dataSlug) {
+                          node.properties.dataSlug = firstCodeElement.properties.dataSlug;
+                        }
+
+                        // Set user props if any exist
+                        if (userProps) {
+                          node.properties.dataContentProps = JSON.stringify(userProps);
+                        }
                         _context2.n = 3;
                         break;
                       case 2:

package/esm/pipeline/transformMarkdownCode/transformMarkdownCode.js

@@ -2,6 +2,8 @@ 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';
+import { normalizeLanguage } from "../loaderUtils/getLanguageFromExtension.js";
+
 /**
  * Remark plugin that transforms code blocks with variants into semantic HTML structures.
  *
@@ -54,67 +56,36 @@ import { visit } from 'unist-util-visit';
  *     <dl>
  *       <dt><code>index.js</code></dt>
  *       <dd>
- *         <pre><code class="language-bash">pnpm install @mui/internal-docs-infra</code></pre>
+ *         <pre><code class="language-shell">pnpm install @mui/internal-docs-infra</code></pre>
  *       </dd>
  *     </dl>
  *   </figure>
  * </section>
  *
- * Or for individual blocks (no figure/figcaption needed):
+ * Or for individual blocks without filename (no dl wrapper needed):
+ * <pre><code class="language-typescript" data-transform="true">console.log('test' as const)</code></pre>
+ *
+ * Or with explicit filename (uses dl/dt/dd structure):
  * <dl>
- *   <dt><code>index.ts</code></dt>
+ *   <dt><code>example.ts</code></dt>
  *   <dd>
- *     <pre><code class="language-ts" data-transform="true">console.log('test' as const)</code></pre>
+ *     <pre><code class="language-typescript">console.log('test' as const)</code></pre>
  *   </dd>
  * </dl>
+ *
+ * Note: The `dl/dt/dd` structure is only used when an explicit `filename` prop is provided.
+ * Language information is passed via the `class="language-*"` attribute on the code element.
  */
 
 /**
- * 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
+ * Gets filename from explicit filename prop only.
+ * Does not derive filename from language - language is passed via className instead.
  */
-function getFileName(language, props) {
-  // Check for explicit filename
+function getFileName(props) {
+  // Only return 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;
 }
 
@@ -230,12 +201,11 @@ 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 dl element for individual blocks with options
           var codeHProperties = {};
 
-          // Add language class if available
+          // Add normalized language as class
           if (langFromMeta) {
-            codeHProperties.className = "language-".concat(langFromMeta);
+            codeHProperties.className = "language-".concat(normalizeLanguage(langFromMeta));
           }
 
           // Add all props as data attributes (in camelCase)
@@ -249,15 +219,40 @@ export var transformMarkdownCode = function transformMarkdownCode() {
             }).join('')) : "data".concat(key.charAt(0).toUpperCase() + key.slice(1));
             codeHProperties[camelKey] = value;
           });
-          var fileName = getFileName(langFromMeta, allProps);
-          var dlElement = {
+          var fileName = getFileName(allProps);
+
+          // Create pre > code element
+          var preElement = {
+            type: 'element',
+            tagName: 'pre',
+            data: {
+              hName: 'pre',
+              hProperties: {}
+            },
+            children: [{
+              type: 'element',
+              tagName: 'code',
+              data: {
+                hName: 'code',
+                hProperties: codeHProperties
+              },
+              children: [{
+                type: 'text',
+                value: codeNode.value
+              }]
+            }]
+          };
+
+          // If there's a filename, wrap in dl/dt/dd structure
+          // Otherwise, just use pre > code directly
+          var outputElement = fileName ? {
             type: 'element',
             tagName: 'dl',
             data: {
               hName: 'dl',
               hProperties: {}
             },
-            children: [].concat(_toConsumableArray(fileName ? [{
+            children: [{
               type: 'element',
               tagName: 'dt',
               data: {
@@ -276,38 +271,19 @@ export var transformMarkdownCode = function transformMarkdownCode() {
                   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
-                  }]
-                }]
-              }]
-            }])
-          };
+              children: [preElement]
+            }]
+          } : preElement;
 
           // Replace this individual code block immediately
-          parentNode.children[index] = dlElement;
+          parentNode.children[index] = outputElement;
           processedIndices.add(index);
           return;
         }
@@ -499,9 +475,9 @@ export var transformMarkdownCode = function transformMarkdownCode() {
                 // Build hProperties for HTML attributes
                 var codeHProperties = {};
 
-                // Add language class if available
+                // Add normalized language as class
                 if (block.actualLang) {
-                  codeHProperties.className = "language-".concat(block.actualLang);
+                  codeHProperties.className = "language-".concat(normalizeLanguage(block.actualLang));
                 }
 
                 // Add additional props as data attributes (in camelCase)
@@ -518,7 +494,7 @@ export var transformMarkdownCode = function transformMarkdownCode() {
 
                 // Add data-variant to track the variant
                 codeHProperties.dataVariant = block.variant;
-                var fileName = getFileName(block.actualLang, block.props);
+                var fileName = getFileName(block.props);
                 return {
                   type: 'element',
                   tagName: 'figure',
@@ -679,9 +655,9 @@ export var transformMarkdownCode = function transformMarkdownCode() {
             var block = codeBlocks[0];
             var _codeHProperties = {};
 
-            // Add language class if available
+            // Add normalized language as class
             if (block.actualLang) {
-              _codeHProperties.className = "language-".concat(block.actualLang);
+              _codeHProperties.className = "language-".concat(normalizeLanguage(block.actualLang));
             }
 
             // Add additional props as data attributes (in camelCase)
@@ -698,8 +674,8 @@ export var transformMarkdownCode = function transformMarkdownCode() {
 
             // Add data-variant to track the variant
             _codeHProperties.dataVariant = block.variant;
-            var _fileName = getFileName(block.actualLang, block.props);
-            var _dlElement = {
+            var _fileName = getFileName(block.props);
+            var dlElement = {
               type: 'element',
               tagName: 'dl',
               data: {
@@ -762,7 +738,7 @@ export var transformMarkdownCode = function transformMarkdownCode() {
             };
 
             // Replace this single code block
-            parentNode.children[codeBlocks[0].index] = _dlElement;
+            parentNode.children[codeBlocks[0].index] = dlElement;
           }
         }
       }

package/esm/useCode/Pre.d.ts

@@ -3,12 +3,14 @@ import type { VariantSource } from "../CodeHighlighter/types.js";
 export declare function Pre({
   children,
   className,
+  language,
   ref,
   shouldHighlight,
   hydrateMargin
 }: {
   children: VariantSource;
   className?: string;
+  language?: string;
   ref?: React.Ref<HTMLPreElement>;
   shouldHighlight?: boolean;
   hydrateMargin?: string;