diff --git a/docs/modules/editable-layers/README.md b/docs/modules/editable-layers/README.md index 5167f24c..1923c907 100644 --- 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,29 @@ 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 + +- Changes + - 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 new file mode 100644 index 00000000..95a4495b --- /dev/null +++ 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 new file mode 100644 index 00000000..30a71266 --- /dev/null +++ b/docs/modules/editable-layers/developer-guide/data-model.md @@ -0,0 +1,33 @@ +# 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 index b104d007..8a0f6145 100644 --- 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 index 40e1497a..c32ab2ab 100644 --- 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 index e2c38c46..2547eab6 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -1,21 +1,23 @@ # 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#whats-new) +- [`arrow-layers`](/docs/modules/arrow-layers#whats-new) +- [`editable-layers`](/docs/modules/editable-layers#uhats-new) +- [`layers`](/docs/modules/editable-layers#whats-new) -November 20, 2024 [**`@deck.gl-community/editable-layers`**](/docs/modules/editable-layers)) - When drawing circles or ellipses properties of the created geometry are now stored in the vector's properties. - +## 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 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. +November 20, 2024 [**`@deck.gl-community/editable-layers`**](/docs/modules/editable-layers)) - When drawing circles or ellipses properties of the created geometry are now stored in the vector's properties. +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.