simple-circuit-engine 0.0.11 → 0.0.13

package/dist/scene/shared/components/ComponentVisualFactory.d.ts

@@ -0,0 +1,438 @@
+import { Component, ComponentType, ComponentState, ENode, ENodeSourceType } from '../../../core/index.ts';
+import { AnimationContext, ConfigFormDefinition, VisualContext } from '../types';
+import { Direction2D } from '../utils/GeometryUtils';
+import { MeshLambertMaterial } from 'three';
+import { CmpMatCategory, CmpMatVariant } from './types';
+import * as THREE from 'three';
+/**
+ * Interface for component visual factories
+ *
+ * Implementations provide methods for:
+ * - Creating the 3D visual representation
+ * - Applying/removing hover effects
+ * - Applying/removing selection effects
+ * - Updating animation based on simulation state
+ *
+ * @example
+ * ```typescript
+ * class MyComponentFactory extends ComponentVisualFactoryBase {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
+ *     const group = new THREE.Group();
+ *     // ... create visual elements
+ *     group.userData.componentId = component.id;
+ *     group.userData.componentType = component.type;
+ *     return group;
+ *   }
+ * }
+ * ```
+ */
+export interface IComponentVisualFactory {
+    /**
+     * @returns nominal rotation along the Y axis when component added (angle in radian)
+     */
+    defaultRotation(): number;
+    /**
+     * Create the Three.js visual representation for a component
+     *
+     * @param component - The circuit component to visualize
+     * @param context - Optional visual context providing access to ENode data
+     * @returns THREE.Object3D (typically a Group) containing the visual
+     *
+     * @remarks
+     * Implementations MUST:
+     * - Set `object.userData.componentId = component.id`
+     * - Set `object.userData.componentType = component.type`
+     * - Create component hitbox on HitboxLayers.COMPONENT layer
+     * - Create pin groups with enodes on HitboxLayers.ENODE layer
+     * - Return objects positioned at origin (scene controllerType handles placement)
+     */
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    /**
+     * Update visual based on component configuration
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param config - The core component configuration Map
+     *
+     */
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Apply hover visual effect to a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Should store original material state in userData for restoration
+     * - Default implementation: emissive glow effect (light blue, 0.5 intensity)
+     * - Called by scene controllerType when component is hovered
+     * - Should be idempotent (safe to call multiple times)
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover visual effect from a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Should restore original material state from userData
+     * - Called by scene controllerType when hover ends
+     * - Should be safe to call even if not currently hovered
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection visual effect to a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Currently a placeholder (no-op) for future implementation
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection visual effect from a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Currently a placeholder (no-op) for future implementation
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * Update pin source type visual (optional method)
+     *
+     * @param pinGroup - The THREE.Group containing the pin visual
+     * @param sourceType - The new source type (null for no source)
+     *
+     * @remarks
+     * - Optional method for component factories that support pin source type visualization
+     * - Changes pin color based on source type (bronze/red/blue)
+     * - Default implementation in ComponentVisualFactoryBase
+     */
+    updatePinSourceType(pinGroup: THREE.Object3D, sourceType: ENodeSourceType | null): void;
+    /**
+     * Apply hover effect on a pin
+     * @param pinGroup
+     */
+    applyPinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Remove hover effect on a pin
+     */
+    removePinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Update animation state based on simulation data
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component's current simulation state or null to reset to edition mode
+     *
+     * @remarks
+     * - Called by CircuitRunnerController during simulation
+     * - Animation visual updates have priority over hover effects
+     * - Default implementation: no-op (static components)
+     * - Subclasses override for component-specific animation
+     *   (e.g., LED glow, switch contactor rotation)
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Get the config form definition for this component type
+     *
+     * @param config - Optional current component config to compute field states (e.g., disabled)
+     * @returns Form definition with field specifications, or null if no config
+     *
+     * @remarks
+     * Defines the UI controls for editing component configuration.
+     * Return null for components with no configurable options.
+     * When config is provided, implementations may use it to set field.disabled
+     * based on interdependencies (e.g., transitionSpan disabled when defaultLogicFamily != Sandbox).
+     */
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core component config (string values) to form data (typed values)
+     *
+     * @param config - Core config from Component.config
+     * @returns Form data with appropriate types for UI controls
+     *
+     * @remarks
+     * Called when config panel opens to initialize form controls.
+     * Converts core string values to UI-appropriate types (e.g., "open" → true).
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data (typed values) back to core config (string values)
+     *
+     * @param formData - Current form values from UI
+     * @returns Core config ready for Component.setAllParameters()
+     *
+     * @remarks
+     * Called on each value change to update Component.config.
+     * Converts UI values back to core string format (e.g., true → "open").
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Set the shared animation context for simulation-aware factories.
+     * Called by the registry fan-out when entering/leaving simulation.
+     *
+     * @param ctx - Animation context, or null when leaving simulation
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}
+/**
+ * Abstract base class for component visual factories
+ *
+ * Provides default implementations for:
+ * - Hover effect (emissive glow)
+ * - Selection effect (placeholder/no-op)
+ * - Animation update (placeholder/no-op)
+ * - Pin group creation (shared helper)
+ * - Component hitbox creation (shared helper)
+ *
+ * Subclasses must implement:
+ * - createVisual() - component-specific visual creation
+ *
+ * Subclasses may override:
+ * - applyHover() / removeHover() - custom hover effect
+ * - applySelection() / removeSelection() - custom selection effect (future)
+ * - updateAnimation() - component-specific animation
+ *
+ * @example
+ * ```typescript
+ * export class BatteryVisualFactory extends ComponentVisualFactoryBase {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
+ *     const group = new THREE.Group();
+ *     // ... create battery-specific visual
+ *     return group;
+ *   }
+ *   // Inherits default hover, selection, and animation
+ * }
+ * ```
+ */
+export declare abstract class ComponentVisualFactoryBase implements IComponentVisualFactory {
+    /** Shared animation context injected by the registry during simulation */
+    protected _animationContext: AnimationContext | null;
+    /** ComponentType handled by this factory, set in each subclass constructor */
+    protected _componentType: ComponentType | null;
+    /** Default hover glow color (light blue) */
+    protected static readonly DEFAULT_HOVER_COLOR = 4491519;
+    /** Default hover emissive intensity */
+    protected static readonly DEFAULT_HOVER_INTENSITY = 0.6;
+    protected getMat(category: CmpMatCategory, variant?: CmpMatVariant): MeshLambertMaterial;
+    defaultRotation(): number;
+    /**
+     * Create the Three.js visual representation for a component
+     * Must be implemented by subclasses
+     */
+    abstract createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    /**
+     * By default no visual configuration-based updates is needed
+     */
+    updateFromConfiguration(_object3D: THREE.Object3D, _config: Map<string, string>): void;
+    /**
+     * Apply hover visual effect using emissive glow
+     *
+     * Default implementation traverses all meshes and applies
+     * an emissive blue glow effect, storing original values in userData.
+     *
+     * Note: If component is selected, selection visual takes precedence
+     * and hover visual is not applied (but isHovered flag is still set).
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover visual effect, restoring original materials
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection visual effect using emissive orange glow
+     *
+     * Selection takes precedence over hover effect.
+     * Stores original material state in userData for restoration.
+     *
+     * @param object3D - The component's root Three.js object
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection visual effect, restoring original or hover state
+     *
+     * If component was hovered before selection, restores hover visual.
+     * Otherwise, restores original material state.
+     *
+     * @param object3D - The component's root Three.js object
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * @private
+     */
+    private pointPinGroupToward;
+    /**
+     * Create a pin group with hitbox and visual sphere
+     *
+     * Creates a THREE.Group containing:
+     * - Hemisphere hitbox (on ENODE layer for raycasting)
+     * - Hemisphere visual (blue sphere)
+     * - Hover callback in userData
+     *
+     * @param node - ENode to create as visual pin
+     * @param pointsTo - rotate pin to make it point the wanted direction
+     * @param visualRotation - if set rotate the visual of the pin to adjust display without affecting hitbox
+     * @returns THREE.Group configured as pin group
+     */
+    protected createPinGroup(node: ENode, pointsTo?: Direction2D, visualRotation?: THREE.Euler | null): THREE.Group;
+    /**
+     * Utility to create semi spheres visually closing pins
+     * @param pinGroup
+     * @param material
+     * @protected
+     */
+    protected createPinCounterpart(pinGroup: THREE.Group, material: THREE.MeshLambertMaterial): THREE.Mesh | null;
+    /**
+     * Find pin group by label within a component Object3D
+     * @param object3D
+     * @param label
+     */
+    findPinGroup(object3D: THREE.Object3D, label: string): THREE.Group | null;
+    /**
+     * fin pin inner visual from within its pin group
+     * @param pinGroup
+     */
+    findPinVisualFromGroup(pinGroup: THREE.Group): THREE.Mesh | null;
+    /**
+     * Find pin group visual by label within a component Object3D
+     * @param object3D
+     * @param label
+     */
+    findPinVisual(object3D: THREE.Object3D, label: string): THREE.Mesh | null;
+    /**
+     * Create component hitbox mesh
+     *
+     * Helper to create standard component hitbox with proper userData and layer.
+     *
+     * @param componentId - UUID of the component
+     * @param groupId - ID of the parent THREE.Group
+     * @param width - Hitbox width
+     * @param height - Hitbox height
+     * @param depth - Hitbox depth
+     * @returns THREE.Mesh configured as component hitbox
+     */
+    protected createComponentHitbox(componentId: string, groupId: number, width: number, height: number, depth: number): THREE.Mesh;
+    protected findHitbox(object3D: THREE.Object3D): THREE.Mesh | null;
+    protected pinColorForSourceType(sourceType: ENodeSourceType | null): number;
+    protected pinColorForElectricalState(state: 'current' | 'voltage' | 'vc' | 'idle'): number;
+    /**
+     * Updates the visual color of a component pin based on its sourceType type.
+     *
+     * This method changes the pin's material color to reflect the sourceType type:
+     * - null/undefined: copper (default pin color)
+     * - Voltage: red
+     * - Current: blue
+     *
+     * @param pinGroup - The THREE.Group containing the pin visual (created by createPinGroup)
+     * @param sourceType - The new sourceType (null for no sourceType)
+     *
+     * @remarks
+     * - Searches for the child mesh with userData.type === 'enode'
+     * - Updates both color and emissive properties for visual consistency
+     * - If sourceType is null/undefined, restores default copper pin color
+     * - Color scheme matches BranchingPointVisualFactory for consistency
+     */
+    updatePinSourceType(pinGroup: THREE.Object3D, sourceType: ENodeSourceType | null): void;
+    /**
+     * Apply hover visual effect on this pin
+     */
+    applyPinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * remove hover visual effect on this pin
+     */
+    removePinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Update animation state based on simulation data (placeholder)
+     *
+     * Default implementation is a no-op for static components.
+     * Override in subclasses that have animation (LED, Switch).
+     */
+    updateAnimation(_object3D: THREE.Object3D, _state: ComponentState | null): void;
+    /**
+     * Get config form definition (default: null - no config)
+     *
+     * Override in subclasses that have configurable options.
+     */
+    getConfigFormDefinition(_config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (default: identity mapping)
+     *
+     * Override in subclasses that need type conversions.
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (default: convert all to strings)
+     *
+     * Override in subclasses that need type conversions.
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Set the shared animation context for simulation-aware factories.
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}
+/**
+ * Registry interface for managing component visual factories
+ *
+ * Provides type-safe registration and retrieval of component factories.
+ * Falls back to a default factory for unregistered component types.
+ *
+ * @remarks
+ * Updated to support both function-based and class-based factories.
+ * Prefer using IComponentVisualFactory class instances.
+ *
+ * @example
+ * ```typescript
+ * const registry = new FactoryRegistry(new DefaultVisualFactory());
+ * registry.register(ComponentType.Battery, new BatteryVisualFactory());
+ * registry.register(ComponentType.LED, new SmallLEDVisualFactory());
+ *
+ * const factory = registry.get(ComponentType.Battery);
+ * const mesh = factory.createVisual(batteryComponent);
+ * ```
+ */
+export interface IFactoryRegistry {
+    /**
+     * Retrieve the factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns Factory (fallback factory if type not registered)
+     *
+     * @remarks
+     * This method NEVER returns null/undefined. If the type is not registered,
+     * the fallback factory provided in the constructor is returned.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered component types
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Unregister a factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if factory was registered and removed, false otherwise
+     *
+     * @remarks
+     * After unregistering, get() will return the fallback factory for this type.
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Get all registered component types
+     *
+     * @returns Array of ComponentType values that have registered factories
+     */
+    getRegisteredTypes(): ComponentType[];
+    /**
+     * Fan out animation context to all registered factories and the fallback.
+     *
+     * @param ctx - Animation context, or null when leaving simulation
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}

package/dist/scene/shared/components/DefaultVisualFactory.d.ts

@@ -0,0 +1,51 @@
+import { ComponentVisualFactoryBase } from './ComponentVisualFactory';
+import { Component } from '../../../core/index.ts';
+import { ConfigFormDefinition } from '../types';
+import * as THREE from 'three';
+/**
+ * Default Visual factory for not yet defined components
+ *
+ * Creates:
+ * - Box squared mesh (white)
+ * - Component hitbox for raycasting
+ *
+ * This default visual is pinless no matter the component definition.
+ */
+export declare class DefaultVisualFactory extends ComponentVisualFactoryBase {
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition (T028)
+     * Returns form for Cube (color) - RectangleLED uses SmallLEDVisualFactory
+     *
+     * @returns Form definition with color field for Cube
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (T028)
+     * Converts hex/preset strings to hex values for color picker
+     *
+     * @param config - Core component config
+     * @returns Form data with hex color string
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (T028)
+     * Converts hex colors to preset names if they match, otherwise keeps hex
+     *
+     * @param formData - Form data with hex color string
+     * @returns Core config with hex or preset name string
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Update visual from configuration (T023)
+     * Updates Cube/RectangleLED color based on color config
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param config - Component configuration map
+     *
+     * @remarks
+     * Updates the box mesh color if 'color' config exists
+     * Supports both hex colors and color presets
+     */
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}

package/dist/scene/shared/components/FactoryRegistry.d.ts

@@ -0,0 +1,84 @@
+import { ComponentType } from '../../../core/index.ts';
+import { AnimationContext } from '../types';
+import { IComponentVisualFactory, IFactoryRegistry } from './ComponentVisualFactory';
+/**
+ * Registry mapping ComponentType to ComponentVisualFactory
+ *
+ * Provides type-safe registration and retrieval with automatic fallback.
+ * Supports both function-based (legacy) and class-based (new) factories.
+ * Thread-safe for read operations (get/has), write operations should be
+ * performed during initialization.
+ *
+ * @example
+ * ```typescript
+ * const registry = new FactoryRegistry(new DefaultVisualFactory());
+ * registry.register(ComponentType.Battery, new BatteryVisualFactory());
+ * registry.register(ComponentType.LED, new SmallLEDVisualFactory());
+ *
+ * const factory = registry.get(ComponentType.Battery); // Returns BatteryVisualFactory
+ * const unknown = registry.get(ComponentType.Unknown); // Returns fallback
+ * const mesh = factory.createVisual(component);
+ * ```
+ */
+export declare class FactoryRegistry implements IFactoryRegistry {
+    private factories;
+    private fallbackFactory;
+    /**
+     * Create a new factory registry
+     *
+     * @param fallbackFactory - Factory to use for unregistered component types
+     * @throws {TypeError} If fallbackFactory is null or undefined
+     */
+    constructor(fallbackFactory: IComponentVisualFactory);
+    /**
+     * Register a visual factory for a specific component type
+     *
+     * @param type - Component type identifier
+     * @param factory - Factory (class instance or function) to create visuals for this type
+     * @throws {TypeError} If type is empty/whitespace or factory is null/undefined
+     * @returns This FactoryRegistry instance (for chaining)
+     */
+    register(type: ComponentType, factory: IComponentVisualFactory): FactoryRegistry;
+    /**
+     * Retrieve the factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns Factory (fallback factory if type not registered)
+     *
+     * @remarks
+     * This method NEVER returns null/undefined. If the type is not registered,
+     * the fallback factory provided in the constructor is returned.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered types
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Unregister a factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if factory was registered and removed, false otherwise
+     *
+     * @remarks
+     * After unregistering, get() will return the fallback factory for this type.
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Get all registered component types
+     *
+     * @returns Array of ComponentType values that have registered factories
+     */
+    getRegisteredTypes(): ComponentType[];
+    /**
+     * Fan out animation context to all registered factories and the fallback.
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}