@m2c2kit/addons 0.3.13 → 0.3.15

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.
    *
@@ -260,6 +260,8 @@ class Button extends Composite {
     this.fontSize = 20;
     this._text = "";
     this._fontColor = WebColors.White;
+    this._interpolation = {};
+    this._localize = true;
     if (options.text) {
       this.text = options.text;
     }
@@ -269,6 +271,12 @@ class Button extends Composite {
     if (options.cornerRadius !== void 0) {
       this.cornerRadius = options.cornerRadius;
     }
+    if (options.fontName) {
+      this.fontName = options.fontName;
+    }
+    if (options.fontNames) {
+      this.fontNames = options.fontNames;
+    }
     if (options.fontSize !== void 0) {
       this.fontSize = options.fontSize;
     }
@@ -278,6 +286,12 @@ class Button extends Composite {
     if (options.backgroundColor) {
       this.backgroundColor = options.backgroundColor;
     }
+    if (options.interpolation) {
+      this.interpolation = options.interpolation;
+    }
+    if (options.localize !== void 0) {
+      this.localize = options.localize;
+    }
   }
   initialize() {
     this.removeAllChildren();
@@ -299,6 +313,10 @@ class Button extends Composite {
     this.addChild(buttonRectangle);
     const buttonLabel = new Label({
       text: this.text,
+      localize: this.localize,
+      interpolation: this.interpolation,
+      fontName: this.fontName,
+      fontNames: this.fontNames,
       fontSize: this.fontSize,
       fontColor: this.fontColor
     });
@@ -329,26 +347,59 @@ class Button extends Composite {
     this._fontColor = fontColor;
     this.needsInitialization = true;
   }
+  get fontName() {
+    return this._fontName;
+  }
+  set fontName(fontName) {
+    this._fontName = fontName;
+    this.needsInitialization = true;
+  }
+  get fontNames() {
+    return this._fontNames;
+  }
+  set fontNames(fontNames) {
+    this._fontNames = fontNames;
+    this.needsInitialization = true;
+  }
+  get interpolation() {
+    return this._interpolation;
+  }
+  set interpolation(interpolation) {
+    this._interpolation = interpolation;
+    Object.freeze(this._interpolation);
+    this.needsInitialization = true;
+  }
+  get localize() {
+    return this._localize;
+  }
+  set localize(localize) {
+    this._localize = localize;
+    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,
       cornerRadius: this.cornerRadius,
       backgroundColor: this.backgroundColor,
       fontColor: this.fontColor,
-      name: newName
+      name: newName,
+      localize: this.localize,
+      interpolation: JSON.parse(JSON.stringify(this.interpolation)),
+      fontName: this.fontName,
+      fontNames: JSON.parse(JSON.stringify(this.fontNames))
     });
     if (this.children.length > 0) {
       dest.children = this.children.map((child) => {
@@ -384,7 +435,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;
@@ -425,15 +476,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);
@@ -455,9 +507,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 */
@@ -503,9 +555,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 */
@@ -525,9 +577,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 */
@@ -555,13 +607,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) {
@@ -594,7 +646,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}
@@ -919,45 +971,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,
@@ -966,7 +1018,7 @@ class DrawPad extends Composite {
         );
       }
     });
-    Object.defineProperty(entity, "onStrokeLeave", {
+    Object.defineProperty(node, "onStrokeLeave", {
       value: function(callback, options) {
         this.addEventListener(
           DrawPadItemEventType.StrokeLeave,
@@ -975,62 +1027,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.
@@ -1197,8 +1249,12 @@ class VirtualKeyboard extends Composite {
    */
   constructor(options) {
     super(options);
+    this.compositeType = "VirtualKeyboard";
     this.rowsConfiguration = new Array();
     this.shiftActivated = false;
+    this.keyShapes = new Array();
+    // VirtualKeyboard defaults to being user interactive.
+    this._isUserInteractionEnabled = true;
     this.size = options.size;
     this.position = options.position ?? { x: 0, y: 0 };
     this.keyboardHorizontalPaddingPercent = options.keyboardHorizontalPaddingPercent ?? 0.02;
@@ -1380,6 +1436,7 @@ class VirtualKeyboard extends Composite {
     const keyboardHorizontalPadding = (this.keyboardHorizontalPaddingPercent ?? 0.02) * this.size.width;
     const keyBoxHeight = (this.size.height - 2 * keyboardVerticalPadding) / rows.length;
     const keyBoxWidth = (this.size.width - 2 * keyboardHorizontalPadding) / this.keysPerRow;
+    this.keyShapes = [];
     for (let r = 0; r < rows.length; r++) {
       const row = rows[r];
       const rowSumKeyWidths = row.reduce(
@@ -1418,9 +1475,10 @@ class VirtualKeyboard extends Composite {
           cornerRadius: 4,
           fillColor: this.keyColor,
           lineWidth: 0,
-          isUserInteractionEnabled: true
+          isUserInteractionEnabled: this.isUserInteractionEnabled
         });
         keyBox.addChild(keyShape);
+        this.keyShapes.push(keyShape);
         keyShape.onTapUp((tapEvent) => {
           let keyAsString = "";
           if (!key.isShift) {
@@ -1456,10 +1514,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,
@@ -1524,10 +1582,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,
@@ -1581,54 +1639,55 @@ 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);
   }
+  /**
+   * Does the `VirtualKeyboard` respond to user events? Default is true.
+   */
+  get isUserInteractionEnabled() {
+    return this._isUserInteractionEnabled;
+  }
+  /**
+   * Does the `VirtualKeyboard` respond to user events? Default is true.
+   */
+  set isUserInteractionEnabled(isUserInteractionEnabled) {
+    this._isUserInteractionEnabled = isUserInteractionEnabled;
+    this.keyShapes.forEach((keyShape) => {
+      keyShape.isUserInteractionEnabled = isUserInteractionEnabled;
+    });
+  }
   update() {
     super.update();
   }
@@ -1642,31 +1701,31 @@ class VirtualKeyboard extends Composite {
     });
   }
   duplicate(newName) {
-    throw new Error("Method not implemented.");
+    throw new Error(`Method not implemented. ${newName}`);
   }
 }
 
-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";
@@ -1851,9 +1910,605 @@ 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));
+    });
+  }
+}
+
+class LocalePicker extends Composite {
+  /**
+   * An icon and dialog box for selecting a locale from a list of options.
+   *
+   * @remarks This composite node is composed of a dialog box that appears
+   * when the user taps a globe icon. Typically, the `LocalePicker` will be
+   * added as a free node to the game so that it exists independently of
+   * the game's scenes. The dialog box contains a list of locales that the
+   * user can choose from. By default, this list is populated with the locales
+   * in the game's `Translation` object. When the user selects a locale, the
+   * dialog box disappears and the locale is set as the game's current locale.
+   *  The dialog box is automatically sized to fit the number of locale
+   * options.
+   *
+   * @example
+   * let localePicker: LocalePicker;
+   * if (game.getParameter<boolean>("show_locale_picker")) {
+   *   localePicker = new LocalePicker();
+   *   game.addFreeNode(localePicker);
+   * }
+   *
+   * @param options - {@link LocalePickerOptions}
+   */
+  constructor(options) {
+    super(options);
+    this.compositeType = "LocalePicker";
+    this.zPosition = Number.MAX_VALUE;
+    this.DEFAULT_FONT_SIZE = 24;
+    this.automaticallyChangeLocale = true;
+    this._localeOptions = new Array();
+    this._backgroundColor = WebColors.White;
+    this._fontSize = this.DEFAULT_FONT_SIZE;
+    this._fontColor = WebColors.Black;
+    this._cornerRadius = 8;
+    this._overlayAlpha = 0.5;
+    this._icon = {
+      // public domain SVG from https://commons.wikimedia.org/wiki/File:Globe_icon.svg
+      svgString: `<svg xmlns="http://www.w3.org/2000/svg" width="420" height="420" stroke="#000" fill="none"><path stroke-width="26" d="M209 15a195 195 0 1 0 2 0z"/><path stroke-width="18" d="M210 15v390m195-195H15M59 90a260 260 0 0 0 302 0m0 240a260 260 0 0 0-302 0M195 20a250 250 0 0 0 0 382m30 0a250 250 0 0 0 0-382"/></svg>`,
+      height: 32,
+      width: 32
+    };
+    this._iconPosition = { x: 32, y: 32 };
+    /**
+     * Wrap displayed locale in double angle quotes if it is the current locale.
+     * Note: Although the code editor will allow us to enter almost any
+     * unicode character, it will not render correctly if the font does
+     * not support the character. Thus, be careful to use characters that
+     * are supported by the font. For example, check a page like
+     * https://www.fontspace.com/roboto-font-f13281 to see which characters
+     * are supported by Roboto Regular, which is often the default font in
+     * m2c2kit. Emoji or checkmarks like ✓ are not in Roboto Regular!
+     */
+    this.LEFT_SELECTION_INDICATOR = "\xAB";
+    this.RIGHT_SELECTION_INDICATOR = "\xBB";
+    if (!options) {
+      return;
+    }
+    if (options.localeOptions) {
+      this.localeOptions = options.localeOptions;
+    }
+    if (options.backgroundColor) {
+      this.backgroundColor = options.backgroundColor;
+    }
+    if (options.overlayAlpha !== void 0) {
+      this.overlayAlpha = options.overlayAlpha;
+    }
+    if (options.fontSize !== void 0) {
+      this.fontSize = options.fontSize;
+    }
+    if (options.fontColor) {
+      this.fontColor = options.fontColor;
+    }
+    if (options.cornerRadius) {
+      this.cornerRadius = options.cornerRadius;
+    }
+    if (options.currentLocale !== void 0) {
+      this.currentLocale = options.currentLocale;
+    }
+    if (options.icon) {
+      this.icon = options.icon;
+    }
+    if (options.automaticallyChangeLocale !== void 0) {
+      this.automaticallyChangeLocale = options.automaticallyChangeLocale;
+    }
+  }
+  /**
+   * Executes a callback when the user selects a locale.
+   *
+   * @param callback - function to execute
+   * @param options - {@link CallbackOptions}
+   */
+  onResult(callback, options) {
+    const eventListener = {
+      type: M2EventType.CompositeCustom,
+      compositeType: "LocalePickerResult",
+      nodeUuid: this.uuid,
+      callback
+    };
+    if (options?.replaceExisting) {
+      this.eventListeners = this.eventListeners.filter(
+        (listener) => !(listener.nodeUuid === eventListener.nodeUuid && listener.type === "LocalePickerResult")
+      );
+    }
+    this.eventListeners.push(eventListener);
+  }
+  initialize() {
+    if (this.currentLocale === void 0) {
+      this.currentLocale = this.game.i18n?.locale;
+    }
+    if (this.localeOptions.length === 0) {
+      const locales = Object.keys(this.game.i18n?.translation || {});
+      locales.filter((locale) => locale !== "configuration").forEach((locale) => {
+        this.localeOptions.push({
+          text: this.game.i18n?.translation[locale].localeName || locale,
+          locale,
+          svg: this.game.i18n?.translation[locale].localeSvg
+        });
+      });
+    }
+    if (this.localeOptions.length === 0) {
+      throw new Error("No locales available for LocalePicker");
+    }
+    this.children.filter((child) => child.name !== "localePickerIcon").forEach((child) => this.removeChild(child));
+    this.game.imageManager.loadImages([
+      {
+        imageName: "__localePickerIcon",
+        svgString: this.icon.svgString,
+        height: this.icon.height,
+        width: this.icon.width
+      }
+    ]);
+    if (!this.iconSprite) {
+      this.iconSprite = new Sprite({
+        // name is how we refer to this sprite, as a node.
+        name: "localePickerIcon",
+        // imageName is the loaded image that we can assign to the sprite
+        imageName: "__localePickerIcon",
+        position: this.iconPosition,
+        isUserInteractionEnabled: true
+      });
+      this.addChild(this.iconSprite);
+      this.iconSprite.onTapDown(() => {
+        this.setDialogVisibility(true);
+      });
+    }
+    const overlay = new Shape({
+      rect: {
+        width: Globals.canvasCssWidth,
+        height: Globals.canvasCssHeight,
+        x: Globals.canvasCssWidth / 2,
+        y: Globals.canvasCssHeight / 2
+      },
+      fillColor: [0, 0, 0, this.overlayAlpha],
+      zPosition: -1,
+      isUserInteractionEnabled: true,
+      hidden: true
+    });
+    overlay.onTapDown((e) => {
+      e.handled = true;
+      if (this.eventListeners.length > 0) {
+        this.eventListeners.filter((listener) => listener.type === "LocalePickerResult").forEach((listener) => {
+          const languagePickerEvent = {
+            type: "LocalePickerResult",
+            target: this,
+            handled: false,
+            result: {
+              locale: void 0
+            }
+          };
+          listener.callback(languagePickerEvent);
+        });
+      }
+      this.setDialogVisibility(false);
+    });
+    this.addChild(overlay);
+    const lineHeight = this.fontSize / this.DEFAULT_FONT_SIZE * 50;
+    const dialogHeight = this.localeOptions.length * lineHeight;
+    const dialogWidth = Globals.canvasCssWidth / 2;
+    const sceneCenter = {
+      x: Globals.canvasCssWidth / 2,
+      y: Globals.canvasCssHeight / 2
+    };
+    const localeDialog = new Shape({
+      rect: {
+        width: dialogWidth,
+        height: dialogHeight,
+        x: sceneCenter.x,
+        y: sceneCenter.y
+      },
+      cornerRadius: this.cornerRadius,
+      fillColor: this.backgroundColor,
+      isUserInteractionEnabled: true,
+      hidden: true
+    });
+    localeDialog.onTapDown((e) => {
+      e.handled = true;
+    });
+    this.addChild(localeDialog);
+    for (let i = 0; i < this.localeOptions.length; i++) {
+      const localeOption = this.localeOptions[i];
+      if (!localeOption.svg) {
+        let labelText = localeOption.text;
+        if (this.currentLocale === localeOption.locale) {
+          labelText = `${this.LEFT_SELECTION_INDICATOR} ${labelText} ${this.RIGHT_SELECTION_INDICATOR}`;
+        }
+        const text = new Label({
+          text: labelText,
+          fontSize: this.fontSize,
+          fontColor: this.fontColor,
+          position: {
+            x: sceneCenter.x,
+            y: sceneCenter.y + i * lineHeight - dialogHeight / 2 + lineHeight / 2
+          },
+          isUserInteractionEnabled: true,
+          zPosition: 1,
+          hidden: true,
+          // do not localize the text of each language option
+          localize: false
+        });
+        text.onTapDown((e) => {
+          this.handleLocaleSelection(e, localeOption);
+        });
+        this.addChild(text);
+      } else {
+        this.game.imageManager.loadImages([
+          {
+            imageName: localeOption.text,
+            svgString: localeOption.svg.svgString,
+            height: localeOption.svg.height,
+            width: localeOption.svg.width
+          }
+        ]);
+        const localeSprite = new Sprite({
+          imageName: localeOption.text,
+          position: {
+            x: sceneCenter.x,
+            y: sceneCenter.y + i * lineHeight - dialogHeight / 2 + lineHeight / 2
+          },
+          isUserInteractionEnabled: true,
+          zPosition: 1,
+          hidden: true
+        });
+        this.addChild(localeSprite);
+        if (this.currentLocale === localeOption.locale) {
+          const leftSelectionIndicator = new Label({
+            text: this.LEFT_SELECTION_INDICATOR,
+            fontSize: this.fontSize,
+            fontColor: this.fontColor,
+            position: {
+              x: sceneCenter.x - localeOption.svg.width / 2,
+              y: sceneCenter.y + i * lineHeight - dialogHeight / 2 + lineHeight / 2
+            },
+            hidden: true,
+            // do not localize the left selection indicator
+            localize: false
+          });
+          this.addChild(leftSelectionIndicator);
+          const rightSelectionIndicator = new Label({
+            text: this.RIGHT_SELECTION_INDICATOR,
+            fontSize: this._fontSize,
+            fontColor: this.fontColor,
+            position: {
+              x: sceneCenter.x + localeOption.svg.width / 2,
+              y: sceneCenter.y + i * lineHeight - dialogHeight / 2 + lineHeight / 2
+            },
+            hidden: true,
+            // do not localize the left selection indicator
+            localize: false
+          });
+          this.addChild(rightSelectionIndicator);
+        }
+        localeSprite.onTapDown((e) => {
+          this.handleLocaleSelection(e, localeOption);
+        });
+      }
+    }
+    this.needsInitialization = false;
+  }
+  handleLocaleSelection(e, localeOption) {
+    e.handled = true;
+    if (this.eventListeners.length > 0) {
+      this.eventListeners.filter(
+        (listener) => listener.type === M2EventType.CompositeCustom && listener.compositeType === "LocalePickerResult" && listener.nodeUuid == this.uuid
+      ).forEach((listener) => {
+        const languagePickerEvent = {
+          type: M2EventType.CompositeCustom,
+          compositeType: "LocalePickerResult",
+          target: this,
+          handled: false,
+          result: {
+            locale: localeOption.locale
+          }
+        };
+        listener.callback(languagePickerEvent);
+      });
+    }
+    this.setDialogVisibility(false);
+    if (this.automaticallyChangeLocale) {
+      this.game.i18n?.switchToLocale(localeOption.locale);
+      this.currentLocale = localeOption.locale;
+    }
+  }
+  setDialogVisibility(visible) {
+    this.children.filter((child) => child.name !== "localePickerIcon").forEach((child) => {
+      child.hidden = !visible;
+    });
+  }
+  get backgroundColor() {
+    return this._backgroundColor;
+  }
+  set backgroundColor(backgroundColor) {
+    this._backgroundColor = backgroundColor;
+    this.needsInitialization = true;
+  }
+  get fontSize() {
+    return this._fontSize;
+  }
+  set fontSize(fontSize) {
+    this._fontSize = fontSize;
+    this.needsInitialization = true;
+  }
+  get fontColor() {
+    return this._fontColor;
+  }
+  set fontColor(fontColor) {
+    this._fontColor = fontColor;
+    this.needsInitialization = true;
+  }
+  get cornerRadius() {
+    return this._cornerRadius;
+  }
+  set cornerRadius(cornerRadius) {
+    this._cornerRadius = cornerRadius;
+    this.needsInitialization = true;
+  }
+  get overlayAlpha() {
+    return this._overlayAlpha;
+  }
+  set overlayAlpha(alpha) {
+    this._overlayAlpha = alpha;
+    this.needsInitialization = true;
+  }
+  get icon() {
+    const localePicker = this;
+    return {
+      get svgString() {
+        return localePicker._icon.svgString;
+      },
+      set svgString(svgString) {
+        localePicker._icon.svgString = svgString;
+        localePicker.needsInitialization = true;
+      },
+      get imageName() {
+        return localePicker._icon.imageName;
+      },
+      set imageName(imageName) {
+        localePicker._icon.imageName = imageName;
+        localePicker.needsInitialization = true;
+      },
+      get height() {
+        return localePicker._icon.height;
+      },
+      set height(height) {
+        localePicker._icon.height = height;
+        localePicker.needsInitialization = true;
+      },
+      get width() {
+        return localePicker._icon.width;
+      },
+      set width(width) {
+        localePicker._icon.width = width;
+        localePicker.needsInitialization = true;
+      }
+    };
+  }
+  set icon(icon) {
+    this._icon = icon;
+    this.needsInitialization = true;
+  }
+  get iconPosition() {
+    const localePicker = this;
+    return {
+      get x() {
+        return localePicker._iconPosition.x;
+      },
+      set x(x) {
+        localePicker._iconPosition.x = x;
+        if (localePicker.iconSprite) {
+          localePicker.iconSprite.position = localePicker._iconPosition;
+        }
+        localePicker.needsInitialization = true;
+      },
+      get y() {
+        return localePicker._iconPosition.y;
+      },
+      set y(y) {
+        localePicker._iconPosition.y = y;
+        if (localePicker.iconSprite) {
+          localePicker.iconSprite.position = localePicker._iconPosition;
+        }
+        localePicker.needsInitialization = true;
+      }
+    };
+  }
+  set iconPosition(position) {
+    this._iconPosition = position;
+    if (this.iconSprite) {
+      this.iconSprite.position = position;
+    }
+    this.needsInitialization = true;
+  }
+  get localeOptions() {
+    return this._localeOptions;
+  }
+  set localeOptions(options) {
+    this._localeOptions = options;
+    this.needsInitialization = true;
+  }
+  get currentLocale() {
+    return this._currentLocale;
+  }
+  set currentLocale(locale) {
+    if (locale === this.currentLocale) {
+      return;
+    }
+    this._currentLocale = locale;
+    this.needsInitialization = true;
+  }
+  update() {
+    super.update();
+  }
+  draw(canvas) {
+    super.drawChildren(canvas);
+  }
+  warmup(canvas) {
+    this.initialize();
+    this.children.filter((child) => child.isDrawable).forEach((child) => {
+      child.warmup(canvas);
+    });
+  }
+  /**
+   * Duplicates a node using deep copy.
+   *
+   * @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 node. If not
+   * provided, name will be the new uuid
+   */
+  duplicate(newName) {
+    throw new Error(`duplicate not implemented. ${newName}`);
+  }
 }
 
-console.log("\u26AA @m2c2kit/addons version 0.3.13 (d8a00e86)");
+console.log("\u26AA @m2c2kit/addons version 0.3.15 (b3a70752)");
 
-export { Button, Dialog, DialogResult, DrawPad, DrawPadEventType, DrawPadItemEventType, Grid, Instructions, VirtualKeyboard };
+export { Button, CountdownScene, Dialog, DialogResult, DrawPad, DrawPadEventType, DrawPadItemEventType, Grid, Instructions, LocalePicker, VirtualKeyboard };
 //# sourceMappingURL=index.js.map