hart-estate-widget 3.8.5 → 3.9.0

package/README.md

@@ -97,7 +97,7 @@ const createWidget = async (logoUrl) => {
   const planData = await widgetApiHandler.loadWidgetData(planId);
   const options = { // the parameters you need that are described below in "Parameters"
     ...planData.parsed,
-    API_URL: WIDGET_API_URL,
+    api_url: WIDGET_API_URL,
     rotationMode: rotationModes.DEFAULT,
     tabs: ['panorama', 'rotation'],
     locale: 'en',
@@ -146,124 +146,218 @@ body
 ## Parameters:
 Here you can see a list of accessible options and examples of usage. There are accessible values for each option below in the block "Types of Elements".
 
-```js
-{
-  // elements  
-  tabs: ['rotation', 'panorama'], // included elements
-
-  // logo
-  logo: '', // path/link to the logo
-  logoUrl: '', // link opened when logo is clicked
-
-  // localization
-  // accessible languages are in "Types of Elements"
-  locale: 'en', // ISO 639 language code
-
-  // width/height
+```ts
+type TConfig = {
+  /** Widget API Backend URL */
+  api_url: 'https://backend.example.com/';
+
+  /** Path/link to the logo */
+  logo: '';
+  /** Link opened when logo is clicked */
+  logoUrl: '';
+  
+  /** Widget container offsetWidth */
   width: 1920,
+  /** Widget container offsetHeight */
   height: 1080,
-  resizable: true, // automatically resize the widget to the size of the container when the window is resized
-
-  // values
-  rotationMode: '', // mode of operation for plan images
-  panoramaFov: 75, // camera field of view angle for panoramic tour
-  preloadPerPanoramaCount: 3, // the number of panoramas loaded next to the current one to optimize transitions
-  enablePreloadMasks: true, // also preload depth textures
-  forcePreloadNonCached: true, // give preloading a higher priority for unloaded panoramas than by distance from the current one
-  forceTopViewOnMap: true, // show top view map instead of standard by default
-  topViewResolutionUpscale: 2, // upscale top view map by coef (200px * 2 = 400px)
-  enableCameraTransitionBetweenPanoramas: true, // enable/disable camera rotation transition between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON)
-  enableCameraRotationBetweenPanoramas: true, // enable/disable camera rotation between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON)
-  instructionVisible: true, // enable/disable modal of instruction in 3D tour
-  autoRotate: false, // enable/disable auto rotation in 3D tour
-  primaryCameraPointId: null, // primary camera point ID for panorama tour
-  floors: [ // array of floors, contains 360° images and panoramic tour data
-    {
-      original_plan_img: '',  // path to the original plan image (required for panoramic tour)
-      styled_plan_img: '',  // path to the styled plan image (required for panoramic tour)
-      top_view_img: '',  // path to the top view image
-      panorama: '',  // type of panorama and paths to 360° images
-      rotate: '',  // type of images and paths to circular view images (order is mandatory)
-    }
-  ],
-
-  // colors
+  /** Automatically resize the widget to the size of the container when the window is resized */
+  resizable: true;
+
+  /** Widget localization language (default: en) */
+  locale: 'en'
+
+  /** Use door proactive rectangle instead of door icon. */
+  enableDoorVisibility: false;
+  /** Type of images that will present in rotation tab, used as whitelist filter, defaults ['carousel', 'plan', 'topView'] */
+  availableRotationSteps: ['carousel', 'plan', 'topView'];
+
+  /** Available widget tabs, defaults ['rotation', 'plan', 'panorama'] */
+  tabs: ['rotation', 'plan', 'panorama'];
+
+  /**
+   * Mode of operation for plan images
+   * - `rotationModes.DEFAULT` - top view mode (multiple perspectives) and stylized plan view
+   * - `rotationModes.THREESIXTY` - image scrolling mode for circular view
+   * */
+  rotationMode: rotationModes.DEFAULT;
+  /** Camera persective FOV */
+  panoramaFov: 75;
+  /** Enable/disable camera rotation between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON) */
+  enableCameraRotationBetweenPanoramas: true;
+  /** Enable/disable transition for camera rotation between panoramas (if CameraPoint.Rotation.Yaw is defined in JSON and enableCameraRotationBetweenPanoramas enabled) */
+  enableCameraTransitionBetweenPanoramas: false;
+  /** Override primary camera point ID over JSON */
+  primaryCameraPointId: 'CameraPointId12345678-12345678-12345678';
+
+  /**
+   * Widget color settings
+   * - `main`: main color of buttons, elements
+   * - `mainText`: text color for buttons, elements contrasting with the main color
+   * */
   colors: {
-    main: '#HEX', // main color of buttons, elements
-    mainText: '#HEX', // text color for buttons, elements contrasting with the main color
-  },
+    main: '#FFA900',
+    mainText: '#413E3E',
+  };
 
-  // copyRight: all text in widget
-  dictionaryOverrides: {
-    "create-points": "Create a point", // text for create point
-    "delete-points": "Remove point", // text for delete point
-    "research-plan": "Research plan", // text for research plan
-    "rotate-plan": "Rotate plan", // text for rotate plan
-    "ok": "Ok", // button text
-    "made-by-link": "https://getfloorplan.com/", // watermark link
-    "made-by-text": "getfloorplan.com", // watermark text
-    "instructions-hint-text": "", // additional text on the bottom of instruction modal
-    "floor": "$0 floor" // floor text
-  },
-
-  API_URL: '', // API URL
-
-  // branding.
-  branding: {
-    company_url: '', // link opened when logo is clicked (higher priority than logoUrl)
-    company_name: '', // watermark text (higher priority than dictionaryOverrides['made-by-text'])
-    widget_language: 'en', // ISO 639 language code
-    logo_path: '', // path to logo
-    
-  // panorama icons
+  /** Panorama icons */
   panoramaIcons: {
-    spot: 'URL', // icon for camera points in one room
-    door: 'URL' // icon for door
-  },
-
-  // scales
-  scales: ['x05', 'x1'],
-    
-  // integrations
+    /** Icon for camera point links in one room */
+    spot: 'https://images.com/image-spot.svg';
+    /** Icon for proactive camera point links in one room */
+    interactiveSpot: 'https://images.com/image-interactive-spot.svg';
+    /** Icon for door link */
+    door: 'https://images.com/image-door.png';
+  };
+
+  /** Overrides locale keys with custom text or translation */
+  dictionaryOverrides: {
+    'create-points': 'Create a point', // text for create point
+    'delete-points': 'Remove point', // text for delete point
+    'research-plan': 'Research plan', // text for research plan
+    'rotate-plan': 'Rotate plan', // text for rotate plan
+    'ok': 'Ok', // button text
+    'made-by-link': 'https://getfloorplan.com/', // watermark link
+    'made-by-text': 'getfloorplan.com', // watermark text
+    'instructions-hint-text': '', // additional text on the bottom of instruction modal
+    'floor': '$0 floor' // floor text
+  };
+
+  /** Enable/disable modal of instruction in 3D tour */
+  instructionVisible: true;
+  /** Enable/disable auto rotation in 3D tour */
+  autoRotate: false;
+  /** Array of scale keys used as filter, can be x05, x1, x2, x3, x4 */
+  scales: ['x05', 'x1'];
+  /** Enable/disable device gyroscope for AR */
+  enableGyroscope: true;
+
+  /**
+   * Scale button type
+   * - `img`: legacy button with icons x05, x1, etc...
+   * - `text`: button with text content instead of icon x05, x1, etc...
+   */
+  scaleButtonType: 'img';
+  /** Show floor number endings in floors locale translation */
+  floorNumberEndingsVisible: false;
+
+  /**
+   * Design type
+   * - `standard`: bottom panel without sidebar, external floors select
+   * - `sidebar`: all buttons in sidebar, also floors select in sidebar
+   * - `custom`: use `bottombarContent` and `sidebarContent` to select required buttons manually
+   */
+  designType: 'sidebar';
+  /** Bottom container button types to show */
+  bottombarContent: [];
+  /** Sidebar button types to show */
+  sidebarContent: ['floors', 'ruler', 'scale', 'rotation', 'furniture'];
+  /**
+   * Buttons design version
+   * - `two`: buttons design v2.0
+   * - `three`: buttons design v3.0
+   */
+  tabsButtonsDesign: 'three';
+  /** Proactive cursor type: 'pointer' or 'circle' */
+  cursor: 'pointer';
+  /** Enable/disable proactive cursor pulse */
+  enableCursorPulse: true;
+  
+  /** Widget external integrations */
   integrations: {
-    sentry: {
-      dsn: '<sentry_dsn>',
-      // Other sentry params
-    },
-  },
-
-  cursorType: 'pointer', // can be 'pointer' or 'circle'
-  enableCursorPulse: true, // enable cursor pulse animation
-  movementType: 'interroom', // allows movement only within a room or between rooms
-
-  defaultLinkOptions: {
-    hasRealSize: false, // enable real size icons in classic navigation mode
-    realSize: 300, // real size
-    realSizeMobileScale: 1, // mobile scale factor in real size
-    realSizeMinDistance: 100, // minimal distance to scale down real size icon
-    realSizeDistanceMinScale: 0.1, // minimal scale for minimal distance scale down
-    hoverScale: 1.2 // hover scale factor
-  },
-
-  fadeOptions: {
-    fadeInTime: 0.5, // fade in duration (in seconds)
-    fadeOutTime: 0.5, // fade out duration (in seconds)
-  },
-
-  rulerOptions: {
-    fontSize: 38, // ruler font size
-  },
-
-  linkOptions: {
-    enablePulse: false, // enable hover pulse
-    pulseFrom: 1, // pulse from scale
-    pulseTo: 2, // pulse to scale
-    pulseSpeed: 1, // pulse speed (1 pulse per second)
-  },
-    
-  room_label_visible: false, // show room type label
-}
-
+    /** Configuration options for the Sentry Browser SDK. See: Sentry API BrowserOptions */
+    sentry: BrowserOptions;
+  };
+  
+  /** Allows movement only within a room or between rooms, can be interroom or intraroom */
+  movementType: 'interroom';
+  
+  /** Options for DefaultLink graphics */
+  default_link_options: {
+    /** Use perspective size for DefaultLink sprite */
+    use_real_size: false;
+    /** Perspective size */
+    real_size: 300;
+    /** Perspective size scale on mobile devices */
+    real_size_mobile_scale: 1;
+    /** Minimal distance to prevent overscale in near distances */
+    real_size_min_distance: 100;
+    /** Minimal distance scale clamp on near distances */
+    real_size_distance_min_scale: 0.1;
+    /** Enable/disable scale on hover */
+    hover_scale: 1.2;
+  };
+  
+  /** Panorama fading options */
+  fade_options: {
+    /** Time for fade in (seconds) */
+    fade_in_time: 0.5;
+    /** Time for fade out (seconds) */
+    fade_out_time: 0.5;
+  };
+  
+  /** Options for DefaultLink graphics */
+  ruler_options: {
+    /** Font size for ruler text */
+    font_size: 38;
+  };
+  
+  /** Options for DefaultLink graphics */
+  link_options: {
+    /** Enable/disable link pulse on hover */
+    enable_pulse: false;
+    /** Pulse scale from */
+    pulse_from_scale: 1;
+    /** Pulse scale to */
+    pulse_to_scale: 2;
+    /** Pulse speed */
+    pulse_speed: 1;
+
+    /** Enable/disable scale on hover */
+    enable_point_hover_scale: false;
+    /** Hover scale */
+    point_hover_scale: 1;
+  };
+  
+  /** Options for DefaultLink graphics */
+  map_options: {
+    /** Map type, should be 'default', 'top_view' or 'multi_floor' */
+    type: 'default';
+    /** Upscale top view resolution for better rendering */
+    top_view_upscale: 2;
+  };
+  
+  /** Options for Scene camera */
+  camera_options: {
+    fov_change_speed: 0;
+  };
+  
+  /** Options for DefaultLink graphics */
+  lazy_load_options: {
+    /** Count panoramas to lazy load after move to another panorama */
+    preload_count: 3;
+    /** Force lazy load another non-loaded panoramas instead of skipping near cached panoramas */
+    force_preload_non_cached: true;
+    /** Preload depth maps */
+    use_masks_preload: true;
+  };
+
+  /** Widget branding data */
+  widget_branding: {
+    /** Branded logo path */
+    logo_path: 'https://es-logos.com/logo.png';
+    /** Branded company name */
+    company_name: 'ES Company';
+    /** Branded company url */
+    company_url: 'https://es.company.com';
+    /** Branded widget language (See locale/*) */
+    widget_language: 'es';
+  }
+  
+  /** Show/hide fullscreen button */
+  fullscreen_button_visible: false;
+  /** Show/hide room type label */
+  room_label_visible: false;
+};
 ```
 
 ## Types of elements
@@ -294,6 +388,8 @@ locale: [
 scales: [
   'x1',
   'x2',
+  'x3',
+  'x4',
   'x05'
 ],
 ```
@@ -329,6 +425,7 @@ panorama: { // type of panorama and paths to 360° images
         top: null,
         bottom: null,
         scene_depth: "", // path to EXR file for depth map if available
+        object_ids: "", // path to EXR file for furniture object ids if available
       ]
     }
   ]