@playcanvas/web-components 0.18.0 → 0.19.0

package/dist/app.d.cts

@@ -63,10 +63,24 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
     private _app;
     private _loadProgress;
     /**
@@ -187,8 +201,15 @@ declare class AppElement extends AsyncElement {
     private _onPointerMove;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/app.d.ts

@@ -63,10 +63,24 @@ declare class AppElement extends AsyncElement {
      */
     private _entityElements;
     private _picker;
-    private _hasPointerListeners;
     private _hoveredEntity;
     private _pickToken;
     private _pointerHandlers;
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks;
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened;
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick;
     private _app;
     private _loadProgress;
     /**
@@ -187,8 +201,15 @@ declare class AppElement extends AsyncElement {
     private _onPointerMove;
     private _onPointerDown;
     private _onPointerUp;
-    private _onPointerListenerAdded;
-    private _onPointerListenerRemoved;
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners;
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/dist/components/anim-clip.d.cts

@@ -16,8 +16,6 @@ import { AnimComponentElement } from './anim-component.cjs';
  * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
  * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
  * own animations. Must be a direct child of `<pc-anim>`.
- *
- * @category Components
  */
 declare class AnimClipElement extends AsyncElement {
     /**

package/dist/components/anim-clip.d.ts

@@ -16,8 +16,6 @@ import { AnimComponentElement } from './anim-component.js';
  * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
  * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
  * own animations. Must be a direct child of `<pc-anim>`.
- *
- * @category Components
  */
 declare class AnimClipElement extends AsyncElement {
     /**

package/dist/custom-elements.json

@@ -1378,9 +1378,16 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The EntityElement interface provides properties and methods for manipulating\n[`<pc-entity>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/) elements.\nThe EntityElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe pointer events below are dispatched by the containing `<pc-app>` element when the pointer\nintersects this entity's geometry. They are only generated while the entity has a listener for\nthem, registered either with EventTarget.addEventListener or with the matching inline `onpointer*`\nattribute.\n",
+          "description": "The EntityElement interface provides properties and methods for manipulating\n[`<pc-entity>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/) elements.\nThe EntityElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe pointer events below are dispatched by the containing `<pc-app>` element when the pointer\nintersects this entity's geometry. They are only generated while the entity has a listener for\nthem, registered either with EventTarget.addEventListener or with the matching inline\nattribute (`onpointerdown`, `onclick`, ...).\n",
           "name": "EntityElement",
           "events": [
+            {
+              "type": {
+                "text": "PointerEvent"
+              },
+              "description": "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.",
+              "name": "click"
+            },
             {
               "type": {
                 "text": "PointerEvent"
@@ -1446,6 +1453,14 @@
               "description": "The name of the entity.",
               "fieldName": "name"
             },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "Script to run when the entity is clicked: a primary pointer button pressed and then released over it.",
+              "name": "onclick",
+              "fieldName": "onclick"
+            },
             {
               "type": {
                 "text": "string"
@@ -4711,6 +4726,13 @@
             }
           ],
           "events": [
+            {
+              "type": {
+                "text": "PointerEvent"
+              },
+              "description": "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.",
+              "name": "click"
+            },
             {
               "name": "error",
               "type": {
@@ -4798,6 +4820,14 @@
               "description": "The name of the model.",
               "fieldName": "name"
             },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "Script to run when the model is clicked: a primary pointer button pressed and then released over it.",
+              "name": "onclick",
+              "fieldName": "onclick"
+            },
             {
               "type": {
                 "text": "string"
@@ -5235,6 +5265,13 @@
             }
           ],
           "events": [
+            {
+              "type": {
+                "text": "PointerEvent"
+              },
+              "description": "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.",
+              "name": "click"
+            },
             {
               "type": {
                 "text": "PointerEvent"
@@ -5315,6 +5352,14 @@
               "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",
               "fieldName": "name"
             },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "Script to run when the node is clicked: a primary pointer button pressed and then released over it.",
+              "name": "onclick",
+              "fieldName": "onclick"
+            },
             {
               "type": {
                 "text": "string"
@@ -5469,6 +5514,22 @@
                 "module": "src/async-element.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "exposure",
+              "description": "Gets the exposure of the scene.",
+              "parameters": [
+                {
+                  "description": "The exposure.",
+                  "name": "value"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": ""
+                }
+              }
+            },
             {
               "kind": "field",
               "name": "fog",
@@ -5595,6 +5656,15 @@
             }
           ],
           "attributes": [
+            {
+              "name": "exposure",
+              "type": {
+                "text": "number"
+              },
+              "fieldName": "exposure",
+              "default": "1",
+              "description": "The exposure of the scene."
+            },
             {
               "name": "fog",
               "type": {
@@ -5654,7 +5724,7 @@
             "name": "AsyncElement",
             "module": "/src/async-element"
           },
-          "summary": "The `<pc-scene>` element holds the entity hierarchy the application renders,\nalong with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.\n",
+          "summary": "The `<pc-scene>` element holds the entity hierarchy the application renders,\nalong with the scene-wide fog, exposure and gravity settings. Must be a direct child of\n`<pc-app>`.\n",
           "tagName": "pc-scene",
           "customElement": true,
           "events": [

package/dist/entity-base.d.cts

@@ -17,11 +17,12 @@ declare class EntityBaseElement extends AsyncElement {
      */
     protected _appElement: AppElement | null;
     /**
-     * The pointer event listeners for the entity.
+     * The event listeners registered on the element, by type.
      */
     private _listeners;
     /**
-     * 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;
     /**
@@ -45,7 +46,7 @@ declare class EntityBaseElement extends AsyncElement {
      */
     protected _unregisterEntity(entity: Entity): void;
     /**
-     * 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

package/dist/entity-base.d.ts

@@ -17,11 +17,12 @@ declare class EntityBaseElement extends AsyncElement {
      */
     protected _appElement: AppElement | null;
     /**
-     * The pointer event listeners for the entity.
+     * The event listeners registered on the element, by type.
      */
     private _listeners;
     /**
-     * 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;
     /**
@@ -45,7 +46,7 @@ declare class EntityBaseElement extends AsyncElement {
      */
     protected _unregisterEntity(entity: Entity): void;
     /**
-     * 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

package/dist/entity.d.cts

@@ -7,8 +7,8 @@ import { EntityOwnerElement } from './entity-owner.cjs';
  *
  * 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
@@ -28,11 +28,17 @@ import { EntityOwnerElement } from './entity-owner.cjs';
  * 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.
  */
 declare class EntityElement extends EntityOwnerElement {
     connectedCallback(): void;

package/dist/entity.d.ts

@@ -7,8 +7,8 @@ import { EntityOwnerElement } from './entity-owner.js';
  *
  * 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
@@ -28,11 +28,17 @@ import { EntityOwnerElement } from './entity-owner.js';
  * 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.
  */
 declare class EntityElement extends EntityOwnerElement {
     connectedCallback(): void;

package/dist/model.d.cts

@@ -97,11 +97,17 @@ type HierarchyNode = {
  * 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.

package/dist/model.d.ts

@@ -97,11 +97,17 @@ type HierarchyNode = {
  * 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.

package/dist/node.d.cts

@@ -67,11 +67,17 @@ type MaterialOverrides = Readonly<Record<string, string>>;
  * 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.
  */
 declare class NodeElement extends EntityBaseElement {
     private _name;

package/dist/node.d.ts

@@ -67,11 +67,17 @@ type MaterialOverrides = Readonly<Record<string, string>>;
  * 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.
  */
 declare class NodeElement extends EntityBaseElement {
     private _name;