@virtualdisplay.io/client 3.1.0

package/dist/index.d.ts

@@ -0,0 +1,503 @@
+import { Logger } from '@virtualdisplay-io/logger';
+
+/**
+ * Pure domain aggregate for managing attribute values
+ * No side effects - only business logic and state management
+ */
+declare class Attribute {
+    private readonly attributeName;
+    private readonly values;
+    constructor(name: string);
+    addValue(attributeValue: AttributeValue): void;
+    /**
+     * Select a value - returns mutations needed for the change
+     * Pure function - no side effects
+     */
+    select(value: string): Mutation[];
+    getDefaultMutations(): Mutation[];
+    getCurrentValue(): AttributeValue | undefined;
+    getValue(valueName: string): AttributeValue | undefined;
+    getAllValues(): AttributeValue[];
+    hasValue(valueName: string): boolean;
+    get name(): string;
+    get currentSelection(): string | undefined;
+}
+
+/**
+ * Configuration for a single attribute
+ */
+export declare interface AttributeConfig {
+    readonly name: string;
+    readonly values: AttributeValueConfig[];
+}
+
+/**
+ * Public API for selecting attribute values
+ * Provides fluent interface for client usage
+ */
+export declare class AttributeSelector {
+    private readonly attributeService;
+    private readonly attributeName;
+    constructor(attributeService: AttributeService, attributeName: string);
+    /**
+     * Select a value for this attribute
+     * Fire-and-forget: returns immediately, 3D updates asynchronously
+     * @returns this AttributeSelector for method chaining
+     * @throws {VirtualdisplayError} When value not found for attribute
+     */
+    select(value: string): AttributeSelector;
+    get name(): string;
+    get currentValue(): string | undefined;
+    get availableValues(): string[];
+    /**
+     * Register a callback to be called when any value's selection state changes
+     * This registers the callback on all AttributeValue objects for this attribute
+     * @param callback Function to call when selection state changes
+     * @returns this AttributeSelector for method chaining
+     */
+    onChange(callback: () => void): AttributeSelector;
+    /**
+     * Get all AttributeValue objects for direct property access
+     * @returns Array of AttributeValue objects
+     */
+    getValues(): AttributeValue[];
+    /**
+     * Get a specific AttributeValue object by value name
+     * @param value The value name to find
+     * @returns AttributeValue object or undefined if not found
+     */
+    getValue(value: string): AttributeValue | undefined;
+    private getAttribute;
+}
+
+/**
+ * Application service for managing attributes
+ * Handles business logic and coordinates with other domains via events
+ */
+declare class AttributeService {
+    private readonly attributes;
+    private readonly eventBus;
+    private isInitialized;
+    constructor(eventBus: EventBus);
+    /**
+     * Load mapping configuration and apply defaults
+     * @throws {VirtualdisplayError} When mapping configuration is invalid
+     */
+    loadMapping(config: MappingConfiguration): void;
+    selectAttributeValue(attributeName: string, value: string): void;
+    getAttribute(name: string): Attribute | undefined;
+    getAllAttributes(): Attribute[];
+    get initialized(): boolean;
+    private syncStateWithAttributes;
+    private getAttributeValueForNode;
+    clear(): void;
+}
+
+/**
+ * Pure domain entity representing a single attribute value
+ * No side effects - only business logic and data
+ */
+declare class AttributeValue {
+    private readonly attributeValue;
+    private readonly nodeIds;
+    private selected;
+    onChange?: () => void;
+    constructor(value: string, nodeIds: string[], isSelected?: boolean);
+    getMutations(): Mutation[];
+    setSelected(selected: boolean): void;
+    get value(): string;
+    get nodeList(): string[];
+    hasNode(nodeId: string): boolean;
+    get isSelected(): boolean;
+    setOnChange(callback: () => void): void;
+}
+
+/**
+ * Configuration for a single attribute value
+ */
+export declare interface AttributeValueConfig {
+    readonly value: string;
+    readonly nodeIds: string[];
+    readonly isSelected?: boolean;
+}
+
+/**
+ * Base message interface
+ */
+declare interface BaseMessage {
+    readonly type: MessageType;
+}
+
+/**
+ * Configuration options for VirtualdisplayClient
+ */
+export declare interface ClientOptions {
+    readonly parent: string | HTMLElement;
+    readonly model: string;
+    readonly license: string;
+    readonly debug?: boolean;
+    readonly language?: string;
+}
+
+declare interface CreateNodeParams {
+    id: string;
+    name: string;
+    type: NodeType;
+    visible: boolean;
+}
+
+/**
+ * Central Event Registry
+ */
+export declare interface DomainEvents extends Record<string, unknown> {
+    [EVENT_NAMES.IFRAME_READY]: VoidEvent;
+    [EVENT_NAMES.MUTATION_MESSAGE]: MutationMessageEvent;
+    [EVENT_NAMES.MESSAGE_RECEIVED]: MessageReceivedEvent;
+    [EVENT_NAMES.STATE_CHANGED]: StateChangedEvent;
+}
+
+export declare function enableDebugMode(): void;
+
+/**
+ * Error codes for Virtualdisplay client errors
+ */
+export declare const ERROR_CODES: {
+    readonly NO_MAPPING: "NO_MAPPING";
+    readonly ATTRIBUTE_NOT_FOUND: "ATTRIBUTE_NOT_FOUND";
+    readonly VALUE_NOT_FOUND: "VALUE_NOT_FOUND";
+    readonly INVALID_MAPPING: "INVALID_MAPPING";
+    readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
+    readonly INVALID_MUTATIONS: "INVALID_MUTATIONS";
+};
+
+export declare type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+
+/**
+ * Event name constants for type-safe event communication
+ */
+export declare const EVENT_NAMES: {
+    readonly IFRAME_READY: "iframe:ready";
+    readonly MUTATION_MESSAGE: "mutation:message";
+    readonly MESSAGE_RECEIVED: "message:received";
+    readonly STATE_CHANGED: "state:changed";
+};
+
+/**
+ * EventBus for domain coordination
+ * Provides loose coupling between domains via events
+ */
+declare class EventBus {
+    private readonly listeners;
+    on<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
+    emit<K extends keyof DomainEvents>(event: K, payload: DomainEvents[K]): void;
+    once<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
+    off<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
+}
+
+declare type EventListener_2<T> = (payload: T) => void;
+
+export declare function isDebugMode(): boolean;
+
+export declare const logger: Logger;
+
+/**
+ * Complete mapping configuration
+ * Defines how product attributes map to 3D nodes
+ */
+export declare interface MappingConfiguration {
+    readonly attributes: AttributeConfig[];
+}
+
+export declare const mappingSchema: {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Virtualdisplay mapping configuration",
+    "description": "Schema for attribute-based 3D model configuration",
+    "type": "object",
+    "required": ["attributes"],
+    "definitions": {
+        "attribute": {
+            "type": "object",
+            "description": "A configurable attribute with multiple possible values",
+            "required": ["name", "values"],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Unique attribute name (e.g., 'Color', 'Size')",
+                    "minLength": 1,
+                    "pattern": "^\\S.*\\S$|^\\S$"
+                },
+                "values": {
+                    "type": "array",
+                    "description": "Possible values for this attribute",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/attributeValue"
+                    }
+                }
+            }
+        },
+        "attributeValue": {
+            "type": "object",
+            "description": "A single value option for an attribute",
+            "required": ["value", "nodeIds"],
+            "properties": {
+                "value": {
+                    "type": "string",
+                    "description": "Display value (e.g., 'Red', 'Large')",
+                    "minLength": 1,
+                    "pattern": "^\\S.*\\S$|^\\S$"
+                },
+                "nodeIds": {
+                    "type": "array",
+                    "description": "3D model node IDs controlled by this value",
+                    "items": {
+                        "type": "string",
+                        "description": "Node ID in the 3D model"
+                    }
+                },
+                "isSelected": {
+                    "type": "boolean",
+                    "description": "Whether this value is selected by default",
+                    "default": false
+                }
+            }
+        }
+    },
+    "properties": {
+        "attributes": {
+            "type": "array",
+            "description": "List of all configurable attributes",
+            "minItems": 1,
+            "items": {
+                "$ref": "#/definitions/attribute"
+            }
+        }
+    }
+};
+
+/**
+ * Validator for mapping configuration using AJV
+ */
+export declare class MappingValidator {
+    private static readonly ajv;
+    private static readonly validateFn;
+    /**
+     * Validate complete mapping configuration
+     * @throws {VirtualdisplayError} When mapping configuration is invalid
+     */
+    static validate(config: MappingConfiguration): void;
+}
+
+/**
+ * Union of all possible messages
+ */
+export declare type Message = MutationMessage | StateMessage;
+
+/**
+ * Types of messages exchanged between client and server
+ * Using lowercase format to match server
+ */
+export declare const MESSAGE_TYPES: {
+    readonly MUTATION: "mutation";
+    readonly STATE: "state";
+};
+
+/**
+ * State Flow Events (Server → Client)
+ */
+declare interface MessageReceivedEvent {
+    message: unknown;
+}
+
+declare type MessageType = typeof MESSAGE_TYPES[keyof typeof MESSAGE_TYPES];
+
+/**
+ * Represents a 3D node in the scene
+ * Live object that can be updated to reflect state changes
+ */
+export declare class ModelNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: NodeType;
+    private visible;
+    constructor(params: CreateNodeParams);
+    get isVisible(): boolean;
+    show(): void;
+    hide(): void;
+}
+
+/**
+ * DTO for model node data received from server
+ */
+export declare interface ModelNodeDto {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly visible: boolean;
+}
+
+/**
+ * A mutation represents a change to be applied to a 3D node
+ * This is a pure data class with no side effects
+ */
+export declare class Mutation {
+    readonly type: MutationType;
+    readonly nodeId: string;
+    constructor(type: MutationType, nodeId: string);
+    static show(nodeId: string): Mutation;
+    static hide(nodeId: string): Mutation;
+    inverse(): Mutation;
+    equals(other: Mutation): boolean;
+    toDto(): MutationDto;
+}
+
+/**
+ * Types of mutations that can be applied to 3D nodes
+ */
+export declare const MUTATION_TYPES: {
+    readonly SHOW: "show";
+    readonly HIDE: "hide";
+};
+
+/**
+ * Data Transfer Object for mutations
+ * Plain object for client-server communication without methods
+ */
+export declare interface MutationDto {
+    readonly type: MutationType;
+    readonly nodeId: string;
+}
+
+/**
+ * Mutation message sent to server
+ */
+export declare interface MutationMessage extends BaseMessage {
+    readonly type: typeof MESSAGE_TYPES.MUTATION;
+    readonly mutations: MutationDto[];
+}
+
+/**
+ * Mutation Flow Events (Client → Server)
+ */
+declare interface MutationMessageEvent {
+    message: MutationMessage;
+}
+
+export declare type MutationType = typeof MUTATION_TYPES[keyof typeof MUTATION_TYPES];
+
+/**
+ * Types of nodes in the 3D scene
+ */
+export declare const NODE_TYPES: {
+    readonly MESH: "mesh";
+    readonly VARIANT: "variant";
+};
+
+/**
+ * Public API for controlling individual nodes
+ * Provides direct node manipulation without attribute mapping
+ */
+export declare class NodeSelector {
+    private readonly eventBus;
+    private readonly stateService;
+    private readonly nodeId;
+    constructor(eventBus: EventBus, stateService: StateService, nodeId: string);
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    get id(): string;
+    get isVisible(): boolean;
+    getNode(): ModelNode | undefined;
+    get type(): string | undefined;
+    get name(): string | undefined;
+    private emitMutation;
+}
+
+declare type NodeType = typeof NODE_TYPES[keyof typeof NODE_TYPES];
+
+declare interface StateChangedEvent {
+    nodes: ModelNode[];
+}
+
+/**
+ * State message received from server
+ * Contains array of model node DTOs
+ */
+export declare interface StateMessage extends BaseMessage {
+    readonly type: typeof MESSAGE_TYPES.STATE;
+    readonly nodes: ModelNodeDto[];
+}
+
+/**
+ * Application service for managing node state
+ * Handles state updates from server and emits node change events
+ */
+declare class StateService {
+    private readonly nodes;
+    private readonly eventBus;
+    constructor(eventBus: EventBus);
+    private handleMessage;
+    private updateState;
+    private updateOrCreateNode;
+    private createNewNode;
+    getNode(id: string): ModelNode | undefined;
+    getAllNodes(): ModelNode[];
+    get isReady(): boolean;
+    get nodeCount(): number;
+    private get hasInitialState();
+    clear(): void;
+}
+
+/**
+ * Main Virtualdisplay Client
+ * Provides the public API for 3D product visualization
+ */
+export declare class VirtualdisplayClient {
+    private readonly eventBus;
+    private readonly attributeService;
+    private readonly stateService;
+    private readonly messageHandler;
+    private readonly options;
+    private iframe;
+    constructor(options: ClientOptions);
+    private initializeLogging;
+    private createAndConnectIframe;
+    /**
+     * Load attribute mapping configuration
+     * @throws {VirtualdisplayError} When mapping configuration is invalid
+     */
+    setMapping(config: MappingConfiguration): void;
+    /**
+     * Get attribute selector for fluent API
+     * @throws {VirtualdisplayError} When no mapping is configured or attribute not found
+     */
+    getAttribute(name: string): AttributeSelector;
+    /**
+     * Get node selector for direct node control
+     * @param nodeId The node ID to control
+     * @returns NodeSelector if node exists, undefined otherwise
+     */
+    getNodeSelector(nodeId: string): NodeSelector | undefined;
+    getNode(id: string): ModelNode | undefined;
+    getNodes(): ModelNode[];
+    destroy(): void;
+}
+
+/**
+ * Custom error class for Virtualdisplay client errors
+ */
+export declare class VirtualdisplayError extends Error {
+    readonly code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
+    static noMapping(): VirtualdisplayError;
+    static attributeNotFound(attributeName: string): VirtualdisplayError;
+    static valueNotFound(attributeName: string, valueName: string): VirtualdisplayError;
+    static invalidMapping(reason?: string): VirtualdisplayError;
+    static parentNotFound(selector: string): VirtualdisplayError;
+    static invalidMutations(reason?: string): VirtualdisplayError;
+}
+
+declare interface VoidEvent {
+}
+
+export { }