@terraware/web-components 4.2.13 → 4.2.14-rc.1

package/components/VirtualWalkthrough/TfAnnotationManager.js

@@ -0,0 +1,368 @@
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { FILTER_LINEAR, PIXELFORMAT_RGBA8, Texture } from 'playcanvas';
+import { AnnotationManager as PcAnnotationManager } from 'playcanvas/scripts/esm/annotations.mjs';
+import Icon from '../Icon/Icon';
+// Maps each annotation icon type to a @terraware/web-components icon.
+const ANNOTATION_ICONS = {
+  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.
+ */
+export class TfAnnotationManager extends PcAnnotationManager {
+  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;
+    }
+
+    // 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;
+    }
+    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;
+    }
+
+    // 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);
+            });
+          }
+        }
+
+        // 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);
+  }
+
+  /**
+   * Recreates the hotspot texture with the appropriate media icon drawn on it.
+   * @private
+   */
+  _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();
+    });
+  }
+
+  /**
+   * 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;
+    }
+    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`;
+    }
+    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);
+    }
+  }
+
+  /**
+   * 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;
+
+    // Calculate world size based on screen size and distance
+    const unclamped = this._hotspotSize / screenHeight * (2 * distance / projMatrix.data[5]);
+
+    // Clamp to maximum world size
+    const worldSize = Math.min(unclamped, this._maxWorldSize);
+    const hovered = this._hoverAnnotation === annotation;
+    const hoverScale = hovered ? HOTSPOT_HOVER_SCALE : 1;
+    const entityScale = worldSize * 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.
+    const resources = this._annotationResources.get(annotation);
+    if (resources && resources.hotspotDom) {
+      const scaleFactor = worldSize / unclamped;
+      const baseSize = this._hotspotSize + 5; // Match the +5 from the stylesheet
+      const scaledSize = baseSize * scaleFactor * 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');
+    }
+
+    // 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)]
+    });
+  }
+}

package/components/VirtualWalkthrough/TfXrNavigation.d.ts

@@ -0,0 +1,15 @@
+import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr-navigation.mjs';
+/**
+ * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
+ * the enableTeleport flag setting.
+ */
+export declare class TfXrNavigation extends PcXrNavigation {
+    static scriptName: string;
+    /**
+     * Override tryTeleport to respect the enableTeleport flag.
+     * The base implementation is always called from handleSelectEnd,
+     * but we only want to teleport when enableTeleport is true.
+     */
+    tryTeleport(inputSource: any): void;
+}
+//# sourceMappingURL=TfXrNavigation.d.ts.map

package/components/VirtualWalkthrough/TfXrNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TfXrNavigation.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/TfXrNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE1F;;;GAGG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,MAAM,CAAC,UAAU,SAAoB;IAErC;;;;OAIG;IACH,WAAW,CAAC,WAAW,EAAE,GAAG;CAS7B"}

package/components/VirtualWalkthrough/TfXrNavigation.js

@@ -0,0 +1,24 @@
+import { XrNavigation as PcXrNavigation } from 'playcanvas/scripts/esm/xr-navigation.mjs';
+
+/**
+ * Extended XrNavigation that fixes the bug where tryTeleport doesn't respect
+ * the enableTeleport flag setting.
+ */
+export class TfXrNavigation extends PcXrNavigation {
+  static scriptName = 'tfXrNavigation';
+
+  /**
+   * Override tryTeleport to respect the enableTeleport flag.
+   * The base implementation is always called from handleSelectEnd,
+   * but we only want to teleport when enableTeleport is true.
+   */
+  tryTeleport(inputSource) {
+    // Only proceed with teleportation if enableTeleport is true
+    if (!this.enableTeleport) {
+      return;
+    }
+
+    // Call the parent implementation
+    super.tryTeleport(inputSource);
+  }
+}

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts

@@ -0,0 +1,27 @@
+import { AnnotationProps } from './Annotation';
+import { SplatControlsStrings } from './SplatControls';
+export interface VirtualWalkthroughViewerProps {
+    splatSrc: string;
+    origin?: [number, number, number];
+    cameraPosition?: [number, number, number];
+    sceneBounds?: {
+        x: number;
+        y: number;
+        z: number;
+        m: number;
+    };
+    groundPlane?: [number, number, number][];
+    skyColor?: string;
+    groundColor?: string;
+    averageCameraHeight?: number;
+    annotations: AnnotationProps[];
+    onSaveAnnotations: (annotations: AnnotationProps[]) => void | Promise<void>;
+    strings: SplatControlsStrings;
+    editable?: boolean;
+    showFreeFly?: boolean;
+    isFullScreen?: boolean;
+    onToggleFullScreen?: () => void;
+}
+declare const VirtualWalkthroughViewer: ({ splatSrc, origin, cameraPosition, sceneBounds, groundPlane: groundPlaneProp, skyColor, groundColor, averageCameraHeight, annotations, onSaveAnnotations, strings, editable, showFreeFly, isFullScreen, onToggleFullScreen, }: VirtualWalkthroughViewerProps) => import("react/jsx-runtime").JSX.Element;
+export default VirtualWalkthroughViewer;
+//# sourceMappingURL=VirtualWalkthroughViewer.d.ts.map

package/components/VirtualWalkthrough/VirtualWalkthroughViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VirtualWalkthroughViewer.d.ts","sourceRoot":"","sources":["../../../src/components/VirtualWalkthrough/VirtualWalkthroughViewer.tsx"],"names":[],"mappings":"AAWA,OAAmB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK3D,OAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAStE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;CACjC;AAED,QAAA,MAAM,wBAAwB,GAAI,gOAgB/B,6BAA6B,4CAwR/B,CAAC;AAEF,eAAe,wBAAwB,CAAC"}