@m2c2kit/addons 0.3.12 → 0.3.14

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Canvas } from 'canvaskit-wasm';
-import { CompositeOptions, Size, RgbaColor, Composite, Entity, GlobalVariables, TextOptions, IText, EntityEvent, Point, CallbackOptions, ShapeOptions, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene } from '@m2c2kit/core';
+import { CompositeOptions, Size, RgbaColor, Composite, M2Node, GlobalVariables, TextOptions, IText, M2NodeEvent, CallbackOptions, Point, ShapeOptions, LabelHorizontalAlignmentMode, Transition, StoryOptions, Story, Scene, SceneOptions } from '@m2c2kit/core';
 
 interface GridOptions extends CompositeOptions {
     /** Number of rows in the grid. Must be 1 or greater */
@@ -16,7 +16,7 @@ interface GridOptions extends CompositeOptions {
     gridLineColor?: RgbaColor;
 }
 interface GridChild {
-    entity: Entity;
+    node: M2Node;
     row: number;
     column: number;
 }
@@ -32,11 +32,11 @@ declare class Grid extends Composite {
     gridChildren: GridChild[];
     private _gridBackground?;
     /**
-     * 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}
@@ -47,13 +47,13 @@ declare class Grid extends Composite {
     private set gridBackground(value);
     dispose(): void;
     /**
-     * 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?: string): Grid;
@@ -65,26 +65,26 @@ declare class Grid extends Composite {
      */
     removeAllChildren(): void;
     /**
-     * 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: Entity, row: number, column: number): void;
+    addAtCell(node: M2Node, row: number, column: number): void;
     /**
-     * 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
      */
     removeAllAtCell(row: number, column: number): void;
     /**
-     * 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: Entity): void;
+    removeChild(node: M2Node): void;
 }
 
 declare global {
@@ -111,13 +111,13 @@ declare class Button extends Composite implements IText {
     };
     cornerRadius: number;
     fontSize: number;
-    text: string;
+    private _text;
     private _fontColor;
     private backgroundPaint?;
     /**
      * 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.
      *
@@ -126,18 +126,20 @@ declare class Button extends Composite implements IText {
     constructor(options: ButtonOptions);
     initialize(): void;
     dispose(): void;
+    get text(): string;
+    set text(text: string);
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
     get fontColor(): RgbaColor;
     set fontColor(fontColor: RgbaColor);
     /**
-     * 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?: string): Button;
@@ -167,7 +169,7 @@ declare enum DialogResult {
     Positive = "Positive",
     Negative = "Negative"
 }
-interface DialogEvent extends EntityEvent {
+interface DialogEvent extends M2NodeEvent {
     dialogResult: DialogResult;
 }
 declare class Dialog extends Composite {
@@ -184,20 +186,20 @@ declare class Dialog extends Composite {
     private backgroundPaint?;
     constructor(options?: DialogOptions);
     show(): void;
-    onDialogResult(callback: (dialogResultEvent: DialogEvent) => void, replaceExistingCallback?: boolean): void;
+    onDialogResult(callback: (dialogResultEvent: DialogEvent) => void, options?: CallbackOptions): void;
     initialize(): void;
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
     get fontColor(): RgbaColor;
     set fontColor(fontColor: RgbaColor);
     /**
-     * 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?: string): Dialog;
@@ -234,7 +236,7 @@ declare const DrawPadEventType: {
     readonly StrokeEnd: "StrokeEnd";
 };
 type DrawPadEventType = (typeof DrawPadEventType)[keyof typeof DrawPadEventType];
-interface DrawPadEvent extends EntityEvent {
+interface DrawPadEvent extends M2NodeEvent {
     type: DrawPadEventType;
     position: Point;
 }
@@ -243,7 +245,7 @@ declare const DrawPadItemEventType: {
     readonly StrokeLeave: "StrokeLeave";
 };
 type DrawPadItemEventType = (typeof DrawPadItemEventType)[keyof typeof DrawPadItemEventType];
-interface DrawPadItemEvent extends EntityEvent {
+interface DrawPadItemEvent extends M2NodeEvent {
     type: DrawPadItemEventType;
 }
 interface StrokeInteraction {
@@ -253,6 +255,8 @@ interface StrokeInteraction {
     position: Point;
     /** Device ISO8601 Timestamp of the interaction. */
     iso8601Timestamp: string;
+    /** Was the interaction's position interpolated? (clipped to DrawPad boundary) because the user drew out of bounds? @remarks Only StrokeMove and StrokeEnd can be interpolated. A StrokeStart position can never begin out of bounds. */
+    interpolated: boolean;
 }
 type DrawPadStroke = Array<StrokeInteraction>;
 interface DrawPadItem {
@@ -299,7 +303,7 @@ declare 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}
@@ -310,6 +314,7 @@ declare class DrawPad extends Composite {
     private initializeDrawArea;
     private dist;
     private handleTapDown;
+    private addInterpolatedStrokeMove;
     private handleTapLeave;
     private handleTapUpAny;
     private handlePointerMove;
@@ -344,20 +349,20 @@ declare class DrawPad extends Composite {
      */
     onStrokeEnd(callback: (ev: DrawPadEvent) => void, options?: CallbackOptions): void;
     /**
-     * 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<T extends Entity>(entity: T): T & DrawPadItem;
+    addItem<T extends M2Node>(node: T): T & DrawPadItem;
     /**
      * Takes a screenshot of the DrawPad.
      *
@@ -365,6 +370,24 @@ declare class DrawPad extends Composite {
      * PNG format.
      */
     takeScreenshot(): string;
+    /**
+     * 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
+     */
+    private isPointWithinDrawPad;
+    /**
+     * 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
+     */
+    private interpolateToDrawPadBorder;
     private arrayBufferToBase64String;
     get backgroundColor(): RgbaColor;
     set backgroundColor(backgroundColor: RgbaColor);
@@ -431,7 +454,7 @@ interface VirtualKeyboardOptions extends CompositeOptions {
     /** If true, a preview of the key that will be pressed will be shown. */
     showKeyDownPreview?: boolean;
 }
-interface VirtualKeyboardEvent extends EntityEvent {
+interface VirtualKeyboardEvent extends M2NodeEvent {
     /** String that is generated when key is pressed, with any modifiers (e.g., Shift) applied. */
     key: string;
     /** Code for the key, not taking into account any modifiers. */
@@ -478,29 +501,21 @@ declare 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: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, replaceExistingCallback?: boolean): void;
+    onKeyDown(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
     /**
      * 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: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, replaceExistingCallback?: boolean): void;
+    onKeyUp(callback: (virtualKeyboardEvent: VirtualKeyboardEvent) => void, options?: CallbackOptions): void;
     private addVirtualKeyboardEventListener;
     update(): void;
     draw(canvas: Canvas): void;
     warmup(canvas: Canvas): void;
-    duplicate(newName?: string | undefined): Entity;
+    duplicate(newName?: string | undefined): M2Node;
 }
 
 interface InstructionScene {
@@ -595,12 +610,78 @@ interface InstructionsOptions extends StoryOptions {
 }
 declare 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: InstructionsOptions): Array<Scene>;
+    /**
+     * 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: InstructionsOptions): Array<Scene>;
 }
 
-export { Button, type ButtonOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type StrokeInteraction, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };
+interface CountdownSceneOptions extends SceneOptions {
+    /** Duration of the countdown, in milliseconds. */
+    milliseconds: number;
+    /** Duration of the slide transition, in milliseconds, to the next scene after the countdown completes. Default is 500. */
+    transitionDurationMilliseconds?: number;
+    /** A custom transition to use to present next scene after the countdown completes. */
+    transition?: Transition;
+    /** Duration in milliseconds to stay on zero before transitioning to the next scene. Default is zero. This option should be used if `transition` is set to `Transition.none()`. Otherwise, the zero will flash for a single frame before presenting the next scene. */
+    zeroDwellMilliseconds?: number;
+    /** Text shown below the countdown shape. Default is "GET READY". */
+    text?: string;
+    /** Font name for text  */
+    textFontName?: string;
+    /** Font size for text. Default is 50. */
+    textFontSize?: number;
+    /** Font color for text. Default is black. */
+    textFontColor?: RgbaColor;
+    /** Distance between bottom of countdown shape and text. Default is 32. */
+    textMarginTop?: number;
+    /** Font name for timer numbers. */
+    timerNumbersFontName?: string;
+    /** Font size for timer numbers. Default is 50. */
+    timerNumbersFontSize?: number;
+    /** Font size for timer numbers. Default is white. */
+    timerNumbersFontColor?: RgbaColor;
+    /** String to show when the timer reaches zero. Default is "0". This could be changed to another value, such as "GO!" */
+    timerZeroString?: string;
+    /** Shape of the timer. Default is a Royal Blue circle with a radius of 100 centered vertically. */
+    timerShape?: TimerShape;
+}
+interface TimerShape {
+    circle?: {
+        /** Radius of the circle timer shape. */
+        radius: number;
+    };
+    rectangle?: {
+        /** Width of the rectangle timer shape. */
+        width: number;
+        /** Height of the rectangle timer shape. */
+        height: number;
+        /** Corner radius of the rectangle timer shape. Default is 0. */
+        cornerRadius?: number;
+    };
+    /** Color of the timer shape. Default is Royal Blue. */
+    fillColor?: RgbaColor;
+    /** Default is to center the timer shape vertically within the scene (verticalBias = .5). Setting verticalBias less than .5 will pull the shape towards the top. Setting verticalBias greater than .5 will pull the shape towards the bottom. */
+    verticalBias?: number;
+}
+declare 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: CountdownSceneOptions);
+}
+
+export { Button, type ButtonOptions, CountdownScene, type CountdownSceneOptions, Dialog, type DialogEvent, type DialogOptions, DialogResult, DrawPad, type DrawPadEvent, DrawPadEventType, type DrawPadItem, type DrawPadItemEvent, DrawPadItemEventType, type DrawPadOptions, type DrawPadStroke, Grid, type GridOptions, type InstructionScene, Instructions, type InstructionsOptions, type KeyConfiguration, type KeyTapMetadata, type StrokeInteraction, type TimerShape, VirtualKeyboard, type VirtualKeyboardEvent, type VirtualKeyboardOptions, type VirtualKeyboardRow };