@seatmap.pro/renderer 1.55.2 → 1.57.0

package/README.md

@@ -0,0 +1,104 @@
+# @seatmap.pro/renderer
+
+A powerful and flexible interactive seat map renderer for event ticketing systems.
+
+## Overview
+
+The Seatmap.pro Renderer is a high-performance JavaScript library for rendering interactive venue seating charts. It provides a complete solution for displaying, selecting, and managing seats for events, concerts, theaters, sports venues, and more.
+
+## Features
+
+- Interactive seat selection and deselection
+- Support for general admission areas
+- Customizable seat and section styling
+- Zoom and pan functionality
+- Mobile-friendly with touch support
+- High performance rendering using Canvas/WebGL
+- Comprehensive event system for integration with ticketing platforms
+- Accessibility features
+
+## Installation
+
+```bash
+npm install @seatmap.pro/renderer
+```
+
+or
+
+```bash
+yarn add @seatmap.pro/renderer
+```
+
+## Basic Usage
+
+```javascript
+import { SeatmapBookingRenderer } from '@seatmap.pro/renderer';
+
+// Create a new renderer instance
+const renderer = new SeatmapBookingRenderer({
+  container: document.getElementById('seatmap-container'),
+  onSeatSelect: (seat) => {
+    console.log('Seat selected:', seat);
+  },
+  onSchemaDataLoaded: () => {
+    console.log('Schema data loaded successfully');
+  }
+});
+
+// Load event data
+renderer.loadEvent(eventId);
+```
+
+## Checking Version
+
+You can check the library version in several ways:
+
+### Script Tag (Standalone Bundle)
+
+```html
+<script src="seatmap-booking-renderer.js"></script>
+<script>
+  console.log(SeatmapBookingRenderer.VERSION);
+</script>
+```
+
+### NPM Module
+
+```javascript
+import { SeatmapBookingRenderer, VERSION } from '@seatmap.pro/renderer';
+
+console.log(VERSION);
+// or
+console.log(SeatmapBookingRenderer.VERSION);
+```
+
+### Instance Method
+
+```javascript
+const renderer = new SeatmapBookingRenderer(element, settings);
+console.log(renderer.getVersion());
+```
+
+## Documentation
+
+For detailed documentation, visit our:
+
+- [Knowledge Base](https://seatmap.pro/knowledge-base/) - Complete documentation for all Seatmap.pro components
+- [Renderer Specification](https://seatmap.pro/knowledge-base/renderer/spec/) - Detailed API reference for the renderer
+- [API Documentation](https://seatmap.pro/knowledge-base/api/v2/) - Additional API documentation
+
+## Examples
+
+Check out our [examples page](https://seatmap.pro/knowledge-base/renderer/sdk/) for implementation samples.
+
+## Product Website
+
+For more information, pricing, and demos, visit [https://seatmap.pro](https://seatmap.pro).
+
+## License
+
+This package is licensed under a commercial license. Please contact [support@seatmap.pro](mailto:support@seatmap.pro) for licensing information.
+
+## Support
+
+For support, please contact [support@seatmap.pro](mailto:support@seatmap.pro) or visit our [support portal](https://support.seatmap.pro).

package/lib/index.d.ts

@@ -1147,6 +1147,62 @@ interface IMinimapSettings {
      */
     showCartPins?: boolean;
 }
+/**
+ * Loading phase identifiers for progress tracking.
+ */
+type LoadingPhase = 'schema' | 'prices' | 'rows' | 'background-blurred' | 'background-preview' | 'background-full' | 'processing';
+/**
+ * Progress event data passed to onLoadProgress callback.
+ */
+interface ILoadProgressEvent {
+    phase: LoadingPhase;
+    progress: number;
+    isIndeterminate: boolean;
+    message: string;
+}
+/**
+ * Background image loaded event data.
+ * @hidden
+ */
+interface IBackgroundImageLoadedEvent {
+    type: 'blurred' | 'preview' | 'full';
+    loadTimeMs: number;
+    sizeBytes?: number;
+}
+/**
+ * Loader display style.
+ */
+type LoaderStyle = 'overlay' | 'top-bar';
+/**
+ * Loader theme configuration.
+ */
+interface ILoaderTheme {
+    overlayColor?: string;
+    overlayOpacity?: number;
+    progressBarColor?: string;
+    progressBarBackgroundColor?: string;
+    progressBarHeight?: number;
+    textColor?: string;
+    fontSize?: number;
+}
+/**
+ * Loader configuration settings.
+ */
+interface ILoaderSettings {
+    enabled: boolean;
+    style?: LoaderStyle;
+    theme?: ILoaderTheme;
+    showText?: boolean;
+    texts?: {
+        schema?: string;
+        prices?: string;
+        rows?: string;
+        backgroundBlurred?: string;
+        backgroundPreview?: string;
+        backgroundFull?: string;
+        processing?: string;
+    };
+}
 /**
  * Configuration settings for the renderer.
  * Defines various options that control the behavior and appearance of the renderer.
@@ -1162,6 +1218,12 @@ interface IRendererSettings {
      * Can be 'local', 'stage', or 'production' (default).
      */
     env?: string;
+    /**
+     * Base URL prefix for background images.
+     * Used to resolve relative image paths to absolute URLs.
+     * Absolute URLs (starting with http://, https://, or data:) are used as-is.
+     */
+    backgroundImageBaseUrl?: string;
     /**
      * External price information for seats.
      */
@@ -1261,6 +1323,11 @@ interface IRendererSettings {
      * Minimap configuration settings.
      */
     minimap?: IMinimapSettings;
+    /**
+     * Loader configuration settings.
+     * Controls the loading overlay with progress bar during event loading.
+     */
+    loader?: ILoaderSettings;
     /**
      * Option to configure zoom settings
      */
@@ -1388,6 +1455,24 @@ interface IRendererSettings {
      * schema being fully initialized.
      */
     onSchemaDataLoaded?: () => void;
+    /**
+     * Fires during loading to report progress.
+     *
+     * @remarks
+     *
+     * Progress event contains phase, progress percentage (0-100),
+     * whether the phase is indeterminate, and a status message.
+     */
+    onLoadProgress?: (event: ILoadProgressEvent) => void;
+    /**
+     * Fires when a background image has been loaded.
+     *
+     * @remarks
+     *
+     * Provides the image type (blurred, preview, full), load time in ms, and size in bytes.
+     * @hidden
+     */
+    onBackgroundImageLoaded?: (event: IBackgroundImageLoadedEvent) => void;
     /**
      * Fires while panning.
      */
@@ -1592,6 +1677,43 @@ declare class OutlineLayer {
     appendRowsOverlay(rowsFragment: string, css?: string): void;
 }
 
+interface IRendererZoomControls {
+    zoomToFit: () => void;
+    getSectionsWithCoords: () => ISectionWithCoords[];
+}
+interface ISectionTransform {
+    rotationAngle: number;
+    center: IPoint;
+    top: IPoint;
+    section: IPoint;
+    skewAngle: number;
+}
+
+interface IStageLayer {
+    destroy: () => void;
+    backgroundElement: HTMLImageElement;
+    redraw: () => void;
+    drawOffscreenCanvas: () => void;
+    drawOnscreenCanvas: (scale: number, translate: IPoint) => void;
+    getVisibleSeats: () => any[];
+    updateSize: () => void;
+    sectionViewActive: boolean;
+    getAnimationState: () => {
+        inProgress: boolean;
+        rotationAngle: number;
+        skewAngle: number;
+        duration: number;
+    };
+    applySectionViewAnimation: (section: ISectionWithCoords, options: IRendererZoomControls) => Promise<boolean>;
+    getAnimationPoint: () => IPoint;
+    sectionViewTransform: ISectionTransform;
+    /**
+     * Captures a snapshot of the full seatmap (background-sized) for use in minimap.
+     * Should resolve after the first full render finishes.
+     */
+    captureSeatmap: () => Promise<HTMLImageElement | null>;
+}
+
 /**
  * @hidden
  */
@@ -1882,10 +2004,11 @@ declare class Renderer implements IRenderer {
     private width;
     private padding;
     protected readonly context: Context;
-    private stageLayer;
+    protected stageLayer: IStageLayer;
     private selectionLayer;
     protected outlineLayer: OutlineLayer;
     private minimapLayer?;
+    private loaderLayer?;
     private service;
     private zoomToFitScale;
     private isTouchMode;
@@ -1930,6 +2053,9 @@ declare class Renderer implements IRenderer {
      * @returns The version string
      */
     getVersion(): string;
+    protected showLoader(): void;
+    protected updateLoaderProgress(phase: LoadingPhase, phaseProgress?: number): void;
+    protected completeLoader(): void;
     /**
      * Sets the interaction mode for the renderer.
      *
@@ -2462,6 +2588,7 @@ interface IAdminRendererSettings extends IRendererSettings {
  * Extends the base Renderer with admin-specific functionality.
  */
 declare class SeatmapAdminRenderer extends Renderer {
+    static readonly VERSION = "1.57.0";
     protected apiClient: BookingApiClient;
     /**
      * Creates a new instance of the AdminRenderer.
@@ -2615,9 +2742,12 @@ interface IBookingRendererSettings extends IRendererSettings {
  * Extends the base Renderer with booking-specific functionality.
  */
 declare class SeatmapBookingRenderer extends Renderer {
+    static readonly VERSION = "1.57.0";
     private apiClient;
     private stats;
-    private tags;
+    private tags?;
+    private lastSentViewBox?;
+    private debugOverlay?;
     /**
      * Creates a new instance of the SeatmapBookingRenderer.
      *
@@ -2634,7 +2764,7 @@ declare class SeatmapBookingRenderer extends Renderer {
      *
      * @throws {Error} Throws an error if the public key is undefined
      */
-    constructor(element: HTMLElement, settings?: IBookingRendererSettings, tags?: any);
+    constructor(element: HTMLElement, settings?: IBookingRendererSettings, tags?: Record<string, string | number | boolean>);
     /**
      * Gets the current view box properties.
      *
@@ -2642,11 +2772,13 @@ declare class SeatmapBookingRenderer extends Renderer {
      * @private
      */
     private getViewBox;
+    private hasViewBoxChanged;
     /**
      * Loads event's schema and prices.
      *
      * Fetches the schema, prices, and row SVG data for the specified event.
-     * Initializes analytics tracking and sets up event handlers for user interactions.
+     * Uses progressive loading: renders schema immediately with disabled interactions,
+     * then enables interactions when prices arrive.
      *
      * @example
      * ```js
@@ -2668,9 +2800,11 @@ declare class SeatmapBookingRenderer extends Renderer {
      *
      * @param eventId - Event GUID to load
      * @param sectorId - Optional sector ID to show only a specific sector
-     * @returns A promise that resolves when the data fetching is completed
+     * @returns A promise that resolves when the schema is loaded and rendered
      */
     loadEvent(eventId: string, sectorId?: number): Promise<void>;
+    private handlePricesLoaded;
+    private setupEventHandlers;
     /**
      * Creates a statistics data object for seat selection/deselection events.
      *
@@ -2696,7 +2830,7 @@ declare class SeatmapBookingRenderer extends Renderer {
  * Package version information
  * This file is automatically updated during the build process
  */
-declare const VERSION = "1.55.2";
+declare const VERSION = "1.57.0";
 
 declare const defaultZoomSettings: IZoomSettings;
 declare const mergeSettings: (defaults: IRendererSettings, settings?: Partial<IRendererSettings>) => IRendererSettings & Partial<IRendererSettings>;
@@ -2739,4 +2873,4 @@ declare class RotationAnimation {
     getAnimation(): IRotationAnimation | null;
 }
 
-export { BookingApiClient, type ById, type ColorById, type ColorSequenceSettings, type DeepPartial, type DestEvent, DestEventType, type IAdminRendererSettings, type IBaseSeat, type IBaseSector, type IBasicSeatStyle, type IBeforeSeatDrawEvent, type IBookingRendererSettings, type ICart, type ICartGa, type ICartSeat, type IClickSrcEvent, type IColoredPrice, type IConfigurationDTO, type IDeselectDestEvent, type IDragEndSrcEvent, type IDragMoveSrcEvent, type IDragStartSrcEvent, type IExtendedSeat, type IMinimapSettings, type IMouseMoveSrcEvent, type IPanDestEvent, type IPanZoomDestEvent, type IPlainSeatsDTO, type IPngBackgroundDTO, type IPoint, type IPrice, type IPriceDTO, type IPriceId, type IPriceListDTO, type IRectSelectDestEvent, type IRemovedCartGa, type IRenderer, type IRendererAnimation, type IRendererMachineContext, type IRendererSeatStyleSettings, type IRendererSettings, type IRendererSvgSectionStylesSetting, type IRendererTheme, type IRowDTO, type ISVGBackgroundDTO, type ISchemaDTO, type ISeat, type ISeatCartSwitchDestEvent, type ISeatDTO, type ISeatMouseEnterDestEvent, type ISeatMouseLeaveDestEvent, type ISeatPriceScheme, type ISeatSelectDestEvent, type ISeatStyle, type ISection, type ISectionClickDestEvent, type ISectionMouseEnterDestEvent, type ISectionMouseLeaveDestEvent, type ISectionRect, type ISectionWithCoords, type ISector, type ISectorDTO, type ISpecialPrice, type ISpecialState, type ISvgSectionStyle, type IVenueDTO, type IVisibilitySettings, type IZoomSettings, type MinimapPosition, type Nullable, Renderer, type RendererMachine, type RendererMachineReducer, type RendererMachineService, RendererSelectMode, RendererTargetType, RotationAnimation, type SeatFilter, type SeatInteractionState, SeatmapAdminRenderer, SeatmapBookingRenderer, type SrcEvent, SrcEventType, type TransformArray, VERSION, convertPricesToColored, convertPricesToColoredById, defaultZoomSettings, mergeSettings, sortPrices };
+export { BookingApiClient, type ById, type ColorById, type ColorSequenceSettings, type DeepPartial, type DestEvent, DestEventType, type IAdminRendererSettings, type IBackgroundImageLoadedEvent, type IBaseSeat, type IBaseSector, type IBasicSeatStyle, type IBeforeSeatDrawEvent, type IBookingRendererSettings, type ICart, type ICartGa, type ICartSeat, type IClickSrcEvent, type IColoredPrice, type IConfigurationDTO, type IDeselectDestEvent, type IDragEndSrcEvent, type IDragMoveSrcEvent, type IDragStartSrcEvent, type IExtendedSeat, type ILoadProgressEvent, type ILoaderSettings, type ILoaderTheme, type IMinimapSettings, type IMouseMoveSrcEvent, type IPanDestEvent, type IPanZoomDestEvent, type IPlainSeatsDTO, type IPngBackgroundDTO, type IPoint, type IPrice, type IPriceDTO, type IPriceId, type IPriceListDTO, type IRectSelectDestEvent, type IRemovedCartGa, type IRenderer, type IRendererAnimation, type IRendererMachineContext, type IRendererSeatStyleSettings, type IRendererSettings, type IRendererSvgSectionStylesSetting, type IRendererTheme, type IRowDTO, type ISVGBackgroundDTO, type ISchemaDTO, type ISeat, type ISeatCartSwitchDestEvent, type ISeatDTO, type ISeatMouseEnterDestEvent, type ISeatMouseLeaveDestEvent, type ISeatPriceScheme, type ISeatSelectDestEvent, type ISeatStyle, type ISection, type ISectionClickDestEvent, type ISectionMouseEnterDestEvent, type ISectionMouseLeaveDestEvent, type ISectionRect, type ISectionWithCoords, type ISector, type ISectorDTO, type ISpecialPrice, type ISpecialState, type ISvgSectionStyle, type IVenueDTO, type IVisibilitySettings, type IZoomSettings, type LoaderStyle, type LoadingPhase, type MinimapPosition, type Nullable, Renderer, type RendererMachine, type RendererMachineReducer, type RendererMachineService, RendererSelectMode, RendererTargetType, type RequestMetrics, RotationAnimation, type SeatFilter, type SeatInteractionState, SeatmapAdminRenderer, SeatmapBookingRenderer, type SrcEvent, SrcEventType, type TransformArray, VERSION, convertPricesToColored, convertPricesToColoredById, defaultZoomSettings, mergeSettings, sortPrices };