@panoramax/web-viewer 3.2.3 → 4.0.0-develop-9f9cf858

package/docs/09_Develop.md

@@ -4,24 +4,55 @@ You want to work on our library and offer bug fixes or new features ? That's awe
 
 Here are some inputs about working with Panoramax web client code.
 
-If something seems missing or incomplete, don't hesitate to contact us by [email](mailto:panieravide@riseup.net) or using [an issue](https://gitlab.com/panoramax/clients/web-viewer/-/issues). We really want Panoramax to be a collaborative project, so everyone is welcome (see our [code of conduct](https://gitlab.com/panoramax/clients/web-viewer/-/blob/develop/CODE_OF_CONDUCT.md)).
+!!! note
+
+	If something seems missing or incomplete, don't hesitate to contact us by [email](mailto:panoramax@panoramax.fr) or using [an issue](https://gitlab.com/panoramax/clients/web-viewer/-/issues). We really want Panoramax to be a collaborative project, so everyone is welcome (see our [code of conduct](https://gitlab.com/panoramax/clients/web-viewer/-/blob/develop/CODE_OF_CONDUCT.md)).
 
 ## Architecture
 
 The current code is split between various elements:
 
-- __Views__: a single functional entry, like _Viewer_ (map + picture), _StandaloneMap_ or _Editor_. They share parts of code in _CoreView_ class. They specialized the behaviour of components depending on the needs.
-- __Components__: reusable elements, like _Map_, _Photo_ or _Loader_. They are used in some views depending of the context.
-- __Utils__: utility functions, splitted in various files for clarity (_API, I18n, Map, Utils, Widgets_).
+- __Core components__: a single functional entry, like [Viewer](./reference/components/core/Viewer.md) (map + picture), [Photo Viewer](./reference/components/core/PhotoViewer.md) (picture only), [Coverage Map](./reference/components/core/CoverageMap.md) or [Editor](./reference/components/core/Editor.md). They share parts of code in [Basic](./reference/components/core/Basic.md) class. They specialized the behaviour of components depending on the needs.
+- __UI components, menus & widgets__: reusable web components, like [Map](./reference/components/ui/Map.md), [Photo](./reference/components/ui/Photo.md) or [Loader](./reference/components/ui/Loader.md). They are used in some views depending of the context.
+- __Utils__: utility functions, splitted in various files for clarity.
 
 ![Class diagram of Panoramax web viewer](./images/class_diagram.jpg)
 
 The library is relies on various other libraries:
 
+- [Lit](https://lit.dev/), for web components management
 - [Photo Sphere Viewer](https://github.com/mistic100/Photo-Sphere-Viewer), for displaying classic and 360° pictures
 - [Maplibre GL JS](https://github.com/maplibre/maplibre-gl-js), for displaying the map which shows sequences and pictures location
 - [JS Library Boilerplate](https://github.com/hodgef/js-library-boilerplate), for having a ready-to-use development toolbox
 
+## Good to know
+
+### Components `z-index`
+
+In order to offer a coherent overlay of widgets, we follow this general `z-index` ordering:
+
+| Component type                    | Z-Index |
+|-----------------------------------|:-------:|
+| MapLibre GL & Photo Sphere Viewer | <= 110  |
+| Widgets / Cornered Grid's corners |   120   |
+| Togglable menus                   |   130   |
+| Fullscreen loaders & popups       |   200   |
+
+### Parameters handling
+
+!!! note
+
+	This concerns only __Viewer__ component. Editor & Coverage Map read input parameters only from Web Components attributes.
+
+Viewer component can read parameters from 3 different sources:
+
+- Web Component __attributes__, passed through DOM
+- Browser __local storage__
+- __URL search__ parameters
+
+This allows a flexible way to interact with viewer for users. Prioritization of parameters is managed by [InitParameters class](./reference/utils/InitParameters.md), URL parameters coming first, then local storage, to fallback with Web component attributes (and eventually some hard-coded defaults).
+
+This means that, when developing, if you want to check if your attributes are well-defined, you may want to get rid of URL search parameters, as well as remove the `pnx-map-parameters` local storage item. Otherwise, they may not be read as they are lower priority than others.
 
 ## Testing
 
@@ -37,26 +68,30 @@ If you're working on bug fixes or new features, please __make sure to add approp
 
 ## Documentation
 
-Documentation is offered through two means in this repository:
+The documentation is a mix of:
 
-- Code itself is documented with [JSDoc comments](https://jsdoc.app/about-getting-started)
-- A broader doc is available in `docs` folder
+- [JSDoc comments](https://jsdoc.app/about-getting-started) embed directly in source files, and exported in `docs/reference/` folder
+- Higher-level docs as Markdown files, in `docs/` folder.
 
-The code documentation can be generated using the following command:
+The JSDoc can be exported as Markdown using this command:
 
 ```bash
 npm run doc
 ```
 
-That will update the `docs/02_Usage.md` file with all functions and parameters.
-
-The broader doc can be served and viewed using [Mkdocs](https://www.mkdocs.org/):
+And all documentation can be previewed or built using [Mkdocs](https://www.mkdocs.org/):
 
 ```bash
 pip install mkdocs mkdocs-material
 mkdocs serve
+mkdocs build
 ```
 
+Online versions are available at:
+
+- [docs.panoramax.fr](https://docs.panoramax.fr/web-viewer/) for __stable__ version
+- [viewer.geovisio.fr/docs](https://viewer.geovisio.fr/docs/) for __develop__ version
+
 ## Make a release
 
 See [dedicated documentation](./90_Releases.md).

package/docs/90_Releases.md

@@ -1,10 +1,10 @@
 # Make a release
 
-Panoramax Web Viewer uses [semantic versioning](https://semver.org/) for its release numbers.
+Panoramax JS uses [semantic versioning](https://semver.org/) for its release numbers.
 
 !!! note
 
-	On Viewer versions < 3.0, a strong constraint was put to keep versions in sync between API and Viewer. Each component could have different `PATCH` versions, but compatibility __had to be__ ensured between `MAJOR.MINOR` versions. Since Viewer version >= 3.0, any STAC-compliant API should be supported by Viewer.
+	On versions < 3.0, a strong constraint was put to keep versions in sync between API and Viewer. Each component could have different `PATCH` versions, but compatibility __had to be__ ensured between `MAJOR.MINOR` versions. Since Viewer version >= 3.0, any STAC-compliant API should be supported by Viewer.
 
 Run these commands in order to issue a new release:
 

package/docs/images/class_diagram.drawio

@@ -1,94 +1,102 @@
-<mxfile host="app.diagrams.net" modified="2024-03-25T13:20:49.245Z" agent="Mozilla/5.0 (X11; Linux x86_64; rv:124.0) Gecko/20100101 Firefox/124.0" etag="r1p7scxPnhYybEiXE-8z" version="23.1.2" type="device">
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64; rv:136.0) Gecko/20100101 Firefox/136.0" version="26.1.1">
   <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">
-    <mxGraphModel dx="1018" dy="574" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="983" dy="448" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="WIyWlLk6GJQsqaUBKTNV-0" />
         <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0" />
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-1" value="CoreView" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-1" value="Basic" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
           <mxGeometry x="20" y="40" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-3" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-1">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-3" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-1" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-9" value="Viewer" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
-          <mxGeometry x="20" y="160" width="160" height="34" as="geometry" />
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-9" value="PhotoViewer" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="20" y="148" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-10" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-9">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-10" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-9" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-11" value="StandaloneMap" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
-          <mxGeometry x="200" y="160" width="160" height="34" as="geometry" />
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-11" value="CoverageMap" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="200" y="148" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-12" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-11">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-12" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-11" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-13" value="Editor" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
-          <mxGeometry x="380" y="160" width="160" height="34" as="geometry" />
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-13" value="Editor" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="380" y="148" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-14" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-13">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-14" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-13" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-15" value="Extends" style="endArrow=block;endSize=16;endFill=0;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-9" target="-sBJLWWXFzCuZ66xZKHM-1">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-15" value="Extends" style="endArrow=block;endSize=16;endFill=0;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-9" target="-sBJLWWXFzCuZ66xZKHM-1" edge="1">
           <mxGeometry width="160" relative="1" as="geometry">
             <mxPoint x="310" y="260" as="sourcePoint" />
             <mxPoint x="470" y="260" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-17" value="" style="endArrow=none;html=1;rounded=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-17" value="" style="endArrow=none;html=1;rounded=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" edge="1">
           <mxGeometry width="50" height="50" relative="1" as="geometry">
-            <mxPoint x="100" y="140" as="sourcePoint" />
-            <mxPoint x="460" y="140" as="targetPoint" />
+            <mxPoint x="100" y="128" as="sourcePoint" />
+            <mxPoint x="460" y="128" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-19" value="" style="endArrow=none;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-11">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-19" value="" style="endArrow=none;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-11" edge="1">
           <mxGeometry width="50" height="50" relative="1" as="geometry">
             <mxPoint x="370" y="290" as="sourcePoint" />
-            <mxPoint x="280" y="140" as="targetPoint" />
+            <mxPoint x="280" y="130" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-20" value="" style="endArrow=none;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-20" value="" style="endArrow=none;html=1;rounded=0;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13" edge="1">
           <mxGeometry width="50" height="50" relative="1" as="geometry">
             <mxPoint x="290" y="170" as="sourcePoint" />
-            <mxPoint x="460" y="140" as="targetPoint" />
+            <mxPoint x="460" y="130" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-22" value="Views" style="swimlane;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
-          <mxGeometry x="10" y="10" width="540" height="200" as="geometry" />
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-22" value="components.core" style="swimlane;whiteSpace=wrap;html=1;startSize=23;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="10" y="10" width="540" height="240" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-23" value="Components" style="swimlane;whiteSpace=wrap;html=1;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
-          <mxGeometry x="10" y="230" width="540" height="90" as="geometry" />
+        <mxCell id="l_DTcpemKbOkDnIudQOG-0" value="Viewer" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-22">
+          <mxGeometry x="60" y="200" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-26" value="Photo" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-23">
+        <mxCell id="l_DTcpemKbOkDnIudQOG-1" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="l_DTcpemKbOkDnIudQOG-0">
+          <mxGeometry y="26" width="160" height="8" as="geometry" />
+        </mxCell>
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-23" value="components.ui" style="swimlane;whiteSpace=wrap;html=1;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="10" y="271" width="540" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-26" value="Photo" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="-sBJLWWXFzCuZ66xZKHM-23" vertex="1">
           <mxGeometry x="10" y="40" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-27" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-26">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-27" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-26" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-28" value="Loader" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-23">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-28" value="Loader" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="-sBJLWWXFzCuZ66xZKHM-23" vertex="1">
           <mxGeometry x="370" y="40" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-29" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-28">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-29" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-28" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-24" value="Map" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-23">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-24" value="Map" style="swimlane;fontStyle=1;align=center;verticalAlign=top;childLayout=stackLayout;horizontal=1;startSize=26;horizontalStack=0;resizeParent=1;resizeParentMax=0;resizeLast=0;collapsible=1;marginBottom=0;whiteSpace=wrap;html=1;" parent="-sBJLWWXFzCuZ66xZKHM-23" vertex="1">
           <mxGeometry x="190" y="40" width="160" height="34" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-25" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" vertex="1" parent="-sBJLWWXFzCuZ66xZKHM-24">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-25" value="" style="line;strokeWidth=1;fillColor=none;align=left;verticalAlign=middle;spacingTop=-1;spacingLeft=3;spacingRight=3;rotatable=0;labelPosition=right;points=[];portConstraint=eastwest;strokeColor=inherit;" parent="-sBJLWWXFzCuZ66xZKHM-24" vertex="1">
           <mxGeometry y="26" width="160" height="8" as="geometry" />
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-30" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-9" target="-sBJLWWXFzCuZ66xZKHM-24">
-          <mxGeometry width="160" relative="1" as="geometry">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-30" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="l_DTcpemKbOkDnIudQOG-0" target="-sBJLWWXFzCuZ66xZKHM-24" edge="1">
+          <mxGeometry x="0.3561" y="-10" width="160" relative="1" as="geometry">
             <mxPoint x="370" y="300" as="sourcePoint" />
             <mxPoint x="234" y="272" as="targetPoint" />
+            <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-31" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.506;exitY=1;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-10" target="-sBJLWWXFzCuZ66xZKHM-26">
-          <mxGeometry width="160" relative="1" as="geometry">
-            <mxPoint x="370" y="300" as="sourcePoint" />
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-31" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;entryX=0.123;entryY=0.023;entryDx=0;entryDy=0;entryPerimeter=0;exitX=0.114;exitY=0.919;exitDx=0;exitDy=0;exitPerimeter=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-10" target="-sBJLWWXFzCuZ66xZKHM-26" edge="1">
+          <mxGeometry x="0.4701" width="160" relative="1" as="geometry">
+            <mxPoint x="40" y="200" as="sourcePoint" />
             <mxPoint x="530" y="300" as="targetPoint" />
+            <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-32" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=1;exitY=0.25;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-1" target="-sBJLWWXFzCuZ66xZKHM-28">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-32" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=1;exitY=0.25;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-1" target="-sBJLWWXFzCuZ66xZKHM-28" edge="1">
           <mxGeometry x="0.3304" width="160" relative="1" as="geometry">
             <mxPoint x="111" y="204" as="sourcePoint" />
             <mxPoint x="290" y="280" as="targetPoint" />
@@ -99,30 +107,37 @@
             <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-38" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13" target="-sBJLWWXFzCuZ66xZKHM-24">
-          <mxGeometry width="160" relative="1" as="geometry">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-38" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13" target="-sBJLWWXFzCuZ66xZKHM-24" edge="1">
+          <mxGeometry x="0.4416" y="4" width="160" relative="1" as="geometry">
             <mxPoint x="320" y="390" as="sourcePoint" />
             <mxPoint x="480" y="390" as="targetPoint" />
+            <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-39" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=1;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-11" target="-sBJLWWXFzCuZ66xZKHM-24">
-          <mxGeometry x="-0.5789" width="160" relative="1" as="geometry">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-39" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=1;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-11" target="-sBJLWWXFzCuZ66xZKHM-24" edge="1">
+          <mxGeometry x="0.2678" y="6" width="160" relative="1" as="geometry">
             <mxPoint x="210" y="360" as="sourcePoint" />
             <mxPoint x="240" y="270" as="targetPoint" />
             <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="-sBJLWWXFzCuZ66xZKHM-41" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13" target="-sBJLWWXFzCuZ66xZKHM-26">
+        <mxCell id="-sBJLWWXFzCuZ66xZKHM-41" value="Use" style="endArrow=open;endSize=12;dashed=1;html=1;rounded=0;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-sBJLWWXFzCuZ66xZKHM-13" target="-sBJLWWXFzCuZ66xZKHM-26" edge="1">
           <mxGeometry width="160" relative="1" as="geometry">
             <mxPoint x="150" y="370" as="sourcePoint" />
             <mxPoint x="310" y="370" as="targetPoint" />
             <Array as="points">
-              <mxPoint x="370" y="220" />
-              <mxPoint x="250" y="220" />
-              <mxPoint x="190" y="240" />
+              <mxPoint x="350" y="260" />
+              <mxPoint x="190" y="280" />
             </Array>
           </mxGeometry>
         </mxCell>
+        <mxCell id="l_DTcpemKbOkDnIudQOG-4" value="Extends" style="endArrow=block;endSize=16;endFill=0;html=1;rounded=0;exitX=0.441;exitY=0.022;exitDx=0;exitDy=0;exitPerimeter=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="l_DTcpemKbOkDnIudQOG-0">
+          <mxGeometry x="-0.2397" y="-30" width="160" relative="1" as="geometry">
+            <mxPoint x="110" y="158" as="sourcePoint" />
+            <mxPoint x="140" y="182" as="targetPoint" />
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
       </root>
     </mxGraphModel>
   </diagram>

package/docs/index.md

@@ -0,0 +1,135 @@
+# 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:panoramax@panoramax.fr).
+
+## Install
+
+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 4.0.0, just change the release in URL -->
+	<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@4.0.0/build/index.css" />
+	<script src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@4.0.0/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 any recent __Node.js__ version, 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 import Panoramax code:
+
+=== ":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>
+	```
+
+=== ":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';
+	```
+
+Once ready, you can create for example a viewer. We use web components to do so, you can create it in HTML or in other web components:
+
+```html
+<pnx-viewer
+  endpoint="https://api.panoramax.xyz/api"
+/>
+```
+
+[Many options are available to configure it finely](./reference/components/core/Viewer.md).
+
+You may also add some CSS to make sure your component has proper dimensions:
+
+```css
+pnx-viewer {
+	width: 300px;
+	height: 250px;
+}
+```
+
+Beyond classic viewer, other widgets are available and [can be tested online](https://viewer.geovisio.fr/).
+
+__Coverage map__
+
+A simple map for showing Panoramax data availability.
+
+```html
+<pnx-coverage-map
+  endpoint="https://api.panoramax.xyz/api"
+/>
+```
+
+[Many options are available as well](./reference/components/core/CoverageMap.md).
+
+__Photo Viewer__
+
+A photo-only viewer, showing one picture at a time, and offering navigation through sequence and nearby pictures.
+
+```html
+<pnx-photo-viewer
+  endpoint="https://api.panoramax.xyz/api"
+  sequence="id-to-an-existing-sequence"
+  picture="id-to-a-picture-in-this-sequence"
+/>
+```
+
+[Many options are available as well](./reference/components/core/PhotoViewer.md).
+
+__Editor__
+
+A map and photo viewer, focused on a single sequence, for previewing edits made to it.
+
+```html
+<pnx-editor
+  endpoint="https://panoramax.openstreetmap.fr/api"
+  sequence="id-to-an-existing-sequence"
+  picture="id-to-a-picture-in-this-sequence"
+/>
+```
+
+[Many options are available as well](./reference/components/core/Editor.md).