simple-circuit-engine 0.0.11 → 0.0.13

package/dist/scene/shared/SelectionManager.d.ts

@@ -0,0 +1,159 @@
+import { UUID } from '../../core/index.ts';
+import { HoverableType, SelectionData } from './types';
+/**
+ * Callback invoked when selection changes
+ *
+ * @param newSelection - The new selection, or null if deselected
+ * @param previousSelection - The previous selection, or null if none was selected
+ */
+export type SelectionCallback = (newSelection: SelectionData | null, previousSelection: SelectionData | null) => void;
+/**
+ * Manages selected components, enodes or wires for the circuit scene.
+ * Multi-selection is planned (notably with the use of a flexible SelectionData) but still to implement.
+ *
+ * Key current responsibilities:
+ * - Track -currently single object- selection state
+ * - Notify listeners of selection changes (observer pattern)
+ *
+ * @example
+ * ```typescript
+ * const selectionManager = new SelectionManager();
+ *
+ *
+ * // Select a single object
+ * selectionManager.selectOne('component', 'component-uuid-1234');
+ * selectionManager.selectOne('enode', 'enode-uuid-1234');
+ * selectionManager.selectOne('wire', 'wire-uuid-1234');
+ *
+ * // Deselect
+ * selectionManager.deselect();
+ * ```
+ */
+export declare class SelectionManager {
+    /** Current selection */
+    private selection;
+    /** Timestamp when selection occurred (for double-click detection) */
+    private selectedAt;
+    /** Registered selection change callbacks */
+    private callbacks;
+    /**
+     * Create a new SelectionManager
+     */
+    constructor();
+    /**
+     * Get the current selection
+     *
+     * @returns The SelectionData, or null if nothing is selected
+     */
+    getSelection(): SelectionData | null;
+    /**
+     * Get the timestamp when selection occurred
+     *
+     * @returns Timestamp in milliseconds, or null if nothing is selected
+     */
+    getSelectedAt(): number | null;
+    /**
+     * Check if a specific object is selected
+     *
+     * @param type - The type of hoverable object
+     * @param objectId - The object ID to check
+     * @returns true if the object is currently selected
+     */
+    isSelected(type: HoverableType, objectId: UUID): boolean;
+    /**
+     * Check if anything is selected
+     *
+     * @returns true if one object is currently selected or several objects are currently selected
+     */
+    hasSelection(): boolean;
+    private _selectionsEqual;
+    /**
+     * Select one object
+     *
+     * If another object was previously selected or a multi selection existed, they will be deselected first.
+     *
+     * @param type - The type of hoverable object to select
+     * @param objectId - The object ID to select
+     * @param userData - Optional userData of the 3D object being selected
+     */
+    selectOne(type: HoverableType, objectId: UUID, userData?: object | undefined): void;
+    /**
+     * Deselect the current selection
+     */
+    deselect(): void;
+    /**
+     * Select multiple elements at once, replacing any existing selection
+     *
+     * Creates a MultiSelectionData with the provided element maps.
+     * Empty maps are allowed; passing all empty maps clears the selection.
+     *
+     * @param components - Map of component IDs to optional metadata
+     * @param enodes - Map of enode IDs to optional metadata
+     * @param wires - Map of wire IDs to optional metadata
+     */
+    selectMultiple(components?: Map<UUID, string | null>, enodes?: Map<UUID, string | null>, wires?: Map<UUID, string | null>): void;
+    /**
+     * Add a single element to the current selection
+     *
+     * If current selection is null, creates a mono selection.
+     * If current selection is mono, converts to multi and adds element.
+     * If current selection is multi, adds element to appropriate map.
+     *
+     * No-op if element is already selected.
+     *
+     * @param type - Type of element to add
+     * @param objectId - UUID of element to add
+     * @param userData - Optional metadata for the element
+     */
+    addToSelection(type: HoverableType, objectId: UUID, userData?: object): void;
+    /**
+     * Remove a single element from the current selection
+     *
+     * If element is in a mono selection, clears the selection.
+     * If element is in a multi selection, removes from appropriate map.
+     * If multi selection becomes single element, converts to mono.
+     *
+     * No-op if element is not selected.
+     *
+     * @param type - Type of element to remove
+     * @param objectId - UUID of element to remove
+     */
+    removeFromSelection(type: HoverableType, objectId: UUID): void;
+    /**
+     * Get the total count of selected elements across all types
+     *
+     * @returns Number of selected elements (0 if no selection)
+     */
+    getSelectionCount(): number;
+    /**
+     * Get all selected element IDs grouped by type
+     *
+     * Returns empty arrays if no selection.
+     * For mono selection, returns single-element array in appropriate category.
+     *
+     * @returns Object with arrays of selected IDs by type
+     */
+    getSelectedIds(): {
+        components: UUID[];
+        enodes: UUID[];
+        wires: UUID[];
+    };
+    /**
+     * Register a callback for selection changes
+     *
+     * @param callback - Function to call when selection changes
+     * @returns Unsubscribe function
+     */
+    onSelectionChange(callback: SelectionCallback): () => void;
+    /**
+     * Notify all registered callbacks of selection change
+     *
+     * @param newSelection - New selection
+     * @param previousSelection - Previous selection
+     */
+    private notifyCallbacks;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}

package/dist/scene/shared/WireVisualManager.d.ts

@@ -0,0 +1,242 @@
+import { Line2 } from 'three/examples/jsm/lines/Line2.js';
+import { UUID, Wire, Circuit } from '../../core/index.ts';
+/**
+ * Wire Visual Manager
+ * @module scene/shared/WireVisualManager
+ *
+ * Manages wire visual rendering with:
+ * - Pin-accurate endpoints (derived from component visuals)
+ * - Multi-segment rendering via intermediate positions
+ * - Dynamic updates during component movement
+ */
+import * as THREE from 'three';
+/**
+ * Wire path representation for rendering
+ */
+export interface WirePath {
+    /** Wire ID */
+    wireId: UUID;
+    /** Ordered points in world space (Three.js coordinates) */
+    points: THREE.Vector3[];
+}
+/**
+ * Delegation of CircuitController which handles wire visual rendering with proper pin targeting and dynamic updates.
+ *
+ * Key responsibilities:
+ * - Create wire visuals with endpoints at actual pin positions
+ * - Support multi-segment wires via intermediatePositions
+ * - Update wires dynamically when components move/rotate
+ * - Update wire materials for hover/selection states
+ * - may add and remove wire and branching point object3Ds in the scene directly
+ *
+ * @example
+ * ```typescript
+ * const wireManager = new WireVisualManager();
+ *
+ * // Create wire visual
+ * const line = wireManager.createOrUpdateWire(wire, circuit, scene, componentGroups);
+ *
+ * // Update wires when component moves
+ * wireManager.updateWiresForComponent(componentId, circuit, componentGroups);
+ * ```
+ */
+export declare class WireVisualManager {
+    private containerWidth;
+    private containerHeight;
+    private _scene;
+    private _camera;
+    private _componentObject3Ds;
+    private _wireObject3Ds;
+    private _container;
+    private _circuit;
+    /** Shared LineMaterials for all wires (memory efficient, consistent styling) */
+    private wireMaterials;
+    /** Preview wire for wire creation mode */
+    private previewWire;
+    constructor(componentObject3Ds: Map<UUID, THREE.Object3D>, wireObject3Ds: Map<UUID, Line2>);
+    setContainer(container: HTMLElement | null): void;
+    setSceneAndCamera(scene: THREE.Scene, camera: THREE.Camera): void;
+    setCircuit(circuit: Circuit | null): void;
+    /**
+     * Set the resolution for LineMaterial rendering
+     *
+     * MUST be called after initialization and on window/container resize
+     * for Line2 to render correctly.
+     *
+     * @param width - Viewport width in pixels
+     * @param height - Viewport height in pixels
+     *
+     * @example
+     * ```typescript
+     * wireManager.setResolution(window.innerWidth, window.innerHeight);
+     *
+     * window.addEventListener('resize', () => {
+     *   wireManager.setResolution(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    setResolution(width: number, height: number): void;
+    /**
+     * Get the Line2 object for a wire
+     *
+     * @param wireId - Wire ID
+     * @returns Line2 or undefined if not found or disposed
+     */
+    getWireLine(wireId: UUID): Line2 | undefined;
+    /**
+     * Check if a wire visual exists
+     *
+     * @param wireId - Wire ID
+     * @returns true if wire visual exists, false if not found or disposed
+     */
+    hasWire(wireId: UUID): boolean;
+    /**
+     * Get all wire IDs managed by this controllerType
+     *
+     * @returns Array of wire UUIDs, empty if disposed
+     */
+    getWireIds(): UUID[];
+    /**
+     * Create or update the visual for a wire using model wire positions
+     *
+     * @param wire - Wire to render
+     * @returns The created/updated Line2 object
+     */
+    createOrUpdateWire(wire: Wire): Line2;
+    /**
+     * Update a specific wire's geometry
+     *
+     * @param wireId - Wire ID to update
+     */
+    updateWireById(wireId: UUID): void;
+    /**
+     * Update all wires connected to a component
+     *
+     * Called when a component is moved or rotated to update wire endpoints.
+     *
+     * @param componentId - Component that moved
+     */
+    updateWiresForComponent(componentId: UUID): void;
+    /**
+     * visual hover and selection effects
+     */
+    /**
+     * Apply hovered visual effect to a wire
+     * @param wireId
+     */
+    applyHoveredVisual(wireId: UUID): void;
+    removeHoveredVisual(wireId: UUID): void;
+    applySelectedVisual(wireId: UUID): void;
+    removeSelectedVisual(wireId: UUID): void;
+    /**
+     * Apply electrical state material to a wire
+     * Used during simulation to visualize voltage/current flow
+     *
+     * @param wireId - Wire ID to update
+     * @param state - Material state: 'current', 'voltage', 'vc' (voltage and current) or 'idle'
+     */
+    applyElectricalState(wireId: UUID, state: 'current' | 'voltage' | 'vc' | 'idle'): void;
+    /**
+     * removal and dispose
+     */
+    /**
+     * Remove a wire visual from the scene
+     *
+     * @param wireId - Wire ID to remove
+     */
+    removeWire(wireId: UUID): void;
+    /**
+     * Clean up all managed wire visuals
+     */
+    dispose(): void;
+    /**
+     * Preview wire helpers
+     */
+    /**
+     * Create a preview wire for wire creation mode.
+     * @param startPosition - World position of wire start
+     * @returns Line2 object for preview
+     */
+    createPreviewWire(startPosition: THREE.Vector3): Line2;
+    /**
+     * Update preview wire endpoint.
+     * @param endPosition - World position of wire end
+     */
+    updatePreviewWire(endPosition: THREE.Vector3): void;
+    /**
+     * Remove preview wire from scene.
+     */
+    removePreviewWire(): void;
+    /**
+     * Intermediate points and position helpers
+     */
+    /**
+     * Get pin world position by traversing component group
+     *
+     * @param enodeId - The pin's ENode ID
+     * @param componentGroup - The component's Three.js group
+     * @returns World position of the pin, or null if not found
+     */
+    getPinWorldPositionFromGroup(enodeId: UUID, componentGroup: THREE.Object3D): THREE.Vector3 | null;
+    /**
+     * Get insertion index for a new intermediate point on a wire (T058)
+     * @param wireId - Wire ID
+     * @param worldPosition - Position where user clicked
+     * @returns Index where new point should be inserted
+     */
+    getInsertIndexForPosition(wireId: UUID, worldPosition: THREE.Vector3): number;
+    /**
+     * Find nearest intermediate point on a wire within proximity threshold (T057)
+     * @param wireId - Wire ID to search
+     * @param clientPos - Client position (event.clientX/Y) to test - will be converted to container-relative
+     * @param thresholdPx - Proximity threshold in pixels (default: 10)
+     * @returns Object with pointIndex and distance, or null if none found
+     */
+    findNearestIntermediatePoint(wireId: UUID, clientPos: THREE.Vector2, thresholdPx?: number): {
+        pointIndex: number;
+        distance: number;
+    } | null;
+    /**
+     * Compute the full path for a wire including intermediate positions
+     *
+     * @param wire - Wire to compute path for
+     * @returns WirePath with array of Vector3 points from start to end
+     */
+    computeWirePath(wire: Wire): WirePath;
+    /**
+     * private helpers
+     */
+    /**
+     * Get the world position of an ENode (pin or branching point)
+     *
+     * For pins: Traverses component group to find pin visual and gets world position
+     * For branching points: Converts grid position to world coordinates
+     *
+     * @param enodeId - The ENode ID
+     * @param enodeType - Type of the ENode (Pin or BranchingPoint)
+     * @param componentId - Parent component ID (for pins)
+     * @param circuit - Circuit for position lookup
+     * @param componentGroups - Map of component ID to Three.js objects
+     * @returns World position as Vector3
+     */
+    private _getENodeWorldPosition;
+    /**
+     * Convert 3D world position to 2D screen position (T056)
+     * @param worldPosition - World position as Vector3
+     * @returns Screen position as Vector2
+     */
+    private worldToScreen;
+    /**
+     * Calculate distance between two 2D screen positions (T056)
+     * @param screenPos1 - First screen position
+     * @param screenPos2 - Second screen position
+     * @returns Distance in pixels
+     */
+    private screenDistance;
+    /**
+     * Convert client coordinates (event.clientX/Y) to container-relative coordinates
+     * @param clientPos - Position in client/viewport coordinates
+     * @returns Position relative to the container's top-left corner
+     */
+    private clientToContainerCoords;
+}