@shopware-ag/dive 1.19.1-beta.0 → 1.19.1-beta.10

package/README.md

@@ -1,12 +1,3 @@
-<!--
-
-
-This file is automatically generated
-You can find the template in ci/readme/template/TEMPLATE_README.md
-
-
--->
-
 <p align="center">
     <img alt="DIVE logo" src="./assets/svg/dive.svg" style="width: 100%; height: auto; max-height: 500px;">
 </p>
@@ -28,23 +19,23 @@ You can find the template in ci/readme/template/TEMPLATE_README.md
 
 ## Table of Contents
 
-1. [About](#about)
-2. [Installation](#installation)
-3. [Local development](#local-development)
-4. [Setup in Shopware](#setup-in-shopware)
-5. [Usage](#usage)
-6. [Unit Tests](#unit-tests)
-7. [Formatting](#formatting)
+- [Table of Contents](#table-of-contents)
+- [About](#about)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+  - [Basic Setup](#basic-setup)
+  - [Quick View](#quick-view)
+- [Modules](#modules)
+- [Documentation](#documentation)
 
 ## About
 
-DIVE is a spatial framework made by and optimized for Shopware. It can be used
-directly integrated in a Shopware frontend such as Storefront or in any other
-frontend you want to use it in, it is not tied to Shopware.
+DIVE is a spatial framework made by and optimized for Shopware. It can be used directly integrated
+in a Shopware frontend such as Storefront or in any other frontend you want to use it in, it is not
+tied to Shopware.
 
-DIVE supplies your frontend application with all needed tooling to set up a
-basic 3D application with event-based controls called "Actions". For further
-information, see [Getting started](#getting-started).
+DIVE supplies your frontend application with all needed tooling to set up a basic 3D application
+with event-based controls called "Actions".
 
 ## Installation
 
@@ -58,492 +49,63 @@ or
 yarn add @shopware-ag/dive
 ```
 
-## Local development
-
-### with devenv
-
-If you are using `devenv`, you have to make sure that you are in the correct shell while linking. `nix` (what `devenv` is
-based on) uses it's own instances of `npm` so we need to make sure that the `npm link` get's executed within the correct `devenv` environment a.k.a `nix/store`.
-To make sure you are using the correct instance of `npm` you have to browse to your `devenv` project:
-
-```bash
-cd path/to/your/devenv.nix
-```
-
-#### with direnv
-
-If you use `direnv` you should be launched into the correct shell automatically.
-
-#### without direnv
-
-If you don't use `direnv` you can start the correct shell manually by running
-
-```bash
-devenv shell
-```
-
-Within the `devenv shell` you have to browse to your DIVE folder
+For local development setup, see [Local Development Guide](./docs/local-development.md).
 
-```bash
-cd path/to/@shopware-ag/dive
-```
-
-### without devenv
+## Getting Started
 
-You don't have to do anything special if you don't use `devenv`.
+### Basic Setup
 
-### npm link
-
-If you want to link DIVE package locally after checking out, you can to that in the package's project folder:
-
-```bash
-cd path/to/@shopware-ag/dive
-npm link
-```
-
-After registering the package in npm, you can use the sym-link in your project:
-
-```bash
-cd path/to/your/package.json
-npm link @shopware-ag/dive
-```
-
-After successfully linking DIVE into your project you will find the according sym-link in your `node_modules`.
-
-## Setup in Shopware
-
-Don't forget to include DIVE in your `webpack.config.js`:
-
-```js
-const path = require('path');
-
-module.exports = () => {
-    return {
-        // Other configurations...
-        resolve: {
-            extensions: [
-                '.ts',
-                '.cjs',
-                '.js',
-            ],
-            alias: {
-                three: path.resolve(__dirname, 'path/to/node_modules/three'),
-                '@shopware-ag/dive': path.resolve(
-                    __dirname,
-                    'path/to/node_modules/@shopware-ag/dive',
-                ),
-            },
-        },
-        module: {
-            rules: [
-                // Other rules...
-                {
-                    test: /\.(js|ts)$/,
-                    loader: 'swc-loader',
-                    include: [
-                        path.resolve(__dirname, 'path/to/node_modules/three'),
-                        path.resolve(
-                            __dirname,
-                            'path/to/node_modules/@shopware-ag/dive',
-                        ),
-                    ],
-                    options: {
-                        jsc: {
-                            parser: {
-                                syntax: 'typescript',
-                            },
-                            target: 'es2022',
-                        },
-                    },
-                },
-                // Other rules...
-            ],
-        },
-    };
-};
-```
-
-## Usage
-
-### Quick View
-
-QuickView is used to quickly display your assets with as few lines of code as
-possible. Simply call the static `QuickView()` method, with your data URI as a
-parameter, to create an instance of DIVE with your asset to use in further code.
+To get started with DIVE, import and instantiate it:
 
 ```ts
 import { DIVE } from '@shopware-ag/dive';
 
-const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
-
+// Create a DIVE instance
+const dive = new DIVE();
 const myCanvasWrapper = document.createElement('div');
-myCanvasWrapper.appendChild(dive.Canvas);
+myCanvasWrapper.appendChild(dive.canvas);
 ```
 
-### Example with Error Handling:
-
-```ts
-import { DIVE } from '@shopware-ag/dive';
-
-try {
-    const dive = DIVE.QuickView('your/asset/uri.glb'); // <-- call QuickView()
-
-    const myCanvasWrapper = document.createElement('div');
-    myCanvasWrapper.appendChild(dive.Canvas);
-} catch (error) {
-    console.error('Failed to load asset:', error);
-}
-```
-
-### Getting started
-
-#### Import:
-
-```ts
-import { DIVE } from '@shopware-ag/dive'; // <-- import DIVE
-```
+### Quick View
 
-#### Instantiate:
+For a simpler setup, you can use QuickView to quickly display your assets within a basic default
+scene setup:
 
 ```ts
 import { DIVE } from '@shopware-ag/dive';
 
-const dive = new DIVE(); // <-- instantiate DIVE
-```
-
-DIVE supplies your application with a HTMLCanvasElement that it uses as a render
-target. After instantiating, you can use the supplied canvas within your frontend
-code to attach it to your DOM.
-
-```ts
-const dive = new DIVE();
-
-const myCanvasWrapper = document.createElement('div'); // <-- create wrapper element
-myCanvasWrapper.appendChild(dive.Canvas); // <-- reference DIVE canvas
-```
-
-To interact with your newly created DIVE instance you have to perform actions
-via DIVECommunication. For further information, see [Actions](#actions).
-
-```ts
-const dive = new DIVE();
-
+// Use static QuickView method to instantiate DIVE
+const dive = await DIVE.QuickView('your/asset/uri.glb');
 const myCanvasWrapper = document.createElement('div');
-myCanvasWrapper.appendChild(dive.Canvas);
-
-const com = dive.Communication; // <-- reference DIVECommunication
-
-com.PerformAction('SET_CAMERA_TRANSFORM', {
-    // <-- perform action on DIVECommunication
-    position: { x: 0, y: 2, z: 2 },
-    target: { x: 0, y: 0.5, z: 0 },
-});
+myCanvasWrapper.appendChild(dive.canvas);
 ```
 
-### Actions
-
-Actions symbolize the communication between frontend and 3D space. All actions
-can be performed anywhere, no matter if you are in frontend or 3D.
-
-In addition to the impact that specific actions have, every action can be
-subscribed to.
+## Modules
 
-```ts
-const myCanvasWrapper = document.createElement('div');
-const dive = new DIVE();
-
-myCanvasWrapper.appendChild(dive.Canvas);
-
-const com = dive.Communication;
-
-com.Subscribe('SET_CAMERA_TRANSFORM', () => {
-    // <-- add subscription
-    // do something
-});
-
-com.PerformAction('SET_CAMERA_TRANSFORM', {
-    position: { x: 0, y: 2, z: 2 },
-    target: { x: 0, y: 0.5, z: 0 },
-});
-```
-
-Subscribing to an action returns a `unsubscribe()`-callback that should be
-executed when not needed anymore.
+DIVE comes with several built-in modules that provide specific functionality. Served modules are
+independent and can be accessed directly from the modules directory:
 
 ```ts
-const myCanvasWrapper = document.createElement('div');
-const dive = new DIVE();
-
-myCanvasWrapper.appendChild(dive.Canvas);
-
-const com = dive.Communication;
+import { ARSystem } from '@shopware-ag/dive/modules/ARSystem';
 
-const unsubscribe = com.Subscribe('SET_CAMERA_TRANSFORM', () => {
-    // <-- save unsubscribe callback
-    // do something
+// Initialize AR with options
+const arSystem = new ARSystem();
+await arSystem.launch('path/to/model.glb', {
+    arPlacement: 'horizontal', // or 'vertical'
+    arScale: 'auto' // or 'fixed'
 });
-
-com.PerformAction('SET_CAMERA_TRANSFORM', {
-    position: { x: 0, y: 2, z: 2 },
-    target: { x: 0, y: 0.5, z: 0 },
-});
-
-unsubscribe(); // <-- execute unsubscribe callback when done
 ```
 
-#### Actions List
-
-In the following you find a list of all available actions to perform on
-DIVECommunication class via
-[`com.PerformAction()`](https://github.com/shopware/dive/blob/2e193c58843939ce07a1d35bfbd5b3c9d26eeeca/src/com/Communication.ts#L85).
-
-<table>
-    <tr>
-        <th>Actions</th>
-        <th>Description</th>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/addobject.ts"> ADD_OBJECT </a>
-        </td>
-        <td>
-            Adds an object to the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/computeencompassingview.ts"> COMPUTE_ENCOMPASSING_VIEW </a>
-        </td>
-        <td>
-            Calculates the camera position and target to view the whole scene. (experimental)
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/deleteobject.ts"> DELETE_OBJECT </a>
-        </td>
-        <td>
-            Deletes an object from the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/deselectobject.ts"> DESELECT_OBJECT </a>
-        </td>
-        <td>
-            Deselects an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/dropit.ts"> DROP_IT </a>
-        </td>
-        <td>
-            Places an object on top of an underlying object or the floor.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/exportscene.ts"> EXPORT_SCENE </a>
-        </td>
-        <td>
-            Exports the current scene to a blob and returns the URL.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/media/generatemedia.ts"> GENERATE_MEDIA </a>
-        </td>
-        <td>
-            Generates a screenshot, stores it in a Blob and returns a Promise of a valid URI.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/getallobjects.ts"> GET_ALL_OBJECTS </a>
-        </td>
-        <td>
-            Retrieves all objects in the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/getallscenedata.ts"> GET_ALL_SCENE_DATA </a>
-        </td>
-        <td>
-            Retrieves all current scene data.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/getcameratransform.ts"> GET_CAMERA_TRANSFORM </a>
-        </td>
-        <td>
-            Returns the current camera position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/getobjects.ts"> GET_OBJECTS </a>
-        </td>
-        <td>
-            Returns a list of objects of given IDs.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/launchar.ts"> LAUNCH_AR </a>
-        </td>
-        <td>
-            Launches AR mode in native capabilities. (iOS: AR Quick Look, Android: Google Scene Viewer)
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/modelloaded.ts"> MODEL_LOADED </a>
-        </td>
-        <td>
-            Is triggered when a model is loaded.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/movecamera.ts"> MOVE_CAMERA </a>
-        </td>
-        <td>
-            Moves the camera to a new position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/model/placeonfloor.ts"> PLACE_ON_FLOOR </a>
-        </td>
-        <td>
-            Places an object on the floor.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/resetcamera.ts"> RESET_CAMERA </a>
-        </td>
-        <td>
-            Reset the camera to its initial position and rotation.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/selectobject.ts"> SELECT_OBJECT </a>
-        </td>
-        <td>
-            Selects an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/setbackground.ts"> SET_BACKGROUND </a>
-        </td>
-        <td>
-            Set the background color of the scene.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/setcameralayer.ts"> SET_CAMERA_LAYER </a>
-        </td>
-        <td>
-            Sets the camera layer to a certain layer.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/setcameratransform.ts"> SET_CAMERA_TRANSFORM </a>
-        </td>
-        <td>
-            Sets the camera position and target.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/select/setgizmomode.ts"> SET_GIZMO_MODE </a>
-        </td>
-        <td>
-            Sets the gizmo's mode.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/transform/setgizmoscalelinked.ts"> SET_GIZMO_SCALE_LINKED </a>
-        </td>
-        <td>
-            Sets the gizmo's unified scale mode.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/transform/setgizmovisible.ts"> SET_GIZMO_VISIBILITY </a>
-        </td>
-        <td>
-            Sets the gizmo's visibility.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/setparent.ts"> SET_PARENT </a>
-        </td>
-        <td>
-            Attach an object to another object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/renderer/startrender.ts"> START_RENDER </a>
-        </td>
-        <td>
-            Starts the render process.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/object/updateobject.ts"> UPDATE_OBJECT </a>
-        </td>
-        <td>
-            Updates an existing object.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/scene/updatescene.ts"> UPDATE_SCENE </a>
-        </td>
-        <td>
-            Updates global scene data.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/toolbox/usetool.ts"> USE_TOOL </a>
-        </td>
-        <td>
-            Activates a specific tool from the toolbox.
-        </td>
-    </tr>
-    <tr>
-        <td>
-            <a href="src/com/actions/camera/zoomcamera.ts"> ZOOM_CAMERA </a>
-        </td>
-        <td>
-            Zooms the camera in or out by a certain amount.
-        </td>
-    </tr>
-</table>
-
-## Unit Tests
-
-All relevant files are covered by Jest tests. If you find any file that has not been covered yet, feel free to add unit tests accordingly.
-
-If there are any modules that have to be mocked (like `three`) you can create a given file in the `__mocks__` folder in project root. Jest manages to mock modules with a given file with the modules name as a file name (for example `three.ts`). Every export will be part of the modules mock. You don't need to mock the module in your test anymore, you only extend the module mock.
+For detailed information about the module system, see
+[Module System Documentation](docs/module-system.md).
 
-If you have any other things from a module to import, you can simply create a folder structure and place the mock file at the end of your structure. To understand better please take a look at the `__mocks__` folder for yourself.
+## Documentation
 
-## Formatting
+For detailed documentation, please refer to the following sections:
 
-DIVE uses Prettier as a preconfigured formatter.
+- [Module System](docs/module-system.md) - Detailed module system architecture and usage
+- [Shopware Integration](docs/shopware-integration.md) - Integration with Shopware projects
+- [Testing and Quality Assurance](docs/testing.md) - Testing guidelines and best practices
+- [Local Development](docs/local-development.md) - Local development setup and workflow
+- [Module Reference](docs/module-reference.md) - Complete list of available modules
+- [Actions Reference](docs/actions-reference.md) - Complete list of available actions