@playcanvas/web-components 0.10.0 → 0.11.0

package/dist/app.d.ts

@@ -1,10 +1,16 @@
-import { AppBase } from 'playcanvas';
+import { AppBase, Entity } from 'playcanvas';
 import { AsyncElement } from './async-element';
+import { EntityElement } from './entity';
 /**
  * The AppElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
  * The AppElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
+ * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
+ * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
+ * not bubble.
  */
 declare class AppElement extends AsyncElement {
     /**
@@ -14,21 +20,46 @@ declare class AppElement extends AsyncElement {
     private _alpha;
     private _backend;
     private _antialias;
-    private _depth;
-    private _stencil;
-    private _highResolution;
+    private _depthBuffer;
+    private _stencilBuffer;
+    private _maxPixelRatio;
+    private _loadingBar;
+    /**
+     * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+     * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+     * cleared on disconnect so a re-connected element boots from its current attributes.
+     */
+    private _optionsLocked;
+    private _bar;
     private _hierarchyReady;
+    /**
+     * The elements backing this application's entities, keyed by the entity itself. Registered
+     * by EntityElement at creation and removed when an entity is destroyed, this joins engine
+     * scene nodes back to their owning elements by identity - never by name.
+     */
+    private _entityElements;
     private _picker;
     private _hasPointerListeners;
     private _hoveredEntity;
+    private _pickToken;
     private _pointerHandlers;
     private _app;
+    private _loadProgress;
     /**
-     * The PlayCanvas application instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The application instance.
+     * The PlayCanvas application instance. `null` until the element is ready, and again once it
+     * has been removed from the document — await {@link whenReady} or the element's `ready()`
+     * promise before accessing it.
+     * @returns The application instance, or `null`.
      */
-    get app(): AppBase;
+    get app(): AppBase | null;
+    /**
+     * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
+     * preloading begins (and again once the element has been removed from the document), and 1
+     * once preloading has finished — including when there was nothing to preload. Read this to
+     * initialize a loading UI; subsequent updates arrive via the `progress` event.
+     * @returns The preload progress.
+     */
+    get loadProgress(): number;
     /**
      * Creates a new AppElement instance.
      *
@@ -40,35 +71,100 @@ declare class AppElement extends AsyncElement {
     _onWindowResize(): void;
     _pickerCreate(): void;
     _pickerDestroy(): void;
+    /**
+     * Registers the element that created an entity. Called by EntityElement when it creates its
+     * entity.
+     *
+     * @param entity - The entity.
+     * @param element - The element that created it.
+     * @ignore
+     */
+    _registerEntityElement(entity: Entity, element: EntityElement): void;
+    /**
+     * Removes the registration for a destroyed entity. Called by EntityElement.
+     *
+     * @param entity - The entity.
+     * @ignore
+     */
+    _unregisterEntityElement(entity: Entity): void;
+    /**
+     * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
+     * entity was not created by an element of this application - for example, a node inside a
+     * model's instantiated hierarchy, or an entity created through the engine API.
+     *
+     * @param entity - The entity to look up.
+     * @returns The element backing the entity, or `null`.
+     */
+    elementFromEntity(entity: Entity): EntityElement | null;
+    /**
+     * Resolves the element that owns a picked node: the nearest node up the parent chain -
+     * starting with the node itself - that was created by a `<pc-entity>` of this application.
+     * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
+     * the model.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The owning element, or `null`.
+     */
+    private _elementFromNode;
+    /**
+     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
+     * on an unlistened child still reaches a listening ancestor.
+     *
+     * @param node - The picked node, or `null`.
+     * @param type - The pointer event type a listener is required for.
+     * @returns The nearest listening element, or `null`.
+     */
+    private _elementWithListener;
     private _getPickerCoordinates;
-    _onPointerMove(event: PointerEvent): void;
-    _onPointerDown(event: PointerEvent): void;
-    _onPointerUp(event: PointerEvent): void;
+    /**
+     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
+     *
+     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
+     * supported on WebGPU, where it returns an empty selection rather than failing - which
+     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
+     * async variant works on both backends and does not block the main thread on a GPU read.
+     *
+     * @param event - The pointer event to pick under.
+     * @returns The graph node under the pointer, or `null` if nothing was hit.
+     */
+    private _pickNode;
+    _onPointerMove(event: PointerEvent): Promise<void>;
+    _onPointerDown(event: PointerEvent): Promise<void>;
+    _onPointerUp(event: PointerEvent): Promise<void>;
     _onPointerListenerAdded(type: string): void;
     _onPointerListenerRemoved(type: string): void;
     /**
-     * Sets the alpha flag.
+     * 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
+     * only the element's own property - silently, without this.
+     *
+     * @param name - The name of the option, as its attribute.
+     */
+    private _warnIfBooted;
+    /**
+     * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+     * wherever the scene has not drawn. Read only when the application boots.
      * @param value - The alpha flag.
      */
     set alpha(value: boolean);
     /**
-     * Gets the alpha flag.
+     * Gets whether the frame buffer has an alpha channel.
      * @returns The alpha flag.
      */
     get alpha(): boolean;
     /**
-     * Sets the antialias flag.
+     * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
      * @param value - The antialias flag.
      */
     set antialias(value: boolean);
     /**
-     * Gets the antialias flag.
+     * Gets whether the frame buffer is anti-aliased.
      * @returns The antialias flag.
      */
     get antialias(): boolean;
     /**
      * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
-     * is not supported by the browser.
+     * is not supported by the browser. Read only when the application boots.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null');
@@ -78,15 +174,16 @@ declare class AppElement extends AsyncElement {
      */
     get backend(): "webgpu" | "webgl2" | "null";
     /**
-     * Sets the depth flag.
-     * @param value - The depth flag.
+     * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+     * surface is nearest the camera. Read only when the application boots.
+     * @param value - The depth buffer flag.
      */
-    set depth(value: boolean);
+    set depthBuffer(value: boolean);
     /**
-     * Gets the depth flag.
-     * @returns The depth flag.
+     * Gets whether the frame buffer has a depth buffer.
+     * @returns The depth buffer flag.
      */
-    get depth(): boolean;
+    get depthBuffer(): boolean;
     /**
      * Gets the hierarchy ready flag.
      * @returns The hierarchy ready flag.
@@ -94,26 +191,45 @@ declare class AppElement extends AsyncElement {
      */
     get hierarchyReady(): boolean;
     /**
-     * Sets the high resolution flag. When true, the application will render at the device's
-     * physical resolution. When false, the application will render at CSS resolution.
-     * @param value - The high resolution flag.
+     * Sets whether the application shows its built-in loading bar while it boots and preloads its
+     * assets. Enabled by default; setting `false` removes the bar immediately, while setting
+     * `true` has no effect until the element is next connected. The bar can be themed with the
+     * CSS custom properties `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+     * `--pc-loading-bar-height`.
+     * @param value - The loading bar flag.
+     */
+    set loadingBar(value: boolean);
+    /**
+     * Gets whether the application shows its built-in loading bar while it boots and preloads
+     * its assets.
+     * @returns The loading bar flag.
+     */
+    get loadingBar(): boolean;
+    /**
+     * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+     * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+     * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+     * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+     * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+     * @param value - The maximum pixel ratio.
      */
-    set highResolution(value: boolean);
+    set maxPixelRatio(value: number);
     /**
-     * Gets the high resolution flag.
-     * @returns The high resolution flag.
+     * Gets the cap on the pixel ratio the application renders at.
+     * @returns The maximum pixel ratio.
      */
-    get highResolution(): boolean;
+    get maxPixelRatio(): number;
     /**
-     * Sets the stencil flag.
-     * @param value - The stencil flag.
+     * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+     * masking need. Read only when the application boots.
+     * @param value - The stencil buffer flag.
      */
-    set stencil(value: boolean);
+    set stencilBuffer(value: boolean);
     /**
-     * Gets the stencil flag.
-     * @returns The stencil flag.
+     * Gets whether the frame buffer has a stencil buffer.
+     * @returns The stencil buffer flag.
      */
-    get stencil(): boolean;
+    get stencilBuffer(): boolean;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }

package/dist/asset.d.ts

@@ -27,6 +27,13 @@ import { AsyncElement } from './async-element';
  * @attribute {number} pixels-per-unit - For a `sprite` asset, the number of pixels per world unit.
  * @attribute {'simple' | 'sliced' | 'tiled'} render-mode - For a `sprite` asset, how the sprite is
  * rendered when resized.
+ *
+ * @fires {Event} load - Fired each time the asset finishes loading, including a `lazy` asset
+ * loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor to observe every asset.
+ * @fires {ErrorEvent} error - Fired when the asset fails to load, with the engine's error in
+ * `message`. Does not bubble. The element still becomes ready — readiness means the load settled,
+ * not that it succeeded.
  */
 declare class AssetElement extends AsyncElement {
     private _lazy;
@@ -37,6 +44,8 @@ declare class AssetElement extends AsyncElement {
     asset: Asset | null;
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
+    private _onAssetLoad;
+    private _onAssetError;
     createAsset(): void;
     /**
      * Builds the `data` object for the asset from an optional inline `data` attribute (JSON) and,

package/dist/async-element.d.ts

@@ -11,8 +11,18 @@ declare class AsyncElement extends HTMLElement {
     private _readyResolve;
     /** @ignore */
     constructor();
-    get closestApp(): AppElement;
-    get closestEntity(): EntityElement;
+    /**
+     * The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest app element, or `null`.
+     */
+    get closestApp(): AppElement | null;
+    /**
+     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest entity element, or `null`.
+     */
+    get closestEntity(): EntityElement | null;
     /**
      * Called when the element is fully initialized and ready. Subclasses should call this when
      * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`

package/dist/components/camera-component.d.ts

@@ -21,7 +21,7 @@ declare class CameraComponentElement extends ComponentElement {
     private _gamma;
     private _horizontalFov;
     private _nearClip;
-    private _orthographic;
+    private _projection;
     private _orthoHeight;
     private _priority;
     private _rect;
@@ -42,12 +42,12 @@ declare class CameraComponentElement extends ComponentElement {
         gammaCorrection: 0 | 1;
         horizontalFov: boolean;
         nearClip: number;
-        projection: 0 | 1;
+        projection: number;
         orthoHeight: number;
         priority: number;
         rect: Vec4;
         scissorRect: Vec4;
-        toneMapping: number | undefined;
+        toneMapping: number;
     };
     get xrAvailable(): boolean | null;
     /**
@@ -186,16 +186,6 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The near clip distance.
      */
     get nearClip(): number;
-    /**
-     * Sets the orthographic projection of the camera.
-     * @param value - The orthographic projection.
-     */
-    set orthographic(value: boolean);
-    /**
-     * Gets the orthographic projection of the camera.
-     * @returns The orthographic projection.
-     */
-    get orthographic(): boolean;
     /**
      * Sets the orthographic height of the camera.
      * @param value - The orthographic height.
@@ -216,6 +206,16 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The priority.
      */
     get priority(): number;
+    /**
+     * Sets the projection of the camera. Use `orthoHeight` to size an orthographic projection.
+     * @param value - The projection ('perspective' or 'orthographic').
+     */
+    set projection(value: 'perspective' | 'orthographic');
+    /**
+     * Gets the projection of the camera.
+     * @returns The projection.
+     */
+    get projection(): "perspective" | "orthographic";
     /**
      * Sets the rect of the camera.
      * @param value - The rect.

package/dist/components/component.d.ts

@@ -23,11 +23,12 @@ declare class ComponentElement extends AsyncElement {
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     /**
-     * The PlayCanvas component instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The component instance.
+     * The PlayCanvas component instance. `null` until the element is ready, and also for an
+     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
+     * element's `ready()` promise before accessing it.
+     * @returns The component instance, or `null`.
      */
-    get component(): Component;
+    get component(): Component | null;
     /**
      * Sets the enabled state of the component.
      * @param value - The enabled state of the component.

package/dist/components/screen-component.d.ts

@@ -13,7 +13,7 @@ declare class ScreenComponentElement extends ComponentElement {
     private _resolution;
     private _referenceResolution;
     private _priority;
-    private _blend;
+    private _scaleMode;
     private _scaleBlend;
     /** @ignore */
     constructor();
@@ -22,7 +22,7 @@ declare class ScreenComponentElement extends ComponentElement {
         referenceResolution: Vec2;
         resolution: Vec2;
         scaleBlend: number;
-        scaleMode: "none" | "blend";
+        scaleMode: string;
         screenSpace: boolean;
     };
     /**
@@ -36,10 +36,31 @@ declare class ScreenComponentElement extends ComponentElement {
     get referenceResolution(): Vec2;
     set resolution(value: Vec2);
     get resolution(): Vec2;
+    /**
+     * Sets how the screen's `resolution` and `referenceResolution` are weighted against each other
+     * when `scaleMode` is `blend`, from 0 (follow the resolution) to 1 (follow the reference
+     * resolution). Ignored while `scaleMode` is `none`.
+     * @param value - The scale blend factor.
+     */
     set scaleBlend(value: number);
+    /**
+     * Gets how the screen's resolutions are weighted against each other.
+     * @returns The scale blend factor.
+     */
     get scaleBlend(): number;
-    set blend(value: boolean);
-    get blend(): boolean;
+    /**
+     * Sets how the screen scales its contents. `none` renders at `resolution` and ignores
+     * `referenceResolution`; `blend` scales between the two, weighted by `scaleBlend`, which is what
+     * keeps a UI laid out at one resolution usable at another. Requires `screenSpace` - the engine
+     * forces `none` on a world-space screen, which does not support scaling.
+     * @param value - The scale mode ('none' or 'blend').
+     */
+    set scaleMode(value: 'none' | 'blend');
+    /**
+     * Gets how the screen scales its contents.
+     * @returns The scale mode.
+     */
+    get scaleMode(): "none" | "blend";
     set screenSpace(value: boolean);
     get screenSpace(): boolean;
     static get observedAttributes(): string[];

package/dist/components/scrollview-component.d.ts

@@ -31,22 +31,24 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get component(): ScrollViewComponent;
     /**
-     * Sets whether horizontal scrolling is enabled.
+     * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
      * @param value - Whether horizontal scrolling is enabled.
      */
     set horizontal(value: boolean);
     /**
-     * Gets whether horizontal scrolling is enabled.
+     * Gets whether scrolling along the horizontal axis is enabled.
      * @returns Whether horizontal scrolling is enabled.
      */
     get horizontal(): boolean;
     /**
-     * Sets whether vertical scrolling is enabled.
+     * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
      * @param value - Whether vertical scrolling is enabled.
      */
     set vertical(value: boolean);
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical(): boolean;