@playcanvas/web-components 0.9.0 → 0.10.0

package/dist/model.d.ts

@@ -24,7 +24,7 @@ declare class ModelElement extends AsyncElement {
      */
     get asset(): 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/module.d.ts

@@ -3,6 +3,16 @@
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
  * The ModuleElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * Note that these attributes are read once when the element is created, so changing them later
+ * has no effect.
+ *
+ * @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.
+ * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+ * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+ * WebAssembly is unavailable.
  */
 declare class ModuleElement extends HTMLElement {
     private loadPromise;

package/dist/{utils.d.ts → parse.d.ts}

@@ -1,17 +1,21 @@
-import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 /**
- * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ * Converts HTML attribute values into the values the engine expects. Every element's
+ * `attributeChangedCallback` funnels through this module.
  *
- * - Attribute absent (or removed): the supplied default is used.
- * - Attribute set to the string 'false': `false`.
- * - Attribute present with any other value, including the empty string of a bare boolean
- *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ * The parsers share one contract:
  *
- * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param defaultValue - The value to use when the attribute is absent or removed.
- * @returns The parsed boolean.
+ * - A `null` value means the attribute is absent or was removed, and yields the supplied default.
+ * - A malformed value yields the same default and logs exactly one `console.warn` naming the
+ *   attribute, so misuse is reported rather than thrown — nothing here throws or rejects.
+ * - A math-type default is cloned on the way out, which is what makes it safe to pass the engine's
+ *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
+ * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
+ *   so they never warn.
+ *
+ * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
+ * literal, and returns `null` instead of falling back to a default.
  */
-export declare const parseBool: (value: string | null, defaultValue: boolean) => boolean;
+import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 /**
  * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
  * value does not consist of exactly `count` whitespace-separated finite numbers.
@@ -22,6 +26,19 @@ export declare const parseBool: (value: string | null, defaultValue: boolean) =>
  * @ignore
  */
 export declare const parseComponents: (value: string, count: number) => number[] | null;
+/**
+ * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ *
+ * - Attribute absent (or removed): the supplied default is used.
+ * - Attribute set to the string 'false': `false`.
+ * - Attribute present with any other value, including the empty string of a bare boolean
+ *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed boolean.
+ */
+export declare const parseBool: (value: string | null, defaultValue: boolean) => boolean;
 /**
  * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
  * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
@@ -35,6 +52,29 @@ export declare const parseComponents: (value: string, count: number) => number[]
  * @returns The parsed Color object.
  */
 export declare const parseColor: <T extends Color | null>(value: string | null, defaultValue: T, attribute: string) => Color | T;
+/**
+ * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+ * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+ * the value is invalid — the latter also logs a warning listing the valid names.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The resolved enum name.
+ */
+export declare const parseEnum: <T extends string>(value: string | null, valid: readonly T[] | ReadonlyMap<T, number>, defaultValue: T, attribute: string) => T;
+/**
+ * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+ * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+ * finite number — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed number.
+ */
+export declare const parseNumber: <T extends number | null>(value: string | null, defaultValue: T, attribute: string) => number | T;
 /**
  * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
  * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
@@ -47,6 +87,19 @@ export declare const parseColor: <T extends Color | null>(value: string | null,
  * @returns The parsed Quat object.
  */
 export declare const parseQuat: <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string) => Quat | T;
+/**
+ * Parse a tags attribute value. The expected format is a comma-separated list of tag names
+ * (e.g. 'enemy, flying'). Surrounding whitespace is trimmed from each name and empty names are
+ * discarded, so a trailing comma or a doubled separator does not produce a blank tag. Returns a
+ * copy of `defaultValue` when the attribute is absent or removed (`null`).
+ *
+ * Every value is valid, so this never warns.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed tag names.
+ */
+export declare const parseTags: (value: string | null, defaultValue?: string[]) => string[];
 /**
  * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
  * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
@@ -80,29 +133,6 @@ export declare const parseVec3: <T extends Vec3 | null>(value: string | null, de
  * @returns The parsed Vec4 object.
  */
 export declare const parseVec4: <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string) => Vec4 | T;
-/**
- * Resolves an enum attribute value against its set of valid names. Returns the value when it is
- * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
- * the value is invalid — the latter also logs a warning listing the valid names.
- *
- * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param valid - The valid names: an array, or a map whose keys are the valid names.
- * @param defaultValue - The value to use when the attribute is absent or invalid.
- * @param attribute - The attribute name, used in the warning message.
- * @returns The resolved enum name.
- */
-export declare const parseEnum: <T extends string>(value: string | null, valid: readonly T[] | ReadonlyMap<T, number>, defaultValue: T, attribute: string) => T;
-/**
- * Parses a number attribute value. Returns the parsed number when the value is a finite number.
- * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
- * finite number — the latter also logs a warning.
- *
- * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param defaultValue - The value to use when the attribute is absent or invalid.
- * @param attribute - The attribute name, used in the warning message.
- * @returns The parsed number.
- */
-export declare const parseNumber: <T extends number | null>(value: string | null, defaultValue: T, attribute: string) => number | T;
 /**
  * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
  * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare