@playcanvas/web-components 0.6.0 → 0.7.1

package/src/components/scrollview-component.ts

@@ -0,0 +1,427 @@
+import { SCROLL_MODE_BOUNCE, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, ScrollViewComponent, Vec2 } from 'playcanvas';
+
+import { ComponentElement } from './component';
+import { getEntity, parseEnum, parseVec2 } from '../utils';
+
+const scrollModes = new Map<string, number>([
+    ['clamp', SCROLL_MODE_CLAMP],
+    ['bounce', SCROLL_MODE_BOUNCE],
+    ['infinite', SCROLL_MODE_INFINITE]
+]);
+
+const visibilities = new Map<string, number>([
+    ['always', SCROLLBAR_VISIBILITY_SHOW_ALWAYS],
+    ['when-required', SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED]
+]);
+
+/**
+ * The ScrollViewComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scrollview/ | `<pc-scrollview>`} elements.
+ * The ScrollViewComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * @category Components
+ */
+class ScrollViewComponentElement extends ComponentElement {
+    private _horizontal = true;
+
+    private _vertical = true;
+
+    private _scrollMode: number = SCROLL_MODE_BOUNCE;
+
+    private _bounceAmount = 0.1;
+
+    private _friction = 0.05;
+
+    private _useMouseWheel = true;
+
+    private _mouseWheelSensitivity = new Vec2(1, 1);
+
+    private _horizontalScrollbarVisibility: number = SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+
+    private _verticalScrollbarVisibility: number = SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+
+    private _viewport = '';
+
+    private _content = '';
+
+    private _horizontalScrollbar = '';
+
+    private _verticalScrollbar = '';
+
+    /** @ignore */
+    constructor() {
+        super('scrollview');
+    }
+
+    getInitialComponentData() {
+        const data: Record<string, any> = {
+            horizontal: this._horizontal,
+            vertical: this._vertical,
+            scrollMode: this._scrollMode,
+            bounceAmount: this._bounceAmount,
+            friction: this._friction,
+            useMouseWheel: this._useMouseWheel,
+            mouseWheelSensitivity: this._mouseWheelSensitivity,
+            horizontalScrollbarVisibility: this._horizontalScrollbarVisibility,
+            verticalScrollbarVisibility: this._verticalScrollbarVisibility
+        };
+
+        const viewport = getEntity(this._viewport);
+        if (viewport) {
+            data.viewportEntity = viewport;
+        }
+
+        const content = getEntity(this._content);
+        if (content) {
+            data.contentEntity = content;
+        }
+
+        const horizontalScrollbar = getEntity(this._horizontalScrollbar);
+        if (horizontalScrollbar) {
+            data.horizontalScrollbarEntity = horizontalScrollbar;
+        }
+
+        const verticalScrollbar = getEntity(this._verticalScrollbar);
+        if (verticalScrollbar) {
+            data.verticalScrollbarEntity = verticalScrollbar;
+        }
+
+        return data;
+    }
+
+    /**
+     * Gets the underlying PlayCanvas scroll view component.
+     * @returns The scroll view component.
+     */
+    get component(): ScrollViewComponent | null {
+        return super.component as ScrollViewComponent | null;
+    }
+
+    /**
+     * Sets whether horizontal scrolling is enabled.
+     * @param value - Whether horizontal scrolling is enabled.
+     */
+    set horizontal(value: boolean) {
+        this._horizontal = value;
+        if (this.component) {
+            this.component.horizontal = value;
+        }
+    }
+
+    /**
+     * Gets whether horizontal scrolling is enabled.
+     * @returns Whether horizontal scrolling is enabled.
+     */
+    get horizontal() {
+        return this._horizontal;
+    }
+
+    /**
+     * Sets whether vertical scrolling is enabled.
+     * @param value - Whether vertical scrolling is enabled.
+     */
+    set vertical(value: boolean) {
+        this._vertical = value;
+        if (this.component) {
+            this.component.vertical = value;
+        }
+    }
+
+    /**
+     * Gets whether vertical scrolling is enabled.
+     * @returns Whether vertical scrolling is enabled.
+     */
+    get vertical() {
+        return this._vertical;
+    }
+
+    /**
+     * Sets how the scroll view should behave when the content is scrolled beyond its bounds. Can be
+     * `clamp` (0), `bounce` (1) or `infinite` (2).
+     * @param value - The scroll mode.
+     */
+    set scrollMode(value: number) {
+        this._scrollMode = value;
+        if (this.component) {
+            this.component.scrollMode = value;
+        }
+    }
+
+    /**
+     * Gets how the scroll view behaves when the content is scrolled beyond its bounds.
+     * @returns The scroll mode.
+     */
+    get scrollMode() {
+        return this._scrollMode;
+    }
+
+    /**
+     * Sets how far the content is allowed to bounce beyond its bounds when `scroll-mode` is
+     * `bounce`, in the range 0 to 1.
+     * @param value - The bounce amount.
+     */
+    set bounceAmount(value: number) {
+        this._bounceAmount = value;
+        if (this.component) {
+            this.component.bounceAmount = value;
+        }
+    }
+
+    /**
+     * Gets the bounce amount.
+     * @returns The bounce amount.
+     */
+    get bounceAmount() {
+        return this._bounceAmount;
+    }
+
+    /**
+     * Sets how freely the content moves once thrown, in the range 0 (no friction) to 1.
+     * @param value - The friction.
+     */
+    set friction(value: number) {
+        this._friction = value;
+        if (this.component) {
+            this.component.friction = value;
+        }
+    }
+
+    /**
+     * Gets the friction.
+     * @returns The friction.
+     */
+    get friction() {
+        return this._friction;
+    }
+
+    /**
+     * Sets whether the scroll view responds to mouse wheel events.
+     * @param value - Whether to use the mouse wheel.
+     */
+    set useMouseWheel(value: boolean) {
+        this._useMouseWheel = value;
+        if (this.component) {
+            this.component.useMouseWheel = value;
+        }
+    }
+
+    /**
+     * Gets whether the scroll view responds to mouse wheel events.
+     * @returns Whether the mouse wheel is used.
+     */
+    get useMouseWheel() {
+        return this._useMouseWheel;
+    }
+
+    /**
+     * Sets the mouse wheel sensitivity as a Vec2 (horizontal, vertical). A value of 0 on an axis
+     * disables mouse wheel scrolling for that axis.
+     * @param value - The mouse wheel sensitivity.
+     */
+    set mouseWheelSensitivity(value: Vec2) {
+        this._mouseWheelSensitivity = value;
+        if (this.component) {
+            this.component.mouseWheelSensitivity = value;
+        }
+    }
+
+    /**
+     * Gets the mouse wheel sensitivity.
+     * @returns The mouse wheel sensitivity.
+     */
+    get mouseWheelSensitivity() {
+        return this._mouseWheelSensitivity;
+    }
+
+    /**
+     * Sets the visibility of the horizontal scrollbar. Can be `always` (0) or `when-required` (1).
+     * @param value - The horizontal scrollbar visibility.
+     */
+    set horizontalScrollbarVisibility(value: number) {
+        this._horizontalScrollbarVisibility = value;
+        if (this.component) {
+            this.component.horizontalScrollbarVisibility = value;
+        }
+    }
+
+    /**
+     * Gets the visibility of the horizontal scrollbar.
+     * @returns The horizontal scrollbar visibility.
+     */
+    get horizontalScrollbarVisibility() {
+        return this._horizontalScrollbarVisibility;
+    }
+
+    /**
+     * Sets the visibility of the vertical scrollbar. Can be `always` (0) or `when-required` (1).
+     * @param value - The vertical scrollbar visibility.
+     */
+    set verticalScrollbarVisibility(value: number) {
+        this._verticalScrollbarVisibility = value;
+        if (this.component) {
+            this.component.verticalScrollbarVisibility = value;
+        }
+    }
+
+    /**
+     * Gets the visibility of the vertical scrollbar.
+     * @returns The vertical scrollbar visibility.
+     */
+    get verticalScrollbarVisibility() {
+        return this._verticalScrollbarVisibility;
+    }
+
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
+     * viewport, which clips the content to the scroll view's bounds.
+     * @param value - The viewport entity reference.
+     */
+    set viewport(value: string) {
+        this._viewport = value;
+        const entity = getEntity(value);
+        if (this.component && entity) {
+            this.component.viewportEntity = entity;
+        }
+    }
+
+    /**
+     * Gets the reference to the `<pc-entity>` used as the viewport.
+     * @returns The viewport entity reference.
+     */
+    get viewport() {
+        return this._viewport;
+    }
+
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
+     * content, which is moved as the scroll view is scrolled.
+     * @param value - The content entity reference.
+     */
+    set content(value: string) {
+        this._content = value;
+        const entity = getEntity(value);
+        if (this.component && entity) {
+            this.component.contentEntity = entity;
+        }
+    }
+
+    /**
+     * Gets the reference to the `<pc-entity>` used as the content.
+     * @returns The content entity reference.
+     */
+    get content() {
+        return this._content;
+    }
+
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
+     * the horizontal `<pc-scrollbar>`.
+     * @param value - The horizontal scrollbar entity reference.
+     */
+    set horizontalScrollbar(value: string) {
+        this._horizontalScrollbar = value;
+        const entity = getEntity(value);
+        if (this.component && entity) {
+            this.component.horizontalScrollbarEntity = entity;
+        }
+    }
+
+    /**
+     * Gets the reference to the `<pc-entity>` containing the horizontal scrollbar.
+     * @returns The horizontal scrollbar entity reference.
+     */
+    get horizontalScrollbar() {
+        return this._horizontalScrollbar;
+    }
+
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
+     * the vertical `<pc-scrollbar>`.
+     * @param value - The vertical scrollbar entity reference.
+     */
+    set verticalScrollbar(value: string) {
+        this._verticalScrollbar = value;
+        const entity = getEntity(value);
+        if (this.component && entity) {
+            this.component.verticalScrollbarEntity = entity;
+        }
+    }
+
+    /**
+     * Gets the reference to the `<pc-entity>` containing the vertical scrollbar.
+     * @returns The vertical scrollbar entity reference.
+     */
+    get verticalScrollbar() {
+        return this._verticalScrollbar;
+    }
+
+    static get observedAttributes() {
+        return [
+            ...super.observedAttributes,
+            'horizontal',
+            'vertical',
+            'scroll-mode',
+            'bounce-amount',
+            'friction',
+            'use-mouse-wheel',
+            'mouse-wheel-sensitivity',
+            'horizontal-scrollbar-visibility',
+            'vertical-scrollbar-visibility',
+            'viewport',
+            'content',
+            'horizontal-scrollbar',
+            'vertical-scrollbar'
+        ];
+    }
+
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+        super.attributeChangedCallback(name, _oldValue, newValue);
+
+        switch (name) {
+            case 'horizontal':
+                this.horizontal = newValue !== 'false';
+                break;
+            case 'vertical':
+                this.vertical = newValue !== 'false';
+                break;
+            case 'scroll-mode':
+                this.scrollMode = parseEnum(newValue, scrollModes, SCROLL_MODE_BOUNCE);
+                break;
+            case 'bounce-amount':
+                this.bounceAmount = Number(newValue);
+                break;
+            case 'friction':
+                this.friction = Number(newValue);
+                break;
+            case 'use-mouse-wheel':
+                this.useMouseWheel = newValue !== 'false';
+                break;
+            case 'mouse-wheel-sensitivity':
+                this.mouseWheelSensitivity = parseVec2(newValue);
+                break;
+            case 'horizontal-scrollbar-visibility':
+                this.horizontalScrollbarVisibility = parseEnum(newValue, visibilities, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED);
+                break;
+            case 'vertical-scrollbar-visibility':
+                this.verticalScrollbarVisibility = parseEnum(newValue, visibilities, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED);
+                break;
+            case 'viewport':
+                this.viewport = newValue;
+                break;
+            case 'content':
+                this.content = newValue;
+                break;
+            case 'horizontal-scrollbar':
+                this.horizontalScrollbar = newValue;
+                break;
+            case 'vertical-scrollbar':
+                this.verticalScrollbar = newValue;
+                break;
+        }
+    }
+}
+
+customElements.define('pc-scrollview', ScrollViewComponentElement);
+
+export { ScrollViewComponentElement };

package/src/entity.ts

@@ -45,12 +45,24 @@ class EntityElement extends AsyncElement {
      */
     private _listeners: { [key: string]: EventListener[] } = {};
 
+    /**
+     * Whether the hierarchy has been built for this entity.
+     */
+    private _built = false;
+
     /**
      * The PlayCanvas entity instance.
      */
     entity: Entity | null = null;
 
     createEntity(app: AppBase) {
+        // Guard against double creation. When a subtree is inserted at runtime (e.g. cloning a
+        // `<template>`), an ancestor's connectedCallback eagerly creates descendant entities; the
+        // descendants' own connectedCallbacks would otherwise create them a second time.
+        if (this.entity) {
+            return;
+        }
+
         // Create a new entity
         this.entity = new Entity(this.getAttribute('name') || this._name, app);
 
@@ -106,7 +118,8 @@ class EntityElement extends AsyncElement {
     }
 
     buildHierarchy(app: AppBase) {
-        if (!this.entity) return;
+        if (!this.entity || this._built) return;
+        this._built = true;
 
         const closestEntity = this.closestEntity;
         if (closestEntity?.entity) {
@@ -152,6 +165,7 @@ class EntityElement extends AsyncElement {
             // Destroy the entity
             this.entity.destroy();
             this.entity = null;
+            this._built = false;
         }
     }
 

package/src/index.ts

@@ -16,15 +16,20 @@ import { AppElement } from './app';
 import { EntityElement } from './entity';
 import { AssetElement } from './asset';
 import { ListenerComponentElement } from './components/listener-component';
+import { ButtonComponentElement } from './components/button-component';
 import { CameraComponentElement } from './components/camera-component';
 import { CollisionComponentElement } from './components/collision-component';
 import { ComponentElement } from './components/component';
 import { ElementComponentElement } from './components/element-component';
+import { LayoutChildComponentElement } from './components/layoutchild-component';
+import { LayoutGroupComponentElement } from './components/layoutgroup-component';
 import { LightComponentElement } from './components/light-component';
 import { ParticleSystemComponentElement } from './components/particlesystem-component';
 import { RenderComponentElement } from './components/render-component';
 import { RigidBodyComponentElement } from './components/rigidbody-component';
 import { ScreenComponentElement } from './components/screen-component';
+import { ScrollbarComponentElement } from './components/scrollbar-component';
+import { ScrollViewComponentElement } from './components/scrollview-component';
 import { ScriptComponentElement } from './components/script-component';
 import { ScriptElement } from './components/script';
 import { SoundComponentElement } from './components/sound-component';
@@ -41,16 +46,21 @@ export {
     AppElement,
     EntityElement,
     AssetElement,
+    ButtonComponentElement,
     CameraComponentElement,
     CollisionComponentElement,
     ComponentElement,
     ElementComponentElement,
+    LayoutChildComponentElement,
+    LayoutGroupComponentElement,
     ParticleSystemComponentElement,
     LightComponentElement,
     ListenerComponentElement,
     RenderComponentElement,
     RigidBodyComponentElement,
     ScreenComponentElement,
+    ScrollbarComponentElement,
+    ScrollViewComponentElement,
     ScriptComponentElement,
     ScriptElement,
     SoundComponentElement,

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { CSS_COLORS } from './colors';
 
@@ -69,3 +69,51 @@ export const parseVec4 = (value: string): Vec4 => {
     const components = value.split(' ').map(Number);
     return new Vec4(components);
 };
+
+/**
+ * Resolves an enum value supplied as either a named string (looked up in `map`) or a numeric
+ * string. Falls back to `defaultValue` when the value is neither a known name nor a finite number.
+ *
+ * @param value - The attribute value to parse.
+ * @param map - A map of named values to their numeric enum equivalents.
+ * @param defaultValue - The value to return when parsing fails.
+ * @returns The resolved numeric enum value.
+ */
+export const parseEnum = (value: string, map: Map<string, number>, defaultValue: number): number => {
+    const named = map.get(value);
+    if (named !== undefined) {
+        return named;
+    }
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : defaultValue;
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
+ * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
+ * entity name. Returns `null` if no matching element (or backing entity) is found.
+ *
+ * @param ref - The reference string to resolve.
+ * @returns The resolved entity, or `null`.
+ */
+export const getEntity = (ref: string): Entity | null => {
+    if (!ref) {
+        return null;
+    }
+
+    let element: Element | null = null;
+
+    // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
+    // spaces) throws, in which case we fall back to id/name lookups below.
+    try {
+        element = document.querySelector(ref);
+    } catch {
+        element = null;
+    }
+
+    if (!element) {
+        element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
+    }
+
+    return (element as { entity?: Entity } | null)?.entity ?? null;
+};