@playcanvas/web-components 0.9.0 → 0.10.0

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

@@ -67,7 +67,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');
@@ -114,7 +115,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,21 @@ 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.
  */
 declare class AssetElement extends AsyncElement {
     private _lazy;
@@ -44,7 +59,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,6 +2,9 @@ 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;

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

@@ -39,6 +39,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 {