@playcanvas/web-components 0.10.0 → 0.10.1

package/dist/app.d.ts

@@ -5,6 +5,11 @@ import { AsyncElement } from './async-element';
  * {@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 {
     /**
@@ -17,18 +22,31 @@ declare class AppElement extends AsyncElement {
     private _depth;
     private _stencil;
     private _highResolution;
+    private _loadingBar;
+    private _bar;
     private _hierarchyReady;
     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.
      *
@@ -41,9 +59,21 @@ declare class AppElement extends AsyncElement {
     _pickerCreate(): void;
     _pickerDestroy(): void;
     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;
     /**
@@ -104,6 +134,21 @@ declare class AppElement extends AsyncElement {
      * @returns The high resolution flag.
      */
     get highResolution(): boolean;
+    /**
+     * 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 stencil flag.
      * @param value - The stencil flag.

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/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.