build: Enable TypeScript type checking

[camdecoster]

Description

Enable TypeScript type checking.

Closes #7678.

Changes

• Add set of plotly.js types
• Enable type checking
• Update some files to TypeScript
• Use ts-node for running some scripts
• Add type generation script that uses attributes files schema
• Add type checking steps to CI

Testing

• CI should cover everything
• Run npm run build locally to check that everything is bundled properly by esbuild
• Run npm run schema to recreate the generated types
• 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
  
  > plotly.js@3.5.1 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 of the types are now built straight from the schema
• (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.
• There's an entry point for types now. It points to the public types, which are a subset of all types. In the future, there could be a type build step that compiles them down to a flat file.

[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.

[camdecoster]

There's an issue that covers converting from CJS to ESM in #7119. I left a comment mentioning your suggestion.

[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

[codeCraft-Ritik]

Great work! The implementation is clean and easy to understand

[emilykl]

or layer a hand-written refinement on top

I'm not sure there's really a clean way to do this using the proposed architecture

[camdecoster]

You could extend the generated type with the additional information without too much trouble. The clunky part would be the naming. For ModeBar, you could generate ModeBarGenerated then extend it as ModeBar. Not ideal, but it would work.

[emilykl]

@camdecoster As far as I can tell, the attributes defined in src/plots/attributes.js are additionally added to every trace type, so that probably needs to be accounted for in the type gen. (Unless it doesn't matter if some attributes are missing, I'm not sure what the consequences of that are)