Merge pull request #91 from Dataport/feature/generic-client-and-docum…

…entation-improvement

Feature/generic client and documentation improvement

.eslintignore

@@ -6,5 +6,4 @@
 **/docs
 **/node_modules
 **/tests_output
-pages_output
 *.d.ts

.github/workflows/publish-pages.yml

@@ -15,9 +15,9 @@ jobs:
           node-version: 18.13.0
           registry-url: https://registry.npmjs.org/
       - run: npm ci
-      - run: npm run buildPages
+      - run: npm run pages:build
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./pages_output
+          publish_dir: ./pages

.gitignore

@@ -7,7 +7,6 @@
 **/docs
 **/node_modules
 /public
-/pages_output
 **/tests_output
 /*.log
 logs/*.log

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-There is currently no formally defined process about contributions to the POLAR repository. Should you want to contribute to the project, please contact [email protected] with your matter in question.
+There is no formally defined process about contributions to the POLAR repository yet. For any contributions, please contact [email protected] with your matter in question.
 
 ## Issues
 

README.md

@@ -2,30 +2,90 @@
 [![License: EUPL v1.2](https://img.shields.io/badge/License-EUPL%20v1.2-blue)](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)
 [![We're on NPM!](https://img.shields.io/badge/npm-%F0%9F%9A%80-green)](https://www.npmjs.com/search?q=%40polar)
 
-# POLAR 🗺️
+<h1 align="center"><img alt="POLAR" height="80px" src="./pages/assets/iceberg.svg" /></h1>
 
-The **Plugins for OpenLAyeRs** library is based on the [masterportalAPI](https://bitbucket.org/geowerkstatt-hamburg/masterportalapi) and [OpenLayers](https://openlayers.org/).
+**Plugins for OpenLAyeRs** is based on the [masterportalAPI](https://bitbucket.org/geowerkstatt-hamburg/masterportalapi) and [OpenLayers](https://openlayers.org/).
 
-## The Idea 💡
+POLAR is ...
 
-POLAR is built to ease the creation of new map clients: A lot of feature requests in map clients are recurring and can be fulfilled with reusable parts. Then again, many map clients require a _little extra_.
+* ... a configurable map client package.
+* ... a flexible map client factory.
+* ... an extensible library.
 
-POLAR is built to serve both worlds. For generic use cases, generic clients are ready-made and usable by configuration. More specific use cases can be matched with special clients that still make use of the plugins, but fill in the missing parts right where they belong.
+## Quick Start
 
-POLAR runs both as full page application and as component. The most common usage is as component: Think of it as a form input where the input data is geospatial.
+Usage without NPM documented in chapter "Getting started (for developers)".
+
+```bash
+npm i @polar/client-generic
+```
+
+```js
+import polar from '@polar/client-generic'
+
+polar.createMap({
+  // a div must have this id
+  containerId: 'polarstern',
+  // any service register – this is Hamburg's
+  services: 'https://geodienste.hamburg.de/services-internet.json',
+  mapConfiguration: {
+    // this initially shows Hamburg's city plan
+    layers: [{
+      id: '453',
+      visibility: true,
+      type: 'background',
+    }]
+  }
+})
+```
+
+See our [documentation page](https://dataport.github.io/polar/) for all features and configuration options included in this modulith client, with running examples.
 
-## Maps 🗺️
+## Example clients
 
 The most common use case for this client is in citizen's application processes regarding public service.
 
-Other clients with more specific code (and more visibility) include the [Denkmalkarte Schleswig-Holstein](https://efi2.schleswig-holstein.de/dish/dish_client/index.html), a memorial map, and the [Meldemichel Hamburg](https://static.hamburg.de/kartenclient/prod/), a map to inspect and create reports regarding damages to public infrastructure. The latter is currently being migrated to the version seen in this repository.
+Other clients with more specific code include the [Denkmalkarte Schleswig-Holstein](https://efi2.schleswig-holstein.de/dish/dish_client/index.html), a memorial map, and the [Meldemichel Hamburg](https://static.hamburg.de/kartenclient/prod/), a map to inspect and create reports regarding damages to public infrastructure. The latter is currently being migrated to the version seen in this repository.
+
+## Backers and users
+
+### States of Germany
+
+<table align="center">
+  <tr align="center">
+    <td align="center"><img src="./pages/assets/landessymbole/bremen.svg" alt="Bremer Wappenzeichen" height="120px" style="object-fit: contain;"><div>Freie Hansestadt Bremen</div></td>
+    <td align="center"><img src="./pages/assets/landessymbole/hamburg.svg" alt="Hamburg-Symbol" height="120px" style="object-fit: contain;"><div>Freie Freie und Hansestadt Hamburg</div></td>
+  </tr>
+  <tr align="center">
+    <td align="center"><img src="./pages/assets/landessymbole/sachsen-anhalt.svg" alt="Landessymbol Sachsen-Anhalt" height="120px" style="object-fit: contain;"><div>Sachsen-Anhalt</div></td>
+    <td align="center"><img src="./pages/assets/landessymbole/schleswig-holstein.svg" alt="Landessymbol Schleswig-Holstein" height="120px" style="object-fit: contain;"><div>Schleswig-Holstein</div></td>
+  </tr>
+</table>
+
+### Government agencies
+
+* [Senatskanzlei Hamburg](https://www.hamburg.de/senatskanzlei/)
+* [Landesamt für Denkmalpflege Schleswig-Holstein](https://www.schleswig-holstein.de/DE/landesregierung/ministerien-behoerden/LD/ld_node.html)
+* [Dataport AöR](https://www.dataport.de/)
 
-## Plugins 🧩
+## Technical concepts
+
+### Reusability *and* adaptability
+
+POLAR is built to ease the creation of new map clients. A lot of feature requests in map clients are recurring and can be fulfilled with reusable parts. Then again, many map clients require a _little extra_.
+
+POLAR is built to serve both worlds. For generic use cases, generic clients are ready-made and usable by configuration. More specific use cases can be matched with special clients that still make use of the plugins and fill in the missing parts.
+
+POLAR runs both as full page application and as component. The most common usage is as component: Think of it as a form input where the input data is geospatial.
+
+### Plugin-based approach
+
+To see our plugins in action, please visit our [documentation page](https://dataport.github.io/polar/) to see running examples. Plugins are designed to be configurable, optional, and replacable.
 
 |Name|Details|
 |-|-|
 |[AddressSearch](https://github.com/Dataport/polar/tree/main/packages/plugins/AddressSearch)|Offers a search field and standard search service implementations with API for your own configurable custom search services. For already usable search services, see the documentation of the package. Integration with Reverse Geocoder and Pins possible, or usable as a data source for further processing.|
-|[Attributions](https://github.com/Dataport/polar/tree/main/packages/plugins/Attributions)|Shows layer copyright information of visible layers.|
+|[Attributions](https://github.com/Dataport/polar/tree/main/packages/plugins/Attributions)|Shows layer copyright information of visible layers and client.|
 |[Draw](https://github.com/Dataport/polar/tree/main/packages/plugins/Draw)|Allows the user to draw various geometries onto the map. The resulting GeoJSON can be forwarded to later processing steps, or be used by the Export plugin to generate screenshots.|
 |[Export](https://github.com/Dataport/polar/tree/main/packages/plugins/Export)|Offers screenshot functionality for the user or further processing.|
 |[Filter](https://github.com/Dataport/polar/tree/main/packages/plugins/Filter)|Allows users to filter vector layers to content relevant to their interests.|
@@ -42,36 +102,23 @@ Other clients with more specific code (and more visibility) include the [Denkmal
 |[Toast](https://github.com/Dataport/polar/tree/main/packages/plugins/Toast)|Shows information to the user. Configurable in many plugins to communicate status updates or procedural advice.|
 |[Zoom](https://github.com/Dataport/polar/tree/main/packages/plugins/Zoom)|Allows zooming in and out of the client with buttons.|
 
-## Getting started 🚀
+## Getting started (for developers)
 
 ### Using POLAR
 
-Select a client from our [releases](https://github.com/Dataport/polar/releases). For a generic client, use `@polar/client-afm`. The zipped client is downloadable and attached as an asset to the release.
-
-The package contains example files that illustrate how the client can be used. You may also inspect the example usage [here](https://github.com/Dataport/polar/tree/main/packages/clients/afm/example).
+First check if the generic map client fulfills your need. For this, see the section "Quick start" above. Should your project not use NPM, you may also select a client from our [releases](https://github.com/Dataport/polar/releases). On all client releases, the zipped client is downloadable and attached as an asset to the release.
 
-To adapt the client to your use case, change the included `polar-example.js` file, and replace the object used in the `.createMap` call with your configuration. To learn more about configuration options, read the [AfM documentation](https://dataport.github.io/polar/docs/afm/client-afm.html), or the documentation of the client you chose.
+Client packages contain example files that illustrate how the client can be used. The `@polar/client-generic` package's use is furthermore illustrated on our [documentation page](https://dataport.github.io/polar/).
 
 ### Developing POLAR
 
 Clone the repository and run `npm install && npm run snowbox`. This winds up our development client in a minimal test environment as a starting point.
 
-If you aim to create an additional plugin, you may now create and install it to the snowbox during development. To create a new client, it is advised to create a copy of the AfM client as a base project and adjust it to your needs.
-
-## Roadmap 🛣️
-
-We're production-ready. After a history as Inner Source software, we are now gradually switching to being Open Source software.
+If you aim to create an additional plugin, you may now create and install it to the snowbox during development. To create a new client, it is advised to create a copy of e.g. `@polar/client-generic` as a base project and adjust it to your needs.
 
-| Topic                          | Description                                                                                                                                                                                                                            | Status |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| Re-release                     | Offer all packages as 1.0.0 on the NPM registry and as GitHub releases. Previous inner source version history and changelogs are reset.                                                                                         | ✔️     |
-| GitHub Actions                 | ~~Linting and testing is done with [husky](https://github.com/typicode/husky) until pipelines are ready.~~ Tests and linting now run in the pipeline. Farewell, husky! 🐺❄️                                                     | ✔️     |
-| GitHub Page                    | ~~Create a page offering our full documentation and examples. This includes adapting the internal _snowbox_ client to work as both example and development environment.~~ [Page done.](https://dataport.github.io/polar/) Keeping it up to date is an ongoing effort. | ✔️     |
-| Getting started                | A short introduction is available above. We will expand upon this after the following task.                                                                                                                                                                                | 🏗️     |
-| Working outside the repository | Clients can be used anywhere, but their development requires further setup. Right now, clients should be developed in this repository or in a fork.                                                                             | ⌛     |
-| OSS Best Practices             | Contributions, Issues, Discussions, The Wiki – there's a lot to fill out and define.                                                                                                                                            | ✔️     |
+Clients run anywhere, but their development requires further setup. Right now, clients should be developed in this repository or in a fork of it to make use of its setup.
 
-## Stay In Touch 💬
+## Stay In Touch
 
 - [Contact us via email 📧](mailto:[email protected])
 

lerna.json

@@ -7,6 +7,7 @@
     "packages/core",
     "packages/lib/*",
     "packages/plugins/*",
-    "packages/types/*"
+    "packages/types/*",
+    "pages"
   ]
 }

package.json

@@ -12,6 +12,9 @@
     "afm:build": "lerna run build --scope @polar/client-afm --stream && npm run docs:afm",
     "afm:build:serve": "http-server ./packages/clients/afm -o /example/prod-example.html",
     "afm:dev": "cd packages/clients/afm/ && vite --host",
+    "generic:build": "lerna run build --scope @polar/client-generic --stream",
+    "generic:build:serve": "http-server ./packages/clients/generic -o /example/index.html",
+    "generic:dev": "cd packages/clients/generic/ && vite --host",
     "dish:build": "lerna run build --scope @polar/client-dish --stream",
     "dish:build:serve": "http-server ./packages/clients/dish -o /dist/index.html",
     "dish:dev": "cd packages/clients/dish/ && vite --host",
@@ -21,10 +24,11 @@
     "snowbox": "cd packages/clients/snowbox/ && vite --host",
     "snowbox:build": "lerna run build --scope @polar/client-snowbox --stream",
     "snowbox:build:serve": "http-server packages/clients/snowbox -o /dist/index.html",
-    "buildPages": "rimraf ./pages_output && bash ./scripts/buildPages.sh",
-    "buildPages:serve": "http-server pages_output -o index.html",
-    "clean": "lerna clean && rimraf --glob packages/**/{.cache,dist,docs} && rimraf --glob {.cache,dist,pages_output} && node ./scripts/clean",
+    "pages:build": "rimraf ./pages/docs && npm run generic:build && bash ./scripts/buildPages.sh",
+    "pages:build:serve": "http-server pages -o index.html",
+    "clean": "lerna clean && rimraf --glob packages/**/{.cache,dist,docs} && rimraf --glob {.cache,dist} && node ./scripts/clean",
     "docs:afm": "node ./scripts/makeDocs ./packages/clients/afm",
+    "docs:generic": "node ./scripts/makeDocs ./packages/clients/generic",
     "docs:meldemichel": "node ./scripts/makeDocs ./packages/clients/meldemichel && npm run meldemichel:build && cp -r ./packages/clients/meldemichel/dist ./packages/clients/meldemichel/example ./packages/clients/meldemichel/docs",
     "docs:sbom": "npx @cyclonedx/cyclonedx-npm --output-file sbom.json",
     "docs:snowbox": "node ./scripts/makeDocs ./packages/clients/snowbox",

packages/clients/afm/API.md

@@ -1,6 +1,6 @@
 # POLAR AfM map client
 
-This is a default compilation of POLAR feature packages that can be used for online services. This document and its child documents describe the setup.
+This is a default compilation of POLAR feature packages for online services. This document and its child documents describe the setup.
 
 ## Requirements
 

packages/clients/generic/API.md

@@ -0,0 +1,51 @@
+# Generic MapClient API 🗺️ `@polar/client-generic`
+
+This client is based on [POLAR](https://github.com/Dataport/polar) and subsequently the [masterportalAPI](https://bitbucket.org/geowerkstatt-hamburg/masterportalapi/src/master/). The following documentation only contains how this specific client can be used, and the minimal information required to get it running.
+
+For all additional details, check the [full documentation](https://dataport.github.io/polar/docs/generic/client-generic.html).
+
+For the development test deployments and example configurations, [see here](https://dataport.github.io/polar#plugin-gallery).
+
+## Basic usage
+
+The NPM package `@polar/client-generic` can be installed via NPM or downloaded from the [release page](https://github.com/Dataport/polar/releases). When using `import mapClient from '@polar/client-generic'`, the object `mapClient` contains a method `createMap`. This is the main method required to get the client up and running. Should you use another import method, check the package's `dist` folder for available files.
+
+The method expects a single object with the following parameters.
+
+| fieldName | type | description |
+| - | - | - |
+| containerId | string | ID of the container the map is supposed to render itself to. |
+| services | object[] \| string | Either a link to a service registry or an array containing service description objects. For more details, see the startup section on [POLAR documentation](https://dataport.github.io/polar/documentation.html#configuration). |
+| mapConfiguration | object | See full documentation for all possible configuration options. |
+| enabledPlugins  | string[]? | This is a client-specific field. Since the `@polar/client-generic` client contains all existing plugins, they are activated by strings. The strings match their package names: `'address-search' \| 'attributions' \| 'draw'* \| 'export' \| 'filter'* \| 'fullscreen'* \| 'geo-location'* \| 'gfi'* \| 'icon-menu' \| 'layer-chooser'* \| 'legend' \| 'loading-indicator' \| 'pins' \| 'reverse-geocoder' \| 'scale' \| 'toast' \| 'zoom'*`. The plugins marked with * are nested in the `'icon-menu'` in this pre-layouting, hence they depend upon it being active, too. |
+| modifyLayerConfiguration | ((layerConf: object[]) => object[])? | Defaults to identity function. This function is applied to the loaded layer configuration before usage. That is, the `services` can be modified by this to e.g. set parameters not supported by the service register, add additional layers, and so on. |
+
+`createMap` returns a Promise of a map instance. This returned instance is required to retrieve information from the map.
+
+The package also includes a `style.css` and an `index.html` file. The `style.css`'s relative path must, if it isn't the default value `'./style.css'`, be included in the `mapConfiguration` as follows:
+
+```js
+{
+  // ...
+  stylePath: '../the/relative/path/style.css'
+}
+```
+
+The value to `stylePath` is the same as as a `link` tag would have in its `href`.
+
+### Destroy instance
+
+The `mapInstance` returned by the `createMap` call can be destroyed by calling `mapInstance.$destroy`. This will not remove the rendered HTML, but unlink all internal creations and effects. This should be called before re-navigating, usual lifecycle hooks are `beforeDestroy` or `beforeUnmount`, depending on the framework in use.
+
+After this, `createMap` can be used again when the DOM is restored. That is, the original `div` with its `id` must be recreated, since POLAR changes the DOM in the `div`. Normally, an SPA will take care of this by itself since it will render the outlying component anew.
+
+Should this not be the case in your framework, the following snippet restores the DOM:
+
+```js
+// assuming the render div's id was `"polarstern"`
+const polarstern = document.getElementById('polarstern-wrapper')
+const newStar = document.createElement('div')
+newStar.id = 'polarstern'
+newStar.classList.add('polarstern')
+polarstern?.parentElement?.replaceChild(newStar, polarstern)
+```

packages/clients/generic/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## unpublished
+
+Initial release.