@terraware/web-components 5.0.27-rc.0 → 5.0.27

package/components/VirtualWalkthrough/TfAnnotationManager.js

@@ -1,218 +1,400 @@
-import { createElement } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
-import { FILTER_LINEAR, PIXELFORMAT_RGBA8, Texture } from "playcanvas";
-import { AnnotationManager } from "playcanvas/scripts/esm/annotations.mjs";
-import Icon from "../Icon/Icon.js";
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { Texture, FILTER_LINEAR, PIXELFORMAT_RGBA8 } from 'playcanvas';
+import { AnnotationManager } from 'playcanvas/scripts/esm/annotations.mjs';
+import Icon from '../Icon/Icon.js';
+
+// Maps each annotation icon type to a @terraware/web-components icon.
 const ANNOTATION_ICONS = {
-    text: 'iconComment',
-    image: 'iconPhoto',
-    video: 'iconVideo'
+  text: 'iconComment',
+  image: 'iconPhoto',
+  video: 'iconVideo'
 };
+
+// Pixel dimensions of the (square) hotspot texture canvas at rest.
 const HOTSPOT_TEXTURE_SIZE = 64;
+
+// How much larger the hotspot appears while hovered.
 const HOTSPOT_HOVER_SCALE = 1.3;
+
+/**
+ * Extended AnnotationManager that adds max size clamping for annotations
+ * and fixes positioning when canvas is not at document origin.
+ */
 class TfAnnotationManager extends AnnotationManager {
-    static scriptName = 'tfAnnotationManager';
-    _maxWorldSize = 1.0;
-    _customParentDom = null;
-    _clickHandlersAttached = new Set();
-    _hotspotBackgroundColor = '#2C8658';
-    _iconImages = new Map();
-    set maxWorldSize(value) {
-        this._maxWorldSize = value;
+  static scriptName = 'tfAnnotationManager';
+  _maxWorldSize = 1.0;
+  _customParentDom = null;
+  _clickHandlersAttached = new Set();
+  _hotspotBackgroundColor = '#2C8658';
+  _iconImages = new Map();
+
+  /**
+   * Maximum world-space size for annotations.
+   * This prevents annotations from growing beyond this size regardless of camera distance.
+   *
+   * @attribute
+   * @title Max World Size
+   * @type {number}
+   * @default 1.0
+   */
+  set maxWorldSize(value) {
+    this._maxWorldSize = value;
+  }
+  get maxWorldSize() {
+    return this._maxWorldSize;
+  }
+
+  /**
+   * Background color for the hotspot texture canvas (the circle fill color).
+   * This is a hex color string (e.g., '#2C8658') that's drawn on the texture canvas.
+   * Note: This is different from hotspotColor and hoverColor, which are PlayCanvas Color objects
+   * used for the material's emissive property.
+   *
+   * @attribute
+   * @title Hotspot Background Color
+   * @type {string}
+   * @default '#2C8658'
+   */
+  set hotspotBackgroundColor(value) {
+    this._hotspotBackgroundColor = value;
+  }
+  get hotspotBackgroundColor() {
+    return this._hotspotBackgroundColor;
+  }
+
+  /**
+   * Initialize with custom parent DOM if needed.
+   */
+  initialize() {
+    // Find a container div with data-annotation-container attribute
+    const canvas = this.app.graphicsDevice.canvas;
+    const container = canvas.parentElement?.querySelector('[data-annotation-container]');
+    if (container) {
+      this._customParentDom = container;
+      this._parentDom = container;
     }
-    get maxWorldSize() {
-        return this._maxWorldSize;
+
+    // Call parent initialize
+    super.initialize();
+    this._loadIconImages();
+  }
+
+  /**
+   * Renders each web-components icon to an SVG image once. When an image finishes
+   * loading, any annotations already using that icon are redrawn.
+   * @private
+   */
+  _loadIconImages() {
+    const fillColor = this._hotspotColor?.toString() ?? '#ffffff';
+    Object.keys(ANNOTATION_ICONS).forEach(iconType => {
+      const name = ANNOTATION_ICONS[iconType];
+      const markup = renderToStaticMarkup(/*#__PURE__*/createElement(Icon, {
+        name,
+        fillColor
+      })).replace(/^<svg/, '<svg width="128" height="128"');
+      const image = new Image();
+      image.onload = () => this._refreshIcon(iconType);
+      image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+      this._iconImages.set(iconType, image);
+    });
+  }
+
+  /**
+   * Redraws the texture for all annotations using the given icon, once its image
+   * has loaded.
+   * @private
+   */
+  _refreshIcon(iconType) {
+    const annotationResources = this._annotationResources;
+    if (!annotationResources) {
+      return;
     }
-    set hotspotBackgroundColor(value) {
-        this._hotspotBackgroundColor = value;
-    }
-    get hotspotBackgroundColor() {
-        return this._hotspotBackgroundColor;
+    annotationResources.forEach((_resources, annotation) => {
+      if ((annotation.icon ?? 'text') === iconType) {
+        this._applyAnnotationIcon(annotation);
+      }
+    });
+  }
+
+  /**
+   * Update loop to attach click handlers to annotations and manage visibility.
+   */
+  update() {
+    const annotationResources = this._annotationResources;
+    if (!annotationResources) {
+      return;
     }
-    initialize() {
-        const canvas = this.app.graphicsDevice.canvas;
-        const container = canvas.parentElement?.querySelector('[data-annotation-container]');
-        if (container) {
-            this._customParentDom = container;
-            this._parentDom = container;
+
+    // Attach click handlers and manage visibility for all annotations
+    annotationResources.forEach((resources, annotation) => {
+      if (resources && resources.hotspotDom) {
+        // Attach click handler if not already attached
+        if (!this._clickHandlersAttached.has(annotation)) {
+          const callback = annotation.onClickCallback;
+          if (callback) {
+            this._clickHandlersAttached.add(annotation);
+            resources.hotspotDom.addEventListener('pointerdown', e => {
+              callback(e.clientX, e.clientY);
+            });
+          }
         }
-        super.initialize();
-        this._loadIconImages();
-    }
-    _loadIconImages() {
-        const fillColor = this._hotspotColor?.toString() ?? '#ffffff';
-        Object.keys(ANNOTATION_ICONS).forEach((iconType)=>{
-            const name = ANNOTATION_ICONS[iconType];
-            const markup = renderToStaticMarkup(createElement(Icon, {
-                name,
-                fillColor
-            })).replace(/^<svg/, '<svg width="128" height="128"');
-            const image = new Image();
-            image.onload = ()=>this._refreshIcon(iconType);
-            image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
-            this._iconImages.set(iconType, image);
-        });
-    }
-    _refreshIcon(iconType) {
-        const annotationResources = this._annotationResources;
-        if (!annotationResources) return;
-        annotationResources.forEach((_resources, annotation)=>{
-            if ((annotation.icon ?? 'text') === iconType) this._applyAnnotationIcon(annotation);
-        });
-    }
-    update() {
-        const annotationResources = this._annotationResources;
-        if (!annotationResources) return;
-        annotationResources.forEach((resources, annotation)=>{
-            if (resources && resources.hotspotDom) {
-                if (!this._clickHandlersAttached.has(annotation)) {
-                    const callback = annotation.onClickCallback;
-                    if (callback) {
-                        this._clickHandlersAttached.add(annotation);
-                        resources.hotspotDom.addEventListener('pointerdown', (e)=>{
-                            callback(e.clientX, e.clientY);
-                        });
-                    }
-                }
-                const isVisible = void 0 !== annotation.enabled ? annotation.enabled : true;
-                if (this._activeAnnotation === annotation && !isVisible) {
-                    this._tooltipDom.style.visibility = 'hidden';
-                    this._tooltipDom.style.opacity = '0';
-                    this._activeAnnotation = null;
-                }
-            }
-        });
-    }
-    _registerAnnotation(annotation) {
-        super._registerAnnotation(annotation);
-        this._applyAnnotationIcon(annotation);
-        const resources = this._annotationResources.get(annotation);
-        if (resources) {
-            resources.baseEntity.enabled = false;
-            resources.overlayEntity.enabled = false;
+
+        // Disable/enable the entity itself based on visibility
+        const isVisible = annotation.enabled !== undefined ? annotation.enabled : true;
+
+        // Hide tooltip if the active annotation is hidden
+        if (this._activeAnnotation === annotation && !isVisible) {
+          this._tooltipDom.style.visibility = 'hidden';
+          this._tooltipDom.style.opacity = '0';
+          this._activeAnnotation = null;
         }
+      }
+    });
+  }
+
+  /**
+   * Override annotation registration to draw the media icon onto the hotspot
+   * texture once the annotation (and its icon) is available.
+   * @private
+   */
+  _registerAnnotation(annotation) {
+    super._registerAnnotation(annotation);
+    this._applyAnnotationIcon(annotation);
+
+    // Keep the hotspot mesh hidden until the first scale pass sizes it. The annotation entity
+    // starts at unit scale, so the plane would render a metre across for the frames before
+    // _updateAnnotationRotationAndScale runs.
+    const resources = this._annotationResources.get(annotation);
+    if (resources) {
+      resources.baseEntity.enabled = false;
+      resources.overlayEntity.enabled = false;
     }
-    _applyAnnotationIcon(annotation) {
-        const resources = this._annotationResources.get(annotation);
-        if (!resources) return;
-        const icon = annotation.icon ?? 'text';
-        resources.texture.destroy();
-        resources.texture = this._createHotspotTexture(annotation.label, HOTSPOT_TEXTURE_SIZE, 6, icon);
-        resources.materials.forEach((material)=>{
-            material.emissiveMap = resources.texture;
-            material.opacityMap = resources.texture;
-            material.update();
-        });
+  }
+
+  /**
+   * Recreates the hotspot texture with the appropriate media icon drawn on it.
+   * @private
+   */
+  _applyAnnotationIcon(annotation) {
+    const resources = this._annotationResources.get(annotation);
+    if (!resources) {
+      return;
     }
-    _drawIcon(ctx, icon, size) {
-        const image = this._iconImages.get(icon);
-        if (!image || !image.complete || 0 === image.naturalWidth) return;
-        const iconSize = 0.5 * size;
-        const offset = (size - iconSize) / 2;
-        ctx.drawImage(image, offset, offset, iconSize, iconSize);
+    const icon = annotation.icon ?? 'text';
+    resources.texture.destroy();
+    resources.texture = this._createHotspotTexture(annotation.label, HOTSPOT_TEXTURE_SIZE, 6, icon);
+    resources.materials.forEach(material => {
+      material.emissiveMap = resources.texture;
+      material.opacityMap = resources.texture;
+      material.update();
+    });
+  }
+
+  /**
+   * Draws the icon image onto the hotspot texture canvas, scaled to fit the
+   * circle. Does nothing if the image has not finished loading yet; the
+   * annotation is redrawn once it has (see `_refreshIcon`).
+   * @private
+   */
+  _drawIcon(ctx, icon, size) {
+    const image = this._iconImages.get(icon);
+    if (!image || !image.complete || image.naturalWidth === 0) {
+      return;
     }
-    _onLabelChange(annotation) {
-        this._applyAnnotationIcon(annotation);
+    const iconSize = size * 0.5;
+    const offset = (size - iconSize) / 2;
+    ctx.drawImage(image, offset, offset, iconSize, iconSize);
+  }
+
+  /**
+   * Keep the media icon drawn on the hotspot texture. The label text itself
+   * is not rendered on the hotspot, so we simply redraw with the icon.
+   * @private
+   */
+  _onLabelChange(annotation) {
+    this._applyAnnotationIcon(annotation);
+  }
+
+  /**
+   * The hotspot colors are baked into the texture in `_createHotspotTexture`,
+   * so the material emissive is kept white to let those colors render as drawn.
+   * @private
+   */
+  _createHotspotMaterial(texture, options) {
+    const material = super._createHotspotMaterial(texture, options);
+    material.emissive.set(1, 1, 1);
+    material.update();
+    return material;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _setAnnotationHover(_annotation, _hover) {
+    // No-op: the hover growth is handled in _updateAnnotationRotationAndScale
+    // (via _hoverAnnotation); the texture is identical in both states.
+  }
+  _updateAllAnnotationColors() {
+    // No-op: hotspot colors are baked into the texture (see _createHotspotMaterial).
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _showTooltip(_annotation) {
+    // No-op: AnnotationPanel handles all annotation UI, this removes default behavior
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _onTextChange(_annotation, _text) {
+    // No-op: AnnotationPanel handles all annotation UI, this removes default behavior
+  }
+
+  /**
+   * Override position update to adjust for canvas offset and respect visibility.
+   * @private
+   */
+  _updateAnnotationPositions(annotation, resources, screenPos) {
+    const canvas = this.app.graphicsDevice.canvas;
+    const rect = canvas.getBoundingClientRect();
+
+    // If using a custom parent (positioned container), use raw screen coordinates
+    // Otherwise, adjust for canvas position in document
+    const offsetX = this._customParentDom ? 0 : rect.left + window.scrollX;
+    const offsetY = this._customParentDom ? 0 : rect.top + window.scrollY;
+
+    // Check if annotation is visible (defaults to true if not specified)
+    const isVisible = annotation.enabled !== undefined ? annotation.enabled : true;
+    resources.hotspotDom.style.display = isVisible ? 'block' : 'none';
+    resources.hotspotDom.style.left = `${screenPos.x + offsetX}px`;
+    resources.hotspotDom.style.top = `${screenPos.y + offsetY}px`;
+    if (this._activeAnnotation === annotation) {
+      this._tooltipDom.style.display = isVisible ? 'block' : 'none';
+      this._tooltipDom.style.left = `${screenPos.x + offsetX}px`;
+      this._tooltipDom.style.top = `${screenPos.y + offsetY}px`;
     }
-    _createHotspotMaterial(texture, options) {
-        const material = super._createHotspotMaterial(texture, options);
-        material.emissive.set(1, 1, 1);
-        material.update();
-        return material;
+    if (annotation.onScreenPositionUpdateCallback) {
+      // Rendered hotspot diameter (px), set by _updateAnnotationRotationAndScale.
+      // Parsed from the style rather than measured to avoid forcing a reflow.
+      const hotspotSize = parseFloat(resources.hotspotDom.style.width) || undefined;
+      annotation.onScreenPositionUpdateCallback(screenPos.x + offsetX, screenPos.y + offsetY, hotspotSize);
     }
-    _setAnnotationHover(_annotation, _hover) {}
-    _updateAllAnnotationColors() {}
-    _showTooltip(_annotation) {}
-    _onTextChange(_annotation, _text) {}
-    _updateAnnotationPositions(annotation, resources, screenPos) {
-        const canvas = this.app.graphicsDevice.canvas;
-        const rect = canvas.getBoundingClientRect();
-        const offsetX = this._customParentDom ? 0 : rect.left + window.scrollX;
-        const offsetY = this._customParentDom ? 0 : rect.top + window.scrollY;
-        const isVisible = void 0 !== annotation.enabled ? annotation.enabled : true;
-        resources.hotspotDom.style.display = isVisible ? 'block' : 'none';
-        resources.hotspotDom.style.left = `${screenPos.x + offsetX}px`;
-        resources.hotspotDom.style.top = `${screenPos.y + offsetY}px`;
-        if (this._activeAnnotation === annotation) {
-            this._tooltipDom.style.display = isVisible ? 'block' : 'none';
-            this._tooltipDom.style.left = `${screenPos.x + offsetX}px`;
-            this._tooltipDom.style.top = `${screenPos.y + offsetY}px`;
-        }
-        if (annotation.onScreenPositionUpdateCallback) {
-            const hotspotSize = parseFloat(resources.hotspotDom.style.width) || void 0;
-            annotation.onScreenPositionUpdateCallback(screenPos.x + offsetX, screenPos.y + offsetY, hotspotSize);
-        }
+  }
+
+  /**
+   * Override to also disable the hotspot mesh (not just the DOM) when the annotation is behind the
+   * camera. The base implementation leaves the mesh enabled, so a not-yet-scaled plane would stay
+   * in view at its full unit size until the camera moves the anchor in front.
+   * @private
+   */
+  _hideAnnotationElements(annotation, resources) {
+    super._hideAnnotationElements(annotation, resources);
+    resources.baseEntity.enabled = false;
+    resources.overlayEntity.enabled = false;
+  }
+
+  /**
+   * Override the scale update to clamp the world size to a maximum value.
+   * Also scales the hotspot DOM element to match.
+   * @private
+   */
+  _updateAnnotationRotationAndScale(annotation) {
+    const cameraRotation = this._camera.getRotation();
+    annotation.entity.setRotation(cameraRotation);
+    annotation.entity.rotateLocal(90, 0, 0);
+    const cameraPos = this._camera.getPosition();
+    const distance = annotation.entity.getPosition().distance(cameraPos);
+    const canvas = this.app.graphicsDevice.canvas;
+    const screenHeight = canvas.clientHeight;
+    const projMatrix = this._camera.camera.projectionMatrix;
+
+    // The world size that projects to _hotspotSize screen pixels at this distance.
+    const targetWorldSize = this._hotspotSize / screenHeight * (2 * distance / projMatrix.data[5]);
+
+    // Annotations hang off an unscaled parent, so local scale is world scale and maxWorldSize
+    // clamps the hotspot at a size in metres.
+    const clampedScale = Math.min(targetWorldSize, this._maxWorldSize);
+    const hovered = this._hoverAnnotation === annotation;
+    const hoverScale = hovered ? HOTSPOT_HOVER_SCALE : 1;
+    const entityScale = clampedScale * hoverScale;
+    annotation.entity.setLocalScale(entityScale, entityScale, entityScale);
+
+    // Scale the hotspot DOM element proportionally when clamped, including the
+    // hover growth so it tracks the visible circle. This is a pure screen-space
+    // size, so it uses the true _hotspotSize and the clamp ratio only.
+    const resources = this._annotationResources.get(annotation);
+    if (resources) {
+      // This branch only runs for annotations in front of the camera, and the scale above is now
+      // clamped, so it is safe to reveal the mesh (hidden on register / when behind the camera).
+      resources.baseEntity.enabled = true;
+      resources.overlayEntity.enabled = true;
     }
-    _hideAnnotationElements(annotation, resources) {
-        super._hideAnnotationElements(annotation, resources);
-        resources.baseEntity.enabled = false;
-        resources.overlayEntity.enabled = false;
+    if (resources && resources.hotspotDom) {
+      const clampRatio = clampedScale / targetWorldSize;
+      const baseSize = this._hotspotSize + 5; // Match the +5 from the stylesheet
+      const scaledSize = baseSize * clampRatio * hoverScale;
+      resources.hotspotDom.style.width = `${scaledSize}px`;
+      resources.hotspotDom.style.height = `${scaledSize}px`;
     }
-    _updateAnnotationRotationAndScale(annotation) {
-        const cameraRotation = this._camera.getRotation();
-        annotation.entity.setRotation(cameraRotation);
-        annotation.entity.rotateLocal(90, 0, 0);
-        const cameraPos = this._camera.getPosition();
-        const distance = annotation.entity.getPosition().distance(cameraPos);
-        const canvas = this.app.graphicsDevice.canvas;
-        const screenHeight = canvas.clientHeight;
-        const projMatrix = this._camera.camera.projectionMatrix;
-        const targetWorldSize = this._hotspotSize / screenHeight * (2 * distance / projMatrix.data[5]);
-        const clampedScale = Math.min(targetWorldSize, this._maxWorldSize);
-        const hovered = this._hoverAnnotation === annotation;
-        const hoverScale = hovered ? HOTSPOT_HOVER_SCALE : 1;
-        const entityScale = clampedScale * hoverScale;
-        annotation.entity.setLocalScale(entityScale, entityScale, entityScale);
-        const resources = this._annotationResources.get(annotation);
-        if (resources) {
-            resources.baseEntity.enabled = true;
-            resources.overlayEntity.enabled = true;
-        }
-        if (resources && resources.hotspotDom) {
-            const clampRatio = clampedScale / targetWorldSize;
-            const baseSize = this._hotspotSize + 5;
-            const scaledSize = baseSize * clampRatio * hoverScale;
-            resources.hotspotDom.style.width = `${scaledSize}px`;
-            resources.hotspotDom.style.height = `${scaledSize}px`;
-        }
+  }
+
+  /**
+   * Override to create hotspot texture with custom background color.
+   * @private
+   */
+  _createHotspotTexture(label, size = HOTSPOT_TEXTURE_SIZE, borderWidth = 6, icon) {
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+      throw new Error('Failed to get canvas 2d context');
     }
-    _createHotspotTexture(label, size = HOTSPOT_TEXTURE_SIZE, borderWidth = 6, icon) {
-        const canvas = document.createElement('canvas');
-        canvas.width = size;
-        canvas.height = size;
-        const ctx = canvas.getContext('2d');
-        if (!ctx) throw new Error('Failed to get canvas 2d context');
-        ctx.fillStyle = 'white';
-        ctx.globalAlpha = 0;
-        ctx.fillRect(0, 0, size, size);
-        ctx.globalAlpha = 1.0;
-        const centerX = size / 2;
-        const centerY = size / 2;
-        const radius = size / 2 - 4;
-        const foregroundColor = this._hotspotColor?.toString() ?? '#ffffff';
-        ctx.beginPath();
-        ctx.arc(centerX, centerY, radius, 0, 2 * Math.PI);
-        ctx.fillStyle = this._hotspotBackgroundColor;
-        ctx.fill();
-        ctx.beginPath();
-        ctx.arc(centerX, centerY, radius, 0, 2 * Math.PI);
-        ctx.lineWidth = borderWidth;
-        ctx.strokeStyle = foregroundColor;
-        ctx.stroke();
-        if (icon) this._drawIcon(ctx, icon, size);
-        const imageData = ctx.getImageData(0, 0, size, size);
-        const data = imageData.data;
-        return new Texture(this.app.graphicsDevice, {
-            width: size,
-            height: size,
-            format: PIXELFORMAT_RGBA8,
-            magFilter: FILTER_LINEAR,
-            minFilter: FILTER_LINEAR,
-            mipmaps: false,
-            levels: [
-                new Uint8Array(data.buffer)
-            ]
-        });
+
+    // First clear with stroke color at zero alpha
+    ctx.fillStyle = 'white';
+    ctx.globalAlpha = 0;
+    ctx.fillRect(0, 0, size, size);
+    ctx.globalAlpha = 1.0;
+
+    // Draw circle with custom background color
+    const centerX = size / 2;
+    const centerY = size / 2;
+    const radius = size / 2 - 4;
+
+    // The icon fill and border share the hotspot color
+    const foregroundColor = this._hotspotColor?.toString() ?? '#ffffff';
+
+    // Draw main circle
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    ctx.fillStyle = this._hotspotBackgroundColor;
+    ctx.fill();
+
+    // Draw border
+    ctx.beginPath();
+    ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+    ctx.lineWidth = borderWidth;
+    ctx.strokeStyle = foregroundColor;
+    ctx.stroke();
+
+    // Draw the media icon inside the circle
+    if (icon) {
+      this._drawIcon(ctx, icon, size);
     }
+
+    // Get pixel data
+    const imageData = ctx.getImageData(0, 0, size, size);
+    const data = imageData.data;
+
+    // Create and return the texture
+    return new Texture(this.app.graphicsDevice, {
+      width: size,
+      height: size,
+      format: PIXELFORMAT_RGBA8,
+      magFilter: FILTER_LINEAR,
+      minFilter: FILTER_LINEAR,
+      mipmaps: false,
+      levels: [new Uint8Array(data.buffer)]
+    });
+  }
 }
+
 export { TfAnnotationManager };