Add tests, docs, build

.eslintrc.json

@@ -0,0 +1,22 @@
+{
+  "rules": {},
+  "env": {
+    "es6": true,
+    "browser": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2018,
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "extends": "eslint:recommended",
+  "globals": {
+    "Atomics": "readonly",
+    "SharedArrayBuffer": "readonly"
+  },
+  "plugins": [
+    "react"
+  ]
+}

.gitignore

@@ -1,8 +1,23 @@
 node_modules/
 npm-debug.log
 
-# On a fresh install with yarn 3.3.0 these extra files were generated.
 .yarn
 .pnp.cjs
 .pnp.loader.mjs
 yarn.lock
+
+documentation/
+.cache/
+coverage/
+dist/*
+dist-dev/*
+*.log
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    "cSpell.words": [
+        "bbox",
+        "EPSG",
+        "extwmsparams",
+        "isempty",
+        "isequal",
+        "maxx",
+        "maxy",
+        "miny",
+        "reproject",
+        "reprojecting",
+        "Sublayer",
+        "sublayers",
+        "USERLAYER"
+    ]
+}

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

README.md

@@ -11,3 +11,54 @@ See:
 * [this presentation](https://blog.sourcepole.ch/assets/2019/qwc2-foss4g19.pdf) for an overview and architecture of QWC2.
 
 Please report QWC2 issues at [qwc2-demo-app/issues](https://github.com/qgis/qwc2-demo-app/issues).
+
+Development
+-----------
+
+Start by installing the development dependencies:
+
+    yarn install
+
+All the output generated by the commands below is deposited directly
+in the root directory of the repository. To clean up the output:
+
+    yarn clean
+
+### Building
+
+We use webpack to build the QWC2 library. Check out its configuration
+in `webpack.config.js`.
+
+To build the library in production mode:
+
+    yarn build-prod
+
+To build the library in development mode:
+
+    yarn build-dev
+
+The results are deposited in `dist/` for production
+and `dist-dev/` for development.
+
+### Testing
+
+We use Jest to run unit tests. It is configured in `jest.config.js`
+and coverage data is collected in `coverage/`.
+
+The tests can be run with:
+
+    yarn test
+
+To run the tests in watch mode:
+
+    yarn test-watch
+
+### Documentation
+
+We use TypeDoc to document the QWC2 library. It is configured in `typedoc.json`
+and the resulting documentation is deposited in `documentation/`.
+
+JsDoc documentation can be generated with one of the following commands:
+
+    yarn doc
+    yarn doc --watch

__mocks__/axios.js

@@ -0,0 +1,2 @@
+import mockAxios from 'jest-mock-axios';
+export default mockAxios;

__mocks__/fileMock.js

@@ -0,0 +1 @@
+export default 'test-file-stub';

__mocks__/styleMock.js

@@ -0,0 +1 @@
+export default {};

actions/browser.js

@@ -13,7 +13,13 @@ ReducerIndex.register("browser", browserReducer);
 
 export const CHANGE_BROWSER_PROPERTIES = 'CHANGE_BROWSER_PROPERTIES';
 
-
+/**
+ * Update browser properties.
+ * 
+ * @param {import("qwc2/typings").BrowserData} properties - information
+ *  retrieved by {@link ConfigUtils.getBrowserProperties}.
+ * @group Redux Store.Actions
+ */
 export function changeBrowserProperties(properties) {
     return {
         type: CHANGE_BROWSER_PROPERTIES,

actions/display.js

@@ -12,6 +12,10 @@ ReducerIndex.register("display", displayReducer);
 
 export const TOGGLE_FULLSCREEN = 'TOGGLE_FULLSCREEN';
 
+/**
+ * Issues a request to the browser to
+ * enter full screen mode.
+ */
 export function requestFullscreen() {
     if (document.documentElement.requestFullscreen) {
         document.documentElement.requestFullscreen();
@@ -24,6 +28,10 @@ export function requestFullscreen() {
     }
 }
 
+/**
+ * Issues a request to the browser to
+ * exit full screen mode.
+ */
 export function endFullscreen() {
     if (document.exitFullscreen) {
         document.exitFullscreen();
@@ -36,6 +44,14 @@ export function endFullscreen() {
     }
 }
 
+
+/**
+ * Change full screen mode.
+ * 
+ * @param {boolean} fullscreen - true to enter full
+ *  screen mode, false to exit it.
+ * @group Redux Store.Actions
+ */
 export function toggleFullscreen(fullscreen) {
     if (fullscreen) {
         requestFullscreen();

actions/editing.js

@@ -13,6 +13,18 @@ ReducerIndex.register("editing", editingReducer);
 export const SET_EDIT_CONTEXT = 'SET_EDIT_CONTEXT';
 export const CLEAR_EDIT_CONTEXT = 'CLEAR_EDIT_CONTEXT';
 
+
+/**
+ * Set current edit context.
+ * 
+ * The `contextId` is set in the store as the `currentContext` and the
+ * `editContext` is saved into the context identified
+ * by the `contextId` in the store's `contexts` members.
+ * 
+ * @param {string} contextId - the ID of this context.
+ * @param {object} editContext - the context.
+ * @group Redux Store.Actions
+ */
 export function setEditContext(contextId, editContext) {
     return {
         type: SET_EDIT_CONTEXT,
@@ -21,6 +33,18 @@ export function setEditContext(contextId, editContext) {
     };
 }
 
+
+/**
+ * Clear current edit context.
+ * 
+ * The context identified by the `contextId` is removed from the store's
+ * `contexts` members and the `newActiveContextId` is set as the new
+ * `currentContext` (but only if `contextId` is currently `currentContext`).
+ * 
+ * @param {string} contextId - the ID of this context.
+ * @param {object} newActiveContextId - the context.
+ * @group Redux Store.Actions
+ */
 export function clearEditContext(contextId, newActiveContextId = null) {
     return {
         type: CLEAR_EDIT_CONTEXT,
@@ -29,12 +53,55 @@ export function clearEditContext(contextId, newActiveContextId = null) {
     };
 }
 
+
+// This is where we keep the feature template factories
+// for each dataset. It maps dataset names to functions
+// that transform a feature in `getFeatureTemplate()`.
 const FeatureTemplateFactories = {};
 
+/**
+ * @callback FeatureTemplate
+ * 
+ * The factory function takes a feature as input and
+ * returns a feature as output. The feature is then
+ * used as the template for the feature form.
+ * 
+ * @param {object} feature - the input feature
+ * @returns {object} the output feature
+ */
+
+
+/**
+ * Set the feature template factory for a dataset.
+ * 
+ * The factory function takes a feature as input and
+ * returns a feature as output. The feature is then
+ * used as the template for the feature form.
+ * 
+ * @param {string} dataset - the dataset name.
+ * @param {FeatureTemplate} factory - the factory function.
+ */
 export function setFeatureTemplateFactory(dataset, factory) {
     FeatureTemplateFactories[dataset] = factory;
 }
 
+/**
+ * Compute a defaukt value for a field.
+ * 
+ * The default value is evaluated as follows:
+ * - if it starts with `expr:` then the rest of the
+ *   string is evaluated as follows:
+ *   - `expr:now()` returns the current date/time
+ *   - `expr:true` returns `true`
+ *   - `expr:false` returns `false`
+ *   - otherwise it returns an empty string.
+ * - otherwise the string is used as is.
+ * 
+ * @param {object} field - the field to evaluate
+ * 
+ * @returns {any} the default value
+ * @private
+ */
 function evaluateDefaultValue(field) {
     if (field.defaultValue.startsWith("expr:")) {
         const expr = field.defaultValue.slice(5);
@@ -55,6 +122,24 @@ function evaluateDefaultValue(field) {
     }
 }
 
+
+/**
+ * Get a feature template for a dataset.
+ * 
+ * The feature template is computed as follows:
+ * - if the dataset has a feature template factory
+ *   registered, then the factory is called with the
+ *   feature as input and the result is then used in next step;
+ * - each field of the feature is checked for a
+ *   `defaultValue` property and if it exists, the
+ *   default value is evaluated and assigned to the
+ *   feature's `properties` attribute under the `id` of the field.
+ * 
+ * @param {object} editConfig - the edit configuration
+ * @param {object} feature - the input feature
+ * 
+ * @returns {object} the output feature
+ */
 export function getFeatureTemplate(editConfig, feature) {
     if (editConfig.editDataset in FeatureTemplateFactories) {
         feature = FeatureTemplateFactories[editConfig.editDataset](feature);

actions/identify.js

@@ -14,10 +14,31 @@ import ConfigUtils from '../utils/ConfigUtils';
 
 export const SET_IDENTIFY_TOOL = 'SET_IDENTIFY_TOOL';
 
+
+/**
+ * Sets the current identify tool.
+ * 
+ * The function will use the `identifyTool` property from the
+ * `theme` argument or from current theme if `theme` is not specified.
+ * 
+ * If the theme does not specify an `identifyTool` property,
+ * the default `Identify` is used.
+ * 
+ * If the `enabled` argument is `false`, the current tool is set to `null`.
+ * 
+ * @param {boolean} enabled - whether identify tool is enabled.
+ * @param {string} theme - optional theme name to use for identify tool.
+ * 
+ * @group Redux Store.Actions
+ */
 export function setIdentifyEnabled(enabled, theme = null) {
     return (dispatch, getState) => {
-        let identifyTool = ConfigUtils.getConfigProp("identifyTool", theme || getState().theme.current);
-        identifyTool = identifyTool !== undefined ? identifyTool : "Identify";
+        let identifyTool = ConfigUtils.getConfigProp(
+            "identifyTool", theme || getState().theme.current
+        );
+        identifyTool = identifyTool !== undefined
+            ? identifyTool
+            : "Identify";
         dispatch({
             type: SET_IDENTIFY_TOOL,
             tool: enabled ? identifyTool : null