@playcanvas/web-components 0.13.1 → 0.14.0

package/dist/node.d.ts

@@ -7,6 +7,13 @@ import { EntityBaseElement } from './entity-base.js';
  * naming the cause.
  */
 type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+/**
+ * A sparse mapping from selector to `pc-material` id, as carried by the `material-overrides`
+ * attribute and `materialOverrides` property. A `name:X` key selects every mesh instance of the
+ * bound node's render component whose baseline material is named `X`; an `index:N` key selects
+ * mesh instance `N` and wins over a name rule for the same instance.
+ */
+type MaterialOverrides = Readonly<Record<string, string>>;
 /**
  * The NodeElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-node/ | `<pc-node>`}
@@ -41,6 +48,13 @@ type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplica
  * "x y z" triple.
  * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
  * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+ * @attribute {string} material-overrides - Overrides material assignments on the bound node's
+ * render component, as a JSON object from selector to `pc-material` id — for example
+ * `{"name:CarPaint": "candy-red", "index:7": "smoked-glass"}`. A `name:X` key selects every mesh
+ * instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and
+ * wins over a name rule for the same instance. Assignments no rule matches keep their baseline
+ * materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to
+ * discover the names and indices a node offers.
  * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
  * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
  * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
@@ -76,11 +90,24 @@ declare class NodeElement extends EntityBaseElement {
     private _destroyHandle;
     /** The authored values displaced by this element's overrides, captured per property. */
     private _authored;
+    /**
+     * The model-authored render component of the bound node, recorded at bind — before child
+     * decorations build — so a render component added later by a child `pc-render` can never
+     * become the override target. `null` when the bound node has none.
+     */
+    private _authoredRender;
+    /**
+     * The baseline assignments displaced by the material overrides, captured for every mesh
+     * instance when the first non-empty mapping applies and released when the mapping goes
+     * absent (restoring them) or the binding dissolves.
+     */
+    private _baseline;
     private _enabled;
     private _position;
     private _rotation;
     private _scale;
     private _tags;
+    private _materialOverrides;
     /**
      * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
      * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
@@ -149,6 +176,19 @@ declare class NodeElement extends EntityBaseElement {
      * themselves are kept - they re-apply on the next binding.
      */
     private _revertOverrides;
+    /**
+     * Applies the material mapping to the authored render component: parse the mapping's valid
+     * rules, capture the baseline on first application, then recompute every assignment from
+     * that baseline - name rules write over it, index rules write over them, so `index:` wins -
+     * and assign whatever changed. An absent mapping, or one with no valid rules, restores the
+     * baseline instead. Called while bound, from `_applyOverrides` and the property setter.
+     */
+    private _applyMaterialOverrides;
+    /**
+     * Restores every baseline assignment the material overrides displaced and releases the
+     * capture, so the next non-empty mapping captures afresh. Safe to call without a capture.
+     */
+    private _restoreBaseline;
     /**
      * Renders the path of `node` below `root`, for the `path` property and the resolution
      * warnings.
@@ -247,7 +287,22 @@ declare class NodeElement extends EntityBaseElement {
      * @returns The tags, or `null` while no override is set.
      */
     get tags(): string[] | null;
+    /**
+     * Sets the material overrides: a sparse mapping from selector to `pc-material` id, applied
+     * to the bound node's authored render component. A `name:X` key selects every mesh instance
+     * whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins
+     * over a name rule for the same instance. Assignments no rule matches keep their baseline
+     * materials. `null` clears the mapping, restoring every baseline assignment.
+     * @param value - The mapping, or `null`.
+     */
+    set materialOverrides(value: MaterialOverrides | null);
+    /**
+     * Gets the material overrides.
+     * @returns The mapping, or `null` while no override is set.
+     */
+    get materialOverrides(): MaterialOverrides | null;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
 }
 export { NodeElement };
+export type { MaterialOverrides };

package/dist/parse.d.cts

@@ -15,133 +15,4 @@
  * `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.
  */
-import type { Entity } from 'playcanvas';
-import { Color, 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.
- *
- * @param value - The value to split.
- * @param count - The required number of components.
- * @returns The parsed components, or `null`.
- * @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
- * (e.g. '1 0.5 0.5' or '1 0.5 0.5 0.5'). Returns `defaultValue` (cloned, when it is a color)
- * when the attribute is absent (`null`), or when the value is malformed — 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 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. Only the keys
- * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
- * but some (e.g. `SCALEMODE_BLEND`) are strings.
- * @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, unknown>, 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
- * a quaternion) when the attribute is absent (`null`), or when the value is malformed — 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 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`),
- * or when the value is malformed — 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 Vec2 object.
- */
-export declare const parseVec2: <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string) => Vec2 | T;
-/**
- * Parse a Vec3 attribute value. The expected format is 3 space-separated numbers (e.g. '1 2 3').
- * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
- * or when the value is malformed — 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 Vec3 object.
- */
-export declare const parseVec3: <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string) => Vec3 | T;
-/**
- * Parse a Vec4 attribute value. The expected format is 4 space-separated numbers
- * (e.g. '1 2 3 4'). Returns `defaultValue` (cloned, when it is a vector) when the attribute is
- * absent (`null`), or when the value is malformed — 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 Vec4 object.
- */
-export declare const parseVec4: <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string) => Vec4 | 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
- * entity name. Returns `null` if no matching element (or backing entity) is found.
- *
- * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
- */
-export declare const getEntity: (ref: string) => Entity | null;
+export {};

package/dist/parse.d.ts

@@ -15,133 +15,4 @@
  * `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.
  */
-import type { Entity } from 'playcanvas';
-import { Color, 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.
- *
- * @param value - The value to split.
- * @param count - The required number of components.
- * @returns The parsed components, or `null`.
- * @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
- * (e.g. '1 0.5 0.5' or '1 0.5 0.5 0.5'). Returns `defaultValue` (cloned, when it is a color)
- * when the attribute is absent (`null`), or when the value is malformed — 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 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. Only the keys
- * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
- * but some (e.g. `SCALEMODE_BLEND`) are strings.
- * @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, unknown>, 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
- * a quaternion) when the attribute is absent (`null`), or when the value is malformed — 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 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`),
- * or when the value is malformed — 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 Vec2 object.
- */
-export declare const parseVec2: <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string) => Vec2 | T;
-/**
- * Parse a Vec3 attribute value. The expected format is 3 space-separated numbers (e.g. '1 2 3').
- * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
- * or when the value is malformed — 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 Vec3 object.
- */
-export declare const parseVec3: <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string) => Vec3 | T;
-/**
- * Parse a Vec4 attribute value. The expected format is 4 space-separated numbers
- * (e.g. '1 2 3 4'). Returns `defaultValue` (cloned, when it is a vector) when the attribute is
- * absent (`null`), or when the value is malformed — 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 Vec4 object.
- */
-export declare const parseVec4: <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string) => Vec4 | 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
- * entity name. Returns `null` if no matching element (or backing entity) is found.
- *
- * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
- */
-export declare const getEntity: (ref: string) => Entity | null;
+export {};