@panoramax/web-viewer 3.2.3-develop-dfee2adc → 3.2.3-develop-357c83ca

package/config/jest/mocks.js

@@ -89,6 +89,7 @@ jest.mock("maplibre-gl", () => ({
 		constructor(opts) {
 			this._mapOpts = opts;
 			this._handlers = {};
+			this._handlersOnce = {};
 		}
 		getContainer() {
 			return this._mapOpts.container;
@@ -98,6 +99,7 @@ jest.mock("maplibre-gl", () => ({
 		addLayer() {;}
 		getLayer() {;}
 		setLayoutProperty() {;}
+		setPaintProperty() {;}
 		getStyle() {
 			return {
 				layers: [],
@@ -110,8 +112,16 @@ jest.mock("maplibre-gl", () => ({
 			if(!this._handlers[type]) { this._handlers[type] = []; }
 			this._handlers[type].push(handler);
 		}
+		once(type, handler) {
+			if(!this._handlersOnce[type]) { this._handlersOnce[type] = []; }
+			this._handlersOnce[type].push(handler);
+		}
 		fire(type, opts) {
 			this._handlers[type]?.forEach(f => f(opts));
+			this._handlersOnce?.[type]?.forEach(f => f(opts));
+			if(this._handlersOnce?.[type]) {
+				this._handlersOnce[type] = [];
+			}
 		}
 	},
 	LngLat: function() {

package/docs/reference/components/core/Basic.md

@@ -164,13 +164,28 @@ Event for sequence/picture selection
 <a name="Panoramax.components.core.Basic+event_ready"></a>
 
 ### "ready"
-Event for component being ready to use (API loaded)
+Event when component is ready to use.
+This happens when loader screen disappear, with picture and map loaded.
+
+To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+```js
+// Watch API-readiness
+viewer.addEventListener("api:ready", ...); // From parent
+viewer.api.addEventListener("ready", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Basic</code>](#Panoramax.components.core.Basic)  
 <a name="Panoramax.components.core.Basic+event_broken"></a>
 
 ### "broken"
-Event for viewer failing to initially load
+Event for viewer failing to initially load.
+
+To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+```js
+// Watch API breaks
+viewer.addEventListener("api:broken", ...); // From parent
+viewer.api.addEventListener("broken", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Basic</code>](#Panoramax.components.core.Basic)  
 **Properties**

package/docs/reference/components/core/CoverageMap.md

@@ -178,13 +178,28 @@ Event for sequence/picture selection
 <a name="Panoramax.components.core.Basic+event_ready"></a>
 
 ### "ready"
-Event for component being ready to use (API loaded)
+Event when component is ready to use.
+This happens when loader screen disappear, with picture and map loaded.
+
+To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+```js
+// Watch API-readiness
+viewer.addEventListener("api:ready", ...); // From parent
+viewer.api.addEventListener("ready", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>CoverageMap</code>](#Panoramax.components.core.CoverageMap)  
 <a name="Panoramax.components.core.Basic+event_broken"></a>
 
 ### "broken"
-Event for viewer failing to initially load
+Event for viewer failing to initially load.
+
+To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+```js
+// Watch API breaks
+viewer.addEventListener("api:broken", ...); // From parent
+viewer.api.addEventListener("broken", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>CoverageMap</code>](#Panoramax.components.core.CoverageMap)  
 **Properties**

package/docs/reference/components/core/Editor.md

@@ -193,13 +193,28 @@ Event for sequence/picture selection
 <a name="Panoramax.components.core.Basic+event_ready"></a>
 
 ### "ready"
-Event for component being ready to use (API loaded)
+Event when component is ready to use.
+This happens when loader screen disappear, with picture and map loaded.
+
+To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+```js
+// Watch API-readiness
+viewer.addEventListener("api:ready", ...); // From parent
+viewer.api.addEventListener("ready", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Editor</code>](#Panoramax.components.core.Editor)  
 <a name="Panoramax.components.core.Basic+event_broken"></a>
 
 ### "broken"
-Event for viewer failing to initially load
+Event for viewer failing to initially load.
+
+To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+```js
+// Watch API breaks
+viewer.addEventListener("api:broken", ...); // From parent
+viewer.api.addEventListener("broken", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Editor</code>](#Panoramax.components.core.Editor)  
 **Properties**

package/docs/reference/components/core/PhotoViewer.md

@@ -273,13 +273,28 @@ Event for sequence/picture selection
 <a name="Panoramax.components.core.Basic+event_ready"></a>
 
 ### "ready"
-Event for component being ready to use (API loaded)
+Event when component is ready to use.
+This happens when loader screen disappear, with picture and map loaded.
+
+To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+```js
+// Watch API-readiness
+viewer.addEventListener("api:ready", ...); // From parent
+viewer.api.addEventListener("ready", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)  
 <a name="Panoramax.components.core.Basic+event_broken"></a>
 
 ### "broken"
-Event for viewer failing to initially load
+Event for viewer failing to initially load.
+
+To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+```js
+// Watch API breaks
+viewer.addEventListener("api:broken", ...); // From parent
+viewer.api.addEventListener("broken", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>PhotoViewer</code>](#Panoramax.components.core.PhotoViewer)  
 **Properties**

package/docs/reference/components/core/Viewer.md

@@ -316,13 +316,28 @@ Event for sequence/picture selection
 <a name="Panoramax.components.core.Basic+event_ready"></a>
 
 ### "ready"
-Event for component being ready to use (API loaded)
+Event when component is ready to use.
+This happens when loader screen disappear, with picture and map loaded.
+
+To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+```js
+// Watch API-readiness
+viewer.addEventListener("api:ready", ...); // From parent
+viewer.api.addEventListener("ready", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Viewer</code>](#Panoramax.components.core.Viewer)  
 <a name="Panoramax.components.core.Basic+event_broken"></a>
 
 ### "broken"
-Event for viewer failing to initially load
+Event for viewer failing to initially load.
+
+To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+```js
+// Watch API breaks
+viewer.addEventListener("api:broken", ...); // From parent
+viewer.api.addEventListener("broken", ...); // Or on sub-component
+```
 
 **Kind**: event emitted by [<code>Viewer</code>](#Panoramax.components.core.Viewer)  
 **Properties**

package/docs/reference/components/ui/Map.md

@@ -3,7 +3,7 @@
 ## Panoramax.components.ui.Map ⇐ <code>[maplibregl.Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)</code>
 **Kind**: static class of <code>Panoramax.components.ui</code>  
 **Extends**: <code>[maplibregl.Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)</code>  
-**Emits**: [<code>background-changed</code>](#Panoramax.components.ui.Map+event_background-changed), [<code>users-changed</code>](#Panoramax.components.ui.Map+event_users-changed), [<code>sequence-hover</code>](#Panoramax.components.ui.Map+event_sequence-hover), [<code>sequence-click</code>](#Panoramax.components.ui.Map+event_sequence-click), [<code>picture-click</code>](#Panoramax.components.ui.Map+event_picture-click)  
+**Emits**: [<code>background-changed</code>](#Panoramax.components.ui.Map+event_background-changed), [<code>users-changed</code>](#Panoramax.components.ui.Map+event_users-changed), [<code>sequence-hover</code>](#Panoramax.components.ui.Map+event_sequence-hover), [<code>sequence-click</code>](#Panoramax.components.ui.Map+event_sequence-click), [<code>picture-click</code>](#Panoramax.components.ui.Map+event_picture-click), [<code>ready</code>](#Panoramax.components.ui.Map+event_ready)  
 
 * [.Map](#Panoramax.components.ui.Map) ⇐ <code>[maplibregl.Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)</code>
     * [new Map(parent, container, [options])](#new_Panoramax.components.ui.Map_new)
@@ -18,6 +18,8 @@
     * [.filterUserLayersContent(dataType, filter)](#Panoramax.components.ui.Map+filterUserLayersContent)
     * [.displayPictureMarker(lon, lat, heading, [skipCenter])](#Panoramax.components.ui.Map+displayPictureMarker)
     * [.reloadLayersStyles()](#Panoramax.components.ui.Map+reloadLayersStyles)
+    * [.addEventListener(type, listener)](#Panoramax.components.ui.Map+addEventListener)
+    * ["ready"](#Panoramax.components.ui.Map+event_ready)
     * ["background-changed"](#Panoramax.components.ui.Map+event_background-changed)
     * ["users-changed"](#Panoramax.components.ui.Map+event_users-changed)
     * ["sequence-hover"](#Panoramax.components.ui.Map+event_sequence-hover)
@@ -36,6 +38,7 @@ A more complete version of Map (with filters & themes) is available through [Map
 ⚠️ This class doesn't inherit from [EventTarget](https://developer.mozilla.org/fr/docs/Web/API/EventTarget), so it doesn't have `addEventListener` and `dispatchEvent` functions.
 It uses instead [`on`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#on) and `fire` functions from MapLibre Map class.
 `fire` function doesn't take directly [`Event`](https://developer.mozilla.org/fr/docs/Web/API/Event) objects, but a string and object data.
+A shorthand `addEventListener` function is added for simpler usage.
 
 
 | Param | Type | Default | Description |
@@ -150,6 +153,27 @@ Forces reload of pictures/sequences layer styles.
 This is useful after a map theme change.
 
 **Kind**: instance method of [<code>Map</code>](#Panoramax.components.ui.Map)  
+<a name="Panoramax.components.ui.Map+addEventListener"></a>
+
+### map.addEventListener(type, listener)
+Listen to map events.
+This is a binder to [`on`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#on) and [`once`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#once) MapLibre GL functions.
+
+**Kind**: instance method of [<code>Map</code>](#Panoramax.components.ui.Map)  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| type | <code>string</code> |  | The event type to listen for |
+| listener | <code>function</code> |  | The event handler |
+| [options.once] | <code>boolean</code> | <code>false</code> | Set to true to only listen to first event. |
+
+<a name="Panoramax.components.ui.Map+event_ready"></a>
+
+### "ready"
+Event when map is ready to display.
+This includes Maplibre initial load, enough map data display and styling.
+
+**Kind**: event emitted by [<code>Map</code>](#Panoramax.components.ui.Map)  
 <a name="Panoramax.components.ui.Map+event_background-changed"></a>
 
 ### "background-changed"

package/docs/reference/components/ui/MapMore.md

@@ -18,7 +18,9 @@
     * [.filterUserLayersContent(dataType, filter)](Map.md/#Panoramax.components.ui.Map+filterUserLayersContent)
     * [.displayPictureMarker(lon, lat, heading, [skipCenter])](#Panoramax.components.ui.Map+displayPictureMarker)
     * [.reloadLayersStyles()](Map.md/#Panoramax.components.ui.Map+reloadLayersStyles)
+    * [.addEventListener(type, listener)](Map.md/#Panoramax.components.ui.Map+addEventListener)
     * ["filters-changed"](#Panoramax.components.ui.MapMore+event_filters-changed)
+    * ["ready"](Map.md/#Panoramax.components.ui.Map+event_ready)
     * ["background-changed"](Map.md/#Panoramax.components.ui.Map+event_background-changed)
     * ["users-changed"](Map.md/#Panoramax.components.ui.Map+event_users-changed)
     * ["sequence-hover"](Map.md/#Panoramax.components.ui.Map+event_sequence-hover)
@@ -151,6 +153,20 @@ Forces reload of pictures/sequences layer styles.
 This is useful after a map theme change.
 
 **Kind**: instance method of [<code>MapMore</code>](#Panoramax.components.ui.MapMore)  
+<a name="Panoramax.components.ui.Map+addEventListener"></a>
+
+### mapMore.addEventListener(type, listener)
+Listen to map events.
+This is a binder to [`on`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#on) and [`once`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#once) MapLibre GL functions.
+
+**Kind**: instance method of [<code>MapMore</code>](#Panoramax.components.ui.MapMore)  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| type | <code>string</code> |  | The event type to listen for |
+| listener | <code>function</code> |  | The event handler |
+| [options.once] | <code>boolean</code> | <code>false</code> | Set to true to only listen to first event. |
+
 <a name="Panoramax.components.ui.MapMore+event_filters-changed"></a>
 
 ### "filters-changed"
@@ -168,6 +184,13 @@ Event for filters changes
 | [theme] | <code>string</code> | Map theme |
 | [qualityscore] | <code>Array.&lt;number&gt;</code> | QualityScore values, as a list of 1 to 5 grades |
 
+<a name="Panoramax.components.ui.Map+event_ready"></a>
+
+### "ready"
+Event when map is ready to display.
+This includes Maplibre initial load, enough map data display and styling.
+
+**Kind**: event emitted by [<code>MapMore</code>](#Panoramax.components.ui.MapMore)  
 <a name="Panoramax.components.ui.Map+event_background-changed"></a>
 
 ### "background-changed"

package/docs/reference/components/ui/Photo.md

@@ -3,7 +3,7 @@
 ## Panoramax.components.ui.Photo ⇐ <code>[photo-sphere-viewer.core.Viewer](https://photo-sphere-viewer.js.org/api/classes/Core.Viewer.html)</code>
 **Kind**: static class of <code>Panoramax.components.ui</code>  
 **Extends**: <code>[photo-sphere-viewer.core.Viewer](https://photo-sphere-viewer.js.org/api/classes/Core.Viewer.html)</code>  
-**Emits**: [<code>picture-loading</code>](#Panoramax.components.ui.Photo+event_picture-loading), [<code>picture-preview-started</code>](#Panoramax.components.ui.Photo+event_picture-preview-started), [<code>picture-preview-stopped</code>](#Panoramax.components.ui.Photo+event_picture-preview-stopped), [<code>view-rotated</code>](#Panoramax.components.ui.Photo+event_view-rotated), [<code>picture-loaded</code>](#Panoramax.components.ui.Photo+event_picture-loaded), [<code>picture-tiles-loaded</code>](#Panoramax.components.ui.Photo+event_picture-tiles-loaded), [<code>transition-duration-changed</code>](#Panoramax.components.ui.Photo+event_transition-duration-changed), [<code>sequence-playing</code>](#Panoramax.components.ui.Photo+event_sequence-playing), [<code>sequence-stopped</code>](#Panoramax.components.ui.Photo+event_sequence-stopped), [<code>pictures-navigation-changed</code>](#Panoramax.components.ui.Photo+event_pictures-navigation-changed)  
+**Emits**: [<code>picture-loading</code>](#Panoramax.components.ui.Photo+event_picture-loading), [<code>picture-preview-started</code>](#Panoramax.components.ui.Photo+event_picture-preview-started), [<code>picture-preview-stopped</code>](#Panoramax.components.ui.Photo+event_picture-preview-stopped), [<code>view-rotated</code>](#Panoramax.components.ui.Photo+event_view-rotated), [<code>picture-loaded</code>](#Panoramax.components.ui.Photo+event_picture-loaded), [<code>picture-tiles-loaded</code>](#Panoramax.components.ui.Photo+event_picture-tiles-loaded), [<code>transition-duration-changed</code>](#Panoramax.components.ui.Photo+event_transition-duration-changed), [<code>sequence-playing</code>](#Panoramax.components.ui.Photo+event_sequence-playing), [<code>sequence-stopped</code>](#Panoramax.components.ui.Photo+event_sequence-stopped), [<code>pictures-navigation-changed</code>](#Panoramax.components.ui.Photo+event_pictures-navigation-changed), [<code>ready</code>](#Panoramax.components.ui.Photo+event_ready)  
 
 * [.Photo](#Panoramax.components.ui.Photo) ⇐ <code>[photo-sphere-viewer.core.Viewer](https://photo-sphere-viewer.js.org/api/classes/Core.Viewer.html)</code>
     * [new Photo(parent, container, [options])](#new_Panoramax.components.ui.Photo_new)
@@ -29,6 +29,7 @@
     * [.getPicturesNavigation()](#Panoramax.components.ui.Photo+getPicturesNavigation) ⇒ <code>string</code>
     * [.setPicturesNavigation(pn)](#Panoramax.components.ui.Photo+setPicturesNavigation)
     * [.forceRefresh()](#Panoramax.components.ui.Photo+forceRefresh)
+    * ["ready"](#Panoramax.components.ui.Photo+event_ready)
     * ["picture-loading"](#Panoramax.components.ui.Photo+event_picture-loading)
     * ["picture-preview-started"](#Panoramax.components.ui.Photo+event_picture-preview-started)
     * ["picture-preview-stopped"](#Panoramax.components.ui.Photo+event_picture-preview-stopped)
@@ -251,6 +252,13 @@ Switch the allowed navigation between pictures.
 Force reload of texture and tiles.
 
 **Kind**: instance method of [<code>Photo</code>](#Panoramax.components.ui.Photo)  
+<a name="Panoramax.components.ui.Photo+event_ready"></a>
+
+### "ready"
+Triggered once when the panorama image has been loaded and the viewer is ready to perform the first render.
+
+**Kind**: event emitted by [<code>Photo</code>](#Panoramax.components.ui.Photo)  
+**See**: [Photo Sphere Viewer documentation](https://photo-sphere-viewer.js.org/guide/events.html#ready)  
 <a name="Panoramax.components.ui.Photo+event_picture-loading"></a>
 
 ### "picture-loading"

package/docs/reference/utils/API.md

@@ -2,6 +2,7 @@
 
 ## Panoramax.utils.API
 **Kind**: static class of <code>Panoramax.utils</code>  
+**Emits**: [<code>ready</code>](#Panoramax.utils.API+event_ready), [<code>broken</code>](#Panoramax.utils.API+event_broken)  
 
 * [.API](#Panoramax.utils.API)
     * [new API(endpoint, [options])](#new_Panoramax.utils.API_new)
@@ -24,6 +25,8 @@
         * [.searchUsers(query)](#Panoramax.utils.API+searchUsers) ⇒ <code>Promise</code>
         * [.getUserName(userId)](#Panoramax.utils.API+getUserName) ⇒ <code>Promise</code>
         * [.sendReport(data)](#Panoramax.utils.API+sendReport) ⇒ <code>Promise</code>
+        * ["broken"](#Panoramax.utils.API+event_broken)
+        * ["ready"](#Panoramax.utils.API+event_ready)
     * _static_
         * [.isValidHttpUrl(str)](#Panoramax.utils.API.isValidHttpUrl) ⇒ <code>boolean</code>
         * [.isIdValid(id)](#Panoramax.utils.API.isIdValid) ⇒ <code>boolean</code>
@@ -281,6 +284,26 @@ Send a report to API
 | --- | --- | --- |
 | data | <code>object</code> | The input form data |
 
+<a name="Panoramax.utils.API+event_broken"></a>
+
+### "broken"
+Event when API is broken.
+This happens on any API loading or map styling issue.
+
+**Kind**: event emitted by [<code>API</code>](#Panoramax.utils.API)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| detail.error | <code>Error</code> | The original error |
+
+<a name="Panoramax.utils.API+event_ready"></a>
+
+### "ready"
+Event when API is ready to use.
+This happens after initial API read and map styles load.
+
+**Kind**: event emitted by [<code>API</code>](#Panoramax.utils.API)  
 <a name="Panoramax.utils.API.isValidHttpUrl"></a>
 
 ### API.isValidHttpUrl(str) ⇒ <code>boolean</code>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panoramax/web-viewer",
-  "version": "3.2.3-develop-dfee2adc",
+  "version": "3.2.3-develop-357c83ca",
   "description": "Panoramax web viewer for geolocated pictures",
   "main": "build/index.js",
   "author": "Panoramax team",
@@ -100,7 +100,7 @@
     "@photo-sphere-viewer/virtual-tour-plugin": "5.12.1",
     "json5": "^2.2.3",
     "lit": "^3.2.1",
-    "maplibre-gl": "^5.2.0",
+    "maplibre-gl": "^5.3.0",
     "pmtiles": "^4.3.0",
     "query-selector-shadow-dom": "^1.0.1"
   },

package/src/components/core/Basic.js

@@ -59,7 +59,7 @@ export default class Basic extends LitElement {
 		this.users = ["geovisio"];
 		this.mapstyle = this.getAttribute("mapstyle") || DEFAULT_TILES;
 		this.lang = this.getAttribute("lang") || null;
-		this.endpoint = null; // No default
+		this.endpoint = this.getAttribute("endpoint") || null; // No default
 		this.picture = null;
 		this.sequence = null;
 
@@ -83,6 +83,18 @@ export default class Basic extends LitElement {
 
 	connectedCallback() {
 		super.connectedCallback();
+
+		if(
+			!(this._loadsAPI && this.endpoint && this._loadsAPI === this.endpoint)
+			&& !(this.api && this.api._endpoint === this.endpoint)
+			&& this.endpoint
+		) {
+			if(this._loadsAPI || this.api) {
+				delete this.api;
+				delete this._loadsAPI;
+			}
+			this._setupAPI();
+		}
 	}
 
 	/**
@@ -310,20 +322,8 @@ export default class Basic extends LitElement {
 		if(prefix && this.getSubComponentsNames().includes(prefix)) {
 			const subType = type.substring(prefix.length+1);
 
-			// Special handling for map: not eventtarget
-			if(prefix === "map") {
-				if(this.map?.on) {
-					if(options?.once) { this.map.once(subType, listener); }
-					else { this.map.on(subType, listener); }
-				}
-				else {
-					setTimeout(() => {
-						this.addEventListener(type, listener, options);
-					}, 50);
-				}
-			}
 			// Add directly if available
-			else if(this[prefix]?.addEventListener) {
+			if(this[prefix]?.addEventListener) {
 				this[prefix].addEventListener(subType, listener, options);
 			}
 			// Wait for addEventListener to be available
@@ -340,7 +340,9 @@ export default class Basic extends LitElement {
 	/** @private */
 	static GetJSONConverter() {
 		return {
-			fromAttribute: (value) => JSON5.parse(value),
+			fromAttribute: (value) => {
+				return typeof value === "object" ? value : JSON5.parse(value);
+			},
 			toAttribute: (value) => JSON.stringify(value)
 		};
 	}

package/src/components/core/Viewer.js

@@ -253,11 +253,11 @@ export default class Viewer extends PhotoViewer {
 		return new Promise(resolve => {
 			waiter = setInterval(() => {
 				if(typeof this.map === "object") {
-					if(this.map.loaded?.()) {
+					if(this.map?.loaded?.()) {
 						clearInterval(waiter);
 						resolve();
 					}
-					else if(this.map.once) {
+					else if(this.map?.once) {
 						this.map.once("render", () => {
 							clearInterval(waiter);
 							resolve();

package/src/components/ui/Loader.js

@@ -110,7 +110,15 @@ export default class Loader extends LitElement {
 			setTimeout(() => this.parentNode.removeChild(this), 2000);
 
 			/**
-			 * Event for component being ready to use (API loaded)
+			 * Event when component is ready to use.
+			 * This happens when loader screen disappear, with picture and map loaded.
+			 * 
+			 * To follow more precisely loading steps, you can also watch for sub-components `ready` events.
+			 * ```js
+			 * // Watch API-readiness
+			 * viewer.addEventListener("api:ready", ...); // From parent
+			 * viewer.api.addEventListener("ready", ...); // Or on sub-component
+			 * ```
 			 * @event Panoramax.components.core.Basic#ready
 			 * @type {CustomEvent}
 			 */
@@ -138,7 +146,14 @@ export default class Loader extends LitElement {
 			const errLabel = errMeaningful || "Panoramax JS had a blocking exception";
 
 			/**
-			 * Event for viewer failing to initially load
+			 * Event for viewer failing to initially load.
+			 * 
+			 * To follow more precisely loading failures, you can also watch for sub-components `broken` events.
+			 * ```js
+			 * // Watch API breaks
+			 * viewer.addEventListener("api:broken", ...); // From parent
+			 * viewer.api.addEventListener("broken", ...); // Or on sub-component
+			 * ```
 			 * @event Panoramax.components.core.Basic#broken
 			 * @type {CustomEvent}
 			 * @property {string} detail.error The user-friendly error message to display

package/src/components/ui/Map.js

@@ -28,6 +28,7 @@ maplibregl.addProtocol("pmtiles", new pmtiles.Protocol().tile);
  * ⚠️ This class doesn't inherit from [EventTarget](https://developer.mozilla.org/fr/docs/Web/API/EventTarget), so it doesn't have `addEventListener` and `dispatchEvent` functions.
  * It uses instead [`on`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#on) and `fire` functions from MapLibre Map class.
  * `fire` function doesn't take directly [`Event`](https://developer.mozilla.org/fr/docs/Web/API/Event) objects, but a string and object data.
+ * A shorthand `addEventListener` function is added for simpler usage.
  * @class Panoramax.components.ui.Map
  * @extends [maplibregl.Map](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/)
  * @param {Panoramax.components.core.Basic} parent The parent view
@@ -41,6 +42,7 @@ maplibregl.addProtocol("pmtiles", new pmtiles.Protocol().tile);
  * @fires Panoramax.components.ui.Map#sequence-hover
  * @fires Panoramax.components.ui.Map#sequence-click
  * @fires Panoramax.components.ui.Map#picture-click
+ * @fires Panoramax.components.ui.Map#ready
  * @example
  * const map = new Panoramax.components.ui.Map(viewer, mapNode, {center: {lat: 48.7, lng: -1.7}});
  */
@@ -103,7 +105,7 @@ export default class Map extends maplibregl.Map {
 
 		// Timeout for initial loading
 		setTimeout(() => {
-			if(!this.loaded() && this._parent.loader.isVisible()) {
+			if(!this.loaded() && this._parent?.loader.isVisible()) {
 				this._parent.loader.dismiss({}, this._parent._t.map.slow_loading, () => {});
 			}
 		}, 15000);
@@ -118,6 +120,14 @@ export default class Map extends maplibregl.Map {
 		this.resize();
 		await this.setVisibleUsers(this._parent.users);
 		this.reloadLayersStyles();
+
+		/**
+		 * Event when map is ready to display.
+		 * This includes Maplibre initial load, enough map data display and styling.
+		 * @event Panoramax.components.ui.Map#ready
+		 * @type {maplibregl.util.evented.Event}
+		 */
+		this.fire("ready");
 	}
 
 	/**
@@ -917,4 +927,17 @@ export default class Map extends maplibregl.Map {
 			});
 		}
 	}
+
+	/**
+	 * Listen to map events.
+	 * This is a binder to [`on`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#on) and [`once`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#once) MapLibre GL functions.
+	 * @param {string} type The event type to listen for
+	 * @param {function} listener The event handler
+	 * @param {boolean} [options.once=false] Set to true to only listen to first event.
+	 * @memberof Panoramax.components.ui.Map#
+	 */
+	addEventListener(type, listener, options = {}) {
+		if(options?.once) { this.once(type, listener); }
+		else { this.on(type, listener); }
+	}
 }

package/src/components/ui/Photo.js

@@ -43,6 +43,14 @@ export const PIC_MAX_STAY_DURATION = 3000;
 
 PSViewer.useNewAnglesOrder = true;
 
+/**
+ * Triggered once when the panorama image has been loaded and the viewer is ready to perform the first render.
+ * @see [Photo Sphere Viewer documentation](https://photo-sphere-viewer.js.org/guide/events.html#ready)
+ * @event Panoramax.components.ui.Photo#ready
+ * @memberof Panoramax.components.ui.Photo
+ * @type {Event}
+ */
+
 /**
  * Photo is the component showing a single picture.
  * It uses Photo Sphere Viewer as a basis, and pre-configure dialog with STAC API.
@@ -68,6 +76,7 @@ PSViewer.useNewAnglesOrder = true;
  * @fires Panoramax.components.ui.Photo#sequence-playing
  * @fires Panoramax.components.ui.Photo#sequence-stopped
  * @fires Panoramax.components.ui.Photo#pictures-navigation-changed
+ * @fires Panoramax.components.ui.Photo#ready
  * @example
  * const psv = new Panoramax.components.ui.Photo(viewer, psvNode, {transitionDuration: 500})
  */

package/src/utils/API.js

@@ -6,6 +6,8 @@ import { isNullId } from "./utils";
  *
  * @class Panoramax.utils.API
  * @typicalname api
+ * @fires Panoramax.utils.API#ready
+ * @fires Panoramax.utils.API#broken
  * @param {string} endpoint The endpoint. It corresponds to the <a href="https://github.com/radiantearth/stac-api-spec/blob/main/overview.md#example-landing-page">STAC landing page</a>, with all links describing the API capabilites.
  * @param {object} [options] Options
  * @param {string|object} [options.style] General map style
@@ -14,10 +16,14 @@ import { isNullId } from "./utils";
  * @param {object} [options.fetch] Set custom options for fetch calls made against API ([same syntax as fetch options parameter](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters))
  * @param {string[]} [options.users] List of initial user IDs to load map styles for
  */
-export default class API {
+export default class API extends EventTarget {
 	constructor(endpoint, options = {}) {
+		super();
+		
 		if(endpoint === null || endpoint === undefined || typeof endpoint !== "string") {
-			throw new Error("endpoint parameter is empty or not a valid string");
+			const e = new Error("endpoint parameter is empty or not a valid string");
+			this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+			throw e;
 		}
 
 		// Parse local endpoints
@@ -27,7 +33,9 @@ export default class API {
 
 		// Check endpoint
 		if(!API.isValidHttpUrl(endpoint)) {
-			throw new Error(`endpoint parameter is not a valid URL: ${endpoint}`);
+			const e = new Error(`endpoint parameter is not a valid URL: ${endpoint}`);
+			this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+			throw e;
 		}
 
 		this._endpoint = endpoint;
@@ -43,11 +51,30 @@ export default class API {
 			.catch(e => {
 				this._isReady = -1;
 				console.error(e);
+
+				/**
+				 * Event when API is broken.
+				 * This happens on any API loading or map styling issue.
+				 * @event Panoramax.utils.API#broken
+				 * @type {CustomEvent}
+				 * @property {Error} detail.error The original error
+				 */
+				this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+
 				return Promise.reject("Viewer failed to communicate with API");
 			})
 			.then(() => this._loadMapStyles(options.style, options.users))
 			.then(() => {
 				this._isReady = 1;
+
+				/**
+				 * Event when API is ready to use.
+				 * This happens after initial API read and map styles load.
+				 * @event Panoramax.utils.API#ready
+				 * @type {Event}
+				 */
+				this.dispatchEvent(new Event("ready"));
+
 				return "API is ready";
 			});
 	}