build: Enable TypeScript type checking

[camdecoster]

Description

Enable TypeScript type checking.

Closes #7678.

Changes

• Add limited set of plotly.js types
• Enable type checking
• Update some files to TypeScript
• Use ts-node for running some scripts

Testing

• CI should cover everything
• Run npm run build locally to check that everything is bundled properly by esbuild
• Run plotly.js devtools and load some mocks to make sure everything is working correctly
• Run npm run typecheck to perform a type check on the source code. There should be no errors:

  $ npm run typecheck
  
  > [email protected] typecheck
  > tsc --noEmit
  $

Notes

• This PR adds the TypeScript compiler and typechecking via npm script
• The provided types are a combination of plotly.js types from DefinitelyTyped and the schema (with Claude combining the two). This is a first pass and the types will need to be updated as files are converted.
• (Most) IDEs will read the types and provide autocompletion once files are converted over
• Read the README in src/types for an overview of how the types are set up
• esbuild is compatible with TypeScript already, but it doesn't do type checking. To check types you need to run npm run typecheck. VS Code will also provide feedback as you're editing files.
• I converted a few simple files to TypeScript as an example. I opted to use ESM syntax for these files which necessitated some changes in the require statements for the converted files. This is due to how esbuild determines if a default import should be namespaced or not.
• Some of the converted files are used in scripts not processed by esbuild. Node 18 doesn't handle TS files natively, so these scripts need to be run with ts-node, a "TypeScript execution and REPL for node.js".
• The TS config is pretty lenient right now to make it easier to convert things piece by piece. Once we make enough progress, this can be tightened up.
• TS is not emitting files/types right now. esbuild handles converting the TS so the TS compiler won't need to do that. It would be valuable to have the compiler write the type definition files in the future.

[emilykl]

@camdecoster Is it worth considering moving away from default exports entirely as part of this transition?

[camdecoster]

It only matters when one mixes CJS and ESM. That said, I don't think that we can avoid that for a long time. I suppose we could make just pick a direction to go and standardize. I could go either way, but the esbuild docs make it clear that they don't like default exports.

[emilykl]

Does TypeScript have any support for 'flag list'-type string values such as this, where the string may consist of any number of a fixed set of values joined by a delimiter? I suppose not as it's fairly custom.

Otherwise could we use a custom type or a custom function to generate these lists of allowed values based on the flags?

[camdecoster]

Yes, it's called a union type. What's shown on 133 is an example of that (though it's only used on that line). If we needed that type elsewhere, we could define it separately and reference it within the ScatterTrace type like this:

type Mode = 'lines' | 'markers' | 'lines+markers' | 'none' | 'text' | 'lines+text' | 'markers+text' | 'lines+markers+text';

export interface ScatterTrace extends TraceBase {
    ...,
    mode: Mode;
    ...,
}

[emilykl]

Yeah I guess I'm imagining something like a helper function which looks like flagList(flaglistVals, otherVals) such that

flaglistVals(['lines', 'markers', 'text'], ['none'])

returns

'lines' | 'markers' | 'lines+markers' | 'none' | 'text' | 'lines+text' | 'markers+text' | 'lines+markers+text';`

[emilykl]

I'm not sure there are any traces where x/y/z are allowed to be a type other than number[] | string[] but I could be wrong about that.

[camdecoster]

That's why it's permissive here. Once we become sure, we can change this as you suggest.

[emilykl]

In this case maybe it would be easier to start stricter and loosen if needed?

[emilykl]

Actually, scratch that

[emilykl]

@camdecoster Can you add a type-check step to the CI?

[emilykl]

Can we tighten this layout spec here to match the plot schema?

[emilykl]

@camdecoster Some initial thoughts on organization of the types:

For types corresponding directly to the schema:

• Group them all under a single directory (e.g. types/core/schema/), maybe even in a single file if not too unwieldy
• Use nested types where useful for repeated patterns (e.g. font options); these should use some kind of consistent naming scheme