[camdecoster]

Description

Add TypeScript declarations for lifecycle and WebGL context events.

Changes

• Add new types
• Rename test file
• Add new TS type tests

Testing

• Check CI
• Locally, run npm run test-types
• Open test/types/events.ts
• Hover over a gd.on('plotly_...', (event) => ...) call
• Note that the proper type appears in the tooltip
• In the same file, type gd.on('plotly_ on a new line
• Note that you're prompted to fill in a number of event types, including the new events

Notes

• This was found while I was reviewing Remove the @types/plotly.js dev dependency plotly.py#5759

[KoolADE85]

These types reuse SunburstPlotDatum which declares that value, id, color, and hovertext are all required.
However, at runtime a click payload does NOT always have those fields:

gd.on('plotly_treemapclick', (e) => {
    const pt = e.points[0];
    panel.textContent = `${pt.label}: ${pt.value.toLocaleString()} people`; // TypeError: pt.value is undefined
    loadDetails(pt.id); // undefined without `ids`
});

Also, the sunburst event has the same gap today, and this PR extends the gap to two more events.
In this PR, nextLevel became optional for the same reason.

[camdecoster]

I'll make these properties optional.

[KoolADE85]

An event handler that only observes the event (i.e. does NOT return false) reports a type error:

gd.on('plotly_legendtitleclick', (e) => {
    console.log({ legend: e.legendId });
});

error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type '"plotly_legendtitleclick"' is not assignable to parameter of type '"plotly_afterexport" | ...

[camdecoster]

You're right, these should return boolean | void. I'll update them.

[KoolADE85]

Small mismatch here vs what the runtime actually does:

config is not optional here, but a call without a config sends config: undefined.

gd.on('plotly_react', (e) => console.log(e.config.responsive)); // no TS error
Plotly.react(gd, data, layout);
// TypeError: Cannot read properties of undefined (reading 'responsive')

[camdecoster]

config and layout don't have to be passed in to react, so they are optional here. You can see the logic checking both in the react code.

[KoolADE85]

This isn't new to this PR, but I just noticed it:

npm run test-types will not catch a broken type reference inside the declarations!

Example:

 export interface WebGLContextLostEvent {
     /** The original DOM `webglcontextlost` event. */
-    event: WebGLContextEvent;
+    event: WebGLContextEvnt;

• npx tsc --noEmit -p test/types --skipLibCheck false fails as expected
• npm run test-types passes

It's not obvious, but test/types/tsconfig.json is extending the root tsconfig, which sets skipLibCheck: true.

[camdecoster]

Good catch. I'll update the test tsconfig.