@planet/maps 8.0.0 → 8.1.0

package/readme.md

@@ -1,60 +1,69 @@
-# Planet Maps
+# @planet/maps
 
-Custom builds of OpenLayers 3.
+![Test Status](https://github.com/planetlabs/maps/actions/workflows/test.yml/badge.svg)
+
+Declarative mapping components
 
 ## Use
 
-Install `planet-maps` as a dependency with [`npm`](http://nodejs.org/).
+```
+npm install @planet/maps
+```
 
-    npm install planet-maps --save-dev
+See the [planetlabs.github.io/maps](https://planetlabs.github.io/maps/) website for more details and examples using the library.
 
-Use [Browserify](http://browserify.org/) to `require` OpenLayers 3.
+## Background
 
-```js
-// see below for a list of custom builds
-var ol = require('@planet/maps/common');
-```
+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.
 
-You'll also want to import the stylesheet:
+This library provides declarative mapping components representing imperative APIs from OpenLayers.
 
-```css
-/* Make sure to use the path to your node_modules */
-@import url('./node_modules/planet-maps/ol.css');
-```
+## Design Goals
 
-## Builds
+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.
 
-### `common`
+Here are some of the goals of this project:
 
-```js
-var ol = require('@planet/maps/common');
-```
+  * 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).
 
-Support for everything required by Scenes, Mosaics, Labs, etc.  See `config/common.json` for details on what is included.
+## Non-Goals
 
-### `explorer`
+This project does not intend to provide any of the following:
 
-```js
-var ol = require('@planet/maps/explorer');
-```
+ * 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.
 
-Support for everything required by Planet Explorer.  See `config/explorer.json` for details on what is included.
+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.
 
-### `debug`
+## Development
 
-This is a debug build that should never be used in production.
+The development setup depends on [Node 18](https://nodejs.org/) (most things work on 16, but not all).
 
-## Publishing a new release
+Install project dependencies:
 
-Edit the `config` files to include what you need exported and commit the changes.  Then you'll want to bump the version number in `package.json`, commit this change, and create a tag.  This should be done with the `npm version` command (choose one of `patch`, `minor`, or `major`).  E.g.
+```bash
+npm install
+```
 
-    npm version minor
+Start the development server:
+```bash
+npm start
+```
+
+Run the tests:
+```bash
+npm test
+```
 
-Next you'll want to push your commits (and the tag) and publish your changes to npmjs.org.
+The rendering tests use Playwright for visual snapshot comparison.  See the [`tests/rendering/readme.md`](tests/rendering/readme.md) for more detail.
 
-    git push --tags origin master
-    npm publish
 
-Before publishing, the `prepublish` step will run `make`.  This will create builds that are *not* tracked by `git` but that are pushed to the npmjs.org repository for use by consuming packages.
+## Prior Art
 
-Note the new version number in `package.json` and use it in packages that depend on this one.
+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.

package/renderer/render.js

@@ -0,0 +1,313 @@
+import BaseLayer from 'ol/layer/Base.js';
+import Control from 'ol/control/Control.js';
+import GroupLayer from 'ol/layer/Group.js';
+import Interaction from 'ol/interaction/Interaction.js';
+import Overlay from 'ol/Overlay.js';
+import ReactReconciler from 'react-reconciler';
+import Source from 'ol/source/Source.js';
+import View from 'ol/View.js';
+import {CONTROL, INTERACTION, LAYER, OVERLAY, SOURCE, VIEW} from '../config.js';
+import {
+  ConcurrentRoot,
+  DefaultEventPriority,
+} from 'react-reconciler/constants.js';
+import {
+  prepareControlUpdate,
+  prepareInteractionUpdate,
+  prepareLayerUpdate,
+  prepareOverlayUpdate,
+  prepareSourceUpdate,
+  prepareViewUpdate,
+  reservedProps,
+} from './update.js';
+
+const listenerRegex = /^on([A-Z].*)/;
+
+function upperFirst(str) {
+  return str[0].toUpperCase() + str.slice(1);
+}
+
+function setterName(str) {
+  return 'set' + upperFirst(str);
+}
+
+const knownTypes = {
+  [VIEW]: true,
+  [OVERLAY]: true,
+  [CONTROL]: true,
+  [INTERACTION]: true,
+  [LAYER]: true,
+  [SOURCE]: true,
+};
+
+export function updateInstanceFromProps(instance, props, oldProps = {}) {
+  for (const key in props) {
+    if (reservedProps[key]) {
+      continue;
+    }
+    if (listenerRegex.test(key)) {
+      const listener = props[key];
+      const type = key.replace(listenerRegex, '$1').toLowerCase();
+      instance.on(type, listener);
+      if (oldProps[key]) {
+        instance.un(type, oldProps[key]);
+      }
+      continue;
+    }
+
+    const setter = setterName(key);
+    if (typeof instance[setter] === 'function') {
+      instance[setter](props[key]);
+      continue;
+    }
+
+    if (key === 'features' && typeof instance.addFeatures === 'function') {
+      // TODO: there is likely a smarter way to diff features
+      instance.clear(true);
+      instance.addFeatures(props[key]);
+      continue;
+    }
+
+    if (
+      key === 'interactions' &&
+      typeof instance.addInteraction === 'function'
+    ) {
+      instance.getInteractions().clear();
+      props[key].forEach(interaction => instance.addInteraction(interaction));
+      continue;
+    }
+    if (key === 'controls' && typeof instance.addControl === 'function') {
+      instance.getControls().clear();
+      props[key].forEach(control => instance.addControl(control));
+      continue;
+    }
+
+    throw new Error(`Cannot update '${key}' property`);
+  }
+}
+
+function createInstance(type, {cls: Constructor, ...props}) {
+  if (!knownTypes[type]) {
+    throw new Error(`Unsupported element type: ${type}`);
+  }
+  if (!Constructor) {
+    throw new Error(`No constructor for type: ${type}`);
+  }
+
+  const instance = new Constructor(props.options || {});
+  updateInstanceFromProps(instance, props);
+  return instance;
+}
+
+function createTextInstance() {
+  throw new Error('Cannot add text to the map');
+}
+
+function appendChildToContainer(map, child) {
+  if (child instanceof View) {
+    map.setView(child);
+    return;
+  }
+  if (child instanceof Overlay) {
+    map.addOverlay(child);
+    return;
+  }
+  if (child instanceof Control) {
+    map.addControl(child);
+    return;
+  }
+  if (child instanceof Interaction) {
+    map.addInteraction(child);
+    return;
+  }
+  if (child instanceof BaseLayer) {
+    map.addLayer(child);
+    return;
+  }
+  throw new Error(`Cannot add child to the map: ${child}`);
+}
+
+function appendChild(parent, child) {
+  if (child instanceof Source) {
+    if (!(parent instanceof BaseLayer)) {
+      throw new Error(`Cannot add source to ${parent}`);
+    }
+    parent.setSource(child);
+    return;
+  }
+  // Layer groups are an instance of a layer
+  if (child instanceof BaseLayer && parent instanceof GroupLayer) {
+    parent.getLayers().push(child);
+    return;
+  }
+  throw new Error(`Cannot add ${child} to ${parent}`);
+}
+
+const updaters = {
+  [VIEW]: prepareViewUpdate,
+  [OVERLAY]: prepareOverlayUpdate,
+  [CONTROL]: prepareControlUpdate,
+  [INTERACTION]: prepareInteractionUpdate,
+  [LAYER]: prepareLayerUpdate,
+  [SOURCE]: prepareSourceUpdate,
+};
+
+function prepareUpdate(instance, type, oldProps, newProps) {
+  const updater = updaters[type];
+  if (!updater) {
+    throw new Error(`Unsupported element type: ${type}`);
+  }
+  return updater(instance, type, oldProps, newProps);
+}
+
+function commitUpdate(instance, updatePayload, type, oldProps) {
+  updateInstanceFromProps(instance, updatePayload, oldProps);
+}
+
+function removeChildFromContainer(map, child) {
+  if (child instanceof View) {
+    map.setView(child);
+    return;
+  }
+  if (child instanceof Overlay) {
+    map.removeOverlay(child);
+    return;
+  }
+  if (child instanceof Control) {
+    map.removeControl(child);
+    return;
+  }
+  if (child instanceof Interaction) {
+    map.removeInteraction(child);
+    return;
+  }
+  if (child instanceof BaseLayer) {
+    map.removeLayer(child);
+    return;
+  }
+  throw new Error(`Cannot remove child from the map: ${child}`);
+}
+
+function removeChild(parent, child) {
+  // this happens with group layers
+  if (child instanceof BaseLayer && parent.getLayers) {
+    parent.getLayers().remove(child);
+    return;
+  }
+  throw new Error(`TODO: implement removeChild for ${parent} and ${child}`);
+}
+
+function clearContainer(map) {
+  map.getLayers().clear();
+  // Need to leave the default controls and interactions.
+  // TODO: determine when this gets called.
+}
+
+function insertInCollection(collection, child, beforeChild) {
+  const index = collection.getArray().indexOf(beforeChild);
+  if (index < 0) {
+    collection.push(child);
+  } else {
+    collection.insertAt(index, child);
+  }
+}
+
+function insertInContainerBefore(map, child, beforeChild) {
+  if (child instanceof View) {
+    map.setView(child);
+    return;
+  }
+  let collection;
+  if (child instanceof Overlay) {
+    collection = map.getOverlays();
+  } else if (child instanceof Control) {
+    collection = map.getControls();
+  } else if (child instanceof Interaction) {
+    collection = map.getInteractions();
+  } else if (child instanceof BaseLayer) {
+    collection = map.getLayers();
+  }
+  if (collection) {
+    insertInCollection(collection, child, beforeChild);
+  }
+}
+
+function insertBefore(parent, child, beforeChild) {
+  if (child instanceof BaseLayer && parent instanceof GroupLayer) {
+    insertInCollection(parent.getLayers(), child, beforeChild);
+    return;
+  }
+  throw new Error(`Cannot insert child ${child} into parent ${parent}`);
+}
+
+const reconciler = ReactReconciler({
+  supportsMutation: true,
+  isPrimaryRenderer: false,
+  createInstance,
+  createTextInstance,
+  appendChildToContainer,
+  appendChild,
+  appendInitialChild: appendChild,
+  prepareUpdate,
+  commitUpdate,
+  clearContainer,
+  removeChildFromContainer,
+  removeChild,
+
+  insertInContainerBefore,
+  insertBefore,
+
+  finalizeInitialChildren() {
+    return false;
+  },
+
+  getChildHostContext() {},
+
+  getPublicInstance(instance) {
+    return instance;
+  },
+
+  getRootHostContext() {},
+
+  getCurrentEventPriority() {
+    return DefaultEventPriority;
+  },
+
+  prepareForCommit() {
+    return null;
+  },
+
+  resetAfterCommit() {},
+
+  shouldSetTextContent() {
+    return false;
+  },
+
+  detachDeletedInstance() {},
+});
+
+const roots = new Map();
+
+export function render(element, container) {
+  let root = roots.get(container);
+  if (!root) {
+    const logRecoverableError =
+      typeof reportError === 'function'
+        ? reportError // eslint-disable-line no-undef
+        : console.error; // eslint-disable-line no-console
+
+    root = reconciler.createContainer(
+      container,
+      ConcurrentRoot,
+      null,
+      false,
+      null,
+      '',
+      logRecoverableError,
+      null
+    );
+    roots.set(container, root);
+  }
+
+  reconciler.updateContainer(element, root, null, null);
+}

package/renderer/update.js

@@ -0,0 +1,98 @@
+function arrayEquals(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export const reservedProps = {
+  children: true,
+  cls: true,
+  options: true,
+};
+
+export function prepareViewUpdate(view, type, oldProps, newProps) {
+  if (view.getAnimating()) {
+    return null;
+  }
+  const payload = {};
+  let needsUpdate = false;
+  for (const key in newProps) {
+    if (reservedProps[key]) {
+      continue;
+    }
+    if (key === 'center') {
+      if (
+        !(
+          arrayEquals(oldProps.center, newProps.center) ||
+          arrayEquals(view.getCenter(), newProps.center)
+        )
+      ) {
+        payload.center = newProps.center;
+        needsUpdate = true;
+      }
+      continue;
+    }
+    if (key === 'zoom') {
+      if (
+        !(oldProps.zoom === newProps.zoom || view.getZoom() === newProps.zoom)
+      ) {
+        payload.zoom = newProps.zoom;
+        needsUpdate = true;
+      }
+      continue;
+    }
+    if (key === 'rotation') {
+      if (
+        !(
+          oldProps.rotation === newProps.rotation ||
+          view.getRotation() === newProps.rotation
+        )
+      ) {
+        payload.rotation = newProps.rotation;
+        needsUpdate = true;
+      }
+      continue;
+    }
+    if (newProps[key] !== oldProps[key]) {
+      payload[key] = newProps[key];
+      needsUpdate = true;
+    }
+  }
+  if (!needsUpdate) {
+    return null;
+  }
+  return payload;
+}
+
+function prepareGenericUpdate(instance, type, oldProps, newProps) {
+  const payload = {};
+  let needsUpdate = false;
+  for (const key in newProps) {
+    if (reservedProps[key]) {
+      continue;
+    }
+
+    if (newProps[key] !== oldProps[key]) {
+      payload[key] = newProps[key];
+      needsUpdate = true;
+    }
+  }
+  if (!needsUpdate) {
+    return null;
+  }
+  return payload;
+}
+
+export {
+  prepareGenericUpdate as prepareOverlayUpdate,
+  prepareGenericUpdate as prepareLayerUpdate,
+  prepareGenericUpdate as prepareSourceUpdate,
+  prepareGenericUpdate as prepareControlUpdate,
+  prepareGenericUpdate as prepareInteractionUpdate,
+};

package/.npmignore

@@ -1,2 +0,0 @@
-/Makefile
-/config/