@m2c2kit/addons 0.3.12 → 0.3.14

package/dist/index.js

@@ -1,12 +1,12 @@
-import { Composite, WebColors, Shape, Label, CanvasKitHelpers, EventType, MutablePath, Easings, Story, Transition, TransitionDirection, LabelHorizontalAlignmentMode, Scene, Dimensions, Sprite } from '@m2c2kit/core';
+import { Composite, WebColors, Shape, Label, CanvasKitHelpers, M2EventType, MutablePath, Easings, Story, Transition, TransitionDirection, LabelHorizontalAlignmentMode, Scene, Dimensions, Sprite, Action } from '@m2c2kit/core';
 
 class Grid extends Composite {
   /**
-   * A rectangular grid that supports placement of entities within the grid's
+   * A rectangular grid that supports placement of nodes within the grid's
    * cells.
    *
-   * @remarks This composite entity is composed of rectangles and lines. It
-   * has convenience functions for placing and clearing entities on the grid
+   * @remarks This composite node is composed of rectangles and lines. It
+   * has convenience functions for placing and clearing nodes on the grid
    * by row and column position (zero-based indexing)
    *
    * @param options - {@link GridOptions}
@@ -102,11 +102,11 @@ class Grid extends Composite {
         }
         const x = -this.size.width / 2 + this.cellWidth / 2 + gridChild.column * this.cellWidth;
         const y = -this.size.height / 2 + this.cellHeight / 2 + gridChild.row * this.cellHeight;
-        gridChild.entity.position = {
-          x: x + gridChild.entity.position.x,
-          y: y + gridChild.entity.position.y
+        gridChild.node.position = {
+          x: x + gridChild.node.position.x,
+          y: y + gridChild.node.position.y
         };
-        this.gridBackground.addChild(gridChild.entity);
+        this.gridBackground.addChild(gridChild.node);
       });
     }
     this.needsInitialization = false;
@@ -120,24 +120,24 @@ class Grid extends Composite {
   set gridBackground(gridBackground) {
     this._gridBackground = gridBackground;
   }
-  // all entities that make up grid are added as children, so they
+  // all nodes that make up grid are added as children, so they
   // have their own dispose methods
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   dispose() {
   }
   /**
-   * Duplicates an entity using deep copy.
+   * Duplicates a node using deep copy.
    *
-   * @remarks This is a deep recursive clone (entity and children).
-   * The uuid property of all duplicated entities will be newly created,
+   * @remarks This is a deep recursive clone (node and children).
+   * The uuid property of all duplicated nodes will be newly created,
    * because uuid must be unique.
    *
-   * @param newName - optional name of the new, duplicated entity. If not
+   * @param newName - optional name of the new, duplicated node. If not
    * provided, name will be the new uuid
    */
   duplicate(newName) {
     const dest = new Grid({
-      ...this.getEntityOptions(),
+      ...this.getNodeOptions(),
       ...this.getDrawableOptions(),
       rows: this.rows,
       columns: this.columns,
@@ -168,8 +168,8 @@ class Grid extends Composite {
       child.warmup(canvas);
     });
   }
-  // override Entity.RemoveAllChildren() so that when RemoveAllChildren() is called on a Grid,
-  // it removes only entities added to the grid cells (what we call grid children), not the grid lines!
+  // override M2Node.RemoveAllChildren() so that when RemoveAllChildren() is called on a Grid,
+  // it removes only nodes added to the grid cells (what we call grid children), not the grid lines!
   /**
    * Removes all children from the grid, but retains grid lines.
    */
@@ -180,29 +180,29 @@ class Grid extends Composite {
     while (this.gridChildren.length) {
       const gridChild = this.gridChildren.pop();
       if (gridChild) {
-        this.gridBackground.removeChild(gridChild.entity);
+        this.gridBackground.removeChild(gridChild.node);
       }
     }
     this.needsInitialization = true;
   }
   /**
-   * Adds an entity to the grid at the specified row and column position.
+   * Adds a node to the grid at the specified row and column position.
    *
-   * @param entity - entity to add to the grid
-   * @param row  - row position within grid to add entity; zero-based indexing
-   * @param column - column position within grid to add entity; zero-based indexing
+   * @param node - node to add to the grid
+   * @param row  - row position within grid to add node; zero-based indexing
+   * @param column - column position within grid to add node; zero-based indexing
    */
-  addAtCell(entity, row, column) {
+  addAtCell(node, row, column) {
     if (row < 0 || row >= this.rows || column < 0 || column >= this.columns) {
       console.warn(
-        `warning: addAtCell() requested to add entity at row ${row}, column ${column}. This is outside the bounds of grid ${this.name}, which is size ${this.rows}x${this.columns}. Note that addAtCell() uses zero-based indexing. AddAtCell() will proceed, but may draw entities outside the grid`
+        `warning: addAtCell() requested to add node at row ${row}, column ${column}. This is outside the bounds of grid ${this.name}, which is size ${this.rows}x${this.columns}. Note that addAtCell() uses zero-based indexing. AddAtCell() will proceed, but may draw nodes outside the grid`
       );
     }
-    this.gridChildren.push({ entity, row, column });
+    this.gridChildren.push({ node, row, column });
     this.needsInitialization = true;
   }
   /**
-   * Removes all child entities at the specified row and column position.
+   * Removes all child nodes at the specified row and column position.
    *
    * @param row - row position within grid at which to remove children; zero-based indexing
    * @param column - column position within grid at which to remove children; zero-based indexing
@@ -215,24 +215,24 @@ class Grid extends Composite {
       return;
     }
     this.gridBackground.removeChildren(
-      gridChildrenToRemove.map((gridChild) => gridChild.entity)
+      gridChildrenToRemove.map((gridChild) => gridChild.node)
     );
     this.gridChildren = this.gridChildren.filter(
       (gridChild) => gridChild.row !== row && gridChild.column !== column
     );
     this.needsInitialization = true;
   }
-  // override Entity.RemoveChild() so that when RemoveChild() is called on a Grid, it removes the
-  // entity from the gridBackground rectangle AND our grid's own list of children (in gridChildren)
+  // override M2Node.RemoveChild() so that when RemoveChild() is called on a Grid, it removes the
+  // node from the gridBackground rectangle AND our grid's own list of children (in gridChildren)
   /**
-   * Removes the child entity from the grid.
+   * Removes the child node from the grid.
    *
-   * @param entity - entity to remove
+   * @param node - node to remove
    */
-  removeChild(entity) {
-    this.gridBackground.removeChild(entity);
+  removeChild(node) {
+    this.gridBackground.removeChild(node);
     this.gridChildren = this.gridChildren.filter(
-      (gridChild) => gridChild.entity != entity
+      (gridChild) => gridChild.node != node
     );
     this.needsInitialization = true;
   }
@@ -244,7 +244,7 @@ class Button extends Composite {
   /**
    * A simple button of rectangle with text centered inside.
    *
-   * @remarks This composite entity is composed of a rectangle and text. To
+   * @remarks This composite node is composed of a rectangle and text. To
    * respond to user taps, the isUserInteractionEnabled property must be set
    * to true and an appropriate callback must be set to handle the tap event.
    *
@@ -258,7 +258,7 @@ class Button extends Composite {
     this.size = { width: 200, height: 50 };
     this.cornerRadius = 9;
     this.fontSize = 20;
-    this.text = "";
+    this._text = "";
     this._fontColor = WebColors.White;
     if (options.text) {
       this.text = options.text;
@@ -266,10 +266,10 @@ class Button extends Composite {
     if (options.size) {
       this.size = options.size;
     }
-    if (options.cornerRadius) {
+    if (options.cornerRadius !== void 0) {
       this.cornerRadius = options.cornerRadius;
     }
-    if (options.fontSize) {
+    if (options.fontSize !== void 0) {
       this.fontSize = options.fontSize;
     }
     if (options.fontColor) {
@@ -308,6 +308,13 @@ class Button extends Composite {
   dispose() {
     CanvasKitHelpers.Dispose([this.backgroundPaint]);
   }
+  get text() {
+    return this._text;
+  }
+  set text(text) {
+    this._text = text;
+    this.needsInitialization = true;
+  }
   get backgroundColor() {
     return this._backgroundColor;
   }
@@ -323,18 +330,18 @@ class Button extends Composite {
     this.needsInitialization = true;
   }
   /**
-   * Duplicates an entity using deep copy.
+   * Duplicates a node using deep copy.
    *
-   * @remarks This is a deep recursive clone (entity and children).
-   * The uuid property of all duplicated entities will be newly created,
+   * @remarks This is a deep recursive clone (node and children).
+   * The uuid property of all duplicated nodes will be newly created,
    * because uuid must be unique.
    *
-   * @param newName - optional name of the new, duplicated entity. If not
+   * @param newName - optional name of the new, duplicated node. If not
    * provided, name will be the new uuid
    */
   duplicate(newName) {
     const dest = new Button({
-      ...this.getEntityOptions(),
+      ...this.getNodeOptions(),
       ...this.getDrawableOptions(),
       ...this.getTextOptions(),
       size: this.size,
@@ -377,7 +384,7 @@ class Dialog extends Composite {
   // todo: add default "behaviors" (?) like button click animation?
   constructor(options) {
     super(options);
-    this.compositeType = "dialog";
+    this.compositeType = "Dialog";
     this._backgroundColor = WebColors.White;
     this.cornerRadius = 9;
     this.overlayAlpha = 0.5;
@@ -418,15 +425,16 @@ class Dialog extends Composite {
   show() {
     this.hidden = false;
   }
-  onDialogResult(callback, replaceExistingCallback = true) {
+  onDialogResult(callback, options) {
     const eventListener = {
-      type: EventType.CompositeCustom,
-      entityUuid: this.uuid,
+      type: M2EventType.CompositeCustom,
+      compositeType: "DialogResult",
+      nodeUuid: this.uuid,
       callback
     };
-    if (replaceExistingCallback) {
+    if (options?.replaceExisting) {
       this.eventListeners = this.eventListeners.filter(
-        (listener) => !(listener.entityUuid === eventListener.entityUuid && listener.type === eventListener.type)
+        (listener) => !(listener.nodeUuid === eventListener.nodeUuid && listener.type === eventListener.type)
       );
     }
     this.eventListeners.push(eventListener);
@@ -448,9 +456,9 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
           const dialogEvent = {
-            type: EventType.CompositeCustom,
+            type: M2EventType.CompositeCustom,
             target: this,
             handled: false,
             dialogResult: "Dismiss" /* Dismiss */
@@ -496,9 +504,9 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
           const dialogEvent = {
-            type: EventType.CompositeCustom,
+            type: M2EventType.CompositeCustom,
             target: this,
             handled: false,
             dialogResult: "Negative" /* Negative */
@@ -518,9 +526,9 @@ class Dialog extends Composite {
       e.handled = true;
       this.hidden = true;
       if (this.eventListeners.length > 0) {
-        this.eventListeners.filter((listener) => listener.type === EventType.CompositeCustom).forEach((listener) => {
+        this.eventListeners.filter((listener) => listener.type === M2EventType.CompositeCustom).forEach((listener) => {
           const dialogEvent = {
-            type: EventType.CompositeCustom,
+            type: M2EventType.CompositeCustom,
             target: this,
             handled: false,
             dialogResult: "Positive" /* Positive */
@@ -548,13 +556,13 @@ class Dialog extends Composite {
     this.needsInitialization = true;
   }
   /**
-   * Duplicates an entity using deep copy.
+   * Duplicates a node using deep copy.
    *
-   * @remarks This is a deep recursive clone (entity and children).
-   * The uuid property of all duplicated entities will be newly created,
+   * @remarks This is a deep recursive clone (node and children).
+   * The uuid property of all duplicated nodes will be newly created,
    * because uuid must be unique.
    *
-   * @param newName - optional name of the new, duplicated entity. If not
+   * @param newName - optional name of the new, duplicated node. If not
    * provided, name will be the new uuid
    */
   duplicate(newName) {
@@ -587,7 +595,7 @@ class DrawPad extends Composite {
   /**
    * A rectangular area on which the user can draw strokes (lines).
    *
-   * @remarks This composite entity is composed of a rectangle Shape and
+   * @remarks This composite node is composed of a rectangle Shape and
    * another Shape that is formed from a path of points.
    *
    * @param options - {@link DrawPadOptions}
@@ -674,8 +682,8 @@ class DrawPad extends Composite {
       this.drawArea.onTapUpAny(() => {
         this.handleTapUpAny();
       });
-      this.drawArea.onTapLeave(() => {
-        this.handleTapLeave();
+      this.drawArea.onTapLeave((e) => {
+        this.handleTapLeave(e);
       });
     }
     this.drawArea.fillColor = this.backgroundColor;
@@ -687,11 +695,10 @@ class DrawPad extends Composite {
   }
   handleTapDown(e) {
     if (this.isUserInteractionEnabled) {
-      const drawShape = this.drawShape;
-      if (!drawShape) {
-        throw new Error("no draw shape");
+      if (!this.drawShape?.path) {
+        throw new Error("DrawPad.handleTapDown(): no drawShape.path");
       }
-      const path = drawShape.path;
+      const path = this.drawShape.path;
       if (this.continuousDrawingOnly && path.subpaths.length !== 0) {
         const prevPoint = path.subpaths[path.subpaths.length - 1][path.subpaths[path.subpaths.length - 1].length - 1];
         const currentPoint = e.point;
@@ -700,6 +707,7 @@ class DrawPad extends Composite {
           return;
         }
       }
+      this.currentStrokesNotAllowed = false;
       this.isDrawingPointerDown = true;
       path.move(e.point);
       const drawPadEvent = {
@@ -712,13 +720,43 @@ class DrawPad extends Composite {
         {
           type: DrawPadEventType.StrokeStart,
           position: e.point,
-          iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          interpolated: false
         }
       ]);
       this.raiseDrawPadEvent(drawPadEvent);
     }
   }
-  handleTapLeave() {
+  addInterpolatedStrokeMove(point) {
+    const strokeCount = this.strokes.length;
+    const strokeInteractionCount = this.strokes[strokeCount - 1].length;
+    const previousPoint = this.strokes[this.strokes.length - 1][strokeInteractionCount - 1].position;
+    const interpolatedPoint = this.interpolateToDrawPadBorder(
+      point,
+      previousPoint,
+      this.size
+    );
+    if (!this.drawShape?.path) {
+      throw new Error("DrawPad.addInterpolatedStrokeMove(): no drawShape.path");
+    }
+    const path = this.drawShape.path;
+    path.addLine(interpolatedPoint);
+    const drawPadEvent = {
+      type: DrawPadEventType.StrokeMove,
+      target: this,
+      handled: false,
+      position: interpolatedPoint
+    };
+    this.strokes[strokeCount - 1].push({
+      type: DrawPadEventType.StrokeMove,
+      position: interpolatedPoint,
+      iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      interpolated: true
+    });
+    this.raiseDrawPadEvent(drawPadEvent);
+    return interpolatedPoint;
+  }
+  handleTapLeave(e) {
     if (this.currentStrokesNotAllowed) {
       this.isDrawingPointerDown = false;
       return;
@@ -727,6 +765,12 @@ class DrawPad extends Composite {
       this.isDrawingPointerDown = false;
       const strokeCount = this.strokes.length;
       const strokeInteractionCount = this.strokes[strokeCount - 1].length;
+      let pointWasInterpolated = false;
+      let point = e.point;
+      if (!this.isPointWithinDrawPad(e.point, this.size)) {
+        point = this.addInterpolatedStrokeMove(e.point);
+        pointWasInterpolated = true;
+      }
       const drawPadEvent = {
         type: DrawPadEventType.StrokeEnd,
         position: this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
@@ -735,10 +779,12 @@ class DrawPad extends Composite {
       };
       this.strokes[strokeCount - 1].push({
         type: DrawPadEventType.StrokeEnd,
-        position: this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
-        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        position: pointWasInterpolated ? point : this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
+        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        interpolated: pointWasInterpolated
       });
       this.raiseDrawPadEvent(drawPadEvent);
+      this.currentStrokesNotAllowed = true;
     } else {
       this.pointerIsDownAndPointerLeftDrawAreaWhenDown = true;
     }
@@ -762,18 +808,18 @@ class DrawPad extends Composite {
       this.strokes[strokeCount - 1].push({
         type: DrawPadEventType.StrokeEnd,
         position: this.strokes[strokeCount - 1][strokeInteractionCount - 1].position,
-        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        interpolated: false
       });
       this.raiseDrawPadEvent(drawPadEvent);
     }
   }
   handlePointerMove(e) {
     if (this.isUserInteractionEnabled && this.isDrawingPointerDown) {
-      const drawShape = this.drawShape;
-      if (!drawShape) {
-        throw new Error("no draw shape");
+      if (!this.drawShape?.path) {
+        throw new Error("DrawPad.handlePointerMove(): no drawShape.path");
       }
-      const path = drawShape.path;
+      const path = this.drawShape.path;
       if (this.isDrawingPointerDown && !this.pointerIsDownAndPointerLeftDrawAreaWhenDown) {
         path.addLine(e.point);
       }
@@ -791,7 +837,8 @@ class DrawPad extends Composite {
       this.strokes[strokeCount - 1].push({
         type: DrawPadEventType.StrokeMove,
         position: e.point,
-        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        iso8601Timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        interpolated: false
       });
       this.raiseDrawPadEvent(drawPadEvent);
     }
@@ -820,11 +867,10 @@ class DrawPad extends Composite {
    * Removes all strokes from the DrawPad.
    */
   clear() {
-    const drawShape = this.drawShape;
-    if (!drawShape) {
-      throw new Error("no draw shape");
+    if (!this.drawShape?.path) {
+      throw new Error("DrawPad.clear(): no drawShape.path");
     }
-    const path = drawShape.path;
+    const path = this.drawShape.path;
     path.clear();
     this.strokes = new Array();
   }
@@ -874,45 +920,45 @@ class DrawPad extends Composite {
     );
   }
   /**
-   * Adds an entity to the DrawPad.
+   * Adds a node to the DrawPad.
    *
-   * @remarks After the entity is added to the DrawPad, its
+   * @remarks After the node is added to the DrawPad, its
    * position is adjusted to be relative to the DrawPad's coordinate
    * system, and it is made interactive. The method returns an object
-   * which is the entity as a DrawPadItem, which has additional methods,
-   * properties, and events specific to it now being on a DrawPad. The entity
+   * which is the node as a DrawPadItem, which has additional methods,
+   * properties, and events specific to it now being on a DrawPad. The node
    * now **must** be manipulated only using the DrawPadItem object. Using
-   * the original entity object will result in undefined behavior.
+   * the original node object will result in undefined behavior.
    *
-   * @param entity - the entity to add to the DrawPad
-   * @returns the entity as a DrawPadItem
+   * @param node - the node to add to the DrawPad
+   * @returns the node as a DrawPadItem
    */
-  addItem(entity) {
-    Object.defineProperty(entity, "drawPadPosition", {
+  addItem(node) {
+    Object.defineProperty(node, "drawPadPosition", {
       get: function() {
-        const drawPad = entity.parent;
+        const drawPad = node.parent;
         return {
           get x() {
-            return entity.position.x + drawPad.size.width / 2;
+            return node.position.x + drawPad.size.width / 2;
           },
           set x(value) {
-            entity.position.x = value - drawPad.size.width / 2;
+            node.position.x = value - drawPad.size.width / 2;
           },
           get y() {
-            return entity.position.y + drawPad.size.height / 2;
+            return node.position.y + drawPad.size.height / 2;
           },
           set y(value) {
-            entity.position.y = value - drawPad.size.height / 2;
+            node.position.y = value - drawPad.size.height / 2;
           }
         };
       },
       set: function(value) {
-        const drawPad = entity.parent;
-        entity.position.x = value.x - drawPad.size.width / 2;
-        entity.position.y = value.y - drawPad.size.height / 2;
+        const drawPad = node.parent;
+        node.position.x = value.x - drawPad.size.width / 2;
+        node.position.y = value.y - drawPad.size.height / 2;
       }
     });
-    Object.defineProperty(entity, "onStrokeEnter", {
+    Object.defineProperty(node, "onStrokeEnter", {
       value: function(callback, options) {
         this.addEventListener(
           DrawPadItemEventType.StrokeEnter,
@@ -921,7 +967,7 @@ class DrawPad extends Composite {
         );
       }
     });
-    Object.defineProperty(entity, "onStrokeLeave", {
+    Object.defineProperty(node, "onStrokeLeave", {
       value: function(callback, options) {
         this.addEventListener(
           DrawPadItemEventType.StrokeLeave,
@@ -930,62 +976,62 @@ class DrawPad extends Composite {
         );
       }
     });
-    Object.defineProperty(entity, "isStrokeWithinBounds", {
+    Object.defineProperty(node, "isStrokeWithinBounds", {
       value: false,
       writable: true
     });
-    entity.onPointerDown(() => {
+    node.onPointerDown(() => {
       if (this.isDrawingPointerDown) {
-        if (entity.isStrokeWithinBounds === false) {
-          entity.isStrokeWithinBounds = true;
+        if (node.isStrokeWithinBounds === false) {
+          node.isStrokeWithinBounds = true;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeEnter,
-            target: entity
+            target: node
           };
-          this.raiseDrawPadItemEvent(entity, drawPadItemEvent);
+          this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
       }
     });
-    entity.onPointerMove(() => {
+    node.onPointerMove(() => {
       if (this.isDrawingPointerDown) {
-        if (entity.isStrokeWithinBounds === false) {
-          entity.isStrokeWithinBounds = true;
+        if (node.isStrokeWithinBounds === false) {
+          node.isStrokeWithinBounds = true;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeEnter,
-            target: entity
+            target: node
           };
-          this.raiseDrawPadItemEvent(entity, drawPadItemEvent);
+          this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
       }
     });
-    entity.onPointerLeave(() => {
+    node.onPointerLeave(() => {
       if (this.isDrawingPointerDown) {
-        if (entity.isStrokeWithinBounds === true) {
-          entity.isStrokeWithinBounds = false;
+        if (node.isStrokeWithinBounds === true) {
+          node.isStrokeWithinBounds = false;
           const drawPadItemEvent = {
             type: DrawPadItemEventType.StrokeLeave,
-            target: entity
+            target: node
           };
-          this.raiseDrawPadItemEvent(entity, drawPadItemEvent);
+          this.raiseDrawPadItemEvent(node, drawPadItemEvent);
         }
       }
     });
-    entity.onPointerUp(() => {
-      if (entity.isStrokeWithinBounds === true) {
-        entity.isStrokeWithinBounds = false;
+    node.onPointerUp(() => {
+      if (node.isStrokeWithinBounds === true) {
+        node.isStrokeWithinBounds = false;
         const drawPadItemEvent = {
           type: DrawPadItemEventType.StrokeLeave,
-          target: entity
+          target: node
         };
-        this.raiseDrawPadItemEvent(entity, drawPadItemEvent);
+        this.raiseDrawPadItemEvent(node, drawPadItemEvent);
       }
     });
-    this.addChild(entity);
-    entity.zPosition = -1;
-    entity.position.x = entity.position.x - this.size.width / 2;
-    entity.position.y = entity.position.y - this.size.height / 2;
-    entity.isUserInteractionEnabled = true;
-    return entity;
+    this.addChild(node);
+    node.zPosition = -1;
+    node.position.x = node.position.x - this.size.width / 2;
+    node.position.y = node.position.y - this.size.height / 2;
+    node.isUserInteractionEnabled = true;
+    return node;
   }
   /**
    * Takes a screenshot of the DrawPad.
@@ -994,13 +1040,9 @@ class DrawPad extends Composite {
    * PNG format.
    */
   takeScreenshot() {
-    const surface = this.game.surface;
-    if (!surface) {
-      throw new Error("no surface");
-    }
     const drawArea = this.drawArea;
     if (!drawArea) {
-      throw new Error("no draw area");
+      throw new Error("DrawPad.takeScreenshot(): no drawArea");
     }
     const sx = (drawArea.absolutePosition.x - drawArea.size.width / 2) * Globals.canvasScale;
     const sy = (drawArea.absolutePosition.y - drawArea.size.height / 2) * Globals.canvasScale;
@@ -1021,15 +1063,85 @@ class DrawPad extends Composite {
       pixelData.length / sh
     );
     if (!croppedImage) {
-      throw new Error("no cropped image");
+      throw new Error("DrawPad.takeScreenshot(): no croppedImage");
     }
     const bytes = croppedImage.encodeToBytes();
     if (!bytes) {
-      throw new Error("no bytes");
+      throw new Error(
+        "DrawPad.takeScreenshot(): croppedImage.encodeToBytes() failed"
+      );
     }
     croppedImage.delete();
     return this.arrayBufferToBase64String(bytes);
   }
+  /**
+   * Determines whether a point is within the DrawPad.
+   *
+   * @param point - The point to check
+   * @returns True - if the point is within the DrawPad, false otherwise
+   */
+  isPointWithinDrawPad(point, drawPadSize) {
+    return point.x >= 0 && point.x <= drawPadSize.width && point.y >= 0 && point.y <= drawPadSize.height;
+  }
+  /**
+   * Interpolates a point to the border of the DrawPad based on a line that
+   * crosses the DrawPad border. The line is formed by the current "out of
+   * bounds" point the and previous "within bounds" point.
+   *
+   * @param currentPoint - The current point
+   * @param previousPoint - The previous point
+   * @param drawPadSize - The size of the DrawPad
+   * @returns A new point on the border of the DrawPad
+   */
+  interpolateToDrawPadBorder(currentPoint, previousPoint, drawPadSize) {
+    const slope = (currentPoint.y - previousPoint.y) / (currentPoint.x - previousPoint.x);
+    const intercept = currentPoint.y - slope * currentPoint.x;
+    const newPoint = { x: 0, y: 0 };
+    if (!Number.isFinite(slope)) {
+      newPoint.x = currentPoint.x;
+      if (currentPoint.y - previousPoint.y > 0) {
+        newPoint.y = drawPadSize.height;
+        return newPoint;
+      }
+      if (currentPoint.y - previousPoint.y < 0) {
+        newPoint.y = 0;
+        return newPoint;
+      }
+    }
+    const yLeft = slope * 0 + intercept;
+    const yRight = slope * drawPadSize.width + intercept;
+    if (yLeft >= 0 && yLeft <= drawPadSize.height) {
+      if (currentPoint.x - previousPoint.x < 0) {
+        newPoint.x = 0;
+        newPoint.y = yLeft;
+        return newPoint;
+      }
+    }
+    if (yRight >= 0 && yRight <= drawPadSize.height) {
+      if (currentPoint.x - previousPoint.x > 0) {
+        newPoint.x = drawPadSize.width;
+        newPoint.y = yRight;
+        return newPoint;
+      }
+    }
+    const xTop = (0 - intercept) / slope;
+    const xBottom = (drawPadSize.height - intercept) / slope;
+    if (xTop >= 0 && xTop <= drawPadSize.width) {
+      if (currentPoint.y - previousPoint.y < 0) {
+        newPoint.x = xTop;
+        newPoint.y = 0;
+        return newPoint;
+      }
+    }
+    if (xBottom >= 0 && xBottom <= drawPadSize.width) {
+      if (currentPoint.y - previousPoint.y > 0) {
+        newPoint.x = xBottom;
+        newPoint.y = drawPadSize.height;
+        return newPoint;
+      }
+    }
+    return currentPoint;
+  }
   arrayBufferToBase64String(buffer) {
     let binary = "";
     const bytes = new Uint8Array(buffer);
@@ -1074,7 +1186,7 @@ class DrawPad extends Composite {
     this.needsInitialization = true;
   }
   duplicate(newName) {
-    throw new Error("Method not implemented.");
+    throw new Error("DrawPad.duplicate(): Method not implemented.");
   }
 }
 
@@ -1345,10 +1457,10 @@ class VirtualKeyboard extends Composite {
           letterCircle.hidden = true;
           if (this.eventListeners.length > 0) {
             this.eventListeners.filter(
-              (listener) => listener.type === EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyUp"
+              (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyUp"
             ).forEach((listener) => {
               const virtualKeyboardEvent = {
-                type: EventType.CompositeCustom,
+                type: M2EventType.CompositeCustom,
                 target: this,
                 handled: false,
                 key: keyAsString,
@@ -1413,10 +1525,10 @@ class VirtualKeyboard extends Composite {
           }
           if (this.eventListeners.length > 0) {
             this.eventListeners.filter(
-              (listener) => listener.type === EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyDown"
+              (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "VirtualKeyboardKeyDown"
             ).forEach((listener) => {
               const virtualKeyboardEvent = {
-                type: EventType.CompositeCustom,
+                type: M2EventType.CompositeCustom,
                 target: this,
                 handled: false,
                 key: keyAsString,
@@ -1470,50 +1582,36 @@ class VirtualKeyboard extends Composite {
    * Executes a callback when the user presses down on a key.
    *
    * @param callback - function to execute
-   * @param replaceExistingCallback  - should the provided callback replace
-   * any existing callbacks of the same event type on this entity? Usually
-   * there should be only one callback defined, instead of chaining multiple
-   * ones. It is strongly recommended not to change this, unless you have a
-   * special use case. Default is true.
+   * @param options
    */
-  onKeyDown(callback, replaceExistingCallback = true) {
+  onKeyDown(callback, options) {
     const eventListener = {
-      type: EventType.CompositeCustom,
+      type: M2EventType.CompositeCustom,
       compositeType: "VirtualKeyboardKeyDown",
-      entityUuid: this.uuid,
+      nodeUuid: this.uuid,
       callback
     };
-    this.addVirtualKeyboardEventListener(
-      replaceExistingCallback,
-      eventListener
-    );
+    this.addVirtualKeyboardEventListener(eventListener, options);
   }
   /**
    * Executes a callback when the user releases a key.
    *
    * @param callback - function to execute
-   * @param replaceExistingCallback  - should the provided callback replace
-   * any existing callbacks of the same event type on this entity? Usually
-   * there should be only one callback defined, instead of chaining multiple
-   * ones. It is strongly recommended not to change this, unless you have a
-   * special use case. Default is true.
+   * @param options
    */
-  onKeyUp(callback, replaceExistingCallback = true) {
+  onKeyUp(callback, options) {
     const eventListener = {
-      type: EventType.CompositeCustom,
+      type: M2EventType.CompositeCustom,
       compositeType: "VirtualKeyboardKeyUp",
-      entityUuid: this.uuid,
+      nodeUuid: this.uuid,
       callback
     };
-    this.addVirtualKeyboardEventListener(
-      replaceExistingCallback,
-      eventListener
-    );
+    this.addVirtualKeyboardEventListener(eventListener, options);
   }
-  addVirtualKeyboardEventListener(replaceExistingCallback, eventListener) {
-    if (replaceExistingCallback) {
+  addVirtualKeyboardEventListener(eventListener, options) {
+    if (options?.replaceExisting) {
       this.eventListeners = this.eventListeners.filter(
-        (listener) => !(listener.entityUuid === eventListener.entityUuid && listener.type === eventListener.type && listener.compositeType === eventListener.compositeType)
+        (listener) => !(listener.nodeUuid === eventListener.nodeUuid && listener.type === eventListener.type && listener.compositeType === eventListener.compositeType)
       );
     }
     this.eventListeners.push(eventListener);
@@ -1535,27 +1633,27 @@ class VirtualKeyboard extends Composite {
   }
 }
 
-const SCENE_TRANSITION_EASING = Easings.sinusoidalInOut;
+const SCENE_TRANSITION_EASING$1 = Easings.sinusoidalInOut;
 const SCENE_TRANSITION_DURATION = 500;
 class Instructions extends Story {
   /**
-   * Create an array of scenes containing instructions on how to complete the task
+   * Creates an array of scenes containing instructions on how to complete the assessment
    *
    * @param options - {@link InstructionsOptions}
-   * @returns
+   * @returns instruction scenes
    */
-  static Create(options) {
+  static create(options) {
     const scenes = new Array();
     options.instructionScenes.forEach((s, i) => {
       const nextSceneTransition = s.nextSceneTransition ?? options.nextSceneTransition ?? Transition.slide({
         direction: TransitionDirection.Left,
         duration: SCENE_TRANSITION_DURATION,
-        easing: SCENE_TRANSITION_EASING
+        easing: SCENE_TRANSITION_EASING$1
       });
       const backSceneTransition = s.backSceneTransition ?? options.backSceneTransition ?? Transition.slide({
         direction: TransitionDirection.Right,
         duration: SCENE_TRANSITION_DURATION,
-        easing: SCENE_TRANSITION_EASING
+        easing: SCENE_TRANSITION_EASING$1
       });
       const backButtonText = s.backButtonText ?? options.backButtonText ?? "Back";
       const nextButtonText = s.nextButtonText ?? options.nextButtonText ?? "Next";
@@ -1740,9 +1838,150 @@ class Instructions extends Story {
     });
     return scenes;
   }
+  /**
+   * Creates an array of scenes containing instructions on how to complete the assessment
+   *
+   * @deprecated Use {@link Instructions.create} instead (lower case method name "create")
+   *
+   * @param options - {@link InstructionsOptions}
+   * @returns instruction scenes
+   */
+  static Create(options) {
+    return this.create(options);
+  }
+}
+
+const SCENE_TRANSITION_EASING = Easings.sinusoidalInOut;
+const SCENE_TRANSITION_DURATION_MS = 500;
+class CountdownScene extends Scene {
+  /**
+   * A scene that counts down from a specified number to zero, then transitions to the next scene.
+   *
+   * @param options - {@link CountdownSceneOptions}
+   */
+  constructor(options) {
+    super(options);
+    if (options?.transitionDurationMilliseconds !== void 0 && options?.transition) {
+      throw new Error(
+        "Both transition and transitionDurationMilliseconds options were provided. Only one should be provided. If using a custom transition, then the duration of that transition must be specified within the custom transition."
+      );
+    }
+    let timerShape;
+    if (options?.timerShape?.circle === void 0 && options?.timerShape?.rectangle === void 0 || options?.timerShape.circle !== void 0) {
+      timerShape = new Shape({
+        circleOfRadius: options?.timerShape?.circle?.radius ?? 100,
+        layout: {
+          constraints: {
+            topToTopOf: this,
+            bottomToBottomOf: this,
+            startToStartOf: this,
+            endToEndOf: this,
+            verticalBias: options?.timerShape?.verticalBias ?? 0.5
+          }
+        },
+        fillColor: options?.timerShape?.fillColor ?? WebColors.RoyalBlue
+      });
+      this.addChild(timerShape);
+    } else if (options?.timerShape.rectangle !== void 0) {
+      timerShape = new Shape({
+        rect: {
+          width: options?.timerShape?.rectangle?.width ?? 200,
+          height: options?.timerShape?.rectangle?.height ?? 200
+        },
+        cornerRadius: options?.timerShape?.rectangle?.cornerRadius,
+        layout: {
+          constraints: {
+            topToTopOf: this,
+            bottomToBottomOf: this,
+            startToStartOf: this,
+            endToEndOf: this,
+            verticalBias: options?.timerShape?.verticalBias ?? 0.5
+          }
+        },
+        fillColor: options?.timerShape?.fillColor ?? WebColors.RoyalBlue
+      });
+      this.addChild(timerShape);
+    } else {
+      throw new Error("Invalid timer shape options.");
+    }
+    const timerInitialNumber = Math.floor(options.milliseconds / 1e3);
+    const timerNumberLabel = new Label({
+      // Number text will be set in onSetup()
+      text: "",
+      fontSize: options?.timerNumbersFontSize ?? 50,
+      fontName: options?.timerNumbersFontName,
+      fontColor: options?.timerNumbersFontColor ?? WebColors.White
+    });
+    timerShape.addChild(timerNumberLabel);
+    const textLabel = new Label({
+      text: options?.text ?? "GET READY",
+      fontSize: options?.textFontSize ?? 50,
+      fontName: options?.textFontName,
+      fontColor: options?.textFontColor,
+      layout: {
+        marginTop: options?.textMarginTop ?? 32,
+        constraints: {
+          topToBottomOf: timerShape,
+          startToStartOf: this,
+          endToEndOf: this
+        }
+      }
+    });
+    this.addChild(textLabel);
+    const countdownSequence = new Array();
+    for (let i = timerInitialNumber - 1; i > 0; i--) {
+      countdownSequence.push(Action.wait({ duration: 1e3 }));
+      countdownSequence.push(
+        Action.custom({
+          callback: () => {
+            timerNumberLabel.text = i.toString();
+          }
+        })
+      );
+    }
+    countdownSequence.push(Action.wait({ duration: 1e3 }));
+    countdownSequence.push(
+      Action.custom({
+        callback: () => {
+          timerNumberLabel.text = options?.timerZeroString ?? "0";
+        }
+      })
+    );
+    if (options?.zeroDwellMilliseconds !== void 0) {
+      countdownSequence.push(
+        Action.wait({ duration: options.zeroDwellMilliseconds })
+      );
+    }
+    countdownSequence.push(
+      Action.custom({
+        callback: () => {
+          const game = this.game;
+          const isLastScene = game.scenes.indexOf(this) === game.scenes.length - 1;
+          if (isLastScene) {
+            game.end();
+          }
+          const nextScene = game.scenes[game.scenes.indexOf(this) + 1];
+          game.presentScene(
+            nextScene,
+            options?.transition ?? Transition.slide({
+              direction: TransitionDirection.Left,
+              duration: options?.transitionDurationMilliseconds ?? SCENE_TRANSITION_DURATION_MS,
+              easing: SCENE_TRANSITION_EASING
+            })
+          );
+        }
+      })
+    );
+    this.onSetup(() => {
+      timerNumberLabel.text = timerInitialNumber.toString();
+    });
+    this.onAppear(() => {
+      this.run(Action.sequence(countdownSequence));
+    });
+  }
 }
 
-console.log("\u26AA @m2c2kit/addons version 0.3.12 (38470c49)");
+console.log("\u26AA @m2c2kit/addons version 0.3.14 (ebbdc605)");
 
-export { Button, Dialog, DialogResult, DrawPad, DrawPadEventType, DrawPadItemEventType, Grid, Instructions, VirtualKeyboard };
+export { Button, CountdownScene, Dialog, DialogResult, DrawPad, DrawPadEventType, DrawPadItemEventType, Grid, Instructions, VirtualKeyboard };
 //# sourceMappingURL=index.js.map