@@ -14,6 +14,7 @@ import type {
1414 LayoutAxis ,
1515 Slider ,
1616 Transition ,
17+ UpdateMenu
1718} from '../generated/schema' ;
1819import type { Datum } from '../lib/common' ;
1920import type { Config } from './config' ;
@@ -113,6 +114,8 @@ export interface PlotMouseEvent {
113114 xPixel ?: number ;
114115 /** Cursor y position in pixels from the graph div's top-left corner */
115116 yPixel ?: number ;
117+ /** Category constraints of the hovered or clicked path, set by `parcats` traces only. */
118+ constraints ?: Record < string , any > ;
116119}
117120
118121/** Payload for `plotly_hover` — augments `PlotMouseEvent` with axis values. */
@@ -157,6 +160,14 @@ export type PlotRestyleEvent = [PlotRestyleEventUpdate, number[]];
157160 */
158161export type PlotRelayoutEvent = LayoutUpdate ;
159162
163+ /** Payload for `plotly_update`: the restyle and relayout payloads of one `Plotly.update` call. */
164+ export interface PlotUpdateEvent {
165+ /** Restyle part of the update: the attribute changes and the affected trace indices. */
166+ data : PlotRestyleEvent ;
167+ /** Relayout part of the update. */
168+ layout : PlotRelayoutEvent ;
169+ }
170+
160171// ---------------------------------------------------------------------------
161172// 3D scene / annotation / animation / legend events
162173// ---------------------------------------------------------------------------
@@ -235,6 +246,48 @@ export interface LegendClickEvent {
235246 fullLayout : Partial < Layout > ;
236247}
237248
249+ /**
250+ * Payload for `plotly_legendtitleclick` and `plotly_legendtitledoubleclick`.
251+ * Return `false` from the handler to suppress Plotly's default title click behavior.
252+ */
253+ export interface LegendTitleClickEvent {
254+ /** The original DOM mouse event. */
255+ event : MouseEvent ;
256+ /** Id of the legend whose title was clicked, for example `'legend2'`. */
257+ legendId : string ;
258+ /** User-supplied data array. */
259+ data : Data [ ] ;
260+ /** User-supplied layout object. */
261+ layout : Partial < Layout > ;
262+ /** Fully-resolved data array (defaults applied). */
263+ fullData : Data [ ] ;
264+ /** Fully-resolved layout object (defaults applied). */
265+ fullLayout : Partial < Layout > ;
266+ }
267+
268+ /**
269+ * Payload for `plotly_react`. The event does not fire if the call changed the config.
270+ * The `config` and `layout` values are `undefined` if the `Plotly.react` call omitted them.
271+ */
272+ export interface PlotReactEvent {
273+ /** User-supplied config object. */
274+ config : Partial < Config > | undefined ;
275+ /** User-supplied data array. */
276+ data : Data [ ] ;
277+ /** User-supplied layout object. */
278+ layout : Partial < Layout > | undefined ;
279+ }
280+
281+ /** Payload for `plotly_buttonclicked`, emitted when a button of an updatemenu is clicked. */
282+ export interface ButtonClickedEvent {
283+ /** The updatemenu that holds the button. */
284+ menu : UpdateMenu ;
285+ /** The clicked button. */
286+ button : NonNullable < UpdateMenu [ 'buttons' ] > [ number ] ;
287+ /** Index of the active button, or `-1` if none is active. */
288+ active : number ;
289+ }
290+
238291// ---------------------------------------------------------------------------
239292// Slider events
240293// ---------------------------------------------------------------------------
@@ -268,14 +321,26 @@ export interface SliderEndEvent {
268321 step : SliderStep ;
269322}
270323
324+ // ---------------------------------------------------------------------------
325+ // WebGL context events
326+ // ---------------------------------------------------------------------------
327+
328+ /** Payload for `plotly_webglcontextlost`, emitted when a WebGL context is lost. */
329+ export interface WebGLContextLostEvent {
330+ /** The original DOM `webglcontextlost` event. */
331+ event : WebGLContextEvent ;
332+ /** Identifier of the regl layer or the gl3d scene that lost its context. */
333+ layer : string ;
334+ }
335+
271336// ---------------------------------------------------------------------------
272337// Sunburst / before-plot
273338// ---------------------------------------------------------------------------
274339
275- /** Point payload for `plotly_sunburstclick`. */
340+ /** Point payload for `plotly_sunburstclick`. Treemap and icicle traces emit the same point shape. */
276341export interface SunburstPlotDatum {
277- /** Color value associated with the sector. */
278- color : number ;
342+ /** Color value associated with the sector. Present only if the trace sets `marker.colors`. */
343+ color ? : number | undefined ;
279344 /** Index of the trace producing this sector. */
280345 curveNumber : number ;
281346 /** The trace this sector belongs to. */
@@ -284,14 +349,14 @@ export interface SunburstPlotDatum {
284349 entry : string ;
285350 /** Fully-resolved trace data. */
286351 fullData : Data ;
287- /** Hover text shown for this sector. */
288- hovertext : string ;
289- /** Hierarchical id of the sector. */
290- id : string ;
291- /** Display label of the sector. */
292- label : string ;
293- /** Parent sector id. */
294- parent : string ;
352+ /** Hover text shown for this sector. Present only if the trace sets `hovertext`. */
353+ hovertext ? : string | undefined ;
354+ /** Hierarchical id of the sector. Present only if the trace sets `ids`. */
355+ id ? : string | undefined ;
356+ /** Display label of the sector. Present only if the trace sets `labels`. */
357+ label ? : string | undefined ;
358+ /** Parent sector id. Absent on the root sector. */
359+ parent ? : string | undefined ;
295360 /** Percentage of the immediate entry sector this sector represents. */
296361 percentEntry : number ;
297362 /** Percentage of the parent sector this sector represents. */
@@ -302,20 +367,32 @@ export interface SunburstPlotDatum {
302367 pointNumber : number ;
303368 /** Root sector id. */
304369 root : string ;
305- /** Numeric value of the sector. */
306- value : number ;
370+ /** Numeric value of the sector. Present only if the trace sets `values`. */
371+ value ? : number | undefined ;
307372}
308373
309- /** Payload for `plotly_sunburstclick`, including the next-level entry. */
374+ /** Point payload for `plotly_treemapclick`. Same shape as `SunburstPlotDatum`. */
375+ export type TreemapPlotDatum = SunburstPlotDatum ;
376+
377+ /** Point payload for `plotly_icicleclick`. Same shape as `SunburstPlotDatum`. */
378+ export type IciclePlotDatum = SunburstPlotDatum ;
379+
380+ /** Payload for `plotly_sunburstclick`. Treemap and icicle traces emit the same payload, including the next-level entry. */
310381export interface SunburstClickEvent {
311382 /** The original DOM mouse event. */
312383 event : MouseEvent ;
313- /** Sector id that becomes the entry on click. */
314- nextLevel : string ;
384+ /** Sector id that becomes the entry on click. Absent when the click does not change the entry, as on a sunburst root or leaf. */
385+ nextLevel ? : string ;
315386 /** Clicked sector(s). */
316387 points : SunburstPlotDatum [ ] ;
317388}
318389
390+ /** Payload for `plotly_treemapclick`. Same shape as `SunburstClickEvent`. */
391+ export type TreemapClickEvent = SunburstClickEvent ;
392+
393+ /** Payload for `plotly_icicleclick`. Same shape as `SunburstClickEvent`. */
394+ export type IcicleClickEvent = SunburstClickEvent ;
395+
319396/**
320397 * Payload for `plotly_beforeplot`. Returning `false` from the handler
321398 * cancels the plot operation.
@@ -349,37 +426,62 @@ export interface PlotlyHTMLElement extends HTMLElement {
349426 on ( event : 'plotly_restyle' , callback : ( data : PlotRestyleEvent ) => void ) : void ;
350427 /** Subscribe to relayout events (layout updates, including in-progress). */
351428 on ( event : 'plotly_relayout' | 'plotly_relayouting' , callback : ( event : PlotRelayoutEvent ) => void ) : void ;
429+ /** Subscribe to update events (`Plotly.update` calls). */
430+ on ( event : 'plotly_update' , callback : ( event : PlotUpdateEvent ) => void ) : void ;
431+ /** Subscribe to WebGL context loss events. */
432+ on ( event : 'plotly_webglcontextlost' , callback : ( event : WebGLContextLostEvent ) => void ) : void ;
352433 /** Subscribe to annotation click events. */
353434 on ( event : 'plotly_clickannotation' , callback : ( event : ClickAnnotationEvent ) => void ) : void ;
354435 /** Subscribe to per-frame animation events. */
355436 on ( event : 'plotly_animatingframe' , callback : ( event : FrameAnimationEvent ) => void ) : void ;
356437 /** Subscribe to legend click events; return `false` to suppress default toggle. */
357- on ( event : 'plotly_legendclick' | 'plotly_legenddoubleclick' , callback : ( event : LegendClickEvent ) => boolean ) : void ;
438+ on (
439+ event : 'plotly_legendclick' | 'plotly_legenddoubleclick' ,
440+ callback : ( event : LegendClickEvent ) => boolean | void
441+ ) : void ;
442+ /** Subscribe to legend title click events; return `false` to suppress default behavior. */
443+ on (
444+ event : 'plotly_legendtitleclick' | 'plotly_legendtitledoubleclick' ,
445+ callback : ( event : LegendTitleClickEvent ) => boolean | void
446+ ) : void ;
447+ /** Subscribe to react events. */
448+ on ( event : 'plotly_react' , callback : ( event : PlotReactEvent ) => void ) : void ;
449+ /** Subscribe to updatemenu button click events. */
450+ on ( event : 'plotly_buttonclicked' , callback : ( event : ButtonClickedEvent ) => void ) : void ;
451+ /** Subscribe to pre-hover events; return `false` to cancel the hover. */
452+ on ( event : 'plotly_beforehover' , callback : ( event : MouseEvent ) => boolean | void ) : void ;
358453 /** Subscribe to slider change events. */
359454 on ( event : 'plotly_sliderchange' , callback : ( event : SliderChangeEvent ) => void ) : void ;
360455 /** Subscribe to slider end-of-interaction events. */
361456 on ( event : 'plotly_sliderend' , callback : ( event : SliderEndEvent ) => void ) : void ;
362457 /** Subscribe to slider start-of-interaction events. */
363458 on ( event : 'plotly_sliderstart' , callback : ( event : SliderStartEvent ) => void ) : void ;
364- /** Subscribe to sunburst sector click events. */
365- on ( event : 'plotly_sunburstclick' , callback : ( event : SunburstClickEvent ) => void ) : void ;
459+ /** Subscribe to sunburst sector click events; return `false` to suppress the default zoom. */
460+ on ( event : 'plotly_sunburstclick' , callback : ( event : SunburstClickEvent ) => boolean | void ) : void ;
461+ /** Subscribe to treemap sector click events; return `false` to suppress the default zoom. */
462+ on ( event : 'plotly_treemapclick' , callback : ( event : TreemapClickEvent ) => boolean | void ) : void ;
463+ /** Subscribe to icicle sector click events; return `false` to suppress the default zoom. */
464+ on ( event : 'plotly_icicleclick' , callback : ( event : IcicleClickEvent ) => boolean | void ) : void ;
366465 /** Subscribe to generic plotly events (low-level catch-all). */
367466 on ( event : 'plotly_event' , callback : ( data : any ) => void ) : void ;
368467 /** Subscribe to pre-plot events; return `false` to cancel plotting. */
369- on ( event : 'plotly_beforeplot' , callback : ( event : BeforePlotEvent ) => boolean ) : void ;
468+ on ( event : 'plotly_beforeplot' , callback : ( event : BeforePlotEvent ) => boolean | void ) : void ;
370469 /** Subscribe to bare lifecycle events that carry no payload. */
371470 on (
372471 event :
373472 | 'plotly_afterexport'
374473 | 'plotly_afterplot'
375474 | 'plotly_animated'
475+ | 'plotly_animating'
376476 | 'plotly_animationinterrupted'
377477 | 'plotly_autosize'
378478 | 'plotly_beforeexport'
379479 | 'plotly_deselect'
380480 | 'plotly_doubleclick'
481+ | 'plotly_exportfail'
381482 | 'plotly_framework'
382483 | 'plotly_redraw'
484+ | 'plotly_transitioned'
383485 | 'plotly_transitioning'
384486 | 'plotly_transitioninterrupted' ,
385487 callback : ( ) => void
@@ -401,6 +503,7 @@ export type PlotlyEventName =
401503 | 'plotly_afterexport'
402504 | 'plotly_afterplot'
403505 | 'plotly_animated'
506+ | 'plotly_animating'
404507 | 'plotly_animatingframe'
405508 | 'plotly_animationinterrupted'
406509 | 'plotly_autosize'
@@ -412,10 +515,15 @@ export type PlotlyEventName =
412515 | 'plotly_clickannotation'
413516 | 'plotly_deselect'
414517 | 'plotly_doubleclick'
518+ | 'plotly_exportfail'
415519 | 'plotly_framework'
416520 | 'plotly_hover'
521+ | 'plotly_icicleclick'
417522 | 'plotly_legendclick'
418523 | 'plotly_legenddoubleclick'
524+ | 'plotly_legendtitleclick'
525+ | 'plotly_legendtitledoubleclick'
526+ | 'plotly_react'
419527 | 'plotly_redraw'
420528 | 'plotly_relayout'
421529 | 'plotly_relayouting'
@@ -426,8 +534,10 @@ export type PlotlyEventName =
426534 | 'plotly_sliderend'
427535 | 'plotly_sliderstart'
428536 | 'plotly_sunburstclick'
537+ | 'plotly_transitioned'
429538 | 'plotly_transitioning'
430539 | 'plotly_transitioninterrupted'
431540 | 'plotly_treemapclick'
432541 | 'plotly_unhover'
542+ | 'plotly_update'
433543 | 'plotly_webglcontextlost' ;
0 commit comments