@mui/internal-markdown 1.0.2 → 1.0.4

package/index.d.ts

@@ -12,7 +12,24 @@ export function createRender(context: {
   ignoreLanguagePages: (path: string) => boolean;
 }): (markdown: string) => string;
 
-export function getHeaders(markdown: string): Record<string, string | string[]>;
+export interface MarkdownHeaders {
+  packageName?: string;
+  productId: string;
+  githubLabel?: string;
+  waiAria?: string;
+  materialDesign?: string;
+  components: string[];
+  hooks?: string[];
+  slug?: string;
+  title?: string;
+  description?: string;
+  image?: string;
+  tags?: string[];
+  authors?: string[];
+  date?: string;
+}
+
+export function getHeaders(markdown: string): MarkdownHeaders;
 
 export function getTitle(markdown: string): string;
 

package/loader.js

@@ -1,4 +1,4 @@
-const { promises: fs, readdirSync } = require('fs');
+const { promises: fs, readdirSync, statSync } = require('fs');
 const path = require('path');
 const prepareMarkdown = require('./prepareMarkdown');
 const extractImports = require('./extractImports');
@@ -19,7 +19,7 @@ function upperCaseFirst(string) {
  * @example moduleIDToJSIdentifier('../Box-new.js') === '$$$BoxNewJs'
  */
 function moduleIDToJSIdentifier(moduleID) {
-  const delimiter = /(\.|-|\/|:)/;
+  const delimiter = /(@|\.|-|\/|:)/;
   return moduleID
     .split(delimiter)
     .filter((part) => !delimiter.test(part))
@@ -127,6 +127,7 @@ module.exports = async function demoLoader() {
   const demoModuleIDs = new Set();
   const componentModuleIDs = new Set();
   const nonEditableDemos = new Set();
+  const relativeModules = new Map();
   const demoNames = Array.from(
     new Set(
       docs.en.rendered
@@ -142,6 +143,63 @@ module.exports = async function demoLoader() {
     ),
   );
 
+  /**
+   * @param {*} demoName
+   * @param {*} moduleFilepath
+   * @param {*} variant
+   * @param {*} importModuleID
+   * @example detectRelativeImports('ComboBox.js', '', JS', './top100Films') => relativeModules.set('ComboBox.js', new Map([['./top100Films.js', ['JS']]]))
+   */
+  function detectRelativeImports(demoName, moduleFilepath, variant, importModuleID) {
+    if (importModuleID.startsWith('.')) {
+      let relativeModuleFilename = importModuleID;
+      const demoMap = relativeModules.get(demoName);
+      // If the moduleID does not end with an extension, or ends with an unsupported extension (e.g. ".styling") we need to resolve it
+      // Fastest way to get a file extension, see: https://stackoverflow.com/a/12900504/
+      const importType = importModuleID.slice(
+        (Math.max(0, importModuleID.lastIndexOf('.')) || Infinity) + 1,
+      );
+      const supportedTypes = ['js', 'jsx', 'ts', 'tsx', 'css', 'json'];
+      if (!importType || !supportedTypes.includes(importType)) {
+        // If the demo is a JS demo, we can assume that the relative import is either
+        // a `.js` or a `.jsx` file, with `.js` taking precedence over `.jsx`
+        // likewise for TS demos, with `.ts` taking precedence over `.tsx`
+        const extensions =
+          variant === 'JS' ? ['.js', '.jsx', '.ts', '.tsx'] : ['.ts', '.tsx', '.js', '.jsx'];
+        const extension = extensions.find((ext) => {
+          try {
+            return statSync(path.join(moduleFilepath, '..', `${importModuleID}${ext}`));
+          } catch (error) {
+            // If the file does not exist, we return false and continue to the next extension
+            return false;
+          }
+        });
+        if (!extension) {
+          throw new Error(
+            [
+              `You are trying to import a module "${importModuleID}" in the demo "${demoName}" that could not be resolved.`,
+              `Please make sure that one of the following file exists:`,
+              ...extensions.map((ext) => `- ${importModuleID}${ext}`),
+            ].join('\n'),
+          );
+        } else {
+          relativeModuleFilename = `${importModuleID}${extension}`;
+        }
+      }
+
+      if (!demoMap) {
+        relativeModules.set(demoName, new Map([[relativeModuleFilename, [variant]]]));
+      } else {
+        const variantArray = demoMap.get(relativeModuleFilename);
+        if (variantArray) {
+          variantArray.push(variant);
+        } else {
+          demoMap.set(relativeModuleFilename, [variant]);
+        }
+      }
+    }
+  }
+
   await Promise.all(
     demoNames.map(async (demoName) => {
       const multipleDemoVersionsUsed = !demoName.endsWith('.js');
@@ -168,11 +226,14 @@ module.exports = async function demoLoader() {
         raw: await fs.readFile(moduleFilepath, { encoding: 'utf8' }),
       };
       demoModuleIDs.add(moduleID);
+
       // Skip non-editable demos
       if (!nonEditableDemos.has(demoName)) {
-        extractImports(demos[demoName].raw).forEach((importModuleID) =>
-          importedModuleIDs.add(importModuleID),
-        );
+        extractImports(demos[demoName].raw).forEach((importModuleID) => {
+          // detect relative import
+          detectRelativeImports(demoName, moduleFilepath, 'JS', importModuleID);
+          importedModuleIDs.add(importModuleID);
+        });
       }
 
       if (multipleDemoVersionsUsed) {
@@ -343,10 +404,69 @@ module.exports = async function demoLoader() {
         // But this leads to building both demo version i.e. more build time.
         demos[demoName].moduleTS = this.mode === 'production' ? moduleID : moduleTS;
         demos[demoName].rawTS = rawTS;
+
+        // Extract relative imports from the TypeScript version
+        // of demos which have relative imports in the JS version
+        if (relativeModules.has(demoName)) {
+          extractImports(demos[demoName].rawTS).forEach((importModuleID) => {
+            detectRelativeImports(demoName, moduleTSFilepath, 'TS', importModuleID);
+            importedModuleIDs.add(importModuleID);
+          });
+        }
+
         demoModuleIDs.add(demos[demoName].moduleTS);
       } catch (error) {
         // TS version of the demo doesn't exist. This is fine.
       }
+
+      /* Map over relative import module IDs and resolve them
+       * while grouping by demo variant
+       * From:
+       * relativeModules: { 'ComboBox.js' =>
+       *    { './top100Films.js'  => ['JS', 'TS'] }
+       * }
+       * To:
+       * demos["ComboBox.js"].relativeModules = {
+       *     JS: [{ module: './top100Films.js', raw: '...' }],
+       *     TS: [{ module: './top100Films.js', raw: '...' }]
+       *   }
+       * }
+       */
+
+      if (relativeModules.has(demoName)) {
+        if (!demos[demoName].relativeModules) {
+          demos[demoName].relativeModules = {};
+        }
+
+        await Promise.all(
+          Array.from(relativeModules.get(demoName)).map(async ([relativeModuleID, variants]) => {
+            let raw = '';
+            try {
+              raw = await fs.readFile(path.join(path.dirname(moduleFilepath), relativeModuleID), {
+                encoding: 'utf8',
+              });
+            } catch {
+              throw new Error(
+                `Could not find a module for the relative import "${relativeModuleID}" in the demo "${demoName}"`,
+              );
+            }
+
+            const moduleData = { module: relativeModuleID, raw };
+            const modules = demos[demoName].relativeModules;
+
+            variants.forEach((variant) => {
+              if (modules[variant]) {
+                // Avoid duplicates
+                if (!modules[variant].some((elem) => elem.module === relativeModuleID)) {
+                  modules[variant].push(moduleData);
+                }
+              } else {
+                modules[variant] = [moduleData];
+              }
+            });
+          }),
+        );
+      }
     }),
   );
 
@@ -365,7 +485,9 @@ module.exports = async function demoLoader() {
   );
 
   componentNames.forEach((componentName) => {
-    const moduleID = path.join(this.rootContext, 'src', componentName).replace(/\\/g, '/');
+    const moduleID = componentName.startsWith('@mui/docs/')
+      ? componentName
+      : path.join(this.rootContext, 'src', componentName).replace(/\\/g, '/');
 
     components[moduleID] = componentName;
     componentModuleIDs.add(moduleID);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-markdown",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "author": "MUI Team",
   "description": "MUI markdown parser. This is an internal package not meant for general use.",
   "main": "./index.js",
@@ -16,13 +16,13 @@
     "directory": "packages/markdown"
   },
   "dependencies": {
-    "@babel/runtime": "^7.24.4",
+    "@babel/runtime": "^7.24.5",
     "lodash": "^4.17.21",
     "marked": "^5.1.2",
     "prismjs": "^1.29.0"
   },
   "devDependencies": {
-    "@types/chai": "^4.3.14",
+    "@types/chai": "^4.3.16",
     "chai": "^4.4.1"
   },
   "publishConfig": {

package/parseMarkdown.js

@@ -364,11 +364,7 @@ function createRender(context) {
       }
 
       return [
-        `<h${level} id="${hash}">`,
-        headingHtml,
-        `<a aria-labelledby="${hash}" class="anchor-link" href="#${hash}" tabindex="-1">`,
-        '<svg><use xlink:href="#anchor-link-icon" /></svg>',
-        '</a>',
+        `<h${level} id="${hash}"><a href="#${hash}" class="title-link-to-anchor">${headingHtml}<span class="anchor-icon"><svg><use xlink:href="#anchor-link-icon" /></svg></span></a>`,
         `<button title="Post a comment" class="comment-link" data-feedback-hash="${hash}">`,
         '<svg><use xlink:href="#comment-link-icon" /></svg>',
         `</button>`,
@@ -427,10 +423,8 @@ function createRender(context) {
         escaped ? code : escape(code, true)
       }</code></pre>${[
         '<button data-ga-event-category="code" data-ga-event-action="copy-click" aria-label="Copy the code" class="MuiCode-copy">',
-        '<svg focusable="false" aria-hidden="true" viewBox="0 0 24 24" data-testid="ContentCopyRoundedIcon">',
-        '<use class="MuiCode-copy-icon" xlink:href="#copy-icon" />',
-        '<use class="MuiCode-copied-icon" xlink:href="#copied-icon" />',
-        '</svg>',
+        '<span class="MuiCode-copy-label">Copy</span>',
+        '<span class="MuiCode-copied-label">Copied</span>',
         '<span class="MuiCode-copyKeypress"><span>(or</span> $keyC<span>)</span></span></button></div>',
       ].join('')}\n`;
     };

package/parseMarkdown.test.js

@@ -295,9 +295,9 @@ authors:
       ).to.equal(
         [
           `<h1>Accordion</h1>`,
-          `<h2 id="basic-features">Basic features 🧪<a aria-labelledby="basic-features" class="anchor-link" href="#basic-features" tabindex="-1"><svg><use xlink:href="#anchor-link-icon" /></svg></a><button title="Post a comment" class="comment-link" data-feedback-hash="basic-features"><svg><use xlink:href="#comment-link-icon" /></svg></button></h2>`,
-          `<h2 id="using-slots-and-slotprops">Using <code>slots</code> and <code>slotProps</code><a aria-labelledby="using-slots-and-slotprops" class="anchor-link" href="#using-slots-and-slotprops" tabindex="-1"><svg><use xlink:href="#anchor-link-icon" /></svg></a><button title="Post a comment" class="comment-link" data-feedback-hash="using-slots-and-slotprops"><svg><use xlink:href="#comment-link-icon" /></svg></button></h2>`,
-          `<h3 id="specific-example">Specific example<a aria-labelledby="specific-example" class="anchor-link" href="#specific-example" tabindex="-1"><svg><use xlink:href="#anchor-link-icon" /></svg></a><button title="Post a comment" class="comment-link" data-feedback-hash="specific-example"><svg><use xlink:href="#comment-link-icon" /></svg></button></h3>`,
+          `<h2 id="basic-features"><a href="#basic-features" class="title-link-to-anchor">Basic features 🧪<span class="anchor-icon"><svg><use xlink:href="#anchor-link-icon" /></svg></span></a><button title="Post a comment" class="comment-link" data-feedback-hash="basic-features"><svg><use xlink:href="#comment-link-icon" /></svg></button></h2>`,
+          `<h2 id="using-slots-and-slotprops"><a href="#using-slots-and-slotprops" class="title-link-to-anchor">Using <code>slots</code> and <code>slotProps</code><span class="anchor-icon"><svg><use xlink:href="#anchor-link-icon" /></svg></span></a><button title="Post a comment" class="comment-link" data-feedback-hash="using-slots-and-slotprops"><svg><use xlink:href="#comment-link-icon" /></svg></button></h2>`,
+          `<h3 id="specific-example"><a href="#specific-example" class="title-link-to-anchor">Specific example<span class="anchor-icon"><svg><use xlink:href="#anchor-link-icon" /></svg></span></a><button title="Post a comment" class="comment-link" data-feedback-hash="specific-example"><svg><use xlink:href="#comment-link-icon" /></svg></button></h3>`,
         ].join(''),
       );
 

package/prepareMarkdown.js

@@ -110,7 +110,7 @@ This unstyled version of the component is the ideal choice for heavy customizati
         `);
       }
 
-      if (headers.components.length > 0) {
+      if (headers.components.length > 0 && headers.productId !== 'base-ui') {
         contents.push(`
 ## API