@panoramax/web-viewer 3.0.2-develop-a8ea8e60

package/config/webpackDevServer.config.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const evalSourceMapMiddleware = require('react-dev-utils/evalSourceMapMiddleware');
+const noopServiceWorkerMiddleware = require('react-dev-utils/noopServiceWorkerMiddleware');
+const ignoredFiles = require('react-dev-utils/ignoredFiles');
+const redirectServedPath = require('react-dev-utils/redirectServedPathMiddleware');
+const paths = require('./paths');
+const getHttpsConfig = require('./getHttpsConfig');
+
+const host = process.env.HOST || '0.0.0.0';
+const sockHost = process.env.WDS_SOCKET_HOST;
+const sockPath = process.env.WDS_SOCKET_PATH; // default: '/ws'
+const sockPort = process.env.WDS_SOCKET_PORT;
+
+module.exports = function (proxy, allowedHost) {
+  const disableFirewall =
+    !proxy || process.env.DANGEROUSLY_DISABLE_HOST_CHECK === 'true';
+  return {
+    // WebpackDevServer 2.4.3 introduced a security fix that prevents remote
+    // websites from potentially accessing local content through DNS rebinding:
+    // https://github.com/webpack/webpack-dev-server/issues/887
+    // https://medium.com/webpack/webpack-dev-server-middleware-security-issues-1489d950874a
+    // However, it made several existing use cases such as development in cloud
+    // environment or subdomains in development significantly more complicated:
+    // https://github.com/facebook/create-react-app/issues/2271
+    // https://github.com/facebook/create-react-app/issues/2233
+    // While we're investigating better solutions, for now we will take a
+    // compromise. Since our WDS configuration only serves files in the `public`
+    // folder we won't consider accessing them a vulnerability. However, if you
+    // use the `proxy` feature, it gets more dangerous because it can expose
+    // remote code execution vulnerabilities in backends like Django and Rails.
+    // So we will disable the host check normally, but enable it if you have
+    // specified the `proxy` setting. Finally, we let you override it if you
+    // really know what you're doing with a special environment variable.
+    // Note: ["localhost", ".localhost"] will support subdomains - but we might
+    // want to allow setting the allowedHosts manually for more complex setups
+    allowedHosts: disableFirewall ? 'all' : [allowedHost],
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': '*',
+      'Access-Control-Allow-Headers': '*',
+    },
+    // Enable gzip compression of generated files.
+    compress: true,
+    static: {
+      // By default WebpackDevServer serves physical files from current directory
+      // in addition to all the virtual build products that it serves from memory.
+      // This is confusing because those files won’t automatically be available in
+      // production build folder unless we copy them. However, copying the whole
+      // project directory is dangerous because we may expose sensitive files.
+      // Instead, we establish a convention that only files in `public` directory
+      // get served. Our build script will copy `public` into the `build` folder.
+      // In `index.html`, you can get URL of `public` folder with %PUBLIC_URL%:
+      // <link rel="icon" href="%PUBLIC_URL%/favicon.ico">
+      // In JavaScript code, you can access it with `process.env.PUBLIC_URL`.
+      // Note that we only recommend to use `public` folder as an escape hatch
+      // for files like `favicon.ico`, `manifest.json`, and libraries that are
+      // for some reason broken when imported through webpack. If you just want to
+      // use an image, put it in `src` and `import` it from JavaScript instead.
+      directory: paths.appPublic,
+      publicPath: [paths.publicUrlOrPath],
+      // By default files from `contentBase` will not trigger a page reload.
+      watch: {
+        // Reportedly, this avoids CPU overload on some systems.
+        // https://github.com/facebook/create-react-app/issues/293
+        // src/node_modules is not ignored to support absolute imports
+        // https://github.com/facebook/create-react-app/issues/1065
+        ignored: ignoredFiles(paths.appSrc),
+      },
+    },
+    client: {
+      webSocketURL: {
+        // Enable custom sockjs pathname for websocket connection to hot reloading server.
+        // Enable custom sockjs hostname, pathname and port for websocket connection
+        // to hot reloading server.
+        hostname: sockHost,
+        pathname: sockPath,
+        port: sockPort,
+      },
+      overlay: {
+        errors: true,
+        warnings: false,
+      },
+    },
+    devMiddleware: {
+      // It is important to tell WebpackDevServer to use the same "publicPath" path as
+      // we specified in the webpack config. When homepage is '.', default to serving
+      // from the root.
+      // remove last slash so user can land on `/test` instead of `/test/`
+      publicPath: paths.publicUrlOrPath.slice(0, -1),
+    },
+
+    https: getHttpsConfig(),
+    host,
+    historyApiFallback: {
+      // Paths with dots should still use the history fallback.
+      // See https://github.com/facebook/create-react-app/issues/387.
+      disableDotRule: true,
+      index: paths.publicUrlOrPath,
+    },
+    // `proxy` is run between `before` and `after` `webpack-dev-server` hooks
+    proxy,
+    onBeforeSetupMiddleware(devServer) {
+      // Keep `evalSourceMapMiddleware`
+      // middlewares before `redirectServedPath` otherwise will not have any effect
+      // This lets us fetch source contents from webpack for the error overlay
+      devServer.app.use(evalSourceMapMiddleware(devServer));
+
+      if (fs.existsSync(paths.proxySetup)) {
+        // This registers user provided middleware for proxy reasons
+        require(paths.proxySetup)(devServer.app);
+      }
+    },
+    onAfterSetupMiddleware(devServer) {
+      // Redirect to `PUBLIC_URL` or `homepage` from `package.json` if url not match
+      devServer.app.use(redirectServedPath(paths.publicUrlOrPath));
+
+      // This service worker file is effectively a 'no-op' that will reset any
+      // previous service worker registered for the same host:port combination.
+      // We do this in development to avoid hitting the production cache if
+      // it used the same host and port.
+      // https://github.com/facebook/create-react-app/issues/2272#issuecomment-302832432
+      devServer.app.use(noopServiceWorkerMiddleware(paths.publicUrlOrPath));
+    },
+  };
+};

package/docs/01_Start.md

@@ -0,0 +1,149 @@
+# Web viewer documentation
+
+Welcome to Panoramax __Web Viewer__ documentation ! It will help you through all phases of setup, run and develop on Panoramax JS pictures viewer.
+
+![Web viewer screenshots](./images/screenshot.jpg)
+
+!!! note
+
+	If at some point you're lost or need help, you can contact us through [issues](https://gitlab.com/panoramax/clients/web-viewer/-/issues) or by [email](mailto:panieravide@riseup.net).
+
+## Install the viewer
+
+Many options are available for installing the viewer.
+
+=== ":simple-npm: NPM"
+
+	Panoramax viewer is available on NPM as [@panoramax/web-viewer](https://www.npmjs.com/package/@panoramax/web-viewer) package.
+
+	```bash
+	npm install @panoramax/web-viewer
+	```
+
+	If you want the latest version (corresponding to the `develop` git branch), you can use the `develop` NPM dist-tag:
+
+	```bash
+	npm install @panoramax/web-viewer@develop
+	```
+
+=== ":material-web: Hosted"
+
+	You can rely on various providers offering hosted NPM packages, for example JSDelivr.
+
+	```html
+	<!-- You may use another version than 3.0.2, just change the release in URL -->
+	<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@3.0.2/build/index.css" />
+	<script src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@3.0.2/build/index.js"></script>
+	```
+
+=== ":material-code-tags: Source code"
+
+	You can install and use Panoramax web client based on code provided in this repository.
+
+	This library relies on __Node.js 16__, which should be installed on your computer. Then, you can build the library using these commands:
+
+	```bash
+	git clone https://gitlab.com/panoramax/clients/web-viewer.git
+	cd web-viewer/
+	npm install
+	npm build
+	```
+
+
+## Basic usage
+
+First, you need to make sure everything is ready to create the viewer:
+
+=== ":fontawesome-brands-js: Old-school JS"
+
+	Make sure to have both JS and CSS code available in your HTML `head` part:
+
+	```html
+	<!-- Change the actual path depending of where you installed the library -->
+	<link rel="stylesheet" type="text/css" href="web-viewer/build/index.css" />
+	<script src="web-viewer/build/index.js"></script>
+	```
+
+	And you also node a `div` somewhere in your HTML:
+
+	```html
+	<div id="viewer" style="width: 500px; height: 300px"></div>
+	```
+
+	Then, the div is populated with this JavaScript code:
+
+	```js
+	let myViewer = new Panoramax.Viewer(
+		"viewer",  // Div ID
+		"https://api.panoramax.xyz/api",  // STAC API endpoint
+		{ map: true }  // Viewer options
+	);
+	```
+
+=== ":fontawesome-brands-node-js: New-style JS"
+
+	Make sure to import both JS and CSS in your code:
+
+	```js
+	import Panoramax from '@panoramax/web-viewer';
+	import '@panoramax/web-viewer/build/index.css';
+	```
+
+	And have access in some way to a classic `div` HTML element:
+
+	```js
+	const myDiv = document.getElementById("viewer");
+	```
+
+	Then, the div is populated with this JavaScript code:
+
+	```js
+	let myViewer = new Panoramax.Viewer(
+		myDiv,  // Div Element
+		"https://api.panoramax.xyz/api",  // STAC API endpoint
+		{ map: true }  // Viewer options
+	);
+	```
+
+
+Beyond classic viewer, other widgets are available and [can be tested online](https://viewer.geovisio.fr/):
+
+__Standalone-map__
+
+A simple map for showing coverage only.
+
+```js
+var myMap = new Panoramax.StandaloneMap(
+	"map",  // Div ID
+	"https://api.panoramax.xyz/api"  // STAC API endpoint
+);
+```
+
+__Editor__
+
+A map and photo viewer, focused on a single sequence, for previewing edits made to it.
+
+```js
+var myEditor = new Panoramax.Editor(
+	"editor",  // Div ID
+	"https://api.panoramax.xyz/api",  // STAC API endpoint
+	{
+		selectedSequence: "id-to-an-existing-sequence", // Sequence ID (mandatory)
+		selectedPicture: "id-to-a-picture-in-this-sequence" // Picture ID (optional)
+	}
+);
+```
+
+## User interface
+
+### Keyboard shortcuts
+
+All interactions with the viewer can be done using the mouse, and some can be also done using keyboard.
+
+* __Arrows__ (or 2/4/8/6 on keypad): move inside the picture, or move the map
+* __Page up/down__ (or 3/9 on keypad) : go to next or previous picture in sequence
+* __+ / -__ : zoom picture or map in or out
+* __*__ (or 5 on keypad) : move picture or map to its center
+* __Home / ↖️__ (or 7 on keypad) : switch map and picture as main shown component
+* __End__ (or 1 on keypad) : hide minimized map or picture
+* __Space__ : play or pause current sequence