Docs in UI

I think storybook is a fantastic tool and would be perfect to leverage in visual testing. However, storybook is not a very good substitute for documentation. I would like to implement something similar to what EUI has done for charts here but more in-depth.

Fortunately, typescript is a huge plus for generating docs for getting the possible props as storybook does today.

This would also include a stackblitz-like UI to modify the chart code in the browser and see instant UI updates.

Docs in code

To a certain extent, if done right, our code could be self documented. I would like to enhance our JSDocs to provide context to the user what each and every property does and how it will affect the chart they are building.

Some resistance to JSDocs might be to not bloat the size of the final bundle size. To address this I would love to see us distribute a “dev” version of our library packed FULL of documentation. This would not have to worry about minifying or obfuscating the library. This somewhat piggybacks off of issue #85 in providing a verbose way for us as developers of charts to explain how the configuration is wrong and explain to the consumer how to fix it.

In addition to JSDocs I think we could have a way to programmatically help the Chart developers. This could include:

• Console warnings or errors when their configuration is bad
• Use React error boundaries to display error help messages.
• Point to docs to help resolve issues or suggestions to help fix

The library would have a “prod” version of the library the strips all comments and helper warnings and optimize the size of the final bundle. I'm thinking some webpack plugin that can remove code like. This could be achieved using vite along with dead code elimination for prod builds, See example here.

const domain = { max: Infinity };

/* echRemove:start */
if (domain.max === Infinity) {
  console.warn('domain max value must be a real number')
}
/* echRemove:end */

then the final output would be

const domain = { max: Infinity };