@playcanvas/web-components 0.18.0 → 0.20.0

package/src/components/script-instance.ts

@@ -15,7 +15,9 @@ import { parseBool } from '../parse';
  *   Values are parsed according to the type of the attribute's current value — initially the
  *   script's declared default (numbers, booleans, strings, Vec2/3/4, Color, Quat as Euler
  *   angles) — and the `asset:`/`entity:`/`vec2:`/`vec3:`/`vec4:`/`color:` prefixes may be used
- *   to be explicit.
+ *   to be explicit. An `entity:` reference is an entity name — resolved against the nearest
+ *   enclosing entity first, then outward, then the document — or a document-wide `#` selector
+ *   (`entity:#id`); a bare value is always a name, never an element id.
  * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
  *   names that collide with reserved HTML attribute names (e.g. `title`).
  *
@@ -31,7 +33,8 @@ import { parseBool } from '../parse';
  *
  * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
  * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
- * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
+ * name, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —
+ * write `entity:#id` for an element id. Must be a direct child of `<pc-script>`.
  *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
@@ -54,9 +57,11 @@ class ScriptInstanceElement extends AsyncElement {
     /**
      * Sets the attributes of the script as an object. Values are converted with the same rules
      * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
-     * `color:` prefixed strings are resolved, and a plain numeric array is converted to the
-     * type of the attribute it targets when that attribute currently holds a Vec2, Vec3, Vec4
-     * or Color.
+     * `color:` prefixed strings are resolved (an entity name against the nearest enclosing
+     * entity first, then outward, then the document — or a document-wide `#` selector; a bare
+     * value is always a name, never an element id), and a plain numeric array is converted to
+     * the type of the attribute it targets when that attribute currently holds a Vec2, Vec3,
+     * Vec4 or Color.
      * @param value - The attributes of the script.
      */
     set scriptAttributes(value: Record<string, any>) {
@@ -70,7 +75,10 @@ class ScriptInstanceElement extends AsyncElement {
     }
 
     /**
-     * Gets the attributes of the script.
+     * Gets the attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`,
+     * `vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being
+     * an entity name (nearest enclosing entity first, then outward, then the document) or a
+     * document-wide `#` selector (`entity:#id`), never a bare element id.
      * @returns The attributes of the script.
      */
     get scriptAttributes(): Record<string, any> {

package/src/components/scroll-view-component.ts

@@ -8,7 +8,7 @@ import {
     Vec2
 } from 'playcanvas';
 
-import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
+import { parseBool, parseEnum, parseNumber, parseVec2, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -82,22 +82,22 @@ class ScrollViewComponentElement extends ComponentElement {
             verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
         };
 
-        const viewport = getEntity(this._viewport);
+        const viewport = resolveEntity(this._viewport, this, 'viewport', 'reference ignored');
         if (viewport) {
             data.viewportEntity = viewport;
         }
 
-        const content = getEntity(this._content);
+        const content = resolveEntity(this._content, this, 'content', 'reference ignored');
         if (content) {
             data.contentEntity = content;
         }
 
-        const horizontalScrollbar = getEntity(this._horizontalScrollbar);
+        const horizontalScrollbar = resolveEntity(this._horizontalScrollbar, this, 'horizontal-scrollbar', 'reference ignored');
         if (horizontalScrollbar) {
             data.horizontalScrollbarEntity = horizontalScrollbar;
         }
 
-        const verticalScrollbar = getEntity(this._verticalScrollbar);
+        const verticalScrollbar = resolveEntity(this._verticalScrollbar, this, 'vertical-scrollbar', 'reference ignored');
         if (verticalScrollbar) {
             data.verticalScrollbarEntity = verticalScrollbar;
         }
@@ -294,20 +294,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * 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.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport, which clips the content to the scroll view's
+     * bounds. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @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;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'viewport', 'reference ignored');
+            if (entity) {
+                this.component.viewportEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the viewport.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport.
      * @returns The viewport entity reference.
      */
     get viewport() {
@@ -315,20 +320,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * 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.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content, which is moved as the scroll view is
+     * scrolled. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @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;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'content', 'reference ignored');
+            if (entity) {
+                this.component.contentEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the content.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content.
      * @returns The content entity reference.
      */
     get content() {
@@ -336,20 +346,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the horizontal `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @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;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'horizontal-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.horizontalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the horizontal scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal scrollbar.
      * @returns The horizontal scrollbar entity reference.
      */
     get horizontalScrollbar() {
@@ -357,20 +372,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the vertical `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @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;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'vertical-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.verticalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the vertical scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical scrollbar.
      * @returns The vertical scrollbar entity reference.
      */
     get verticalScrollbar() {

package/src/components/scrollbar-component.ts

@@ -1,7 +1,7 @@
 import type { ScrollbarComponent } from 'playcanvas';
 import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from 'playcanvas';
 
-import { getEntity, parseEnum, parseNumber } from '../parse';
+import { parseEnum, parseNumber, resolveEntity } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -45,7 +45,7 @@ class ScrollbarComponentElement extends ComponentElement {
             handleSize: this._handleSize
         };
 
-        const handle = getEntity(this._handle);
+        const handle = resolveEntity(this._handle, this, 'handle', 'reference ignored');
         if (handle) {
             data.handleEntity = handle;
         }
@@ -120,20 +120,25 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * scrollbar handle.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle. An exact name resolves against the
+     * nearest enclosing entity first, then outward, then the document. A non-empty reference that
+     * does not resolve warns and is ignored.
      * @param value - The handle entity reference.
      */
     set handle(value: string) {
         this._handle = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.handleEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'handle', 'reference ignored');
+            if (entity) {
+                this.component.handleEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the scrollbar handle.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle.
      * @returns The handle entity reference.
      */
     get handle() {

package/src/entity-base.ts

@@ -4,18 +4,29 @@ import type { AppElement } from './app';
 import { AsyncElement } from './async-element';
 
 /**
- * The attribute names of the inline `onpointer*` event handlers, shared by every element that
- * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * The event types the containing `<pc-app>` synthesizes on entity-fronting elements via picking:
+ * the `pointer*` events, plus `click` — which concludes a primary-button press and release, and
+ * is delivered as a `PointerEvent` exactly as modern browsers deliver native clicks.
  * @internal
  */
-export const POINTER_ATTRIBUTES = [
-    'onpointerenter',
-    'onpointerleave',
-    'onpointerdown',
-    'onpointerup',
-    'onpointermove'
+export const SYNTHESIZED_EVENTS = [
+    'pointerenter',
+    'pointerleave',
+    'pointerdown',
+    'pointerup',
+    'pointermove',
+    'click'
 ] as const;
 
+const SYNTHESIZED_EVENT_SET: ReadonlySet<string> = new Set(SYNTHESIZED_EVENTS);
+
+/**
+ * The attribute names of the inline event handlers (`onpointerdown`, `onclick`, ...), shared by
+ * every element that fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * @internal
+ */
+export const EVENT_ATTRIBUTES = SYNTHESIZED_EVENTS.map((type) => `on${type}`);
+
 /**
  * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
  * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
@@ -34,12 +45,13 @@ class EntityBaseElement extends AsyncElement {
     protected _appElement: AppElement | null = null;
 
     /**
-     * The pointer event listeners for the entity.
+     * The event listeners registered on the element, by type.
      */
     private _listeners: Record<string, EventListener[]> = {};
 
     /**
-     * The event types for which an inline `onpointer*` attribute is currently present.
+     * The event types for which an inline handler attribute (`onpointerdown`, `onclick`, ...)
+     * is currently present.
      */
     private _inlineHandlerTypes = new Set<string>();
 
@@ -75,7 +87,7 @@ class EntityBaseElement extends AsyncElement {
     }
 
     /**
-     * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+     * Tracks whether an inline handler attribute is present. The browser itself compiles and
      * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
      * the previous handler and removing it removes the handler, exactly like `onclick` on any
      * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
@@ -105,7 +117,7 @@ class EntityBaseElement extends AsyncElement {
         }
         this._listeners[type].push(listener);
         super.addEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
         }
     }
@@ -115,15 +127,15 @@ class EntityBaseElement extends AsyncElement {
             this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
         }
         super.removeEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
         }
     }
 
     /**
      * Whether the element has a listener for an event type, registered either with
-     * {@link EventTarget.addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-     * containing `<pc-app>` element to gate pointer event synthesis.
+     * {@link EventTarget.addEventListener} or with the matching inline handler attribute. Read by the
+     * containing `<pc-app>` element to gate event synthesis.
      *
      * @param type - The event type.
      * @returns Whether a listener is registered.

package/src/entity.ts

@@ -1,6 +1,6 @@
 import { Vec3 } from 'playcanvas';
 
-import { POINTER_ATTRIBUTES } from './entity-base';
+import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -12,8 +12,8 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  *
  * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
  * intersects this entity's geometry. They are only generated while the entity has a listener for
- * them, registered either with {@link EventTarget.addEventListener} or with the matching inline `onpointer*`
- * attribute.
+ * them, registered either with {@link EventTarget.addEventListener} or with the matching inline
+ * attribute (`onpointerdown`, `onclick`, ...).
  *
  * @elementSummary The `<pc-entity>` element creates an entity: a named, transformable node of the
  * scene hierarchy, and the host for component elements such as `<pc-camera>`, `<pc-light>` and
@@ -33,11 +33,17 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * entity.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * entity.
+ * @attribute {string} onclick - Script to run when the entity is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the entity. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  */
 class EntityElement extends EntityOwnerElement {
     connectedCallback() {
@@ -77,7 +83,7 @@ class EntityElement extends EntityOwnerElement {
     }
 
     static get observedAttributes() {
-        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -105,6 +111,7 @@ class EntityElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/model.ts

@@ -2,7 +2,7 @@ import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 import { Vec3 } from 'playcanvas';
 
 import { useAsset } from './asset';
-import { POINTER_ATTRIBUTES } from './entity-base';
+import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -143,11 +143,17 @@ const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number
  * model.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * model.
+ * @attribute {string} onclick - Script to run when the model is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the model.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the model.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the model.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the model.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the model.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the model. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  * @fires {Event} load - Fired each time a container asset finishes instantiating, including
  * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
  * capture-phase listener on an ancestor.
@@ -435,7 +441,7 @@ class ModelElement extends EntityOwnerElement {
     }
 
     static get observedAttributes() {
-        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -466,6 +472,7 @@ class ModelElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/node.ts

@@ -2,7 +2,7 @@ import type { Entity, EventHandle, GraphNode, Material, MeshInstance, Quat, Rend
 import { Vec3 } from 'playcanvas';
 
 import { ComponentElement } from './components/component';
-import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
+import { EntityBaseElement, EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities } from './entity-owner';
 import type { EntityOwnerElement } from './entity-owner';
 import { MaterialElement } from './material';
@@ -193,11 +193,17 @@ const levenshtein = (a: string, b: string): number => {
  * node.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * node.
+ * @attribute {string} onclick - Script to run when the node is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the node. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  */
 class NodeElement extends EntityBaseElement {
     private _name = '';
@@ -933,7 +939,7 @@ class NodeElement extends EntityBaseElement {
             'rotation',
             'scale',
             'tags',
-            ...POINTER_ATTRIBUTES
+            ...EVENT_ATTRIBUTES
         ];
     }
 
@@ -982,6 +988,7 @@ class NodeElement extends EntityBaseElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }