Embed growth chart client into mkdocs, remove iframe

[dc2007git]

Need to build in the growth chart client into mkdocs. Iframe makes it difficult to zoom as confuses the action with scrolling

[pacharanero]

Agreed. The iframe was always a bit of a hack really, it got the job done, but it affects zoom functionality.

We also need to bring the codebase for the React client into the same repo as the MkDocs site. It'll result is a slightly more complex GitHub Action/workflow for build, but it'll be tidier and better integrated.

Anyone fancy taking on this job? @anchit-chandran @dc2007git @eatyourpeas @chvanlennep?
Any thoughts about the proposal? Alternative suggestions?

[Raxxius]

Process for direct implimentation of React Component into Material for MKDocs via <script> injection

Requirements

React component ready for deployment
MKDocs environment

Process

Prepare React Component pre React 18

1. In the React 'public' folder select the index.html file
2. In the component rename the
   to an appropriate name e.g.
3. In the React 'src' folder select the index.js file
4. Change the ReactDOM render command to the same name e.g. ReactDOM.render( , document.getElementById("growth-chart") );
5. In the terminal run "npm run build"

This process will create a folder named "build" in your React component directory

• Note the above is not strictly necessary as the default "root" id will work, however should you need to render more than one react component you will end up with multiple divs with id "root" which will cause issues.

Prepare React Component React 18+

React 18 changes the setup of a basic React component, moving the index.js to the 'src' folder, and replacing ReactDOM.render with ReactDOM.createROOT, regardless the document.getElementById("TAG") change will remain and this will be the key value to change.

• Note certain other React app creation devices (such as Vite) change build folders as well, so when npm run build is used, the actual build folder can vary.

Move React Component into MkDocs

1. In the React "build" folder open the "static" then "js" folders
2. There should be a js file titled main.A_HASH_CODE.js
3. Rename this js file to something appropiate, e.g. growthChart.js
4. In the React "build" folder open the "static" then "css" folders
5. There should be a js file titled main.A_HASH_CODE.css
6. Rename this js file to something appropiate, e.g. growth-chart.css
7. In your MkDocs "docs" directory create or open a folder called "assets"
8. Copy the js and css files into the assets folder

Rendering a React component in Material for MkDocs

1. In the relevant MkDocs page place the following code

   <script src="/assets/growthChart.js"></script>

2. In the mkdocs.yml add the css with the following code

   extra_css:

   • /assets/growth-chart.css

Component should now render in MkDocs.

Notes/Bugs/Issues

1. MkDocs provides basic css which can interfear with the React components css via undeclared variables not being standard, suggest using a css reset on the main react container to prevent styling.
2. React css will be loaded on all pages, even ones without the React component - will look into potential fixes.

[eatyourpeas]

This is very promising and might address the issue one of our implementers has using Coldfusion and cannot use NPM.

Does this involve importing react, react-dom and babel in the head tag?
Does it matter how the app is built ? (ie ESM vs UMD etc)

[Raxxius]

This is very promising and might address the issue one of our implementers has using Coldfusion and cannot use NPM.

Does this involve importing react, react-dom and babel in the head tag? Does it matter how the app is built ? (ie ESM vs UMD etc)

So from how I understand it's working it doesn't need react, react-dom or babel in the head tags as I didn't include them in my demo build, and when you execute a 'run build' command it creates a javascript file that's designed to be read by webclients, so Babel is already used at that stage.

The demo I setup on https://react-in-mkdocs-test.vercel.app/ was a React 17 project I built about a year ago, and but I've tested with a React 18 project as well, all be it a simple one.

I can't conclusively say if how the React app is constructed is irrelvant, I think if code blocks are used and multiple js files are generated then more work will be required to see how they interact. It might be as simple as sequential script execution. As for ESM vs UMD I'd have to run some live test, but I don't think in principle any specific build style is required.

[mbarton]

I've raised rcpch/digital-growth-charts-react-component-library#135 to track the iframe build in the main repo as it could be a helpful way of integrating for some customers