@houstonp/rubiks-cube 2.0.0 → 3.0.0

package/types/rubiksCube3D/rubiksCube3D.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @implements {RubiksCubeViewInterface}
+ */
+export default class RubiksCube3D extends Object3D<import("three").Object3DEventMap> implements RubiksCubeViewInterface {
+    /**
+     * @public
+     * @param {RubiksCube3DSettings} cubeSettings
+     */
+    constructor(cubeSettings: RubiksCube3DSettings);
+    /** @type {RubiksCube3DSettings} */
+    _cubeSettings: RubiksCube3DSettings;
+    /** @type {number} */
+    _pieceGap: number;
+    /** @type {CubeType} */
+    _cubeType: CubeType;
+    /** @type {CubeConfig} */
+    _cubeConfig: CubeConfig;
+    /** @type {Group} */
+    _mainGroup: Group;
+    /** @type {Group} */
+    _animationGroup: Group;
+    /** @type {GSAPAnimation | undefined} */
+    _currentAnimation: GSAPAnimation | undefined;
+    /**
+     * Creates the main group containing all the pieces of the cube in their default position and rotation. Should only be called once during initialization.
+     * @private
+     **/
+    private createCubeGroup;
+    /**
+     * @param {Group} group
+     * @returns {(CornerPiece | EdgePiece | CenterPiece)[]}
+     */
+    _getPieces(group?: Group): (CornerPiece | EdgePiece | CenterPiece)[];
+    /**
+     * Returns the sticker state of the cube. Can only be called when an Animation is not in progress as not all pieces would be in the main group.
+     * @returns {StickerState}
+     */
+    getStickerState(): StickerState;
+    /**
+     * Sets the sticker state of the cube. Can only be called when an Animation is not in progress as not all pieces would be in the main group.
+     * @private
+     * @param {StickerState} stickerState
+     */
+    private setStickerState;
+    /**
+     *
+     * @param {string} logo
+     */
+    addLogo(logo: string): void;
+    /**
+     * Returns the pieces that should be rotated for a given slice. If the slice has no layers, all pieces will be returned. Should only be called before an Animation is started.
+     * @private
+     * @param {Slice} slice
+     * @returns {Object3D[]}
+     */
+    private getRotationLayer;
+    /**
+     * Updates the gap of the pieces. To be used when the cube is not rotating
+     * @private
+     * @param {number} pieceGap
+     * @returns {void}
+     */
+    private updateGap;
+    /**
+     * Adds pieces in the rotationGroup back into the main group.
+     * Updates the position and rotation of the pieces according to their world position and rotation, then resets the rotation of the rotation group.
+     * Should only be called when a rotation is in progress.
+     * @private
+     * @returns {void}
+     */
+    private clearAnimationGroup;
+    /**
+     * @private
+     * @param {Slice} slice
+     */
+    private fillAnimationGroup;
+    /**
+     * @public
+     * @param {number} animationSpeedMs
+     */
+    public setCurrentAnimationSpeed(animationSpeedMs: number): void;
+    /**
+     * @public
+     */
+    public reset(): void;
+    /**
+     * @public
+     * @param {StickerState} stickerState
+     */
+    public setState(stickerState: StickerState): void;
+    /**
+     * sets the state of the cube
+     * @public
+     * @param {CubeType} cubeType
+     * @returns {void}
+     */
+    public setType(cubeType: CubeType): void;
+    /**
+     * @public
+     * @param {Slice} slice
+     * @param {{animationSpeedMs: number?, ease: gsap.EaseString | gsap.EaseFunction | undefined}} [options]
+     * @returns {Promise<void>}
+     */
+    public slice(slice: Slice, options?: {
+        animationSpeedMs: number | null;
+        ease: gsap.EaseString | gsap.EaseFunction | undefined;
+    }): Promise<void>;
+}
+export type RubiksCubeViewInterface = _RubiksCubeViewInterface;
+import { Object3D } from 'three';
+import RubiksCube3DSettings from './cubeSettings';
+import type { CubeType } from '../core';
+import type { CubeConfig } from './cubeConfig';
+import { Group } from 'three';
+import { CornerPiece } from './cornerPiece';
+import { EdgePiece } from './edgePiece';
+import { CenterPiece } from './centerPiece';
+import type { StickerState } from '../state/stickerState';
+import type { Slice } from '../state/slice';
+import type { RubiksCubeViewInterface as _RubiksCubeViewInterface } from '../rubiksCube/rubiksCubeController';

package/types/rubiksCube3D/sticker.d.ts

@@ -0,0 +1,18 @@
+/** @import {BufferGeometry, ColorRepresentation} from 'three' */
+export class Sticker extends Mesh<BufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>, import("three").Material | import("three").Material[], import("three").Object3DEventMap> {
+    /**
+     * @param {BufferGeometry} geometry
+     */
+    constructor(geometry: BufferGeometry);
+    /**
+     * @param {ColorRepresentation} color
+     */
+    set color(color: ColorRepresentation);
+    /**
+     * @returns {ColorRepresentation} color
+     */
+    get color(): ColorRepresentation;
+}
+import type { BufferGeometry } from 'three';
+import { Mesh } from 'three';
+import type { ColorRepresentation } from 'three';

package/types/state/index.d.ts

@@ -0,0 +1,5 @@
+import { RubiksCubeState } from './rubiksCubeState';
+import { Axi } from './slice';
+import { GetMovementSlice } from './slice';
+import { GetRotationSlice } from './slice';
+export { RubiksCubeState, Axi, GetMovementSlice, GetRotationSlice };

package/types/state/rubiksCubeState.d.ts

@@ -0,0 +1,108 @@
+export class RubiksCubeState {
+    /**
+     *
+     * @param {CubeType} cubeType
+     */
+    constructor(cubeType: CubeType);
+    cubeType: CubeType;
+    /** @type {StickerState?} */
+    stickerState: StickerState | null;
+    /** @type {number[]} */
+    layers: number[];
+    /** @type {pieceState[]} */
+    corners: pieceState[];
+    /** @type {pieceState[]} */
+    edges: pieceState[];
+    /** @type {pieceState[]} */
+    centers: pieceState[];
+    reset(): void;
+    /**
+     * @param {StickerState} stickerState
+     * @returns {void}
+     */
+    setState(stickerState: StickerState): void;
+    /**
+     * @return {StickerState}
+     */
+    getState(): StickerState;
+    /**
+     * @returns {string}
+     */
+    getKociemba(): string;
+    /**
+     * @param {string} kociembaString
+     * @returns {boolean}
+     */
+    setKociemba(kociembaString: string): boolean;
+    /**
+     *
+     * @param {Slice} slice
+     */
+    slice(slice: Slice): void;
+    /**
+     * @param {Movement} movement
+     * @param {MoveOptions} [options]
+     * @returns {Slice?}
+     */
+    move(movement: Movement, options?: MoveOptions): Slice | null;
+    /**
+     * @param {Rotation} rotation
+     * @param {RotationOptions} [options]
+     * @returns {Slice?}
+     */
+    rotate(rotation: Rotation, options?: RotationOptions): Slice | null;
+    /**
+     * @param {(Rotation | Movement)[]} actions
+     * @param {MoveOptions | RotationOptions } [options]
+     */
+    do(actions: (Rotation | Movement)[], options?: MoveOptions | RotationOptions): void;
+    /**
+     * @private
+     * @param {number} position
+     * @returns {number}
+     */
+    private _getLayerNumber;
+}
+export function corners(layers: number[]): {
+    position: vector;
+    rotation: vector;
+}[];
+export function centers(layers: number[]): {
+    position: vector;
+    rotation: vector;
+}[];
+export function edges(layers: number[]): {
+    position: vector;
+    rotation: vector;
+}[];
+export type state = {
+    corners: pieceState[];
+    edges: pieceState[];
+    centers: pieceState[];
+};
+export type pieceState = {
+    position: vector;
+    rotation: vector;
+    stickers: {
+        face: Face;
+        direction: vector;
+    }[];
+};
+export type vector = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type MoveOptions = {
+    translate?: boolean | undefined;
+    reverse?: boolean | undefined;
+};
+export type RotationOptions = {
+    reverse?: boolean | undefined;
+};
+import type { CubeType } from '../core';
+import type { StickerState } from './stickerState';
+import type { Slice } from './slice';
+import type { Movement } from '../core';
+import type { Rotation } from '../core';
+import type { Face } from '../core';

package/types/state/slice.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A slice represents an action or movement of a 3D rubiks cube. layers
+ * @typedef  Slice
+ * @property {Axis} axis the axis that pieces rotate around
+ * @property {number[]} layerIds starting from 0 to the size of the cube. Layers represent what layers are included in the movement.
+ * @property {number} direction the direction and magnitude of the rotation
+ **/
+/**
+ * @param {Movement} movement
+ * @param {number} layerCount
+ * @returns {Slice | undefined}
+ */
+export function GetMovementSlice(movement: Movement, layerCount: number): Slice | undefined;
+/**
+ * @param {Rotation} rotation
+ * @param {number} layerCount
+ * @returns {Slice | undefined}
+ */
+export function GetRotationSlice(rotation: Rotation, layerCount: number): Slice | undefined;
+/** @import {Movement, Rotation} from '../core' */
+/** @typedef {typeof Axi[keyof typeof Axi]} Axis */
+export const Axi: Readonly<{
+    x: "x";
+    y: "y";
+    z: "z";
+}>;
+/**
+ * A slice represents an action or movement of a 3D rubiks cube. layers
+ */
+export type Slice = {
+    /**
+     * the axis that pieces rotate around
+     */
+    axis: Axis;
+    /**
+     * starting from 0 to the size of the cube. Layers represent what layers are included in the movement.
+     */
+    layerIds: number[];
+    /**
+     * the direction and magnitude of the rotation
+     */
+    direction: number;
+};
+export type Axis = (typeof Axi)[keyof typeof Axi];
+import type { Movement } from '../core';
+import type { Rotation } from '../core';

package/types/state/stickerState.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @param {vector} stickerDirection
+ * @param {vector} piecePosition
+ * @param {number[]} layers
+ * @returns {{face: Face, i: number, j: number}}
+ */
+export function getStickerFaceIndex(stickerDirection: vector, piecePosition: vector, layers: number[]): {
+    face: Face;
+    i: number;
+    j: number;
+};
+/**
+ * @param {StickerState} stickerState
+ * @returns {string}
+ */
+export function toKociemba(stickerState: StickerState): string;
+/**
+ * @param {string} kociembaString
+ * @returns {StickerState | undefined} stickerState
+ */
+export function fromKociemba(kociembaString: string): StickerState | undefined;
+export function defaultStickerState(cubeType: CubeType): StickerState;
+export function getEmptyStickerState(cubeType: CubeType): StickerState;
+export type StickerState = {
+    U: Face[][];
+    D: Face[][];
+    F: Face[][];
+    B: Face[][];
+    L: Face[][];
+    R: Face[][];
+};
+import type { vector } from './rubiksCubeState';
+import type { Face } from '../core';
+import type { CubeType } from '../core';

package/types/webComponent/cameraState.d.ts

@@ -0,0 +1,22 @@
+/** @import {PeekAction, PeekState} from './constants' */
+export class CameraState {
+    /**
+     * @param {boolean} up
+     * @param {boolean} right
+     */
+    constructor(up?: boolean, right?: boolean);
+    /** @type {boolean} */
+    Up: boolean;
+    /** @type {boolean} */
+    Right: boolean;
+    /**
+     * @param {PeekAction} action
+     */
+    peekCamera(action: PeekAction): void;
+    /**
+     * @returns {PeekState}
+     */
+    toPeekState(): PeekState;
+}
+import type { PeekAction } from './constants';
+import type { PeekState } from './constants';

package/types/webComponent/constants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @typedef CameraOptions
+ * @property {number} [cameraSpeedMs]
+ */
+/**
+ * @typedef {typeof AnimationStyles[keyof typeof AnimationStyles]} AnimationStyle
+ */
+export const AnimationStyles: Readonly<{
+    Exponential: "exponential";
+    Linear: "linear";
+    Next: "next";
+    Fixed: "fixed";
+    Match: "match";
+}>;
+/**
+ * @typedef {typeof PeekStates [keyof typeof PeekStates]} PeekState
+ */
+export const PeekStates: Readonly<{
+    RightUp: "rightUp";
+    RightDown: "rightDown";
+    LeftUp: "leftUp";
+    LeftDown: "leftDown";
+}>;
+/**
+ * @typedef {typeof PeekActions [keyof typeof PeekActions]} PeekAction
+ */
+export const PeekActions: Readonly<{
+    Horizontal: "horizontal";
+    Vertical: "vertical";
+    Right: "right";
+    Left: "left";
+    Up: "up";
+    Down: "down";
+    RightUp: "rightUp";
+    RightDown: "rightDown";
+    LeftUp: "leftUp";
+    LeftDown: "leftDown";
+}>;
+export namespace AttributeNames {
+    let cubeType: "cube-type";
+    let pieceGap: "piece-gap";
+    let animationSpeed: "animation-speed-ms";
+    let animationStyle: "animation-style";
+    let cameraSpeed: "camera-speed-ms";
+    let cameraRadius: "camera-radius";
+    let cameraFieldOfView: "camera-field-of-view";
+    let cameraPeekAngleHorizontal: "camera-peek-angle-horizontal";
+    let cameraPeekAngleVertical: "camera-peek-angle-vertical";
+    let logo: "logo";
+}
+export type CameraOptions = {
+    cameraSpeedMs?: number;
+};
+export type AnimationStyle = (typeof AnimationStyles)[keyof typeof AnimationStyles];
+export type PeekState = (typeof PeekStates)[keyof typeof PeekStates];
+export type PeekAction = (typeof PeekActions)[keyof typeof PeekActions];
+export type AttributeName = (typeof AttributeNames)[keyof typeof AttributeNames];

package/types/webComponent/index.d.ts

@@ -0,0 +1,6 @@
+export { RubiksCubeElement } from "./rubiksCubeElement";
+export type PeekState = import("./constants").PeekState;
+export type PeekAction = import("./constants").PeekAction;
+export type CameraOptions = import("./constants").CameraOptions;
+export type AnimationStyle = import("./constants").AnimationStyle;
+export { AttributeNames, PeekStates, PeekActions, AnimationStyles } from "./constants";

package/types/webComponent/rubiksCubeElement.d.ts

@@ -0,0 +1,89 @@
+/// <reference path="globals.d.ts" preserve="true" />
+export class RubiksCubeElement extends HTMLElement {
+    /**
+     * @param {string} tagName the name of the tag to register the web component under
+     */
+    static register(tagName?: string): void;
+    static get observedAttributes(): ("cube-type" | "piece-gap" | "animation-speed-ms" | "animation-style" | "camera-speed-ms" | "camera-radius" | "camera-field-of-view" | "camera-peek-angle-horizontal" | "camera-peek-angle-vertical" | "logo")[];
+    /** @private @type {HTMLCanvasElement} */
+    private canvas;
+    /** @private @type {Settings} */
+    private settings;
+    /** @private @type {RubiksCube3D?} */
+    private _rubiksCube3D;
+    /** @private @type {RubiksCubeController?} */
+    private _rubiksCube;
+    connectedCallback(): void;
+    /**
+     * @param {string} name
+     * @param {string?} oldVal
+     * @param {string?} newVal
+     *  */
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    /** @private */
+    private animateCameraSetting;
+    /** @private */
+    private animateCameraRadius;
+    /** @private */
+    private updateCameraFOV;
+    /** @internal @typedef {{eventId: string, move: Movement, reason: string}} MovementFailedEventData */
+    /**
+     * @param {Movement} move
+     * @param {AnimationOptions} [options]
+     * @returns {Promise<string>}
+     */
+    move(move: Movement, options?: AnimationOptions): Promise<string>;
+    /**
+     * @param {Rotation} rotation
+     * @param {AnimationOptions} [options]
+     * @returns {Promise<string>}
+     */
+    rotate(rotation: Rotation, options?: AnimationOptions): Promise<string>;
+    /**
+     * @returns {string}
+     */
+    reset(): string;
+    /**
+     * @param {string} kociembaState
+     * @returns {boolean}
+     */
+    setState(kociembaState: string): boolean;
+    /**
+     * @returns {string}
+     */
+    getState(): string;
+    /**
+     * @param {CubeType} cubeType
+     * @returns {string}
+     */
+    setType(cubeType: CubeType): string;
+    /**
+     * @private
+     **/
+    private _rebuild;
+    /** @internal @typedef {{eventId: string, action: PeekAction, options: CameraOptions?}} CameraPeekEventData */
+    /** @internal @typedef {{eventId: string, peekState: PeekState }} CameraPeekCompleteEventData */
+    /**
+     * Animates the camera to a new "peek" position.
+     *
+     * The camera tracks two independent boolean axes (horizontal: Right/Left, vertical: Up/Down), giving four
+     * reachable positions (the {@link PeekState}s). Each `PeekAction` operates on this state machine: actions like
+     * `RightUp` set both axes; `Up`/`Right`/`Left`/`Down` set one axis and leave the other untouched;
+     * `Horizontal`/`Vertical` toggle one axis relative to its current value. The result of a partial action
+     * therefore depends on the current peek state.
+     *
+     * @param {PeekAction} action
+     * @param {CameraOptions?} options
+     * @returns {Promise<PeekState>}
+     */
+    peek(action: PeekAction, options?: CameraOptions | null): Promise<PeekState>;
+    /** @private */
+    private init;
+}
+import type { Movement } from '../core';
+import type { AnimationOptions } from '../rubiksCube';
+import type { Rotation } from '../core';
+import type { CubeType } from '../core';
+import type { PeekAction } from './constants';
+import type { CameraOptions } from './constants';
+import type { PeekState } from './constants';

package/types/{settings.d.ts → webComponent/settings.d.ts}

@@ -1,10 +1,6 @@
 export default class Settings {
-    /** @type {number} */
-    pieceGap: number;
-    /** @type {number} */
-    animationSpeedMs: number;
-    /** @type {import("./cube/cubeSettings").AnimationStyle} */
-    animationStyle: import("./cube/cubeSettings").AnimationStyle;
+    /** @type {RubiksCube3DSettings} */
+    rubiksCube3DSettings: RubiksCube3DSettings;
     /** @type {number} */
     cameraSpeedMs: number;
     /** @type {number} */
@@ -15,12 +11,14 @@ export default class Settings {
     cameraPeekAngleHorizontal: number;
     /** @type {number} */
     cameraPeekAngleVertical: number;
+    /** @param {any} value */
+    setCubeType(value: any): void;
     /** @param {string | null} value*/
     setPieceGap(value: string | null): void;
     /** @param {string | null} value in ms */
     setAnimationSpeed(value: string | null): void;
-    /** @param {string | null} value */
-    setAnimationStyle(value: string | null): void;
+    /** @param {any} value */
+    setAnimationStyle(value: any): void;
     /** @param {string | null} value in ms */
     setCameraSpeed(value: string | null): void;
     /** @param {string | null} value */
@@ -31,4 +29,7 @@ export default class Settings {
     setCameraPeekAngleVertical(value: string | null): void;
     /** @param {string | null} value in ms */
     setCameraFieldOfView(value: string | null): void;
+    /** @param {string | null} value in ms */
+    setLogo(value: string | null): void;
 }
+import RubiksCube3DSettings from '../rubiksCube3D/cubeSettings';

package/src/core.js

@@ -1,127 +0,0 @@
-// @ts-check
-/**
- * @typedef {typeof Movements[keyof typeof Movements]} Movement
- */
-export const Movements = Object.freeze({
-    R: 'R',
-    R2: 'R2',
-    RP: "R'",
-    L: 'L',
-    L2: 'L2',
-    LP: "L'",
-    U: 'U',
-    U2: 'U2',
-    UP: "U'",
-    D: 'D',
-    D2: 'D2',
-    DP: "D'",
-    F: 'F',
-    F2: 'F2',
-    FP: "F'",
-    B: 'B',
-    B2: 'B2',
-    BP: "B'",
-    // Wide moves
-    r: 'r',
-    r2: 'r2',
-    rP: "r'",
-    l: 'l',
-    l2: 'l2',
-    lP: "l'",
-    u: 'u',
-    u2: 'u2',
-    uP: "u'",
-    d: 'd',
-    d2: 'd2',
-    dP: "d'",
-    f: 'f',
-    f2: 'f2',
-    fP: "f'",
-    b: 'b',
-    b2: 'b2',
-    bP: "b'",
-    // Slice moves
-    M: 'M',
-    M2: 'M2',
-    MP: "M'",
-    E: 'E',
-    E2: 'E2',
-    EP: "E'",
-    S: 'S',
-    S2: 'S2',
-    SP: "S'",
-});
-
-/**
- * @typedef {typeof Rotations[keyof typeof Rotations]} Rotation
- */
-export const Rotations = Object.freeze({
-    x: 'x',
-    x2: 'x2',
-    xP: "x'",
-    y: 'y',
-    y2: 'y2',
-    yP: "y'",
-    z: 'z',
-    z2: 'z2',
-    zP: "z'",
-});
-
-/**
- * @typedef {typeof Axi[keyof typeof Axi]} Axis
- */
-export const Axi = Object.freeze({
-    x: 'x',
-    y: 'y',
-    z: 'z',
-});
-
-/**
- * @typedef {typeof Faces [keyof typeof Faces]} Face
- */
-export const Faces = Object.freeze({
-    up: 'U',
-    down: 'D',
-    left: 'L',
-    right: 'R',
-    front: 'F',
-    back: 'B',
-});
-
-/**
- * @typedef {typeof FaceColours [keyof typeof FaceColours]} FaceColour
- */
-export const FaceColours = Object.freeze({
-    up: 'white',
-    down: 'yellow',
-    left: 'orange',
-    right: 'red',
-    front: 'green',
-    back: 'blue',
-});
-
-/**
- * @typedef {typeof PeekTypes [keyof typeof PeekTypes]} PeekType
- */
-export const PeekTypes = Object.freeze({
-    Horizontal: 'horizontal',
-    Vertical: 'vertical',
-    Right: 'right',
-    Left: 'left',
-    Up: 'up',
-    Down: 'down',
-    RightUp: 'rightUp',
-    RightDown: 'rightDown',
-    LeftUp: 'leftUp',
-    LeftDown: 'leftDown',
-});
-
-/**
- * @typedef {typeof PeekStates [keyof typeof PeekStates]} PeekState
- */
-export const PeekStates = Object.freeze({
-    RightUp: 'rightUp',
-    RightDown: 'rightDown',
-    LeftUp: 'leftUp',
-    LeftDown: 'leftDown',
-});