Merge pull request #64 from smplrspace/next

v2.17.0

docs/api-reference/space/custom-ux.md

@@ -74,6 +74,7 @@ space.startViewer({
   },
   disableCameraControls?: boolean,
   disableCameraRotation?: boolean,
+  autoRotate?: boolean,
   hideNavigationButtons?: boolean
 }) => void
 ```
@@ -85,6 +86,7 @@ space.startViewer({
 - `cameraPlacement` - _optional_ - set the initial position and direction of the camera. See [camera controls](./custom-ux#camera-controls) for more details.
 - `disableCameraControls` - _optional_ - set this to true so the camera placement cannot be changed by the user. This disables mouse, touch and keyboard inputs as well as removes the zoom control buttons. _Default value: false_
 - `disableCameraRotation` - _optional_ - set this to true to force a top view of the scene. It essentially gets the interactivity to match the 2D mode, but in 3D mode. _Default value: false_
+- `autoRotate` - _optional_ - set this to true to have the viewer spin around the space automatically. You can also start, set the rotation speed, and stop the rotation as described [below](#auto-rotate-the-viewer). _Default value: false_
 - `hideNavigationButtons` - _optional_ - set this to true if you want the user to control the camera but want to remove the navigation buttons. Mouse, touch and keyboard inputs will work while the buttons are hidden. _Default value: false_
 
 ## Viewer controls
@@ -99,6 +101,16 @@ space.updateRenderOptions(options: RenderOptions) => void
 
 - `options` is an object of the [`RenderOptions`](#render-options) interface, which is deeply merged with the current options used by the viewer. To "unset" an optional value, you can pass `undefined` explicitely.
 
+### Switch between 2D and 3D
+
+To programatically switch between 2D and 3D modes without restarting the viewer, you can call:
+
+```ts
+space.setMode(mode: '2d' | '3d') => void
+```
+
+- `mode` - the desired rendering mode.
+
 ### Navigate levels
 
 This is the programmatic equivalent to pressing the level buttons in the bottom-left controls:
@@ -199,6 +211,22 @@ space.zoomIn() => void
 space.zoomOut() => void
 ```
 
+### Auto-rotate the viewer
+
+You can get the viewer to spin around the building at a certain speed. To start the rotation:
+
+```ts
+space.startAutoRotation(speed?: number) => void
+```
+
+- `speed` - _optional_ - sets how fast the rotation goes. _Default value: 0.8_.
+
+To stop the rotation:
+
+```ts
+space.stopAutoRotation() => void
+```
+
 ## Reacting to events from the viewer
 
 You can add event listeners on the viewer to react to interactions happenning in it. The list of event types that can be observed is limited at the moment, and we'll be adding more based on users needs and demand.

docs/api-reference/space/space.md

@@ -38,6 +38,7 @@ To initiate an interactive viewer session, use the following code.
 space.startViewer({
   preview?: boolean,
   loadingMessage?: string,
+  renderingMessage?: string,
   mode?: '2d' | '3d',
   allowModeChange?: boolean,
   onModeChange?: (mode: '2d' | '3d') => void,
@@ -46,20 +47,23 @@ space.startViewer({
   onResize?: (containerRect: DOMRect) => void,
   onVisibleLevelsChanged?: (visibleLevels: number[]) => void
   ...customUX: object
-}) => void
+}) => Promise<void>
 ```
 
 - `preview` - _optional_ - starts by a preview image with a play button similar to YouTube embed. It is advisable to use [our ESM bundle](/#esm-bundle-supports-runtime-tree-shaking) to ensure a quick initial render. _Default value: false_.
 - `loadingMessage` - _optional_ - lets you override the text displayed while the space is loading. _Default value: "Loading your space"_.
+- `renderingMessage` - _optional_ - lets you override the text displayed when the space is loaded but still rendering. _Default value: same as loadingMessage_.
 - `mode` - _optional_ - lets you choose between 2D and 3D rendering. _Default value: 3d_.
 - `allowModeChange` - _optional_ - set this to true to allow users to switch between 2D and 3D. _Default value: false_.
 - `onModeChange` - _optional_ - is called whenever the user changes the mode. Requires allowModeChange to be set to true.
-- `onReady` - _optional_ - is called once the viewer's initial render is done.
-- `onError` - _optional_ - is called if an error occur while starting the viewer.
+- `onReady` - _optional_ - is called once the viewer's initial render is done. You may alternatively use the promise returned by startViewer, which resolves when the viewer is ready.
+- `onError` - _optional_ - is called if an error occur while starting the viewer. You may alternatively use the promise returned by startViewer to catch errors.
 - `onResize` - _optional_ - is called whenever the viewer is resized, including after the initial render, when the window is resized, or on mobile when the device is rotated between vertical to horizontal positions. This can be used to reposition custom tooltips (e.g.).
 - `onVisibleLevelsChanged` - _optional_ - is called whenever there is a change in the visible levels. This could be through the user clicking the level picker, or through an API call of [`showUpToLevel`](/api-reference/space/custom-ux#navigate-levels). It is also called when the space first renders. The handler take a single argument `visibleLevels`, which is the ordered list of zero-based level indices currently visible in the viewer. The last element in that list is always the highest visible level.
 - `...customUX` represents additional options that let you customise the user experience as documented in the [custom UX](./custom-ux#viewer-options) page.
 
+Calling `startViewer` returns a `Promise` ([MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)) which resolves when the viewer is ready. This lets you use `Promise.then().catch()` or `async/await` with a `try/catch` block to react when the viewer is ready, or to handle errors that may occur. It is an alternative to providing `onReady` and `onError` callback methods. You may choose the option that suits the most your environment or coding style.
+
 Although not a rule not to break, we generally _recommend_ to use `preview: true` as this avoids loading the space if the user do not intend to interact with it. It also helps with reducing the number of views counted on your spaces.
 
 ### Stop the viewer
@@ -164,3 +168,11 @@ space.removeDataLayer(id: string) => void
 - `id` is the identifier of the layer to remove.
 
 An equivalent method is `remove` on a [data layer controller](./data-layers#data-layer-controller).
+
+### Remove all layers
+
+Removing all data layers at once is done as follow.
+
+```ts
+space.removeAllDataLayers() => void
+```

docusaurus.config.js

@@ -97,6 +97,10 @@ const config = {
   ],
 
   scripts: [
+    {
+      src: '/js/hotkey.js',
+      async: false
+    },
     process.env.NODE_ENV === 'production'
       ? {
         src: 'https://deep-positive.smplrspace.com/script.js',

static/js/hotkey.js

@@ -0,0 +1,11 @@
+// Ctrl + K should focus the search bar
+document.onkeydown = function (e) {
+  if (e.ctrlKey && e.key === 'k') {
+    const search = document.getElementsByClassName('navbar__search-input')[0]
+    if (search) {
+      search.focus()
+    }
+    // By default, using Ctrl + K in Chrome will open the location bar, so disable this
+    e.preventDefault()
+  }
+}