[docs-infra] Add recursively the relative modules in the demos #44150

mnajdova · 2024-10-18T11:54:33Z

BRREAKING CHANGE

For the demos that used relative imports, make sure that you have a TypeScript version of the relative modules too, as the infra was updated to look for TypeScript files in the TypeScript version of the demo. In Core, the only usage was in the Autocomplete component related to the top100films.js file. You can likely easily search for this in the docs/data directory of your projects.

This PR adds support for complex demos that need a specific folder structure in order to improve the collocation of the files in the demos. I copied the Advanced ListView demo from MUI X.

List of needed changes to enable this feature:

update the markdown loader logic to include the relative modules of all files used in the demo (not just the root demo file)
a small change in the CodeSandbox & Stackblitz to update imports statements of all files, not just the Demo.js|tsx file
updated the docs:typescript:formatted script to create a JS version for all TypeScript files, not just the component ones

I've tested that:

all files are present in the file tabs for both the JS and TS version of the demos
CodeSandbox export works as expected
Stackblitz export works as expected

TODO:

Remove the test demo before merging

mui-bot · 2024-10-18T11:56:57Z

Netlify deploy preview

https://deploy-preview-44150--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 07f45cf

docs/scripts/formattedTSDemos.js

mnajdova · 2024-10-24T10:57:13Z

docs/src/modules/sandbox/CodeSandbox.ts

-            content: curr.raw,
+            content: flattenRelativeImports(
+              curr.raw,
+              demoData.relativeModules?.map((file) => file.module),


Do the same as the Demo.js file as we now allow relatives imports in all files.

mnajdova · 2024-10-24T10:57:49Z

docs/src/modules/sandbox/FlattenRelativeImports.ts

@@ -5,6 +5,9 @@ export default function flattenRelativeImports(rawCode: string, modulePaths: str
    // Move the relative import to the current directory
    const newPath = `./${pathWithoutExtension.replace(/^.*[\\/]/g, '')}`;
    newCode = newCode.replace(pathWithoutExtension, newPath);
+
+    // Replace the relative import towards parent directory
+    newCode = newCode.replace('../', './');


We need to replace nested imports toward the parent directory, e.g. a file importing from "../utils". Not sure if this is the best way to fix this, but I am open for suggestions.

I got confused when writing this piece of code. I thaught path would be the path as expressed in the file. But it's the path from the root of the Demo.

We could move the replace outside of the forEach by using a replaceAll. Currently, it works because we apply this Replace once per file existing in the demo

Another option would be to use similar Regexp as the one to compute newPath

newCode = newCode.replace(/from '.*[\\/]/g, `from './`);

It replaces any sequence of . and / to support multiple levels of nested components (I hope we
will not reach that level 🙈)

And the from ' prevent replacing a ../ that could be present in the comments

mnajdova · 2024-10-24T10:58:01Z

docs/src/modules/sandbox/StackBlitz.ts

@@ -63,7 +63,10 @@ function createReactApp(demoData: DemoData) {
        (acc, curr) => ({
          ...acc,
          // Remove the path and keep the filename
-          [`${curr.module.replace(/^.*[\\/]/g, '')}`]: curr.raw,
+          [`${curr.module.replace(/^.*[\\/]/g, '')}`]: flattenRelativeImports(


Same change as in the CodeSandbox file.

mnajdova · 2024-10-24T10:58:22Z

packages/markdown/loader.js

@@ -198,6 +198,7 @@ module.exports = async function demoLoader() {
        }
      }
    }
+    return relativeModuleFilename;


I decided to update the method to return the file as it is needed when iterating the relative modules.

mnajdova · 2024-10-24T10:58:46Z

packages/markdown/loader.js

-            } catch {
-              throw new Error(
-                `Could not find a module for the relative import "${relativeModuleID}" in the demo "${demoName}"`,
+            for (const variant of variants) {


This only iterates through ['JS', 'TS']

alexfauquette

I left few comments, but for me it's good.

I just wait for the removal of the test demo before approving to be sure nobody merge it by mistake 🙈

docs/scripts/formattedTSDemos.js

alexfauquette · 2024-10-24T14:10:33Z

docs/src/modules/sandbox/FlattenRelativeImports.ts

@@ -5,6 +5,9 @@ export default function flattenRelativeImports(rawCode: string, modulePaths: str
    // Move the relative import to the current directory
    const newPath = `./${pathWithoutExtension.replace(/^.*[\\/]/g, '')}`;
    newCode = newCode.replace(pathWithoutExtension, newPath);
+
+    // Replace the relative import towards parent directory
+    newCode = newCode.replace('../', './');


I got confused when writing this piece of code. I thaught path would be the path as expressed in the file. But it's the path from the root of the Demo.

We could move the replace outside of the forEach by using a replaceAll. Currently, it works because we apply this Replace once per file existing in the demo

Another option would be to use similar Regexp as the one to compute newPath

newCode = newCode.replace(/from '.*[\\/]/g, `from './`);

It replaces any sequence of . and / to support multiple levels of nested components (I hope we
will not reach that level 🙈)

And the from ' prevent replacing a ../ that could be present in the comments

packages/markdown/loader.js

mnajdova · 2024-10-25T09:25:10Z

@alexfauquette all comments were resolved in separate commits, you can checke the changes commit per commit. Everything was working as expected (I've tested after all the changes). I noticed one breaking change tough, I described it in the PR description. I am tagging @bharatkashyap too to be aware for it for the Toolpad project. Tagging also @michaldudak I am not sure if this affects the new Base UI docs, but just in case.

alexfauquette

Nice reduction of the flattenRelativeImports 👍

BY the way @bharatkashyap this PR might close some of the followup issues

bharatkashyap

What a great improvement! Thanks for working on this. Added some small suggestions

packages/markdown/loader.js

michaldudak · 2024-10-29T10:26:12Z

For the record, the demo loader used in Base UI docs has this functionality built-in already, so once we propagate it to other repos, it should still work fine.

Co-authored-by: Bharat Kashyap <[email protected]> Signed-off-by: Marija Najdova <[email protected]>

[docs-infra] Add recursively the relative modules in the demos

2ac8d3b

mnajdova added the scope: docs-infra Specific to the docs-infra product label Oct 18, 2024

mnajdova added 3 commits October 18, 2024 14:56

add DataGrid demo for testing

f688c35

Update the script to support .js files

31b81e6

update codesandbox and stackblitz

e41c30a

mnajdova closed this Oct 21, 2024

alexfauquette mentioned this pull request Oct 23, 2024

[docs] Chart example with responsive container and tooltip demo is broken mui/mui-x#15059

Closed

mnajdova reopened this Oct 23, 2024

mnajdova added 3 commits October 24, 2024 11:56

fix TS demos

8270fb8

Merge branch 'master' into docs/demos-fix

b3652fb

fix lint issues

617e250

mnajdova commented Oct 24, 2024

View reviewed changes

docs/scripts/formattedTSDemos.js Outdated Show resolved Hide resolved

mnajdova commented Oct 24, 2024

View reviewed changes

docs/scripts/formattedTSDemos.js Show resolved Hide resolved

mnajdova commented Oct 24, 2024

View reviewed changes

cleanup the code

b0357d5

mnajdova marked this pull request as ready for review October 24, 2024 12:52

mnajdova requested review from bharatkashyap and alexfauquette October 24, 2024 12:52

alexfauquette reviewed Oct 24, 2024

View reviewed changes

mnajdova added 6 commits October 25, 2024 09:19

simplify refexp

886577e

add early continue statement

5effeec

add TS version of top100Films file

c033e45

Merge branch 'master' into docs/demos-fix

156c128

simplify flattenRelativeImporst util

2dfdc9a

remove ListView demo

c70dce0

lint issue

0463a8a

mnajdova added the breaking change label Oct 25, 2024

mnajdova requested a review from alexfauquette October 25, 2024 10:09

alexfauquette approved these changes Oct 25, 2024

View reviewed changes

bharatkashyap approved these changes Oct 25, 2024

View reviewed changes

mnajdova and others added 5 commits October 30, 2024 08:08

Merge branch 'master' into docs/demos-fix

64736e8

Update packages/markdown/loader.js

84a5210

Co-authored-by: Bharat Kashyap <[email protected]> Signed-off-by: Marija Najdova <[email protected]>

move function outside of loop

87afe6c

remove unnecessary conditions

87dc3fd

fix relativeModules map

07f45cf

mnajdova merged commit 4d6e990 into mui:master Oct 30, 2024
22 checks passed

KenanYusuf mentioned this pull request Nov 8, 2024

[docs-infra] Transpile .ts demo files mui/mui-x#15345

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs-infra] Add recursively the relative modules in the demos #44150

[docs-infra] Add recursively the relative modules in the demos #44150

mnajdova commented Oct 18, 2024 •

edited by bharatkashyap

Loading

mui-bot commented Oct 18, 2024 •

edited

Loading

mnajdova Oct 24, 2024

mnajdova Oct 24, 2024

alexfauquette Oct 24, 2024

mnajdova Oct 24, 2024

mnajdova Oct 24, 2024

mnajdova Oct 24, 2024

alexfauquette left a comment

alexfauquette Oct 24, 2024

mnajdova commented Oct 25, 2024

alexfauquette left a comment

bharatkashyap left a comment

michaldudak commented Oct 29, 2024

[docs-infra] Add recursively the relative modules in the demos #44150

[docs-infra] Add recursively the relative modules in the demos #44150

Conversation

mnajdova commented Oct 18, 2024 • edited by bharatkashyap Loading

BRREAKING CHANGE

mui-bot commented Oct 18, 2024 • edited Loading

Netlify deploy preview

Bundle size report

mnajdova Oct 24, 2024

Choose a reason for hiding this comment

mnajdova Oct 24, 2024

Choose a reason for hiding this comment

alexfauquette Oct 24, 2024

Choose a reason for hiding this comment

mnajdova Oct 24, 2024

Choose a reason for hiding this comment

mnajdova Oct 24, 2024

Choose a reason for hiding this comment

mnajdova Oct 24, 2024

Choose a reason for hiding this comment

alexfauquette left a comment

Choose a reason for hiding this comment

alexfauquette Oct 24, 2024

Choose a reason for hiding this comment

mnajdova commented Oct 25, 2024

alexfauquette left a comment

Choose a reason for hiding this comment

bharatkashyap left a comment

Choose a reason for hiding this comment

michaldudak commented Oct 29, 2024

mnajdova commented Oct 18, 2024 •

edited by bharatkashyap

Loading

mui-bot commented Oct 18, 2024 •

edited

Loading