@houstonp/rubiks-cube 1.3.0 → 1.4.1

package/README.md

@@ -38,51 +38,85 @@ import '@houstonp/rubiks-cube';
 
 ## state of the component
 
-A state event occurs when a movement animation is completed. The event details contains the current state of the cube. The state is an object containing the stickers of each face. A sticker is either "up", "down", "left", "right", "front" or "back".
+A state event occurs when a movement animation is completed. The event details contains the current state of the cube along with the eventId of the animation. The state is an object containing the stickers of each face. A sticker is either "up", "down", "left", "right", "front" or "back".
 
 To listen for the state event, add an event listener to the rubiks-cube element.
 
 ```js
 const cube = document.querySelector('rubiks-cube');
 cube.addEventListener('state', (e) => {
-    console.log(e.detail.state);
+    console.log(e.detail);
 });
 /*
 {
-    up: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
-    down: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
-    left: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
-    right: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
-    front: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
-    back: [
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-        [sticker, sticker, sticker],
-    ],
+    eventId: "guid-guid-guid-guid-guid",
+    state: {
+        up: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+        down: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+        left: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+        right: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+        front: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+        back: [
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+            [sticker, sticker, sticker],
+        ],
+    }
 }
 */
 ```
 
+## Rubiks Cube Notation
+
+Notations can include the number of roations of a face. For example, `U2` means rotate the upper face 180 degrees.
+
+Noations can also include a prime symbol `'` to indicate a counter clockwise rotation. For example, `U'` means rotate the upper face counter clockwise. The direction is always determined relative to the face being moved.
+
+When both a number and a prime symbol are included the number is stated before the prime symbol. For example, `U2'` means rotate the upper face 180 degrees counter clockwise. and `U'2` is invalid.
+
+| Notation | Movement                                         |
+| -------- | ------------------------------------------------ |
+| U        | Top face clockwise                               |
+| u        | Top two layers clockwise                         |
+| D        | Bottom face clockwise                            |
+| d        | Bottom two layers clockwise                      |
+| L        | Left face clockwise                              |
+| l        | Left two layers clockwise                        |
+| R        | Right face clockwise                             |
+| r        | Right two layers clockwise                       |
+| F        | Front face clockwise                             |
+| f        | Front two layers clockwise                       |
+| B        | Back face clockwise                              |
+| b        | Back two layers clockwise                        |
+| M        | Middle layer clockwise (relative to L)           |
+| E        | Equatorial layer clockwise (relative to D)       |
+| S        | Standing layer clockwise (relative to F)         |
+| x        | Rotate cube on x axis clockwise (direction of R) |
+| y        | Rotate cube on y axis clockwise (direction of U) |
+| z        | Rotate cube on z axis clockwise (direction of F) |
+
+these symbols are used as actionIds for the action event below.
+
 ## Updating the component
 
 The Rubiks cube web component listens for custom events to perform twists, rotations and camera changes. As per convention, the starting rotation has green facing forward, white facing up and red facing to the right.
@@ -98,11 +132,29 @@ const cube = document.querySelector('rubiks-cube');
 cube.dispatchEvent(new CustomEvent('reset'));
 ```
 
-### Camera events
+### Action event
 
-The rubiks-cube element listens for the `camera` custom event and moves the camera to the specified position.
+The rubiks-cube element listens for the `action` custom event and moves the camera to the specified position.
+
+```js
+{
+    eventId: string,
+    action: {
+        type: "movement" | "camera" | "rotation",
+        actionId: string
+    }
+}
+```
+
+```js
+var event = new CustomEvent('action', {
+    detail: { eventId: 'guid-guid-guid-guid-guid', action: { type: 'camera', actionId: 'peek-toggle-horizontal' } },
+});
+```
 
-The camera position specified in the event details must be one of the following:
+#### Camera action event
+
+action IDs for camera actions are as follows
 
 -   `peek-right` - Camera is moved to the right of the cube so that the right face is visible
 -   `peek-left` - Camera is moved to the left of the cube so that the left face is visible
@@ -111,61 +163,94 @@ The camera position specified in the event details must be one of the following:
 -   `peek-toggle-horizontal` - Camera is moved to the opposite side of the cube in the horizontal plane
 -   `peek-toggle-vertical` - Camera is moved to the opposite side of the cube in the vertical plane
 
-Note: The camera position cannot change to perform an equivalent cube rotation.
-
 #### Example
 
 ```js
 const cube = document.querySelector('rubiks-cube');
-cube.dispatchEvent(
-    new CustomEvent('camera', {
-        detail: { action: 'peek-right' },
-    }),
-);
+const event = new CustomEvent('action', {
+    detail: { eventId: 'guid-guid-guid-guid-guid', action: { type: 'camera', actionId: 'peek-toggle-horizontal' } },
+});
+cube.dispatchEvent(event);
 ```
 
-### Rotation event
+#### Rotation action event
 
-The rubiks-cube element listens for the `rotate` custom event and rotates a face or entire cube in the direction specified by the event details.
+| Notation | Rotation                                         |
+| -------- | ------------------------------------------------ |
+| x        | Rotate cube on x axis clockwise (direction of R) |
+| y        | Rotate cube on y axis clockwise (direction of U) |
+| z        | Rotate cube on z axis clockwise (direction of F) |
 
-The rotation type specified in the event details must follow standard rubiks cube notation.
+actionIDs for action type "rotation" are as follows
 
-#### Rubiks Cube Notation
+-   'x',
+-   'x2',
+-   "x'",
+-   'y',
+-   'y2',
+-   "y'",
+-   'z',
+-   'z2',
+-   "z'",
 
-Notations can include the number of roations of a face. For example, `U2` means rotate the upper face 180 degrees.
+#### Example
 
-Noations can also include a prime symbol `'` to indicate a counter clockwise rotation. For example, `U'` means rotate the upper face counter clockwise. The direction is always determined relative to the face being moved.
+```js
+const cube = document.querySelector('rubiks-cube');
+const event = new CustomEvent('action', {
+    detail: { eventId: 'guid-guid-guid-guid-guid', action: { type: 'rotation', actionId: 'x' } },
+});
+cube.dispatchEvent(event);
+```
 
-When both a number and a prime symbol are included the number is stated before the prime symbol. For example, `U2'` means rotate the upper face 180 degrees counter clockwise. and `U'2` is invalid.
-
-| Notation | Movement                                         |
-| -------- | ------------------------------------------------ |
-| U        | Top face clockwise                               |
-| u        | Top two layers clockwise                         |
-| D        | Bottom face clockwise                            |
-| d        | Bottom two layers clockwise                      |
-| L        | Left face clockwise                              |
-| l        | Left two layers clockwise                        |
-| R        | Right face clockwise                             |
-| r        | Right two layers clockwise                       |
-| F        | Front face clockwise                             |
-| f        | Front two layers clockwise                       |
-| B        | Back face clockwise                              |
-| b        | Back two layers clockwise                        |
-| M        | Middle layer clockwise (relative to L)           |
-| E        | Equatorial layer clockwise (relative to D)       |
-| S        | Standing layer clockwise (relative to F)         |
-| x        | Rotate cube on x axis clockwise (direction of R) |
-| y        | Rotate cube on y axis clockwise (direction of U) |
-| z        | Rotate cube on z axis clockwise (direction of F) |
+#### Movement action event
+
+| Notation | Movement                                   |
+| -------- | ------------------------------------------ |
+| U        | Top face clockwise                         |
+| u        | Top two layers clockwise                   |
+| D        | Bottom face clockwise                      |
+| d        | Bottom two layers clockwise                |
+| L        | Left face clockwise                        |
+| l        | Left two layers clockwise                  |
+| R        | Right face clockwise                       |
+| r        | Right two layers clockwise                 |
+| F        | Front face clockwise                       |
+| f        | Front two layers clockwise                 |
+| B        | Back face clockwise                        |
+| b        | Back two layers clockwise                  |
+| M        | Middle layer clockwise (relative to L)     |
+| E        | Equatorial layer clockwise (relative to D) |
+| S        | Standing layer clockwise (relative to F)   |
+
+actionIDs for action type "movement" are as follows
+
+-   'R',
+-   'R2',
+-   "R'",
+-   'L',
+-   'L2',
+-   "L'",
+-   'U',
+-   'U2',
+-   "U'",
+-   'D',
+-   'D2',
+-   "D'",
+-   'F',
+-   'F2',
+-   "F'",
+-   'B',
+-   'B2',
+-   "B'",
+-   etc...
 
 #### Example
 
 ```js
 const cube = document.querySelector('rubiks-cube');
-cube.dispatchEvent(
-    new CustomEvent('rotate', {
-        detail: { action: "u2'" },
-    }),
-);
+const event = new CustomEvent('action', {
+    detail: { eventId: 'guid-guid-guid-guid-guid', action: { type: 'movement', actionId: 'U' } },
+});
+cube.dispatchEvent(event);
 ```

package/index.js

@@ -16,8 +16,6 @@ class RubiksCube extends HTMLElement {
         super();
         /** @type {number} */
         this.animationSpeed = defaultAnimationSpeed;
-        /** @type {"exponential" | "instant"} */
-        this.animationStyle = this.getAttribute('animation-style') || defaultAnimationStyle;
         this.attachShadow({ mode: 'open' });
         this.shadowRoot.innerHTML = `<canvas id="cube-canvas" style="display:block;"></canvas>`;
         this.canvas = this.shadowRoot.getElementById('cube-canvas');
@@ -116,9 +114,8 @@ class RubiksCube extends HTMLElement {
         const cameraAnimationGroup = new Group();
         cameraAnimationGroup.add(new Tween(camera.position).to({ x: 2.5, y: 2.5, z: 4 }, 1000).easing(Easing.Cubic.InOut).start());
 
-        const sendState = () => {
-            const state = cube.getStickerState();
-            const event = new CustomEvent('state', { detail: { state } });
+        const sendState = (eventId) => {
+            const event = new CustomEvent('state', { detail: { eventId, state: cube.currentState } });
             this.dispatchEvent(event);
         };
 
@@ -127,9 +124,9 @@ class RubiksCube extends HTMLElement {
             cameraAnimationGroup.update();
             controls.update();
 
-            var cubeState = cube.update();
-            if (cubeState) {
-                sendState();
+            var eventId = cube.update();
+            if (eventId) {
+                sendState(eventId);
             }
             renderer.render(scene, camera);
         }
@@ -137,28 +134,48 @@ class RubiksCube extends HTMLElement {
         // add event listeners for rotation and camera controls
         this.addEventListener('reset', () => {
             cube.reset();
-            sendState();
+            sendState('reset');
         });
 
-        this.addEventListener('rotate', (e) => {
-            const action = getRotationDetailsFromNotation(e.detail.action);
-            if (action !== undefined) {
-                cube.rotate(action);
+        this.addEventListener('action', (e) => {
+            /**  @type {{eventId: string, action: {type: "movement" | "camera" | "rotation", actionId: string }}} move */
+            var move = e.detail.move;
+            if (move.action.type === 'camera') {
+                handleCameraAction(move.action.actionId);
+                return;
+            }
+            if (move.action.type === 'movement' || move.action.type === 'rotation') {
+                handleRotationAction(move.eventId, move.action.actionId);
+                return;
             }
         });
 
-        this.addEventListener('camera', (e) => {
-            if (e.detail.action === 'peek-toggle-horizontal') {
+        /**
+         * @param {string} eventId
+         * @param {string} actionId
+         */
+        const handleRotationAction = (eventId, actionId) => {
+            const rotationDetails = getRotationDetailsFromNotation(actionId);
+            if (rotationDetails !== undefined) {
+                cube.rotate(eventId, rotationDetails);
+            }
+        };
+
+        /**
+         * @param {'peek-toggle-horizontal' | 'peek-toggle-vertical' | 'peek-right' | 'peek-left' | 'peek-up' | 'peek-down'} actionId
+         */
+        const handleCameraAction = (actionId) => {
+            if (actionId === 'peek-toggle-horizontal') {
                 cameraState.Right = !cameraState.Right;
-            } else if (e.detail.action === 'peek-toggle-vertical') {
+            } else if (actionId === 'peek-toggle-vertical') {
                 cameraState.Up = !cameraState.Up;
-            } else if (e.detail.action === 'peek-right') {
+            } else if (actionId === 'peek-right') {
                 cameraState.Right = true;
-            } else if (e.detail.action === 'peek-left') {
+            } else if (actionId === 'peek-left') {
                 cameraState.Right = false;
-            } else if (e.detail.action === 'peek-up') {
+            } else if (actionId === 'peek-up') {
                 cameraState.Up = true;
-            } else if (e.detail.action === 'peek-down') {
+            } else if (actionId === 'peek-down') {
                 cameraState.Up = false;
             }
             cameraAnimationGroup.add(
@@ -173,7 +190,7 @@ class RubiksCube extends HTMLElement {
                     )
                     .start(),
             );
-        });
+        };
     }
 }
 customElements.define('rubiks-cube', RubiksCube);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@houstonp/rubiks-cube",
-    "version": "1.3.0",
+    "version": "1.4.1",
     "description": "Rubiks Cube Web Component built with threejs",
     "main": "index.js",
     "author": "Houston Pearse",

package/src/cube/cube.js

@@ -18,6 +18,8 @@ export default class Cube {
         this.rotationQueue = [];
         /** @type {CubeRotation | undefined} */
         this.currentRotation = undefined;
+        /** @type {{ up: string[][], down: string[][], front: string[][], back: string[][], left: string[][], right: string[][] }} */
+        this.currentState = this.getStickerState();
         /** @type {number | undefined} */
         this._matchSpeed = undefined;
         /** @type {number} */
@@ -82,8 +84,10 @@ export default class Cube {
         }
         if (this.currentRotation.status === 'complete') {
             this.clearRotationGroup();
+            var eventId = this.currentRotation.eventId;
             this.currentRotation = undefined;
-            return this.getStickerState();
+            this.currentState = this.getStickerState();
+            return eventId;
         }
         return undefined;
     }
@@ -194,13 +198,11 @@ export default class Cube {
     }
 
     /**
+     * @param {string} eventId
      * @param {{axis: "x"|"y"|"z", layers: (-1|0|1)[], direction: 1|-1|2|-2}} input
      */
-    rotate(input) {
-        var queueLength = this.rotationQueue.length;
-        if (queueLength > 0 && this.rotationQueue[queueLength - 1].rotation.axis === input.axis) {
-        }
-        this.rotationQueue.push(new CubeRotation(input));
+    rotate(eventId, input) {
+        this.rotationQueue.push(new CubeRotation(eventId, input));
     }
 
     /**

package/src/cube/cubeRotation.js

@@ -2,11 +2,14 @@ import { Vector3, Group } from 'three';
 
 export class CubeRotation {
     /**
-     * @param {{axis: "x"|"y"|"z", layers: (-1|0|1)[], direction: 1|-1|2|-2}} input
+     * @param {string} eventId
+     * @param {{axis: "x"|"y"|"z", layers: (-1|0|1)[], direction: 1|-1|2|-2}} rotationDetails
      */
-    constructor(rotation) {
+    constructor(eventId, rotationDetails) {
+        /** @type {string} */
+        this.eventId = eventId;
         /** @type {{axis: "x"|"y"|"z", layers: (-1|0|1)[], direction: 1|-1|2|-2}} */
-        this.rotation = rotation;
+        this.rotation = rotationDetails;
         /** @type {"pending" | "initialised" | "complete" | "disposed"} */
         this.status = 'pending';
         /** @type {number} */