v2.35.0

docs/api-reference/map/data-layers.md

@@ -4,9 +4,11 @@ sidebar_position: 3
 
 # Data layers
 
-To add or update data layers, you should use the type-specific methods detiled in [the next section](#types-of-layers), while other methods are shared between the layer types and documented [further down](#shared-methods).
+To add or update data layers, you should use the type-specific methods documented in the next sections, while other methods are shared between the layer types and documented [further down](#shared-methods).
 
-## Types of layers
+## Space data layers
+
+Space data layers are layers rendering data with coordinates coming from a Smplrspace space. They're mostly compatible with the [space viewer data layers](/api-reference/space/data-layers).
 
 ### Point layer
 
@@ -43,13 +45,81 @@ map.updatePolygonDataLayer(definitionUpdates: Partial<PolygonMapDataLayerDefinit
 ```
 
 - `id` is a unique identifier for this layer which is used for updates.
-- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array. Elements can also contain any additional custom data used for rendering options.
+- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array.
   - `coordinates` in its simple form is an array of points in the 2D horizontal space, it can also be an array of "rings" where the first ring is the external perimeter of the polygon, and the others are "holes" cut into the external perimeter.
+  - `customData` - _optional_ - elements can also contain any additional custom data used for rendering options.
 - `baseHeight` - _optional_ - defines the elevation from the ground at the base of the polygon in meters. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the base height for that element. _Default value: 0m._
 - `height` - _optional_ - defines the height of the polygon in meters from its base to its top. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the height for that element. _Default value: 3m._
 - `color` - _optional_ - defines the color of the element to render. It can be defined as any valid CSS color string like "orange" or "#3a3c3c", and applied for all elements or per element with a function that takes each element as argument and returns the color string for that element. _Default value: "#2393d4"_
 - `SharedDefinitionOptions` are defined [here](#shared-definition-options).
 
+## Geospatial data layers
+
+Geospatial data layers are layers rendering data with GPS-based coordinates. The data could be created using our entity manager, or any other map provider or geospatial tool.
+
+### GeoPoint layer
+
+A geopoint layer has each data element rendered as a point or marker on the map. It is useful to highlight various points of interest.
+
+```ts
+interface GeoPointMapDataLayerDefinition {
+  id: string,
+  data: [{
+    id: string,
+    position: {
+      lng: number
+      lat: number
+    },
+    ...customData: object
+  }]
+  color?: string | ((dataElement: object) => string)
+  alpha?: number | ((dataElement: object) => number)
+  // + fields from SharedDefinitionOptions defined further down
+}
+
+map.addGeoPointDataLayer(definition: PointMapDataLayerDefinition) => void
+map.updateGeoPointDataLayer(definitionUpdates: Partial<PointMapDataLayerDefinition>) => void
+```
+
+- `id` is a unique identifier for this layer which is used for updates.
+- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `position`. Elements can also contain any additional custom data used for rendering options.
+- `color` - _optional_ - defines the color of the element to render. It can be defined as any valid CSS color string like "orange" or "#3a3c3c", and applied for all elements or per element with a function that takes each element as argument and returns the color string for that element. _Default value: "#2393d4"_
+- `alpha` - _optional_ - defines the transparency of the element to render. The value should be between 0 (invisible) and 1 (opaque). It can be defined as a fix value for all elements or per element with a function that takes each element as argument and returns the alpha value for that element. _Default value: 1_
+- `SharedDefinitionOptions` are defined [here](#shared-definition-options).
+
+### GeoPolygon layer
+
+A geopolygon layer has each data element rendered as a polygon on the map. It is useful to highlight project boundaries, micromarkets, areas under development, etc.
+
+```ts
+interface GeoPolygonMapDataLayerDefinition {
+  id: string,
+  // data of type GeoPolygonData[]
+  data: [{
+    id: string,
+    coordinates: [[{
+      lng: number
+      lat: number
+    }]],
+    ...customData: object
+  }]
+  color?: string | ((dataElement: object) => string)
+  alpha?: number | ((dataElement: object) => number)
+  // + fields from SharedDefinitionOptions defined further down
+}
+
+map.addGeoPolygonDataLayer(definition: PolygonMapDataLayerDefinition) => void
+map.updateGeoPolygonDataLayer(definitionUpdates: Partial<PolygonMapDataLayerDefinition>) => void
+```
+
+- `id` is a unique identifier for this layer which is used for updates.
+- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array.
+  - `coordinates` is an array of "rings" where the first ring is the external perimeter of the polygon, and the others (optional) rings are "holes" cut into the external perimeter. Ring are made of GPS points.
+  - `customData` - _optional_ - elements can also contain any additional custom data used for rendering options.
+- `color` - _optional_ - defines the color of the element to render. It can be defined as any valid CSS color string like "orange" or "#3a3c3c", and applied for all elements or per element with a function that takes each element as argument and returns the color string for that element. _Default value: "#2393d4"_
+- `alpha` - _optional_ - defines the transparency of the element to render. The value should be between 0 (invisible) and 1 (opaque). It can be defined as a fix value for all elements or per element with a function that takes each element as argument and returns the alpha value for that element. _Default value: 1_
+- `SharedDefinitionOptions` are defined [here](#shared-definition-options).
+
 ## Shared definition options
 
 Some options correspond to generic behaviours that are shared by all data layers, making it easy to swap between similar layer types (e.g. "point" and "polygon").

docs/api-reference/map/map.md

@@ -73,17 +73,46 @@ Calling `startViewer` returns a `Promise` ([MDN docs](https://developer.mozilla.
 To stop the viewer, dispose of resources it allocated, and clear the container in which it is rendered back to its original state, call the following function.
 
 ```ts
-space.remove() => void
+map.remove() => void
 ```
 
 ### Check if the viewer is ready
 
 To check if the viewer has finished initializing and is ready for API methods to be called, you can do:
 
 ```ts
-space.isViewerStarted() => boolean
+map.isViewerStarted() => boolean
 ```
 
+## Picking mode
+
+In order to know where a user clicks or taps on the map, you can enable picking mode. For example, this is useful if you have an admin interface to position items or draw on the map. Enabling picking mode is done as follows.
+
+```ts
+// call this after `onReady` has fired
+map.enablePickingMode({
+  onPick: ({ 
+    coordinates: {
+      lng: number
+      lat: number
+    }
+    event: MapMouseEvent
+  }) => void
+}) => void
+```
+
+- `onPick` is called each time a click/tap event fires:
+  - The `coordinates` object provides the location that was picked. It should be stored in your database and reused anytime you need to display data at this location.
+  - The `event` value is the event object fired by Mapbox and is documented [here](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapmouseevent).
+
+Disabling picking mode is done as follow. For example, you would call `disablePickingMode` inside the `onPick` handler if you want to process a single pick event.
+
+```ts
+map.disablePickingMode() => void
+```
+
+You may refer to the [Add data elements](/examples/add-data-elements) example to see picking mode in action and understand the API. The example uses the space viewer, but the concepts are the same.
+
 ## Render buildings
 
 See the dedicated functions you can call to render buildings [on this page](/api-reference/map/buildings).

docs/api-reference/space/data-layers.md

@@ -220,8 +220,9 @@ space.addPolygonDataLayer({
 ```
 
 - `id` is a unique identifier for this layer which is used for updates.
-- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array. Elements can also contain any additional custom data used for rendering options.
+- `data` is an array of objects (refered to as data elements) to be rendered. Each element **must** have an `id` (unique identifier within the data array) and a `coordinates` array.
   - `coordinates` in its simple form is an array of points in the 2D horizontal space, it can also be an array of "rings" where the first ring is the external perimeter of the polygon, and the others are "holes" cut into the external perimeter.
+  - `customData` - _optional_ - elements can also contain any additional custom data used for rendering options.
 - `baseHeight` - _optional_ - defines the elevation from the ground at the base of the polygon in meters. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the base height for that element. _Default value: 0m._
 - `height` - _optional_ - defines the height of the polygon in meters from its base to its top. It can be defined as a number for all elements or per element with a function that takes each element as argument and returns the height for that element. _Default value: 3m._
 - `color` - _optional_ - defines the color of the element to render. It can be defined as any valid CSS color string like "orange" or "#3a3c3c", and applied for all elements or per element with a function that takes each element as argument and returns the color string for that element. _Default value: "#2393d4"_

docs/api-reference/space/space.md

@@ -115,7 +115,7 @@ space.enablePickingMode({
 
 - `onPick` is called each time a click/tap event fires. The `coordinates` object provides the location that was picked in 3D. The `furnitureId` value is set when the user picked a furniture (now called equipment in the app) and contains its unique identifier. These pieces of information should be stored in your database and reused anytime you need to display data at this location.
 
-Disabling picking mode is done as follow. You could call `disablePickingMode` inside the `onPick` handler to limit the number of times a pick event should be processed.
+Disabling picking mode is done as follow. For example, you would call `disablePickingMode` inside the `onPick` handler if you want to process a single pick event.
 
 ```ts
 space.disablePickingMode() => void

docs/guides/sid.md

@@ -28,6 +28,7 @@ _TL;DR: better DX and better UX._
 spc_    space
 rpt_    report
 rpg_    report page
+prj_    project
 ```
 
 That's it, pretty short list ;). More will come soon.