bpmn-js 12.1.0 → 13.0.0

package/lib/features/modeling/ElementFactory.test.ts

@@ -0,0 +1,133 @@
+import Modeler from '../../Modeler';
+
+import ElementFactory from './ElementFactory';
+
+import {
+  Connection,
+  Label,
+  Root,
+  Shape
+} from '../../model/Types';
+
+const modeler = new Modeler();
+
+const elementFactory = modeler.get<ElementFactory>('elementFactory');
+
+const shape1 = elementFactory.create('shape', {
+  type: 'bpmn:Task',
+  id: 'shape1',
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+});
+
+const shape2 = elementFactory.create('shape', {
+  type: 'bpmn:Task',
+  id: 'shape2',
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+});
+
+const connection = elementFactory.create('connection', {
+  type: 'bpmn:SequenceFlow',
+  id: 'connection',
+  source: shape1,
+  target: shape2,
+  waypoints: []
+});
+
+elementFactory.create('root', {
+  type: 'bpmn:Process',
+  id: 'root'
+});
+
+elementFactory.create('label', {
+  type: 'bpmn:Task',
+  id: 'label'
+});
+
+elementFactory.create('shape', {
+  type: 'bpmn:Task'
+});
+
+elementFactory.create('connection', {
+  type: 'bpmn:SequenceFlow'
+});
+
+elementFactory.create('root', {
+  type: 'bpmn:Process'
+});
+
+elementFactory.create('label', {
+  type: 'bpmn:Task'
+});
+
+elementFactory.create('connection', {
+  type: 'bpmn:Association',
+  associationDirection: 'One'
+});
+
+elementFactory.create('shape', {
+  type: 'bpmn:BoundaryEvent',
+  cancelActivity: true,
+  eventDefinitionType: 'bpmn:ErrorEventDefinition'
+});
+
+elementFactory.create('shape', {
+  type: 'bpmn:Task',
+  isForCompensation: false
+});
+
+elementFactory.create('shape', {
+  type: 'bpmn:Participant',
+  processRef: {}
+});
+
+elementFactory.create('shape', {
+  type: 'bpmn:SubProcess',
+  triggeredByEvent: true
+});
+
+elementFactory.createElement('connection', {
+  type: 'bpmn:SequenceFlow'
+});
+
+elementFactory.createElement('root', {
+  type: 'bpmn:Process'
+});
+
+elementFactory.createElement('shape', {
+  type: 'bpmn:Task'
+});
+
+elementFactory.getDefaultSize(shape1, { type: 'bpmndi:BPMNShape' });
+
+elementFactory.getDefaultSize(connection, { type: 'bpmndi:BPMNEdge' });
+
+elementFactory.createParticipantShape();
+
+elementFactory.createParticipantShape(true);
+
+elementFactory.createParticipantShape({
+  type: 'bpmn:Participant',
+  isExpanded: true
+});
+
+/**
+ * Customization
+ */
+
+type CustomShape = {
+  foo: string;
+} & Shape;
+
+export class CustomElementFactory extends ElementFactory<Connection, Label, Root, CustomShape> {};
+
+const customElementFactory = modeler.get<CustomElementFactory>('elementFactory');
+
+const customShape = customElementFactory.createShape({ foo: 'bar' });
+
+console.log(customShape.foo);

package/lib/features/modeling/Modeling.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The BPMN 2.0 modeling entry point.
+ *
+ *
+ * @extends {BaseModeling<T, U, V, W, X>}
+ *
+ */
+export default class Modeling<T extends import("../../model/Types").Connection = import("../../model/Types").Connection, U extends import("../../model/Types").Element = import("../../model/Types").Element, V extends import("../../model/Types").Label = import("../../model/Types").Label, W extends import("../../model/Types").Parent = import("../../model/Types").Parent, X extends import("../../model/Types").Shape = import("../../model/Types").Shape> extends BaseModeling<T, U, V, W, X> {
+  /**
+   * @param eventBus
+   * @param elementFactory
+   * @param commandStack
+   * @param bpmnRules
+   */
+  constructor(eventBus: EventBus, elementFactory: ElementFactory, commandStack: CommandStack, bpmnRules: BpmnRules);
+
+  getHandlers(): any;
+
+  /**
+   * Update an element's label.
+   *
+   * @param element The element.
+   * @param newLabel The new label.
+   * @param newBounds The optional bounds of the label.
+   * @param hints The optional hints.
+   */
+  updateLabel(element: Element, newLabel: string, newBounds?: Rect, hints?: UpdateLabelHints): void;
+
+  /**
+   * @param source
+   * @param target
+   * @param attrs
+   * @param hints
+   *
+   * @return
+   */
+  connect(source: Element, target: Element, attrs: Partial<Connection>, hints?: ModelingHints): T;
+
+  /**
+   * Update a model element's properties.
+   *
+   * @param element The element.
+   * @param moddleElement The model element.
+   * @param properties The updated properties.
+   */
+  updateModdleProperties(element: Element, moddleElement: ModdleElement, properties: any): void;
+
+  /**
+   * Update an element's properties.
+   *
+   * @param element The element.
+   * @param properties The updated properties.
+   */
+  updateProperties(element: Element, properties: any): void;
+
+  /**
+   * Resize a lane.
+   *
+   * @param laneShape The lane.
+   * @param newBounds The new bounds of the lane.
+   * @param balanced Wether to resize neighboring lanes.
+   */
+  resizeLane(laneShape: Shape, newBounds: Rect, balanced?: boolean): void;
+
+  /**
+   * Add a lane.
+   *
+   * @param targetLaneShape The shape to add the lane to.
+   * @param location The location.
+   *
+   * @return The added lane.
+   */
+  addLane(targetLaneShape: Shape, location: string): Shape;
+
+  /**
+   * Split a lane.
+   *
+   * @param targetLane The lane to split.
+   * @param count The number of lanes to split the lane into. Must not
+   * exceed the number of existing lanes.
+   */
+  splitLane(targetLane: Shape, count: number): void;
+
+  /**
+   * Turn a process into a collaboration.
+   *
+   * @return The root of the collaboration.
+   */
+  makeCollaboration(): Root;
+
+  /**
+   * Transform a collaboration into a process.
+   *
+   * @return The root of the process.
+   */
+  makeProcess(): Root;
+
+  /**
+   * Update the referenced lanes of each flow node.
+   *
+   * @param flowNodeShapes The flow nodes to update.
+   * @param laneShapes The lanes.
+   */
+  updateLaneRefs(flowNodeShapes: Shape[], laneShapes: Shape[]): void;
+
+  /**
+   * Claim an ID.
+   *
+   * @param id The ID to claim.
+   * @param moddleElement The model element the ID is claimed for.
+   */
+  claimId(id: string, moddleElement: ModdleElement): void;
+
+  /**
+   * Unclaim an ID.
+   *
+   * @param id The ID to unclaim.
+   * @param moddleElement The model element the ID is claimed for.
+   */
+  unclaimId(id: string, moddleElement: ModdleElement): void;
+
+  /**
+   * Set the color(s) of one or many elements.
+   *
+   * @param elements The elements to set the color(s) for.
+   * @param colors The color(s) to set.
+   */
+  setColor(elements: Element[], colors: Colors): void;
+}
+
+type BpmnRules = import('../rules/BpmnRules').default;
+type CommandStack = import('diagram-js/lib/command/CommandStack').default;
+type ElementFactory = import('./ElementFactory').default;
+type EventBus = import('diagram-js/lib/core/EventBus').default;
+type ModelingHints = import('diagram-js/lib/features/modeling/Modeling').ModelingHints;
+type Connection = import('../../model/Types').Connection;
+type Element = import('../../model/Types').Element;
+type Label = import('../../model/Types').Label;
+type Parent = import('../../model/Types').Parent;
+type Root = import('../../model/Types').Root;
+type Shape = import('../../model/Types').Shape;
+type ModdleElement = import('../../model/Types').ModdleElement;
+type Rect = import('diagram-js/lib/util/Types').Rect;
+type Colors = import('../../util/Types').Colors;
+
+export type UpdateLabelHints = {
+    removeShape?: boolean;
+};
+
+import BaseModeling from 'diagram-js/lib/features/modeling/Modeling';

package/lib/features/modeling/Modeling.js

@@ -14,9 +14,41 @@ import SetColorHandler from './cmd/SetColorHandler';
 
 import UpdateLabelHandler from '../label-editing/cmd/UpdateLabelHandler';
 
+/**
+ * @typedef {import('../rules/BpmnRules').default} BpmnRules
+ * @typedef {import('diagram-js/lib/command/CommandStack').default} CommandStack
+ * @typedef {import('./ElementFactory').default} ElementFactory
+ * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+ *
+ * @typedef {import('diagram-js/lib/features/modeling/Modeling').ModelingHints} ModelingHints
+ *
+ * @typedef {import('../../model/Types').Connection} Connection
+ * @typedef {import('../../model/Types').Element} Element
+ * @typedef {import('../../model/Types').Label} Label
+ * @typedef {import('../../model/Types').Parent} Parent
+ * @typedef {import('../../model/Types').Root} Root
+ * @typedef {import('../../model/Types').Shape} Shape
+ * @typedef {import('../../model/Types').ModdleElement} ModdleElement
+ *
+ * @typedef {import('diagram-js/lib/util/Types').Rect} Rect
+ *
+ * @typedef {import('../../util/Types').Colors} Colors
+ *
+ * @typedef { {
+ *   removeShape?: boolean;
+ * } } UpdateLabelHints
+ */
 
 /**
- * BPMN 2.0 modeling features activator
+ * The BPMN 2.0 modeling entry point.
+ *
+ * @template {Connection} [T=Connection]
+ * @template {Element} [U=Element]
+ * @template {Label} [V=Label]
+ * @template {Parent} [W=Parent]
+ * @template {Shape} [X=Shape]
+ *
+ * @extends {BaseModeling<T, U, V, W, X>}
  *
  * @param {EventBus} eventBus
  * @param {ElementFactory} elementFactory
@@ -24,8 +56,11 @@ import UpdateLabelHandler from '../label-editing/cmd/UpdateLabelHandler';
  * @param {BpmnRules} bpmnRules
  */
 export default function Modeling(
-    eventBus, elementFactory, commandStack,
-    bpmnRules) {
+    eventBus,
+    elementFactory,
+    commandStack,
+    bpmnRules
+) {
 
   BaseModeling.call(this, eventBus, elementFactory, commandStack);
 
@@ -59,7 +94,14 @@ Modeling.prototype.getHandlers = function() {
   return handlers;
 };
 
-
+/**
+ * Update an element's label.
+ *
+ * @param {Element} element The element.
+ * @param {string} newLabel The new label.
+ * @param {Rect} [newBounds] The optional bounds of the label.
+ * @param {UpdateLabelHints} [hints] The optional hints.
+ */
 Modeling.prototype.updateLabel = function(element, newLabel, newBounds, hints) {
   this._commandStack.execute('element.updateLabel', {
     element: element,
@@ -69,7 +111,14 @@ Modeling.prototype.updateLabel = function(element, newLabel, newBounds, hints) {
   });
 };
 
-
+/**
+ * @param {Element} source
+ * @param {Element} target
+ * @param {Partial<Connection>} attrs
+ * @param {ModelingHints} [hints]
+ *
+ * @return {T}
+ */
 Modeling.prototype.connect = function(source, target, attrs, hints) {
 
   var bpmnRules = this._bpmnRules;
@@ -85,7 +134,13 @@ Modeling.prototype.connect = function(source, target, attrs, hints) {
   return this.createConnection(source, target, attrs, source.parent, hints);
 };
 
-
+/**
+ * Update a model element's properties.
+ *
+ * @param {Element} element The element.
+ * @param {ModdleElement} moddleElement The model element.
+ * @param {Object} properties The updated properties.
+ */
 Modeling.prototype.updateModdleProperties = function(element, moddleElement, properties) {
   this._commandStack.execute('element.updateModdleProperties', {
     element: element,
@@ -94,6 +149,12 @@ Modeling.prototype.updateModdleProperties = function(element, moddleElement, pro
   });
 };
 
+/**
+ * Update an element's properties.
+ *
+ * @param {Element} element The element.
+ * @param {Object} properties The updated properties.
+ */
 Modeling.prototype.updateProperties = function(element, properties) {
   this._commandStack.execute('element.updateProperties', {
     element: element,
@@ -101,6 +162,13 @@ Modeling.prototype.updateProperties = function(element, properties) {
   });
 };
 
+/**
+ * Resize a lane.
+ *
+ * @param {Shape} laneShape The lane.
+ * @param {Rect} newBounds The new bounds of the lane.
+ * @param {boolean} [balanced] Wether to resize neighboring lanes.
+ */
 Modeling.prototype.resizeLane = function(laneShape, newBounds, balanced) {
   this._commandStack.execute('lane.resize', {
     shape: laneShape,
@@ -109,6 +177,14 @@ Modeling.prototype.resizeLane = function(laneShape, newBounds, balanced) {
   });
 };
 
+/**
+ * Add a lane.
+ *
+ * @param {Shape} targetLaneShape The shape to add the lane to.
+ * @param {string} location The location.
+ *
+ * @return {Shape} The added lane.
+ */
 Modeling.prototype.addLane = function(targetLaneShape, location) {
   var context = {
     shape: targetLaneShape,
@@ -120,6 +196,13 @@ Modeling.prototype.addLane = function(targetLaneShape, location) {
   return context.newLane;
 };
 
+/**
+ * Split a lane.
+ *
+ * @param {Shape} targetLane The lane to split.
+ * @param {number} count The number of lanes to split the lane into. Must not
+ * exceed the number of existing lanes.
+ */
 Modeling.prototype.splitLane = function(targetLane, count) {
   this._commandStack.execute('lane.split', {
     shape: targetLane,
@@ -128,9 +211,9 @@ Modeling.prototype.splitLane = function(targetLane, count) {
 };
 
 /**
- * Transform the current diagram into a collaboration.
+ * Turn a process into a collaboration.
  *
- * @return {djs.model.Root} the new root element
+ * @return {Root} The root of the collaboration.
  */
 Modeling.prototype.makeCollaboration = function() {
 
@@ -147,18 +230,10 @@ Modeling.prototype.makeCollaboration = function() {
   return collaborationElement;
 };
 
-Modeling.prototype.updateLaneRefs = function(flowNodeShapes, laneShapes) {
-
-  this._commandStack.execute('lane.updateRefs', {
-    flowNodeShapes: flowNodeShapes,
-    laneShapes: laneShapes
-  });
-};
-
 /**
- * Transform the current diagram into a process.
+ * Transform a collaboration into a process.
  *
- * @return {djs.model.Root} the new root element
+ * @return {Root} The root of the process.
  */
 Modeling.prototype.makeProcess = function() {
 
@@ -173,7 +248,26 @@ Modeling.prototype.makeProcess = function() {
   this._commandStack.execute('canvas.updateRoot', context);
 };
 
+/**
+ * Update the referenced lanes of each flow node.
+ *
+ * @param {Shape[]} flowNodeShapes The flow nodes to update.
+ * @param {Shape[]} laneShapes The lanes.
+ */
+Modeling.prototype.updateLaneRefs = function(flowNodeShapes, laneShapes) {
 
+  this._commandStack.execute('lane.updateRefs', {
+    flowNodeShapes: flowNodeShapes,
+    laneShapes: laneShapes
+  });
+};
+
+/**
+ * Claim an ID.
+ *
+ * @param {string} id The ID to claim.
+ * @param {ModdleElement} moddleElement The model element the ID is claimed for.
+ */
 Modeling.prototype.claimId = function(id, moddleElement) {
   this._commandStack.execute('id.updateClaim', {
     id: id,
@@ -182,7 +276,12 @@ Modeling.prototype.claimId = function(id, moddleElement) {
   });
 };
 
-
+/**
+ * Unclaim an ID.
+ *
+ * @param {string} id The ID to unclaim.
+ * @param {ModdleElement} moddleElement The model element the ID is claimed for.
+ */
 Modeling.prototype.unclaimId = function(id, moddleElement) {
   this._commandStack.execute('id.updateClaim', {
     id: id,
@@ -190,6 +289,12 @@ Modeling.prototype.unclaimId = function(id, moddleElement) {
   });
 };
 
+/**
+ * Set the color(s) of one or many elements.
+ *
+ * @param {Element[]} elements The elements to set the color(s) for.
+ * @param {Colors} colors The color(s) to set.
+ */
 Modeling.prototype.setColor = function(elements, colors) {
   if (!elements.length) {
     elements = [ elements ];

package/lib/features/modeling/Modeling.test.ts

@@ -0,0 +1,148 @@
+import { expectType } from 'ts-expect';
+
+import Modeler from '../../Modeler';
+
+import {
+  Connection,
+  Element,
+  Label,
+  Parent,
+  Shape
+} from '../../model/Types';
+
+import ElementFactory from './ElementFactory';
+import Modeling from './Modeling';
+
+import { getBusinessObject } from '../../util/ModelUtil';
+
+import { CustomElementFactory } from './ElementFactory.test';
+
+const modeler = new Modeler();
+
+const elementFactory = modeler.get<ElementFactory>('elementFactory');
+
+const sequenceFlow = elementFactory.create('connection', { type: 'bpmn:SequenceFlow' }),
+      process = elementFactory.create('root', { type: 'bpmn:Process' }),
+      subProcess = elementFactory.create('shape', { type: 'bpmn:SubProcess' }),
+      task = elementFactory.create('shape', { type: 'bpmn:Task' });
+
+const modeling = modeler.get<Modeling>('modeling');
+
+modeling.updateLabel(task, 'foo');
+
+modeling.updateLabel(task, 'foo', {
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+});
+
+modeling.updateLabel(task, 'foo', {
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+}, { removeShape: true });
+
+modeling.connect(subProcess, task, sequenceFlow);
+
+modeling.connect(subProcess, task, sequenceFlow, { foo: 'bar' });
+
+modeling.updateModdleProperties(task, { type: 'bpmn:ExtensionElements' }, {
+  values: []
+});
+
+modeling.updateProperties(task, {
+  name: 'foo'
+});
+
+const participant = elementFactory.create('shape', { type: 'bpmn:Participant'}),
+      lane = elementFactory.create('shape', { type: 'bpmn:Lane'});
+
+modeling.resizeLane(lane, {
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+});
+
+modeling.resizeLane(lane, {
+  x: 100,
+  y: 100,
+  width: 100,
+  height: 100
+}, true);
+
+modeling.addLane(participant, 'top');
+
+modeling.addLane(participant, 'bottom');
+
+modeling.splitLane(lane, 3);
+
+modeling.makeCollaboration();
+
+modeling.makeProcess();
+
+modeling.updateLaneRefs([ task ], [ lane ]);
+
+modeling.claimId('foo', task.businessObject);
+
+modeling.unclaimId('foo', task.businessObject);
+
+modeling.setColor([ task ], { fill: 'red', stroke: 'green' });
+
+modeling.setColor([ task ], { fill: 'red' });
+
+modeling.setColor([ task ], { stroke: 'green' });
+
+/**
+ * Integration
+ */
+
+expectType<Connection>(modeling.createConnection(subProcess, task, sequenceFlow, process));
+
+expectType<Label>(modeling.createLabel(task, { x: 100, y: 100 }, {
+  businessObject: getBusinessObject(task)
+}));
+
+expectType<Shape>(modeling.createShape(task, { x: 100, y: 100 }, process));
+
+expectType<Element[]>(modeling.createElements([
+  subProcess,
+  task,
+  sequenceFlow
+], { x: 100, y: 100 }, process));
+
+modeling.moveShape(task, { x: 100, y: 100 });
+
+modeling.moveConnection(sequenceFlow, { x: 100, y: 100 });
+
+modeling.moveElements([ subProcess, task ], { x: 100, y: 100 });
+
+/**
+ * Customization
+ */
+
+type CustomElement = {
+  foo: string;
+} & Element;
+
+type CustomShape = {
+  bar: string;
+} & Shape & CustomElement;
+
+class CustomModeling extends Modeling<Connection, CustomElement, Label, Parent, CustomShape> {};
+
+const customModeling = modeler.get<CustomModeling>('modeling');
+
+const customShape = customModeling.createShape({ bar: 'bar' }, { x: 100, y: 100 }, modeler.get<CustomElementFactory>('elementFactory').create('root'));
+
+customModeling.distributeElements([
+  {
+    elements: [ customShape ],
+    range: {
+      min: 100,
+      max: 200
+    }
+  }
+], 'x', 'width');

package/lib/features/modeling/behavior/AdaptiveLabelPositioningBehavior.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A component that makes sure that external labels are added
+ * together with respective elements and properly updated (DI wise)
+ * during move.
+ *
+ */
+export default class AdaptiveLabelPositioningBehavior extends CommandInterceptor {
+    /**
+     * @param eventBus
+     * @param modeling
+     */
+    constructor(eventBus: EventBus, modeling: Modeling);
+}
+
+type EventBus = import('diagram-js/lib/core/EventBus').default;
+type Modeling = import('../Modeling').default;
+type Element = import('../../../model/Types').Element;
+type Shape = import('../../../model/Types').Shape;
+type DirectionTRBL = import('diagram-js/lib/util/Types').DirectionTRBL;
+import CommandInterceptor from 'diagram-js/lib/command/CommandInterceptor';