Address PR feedback

Author: camdecoster

src/types/core/events.d.ts

@@ -265,14 +265,17 @@ export interface LegendTitleClickEvent {
     fullLayout: Partial<Layout>;
 }
 
-/** Payload for `plotly_react`, emitted after a `Plotly.react` call that left the config unchanged. */
+/**
+ * Payload for `plotly_react`. The event does not fire if the call changed the config.
+ * The `config` and `layout` values are `undefined` if the `Plotly.react` call omitted them.
+ */
 export interface PlotReactEvent {
     /** User-supplied config object. */
-    config: Partial<Config>;
+    config: Partial<Config> | undefined;
     /** User-supplied data array. */
     data: Data[];
     /** User-supplied layout object. */
-    layout: Partial<Layout>;
+    layout: Partial<Layout> | undefined;
 }
 
 /** Payload for `plotly_buttonclicked`, emitted when a button of an updatemenu is clicked. */
@@ -336,8 +339,8 @@ export interface WebGLContextLostEvent {
 
 /** Point payload for `plotly_sunburstclick`. Treemap and icicle traces emit the same point shape. */
 export interface SunburstPlotDatum {
-    /** Color value associated with the sector. */
-    color: number;
+    /** Color value associated with the sector. Present only if the trace sets `marker.colors`. */
+    color?: number | undefined;
     /** Index of the trace producing this sector. */
     curveNumber: number;
     /** The trace this sector belongs to. */
@@ -346,14 +349,14 @@ export interface SunburstPlotDatum {
     entry: string;
     /** Fully-resolved trace data. */
     fullData: Data;
-    /** Hover text shown for this sector. */
-    hovertext: string;
-    /** Hierarchical id of the sector. */
-    id: string;
-    /** Display label of the sector. */
-    label: string;
-    /** Parent sector id. */
-    parent: string;
+    /** Hover text shown for this sector. Present only if the trace sets `hovertext`. */
+    hovertext?: string | undefined;
+    /** Hierarchical id of the sector. Present only if the trace sets `ids`. */
+    id?: string | undefined;
+    /** Display label of the sector. Present only if the trace sets `labels`. */
+    label?: string | undefined;
+    /** Parent sector id. Absent on the root sector. */
+    parent?: string | undefined;
     /** Percentage of the immediate entry sector this sector represents. */
     percentEntry: number;
     /** Percentage of the parent sector this sector represents. */
@@ -364,8 +367,8 @@ export interface SunburstPlotDatum {
     pointNumber: number;
     /** Root sector id. */
     root: string;
-    /** Numeric value of the sector. */
-    value: number;
+    /** Numeric value of the sector. Present only if the trace sets `values`. */
+    value?: number | undefined;
 }
 
 /** Point payload for `plotly_treemapclick`. Same shape as `SunburstPlotDatum`. */
@@ -432,34 +435,37 @@ export interface PlotlyHTMLElement extends HTMLElement {
     /** Subscribe to per-frame animation events. */
     on(event: 'plotly_animatingframe', callback: (event: FrameAnimationEvent) => void): void;
     /** Subscribe to legend click events; return `false` to suppress default toggle. */
-    on(event: 'plotly_legendclick' | 'plotly_legenddoubleclick', callback: (event: LegendClickEvent) => boolean): void;
+    on(
+        event: 'plotly_legendclick' | 'plotly_legenddoubleclick',
+        callback: (event: LegendClickEvent) => boolean | void
+    ): void;
     /** Subscribe to legend title click events; return `false` to suppress default behavior. */
     on(
         event: 'plotly_legendtitleclick' | 'plotly_legendtitledoubleclick',
-        callback: (event: LegendTitleClickEvent) => boolean
+        callback: (event: LegendTitleClickEvent) => boolean | void
     ): void;
     /** Subscribe to react events. */
     on(event: 'plotly_react', callback: (event: PlotReactEvent) => void): void;
     /** Subscribe to updatemenu button click events. */
     on(event: 'plotly_buttonclicked', callback: (event: ButtonClickedEvent) => void): void;
     /** Subscribe to pre-hover events; return `false` to cancel the hover. */
-    on(event: 'plotly_beforehover', callback: (event: MouseEvent) => boolean): void;
+    on(event: 'plotly_beforehover', callback: (event: MouseEvent) => boolean | void): void;
     /** Subscribe to slider change events. */
     on(event: 'plotly_sliderchange', callback: (event: SliderChangeEvent) => void): void;
     /** Subscribe to slider end-of-interaction events. */
     on(event: 'plotly_sliderend', callback: (event: SliderEndEvent) => void): void;
     /** Subscribe to slider start-of-interaction events. */
     on(event: 'plotly_sliderstart', callback: (event: SliderStartEvent) => void): void;
-    /** Subscribe to sunburst sector click events. */
-    on(event: 'plotly_sunburstclick', callback: (event: SunburstClickEvent) => void): void;
-    /** Subscribe to treemap sector click events. */
-    on(event: 'plotly_treemapclick', callback: (event: TreemapClickEvent) => void): void;
-    /** Subscribe to icicle sector click events. */
-    on(event: 'plotly_icicleclick', callback: (event: IcicleClickEvent) => void): void;
+    /** Subscribe to sunburst sector click events; return `false` to suppress the default zoom. */
+    on(event: 'plotly_sunburstclick', callback: (event: SunburstClickEvent) => boolean | void): void;
+    /** Subscribe to treemap sector click events; return `false` to suppress the default zoom. */
+    on(event: 'plotly_treemapclick', callback: (event: TreemapClickEvent) => boolean | void): void;
+    /** Subscribe to icicle sector click events; return `false` to suppress the default zoom. */
+    on(event: 'plotly_icicleclick', callback: (event: IcicleClickEvent) => boolean | void): void;
     /** Subscribe to generic plotly events (low-level catch-all). */
     on(event: 'plotly_event', callback: (data: any) => void): void;
     /** Subscribe to pre-plot events; return `false` to cancel plotting. */
-    on(event: 'plotly_beforeplot', callback: (event: BeforePlotEvent) => boolean): void;
+    on(event: 'plotly_beforeplot', callback: (event: BeforePlotEvent) => boolean | void): void;
     /** Subscribe to bare lifecycle events that carry no payload. */
     on(
         event:

test/types/events.ts

@@ -36,13 +36,57 @@ gd.on('plotly_webglcontextlost', (event) => {
 
 gd.on('plotly_react', (event) => {
     const dataLength: number = event.data.length;
+    const responsive: boolean | undefined = event.config?.responsive;
+    const autosize: boolean | undefined = event.layout?.autosize;
+
+    // @ts-expect-error `config` is `undefined` if the `Plotly.react` call omitted it
+    const unchecked: boolean | undefined = event.config.responsive;
 });
 
 gd.on('plotly_legendtitleclick', (event) => {
     const legendId: string = event.legendId;
     return false;
 });
 
+// A handler that only observes the event is valid
+gd.on('plotly_legendclick', (event) => {
+    console.log(event.curveNumber);
+});
+
+gd.on('plotly_legenddoubleclick', (event) => {
+    console.log(event.curveNumber);
+});
+
+gd.on('plotly_beforeplot', (event) => {
+    console.log(event.data.length);
+});
+
+gd.on('plotly_sunburstclick', (event) => {
+    console.log(event.points.length);
+});
+
+gd.on('plotly_treemapclick', (event) => {
+    console.log(event.points.length);
+});
+
+gd.on('plotly_icicleclick', (event) => {
+    console.log(event.points.length);
+});
+
+// A handler can return `false` to cancel the default behavior
+gd.on('plotly_legendclick', () => false);
+gd.on('plotly_beforeplot', () => false);
+gd.on('plotly_sunburstclick', () => false);
+gd.on('plotly_treemapclick', () => false);
+
+gd.on('plotly_legendtitleclick', (event) => {
+    console.log(event.legendId);
+});
+
+gd.on('plotly_beforehover', (event) => {
+    console.log(event.clientX);
+});
+
 gd.on('plotly_buttonclicked', (event) => {
     const active: number = event.active;
 });
@@ -58,6 +102,10 @@ gd.on('plotly_icicleclick', (event) => {
 
 gd.on('plotly_treemapclick', (event) => {
     const points: TreemapPlotDatum[] = event.points;
+
+    // @ts-expect-error `value` is absent unless the trace sets `values`
+    const value: number = points[0].value;
+    const optionalValue: number | undefined = points[0].value;
 });
 
 gd.on('plotly_animating', () => {});

test/types/tsconfig.json

@@ -1,5 +1,8 @@
 {
   "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "skipLibCheck": false
+  },
   "include": ["./**/*.ts"],
   "exclude": []
 }