Merge pull request #87 from smplrspace/next

v2.29.0

Author: tibotiber

docs/api-reference/editor/editor.md

@@ -21,19 +21,21 @@ const editor = new smplr.Editor({
     picture?: string
   }
   clientToken: string
-  containerId: string
+  containerId?: string
+  container?: HTMLElement
   disableErrorReporting?: boolean
   whiteLabel?: boolean
 }) => Editor
 ```
 
-- `spaceId` is the unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` is the unique identifier of the space in Smplrspace, something like "spc_xxx". Refer to the [page on SIDs](/guides/sid) to learn more.
 - `user` is an object used to identify who is making the changes on the space.
   - `id` is a required unique identifier for the user. It does not represent anything on the Smplrspace side, it should most likely be your own internal `id`. It is used to track who made the changes.
   - `name` is an optional user-readable name for the user. The value is used in the Smplrspace app to indicate who made the changes. If you decide not to indicate the name, the app will indicate that "Someone" made the changes. This is purely an optional to improve your team's user experience of the Smplrspace app.
   - `picture` is an optional URL used as the avatar of the person who made changes in the app. If you decide not to provide a picture, the avatar will not be displayed in the app. This is purely an optional to improve your team's user experience of the Smplrspace app.
 - `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. [More info](/guides/embedding#client-tokens).
 - `containerId` is the "id" of the html "div" container where smplr.js should render the editor, something like "smplr-container" that can be found in your html. Only ids are supported, not classes.
+- `container` is an alternative to `containerId` that lets you provide the HTML element directly instead of an id.
 - `disableErrorReporting` - _optional_ - can be set to "true" to disable the automated reporting of errors to our 3rd party error tracking tool, [Sentry](https://sentry.io/). We have discovered that Sentry's instrumentation could make it seem as if all network requests originated from smplr.js. Unfortunately, there is nothing simple we can do on our side to avoid that. If this is an issue for you, you can disable Sentry altogether. The tradeoff is that we will not automatically detect errors hapenning in your integration, and you may need to be more proactive to report them for us to roll out fixes.
 - `whiteLabel` - _optional_ - can be set to "true" to remove the "Powered by Smplrspace" attribution from the editor. This is a paid add-on. You can check if it is enabled from the Organization settings page. [Get in touch](mailto:hello@smplrspace.com) to learn more. _Note: there is currently no attribution in the editor, but there might be in the future._
 

docs/api-reference/map/buildings.md

@@ -17,7 +17,7 @@ To fetch spaces from your Smplrspace account and render them on the map, call th
 map.addSpacesById(spaceIds: string[]) => void
 ```
 
-- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "spc_xxx".
 
 ### Remove spaces by ID
 
@@ -27,7 +27,7 @@ To remove specific spaces from the map, call this function:
 map.removeSpacesById(spaceIds: string[]) => void
 ```
 
-- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceIds` - unique identifiers of the spaces in Smplrspace, something like "spc_xxx".
 
 ### Remove all spaces
 

docs/api-reference/map/map.md

@@ -14,14 +14,16 @@ To create a Map instance, initialise it as follow.
 
 ```ts
 const map = new smplr.Map({
-  clientToken: string,
-  containerId: string,
-  disableErrorReporting?: boolean,
+  clientToken: string
+  containerId?: string
+  container?: HTMLElement
+  disableErrorReporting?: boolean
 }) => Map
 ```
 
 - `clientToken` is an API token that is used to authenticate client-side requests. It is safe to have it exposed in your client code. You can manage your organisation's tokens in the Smplrspace app, by heading to the Developers page from the main menu. [More info](/guides/embedding#client-tokens).
 - `containerId` is the "id" of the html "div" container where smplr.js should render the viewer, something like "smplr-container" that can be found in your html. Only ids are supported, not classes.
+- `container` is an alternative to `containerId` that lets you provide the HTML element directly instead of an id.
 - `disableErrorReporting` - _optional_ - can be set to "true" to disable the automated reporting of errors to our 3rd party error tracking tool, [Sentry](https://sentry.io/). We have discovered that Sentry's instrumentation could make it seem as if all network requests originated from smplr.js. Unfortunately, there is nothing simple we can do on our side to avoid that. If this is an issue for you, you can disable Sentry altogether. The tradeoff is that we will not automatically detect errors hapenning in your integration, and you may need to be more proactive to report them for us to roll out fixes.
 
 ## Interactive map viewer session
@@ -44,12 +46,12 @@ map.startViewer({
 }) => Promise<void>
 ```
 
-- `spaceIds` - _optional_ - lets you specify the Smplrspace ID of the spaces to render on the map when initializing the viewer. You can also do that dynamically as described on the [Building page](/api-reference/map/buildings).
+- `spaceIds` - _optional_ - lets you specify the Smplrspace ID ("spc_xxx") of the spaces to render on the map when initializing the viewer. You can also do that dynamically as described on the [Building page](/api-reference/map/buildings).
 - `osmBuildings` - _optional_ - lets you choose whether to render or not cities in 3D. City buildings data comes from OpenStreetMap and is automatically rendered in 3D. You can also do that dynamically as described in [3D cities](/api-reference/map/buildings#3d-cities). _Default value: true_.
 - `hash` - _optional_ - lets you choose whether to automatically sync the map location to the hash fragment of the page's URL. This makes it for easy to share links to specific map locations. It relies on Mapbox's corresponding [parameter](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters). _Default value: false_.
-- `fitNewSpacesInScreen` - _optional_ - lets you choose whether to automatically recenter the map to fit all the spaces when the spaces rendered on the map change. You can also center the map using [`fitAllSpacesInScreen`](#fit-all-spaces-in-screen). \_Default value: true.
+- `fitNewSpacesInScreen` - _optional_ - lets you choose whether to automatically recenter the map to fit all the spaces when the spaces rendered on the map change. You can also center the map using [`fitAllSpacesInScreen`](#fit-all-spaces-in-screen). _Default value: true._
 - `loadingMessage` - _optional_ - lets you override the text displayed while the space is loading. This can be change dynamically as well, see [UI controls](#ui-controls). _Default value: "Loading map"_.
-- `forceLoader` - _optional_ - provides programmatic control to whether the loader should be displayed or not. By default we display it while loading the map and initial spaces provided by `spaceIds`, but you can control this if you load your own data as well. This can be change dynamically as well, see [UI controls](#ui-controls). \_Default value: false.
+- `forceLoader` - _optional_ - provides programmatic control to whether the loader should be displayed or not. By default we display it while loading the map and initial spaces provided by `spaceIds`, but you can control this if you load your own data as well. This can be change dynamically as well, see [UI controls](#ui-controls). _Default value: false._
 - `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.
 - `onSpaceClick` - _optional_ - is called when the user clicks a 3D space, and provide data about which space and which level where clicked.
@@ -78,7 +80,7 @@ You can change automatically "fly" the map to a specific space, by providing the
 map.flyToSpace(spaceId: string) => void
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 
 ### Fit all spaces in screen
 

docs/api-reference/queryclient/doors-windows.md

@@ -28,7 +28,7 @@ interface Opening {
 ```
 
 - `id` - unique identifier of this particular opening.
-- `name` - name given to the furniture in the editor. It could be an empty string.
+- `name` - name given to the opening in the editor. It could be an empty string.
 - `dimensions.width` - horizontal width of the opening in centimeters.
 - `dimensions.baseHeight` - distance between the ground and the bottom of the opening. It is usually 0 for doors and positive for windows.
 - `dimensions.height` - distance between the bottom and the top of the opening.
@@ -39,21 +39,21 @@ interface Opening {
 To list all doors from a space, you can call the following query.
 
 ```ts
-smplrClient.getAllDoorsInSpace(id: string): Promise<Opening[]>
+smplrClient.getAllDoorsInSpace(spaceId: string): Promise<Opening[]>
 ```
 
-- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `Opening` - this main interface is described [here](#opening-interface).
 
 ## getAllDoorsInSpaceFromCache
 
 This is the synchronous equivalent of the query right above.
 
 ```ts
-smplrClient.getAllDoorsInSpaceFromCache(id: string): Opening[]
+smplrClient.getAllDoorsInSpaceFromCache(spaceId: string): Opening[]
 ```
 
-where `id` and `Opening` are as defined in `getAllDoorsInSpace`.
+where `spaceId` and `Opening` are as defined in `getAllDoorsInSpace`.
 
 ## getDoorsOnLevel
 
@@ -66,7 +66,7 @@ smplrClient.getDoorsOnLevel({
 }): Promise<Opening[]>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Opening interface](#opening-interface) to learn more.
 - `Opening` - this main interface is described [here](#opening-interface).
 
@@ -88,21 +88,21 @@ where `spaceId`, `levelIndex`, and `Opening` are as defined in `getDoorsOnLevel`
 To list all windows from a space, you can call the following query.
 
 ```ts
-smplrClient.getAllWindowsInSpace(id: string): Promise<Opening[]>
+smplrClient.getAllWindowsInSpace(spaceId: string): Promise<Opening[]>
 ```
 
-- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `Opening` - this main interface is described [here](#opening-interface).
 
 ## getAllWindowsInSpaceFromCache
 
 This is the synchronous equivalent of the query right above.
 
 ```ts
-smplrClient.getAllWindowsInSpaceFromCache(id: string): Opening[]
+smplrClient.getAllWindowsInSpaceFromCache(spaceId: string): Opening[]
 ```
 
-where `id` and `Opening` are as defined in `getAllWindowsInSpace`.
+where `spaceId` and `Opening` are as defined in `getAllWindowsInSpace`.
 
 ## getWindowsOnLevel
 
@@ -115,7 +115,7 @@ smplrClient.getWindowsOnLevel({
 }): Promise<Opening[]>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Opening interface](#opening-interface) to learn more.
 - `Opening` - this main interface is described [here](#opening-interface).
 

docs/api-reference/queryclient/furniture.md

@@ -4,6 +4,10 @@ sidebar_position: 6
 
 # Furniture
 
+:::info
+"Furniture" is gradually being renamed to "Equipment". You'll read equipment is the app and furniture here, until the change is complete. They are one and the same concept.
+:::
+
 ## Furniture interface
 
 Multiple queries in this page return objects of the type `Furniture` described below:
@@ -47,21 +51,21 @@ interface Furniture {
 To list all furniture from a space, you can call the following query.
 
 ```ts
-smplrClient.getAllFurnitureInSpace(id: string): Promise<Furniture[]>
+smplrClient.getAllFurnitureInSpace(spaceId: string): Promise<Furniture[]>
 ```
 
-- `id` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `Furniture` - this main interface is described [here](#furniture-interface).
 
 ## getAllFurnitureInSpaceFromCache
 
 This is the synchronous equivalent of the query right above.
 
 ```ts
-smplrClient.getAllFurnitureInSpaceFromCache(id: string): Furniture[]
+smplrClient.getAllFurnitureInSpaceFromCache(spaceId: string): Furniture[]
 ```
 
-where `id` and `Furniture` are as defined in `getAllFurnitureInSpace`.
+where `spaceId` and `Furniture` are as defined in `getAllFurnitureInSpace`.
 
 ## getFurnitureOnLevel
 
@@ -74,7 +78,7 @@ smplrClient.getFurnitureOnLevel({
 }): Promise<Furniture[]>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Furniture interface](#furniture-interface) to learn more.
 - `Furniture` - this main interface is described [here](#furniture-interface).
 
@@ -106,7 +110,7 @@ smplrClient.getFurnitureInPolygon({
 }): Promise<Furniture[]>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
 - `Furniture` - this main interface is described [here](#furniture-interface).
 
@@ -138,8 +142,8 @@ smplrClient.getFurnitureById({
 }): Promise<Furniture | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
-- `furnitureId` - unique identifier of the furniture in the space, has a similar format to `spaceId`.
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
+- `furnitureId` - unique identifier of the furniture in the space, something like "fbc5617e-5a27-4138-851e-839446121b2e".
 - `Furniture` - this main interface is described [here](#furniture-interface).
 
 Returns `null` if the furniture is not found in the space.
@@ -173,8 +177,8 @@ smplrClient.getFurnitureGroundFootprintById({
 }[] | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
-- `furnitureId` - unique identifier of the furniture in the space, has a similar format to `spaceId`.
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
+- `furnitureId` - unique identifier of the furniture in the space, something like "fbc5617e-5a27-4138-851e-839446121b2e".
 - `closed` - _optional_ - indicates whether the returned array should be "closed", i.e. the last element repeats the first element. _Default value: false._
 
 Returns `null` if the furniture is not found in the space.
@@ -213,8 +217,8 @@ smplrClient.isFurnitureInPolygon({
 }): Promise<boolean | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
-- `furnitureId` - unique identifier of the furniture in the space, has a similar format to `spaceId`.
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
+- `furnitureId` - unique identifier of the furniture in the space, something like "fbc5617e-5a27-4138-851e-839446121b2e".
 - `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
 
 Returns `null` if the furniture is not found in the space, `false` if it is found but not in the polygon, `true` if it is found in the polygon.

docs/api-reference/queryclient/geometry.md

@@ -155,7 +155,7 @@ smplrClient.isPointInPolygon({
 ```
 
 - `point` - the point coordinates in 2D, with the same schema as `polygon` below.
-- `polygon` - the definition of the area used as a mask to extract furniture. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
+- `polygon` - the polygon in which the point should be located or not. It has the same schema as the coordinates from the [polygon data layers](/api-reference/space/data-layers#polygon-layer). It is assumed here that all coordinates have the same `levelIndex` value.
 
 A similar query is available for furniture pieces, see [isFurnitureInPolygon](/api-reference/queryclient/furniture#isfurnitureinpolygon).
 

docs/api-reference/queryclient/levels-rooms.md

@@ -20,7 +20,7 @@ smplrClient.getLevelBoundingBox({
 }[]>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Furniture interface](/api-reference/queryclient/furniture#furniture-interface) to learn more.
 - `padding` - _optional_ - minimum space between the floor plate's grounds/walls and the bounding box in meters. _Default value: 0_
 
@@ -57,7 +57,7 @@ smplrClient.getLevelAutomaticGround({
 }[] | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Furniture interface](/api-reference/queryclient/furniture#furniture-interface) to learn more.
 
 ## getLevelAutomaticGroundFromCache
@@ -105,7 +105,7 @@ smplrClient.getRoomsOnLevel({
 }[] | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `levelIndex` - zero-based index of the level. Refer to the [Furniture interface](/api-reference/queryclient/furniture#furniture-interface) to learn more.
 - `useCache` - _optional_ - set this to control whether the request should use the client's local cache of computed automatic rooms. You can call this query with `useCache` set to `false` to refresh the cache for all automatic rooms related queries. _Default value: true_
 
@@ -157,7 +157,7 @@ smplrClient.getRoomAtPoint({
 }[] | null>
 ```
 
-- `spaceId` - unique identifier of the space in Smplrspace, something like "fbc5617e-5a27-4138-851e-839446121b2e".
+- `spaceId` - unique identifier of the space in Smplrspace, something like "spc_xxx".
 - `point` - the point coordinates in 2D, with the same schema as `polygon` below.
 
 ## getRoomAtPointFromCache