@playcanvas/web-components 0.9.0 → 0.10.1

package/README.md

@@ -38,6 +38,24 @@ See PlayCanvas Web Components in action here: https://playcanvas.github.io/web-c
 
 Please see the [Getting Started Guide](https://developer.playcanvas.com/user-manual/web-components/getting-started/) for installation and usage instructions.
 
+## Editor Support
+
+The package ships a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest), which editors use to offer tag and attribute completions, valid attribute values and hover documentation when authoring HTML.
+
+**VS Code** — add the following to your workspace `.vscode/settings.json`:
+
+```json
+{
+  "html.customData": [
+    "./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json"
+  ]
+}
+```
+
+**JetBrains IDEs** (WebStorm, IntelliJ IDEA) — no setup required. The IDE discovers the bundled `web-types.json` automatically.
+
+**Other tooling** — the manifest itself is at `@playcanvas/web-components/dist/custom-elements.json` and is declared in the package's `customElements` field, which is how tools such as `lit-analyzer` and Storybook locate it.
+
 ## Development 
 
 ### Setting Up Local Development

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;
     /**
@@ -67,7 +97,8 @@ declare class AppElement extends AsyncElement {
      */
     get antialias(): boolean;
     /**
-     * Sets the graphics backend.
+     * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
+     * is not supported by the browser.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null');
@@ -103,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.
@@ -114,7 +160,7 @@ declare class AppElement extends AsyncElement {
      */
     get stencil(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/asset.d.ts

@@ -12,6 +12,28 @@ import { AsyncElement } from './async-element';
  * while the application is running are created and registered on insertion, and begin loading
  * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
  * elsewhere, or with an unsupported asset type, never become ready.
+ *
+ * Apart from `lazy`, these attributes are read once when the asset is created, so changing them
+ * later has no effect.
+ *
+ * @attribute {string} id - The identifier used to reference the asset from other elements.
+ * @attribute {string} src - The URL of the asset to load.
+ * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.
+ * @attribute {string} data - Additional asset data, as a JSON object.
+ * @attribute {string} atlas - For a `sprite` asset, the `id` of the texture atlas asset it uses.
+ * The atlas must be declared before the sprite.
+ * @attribute {string} frame-keys - For a `sprite` asset, the atlas frame keys it uses, separated
+ * by spaces or commas.
+ * @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;
@@ -22,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,
@@ -44,7 +68,7 @@ declare class AssetElement extends AsyncElement {
     get lazy(): boolean;
     static get(id: string): Asset | null | undefined;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/async-element.d.ts

@@ -2,14 +2,27 @@ import { AppElement } from './app';
 import { EntityElement } from './entity';
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
+ *
+ * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
+ * composed.
  */
 declare class AsyncElement extends HTMLElement {
     private _readyPromise;
     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/button-component.d.ts

@@ -180,7 +180,7 @@ declare class ButtonComponentElement extends ComponentElement {
      */
     get inactiveSpriteFrame(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -247,7 +247,7 @@ declare class CameraComponentElement extends ComponentElement {
      */
     get tonemap(): 'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral';
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -51,7 +51,7 @@ declare class CollisionComponentElement extends ComponentElement {
     set type(value: 'box' | 'capsule' | 'compound' | 'cone' | 'cylinder' | 'mesh' | 'sphere');
     get type(): "box" | "capsule" | "compound" | "cone" | "cylinder" | "mesh" | "sphere";
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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.
@@ -39,6 +40,6 @@ declare class ComponentElement extends AsyncElement {
      */
     get enabled(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 export { ComponentElement };

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

@@ -310,7 +310,7 @@ declare class ElementComponentElement extends ComponentElement {
      */
     get maxFontSize(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -103,7 +103,7 @@ declare class GSplatComponentElement extends ComponentElement {
      */
     get lodRangeMax(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -105,7 +105,7 @@ declare class LayoutChildComponentElement extends ComponentElement {
      */
     get excludeFromLayout(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -130,7 +130,7 @@ declare class LayoutGroupComponentElement extends ComponentElement {
      */
     get wrap(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -258,7 +258,7 @@ declare class LightComponentElement extends ComponentElement {
      */
     get shadowBlockerSamples(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -47,7 +47,7 @@ declare class ParticleSystemComponentElement extends ComponentElement {
      */
     stop(): void;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -71,7 +71,7 @@ declare class RenderComponentElement extends ComponentElement {
      */
     get receiveShadows(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -82,7 +82,7 @@ declare class RigidBodyComponentElement extends ComponentElement {
     set type(value: 'static' | 'dynamic' | 'kinematic');
     get type(): "static" | "dynamic" | "kinematic";
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -43,7 +43,7 @@ declare class ScreenComponentElement extends ComponentElement {
     set screenSpace(value: boolean);
     get screenSpace(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/script.d.ts

@@ -25,6 +25,13 @@ import { AsyncElement } from '../async-element';
  *
  * The element becomes ready once its script instance has been created by the parent
  * `<pc-scripts>` element.
+ *
+ * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
+ * `detail` carries the new `attributes` object. Bubbles.
+ * @fires {CustomEvent} scriptenablechange - Fired when the script's enabled state changes. The
+ * `detail` carries the new `enabled` state. Bubbles.
+ * @fires {CustomEvent} scriptnamechange - Fired when the script is renamed on a live element. The
+ * `detail` carries `oldName` and `newName`. Bubbles.
  */
 declare class ScriptElement extends AsyncElement {
     private _attributes;
@@ -97,7 +104,7 @@ declare class ScriptElement extends AsyncElement {
      */
     _onScriptCreated(): void;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -64,7 +64,7 @@ declare class ScrollbarComponentElement extends ComponentElement {
      */
     get handle(): string;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -170,7 +170,7 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get verticalScrollbar(): string;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -103,7 +103,7 @@ declare class SoundComponentElement extends ComponentElement {
      */
     get volume(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/sound-slot.d.ts

@@ -16,6 +16,14 @@ declare class SoundSlotElement extends AsyncElement {
     private _pitch;
     private _startTime;
     private _volume;
+    /**
+     * The `<pc-sounds>` this slot was added to, captured at connect time.
+     *
+     * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+     * `parentElement` is already `null`, so a lookup would both fail to find the component and
+     * emit a misleading "must be a direct child" warning for what is an ordinary removal.
+     */
+    private _soundElement;
     /**
      * The sound slot.
      */
@@ -114,7 +122,7 @@ declare class SoundSlotElement extends AsyncElement {
      */
     get volume(): number;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 declare global {
     interface HTMLElementTagNameMap {