chore: clean up code in mermaidAPI render() and write specs/tests

[weedySeaDragon]

📑 Summary

Cleaned up and refactored render() in mermaidAPI so that specs/tests could be written for discrete steps, reduced duplication, and made it easier to understand for future maintainers.

Partially resolves #3648

📏 Design Decisions

There is more refactoring and clean-up that can be done (including the other main functions), but this is a first pass. render() seemed the most important because it is the core functionality.

Could not figure out how to mock/spyOn just one function within mermaidAPI, so some tests instead painfully check results. See TODOs in mermaidAPI.spec.ts.

• cleaned up code: DRY, created constants for literals, renamed variables to clarify intent
• refactored into testable functions
• wrote specs/tests

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 🔖 targeted develop branch

[sidharthv96]

@weedySeaDragon, added some more types and slightly wandered into some related files.
Saw some TODOs, are they intended for a discussion here?

[weedySeaDragon]

@sidharthv96 -- looks like I shouldn't change if statements to one line. Ex:

if (someConditional) {
  something = someNewValue; // some short 1 line statement
}

changed to

if (someConditional)  something = someNewValue; // some short 1 line statement

There is an eslint rule for this: curly: "error" (default is that all should be blocks with curly braces). Should we put it into .eslintrc.json? (Obv we should create a separate issue. Mentioning it here because I was looking at your changes.

[weedySeaDragon]

@sidharthv96 Re TODOs -- mostly they are for the future. But we can discuss and try to resolve with this PR if you think that's best.

[weedySeaDragon]

@sidharthv96 p.s. I just logged into Slack if you want to chat there. (My user name there is 'Ashley Engelund' which is my IRL name :-)

[sidharthv96]

There is an eslint rule for this: curly: "error" (default is that all should be blocks with curly braces). Should we put it into .eslintrc.json? (Obv we should create a separate issue. Mentioning it here because I was looking at your changes.

I didn't add curly to keep the footprint low. We should add it separately. I'll create an issue.

[knsv]

@weedySeaDragon @sidharthv96 Hey, whats the status on this one?

[weedySeaDragon]

I've been waiting for more reviews.

(I'll merge it with the most recent to bring it up to date.)

[weedySeaDragon]

@sidharthv96 - This is still failing during pnpm run docs:verify.
The package.json file doesn't even have any of the docs.. scripts. (They got removed during all of the vitepress/documentation changes.)
Even so, when I (manually) run

ts-node-esm packages/mermaid/src/docs.mts

no document are updated ("Transforming 0 ___ files..." for all file types), and

ts-node-esm packages/mermaid/src/docs.mts --verify

verifies 0 files (for all file types).

Not sure how else to verify or change the src/docs files locally to get this to pass during CI.

ETA: Comparing /docs/setup/modules/mermaidAPI.md with src/setup/modules/mermaidAPI.md on my machine, there are 2 differences:

1. line 19 in docs version, line 13 on src version:
   there is a "/" before the closing ">" in src but not in the docs version

2. The parameters tables are not the same for only some of the functions. There are differences for these functions:

   • createCssStyles
   • createUserStyles
   • cssImportantStyles

(As a side note: those are exported just so they can be tested in the spec. Is there a different/better way to be able to test them without having them be "public" via export statements? Certainly the "right" way is to never test private (non-exported) functions, but to only test the results of them (the ultimate effect/result). I can certainly do that, but it's rather tedious. )

[sidharthv96]

I think this might be the issue.

[weedySeaDragon]

Thanks for fixing those.

Shouldn't those differences have been taken care of automatically?
And is there anything I could have done locally to detect the problem?

[sidharthv96]

Thanks for fixing those.

Shouldn't those differences have been taken care of automatically? And is there anything I could have done locally to detect the problem?

They should be, from now on.

Added the correct config for typedoc here.

[sidharthv96]

LGTM!

This should make the merge from master with the duplicate renderAsync much smaller.

[MermaidChart]

Good job! I can see how the d3 mock can be usefull!