@planet/maps 9.0.0-dev.1698333742151 → 9.0.0-dev.1698338214745

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet/maps",
-  "version": "9.0.0-dev.1698333742151",
+  "version": "9.0.0-dev.1698338214745",
   "description": "Declarative mapping components for React",
   "type": "module",
   "scripts": {

package/readme.md

@@ -0,0 +1,86 @@
+# @planet/maps
+
+![Test Status](https://github.com/planetlabs/maps/actions/workflows/test.yml/badge.svg)
+
+Declarative mapping components
+
+## Use
+
+```
+npm install @planet/maps
+```
+
+See the [planetlabs.github.io/maps](https://planetlabs.github.io/maps/) website for more details and examples using the library.
+
+## Background
+
+React lets you build interactive UIs with (mostly) declarative syntax.  OpenLayers provides an imperative API for building mapping apps.  It can be awkward to map React's component API to an imperative API.  However, the React team provides a package for creating custom renderers: [`react-reconciler`](https://www.npmjs.com/package/react-reconciler).  This is how they integrate with imperative APIs themselves.  The `react-dom` package uses `react-reconciler` to provide a mapping to the imperative DOM API.  `react-native` uses `react-reconciler` to map to imperative native APIs.
+
+This library provides declarative mapping components representing imperative APIs from OpenLayers.
+
+## Design Goals
+
+The purpose of this project is to provide a mapping between React's declarative components and OpenLayers' imperative API.  In other words, this project provides a React renderer for OpenLayers.
+
+Here are some of the goals of this project:
+
+  * Ideally, the renderer would not have any additional dependencies beyond what is bundled with an OpenLayers map.
+  * Components exported by this package map 1:1 with classes exported by OpenLayers.
+  * Component props map directly to properties that are settable on instances of OpenLayers classes.  Exceptions to this are props like `options` (passed to the constructor only), listener props (e.g. `onChange`), and `ref`.
+  * Components accept a `ref` that provide access to the underlying OpenLayers instance.
+  * The renderer should add negligible overhead in terms of bundle size, memory consumption, or processing.
+  * Code components can be generated by using OpenLayers sources.  Exceptions to this are the map component (responsible for invoking the custom renderer) and components that map to classes without subclasses (e.g. the view).
+
+## Non-Goals
+
+This project does not intend to provide any of the following:
+
+ * Higher level abstractions or components that combine logic from multiple OpenLayers instances (e.g. an editable layer component that wraps a layer, source, and editing interactions).
+ * Styled widgets (e.g. a layer switcher/browser).
+ * Other utilities for working with vector data, projections, etc.
+
+We hope that this package can provide the foundation for other, higher-level libraries with more opinions about the look and feel of mapping components.
+
+## Development
+
+The development setup depends on [Node 18](https://nodejs.org/) (most things work on 16, but not all).
+
+Install project dependencies:
+
+```bash
+npm install
+```
+
+Start the development server:
+```bash
+npm start
+```
+
+The rendering tests use Playwright for visual snapshot comparison.  See the [`tests/rendering/readme.md`](tests/rendering/readme.md) for more detail.
+
+Before running tests for the first time, install the required Playwright browser:
+```bash
+npx playwright install chromium
+```
+
+Run the tests:
+```bash
+npm test
+```
+
+After updating the `ol` package to a new version, the generated component sources should be updated:
+```bash
+npm run generate
+```
+
+To publish a new release, choose the release type, update the `package.json` version and create a tag with `npm version`, and then push the change:
+```bash
+npm version minor
+git push --tags origin main
+```
+
+After pushing the changes, draft release notes based on the tag and publish the [GitHub release](https://github.com/planetlabs/maps/releases).
+
+## Prior Art
+
+Other projects like [`react-openlayers-fiber`](https://github.com/crubier/react-openlayers-fiber) and [`react-ol-fiber`](https://www.npmjs.com/package/react-ol-fiber) use a similar approach and provided inspiration for this project.  The major difference between this project and those is that this project provides importable components for OpenLayers layers, sources, controls, and interactions.  The other projects bundle all of OpenLayers in their renderer.  So a simple "hello world" map with one of the existing projects is about 1.5 MB while the same with this project is about 460 KB.