@panoramax/web-viewer 3.2.3-develop-fbf5d630 → 3.2.3-develop-881b0162

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-fbf5d630",
+  "version": "3.2.3-develop-881b0162",
   "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

@@ -322,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

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/translations/zh_Hant.json

@@ -162,7 +162,7 @@
         "filter_date_1month": "1 個月",
         "filter_date_1year": "1 年",
         "qualityscore_doc_2": "分數以 A/B/C/D/E 等級的形式顯示 (A 最佳、E 最差) ，並透過這個量尺視覺化顯示:",
-        "qualityscore_doc_link": "關於品質分數的計算方式，請參閱我們的文件。",
+        "qualityscore_doc_link": "深入了解品質分數",
         "qualityscore_title": "關於品質分數",
         "qualityscore_doc_1": "Panoramax 為每張相片提供品質分數，這能幫助我們輕鬆地在地圖上篩選和顯示高品質相片。",
         "qualityscore_doc_3": "它根據 GPS 精確度和相片解析度計算得出，專業設備的等級為 A、360° 運動相機的等級為 B、智慧型手機的等級為 C/D/E。",
@@ -172,7 +172,9 @@
         "loading": "正在載入…",
         "not_public": "未公開顯示",
         "thumbnail": "遊標懸停相片的縮圖",
-        "slow_loading": "地圖載入速度緩慢而且可能出現損壞"
+        "slow_loading": "地圖載入速度緩慢而且可能出現損壞",
+        "more_panoramax": "深入了解 Panoramax",
+        "map_data": "地圖資料:"
     },
     "psv": {
         "ctrlZoom": "使用 CTRL + 滑鼠滾輪縮放圖片",

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";
 			});
 	}

package/tests/components/core/Basic.test.js

@@ -103,7 +103,7 @@ describe("addEventListener", () => {
 		expect(listener).toHaveBeenCalledTimes(1);
 	});
 
-	it("should wait for map to be available", () => {
+	it("should wait for sub-component to be available", () => {
 		const listener = jest.fn();
 		global.setTimeout = jest.fn();
 		basic.getSubComponentsNames = () => ["loader", "api", "map"];
@@ -112,15 +112,6 @@ describe("addEventListener", () => {
 		expect(global.setTimeout).toHaveBeenCalled();
 	});
 
-	it("should add event listener with once option for map", () => {
-		const listener = jest.fn();
-		basic.getSubComponentsNames = () => ["loader", "api", "map"];
-		basic.map = { on: jest.fn(), once: jest.fn() };
-		basic.addEventListener("map:move", listener, { once: true });
-		expect(basic.map.on).toHaveBeenCalledTimes(0);
-		expect(basic.map.once).toHaveBeenCalledWith("move", listener);
-	});
-
 	it("adds listener to basic if no sub-component matches prefix", () => {
 		const listener = jest.fn();
 		basic.addEventListener("unknown:event", listener);