feat: add type declarations for core components

index.d.ts

@@ -0,0 +1 @@
+export { default } from './lib/Diagram';

lib/Diagram.d.ts

@@ -0,0 +1,89 @@
+import {
+  InjectionContext,
+  Injector,
+  LocalsMap,
+  ModuleDeclaration
+} from 'didi';
+
+export type DiagramOptions = {
+  modules: ModuleDeclaration[]
+}
+
+/**
+ * The main diagram-js entry point that bootstraps the diagram with the given
+ * configuration.
+ *
+ * To register extensions with the diagram, pass them as Array<Module> to the constructor.
+ *
+ * @example
+ *
+ * <caption>Creating a plug-in that logs whenever a shape is added to the canvas.</caption>
+ *
+ * // plug-in implemenentation
+ * function MyLoggingPlugin(eventBus) {
+ *   eventBus.on('shape.added', function(event) {
+ *     console.log('shape ', event.shape, ' was added to the diagram');
+ *   });
+ * }
+ *
+ * // export as module
+ * export default {
+ *   __init__: [ 'myLoggingPlugin' ],
+ *     myLoggingPlugin: [ 'type', MyLoggingPlugin ]
+ * };
+ *
+ *
+ * // instantiate the diagram with the new plug-in
+ *
+ * import MyLoggingModule from 'path-to-my-logging-plugin';
+ *
+ * var diagram = new Diagram({
+ *   modules: [
+ *     MyLoggingModule
+ *   ]
+ * });
+ *
+ * diagram.invoke([ 'canvas', function(canvas) {
+ *   // add shape to drawing canvas
+ *   canvas.addShape({ x: 10, y: 10 });
+ * });
+ *
+ * // 'shape ... was added to the diagram' logged to console
+ *
+ * @param options
+ * @param injector An (optional) injector to bootstrap the diagram with.
+ */
+export default class Diagram {
+  constructor(options: DiagramOptions, injector?: Injector);
+
+  /**
+   * Resolves a diagram service.
+   *
+   * @method Diagram#get
+   *
+   * @param name The name of the service to get.
+   * @param strict If false, resolve missing services to null.
+   */
+  get<T>(name: string, strict?: boolean): T;
+
+  /**
+   * Executes a function with its dependencies injected.
+   *
+   * @method Diagram#invoke
+   *
+   * @param fn The function to be executed.
+   * @param context The context.
+   * @param locals The locals.
+   */
+  invoke<T>(fn: (...args: any[]) => T, context?: InjectionContext, locals?: LocalsMap): T;
+
+  /**
+   * Destroys the diagram
+   */
+  destroy(): void;
+
+  /**
+   * Clear the diagram, removing all contents.
+   */
+  clear(): void;
+}

lib/Diagram.js

@@ -3,13 +3,17 @@ import { Injector } from 'didi';
 import CoreModule from './core';
 
 /**
- * @typedef { import('didi').ModuleDeclaration } Module
+ * @typedef {import('didi').InjectionContext} InjectionContext
+ * @typedef {import('didi').LocalsMap} LocalsMap
+ * @typedef {import('didi').ModuleDeclaration} ModuleDeclaration
+ *
+ * @typedef {import('./Diagram').DiagramOptions} DiagramOptions
  */
 
 /**
  * Bootstrap an injector from a list of modules, instantiating a number of default components
  *
- * @param {Array<Module>} modules
+ * @param {ModuleDeclaration[]} modules
  *
  * @return {Injector} a injector to use to access the components
  */
@@ -24,7 +28,8 @@ function bootstrap(modules) {
 /**
  * Creates an injector from passed options.
  *
- * @param {Object} options
+ * @param {DiagramOptions} options
+ *
  * @return {Injector}
  */
 function createInjector(options) {
@@ -47,8 +52,7 @@ function createInjector(options) {
  *
  * To register extensions with the diagram, pass them as Array<Module> to the constructor.
  *
- * @class djs.Diagram
- * @memberOf djs
+ * @class
  * @constructor
  *
  * @example
@@ -86,9 +90,9 @@ function createInjector(options) {
  *
  * // 'shape ... was added to the diagram' logged to console
  *
- * @param {Object} options
- * @param {Array<Module>} [options.modules] external modules to instantiate with the diagram
- * @param {Injector} [injector] an (optional) injector to bootstrap the diagram with
+ * @param {DiagramOptions} options
+ * @param {ModuleDeclaration[]} [options.modules] External modules to instantiate with the diagram.
+ * @param {Injector} [injector] An (optional) injector to bootstrap the diagram with.
  */
 export default function Diagram(options, injector) {
 
@@ -98,22 +102,23 @@ export default function Diagram(options, injector) {
   // API
 
   /**
-   * Resolves a diagram service
+   * Resolves a diagram service.
    *
    * @method Diagram#get
    *
-   * @param {string} name the name of the diagram service to be retrieved
-   * @param {boolean} [strict=true] if false, resolve missing services to null
+   * @param {string} name The name of the service to get.
+   * @param {boolean} [strict=true] If false, resolve missing services to null.
    */
   this.get = injector.get;
 
   /**
-   * Executes a function into which diagram services are injected
+   * Executes a function with its dependencies injected.
    *
    * @method Diagram#invoke
    *
-   * @param {Function|Object[]} fn the function to resolve
-   * @param {Object} locals a number of locals to use to resolve certain dependencies
+   * @param {Function} fn The function to be executed.
+   * @param {InjectionContext} [context] The context.
+   * @param {LocalsMap} [locals] The locals.
    */
   this.invoke = injector.invoke;
 

lib/Diagram.spec.ts

@@ -0,0 +1,31 @@
+import Diagram from './Diagram';
+
+import CommandModule from './command';
+
+import CoreModule from './core';
+import EventBus from './core/EventBus';
+
+import ModelingModule from './features/modeling';
+import Modeling from './features/modeling/Modeling';
+
+const diagram = new Diagram({
+  modules: [
+    CoreModule,
+    CommandModule,
+    ModelingModule
+  ]
+});
+
+diagram.clear();
+
+diagram.destroy();
+
+diagram.invoke((eventBus: EventBus) => eventBus.fire('foo'));
+
+const foo = diagram.invoke((modeling: Modeling, eventBus: EventBus) => {
+  return {
+    bar: true
+  };
+});
+
+foo.bar = false;

lib/command/CommandHandler.d.ts

@@ -0,0 +1,55 @@
+import { ElementLike } from '../core';
+
+import CommandStack from './CommandStack';
+
+import { CommandContext } from './CommandStack';
+
+/**
+ * A command handler that may be registered via
+ * {@link CommandStack#registerHandler}.
+ */
+export default interface CommandHandler {
+
+  /**
+   * Execute changes described in the passed action context.
+   *
+   * @param context The execution context.
+   *
+   * @return The list of diagram elements that have changed.
+   */
+  execute?(context: CommandContext): ElementLike[];
+
+  /**
+   * Revert changes described in the passed action context.
+   *
+   * @param context The execution context.
+   *
+   * @return The list of diagram elements that have changed.
+   */
+  revert?(context: CommandContext): ElementLike[];
+
+  /**
+   * Return true if the handler may execute in the given context.
+   *
+   * @param context The execution context.
+   *
+   * @return Whether the command can be executed.
+   */
+  canExecute?(context: CommandContext): boolean;
+
+  /**
+   * Execute actions before the actual command execution but
+   * grouped together (for undo/redo) with the action.
+   *
+   * @param context The execution context.
+   */
+  preExecute?(context: CommandContext): void;
+
+  /**
+   * Execute actions after the actual command execution but
+   * grouped together (for undo/redo) with the action.
+   *
+   * @param context The execution context.
+   */
+  postExecute?(context: CommandContext): void;
+}

lib/command/CommandHandler.js

@@ -1,38 +1,46 @@
 /**
- * A command handler that may be registered with the
- * {@link CommandStack} via {@link CommandStack#registerHandler}.
+ * @typedef {import('../core').ElementLike} ElementLike
+ *
+ * @typedef {import('./CommandStack').default} CommandStack
+ * @typedef {import('./CommandStack').CommandContext} CommandContext
+ */
+
+/**
+ *A command handler that may be registered via
+ * {@link CommandStack#registerHandler}.
+ *
+ * @class
+ * @constructor
  */
 export default function CommandHandler() {}
 
 
 /**
  * Execute changes described in the passed action context.
  *
- * @param {Object} context the execution context
+ * @param {CommandContext} context The execution context.
  *
- * @return {Array<djs.model.Base>} list of touched (áka dirty) diagram elements
+ * @return {ElementLike[]} The list of diagram elements that have changed.
  */
 CommandHandler.prototype.execute = function(context) {};
 
 
 /**
  * Revert changes described in the passed action context.
  *
- * @param {Object} context the execution context
+ * @param {CommandContext} context The execution context.
  *
- * @return {Array<djs.model.Base>} list of touched (áka dirty) diagram elements
+ * @return {ElementLike[]} The list of diagram elements that have changed.
  */
 CommandHandler.prototype.revert = function(context) {};
 
 
 /**
  * Return true if the handler may execute in the given context.
  *
- * @abstract
- *
- * @param {Object} context the execution context
+ * @param {CommandContext} context The execution context.
  *
- * @return {boolean} true if executing in the context is possible
+ * @return {boolean} Whether the command can be executed.
  */
 CommandHandler.prototype.canExecute = function(context) {
   return true;
@@ -43,14 +51,15 @@ CommandHandler.prototype.canExecute = function(context) {
  * Execute actions before the actual command execution but
  * grouped together (for undo/redo) with the action.
  *
- * @param {Object} context the execution context
+ * @param {CommandContext} context The execution context.
  */
 CommandHandler.prototype.preExecute = function(context) {};
 
+
 /**
  * Execute actions after the actual command execution but
  * grouped together (for undo/redo) with the action.
  *
- * @param {Object} context the execution context
+ * @param {CommandContext} context The execution context.
  */
 CommandHandler.prototype.postExecute = function(context) {};

lib/command/CommandHandler.spec.ts

@@ -0,0 +1,49 @@
+import CommandHandler from '../../lib/command/CommandHandler';
+
+import Canvas from '../../lib/core/Canvas';
+
+export class AddShapeHandler implements CommandHandler {
+  private _canvas: Canvas;
+
+  static $inject = [ 'canvas', 'rules' ];
+
+  constructor(canvas: Canvas) {
+    this._canvas = canvas;
+  }
+
+  execute(context: any) {
+    const {
+      parent,
+      shape
+    } = context;
+
+    this._canvas.addShape(shape, parent);
+
+    return [
+      parent,
+      shape
+    ];
+  }
+
+  revert(context: any) {
+    const {
+      parent,
+      shape
+    } = context;
+
+    this._canvas.removeShape(shape);
+
+    return [
+      parent,
+      shape
+    ];
+  }
+
+  canExecute(context: any): boolean {
+    return true;
+  }
+
+  preExecute(context: any): void {}
+
+  postExecute(context: any): void {}
+}