docs: Add upgrade guides, in particular for editable layers

visgl · Dec 3, 2024 · 7ade7d7 · 7ade7d7
1 parent 270d6c7
commit 7ade7d7
Show file tree

Hide file tree

Showing 6 changed files with 106 additions and 10 deletions.
diff --git a/docs/modules/editable-layers/README.md b/docs/modules/editable-layers/README.md
@@ -4,7 +4,6 @@
 The deck.gl-community repo is specifically set up to collect useful code that no longer has dedicated maintainers. This means that there is often no one who can respond quickly to issues. The vis.gl / Open Visualization team members who try to keep this running can only put a few hours into it every now and then. It is important to understand this limitation. If your project depends on timely fixes, and you are not able to contribute them yourself, deck.gl-community modules may not be the right choice for you.
 :::
 
-
 ![deck.gl v9](https://img.shields.io/badge/deck.gl-v9-green.svg?style=flat-square")
 ![WebGPU not supported](https://img.shields.io/badge/webgpu-no-red.svg?style=flat-square")
 
@@ -29,9 +28,13 @@ A fork of @nebula.gl. [nebula.gl](https://nebula.gl) is an important part of the
 
 This page contains highlights of each `editable-layers` release.
 
+### editable-layers v9.1
+
+- Now stores properties of created circles and ellipses in `properties.editProperties`.
+
 ### editable-layers v9.0
 
-- The code has been updated to work with deck.gl v9. 
+- The code has been updated to work with deck.gl v9.
 - The module structure has been simplified via the module mapping in the table below.
 
 | @deck.gl-community/editable-layers module | Description         | deck.gl-community module                |
@@ -43,6 +46,30 @@ This page contains highlights of each `editable-layers` release.
 | `@nebula.gl/editor`                       | React wrappers      | => Code moved into "editor" example     |
 | `react-map-gl-draw`                       | Non-deck-wrapper    | => NOT FORKED                           |
 
-Notes:
-- `react-map-gl-draw`- A notable omission is that `react-map-gl-draw` is not included in this fork. This decision was made to simplify the nebula.gl code base with the hope of making it easier for non-dedicated maintainers to keep the deck.gl layers version of nebula.gl alive. Given that the new version is no longer broken into deck.gl independent modules, it may not be easy to add.
-The main reason for updating react-map-gl-draw is likely to make it work with the latest React versions. If it helps, `react-map-gl-draw` is a small module and you can probably copy the source code into your app and bump the react dependency.
+## Upgrade Guide
+
+### Upgrade to editable-layers v9.1
+
+- Make sure your deck.gl and luma.gl dependencies are updated to v9.1
+
+Deprecations:
+
+- `properties.shape` is deprecated, use `properties.editProperties.shape`.
+
+### Upgrading from nebula.gl to editable-layers v9.0
+
+The main effort should be to replace your dependencies in package.json and replace import statements in your code:
+
+| nebula.gl import                 | deck.gl-community import                | Comment                                                  |
+| -------------------------------- | --------------------------------------- | -------------------------------------------------------- |
+| nebula.gl                        | => `@deck.gl-community/editable-layers` |                                                          |
+| `import '@nebula.gl/edit-modes'` | => `@deck.gl-community/editable-layers` |                                                          |
+| `import '@nebula.gl/layers`      | => `@deck.gl-community/editable-layers` |                                                          |
+| `import '@nebula.gl/overlays`    | => `@deck.gl-community/react`           |                                                          |
+| `import '@nebula.gl/editor'`     | => N/A                                  | Copy code from `examples/editor` directory into your app |
+| `import 'react-map-gl-draw'`     | => N/A                                  | Copy code from nebula.gl repo into your app.             |
+
+- **`react-map-gl-draw`**
+  - nebula.gl's `react-map-gl-draw` module was not ported to `deck.gl-community`.
+  - The main reason why a user would want to update `react-map-gl-draw` is likely to make it work with a newer React version.
+  - `react-map-gl-draw` is a small module in nebula.gl and you could probably just copy the source code into your app and bump the react dependency.
diff --git a/docs/modules/editable-layers/developer-guide/configuration.md b/docs/modules/editable-layers/developer-guide/configuration.md
@@ -0,0 +1,21 @@
+# Configuration
+
+Editable layers need to be configured. 
+
+## Edit Modes
+
+The primary way of configuring editable layers is to provide a list of edit modes. 
+Editable layers accept `EditMode`s that provide a way of specifying what user interactions are supported in order to:
+
+- create and manipulate GeoJSON features and geometries.
+- select and duplicate geometries.
+- measure geometries
+- create custom reusable interactions
+
+A range of Edit Modes are provided by the `@deck.gl-community/editable-layers` module, and applications can also define custom edit modes. 
+
+Some examples of provided edit modes are:
+
+- `ViewMode` - No edits are possible, but selection is still possible.
+- `DuplicateMode` - User can duplicate and translate a feature by clicking selected feature and dragging anywhere on the screen.
+- `CompositeMode` - Use `CompositeMode` to combine multiple modes. _Not all combinations are guaranteed to work._
diff --git a/docs/modules/editable-layers/developer-guide/data-model.md b/docs/modules/editable-layers/developer-guide/data-model.md
@@ -0,0 +1,34 @@
+# Data Model
+
+The core editable layers are designed to work with GeoJSON style "features". The basic structure of each row in a table is:
+
+```ts
+type Feature = {
+  type: 'Feature',
+  geometry: {type: '...', coordinates: [...]},
+  properties: {
+    [columnName: string]
+  }
+}
+
+## Geometry
+
+## Properties
+
+In general, the properties field in a feature is used to store the non-geometry column values for the row.
+
+
+## Edit Properties
+
+The editable-layers framework adds certain properties
+
+### `properties.editProperties`
+
+this is an object that contain shape specific properties, consult each edit mode for detailed documentation
+
+### `properties.shape` (deprecated)
+
+The layer stores the type of shape represented by a feature in the `properties.shape` field.
+
+`properties.shape` is now deprecated and replaced by `properties.editProperties.shape`
+
diff --git a/docs/modules/editable-layers/sidebar.json b/docs/modules/editable-layers/sidebar.json
@@ -4,6 +4,8 @@
   "items": [
     "modules/editable-layers/README",
     "modules/editable-layers/developer-guide/get-started",
+    "modules/editable-layers/developer-guide/data-model",
+    "modules/editable-layers/developer-guide/configuration",
     {
       "type": "category",
       "label": "Layers",

diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -1 +1,10 @@
 # Upgrade Guide
+
+Modules in `@deck.gl-community` are independently maintained, so this page will only list occasional major changes.
+
+Please refer the documentation of each module for detailed upgrade guides, e.g:
+
+- [`graph-layers`](/docs/modules/graph-layers#upgrade-guide)
+- [`arrow-layers`](/docs/modules/arrow-layers#upgrade-guide)
+- [`editable-layers`](/docs/modules/editable-layers#upgrade-guide)
+- [`layers`](/docs/modules/editable-layers#upgrade-guide)
diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -1,18 +1,21 @@
 # What's New
 
-The detailed release notes of each module can be found in the module-specific docs section.
+Modules in `@deck.gl-community` are independently maintained, so this page will only list occasional major changes.
 
-High-level updates are 
+Please refer the documentation of each module for detailed news, e.g:
 
+- [`graph-layers`](/docs/modules/graph-layers#uwhats-new)
+- [`arrow-layers`](/docs/modules/arrow-layers#uwhats-new)
+- [`editable-layers`](/docs/modules/editable-layers#uwhats-new)
+- [`layers`](/docs/modules/editable-layers#uwhats-new)
 
-April 15, 2024: [**`@deck.gl-community/editable-layers`**](/docs/modules/editable-layers)) v9 - This new layer pack is a fork of Uber's no longer maintained [nebula.gl](https://nebula.gl) framework. nebula.gl has been an important part of the deck.gl ecosystem but the repository has lacked maintainers for several years and the repository no longer accepts external contributions.
+## High-Level updates
 
+April 15, 2024: [**`@deck.gl-community/editable-layers`**](/docs/modules/editable-layers)) v9 - This new layer pack is a fork of Uber's [nebula.gl](https://nebula.gl) framework which is no longer maintained. nebula.gl has been an important part of the deck.gl ecosystem but the repository has lacked maintainers for several years and the repository no longer accepts external contributions.
 
 Feb 29, 2024: [**`@deck.gl-community/layers`**](/docs/modules/layers) v9 - deck,gl community-layers now support deck.gl v9.
 
-
 December 22, 2023: [**`@deck.gl-community/layers`**](/docs/modules/layers) v0 - A new module intended to containing a collection of useful community layers. Initial layers are `TileSourceLayer`, `DataDrivenTile3DLayer`.
 
-
 April 14, 2023: [**`@deck-graph-layers`**](/docs/modules/graph-layers) - A new layer pack for rendering graphs (nodes and edges). Forked from Uber's archived [graph.gl](https://graph.gl) repo.