feat: add typed EventMap for Paper and Graph with IDE autocomplete

packages/joint-core/test/ts/index.test.ts

@@ -4,6 +4,29 @@ import * as joint from '../../';
 
 const graph = new joint.dia.Graph({ graphAttribute: true });
 
+// graph events
+graph.on('add', function(cell, collection, options) {
+    const isCell: AssertExtends<typeof cell, joint.dia.Cell> = true;
+    const isCollection: AssertExtends<typeof collection, joint.mvc.Collection<joint.dia.Cell>> = true;
+});
+
+graph.on('batch:stop', function(data) {
+    // data is Graph.Options
+});
+
+graph.on('custom', () => {
+    // do something
+});
+
+graph.on({
+    'add': function(cell) {
+        const isCell: AssertExtends<typeof cell, joint.dia.Cell> = true;
+    },
+    'custom': () => {
+        // do something
+    }
+});
+
 const layoutPortGroupFn: joint.layout.Port.LayoutFunction = (portGroupOptions) => {
     return portGroupOptions.map((portOptions) => {
         return { x: portOptions.start, /* y: 0, angle: 0 */ };
@@ -161,13 +184,20 @@ paper.on('element:pointerdblclick', function(elementView) {
     elementView.model.addPort({});
 });
 
+paper.on('custom', () => {
+    // do something
+});
+
 paper.on({
     'render:done': function(stats) {
         if (stats.priority > 2) {
             paper.on('custom-event', function(paper: joint.dia.Paper) {
                 paper.off('custom-event');
             });
         }
+    },
+    'custom': () => {
+        // do something
     }
 });
 

packages/joint-core/types/joint.d.ts

@@ -15,6 +15,19 @@ export namespace config {
 
 type NativeEvent = Event;
 
+/**
+ * Accepts any known literal from `T` while still allowing arbitrary strings.
+ * Preserves IDE autocomplete for the known literals.
+ */
+type LiteralUnion<T extends string> = T | (string & {});
+
+/**
+ * Strips the index signature from a type, keeping only explicitly declared keys.
+ */
+type ExcludeIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]
+};
+
 type _DeepRequired<T> = {
     [P in keyof T]-?: T[P] extends object ? _DeepRequired<T[P]> : T[P];
 };
@@ -333,6 +346,35 @@ export namespace dia {
             before?: GraphLayer.ID | null;
             index?: number;
         }
+
+        interface EventMap {
+            // cell collection events
+            'add': (cell: Cell, collection: mvc.Collection<Cell>, options: Options) => void;
+            'remove': (cell: Cell, collection: mvc.Collection<Cell>, options: Options) => void;
+            'reset': (collection: mvc.Collection<Cell>, options: Options) => void;
+            'sort': (collection: mvc.Collection<Cell>, options: Options) => void;
+            'update': (collection: mvc.Collection<Cell>, options: Options) => void;
+            // cell events
+            'change': (cell: Cell, options: Options) => void;
+            [changeEvent: `change:${string}`]: (cell: Cell, newValue: any, options: Options) => void;
+            'move': (cell: Cell, options: Options) => void;
+            'changeId': (cell: Cell, previousId: Cell.ID, options: Options) => void;
+            // layer events
+            'layer:add': (layer: GraphLayer, collection: GraphLayerCollection, options: Options) => void;
+            'layer:remove': (layer: GraphLayer, collection: GraphLayerCollection, options: Options) => void;
+            'layer:change': (layer: GraphLayer, options: Options) => void;
+            [layerChangeEvent: `layer:change:${string}`]: (layer: GraphLayer, newValue: any, options: Options) => void;
+            'layer:default': (layer: GraphLayer, options: Options) => void;
+            'layers:sort': (collection: GraphLayerCollection, options: Options) => void;
+            // batch
+            'batch:start': (data: Options) => void;
+            'batch:stop': (data: Options) => void;
+            // custom
+            [eventName: string]: mvc.EventHandler;
+        }
+
+        type DefinedEventMap = ExcludeIndexSignature<EventMap>;
+
     }
 
     class Graph<A extends ObjectHash = Graph.Attributes, S = dia.ModelSetOptions> extends mvc.Model<A, S> {
@@ -355,6 +397,24 @@ export namespace dia {
             cellModel?: typeof Cell
         });
 
+        // events
+
+        on<T extends keyof Graph.DefinedEventMap>(
+            eventName: T,
+            callback: Graph.DefinedEventMap[T],
+            context?: any
+        ): this;
+        on(
+            eventName: LiteralUnion<keyof Graph.DefinedEventMap>,
+            callback: mvc.EventHandler,
+            context?: any
+        ): this;
+
+        on<E extends mvc.EventCallbackMap<Graph.DefinedEventMap>>(
+            events: E,
+            context?: any
+        ): this;
+
         addCell(cell: Graph.CellInit, opt?: CollectionAddOptions): this;
         addCell(cell: Array<Graph.CellInit>, opt?: CollectionAddOptions): this;
 
@@ -1848,6 +1908,9 @@ export namespace dia {
             // render
             'render:done': (stats: UpdateStats, opt: any) => void;
             'render:idle': (opt: Paper.UpdateViewsAsyncOptions) => void;
+            // paper
+            'paper:mouseenter': (evt: dia.Event) => void;
+            'paper:mouseleave': (evt: dia.Event) => void;
             // transformations
             'translate': (tx: number, ty: number, data: unknown) => void;
             'scale': (sx: number, sy: number, data: unknown) => void;
@@ -1857,6 +1920,8 @@ export namespace dia {
             [eventName: string]: mvc.EventHandler;
         }
 
+        type DefinedEventMap = ExcludeIndexSignature<EventMap>;
+
         interface BufferOptions {
             /**
              * A buffer around the area to extend the search to
@@ -2147,9 +2212,21 @@ export namespace dia {
 
         // events
 
-        on<T extends keyof Paper.EventMap = keyof Paper.EventMap>(eventName: T, callback: Paper.EventMap[T], context?: any): this;
-
-        on<T extends keyof Paper.EventMap = keyof Paper.EventMap>(events: { [eventName in T]: Paper.EventMap[eventName]; }, context?: any): this;
+        on<T extends keyof Paper.DefinedEventMap>(
+            eventName: T,
+            callback: Paper.DefinedEventMap[T],
+            context?: any
+        ): this;
+        on(
+            eventName: LiteralUnion<keyof Paper.DefinedEventMap>,
+            callback: mvc.EventHandler,
+            context?: any
+        ): this;
+
+        on<E extends mvc.EventCallbackMap<Paper.DefinedEventMap>>(
+            events: E,
+            context?: any
+        ): this;
 
         // protected
 
@@ -3565,6 +3642,12 @@ export namespace mvc {
         [event: string]: EventHandler;
     }
 
+    /**
+     * A partial map of known event callbacks, plus any custom string events.
+     * Use with a DefinedEventMap to get autocomplete for known events.
+     */
+    type EventCallbackMap<T> = Partial<T> & { [key: string]: EventHandler };
+
     const Events: Events;
     interface Events extends EventsMixin {}