@mui/internal-docs-infra 0.3.1-canary.1 → 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/syncPageIndex/mergeMetadataMarkdown.js

@@ -68,7 +68,6 @@ function _mergeMetadataMarkdown() {
       _step2,
       existingPage,
       newPage,
-      _newPage$openGraph,
       descriptionMarkdown,
       existingPageWithoutDescriptionMarkdown,
       merged,
@@ -148,11 +147,7 @@ function _mergeMetadataMarkdown() {
                   // Preserve skipDetailSection from existing (user-managed for external links)
                   skipDetailSection: existingPage.skipDetailSection,
                   // Preserve sections from existing if new doesn't have them
-                  sections: newPage.sections || existingPage.sections,
-                  // Merge openGraph, but ensure description comes from newPage if it has one
-                  openGraph: (_newPage$openGraph = newPage.openGraph) != null ? _newPage$openGraph : newPage.description ? _extends(_extends({}, existingPage.openGraph), {}, {
-                    description: newPage.description
-                  }) : existingPage.openGraph
+                  sections: newPage.sections || existingPage.sections
                 });
                 pages.push(merged);
                 addedPaths.add(newPage.path);

package/esm/pipeline/syncPageIndex/metadataToMarkdown.js

@@ -429,9 +429,8 @@ export function metadataToMarkdownAst(data) {
     _step5;
   try {
     for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
-      var _page$openGraph;
       var page = _step5.value;
-      var pageTitle = ((_page$openGraph = page.openGraph) == null ? void 0 : _page$openGraph.title) || page.title || page.slug;
+      var pageTitle = page.title || page.slug;
 
       // Check if this is a single-link entry (external link or no detail section)
       var isSingleLink = page.skipDetailSection || false;
@@ -511,13 +510,12 @@ export function metadataToMarkdownAst(data) {
     _step6;
   try {
     for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
-      var _page$openGraph2, _page$openGraph3, _page$openGraph4;
       var _page = _step6.value;
-      var _pageTitle = ((_page$openGraph2 = _page.openGraph) == null ? void 0 : _page$openGraph2.title) || _page.title || _page.slug;
+      var _pageTitle = _page.title || _page.slug;
       // Note: We don't replace newlines here to allow natural line breaks in detailed sections
-      var description = ((_page$openGraph3 = _page.openGraph) == null ? void 0 : _page$openGraph3.description) || _page.description || 'No description available';
+      var description = _page.description || 'No description available';
       var keywords = _page.keywords || [];
-      var image = (_page$openGraph4 = _page.openGraph) == null || (_page$openGraph4 = _page$openGraph4.images) == null ? void 0 : _page$openGraph4[0];
+      var image = _page.image;
 
       // Add page heading
       children.push(heading(2, _pageTitle));
@@ -800,9 +798,8 @@ export function metadataToMarkdown(data) {
     _step9;
   try {
     for (_iterator9.s(); !(_step9 = _iterator9.n()).done;) {
-      var _page$openGraph5;
       var page = _step9.value;
-      var pageTitle = ((_page$openGraph5 = page.openGraph) == null ? void 0 : _page$openGraph5.title) || page.title || page.slug;
+      var pageTitle = page.title || page.slug;
 
       // Check if this is a single-link entry (external link or no detail section)
       var isSingleLink = page.skipDetailSection || false;
@@ -871,24 +868,22 @@ export function metadataToMarkdown(data) {
     _step0;
   try {
     for (_iterator0.s(); !(_step0 = _iterator0.n()).done;) {
-      var _page2$openGraph, _page2$openGraph3;
       var _page2 = _step0.value;
       // Skip detail section for single-link entries (external links)
       if (_page2.skipDetailSection) {
         continue;
       }
-      var _pageTitle2 = ((_page2$openGraph = _page2.openGraph) == null ? void 0 : _page2$openGraph.title) || _page2.title || _page2.slug;
+      var _pageTitle2 = _page2.title || _page2.slug;
       // Use descriptionMarkdown to preserve formatting if available
       // Note: We don't replace newlines here to allow natural line breaks in detailed sections
       var pageDescription = void 0;
       if (_page2.descriptionMarkdown && _page2.descriptionMarkdown.length > 0) {
         pageDescription = astNodesToMarkdown(_page2.descriptionMarkdown);
       } else {
-        var _page2$openGraph2;
-        pageDescription = ((_page2$openGraph2 = _page2.openGraph) == null ? void 0 : _page2$openGraph2.description) || _page2.description || 'No description available';
+        pageDescription = _page2.description || 'No description available';
       }
       var keywords = _page2.keywords || [];
-      var image = (_page2$openGraph3 = _page2.openGraph) == null || (_page2$openGraph3 = _page2$openGraph3.images) == null ? void 0 : _page2$openGraph3[0];
+      var image = _page2.image;
 
       // Add page heading
       lines.push("## ".concat(_pageTitle2));
@@ -1164,12 +1159,7 @@ function _markdownToMetadata() {
                     title: pageTitle,
                     description: 'No description available',
                     tags: tags.length > 0 ? tags : undefined,
-                    skipDetailSection: true,
-                    // Mark as external/single-link entry
-                    openGraph: {
-                      title: pageTitle,
-                      description: 'No description available'
-                    }
+                    skipDetailSection: true // Mark as external/single-link entry
                   });
                 } else if (links.length >= 2) {
                   // Two-link format: - [Title](#slug) [Tag1] [Tag2] - [Full Docs](./path/page.mdx)
@@ -1221,11 +1211,7 @@ function _markdownToMetadata() {
                     title: _pageTitle3,
                     description: 'No description available',
                     // Will be updated from details section
-                    tags: _tags.length > 0 ? _tags : undefined,
-                    openGraph: {
-                      title: _pageTitle3,
-                      description: 'No description available' // Will be updated from details section
-                    }
+                    tags: _tags.length > 0 ? _tags : undefined
                   });
                 }
               }
@@ -1329,10 +1315,6 @@ function _markdownToMetadata() {
                   if (_paragraphNode2.children) {
                     currentPage.descriptionMarkdown = stripPositions(_paragraphNode2.children);
                   }
-                  if (!currentPage.openGraph) {
-                    currentPage.openGraph = {};
-                  }
-                  currentPage.openGraph.description = _paragraphText;
                   return;
                 }
               }
@@ -1340,15 +1322,10 @@ function _markdownToMetadata() {
               // Parse image
               if (currentPage && node.type === 'image') {
                 var imageNode = node;
-                if (!currentPage.openGraph) {
-                  currentPage.openGraph = {};
-                }
-                currentPage.openGraph.images = [{
+                currentPage.image = {
                   url: imageNode.url,
-                  width: 800,
-                  height: 600,
                   alt: imageNode.alt || currentPage.title || currentPage.slug || ''
-                }];
+                };
                 return;
               }
             }

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: