@micrio/client 5.4.16 → 5.4.17

package/micrio.min.d.ts

@@ -4,7 +4,7 @@ declare module '@micrio/client' {
 	 * Defines the current version of the Micrio library.
 	 * This constant is used internally and exposed statically via `HTMLMicrioElement.VERSION`.
 	 */
-	export const VERSION = "5.4.16";
+	export const VERSION = "5.4.17";
 	/**
 	 * Loads an image texture asynchronously. Adds the request to the queue
 	 * and returns a Promise that resolves with the TextureBitmap or rejects on error.
@@ -12,6 +12,12 @@ declare module '@micrio/client' {
 	 * @returns A Promise resolving to the loaded TextureBitmap.
 	 */
 	export const loadTexture: (src: string) => Promise<TextureBitmap>;
+	/**
+	 * Converts seconds into a human-readable time string (hh?:mm:ss).
+	 * @param s Time in seconds. Can be negative for remaining time display.
+	 * @returns Formatted time string (e.g., "1:23", "1:05:09", "-0:15").
+	 */
+	export function parseTime(s: number): string;
 	export type PREDEFINED = [string, Models.ImageInfo.ImageInfo, Models.ImageData.ImageData | undefined];
 	/** Enum for identifying media type. */
 	export enum MediaType {
@@ -27,59 +33,32 @@ declare module '@micrio/client' {
 		YouTube = 1,
 		Vimeo = 2
 	}
+	export { isLegacyViews };
 	/**
-	 * Converts seconds into a human-readable time string (hh?:mm:ss).
-	 * @param s Time in seconds. Can be negative for remaining time display.
-	 * @returns Formatted time string (e.g., "1:23", "1:05:09", "-0:15").
-	 */
-	export function parseTime(s: number): string;
-	export const isLegacyViews: (i: Models.ImageInfo.ImageInfo) => boolean;
-	/**
-	 * Decodes a character from a Micrio ID into its numeric value (used for V4 short IDs).
-	 * @private
-	 */
-	export const getIdVal: (a: string) => number;
-	/** Checks if an ID likely belongs to the V5 format (6 or 7 characters). */
-	export const idIsV5: (id: string) => boolean;
-	/** Clamps a view rectangle the image bounds [0, 0, 1, 1]. */
-	export const limitView: (v: Models.Camera.View) => Models.Camera.View;
-	/**
-	 * Calculates the 3D vector and navigation parameters between two images in a 360 space.
-	 * Used for smooth transitions between waypoints.
-	 * @private
-	 * @param micrio The main HTMLMicrioElement instance.
-	 * @param targetId The ID of the target image.
-	 * @returns An object containing the vector, normalized vector, direction, and transition parameters, or undefined if calculation fails.
+	 * Global utility functions used throughout the Micrio application.
+	 * Re-exports all utility modules for convenient importing.
+	 * @author Marcel Duin <marcel@micr.io>
 	 */
-	export function getSpaceVector(micrio: HTMLMicrioElement, targetId: string): {
-		vector: Models.Camera.Vector;
-		directionX: number;
-		v: Models.Spaces.DirectionVector;
-		vN: Models.Spaces.DirectionVector;
-	} | undefined;
+	export { MicrioError } from "ts/utils/error";
+	export { pyth, mod, limitView } from "ts/utils/math";
+	export { clone, deepCopy } from "ts/utils/object";
+	export { createGUID, slugify, parseTime } from "ts/utils/string";
+	export { Browser } from "ts/utils/browser";
+	export { sleep, notypecheck, loadScript } from "ts/utils/dom";
+	export { once, after } from "ts/utils/store";
+	export { View } from "ts/utils/view";
+	export { sanitizeAsset, isLegacyViews, sanitizeImageInfo, sanitizeImageData, sanitizeSpaceData, sanitizeMarker, sanitizeVideoTour } from "ts/utils/sanitize";
+	export { jsonCache, fetchJson, isFetching, getLocalData, fetchInfo, fetchAlbumInfo } from "ts/utils/fetch";
+	export { loadSerialTour } from "ts/utils/tour";
+	export { getIdVal, idIsV5 } from "ts/utils/id";
+	export { getSpaceVector } from "ts/utils/space";
+	export { hasNativeHLS } from "ts/utils/media";
 	/**
-	 * Checks if the browser natively supports HLS video playback via the `<video>` element.
-	 * @private
-	 * @param video Optional HTMLVideoElement to check (defaults to creating a temporary one).
-	 * @returns True if native HLS support is detected.
+	 * Global utility functions used throughout the Micrio application.
+	 * This file re-exports all utilities from the modular utils/ directory.
+	 * @author Marcel Duin <marcel@micr.io>
 	 */
-	export const hasNativeHLS: (video?: HTMLMediaElement) => boolean;
-	export const View: {
-		/** Casts a legacy view array ([x0, y0, x1, y1]) to [x0,y0,width,height]. */
-		fromLegacy: (v?: Models.Camera.ViewRect | Models.Camera.View) => Models.Camera.View | undefined;
-		toCenterJSON: (v: Models.Camera.View) => {
-			centerX: number;
-			centerY: number;
-			width: number;
-			height: number;
-		};
-		rectToCenterJSON: (v: Models.Camera.View) => {
-			centerX: number;
-			centerY: number;
-			width: number;
-			height: number;
-		};
-	};
+	export * from "ts/utils/index";
 	/**
 	 * Defines various enums used throughout the Micrio application,
 	 * primarily for standardizing action types and option values.
@@ -413,6 +392,7 @@ declare module '@micrio/client' {
 		/**
 		 * Loads and instantiates the WebAssembly module.
 		 * @returns A Promise that resolves when the Wasm module is ready.
+		 * @throws Error if WebAssembly binary loading or instantiation fails
 		*/
 		load(): Promise<void>;
 		/** Unbinds event listeners, stops rendering, and cleans up resources. */
@@ -2325,6 +2305,326 @@ declare module '@micrio/client' {
 		/** Disposes WebGL resources used by the PostProcessor. */
 		dispose(): void;
 	}
+	/** Type alias for common event types handled. */
+	export type AllEvents = WheelEvent | MouseEvent | TouchEvent;
+	/** Internal state variables used by the Events controller. */
+	export type EventStateVars = {
+		/** Dragging state */
+		drag: {
+			/** Previous pointer coordinates [x, y] during drag. */
+			prev: number[] | undefined;
+			/** Start coordinates and timestamp [x, y, time] of the drag. */
+			start: number[];
+		};
+		/** Double-tap state */
+		dbltap: {
+			/** Timestamp of the last tap. */
+			lastTapped: number;
+		};
+		/** Pinching state */
+		pinch: {
+			/** The image being pinched (relevant for split-screen). */
+			image: MicrioImage | undefined;
+			/** Initial distance between pinch points. */
+			sDst: number;
+			/** Was panning active before pinching started? */
+			wasPanning: boolean;
+		};
+		/** State for debouncing 'update' events. */
+		updates: {
+			/** Timeout ID for the debounced update. */
+			to: number;
+			/** Stack of event types that triggered the update. */
+			stack: string[];
+		};
+	};
+	/** Flag indicating if passive event listeners are supported (assumed true). */
+	export const supportsPassive = true;
+	/** Event listener options for passive listeners. */
+	export const eventPassive: AddEventListenerOptions;
+	/** Event listener options for passive, capturing listeners. */
+	export const eventPassiveCapture: AddEventListenerOptions;
+	/** Event listener options for non-passive listeners (allowing preventDefault). */
+	export const noEventPassive: AddEventListenerOptions;
+	/** Utility function to stop event propagation and prevent default browser behavior. */
+	export function cancelPrevent(e: AllEvents): void;
+	/**
+	 * Context object providing access to shared state for event handlers.
+	 * This is passed to each handler module to avoid circular dependencies.
+	 */
+	export interface EventContext {
+		/** The main Micrio element */
+		micrio: HTMLMicrioElement;
+		/** The canvas element where events are captured */
+		el: HTMLCanvasElement;
+		/** Whether events are currently enabled */
+		isEnabled(): boolean;
+		/** Whether the user is currently panning */
+		isPanning(): boolean;
+		/** Whether the user is currently pinching */
+		isPinching(): boolean;
+		/** Set panning state */
+		setPanning(value: boolean): void;
+		/** Set pinching state */
+		setPinching(value: boolean): void;
+		/** Get/set wheeling state */
+		isWheeling(): boolean;
+		setWheeling(value: boolean): void;
+		/** Whether Ctrl/Cmd key is required for wheel zoom */
+		isControlZoom(): boolean;
+		/** Whether two fingers are required for touch panning */
+		isTwoFingerPan(): boolean;
+		/** Event state variables */
+		vars: EventStateVars;
+		/** Get visible images */
+		getVisible(): MicrioImage[] | undefined;
+		/** Get image under coordinates */
+		getImage(c: {
+			x: number;
+			y: number;
+		}): MicrioImage | undefined;
+		/** Dispatch custom event */
+		dispatch<K extends keyof Models.MicrioEventDetails>(type: K, detail?: Models.MicrioEventDetails[K]): void;
+		/** Active pointers map for pinch detection */
+		activePointers: Map<number, {
+			x: number;
+			y: number;
+		}>;
+		/** Captured pointer ID for dragging */
+		capturedPointerId: number | undefined;
+		setCapturedPointerId(id: number | undefined): void;
+		/** Current pinch factor */
+		pinchFactor: number | undefined;
+		setPinchFactor(value: number | undefined): void;
+		/** Previous scale during gestures */
+		pScale: number;
+		setPScale(value: number): void;
+		/** Has used Ctrl for zoom */
+		hasUsedCtrl: boolean;
+		setHasUsedCtrl(value: boolean): void;
+		/** Has touch support */
+		hasTouch: boolean;
+	}
+	/**
+	 * Drag/pan event handler module.
+	 * Handles pointer down/move/up events for panning the image.
+	 */
+	export class DragHandler {
+		private ctx;
+		private hooked;
+		constructor(ctx: EventContext);
+		/** Hooks pointer down/move/up listeners for drag panning. */
+		hook(): void;
+		/** Unhooks pointer listeners for drag panning. */
+		unhook(): void;
+		/**
+		 * Handles the start of a drag/pan operation (pointerdown).
+		 * @param e The PointerEvent.
+		 * @param force If true, forces drag start even if target isn't the canvas.
+		 */
+		start(e: PointerEvent, force?: boolean): void;
+		/**
+		 * Handles pointer movement during a drag/pan operation.
+		 * @param e The PointerEvent.
+		 */
+		private move;
+		/**
+		 * Handles the end of a drag/pan operation (pointerup).
+		 * @param e Optional PointerEvent.
+		 * @param noKinetic If true, prevents kinetic coasting animation.
+		 * @param noDispatch If true, suppresses the 'panend' event.
+		 */
+		stop(e?: PointerEvent, noKinetic?: boolean, noDispatch?: boolean): void;
+	}
+	/**
+	 * Touch pinch event handler module (iOS).
+	 * Handles touchstart/touchmove/touchend events for pinch-to-zoom gestures.
+	 */
+	export class PinchHandler {
+		private ctx;
+		private dragHandler;
+		constructor(ctx: EventContext, dragHandler: DragHandler);
+		/** Hooks touch pinch event listeners (iOS only). */
+		hook(): void;
+		/** Unhooks touch pinch event listeners. */
+		unhook(): void;
+		/**
+		 * Handles the start of a touch pinch gesture (touchstart with two fingers).
+		 * @param e The TouchEvent.
+		 */
+		start(e: TouchEvent | Event): void;
+		/**
+		 * Handles touch movement during a pinch gesture.
+		 * @param e The TouchEvent.
+		 */
+		private move;
+		/**
+		 * Handles the end of a touch pinch gesture (touchend).
+		 * @param e The TouchEvent or MouseEvent.
+		 */
+		stop(e: MouseEvent | TouchEvent): void;
+	}
+	/**
+	 * Pointer-based pinch event handler module.
+	 * Handles pointerdown/pointermove/pointerup events for pinch-to-zoom gestures.
+	 * Works on Windows touchscreens, Android, and other platforms supporting Pointer Events.
+	 */
+	export class PointerPinchHandler {
+		private ctx;
+		private dragHandler;
+		constructor(ctx: EventContext, dragHandler: DragHandler);
+		/** Hooks pointer pinch event listeners. */
+		hook(): void;
+		/** Unhooks pointer pinch event listeners. */
+		unhook(): void;
+		/**
+		 * Handles pointer down for multi-touch pinch detection.
+		 * @param e The PointerEvent.
+		 */
+		start(e: PointerEvent): void;
+		/**
+		 * Handles pointer move during a multi-touch pinch gesture.
+		 * @param e The PointerEvent.
+		 */
+		private move;
+		/**
+		 * Handles pointer up/cancel - always called to track active pointers.
+		 * Also ends pinch gesture when needed.
+		 * @param e The PointerEvent.
+		 */
+		end(e: PointerEvent): void;
+	}
+	/**
+	 * macOS trackpad gesture event handler module.
+	 * Handles gesturestart/gesturechange/gestureend events for trackpad pinch-to-zoom.
+	 */
+	export class GestureHandler {
+		private ctx;
+		constructor(ctx: EventContext);
+		/** Hooks macOS gesture event listeners. */
+		hook(): void;
+		/** Unhooks macOS gesture event listeners. */
+		unhook(): void;
+		/**
+		 * GestureEvent interface for macOS trackpad gestures.
+		 * @param e The Event object.
+		 * @returns Gesture data or null if not a gesture event.
+		 */
+		private getGestureEvent;
+		/**
+		 * Handles macOS trackpad gesture events.
+		 * Translates gesture scale into zoom actions.
+		 * @param e The GestureEvent.
+		 */
+		private handle;
+	}
+	/**
+	 * Mouse wheel/scroll event handler module.
+	 * Handles wheel events for zooming and panning.
+	 */
+	export class WheelHandler {
+		private ctx;
+		/** Flag indicating if scroll listeners are attached. */
+		hooked: boolean;
+		/** Timeout ID for debouncing the 'wheelend' event. */
+		private wheelEndTo;
+		constructor(ctx: EventContext);
+		/** Hooks mouse wheel/scroll event listeners. */
+		hook(): void;
+		/** Unhooks mouse wheel/scroll event listeners. */
+		unhook(): void;
+		/**
+		 * Handles mouse wheel events for zooming.
+		 * @param e The WheelEvent.
+		 * @param force Force handling even if conditions normally prevent it.
+		 * @param offX Optional X offset for zoom focus.
+		 */
+		handle(e: WheelEvent | Event, force?: boolean, offX?: number): void;
+		/** Clears the wheeling state after a short delay. */
+		private end;
+	}
+	/**
+	 * Keyboard event handler module.
+	 * Handles keydown events for keyboard navigation (arrows, +/-).
+	 */
+	export class KeyboardHandler {
+		private ctx;
+		constructor(ctx: EventContext);
+		/** Hooks keyboard event listeners. */
+		hook(): void;
+		/** Unhooks keyboard event listeners. */
+		unhook(): void;
+		/**
+		 * Handles keydown events for keyboard navigation.
+		 * @param e The KeyboardEvent.
+		 */
+		private handle;
+	}
+	/**
+	 * Double-tap/click event handler module.
+	 * Handles double-tap (touch) and double-click (mouse) events for zooming.
+	 */
+	export class DoubleTapHandler {
+		private ctx;
+		constructor(ctx: EventContext);
+		/** Hooks double-tap event listener (mobile). */
+		hookTap(): void;
+		/** Unhooks double-tap event listener. */
+		unhookTap(): void;
+		/** Hooks double-click event listener (desktop). */
+		hookClick(): void;
+		/** Unhooks double-click event listener. */
+		unhookClick(): void;
+		/**
+		 * Handles double-tap detection on touch devices.
+		 * @param e The TouchEvent.
+		 */
+		private tap;
+		/**
+		 * Handles double-click (mouse) or double-tap (touch) events for zooming.
+		 * Zooms in if zoomed out, zooms out fully otherwise.
+		 * @param e The MouseEvent or TouchEvent.
+		 */
+		private click;
+	}
+	/**
+	 * List of internal Micrio event types that should trigger a debounced 'update' event.
+	 * The 'update' event signals that the overall state relevant for external integrations might have changed.
+	 * @readonly
+	 */
+	export const UpdateEvents: (keyof Models.MicrioEventMap)[];
+	/**
+	 * Update event handler module.
+	 * Manages debounced 'update' event dispatching when internal state changes.
+	 */
+	export class UpdateHandler {
+		private ctx;
+		constructor(ctx: EventContext);
+		/** Hooks listeners for events that should trigger a debounced 'update' event. */
+		hook(): void;
+		/** Unhooks listeners for the debounced 'update' event. */
+		unhook(): void;
+		/**
+		 * Event listener callback that queues the event type and triggers the debounced dispatch.
+		 * @param e The Event object.
+		 */
+		private handleEvent;
+		/**
+		 * Dispatches the 'update' event with the accumulated event types and current state.
+		 * Clears the event stack.
+		 */
+		private dispatch;
+	}
+	export { DragHandler } from "ts/events/drag";
+	export { PinchHandler } from "ts/events/pinch";
+	export { PointerPinchHandler } from "ts/events/pointer-pinch";
+	export { GestureHandler } from "ts/events/gesture";
+	export { WheelHandler } from "ts/events/wheel";
+	export { KeyboardHandler } from "ts/events/keyboard";
+	export { DoubleTapHandler } from "ts/events/doubletap";
+	export { UpdateHandler, UpdateEvents } from "ts/events/update";
+	export { type AllEvents, type EventStateVars, type EventContext, supportsPassive, eventPassive, eventPassiveCapture, noEventPassive, cancelPrevent, } from "ts/events/shared";
+	export { UpdateEvents } from "ts/events/index";
 	/**
 	 * Handles user input events (mouse, touch, keyboard, wheel, gestures) for the Micrio viewer.
 	 * Translates browser events into camera movements (pan, zoom), dispatches custom Micrio events,
@@ -2332,13 +2632,35 @@ declare module '@micrio/client' {
 	 * Accessed via `micrio.events`.
 	 * @author Marcel Duin <marcel@micr.io>
 	 */
-	export class Events {
+	export class Events implements EventContext {
 		/** Writable Svelte store indicating if event handling is currently enabled. Set to false during tours or animations. */
 		enabled: Writable<boolean>;
 		/** Getter for the current value of the {@link enabled} store. */
 		get $enabled(): boolean;
 		/** Current pinch zoom factor relative to the start of the pinch. Undefined when not pinching. */
 		pinchFactor: number | undefined;
+		private dragHandler;
+		private pinchHandler;
+		private pointerPinchHandler;
+		private gestureHandler;
+		private wheelHandler;
+		private keyboardHandler;
+		private doubleTapHandler;
+		private updateHandler;
+		isEnabled(): boolean;
+		isPanning(): boolean;
+		isPinching(): boolean;
+		setPanning(value: boolean): void;
+		setPinching(value: boolean): void;
+		isWheeling(): boolean;
+		setWheeling(value: boolean): void;
+		isControlZoom(): boolean;
+		isTwoFingerPan(): boolean;
+		getVisible(): MicrioImage[] | undefined;
+		setCapturedPointerId(id: number | undefined): void;
+		setPinchFactor(value: number | undefined): void;
+		setPScale(value: number): void;
+		setHasUsedCtrl(value: boolean): void;
 		/**
 		 * Checks if the user is currently interacting with the map via panning, pinching, or wheeling.
 		 * @returns True if the user is actively navigating.