@playcanvas/web-components 0.17.0 → 0.18.0

package/src/components/scrollbar-component.ts

@@ -18,6 +18,10 @@ const orientations = new Map<'horizontal' | 'vertical', number>([
  *
  * Engine component: {@link ScrollbarComponent} (`scrollbar`).
  *
+ * @elementSummary The `<pc-scrollbar>` element gives its entity a draggable handle reporting a
+ * position from 0 to 1, which a `<pc-scroll-view>` references to scroll its content. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {

package/src/components/sound-component.ts

@@ -12,6 +12,10 @@ import { ComponentElement } from './component';
  *
  * Engine component: {@link SoundComponent} (`sound`).
  *
+ * @elementSummary The `<pc-sound>` element holds the `<pc-sound-slot>` children that play sounds at
+ * its entity, along with the positional audio settings they share. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class SoundComponentElement extends ComponentElement {

package/src/components/sound-slot.ts

@@ -10,6 +10,9 @@ import { SoundComponentElement } from './sound-component';
  * The SoundSlotElement interface provides properties and methods for manipulating
  * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
+ *
+ * @elementSummary The `<pc-sound-slot>` element declares one named sound on its parent `<pc-sound>`
+ * — its asset, volume, pitch, looping and autoplay. Must be a direct child of `<pc-sound>`.
  */
 class SoundSlotElement extends AsyncElement {
     private _asset = '';

package/src/entity-base.ts

@@ -78,7 +78,7 @@ class EntityBaseElement extends AsyncElement {
      * Tracks whether an inline `onpointer*` 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 addEventListener}, the connect/disconnect
+     * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
      * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
      * kept in sync here.
      *
@@ -122,7 +122,7 @@ class EntityBaseElement extends AsyncElement {
 
     /**
      * Whether the element has a listener for an event type, registered either with
-     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+     * {@link EventTarget.addEventListener} or with the matching inline `onpointer*` attribute. Read by the
      * containing `<pc-app>` element to gate pointer event synthesis.
      *
      * @param type - The event type.

package/src/entity-owner.ts

@@ -69,7 +69,7 @@ class EntityOwnerElement extends EntityBaseElement {
     private _tags: string[] = [];
 
     /**
-     * Whether the hierarchy has been built for this entity — set once {@link _buildHierarchy} has
+     * Whether the hierarchy has been built for this entity — set once `_buildHierarchy` has
      * parented it. Read by subclasses that gate work on the entity being in the scene graph.
      */
     protected _built = false;
@@ -170,7 +170,7 @@ class EntityOwnerElement extends EntityBaseElement {
     }
 
     /**
-     * Called by {@link _buildHierarchy} once the backing entity has been parented — exactly once
+     * Called by `_buildHierarchy` once the backing entity has been parented — exactly once
      * per build cycle. The default announces readiness, which is what a parented `<pc-entity>`
      * means; `<pc-model>` overrides it to start loading content instead, because its readiness
      * tracks the content settling rather than the host entering the scene graph.

package/src/entity.ts

@@ -12,9 +12,14 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  *
  * 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 addEventListener} or with the matching inline `onpointer*`
+ * them, registered either with {@link EventTarget.addEventListener} or with the matching inline `onpointer*`
  * attribute.
  *
+ * @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
+ * `<pc-render>`. Place it in the `<pc-scene>`, or nest it under another `<pc-entity>`, a
+ * `<pc-model>` or a `<pc-node>` to parent it there.
+ *
  * @attribute {boolean} enabled - The enabled state of the entity.
  * @attribute {string} name - The name of the entity.
  * @attribute {string} position - The position of the entity.

package/src/index.ts

@@ -134,6 +134,17 @@ export {
     whenReady
 };
 
+export type { AddressMode, MagFilterMode, MinFilterMode } from './asset';
 export type { AsyncElementTagName } from './async-element';
+export type { JointType, MotionMode } from './components/joint-component';
+export type {
+    BlendType,
+    ColorChannel,
+    CullMode,
+    FresnelModel,
+    OccludeSpecular,
+    OpacityDither,
+    ScalarChannel
+} from './material';
 export type { HierarchyMaterial, HierarchyNode } from './model';
-export type { MaterialOverrides } from './node';
+export type { MaterialOverrides, NodeBindingState } from './node';

package/src/material.ts

@@ -29,7 +29,8 @@ import type { AppElement } from './app';
 import { useAsset } from './asset';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2 } from './parse';
 
-type BlendType =
+/** The blend modes for a material. */
+export type BlendType =
     | 'none'
     | 'normal'
     | 'additive'
@@ -56,7 +57,8 @@ const blendTypes = new Map<BlendType, number>([
     ['subtractive', BLEND_SUBTRACTIVE]
 ]);
 
-type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
+/** The face culling modes for a material. */
+export type CullMode = 'none' | 'back' | 'front' | 'front-and-back';
 
 const cullModes = new Map<CullMode, number>([
     ['none', CULLFACE_NONE],
@@ -65,14 +67,16 @@ const cullModes = new Map<CullMode, number>([
     ['front-and-back', CULLFACE_FRONTANDBACK]
 ]);
 
-type FresnelModel = 'none' | 'schlick';
+/** The Fresnel models for a material. */
+export type FresnelModel = 'none' | 'schlick';
 
 const fresnelModels = new Map<FresnelModel, number>([
     ['none', FRESNEL_NONE],
     ['schlick', FRESNEL_SCHLICK]
 ]);
 
-type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
+/** The specular occlusion modes for a material. */
+export type OccludeSpecular = 'none' | 'ao' | 'gloss-dependent';
 
 const occludeSpeculars = new Map<OccludeSpecular, number>([
     ['none', SPECOCC_NONE],
@@ -80,17 +84,20 @@ const occludeSpeculars = new Map<OccludeSpecular, number>([
     ['gloss-dependent', SPECOCC_GLOSSDEPENDENT]
 ]);
 
+/** The opacity dithering modes for a material. */
+export type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
+
 // The DITHER_* constants are strings whose values are exactly these names, so a parsed value is
 // assigned to the material unchanged rather than mapped through a table.
-type OpacityDither = 'none' | 'bayer8' | 'bluenoise' | 'ignnoise';
-
 const opacityDithers: OpacityDither[] = ['none', 'bayer8', 'bluenoise', 'ignnoise'];
 
-type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
+/** The texture channels a color map can sample. */
+export type ColorChannel = 'r' | 'g' | 'b' | 'a' | 'rgb';
 
 const colorChannels: ColorChannel[] = ['r', 'g', 'b', 'a', 'rgb'];
 
-type ScalarChannel = 'r' | 'g' | 'b' | 'a';
+/** The texture channels a scalar map can sample. */
+export type ScalarChannel = 'r' | 'g' | 'b' | 'a';
 
 const scalarChannels: ScalarChannel[] = ['r', 'g', 'b', 'a'];
 
@@ -136,6 +143,10 @@ type TextureSlot =
  * The two aliases are documented here rather than on an accessor, because they resolve to the
  * `gloss` properties and would otherwise inherit gloss's description - which reads inverted.
  *
+ * @elementSummary The `<pc-material>` element defines a physically based material, which
+ * `<pc-render>` elements apply by naming its `id`. It is metal/rough by default, with `metalness`
+ * starting at 0. Must be a direct child of `<pc-app>`.
+ *
  * @attribute {number} roughness - The roughness of the material, from 0 (shiny) to 1 (rough). An
  * alias for `gloss` that also inverts it, so do not combine it with the `gloss` attributes.
  * @attribute {string} roughness-map - The id of the `pc-asset` to use as the roughness map. An

package/src/model.ts

@@ -125,6 +125,11 @@ const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number
  * intersects the model's geometry, exactly as for `<pc-entity>` — a hit on a content node that no
  * `pc-node` fronts resolves to this element.
  *
+ * @elementSummary The `<pc-model>` element instantiates a 3D model from a container asset
+ * (typically a GLB) beneath an entity of its own, so the element's transform and tags place the
+ * instance in the scene. Its `<pc-node>` children override what the asset authored. Place it in the
+ * `<pc-scene>`, or nest it under a `<pc-entity>`, another `<pc-model>` or a `<pc-node>`.
+ *
  * @attribute {boolean} enabled - The enabled state of the model.
  * @attribute {string} name - The name of the model.
  * @attribute {string} position - The position of the model.

package/src/node.ts

@@ -15,7 +15,7 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * `missing`/`ambiguous`/`duplicate` when resolution failed — each accompanied by a warning
  * naming the cause.
  */
-type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+export type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
 
 /**
  * The authored values a bound node's overrides displaced, captured per property when the first
@@ -164,6 +164,11 @@ const levenshtein = (a: string, b: string): number => {
  * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
  * intersects the bound node's geometry, exactly as for `<pc-entity>`.
  *
+ * @elementSummary The `<pc-node>` element binds to a node inside the hierarchy a `<pc-model>`
+ * instantiated and declares overrides against it: a transform, an enabled state, tags, components
+ * to add, or content to attach. Its `name` is a lookup, never a rename. Must be a descendant of
+ * `<pc-model>`.
+ *
  * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
  * `pc-model` (or `pc-node`) once it has instantiated.
  * @attribute {number} index - Which match to bind when `name` matches more than one node,

package/src/scene.ts

@@ -9,6 +9,9 @@ import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scene/ | `<pc-scene>`} elements.
  * The SceneElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
+ * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
  */
 class SceneElement extends AsyncElement {
     /**

package/src/sky.ts

@@ -10,6 +10,10 @@ import { parseBool, parseEnum, parseNumber, parseVec3 } from './parse';
  * The SkyElement interface provides properties and methods for manipulating
  * `<pc-sky>` elements. The SkyElement interface also inherits the properties and
  * methods of the {@link HTMLElement} interface.
+ *
+ * @elementSummary The `<pc-sky>` element renders a skybox from a texture asset, projected as an
+ * infinite background, a box or a dome, and optionally lights the scene from it. Must be a direct
+ * child of `<pc-scene>`.
  */
 class SkyElement extends AsyncElement {
     private _asset = '';

package/src/wasm.ts

@@ -17,6 +17,10 @@ import { AsyncElement } from './async-element';
  * A `<pc-wasm>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
  * boots.
  *
+ * @elementSummary The `<pc-wasm>` element loads a WebAssembly module the engine needs before the
+ * application starts — `Ammo` for physics, `Basis` or `DracoDecoderModule` for compressed assets.
+ * Must be a direct child of `<pc-app>`.
+ *
  * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
  * `Ammo`.
  * @attribute {string} glue - The URL of the module's glue script.