Skip to content

Commit e0ddeaf

Browse files
authored
Merge branch 'main' into bugfix/cursor-consistency
2 parents c2158a1 + 50084b2 commit e0ddeaf

6 files changed

Lines changed: 257 additions & 44 deletions

File tree

‎draftlogs/8145_add.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- Add TypeScript declarations for lifecycle and WebGL context events [[#8145](https://github.com/plotly/plotly.js/pull/8145)]

‎lib/index.d.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,28 +81,37 @@ export type {
8181

8282
export type {
8383
BeforePlotEvent,
84+
ButtonClickedEvent,
8485
ClickAnnotationEvent,
8586
FrameAnimationEvent,
87+
IcicleClickEvent,
88+
IciclePlotDatum,
8689
LegendClickEvent,
90+
LegendTitleClickEvent,
8791
PlotCoordinate,
8892
PlotDatum,
8993
PlotHoverEvent,
9094
PlotlyEventName,
9195
PlotlyHTMLElement,
9296
PlotMouseEvent,
97+
PlotReactEvent,
9398
PlotRelayoutEvent,
9499
PlotRestyleEvent,
95100
PlotRestyleEventUpdate,
96101
PlotScatterDataPoint,
97102
PlotScene,
98103
PlotSelectedData,
99104
PlotSelectionEvent,
105+
PlotUpdateEvent,
100106
SelectionRange,
101107
SliderChangeEvent,
102108
SliderEndEvent,
103109
SliderStartEvent,
104110
SunburstClickEvent,
105-
SunburstPlotDatum
111+
SunburstPlotDatum,
112+
TreemapClickEvent,
113+
TreemapPlotDatum,
114+
WebGLContextLostEvent
106115
} from '../src/types/core/events';
107116

108117
// ---------------------------------------------------------------------------

‎src/types/core/events.d.ts‎

Lines changed: 130 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import type {
1414
LayoutAxis,
1515
Slider,
1616
Transition,
17+
UpdateMenu
1718
} from '../generated/schema';
1819
import type { Datum } from '../lib/common';
1920
import 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
*/
158161
export 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. */
276341
export 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. */
310381
export 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

Comments
 (0)